# xBlink Development Guide

Embedded Rust firmware for a battery-free, NFC-powered LED implant. The NTAG5Link harvests energy from an NFC field (1.8V) and provides EEPROM storage for LED patterns. A SAMD21E MCU reads patterns from EEPROM, drives 6 red LEDs directly via TCC hardware PWM through current-limiting resistors, and updates duty cycles from a 50Hz timer ISR. The MCU stays in IDLE sleep during animation.

## Build Commands

```bash
# Build release firmware
cargo build --release

# Flash via UF2 bootloader (XIAO M0: double-tap RST to enter bootloader)
cargo hf2 --release

# Auto-flash: watches for bootloader USB device, flashes when detected
./flash_when_ready.sh
```

## Target

- Architecture: `thumbv6m-none-eabi` (ARM Cortex-M0+)
- Dev board: Seeed XIAO M0 (SAMD21G18A) — will port to bare SAMD21E18A later
- LEDs: 6x low-Vf red LEDs (Kingbright APTD1608, Vf ~1.7V) driven via TCC PWM + resistors
- NFC: NTAG5Link Click board (MikroElektronika)
- LP5562: removed from design (requires 2.7V min, incompatible with 1.8V EH)

## Dependencies

| Crate          | Version | Purpose                                                  |
| -------------- | ------- | -------------------------------------------------------- |
| `xiao_m0`      | 0.13    | Board support package (dev board phase)                  |
| `panic-halt`   | 0.2     | Minimal panic handler for `no_std`                       |
| `cortex-m`     | 0.7     | Cortex-M runtime, `critical-section-single-core` feature |
| `embedded-hal` | 1.0.0   | Hardware abstraction traits (I2C, GPIO, delay)           |

When porting to bare SAMD21E: replace `xiao_m0` with `atsamd-hal = { version = "0.17", features = ["samd21e"] }` and add `cortex-m-rt = "0.7"`.

## Project Structure

```
src/
  main.rs          # Entry point: boot, EEPROM load, TC4 ISR animation, sleep/wake loop
  led/
    mod.rs         # LED module re-exports
    pwm.rs         # TCC0/TCC1 hardware PWM driver for 6 GPIO-direct LEDs
    lp5562.rs      # LP5562 driver (legacy, kept for reference)
  ntag5/           # NTAG5Link I2C slave driver
  pattern/         # XBLK v2 format, software pattern engine, waveform LUTs
```

## Architecture Conventions

- **`no_std` only**: No heap allocation. Fixed-size arrays and stack-only data structures.
- **`embedded-hal` generics**: All hardware drivers must be generic over `embedded_hal::i2c::I2c` (1.0 traits). Never use concrete HAL types in driver code.
- **Hardware-first**: Get hardware working before extracting abstractions. Traits and formats are designed after hands-on experience, not before.
- **Error types**: Use `Error<E>` enum wrapping underlying I2C error with `From<E>` impl (see LP5562 driver pattern).
- **Register addresses**: Place in a `reg` submodule as `pub const` values.
- **`const fn`**: Prefer `const fn` where possible (see `EngineCommand` builder in LP5562 driver).
- **No `unsafe`**: Avoid unless absolutely necessary for hardware access.

## LED PWM Architecture

6 LEDs driven directly by SAMD21 TCC hardware PWM through current-limiting resistors (10-47 ohm).

| LED | TCC  | Channel | SAMD21E Pin | XIAO Pin |
|-----|------|---------|-------------|----------|
| 0   | TCC0 | WO[0]   | PA04        | A1       |
| 1   | TCC0 | WO[1]   | PA05        | A2       |
| 2   | TCC0 | WO[2]   | PA06        | A3*      |
| 3   | TCC0 | WO[3]   | PA07        | A4*      |
| 4   | TCC1 | WO[0]   | PA10        | D2       |
| 5   | TCC1 | WO[1]   | PA11        | D3       |

*PA06/PA07 conflict with I2C on XIAO M0. Dev board uses 4 LEDs (0,1,4,5).

- **Animation**: TC4 ISR at 50Hz computes brightness from PatternEngine, writes TCC CC registers
- **Power governor**: Proportional scaling ensures total LED current stays within NTAG5 EH budget
- **Sleep**: IDLE mode during animation (~0.5mA MCU), STANDBY when no pattern active (~2uA)

## Key I2C Address

I2C bus (A4/A5) is used for NTAG5 only (LP5562 removed from design).

| Device    | Address | Notes                             |
| --------- | ------- | --------------------------------- |
| NTAG5Link | 0x54    | Default NTP53x2 I2C slave address |

## NTAG5Link I2C Register Map (MCU-side)

The MCU accesses NTAG5Link as a standard I2C slave — plain register read/write, NOT the NFC-side ISO15693 custom commands used by the Python ntag5sensor tooling.

| Region             | Address Range     | Size       | Notes                             |
| ------------------ | ----------------- | ---------- | --------------------------------- |
| Session registers  | 0x00-0x06         | 7 bytes    | Volatile, runtime config          |
| Configuration      | 0x37-0x3F         | Varies     | Persistent, EEPROM-backed         |
| EH config          | 0x3D              | 1 byte     | Energy harvesting voltage/current |
| SRAM               | 0xF8-0xFF         | 256 bytes  | 64 x 4-byte blocks, volatile      |
| EEPROM user memory | blocks 0x00-0x1FF | 2048 bytes | 512 x 4-byte blocks               |

Key config constants (from `../ntag5sensor/vicinity/ntag5link.py`):
- `CONFIG_1_USE_CASE_CONF_I2C_SLAVE = 0 << 4` — NTAG5 as I2C slave (our mode)
- `CONFIG_1_ARBITER_MODE_SRAM_PASSTHROUGH = 2 << 2` — SRAM pass-through for NFC↔I2C
- `CONFIG_1_SRAM_ENABLE = 1 << 1` — Enable SRAM access
- `CONFIG_0_EH_MODE_LOW_FIELD_STRENGTH = 2 << 2` — EH mode for phone NFC

## Hardware Wiring (Dev Board)

| XIAO Pin | Connection            | Function                                    |
| -------- | --------------------- | ------------------------------------------- |
| A1 (PA04)| LED 0 + resistor      | TCC0/WO[0] PWM output                       |
| A2 (PA05)| LED 1 + resistor      | TCC0/WO[1] PWM output                       |
| A4 (SDA) | NTAG5 SDA             | I2C data                                    |
| A5 (SCL) | NTAG5 SCL             | I2C clock                                   |
| D2 (PA10)| LED 4 + resistor      | TCC1/WO[0] PWM output                       |
| D3 (PA11)| LED 5 + resistor      | TCC1/WO[1] PWM output                       |
| A1 (PA04)| NTAG5 FD pin          | Field detect / SRAM write indication (EIC)  |
| TBD      | Hall sensor output    | EIC wake, pattern cycling                   |

## Testing

- **Hardware**: XIAO M0 + NTAG5Link Click + 4 LEDs with resistors on A1/A2/D2/D3
- **PCSC reader**: Use `../ntag5sensor/` Python tooling with ACR1552 reader
- **Phone NFC**: VivoKey RawNFC app for SRAM mailbox testing
- **Phone app**: DT NFC Identifier for basic tag info

## Sibling Projects

- `../ntag5-samd21-lp562/` — Original LP5562 driver (legacy reference)
- `../ntag5sensor/` — NTAG5Link command reference (`vicinity/ntag5link.py`), I2C patterns (`vicinity/i2cbase.py`)