# xblink Development Plan

## Overview

xblink is an NFC-powered LED implant. Development proceeds in phases, starting with dev board prototyping (XIAO M0 + LP5562EVM + NTAG5Link Click) and progressing to a custom SAMD21E PCB suitable for implantation.

LED controller code is modular via a `LedController` trait — the LP5562 is the primary target, but the architecture supports other LED driver ICs and simple GPIO PWM for single-color LEDs.

---

## Phase 1: LP5562 Driver Integration

**Goal**: Get LP5562EVM running RGBW LED patterns from the XIAO M0.

**Hardware**: XIAO M0 ↔ LP5562EVM via I2C (A4/A5) + EN on D0/A0.

### Tasks

1. **Copy LP5562 driver** from `../ntag5-samd21-lp562/src/lp5562.rs` into `src/led/lp5562.rs`. This is a complete 757-line driver covering all LP5562 features: direct PWM, current control, engine programming, LED mapping, power-save, and clock config. It is generic over `embedded_hal::i2c::I2c` (1.0).

2. **Define `LedController` trait** in `src/led/mod.rs`:
   ```rust
   pub trait LedController {
       type Error;
       fn set_channel(&mut self, channel: u8, brightness: u8) -> Result<(), Self::Error>;
       fn set_all_channels(&mut self, values: &[u8]) -> Result<(), Self::Error>;
       fn all_off(&mut self) -> Result<(), Self::Error>;
       fn channel_count(&self) -> u8;
       fn supports_engines(&self) -> bool;
       fn load_pattern(&mut self, pattern: &[u8]) -> Result<(), Self::Error>;
       fn stop_pattern(&mut self) -> Result<(), Self::Error>;
   }
   ```

3. **Add GPIO EN pin** to LP5562 wrapper. The LP5562EVM EN pin is connected to D0/A0 for hardware power control:
   ```rust
   pub struct Lp5562Gpio<I2C, EN> {
       lp: Lp5562<I2C>,
       en_pin: EN,
   }
   ```
   This wrapper manages the hardware enable alongside the I2C driver, allowing complete power-down for energy savings.

4. **Test sequences**:
   - Direct PWM: set individual channel colors, verify RGBW output
   - Current control: set 2-5mA per channel (suitable for EH power budget)
   - Engine programs: breathing pattern (ramp up/down with branch loop)
   - Engine programs: RGB color cycle (3 engines with synchronized triggers)
   - Engine programs: heartbeat pulse (fast ramp, slow decay)

### Reference Code

The sibling project's `main.rs` (lines 49-114) provides a complete working example:
- LP5562 init: `enable()` → 1ms delay → `init_direct_control(Internal)` → `set_all_current(100, 100, 100, 100)`
- Color cycling loop with `set_all_pwm()` and delay
- This exact pattern works with the LP5562EVM

---

## Phase 2: NTAG5Link Driver (MCU-side I2C)

**Goal**: Read and write NTAG5Link EEPROM and SRAM from the SAMD21 over I2C.

**Hardware**: XIAO M0 ↔ NTAG5Link Click via I2C (shared bus with LP5562).

**Important**: The MCU accesses the NTAG5Link as a standard I2C slave at address 0x54. This is plain register read/write — completely different from the NFC-side ISO15693 custom commands (0xD2 READ_SRAM, 0xD4 WRITE_I2C, etc.) used by the Python `ntag5sensor` tooling.

### Driver Design

```rust
pub struct Ntag5Link<I2C> {
    i2c: I2C,
    addr: u8,  // 0x54 default
}
```

**EEPROM access** (2048 bytes, 512 blocks of 4 bytes each):
- Read: I2C write 2-byte block address, then I2C read 4 bytes
- Write: I2C write 2-byte block address + 4 bytes data
- Bulk read: iterate blocks into caller-provided buffer

**SRAM access** (256 bytes, 64 blocks of 4 bytes):
- Same read/write pattern as EEPROM, different address range (0xF8-0xFF)
- Used as NFC ↔ I2C mailbox for phone communication

