feat: add device firmware with USB API, StrixFPGA library and API check tools

README.md

@@ -3,48 +3,48 @@
 
 A portable wireless True Random Number Generator built on an Arduino MKR Vidor 4000.
 
-## Planned Design
+## Design
 
-Entropy comes from FPGA ring oscillators whose sampled timing jitter is XOR-combined into output bits, with no pseudo-random post-processing. A SAMD21 serves the results over WiFi and USB.
+Entropy comes from FPGA ring oscillators whose sampled timing jitter is XOR-combined into output bits, with no pseudo-random post-processing. A SAMD21 serves the results over USB (WiFi is planned).
 
-- Separate stream per entropy source
-- Raw and processed output modes, with a von Neumann extractor that can be toggled per output path
-- On-device health tests (NIST SP 800-90B repetition count and adaptive proportion)
-- Live statistics: bias, z-score, random walk and autocorrelation
-- Configurable random-walk / majority-vote bias amplifier
+- 4 independent generators × 90 ring oscillators. Each generator XORs its rings every 120 MHz clock (spatial) and then several consecutive bits (temporal, default 5): about 24 Mbps per generator.
+- Separate stream per generator, plus a combined stream of all healthy generators
+- On-device health tests per generator: NIST SP 800-90B repetition count and adaptive proportion, plus a dead-ring monitor
+- Live statistics per trial: bias, z-score, random walk and lag-1 autocorrelation, with rolling and cumulative windows
+- Configurable random-walk / majority-vote bias amplifier on a bias path and an autocorrelation path, with sub-trial voting
+- Von Neumann extractor that can be toggled on the stream, statistics and amplifier paths
+- Raw ring captures and frequency measurement for characterization
 
-## Set Up Dev Environment
+The USB protocol is documented in [arduino/strix/API.md](arduino/strix/API.md).
 
-Windows:
+## Layout
 
-1. Install Arduino IDE from here or via chocolatey: `choco install arduino`
-2. Install [Intel Quartus Lite](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). In the list of devices select `Cyclone 10 LP device support`
+- `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/libraries/`: `StrixFPGA` (FPGA boot, SPI access, embedded FPGA image) and `VidorBoot` (vendored subset of Arduino's VidorPeripherals)
+- `tools/`: FPGA image converter, jitter and statistics experiments, API check
 
-## FPGA Development
+## Development (Linux)
 
-- Intel Quartus
-    - Open Project > select `strix.qpf` from the `fpga/src` directory in this repo.
+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, Python and Rust.
 
-## MCU Development
-
-- Arduino IDE
-    - Boards Manager > Install 'Arduino SAMD Boards' (search for 'Vidor 4000')
-    - Library Manager > Install
-        - VidorPeripherals
-        - WiFiNINA (1.8.5, not higher)
-    - Open Project > `strix.ino` from the `arduino/strix` directory in this repo
+1. `devbox run setup`: install the Arduino SAMD core and 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. For characterization, flash the capture tool with `devbox run upload-capture` and use `devbox run jitter <freq|rings|sweep|output|health|stats|amp|pairs>`. `devbox run onod-build` builds the onod3000 test suite used by `jitter output` and `api-check`.
 
 ## TODO
 
-- Implement ring-oscillator entropy generators on the MKR Vidor 4000 FPGA
-- Fetch random numbers from the FPGA via SPI
-- Serve random numbers via USB
-- Make Vidor pairable via Bluetooth/Wifi
-- serve randomness wirelessly
-- battery pack
+- Serve randomness over WiFi (NINA pass-through in the FPGA is wired, firmware not yet)
+- Make Vidor pairable via Bluetooth
+- Battery pack
 - 3D case
 
 ---
 
-## [Development Notes](NOTES.md)
+## [Development Notes](NOTES.md)