googly/.claude/handoffs/2026-07-12-170810-googly-desk-pet.md

# Handoff: googly desk pet — first build session

## Session Metadata
- Created: 2026-07-12 17:08:10
- Project: /home/claude/bin/arduino/googly
- Branch: master (pushed to git.sethpc.xyz/Seth/googly)
- Session duration: ~1.5h (spanned hardware bring-up of the whole Arduino bench)

### Recent Commits (for context)
  - 871a5f3 fix: invert mouth curve (smile was rendering as frown); smoother blink
  - 6dfa1d7 fix: flicker-free delta redraws for pupils/lids; visible smile curve
  - 416bca9 feat: googly desk pet — face engine, mood, touch reactions, EEPROM persistence

## Handoff Chain

- **Continues from**: None (fresh start)
- **Supersedes**: None

## Current State Summary

googly v1 (commit 871a5f3) is flashed and running on the Arduino Mega 2560
(`/dev/ttyACM0`) with a 3.5" UNO-form 8-bit parallel ILI9486 touch shield
(ID 0x9486). Standalone desk pet for Seth's desk at Google: big procedural
face, blinks, pupil wander, poke / multi-poke-dizzy / long-press-pet touch
reactions, sleep after 30 min idle, mood 0–100 persisted in EEPROM. Three fix
rounds happened this session (see commits). **Session ended awaiting Seth's
visual verdict on round 3** (smile shape + blink smoothness). His last
feedback before that flash: "stuck with a frown, blink glitchy but a little
smoother" — the frown is definitively explained by the inverted parabola sign
(fixed in 871a5f3); blink may still need tuning.

## Codebase Understanding

## Architecture Overview

Single-sketch firmware (~380 lines), no external assets. Face is drawn with
GFX primitives; all animation is delta-redraw (full-screen or full-eye
repaints flicker — the 8-bit parallel bus does ~80ms per full screen).
`movePupils()` erases/redraws only the pupil; `setLids()` paints lids
incrementally (BG rect when closing, sclera chord hlines bottom-up when
opening, pupil redraw deferred until the lid clears it). Short animations
(poke, dizzy, yawn, sneeze, fly, wake) are blocking delay() loops —
deliberate ponytail choice, noted in code. Main loop is a 25ms-tick state
machine: IDLE / SLEEPING / PETTING plus gesture edge detection
(tap vs hold vs 3-taps-in-1.5s).

## Critical Files

| File | Purpose | Relevance |
|------|---------|-----------|
| `googly/googly.ino` | entire firmware; tuning knobs at top | everything |
| `../backups/mega-85634313839351202260-{flash,eeprom}.hex` | Mega's original firmware dump (was 99% full — a real program) | restore with avrdude `-c wiring` if Seth ever wants it back |
| `../sd_format_mega/`, `../sd_wipe_mega/`, `../sd_ls_mega/` | Mega SD utilities over soft-SPI | reference for any future SD work on Mega |
| `../sd_wipe/`, `../CardInfo/`, `../graphictest_kbv/` | UNO-side utilities | UNO shield bring-up |

## Key Patterns Discovered

- **AVR has no STL**: no `<initializer_list>` → no range-for over brace lists;
  use plain arrays.
- **Touch shares LCD pins** (XP=6, XM=A2, YP=A1, YM=7): after every
  `ts.getPoint()`, restore A1/A2 to OUTPUT — never remove that. Touch is used
  pressure-only (window 80–1000, two-sample debounce); no x/y calibration
  needed for this UX.
- **SD on Mega with UNO-form shields** needs SdFat soft-SPI: pins 10-13 are
  not Mega hardware SPI. Build with
  `--build-property "compiler.cpp.extra_flags=-DSPI_DRIVER_SELECT=2"`, use
  `SdFat32`/`File32` (plain `SdFat` returns `FsFile`, which lacks
  `rmRfStar()`).

## Work Completed

## Tasks Finished

- [x] Toolchain: arduino-cli 1.5.1 in `~/.local/bin` (NOT on default PATH),
      arduino:avr core, MCUFRIEND_kbv + GFX + TouchScreen + SD + SdFat libs
- [x] UNO clone (CH340, `/dev/ttyUSB0`) + shield verified (ILI9486, SD OK);
      2GB card wiped clean
