Particle Offline Utility: The Ultimate Local Particle Experience for Linux and macOS: by Nathan Robinson
What is po-util?
Po-util, short for Particle Offline Utility, is a tool I created for facilitating a truly offline Particle development environment. Po-util helps you install the same tools that Particle uses in the cloud to build device firmware locally on your computer and provides simple commands to help you use these tools.
Po-util is unique from development environments like the Web IDE, Particle Dev, and particle-cli that Particle provides because it is independent of the Particle cloud and it can build your firmware offline. Po-util makes extensive use of DFU Utilities to transfer firmware to a device over USB rather than upload firmware wirelessly Over The Air, which uses bandwidth and can be less reliable than a direct connection.
Po-util is my personal solution to local Particle development and I use it exclusively when developing on Particle devices. I hope that you will find it beneficial to your Particle workflow.
Features of po-util
Po-util has many features, and is a unique workflow I meticulously developed so that others can experience local Particle development the way it was meant to be.
Po-util offers many features, including:
Full installation of required dependencies like the ARM toolchain, DFU Utilities, and the Particle Firmware.
Support for building firmware for the Particle Photon, P1, Electron, E-Series, Core, Raspberry Pi, and Redbear Duo.
Instant firmware uploading over USB using DFU Utilities.
Sequential Over The Air firmware uploading to multiple devices.
A unified project structure that is cross-compatible between Linux and macOS.
An efficient library manager that works with libraries from Particle Libraries 2.0 and GitHub.
A range of keyboard shortcuts to expedite development within Atom.
Bash Tab completion to improve the command-line experience.
Getting started with po-util
Run the following in your Terminal to install po-util:
You will be prompted with the following. Press ENTER to confirm.
You will asked to configure po-util during the installation process. I suggest that you respond with
yes when prompted.
Creating a project with po-util
To use po-util, you must work in an initialized project directory. (More on project structure below.)
To create a project simply run the following in your Terminal:
This command creates the
newProject folder and creates the appropriate folders and files inside. The Atom shortcuts file is set to build firmware for the Particle Photon. (You can substitute
duo to initialize the project for other devices.)
To make use of the shortcuts you will need the Atom Build package. You can easily the package and a couple other recommended ones with:
Po-util project structure
Po-util operates by keeping your code separated into projects that follow an organized structure:
All source code goes in
firmware/, and the compiled binary is saved as
bin/firmware.bin. You can specify devices to flash sequentially to in
libs.txt is how po-util keeps track of what libraries to use in the project.
Po-util supports build shortcuts for Atom, and these are set in
.atom-build.yml should you need to modify it on a per-project basis.
Using po-util with Atom
Now that you have created a project and installed the recommended packages, open the project folder in Atom.
On the left, you should find your
firmware/main.cpp file. This is where you should keep most of your code. (You can use separate files and libraries however, but the majority of your code should be kept here.)
When your project is initialized, you will find the following dummy code in your
Here is where you can observe one of the most useful features of po-util, the keyboard shortcuts for Atom. If you press
Ctrl + Alt + 1, Atom will build the project by running:
Ctrl + Alt + 2 builds the firmware and flashes it to your device over USB using DFU Utilities by running the following, which can also be done from your Terminal:
If you prototype rapidly like I do, flashing will become a frequently used shortcut.
Ctrl + Alt + 3 cleans the firmware and removes the
bin/ directory by running:
Ctrl + Alt + 4 uploads firmware to your device without rebuilding by running:
Ctrl + Alt + 5 uploads your firmware Over The Air to any devices listed in your
devices.txt by running:
Using Particle libraries with po-util
One of the greatest features of po-util is its flexible library manager. The library manager not only allows using libraries from Particle’s list of libraries, but it also supports using any library that is available from GitHub.
A library can be downloaded and added to a project by using the
$ po lib get and
$ po lib add commands. For example, you could add the
neopixel library to a project with the following commands:
You could go even further and load an example from the
First, check what examples are available with:
The command above returns the following, indicating there are examples available:
To load the
extra-examples example into your project run:
Sharing a po-util project
The most practical way to share a po-util project is to upload it to GitHub, as your project is initialized as a git repository and set up to use Travis CI for testing.
Po-util provides another method if you want a “quick and dirty” way to share your code so that it can be built without using po-util. Using
$ po lib pack, you can create a copy of your
firmware/ directory with all symbolic links and libraries packaged inside. A .zip archive is created as well.
When using publicly accessible libraries it is advised that you clean the binaries and libraries from your project. This removes the symbolic links from your
firmware directory, but leaves the libraries your project depends on in your
To clean your project run the following:
At any time, you can re-download and add the libraries using:
If you are sharing using GitHub and Travis CI, cleaning is not necessary, as Travis CI will do it for you when building your project.
More po-util information
Stars, Feedback, Contributions and Donations are greatly appreciated. I hope you enjoy using po-util as much as I have enjoyed creating it.