From 13704a809e9d06d9ff4251904126cee328217238 Mon Sep 17 00:00:00 2001 From: randogoth Date: Sun, 25 Oct 2026 19:19:29 +0200 Subject: [PATCH] docs: move development notes to NOTES.md and describe the CLI in the README --- NOTES.md | 40 +++++++++++++++++++++++++++------------- README.md | 40 ++++++++++++---------------------------- arduino/strix/API.md | 2 +- 3 files changed, 40 insertions(+), 42 deletions(-) diff --git a/NOTES.md b/NOTES.md index f2b581e..70931c8 100644 --- a/NOTES.md +++ b/NOTES.md @@ -1,18 +1,32 @@ -# IDE Setup (Windows) +## Layout -- Installed Intel Quartus Lite from https://www.intel.com/content/www/us/en/software-kit/825278/intel-quartus-prime-lite-edition-design-software-version-23-1-1-for-windows.html -- Installed Arduino IDE 2 `choco install arduino` +- `fpga/rtl/`: Verilog sources; `fpga/sim/`: testbenches; `fpga/src/`: Quartus project +- `arduino/strix/`: device firmware +- `arduino/strix_capture/`: characterization tool firmware, used by `tools/jitter.py` +- `arduino/strix_nina_passthrough/`: connects USB to the WiFi module's UART for flashing its firmware +- `arduino/libraries/`: `StrixFPGA` (FPGA boot, SPI access, embedded FPGA image), `VidorBoot` (vendored subset of Arduino's VidorPeripherals), and Arduino's `WiFiNINA`, `Arduino_SpiNINA` and `ArduinoBLE`, patched to drive the WiFi module through the FPGA's pin pass-through (see `arduino/libraries/STRIX-NINA-LIBRARIES.md`) +- `tools/`: `strix.py` command-line client, FPGA image converter, jitter and statistics experiments, API check -# Project Setup +## Development (Linux) -based on https://docs.arduino.cc/tutorials/mkr-vidor-4000/vidor-quartus-vhdl/ +The toolchain is managed by [devbox](https://www.jetify.com/devbox): `arduino-cli`, Intel Quartus Prime Lite (Cyclone 10 LP only, through a Nix flake in `nix/`), Icarus Verilog, Rust, and [uv](https://docs.astral.sh/uv/) for the Python tools (`pyproject.toml`, `uv.lock`). -- New Project Wizard - - 'strix' for name and top level design entity - - Skip next screen - - Family, Device, Board Settings > Name filter: `10CL016YU256C8G` - - Finish +1. `devbox run setup`: install the Arduino SAMD core (libraries are vendored in `arduino/libraries/`) +2. `devbox run sim`: run the FPGA testbenches +3. `devbox run fpga`: build the FPGA bitstream (about 10 minutes) +4. `devbox run image`: embed the bitstream in the `StrixFPGA` library +5. `devbox run build`, then `devbox run upload`: build and flash the firmware (`PORT` defaults to `/dev/ttyACM0`) +6. `devbox run api-check`: end-to-end check of the USB API +7. `devbox run strix `: command-line client over USB (see the README) -- Import Pin Settings: - - Menu > Assignments > Import Assignments > vidor_s_pins.qsf - - from https://github.com/vidor-libraries/VidorFPGA/blob/master/constraints/MKRVIDOR4000/vidor_s_pins.qsf \ No newline at end of file +Serial access requires membership in the `dialout` group. If a firmware leaves the board unable to stay on USB, enter the bootloader: hold reset while plugging in, release, then tap reset once quickly. For characterization, flash the capture tool with `devbox run upload-capture` and use `devbox run jitter `. `devbox run onod-build` builds the onod3000 test suite used by `jitter output` and `api-check`. + +### WiFi module firmware + +BLE needs NINA firmware 3.0.0 or newer (the board shipped with 1.0.0). To flash Arduino's [nina-fw](https://github.com/arduino/nina-fw/releases) `NINA.bin`: + +1. Flash the passthrough: `devbox run -- arduino-cli compile -u -p /dev/ttyACM0 --fqbn arduino:samd:mkrvidor4000 --libraries arduino/libraries arduino/strix_nina_passthrough` +2. `devbox run -- uv run esptool --chip esp32 --port /dev/ttyACM0 --baud 115200 write-flash 0 NINA.bin` +3. Flash the STRIX firmware again (`devbox run upload`); `wifi probe` reports the module firmware version. + +The passthrough forwards reliably at 115200 baud, not at 460800. \ No newline at end of file diff --git a/README.md b/README.md index 36a3cfa..f4eb3c6 100644 --- a/README.md +++ b/README.md @@ -18,37 +18,21 @@ Entropy comes from FPGA ring oscillators whose sampled timing jitter is XOR-comb The USB, HTTP and BLE API is documented in [arduino/strix/API.md](arduino/strix/API.md). -## Layout +## Command-line client -- `fpga/rtl/`: Verilog sources; `fpga/sim/`: testbenches; `fpga/src/`: Quartus project -- `arduino/strix/`: device firmware -- `arduino/strix_capture/`: characterization tool firmware, used by `tools/jitter.py` -- `arduino/strix_nina_passthrough/`: connects USB to the WiFi module's UART for flashing its firmware -- `arduino/libraries/`: `StrixFPGA` (FPGA boot, SPI access, embedded FPGA image), `VidorBoot` (vendored subset of Arduino's VidorPeripherals), and Arduino's `WiFiNINA`, `Arduino_SpiNINA` and `ArduinoBLE`, patched to drive the WiFi module through the FPGA's pin pass-through (see `arduino/libraries/STRIX-NINA-LIBRARIES.md`) -- `tools/`: FPGA image converter, jitter and statistics experiments, API check +`tools/strix.py` talks to the device over USB; run it with `devbox run strix ` or `uv run tools/strix.py `. It finds the board by its USB ID (override with `--port` or `STRIX_PORT`). -## Development (Linux) +| Command | Does | +|---|---| +| `id`, `health`, `amp`, `get` | Prints the device's reply | +| `stats [--reset]` | Prints the statistics, or restarts them | +| `set KEY VALUE` | Changes a setting (keys in the API documentation) | +| `entropy N [--out FILE]` | N entropy bytes as hex, or binary into a file | +| `watch stats\|amp` | Prints every new trial until Ctrl-C | +| `gcp [--log FILE] [--full] [--seconds N]` | Follows the per-second GCP-format trials | +| `send LINE` | Sends any command line and prints the reply | -The toolchain is managed by [devbox](https://www.jetify.com/devbox): `arduino-cli`, Intel Quartus Prime Lite (Cyclone 10 LP only, through a Nix flake in `nix/`), Icarus Verilog, Rust, and [uv](https://docs.astral.sh/uv/) for the Python tools (`pyproject.toml`, `uv.lock`). - -1. `devbox run setup`: install the Arduino SAMD core (libraries are vendored in `arduino/libraries/`) -2. `devbox run sim`: run the FPGA testbenches -3. `devbox run fpga`: build the FPGA bitstream (about 10 minutes) -4. `devbox run image`: embed the bitstream in the `StrixFPGA` library -5. `devbox run build`, then `devbox run upload`: build and flash the firmware (`PORT` defaults to `/dev/ttyACM0`) -6. `devbox run api-check`: end-to-end check of the USB API - -Serial access requires membership in the `dialout` group. If a firmware leaves the board unable to stay on USB, enter the bootloader: hold reset while plugging in, release, then tap reset once quickly. For characterization, flash the capture tool with `devbox run upload-capture` and use `devbox run jitter `. `devbox run onod-build` builds the onod3000 test suite used by `jitter output` and `api-check`. - -### WiFi module firmware - -BLE needs NINA firmware 3.0.0 or newer (the board shipped with 1.0.0). To flash Arduino's [nina-fw](https://github.com/arduino/nina-fw/releases) `NINA.bin`: - -1. Flash the passthrough: `devbox run -- arduino-cli compile -u -p /dev/ttyACM0 --fqbn arduino:samd:mkrvidor4000 --libraries arduino/libraries arduino/strix_nina_passthrough` -2. `devbox run -- uv run esptool --chip esp32 --port /dev/ttyACM0 --baud 115200 write-flash 0 NINA.bin` -3. Flash the STRIX firmware again (`devbox run upload`); `wifi probe` reports the module firmware version. - -The passthrough forwards reliably at 115200 baud, not at 460800. +`gcp` prints one line per second: UTC time, second number, the four 200-bit sums, Stouffer Z, Z², and the cumulative Z² − 1 with its p = 0.05 envelope (`*` when outside). `--full` tracks the full-rate trials instead. It reconnects after USB dropouts and fills missed seconds from the device's 60-second history. `--log` appends GCP-style CSV rows, `13,,,,,,` (empty for unhealthy generators), after a `12,gmtime,Date/Time,g0,g1,g2,g3` header. ## TODO diff --git a/arduino/strix/API.md b/arduino/strix/API.md index 022052d..eccb81f 100644 --- a/arduino/strix/API.md +++ b/arduino/strix/API.md @@ -6,7 +6,7 @@ The firmware serves the same commands over USB serial and over HTTP on its own W The firmware speaks a line protocol over the board's USB serial port (115200 baud setting, ignored by native USB). Send one command per line. Every reply is a single JSON line, except `entropy`. Errors look like `{"error":"..."}`, and settings changes confirm with `{"ok":true}`. -`tools/strix.py` (`devbox run strix `) wraps the USB protocol. `strix gcp [--log file.csv] [--full]` follows the per-second trials with a live cumulative Z² − 1 and its p = 0.05 envelope, reconnects after USB dropouts and fills gaps from the device's history. The log has GCP-style rows: `13,,,,,,` (200-bit sums, empty for unhealthy generators), after a `12,gmtime,Date/Time,g0,g1,g2,g3` header. +`tools/strix.py` wraps this protocol (see the README). ## Commands