Telemetry Protocol Documentation for firmware 1.2.6

[emdash]

The following is based on source code analysis, and my conversations with Brent.

The format is ascii, based on JSON. The data stream consists of a series of sample records, each containing a timesamp and multiple samples. Within each sample record, no white-space is found. There are DOS line endings (\r\n) between sample records.

Code: Select all

{"s":{"t":12345,"d"[0.00, 0.00, ... 254]}}\r\n{"s":{"t":12345,"d"[0.00, 0.00, ... 254]}}...

A more detailed explanation of a sample record follows:

Code: Select all

{"s":          // start of sample record
 {"t": 12345,  // sample record time stamp
  "d": [       // start of sample data
        0.00,  // first sample 
        ...
        254    // sample bitmap
       ]
 }
}                    // end of sample record

Metadata

TBD

Sample Data

Samples are encoded as a JSON array. The index of each sample within the array is not meaningful by itself. You need both the bitmap (last value in the array) and the channel config to correctly map a sample to a given hardware channel.

Channel IDs

For the purposes of having a configuration-independent way of identifying RCP channels, it's useful to define Channel ID as the following:

Code: Select all

ID  Name
----------------------------
00 Analog 0
01 Analog 1
02 Analog 2
03 Analog 3
04 Analog 4
05 Analog 5
06 Analog 6
07 Analog 7
08 PWM 0
09 PWM 1
10 PWM 2
11 GPIO 0
12 GPIO 1
13 GPIO 2 
14 Frequency 0 ( a.k.a. Timer 0)
15 Frequency 1
16 Frequency 2
17 Accel 0
18 Accel 1
19 Accel 2
20 Accel 3 (yaw)
21 GPS Latitude 
22 GPS Longitude
23 GPS Speed
24 GPS Time
25 GPS Satellites
26 Track Lap Count
27 Track Lap Time
28 Track Split Time;
29 Track Distance;
30 Track Pred Time;

The above is based on reading the source code here: https://github.com/autosportlabs/RaceCa ... leRecord.h


Note: you can't correctly map sample indexes to channel IDs without knowing the current configuration.

The following pseudo code converts the sample index to its corresponding channel id:

Code: Select all

function genChannelMap(sampleIndex, bitmap):
  let channel = 0
  let index = 0

  for each channel from 0 to MAX_CHANNELS:
    if enabled(channel):
      if bitmap & 1:
         if (index == sampleIndex): return channel
         index = index + 1
      bitmap = bitmap >> 1  // right shift
    channel = channel + 1
  return -1

Notes:

• The above code is not the most efficient way of processing multiple samples.
  
  Currently, the channel configuration can be represented as a 32-bit unsigned integer. This will not be the case if an expansion module is used.
  
  If you're attempting to parse this in a low-level language, like C, be aware of floating-point precision issues when handling the bitmap. In particular, a 32-bit float only has about 23-bits of integer precision. It would be best to parse the bitmap as an unsigned integer.