**Session registers** (7 bytes at 0x00-0x06):
- Single-byte address, read/write 1 byte
- Include EH status, field detection, arbiter mode control

### NTAG5Link Configuration

Must configure NTAG5Link for our use case (via NFC-side config write before first use, or via I2C config registers):

| Setting | Value | Constant (from ntag5link.py) |
|---------|-------|------------------------------|
| Use case | I2C slave | `CONFIG_1_USE_CASE_CONF_I2C_SLAVE = 0 << 4` |
| Arbiter mode | SRAM pass-through | `CONFIG_1_ARBITER_MODE_SRAM_PASSTHROUGH = 2 << 2` |
| SRAM enable | On | `CONFIG_1_SRAM_ENABLE = 1 << 1` |
| EH mode | Low field strength | `CONFIG_0_EH_MODE_LOW_FIELD_STRENGTH = 2 << 2` |
| EH voltage | 3.0V | EH_CONFIG register bits 2:1 = 10 |
| EH current | 9.0mA+ | EH_CONFIG register bits 6:4 |

---

## Phase 3: Pattern Storage Format

**Goal**: Define a compact binary format for LED patterns stored in NTAG5Link EEPROM.

### Format Specification

```
Pattern Header (16 bytes):
  [0-3]   Magic: 0x58 0x42 0x4C 0x4B ("XBLK")
  [4]     Version: 0x01
  [5]     Flags:
            bit 0: has engine 1 program
            bit 1: has engine 2 program
            bit 2: has engine 3 program
            bit 3: has direct color values
            bit 4-7: reserved
  [6]     Number of pattern entries (1-255)
  [7]     Current setting for all channels (0-255 → 0-25.5mA)
  [8-9]   Reserved
  [10-13] Direct color values (R, G, B, W) — used when flag bit 3 set
  [14-15] CRC-16 of bytes 0-13 + all entry data

Pattern Entry (2 + N*2 bytes each):
  [0]     Entry type:
            0x01 = Engine program (LP5562 engine commands)
            0x02 = Direct PWM keyframes
  [1]     Length in 16-bit words (1-16 for engine programs)
  [2..N]  Command words (big-endian, LP5562 engine format)

Engine Assignment Block (4 bytes, after all entries):
  [0]     Engine 1 → entry index (0xFF = unused)
  [1]     Engine 2 → entry index (0xFF = unused)
  [2]     Engine 3 → entry index (0xFF = unused)
  [3]     LED mapping byte (LP5562 LED_MAP register 0x70 format)
```

**Size**: A typical 3-engine pattern with 16 commands each: 16 + 3×(2 + 32) + 4 = **122 bytes**. Even complex multi-pattern configs fit comfortably in the 2048-byte EEPROM.

### Built-in Default Patterns

Hardcoded in firmware as fallbacks:
- **Solid color**: Direct PWM, no engines needed
- **Breathing**: 1 engine — ramp up, ramp down, branch to start
- **RGB cycle**: 3 engines — staggered phase with trigger synchronization
- **Heartbeat**: 1 engine — fast ramp up, slow exponential decay
- **Rainbow fade**: 3 engines — slow ramp with offset phases

---

## Phase 4: Power Management

**Goal**: Minimize MCU power draw so LP5562 gets maximum current budget from energy harvesting.

### Sleep Architecture

1. After boot and LP5562 engine programming, enter SAMD21E **STANDBY** mode (~5µA)
2. LP5562 runs autonomously using its internal 256Hz oscillator — no MCU involvement
3. Wake sources via External Interrupt Controller (EIC):
   - **NTAG5Link FD pin**: NFC field detection or SRAM write indication
   - **Hall sensor GPIO**: Recovery trigger (magnet proximity)

### Power Budget Analysis

| Component | Active | Sleep/Idle | Notes |
|-----------|--------|------------|-------|
| SAMD21E | 3-5mA @ 48MHz | ~5µA standby | Sleep ASAP after boot |
| LP5562 | 0.5mA quiescent + LED current | Power-save mode | LEDs dominate budget |
| LP5562 LEDs (4ch) | 2-5mA × 4 = 8-20mA | 0mA (PS_EN) | Must stay within EH budget |
| NTAG5Link | ~100µA | ~1µA standby | Minimal contributor |
| **Total (steady state)** | **9-21mA** | **~5µA** | EH max: ~12.5mA |

