# Face LCD Animation System (Issue #507)

<<<<<<< HEAD
Implements expressive face animations on an ESP32 LCD display with 5 core emotions and smooth transitions.
=======
Implements expressive face animations on an ESP32-S3 LCD display with 5 core emotions and smooth transitions.
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)

## 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
<<<<<<< HEAD
- ESP32xx (ESP32 BALANCE)
=======
- ESP32-S3xx (ESP32-S3 BALANCE)
>>>>>>> 291dd68 (feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only)
- 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)