xblink/docs/DEVELOPMENT_PLAN.md

xblink Development Plan

Overview

xblink is an NFC-powered LED implant. Development is organized into small milestones grouped by hardware requirements. Each milestone is scoped to roughly one session of work. Abstractions (traits, pattern formats) are deferred until we have hands-on experience with the hardware they'll abstract.

Guiding Principles

• Hardware-first: Get real LEDs blinking before designing abstractions
• YAGNI: No traits, formats, or protocols until we need them
• Small milestones: Each should produce a flashable, testable result
• Test equipment: Multimeter for power budget, logic analyzer (optional) for I2C debugging

---

Group A — LP5562 Only

Hardware needed: XIAO M0 + LP5562EVM + mini-USB cable

M1: LED Smoke Test

Goal: Verify LP5562 direct PWM control works over I2C.

Copy the proven LP5562 driver from ../ntag5-samd21-lp562/src/lp5562.rs into the project. Wire up I2C and GPIO EN in main.rs. Light up each RGBW channel to confirm wiring and driver work.

Tasks:

1. Copy lp5562.rs → src/led/lp5562.rs
2. Create src/led/mod.rs with pub mod lp5562; re-export
3. Update main.rs: I2C init (A4/A5, 400kHz), GPIO EN on D0/A0, LP5562 enable → 1ms delay → init_direct_control(Internal) → set_all_current(100,100,100,100) → cycle through RGBW
4. Flash and verify all 4 LED channels light up

Reference: Sibling project main.rs lines 40-114 — proven working sequence with LP5562EVM.

Done when: All 4 RGBW LEDs cycle on the LP5562EVM.

M2: Engine Patterns

Goal: Program LP5562 execution engines to run patterns autonomously — the core value proposition.

After engine programming, the MCU can sleep while LP5562 keeps running patterns on its own internal oscillator. This milestone proves the architecture works.

Tasks:

1. Build engine programs using EngineCommand builder (already in driver):
   • Breathing: set_pwm(0) → ramp up → ramp down → branch(0, 0) (infinite loop)
   • Heartbeat: set_pwm(0) → fast ramp up → slow ramp down → wait → branch(0, 0)
   • Color cycle: 3 engines with staggered phases, synchronized via trigger()
2. Map LED channels to engines via set_led_mapping()
3. Load programs, set engines to Run, verify LEDs animate without MCU loop
4. Verify MCU can stop_engine() and resume with a different pattern

Done when: LP5562 runs a breathing pattern while main() sits in an idle loop (no delay_ms driving the LEDs).

M3: Hardcoded Pattern Library

Goal: Build a set of const patterns in firmware, selectable at boot.

This gives us real pattern data to inform the EEPROM storage format later (M5), without designing that format prematurely.

Tasks:

1. Define 4-5 patterns as const or static data:
   • Solid RGBW (direct PWM, no engines)
   • Breathing (single channel, 1 engine)
   • Heartbeat pulse (1 engine, asymmetric ramp)
   • RGB color cycle (3 engines, trigger sync)
   • Rainbow fade (3 engines, staggered offset)
2. Simple pattern selector in main.rs (e.g., cycle through patterns on each boot, or use a compile-time const)
3. Reduce LED current to 20-50 (2-5mA/ch) to simulate EH power budget

Done when: Can flash different patterns by changing a const, each runs autonomously on LP5562.

---

Group B — Add NTAG5Link

Hardware needed: + NTAG5Link Click board + I2C jumper wire

M4: NTAG5 EEPROM Read/Write

Goal: Communicate with NTAG5Link over I2C as a slave device.

Important: The MCU accesses NTAG5Link as a standard I2C slave at address 0x54 — plain register read/write. This is NOT the NFC-side ISO15693 custom commands used by the Python ntag5sensor tooling.

I2C bus management: LP5562 (0x30) and NTAG5Link (0x54) share the same I2C bus (A4/A5). Both addresses are used simultaneously — the MCU talks to each device by its address. Key considerations:

• Both are I2C slave devices with non-conflicting addresses
• LP5562 engines run autonomously after programming — no ongoing I2C traffic needed
• Pause LP5562 engines (set exec to Hold) before lengthy NTAG5 I2C transactions to avoid any bus contention edge cases
• NTAG5Link's use_case must be set to i2c_slave (not i2c_master) so it doesn't drive the bus

Tasks:

