Header Photo by Liam Desic on Unsplash
Modern connected devices are amazing. No matter your development board of choice, these devices pack an array of capabilities in a small package! One device, some sensors and actuators, and a whole world of connected control is at your fingertips.
But do you ever look at your devices and wonder just what’s going on in those tiny, powerful brains of theirs? I mean, look at this magical little thing.
It has so much power. It can read sensors, post messages to the cloud, and expose functions and variables to the outside world. But how do I know what it’s thinking? Is it judging me because I skipped lunch today and ate an entire bag of Pizza-flavored combos?
Every Particle hardware device includes an RGB LED that uses color to communicate with you. It can tell you when your device is online, when its firmware is being updated, and even when things have gone terribly wrong and your device is in SOS mode.
It’s like semaphore — that time-honored naval tradition of visually conveying letters and numbers using flags — for your IoT device, just without the flags, nautical garb, and calming scent of fresh ocean air.
And like semaphore, you need to understand how the signals your device is sending map to something meaningful. Particle devices have a number of modes and states, and they use the onboard RGB LED to keep you informed as to what’s happening on your device. Here’s a look at some of the default modes signaled by the on board LED, and how to decode what your devices are trying to tell you.
What is an RGB LED?
But first, a bit of explanation of this pair of acronyms: RGB & LED. A Red-Green-Blue (RGB) Light-emitting diode (LED) is a single LED that contains red, green and blue diodes inside its package. If you’ve ever purchased a starter kit from us, Adafruit or Sparkfun, you’ve probably seen the through-hole variety of this LED, which tends to have a clear or diffused cap and four leads, instead of the two leads common to single-color LEDs.
Each diode in an RGB LED can be controlled independently, and by combining each at varying levels, millions of colors can be created!
The RGB LED used for all Particle devices is a surface-mount device (SMD) diffused LED. It’s manufactured by Cree and comes in a small 2mm by 2mm package. You can read more about it in the datasheets for the Photon or Electron, and even grab some of your own from DigiKey if you’re like me and you impulsively buy parts whenever you discover a new or interesting one.
Demystifying the LED States
You can learn a lot about the state of your device just by looking at the colors and patterns the RGB LED shows. But there are a few common patterns you’ll quickly get used to identifying, as well as some standard and troubleshooting signals you’ll want to be familiar with.
Note: I won’t cover all of the individual device modes here. For additional detail, our Getting Started guides for the Photon and Electron cover all of the possible device modes, including some fancy animated illustrations.
Common Patterns
What first-time startup looks like
The first time you take a Photon or Electron out of the box and power it on, you can expect to see it flash briefly white and then blink blue. The white means that the Wi-Fi or Cellular module is off and being enabled. Once that LED starts blinking blue, it means your device is in Listening mode and is ready for you to claim and name!
What a typical power-up cycle looks like
Assuming your device has already been claimed and connected to Wi-Fi or cellular, the typical power-cycle looks like this:
- Brief flash of white as the Wi-Fi or Cellular module is enabled
- Blinking green as your device looks for and connects to the internet
- Rapidly blinking cyan as the device connects to the cloud
- “Breathing cyan” (flashing slowly on and off) once connected
What a firmware update looks like
When you’re ready to load your firmware onto a Particle device, you’ll do so either via an over-the-air (OTA) update or via a Serial connection. When you flash your device via one of our IDEs or the Particle CLI, you’ll see your device flash magenta, which signals that an OTA firmware update is in progress. Once the update is complete, your device will reboot, triggering the white-blue-cyan cycle mentioned above.
It’s important to note that, depending on the size of your new firmware, included libraries and even the firmware already on the device, this magenta-white-blue-cyan cycle may repeat several times before your device returns to “breathing cyan.” Not to worry, your new firmware is nearly there!
Resetting Wi-Fi on a Photon
Sometimes, you want to reset the Wi-Fi on a Photon device to get it connected to a new access point, router or location. To do this, hold down the SETUP button on your device, for about ten seconds. After a few seconds, your device will start slowly blinking blue as it goes into listening mode, but don’t lift a finger yet! After a few more seconds, your Photon will blink blue rapidly, which means its ready to be assigned to a new network.
Once your device is back to flashing blue, you can get it on a new network by using the Particle App, or connecting it to your computer via USB and running particle setup. Don’t forget to skip the naming prompt if you want to keep the name the same!
“Shouting Rainbows” or Signal Mode
My favorite mode is Signal Mode, or something we refer to as “shouting rainbows” here at Particle. This mode can be very useful if you’re like me and you can’t remember which device is which among the many scattered about your workspace.
Signal Mode can be activated a number of ways, but the easiest is through the Particle mobile app. Simply select a device, click the ellipsis menu in the top right, and click the “Signal for 10sec button.”
Once activated for a device, signal mode will quickly rotate through a number of colors via the onboard LED.
Signaling devices is available via our Cloud API, which means you can signal via our JavaScript, iOS, Android and Windows SDKs, or via the command-line interface using the command particle nyan. In fact, if you run the command particle nyan on without specifying a device, all of your connected devices will shout rainbows at once.
And you can run the command particle nyan off once you tire of being mesmerized by all the pretty blinking lights.
Troubleshooting Modes
Sometimes, but not often, things go sideways and your devices need to let you know. Particle devices have a few additional modes that let you know when something isn’t right and you need to take action.
Wi-Fi or Cellular Module Not Connected
If you see a breathing white on your device that persists more than a few seconds, it means that the Wi-Fi or Cellular module on your device is off, either via module settings or calls to Wifi.off() or Cellular.off() in your firmware. If this is not the case and you still see that breathing white, try DFU mode or particle doctor, as detailed below.
Cloud Not Connected
If your device is breathing green, it means that you’re connected to a Wi-Fi or cellular network, but not the Particle device cloud. This could be due to your firmware blocking (commonly via calls to delay()) for more than ten seconds. If you’re in this situation, visit our docs or the forums for more info.
Safe Mode
If something is going wrong with your device, and you suspect your custom firmware may be the culprit, you can put your device in safe mode, which connects your device to the cloud, but does not run your firmware. To enter safe mode, hold down both the RESET and SETUP buttons on your device, then release the RESET button while still holding onto the SETUP button. Once the LED starts blinking magenta, you can release the SETUP button. At this point, your device will reset and enter the white-green-cyan cycle, before slowly breathing magenta.
Now, you can safely modify your firmware to fix the issue and flash it back onto the device.
DFU Mode
Sometimes, you’ll want or need to update the underlying firmware on the device, aka, the device firmware that Particle provides. To do this, you’ll need to put your device in Device Firmware Update (DFU) mode. It follows the same process as putting your device into safe mode, however, instead of releasing the SETUP button when the light blinks magenta, wait for it to flash yellow.
Once in DFU mode, you can follow our guides to load new firmware over USB.
Note: DFU mode is also really important when recovering from a bricked device, so you’ll want to keep this knowledge handy.
Anything RED is Bad
Speaking of a bricked device, if you ever see your LED blinking red for any reason, it means something is wrong. It could be that your device can’t connect to the internet, can’t reach the Particle cloud, or that your device firmware crashed. There are a variety of errors that might cause a red LED, so check out the docs if this ever happens to you.
Your first step in this case should be to put your device into Safe Mode and try reloading the firmware. You can also try flashing the default tinker app to the device to determine if the cause is in your custom firmware, or something else. Via the CLI, you can do this with the command:
particle flash <mydevice> tinker
Using “particle doctor” when all else fails
If getting your device back into safe mode doesn’t solve your problem, you can turn to particle doctor to restore your device to health. You’ll want to get your device into DFU Mode, connect it via USB and run the command particle doctor from the CLI. From there, particle doctor will guide you through clearing out and cleaning up your device so you can get it up and running, and back in the cloud.
The RGB LED on Particle boards is an invaluable feature of Particle devices, and one that I’ve come to depend on over the years as a firmware developer. Hopefully this guide has helped you learn something new about this little LED. If you have any questions, comments, or need help resolving an issue with your Particle-powered apps, visit us over on the Community Forums. We’d love to hear from you!
