# PixelIt agent guidance ## Project and related repositories This repository contains the Arduino/PlatformIO firmware for ESP8266 and ESP32 PixelIt LED matrix displays, including Ulanzi TC001 support. Read [docs/development.md](docs/development.md) before changing firmware; it describes the source layout, build commands, memory constraints and validation procedures. The wider project is maintained in separate repositories: - [PixelIt.Docs](https://github.com/pixelit-project/PixelIt.Docs): project and user documentation. - [node-red-contrib-pixelit](https://github.com/pixelit-project/node-red-contrib-pixelit): Node-RED nodes for controlling displays. - [PixelIt.WebUI](https://github.com/pixelit-project/PixelIt.WebUI): WebUI source. - [PixelIt.API](https://github.com/pixelit-project/PixelIt.API): API service supplying bitmaps; the device's HTTP/MQTT/WebSocket handlers live in this firmware repository. When changing JSON payloads, endpoints, MQTT topics, WebSocket messages or settings, consult the relevant companion repositories and preserve existing client compatibility. Identify required companion changes explicitly, including updates to the external documentation; local `docs/` alone does not cover the project's user documentation. If a companion repository cannot be inspected, report that limitation. ## Firmware conventions - Smooth animation playback is the highest priority. Preserve consistent frame timing and responsive rendering under concurrent HTTP, MQTT, WebSocket, sensor and telemetry activity. Schedule or defer background work so it does not stall playback; do not trade animation smoothness for other features or throughput. For changes affecting the main loop, rendering, networking or memory allocation, assess their effect on frame timing and playback jitter. - Keep ESP8266 and ESP32 support, board-specific pins and conditional compilation intact. - Use ordinary C++ translation units with explicit declarations. Shared state is declared in `include/FirmwareState.h` and defined in `src/FirmwareState.cpp`; internal function declarations belong in `include/FirmwareFunctions.h`. - Treat ESP8266 heap, contiguous allocation size and loop latency as constraints. ESP8266 memory compatibility is a hard requirement alongside smooth playback: features must fit its available RAM, not merely work on ESP32. Consider peak memory use when animation storage, incoming payloads, previews and network buffers coexist. Avoid duplicate buffers, unbounded allocations, repeated allocation/free cycles and heap fragmentation; reuse bounded storage where practical. Check allocation failures and reject oversized input safely without losing the current display or destabilizing the device. Do not increase limits or buffer sizes without assessing the ESP8266 memory budget. Avoid unnecessary JSON/pixel-buffer copies and blocking work during playback. Review `include/AnimationLimits.h` and the development guide before changing limits, MQTT buffer lifetimes or WebSocket preview scheduling. - Preserve pinned dependency/framework versions unless the task requires an upgrade. Framework changes must also account for the HTTP header patch in `extra_script.py`. - Make WebUI source changes in the WebUI repository. `include/Webinterface.h` is embedded build output generated by `.github/webui.py`; avoid editing it by hand. The current workflow uses the older `pixelit-project/WebUI` path; check its relationship to `PixelIt.WebUI` before changing the integration. - Keep local development documentation and `CHANGELOG.md` aligned with behavior changes. Do not present historical device measurements as results of a new run. - Keep individual `CHANGELOG.md` entries, especially under `Unreleased`, concise: use a short sentence focused on the essential change. Omit implementation and test details, but preserve important dependencies and limitations. When asked to shorten entries, shorten their wording without reducing their number unless consolidation is explicitly requested. - Do not insert blank lines between individual changelog/release-note entries. Keep consecutive entries in a compact list. - Before publishing a stable release, update external PixelIt.Docs with explanations of user-visible logs, including components, fields, units, examples, normal/error cases and troubleshooting. Verify byte-count meanings against that release's code. ## New screen transitions When adding a screen transition, check and update all of these entry points: - Firmware `switchAnimation: random`. Include the effect where its input requirements are met, and check both screen payloads and effect-only requests. - Clock Auto Fallback. Check explicit selection in the WebUI, the corresponding firmware configuration and playback, and the fallback's own random mode. Preserve existing numeric setting values. Firmware and its bundled WebUI ship together, so new Clock Auto Fallback options can be exposed without a compatibility gate for older firmware. Deploy the matching WebUI bundle with the firmware change. - `node-red-contrib-pixelit`. Update the Switch Animation editor, check the emitted payload, and update its documentation. Verify explicit and random selection where applicable, and document any intentional exclusions and required companion changes. ## Validation Run checks appropriate to the affected behavior from the repository root: - Firmware changes: build affected board environments. For shared firmware changes, build all six variants using the command in `docs/development.md`. - Animation, payload validation or preview changes: `python3 test/animation/run.py`. - Home Assistant behavior changes: `python3 test/homeassistant/run.py`. - Host tests require dependencies installed by a PlatformIO build; see the relevant test scripts and development documentation for prerequisites. - Device tests require a designated test device and can change its display state; distinguish host/build verification from physical-device verification. - Changes that can affect playback timing need physical-device timing validation under representative concurrent activity when a test device is available. Check frame interval consistency, jitter and dropped LED frames, especially on ESP8266. Passing builds and host tests alone does not establish smooth playback; explicitly report when device timing validation remains outstanding. - Memory-sensitive changes need ESP8266 checks for minimum free heap and largest contiguous free block during representative peak workloads and repeated requests. Check for allocation failures, fragmentation and resets while animations and network activity run together. A successful build alone does not establish RAM safety; report when physical-device memory validation remains outstanding. Report checks performed and any remaining validation gaps. Documentation-only changes do not require firmware builds.