feat: add MediaTek Filogic CSI simulator and RuView ingestion

docs/adr/ADR-046-android-tv-box-armbian-deployment.md

@@ -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):
 

docs/adr/ADR-266-mediatek-filogic-csi-platform.md

@@ -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/)

docs/adr/ADR-267-mediatek-mimo-csi-wire-protocol.md

@@ -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)

docs/ddd/deployment-platform-domain-model.md

@@ -425,7 +425,7 @@ pub enum WifiChipset {
     BroadcomBcm43455,
     /// Realtek RTL8822CS via modified rtw88 driver.
     RealtekRtl8822cs,
-    /// MediaTek MT7661 via mt76 driver modification.
+    /// Proposed MediaTek MT7661 research target; no public CSI export is verified.
     MediatekMt7661,
 }
 
@@ -455,7 +455,7 @@ pub struct Esp32CompatFrame {
 ```
 
 **Domain Services:**
-- `CsiExtractionService` — Reads raw CSI from patched driver via Netlink socket (BCM43455), procfs (RTL8822CS), or UDP (MT7661)
+- `CsiExtractionService` — Reads raw CSI from a validated chipset adapter. Nexmon/BCM43455 is the established Linux example; RTL8822CS and MT7661 remain unverified research targets and must not be advertised as working capture paths.
 - `SubcarrierResamplerService` — Resamples chipset-specific subcarrier counts to match ESP32 format (e.g., 256 → 128 via decimation or interpolation)
 - `ProtocolTranslatorService` — Converts `ChipsetCsiFrame` to `Esp32CompatFrame` with ADR-018 binary encoding
 - `CalibrationService` — Compensates for chipset-specific phase offsets, antenna spacing, and gain differences relative to ESP32 CSI
@@ -625,7 +625,7 @@ pub struct EspNodeConnection {
 
 ### ESP32 Protocol ACL (CSI Bridge)
 
-The WiFi CSI Bridge translates chipset-specific CSI formats (Nexmon, rtw88, mt76) into the ESP32 binary protocol (ADR-018). The sensing server never knows whether frames came from a real ESP32 or a TV box WiFi chipset. Virtual node IDs (200-254) prevent collision with physical ESP32 IDs but are otherwise treated identically by the ingestion context.
+The WiFi CSI Bridge translates validated chipset-specific CSI formats into a versioned RuView envelope. Nexmon is the established Linux example; rtw88 and mt76 require a verified complex-CSI export before implementation. Virtual node IDs (200-254) prevent collision with physical ESP32 IDs but are otherwise treated identically by the ingestion context.
 
 ### Armbian Platform ACL
 

docs/releases/v0.9.1-mediatek-beta.1.md

@@ -0,0 +1,32 @@
+# RuView v0.9.1-mediatek-beta.1
+
+This simulator-first beta adds a Rust MediaTek Filogic MIMO CSI transport and
+RuView ingestion path while preserving the boundary between demonstrated host
+integration and unavailable physical CSI export.
+
+## Included
+
+- ADR-266 selects OpenWrt One (MT7981/MT7976) as the primary future hardware
+  target and BPI-R3 (MT7986/MT7975) as the secondary 4x4 target.
+- ADR-267 defines the bounded, versioned, CRC-protected `MTC1` wire protocol.
+- `mediatek-csi-sim` provides deterministic MT7981, MT7986, and MT7996 profiles,
+  complex MIMO CSI, per-chain RSSI, UDP streaming, and replay output.
+- RuView validates MediaTek datagrams, publishes bounded WebSocket summaries,
+  and exposes `/api/v1/csi/mediatek/latest`.
+- `mediatek:simulated` provenance is retained end to end.
+
+## Validation
+
+- Codec round trips, deterministic output, corruption/truncation rejection,
+  dimension limits, finite-value enforcement, and prefix parsing are tested.
+- All hardware and sensing-server regression tests pass.
+- All three profiles were streamed over loopback UDP and verified through the
+  RuView REST API.
+
+## Hardware boundary
+
+Upstream `mt76` and public MediaTek SDK material do not currently expose a
+supported raw complex CSI API. This release does not redistribute private SDK
+material, invent a firmware ABI, or claim physical MediaTek capture. Hardware
+support requires a documented firmware/driver channel-estimate export followed
+by calibration and repeatability validation.

v2/crates/wifi-densepose-hardware/README.md

@@ -28,6 +28,21 @@ cargo run -p wifi-densepose-hardware --bin rtl8720f-sim -- `
 Add `--udp 127.0.0.1:5005 --realtime` to stream one ADR-264 frame per UDP datagram. Replay files
 contain a little-endian `u32` frame length followed by the encoded frame.
 
+## MediaTek Filogic CSI simulator (ADR-266/267)
+
+The Rust-only simulator models bounded MIMO CSI for MT7981/MT7976,
+MT7986/MT7975, and MT7988/MT7996 profiles without claiming an undocumented
+MediaTek firmware ABI. Every frame is marked `SYNTHETIC`.
+
+```powershell
+cargo run -p wifi-densepose-hardware --bin mediatek-csi-sim -- `
+  --profile mt7981 --frames 100 --output mediatek-synthetic.mtc
+```
+
+Add `--udp 127.0.0.1:5005 --realtime` to stream one CRC-protected ADR-267
+frame per UDP datagram. Physical support remains gated on a documented `mt76`
+or MediaTek firmware channel-estimate export.
+
 ## Features
 
 - **ESP32 binary parser** -- Parses ADR-018 binary CSI frames streamed over UDP from ESP32 and

v2/crates/wifi-densepose-hardware/src/bin/mediatek-csi-sim.rs

@@ -0,0 +1,133 @@
+//! Deterministic MediaTek Filogic MIMO CSI simulator (ADR-266/267).
+
+use clap::{Parser, ValueEnum};
+use std::{
+    fs::File,
+    io::{self, Write},
+    net::{SocketAddr, UdpSocket},
+    path::PathBuf,
+    thread,
+    time::Duration,
+};
+use wifi_densepose_hardware::mediatek_csi::{
+    simulator::{MediatekCsiSimulator, SimulatorConfig},
+    ChipsetProfile, CsiFrame,
+};
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+enum Profile {
+    Mt7981,
+    Mt7986,
+    Mt7996,
+}
+impl Profile {
+    fn chipset(self) -> ChipsetProfile {
+        match self {
+            Self::Mt7981 => ChipsetProfile::Mt7981Mt7976,
+            Self::Mt7986 => ChipsetProfile::Mt7986Mt7975,
+            Self::Mt7996 => ChipsetProfile::Mt7988Mt7996,
+        }
+    }
+    fn default_chains(self) -> u8 {
+        match self {
+            Self::Mt7981 => 3,
+            Self::Mt7986 | Self::Mt7996 => 4,
+        }
+    }
+}
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "mediatek-csi-sim",
+    about = "Emit synthetic ADR-267 MediaTek Filogic MIMO CSI frames"
+)]
+struct Args {
+    #[arg(long, value_enum, default_value_t=Profile::Mt7981)]
+    profile: Profile,
+    #[arg(long, default_value_t = 100)]
+    frames: u32,
+    #[arg(long, default_value="0x4d544b4353490001", value_parser=parse_u64)]
+    seed: u64,
+    #[arg(long, default_value_t = 80)]
+    bandwidth: u16,
+    #[arg(long, default_value_t = 2)]
+    tx: u8,
+    #[arg(long)]
+    rx: Option<u8>,
+    #[arg(long, default_value_t = 256)]
+    subcarriers: u16,
+    #[arg(long, default_value_t = 20)]
+    interval_ms: u64,
+    #[arg(long)]
+    udp: Option<SocketAddr>,
+    /// Replay: little-endian u32 length followed by one ADR-267 envelope.
+    #[arg(long)]
+    output: Option<PathBuf>,
+    #[arg(long)]
+    realtime: bool,
+}
+fn parse_u64(v: &str) -> Result<u64, String> {
+    if let Some(h) = v.strip_prefix("0x").or_else(|| v.strip_prefix("0X")) {
+        u64::from_str_radix(h, 16).map_err(|e| e.to_string())
+    } else {
+        v.parse()
+            .map_err(|e: std::num::ParseIntError| e.to_string())
+    }
+}
+fn emit(
+    frame: CsiFrame,
+    socket: Option<&UdpSocket>,
+    destination: Option<SocketAddr>,
+    output: &mut Option<File>,
+) -> Result<usize, Box<dyn std::error::Error>> {
+    let wire = frame.to_bytes()?;
+    if let (Some(s), Some(d)) = (socket, destination) {
+        if s.send_to(&wire, d)? != wire.len() {
+            return Err(io::Error::new(io::ErrorKind::WriteZero, "partial UDP datagram").into());
+        }
+    }
+    if let Some(f) = output {
+        f.write_all(&(wire.len() as u32).to_le_bytes())?;
+        f.write_all(&wire)?;
+    }
+    Ok(wire.len())
+}
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let a = Args::parse();
+    if a.udp.is_none() && a.output.is_none() {
+        return Err("select at least one sink with --udp or --output".into());
+    }
+    let cfg = SimulatorConfig {
+        seed: a.seed,
+        chipset: a.profile.chipset(),
+        bandwidth_mhz: a.bandwidth,
+        tx_count: a.tx,
+        rx_count: a.rx.unwrap_or_else(|| a.profile.default_chains()),
+        subcarriers: a.subcarriers,
+        frame_period_us: a.interval_ms * 1000,
+        ..Default::default()
+    };
+    let mut sim = MediatekCsiSimulator::new(cfg)?;
+    let socket = a.udp.map(|_| UdpSocket::bind("0.0.0.0:0")).transpose()?;
+    let mut output = a.output.as_ref().map(File::create).transpose()?;
+    let mut bytes = emit(
+        sim.capabilities_frame(),
+        socket.as_ref(),
+        a.udp,
+        &mut output,
+    )?;
+    for _ in 0..a.frames {
+        bytes += emit(sim.next_frame(), socket.as_ref(), a.udp, &mut output)?;
+        if a.realtime {
+            thread::sleep(Duration::from_millis(a.interval_ms));
+        }
+    }
+    eprintln!(
+        "emitted {} synthetic MediaTek CSI frames ({} bytes, profile={}, seed={:#x})",
+        a.frames + 1,
+        bytes,
+        a.profile.chipset().name(),
+        a.seed
+    );
+    Ok(())
+}

v2/crates/wifi-densepose-hardware/src/lib.rs

@@ -53,6 +53,8 @@ pub mod sync_packet;
 // coordinator-node Rust code drive the controller stack without
 // touching any downstream signal/ruvector/train/mat crate.
 pub mod radio_ops;
+/// ADR-267 vendor-neutral MediaTek Filogic MIMO CSI framing and simulator.
+pub mod mediatek_csi;
 /// ADR-264 host-side framing for Realtek RTL8720F CFR and FMCW radar reports.
 /// This module has no dependency on the vendor SDK.
 pub mod rtl8720f;
@@ -73,6 +75,13 @@ pub use radio_ops::{
     RadioError, RadioHealth, RadioMode, RadioOps, MESH_HEADER_SIZE, MESH_MAGIC, MESH_MAX_PAYLOAD,
     MESH_VERSION,
 };
+pub use mediatek_csi::{
+    ChipsetProfile as MediatekChipsetProfile, CsiFlags as MediatekCsiFlags,
+    CsiFrame as MediatekCsiFrame, CsiParseError as MediatekCsiParseError,
+    CsiPayload as MediatekCsiPayload, ElementFormat as MediatekElementFormat,
+    PpduType as MediatekPpduType, ReportKind as MediatekReportKind,
+    MEDIATEK_CSI_HEADER_LEN, MEDIATEK_CSI_MAGIC, MEDIATEK_CSI_VERSION,
+};
 pub use rtl8720f::{
     ElementFormat as Rtl8720fElementFormat, RadarFlags as Rtl8720fRadarFlags,
     RadarFrame as Rtl8720fRadarFrame, RadarParseError as Rtl8720fRadarParseError,