115 lines
5.3 KiB
Markdown
115 lines
5.3 KiB
Markdown
|
# test_code — runnable prototype
|
||
|
|
|
||
|
|
These scripts validate the **CYW43439 emulator** (`src/cyw43_emulator.ts`)
|
||
|
|
against the public gSPI / SDPCM / IOCTL contracts the real
|
||
|
|
`cyw43-driver` exercises. They are **not** wired into Velxio's
|
||
|
|
frontend yet — the goal is to prove every layer works in isolation
|
||
|
|
before promoting the code into `frontend/src/simulation/cyw43/`.
|
||
|
|
|
||
|
|
The emulator implements the design from
|
||
|
|
`../autosearch/04_emulation_design.md`:
|
||
|
|
|
||
|
|
| Tier | What runs | Status |
|
||
|
|
|---|---|---|
|
||
|
|
| 0 | Bus handshake (`0xFEEDBEAD`), F0/F1 register state, on-board LED IOCTL | ✅ |
|
||
|
|
| 1 | Full IOCTL surface (UP/DOWN/SET_INFRA/SET_AUTH/GET_VAR/SET_VAR/SCAN/SET_SSID/DISASSOC), SDPCM event injection, `Velxio-GUEST` AP, `cur_etheraddr` MAC reply | ✅ |
|
||
|
|
| 2 | Outbound Ethernet frames on F2 fire `onPacketOut`; inbound frames accepted via `injectPacket()`. Ready to be wired to a backend WS bridge. | ✅ chip side; net bridge is the production seam |
|
||
|
|
| 3 | Bluetooth, monitor mode, WPA3-SAE | ⏭ out of scope |
|
||
|
|
|
||
|
|
## Layout
|
||
|
|
|
||
|
|
```
|
||
|
|
test_code/
|
||
|
|
├── README.md ← this file
|
||
|
|
├── package.json ← local Node deps + npm scripts
|
||
|
|
├── tsconfig.json ← strict TS, ESM
|
||
|
|
├── src/
|
||
|
|
│ ├── pio_bus_sniffer.ts ← decodes 32-bit gSPI command words
|
||
|
|
│ ├── cyw43_constants.ts ← F0/F1/WLC/WLC_E definitions
|
||
|
|
│ ├── sdpcm.ts ← SDPCM + CDC + event-frame codec
|
||
|
|
│ ├── virtual_ap.ts ← Velxio-GUEST AP (single source of truth)
|
||
|
|
│ ├── cyw43_emulator.ts ← FULL emulator (Tier 0/1/2)
|
||
|
|
│ ├── cyw43_emulator_tier0.ts ← legacy Tier-0 stub kept for tests/02
|
||
|
|
│ └── harness.ts ← glue with rp2040js
|
||
|
|
└── tests/
|
||
|
|
├── 01_pio_decoder.test.ts ← bit-layout unit tests
|
||
|
|
├── 02_handshake.test.ts ← Tier-0 handshake (legacy stub)
|
||
|
|
├── 03_pico_w_blink.test.ts ← end-to-end (skipped without UF2)
|
||
|
|
├── 04_sdpcm.test.ts ← SDPCM/CDC/event-frame codec
|
||
|
|
├── 05_ioctl.test.ts ← per-IOCTL response validation
|
||
|
|
└── 06_full_lifecycle.test.ts ← bus init → scan → connect → packet → disconnect
|
||
|
|
```
|
||
|
|
|
||
|
|
## Running
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd test/test_Raspberry_Pi_Pico_W/test_code
|
||
|
|
npm install
|
||
|
|
npm test # 30 unit + integration tests, no firmware needed
|
||
|
|
npm run e2e # 1 end-to-end test, needs Pico W MicroPython UF2
|
||
|
|
npm run all # everything
|
||
|
|
```
|
||
|
|
|
||
|
|
## Latest results (2026-04-29)
|
||
|
|
|
||
|
|
```
|
||
|
|
✓ tests/01_pio_decoder.test.ts (9 tests) ← bit decoder
|
||
|
|
✓ tests/02_handshake.test.ts (6 tests) ← Tier-0 handshake
|
||
|
|
✓ tests/04_sdpcm.test.ts (7 tests) ← SDPCM codec
|
||
|
|
✓ tests/05_ioctl.test.ts (5 tests) ← IOCTL surface
|
||
|
|
✓ tests/06_full_lifecycle.test.ts (3 tests) ← FULL WiFi lifecycle
|
||
|
|
↓ tests/03_pico_w_blink.test.ts (1 test | 1 skipped — needs UF2)
|
||
|
|
|
||
|
|
Test Files 5 passed | 1 skipped (6)
|
||
|
|
Tests 30 passed | 1 skipped (31)
|
||
|
|
```
|
||
|
|
|
||
|
|
## What `06_full_lifecycle.test.ts` actually proves
|
||
|
|
|
||
|
|
A single test exercises the entire emulator surface in the order a real
|
||
|
|
driver hits it on `network.WLAN(network.STA_IF).connect("Velxio-GUEST")`:
|
||
|
|
|
||
|
|
1. **Bus handshake** — first F0:0x14 read returns 0, second returns
|
||
|
|
`0xFEEDBEAD`.
|
||
|
|
2. **Clock CSR** — driver requests `HT_AVAIL_REQ`, chip flips
|
||
|
|
`HT_AVAIL` on the next read.
|
||
|
|
3. **WLC_UP** — chip transitions to "up", `isUp()` returns true.
|
||
|
|
4. **WLC_SCAN** — chip emits a `WLC_E_ESCAN_RESULT` event whose
|
||
|
|
embedded BSS info advertises SSID `Velxio-GUEST` with the
|
||
|
|
locally-administered BSSID `02:42:DA:42:00:01`, then
|
||
|
|
`WLC_E_SCAN_COMPLETE`.
|
||
|
|
5. **WLC_SET_SSID Velxio-GUEST** — chip emits the documented event
|
||
|
|
sequence (`JOIN_START` → `AUTH` → `ASSOC_START` → `ASSOC` →
|
||
|
|
`SET_SSID(SUCCESS)` → `LINK(reason=1)`), `getLinkState()` becomes
|
||
|
|
`'up'`, `onConnect` listener fires.
|
||
|
|
6. **WLC_GET_BSSID** — IOCTL reply contains the AP's BSSID.
|
||
|
|
7. **Outbound data path** — host pushes an Ethernet frame on SDPCM
|
||
|
|
channel 2 with a BDC header; the emulator strips the BDC and fires
|
||
|
|
`onPacketOut` with the raw Ethernet payload (this is the seam where
|
||
|
|
a backend WS bridge would tunnel out to the host network).
|
||
|
|
8. **Inbound data path** — `injectPacket()` queues a frame; the next
|
||
|
|
F2 read returns it wrapped in SDPCM with channel = 2.
|
||
|
|
9. **WLC_DOWN** — chip transitions to "down", emits `LINK(reason=0)`,
|
||
|
|
`onDisconnect` fires.
|
||
|
|
|
||
|
|
Plus negative tests:
|
||
|
|
|
||
|
|
- Joining a non-existent SSID → `SET_SSID(FAIL)` event, link stays down.
|
||
|
|
- Streaming 224 KB of "firmware" through F1 doesn't break the chip.
|
||
|
|
|
||
|
|
## Where the constants come from
|
||
|
|
|
||
|
|
Every numeric constant in `src/cyw43_constants.ts` is sourced from
|
||
|
|
**public** documentation:
|
||
|
|
|
||
|
|
- **gSPI register addresses** — Infineon CYW43439 datasheet §3.5.
|
||
|
|
- **WLC IOCTL command numbers** — pico-sdk's `pico_cyw43_driver`
|
||
|
|
(BSD-3) and `jbentham/picowi` (MIT). The MIT-licensed picowi tree is
|
||
|
|
cloned into `wokwi-libs/picowi/` for cross-reference.
|
||
|
|
- **WLC_E event numbers** — same two sources.
|
||
|
|
- **SDPCM/CDC layout** — Broadcom-published in the AirForce SDK and
|
||
|
|
re-implemented identically in every open driver.
|
||
|
|
|
||
|
|
No code from the closed `georgerobotics/cyw43-driver` is copied; we
|
||
|
|
read it for sanity-checking but derive only from BSD/MIT sources.
|