nexus-workshops/udp-telemetry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated dual license setup

Browse Source
This commit is contained in:
Eric Ratliff
2026-03-13 09:10:08 -05:00
parent d2993811ee
commit 410e8e3aa4
2 changed files with 313 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
LICENSES.md Normal file
View File

@@ -0,0 +1,39 @@
# Licenses
This repository contains two separately licensed components.
---
## Source Code -- MIT License
All source code in this repository is copyright Nexus Workshops LLC and is
released under the MIT License. This includes:
- `src/` (all Java source files)
- `telelog.py`
- `pom.xml`
- `site/` (HTML, CSS)
See [LICENSE](LICENSE) for the full MIT License text.
---
## Robot Telemetry: A Complete Field Guide -- Content License
The file `Robot_Telemetry_Complete_Field_Guide.pdf` (and `.docx`) is copyright
Nexus Workshops LLC, a subsidiary of Intrepid Fusion LLC, and is governed by
the Nexus Workshops Content License Agreement included with that document.
It is NOT covered by the MIT License.
Key terms of that license:
- **Personal and educational use** is permitted at no charge, provided this
license notice is retained and no fee is charged for access to the document.
- **Commercial use** -- including use in paid courses, training programs,
paid workshops, or any bundled paid product -- requires a separate written
commercial license from Nexus Workshops LLC.
- **Derivatives** must clearly attribute the original Work to Nexus Workshops LLC
and may not be represented as the original or as officially endorsed.
- All intellectual property rights in the document remain with Nexus Workshops LLC.
To inquire about commercial licensing, visit nexusworkshops.com.

274
README.md Normal file
View File

@@ -0,0 +1,274 @@
# udp-telemetry
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](https://nexusworkshops.com).
---
## 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:
```json
{
"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+**
```bash
sudo apt update
sudo apt install openjdk-11-jdk
java -version
```
**2. Install Maven**
```bash
sudo apt install maven
mvn -version
```
**3. Python 3 is usually pre-installed -- verify**
```bash
python3 --version
```
If not present:
```bash
sudo apt install python3
```
**4. Clone and build**
```bash
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:
```java
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
```sql
-- 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](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](LICENSES.md) for a full breakdown of what each license covers.