Device API
General API
Ports used
Every LoDi device has an IP address of its own. Communication runs over UDP on port 11092.
Ping requests over ICMP are answered so that communication can be checked. That facility is meant for the user rather than the control software; see Establishing a connection below.
LoDi LX devices such as the LoDi-S88-Commander LX also communicate over TCP on port 11092.
Packet format
A UDP data packet consists of at least 3 bytes.
| Packet type | Command | Packet number | Payload |
|---|---|---|---|
A TCP data packet consists of at least 5 bytes.
| Length high | Length low | Packet type | Command | Packet number | Payload |
|---|---|---|---|---|---|
The length covers every byte from the packet type through to the last payload byte. This information is needed to tell packets apart within a TCP stream.
The following packet types are defined:
- 0x20: REQ – request; answered with ACK, NACK or BUSY
- 0x21: ACK – the REQ packet was processed successfully
- 0x22: EVT – packet sent automatically about changes at the sensors
- 0x23: BUSY – the REQ packet has not finished executing yet
- 0x3F: NACK – the REQ packet is faulty. The request cannot be processed.
The command field has to hold a command the device supports. The packet number can be chosen freely; it is mirrored in the reply packet. The packet number of EVT packets is assigned sequentially by our devices.
The payload is optional. Its length depends on the command in question.
Course of communication
Requests from the control software
Communication is half duplex. Every request from the control software starts with a REQ packet. The device answers with an ACK or a NACK packet.
For commands that need to talk to sub-devices, a REQ packet may also be acknowledged with BUSY. In that case the REQ packet is to be sent repeatedly until either ACK or NACK comes back; other requests may be sent in between. Commands that can answer with BUSY are marked accordingly.
If no answer comes from the device within 200 ms over UDP, packet loss can be assumed. The REQ packet is then to be sent again. If there is no answer after three REQ packets, assume loss of communication with that device.
Over TCP retransmission on packet loss happens automatically.
Example: requesting the firmware version of the device
| Packet type | Command | Packet number |
|---|---|---|
| 0x20 | 0x0F | 0x01 |
| Packet type | Command | Packet number | Payload | |||
|---|---|---|---|---|---|---|
| 0x21 | 0x0F | 0x01 | 0x03 | 0x01 | 0x03 | 0x01 |
Events
A device can send an unsolicited event to the control software. Events are always sent in an EVT packet. EVT packets must not be acknowledged by the control software. EVT packets are sent with an ascending packet number, which is how a missed EVT packet is noticed.
Example: an event from a LoDi-S88-Commander
| Packet type | Command | Packet number | Payload | ||||||
|---|---|---|---|---|---|---|---|---|---|
| 0x22 | 0x31 | 0x02 | 0x02 | 0x02 | 0x06 | 0x01 | 0x02 | 0x07 | 0x00 |
Establishing a connection
A connection should be established in the following steps:
- Open a UDP port locally in the control software, or open a TCP connection to the device. The local port number does not matter.
- Send a REQ packet with command 0x0F (query FW version) to the IP address of the device on port 11092.
- Check the answer, timeout 200 ms
- Repeatedly: handle event packets, send further commands, and poll for the information you need where necessary
Searching for devices
Our devices also answer UDP broadcast requests. To scan for devices it is enough to send a REQ packet with command 0x0F by UDP broadcast to the broadcast address of every network interface whose netmask is not 255.255.255.255. The devices then answer with an ACK packet carrying their device identifier and firmware version. The following device identifiers are defined:
- 0x03: LoDi-Rektor
- 0x09: LoDi-Shift-Commander
- 0x0A: LoDi-S88-Commander (LX)
The LoDi-S88-Commander can be told apart from the LX: the LX has firmware from version v06.00.00 onwards.
If the network interfaces cannot be queried, the general broadcast address 255.255.255.255 can be used.
Example:
networks found:
wlan: 192.168.1.2 netmask 255.255.255.0 broadcast 192.168.1.255
lan0: 192.168.2.1 netmask 255.255.255.0 broadcast 192.168.2.255
Two UDP broadcast packets are to be sent:
- Destination address 192.168.1.255, destination port 11092, contents of the UDP packet 0x20, 0x0F, 0x00
- Destination address 192.168.2.255, destination port 11092, contents of the UDP packet 0x20, 0x0F, 0x01
Answer from the devices:
- Address 192.168.2.88, contents of the UDP packet 0x21, 0x0F, 0x01, 0x0A, 0x04, 0x02, 0x04 LoDi-S88-Commander v04.02.04
- Address 192.168.2.44, contents of the UDP packet 0x21, 0x0F, 0x01, 0x03, 0x01, 0x03, 0x01 LoDi-Rektor v01.03.01
Every device is therefore on network interface lan0.