Flexible IO protocol - turag-ev/TURAG-Feldbus GitHub Wiki
This protocol allows a device to define a table of registers which can be read and written by the host. The registers are defined by:
- an index key
- the name of the register
- the data type: char, short, long, float
- the access mode: read-only, write-only or read/write
- an optional floating point conversion factor to be applied by the host when exchanging data values with the device which can be used to automatically convert the raw register values into values with a physical dimension.
The first byte of a packet (address) and the last (checksum) are left out in all packet descriptions/representations on this page.
| Request | Response | Description |
|---|---|---|
<Key>
|
<Byte>
|
Read a register value (response depending on data type of the requested register) |
<Key>
|
<Lowbyte><Highbyte>
|
|
<Key>
|
<Lowbyte0><Lowbyte1><Highbyte0><Highbyte1>
|
|
<Key><Byte>
|
<>
|
Set register value (request depending on data type of the requested register) |
<Key><Lowbyte><Highbyte>
|
<>
|
|
<Key><Lowbyte0><Lowbyte1><Highbyte0><Highbyte1>
|
<>
|
|
<Key><0><0><0>
|
<access mode, byte><data type, byte><conversion factor, float>
|
Read the definition of the specified register |
<1><1><1><1>
|
<number of registers, byte>
|
Read the number of available registers |
<Key><2><2><2>
|
<length of register name, byte>
|
Read the length of the registers name |
<Key><3><3><3>
|
<char 0><char 1>...<char n>
|
Read the name of the register (not null-terminated) |
<0xFF><0x00><Key 1><Key 2>…<Key n>
|
<0x00>: output table rejected<0x01>: output table accepted
|
Define the output table returned by the compound output command |
<0xFF><0x01>
|
<max entries>
|
Read the maximum number of table entries supported by the compound output command |
<0xFF>
|
depends on the output table definition | Compound output command: returns all values as defined in the output table |
Available data types:
| Data type | Length | Description |
|---|---|---|
| 0 | - | Unavaible register. Can be useful to remove a register without changing the keys of the remaining ones. |
| 1 | 1 | signed char (int8) |
| 2 | 2 | signed short (int16) |
| 3 | - | invalid value |
| 4 | 4 | signed int (int32) |
| 5 | - | Label-only register. One use case could be for the host software to display it as some kind of group label. |
| 6 | float | single accuracy floating point |
Available access modes:
| Access mode | Description |
|---|---|
| 0 | Read-only: An input value, for example the reading of an adc measurement. |
| 1 | Write-only: An output value, for example the desired speed of a motor. The host can also read it, but the device must never change it by itself. This allows the host to cache the values. |
| 2 | Read/Write: A value which can be written, but can also change by itself. |
- Valid register keys lie in the range from
0x01to0xFE. - Register values are transmitted in little endian byte order.
- When using any of the commands with a key which was not defined by the device, it will not return any answer at all.
- When trying to read a register with a data type other than 1, 2, 4 or 6, it will not return any answer at all.
- When trying to set a register which is read-only or has a data type other than 1, 2, 4 or 6, it will not return any answer at all.
- When setting a value the host can either send 1, 2 or 4 bytes for data types 1, 2 or 4. Missing data will be set to zero, exceeding data is discarded.
- If the conversion factor of a register is set to 0.0, the host should return the raw value of the register instead of applying the factor and converting it to a floating point value.
- If a device needs to support a register with read-write semantics which corresponds to a phyiscal value (for example the speed of a motor), this should be modeled using two registers: a write-only register ("desired speed") and a read-only register ("measured/actual speed").
- If the values of two registers whose function would qualify them as being write-only depend on each other, for instance because there are two ways to do configure the same function, it is desirable have the second register reflect the change written to the first. In this case both registers should be configured for read/write access, which prevents the host from caching outdated register values.