LoDi-Rektor API

Introduction

The commands the LoDi-Rektor understands are listed below. Communication with the device is explained in General API.

Basic commands

GetVersion

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

The device type is always 0x03 on the LoDi-Rektor.

The firmware version is made up of the three parts major, minor and patch. It is shown in the format "v<major>.<minor>.<patch>". Example: "v01.03.01"

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.

CloseConnection

This command should be sent before the connection is closed.

DeviceConfigGet

This command reads the settings of the LoDi-Rektor.

The fault reaction field defines what happens at the CDE connector when a fault occurs.

• 0: the fault line on the CDE output is left unchanged
• 1: the fault is passed through to the CDE output. Boosters connected there switch off.

The StartStop field sets the behaviour on start/stop at the LoDi-Rektor. This applies both to the button and to the command over the API.

• 0: the states of the boosters do not change.
• 1: the boosters are switched with the start/stop signal.

The CDE entry sets the behaviour of the CDE connector.

• 0: the CDE connector is switched off. It is electrically inactive
• 1: the CDE connector is set to output. The error input is not evaluated.
• 2: the CDE connector is set to input. The track signal comes in over the CDE connector from another command station.
• 3: the CDE connector is set to output. The track signal is generated by the LoDi-Rektor. Further boosters can be connected to the CDE connector.
• 6: the CDE connector is configured as a sniffer. It listens for DCC commands, interprets them and passes them on in the track signal the Rektor generates. This mode is suitable for attaching another command station as a handheld controller.

The "Default protocol" field defines the protocol to be generated by default while there are no commands yet.

1 = DCC

2 = Motorola

3 = M3 / MFX®

SetWatchdog

Once the watchdog command has been received, the LoDi-Rektor expects it again at least every 2 seconds. If it fails to arrive, the boosters are switched off.

The status field switches watchdog monitoring on or off.

• 0: monitoring is switched off.
• 1: monitoring is switched on.

GetModules

This command reads the whole µCon bus.

The 64 type fields are filled in ascending order with every µCon address starting at 0. The values correspond to the types of the devices present.

Structure of type:

• Bit 7: the device is waiting to be assigned a new LoDi bus address.
• Bit 6: the device is in the bootloader. New firmware can be downloaded.
• Bits 5..0: device type:

• 0: no device at this address
• 1: µCon-Booster
• 2: Railspeed
• 3: LoDi-Booster
• 4: CDE connector
• 5: LoDi-TrainSpeed
• 6: LoDi-Booster 10A
• 7: LoDi-Booster 10A+
• 8: LoDi-DC-Car-Booster
• 9: LoDi-OpenCar-Booster
• 10: LoDi-CV-Programmer

GetModulName

Reads the name of a µCon device on the bus. The names are stored in the LoDi-Rektor against the µCon address.

µCon address holds the µCon address of the device to be read.

The length field carries the number of characters in the name.

The fields character 1 to character 16 hold the characters of the device name.

GetModuleVersion

Reads the firmware version of a µCon device on the bus. If the device does not support this command, 0 is returned for MajorVersion and MinorVersion.

µCon address holds the µCon address of the device to be read.

SetModuleName

Sets the name of a µCon device. The names are stored in the LoDi-Rektor against the µCon address.

The address field holds the µCon address of the device.

The length field determines the length of the string to be set, and with it the length of the packet.

The entries character 1 to character 16 hold the individual characters of the string. The string is not 0-terminated.

Booster commands

BoosterOn

This command switches one or more boosters on.

The booster address addresses either a single booster (1 to 63) or every booster (255).

The two booster channels A and B are switched with status A and status B:

• Status X = 0: booster channel off
• Status X = 1: booster channel on

The device answers with an ACK packet when the command has been carried out, or with a NACK packet when, for instance, the booster number given does not exist.

BoosterStatus

This command asks for the status of one booster or of all of them.

The booster address addresses either a single booster (1 to 63) or every booster (255).

The new field has the following meanings:

• 0: all boosters
• 1: new boosters

The count field returns the number of boosters read; each booster takes three bytes in the packet.

Booster address is the µCon address of the booster found. Status A and status B hold the status of the two booster channels according to the following pattern:

• Status X = 0: booster channel off
• Status X = 1: booster channel on
• Status X = 2: booster channel short circuit

BoosterDiagnostics

This command asks for the voltage, the current on both channels and the temperature.

The booster address addresses either a single booster (1 to 63) or every booster (255).