1. Write src/ntag5/mod.rs — Ntag5Link<I2C> struct, generic over embedded_hal::i2c::I2c
2. Write src/ntag5/registers.rs — register map constants from ntag5link.py
3. Implement EEPROM block read/write (2-byte block address, 4 bytes per block)
4. Implement session register read (single-byte address)
5. Test: write known data to EEPROM via PCSC reader (ntag5sensor), read back on MCU, display result as LP5562 colors (visual verification)

NTAG5Link config (one-time setup via PCSC reader):

Setting	Value	Constant
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 bits 2:1 = 10

Done when: MCU reads EEPROM data written by PCSC reader and displays it as LED colors.

M5: Boot-from-EEPROM

Goal: Design pattern binary format (informed by M2-M3 experience) and boot from stored patterns.

By now we know exactly what engine programs look like in practice, so the format design is grounded in real usage.

Tasks:

1. Design binary pattern format — header + engine programs + LED mapping (see format spec below)
2. Write src/pattern/mod.rs — deserializer (parse EEPROM bytes → engine programs)
3. Write src/pattern/engine.rs — convert parsed pattern → LP5562 engine program load sequence
4. Update main.rs boot sequence: read EEPROM → parse pattern → program LP5562 → idle
5. Write a Python script (or extend ntag5sensor) to serialize patterns to EEPROM via PCSC
6. Test: write pattern via PCSC, power-cycle, verify LP5562 runs the pattern

Pattern format (preliminary — will be refined based on M2-M3 learnings):

Header (16 bytes):
  [0-3]   Magic: "XBLK" (0x58 0x42 0x4C 0x4B)
  [4]     Version: 0x01
  [5]     Flags (which engines used, direct color mode)
  [6]     Number of pattern entries
  [7]     LED current setting (0-255 → 0-25.5mA)
  [8-13]  Reserved / direct RGBW color values
  [14-15] CRC-16

Entry (2 + N*2 bytes):
  [0]     Type (0x01 = engine program)
  [1]     Length in 16-bit words (1-16)
  [2..]   Engine command words (big-endian)

Assignment (4 bytes, after entries):
  [0-2]   Engine 1/2/3 → entry index (0xFF = unused)
  [3]     LED_MAP register value

Typical 3-engine pattern: 16 + 3×34 + 4 = 122 bytes (fits easily in 2048B EEPROM).

Done when: MCU boots, reads pattern from EEPROM, LP5562 runs it autonomously.

M6: SRAM Mailbox

Goal: Phone writes a new pattern via NFC, MCU picks it up and reprograms LP5562.

Tasks:

1. Write src/ntag5/sram.rs — SRAM block read/write (64 blocks × 4 bytes at 0xF8-0xFF)
2. Design SRAM mailbox command/response protocol:

   Command (NFC → MCU):  [cmd, seq, len_lo, len_hi, payload...]
   Response (MCU → NFC): [status, seq, len_lo, len_hi, payload...]
   Commands: 0x01=write_pattern, 0x02=get_info, 0x03=set_color, 0x04=get_version
   

3. Configure NTAG5Link FD pin for SRAM write indication
4. Implement polling or interrupt-based command detection (EIC wake comes in M7)
5. MCU receives pattern → stores to EEPROM → reprograms LP5562
6. Test with PCSC reader first, then VivoKey RawNFC app

Done when: Pattern update works via NFC without power-cycling the MCU.

---

Group C — Power + Recovery

Hardware needed: + Hall effect sensor + multimeter

M7: Sleep/Wake

Goal: MCU enters STANDBY after programming LP5562, wakes on NFC activity.

Tasks:

1. Configure SAMD21 EIC for NTAG5Link FD pin (wake source)
2. After LP5562 engine programming, enter STANDBY (~5µA)
3. On EIC interrupt (FD pin), wake, process SRAM mailbox, return to sleep
4. Verify LP5562 keeps running patterns during MCU sleep
5. Measure current with multimeter: active vs standby vs total system

Power budget reference:

Component	Active	Standby
SAMD21E	3-5mA	~5µA
LP5562 quiescent	~0.5mA	~0.5mA
LP5562 LEDs (4ch @ 3mA)	~12mA	~12mA
NTAG5Link	~100µA	~1µA
Hall sensor (DRV5032)	~1.6µA	~1.6µA
EN pull-up (1M @ 3V)	~0	~0 (3µA only when EN low)
Total	~17mA	~12.5mA

Key insight: LED current dominates. MCU sleep saves ~4mA. Total must stay under EH max (~12.5mA), so LED current must be limited.

Done when: MCU sleeps after boot, LP5562 runs patterns, MCU wakes on NFC to accept new pattern.

M8: Recovery Mode + Pattern Swap

Goal: Hall sensor provides pattern cycling (tap) and safe mode entry (hold + confirm).

