Updated dual license setup

README.md

@@ -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.