LoDi-S88-Commander LX API

Introduction

The device type is always 0x0A on the LoDi-S88-Commander.

Basic commands

GetVersion

This command returns the device identifier and the FW version of the device.

This command reads the settings of the LoDi-S88-Commander.

This command reads the settings of the LoDi-Shift-Commander.

The major version only changes when completely new hardware with different characteristics and a different feature set is released.

The minor version changes when the API is extended. Individual commands may also become incompatible.

The patch version changes for general bug fixes that do not touch the API.

DeviceConfigGet

This command reads the settings of the LoDi-S88-Commander.

The fields length bus1 and length bus2 give the number of modules connected to the respective bus. A module is always 16 inputs long. A total of 96 modules may be connected.

The entries speed bus1 and speed bus2 hold the S88 bus speed.

• 0: fast
• 1: normal
• 2: slow

The bus speed matters above all on long buses, to reach a high polling rate. The first clock of a bus cycle always keeps to the values defined in the S88 standard. Every module on the market should tolerate setting 1 (normal), since that matches the S88 standard. Setting 0 (fast) often works too. Every LoDi feedback module supports the fast setting.

The fields on delay bus1 and on delay bus 2 determine how quickly a detected occupancy should trigger. As a rule the value 0 (none) should be entered here.

• 0: none
• 10: short (100 ms)
• 100: medium (1 s)
• 250: long (2.5 s)

The fields off delay bus1 and off delay bus 2 determine how long an occupancy report should stay active once no signal is detected any more. As a rule the value 100 (medium) should be entered here, to avoid a flickering occupancy report and to keep a large enough safety margin.

• 0: none
• 10: short (100 ms)
• 100: medium (1 s)
• 250: long (2.5 s)

The separate buses field is not supported at present and should therefore be 0.

The µCon compatibility setting puts the LoDi-S88-Commander into a mode compatible with the µCon-S88-Master. The device opens an additional UDP port (11082) and listens there for µCon-S88-Master compatible commands. Every event is sent in the µCon-compatible format. Neither RailCom nor current measurement is available.

The use addresses field is not supported at present. It should be 1.

S88 modules

S88BusModulesGet

Reads every device connected to the two S88 buses, sorted by S88 address.

The count field carries the number of bytes that follow — taken twice, since two blocks of information follow, each as long as the value given in count.

The first block holds the modules actually scanned on the bus. A 0 in this block means a standard S88 module. S88.2 compatible modules carry the identifier 0x31 or 0x32 in module type.

• 0x31 LoDi-8-GBM
• 0x32 LoDi-RM-16+
• 0x34 LoDi-8-GBM-P

Module address 1 is 0 for a standard S88 module. Otherwise it gives the address stored in an S88.2 compatible module.

The second block brings the addresses of every S88 module together. Each position in the block maps to the resulting address on the S88 bus. Since S88 modules are usually two bytes long, the same address therefore appears twice in a row. Module address 2 may additionally have its top bit set to show that this module is ready to receive a new address — that it is in programming mode. If module address 2 is 255, the module has not been given an address yet.

S88ModulNameGet

The module address field holds the S88 address of the module to be read.

The length field determines the number of characters that follow in character 0 to character n. The resulting string holds the name of the module.

S88ChannelNamesGet

Reads the channel names of an S88.2 compatible module.

The reply packet holds a list of the channel names in channel order. Each entry consists of the length followed by the characters. The total number of entries can be derived either from the module type of the module asked or from the packet length.

The length field determines the number of characters that follow in character 0 to character n. The resulting string holds the name of the channel

Module status

S88MelderGet

Reads the detectors of every module.

The count field determines how many modules are sent afterwards.

StatusHigh and StatusLow together give the bit-coded occupancy report of the module.

S88LokAddrGet

Fetches the RailCom feedback for a particular channel of an S88.2 module.

Count says how many locomotive reports will follow. The reports are in no particular order.

