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:
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 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 usesudo usermod -a -G dialout $USER
and on WSL you may needsudo usermod -a -G tty $USER
.