seb/saltylab-firmware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
saltylab-firmware/docs/FACE_LCD_ANIMATION.md
sl-jetson cea3eaff97 cleanup: Remove all Mamba/STM32/BlackPill references — ESP32-S3 only 
- Renamed mamba_protocol.py → balance_protocol.py; updated all importers
- can_bridge_node.py rewritten to use balance_protocol.py API (ESP32-S3 BALANCE)
- test_can_bridge.py rewritten to test actual balance_protocol.py constants/functions
- All STM32/Mamba references in Python, YAML, Markdown, shell scripts replaced:
  * Hardware: MAMBA F722S → ESP32-S3 BALANCE/IO
  * Device paths: /dev/stm32-bridge → /dev/esp32-io
  * Node names: stm32_serial_bridge → esp32_io_serial_bridge
  * hardware_id: stm32f722 → esp32s3-balance/esp32s3-io
- C/C++ src/include/lib/test files: added DEPRECATED header comment
- Covers: saltybot_bridge, saltybot_can_bridge, saltybot_can_e2e_test,
  saltybot_bringup, saltybot_diagnostics, saltybot_mode_switch, and all
  chassis, docs, scripts, and project files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-04 08:56:09 -04:00

4.3 KiB
Raw Permalink Blame History

Face LCD Animation System (Issue #507)

Implements expressive face animations on an ESP32-S3 IO 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-S3 IO
  • 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)