- [x] Mega 2560 original firmware backed up, then repurposed
- [x] Mega shield verified (also 0x9486); 16GB card full-card formatted to
      FAT32 via SdFormatter (killed hidden NOOBS ext4 partitions)
- [x] googly designed (brainstormed with Seth), built, flashed, repo created
      and pushed; two feedback-fix rounds applied

## Decisions Made

Logged in `DECISIONS.md`: procedural face over sprites; light mood over full
Tamagotchi; Mega over UNO; no SD dependency; pressure-only touch. New this
session (in commits): delta redraws are mandatory; blocking mini-anims are
acceptable.

## Pending Work

## Immediate Next Steps

1. **Get Seth's verdict on 871a5f3**: smile now a real ∪? blink acceptable?
   If blink still glitches, ask what it looks like (tearing sweep / flash /
   stutter) BEFORE changing code — candidates: setLids step count, reveal
   band size, pupil-pop timing.
2. If good: raise `EVENT_MIN_MS/EVENT_MAX_MS` (5–15 min was chosen short for
   dev visibility; desk-appropriate is more like 15–45 min).
3. Exercise untested paths on real hardware: sleep entry/wake, mood tiers
   (frown <33), EEPROM persistence across power cycles, dizzy window feel,
   fly/sneeze/yawn events.
4. Later: README photo of the face; enclosure/stand before it goes to the
   office.

## Blockers/Open Questions

- [ ] None hard. Only Seth's visual feedback loop.

## Deferred Items

- Serial-dashboard generic firmware — parked; better fit for the Leonardo
  (native USB, no reset-on-open). See `~/bin/arduino/googly/DECISIONS.md`
  Deferred section (also: RTC day/night, sound).

## Context for Resuming Agent

## Important Context

- **Opening `/dev/ttyACM0` resets the board** (DTR pulse) — every stty/cat/
  monitor attach reboots the pet and loses unsaved mood (EEPROM saves are
  5-min throttled). A "boot loop" scare this session was entirely
  self-inflicted attach resets. Attach serial deliberately and rarely.
- **The cdc_acm tty can wedge** after heavy stty/hupcl toggling (TIOCMSET
  protocol errors). Software recovery (`authorized` toggle) failed and made
  it worse; only a physical replug fixed it. Don't escalate down that path —
  ask Seth to replug.
- **Display is 8-bit PARALLEL, not SPI** (SD slot is the only SPI part).
- Seth feedback saved to global memory: never use the AskUserQuestion click
  widget; ask questions in plain text.
- Other bench hardware: second UNO, Leonardo, Kuman UNO (unplugged). UNO
  clone on `/dev/ttyUSB0` has identical shield + clean 2GB card.

## Assumptions Made

- Mood 60 EEPROM state survived the session's resets (banner said mood=60 on
  each boot — consistent).
- The Kuman UNO and Leonardo shields (if any) are untested; only the two
  shields seen this session are confirmed ILI9486.

## Potential Gotchas

- UNO + MCUFRIEND graphictest = 98% flash — UNO can't host big display
  projects; use the Mega or Leonardo.
- Soft-SPI SD on Mega is slow (~100–200KB/s) — fine for config/logs, bad for
  full-screen BMPs.
- nvidia_drm WARNINGs in steel141 dmesg are pre-existing Xorg noise —
  unrelated to Arduino/USB work; don't chase them.

## Environment State

### Tools/Services Used

- arduino-cli 1.5.1 at `~/.local/bin/arduino-cli` — needs
  `export PATH=~/.local/bin:$PATH`
- Build: `arduino-cli compile -b arduino:avr:mega googly` (from repo root);
  flash: `arduino-cli upload -b arduino:avr:mega -p /dev/ttyACM0 googly`

### Active Processes

- None. All background serial monitors from this session are stopped/expired.

### Environment Variables

- None specific to this project.

## Related Resources

- Repo: https://git.sethpc.xyz/Seth/googly (LAN: 192.168.0.125)
- Project docs: `IDEA.md`, `DECISIONS.md`, `CLAUDE.md` in repo root
- MCUFRIEND_kbv examples: `~/Arduino/libraries/MCUFRIEND_kbv/examples/`