The count field returns the number of boosters read; each booster takes five bytes in the packet.

Booster address is the µCon address of the booster found.

The voltage field holds the output voltage measured at the booster. It is calculated as: voltage*17.0/146.0.

The fields current A and current B hold the current measured on the respective booster channel. For the LoDi-Booster the current is calculated as: current*2.5A/127.0.

For the LoDi-Booster 10A the calculation is: current*50mA

For the LoDi-Booster 20A the calculation is: current*100mA

The temperature is calculated as: temp-82.0 in degrees Celsius.

GetBoosterConfig

This command reads the settings of a booster.

The booster address names the booster to be read (1 to 63).

The booster address names the booster whose settings were read.

The sensitivity sets how long it takes before a short circuit is triggered. The following settings are possible:

• 10: 50 ms "very fast"
• 20: 100 ms "fast"
• 30: 300 ms "normal"
• 40: 500 ms "slow"
• 50: 700 ms "very slow"

The switch-off time says how long the booster should stay off after a short circuit before switching itself back on. This value is given in seconds.

The start mode sets the behaviour after a short circuit.

• 0: after a short circuit the booster is switched back on once the time set in sensitivity has elapsed.
• 1: the booster stays off after a short circuit.

The RailCom field says whether the booster generates a RailCom cutout.

• 0: the booster generates no RailCom cutout.
• 1: the booster generates a RailCom cutout.

The max. current entry is sent from firmware version 3.3.2 onwards. It gives the permitted maximum current per channel, calculated as: max. current * 50mA. If max. current is 0, the booster's own maximum applies.

TrainSpeed and Railspeed commands

GetTrainspeedConfig

Reads the settings of a TrainSpeed sensor.

The address field holds the µCon address of the TrainSpeed sensor to be set.

The address field holds the µCon address of the TrainSpeed or Railspeed sensor to be set.

The two fields ScaleHigh and ScaleLow give the scale 1:n for the measurement, where n is calculated as: n = (ScaleHigh*256 + ScaleLow) / 10.

The language field sets the language of the Railspeed sensor's display.

• 0: German
• 1: English

The LenAktiv setting enables length measurement.

• 0: length measurement inactive
• 1: length measurement active

TolAktiv enables tolerance measurement.

• 0: tolerance measurement of the speed is inactive
• 1: tolerance measurement of the speed is active.

TrainspeedSetConfig

Sets the settings of a connected TrainSpeed sensor.

The address field holds the µCon address of the TrainSpeed sensor to be set.

The two fields ScaleHigh and ScaleLow set the scale 1:n for the measurement, where n is calculated as: n = (ScaleHigh*256 + ScaleLow) / 10. For scale H0 (n=87), ScaleHigh is therefore set to 3 and ScaleLow to 102.

The language field sets the language of the Railspeed sensor's display.

• 0: German
• 1: English

The LenAktiv setting enables length measurement.

• 0: length measurement inactive
• 1: length measurement active

TolAktiv enables tolerance measurement.

• 0: tolerance measurement of the speed is inactive
• 1: tolerance measurement of the speed is active.

TrainspeedSetText

Changes the text shown on the Railspeed sensor.

The address field holds the µCon address of the TrainSpeed sensor.

The type field is not used further; 0 should be sent.

The length field determines the length of the string to be shown, and with it the length of the packet.

The entries character 1 to character 16 hold the individual characters of the string. The string is not 0-terminated.

TrainspeedSetActive

Enables and disables the events of TrainSpeed sensors.

The address field holds the µCon address of the TrainSpeed sensor to be enabled. If 255 is given, the events of every TrainSpeed sensor on the bus are enabled or disabled.

The active entry says whether the sensor's events are to be enabled or disabled.

• 0: disable events
• 1: enable events

TrainspeedEvent

This event is sent by the device automatically when TrainSpeed events are switched on.

The address field holds the µCon address of the TrainSpeed sensor that triggered.

Type determines the kind of event.

• 1: speed measurement
• 2: length measurement
• 3: tolerance of the speed

The entries WertHi and WertLo give the measured value. For speed and tolerance measurement the unit is mm/s, for length measurement mm. If WertHi and WertLo are 0, the measurement is invalid.

The measured value is calculated as: value = WertHi*256 + WertLo.

The status field shows whether the measurement has finished.

• 0: measurement finished, ready for the next one
• 1: measurement still running

