CLI command reference
Installing
Using Mac OS or Linux
The easiest way to install the CLI is to open a Terminal and type:
bash <( curl -sL https://particle.io/install-cli )
This command downloads the particle
command to your home directory at ~/bin
, installs a version of Node.js to ~/.particle
and installs the particle-cli
Node.js module that contain the code of the CLI.
It will also try to install DFU-util, a utility program for programming devices over USB. See the instructions for installing DFU-util if the installer is not able to automatically install dfu-util.
Using Windows
Download the Windows CLI Installer and run it to install the Particle CLI, the device drivers and DFU-util.
The CLI is installed to %LOCALAPPDATA%\particle
(C:\Users\username\AppData\Local\particle
for Windows in English).
For other ways to install the Particle CLI, see the CLI guide.
particle login
Login and save an access token for interacting with your account on the Particle Device Cloud.
# how to login - creates and saves an access token for your session with the CLI
$ particle login
particle logout
Logout and optionally revoke the access token for your CLI session.
# how to remove your saved access token, and optionally revoke that token as well
$ particle logout
particle list
Generates a list of what devices you own, and displays information about their status, including what variables and functions are available
# how to show what devices of yours are online
# and what functions and variables are available
$ particle list
Checking with the cloud...
Retrieving devices... (this might take a few seconds)
my_device_name (0123456789abcdef78901234) 0 variables, and 4 functions
Functions:
int digitalWrite(string)
int digitalRead(string)
int analogWrite(string)
int analogRead(string)
particle call
Calls a function on one of your devices, use particle list
to see which devices are online, and what functions are available.
# how to call a function on your device
$ particle call 0123456789abcdef78901234 digitalWrite "D7,HIGH"
1
To call a function on a product device, set the --product
flag to your product's id.
# call the `brew` function on the device with id `0123456789abcdef01234567` within product `12345`
$ particle call 0123456789abcdef01234567 brew --product 12345
particle get
Retrieves a variable value from one of your devices, use particle list
to see which devices are online, and what variables are available.
# how to get a variable value from a device
$ particle get 0123456789abcdef78901234 temperature
72.1
To get a variable from a product device, set the --product
flag to your product's id.
# read the `temperature` variable from the device with id `0123456789abcdef01234567` within product `12345`
$ particle get 0123456789abcdef01234567 temperature --product 12345
particle device
particle device add
Adds a new device to your account.
Your device will need to be connected to the Internet (onboard LED breathing cyan) for this process to work.
# how to add a new device to your account
$ particle device add 0123456789abcdef78901234
Claiming device 0123456789abcdef78901234
Successfully claimed device 0123456789abcdef78901234
particle device rename
Assigns a new name to a device you've claimed
# how to change the name of your device
$ particle device rename 0123456789abcdef78901234 "pirate frosting"
particle device remove
Removes a device from your account so someone else can claim it.
# how to remove a device from your account
$ particle device remove 0123456789abcdef78901234
Are you sure? Please Type yes to continue: yes
releasing device 0123456789abcdef78901234
server said { ok: true }
Okay!
Unclaiming a cellular device removes it from your account, but does not stop billing. As the claiming status and SIM are separate, you must also pause or release ownership of your SIM to stop billing. If you plan on selling or giving away your device, you should both unclaim the device and release ownership of the SIM. That will allow it to be set up as if a new device later.
particle flash
Sends a firmware binary, a source file, or a directory of source files, or a known app to your device.
Flashing a directory
You can setup a directory of source files and libraries for your project, and the CLI will use those when compiling remotely.
# how to compile and flash a directory of source code to your device
$ particle flash 0123456789abcdef78901234 my_project
More commonly, you will be in the directory containing your project.properties
file and instead use .
, which is the current directory.
$ cd my_project
$ particle flash 0123456789abcdef78901234 .
You can also target a specific version of Device OS in the particle flash
command:
$ particle flash 0123456789abcdef78901234 . --target 5.3.1
Flashing a directory with assets
Asset OTA (available in Device OS 5.5.0 and later), makes it possible to include bundled assets in an OTA software update that can be delivered to other processors and components in your product.
The particle flash
command supports asset OTA. Your project directory will typically look like:
my_project/
src/
my_project.cpp
my_project.h
assets/
coprocessor.bin
project.properties
README.md
Flashing a pre-compiled binary OTA
You can flash a binary that you have previously compiled to a .bin file:
$ particle flash 0123456789abcdef78901234 firmware.bin
You can also flash a pre-compiled binary with assets in a .zip file:
$ particle flash 0123456789abcdef78901234 product.zip
Flashing a pre-compiled binary over USB
You can flash a binary that you have previously compiled to a .bin file over USB. The device will be put into DFU mode automatically, if necessary.
$ particle flash --local firmware.bin
$ particle flash --local product.zip
If there are multiple devices connected by USB, you can specify the device for --local
by device ID or device name:
$ particle flash --local wandering-ferret firmware.bin
$ particle flash --local 0123456789abcdef78901234 firmware.bin
Flashing one or more source files
You can include any number of individual source files after the device Name, and the CLI will include them while flashing your app.
# how to compile and flash a list of source files to your device
$ particle flash 0123456789abcdef78901234 app.ino library1.cpp library1.h
Note that the CLI since 1.9.0 has support for firmware libraries via the particle library commands.
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
Target a specific firmware version for flashing
You can compile and flash your application against a specific firmware version using the --target
flag. If you don't specify target
your code will compile against the latest LTS release firmware.
This is useful if you are not ready to upgrade to the latest Device OS version on your device, try a release candidate version, or switch between LTS and developer preview release lines.
# compile your application with the 5.3.1 Device OS version and flash it
$ particle flash --target 5.3.1 0123456789abcdef78901234 my_project
A list of valid version numbers can be found in the release notes.
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
Flashing a known app
You can easily reset a device back to a previous existing app with a quick command. Tinker is the original firmware that ships with the device and can be flashed as follows:
$ particle flash deviceName tinker
You can flash a known app over USB with --local
. The device will be put into DFU mode, blinking yellow.
$ particle flash --local tinker
Flashing tinker will leave the version of Device OS on your device unchanged. You can, however, set a specific version of Device OS (upgrade or downgrade) using the --target
option. A list of valid version numbers can be found in the release notes.
$ particle flash --local tinker --target 5.5.0
In many respects, particle flash --local tinker --target 5.5.0
and particle update --target 5.5.0
are similar. The major difference is that particle update
will update the NCP (network coprocessor) where --local
will not. This will only affect Tracker devices that previously had Device OS 2.x on them and upgrade to 3.x or later. Even if you do not update the NCP over USB, it can still be updated OTA. The Argon also has an NCP, but the version has never been upgraded. No other devices have an NCP.
It is also possible to flash in listening mode (blinking dark blue) using --serial
, however DFU should be used except in rare cases as it's significantly more reliable and provides status in case of failure.
$ particle flash --serial tinker
You can also update the factory reset firmware using the --factory
on devices that support factory reset user firmware. Note that factory reset does not restore the original Device OS version. Additionally, the factory reset firmware slot is empty from the factory, so user firmware won't be replaced, either, unless you manually set it first.
$ particle flash --factory tinker
Flashing a product device
To flash a product device, use the particle cloud flash
command and set the --product
flag to your product's id.
# Compile the source code in the current directory in the cloud and flash to device `0123456789abcdef01234567` within product `12345`
$ particle cloud flash 0123456789abcdef01234567 --product 12345
If the specified Device ID is not marked as a development device, the firmware that you have flashed may be immediately overwritten by the default or locked product firmware.
Compiling remotely and flashing locally
To cloud compile and flash locally over USB:
particle flash --local project/path
Prior to September 2023, a multi-step process was required.
You can also specify a Device OS version. This will be used as both the target Device OS version for your firmware, as well as upgrade or downgrade the Device OS version over USB. A list of valid version numbers can be found in the release notes.
particle flash --local project/path --target x.y.z
You can also add the --application-only
to set the Device OS target version for compiling, but to not change the Device OS version over USB. If the target version is newer than what is on the device, the device will be updated OTA if necessary.
particle flash --local project/path --target x.y.z --application-only
If you specify a directory containing a project.properties
file that contains an assetOtaDir
, then the device will be flashed with the bundle of the user firmware and Asset OTA assets.
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
particle compile
Compiles one or more source file, or a directory of source files, and downloads a firmware binary to your computer. The cloud compiler is device-specific, so the name of device you want to target (or its alias) must be provided as an argument. The supported devices are:
p2
(also Photon 2)boron
argon
bsom
(B Series SoM, 4xx)b5som
(B Series SoM, 5xx)tracker
photon
p1
electron
(also E Series)NOTE: Remember that *.cpp and *.ino files behave differently. You can read more about it in preprocessor in the Device OS Firmware API reference.
$ particle compile boron myapp.ino
While compiling source code using the cloud compiler there are limits:
- Maximum time to compile: 120 seconds
- Maximum source code size: 50 MB
The cloud compiles .ino
and .cpp
files differently. For .ino
files, the cloud will apply a pre-processor. It will add missing function declarations, and it will inject an #include "Particle.h"
line at the top of your files if it is missing. See the pre-processor documentation for details.
If you want to build a library that can be used for both Arduino and Particle, here's a useful code snippet:
#if defined(ARDUINO) && ARDUINO >= 100
#include "Arduino.h"
#elif defined(SPARK)
#include "application.h"
#endif
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
Compiling a directory
You can setup a directory of source files and libraries for your project, and the CLI will use those when compiling remotely.
# how to compile a directory of source code
$ particle compile boron my_project_folder
# by default the current directory will be compiled
$ particle compile boron
More commonly, you will be in the directory containing your project.properties
file and instead use .
, which is the current directory.
You can also specify the filename to save to. If the filename exists, it will be overwritten.
$ cd my_project
$ particle compile p2 . --saveTo firmware.bin
You can also target a specific version of Device OS in the particle flash
command:
$ particle flash 0123456789abcdef78901234 . --target 5.3.1
While compiling source code using the cloud compiler there are limits:
- Maximum time to compile: 120 seconds
- Maximum source code size: 50 MB
A list of valid version numbers can be found in the release notes.
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
Compiling a directory with assets
Asset OTA (available in Device OS 5.5.0 and later), makes it possible to include bundled assets in an OTA software update that can be delivered to other processors and components in your product.
The particle compile
command supports asset OTA. Your project directory will typically look like:
my_project/
src/
my_project.cpp
my_project.h
assets/
coprocessor.bin
project.properties
README.md
$ cd my_project
$ particle compile boron .
The name of the assets directory is specified in project.properties
file contains an assetOtaDir
key and a value containing a valid directory. It does not need to be named assets/
.
assetOtaDir=assets
- When using Particle: Compile Application or
particle compile
projects with bundled assets are built into a .zip file. This file contains both the firmware binary (.bin) as well as the assets. - The asset bundle .zip can be uploaded to the console as product firmware binary.
- When using Particle: Flash application or
particle flash
the same process is followed, except the device is flashed. - When flashing OTA, the asset bundle is transmitted using resumable OTA and compression for efficient data use.
- You will need to include code in your application firmware to process the additional assets, such as sending them to a coprocessor or saving them to the file system.
- Creating bundled assets will not be not possible in the Web IDE. Particle Workbench is recommended.
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
Compiling one or more source files
# how to compile a list of source files
$ particle compile boron app.ino library1.cpp library1.h
Target a specific firmware version for compiling
You can compile your application against a specific firmware version use the --target
flag. If you don't specific target
your code will compile against the latest released firmware.
This is useful if you are not ready to upgrade to the latest Device OS version on your device.
# compile your application with the 0.5.0 Device OS version
$ particle compile boron --target 0.5.0 my_project
$ particle compile electron myapp.ino --target 0.5.1`
$ `particle flash <deviceid> myapp.ino --target 0.5.1` would compile and
flash myapp.ino for device <deviceid> against Device OS version 0.5.1.
This is also useful for the Xenon, which requires 1.5.x or earlier:
$ particle compile xenon --target 1.5.0 my_project
Or the Spark Core, which requires 1.4.4 or earlier:
$ particle compile core --target 1.4.4 my_project
P2 and Photon 2 Devices:
At the time of writing, flashing a P2 or Photon 2 from the CLI targets 3.2.1-p2.2, which is not recommended. You
should always manually target 5.3.1 or later, for example, --target 5.3.1
, instead.
particle project
Use the project structure when you want to use libraries or you want to organize your source code better.
creating a project
You will be prompted to create the project in a default directory or in the current directory. The default directory for projects is your home directory
# create a new project
$ 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
The meta data about the project is stored in the project.properties
file. It includes the project name and what libraries are used by the project.
compiling a project
Compile or flash a project like you would another directory.
# compile the project in the current directory
$ particle compile photon
# flash the project in the current directory to a device
$ particle flash my_device
particle library
The fantastic Particle community has created and ported many libraries to make it easier to get your project done fast. You can use those libraries in projects you compile through the command line.
particle library list
Browse the list of all libraries to see what are the most popular libraries available.
$ particle library list
particle library search
Find a specific library by name. The name is case insensitive.
# seach for the InternetButton library
$ particle library search internet
particle library add
First, create a project then in the project directory add the library. It will be added to the project.properties
.
# add the InternetButton library
$ particle library add internetbutton
# add a specific version of the InternetButton library
$ particle library add internetbutton@0.1.10
# add the line #include "InternetButton.h" in your source code to use the library
To upgrade to a newer version later, just do particle library add
with the same name and the project.properties
will be updated with the latest version of that library.
particle library view
See the source and examples of a library with particle library view
. It will download the library and tell you where it is on the local file system.
# see the InternetButton library
$ particle library view internetbutton
particle library copy
If you need to make modifications to a published library, to fix a bug or add a new feature, copy the library locally to your project. It will end up in the lib
folder of your project.
# add a custom version of the InternetButton library to your project
$ particle library copy internetbutton
# add the line #include "InternetButton.h" in your source code to use the library
If you previously had added the library with particle library add
you should remove it from your project.properties
to make sure you don't include 2 versions of the library: the published one and modified one.
particle library create
To make your own library you can use particle library create
to get a folder structure with all the files you'll need and customize it from there.
$ mkdir mylib
$ cd mylib
$ particle library create
particle library upload
After you modified a published library or you are ready to use the library you created in a project, you upload a private version of your library to the Particle cloud.
# upload the library in the current directory
$ particle library upload
You can upload the same private version several times until you have happy with it.
If you modified an existing library you have to modify the name of the library in library.properties
.
particle library publish
When you're ready to make a new private library version available, you publish it.
# publish you library
$ particle library publish mylib
Remember that it's necessary to publish every new version after uploading it before others can use it in their projects.
particle webhook
particle webhook create
Create a webhook that will trigger an HTTP request when a Particle event is published to the cloud. You can pass in an eventName
, url
, and deviceID
as arguments to the CLI command. Optionally, you can create your own custom JSON file that includes webhook params. For a full list of available
webhook parameters, see the REST API documentation. This command is only available for user webhooks.
$ particle webhook create temperature https://mysite.com
$ particle webhook create temperature https://mysite.com 0123456789abcdef78901234
$ particle webhook create webhook.json
# An example custom webhook JSON file that will target Librato, webhook.json
{
"event": "librato_",
"url": "https://metrics-api.librato.com/v1/metrics",
"name": "Publish to Librato",
"requestType": "POST",
"auth": {
"username": "YOUR_LIBRATO_USERNAME",
"password": "YOUR_LIBRATO_ACCESS_TOKEN"
},
"json": {
"gauges": [
{
"name": "{{PARTICLE_EVENT_NAME}}",
"value": "{{PARTICLE_EVENT_VALUE}}",
"source": "{{PARTICLE_DEVICE_ID}}"
}
]
},
"mydevices": true
}
particle webhook list
List all webhooks belonging to the authenticated user. This command is only available for user webhooks.
$ particle webhook list
Found 2 hooks registered
1.) Hook ID 57223d27ffedc82b02697efb is watching for "temp"
and sending to: http://google.com
for device 53ff73066678505550292167
created at 2016-04-28T16:41:11.687Z
2.) Hook ID 57228c5e4b112b4f2f51cfc2 is watching for "hello"
and sending to: https://google.com
created at 2016-04-28T22:19:10.726Z
particle webhook delete
Delete a webhook and immediately stop it from triggering. This command is only available for user webhooks.
$ particle webhook delete 234523452345234523452345
Successfully deleted webhook!
All registered user webhooks can be removed by passing the all
parameter.
$ particle webhook delete all
? Do you want to delete ALL your webhooks? Yes
Found 3 hooks registered
deleting 58889c0af14a8228a3fe64c8
deleting 58889c0ef14a8228a3fe64dd
deleting 58889c1113e45f1b69be21b7
particle monitor
Pulls the value of a variable at a set interval, and optionally display a timestamp
- Minimum delay for now is 500 (there is a check anyway if you keyed anything less)
- hitting
CTRL + C
in the console will exit the monitoring
# how to poll for a variable value from one or more devices continuously
$ particle monitor 0123456789abcdef78901234 temperature 5000
$ particle monitor 0123456789abcdef78901234 temperature 5000 --time
$ particle monitor all temperature 5000
$ particle monitor all temperature 5000 --time
$ particle monitor all temperature 5000 --time > my_temperatures.csv
particle identify
Retrieves your device id when the device is connected via USB and in listening mode (flashing blue). It also provides the current system firmware version on the device.
# helps get your device id and system firmware version via usb and serial
# make sure your device is connected and blinking blue
$ particle identify
$ particle identify --port 1
$ particle identify --port COM3
$ particle identify --port /dev/cu.usbmodem12345
$ particle identify 0123456789abcdef78901234
particle subscribe
Subscribes to published events on the cloud, and pipes them to the console.
Remember that the eventName is a prefix, so if you subscribe to "test" you'll also get events "testing" and "test1234".
# opens a connection to the API so you can stream events coming from your devices
$ particle subscribe
$ particle subscribe eventName
$ particle subscribe eventName CoreName
$ particle subscribe eventName 0123456789abcdef78901234
# subscribe to all events for a particular device
$ particle subscribe --device deviceName
$ particle subscribe --device 0123456789abcdef01234567
It's also possible to subscribe to all events from a specific device in your account.
# subscribe to all events published by devices within product `12345`
$ particle subscribe --product 12345
To listen to a product's event stream, set the --product
flag to your product's id.
# subscribe to all events published by the device with id `0123456789abcdef01234567` within product `12345`
$ particle subscribe --device 0123456789abcdef01234567 prod-01 --product 12345
Likewise, to listen to a product device's event stream, set the --device
flag to your device's id and the --product
flag to your product's id.
# No longer necessary to use "mine" as this is the only option
# when subscribing to events from your devices
$ particle subscribe mine
$ particle subscribe eventName mine
$ particle subscribe mine deviceName
Prior to August 2020, you could subscribe to the public event stream, but the public event stream is no longer available. Thus specifying special device name "mine" is no longer necessary as you only will ever receive events for your account and devices now.
particle publish
Publishes events to the cloud via API, similar to running Particle.publish() on a Particle Device.
$ particle publish eventName
$ particle publish eventName data
$ particle publish eventName "some data with spaces"
Prior to August 2020, there were both public and private event streams. The public event stream no longer exists, thus you do not need to explicitly specify the --private
flag. All events are private, and will be received whether MY_DEVICES
is specified or not when subscribing on a device.
$ particle publish eventName --private
$ particle publish eventName someData --private
To send events to a product's event stream, set the --product
flag to your product's id.
# publish a `temp` event with a value of `25.0` to your product `12345`'s event stream
$ particle publish temp 25.0 --product 12345
Prior to March 2023, webhook events like hook-sent, hook-error, and hook-response only went to the device owner's event stream. If the device was unclaimed, the events disappeared. Now, these events also appear in the product event stream, in the console, SSE event stream, and webhooks.
particle serial
particle serial wifi
Configure Wi-Fi credentials over serial on the Photon, P1, and Argon.
# Configure new Wi-Fi credentials for a Photon or Argon over a serial connection
$ particle serial wifi
You will need to use this command to set up a device using WPA2 Enterprise and services like EduRoam that use it.
Note: The Argon, P2, and Photon 2 cannot connect to a Wi-Fi network with a hidden SSID, even using the CLI. The reason is that prior to connecting, a Wi-Fi scan is done to find the BSSID with the strongest signal and connect to that. Otherwise, on network with multiple access points, the devices would not necessarily connect to the best AP.
It's possible to read Wi-Fi credentials from a file and send them to a device over serial.
$ particle serial wifi --file credentials.json
The JSON file for passing Wi-Fi credentials should look like this:
{
"network": "my_ssid",
"security": "WPA2_AES",
"password": "my_password"
}
The security
property can be NONE, WEP, WPA2_AES, WPA2_TKIP, WPA2_AES+TKIP, WPA_AES, WPA_TKIP, WPA_AES+TKIP. For enterprise Wi-Fi, set security to WPA_802.1x or WPA2_802.1x and provide the eap
, username
, outer_identity
, client_certificate
, private_key
and root_ca
properties.
WPA Enterprise is only available on the Photon and P1 (Gen 2). It is not available on the Argon (Gen 3).
WPA2 Enterprise support will be added in a future version of Device OS for the P2 and Photon 2.
particle serial list
Shows currently connected Particle devices acting as serial devices over USB
# shows a list of devices connected via serial usb
$ particle serial list
particle serial monitor
Starts listening to the specified serial device, and echoes to the terminal
# opens a read-only serial monitor for a particular device
$ particle serial monitor
$ particle serial monitor --port 1
$ particle serial monitor --port COM3
$ particle serial monitor --port /dev/cu.usbmodem12345
particle serial flash
Flash a firmware binary over serial.
$ particle serial flash firmware.bin
This is a synonym for particle flash --serial firmware.bin
.
Note that at present only binaries can be flashed using this command.
If you wish to flash from application sources, first use particle compile
to compile a binary from sources.
If you have Device OS firmware with debugging enabled (which is the default on the Electron) then flashing via serial will fail unless debugging is disabled. You can disable debugging logs flashing Tinker via USB: particle flash --local tinker
.
In general, using --usb
mode in DFU mode (blinking yellow) is a more reliable way to flash your device over USB.
particle serial inspect
Print information about the firmware modules on a device. The device must be in listening mode (blinking blue) and connected by USB to your computer.
$ particle serial inspect
Platform: 6 - Photon
Modules
Bootloader module #0 - version 502, main location, 16384 bytes max size
Integrity: PASS
Address Range: PASS
Platform: PASS
Dependencies: PASS
System module #1 - version 1512, main location, 262144 bytes max size
Integrity: PASS
Address Range: PASS
Platform: PASS
Dependencies: PASS
System module #2 - version 207
System module #2 - version 1512, main location, 262144 bytes max size
Integrity: PASS
Address Range: PASS
Platform: PASS
Dependencies: PASS
System module #1 - version 1512
Bootloader module #0 - version 400
User module #1 - version 3, main location, 131072 bytes max size
UUID: B3A6DCD529BE70FBE24EE959C7305D58E3BC9A04ACDCE8F093C7A1F759097D09
Integrity: PASS
Address Range: PASS
Platform: PASS
Dependencies: PASS
System module #2 - version 6
If you see any FAIL
entries, there is likely a missing dependency, such as a bootloader that needs to be upgraded. Normally this will be corrected automatically over-the-air, but if you cannot connect to the cloud the dependency cannot be fixed OTA.
The version numbers in the output can be mapped to common version numbers using this table. For example, Device OS version 1512 is more commonly known as 1.5.2.
particle usb
Various commands to interact with a device connected through USB.
On Windows, these commands require the latest drivers. See the CLI installation guide for details.
The Particle USB commands are only available in Device OS 0.9.0 (Gen 3, including Argon and Boron), and 1.0.0 (Gen 2, including Photon, P1, Electron, and E Series). These commands are not available on the Gen 1 (Spark Core).
If you have an older Particle device you can use particle update
will upgrade the devices to support these commands.
particle usb list
List Particle USB devices attached to the host
particle usb list [--exclude-dfu] [--ids-only]
particle usb start-listening
Put a device or multiple devices into the listening mode
particle usb start-listening [devices...] [--all]
Also aliases to usb listen
.
particle usb listen [devices...] [--all]
Start listening can only be done from normal operating mode or safe mode.
particle usb stop-listening
Make a device or multiple devices exit the listening mode
particle usb stop-listening [devices...] [--all]
Stop listening can only be done from listening mode (blinking dark blue).
particle usb safe-mode
Put a device or multiple devices into the safe mode
particle usb safe-mode [devices...] [--all]
Safe mode can only be entered from normal operating mode (not DFU mode).
particle usb dfu
Put a device or multiple devices into the DFU mode
particle usb dfu [devices...] [--all]
DFU mode can only be entered from normal operating mode or safe mode.
particle usb reset
Reset a device or multiple devices
particle usb reset [devices...] [--all]
Reset can be used from normal operating mode, safe mode, or DFU mode.
particle usb setup-done
On the Argon, Boron, B Series SoM, and Tracker SoM running Device OS 3.x and earlier, the setup done flag indicates that mesh setup has been complete. This is set automatically by the mobile apps, however if you are setting up manually over USB, you will need to set the setup done flag, otherwise the device will always boot into listening mode (blinking dark blue).
particle usb setup-done [devices...] [--reset]
The --reset
command clears the setup done flag, so the device will resume booting into listening mode.
Setup done can only be issued when in normal operating mode or safe mode. It is only applicable for Gen 3 devices (Argon, Boron).
With Device OS 4.0 and later, there is no setup done flag and this CLI command does not do anything.
particle usb configure
Install udev rules for Particle USB devices (Linux-only)
particle usb configure
particle update
Update your device to the latest Device OS release. Follow this with particle flash --local tinker
to reflash the default Tinker app to make your device run known good software. This will generally be the latest LTS version, unless the device does not yet have an LTS release, in which case it will be the latest non-RC version in the developer preview release line.
$ particle update
> Your device is ready for a system update.
> This process should take about 30 seconds. Here goes!
! System firmware update successfully completed!
> Your device should now restart automatically.
Additionally, you can upgrade to a specific version of Device OS using the --target
option. This is handy for moving to the developer preview line of releases instead of LTS.
$ particle update --target 5.5.0
You can also downgrade Device OS, however:
- In general we recommend that you do not downgrade Device OS on devices, except to roll back from developer preview back to the adjacent LTS version.
- If you are downgrading, you should first downgrade user firmware or using
particle flash --local tinker
as user firmware that targets a newer version of Device OS will cause it to update back to its original version OTA after reconnecting to the cloud.
Boron LTE BRN402 and B Series SoM B402
If you are downgrading a Boron LTE (BRN402) or B Series SoM B402 from Device OS 2.0.0 or later, to 1.5.1 or earlier, you must first install 1.5.2, allow the device to boot and connect to cellular before downgrading again to an earlier version. The reason is that 2.0.0 and later use a higher baud rate for the cellular modem, and on the SARA-R410M only, this setting is persistent. Older versions of Device OS assume the modem is using the default of 115200 and will fail to communicate with the modem since it will be using 460800. Device OS 1.5.2 uses 115200, however it knows it can be 460800 and will try resetting the baud rate if it can't communicate with the modem.
particle keys
particle keys doctor
Helps you update your keys, or recover your device when the keys on the server are out of sync with the keys on your device. The particle keys
tools requires both dfu-util, and openssl to be installed.
Connect your device in DFU mode, and run this command to replace the unique cryptographic keys on your device. Automatically attempts to send the new public key to the cloud as well.
# helps repair key issues on a device
$ particle keys doctor 0123456789abcdef78901234
See also particle device doctor
particle keys new
Generates a new public / private key pair that can be used on a device.
# generates a new public/private keypair
$ particle keys new
running openssl genrsa -out device.pem 1024
running openssl rsa -in device.pem -pubout -out device.pub.pem
running openssl rsa -in device.pem -outform DER -out device.der
New Key Created!
# generates a new public/private keypair with the filename mykey
$ particle keys new mykey
running openssl genrsa -out mykey.pem 1024
running openssl rsa -in mykey.pem -pubout -out mykey.pub.pem
running openssl rsa -in mykey.pem -outform DER -out mykey.der
New Key Created!
particle keys load
Copies a .DER
formatted private key onto your device's external flash. Make sure your device is connected and in DFU mode. The particle keys
tools requires both dfu-util, and openssl to be installed. Make sure any key you load is sent to the cloud with particle keys send device.pub.pem
# loads a key to your device via USB
# make sure your device is connected and blinking yellow
# requires dfu-util
$ particle keys load device.der
...
Saved!
particle keys save
Copies a .DER
formatted private key from your device's external flash to your computer. Make sure your device is connected and in DFU mode. The particle keys
tools requires both dfu-util, and openssl to be installed.
# creates a backup of the private key from your device to a file
# requires dfu-util
$ particle keys save device.der
...
Saved!
particle keys send
Sends a device's public key to the cloud for use in opening an encrypted session with your device. Please make sure your device has the corresponding private key loaded using the particle keys load
command.
# sends a new public key to the API for use for your device
$ particle keys send 0123456789abcdef78901234 device.pub.pem
submitting public key succeeded!
particle keys server
Switches the server public key stored on the device's external flash. This command is important when changing which server your device is connecting to, and the server public key helps protect your connection. Your device will stay in DFU mode after this command, so that you can load new firmware to connect to your server. By default this will only change the server key associated with the default protocol for a device. If you wish to change a specific protocol, add --protocol tcp
or --protocol udp
to the end of your command.
$ particle keys server my_server.der
$ particle keys server my_server.der --protocol udp
Encoding a server address and port
When using the local cloud you can ask the CLI to encode the IP or dns address into your key to control where your device will connect. You may also specify a port number to be included.
$ particle keys server my_server.pub.pem 192.168.1.10
$ particle keys server my_server.der 192.168.1.10 9000
$ particle keys server my_server.der 192.168.1.10 9000 --protocol udp
particle keys address
Reads and displays the server address, port, and protocol from a device.
$ particle keys address
tcp://device.spark.io:5683
particle keys protocol
Views or changes the transport protocol used to communicate with the cloud. Available options are tcp
and udp
for Electrons (if you are running at least firmware version 0.4.8).
# determine the current protocol
$ particle keys protocol
# set the protocol to tcp or udp
$ particle keys protocol tcp
$ particle keys protocol udp
particle nyan
Make your device shout rainbows. Useful in a hackerspace-type setting to easily identify a specific device, or to verify that your device can receive commands from the cloud.
# Activates the "shouting rainbow LED" sequence
$ particle nyan
$ particle nyan my_device_id on
$ particle nyan my_device_id off
$ particle nyan all on
$ particle nyan [on/off]
$ particle nyan [device_id/all] [on/off]
particle config
The config command lets you create groups of settings and quickly switch to a profile by calling particle config <profile-name>
. This is especially useful for switching to your local server or between other environments.
Calling particle config particle
will switch Particle-Cli back to the Particle Device Cloud API server.
$ particle config my-profile-name // switch to a new profile called 'my-profile-name'
$ particle config particle // switch back to your default profile
$ particle config local apiUrl http://localhost:8080 //creates a new profile with name "local" and saves the IP-address parameter
$ particle config useSudoForDfu true // sets the `useSudoForDfu` option to `true`
Calling particle config
will output your current config settings.
$ particle config
Current profile: particle
Using API: https://api.particle.io
Access token: 01234567890abcdef01234567890abcdef012345
particle binary
Inspect binaries
particle binary inspect
Describe binary generated by compile.
$ particle binary inspect file.bin
file.bin
CRC is ok (06276dc6)
Compiled for photon
This is a system module number 2 at version 6
It depends on a system module number 1 at version 6
You can also inspect a .zip file containing a binary with additional assets.
particle token
particle token list
Retrieve all the access token under your Particle account.
$ particle token list
Checking with the cloud...
? Using account cli@particle.io
Please enter your password: *******
spark-ide
Token: da39a3ee5e6b4b0d3255bfef95601890afd80709
Expires at: null
cloud-compile
Token: da39a3ee5e6b4b0d3255bfef95601890afd80709
Expires at: null
spark-cli
Token: da39a3ee5e6b4b0d3255bfef95601890afd80709
Expires at: null
__PASSWORD_ONLY__
Token: da39a3ee5e6b4b0d3255bfef95601890afd80709
Expires at: 2017-06-12T13:42:46.308Z
__PASSWORD_ONLY__
Token: da39a3ee5e6b4b0d3255bfef95601890afd80709
Expires at: 2017-06-12T09:03:45.797Z
__PASSWORD_ONLY__ (active)
Token: da39a3ee5e6b4b0d3255bfef95601890afd80709
Expires at: 2017-06-12T08:44:16.371Z
particle token create
Create a new access token under your Particle account.
$ particle token create
? Using account cli@particle.io
Please enter your password: *******
New access token expires on Fri Jun 23 2017 23:09:24 GMT+0800 (SGT)
da39a3ee5e6b4b0d3255bfef95601890afd80709
In order to change the duration a token is valid, use --expires-in <seconds>
option. The default if not specified is 90 days.
$ particle token create --expires-in 600
To make a non-expiring token, use the --never-expires
option. Short lived tokens are better for security. Reserve non-expiring tokens for hosted web applications that need to access the Particle API reliably over an indefinite period of time.
$ particle token create --never-expires
particle token revoke
Revoke an access token under your Particle account.
$ particle token revoke ACCESS_TOKEN
? Using account cli@particle.io
Please enter your password: *******
successfully deleted ACCESS_TOKEN
The only available option is --force
which is necessary if you want to delete the access token used by the CLI itself.
particle product [BETA]
Access Particle Product functionality
particle product device add
Adds one or more devices into a Product
# add device id `0123456789abcdef01234567` into product `12345`
$ particle product device add 12345 0123456789abcdef01234567
...or upload a .txt
file with a single column of device ids
# add a list of devices into product `12345`
$ particle product device add 12345 --file ./path/to/device_ids.txt
particle product device list
List all devices that are part of a product
# lists devices in product `12345`
$ particle product device list 12345
particle device doctor
Gen 2 Devices (E Series, Electron, Photon, and P2; does not include E404X):
Only available on Gen 2 devices, Photon, P1, and Electron. For other devices, use web device doctor.
Brings back a Gen2 device (photon
, p1
, electron
) with bad firmware, bad network settings or bad keys
to health so it can connect to the Particle cloud.
The Device Doctor will:
- Update Device OS to the latest version
- Update the CC3000 Wi-Fi module firmware (Core only)
- Reset the antenna selection
- Reset the IP configuration
- Reset the SoftAP (listen mode) hotspot name
- Clear the data in the EEPROM
- Clear the Wi-Fi credentials
- Prompt for new Wi-Fi credentials
- Reset server and device key
- Flash the default Particle Tinker app
# first connect your device to the USB port and disconnect all others
$ particle device doctor
The Device Doctor will put your device back into a healthy state
# follow the prompts to restore your device
particle setup
Gen 2 Devices (E Series, Electron, Photon, and P2; does not include E404X):
Only available on the Photon and P1. setup.particle.io for all devices instead.
To only set Wi-Fi credentials on the Photon 2, P2, Argon, Photon, and P1, use particle serial wifi
.
To set up a Photon or P1 only, you can use:
# Photon or P1 only!
$ particle setup