15 May 2017 by Phillip Johnston • Last updated 15 December 2021

One of my clients uses the Particle Electron in their product. Particle is an IoT platform provider, and Electron is a development platform that connects to the Particle cloud using a 2G/3G cellular connection.

Particle provides a web IDE for developers, but I decided to get myself setup to compile Particle firmware on the host machine. This guide will walk you through the setup of a host-based Particle development environment.

Cheat Sheet

Particle’s documentation is thorough, but I found myself keeping a set of notes to work with their systems and figured it was worth sharing.

Make sure to compile in main/ – most of the particle instructions
make clean to clean projects
make all PLATFORM=electron to build
make program-dfu PLATFORM=electron to flash your recent build (in DFU mode)
particle flash --usb <binary.bin> to flash a specific build (in DFU mode)
particle update to update your device’s system firmware (in DFU mode)
npm update -g particle-cli to upgrade particle-cli
DFU mode entry:
1. Hold down BOTH buttons (RESET + MODE)
2. Release only the RESET button (continue to hold MODE)
3. Wait for the LED to start flashing yellow (it will flash magenta first, which indicates safe mode)
4. Release the MODE button
Safe mode entry:
1. Hold down BOTH buttons (RESET + MODE)
2. Release only the RESET button (continue to hold MODE)
3. Wait for the LED to start flashing magenta
4. Release the MODE button (before it flashes yellow!)

Setup

The Particle Electron Getting Started Guide is a very thorough resource for getting up to speed. I have simplified their notes into a few useful steps.

If you need more information or run into problems, please refer to the Getting Started Guide for help.

Particle CLI

For full CLI installation steps please refer to Particle’s console guide. I’m providing a quick summary here for more advanced users.

These are the dependencies:

npm (to install particle-cli)
dfu-util (to flash Particle boards)
particle-cli (to perform various Particle activities)

I installed npm and dfu-util through homebrew. Once npm is installed, you can run the following commands to set up particle-cli:

npm install -g particle-cli
particle login
particle setup

You can also setup your device using the online Device Setup tool rather than using particle setup.

Interacting with the Particle Electron

Before we dive into building the Particle firmware, I want to share a few brief notes about interacting with the Electron.

Particle Console

The Particle Console is a very useful resource for developing and testing devices. When devices come online, go offline, or publish messages, you will see them listed in the Particle console log. If your device provides functions, you can also call those from the Particle console.

You can find the Particle Console at console.particle.io.

DFU Mode

In order to flash your firmware from your host, you will need to put your device in DFU mode. Getting the device into this mode is simple:

Hold down BOTH buttons (RESET + MODE)
Release only the RESET button (continue to hold MODE)
Wait for the LED to start flashing yellow (it will flash magenta first, which indicates safe mode)
Release the MODE button, and now you’re in DFU

Updating System Firmware

In order to upgrade the system firmware on your device, perform the following:

Put the device into DFU mode
Run particle update

The system firmware is contained in the particle-cli release, so if a new system firmware is released you will need to update your CLI.

Flashing Firmware Images

To flash a firmware image, you can use the following methods:

particle flash --usb <binary.bin> to flash a specific build (in DFU mode)
- Will take any .bin file and flash it
make program-dfu PLATFORM=electron to flash your recent build (in DFU mode)
- Will take the locally built user-part.bin file and flash it to the device
- This is the workflow we will use in our host development process

Safe mode

I just want to mention Safe Mode, as I ran into some issues on this front. If you see that your device’s LED is in a magenta state, it is in safe mode. You can also see it checkin on the Particle Console as a device in /spark/safe-mode. This usually indicates that your app did not run, likely due to a firmware version mismatch or data corruption.

If your device is in safe mode, the first thing to check that the SDK firmware version you are compiling with matches the system firmware on your device.

Safe mode is a useful recovery mechanism in the field. If your device becomes corrupted or hangs, you can manually put it into safe mode. Once in safe mode, it can register to the Particle cloud and receive an OTA update.

Manually entering safe mode is similar to entering DFU mode:

Hold down BOTH buttons (RESET + MODE)
Release only the RESET button (continue to hold MODE)
Wait for the LED to start flashing magenta
Release the MODE button (before it flashes yellow!)

Building Particle Firmware on Your Host

I really hate web development environments. The tools and workflows I like are unavailable, and I am not able to put my code under source control.

Luckily Particle provides their firmware in a Github repository that we can use for host development.

Toolchain

You will need the gcc ARM cross-compiler (gnu-arm-none-eabi) to compile for the Electron.

At the time of this publication, the latest GNU tooltain (6-2017-q1-update) fails to compile. I have decided to use the 4.9-2015-q3 toolchain, which works well. There’s likely a version in between 4.9 and 6 that will work, but I did not have the patience to search.

Once you have downloaded the ARM toolchain, unpack it and add the toolchain’s bin/ folder to your PATH. For example, this is in my .bashrc file:

export PATH="$PATH:$HOME/toolchain/gcc-arm-none-eabi-4.9/bin/"

Getting Firmware Source

You can find the Particle firmware in a Github repository. Checkout or fork the firmare repository. If you don’t want to fork the repository, you will also need a second Github repo which you will use for tracking your firmware.

Once you have checked out the repo, you will be on the development branch. It is very important to check out a stable branch which matches the system firmware you want to use for your devices. If your system firmware does not match the SDK version you are compiling for, your device will end up in safe mode rather than running your user code.

I recommend updating your particle-cli installation to make sure you have the latest version. Using particle update, you can upgrade your device to the latest system firmware.

Not sure what system firmware is on your device? You can check build.particle.io and go to the “devices” tab on the left hand side. If you select the device you’re interested in, you can see note detailing the current firmware version.

Once you know the version you need, checkout the corresponding tag in the firmware repository (0.6.2 at the time of this writing). This will be the baseline for our firmware setup. If you update the system firmware, you will need to pull in the corresponding firmware tag from the Particle firmware repository.

Setting Up Your Project

Once you have selected the proper firmware version we are ready to setup our repository.

If you did not fork the repository, you will need to copy the Particle repository contents to your project repo.

Your project code should go itno the user/ directory. The main source files are stored in user/src. Inside this folder you should find an application.cpp file which matches the “Tinker” demo application. This is the starting point for creating your own Particle project.

Your project needs a setup() and loop() function, but the remaining functions can be stripped out.

When you add source files to the user/src folder they will be automatically picked up – no need to much around with any Makefiles!

Building Firmware

Building firmware is pretty simple. You just need to run:

make all PLATFORM=electron

This command will work from either the root directory or the main/ folder. However, all of the Particle instructions assume that you are compiling inside main/, so I recommend this workflow. You will also find that useful things like make program-dfu fail unless you are compiling from main/.

The build results are output in build/target/user-port/<platform>/. The user-part.bin file is the firmware image that you will want to flash to your device.

Flashing Firmware

Once you’ve successfully compiled your project, you can issue this command to flash your build to a device in DFU mode:

# Assumes you are inside main/
make program-dfu PLATFORM=electron

Otherwise you can run:

particle flash --usb /path/to/user-part.bin

After flashing is complete, your device will reboot and run your new firmware! If there was a problem, you will see the LED turn magenta to indicate it booted into safe mode.

That’s all there is to it! You are now able to start working on your project from the comfort of your host OS. Happy hacking!

Getting Started: Developing for Particle Electron on Your Host