Skip to content

Log an issue

Something not working? Tell us. You do not need to diagnose it, describe what you saw, and hand us the state of the device it happened on. The { } link on every module card leads you there in two clicks, and it is the single most useful thing you can attach.

👉 Open an issue on GitHub

Not sure it's a bug, or want to talk it through first? Discord is the right place for "is this supposed to work like this?".

Steps

Log an issue: search first, check the version, copy each card's { } diagnostics, describe, open the issue. A feature request needs no template.

Bug report template

1. Describe the problem

Steps to reproduce:
1. ...
2. ...

Expected behavior:
[What should happen]

Actual behavior:
[What happens instead]

2. Attach the { } output

⚠️ This is the most useful diagnostic data. It is a JSON snapshot of the module's live state, its type, every control value, its status line and its timing, exactly as it was when things went wrong.

Which cards to include:

  1. Always: System. Names the chip, firmware variant, build, SDK version and the last boot reason, how we tell a board problem from a firmware one
  2. Always: Firmware. The exact version and build you are running
  3. The affected card itself, Effects, Drivers, Layouts, Network, whichever one went wrong
  4. If it is about lights: the Layer card, which carries the geometry
  5. If it is about pins or wiring: the Drivers card

Wrap each one in a fenced code block so the issue stays readable:

API output:

- System
```text
{"name":"System","type":"SystemModule","controls":[{"name":"chip","value":"ESP32-S3"},...]}
```

- Effects
```text
{"name":"Effects","type":"Effects","children":[...]}
```

3. Add a photo

If it is something you can see, a fixture showing the wrong colors, a UI in a state that looks wrong, a photo or screenshot says it faster than a paragraph.

If the device crashed or won't boot

The { } link needs a device that still serves its interface. When it doesn't, tell us instead:

  • What the LEDs did: nothing at all, a brief flash, a repeating pattern
  • What changed just before it started, even if it seems unrelated: a setting, a script edit, a firmware update, a cable moved
  • Does it repeat? Power-cycle it. A device that boots once and fails the next time is a different problem from one that never boots
  • The serial boot log, if you have the device on USB and can run a monitor. If you can't, say so, we will not ask you to set up a toolchain to file a bug

One more thing worth checking yourself: bootReason on the System card. PANIC, TASK_WDT or BROWNOUT means the device crashed or lost power rather than merely misbehaving, and saying so in the first line of the report saves a round trip.

Feature requests

Describe the use case, what you expect it to do, and what you have tried instead. No template, no diagnostics, just tell us what you want to build.