Valid says whether the value shown in WertHi and WertLo is valid.

• 0: WertLo and WertHi are invalid.
• 1: WertLo and WertHi are valid.

The entries SensorL and SensorR show whether the left and right sensor are currently covered.

• 0: sensor clear
• 1: sensor covered

The valid bit can already carry a usable value while a measurement is still running — namely once the locomotive reaches the second sensor. That value may be used, but the locomotive must not be stopped, nor its direction changed, before the status field says the measurement has finished.

Command station

The command station can generate the DCC, Motorola and M3 / MFX® track signals. It is only active when the CDE connector is either switched off or set to output.

Track-Commander

The track commands are optional for the LoDi-Rektor and can be set first.

Every command is acknowledged (0x21) without returning additional data, unless defined otherwise.

ActiveTrackProtocols

This command sets the active track protocols.

Note: the default protocol set with the TrackProtocols command is switched on in addition to the protocols enabled by this command.

ActiveProtocols is bit-coded:

• Bit 0: DCC active
• Bit 1: Motorola active
• Bit 2: mfx active
• Bit 7: store the setting permanently

If bit 7 is set, the choice of protocols is stored permanently and is available again after the next start of the device.

The setting 0x85 enables the protocol selection DCC + mfx and stores it permanently.

If ActiveProtocols is not given, nothing is changed.

The reply packet always returns the protocols currently enabled.

TrackProtocols

This command selects the track protocol and starts track generation if nothing was selected.

The "Default protocol" field defines the protocol to be generated by default while there are no commands yet.

1 = DCC

2 = Motorola

3 = M3 / MFX®

If the highest bit in the field (bit 7) is set, the value is stored permanently and is used after a restart of the Rektor as well (0x81 for DCC, for instance).

RemoveProtocols

This command stops generation of the track protocol. It should be used when an external command station is connected to the CDE input.

Every command starts in the same field as described and is not repeated.

Protocol

DCC, Main = 1;

Sub 1 = 14 steps

Sub 2 = 27 steps (reserved, but not supported)

Sub 3 = 28 steps

Sub 4 = 126 steps

Sub 5 = 126 steps extended (new track commands, F29+ among others)

Motorola, Main = 2;

Sub 1 = 14 steps (the official number of speed steps).

Sub 2 = 27 steps, with 2 packets sent one after another (27A) (reserved, but not supported)

Sub 3 = 27 steps in one packet (27B) for newer MFX locomotives.

Sub 4 = 28 steps in one packet for older MFX locomotives.

Sub 6 = Motorola function decoder (old)

M3 / MFX®, Main = 3

No sub needed, so 0.

Once the sub part has been sent, it does not necessarily have to be sent every time. If a 0 is sent, the number of speed steps is not changed; any other value causes a change.

The locomotive address is given in the bytes AddrL and AddrH. How it is laid out depends on the protocol in use.

Short addresses (1-127) are given in AddrL. AddrH has to be zero.

DCC

Long addresses (1-9999) are given in AddrL and AddrH.

Motorola

With Motorola, addresses (1-255) can be set in AddrL. AddrH has to stay 0,

With M3 / MFX®, addresses (1-16383) can be specified in AddrL and AddrH.

M3 / MFX®

LocoRelease

Used to take an address out of the refresh cycle when the locomotive is no longer on the track.

Sub / Main

Sets the speed step and the direction.

Mask

Bit 7, 1 = forwards, 0 = backwards

Bit 6, 1 = emergency stop (speed has to be 0), 0 for normal speed control.

The speed field specifies the speed step (0 = stop, 1 the first step up to the maximum). The step depends on the protocol chosen and its maximum speed step.

If the command is sent without parameters, the stored data is read out and the packet is sent back as a reply (with 0x21). The packet can also be sent as an event (0x22) when another client changes the settings.

LocoFunctions

Sets the functions that are part of the refresh cycle.

Index

Indices 0-127 can be set individually (0 = f0, 1 = f1). Data has to be 0 or 1.

To set functions more efficiently, function groups can be selected with the upper bit of the index field (bit 7).

Group 1: index = 0x81, data = 0 0 0 f0 f4 f3 f2 f1

DCC (f0-f28)

Group 2: index = 0x82, data = 0 0 0 0 f8 f7 f6 f5

Group 3: index = 0x83, data = 0 0 0 0 f12 f11 f10 f9

Group 4: index = 0x84, data = f20 f19 f18 f17 f16 f15 f14 f13

