LocoNet System Variable (CV’s)
Article revised by : Stéfan Stoltz
This document is an extension to the LocoNet Personal Use Edition 1.0, and describes the System Variables and how to use the SV Programming Message Formats (Ver. 13)
LocoNet uses the 16 byte OPC_PEER <0xE5><0x10> message for the purpose of programming System Variables (SVs).
Technical Note 1:
- This usage of the OPC_PEER <0xE5><0x10> message is distinguished from others by the value of the 4th byte, and the upper nibbles of both the 6th and 11th bytes.
- All devices sending these messages must ensure that those are set appropriately, and all devices interpreting any message with an E5 op-code must check these locations to determine whether the received message is an SV programming command.
Technical Note 2
- Two message structures are defined that are distinguished by the value of the 4th byte:
Type 1: E5 10 nn nn 01 0n nn nn nn nn 1n nn nn nn nn cc
- This is the message format as implemented by the certain existing devices.
- New designs should not use this format!
- The message bytes are assigned as follows:
- The upper nibble of PXCT1 must be 0, and the upper nibble of PXCT2 must be 1. The meanings of the remaining bytes are as defined in the LocoNet Personal Edition specification.
Type 2: E5 10 nn nn 02 1n nn nn nn nn 1n nn nn nn nn cc
- This is the recommended format for new designs.
- The message bytes as assigned as follows:
- The upper nibble of both SVX1 (PXCT1) and SVX2 (PXCT2) must be 1.
Message Field Usage
The field designation is defined below in the table:
<SRC> 7bit source address for the device issuing the programming command.
- 0x0 to 0xF: typically PCs
- 0x10 to 0x7F: other LocoNet devices
- <SV_CMD> Specifies the SV access type
- 0x01 = SV write: write 1 byte of data from D1
- 0x02 = SV read: initiate read 1 byte of data into D1
- 0x03 = SV masked write: write 1 byte of masked data from D1. D2 contains the mask to be used; a 1 bit in D2 means that the corresponding bit should be written.
- 0x05 = SV write 4 bytes: write 4 bytes of data from D1..D4
- 0x06 = SV read 4 bytes: initiate read 4 bytes of data into D1..D4
- 0x07 = Discover: causes all devices to identify themselves by their MANUFACTURER_ID, DEVELOPER_ID, PRODUCT_ID and Serial Number.
- 0x08 = Identify: causes an individual device to identify itself by its MANUFACTURER_ID, DEVELOPER_ID, PRODUCT_ID and Serial Number.
- 0x09 = Change Address: Changes the device address to the values specified in <DST_L> + <DST_H> in the device that matches the values specified in <SV_ADRL> + <SV_ADRH> + <D1>..<D4> that we in the reply to the Discover or Identify command issued previously.
- 0x0F = Reconfigure: initiates a device reconfiguration or reset so that any new device configuration becomes active. read response messages, sent in response to a read command:
- 0x41 = REPLY SV write: transfers a write response in D1
- 0x42 = REPLY SV read: transfers a read response in D1
- 0x43 = REPLY SV masked write: transfers a masked write response in D1
- 0x45 = REPLY SV 4 byte write: transfers a write response in D1..D4
- 0x46 = REPLY SV 4 byte read: transfers a read response in D1..D4
- 0x47 = REPLY Discover: transfers an Discover response containing the MANUFACTURER_ID, DEVELOPER_ID, PRODUCT_ID and Serial Number 0x48 = REPLY Identify: transfers an Identify response containing the MANUFACTURER_ID, DEVELOPER_ID, PRODUCT_ID and Serial Number
- 0x49 = Change Address: transfers a Change Address response.
- 0x4F = REPLY Reconfigure: Acknowledgement immediately prior to a device reconfiguration or reset.
- <SV_TYPE> This field determines the usage of the other fields. A value of 0x02 is required for this format.
All other values reserved
<SVX1> <0 0 0 1 D3 D2 D1 D0>
These bits provide the top bits of the next 4 bytes
- D3: bit 7 of <SV_ADRH>
- D2: bit 7 of <SV_ADRL>
- D1: bit 7 of <DST_H>
- D0: bit 7 of <DST_L>, <DST_L>,<DST_H>
16bit destination address of the device being programmed. The <SV_TYPE> = 0x02 message format does not have a broadcast address (<DST_L> = 0 <DST_H> = 0) like other message.
The Discover command <SV_CMD> = 0x07 performs a broadcast for all devices to report their identity.
16bit destination EEPROM address for read/write. For multi-byte operations this specifies the D1 address: the other bytes go to <Addr+1>, <Addr+2>, <Addr+3> <SVX2> <0 0 0 1 D3 D2 D1 D0> These bits provide the top bits of the next 4 bytes
- D3: bit 7 of <D4> byte
- D2: bit 7 of <D3> byte
- D1: bit 7 of <D2> byte
- D0: bit 7 of <D1> byte
<D1>…<D4> Data payload bytes. D1 is used for single byte operations; D1 is LSB for multi-byte operations.
The following notes contain extra information about the commands described in the table above.
- Destination devices are addressed on the LocoNet by the two fields <DST_L> + <DST_H>
- Each device must have a unique address to function correctly. New devices may be delivered with their <DST_L> + <DST_H> fields set to defaults.
- If several new devices with the same address are connected to the LocoNet, they will need to have their addresses changed before they can be configured.
- See the Change Address note below for details on how to change a device’s address.
Writing to a Device
- When a Write command is received, the destination device selected by <DST_L> + <DST_H> programs its EEPROM at the address selected by <SV_ADRL> and <SV_ADRH> with 1 or 4 bytes of data according to the command issued. It then generates a Write Response message with <SV_CMD>.6= 1 and <D1>..<D4> contain the values that are read back from the locations in the EEPROM that were just written to. By comparing the data values in the response the programming device will be able to determine if the write operation was successful.
Reading from a Device
- When a Read command is received, the destination device selected by <DST_L> + <DST_H> reads 1 or 4 bytes of data from its EEPROM at the address selected by <SV_ADRL> and <SV_ADRH>.
- It then generates a “read reply” message with <SV_CMD>.6 = 1 and fields <D1>..<D4> set to the values read from the EEPROM.
Discover and Identify
- When the Discover command is issued, all devices will respond with a Discover response.
- When the Identify command is issued, only the device addressed by <DST_L> + <DST_H> will respond.
- In either case the response contains the manufacturers assigned MANUFACTURER_ID in <SV_ADRL>, DEVELOPER_ID, in <SV_ADRH>, the PRODUCT_ID in <D1> + <D2> and the Serial Number in <D3> + <D4>. Each 16bit value is transferred LSB first.
- If there are multiple devices with the same <DST_L> + <DST_H> address then the programming device must detect this and change the addresses of the conflicting devices as described in the Change Address note below.
- A board address is changed by executing the <SV_CMD> = 0x09 command. For this command the device is NOT address by the fields <DST_L> + <DST_H>, it is addressed by comparing the values in the fields <SV_ADRL> + <SV_ADRH> and <D1>..<D4> fields to its internal values that it would use when it replies to a Identify command.
- If the fields match then the device changes it’s address to the values specified in <DST_L> + <DST_H>.
- The sequence for doing this is as follows:
- Issue a <SV_CMD> = 0x07 Discover or <SV_CMD> = 0x08 Identify command. This will all or the specified devices to respond with their MANUFACTURER_ID, DEVELOPER_ID, PRODUCT_ID and Serial Number.
- The programming device (probably a PC) will collect all the responses and will detect devices with the same <DST_L> + <DST_H>
- For each device with a conflicting address or for the specific device you want to change, the programming device will execute a <SV_CMD> = 0x08 Change Address command, using the information returned by the previous Identify response.Important: For the Change Address command to work correctly, each device must be factory or user programmed with a unique 16bit serial number which is least unique to the layout.
- If board sales exceed 64k units, to maintain serial number uniqueness a new PRODUCT_ID will need to be assigned for the same device. Software suppliers should consider this possibility in their designs.
- Some manufacturers (e.g. Digitrax) may anticipate board sales >64k units from the start and pre-allocate several PRODUCT_ID’s for a new product.
Standard SV/EEPROM Locations
To ensure consistency across devices, a number of SVs are predefined to contain useful system information. These SV locations are defined as follows:
- SV 1 = EEPROM Size
0 = 256 bytes
1 = 512 bytes
2 = 1024 bytes
3 = 2048 bytes
4 = 4096 bytes
- SV 2 = Software Version Number
The software version number is a value in the range 0 – 255.
- SV 3 = Serial Number Low & SV 4 = Serial Number High
The 16bit serial number is accessible via SVs so that it can be user configurable. Some vendors may choose to disable this feature.
Manufacturer and Developer ID’s
- It is intended that the both the Initial Program Loader (IPL) protocol and the SV protocol should use the same MANUFACTURER_ID and DEVELOPER_ID numbers.
- The MANUFACTURER_ID is an 8 bit value that uniquely identifies all devices from a device manufacturer. If a manufacturer has a NMRA DCC Manufacturer ID Number, this should be used.
- For a list of numbers see: http://www.nmra.org/standards/DCC/mfgnumbers.html
- Manufacturers who use their own NMRA DCC Manufacturer ID may choose to assign and manage their own set of DEVELOPER_ID numbers or leave the DEVELOPER_ID set to 0.
- LocoNet developers who do not have a NMRA DCC Manufacturer ID should apply for a unique DEVELOPER_ID from Digitrax. This DEVELOPER_ID would be allocated by Digitrax under one ofthe following special reserved NMRA DCC Manufacturer ID numbers: 0, 254 & 255.
- DIY LocoNet Developers (LocoNet Hackers) should allocate and manage their own DEVELOPER_ID list under the DIY NMRA DCC Manufacturer ID of 13. This list will most likely be contained in a file in the files section of the LocoNet Hackers Yahoo list.
- The content contained herein is provided for reference purposes only. This means that it is provided solely for non-commercial private use as allowed by Digitrax.
- This information is use by Digitrax customers. No rights are conveyed for the commercial use of this information, and Digitrax is not able to provide technical support for private use.
- Any commercial software or hardware products developed using this information will require a license from Digitrax and also need to be certified by Digitrax.
- Neither the Editor, the website nor Digitrax conveys any warranty for this information and incurs no obligations for its use or incorrect usage.
- LocoNet is a proprietary and registered trademark of Digitrax Inc.