sticklink 0.1.1__tar.gz

sticklink-0.1.1/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.1 (2026-10-06)
+
+- A small window (`sticklink gui`, also what you get when you start the program without arguments): pick the radio or Demo, Start / Stop, status light, buttons for the web pages.
+- Released on PyPI: `uvx sticklink run --demo`, `pip install sticklink`.
+- README links and images are absolute, so the PyPI page renders.
+
+## 0.1.0 (2026-10-06)
+
+First packaged version.
+
+- Live stick, switch and telemetry capture from an EdgeTX radio over USB serial (`DDSTK.lua`, DDLOG protocol v1).
+- Overlay pages for OBS browser sources: classic panel (`/overlay`) and the effects overlay (`/fx`, stickcam renderer, 8 styles).
+- Double-click settings panel; receiver-style setup page (`/setup`) with a 3D quad, channel monitor and learn-by-moving mapping.
+- Smooth, lag-free trails from 20 Hz radio data.
+- Session recordings (JSONL), `replay`, `check-log` quality reports.
+- REST API with OpenAPI spec and offline Swagger UI (`/docs`).
+- The effects overlay fills any Browser Source size and keeps the gimbals centered in it.
+- Permanent links: the settings panel shows a copyable `?cfg=` link for the current configuration (the address bar never changes). A link page uses exactly
+  that configuration and does not write to the server; plain URLs keep using the saved settings.
+- Scene switching: `/modes` page (Betaflight Modes style) to switch OBS scenes from radio switches, with ranges per scene, priority sorting, learn-by-flipping,
+  safe defaults (off until enabled, adopts the current positions, never acts on stale data); OBS WebSocket client; new API under `/api/v1/obs` and `/api/v1/scene-modes`.
+- Every POST now requires `Content-Type: application/json`, even with an empty body (closes cross-site form triggers).
+- Telemetry HUD (`/hud`, `/hud/link`, `/hud/battery`, `/hud/gps`): Link, Battery, GPS and Status blocks in the stickcam styles, three layouts, and a GPS map
+  with live track, home marker and distance (OpenStreetMap tiles by default, switchable, with a track-only fallback).
+- The radio script forwards a broad sensor list (round-robin, per-sensor failure isolation) and the GPS position; new `G` protocol record; sensor names may contain `%`.
+- New API: `GET /api/v1/gps`, `GET`/`DELETE /api/v1/gps/track`; `hud` settings.
+- Self-contained binaries for Linux, Windows and macOS, plus a Python wheel and source package.

sticklink-0.1.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md CHANGELOG.md THIRD_PARTY_NOTICES.md
+recursive-include docs *.md *.png
+recursive-include tests *.py *.cjs
+recursive-include packaging *
+graft fx
+prune fx/node_modules
+global-exclude __pycache__ *.pyc

