access-controller: add deterministic simulation tests for business logic

Extracts the Wiegand frame decoders and the access-task decision
state machine into a pure `access_controller` library so they can be
exercised on the host without ESP32 hardware. `access_task` becomes a
thin adapter that calls `AccessCore::step()` and dispatches the
returned `Effect`s to Embassy primitives; observable firmware
behavior is unchanged.

Tests combine handwritten scenarios with proptest property tests
(seeded ChaCha PRNG for determinism). Run with:

  RUSTUP_TOOLCHAIN=stable cargo test \
      --no-default-features --features sim \
      --target x86_64-unknown-linux-gnu

Properties proven: no OpenDoor without a current fob-cache hit
(A1/A2/A3); silent backoff window (A4); 10-second recheck deadline
never grants past expiry (A5); every granted card swipe is
accompanied by an allowed:true audit record; and Wiegand
frame-parity / fob-format invariants (W1-W4).

Author: jveski

access-controller/README.md

@@ -24,6 +24,35 @@ Copy `network.env.example` to `network.env` and edit with your values:
 source network.env && cargo run --release
 ```
 
+## Deterministic simulation tests
+
+The crate's business-logic core (Wiegand frame decoders + the
+authorization state machine that drives `access_task`) is extracted into
+a small pure library that can be exercised on the host without any
+ESP32 hardware. Tests live in `tests/wiegand_decode.rs` and
+`tests/access_core.rs` and combine handwritten scenarios with
+`proptest`-based property tests over randomly generated event traces.
+
+Run them with the host toolchain (NOT the `esp` toolchain pinned by
+`rust-toolchain.toml`):
+
+```bash
+RUSTUP_TOOLCHAIN=stable cargo test \
+    --no-default-features --features sim \
+    --target x86_64-unknown-linux-gnu
+```
+
+The `sim` feature gates the binary out (`required-features = ["esp32"]`)
+and makes all hardware deps optional, so only pure code and tests are
+compiled. Default `cargo build --release` for the firmware is
+unaffected.
+
+Properties currently proven include: no `OpenDoor` effect without a
+current fob-cache hit (A1/A2/A3); silent backoff window (A4); 10-second
+recheck deadline never grants past expiry (A5); every granted card swipe
+is accompanied by an `allowed:true` audit record; and Wiegand
+frame-parity / fob-format invariants (W1–W4).
+
 ## Flashing an ESP32
 
 1. Connect ESP32 via USB

access-controller/src/core.rs

@@ -0,0 +1,205 @@
+//! Pure access-control decision state machine.
+//!
+//! This is a mechanical extraction of the body of `access_task` in
+//! `src/main.rs`. All side effects (door pulse, reader feedback, event
+//! buffer push, sync request, watchdog feed) are returned as an `Effect`
+//! enum instead of being performed directly, and all time is taken as an
+//! explicit `u64` (milliseconds since boot) parameter rather than read from
+//! `embassy_time::Instant::now()`. The cache is taken as a slice rather than
+//! a `Mutex` lock.
+//!
+//! This makes the firmware's authorization decisions deterministically
+//! testable from host tests under `cargo test --features sim`, without
+//! changing observable runtime behavior in the firmware.
+//!
+//! The firmware adapter in `main.rs` is responsible for:
+//! - selecting on `WIEGAND_CHANNEL` / `SYNC_COMPLETE` / `WATCHDOG_FEED` and
+//!   mapping each to the corresponding `Input` variant,
+//! - calling `embassy_time::Instant::now().as_millis()` and passing it in,
+//! - locking the `FOBS` mutex and passing a slice,
+//! - dispatching each returned `Effect` to the corresponding `Signal` or
+//!   the global `EVENT_BUFFER`.
+
+use heapless::Vec as HVec;
+
+use crate::events::AccessEvent;
+
+/// Window during which a sync completion can retroactively grant a
+/// previously-denied credential. Matches `main.rs` (10 seconds).
+pub const RECHECK_DEADLINE_MS: u64 = 10_000;
+
+/// Number of effects emitted by a single `step()` call. The current
+/// implementation emits at most 3 (Record + Feedback + OpenDoor on grant;
+/// Record + Feedback + RequestSync on denial); 4 leaves headroom.
+pub const MAX_EFFECTS_PER_STEP: usize = 4;
+
+/// A credential read off the Wiegand reader. Already decoded into both the
+/// H10301 fob form and the byte-swapped NFC UID form so the core does not
+/// need to know about Wiegand framing.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct CardRead {
+    pub fob: u32,
+    pub nfc: u32,
+}
+
+/// Inputs that drive the access-control state machine.
+#[derive(Clone, Copy, Debug)]
+pub enum Input {
+    /// A new credential was decoded by the Wiegand reader.
+    Card(CardRead),
+    /// The sync task finished a round-trip with the Conway server (success
+    /// or failure). The fob cache slice passed to `step()` reflects any
+    /// updates that resulted.
+    SyncComplete,
+    /// The 10-second tick that proves `access_task` is responsive; mapped
+    /// to a hardware watchdog feed by the firmware adapter.
+    WatchdogFeed,
+}
+
+/// The decision a `Card` step produced (used to drive reader LED/beeper).
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Outcome {
+    Granted,
+    Denied,
+}
+
+/// Side effects emitted by `step()`. The firmware adapter is the sole
+/// consumer; tests inspect them directly.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Effect {
+    /// Pulse the door relay (200ms in firmware).
+    OpenDoor,
+    /// Drive the reader LED/beeper.
+    Feedback(Outcome),
+    /// Push an entry into the event buffer for later upload.
+    Record(AccessEvent),
+    /// Ask the sync task to attempt an on-demand round-trip with Conway.
+    RequestSync,
+    /// Feed the hardware watchdog.
+    FeedWatchdog,
+}
+
+/// Pure decision state for the access controller. Mirrors the locals
+/// inside `access_task`.
+#[derive(Clone, Debug)]
+pub struct AccessCore {
+    /// `(fob, nfc, deadline_ms)` — a previously denied credential whose
+    /// authorization will be re-checked when the next sync completes.
+    pending_recheck: Option<(u32, u32, u64)>,
+    /// Card reads received before this timestamp are silently dropped.
+    backoff_until: u64,
+    /// Number of consecutive denials. Drives exponential backoff (1, 2, 4,
+    /// then 8s thereafter). Reset to 0 on any grant.
+    failed_attempts: u8,
+}
+
+impl Default for AccessCore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AccessCore {
+    pub const fn new() -> Self {
+        Self {
+            pending_recheck: None,
+            backoff_until: 0,
+            failed_attempts: 0,
+        }
+    }
+
+    /// Read-only access to the pending recheck window, for tests.
+    pub fn pending_recheck(&self) -> Option<(u32, u32, u64)> {
+        self.pending_recheck
+    }
+
+    /// Read-only access to the backoff deadline, for tests.
+    pub fn backoff_until(&self) -> u64 {
+        self.backoff_until
+    }
+
+    /// Read-only access to the consecutive-denial counter, for tests.
+    pub fn failed_attempts(&self) -> u8 {
+        self.failed_attempts
+    }
+
+    /// Step the state machine.
+    ///
+    /// - `now_ms`: virtual wall clock (milliseconds).
+    /// - `fobs`: snapshot of authorized credential IDs at this instant.
+    /// - `input`: the event being delivered.
+    ///
+    /// Returns the ordered list of effects the firmware adapter must apply.
+    pub fn step(
+        &mut self,
+        now_ms: u64,
+        fobs: &[u32],
+        input: Input,
+    ) -> HVec<Effect, MAX_EFFECTS_PER_STEP> {
+        let mut out: HVec<Effect, MAX_EFFECTS_PER_STEP> = HVec::new();
+
+        match input {
+            Input::WatchdogFeed => {
+                let _ = out.push(Effect::FeedWatchdog);
+            }
+
+            Input::SyncComplete => {
+                if let Some((fob, nfc, deadline)) = self.pending_recheck.take() {
+                    if now_ms > deadline {
+                        // Recheck expired; do nothing.
+                        return out;
+                    }
+                    let allowed =
+                        fobs.iter().any(|&f| f == fob) || fobs.iter().any(|&f| f == nfc);
+                    if allowed {
+                        // Mirror main.rs:336-340 — failed_attempts is reset
+                        // to 0 here, but `backoff_until` is intentionally
+                        // *not* cleared. A grant after sync therefore still
+                        // honors any outstanding backoff window for future
+                        // card reads. Tests pin this behavior.
+                        self.failed_attempts = 0;
+                        let _ = out.push(Effect::Feedback(Outcome::Granted));
+                        let _ = out.push(Effect::OpenDoor);
+                    } else {
+                        self.failed_attempts = self.failed_attempts.saturating_add(1);
+                        let delay_ms = (1u64 << self.failed_attempts.min(3)) * 1000;
+                        self.backoff_until = now_ms + delay_ms;
+                        let _ = out.push(Effect::Feedback(Outcome::Denied));
+                    }
+                }
+            }
+
+            Input::Card(read) => {
+                if now_ms < self.backoff_until {
+                    // Card ignored during backoff window; no effects.
+                    return out;
+                }
+
+                let fob = read.fob;
+                let nfc = read.nfc;
+
+                let fob_ok = fobs.iter().any(|&f| f == fob);
+                let nfc_ok = !fob_ok && fobs.iter().any(|&f| f == nfc);
+                let allowed = fob_ok || nfc_ok;
+
+                if allowed {
+                    self.failed_attempts = 0;
+                    let credential = if fob_ok { fob } else { nfc };
+                    let _ = out.push(Effect::Record(AccessEvent {
+                        fob: credential,
+                        allowed: true,
+                    }));
+                    let _ = out.push(Effect::Feedback(Outcome::Granted));
+                    let _ = out.push(Effect::OpenDoor);
+                } else {
+                    let _ = out.push(Effect::Record(AccessEvent { fob, allowed: false }));
+                    let _ = out.push(Effect::Feedback(Outcome::Denied));
+                    let _ = out.push(Effect::RequestSync);
+                    self.pending_recheck = Some((fob, nfc, now_ms + RECHECK_DEADLINE_MS));
+                }
+            }
+        }
+
+        out
+    }
+}

access-controller/src/decode.rs

@@ -0,0 +1,118 @@
+//! Pure Wiegand frame decoders.
+//!
+//! The hardware-driven async reader lives in `src/wiegand.rs`. Everything
+//! testable in isolation (parity checks, field extraction, credential
+//! derivation) lives here so it can be exercised from host tests.
+
+/// Decoded Wiegand credential.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WiegandRead {
+    pub facility: u32,
+    pub card: u32,
+    pub raw_data: u32,
+}
+
+impl WiegandRead {
+    /// H10301 fob format: facility code + 5-digit card ID.
+    pub fn to_fob(&self) -> u32 {
+        self.facility * 100_000 + self.card
+    }
+
+    /// NFC UID derived by byte-reversing the raw data field.
+    pub fn to_nfc_uid(&self) -> u32 {
+        self.raw_data.swap_bytes()
+    }
+}
+
+/// Decode a 26-bit Wiegand frame (H10301).
+///
+/// Frame layout (MSB first):
+/// - bit 25: even-parity over upper 12 data bits
+/// - bits 24..1: 24 data bits (8-bit facility + 16-bit card)
+/// - bit 0: odd-parity over lower 12 data bits
+///
+/// Returns `None` on parity failure.
+pub fn decode_26(raw: u64) -> Option<WiegandRead> {
+    let raw = raw as u32;
+    let leading = (raw >> 25) & 1;
+    let trailing = raw & 1;
+    let data = (raw >> 1) & 0xFF_FFFF;
+
+    let upper = data >> 12;
+    let lower = data & 0xFFF;
+    let even_ok = (upper.count_ones() % 2) == leading;
+    let odd_ok = (lower.count_ones() % 2) != trailing;
+    if !even_ok || !odd_ok {
+        return None;
+    }
+
+    let facility = (data >> 16) & 0xFF;
+    let card = data & 0xFFFF;
+    Some(WiegandRead {
+        facility,
+        card,
+        raw_data: data,
+    })
+}
+
+/// Decode a 34-bit Wiegand frame.
+///
+/// Frame layout (MSB first):
+/// - bit 33: even-parity over upper 16 data bits
+/// - bits 32..1: 32 data bits
+/// - bit 0: odd-parity over lower 16 data bits
+///
+/// NOTE: We intentionally pull facility from bits 23..16 (8-bit), not bits
+/// 31..16 as strict H10304 would specify. This matches the legacy fob
+/// database that pre-dated this firmware. Tests below pin this behavior.
+pub fn decode_34(raw: u64) -> Option<WiegandRead> {
+    let leading = ((raw >> 33) & 1) as u32;
+    let trailing = (raw & 1) as u32;
+    let data = ((raw >> 1) & 0xFFFF_FFFF) as u32;
+
+    let upper = data >> 16;
+    let lower = data & 0xFFFF;
+    let even_ok = (upper.count_ones() % 2) == leading;
+    let odd_ok = (lower.count_ones() % 2) != trailing;
+    if !even_ok || !odd_ok {
+        return None;
+    }
+
+    let facility = (data >> 16) & 0xFF;
+    let card = data & 0xFFFF;
+    Some(WiegandRead {
+        facility,
+        card,
+        raw_data: data,
+    })
+}
+
+/// Build a syntactically valid 26-bit frame for a given facility/card pair,
+/// with correct parity bits. Useful for tests and for round-tripping known
+/// credentials through `decode_26`. Truncates `facility` to 8 bits and
+/// `card` to 16 bits per H10301.
+pub fn encode_26(facility: u32, card: u32) -> u64 {
+    let facility = facility & 0xFF;
+    let card = card & 0xFFFF;
+    let data = (facility << 16) | card;
+    let upper = data >> 12;
+    let lower = data & 0xFFF;
+    // even parity bit: chosen so upper.count_ones() + leading is even.
+    let leading = upper.count_ones() & 1;
+    // odd parity bit: chosen so lower.count_ones() + trailing is odd.
+    let trailing = (lower.count_ones() & 1) ^ 1;
+    ((leading as u64) << 25) | ((data as u64) << 1) | (trailing as u64)
+}
+
+/// Build a syntactically valid 34-bit frame, matching the legacy 8-bit
+/// facility layout that `decode_34` understands.
+pub fn encode_34(facility: u32, card: u32) -> u64 {
+    let facility = facility & 0xFF;
+    let card = card & 0xFFFF;
+    let data: u32 = (facility << 16) | card;
+    let upper = data >> 16;
+    let lower = data & 0xFFFF;
+    let leading = upper.count_ones() & 1;
+    let trailing = (lower.count_ones() & 1) ^ 1;
+    ((leading as u64) << 33) | ((data as u64) << 1) | (trailing as u64)
+}

access-controller/src/events.rs

@@ -0,0 +1,10 @@
+//! Access event reported to the Conway server.
+
+/// A single swipe event: which credential was presented and whether the
+/// local cache authorized it. Buffered locally and POSTed to Conway during
+/// the next sync; only removed from the buffer after the server ACKs.
+#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
+pub struct AccessEvent {
+    pub fob: u32,
+    pub allowed: bool,
+}

access-controller/src/lib.rs

@@ -0,0 +1,19 @@
+//! Pure library surface of the access-controller crate.
+//!
+//! Only modules with zero hardware/HAL dependencies live here. They are
+//! shared between the firmware binary (`src/main.rs`) and host-side
+//! deterministic simulation tests (`tests/*.rs`).
+//!
+//! Build modes:
+//! - Default (firmware): `cargo build` with `--target xtensa-esp32-none-elf`,
+//!   feature `esp32` (enabled by default). `no_std`.
+//! - Simulation/tests: `cargo test --no-default-features --features sim` on
+//!   the host; uses `std` so we can run proptest and standard `#[test]`s.
+
+#![cfg_attr(not(feature = "sim"), no_std)]
+
+extern crate alloc;
+
+pub mod core;
+pub mod decode;
+pub mod events;