Group 5: index = 0x85, data = f28 f27 f26 f25 f24 f23 f22 f21

For DCC 126 extended there are additional groups:

Group 6: index = 0x86, data = f36 f35 f34 f33 f32 f31 f30 f29

Group 7: index = 0x87, data = f44 f43 f42 f41 f40 f39 f38 f37

Group 8: index = 0x88, data = f52 f51 f50 f49 f48 f47 f46 f45

Group 9: index = 0x89, data = f60 f59 f58 f57 f56 f55 f54 f53

Group 10: index = 0x8a, data = f68 f67 f66 f65 f64 f63 f62 f61

These groups are the same original DCC packets that have to be sent.

Motorola (f0-f4)

These functions can be set individually, since each one sends its own packet to the track. Should you want to set every function at once, do the following:

Index = 0x81, data = 0 0 0 f0 f4 f3 f2 f1

For Motorola function decoders it is more efficient to set index 0x81 with f1-f4: every function is then set at once.

Group 1: index = 0x81, data = f7 f6 f5 f4 f3 f2 f1 f0

M3 / MFX® (f0-f31)

Group 2: index = 0x82, data = f15 f14 f13 f12 f11 f10 f9 f8

Group 3: index = 0x83, data = f23 f22 f21 f20 f19 f18 f17 f16

Group 4: index = 0x84, data = f31 f30 f29 f28 f27 f26 f25 f24

Functions f16-f31 can be set individually, since for these an individual packet is sent to the track after all.

The command without parameters reads the data out and sends the packet described back as a reply (with 0x21). The packet can also be sent as an event (0x22) when another client changes something.

LocoBinary

Sets the binary functions (possible in DCC only).

Extra

The field can also be set to zero for the same effect.

AccessoryState

For setting the state of any function decoder.

basic / extended / aspect

There are two settings: a standard and an extended accessory command. The standard command has two states (aspect 0 and 1) and is supported by DCC and Motorola.

With the extended command for DCC, 128 aspects can be set (value 0-127).

If zero is used for the protocol, the default protocol is used. If M3/MFX® is selected, Motorola is used for switching.

Depending on how the addresses are interpreted, you should normally add 4 to them to match the general standard (RCN-213). Addresses 0-3 are a kind of shadow address used by a few systems only (Roco, for instance).

DCC

If the highest bit of the data field (bit 7) is set, standard commands are sent. In that case the lowest bit of the data field (bit 0) gives the state and has to be 0 or 1. Whether the output is active is indicated by bit 3. Normally the command is sent twice, to activate and deactivate, since it is usually a pulse.

Motorola

Supports basic accessories only, with bit 0 as the state (1 = green, 0 = red) and bit 3 to indicate whether the output is active.

LocoCV / AccessoryCV

For setting the configuration variables of vehicles (0xC5) and of accessories (0xC6).

AddL

The mask field holds the action in the lowest nibble (bits 3..0):

0 = write byte, the data field holds the byte value

1 = write bit, the data field has the bit value in the upper bit (bit 7) and the index in the other bits.

2 = read byte, the data field is ignored and should be set to zero.

For accessories, bit 7 of the mask field decides whether basic (1) or extended (0) is used.

At present configuration variables are supported for DCC only, with indices from 0-1023.

ProgTrackCv

This command can only be carried out when a LoDi-CV-Programmer (the programmer from here on) is connected to the LoDi bus. If no programmer is connected, the answer is NACK. Since operations on the programming track take longer, a command may already be running; in that case BUSY is returned. If the programmer accepted the command, ACK is returned.

For read operations the answer comes as a ProgResponseEvent. Write operations produce no event.

Value

All CV registers (1..1024) are addressed directly. Subtract 1 from the CV address, which gives addressing from 0 to 1023 corresponding to CV addresses 1 to 1024.

For write operations, bit 7 in CV_H is set.

The value field is optional and is only needed for write commands.

ProgTrackCvEvent

This event is the answer to CV commands sent to a locomotive or an accessory on the programming track.

Event from the device

CV_H and CV_L: see ProgTrackCV (read only)

Value: the contents of the CV or register addressed.

LocoID

0xCC

The UID is specified in ID1-4.

LoDi-Rektor API Service

• PDFAdobe Acrobat document, 253.6 KBThe commands the LoDi-Shift-Commander understands are listed below. Communication with the device is explained in [General API](docs:api-allgemeines).