feat(hardware): add MediaTek Filogic CSI simulator (#1358)

2026-07-27 18:11:43 +00:00 · 2026-07-18 22:00:09 -04:00
parent 8a5af5dad4
commit 232b1c79f6
11 changed files with 1180 additions and 5 deletions
@@ -83,7 +83,7 @@ This ADR covers Phase 1 (TV box as aggregator) and Phase 2 (custom WiFi firmware
   |---------|--------|-------------|--------------|--------|
   | Broadcom BCM43455 | brcmfmac | **Proven** (Nexmon CSI) | Yes | Low — patches exist |
   | Realtek RTL8822CS | rtw88 | **Moderate** — driver is open-source, CSI hooks need adding | Yes (patched) | Medium |
-   | MediaTek MT7661 | mt76 | **Unknown** — MediaTek has released CSI tools for some chips | Yes | Medium-High |
+   | MediaTek MT7661 | mt76 | **Unverified** — no supported public CSI capture API was found in upstream `mt76` or public MediaTek SDK material | Yes | Research only |

 2. **CSI extraction architecture** (Linux kernel driver modification):

@@ -0,0 +1,75 @@
+# ADR-266: MediaTek Filogic CSI Platform
+
+- **Status**: accepted
+- **Date**: 2026-07-18
+- **Deciders**: RuView maintainers
+- **Tags**: mediatek, filogic, mt76, csi, openwrt, rust
+
+## Context
+
+RuView needs a high-antenna-count, router-class Wi-Fi sensing path beyond ESP32.
+MediaTek Filogic platforms are attractive because the upstream BSD-3-Clause
+`mt76` driver supports MT7915/MT792x/MT7996 families and OpenWrt supports
+MT7981/MT7986/MT7988 systems. The OpenWrt One (MT7981B + MT7976C) additionally
+publishes schematics, platform datasheets, register documentation, serial, and
+JTAG access. The BPI-R3 (MT7986 + MT7975N/P) offers dual-band 4x4 radios.
+
+The current upstream `mt76` tree has testmode, debugfs, RX descriptors, and MCU
+event plumbing, but no supported public interface for exporting per-packet
+complex channel estimates. Public MediaTek SDK material likewise does not expose
+an equivalent to Espressif's CSI callback. PHY computation of channel estimates
+does not imply that firmware transfers those estimates to host memory.
+
+Existing RuView documents that describe MT7661 CSI-over-UDP or released
+MediaTek CSI tools are unverified architectural hypotheses, not supported
+hardware claims.
+
+## Decision
+
+1. Use the OpenWrt One as the primary future hardware/upstreaming target and the
+   BPI-R3 as the secondary 4x4 validation target.
+2. Build a Rust-first simulator and host transport before hardware arrives.
+3. Keep the transport independent of private firmware structures. A future
+   `mt76` adapter must translate a documented kernel/firmware report into it.
+4. Prefer Generic Netlink for capability/control messages and relayfs or a
+   bounded character-device stream if sustained CSI volume exceeds Netlink's
+   practical throughput.
+5. Do not redistribute vendor firmware, private headers, or SDK components.
+6. Label simulator frames end-to-end and never present them as physical capture.
+7. Do not claim MediaTek hardware CSI support until complex CSI from a physical
+   device passes calibration, sequence, timestamp, and repeatability tests.
+
+## Consequences
+
+### Positive
+
+- Development and integration testing can start without fabricating a vendor ABI.
+- OpenWrt One provides a repairable, upstream-friendly hardware target.
+- The same RuView ingestion path can accept simulator, replay, and future driver data.
+- Rust bounds checking isolates untrusted kernel/network input from inference code.
+
+### Negative
+
+- The simulator cannot prove firmware export availability or sensing accuracy.
+- A firmware change or MediaTek cooperation may be required before physical CSI exists.
+- Router-class builds and driver iteration are slower than MCU firmware development.
+
+### Neutral
+
+- NeuroPilot may later accelerate inference but is unrelated to CSI capture.
+- Wi-Fi 7/MLO support remains a later phase after a single-link contract is stable.
+
+## Hardware gates
+
+- Identify a firmware/host report containing complex channel estimates.
+- Document dimensions, quantization, chain ordering, subcarrier indexing, lifetime,
+  timestamps, sequence behavior, calibration, maximum size, and report rate.
+- Validate OpenWrt One first, then BPI-R3 4x4, before considering MT7996/MLO.
+
+## Links
+
+- [ADR-123: BFLD capture path](ADR-123-bfld-capture-path-nexmon-and-esp32.md)
+- [ADR-264: RTL8720F radar wire protocol](ADR-264-rtl8720f-radar-wire-protocol.md)
+- [upstream mt76](https://github.com/openwrt/mt76)
+- [OpenWrt One](https://openwrt.org/toh/openwrt/one)
+- [MediaTek OpenWrt feed](https://git01.mediatek.com/openwrt/feeds/mtk-openwrt-feeds/)
@@ -0,0 +1,61 @@
+# ADR-267: MediaTek MIMO CSI Wire Protocol
+
+- **Status**: accepted
+- **Date**: 2026-07-18
+- **Deciders**: RuView maintainers
+- **Tags**: mediatek, csi, protocol, rust, udp, replay
+
+## Context
+
+The MediaTek simulator, captured regression fixtures, and a future `mt76` agent
+need one safe host-side representation. Copying an undocumented firmware layout
+would couple RuView to a private ABI and make malformed kernel/network data risky.
+MIMO CSI also requires explicit Tx/Rx/subcarrier dimensions and per-Rx-chain RSSI.
+
+## Decision
+
+Define `MTC1` version 1 as a little-endian, self-delimiting envelope:
+
+- 72-byte fixed header with magic, version, report kind, total length, sequence,
+  monotonic timestamp, device ID, chipset profile, frequency, bandwidth, flags,
+  Tx/Rx dimensions, numeric format, PPDU type, subcarrier count, noise floor,
+  scale, subcarrier spacing, calibration ID, and payload length.
+- CSI payload begins with one signed RSSI byte per Rx chain, followed by
+  `tx_count * rx_count * subcarrier_count` complex values in Tx-major,
+  Rx-major, subcarrier-major order.
+- Supported numeric formats are complex signed i16 and complex finite f32.
+- Capability reports use bounded opaque TLVs until a public driver contract exists.
+- CRC-32/IEEE covers header and payload; the final four bytes carry the checksum.
+- One envelope maps to one UDP datagram, capped at the IPv4 UDP payload maximum
+  of 65,507 bytes. Replay files prefix each envelope with a little-endian `u32`.
+- Parsers reject unknown versions/types/formats, invalid dimensions/bandwidth,
+  multiplication overflow, inconsistent payload lengths, non-finite floats,
+  bad CRC, trailing datagram bytes, and frames above the cap.
+- Flags distinguish calibrated, saturated, time-synchronized, dropped-predecessor,
+  and synthetic frames. Synthetic provenance cannot be cleared by downstream code.
+
+## Consequences
+
+### Positive
+
+- Deterministic simulator and future hardware use identical parsing and APIs.
+- Explicit dimensions prevent ambiguous antenna or subcarrier interpretation.
+- CRC, finite-value checks, and hard caps make network/replay ingestion robust.
+- The format supports MT7981, MT7986, and MT7996 profiles without claiming their
+  undocumented firmware layouts.
+
+### Negative
+
+- A translation/copy step is required from a future kernel report.
+- Maximum-size Wi-Fi 7 matrices may need segmentation in a later protocol version.
+
+### Neutral
+
+- Version 1 models one link per report; MLO correlation is a future extension.
+- Capability TLVs are intentionally conservative until hardware metadata is known.
+
+## Links
+
+- [ADR-266: MediaTek Filogic CSI platform](ADR-266-mediatek-filogic-csi-platform.md)
+- [ADR-018: ESP32 binary CSI framing](ADR-018-esp32-csi-frame-protocol.md)
+- [ADR-264: RTL8720F radar wire protocol](ADR-264-rtl8720f-radar-wire-protocol.md)