Join the chat at https://gitter.im/po-util/Lobby Build Status

Particle Offline Utility is a tool created by Nathan Robinson to facilitate local Particle development on macOS and Linux Distributions. It installs all the necessary tools for offline Particle development and provides a more streamlined interface for creating Particle firmware.

Particle Offline Utility is written as po-util, and the Particle Offline Utility command is po.

po-util makes it easy for developers to download the Particle Toolchain and install the required dependencies to quickly begin creating projects using the Particle Platform.

po-util features a responsive experience, giving developers the tools they need for seamless local development, providing understandable commands for simplifying complex tasks like properly compiling and flashing firmware.

Install

The quickest and easiest way to install po-util on Linux or macOS is to run the following:

$ bash <(curl -sL get.po-util.com)

You will be asked to answer several prompts during the installation.


Key Features

Library Manager

The library manager makes it easy to use Particle libraries when developing with po-util locally by using git to download Particle libraries hosted on GitHub and save them to a ~/.po-util/lib directory so that they make be linked inside of projects later. Read more about the Library Manager here.

Full dependency setup

po-util installs all of the dependencies required for local Particle Development, including the ARM toolchain, dfu-util, nodejs, particle-cli and the Particle firmware.

Local compilation and support for flashing over USB or OTA

Building firmware locally for Electrons, Photons and P1s, and automatically flashing over USB using dfu-util or Over The Air using particle-cli. Sequentially flashing multiple devices at once over the air is also supported.

Shortcuts for Building in Atom

po-util supports shortcuts for Atom, the popular open- source IDE by GitHub. The shourcuts provide quick access to commonly used commands for po, including: building firmware, flashing firmware over USB, and flashing firmware Over The Air. Read more about the shortcuts here.

Project Structure

The directory structure of a full po-util project is arranged like so:

firmware/
├ main.cpp
└ lib1/
  ├ lib1.cpp
  ├ lib1.h
  └ ...
bin/
├ firmware.bin
└ ...
 ci/
 devices.txt
 libs.txt
 .atom-build.yml
 .travis.yml
 .gitignore
 .git/
 README.md

Project setup

When using po, your code is arranged into projects with the structure described above. This not only lets you easily work on many projects on one computer, but it provides a standardized way of building locally.

Creating a project with po is simple when you use po init to initialize a project by creating the necessary files. Below is an example:

$ po DEVICE_TYPE init someProject

You can set DEVICE_TYPE to either photon, P1, electron, core, pi, or duo. This is necessary for generating the Atom shortcuts file appropriately.

More Information

Here is some more information about using po.

Writing Firmware

po compiles any .cpp and .h files found in the firmware/ directory, but not .ino files, so #include "Particle.h" must be present in your main.cpp file. This is done for you when you run the po init command to create a project directory.

Building Firmware

To compile firmware, simply run po DEVICE_TYPE build, substituting DEVICE_TYPE for photon, P1, or electron. To compile and flash firmware to your device using dfu-util, simply run po DEVICE_TYPE flash. To clean the project, run po DEVICE_TYPE clean.

DFU Commands

To upload precompiled code over USB, run po DEVICE_TYPE dfu. To put your device into dfu mode, run po dfu-open. To get your device out of dfu mode, run po dfu-close.

Over The Air (OTA) Uploading

To upload precompiled code over the air using particle-cli, run po DEVICE_TYPE ota DEVICE_NAME, where DEVICE_NAME is the name of your device in the Particle cloud. You must be logged into particle-cli to use this feature. You can log into particle-cli with particle cloud login.

You can also flash code to multiple devices at once by passing the -m or --multi argument to ota. This would look like po DEVICE_TYPE ota -m. This relies on a file called devices.txt that you must create in your po project directory.

Testimonials

"I think you identified a common pain point for a lot of users, and the automated installation of the Particle toolchain is a problem that we've been focused on a lot recently ... you should already feel proud of yourself because you have made a meaningful contribution to the community. We are all very thankful for it - our community regularly impresses us, and you are certainly not an exception."

Will Hart, Particle General Manager


"I found that po-util works wonders by condensing the many disparate steps required to automate command-line interactions with Particle products into simple, clear commands. No need to futz with the weird serial stuff on Linux, and nicely full featured. So much better than pressing the buttons, even if you aren’t automating anything else. Highly recommend!"

Justice Reed, Head of Hardware, Amper Technologies


"It has been nearly flawless and a HUGE productivity booster... I cannot believe your steps worked installing so many utils and dependencies perfectly... The Particle world owes you a big debt. If there were Emmy awards for Particle contribs, you would get one."

Andrew Ward, Particle Community Member


"Nice! This is great stuff. Definitely helpful for the local dev / offline use case. Thanks for sharing."

Avidan Ross, Particle Investor


"Thanks a lot for this amazing tool. I finally managed to get everything as I wanted: to be able to work off-line."

Yannick, Particle Community Member


"Po-util is a very handy script - thanks for sharing."

H.S, Particle Community Member


"I can't heart this enough!"

Josh Fisher, Particle Community Member