strix/arduino/strix/API.md

STRIX API

The firmware serves the same commands over USB serial and over HTTP on its own WiFi access point.

USB

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

Commands

Command	Reply
id	Device, firmware and FPGA version, generator and ring counts, and the reset cause of the last boot (reset_cause: SAMD21 PM->RCAUSE; 1 power-on, 4 brown-out, 16 reset pin, 64 software)
wifi	WiFi status: module probed, access point running, module firmware, SSID, IP
wifi probe	Releases the WiFi module from reset and queries it, without starting the radio
wifi start	Starts the access point and the HTTP server
entropy <n> [hex|bin]	n (1–65536) entropy bytes from the stream source. hex (default): one line of hex. bin: a line BIN <n>, then n raw bytes. Refused if the stream source is not healthy. If the source stops delivering for 2 s, hex ends with an error line and binary ends early.
health	Per generator: healthy, active, swept, test failures and event counts, dead rings. Stream FIFO level and dropped bytes.
health clear	Clears latched test failures and event counters
stats	Latest statistics trial: per channel (g0–g3, combined) bits, ones, bias z and lag-1 autocorrelation z for the trial, the rolling window and the cumulative total (with random walk position). Also trials counted and trials missed.
stats reset	Restarts trials and clears the rolling and cumulative windows
amp	Latest bias amplifier trial: per path (bias, autocorr) amplified bits, ones, z, sub-trial votes (1, 0, . for no vote) and the trial result (null on a tie)
get	All settings
set <key> <value>	Changes a setting (see below)
watch stats / watch amp / watch off	Pushes the stats or amp reply after every new trial

Settings

Key	Values	Effect
temporal	1–8	Consecutive bits XORed per generator output bit (default 5: about 24 Mbps per generator). The amplifier needs at least 4.
generators	0–15	Bit mask of running generators
trial_ms	1–65535	Statistics trial length; restarts the statistics
stats_vn	0/1	Von Neumann extractor on the statistics path; restarts the statistics
rolling	1–50	Trials in the rolling window
stream_source	0–4	Entropy stream source: generator 0–3, or 4 for the XOR of all healthy generators (default). Flushes the stream.
stream_vn	0/1	Von Neumann extractor on the entropy stream; flushes the stream
amp_sources	0–15	Generators feeding the amplifier (healthy ones only)
amp_method	walk/vote	Bounded random walk or majority vote in all three stages
amp_stages	a,b,c	Bound or window of the three stages, each 1–65535 (1 = passthrough). The total amplification is a × b × c.
amp_sub_ms	1–255	Sub-trial length
amp_subtrials	1–15	Sub-trials per amplifier trial
amp_vn	0/1	Von Neumann extractor on the amplifier path

Changing an amp_* setting restarts the amplifier.

WiFi

Without a USB host (wall charger or battery), the device starts WiFi by itself: an access point named Strix (WPA2, password owl12345678) at 192.168.4.1, with an HTTP server on port 80. With a computer attached, WiFi stays off until wifi start. On weak USB power the radio's current bursts plus the ring oscillators can reset the board.

Until WiFi is started, the FPGA holds the WiFi module in reset.

URL	USB equivalent
/entropy?bytes=<n>[&format=hex|bin]	entropy <n> [hex|bin]. bin is sent as application/octet-stream, without the BIN line.
/?length=<n>	entropy <n> hex (compatible with the earlier STRIX sketch)
/id, /health, /stats, /amp, /wifi	same command
/config	get
/set?key=<key>&value=<value>	set <key> <value>

Replies have status 200 (errors are JSON {"error":...}), or 404 for unknown paths, and allow cross-origin requests. watch is USB-only.

Example

> id
{"device":"STRIX","firmware":"0.2.0","fpga_ready":true,"fpga_version":8,"generators":4,"rings_per_generator":90,"reset_cause":1}
> entropy 8
3F09A2C47E11D05B
> set amp_stages 8,8,4
{"ok":true}

The device also runs without a USB host (on battery). The LED is on while every enabled generator is healthy.