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 gives you that in one click, 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?".

Checklist

  • Search the existing issues first — it may already be reported, or already fixed
  • Check the Firmware card: are you on the current version?
  • For bugs, include the { } output (below)
  • For feature requests, describe the use case — no template needed

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.

How to get it:

  1. Find the card that misbehaved — the effect that went dark, the driver that isn't lighting, the network card that won't connect
  2. Click the { } link in its title row, next to the ?
  3. Select all in the new tab (Ctrl/Cmd+A), copy, and paste it into the issue

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 colours, 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.