---
phase: "07"
plan: "02"
subsystem: firmware
tags: [micropython, animations, led, firmware]
dependency_graph:
  requires: [07-01]
  provides: [animation-rendering-engine]
  affects: [firmware/main.py, firmware/animations.py]
tech_stack:
  added: []
  patterns: [MicroPython-compatible Python, bytearray GC optimization, HSV inline conversion]
key_files:
  created:
    - firmware/animations.py
    - tests/test_firmware_animations.py
  modified:
    - firmware/main.py
decisions:
  - "Inline _hsv_to_rgb replaces colorsys (not available in MicroPython)"
  - "bytearray for FireAnimation heat buffer avoids GC pressure on device"
  - "create_animation() factory centralizes cmd dict to instance mapping"
  - "density field maps to size for chase, cooling for fire, ignored for others"
metrics:
  duration: "155 seconds"
  completed: "2026-04-07"
  tasks: 3
  files: 3
---

# Phase 07 Plan 02: Animation Command Renderer Summary

All 7 LightSync animations ported to MicroPython-compatible firmware with a complete test suite — 26 tests passing with full server-to-firmware round-trip verification.

## Tasks Completed

| # | Task | Commit | Files |
|---|------|--------|-------|
| 1 | Create firmware/animations.py | 053e1ab | firmware/animations.py |
| 2 | Update firmware/main.py with render wiring | 8e521e5 | firmware/main.py |
| 3 | Create test suite + re-apply main.py | 49f0b0f | tests/test_firmware_animations.py, firmware/main.py |

## What Was Built

`firmware/animations.py` contains all 7 animation classes ported from `lightsync/animations/*.py` with these MicroPython adaptations:
- `_hsv_to_rgb()` inline function replaces `colorsys.hsv_to_rgb` (not in MicroPython)
- `bytearray` for `FireAnimation._heat` buffer (avoids GC pressure on device)
- No type hints, no `abc` ABC, no `lightsync` imports
- `create_animation(cmd)` factory maps parsed command dicts to animation instances

`firmware/main.py` updated to:
- Import `create_animation` from `animations`
- Add `current_anim_instance` global
- Create animation instance on `anim_cmd` packet receipt
- Render animation using `ticks_diff()` timing in the render loop

`tests/test_firmware_animations.py` provides 26 host-side tests covering:
- `_hsv_to_rgb` primary colors and edge cases
- All 7 animation classes: length, value ranges, behavior
- `create_animation()` factory for all types + unknown fallback
- Full round-trip: `encode_animation_cmd` -> `parse_animation_cmd` -> `create_animation` -> `render`

## Verification

- `uv run pytest tests/test_firmware_animations.py -v` — 26 passed in 0.05s
- `_hsv_to_rgb` correct: red=(255,0,0), green=(0,255,0), blue=(0,0,255)
- `FireAnimation` uses `bytearray` confirmed by `test_uses_bytearray`
- Round-trip test passes for all 7 animation types
- No `colorsys`, `abc`, or `lightsync` imports in any `firmware/` file

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Re-applied main.py changes after 07-01 parallel agent overwrite**
- **Found during:** Task 3 (after test file creation)
- **Issue:** Agent 07-01 (running in parallel) committed `firmware/main.py` with the scaffold version, reverting the animation wiring committed in Task 2
- **Fix:** Re-applied all animation changes to main.py via Edit tool after detecting the revert in system notification
- **Files modified:** firmware/main.py
- **Commit:** 49f0b0f (included with test file commit)

## Known Stubs

None — plan goal fully achieved. All 7 animations render correctly, tests pass.

## Self-Check: PASSED