sl-firmware
fa75c442a7
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>
139 lines
4.7 KiB
Markdown
139 lines
4.7 KiB
Markdown
# 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)
|