UAV-Interconnect-Bus.md

   1 INAV implements universal interconnect bus for various types of sensors and executable devices.
   2
   3 It's compatible with all existing controllers that have a spare UART and designed to be able to connect multiple sensors to one shared bus. Devices on the bus can be daisy-chained together for neater wiring.
   4
   5 ## Physical layer
   6 ### Option 1: Differential signalling
   7
   8 This option is taken from automotive applications and uses CAN bus transceivers (MCP2551 or SN65HVD232) to convert between twisted pair and UART. A special converter is required between each device and a bus. While this option is more expensive it's also very reliable.
   9
  10 Advantages: high reliability, long wires possible.
  11
  12 ### Option 2: Shared wire
  13
  14 This option is designed for tight spaces or very cost-sensitive solutions. Wiring should follow Siemens Application Node AP2921: On-Board Communication via CAN without Transceiver (https://www.mikrocontroller.net/attachment/28831/siemens_AP2921.pdf)
  15
  16 Advantages: low price, low wire count
  17
  18 ### Data format on the wire
  19
  20 From data format point of view it's plain asynchronous serial with following parameters:
  21 ```
  22 115200,8,n,1
  23 ```
  24 **FIXME: Chose a baud rate that has high reliability across multiple MCUs **
  25
  26 ### Notes
  27
  28 Both differential signalling and shared wire connection options are verified to work.
  29
  30 ## Device addressing
  31
  32 Each slave device on a bus has a unique **DevID** which defines device functionality (GPS, Optical flow, RC receiver etc). **DevID** is one byte and also serves as a device priority - master controller will favor devices with lower **DevID**
  33
  34 During discovery phase on the bus each device is assigned a **SlotID** which it must use for communicating with the master. **DevID** is only used during discovery phase.
  35
  36 ## Device capabilities
  37
  38 During discovery each device must report capability flags (16-bit field, see IDENTIFY command).
  39
  40 | Flag mask | Name         | Description |
  41 |-----------|--------------|-------------|
  42 | 0x01      | HAS_READ     | Indicates that device supports READ command and should be polled periodically |
  43 | 0x02      | HAS_WRITE    | Indicates that device supports WRITE command and can accept data |
  44
  45 ## Transactions on a bus
  46
  47 Everything on a bus is coordinated by a master device (flight controller) and all transactions are organised in **slots**. There are at most 32 slots (active devices) possible on a single bus.
  48
  49 Master begins transaction with one byte. Highest 3 bits indicate a **command**, while lower 5 bits indicate a **SlotID**. The rest of transaction depends on which command is being executed.
  50
  51 A 2ms guard interval is mandatory between transactions and is used by all devices to reset internal state. First byte after guard interval is assumed to be a command from master device.
  52
  53 ### Data integrity
  54
  55 Each transaction on a bus ends with a 1-byte CRC calculated by CRC-8/DVB-S2 algorithm.
  56 CRC is calculated over all transaction bytes starting with command byte.
  57 CRC is calculated by the data originator and verified by the master.
  58
  59 ## Commands on a bus
  60
  61 | Hex  | Binary  | Name       | Description |
  62 |------|---------|------------|-------------|
  63 | 0x00 | 000xxxx | IDENTIFY   | Performs device identification and slot assignment |
  64 | 0x20 | 001xxxx | NOTIFY     | Notifies a device about assigned (or re-assigned) slot |
  65 | 0x40 | 010xxxx | READ       | Performs a read transaction from a slot |
  66 | 0x60 | 011xxxx | WRITE      | Performs a write transaction on the bus |
  67 | 0x80 | 100xxxx | reserved   | Not used |
  68 | 0xA0 | 101xxxx | reserved   | Not used |
  69 | 0xC0 | 110xxxx | reserved   | Not used |
  70 | 0xE0 | 111xxxx | reserved   | Not used |
  71
  72 ### IDENTIFY (0x00)
  73
  74 | Byte | Originator | Description |
  75 |------|------------|-------------|
  76 | 0    | Master     | Value of (0x00 + SlotID)  |
  77 | 1    | Master     | DevID of requested device |
  78 | 2    | Master     | UIB Protocol version (0x00) |
  79 | 3    | Master     | CRC1 (over bytes 0-1)     |
  80 | 4    | Slave      | Poll interval (low byte) |
  81 | 5    | Slave      | Poll interval (high byte)  |
  82 | 6    | Slave      | Device flags (low byte)  |
  83 | 7    | Slave      | Device flags (high byte)   |
  84 | 8    | Slave      | Device parameters [0]     |
  85 | 9    | Slave      | Device parameters [1]     |
  86 | 10   | Slave      | Device parameters [2]     |
  87 | 11   | Slave      | Device parameters [3]     |
  88 | 12   | Slave      | CRC2 (over bytes 0-10)    |
  89
  90 During discovery phase master sends *IDENTIFY* commands for each supported **DevID**.
  91 Device with corresponding **DevID** must respond with desired poll interval (in milliseconds) and flag field.
  92 Master will send it's protocol version in *IDENTIFY* request. Slave device should respond only if it's able to talk this protocol version.
  93 Also, device which has detected it's **DevID** must remember the **SlotID** of the transaction - this will be the **SlotID** assigned to the device; it should also remember the protocol version it should be using to communicate.
  94
  95 Device parameters field (4 bytes) is device-specific and may be used to pass extended capabilities or non-standard flags to the host driver.
  96
  97 ### NOTIFY (0x20)
  98
  99 | Byte | Originator | Description |
 100 |------|------------|-------------|
 101 | 0    | Master     | Value of (0x20 + SlotID)   |
 102 | 1    | Master     | DevID of requested device  |
 103 | 2    | Master     | UIB Protocol version (0x00) |
 104 | 3    | Master     | CRC1 (over bytes 0-1)      |
 105
 106 Used to assign a slot to a device. Device shouldn't respond, but only keep record of assigned **SlotID**.
 107
 108 ### READ (0x40)
 109
 110 | Byte | Originator | Description |
 111 |------|------------|-------------|
 112 | 0    | Master     | Value of (0x40 + SlotID)  |
 113 | 1    | Master     | CRC1 (over byte 0)        |
 114 | 2    | Slave      | Data payload length (may be zero) |
 115 | 3... | Slave      | Data packet (up to 32 bytes)    |
 116 | last | Slave      | CRC2 (from start of packet)    |
 117
 118 Device with **SlotID** that was assigned to it during discovery phase must respond to this command with a variable-length data packet. If device has no new data available it should respond with zero payload length.
 119
 120 ### WRITE (0x60)
 121
 122 | Byte | Originator | Description |
 123 |------|------------|-------------|
 124 | 0    | Master     | Value of (0x80 + SlotID)  |
 125 | 1    | Slave      | Data payload length (may be zero) |
 126 | 2... | Master     | Data packet (up to 32 bytes)    |
 127 | last | Slave      | CRC2 (from start of packet)    |
 128
 129 Device with **SlotID** that was assigned to it during discovery phase must silently accept the data. No acknowledgement it done by the device. Together with **NOTIFY** this command brings a possibility to have several devices on the same DevID/SlotID.
 130
 131 ## Devices
 132
 133 It's recommended that each device use first byte of READ payload as flag field with following values:
 134
 135 | Bit | Mask | Description |
 136 |-----|------|-------------|
 137 | 0   | 0x01 | UIB_DATA_VALID - indicates data validity  |
 138 | 1   | 0x02 | Unused, must be zero |
 139 | 2   | 0x04 | Unused, must be zero |
 140 | 3   | 0x08 | Unused, must be zero |
 141 | 4   | 0x10 | Unused, must be zero |
 142 | 5   | 0x20 | Unused, must be zero |
 143 | 6   | 0x40 | Unused, must be zero |
 144 | 7   | 0x80 | Unused, must be zero |
 145
 146 ### Device ID = 0x12 : Rangefinder
 147
 148 Flag UIB_DATA_VALID will indicate that reading is valid (surface is in range and measurement is correct)
 149
 150 Recommended payload format:
 151
 152 ```
 153 typedef struct __attribute__((packed)) {
 154     uint8_t flags;
 155     uint16_t distanceCm;
 156 } rangefinderData_t;
 157 ```
 158
 159 ### Device ID = 0x13 : GPS sensor
 160
 161 Flag UIB_DATA_VALID will indicate that reading is valid, UIB_DATA_NEW - that data is fresh
 162
 163 Recommended payload format:
 164
 165 ```
 166 typedef struct __attribute__((packed)) {
 167     uint8_t fix_type;
 168     uint8_t sat_count
 169     uint8_t hdop;
 170     int32_t longitude;
 171     int32_t latitude;
 172     int32_t altitude_msl;
 173     int16_t vel_north;
 174     int16_t vel_east;
 175     int16_t vel_down;
 176     int16_t speed_2d;
 177     int16_t heading_2d;
 178 } gpsDataPacket_t;
 179 ```
 180
 181 ### Device ID = 0x80 : RC Receiver
 182
 183 Flag UIB_DATA_VALID will indicate that receiver has a valid link to transmitter. This is an **inverse** of FAILSAFE flag in common digital receivers.
 184
 185 Recommended payload format:
 186
 187 ```
 188 typedef struct __attribute__((packed)) {
 189     uint8_t  flags;         // UIB_DATA_VALID (0x01) - link ok
 190     uint8_t  rssi;
 191     uint8_t  sticks[4];     // Values in range [0;255], center = 127
 192     uint8_t  aux[8];        // Analog AUX channels - values in range [0;255], center = 127
 193     uint16_t reserved;      // Reserved for future use
 194 } rcReceiverData_t;
 195 ```
 196
 197 Values of `sticks[]` and `aux[]` array should be in range [0;255] and will correspond to [1000;2000] values.