Use po-util to build firmware for Particle Devices

In this guide I will show you how to use po-util to install and use the Particle toolchain locally on Linux and MacOS.

What is po-util?

Po-util is a terminal application (script) that I created to help users build Particle firmware. It takes care of installing the required tools, and lets you focus on building your Particle projects on your own computer without having to worry about the cloud. Also, po-util makes USB flashing much simpler, allowing you to upload your firmware faster, and save bandwidth if you are using an Electron.

How do I install it?

Po-util needs to be downloaded and you need to run the installation command in order for you can start building your projects.

The easiest way to install po-util is directly from terminal. Open a terminal and type:

curl -fsSLO https://raw.githubusercontent.com/nrobinson2000/po-util/master/po-util.sh
./po-util.sh install

Po-util will then go through the installation process, downloading necessary tools and installing dependencies.

Using po-util:

Once po-util is installed, you will have access to the po command. The po command allows you to use po-util to build your projects. Po-util always builds any code in the firmware directory, unless specified otherwise. Your code must be written with a .cpp extension, not .ino, and must be placed in the firmware directory.

Po-util features a command that will automatically create the correct structure for a project. The command is

po init

Let's say that I want to create a project called weather-system. I would run these commands to create it:

mkdir weather-system
cd weather-system
po init

These files would be created inside of weather-system:

firmware/
└ main.cpp
└ README.md

The main.cpp is the file for the majority of your code. It is created with just the boilerplate code:

#include "application.h"
void setup() // Put setup code here to run once
{
}
void loop() // Put code here to loop forever
{
}

To build your project, you would just run

po DEVICE build

replacing DEVICEwith either photon, electron or P1.

To build your project and flash it to your device over USB using dfu-util, run

po DEVICE flash

To upload a pre-compiled binary to your device, run

po DEVICE dfu

There are many more commands for po-util. To see the full list of commands with explanations, run

po 

Configuring po-util:

There are two parts of po-util that can be changed, and to open the configuration menu, you must run

po config

You can select which version (branch) of the Particle Firmware that you want to use, and which baud rate you want to use for putting devices into DFU mode for uploading firmware. You can either use the default baud rate of 14400 which is what all Particle devices are set to use, or you can change the baud rate to the po-util recommended baud rate of 19200, which works better if you are using Linux. If you select the recommended baud rate, you must update the system firmware of each device you are using in order for the device(s) to accept it.

Upgrading System Firmware:

One of the features of po-util is that it makes it possible you compile and flash new system firmware for your devices. This is necessary for updating your devices to the latest Particle Firmware, and to make them use your preferred baud rate. To upgrade the system of a device, you must manually put your device into DFU mode:

and then run:

po DEVICE upgrade

Updating po-util

To download the latest Particle Firmware source code, update dependencies and po-util, you must run:

po update 

Full command list:

                                                  __      __  __ 
                                                 / |     /  |/  |
         ______     ______           __    __   _██ |_   ██/ ██ |
        /      \   /      \  ______ /  |  /  | / ██  |   /  |██ |
       /██████ |  /██████  |/      |██ |  ██ | ██████/   ██ |██ |
       ██   | ██ |██ |  ██ |██████/ ██ |  ██ |   ██ | __ ██ |██ |
       ██  |__██ |██ \__██ |        ██ \__██ |   ██ |/  |██ |██ |
       ██     ██/ ██    ██/         ██    ██/    ██  ██/ ██ |██ |
       ███████/    ██████/           ██████/      ████/  ██/ ██/
       ██ |
       ██ |
       ██/                                  https://po-util.com
Copyright (GPL) 2016 Nathan Robinson
Usage: po DEVICE_TYPE COMMAND DEVICE_NAME
      po DFU_COMMAND
      po install [full_install_path]
Commands:
 install    Download all of the tools needed for development.
            Requires sudo. You can also re-install with this command.
            You can optionally install to an alternate location by
            specifying [full_install_path].
            Example:
                    po install ~/particle
            By default, Firmware is installed in ~/github.
 build      Compile code in "firmware" subdirectory
 flash      Compile code and flash to device using dfu-util
            NOTE: You can supply another argument to "build" and "flash"
            to specify which firmware directory to compile.
            Example:
                    po photon flash photon-firmware/
 clean      Refresh all code (Run after switching device or directory)
 init       Initialize a new po-util project
 update     Update Particle firmware, particle-cli and po-util
 upgrade    Upgrade system firmware on device
 ota        Upload code Over The Air using particle-cli
            NOTE: You can flash code to multiple devices at once by passing
            the -m or --multi argument to "ota".
            Example:
                    po photon ota -m product-firmware/
            NOTE: This is different from the product firmware update feature
            in the Particle Console because it updates the firmware of
            devices one at a time and only if the devices are online when
            the command is run.
 serial     Monitor a device's serial output (Close with CRTL-A +D)
 config     Select Particle firmware branch and DFU trigger baud rate
DFU Commands:
 dfu        Quickly flash pre-compiled code to your device.
            Example:
                    po photon dfu
 dfu-open   Put device into DFU mode
 dfu-close  Get device out of DFU mode

More information:

To find out more about po-util, check out https://po-util.com/ or read the thread on the Particle Forums https://community.particle.io/t/po-util-a-toolchain-installer-helper-for-linux-and-osx/21015