mcp_screen/voice_animations/README.md

Reyna little32 ESP32-S3 Voice State Animations

A collection of 14 standalone MicroPython animation scripts designed for the Reyna little32 ESP32-S3 reflective screen board. These animations support voice gateway visual states instead of a spoken initial acknowledgement (ACK).

Hardware & API Assumptions

• Display Size: Auto-scaling (reads display.width and display.height; defaults to 400x300 for RLCD, but supports others).
• Colors: Designed for monochrome-ish 0 (White/Background) and 1 (Black/Foreground) high-contrast visuals.
• Methods Used: clear(c), fill_rect(x,y,w,h,c), rect(x,y,w,h,c), line(x1,y1,x2,y2,c), text(msg,x,y,c), show().
• Standalone: Each script is entirely self-contained. It can be uploaded individually to board flash and requires no helper modules.
• Robustness: Gracefully falls back and prints a warning if board_config or board_config.display_instance is missing.

---

Animation List & State Mappings

Filename	Voice States / Purposes	Visual Behavior
ack_pulse.py	ack, received, got_it	Bold checkmark with expanding concentric radar pulses.
listening_wave.py	listening, audio_input	A decorative mic icon at the top and dual active overlapping sine waves.
caption_scan.py	captioning, transcribing	Simulated typing log with scanner sweeps and blinking typewriter cursors.
waiting_orbit.py	waiting, thinking, processing	4 circular ring nodes orbiting a central pulsing energy reactor core.
working_gears.py	working, tool_use, executing	Large and small mechanical gears interlocking and rotating in opposite directions.
speaking_mouth.py	speaking, audio_output	Equalizer voiceprint spectrum bars bouncing symmetrically from a center axis.
success_spark.py	success, done, completed	Bold checkmark inside a blooming radial starburst explosion.
error_alert.py	error, failure, alert	Flashing bold exclamation triangle with diagonal warning hazard stripes.
network_retry.py	network_retry, reconnecting	Wi-Fi waves lighting up sequentially inside looping dashed reload arrows.
battery_low.py	battery_low, low_power	Battery outline with tips, flashing empty charge block, and warning triangle.
update_progress.py	update, uploading, downloading	Sliding download arrow dropping into a tray above a percentage progress bar.
breathing_idle.py	idle, ready, breathing	Concentric squares and accent dots scaling slowly in a calm breathing rhythm.
wake_attention.py	wake, attention, active	Stylized robot eyes blinking and shifting gaze left and right to look around.
kid_companion.py	kid_friendly, companion	Friendly robot head with wiggling ears, a winking eye, and a warm smile.

---

Execution Guide

1. Uploading to Flash

You can upload the desired animation files using tools like ampy, rshell, mpremote, or via the board's web console. E.g.

mpremote cp voice_animations/*.py :

2. Execution from REPL (Script Mode)

Run any script automatically with default parameters using exec:

# Runs for 100 frames (approx. 5 seconds) and exits
exec(open("ack_pulse.py").read())

3. Importing and Running (Module Mode)

You can import the module and call its run method directly. The run method supports text customization and infinite looping:

import listening_wave

# Run with custom caption text for 50 frames
listening_wave.run(text="HOTWORD CAPTURED", frames=50)

# Run indefinitely (blocking loop, break with Ctrl+C)
listening_wave.run(text="READY TO HEAR", frames=-1)

---

Technical Details

Customizing Loop Duration

In the run() function:

• Set frames > 0 to run for a finite duration (useful for transition ACK animations).
• Set frames=None or frames=-1 (or omit) to run indefinitely inside a while True loop.
• All scripts catch KeyboardInterrupt to exit gracefully, leaving the screen in a clean state if interrupted.