Twinleaf I/O (TIO)

Communications with Twinleaf devices is possible using the Twinleaf I/O (TIO) protocol. The simplest way to communicate is using text mode. Open a serial port with 115200 baud and receive rows of text data:

# gmr.x gmr.y gmr.z accel.x accel.y accel.z bar therm
00 -14328.8 -45702.9 -19212.5 -0.220632 -9.90098 0.459386 1019.48 34.8908
01 -14321.8 -45712.5 -19205.4
02 -14327.9 -45705.2 -19209.4
03 -14330.8 -45709.6 -19207.4
04 -14322.3 -45706.6 -19207.7
05 -14330.5 -45707.8 -19210.7 -0.216201 -9.9025 0.460285
06 -14321.9 -45713 -19206.9
07 -14327 -45702.5 -19214.6
08 -14329.7 -45710.3 -19211.5
09 -14323 -45708.1 -19210
10 -14332.7 -45705.1 -19213.3 -0.212381 -9.90403 0.461064
11 -14324.7 -45709.5 -19207.6
12 -14328.5 -45702.4 -19212.9
13 -14331.2 -45712.4 -19210.3
14 -14324.3 -45706.1 -19210.8

In this example, notice that the first three columns are sent at a faster rate than the other columns. Decimation rates are fully configurable using a command like

data.decimation 4

There is a lowpass/antialiasing filter that automatically adjusts to the decimated rate rate when <source>.data.autocutoff is 1. To manually adjust the filtering on a source, set <source>.data.autocutoff 0 and then adjust <source>.data.cutoff.

Type commands using rpc [val] format, such as:

coil.x.current 0.5

With a carriage return at the end. It will respond with a confirmation. Any data streams available on the device will be sent as rows of text numbers. The RPC response can be differentiated from the data stream by looking for the # character at the beginning. Simple examples using text mode:

Binary/native TIO protocol

The software tools all use a "native" TIO binary mode protocol. Available packages include:

Some people still need to implement the native TIO protocol from scratch. We are here to support you!

Physical interface

If your device has a USB-C connector, it is possible to use a standard USB-C cable to connect to a host. The sensors employ a USB CDC profile (USB serial port), which does not require drivers on recent operating systems.

Most of our devices provide an 8p8c (RJ-45) connector for serial communication, power delivery, and synchronization called the SSD connector. The pinout is:

Pin Signal Wire color
1 TX+ Orange/White
2 TX- Orange
3 RX+ Green/White
4 +5V Blue
5 Ground Blue/White
6 RX- Green
7 SYNC+ Brown/White
8 SYNC- Brown
9 Shield (Braid)

The wire colors correspond to the colors found in standard ethernet or CATx cable. Standard ethernet cables are appropriate. The serial port uses 3.3V RS-485, a differential signaling format that can be converted to rs-232 or LVTTL for microcontrollers using an RS-485 PHY chip. The data rate is 115200 (N81). We provide a SSD-USB converter dongle.

Where environmentally sealed connectors are required, we use 8STA00609SD on the device, which mates with the plug 8STA60609PD with the following pinout:

Pin Signal Wire color
1 +5V Blue
2 Ground Blue/White
3 TX+ Green/White
4 TX- Green
5 RX+ Orange/White
6 RX- Orange
7 SYNC+ Brown/White
8 SYNC- Brown
9 Shield (Braid)

Troubleshooting

If a windows computer is rebooted with a sensor plugged in, it can sometimes determine that the sensor is a serial mouse. It is possible to disable this in the registry.

Many Linux will attempt to connect with the sensor to determine if it is a modem. On systemd systems like Ubuntu, disable ModemManager using sudo systemctl stop ModemManager.