LED code calculator

TLDR; We could use a calculator for mapping LED codes to human-readable descriptions

The RGB status LED is hugely expressive, and is a sign of the depth of thought Particle has given to the challenge of boiling down complex inner states to simple, unambiguous output. Unfortunately, determining device state from the status LED has aways been an imperfect science.

https://docs.particle.io/tutorials/device-os/led/xenon/ is helpful, but it doesn’t include all the possibilities. And this is likely by design, because the more variations it has, the more it requires wading through a huge list of non-relevant data to find the appropriate blinking code. And the more frustrating it is to discover by the end that the code does not exist.

The forums are full of questions about light codes, and it makes for a fair amount of duplication of effort, a lot of noise, and resurrection of long-dead threads.

I propose a calculator of some kind which takes the device model, the deviceOS, and the light pattern, and maps it to the message. Perhaps even giving relevant data and links to better understand what the device is trying to say.

This could happen via a web page, or via particle cli. The keyboard could be used as a live input for the blink pattern (r for red, b for blue, c for cyan…), where the input cadence gives the calculator the true speed. This avoids the problem of different users understanding “fast” and “slow” differently. This also makes it easier to have a precise count of the number of flashes, which is useful for the SOS blink.

Another alternative is to have the Particle app be able to process live video, in the same way it does the QR code. This has the downside of being harder to implement and requiring lots more testing, but is sort of the be-all, end-all solution.

Inevitably, there will be a flash code which does not correspond to something in the database. At this point the relevant info and video can be uploaded to Particle support. It could also open a GitHub ticket so that users with similar experiences can pool their knowledge and wisdom.

On the back end it’s really just a simple flow-chart, sort of a Particle Zork.


The LED codes have never and due to deprecation of mesh will never catch up with amount intermediate states of mesh connection states and intersectioins with cellular/WiFi state.

Once you take out everything related to mesh, the descriptions already provided should get you by in all standard cases - non-standard cases won’t have a standardised colour code tho’ :wink:

I feel like there’s enough commonality in the problems that we could drive people toward a fast solution instead of toward the forum.

In the specific case of deprecated mesh, the firmware and hardware is still out there and we can certainly hope that Particle will continue to provide documentation even if there is no support. In a calculator, it would only be a fork in the internal state machine and that fork would only be operational for deviceOS v0.8(?)-1.6.

From a more global perspective, I feel like there have always been undocumented LED codes. For instance, the following all contain some kind of pattern which was relevant but is not currently documented:

I’m reluctant to say it, but they haven’t managed to donate specific color codes to distinguish between the mesh, the outbound radio and the cloud connection.
Mesh and outbound radio was merely mingled together into one mushy legacy code scheme and the rest was left to guessing.
And I doubt there is much incentive to change that now, knowing that this will be a zombi-feature.

Agreed. It’s certainly the route I would take as well.

I’m unsure if you’re saying, though, that a calculator would not be useful. I feel that helping people drill down to a particular class of message is helpful, even in the event where there isn’t a unique answer. You’re right that some thought needs to be given to deprecation, old hardware, and since-resolved bugs, but I feel those cases are exhaustive and the problem is topical to the point that complexity is easily hidden from view.

The alternative is the current process of opening a web page in hope that your particular code is documented. When it’s not, you do a forum search, which gets perhaps 6 years of results, many of which are deprecated or unresolved. If you don’t find your answer there, then you open a new topic and cross your fingers that someone knowledgeable soul will chance across it.

It just seems we can do better…

Sure, if there was such a tool it would probably be received well.

1 Like