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

• Toolchain: arduino-cli 1.5.1 in ~/.local/bin (NOT on default PATH), arduino:avr core, MCUFRIEND_kbv + GFX + TouchScreen + SD + SdFat libs
• UNO clone (CH340, /dev/ttyUSB0) + shield verified (ILI9486, SD OK); 2GB card wiped clean
• Mega 2560 original firmware backed up, then repurposed
• Mega shield verified (also 0x9486); 16GB card full-card formatted to FAT32 via SdFormatter (killed hidden NOOBS ext4 partitions)
• 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/