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-mechanical a2c554c232 cleanup: remove all Mamba/F722S/STM32F722 refs — replace with ESP32-S3 BALANCE/IO 
- docs/: rewrite AGENTS.md, wiring-diagram.md (SAUL-TEE arch); update
  SALTYLAB.md, FACE_LCD_ANIMATION.md, board-viz.html, SALTYLAB-DETAILED refs
- cad/: dimensions.scad FC params → ESP32-S3 BALANCE params
- chassis/: ASSEMBLY.md, BOM.md, ip54_BOM.md, *.scad — FC_MOUNT_SPACING/
  FC_PITCH → TBD ESP32-S3; Drone FC → MCU mount throughout
- CLAUDE.md, TEAM.md: project desc → SAUL-TEE; hardware table → ESP32-S3/VESC
- USB_CDC_BUG.md: marked ARCHIVED (legacy STM32 era)
- AUTONOMOUS_ARMING.md: USB CDC → inter-board UART (ESP32-S3 BALANCE)
- projects/saltybot/SLAM-SETUP-PLAN.md: FC/STM32F722 → BALANCE/CAN
- jetson/docs/pinout.md, power-budget.md, README.md: STM32 bridge → CAN bridge
- jetson/config/RECOVERY_BEHAVIORS.md: FC+Hoverboard → BALANCE+VESC
- jetson/ros2_ws: stm32_protocol.py → esp32_protocol.py,
  stm32_cmd_node.py → esp32_cmd_node.py,
  mamba_protocol.py → balance_protocol.py; can_bridge_node imports updated
- scripts/flash_firmware.py: DFU/STM32 → pio run -t upload
- src/ include/: ARCHIVED headers added (legacy code preserved)
- test/: ARCHIVED notices; STM32F722 comments marked LEGACY
- ui/diagnostics_panel.html: Board/STM32 → ESP32-S3

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

4.5 KiB
Raw Permalink Blame History

Face LCD Animation System (Issue #507)

Implements expressive face animations on the ESP32-S3 BALANCE board LCD display (Waveshare Touch LCD 1.28, GC9A01 1.28" round 240×240) 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 BALANCE (Waveshare Touch LCD 1.28)
  • Receives emotion commands from Orin via CAN (0x300 mode byte) or inter-board UART
  • Clock: 240 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)