The fields LokAddrHigh and LokAddrLow give the DCC address and the direction of the locomotive.

LokAddr = LokAddrHigh*256 + LokAddrLow

LokDirection = LokAddrHigh & 0x80

S88CurrentLevelsGet

Reads the current measured on every channel of an S88.2 module.

Count says how many channels will follow. The current measurements are sent in channel order.

The current field holds the measured current. This value is only an indicator and can be used to set the occupancy and short-circuit thresholds.

Events

Events are sent unasked to every active communication partner. As a rule they carry changes to the states listed under module status. Answers to CV commands sent to RailCom-capable locomotives also come back this way.

Event messages are numbered by the LoDi-S88-Commander from 0 to 255 in the packet number field. That is how a lost packet can be detected and the information refreshed with the status commands where needed.

S88EventsActivate

This command enables events for a connection.

The active field determines whether events are sent or not.

• 0: do not send events (unsubscribe)
• 1: send events (subscribe)

S88MelderEvent

This event carries changes in the occupancy report. Several changes can be transmitted at once,

The count field says how many reports will follow.

If nothing has changed at the detector, a keepalive is sent every 1 second as event 0x31 with change 0.

Every report holds the fields module address, giving the S88 address of the reporting module, channel, holding the reporting channel within the module, and status, showing whether the report is coming or going.

• 0: report going, there is no locomotive in the block
• 1: report coming, a locomotive has entered the block

S88LokAddrEvent

This event is sent when the RailCom feedback changes. It fires when a locomotive is newly detected in a block, or when a locomotive has not been detected in the block for a while (about 1 s).

The count field says how many reports will follow.

Every report holds the fields module address, channel, LokAddrHigh, LokAddrLow and status.

The module address holds the S88 address of the reporting module.

The channel field holds the channel within the module that triggered.

The fields LokAddrHigh and LokAddrLow together give the DCC address and the direction of the locomotive:

LokAddr = LokAddrHigh*256 + LokAddrLow

LokDirection = LokAddrHigh & 0x80

The status field says whether this is a coming or a going report.

• 0: the locomotive address was newly detected in the block.
• 1: the locomotive address has not been detected in the block for about 1 s.

S88RawEvent

This event passes on data sent by an S88.2 module that was not processed elsewhere. At present it is only used for current measurement and module status.

The count field says how many reports will follow.

Every report holds the fields module address, event type + channel, and status.

The module address holds the S88 address of the reporting module.

The Eventtyp_Kanal field holds the channel within the module that triggered together with the event type. It is coded as follows:

• Event type = Eventtyp_Kanal / 16
• Channel = Eventtyp_Kanal & 0x0F

The status field carries the contents of the report. How it is coded depends on the event type.

Track quality refers to the occupancy section, not to the locomotive. One of two methods is used to determine it:

1. Without RailCom: contact quality is derived from the jitter in the current measurement.
2. With RailCom: while a locomotive is running, how often its RailCom is received when it is addressed in DCC is measured. Stationary locomotives are not considered.

S88RailcomResponseEvent

This event is the answer to CV commands sent to a locomotive over DCC.

The event type can take the following values:

• 0x01: ACK, acknowledgement of a command (not implemented)
• 0x11: read CV byte, data holds the byte read
• 0x20: speed of the locomotive as reported by the decoder over RailCom DYN 0, 0..255 in km/h, from firmware v05.02.02
• 0x21: speed of the locomotive as reported by the decoder over RailCom DYN 1, 256 + data in km/h, from firmware v05.02.02
• 0x27: DCC quality as reported by the decoder over RailCom DYN 7, 0..100%, from firmware v05.02.02

The module address field encodes the S88 address of the S88.2 module.

The channel field gives the channel number within the module.

The DCC address of the locomotive is calculated from the two fields LokAddrHigh and LokAddrLow.

LokAddr = LokAddrHigh*256 + LokAddrLow

• PDFLoDi-S88-Commander LX API ServiceAdobe Acrobat document, 160.3 KB