feat(firmware): add an optional kaomoji expression library

[AndreLYL]

What

Tiny Engineer already has activity-driven eye modes, but applications cannot independently select and render a catalogue of expressive faces. This adds an optional C++ library with sixteen animated, kaomoji-inspired faces for a 128×32 monochrome OLED, plus a standalone demo that cycles through them every three seconds.

render(Expression, elapsedMs, buffer, bufferSize) writes one frame into a caller-owned 512-byte buffer compatible with Adafruit GFX drawBitmap(). The caller owns timing, expression selection, display initialization, and orientation. Existing eye modes remain the default; this PR does not connect the new expressions to AI events, HTTP commands, or robot motion.

• Sixteen original geometric pixel designs, including happy, curious, thinking, sleepy, sad, angry, shy, and heart eyes.
• Thirty frames per expression at 100 ms per frame. The 480 frame references share 87 unique frames, using 18,624 bytes for losslessly compressed assets and lookup tables.
• No dynamic allocation, blocking delay, or hardware ownership in the renderer.
• Editable drawing source, deterministic generator, native tests, API documentation, and CI checks.

The optional expression-demo build initializes only the OLED. Normal firmware builds and saved settings are unchanged.

Checks

• Conventional Commit title; no breaking HTTP, pin, NVS, servo-default, or hook changes.
• node scripts/expressions/generate.js --check and node scripts/expressions/test-assets.js: all 480 decoded frames match the original design baselines.
• pio test -e native: 21 tests passed, covering the renderer and existing settings/servo normalization tests.
• pio run and pio run -e expression-demo: both passed with Arduino-ESP32 3.3.11.
• Existing Cursor, Antigravity, and Claude Code package tests: 27 tests passed.
• Hardware tested on an OLED bench setup, as described below.
• No credentials, private device logs, or local paths in the source change.

HTTP routes, settings, pins, servo ranges, CAD, and PCB are unchanged, so the corresponding template checks are not applicable.

Hardware validation

Tested the exact example on a Waveshare ESP32-C3-Zero with a 128×32 I²C OLED using the SSD1306 driver at 0x3C. A local EXPRESSION_DEMO_ROTATION=2 override matched the display's mounting orientation; the repository default remains 0.

A 102.148-second serial capture recorded 35 expression states: every expression appeared at least twice in order, with transitions every 2.999–3.003 seconds. An on-site visual check confirmed correct orientation, expressions, and animation. Reset resumed autoplay, and the calibration NVS region was byte-identical before and after flashing.

Fixed-expression long-duration playback and physical power removal/reconnection were not tested on hardware; frame looping is covered by native tests. No photo/video recording is attached.

For the OLED-only bench test, keep the separate servo V+ rail switched off: the demo does not send PCA9685 commands and cannot clear output state retained by an already powered controller.

Summary by CodeRabbit

• New Features

  • Added 16 animated OLED expressions, including happy, curious, sleepy, sad, angry, and love faces.
  • Added a reusable renderer for 128×32 monochrome OLED displays, with 30 frames per expression and three-second animation loops.
  • Added an opt-in ESP32-C3 OLED demo that detects display availability and renders expressions over I²C.

• Documentation

  • Added usage, rendering format, asset workflow, setup, wiring, and upload instructions.

• Quality Improvements

  • Added automated checks for generated assets, rendering behavior, animation timing, and demo builds.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 8dd23e76-baeb-401f-b0fb-6c39a1c7e0e9

📥 Commits

Reviewing files that changed from the base of the PR and between 5a1d005 and fbfa60d.

📒 Files selected for processing (14)

• .github/workflows/ci.yml
• docs/testing.md
• examples/expression-demo/main.cpp
• lib/TinyEngineerExpressions/README.md
• lib/TinyEngineerExpressions/library.json
• lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
• lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
• lib/TinyEngineerExpressions/src/expression_assets.h
• platformio.ini
• scripts/expressions/designs.js
• scripts/expressions/generate.js
• scripts/expressions/manifest.json
• scripts/expressions/test-assets.js
• test/test_expressions/test_expressions.cpp

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

Adds a 16-expression animated OLED library, compressed asset generation and validation, an ESP32-C3 SSD1306 demo, native renderer tests, documentation, and CI checks.

Changes

OLED expressions

Layer / File(s)	Summary
Expression asset pipeline scripts/expressions/designs.js, scripts/expressions/generate.js, scripts/expressions/manifest.json, scripts/expressions/test-assets.js	Defines 16 animated face designs, rasterizes 30 frames per face, compresses frames with RLE, generates C++ and JSON assets, and validates hashes, sizes, and round trips.
Renderer API and library packaging lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h, lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp, lib/TinyEngineerExpressions/library.json, lib/TinyEngineerExpressions/README.md	Adds the expression enum, timing constants, name(), and validated render() support with Arduino program-memory compatibility and documented output format.
Renderer and asset validation test/test_expressions/test_expressions.cpp	Tests names, all animation frames, invalid inputs, buffer guards, timing wraparound, and deterministic rendering.
OLED demo integration and CI checks platformio.ini, examples/expression-demo/main.cpp, .github/workflows/ci.yml, docs/testing.md	Adds the opt-in ESP32-C3 OLED demo, display initialization and animation loop, documented test and bench commands, and CI checks for the demo build and generated assets.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to fbfa6

The optional OLED expression library and demo have no identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.71% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 35 functions across 7 files. (6 skipped: 6…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding an optional kaomoji expression library to the firmware.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 5.71% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 35 functions across 7 files. (6 skipped: 6 unsupported.)

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[jamro]

This looks really cool! I should be able to test it on the actual robot on Thursday/Friday before we merge it. Looking forward to seeing these expressions in action 🙂