# Development Log

## 2026-04-25: Initial Setup

### Project: nrfwarch
Smartwatch firmware for Seeed Xiao nRF54L15 Sense with GDEY0154D61LT 1.54" e-ink display (SSD1680 controller).

### Board setup
- Ported SSD1680 e-ink driver from jcontrerasf/E-ink-display-Zephyr (nRF52840/PlatformIO) to Xiao nRF54L15 with modern Zephyr APIs
- Created custom devicetree binding (`nrfwarch,epd-ctrl`) for EPD GPIO pins
- VCOM command (0x2C, value 0xA5) added to init sequence
- Partial update uses `0xCF` control byte (clock + analog + temperature, no LUT reload)

### Framebuffer renderer
- 200x200 monochrome framebuffer, 5000 bytes
- Y-flip in `wf_set_pixel` compensates for SSD1680 data entry mode 0x01 (Y decrement): `ram_row = (199 - y)`
- `wf_draw_glyph` draws a glyph bitmap onto the framebuffer at (dst_x, dst_y). Font data uses bit=1 for foreground (draw black), bit=0 for background (skip). Background pixels are NOT written so the framebuffer underneath is preserved.
- Stack overflow in `epd_clear` fixed by using static buffer instead of stack allocation

### Fonts
- `tools/gen_fonts.py` generates `src/fonts.h` and `src/fonts.c` programmatically
- Digits are 24x40px (120 bytes each), colon is 8x40px (40 bytes)
- Digits are drawn as stroked outlines: horizontal/vertical lines + filled rectangles
- Each digit is a seven-segment-style rendering with 2px stroke thickness and 3px margins
- To regenerate: `python3 tools/gen_fonts.py`

### EPD wiring (Xiao nRF54L15 Sense)
| Signal | Pin | GPIO |
|--------|-----|------|
| MOSI   | D10 | SPI MOSI |
| CLK    | D8  | SPI SCK |
| CS     | D1  | xiao_d 1 |
| DC     | D3  | xiao_d 3 |
| RST    | D0  | xiao_d 0 |
| BUSY   | D2  | xiao_d 2 |

## 2026-04-25: Display Simulator

### What was done
- `sim/` directory with display simulator for watchface development without hardware
- `sim/src/epd_sim.c` implements the same API as `src/epd_drv.c`, dumps framebuffer as hex over stdout with `!F!`/`!E!` framing
- `sim/view.py` reads hex frames from stdin, inverts polarity (framebuffer bit=1 is white, PBM bit=1 is black), writes PBM to `/tmp/nrfwarch.pbm`
- feh auto-launches with `--auto-reload` for live display
- Sim runs on Zephyr `native_sim` target (native Linux process, not QEMU). Time advances 1 min/sec.

### Sim architecture
```
Zephyr native_sim binary (zephyr.exe)
  -> watchface.c renders to framebuffer (same code as hardware)
  -> epd_sim.c dumps hex frames to stdout
  -> view.py reads stdin, converts to PBM
  -> feh displays the image with auto-reload
```

### Frame protocol
- `!F!` = frame start, then 5000 bytes as hex (32 bytes/line), `!E!` = frame end
- view.py ignores everything outside markers (handles Zephyr log output mixed in)

## 2026-04-25: Flake, Tests, and Font Fixes

### Nix flake
- Converted from shell.nix to flake.nix with three apps:
  - `nix run .#setup-sdk` - downloads Zephyr v4.0 + SDK 0.17.0, patches all ELF binaries for NixOS
  - `nix run .#test` - builds and runs ztest suite on QEMU x86
  - `nix run .#sim` - builds and runs display simulator with feh viewer
- Dev shell includes: cmake, ninja, west, qemu_full, feh, dtc, patchelf

### NixOS SDK patching
- Zephyr SDK binaries are dynamically linked with `/lib64/ld-linux-x86-64.so.2` interpreter
- Must patchelf every ELF binary (bin/, libexec/, lib/) to point at NixOS's ld-linux
- The setup-sdk app handles this automatically

### Test suite (17 tests, all passing)
- **Framebuffer**: clear sets all 0xFF, pixel set/get roundtrip, bounds checking, Y-flip at corners
- **Fonts**: digit/colon array sizes match compile-time constants, all digits contain non-trivial data
- **Rendering**: draw_time modifies buffer, different times produce different buffers, battery indicator renders, 0% vs 100% battery differs
- **Glyph**: all-ones glyph sets pixel to black

### Bugs fixed this session
- **Inverted fonts**: `wf_draw_glyph` had `black = !(val & bit)` which inverted foreground/background. Fixed to only draw when bit=1 (foreground), skip bit=0 (background).
- **Leading bar artifact**: Background pixels were being explicitly written as white on every glyph byte, overwriting adjacent content. Fixed by skipping background pixels entirely (`continue` on bit=0).
- **Font data mismatch**: Original hand-written font data had wrong byte counts (112 bytes declared as 64). Replaced with programmatic generator.
- **epd_clear stack overflow**: 5000-byte array on stack blew past 4KB main stack. Changed to static buffer.
- **Devicetree binding**: `compatible = "simple-bus"` rejected custom GPIO properties. Created proper `nrfwarch,epd-ctrl.yaml` binding.

### Next steps
- BLE CTS client for time sync from phone
- GRTC-based RTC for persistent timekeeping across system-off
- Battery monitoring via ADC channel 7 with VBAT regulator
- LSM6DSO IMU wrist-tilt wake detection
- System-off power management with regulator control
- Partial refresh for minute updates (avoid full refresh flicker)