Tutorial: DIY devices

Posted on by

RaceChrono offers couple of APIs that you can use to connect your own devices, and input your data. The DIY devices are configured from RaceChrono > Settings > Add other device > Add other device > RaceChrono DIY

RC2/RC3 and NMEA 0183 streaming data

The oldest way to connect your DIY devices are the $RC2 and $RC3 data formats. It is a streaming clear-text protocol, that is sort of a RaceChrono extension to NMEA 0183 protocol that is a standard for ordinary GPS receivers. You can mix the NMEA 0183’s $Gxxxx sentences with your $RC2 and $RC3 sentences, or have your own sentences stand-alone.

The connection methods supported by this API in Android are Bluetooth RFCOMM and TCP/IP (Wi-Fi). The connection method supported in iOS is TCP/IP only, as the others are not supported by the operating system.

Data format description (pick either $RC2 or $RC3 format, not both):
$RC2,[time],[count],[xacc],[yacc],[zacc],[rpm/d1],[d2],[a1],[a2],[a3],[a4],[a5],[a6],[a7],[a8]*checksum
$RC3,[time],[count],[xacc],[yacc],[zacc],[gyrox],[gyroy],[gyroz],[rpm/d1],[d2],[a1],[a2],[a3],[a4],[a5],[a6],[a7],[a8],[a9],[a10],[a11],[a12],[a13],[a14],[a15]*[checksum]

  • $ is message start character
  • RC2 and RC3 are message identifiers
  • [time] Timestamp field should be empty, if your device doesn’t have GPS and does not output NMEA 0183 sentences mixed with the $RCx sentences
  • [time] Optional timestamp in NMEA 0183 format, for more accurate data timing, when mixed output with NMEA 0183 sentences.
  • [count] Count is an overflowing line counter 0-65535
  • [count] Count field is empty, when mixed output with NMEA 0183 sentences
  • [xyzacc] acc fields: -1.000 = -1G, 1.000 = +1G
  • [gyroxyz] gyro fields: degrees per second, -1.000 = -1 deg/s, 1.000 = +1 deg/s
  • [rpm/dx] digital channel fields, range -2000000.000 – 2000000.000
  • [ax] analog channel fields, range -2000000.000 – 2000000.000
  • * is message separator character
  • [checksum] NMEA 0183 type checksum, with two uppercase hexadecimal digits (one byte)
  • Each line is terminated with CR plus LF

Notice: If you’re not using mixed NMEA 0183 sentenced, a steady update rate is needed for this format due to the algorithm that RaceChrono uses to synchronize with GPS time. So pick update rate that is close as possible to 1/5/10/20/30/40/50/100 Hz. If you have to skip an update due to data overflow, make sure you add the ‘count’ field even for the skipped updates.

Here’s an example output using counter field (timestamp omitted):

$RC3,,2,0.240,-0.560,-0.290,7.938,-0.125,0.063,,,7.063,-40.438,2.625,70.875,9.875,-48.250,-6.360,-0.340,7.450,-6.100,-0.940,7.170,0,1,10*2F
$RC3,,3,0.250,-0.600,-0.300,7.875,-0.125,-0.063,,,7.625,-40.438,2.750,69.500,9.875,-49.000,-6.360,-0.360,7.450,-6.100,-0.960,7.140,0,1,10*02
$RC3,,4,0.250,-0.560,-0.300,7.750,0.000,-0.125,,,8.188,-40.438,2.875,71.000,9.188,-49.063,-6.360,-0.380,7.450,-6.110,-0.960,7.080,0,1,10*27
$RC3,,5,0.270,-0.560,-0.330,7.938,-0.063,0.000,,,8.750,-40.438,2.938,70.563,9.500,-48.250,-6.360,-0.380,7.450,-6.080,-0.950,7.070,0,1,10*2D
$RC3,,6,0.260,-0.540,-0.370,7.875,0.063,-0.063,,,9.250,-40.438,3.000,69.875,9.875,-48.563,-6.360,-0.390,7.450,-6.080,-0.920,7.090,0,1,10*21
$RC3,,7,0.240,-0.520,-0.300,8.000,0.000,0.188,,,9.813,-40.438,3.063,71.250,9.500,-49.000,-6.360,-0.400,7.440,-6.140,-0.910,7.110,0,1,10*00

And here’s the NMEA 0183 checksum calculation, it’s just simple XOR:

char* sentence = ... // characters between $ and *, not including them
unsigned byte checksum = 0; 
for (int i = 0; i < sentence.length; i++) { 
  checksum = checksum ^ (unsigned byte)sentence[i];
}

Bluetooth LE protocols

RaceChrono also supports couple of Bluetooth DIY protocols. These protocols are very new and they may be changed (improved) in the coming releases. The “Bluetooth LE” connection type needs to be selected in the device configuration. There are currently “GPS” and “CAN-Bus” APIs available.

The APIs and reference devices are documented here: https://github.com/aollin/racechrono-ble-diy-device

Once the CAN-Bus device is configured in settings (through the RaceChrono DIY device as described in the first chapter), there will be CAN-Bus channels section available in the Vehicle profile. You will need to add CAN-Bus channels to translate the raw CAN-Bus data that you feed to the app. The equations are described in here: https://racechrono.com/support/equations