**Key insight**: The system budget is tight. At 12.5mA EH and ~0.6mA quiescent (LP5562 + NTAG5), that leaves ~12mA for LEDs. At 3mA per channel, 4 channels = 12mA — right at the limit. Consider:
- Running fewer channels simultaneously
- Using LP5562 engine PWM duty cycling to reduce average current
- Pulsed patterns (breathing, heartbeat) inherently use less average current than solid-on

### Energy Harvesting Configuration

Set via NTAG5Link config registers (one-time setup via PCSC reader):
- Voltage: 3.0V (EH_CONFIG bits 2:1 = 10)
- Current threshold: start at 9.0mA, increase if patterns are dim
- Mode: Low field strength (CONFIG_0 bits 3:2 = 10) — better for phone NFC
- FD pin: SRAM write indication mode (for NFC communication wake)

---

## Phase 5: NFC Communication Protocol

**Goal**: Enable phone-to-MCU communication through NTAG5Link SRAM mailbox.

### SRAM Mailbox Protocol

The NTAG5Link's 256-byte SRAM is accessible from both NFC (phone) and I2C (MCU) sides. We use it as a command/response mailbox.

```
Command Frame (NFC → MCU, written to SRAM by phone):
  [0]     Command byte:
            0x01 = Write pattern (followed by pattern data)
            0x02 = Read current pattern info
            0x03 = Set direct color (4 bytes RGBW follow)
            0x04 = Get firmware version
            0x05 = Enter bootloader (reserved)
  [1]     Sequence number (for request/response matching)
  [2-3]   Payload length (little-endian, max 252)
  [4-255] Payload data

Response Frame (MCU → NFC, written to SRAM by MCU):
  [0]     Status:
            0x00 = OK
            0x01 = Error (error code in payload)
            0x02 = Busy
            0x03 = Ready for next chunk
  [1]     Sequence number (echoed from command)
  [2-3]   Payload length (little-endian)
  [4-255] Payload data
```

### Chunked Transfer

For patterns larger than 252 bytes (unlikely but supported):
- Command 0x01 payload starts with chunk header: `[chunk_index: u8, total_chunks: u8, ...]`
- MCU accumulates chunks in RAM
- After final chunk, MCU writes complete pattern to EEPROM
- MCU responds with 0x03 (ready for next chunk) or 0x00 (complete)

### Communication Flow

1. Phone writes command frame to NTAG5Link SRAM via NFC
2. NTAG5Link asserts FD pin (SRAM write indication)
3. SAMD21E wakes from STANDBY via EIC interrupt
4. MCU reads SRAM via I2C, processes command
5. MCU pauses LP5562 if needed (set engines to Hold)
6. MCU performs action (update pattern, read info, etc.)
7. MCU writes response frame to SRAM via I2C
8. MCU resumes LP5562 engines if paused
9. MCU returns to STANDBY
10. Phone reads response from SRAM via NFC

---

## Phase 6: Recovery and Safe Mode

**Goal**: Provide a way to recover from bad patterns or firmware issues post-implantation.

### Hall Sensor Recovery

A hall effect sensor connected to a SAMD21E GPIO pin (EIC-capable) provides recovery triggering by holding a magnet near the implant.

**Boot-time check**:
1. On every boot, before reading EEPROM, check hall sensor GPIO state
2. If asserted (magnet present): enter recovery mode
3. If not asserted: normal boot, read EEPROM pattern

