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 ("N-8-1") 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:

MATLAB

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)

TX is data sent to the sensor. RX is data received from the sensor.

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 LVDM, a differential signaling format that can be converted to RS-232 or LVTTL for microcontrollers using an LVDM or LVDS PHY chip. The data rate is 115200 (N81). We provide a SSD-USB converter dongle with all sensors that do not also have a USB-C port.

Troubleshooting

Windows

The serial-USB adapter uses FTDI drivers that may not be installed by default.
Mouse pointer goes crazy: 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.

Linux

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 apt remove modemmanager. To access serial ports without superuser access use sudo usermod -a -G dialout $USER and on WSL you may need sudo usermod -a -G tty $USER.