1.4 Basic Protocol - turag-ev/TURAG-Feldbus GitHub Wiki
The basic protocol must be implemented by all devices and reserves all packets whose first data byte equals zero for internal use. It provides basic functionality including
- device discovery
- querying of device information
- status reporting
Different kinds of devices can be distinguished using two IDs:
- device protocol ID: defines the device protocol implemented by the device; range: 0x01 - 0x7F
- device type ID: specifies the particular type of a device within the device protocol: 0x00 - 0xFF
Packets specified here must be supported by all devices. Reserved packets must not be used by device protocols.
| Request | Response | Description |
|---|---|---|
| - |
<>
|
Availability Request ("Ping Package"): The slave responds with an empty packet to indicate its readiness |
<0x00> |
11 byte | Output of Device Info packet |
<0x00><0x00> |
variabel | Return the device name (without '\0' character) |
<0x00><0x01>
|
<uint32>
|
Uptime counter output (uint32_t value; undefined if feature not available) |
<0x00><0x02>
|
variabel | Return the version info string (without '\0' character) |
<0x00><0x03>
|
<uint32>
|
Return the number of correctly received packets (uint32_t) |
<0x00><0x04>
|
<uint32>
|
Return the number of buffer overflows (uint32_t) |
<0x00><0x05>
|
<uint32>
|
Return the number of lost packets (uint32_t) |
<0x00><0x06>
|
<uint32>
|
Return the number of checksum errors (uint32_t) |
<0x00><0x07>
|
<uint32><uint32><uint32><uint32>
|
Return all four packet numbers in the following order: correct packets, buffer overflows, lost packets, checksum errors (4x uint32_t) |
<0x00><0x08>
|
<>
|
Reset all 4 packet numbers (empty packet as answer) |
<0x00><0x09>
|
<uint32>
|
Return the UUID of device (uint32_t) |
<0x00><0x0A>
|
variabel | Return the extended device info packet. Not available when the device returns a legacy style device info packet. |
<0x00><0x0B>
|
<uint32><uint16>
|
Return the capacity of the static data storage and its page size. For write operations valid values of the address offset are limited to multiples of the page size. |
<0x00><0x0C><uint32><uint16>
|
<uint8><...>
|
Read data from the static data storage from the specified offset with the specified length. The first byte of the response is the error code. |
<0x00><0x0D><uint32><...>
|
<uint8>
|
Write data to the static data storage at the specified offset. Returns an error code. The specified offset must be a multiple of the page size. If the supplied data is shorter than a multiple of the page size, the remaining data of the last page may be deleted. |
<0x00><...>
|
all other packages with leading 0x00 are reserved |
When sending a packet whose single data byte contains 0x00, the device outputs a device information record. There is an older, legacy variant:
| data byte number | description |
|---|---|
| 0 | device protocol ID |
| 1 | device type ID |
| 2 |
Bits 0-2: checksum type ID Bit 3: 0 (legacy device info packet) Bits 4-6: 0 Bit 7: availability of packet statistics |
| 3-4 | input buffer size |
| 5-6 | undefined |
| 7 | length of device name (without '\0' character) |
| 8 | length of version info (without '\0' character) |
| 9-10 | frequency of uptime counter in Hz (0 indicates that the feature is not available) |
The newer device info contains the UUID and moves fields which are not always required to an extended device info packet. It looks like this:
| data byte number | description |
|---|---|
| 0 | device protocol ID |
| 1 | device type ID |
| 2 |
Bits 0-2: checksum type ID Bit 3: 1 (new device info packet) Bits 4-6: 0 Bit 7: availability of packet statistics |
| 3-4 | size of extended device info packet |
| 5-8 | UUID |
| 9-10 | frequency of uptime counter in Hz (0 indicates that the feature is not available) |
The extended device info contains the remaining information, including the name and version string, thus saving a few round-trips:
| data byte number | description |
|---|---|
| 0 | 0 |
| 1 | length of device name (without '\0' character) |
| 2 | length of version info (without '\0' character) |
| 3-4 | input buffer size |
| 5-x | device name |
| x | version info |
It can sometimes be helpful for diagnostic purposes to know how long a device is already running. Therefore, the basic protocol offers a command to read an uptime counter. The uptime can be calculated with the uptime frequency from the device info. If the device does not support this feature, the uptime frequency must be 0.
For diagnostic purposes, the slave can request information about the number of correctly transmitted packets and incorrect transmissions. To save memory, this feature can also be disabled. Bit 7 in byte 2 of the device info indicates whether the device provides the packet statistics or not.
The device may offer the possibility to store arbitrary static data to a non-volatile memory by returning a static storage capacity greater than zero. The basic protocol offers functions to read and write to/from this store. Because often such a memory is organized in pages, the device can additionally return this page size, which limits the allowed address offsets for write operations to multiples of that value. The intepretation of the data is up to the device and/or the host. The available error codes returned by the read and write functions are 0: success, 1: offset/size error, 2: error on write.
Broadcast address = 0 and matching checksum are not specified in the table.
Broadcasts specified here must be supported by all devices. Reserved broadcasts must not be used by device protocols.
| Command name | device protocol ID | data | description | response |
|---|---|---|---|---|
| - | - | the broadcast without device protocol ID and data is reserved | ||
| NopBroadcast | 0x00 | - | Does nothing, but can be used to wake up sleeping devices before doing actual communication, when the GoToSleep broadcast was used. | |
| SendBroadcastPing | 0x00 | 0x00 | ping any device without valid bus address | UUID of answering device |
| SendUuidPing | 0x00 | 0x00;[UUID] | ping device with given UUID | empty packet |
| ReceiveBusAddress | 0x00 | 0x00;[UUID];0x00 | return Bus address of device with given UUID | bus address |
| SetBusAddress | 0x00 | 0x00;[UUID];0x00;[Bus_address] | set bus address of device with given UUID | [0-failure|1-success] |
| ResetBusAddress | 0x00 | 0x00;[UUID];0x01 | reset bus address of specified device | empty packet |
| EnableBusNeighbours | 0x00 | 0x01 | enable bus neighbors | |
| DisableBusNeighbours | 0x00 | 0x02 | disable bus neighbors | |
| ResetAllBusAddresses | 0x00 | 0x03 | reset all bus addresses | |
| RequestBusAssertion | 0x00 |
|
Requests all devices to generate a bit mask with the given length, perform a bitwise-and between the mask and its UUID and perform a bus assertion if the result matches the given search address | special bus assertion where the device actively pulls the bus low for 15 symbol times and then simply releases it. |
| RequestBusAssertionIfNoAddress | 0x00 |
|
same as RequestBusAssertion broadcast, but only applies to devices which do not have a valid bus address. | same as RequestBusAssertion broadcast |
| GoToSleep | 0x00 | 0x06 | Requests the device to enter a powerdown mode. It should be able to wake up upon bus traffic, but it is allowed to take some time for that. The NopBroadcast can be used to wake up devices before doing actual communication. | |
| 0x00 | * | all broadcasts with device protocol ID 0x00 are reserved |
The same applies to fast broadcasts using a broadcast ID of 0x80.
When communicating between the host and the devices, errors may occur which look differently from either side.
| No answer | The device returned no data within the allowed response time. |
| Missing data | The device returned too little data within the response time. |
| Checksum error | The received data contained errors. |
| Transmission error | The host experienced errors while sending the data. |
| Overflow | If the buffer in the device is insufficient to store the complete packet, it must be discarded. If the packet was actually addressed to the device, this is counted as an overflow error. |
| Lost packets | This error indicates that an already received but not yet processed packet had to be discarded because a new packet is already arriving. |
| Checksum error | The packet received from the host contained errors. |
The sum of these three errors + the number of correctly received packets results in the sum of all packets directed to the device including Broadcasts.
Lost packets can usually only occur in two scenarios:
- Immediately after sending a broadcast, the host sends any other packet.
- A received packet is not processed or the processing takes so long that the host interprets it as lost and sends the next packet.
Device protocols define the exact device behavior based on the basic protocol. Pre-defined device protocols are listed here. It is recommended to stick to simple, stateless approaches as they are much less error-prone.
Most TURAG-Feldbus devices have a bootloader that allows updating the firmware. It is active before the start of the actual program. This works as follows:
- After starting the device, the bootloader will be active for a certain time.
- During this time, the host can ask all devices on the bus to remain in the bootloader.
- Devices without a bootloader have to check after powerup for a certain time, if there is bus communication and if so, stop their operation.
- If the host does not want to upgrade the firmware, he must wait a certain minimum of time before he starts communicating on the bus to make sure all devices have left their bootloader.