LoDi-Con API

Introduction

The commands the LoDi-Con 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 0x13 on the LoDi-Con.

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: "v0.5.7"

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.

DatabaseUploadStart

This command starts uploading a database to the LoDi-Con. The upload itself runs over the FTP interface.

The length field defines the size of the database to be uploaded.

DatabaseActivate

This command finishes uploading the database. The file size given earlier is checked; if it matches, a confirmation dialog is shown to the user on the LoDi-Con.

DatabaseDownloadStart

This command has to be sent before downloading the database from the LoDi-Con.

The length field gives the current size of the database file on the LoDi-Con.

GetScreenshot

Requests a screenshot of the current LoDi-Con screen. The image data itself is transmitted as events

The mode field determines how many lines are transmitted per event.

0: only ever one line is transmitted per event.

1: several lines may be transmitted per event.

The fields width and height give the number of pixels.

Once the command is acknowledged, the screenshot has been taken and is transmitted from the LoDi-Con as events.

EventScreenshot

Sends the lines of the screenshot to the control software.

The line number field corresponds to the line in the screenshot

Portrait: 0-319, 240 pixels of 16 bits follow

Landscape: 0-239, 320 pixels of 16 bits follow.

If mode 1 is chosen, further lines may follow, each sent as the line number followed by the data. The maximum packet size is limited to 1500 bytes; how many lines were sent is derived from the packet size.

SendUIInput

Sends a virtual user interface input to the LoDi-Con. (from v0.5.7)

The type field holds the kind of input. The fields X, Y and C are filled depending on the type.

1: touch screen pressed – X: X pos, Y: Y pos

2: touch screen released – X: X pos, Y: Y pos

3: touch screen long-pressed – X: X pos, Y: Y pos

4: knob pressed

5: knob released

6: knob long-pressed

8: knob turned right

9: knob turned left

10: UI element clicked – X: X pos, Y: Y pos

11: swipe – X: X distance, Y: Y distance (X or Y has to be 0)

12: character input – C: ASCII code of the character

Every other type is used internally and is not passed on through the API.

Special key codes for the C field when type=12:

0x06: ACK – confirm, enter

0x15: NACK – cancel

0x08: DEL – delete

Further codes below 0x20 are used internally and should not be driven from outside.

GetLogbook

This command asks for the logbook of the LoDi-Con. The logbook is transmitted as events. (from v0.5.7)

EventLogbook

This event is sent after the GetLogbook command is received, to transmit the current logbook. It is also sent unasked whenever a new entry is added to the logbook. (from v0.5.7)

The timestamp field gives the time since the device started, in milliseconds.

The origin field holds the source of the entry.

1: WLAN

2: API

3: FTP

5: database

10: command station

11: LoDi-Rektor

12: LoDi-S8-Commander

13: LoDi-Shift-Commander

14: Märklin CS2 or CS3

15: ESU ECoS

16: WiThrottle

17: XpressNet

18: z21

20: locomotive

21: accessory

The level gives the severity of the entry.

0: emergency

1: alert

2: critical

3: error

4: warning

5: notice

6: info

7: debug

8: trace

The text is up to 122 characters long and is terminated with 0 if it is shorter than 122 characters.

Up to 10 entries are sent with one event.

ShowLoco

Shows a locomotive on the screen of the LoDi-Con. It can then be driven from the LoDi-Con. Only locomotives that already exist are shown.

The protocol field holds the track format to use.

0: any

1: DCC

2: Motorola

3: mfx

AddrL and AddrH together give the address of the locomotive.

If the locomotive is found and shown, the LoDi-Con returns an ACK packet. Otherwise NACK is sent.

• PDFLoDi-Con API ServiceAdobe Acrobat document, 118.1 KB