saltylab-firmware/docs/FACE_LCD_ANIMATION.md

Face LCD Animation System (Issue #507)

Implements expressive face animations on an ESP32-S3 LCD display with 5 core emotions and smooth transitions.

Features

Emotions

• HAPPY: Upturned eyes, curved smile, raised eyebrows
• SAD: Downturned eyes, frown, lowered eyebrows
• CURIOUS: Wide eyes, raised eyebrows, slight tilt, inquisitive mouth
• ANGRY: Narrowed eyes, downturned brows, clenched frown
• SLEEPING: Closed/squinted eyes, peaceful smile
• NEUTRAL: Baseline relaxed expression

Animation Capabilities

• Smooth Transitions: 0.5s easing between emotions (ease-in-out cubic)
• Idle Blinking: Periodic automatic blinks (4-6s intervals)
• Blink Duration: 100-150ms per blink
• Frame Rate: 30 Hz target refresh rate
• UART Control: Text-based emotion commands from Jetson Orin

Architecture

Components

1. face_lcd.h / face_lcd.c — Display Driver

Low-level abstraction for LCD framebuffer management and rendering.

Features:

• Generic SPI/I2C display interface (hardware-agnostic)
• Monochrome (1-bit) and RGB565 support
• Pixel drawing primitives: line, circle, filled rectangle
• DMA-driven async flush to display
• 30Hz vsync control via systick

2. face_animation.h / face_animation.c — Emotion Renderer

State machine for emotion transitions, blinking, and face rendering.

Features:

• Parameterized emotion models (eye position/size, brow angle, mouth curvature)
• Smooth interpolation between emotions via easing functions
• Automatic idle blinking with configurable intervals
• Renders to LCD via face_lcd_* primitives

3. face_uart.h / face_uart.c — UART Command Interface

Receives emotion commands from Jetson Orin over UART.

Protocol:

HAPPY       → Set emotion to HAPPY
SAD         → Set emotion to SAD
CURIOUS     → Set emotion to CURIOUS
ANGRY       → Set emotion to ANGRY
SLEEP       → Set emotion to SLEEPING
NEUTRAL     → Set emotion to NEUTRAL
BLINK       → Trigger immediate blink
STATUS      → Echo current emotion + idle state

Integration Points

main.c

1. Includes (lines 32-34):

   • face_lcd.h, face_animation.h, face_uart.h

2. Initialization (after servo_init()):

   • face_lcd_init(), face_animation_init(), face_uart_init()

3. SysTick Handler:

   • face_lcd_tick() for 30Hz refresh vsync

4. Main Loop:

   • face_animation_tick() and face_animation_render() after servo_tick()
   • face_uart_process() after jlink_process()

Hardware Requirements

Display

• Type: Small LCD/OLED (SSD1306, ILI9341, ST7789)
• Resolution: 128×64 to 320×240
• Interface: SPI or I2C
• Colors: Monochrome (1-bit) or RGB565

Microcontroller

• ESP32-S3xx (ESP32-S3 BALANCE)- Available UART: USART3 (PB10=TX, PB11=RX)
• Clock: 216 MHz

Animation Timing

Parameter	Value	Notes
Refresh Rate	30 Hz	~33ms per frame
Transition Duration	500ms	15 frames at 30Hz
Easing Function	Cubic ease-in-out	Smooth accel/decel
Blink Duration	100-150ms	~3-5 frames
Blink Interval	4-6s	~120-180 frames

Files Modified/Created

File	Type	Notes
include/face_lcd.h	NEW	LCD driver interface (105 lines)
include/face_animation.h	NEW	Emotion state machine (100 lines)
include/face_uart.h	NEW	UART command protocol (78 lines)
src/face_lcd.c	NEW	LCD framebuffer + primitives (185 lines)
src/face_animation.c	NEW	Emotion rendering + transitions (340 lines)
src/face_uart.c	NEW	UART command parser (185 lines)
src/main.c	MODIFIED	+35 lines (includes + init + ticks)
test/test_face_animation.c	NEW	Unit tests (14 test cases, 350+ lines)
docs/FACE_LCD_ANIMATION.md	NEW	This documentation

Status

✅ Complete:

• Core emotion state machine (6 emotions)
• Smooth transition easing (ease-in-out cubic)
• Idle blinking logic (4-6s intervals, 100-150ms duration)
• UART command interface (text-based, 8 commands)
• LCD framebuffer abstraction (monochrome + RGB565)
• Rendering primitives (line, circle, filled rect)
• systick integration for 30Hz refresh
• Unit tests (14 test cases)
• Documentation

⏳ Pending Hardware:

• LCD hardware detection/initialization
• SPI/I2C peripheral configuration
• Display controller init sequence (SSD1306, ILI9341, etc.)
• Pin configuration for CS/DC/RES (if applicable)