Walkthrough: from device to data
This walkthrough takes you from plugging in a Twinleaf device to viewing, adjusting, and logging its data on the command line, and finally reading it from Python. Install the twinleaf-rust tools first.
Prefer a graphical interface? The Twinleaf App does the viewing, recording, and settings steps below with no commands at all.
1. Connect to the device
Plug the device into your computer over USB, then open the device picker:
tio list
Select your device with the arrow keys and press Enter. This starts a shared connection for the commands in the rest of the walkthrough. Leave it running and open a second terminal.
If your device is not shown, press q and retry with tio list --all. You can also check the serial ports in your operating system's device manager. On Windows, look under Device Manager → Ports; on Linux, make sure your account is in the dialout group (covered in Installing Python).
For a noninteractive workflow, start the connection directly with the serial device path:
tio proxy /dev/cu.usbmodem1101 # macOS
tio proxy COM3 # Windows
tio proxy /dev/ttyACM0 # Linux
Find the sensor route
Most Twinleaf devices contain a communication module at the root route /, with the sensor behind it at /0. Commands that target one device, such as RPCs or exporting one stream, select that sensor with -s/0.
If the connection passes through an RS422 hub and then an RS422 communication module inside the device, the sensor is at /0/0; use -s/0/0. The device tree shown by tio list helps identify the correct route.
tio monitor and tio log do not need a route. The monitor displays every device in the tree, and logging from the root records them all.
2. Watch live data
Stream the device's data in a live display:
tio monitor
You should see the device's channels updating in real time, for example:
● PPMV Serial: PPMV.00023
Scalar magnetic field 52372.9214 nT
Vector magnetic field X 31695.5149 nT
Vector magnetic field Y 52257.1745 nT
Vector magnetic field Z -28478.5591 nT
Signal amplitude 1.1299 V
Use the arrow keys to navigate streams from any device in the tree and press Enter to graph the selected stream. Press Ctrl-C to stop.
3. Read and change settings
Every device parameter is a remote procedure call (RPC). List them all:
tio rpc list -s/0
Read one value:
tio rpc -s/0 field.data.decimation
Set a new value by adding it after the name:
tio rpc -s/0 field.data.decimation 10
Settings save automatically after about a minute; to save immediately, run tio rpc -s/0 dev.conf.save. Replace /0 with your sensor's route. Run tio rpc --help for more options, and see your device's reference page for its specific RPCs.
4. Log data and export to CSV
With the connection running, record raw data to a file:
tio log
This records every stream from every device in the tree. Press Ctrl-C to stop. The command writes a log.YYYYMMDD-XXXXXX.tio file in the current directory.
To export one sensor stream to CSV, select its route and stream name:
tio log csv -s/0 field log.YYYYMMDD-XXXXXX.tio
Replace /0 with your sensor's route.
5. Use Python
Twinleaf-python provides a Python API and itl, an interactive shell for exploring device settings.
Install twinleaf-python
Python 3.10 or later is required. Check your version with python3 --version, or python --version on Windows. If needed, follow Installing Python.
Create a virtual environment and install the package:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade twinleaf
On Windows Command Prompt:
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade twinleaf
Activate this environment whenever you use itl or run a Twinleaf Python script.
Explore settings with itl
Keep the tio list connection from step 1 running. Open another terminal, activate the virtual environment, and select the sensor route:
itl -s/0
For an RS422 hub followed by an RS422 communication module, use itl -s/0/0. At the prompt, type tl.settings. and press Tab to discover the settings available on that sensor. Call a setting with no argument to read it, or pass a value to change it.
Write a Python script
The Python API also connects to the running proxy. Specify the same sensor route:
import twinleaf
vmr = twinleaf.Device(route="/0")
print(vmr.samples.vector(10)) # Read ten vector samples
The device's settings are available as methods on the same object:
print(vmr.settings.vector.x0())
Use route="/0/0" for the RS422 arrangement described above. Run the script while the virtual environment is active:
python my_script.py
If itl is not found, confirm that the virtual environment is active. If Python cannot connect, confirm that the connection started by tio list is still running. See the twinleaf-python repository for more examples.
Questions or trouble? Email contact@twinleaf.com and we'll help.