Particle CLI

The Particle CLI is a powerful tool for interacting with your devices and the Particle Cloud. The CLI uses node.js and can easily run on Windows, Mac OS X, and Linux. It's also open source so you can edit and change it, and even send in your changes as pull requests if you want to share!

Installing

If you are using Windows, you can use the official Particle Windows CLI Installer to automatically install node.js, the particle-cli, and dfu-util.

Otherwise, make sure you have node.js installed.

Next, open a command prompt or terminal, and install by typing:

# how to install the particle-cli
$ npm install -g particle-cli
$ particle login

If you experience permission errors, you have two options: change the permission to npm's default directory or change npm's default directory to another directory (preferred choice on a multiuser environment). Both options are documented here.

For more OS-specific install instructions, see below.

Advanced Install

To use the local flash and key features you'll also need to install dfu-util, and openssl. They are freely available and open-source, and there are installers and binaries for most major platforms.

Here are some great tutorials on the community for full installs:

Install Separate Components for Windows

Installing on Ubuntu 12.04

Installing on Ubuntu 14.04

Installing on Mac

Upgrading to the latest version

To upgrade Particle-CLI, enter the following command:

# how to update the particle-cli
$ npm update -g particle-cli

Running from source (advanced)

To grab the CLI source and play with it locally

# how to get the source code for the CLI
$ git clone https://github.com/spark/particle-cli.git
$ cd particle-cli
$ npm install
$ node bin/particle help

Getting Started

These next two commands are all you need to get started setting up an account, claiming a device, and discovering new features.

particle setup

This command will guide you through logging in or creating a new account as well as claiming your device!

# how to setup your account and your device
$ particle setup

particle help

Shows you what commands are available and how to use them. You can also give the name of a command for detailed help.

# how to get help
$ particle help
$ particle help keys

Flashing over Serial for the Electron

If you're wanting to save data on your Electron you should definitely consider flashing your Electron over serial instead of OTA (over-the-air).

Assuming you've compiled and downloaded the firmware binary from Build IDE by clicking the cloud button next to the file name, you should be able to use the Particle CLI, mentioned above, to flash your application firmware to your Electron without using data.

