Where is the real documentation?

Somehow I’m missing the real information on how to use the Particle devices. After working with a TI MSP430 environment, I can’t seem to find an equivalent for Particle devices. Are there spec sheets on the hardware, all the pins and doc on the specific STM chip used with its internal features? I see programming examples, but no mention what language it is – actually, I thought somewhere I saw “Wire” as the language, but I can’t find that reference again. Isn’t there some comprehensive description of the language and API libraries for programming the devices? How are people engineering serious projects? Could someone point me to the hardcore documentation for these devices?

I finally found some meat after drilling down into a particular device, e.g. the Electron:


And drilling further into the top menu items: Reference and Data Sheets.

I’d like to find a description of how the device, e.g. Electron, is loaded with the “firmware” whose API we call – is it library binary code that is linked and loaded whenever we flash the device, or is the firmware hard-coded in PROM, for example?

The firmware on the Photon and Electron is divided into two logical parts, the system part and the user part. Each can be uploaded to the device separately, so a small user app may only be 6K in size, for example, since all of the cloud connection code and FreeRTOS exist in the system part.

The user firmware can be written in Wiring, the language using for programming Arduino boards, but really that’s just C++ with some standard libraries and definitions layered on top. In reality, it’s all C++ underneath, and even user firmware is built on a standard gcc C++11 compiler underneath, and you can write just to that if you prefer.

There are four development environments currently: Particle Build (Web IDE), Particle Dev (Atom IDE for Windows and Mac), Particle CLI (tools and cloud compile, for Windows, Mac, and Linux), and local gcc-arm (local toolchain).

The last one is particularly complex, but as it’s just gcc and make at that point, you can customize it however you want to build anything arbitrarily complex. Also, the system firmware is also open source and you’re welcome to look inside. While not really recommended for maintainability reasons you can build your own custom version of it using gcc-arm, if you so desire.

Both the system firmware and user firmware can be updated over-to-air (cellular or Wi-Fi, depending on the device) or by USB. The data is stored in flash memory on the Photon or Electron.


Thanks, that gives me an excellent overview. My assumptions would be:

  1. The device comes with the system firmware installed and we normally leave it alone and only upload the user software repeatedly as we develop.

  2. The development platforms make it clear how to reload the system firmware and the user software separately.

By the way, are there any libraries for FTP to an FTP server? Also HTTPS requests?


There is one library called HTTPSClient-Particle on Particle Build (there you can also find the GitHub repo).
And a not very often used ParticleFtpClient lib, but searching this forum might also reveal some libraries which were just never published on Build.

The search feature in Build does help finding libraries :wink:

As we are from time to time seeing new features added in the system firmware, this can be updated frequently too.
A good to have tool is CLI (which is also featured in the docs).

And yes, the docs do actually tell how to upload new firmware to the board.

The most stable firmware module on the devices is the bootloader - that’s hardly ever updated.


You rarely have to even think about the system firmware.

On a Wi-Fi device (Photon, P1, P0) the system firmware gets automatically upgraded over the air anytime you build an application against a newer system. It looks like this:

  • you flash a new application to your Photon
  • then you see the device start up in “safe mode” with a magenta LED
  • this means your application is not running, but the device connected to the cloud using system firmware alone
  • the cloud detects the unmet dependency and does an OTA flash of the version of system firmware your app depends on
  • the device reboots successfully running your new application, and the LED breathes cyan like normal

You may see people refer to that feature as Safe Mode Healer (SMH).

On the Electron we do not automatically perform OTA updates because we want you to have full control over data usage costs. You can still, for example, use the CLI to flash system parts or your application firmware either OTA or over the wire.

Lately we have been releasing system firmware about once a month, sometimes more often. You can follow the Particle Firmware Update Thread if you want to hear about releases.

Happy building!


Thanks for all these “big picture” descriptions – really helps.