**Recovery mode behavior**:
- Load hardcoded default pattern: solid white at 25% brightness (~1.5mA/ch)
- Do NOT read EEPROM pattern (in case it's corrupted or causes issues)
- Set recovery flag in NTAG5Link SRAM so phone app can detect recovery state
- Remain awake (do not enter STANDBY) to allow firmware update operations
- Optionally: blink onboard LED in recognizable recovery pattern

**Runtime trigger**: Hall sensor also serves as EIC wake source during sleep. Possible uses:
- Cycle to next stored pattern
- Enter diagnostic mode
- Force re-read of EEPROM pattern

---

## Phase 7: Firmware Update Strategy

### Analysis

| Approach | Pros | Cons | Feasibility |
|----------|------|------|-------------|
| **NFC pass-through bootloader** | True OTA, no physical access | Complex, slow (256B SRAM chunks for 256KB flash = thousands of transactions), custom bootloader needed | Possible but hard |
| **UF2 bootloader (USB)** | Fast, well-established, standard tooling | Requires USB access — impossible once implanted | Dev phase only |
| **Hybrid (recommended)** | Best of both: UF2 for dev, NFC OTA deferred | Two bootloader systems to maintain | Practical |

### Recommended Approach

1. **Development phase**: Use UF2 bootloader on XIAO M0 for rapid iteration. Flash with `cargo hf2 --release`.
2. **Pre-implant**: Thoroughly test final firmware via UF2. Ensure pattern system works perfectly since that's the primary update mechanism post-implant.
3. **Post-implant updates**: The pattern storage in NTAG5Link EEPROM provides the most common update path — new patterns without new firmware. This covers the majority of use cases.
4. **Future NFC OTA**: Implement minimal NFC pass-through bootloader in a later phase if needed. Would require:
   - ~8KB reserved flash for bootloader code (BOOTPROT fuse)
   - Custom chunked transfer protocol over SRAM mailbox
   - CRC verification before committing new firmware
   - Fallback to known-good firmware on verification failure

---

## Phase 8: Custom PCB (SAMD21E)

### Porting from XIAO M0 to SAMD21E18A

| Change | From (XIAO M0) | To (Custom PCB) |
|--------|----------------|------------------|
| BSP crate | `xiao_m0 = "0.13"` | `atsamd-hal = { version = "0.17", features = ["samd21e"] }` |
| Runtime | Included in BSP | Add `cortex-m-rt = "0.7"` |
| Linker script | Included in BSP | Custom `memory.x` for SAMD21E18A |
| Package | SAMD21G18A (48-pin TQFP) | SAMD21E18A (32-pin QFN, 5×5mm) |
| SERCOM | SERCOM0 (BSP-configured) | Remap to available SERCOM on E variant |
| Pins | BSP pin names (a0, a4, a5, led0) | Direct PAC pin references |

### PCB Design Targets

| Component | Package | Size |
|-----------|---------|------|
| SAMD21E18A | QFN-32 | 5×5mm |
| LP5562 | QFN-16 | 3×3mm |
| NTAG5Link (NTP53x2) | XSON-8 | 1.45×1mm |
| Hall sensor | SOT-23 | 2.9×1.6mm |
| NFC antenna | PCB trace loop | ~12-15mm diameter |

Target form factor: disc under 15mm diameter or capsule under 12×30mm.

---

## Phase 9: Companion App

### React Native App

- NFC communication via platform-native APIs (Android NFC, iOS Core NFC)
- ISO15693 NTAG5Link access for SRAM mailbox protocol
- Pattern editor: visual LED color/pattern picker
- Pattern upload: serialize to XBLK format, send via SRAM mailbox
- Status display: firmware version, current pattern info, recovery state
- Testing: use VivoKey RawNFC and DT NFC Identifier as reference

---

## Technical Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Power budget too tight for 4ch LED | High | Limit current to 2-3mA/ch, use pulsed patterns, run fewer channels |
| I2C bus contention (LP5562 + NTAG5) | Medium | Always pause LP5562 before NTAG5 I2C access, resume after |
| EEPROM write endurance (~100K cycles) | Low | Use SRAM for transient communication, EEPROM only for pattern persistence |
| Boot time too slow for user experience | Low | Estimated ~15-20ms total — fast enough to appear instant |
| NFC coupling distance too short | Medium | Optimize antenna, use low field strength EH mode, accept 1-3cm range |
| Firmware bug post-implant with no OTA | High | Hall sensor recovery, thorough pre-implant testing, pattern-only updates cover most needs |