Steps:

  • 1: Put the Electron in to listening mode
  • 2: Open Particle CLI from your machine (make sure you've installed it first)
  • 3: Navigate to the folder where you've downloaded the firmware.bin file.
  • 4: From the CLI issue particle flash --serial firmware.bin
# How to flash an Electron over serial
$ particle flash --serial firmware.bin

! PROTIP: Hold the SETUP button on your device until it blinks blue!
? Press ENTER when your device is blinking BLUE
sending file: firmware.bin

Flash success!

Note: If your Electron goes into safe mode, this is okay, just make sure that the system firmware you on the device matches the dependency of the system firmware built into the firmware application.

If you're just opening a new device, chances are it's already loaded with Tinker, the app we load at the factory. If you don't have Tinker, or if you've been using the build IDE already, let's load it quickly by typing:

# How to re-load tinker onto a device
$ particle flash my_new_device_name tinker
Including:
/usr/local/lib/node_modules/particle-cli/binaries/particle_tinker.bin
attempting to flash firmware to your device my_new_device_name
flash device said  {"id":"0123456789ABCDEFGHI","status":"Update started"}

Let's make sure your device is online and loaded with Tinker. We should see the four characteristic functions exposed by Tinker, "digitalWrite", "digitalRead", "analogWrite", and "analogRead".

# how to show all your devices and their functions and variables
$ particle list

Checking with the cloud...
Retrieving devices... (this might take a few seconds)
my_device_name (0123456789ABCDEFGHI) 0 variables, and 4 functions
  Functions:
    int digitalread(String args)
    int digitalwrite(String args)
    int analogread(String args)
    int analogwrite(String args)

Let's try turning on the LED attached to pin D7 on your device.

# how to call a function on your device
$ particle call my_device_name digitalwrite D7,HIGH
1
$ particle call my_device_name digitalwrite D7,LOW
1

Nice! You should have seen the small blue LED turn on, and then off.

Update your device remotely

You can write whole apps and flash them remotely from the command line just as you would from the build IDE. Let's write a small blink sketch to try it out.

Copy and paste the following program into a file called blinky.ino

// Copy me to blinky.ino
#define PIN D7
int state = 0;

void setup() {
    //tell the device we want to write to this pin
    pinMode(PIN, OUTPUT);
}
void loop() {
    //alternate the PIN between high and low
    digitalWrite(PIN, (state) ? HIGH : LOW);

    //invert the state
    state = !state;

    //wait half a second
    delay(500);
}

Then let's compile that program to make sure it's valid code. The CLI will automatically download the compiled binary of your program if everything went well.

# how to compile a program without flashing to your device
$ particle compile photon blinky.ino
Including:
blinky.ino
attempting to compile firmware
pushing file: blinky.ino
grabbing binary from: https://api.particle.io/v1/binaries/01234567890ABCDEFGH
saved firmware to firmware_123456781234.bin
Compiled firmware downloaded.

Now that we have a valid program, let's flash it to our device! We can use either the source code again, or we can send our binary.

# how to flash a program to your device (from source code)
$ particle flash my_device_name blinky.ino

# OR - how to flash a pre-compiled binary to your device
$ particle flash my_device_name firmware_123456781234.bin
Including:
firmware_123456781234.bin
attempting to flash firmware to your device my_device_name
flash device said  {"id":"01234567890ABCDEFGH","status":"Update started"}

Compile and flash code locally

You can find a step-by-step guide to installing the local build toolchain for the firmware in the FAQ section of the documentation.

After building your code on your machine, you can flash it to your device over Serial or remotely.

Working with projects and libraries

When your code gets too long for one file or you want to use libraries that other developers have contributed to the Particle platform it's time to create a project.

Creating a project

By default projects are created in your home directory under Particle or in your Documents folder under Particle on Windows. You can also create projects in the current directory.

$ particle project create
What would you like to call your project? [myproject]: doorbell
Would you like to create your project in the default project directory? [Y/n]:
Initializing project in directory /home/user/Particle/projects/doorbell...
> A new project has been initialized in directory /home/user/Particle/projects/doorbell

Using libraries

The CLI supports using libraries with your project. This allows you to incorporate already written and tested code into your project, speeding up development and assuring quality.

The overall flow when consuming a library goes like this

  • set up the initial project for your application
  • find the library you want to add particle library search
  • add the library to your project - particle library add
  • edit your source code to use the library
  • compile your project - particle compile

These commands are described in more details in the CLI reference.

The library search command allows you to search for libraries that are related to the text that you type in.

For example,

particle library search neo

Will find libraries containing neo in their name.

library add

The library add command adds the latest version of a library to your project.

For example, if you wanted to add the InternetButton library to your project, you would type

$ particle library add internetbutton
> Library InternetButton 0.1.10 has been added to the project.
> To get started using this library, run particle library view InternetButton to view the library documentation and sources.

This will add the InternetButton dependency to your project's project.properties file.

The InternetButton library itself is not present in your project, so you won't see the InternetButton sources. The library is added to your project when the project is compiled in the cloud.

To make the library functionality available to your application, you add an include statement to your application source code. The include statement names the library header file, which is the library name with a .h ending.

For example, if we were using the library "UberSensor", it would be included like this

#include "UberSensor.h"

library view

The library view downloads the source code of a library so you can view the code, example and README.

$ particle library view internetbutton
Checking library internetbutton...
Library InternetButton 0.1.11 installed.
Checking library neopixel...
Checking library particle_ADXL362...
Library particle_ADXL362 0.0.1 installed.
Library neopixel 0.0.10 installed.
To view the library documentation and sources directly, please change to the directory /home/monkbroc/Particle/community/libraries/InternetButton@0.1.11

Change to the directory indicated to view the sources.

library copy

Adding a library to your project does not add the library sources. For times when you want to modify the library sources, you can have them added locally.

particle library copy neopixel

The library will be copied to the lib folder of your project. If you already have the library in your project.properties make sure to remove it so the cloud compiler doesn't overwrite your changed copy with the published code.

Incorporating the library into your project

Once the library is added, it is available for use within your project. The first step to using the library is to include the library header, which follows the name of the library. For example:

#include "neopixel.h"

The functions and classes from that library are then available for use in your application. Check out the library examples and documentation that comes with the library for specifics on using that library.

Contributing Libraries

Contributing a library is the process where you author a library and share this with the community.

The steps to creating a library are as follows:

  • optionally, create a project for consuming the library
  • scaffold a new library structure - library create
  • author the library, tests and examples
  • publish the library

Create a project for consuming the library

While it's not strictly necessary to have a project present when authoring a new library, having one can help ensure that the library works as intended before publishing it. The project allows you to consume the library, check that it compiles and verify it behaves as expected on the target platforms before publishing.

For the library consumer project that will consume the library mylib, create an initial project structure that looks like this:

src/project.cpp
src/project.h
project.properties
lib/mylib

The library will exist in the directory lib/mylib.

All these files are initially empty - we'll add content to them as the library is authored.

Scaffolding the library

The library create command is used to scaffold the library. It creates a skeleton structure for the library, containing initial sources, examples, tests and documentation.

In our example project structure we want to create a new library in lib/mylib so we will run these commands:

cd lib/mylib
particle library create

The command will prompt you to enter the name of the library - mylib, the version - 0.0.1 and the author, your name/handle/ident.

The command will then create the skeleton structure for the library.

Authoring the library

You are then free to edit the .cpp and .h files in the lib/mylib/src folder to provide the functionality of your library.

It's a good idea to test often, by writing code in the consuming project that uses each piece of functionality in the library as it's written.

Consuming the library

To test your changes in the library, compile the project using particle compile <platform>

particle compile photon

This will create a .bin file which you then flash to your device.

particle flash mydevice firmware.bin

(Replace the name firmware.bin with the name of the .bin file produced by the compile step.)

Contributing the library

Once you have tested the library and you are ready to upload the library to the cloud, you run the library contribute command. You run this command from the directory containing the library

cd lib/mylib
particle library contribute

Before the library is contributed, it is first validated. If validation succeeds, the library is contributed and is then available for use in your other projects. The library is not available to anyone else.

Publishing the Library

If you wish to make a contributed library available to everyone, it first needs to be published.

When publishing a library, it's important to ensure the version number hasn't been published before - if the version has already been published, the library will not be published and an error message will be displayed.

Incrementing the version number with each publish is a recommended approach to ensuring unique versions.

Once the library is published, it is visible to everyone and available for use. Once the a given version of a library has been published, the files and data cannot be changed. Subsequent changes must be via a new contributed version and subsequent publish.

Reference

For more info on CLI commands, go here.

Also, check out and join our community forums for advanced help, tutorials, and troubleshooting.

Go to Community Forums >