seb/saltylab-firmware
1
0
Fork 0
Code Issues Pull Requests 5 Actions Packages Projects Releases Wiki Activity
saltylab-firmware/docs/FACE_LCD_ANIMATION.md
sl-firmware 291dd689f8 feat: remove all STM32/Mamba/BlackPill references — ESP32-S3 only 
Archive STM32 firmware to legacy/stm32/:
- src/, include/, lib/USB_CDC/, platformio.ini, test stubs, flash_firmware.py
- test/test_battery_adc.c, test_hw_button.c, test_pid_schedule.c, test_vesc_can.c, test_can_watchdog.c
- USB_CDC_BUG.md

Rename: stm32_protocol → esp32_protocol, mamba_protocol → balance_protocol,
  stm32_cmd_node → esp32_cmd_node, stm32_cmd_params → esp32_cmd_params,
  stm32_cmd.launch.py → esp32_cmd.launch.py,
  test_stm32_protocol → test_esp32_protocol, test_stm32_cmd_node → test_esp32_cmd_node

Content cleanup across all files:
- Mamba F722S → ESP32-S3 BALANCE
- BlackPill → ESP32-S3 IO
- STM32F722/F7xx → ESP32-S3
- stm32Mode/Version/Port → esp32Mode/Version/Port
- STM32 State/Mode labels → ESP32 State/Mode
- Jetson Nano → Jetson Orin Nano Super
- /dev/stm32 → /dev/esp32
- stm32_bridge → esp32_bridge
- STM32 HAL → ESP-IDF

docs/SALTYLAB.md:
- Update "Drone FC Details" to describe ESP32-S3 BALANCE board (Waveshare ESP32-S3 Touch LCD 1.28)
- Replace verbose "Self-Balancing Control" STM32 section with brief note pointing to SAUL-TEE-SYSTEM-REFERENCE.md

TEAM.md: Update Embedded Firmware Engineer role to ESP32-S3 / ESP-IDF

No new functionality — cleanup only.

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

4.3 KiB
Raw Blame History

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)