Install po-util

On macOS, po-util is installed by running the installer script. Run the following commands to install po-util:

The most secure way to install po-util is to download po-util.sh directly and run it:

$ curl -fsSLO https://raw.githubusercontent.com/nrobinson2000/po-util/master/po-util.sh
$ chmod +x po-util.sh ; ./po-util.sh install

The quickest and easiest way to install po-util is to run this command:

$ bash <( curl -sL https://raw.githubusercontent.com/nrobinson2000/po-util/master/po-util.sh ) install

You can also install po-util by cloning the GitHub repository:

$ git clone https://github.com/nrobinson2000/po-util
$ cd po-util
$ ./po-util.sh install

Setup po-util

When po first runs, you will be prompted with three questions.

These questions allow po to create your ~/.po config file.

• The first question asks what branch (version) of the Particle Firmware you want to use.

• The second question asks what baud rate you want to use to put your devices into DFU mode with. This allows you to automatic building and flashing over USB using dfu-util when doing $ po DEVICE_TYPE flash. Choose default to use the official default baud rate of 14440, or choose po to use the recommended baud rate of 19200. This baud rate is reccomneded because 14400 is not a valid baud rate on Linux.

• The third question asks if you want headers (#include "Library.h") to be automatically added to a project's main.cpp whenever a library is added.

Po-util will then continue to install its dependencies...

Update device firmware

Once po-util is installed, you must update the system firmware on your Photon / P1 / Electron so it will use the version of the firmware you specified and use DFU baud rate you chose. Follow the instructions below:

Run:

$ po DEVICE_TYPE upgrade

Replace DEVICE_TYPE with photon, P1, or electron.

Put your device into DFU mode:

• Press and hold the SETUP and RESET buttons.
• Release your finger from RESET.
• Keep your finger on SETUP and release it when your device is flashing yellow.

Press ENTER

Your computer will then build the system firmware parts and flash them to your device. This may take a couple minutes depending on your computer.

When your device is no longer flashing yellow, the firmware has finished upgrading.

Setting up a po-util project folder

Po-util works by keeping your projects in separate project folders on your computer. These project folders have a standard structure that allows po-util to operate properly in the project. Below are the commands to create a project folder:

$ mkdir particleProject
$ cd particleProject
$ po init DEVICE_TYPE

Here is what the structure of a full project folder looks like:

po-util_project/
  ├ firmware/
  | ├ main.cpp
  | ├ lib1.cpp
  | ├ lib1.h
  | └ ...
  ├ bin/
  | ├ firmware.bin
  | └ ...
  ├ devices.txt
  ├ libs.txt
  ├ .atom-build.yml
  └ README.md

All source code is kept in firmware/, primarily in main.cpp.

Building and flashing firmware

Now that you have a project folder, it is easy to build the firmware locally and flash the compile binary to your device over USB using dfu-util, or Over The Air using particle-cli.

To build your project, run:

$ po DEVICE_TYPE build

The firmware/ directory is compiled for the specified device and saved as a binary as bin/firmware.bin.

To upload the binary to your device over USB run:

$ po DEVICE_TYPE dfu

You can also use:

$ po DEVICE_TYPE flash

Which will build your firmware and then flash automatically over USB.

You can also upload firmware to your device Over The Air using particle-cli:

$ po DEVICE_TYPE ota DEVICE_NAME

When using po-util, you can sequentially flash to multiple devices Over The Air by providing the -m flag after ota instead of a device name. You need to create a file called devices.txt with the name of each device on each line.

More info

Po-util has its own man page. Run man po to read it. If you are still having trouble using po-util, contact me on the Particle Forums or create an issue on GitHub.