sticklink-0.1.1/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: sticklink
+Version: 0.1.1
+Summary: Live stick and telemetry overlays for OBS, from an EdgeTX radio (RadioMaster Pocket)
+Project-URL: Repository, https://github.com/rotordeck/sticklink
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Multimedia :: Video
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp<4,>=3.10
+Requires-Dist: pyserial<4,>=3.5
+Provides-Extra: dev
+Requires-Dist: openapi-spec-validator>=0.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Provides-Extra: binary
+Requires-Dist: pyinstaller>=6.10; extra == "binary"
+
+# Sticklink
+
+**Live stick and telemetry overlays for OBS, straight from your radio.**
+Sticklink reads your sticks, switches and link telemetry from an EdgeTX radio (tested on a RadioMaster Pocket) over USB,
+serves them as an OBS Browser Source with the same look as [stickcam](https://github.com/rotordeck/stickcam)'s after-the-fact
+overlays, and records every session so you can check and reuse the data later.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/fx-neon.png" width="32%" alt="Neon style">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/fx-arcade.png" width="32%" alt="Arcade style">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/fx-hacker.png" width="32%" alt="Hacker style">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/hud-corners-neon.png" width="49%" alt="Telemetry HUD, neon">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/hud-corners-hacker.png" width="49%" alt="Telemetry HUD, hacker">
+</p>
+
+## What you get
+
+- **Effects overlay** (`/fx`): eight styles (Clean, Minimal, Neon, Arcade, Synthwave, Inferno, Unicorn, Hacker) with glowing
+  trails, sparks, shockwaves and live throttle timers. Trails are smooth curves with no added delay.
+- **Telemetry HUD** (`/hud`): **Link**, **Battery**, **GPS** and **Status** blocks as badges, in the same eight styles. GPS shows a live
+  map with your track, home marker and distance. Each block is also its own page (`/hud/link`, `/hud/battery`, `/hud/gps`), so you can
+  put them in OBS as separate sources. It shows what your radio really receives (see [limits](https://github.com/rotordeck/sticklink#status-and-honest-limits)).
+- **Receiver setup page** (`/setup`): a live 3D quad, stick bars and a 16-channel monitor, like Betaflight Configurator's
+  receiver tab. Press **Learn** and move a stick or switch to assign roll, pitch, yaw, throttle, ARM and Crash Flip, so a
+  swapped or reversed stick is a ten-second fix.
+- **Double-click to configure**: style, effect strength, size and video delay, saved on the
+  server so an OBS source updates by itself. The panel also shows a **permanent link** for the current look: use it as a source's URL to pin
+  that source to its own configuration.
+- **Scene switching** (`/modes`): a Betaflight-style Modes page for your **OBS scenes**: give each scene ranges on a switch channel, sort them so the
+  upper scene wins, and OBS follows your switches (via OBS's built-in WebSocket). Off until you turn it on, and it never acts on stale radio data.
+- **Recordings**: one JSONL file per session, a `check-log` quality report (rate, gaps, lost records, channel ranges) and
+  `replay` to play a session back through the overlay.
+- **REST API + Swagger UI** (`/docs`, works offline) and a WebSocket stream for your own tools.
+- **No dependencies to install**: downloads are single self-contained programs for Linux, Windows and macOS (they carry
+  their own Python). A pip-installable Python package is available too.
+
+## Quick start
+
+1. **Download** the build for your system from the [Releases](https://github.com/rotordeck/sticklink/releases) page, and unpack it.
+1b. **Prefer a window?** Start the program with no arguments (double-click it): pick your radio (or *Demo*), press **Start**, and use the buttons to open the pages. Same as `sticklink gui`.
+2. **Try it without a radio**:
+   ```bash
+   ./sticklink run --demo          # Windows: sticklink.exe run --demo
+   ```
+   Open <http://127.0.0.1:8765/fx>. You should see two gimbals moving by themselves.
+3. **Connect your radio**: install the script and set USB-VCP to LUA ([radio setup](https://github.com/rotordeck/sticklink/blob/main/docs/radio-setup.md)), then
+   ```bash
+   ./sticklink list-ports
+   ./sticklink run --port /dev/ttyACM0 --input-label sticks     # Windows: --port COM5
+   ```
+4. **Assign your sticks and switches** at <http://127.0.0.1:8765/setup> (press *Learn*, move the control).
+5. **Add it to OBS** as a Browser Source with the URL `http://127.0.0.1:8765/fx`, size 576x450, 60 fps
+   ([OBS setup](https://github.com/rotordeck/sticklink/blob/main/docs/obs-setup.md)). Double-click the page (in OBS: right-click, *Interact*) to change the look.
+
+Prefer Python? Once published on PyPI: `uvx sticklink run --demo` (no install, needs [uv](https://docs.astral.sh/uv/)) or
+`pip install sticklink`. Or `pip install sticklink-<version>-py3-none-any.whl` (from the release page), or from a checkout
+`pip install .`; then run `sticklink ...`.
+
+## Pages and commands
+
+| Address / command | What it does |
+|---|---|
+| `/fx` | Effects overlay for OBS (double-click for settings) |
+| `/hud`, `/hud/link`, `/hud/battery`, `/hud/gps` | Telemetry HUD (combined, or one block per page) |
+| `/setup` | Receiver screen: 3D quad, channel monitor, learn-by-moving assignment |
+| `/modes` | Pick which OBS scene a switch selects (ranges per scene, sorted by priority) |
+| `/overlay` | The plain panel with two sticks, ARM/flip lamps and telemetry |
+| `/docs` | Swagger UI for the REST API (spec at `/api/v1/openapi.json`) |
+| `sticklink run --port P \| --demo` | Serve the overlays from a radio or from synthetic data |
+| `sticklink replay FILE` | Serve a recorded session as if it were live |
+| `sticklink check-log FILE` | Quality report for a recording |
+| `sticklink radio-script [DIR]` | Copy the EdgeTX Lua script `DDSTK.lua` (e.g. onto the radio's SD card) |
+| `sticklink list-ports` | List serial ports |
+
+More in [docs/cli.md](https://github.com/rotordeck/sticklink/blob/main/docs/cli.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](https://github.com/rotordeck/sticklink/blob/main/docs/getting-started.md) | Install, run, first checks |
+| [Radio setup](https://github.com/rotordeck/sticklink/blob/main/docs/radio-setup.md) | EdgeTX script, USB-VCP, per-OS port names |
+| [OBS setup](https://github.com/rotordeck/sticklink/blob/main/docs/obs-setup.md) | Browser source, Linux/Wayland notes |
+| [Overlay guide](https://github.com/rotordeck/sticklink/blob/main/docs/overlay-guide.md) | `/fx`, `/setup`, the classic overlay, settings and URL options |
+| [Scene switching](https://github.com/rotordeck/sticklink/blob/main/docs/scenes.md) | `/modes`: switch OBS scenes from radio switches |
+| [CLI reference](https://github.com/rotordeck/sticklink/blob/main/docs/cli.md) | All commands and options |
+| [REST API](https://github.com/rotordeck/sticklink/blob/main/docs/api.md) | Endpoints, examples, security model |
+| [Protocol and log format](https://github.com/rotordeck/sticklink/blob/main/docs/protocol.md) | DDLOG v1, the JSONL recording format |
+| [Architecture](https://github.com/rotordeck/sticklink/blob/main/docs/architecture.md) | Modules and data flow |
+| [Troubleshooting](https://github.com/rotordeck/sticklink/blob/main/docs/troubleshooting.md) | Silent port, crashes, wrong sticks, OBS |
+| [Development](https://github.com/rotordeck/sticklink/blob/main/docs/development.md) | Tests, rebuilding the overlay, releases |
+| [Validation log](https://github.com/rotordeck/sticklink/blob/main/docs/validation.md) | What was tested on real hardware, and what was not |
+
+## Status and honest limits
+
+- Verified on real hardware: a **RadioMaster Pocket (EdgeTX 2.10)** with ExpressLRS, on **Linux**, with OBS 32. The radio
+  reports sticks at about **20 Hz** (EdgeTX runs function scripts every 50 ms); the overlay smooths between readings.
+- The Windows and macOS builds are produced and smoke-tested by CI (unit tests, integration tests and a run of the frozen
+  program), but they have **not been tried with a radio** on those systems yet.
+- The **HUD shows only telemetry your radio actually receives**. Betaflight does not send motor outputs, RPM, PID or gyro over
+  the radio link (those live in the blackbox on the quad), so there is no live motor screen. So far only **link quality (`RQly`) has been seen live on a real
+  radio**; the other link sensors, battery, GPS and attitude were tested with simulated data until the radio script is updated and the quad sends them.
+- The GPS map downloads tiles from the internet (OpenStreetMap by default); see [overlay guide](https://github.com/rotordeck/sticklink/blob/main/docs/overlay-guide.md#telemetry-hud).
+- The effects overlay shows what sticks and switches can drive: trails, sparks, snaps, punch-outs, full-throttle and hang-time
+  timers, arm/disarm. Flips, rolls and crash detection in stickcam need gyro and accelerometer data that the radio does not have.
+- Sticklink only **reads** from the radio. It never writes to it and never changes ExpressLRS or model settings.
+- Unsigned downloads: macOS Gatekeeper and Windows SmartScreen will warn once ([getting started](https://github.com/rotordeck/sticklink/blob/main/docs/getting-started.md)).
+
+## Licence
+
+No licence has been chosen yet, so all rights are reserved. Third-party components are listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/rotordeck/sticklink/blob/main/THIRD_PARTY_NOTICES.md).

sticklink-0.1.1/README.md

@@ -0,0 +1,114 @@
+# Sticklink
+
+**Live stick and telemetry overlays for OBS, straight from your radio.**
+Sticklink reads your sticks, switches and link telemetry from an EdgeTX radio (tested on a RadioMaster Pocket) over USB,
+serves them as an OBS Browser Source with the same look as [stickcam](https://github.com/rotordeck/stickcam)'s after-the-fact
+overlays, and records every session so you can check and reuse the data later.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/fx-neon.png" width="32%" alt="Neon style">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/fx-arcade.png" width="32%" alt="Arcade style">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/fx-hacker.png" width="32%" alt="Hacker style">
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/hud-corners-neon.png" width="49%" alt="Telemetry HUD, neon">
+  <img src="https://raw.githubusercontent.com/rotordeck/sticklink/main/docs/img/hud-corners-hacker.png" width="49%" alt="Telemetry HUD, hacker">
+</p>
+
+## What you get
+
+- **Effects overlay** (`/fx`): eight styles (Clean, Minimal, Neon, Arcade, Synthwave, Inferno, Unicorn, Hacker) with glowing
+  trails, sparks, shockwaves and live throttle timers. Trails are smooth curves with no added delay.
+- **Telemetry HUD** (`/hud`): **Link**, **Battery**, **GPS** and **Status** blocks as badges, in the same eight styles. GPS shows a live
+  map with your track, home marker and distance. Each block is also its own page (`/hud/link`, `/hud/battery`, `/hud/gps`), so you can
+  put them in OBS as separate sources. It shows what your radio really receives (see [limits](https://github.com/rotordeck/sticklink#status-and-honest-limits)).
+- **Receiver setup page** (`/setup`): a live 3D quad, stick bars and a 16-channel monitor, like Betaflight Configurator's
+  receiver tab. Press **Learn** and move a stick or switch to assign roll, pitch, yaw, throttle, ARM and Crash Flip, so a
+  swapped or reversed stick is a ten-second fix.
+- **Double-click to configure**: style, effect strength, size and video delay, saved on the
+  server so an OBS source updates by itself. The panel also shows a **permanent link** for the current look: use it as a source's URL to pin
+  that source to its own configuration.
+- **Scene switching** (`/modes`): a Betaflight-style Modes page for your **OBS scenes**: give each scene ranges on a switch channel, sort them so the
+  upper scene wins, and OBS follows your switches (via OBS's built-in WebSocket). Off until you turn it on, and it never acts on stale radio data.
+- **Recordings**: one JSONL file per session, a `check-log` quality report (rate, gaps, lost records, channel ranges) and
+  `replay` to play a session back through the overlay.
+- **REST API + Swagger UI** (`/docs`, works offline) and a WebSocket stream for your own tools.
+- **No dependencies to install**: downloads are single self-contained programs for Linux, Windows and macOS (they carry
+  their own Python). A pip-installable Python package is available too.
+
+## Quick start
+
+1. **Download** the build for your system from the [Releases](https://github.com/rotordeck/sticklink/releases) page, and unpack it.
+1b. **Prefer a window?** Start the program with no arguments (double-click it): pick your radio (or *Demo*), press **Start**, and use the buttons to open the pages. Same as `sticklink gui`.
+2. **Try it without a radio**:
+   ```bash
+   ./sticklink run --demo          # Windows: sticklink.exe run --demo
+   ```
+   Open <http://127.0.0.1:8765/fx>. You should see two gimbals moving by themselves.
+3. **Connect your radio**: install the script and set USB-VCP to LUA ([radio setup](https://github.com/rotordeck/sticklink/blob/main/docs/radio-setup.md)), then
+   ```bash
+   ./sticklink list-ports
+   ./sticklink run --port /dev/ttyACM0 --input-label sticks     # Windows: --port COM5
+   ```
+4. **Assign your sticks and switches** at <http://127.0.0.1:8765/setup> (press *Learn*, move the control).
+5. **Add it to OBS** as a Browser Source with the URL `http://127.0.0.1:8765/fx`, size 576x450, 60 fps
+   ([OBS setup](https://github.com/rotordeck/sticklink/blob/main/docs/obs-setup.md)). Double-click the page (in OBS: right-click, *Interact*) to change the look.
+
+Prefer Python? Once published on PyPI: `uvx sticklink run --demo` (no install, needs [uv](https://docs.astral.sh/uv/)) or
+`pip install sticklink`. Or `pip install sticklink-<version>-py3-none-any.whl` (from the release page), or from a checkout
+`pip install .`; then run `sticklink ...`.
+
+## Pages and commands
+
+| Address / command | What it does |
+|---|---|
+| `/fx` | Effects overlay for OBS (double-click for settings) |
+| `/hud`, `/hud/link`, `/hud/battery`, `/hud/gps` | Telemetry HUD (combined, or one block per page) |
+| `/setup` | Receiver screen: 3D quad, channel monitor, learn-by-moving assignment |
+| `/modes` | Pick which OBS scene a switch selects (ranges per scene, sorted by priority) |
+| `/overlay` | The plain panel with two sticks, ARM/flip lamps and telemetry |
+| `/docs` | Swagger UI for the REST API (spec at `/api/v1/openapi.json`) |
+| `sticklink run --port P \| --demo` | Serve the overlays from a radio or from synthetic data |
+| `sticklink replay FILE` | Serve a recorded session as if it were live |
+| `sticklink check-log FILE` | Quality report for a recording |
+| `sticklink radio-script [DIR]` | Copy the EdgeTX Lua script `DDSTK.lua` (e.g. onto the radio's SD card) |
+| `sticklink list-ports` | List serial ports |
+
+More in [docs/cli.md](https://github.com/rotordeck/sticklink/blob/main/docs/cli.md).
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](https://github.com/rotordeck/sticklink/blob/main/docs/getting-started.md) | Install, run, first checks |
+| [Radio setup](https://github.com/rotordeck/sticklink/blob/main/docs/radio-setup.md) | EdgeTX script, USB-VCP, per-OS port names |
+| [OBS setup](https://github.com/rotordeck/sticklink/blob/main/docs/obs-setup.md) | Browser source, Linux/Wayland notes |
+| [Overlay guide](https://github.com/rotordeck/sticklink/blob/main/docs/overlay-guide.md) | `/fx`, `/setup`, the classic overlay, settings and URL options |
+| [Scene switching](https://github.com/rotordeck/sticklink/blob/main/docs/scenes.md) | `/modes`: switch OBS scenes from radio switches |
+| [CLI reference](https://github.com/rotordeck/sticklink/blob/main/docs/cli.md) | All commands and options |
+| [REST API](https://github.com/rotordeck/sticklink/blob/main/docs/api.md) | Endpoints, examples, security model |
+| [Protocol and log format](https://github.com/rotordeck/sticklink/blob/main/docs/protocol.md) | DDLOG v1, the JSONL recording format |
+| [Architecture](https://github.com/rotordeck/sticklink/blob/main/docs/architecture.md) | Modules and data flow |
+| [Troubleshooting](https://github.com/rotordeck/sticklink/blob/main/docs/troubleshooting.md) | Silent port, crashes, wrong sticks, OBS |
+| [Development](https://github.com/rotordeck/sticklink/blob/main/docs/development.md) | Tests, rebuilding the overlay, releases |
+| [Validation log](https://github.com/rotordeck/sticklink/blob/main/docs/validation.md) | What was tested on real hardware, and what was not |
+
+## Status and honest limits
+
+- Verified on real hardware: a **RadioMaster Pocket (EdgeTX 2.10)** with ExpressLRS, on **Linux**, with OBS 32. The radio
+  reports sticks at about **20 Hz** (EdgeTX runs function scripts every 50 ms); the overlay smooths between readings.
+- The Windows and macOS builds are produced and smoke-tested by CI (unit tests, integration tests and a run of the frozen
+  program), but they have **not been tried with a radio** on those systems yet.
+- The **HUD shows only telemetry your radio actually receives**. Betaflight does not send motor outputs, RPM, PID or gyro over
+  the radio link (those live in the blackbox on the quad), so there is no live motor screen. So far only **link quality (`RQly`) has been seen live on a real
+  radio**; the other link sensors, battery, GPS and attitude were tested with simulated data until the radio script is updated and the quad sends them.
+- The GPS map downloads tiles from the internet (OpenStreetMap by default); see [overlay guide](https://github.com/rotordeck/sticklink/blob/main/docs/overlay-guide.md#telemetry-hud).
+- The effects overlay shows what sticks and switches can drive: trails, sparks, snaps, punch-outs, full-throttle and hang-time
+  timers, arm/disarm. Flips, rolls and crash detection in stickcam need gyro and accelerometer data that the radio does not have.
+- Sticklink only **reads** from the radio. It never writes to it and never changes ExpressLRS or model settings.
+- Unsigned downloads: macOS Gatekeeper and Windows SmartScreen will warn once ([getting started](https://github.com/rotordeck/sticklink/blob/main/docs/getting-started.md)).
+
+## Licence
+
+No licence has been chosen yet, so all rights are reserved. Third-party components are listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/rotordeck/sticklink/blob/main/THIRD_PARTY_NOTICES.md).

sticklink-0.1.1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Third-party notices
+
+Sticklink bundles or builds on the following. Licence texts are shipped next to the files they cover.
+
+## Bundled in the app
+
+| Component | Licence | Where |
+|---|---|---|
+| [Swagger UI](https://github.com/swagger-api/swagger-ui) 5.33.1 (`swagger-ui-dist`, unmodified) | Apache-2.0 | `src/sticklink/web/swagger/` (`LICENSE`, `NOTICE`) |
+| Fonts: Bungee, Orbitron (900), Fredoka (700), VT323, via [Fontsource](https://fontsource.org) | SIL Open Font License 1.1 | `src/sticklink/web/fonts/`, texts in `fonts/LICENSES/` |
+| Stick overlay renderer (`draw.ts`, `style.ts`, `layout.ts`) | Own code, copied unchanged from [rotordeck/stickcam](https://github.com/rotordeck/stickcam) @ `ca82bf34` | `fx/src/render/`, see `fx/VENDORED_FROM` |
+
+## Map tiles (loaded at runtime, not bundled)
+
+The GPS block can show map tiles. Map data is (c) OpenStreetMap contributors, available under the [Open Database Licence](https://www.openstreetmap.org/copyright).
+Tiles are requested from the provider the user selects: the OpenStreetMap standard tile servers (subject to the
+[OSMF Tile Usage Policy](https://operations.osmfoundation.org/policies/tiles/)), CARTO basemaps (free for non-commercial use only; see CARTO's terms), or a
+custom server. Each provider's credit is always drawn on the map.
+
+## Python dependencies (installed or frozen into the binaries)
+
+| Package | Licence |
+|---|---|
+| [aiohttp](https://github.com/aio-libs/aiohttp) and its dependencies | Apache-2.0 (and permissive licences of its dependencies) |
+| [pyserial](https://github.com/pyserial/pyserial) | BSD-3-Clause |
+| [PyInstaller](https://pyinstaller.org) (only used to build the binaries) | GPL-2.0 with a special exception that permits distributing the frozen programs it creates under any licence |
+| Python itself (embedded in the binaries) | PSF License |
+
+## Build-time only (not shipped)
+
+TypeScript, esbuild, Node.js test tooling, openapi-spec-validator, build.
+
+## This project
+
+No licence has been chosen yet; until one is added, all rights are reserved by the authors.

sticklink-0.1.1/docs/api.md

@@ -0,0 +1,77 @@
+# REST API
+
+Interactive documentation (Swagger UI, offline): <http://127.0.0.1:8765/docs>. The machine-readable OpenAPI 3.0 description
+is at `/api/v1/openapi.json`. A test checks that every route is in that description and that real responses match its schemas.
+
+![Swagger UI](img/swagger.png)
+
+## Endpoints
+
+| Area | Method and path | What it does |
+|---|---|---|
+| Live | `GET /api/v1/status` | Service version, uptime, radio status, diagnostics, WebSocket clients, recording |
+| | `GET /api/v1/state` | The full snapshot (also broadcast on the WebSocket) |
+| | `GET /api/v1/controls` | Sticks normalised to -1..1, raw inputs, switch states |
+| | `GET /api/v1/telemetry`, `/telemetry/{sensor}` | All sensors, or one by name (`RQly`, `RxBt`, ...) |
+| | `GET /api/v1/channels`, `/channels/{n}` | Mixer outputs CH1-CH16, or one (1-16) |
+| | `GET /api/v1/gps` | Position, home, distance and bearing from home, fix state |
+| | `GET`, `DELETE /api/v1/gps/track` | The flown track (thinned to one point per 2 m, at most 5000); forget track and home |
+| Settings | `GET /api/v1/styles` | The overlay styles |
+| | `GET`, `PUT`, `PATCH`, `DELETE /api/v1/settings` | Read; replace everything; change some; reset to defaults |
+| | `GET`, `PUT /api/v1/settings/mapping` | Which inputs drive roll, pitch, yaw, throttle, ARM, Crash Flip |
+| Recording | `GET`, `POST`, `DELETE /api/v1/recording` | Current recording; start (optional `label`); stop |
+| | `GET /api/v1/recordings` | Recordings in the folder, newest first |
+| | `GET`, `DELETE /api/v1/recordings/{name}` | Download the raw JSONL; delete |
+| | `GET /api/v1/recordings/{name}/report` | Quality report, like `check-log` |
+| OBS scenes | `GET /api/v1/obs`, `PATCH /api/v1/obs/connection`, `POST /api/v1/obs/scene` | Connection to OBS, its scenes; change the connection; switch a scene now |
+| | `GET`, `PUT /api/v1/scene-modes`, `GET /api/v1/scene-modes/state`, `POST /api/v1/scene-modes/apply` | The ranges per scene; live state; sync OBS to the switches now (see [scene switching](scenes.md)) |
+| Stream | WebSocket `/ws` | The state object as JSON text, about 30 times a second (receive-only) |
+
+`/api/state` and `/api/fx-config` from earlier versions still work and are marked deprecated.
+
+## Examples
+
+```bash
+curl localhost:8765/api/v1/controls
+curl localhost:8765/api/v1/channels/8
+curl localhost:8765/api/v1/gps
+curl -X PATCH localhost:8765/api/v1/settings -H 'content-type: application/json' -d '{"hud":{"layout":"row","cells":6,"map":{"provider":"none"}}}'
+curl -X PATCH localhost:8765/api/v1/settings -H 'content-type: application/json' -d '{"style":"hacker","mode":2}'
+curl -X POST   localhost:8765/api/v1/recording -H 'content-type: application/json' -d '{"label":"first-flight"}'
+curl -X DELETE localhost:8765/api/v1/recording
+curl localhost:8765/api/v1/recordings/20261006-143000-first-flight.jsonl/report
+```
+
+```python
+import json, websockets, asyncio          # pip install websockets
+async def main():
+    async with websockets.connect("ws://127.0.0.1:8765/ws") as ws:
+        async for message in ws:
+            state = json.loads(message)
+            print(state["status"], state["controls"])
+asyncio.run(main())
+```
+
+Settings include a `hud` object (style, layout, blocks, battery cells, units and the map provider); a partial `hud` or `mapping` in a PATCH only changes what it names.
+
+Values: `controls` are null unless the data is live (a reading within the last 500 ms); `channels` is null until the radio
+script reports them; `status` is `live`, `demo`, `paused` or `disconnected`.
+
+## Errors
+
+Always JSON: `{"error": {"code": "invalid_settings", "message": "..."}}`, with the usual statuses: 400 invalid input, 403 foreign
+Host header, 404 not found, 405 wrong method, 409 conflict (e.g. already recording), 413 body over 64 KB, 415 not JSON.
+
+## Security model
+
+There is no authentication, because the server only listens on `127.0.0.1`. Because a web page you visit could still
+try to reach a local server, it also:
+
+- rejects any request whose `Host` header is not `localhost`, `127.0.0.1` or `[::1]` (blocks DNS rebinding);
+- requires `Content-Type: application/json` for everything that changes something, **including POSTs with an empty body** (a cross-site form
+  cannot send that without a pre-flight request that the server does not answer, so a web page cannot start a recording or switch your OBS scene);
+- creates recordings only in its recordings folder, with names it generates (`YYYYMMDD-HHMMSS[-label].jsonl`); clients can
+  not choose paths, and file names in URLs are matched against a strict pattern;
+- limits request bodies to 64 KB.
+
+Do not expose the port to a network (for example by forwarding it) without putting authentication in front of it.

sticklink-0.1.1/docs/architecture.md

@@ -0,0 +1,54 @@
+# Architecture
+
+```text
+radio (DDSTK.lua) --USB serial--> Source --> Pipeline --> OverlayServer --WebSocket--> overlay pages (OBS)
+                                              |  RadioState              \--> REST API (/api/v1)
+                                              \--> JsonlLog (recording)
+```
+
+| Module (`src/sticklink/`) | Role |
+|---|---|
+| `protocol/ddlog.py` | Line framing and the parser for the DDLOG records |
+| `state.py` | `RadioState`: sessions, sequence gaps, aging, GPS fix / home / track, the snapshot sent to overlays |
+| `pipeline.py` | `Pipeline`: sources call `connection()` / `accept()`; state and recording hang off it |
+| `sources/` | `Source.run(pipeline)`: `serial_port.py` (reconnects), `demo.py`, `replay.py`. New inputs go here |
+| `sinks/jsonl_log.py`, `recorder.py` | The recording file format; start/stop and the recordings folder |
+| `server.py`, `api.py`, `openapi.py` | aiohttp app: pages, WebSocket, REST API, Host guard, the OpenAPI document |
+| `geo.py` | Distance and bearing for the GPS block |
+| `obs.py` | A small obs-websocket v5 client: scenes, current scene, switching; reconnects by itself |
+| `scenes.py` | The scene-mode store (private file, validation) and `SceneEngine`: channel ranges to scene switches, with debounce, priority and safety rules |
+| `fxconfig.py` | Validated, atomically written overlay settings and defaults (including the HUD and map settings) |
+| `analysis.py` | `check-log` / report |
+| `cli.py` | The command line |
+| `web/` | Pages and scripts served to the browser: `fx.html`, `setup.html`, `overlay.html`, `docs.html`, bundles, fonts, Swagger UI |
+| `radio/DDSTK.lua` | The EdgeTX script |
+
+## The overlay (TypeScript, `fx/`)
+
+| File | Role |
+|---|---|
+| `src/render/{draw,style,layout}.ts` | stickcam's canvas renderer, copied unchanged (`fx/VENDORED_FROM`) |
+| `src/live.ts` | `LiveFeed`: builds the frame history the renderer reads, one 60 fps frame at a time. Redraws earlier frames as smooth curves when a reading arrives; detects snaps, punch-outs, full-throttle and hang-time spans, arm/disarm |
+| `src/mapping.ts` | Which input drives which function, and the learn-by-moving detector |
+| `src/element.ts`, `src/index.ts` | The `<stick-fx>` page element (canvas, settings panel, config sync) |
+| `src/setup.ts`, `src/drone3d.ts` | The `/setup` page and its 3D quad |
+| `src/modes/` | The `/modes` page: microsecond scale and handle maths (`scale.ts`), the card list and edits (`model.ts`), the DOM page (`modes-page.ts`) |
+| `src/curve.ts` | Monotone cubic interpolation |
+| `src/hud/catalog.ts` | Sensor names to labelled badges, units, bars and warning levels; builds the Link, Battery and GPS models (pure) |
+| `src/hud/geo.ts`, `layout.ts`, `history.ts` | Map projection and tile maths, block placement for each layout, sparkline buffers (pure) |
+| `src/hud/look.ts` | Turns a stickcam `Style` into badge plates, dials, bars and text for the HUD |
+| `src/hud/blocks.ts`, `map.ts` | The four blocks, and the policy-conscious map tile loader |
+| `src/hud/hud-element.ts` | The `<stick-hud>` page element: data, settings panel, GPS track upkeep, render loop |
+
+`npm run build` (in `fx/`) bundles it with esbuild into `src/sticklink/web/stickfx.js` and `setup.js`. **The bundles are
+committed**, so installing or running Sticklink never needs Node.
+
+## Design decisions worth knowing
+
+- **Receive-only and local.** The bridge never writes to the radio and only listens on `127.0.0.1`.
+- **Snapshots, not events.** The server publishes the whole state about 30 times a second; pages do the rest. A page can
+  reconnect at any time and is correct after one message.
+- **One owner per serial port.** Two programs reading the same port split the data between them. Sticklink cannot detect this.
+- **History is data.** The renderer is a pure function of the frame history, so smoothing is done by rewriting history
+  (no lag) rather than by delaying the display.
+- **Settings live on the server**, not in the browser, so the OBS source and a normal browser tab show the same thing.

sticklink-0.1.1/docs/cli.md

@@ -0,0 +1,51 @@
+# Command-line reference
+
+`sticklink <command> [options]` (the downloaded binary, or `python -m sticklink`).
+
+## `sticklink gui` (or no command)
+
+A small window: radio picker (or Demo), **Start / Stop**, a status light (stopped, waiting for the radio, connected) and buttons that open the web pages. It serves on port 8765 and stops everything when closed. Needs tkinter (included in the downloads; on Linux with pip install `python3-tk`).
+
+## `run` - serve the overlays
+
+Exactly one of `--port` or `--demo`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--port NAME` | | Serial port of the radio (`COM5`, `/dev/ttyACM0`, `/dev/cu.usbmodem...`) |
+| `--demo` | | Synthetic sticks, switches and telemetry; no radio needed |
+| `--baud N` | 115200 | Serial baud rate (USB serial ignores it in practice) |
+| `--http-port N` | 8765 | Port of the web server (it always binds to 127.0.0.1) |
+| `--input-label sticks\|outputs\|unknown` | unknown | What the radio's control values represent; `sticks` for the bundled script |
+| `--stale-ms N` | 500 | No control sample for this long means "paused" |
+| `--scale N` | 1024 | Channel value that counts as full deflection |
+| `--arm-threshold N`, `--crash-threshold N` | 0 | Value above which the default channels 5 / 8 count as on |
+| `--log FILE` | | Start a recording to this file straight away (a path you choose) |
+| `--recordings-dir DIR` | `~/.local/share/sticklink/recordings` | Folder for recordings started through the API |
+| `--fx-config FILE` | `~/.config/sticklink/fx.json` | Overlay settings file |
+| `--scenes-config FILE` | `~/.config/sticklink/scenes.json` | OBS connection (including its password) and the scene modes; readable only by you |
+
+If the radio is unplugged, Sticklink keeps running and reconnects to the same port every two seconds.
+
+## `replay FILE`
+
+Plays a recording back through the overlays at its original speed. Takes the same options as `run` (except the source
+ones), plus `--speed N` (default 1) and `--loop`.
+
+## `check-log FILE`
+
+Prints a quality report for a recording: duration, control rate, gaps on the radio's clock and the computer's clock, lost
+records, resets, channel ranges, which output channels moved, telemetry rates, notes sent by the radio, and warnings
+(low rate, stalls, lost records, sticks that never moved, no telemetry).
+
+## `radio-script [DIR]`
+
+Copies the EdgeTX Lua script `DDSTK.lua` into `DIR` (default: the current folder). See [radio setup](radio-setup.md).
+
+## `list-ports`
+
+Prints the serial ports your system knows, with their descriptions.
+
+## Stopping
+
+Press Ctrl+C. An active recording is closed properly. Background launches from some shells ignore Ctrl+C; use `kill` (SIGTERM).

sticklink-0.1.1/docs/development.md

@@ -0,0 +1,74 @@
+# Development
+
+## Set up
+
+```bash
+git clone git@github.com:rotordeck/sticklink.git && cd sticklink
+python -m venv .venv && . .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+(cd fx && npm ci)                                    # only needed to change the overlay code
+```
+
+## Tests
+
+| What | Command |
+|---|---|
+| Python (protocol, state, log/replay, settings, REST API contract, security) | `python -m unittest discover -s tests` |
+| Overlay logic (live feed, mapping, learn detector, config) | `cd fx && npm test` |
+| Overlay type check | `cd fx && npm run typecheck` |
+| HUD in a real browser: every page, style and layout, the permanent links, and the map's tile requests (needs Chrome and Node 22+) | `STICKLINK_BROWSER_TESTS=1 python -m unittest tests.test_hud_browser` |
+| Radio script under a desktop Lua with a mocked EdgeTX (needs `lua`) | `python -m unittest tests.test_radio_script` |
+| DOM test of the classic overlay (optional, needs jsdom) | `JSDOM_PATH=/path/to/node_modules/jsdom node tests/test_components.cjs` |
+
+The API contract test needs the `dev` extra (`openapi-spec-validator`); it is skipped without it. It checks that the
+OpenAPI document is valid, that every route is documented (and vice versa), and that real responses match the documented schemas.
+
+Without a radio: `sticklink run --demo`, or `sticklink replay some-recording.jsonl --loop`.
+
+## Changing the overlay (`fx/`)
+
+Edit `fx/src`, then `cd fx && npm run build`. This writes `src/sticklink/web/stickfx.js` and `setup.js`; **commit them**
+(CI fails if the committed bundles differ from a fresh build). Rules to remember:
+
+- `fx/src/render/{draw,style,layout}.ts` are stickcam's, copied unchanged. Fix bugs upstream in `rotordeck/stickcam`, then re-copy and update `fx/VENDORED_FROM`.
+- Node runs the TypeScript tests with type stripping: no enums, no constructor parameter properties, `.ts` extensions in imports.
+
+## Changing the radio script
+
+`src/sticklink/radio/DDSTK.lua` runs on EdgeTX's Lua runtime, which is stricter and smaller than desktop Lua. Check the syntax
+with `luac -p`, and keep lines short (the longest line it sends is about 58 bytes). Anything optional is wrapped in `pcall`
+so it cannot stop the stick stream. Test on a radio: see [validation log](validation.md).
+
+## Building the binaries locally
+
+```bash
+pip install ".[binary]"          # non-editable install: the spec collects the package's data files from it
+cd packaging && pyinstaller --noconfirm --clean --distpath ../dist --workpath ../build sticklink.spec
+../dist/sticklink run --demo
+```
+
+The result is one self-contained program (Python included). PyInstaller builds for the system it runs on, so each
+platform is built on its own CI runner. After building, reinstall the editable copy: `pip install -e .`.
+
+## Continuous integration
+
+| Workflow | Runs on | Does |
+|---|---|---|
+| `.github/workflows/ci.yml` | every push and pull request | Python tests on Linux, Windows and macOS (Python 3.10 and 3.13); overlay tests, type check and a check that the committed bundles are up to date |
+| `.github/workflows/release.yml` | tags `v*`, or run by hand | builds the wheel and source package, and the PyInstaller binaries for Linux (x86-64), Windows (x86-64), macOS (Apple Silicon and Intel); smoke-tests each binary; on a tag, attaches everything with `SHA256SUMS.txt` to a GitHub Release, then uploads the wheel and source package to PyPI (so `uvx sticklink` works) |
+
+## Releasing
+
+1. Update `__version__` in `src/sticklink/__init__.py` and `CHANGELOG.md`; commit to `main`.
+2. `git tag v0.1.0 && git push origin v0.1.0` (the tag must equal `v` + `__version__`; the workflow checks it).
+3. The release workflow builds, tests the binaries and publishes the release. Tags with a `-` (`v0.2.0-rc1`) are marked pre-release.
+
+**One-time PyPI setup** (the first upload fails until this is done): on pypi.org, *Your projects, Publishing, Add a pending publisher*:
+project `sticklink`, owner `rotordeck`, repository `sticklink`, workflow `release.yml`, environment `pypi`. In GitHub, *Settings, Environments*,
+create `pypi` (optionally with required reviewers). No API token is stored anywhere. Pre-release tags are not uploaded.
+
+To try the pipeline without releasing: *Actions, Release, Run workflow*. Builds are attached to the run as artifacts.
+
+## Code map
+
+[Architecture](architecture.md), [protocol](protocol.md), [REST API](api.md).