A lightweight UDP telemetry system for FTC robots and other embedded targets. The Java library sends structured JSON packets from the robot (or any JVM process); a Python logger receives them and stores every reading in a SQLite triplestore for later query and analysis.

Built and maintained by Nexus Workshops LLC.

How it works

Robot / JVM process                     Laptop / driver station
+---------------------------+           +---------------------------+
|  UdpTelemetry.java        |  UDP/JSON |  telelog.py               |
|  put("left_motor","power",|---------->|  SQLite triplestore       |
|       0.8)                |  port 3000|  packets + triples tables |
|  send()                   |           +---------------------------+
+---------------------------+

Each call to send() serializes the current buffer into a JSON packet:

{
  "left_motor":  {"power": 0.8,  "temp": 42.1},
  "right_motor": {"power": 0.75, "temp": 38.5},
  "imu":         {"yaw": 45.0,   "steering": 0.05},
  "loop_time_ms": 50
}

telelog.py unpacks every packet into (subject, predicate, object) triples and writes them to SQLite. Nested values are flattened with dot notation (pid.p, pid.i). Flat scalars use the sender's IP as the subject.

Prerequisites

Java (sender)

Java 11 or newer
Apache Maven 3.6 or newer

Python (logger)

Python 3.8 or newer
No third-party packages required -- only the standard library

Installation

Windows

1. Install Java 11+

Download and run the OpenJDK installer from https://adoptium.net. Accept the default options. Verify in a new terminal:

java -version

2. Install Maven

Download the binary zip from https://maven.apache.org/download.cgi. Extract it (e.g. C:\tools\maven), then add C:\tools\maven\bin to your system PATH via System Properties -> Environment Variables. Verify:

mvn -version

3. Install Python 3

Download from https://www.python.org/downloads/windows/. Check "Add python.exe to PATH" during setup. Verify:

python --version

4. Clone and build

git clone https://github.com/nexusworkshops/udp-telemetry.git
cd udp-telemetry
mvn package

The shaded (self-contained) JAR lands at:

target\udp-telemetry-1.0.0-shaded.jar

Linux

1. Install Java 11+

sudo apt update
sudo apt install openjdk-11-jdk
java -version

2. Install Maven

sudo apt install maven
mvn -version

3. Python 3 is usually pre-installed -- verify

python3 --version

If not present:

sudo apt install python3

4. Clone and build

git clone https://github.com/nexusworkshops/udp-telemetry.git
cd udp-telemetry
mvn package

The shaded JAR lands at:

target/udp-telemetry-1.0.0-shaded.jar

Running

Open two terminals in the project directory.

Terminal 1 -- start the logger

Windows:

python telelog.py

Linux:

python3 telelog.py

Output:

[telelog] Schema initialized: telemetry.db
[telelog] Listening on 0.0.0.0:3000  db=telemetry.db  tag=(untagged)
[telelog] Ctrl-C to stop

Terminal 2 -- run the demo sender

Windows:

java -jar target\udp-telemetry-1.0.0-shaded.jar

Linux:

java -jar target/udp-telemetry-1.0.0-shaded.jar

The demo sender transmits 20 packets at 20 Hz simulating two drive motors, a chute hood servo, and an IMU. You will see each packet acknowledged in Terminal 1 and written to telemetry.db.

Logger options

python3 telelog.py [options]

  --port PORT     UDP listen port (default: 3000)
  --host HOST     Bind address (default: 0.0.0.0)
  --db FILE       SQLite database file (default: telemetry.db)
  --tag LABEL     Session label stored with every packet (e.g. auto_match_3)
  --init-db       Create/reset the schema and exit
  --quiet         Suppress per-packet console output

Example -- tag a match session:

python3 telelog.py --tag "semifinal_1" --port 3000

Sending from a real robot

Point UdpTelemetry at the driver station IP and add it to your op mode:

UdpTelemetry t = new UdpTelemetry("192.168.43.100", 3000);

// In your loop:
t.put("left_motor",  "power", leftDrive.getPower())
 .put("right_motor", "power", rightDrive.getPower())
 .put("imu",         "yaw",   imu.getRobotYawPitchRollAngles().getYaw(AngleUnit.DEGREES))
 .send();

Call t.close() in your op mode's stop() method.

Querying the database

-- All readings from the left motor
SELECT p.ts, t.predicate, t.object
FROM triples t
JOIN packets p ON p.id = t.packet_id
WHERE t.subject = 'left_motor'
ORDER BY p.ts;

-- Peak yaw value in a session
SELECT MAX(CAST(t.object AS REAL))
FROM triples t
JOIN packets p ON p.id = t.packet_id
WHERE t.subject = 'imu'
  AND t.predicate = 'yaw'
  AND p.tag = 'semifinal_1';

Project structure

udp-telemetry/
  src/main/java/com/nexusworkshops/telemetry/
    UdpTelemetry.java   -- UDP sender library
    Main.java           -- demo sender
  telelog.py            -- UDP logger / SQLite triplestore
  pom.xml               -- Maven build
  site/                 -- Nexus Workshops learning site assets

License

The source code in this repository is released under the MIT License. See LICENSE for the full text.

The field guide (Robot_Telemetry_Complete_Field_Guide.pdf/.docx) is separately licensed under the Nexus Workshops Content License Agreement and is not covered by the MIT License. Personal and educational use is permitted; commercial use requires a separate written license from Nexus Workshops LLC.

See LICENSES.md for a full breakdown of what each license covers.