xblink/README.md

# xBlink

NFC-powered LED implant using NTAG5Link, SAMD21E, and LP5562.

A battery-free subdermal LED implant that harvests energy from an NFC field. An NTAG5Link provides power and storage, a SAMD21E microcontroller reads stored LED patterns and programs the LP5562 LED driver's autonomous execution engines, then sleeps. Patterns are updated wirelessly via NFC from a phone.

## Hardware Overview

```
                                    I2C (0x30)
  Phone/Reader )))  NFC  ((( NTAG5Link ---------> LP5562 -----> RGBW LEDs
                            |         |           |
                            | VOUT    | FD pin    | EN (wired-AND)
                            |  (EH)   |           |  |
                            v         v           |  |
                          +--SAMD21E--+           |  |
                          | D0/A0 (open-drain) ---+  |
                          | A4/A5 (I2C bus) ------+  |
                          | EIC  <--- Hall Sensor ---+  (open-drain)
                          +----------+     |
                                          Rpull-up (1M)
                                           |
                                          VCC
```

All power comes from NTAG5Link energy harvesting — no battery.

## Components

| Component       | Part                                 | Role                                                | I2C Addr     | Key Specs                                                  |
| --------------- | ------------------------------------ | --------------------------------------------------- | ------------ | ---------------------------------------------------------- |
| NFC + Power     | NXP NTAG5Link (NTP53x2)              | NFC interface, energy harvesting, pattern storage   | 0x54 (slave) | 2048B EEPROM, 256B SRAM, ISO15693, 1.8/2.4/3.0V EH output  |
| MCU             | SAMD21E18A                           | Firmware (Rust), pattern loading, sleep/wake        | —            | 256KB flash, 32KB RAM, ARM Cortex-M0+, 32-pin QFN          |
| LED Driver      | TI LP5562                            | RGBW LED control with autonomous patterns           | 0x30         | 4ch RGBW, 3 execution engines, 16 cmds/engine, 0-25.5mA/ch |
| Recovery + Swap | Hall effect sensor (e.g. TI DRV5032) | Pattern cycling, recovery trigger, hardware EN kill | —            | Open-drain, active-low, omnipolar, <2µA quiescent          |

**Dev board**: Seeed XIAO M0 (SAMD21G18A) + LP5562EVM + MikroElektronika NTAG5 Link Click

## Architecture

### Boot Sequence

1. NFC field detected by NTAG5Link
2. VOUT powers SAMD21E; pull-up asserts LP5562 EN (unless hall sensor is active)
3. SAMD21E boots, reads hall sensor GPIO
4. If hall asserted → **boot-time recovery** (see Recovery Mode below)
5. Normal boot: reads LED pattern from NTAG5Link EEPROM via I2C
6. Programs LP5562 execution engines with pattern data
7. Enters STANDBY sleep (~5µA)
8. LP5562 runs patterns autonomously using internal oscillator
9. NFC field drops → VOUT drops → clean power-off

### Pattern Update Sequence

1. Phone sends new pattern data to NTAG5Link via NFC
2. NTAG5Link signals MCU via FD pin (SRAM write indication)
3. SAMD21E wakes from sleep via EIC interrupt
4. Pauses LP5562 engines (set exec to Hold)
5. Reads new pattern from NTAG5Link SRAM mailbox via I2C
6. Writes pattern to NTAG5Link EEPROM for persistence
7. Reprograms LP5562 engines with new pattern
8. Returns to STANDBY sleep

### Hall Sensor Interaction

The hall sensor serves three purposes via a wired-AND circuit: the hall sensor (open-drain, active-low) and MCU GPIO (open-drain) share the LP5562 EN line with a pull-up resistor. When the magnet is present, EN is forced low at the hardware level — independent of MCU state.

**Pattern Swap (tap <1s):**
1. Magnet near → hall pulls EN low → LEDs off instantly (hardware)
2. MCU wakes via EIC interrupt, starts timer
3. Magnet removed → MCU re-asserts EN (pin high-Z, pull-up takes over)
4. Loads next stored pattern → LEDs back on

**Boot-time Recovery:**
If the hall sensor is asserted when the MCU powers up (magnet was present before NFC field arrived):
- LP5562 EN held low by hardware (LEDs never turn on)
- Loads a hardcoded default pattern (solid white, low brightness)
- Ignores EEPROM pattern data
- Sets recovery flag in SRAM for phone app detection
- Remains awake for firmware update if supported

**Hardware Safety:** Even if the MCU firmware crashes, holding a magnet near the implant forces the LEDs off at the circuit level.

## Power Budget

All power from NTAG5Link energy harvesting. Budget is constrained and TBD pending prototype measurements.

| Parameter          | Value    | Notes                                                   |
| ------------------ | -------- | ------------------------------------------------------- |
| EH max current     | ~12.5mA  | Highest threshold setting                               |
| EH voltage         | 3.0V     | Required for LP5562 (2.7-5.5V) and SAMD21E (1.62-3.63V) |
| LP5562 per channel | 0-25.5mA | Must limit to ~2-5mA/ch for EH budget                   |
| SAMD21E active     | ~3-5mA   | During boot and pattern programming                     |
| SAMD21E standby    | ~5uA     | After LP5562 engines are running                        |

## Getting Started

### Toolchain Setup

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Add ARM Cortex-M0+ target
rustup target add thumbv6m-none-eabi

# Install cargo-hf2 for UF2 flashing (XIAO M0)
cargo install cargo-hf2
```

On Linux, add udev rule for XIAO bootloader (vendor ID 0x2886):
```bash
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2886", MODE="0666"' | sudo tee /etc/udev/rules.d/99-xiao.rules
sudo udevadm control --reload-rules
```

### Build and Flash

```bash
cargo build --release

# Put XIAO in bootloader mode (double-tap RST), then:
cargo hf2 --release
```

## Dev Board Wiring

Current prototype (XIAO M0 + LP5562EVM):

| XIAO Pin  | Connection                  | Function                                    |
| --------- | --------------------------- | ------------------------------------------- |
| A4 (SDA)  | LP5562 SDA, NTAG5 SDA       | Shared I2C data                             |
| A5 (SCL)  | LP5562 SCL, NTAG5 SCL       | Shared I2C clock                            |
| D0/A0     | LP5562 EN line (open-drain) | Hardware enable, wired-AND with hall sensor |
| TBD (EIC) | Hall sensor output          | Interrupt/wake + wired-AND to EN line       |
| 3V3       | VCC                         | Power                                       |
| GND       | GND                         | Ground                                      |

LP5562 EN line has a 1M pull-up resistor to VCC. Both D0/A0 (open-drain) and the hall sensor (open-drain, active-low) connect to this line — either can pull EN low.

## Project Status

See [docs/STATUS.md](docs/STATUS.md) for current progress.

## Related Projects

- `../ntag5-samd21-lp562/` — LP5562 Rust driver prototype and SAMD21 test firmware
- `../ntag5sensor/` — Python NTAG5Link tooling (PCSC reader, ISO15693, sensor interface)