Circuit: Wired-AND on LP5562 EN — hall sensor (open-drain) + MCU GPIO (open-drain) + pull-up resistor. Magnet presence forces EN low at hardware level, independent of MCU state. Hall output also connected to MCU EIC pin for interrupt/wake. See docs/plans/2026-03-03-hall-en-design.md.

Interaction model:

• Boot-time recovery: Hall asserted at power-on → EN held low (hardware), MCU skips EEPROM, loads default pattern, stays awake
• Tap (<1s): LEDs off instantly (hardware EN drop) → magnet removed → MCU loads next pattern → LEDs back
• Hold (>3s + confirm): LEDs off (hardware) → magnet removed → MCU blinks warning (3x red) → 2s window for confirmation tap → if confirmed, enters recovery mode. No second tap → resumes normal operation
• MCU crashed + magnet: Hall still kills EN (hardware safety)

Tasks:

1. Wire hall sensor: open-drain output to EN line (wired-AND) + separate wire to EIC pin
2. Add pull-up resistor (100k-1M) on EN line
3. Configure MCU GPIO (D0/A0) as open-drain for EN control
4. Implement EIC interrupt handler for hall sensor pin
5. Implement boot-time recovery: read hall GPIO at startup, if asserted → default pattern, skip EEPROM
6. Implement runtime state machine: tap detection, hold timing, warning blink, recovery confirmation
7. Recovery behavior: load hardcoded solid white (low brightness), skip EEPROM, stay awake
8. Set recovery flag in SRAM so phone app can detect it

Done when: Boot-time recovery works (magnet at power-on), tap cycles patterns at runtime, hold + confirm enters runtime recovery, hardware EN kill works even if MCU is unresponsive.

M9: Power Characterization

Goal: Measure real power consumption and tune EH settings.

Tasks:

1. Measure current draw: MCU active, MCU standby, LP5562 at various current settings
2. Test NTAG5Link EH output with phone NFC at different current thresholds
3. Find optimal balance: maximum LED brightness within EH budget
4. Document actual power budget (replaces estimates in this plan)

Done when: We have real numbers and documented EH configuration that works reliably.

---

Group D — Abstraction + Polish

Prerequisite: Groups A-C working. Now we know the real interface needs.

M10: LedController Trait

Goal: Extract trait from proven LP5562 usage patterns.

After M1-M9, we know exactly what set_channel, load_pattern, and stop_pattern actually need to look like. Design the trait from real experience, not speculation.

Tasks:

1. Define LedController trait in src/led/mod.rs based on actual usage in main.rs
2. Implement for LP5562 wrapper (including GPIO EN pin)
3. Refactor main.rs to use trait-based API
4. Verify everything still works

M11: SimplePwm Driver

Goal: Single-color LED support via GPIO PWM — only if we have hardware to test.

Implement LedController for direct GPIO PWM. Skip this milestone entirely if we don't have single-color LEDs to validate against.

---

Group E — Future

Deferred until Groups A-D are solid.

Custom PCB (SAMD21E)

• Port from xiao_m0 BSP to atsamd-hal with samd21e feature
• Add cortex-m-rt = "0.7", custom memory.x linker script
• Remap SERCOM and pin assignments for 32-pin QFN
• PCB design: SAMD21E (5×5mm) + LP5562 (3×3mm) + NTAG5Link (1.45×1mm) + hall sensor + antenna
• Target: disc <15mm diameter or capsule <12×30mm

Companion App (React Native)

• NFC via platform APIs (Android NFC, iOS Core NFC)
• ISO15693 access to NTAG5Link SRAM mailbox
• Pattern editor UI + upload
• Status display (firmware version, current pattern, recovery state)

Firmware Update (NFC OTA)

• Custom bootloader in protected flash (~8KB, BOOTPROT fuse)
• Chunked firmware transfer via SRAM mailbox (256B per chunk)
• CRC verification, fallback to known-good firmware
• Development: use UF2 via USB; NFC OTA only if needed post-implant

---

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	Non-conflicting addresses (0x30 vs 0x54). Pause LP5562 engines during NTAG5 I2C bursts. Verify NTAG5 is in i2c_slave mode (not i2c_master)
EEPROM write endurance (~100K cycles)	Low	SRAM for transient comms, EEPROM only for pattern persistence
Boot time too slow	Low	Estimated ~15-20ms — appears instant to user
NFC coupling distance too short	Medium	Optimize antenna, low field strength EH mode, accept 1-3cm
Firmware bug post-implant	High	Hall sensor recovery, thorough pre-implant testing, pattern-only updates