Skip to content

Commit cd12aa7

Browse files
James Boultonclaude
andcommitted
Restructure the user docs in docs/, and add a how it works animation
- A short README, with a feature list, a quick start (ex03), how you develop with it, and a table of docs. - docs/: getting-started, layouts, controls, device, connections, storage and data-exporter, with tables of parameters and defaults. Documents/Documentation.md now points to them. - Checked against the code: TableRow, ZMQConnection, is_active, add_break(), toggle_btn() and the provisioning callbacks' messages are documented; wrong examples and defaults fixed; storage_enable() is needed for the server to keep uploaded history. - docs/animation: a Manim scene of a knob turned in the Dash app, through the library to your callback and back out, and a DashStore upload. It makes docs/images/how-it-works.gif, shown at the top of the README. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 9030158 commit cd12aa7

17 files changed

Lines changed: 1757 additions & 1238 deletions

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ venv/
111111
ENV/
112112
env.bak/
113113
venv.bak/
114-
114+
JMB_Test_Code/
115115
# Spyder project settings
116116
.spyderproject
117117
.spyproject

‎CLAUDE.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,11 @@ Notes for working on python-dashio, the Python library for the DashIO protocol a
1414
- `utilities/`: the `c64_encode`, `c64_decode` and `dashio_data_exporter` commands.
1515
- `tests/`: unittest/pytest tests.
1616
- `Examples/`:
17-
- `ex01`–`ex06`: shown in the README. Keep the README snippets identical to these files.
17+
- `ex01`–`ex06`: shown in `docs/getting-started.md` (and `ex03` in the README). Keep the snippets identical to these files.
1818
- `greenhouse/` and `server_monitor/`: full applications.
19-
- `Documents/Documentation.md`: the library reference. Keep it in step with the code.
19+
- `docs/`: the user documentation, in the style of zephyr-dashio's `docs/`: `getting-started.md`, `layouts.md`, `controls.md`, `device.md`, `connections.md`, `storage.md`, `data-exporter.md`. Keep it in step with the code. `docs/agents/` and `docs/adr/` are for working on the library.
20+
- `docs/animation/`: the Manim scene for the README's `docs/images/how-it-works.gif`, with its rendering steps. The names it shows must match the code.
21+
- `Documents/`: the control pictures the docs link to (by raw GitHub URL, so they show on PyPI), and `Documentation.md`, now a pointer to `docs/` for old links.
2022
- `skills/python-dashio/SKILL.md`: a Claude Code skill for library users, for Python devices and for making layouts for Arduino and zephyr-dashio firmware. Keep it in step with the code and the utilities.
2123
- `Documents/DashIO-Controls-V2.pdf` and `DashIO-Protocol-Definition-V5.pdf`: the authoritative protocol and controls references. They're git-ignored (`*.pdf`). Read them with `pypdf`; poppler isn't installed.
2224

@@ -78,7 +80,9 @@ Notes for working on python-dashio, the Python library for the DashIO protocol a
7880
- **The Dash server is the source of truth for history.** For a control with `storage_enable()` (`Device._server_stored`), history requests are only answered when they come from a Dash server connection (`msg_from` starting `DASH:`), never over TCP, BLE or other local connections. Otherwise an app connected locally takes the device's history as complete and doesn't fetch the older history from the server. Live updates still go to every connection.
7981
- **`DashStore` and history upload (SDU):** a port of the firmware's DashIO Storage Manager (`../zephyr-dashio-tally/port.md`, ESP-IDF port in `../dashesp/components/dashio_dsm`), using sqlite instead of a flash ring buffer.
8082
- `Device(..., store=DashStore(path))` gives every TimeGraph, EventLog and Map on the device the store (`control._store`). They record into it as well as their ring buffers, and answer the app's history requests from it.
81-
- The wire format must match the firmware byte for byte, as the Dash server is shared with it: the timestamp request, `controlInfo` order (lines, then tracks, then logs), `%.6f` floats, `T`/`F` booleans, unquoted LOG and MAP objects, and the FNV-1a hash (`%016x`) over the JSON. The golden vectors are in `tests/test_dash_store.py`.
83+
- The wire format follows `../dash_docs/DashIODataFormat/DashIO_Data_Updater.md` (the SDU section): the timestamp request (lines, then tracks, then logs), `%.6f` floats, `T`/`F` booleans, MAP values as strings without `time`, LOG `color` left out when empty, and the FNV-1a hash (`%016x`) over the JSON. The golden vectors are in `tests/test_dash_store.py`.
84+
- Each UPDATE's `controlInfo` lists only the lines, tracks and logs with data in it, or deleted by it, in order of first use. A line's or track's info goes in the first packet with its data after a `sendInfo`, and is sent again until a packet with it is ACKed. Logs answer `sendAll`.
85+
- `DashStore.delete()` (the controls' `delete_history()`) deletes locally and records a pending delete in the `pending_deletes` table. Pending deletes go first in the next session's first UPDATE as `"action": "delete"` entries with no data, and are removed when it's ACKed. `MapTrack(replace=True)` sends `"action": "replace"`.
8286
- The timestamp request goes to the announce topic when the device's control topic subscription succeeds (`send_store_request` command, after `send_announce`). The server's `DATA SDU REQUEST/ACK/NACK` arrive as normal device messages (`Device._data_rx`). All SDU messages from the device, the timestamp request and the UPDATE packets, go to the **announce** topic (the `ANNOUNCE` zmq topic, which only Dash server connections receive), because that's where the server handles `DATA` messages.
8387
- Unlike the firmware, a session sends from the server's timestamps for each line, track and log, not from the last ACK. Lines missing from the server's request aren't sent. TimeGraph breaks aren't stored.
8488
- The session runs on the device thread: the 10 second ACK timeout is checked by `SDUSession.poll()` in `Device.run()`, because zmq sockets aren't thread safe.

0 commit comments

Comments
 (0)