Console

The Particle Console is your centralized IoT command center. It provides interfaces to make interacting with and managing Particle devices easy. This guide is divided into two main sections, tools for developers and tools to manage product fleets.

Note: The Console does not work in Microsoft Internet Explorer. Please use another browser, such as Chrome, Firefox, or Edge, to access the Console. If you're experiencing rendering issues, turn off any ad blocking extensions you may be using.

Demo

You can explore a live demo environment with a continuously operating device fleet, no hardware or setup required!

Visit the demo site for instant access.

Welcome page

The console welcome page provides easy access to developer, product, and organization features.

The Sandbox popup in the upper left corner switches between your personal view ("Sandbox") and being able to see the devices and products in your organization, if your account is part of an organization.

Sandbox

Search - sandbox

The search box makes it easy to search for a device from its Device ID (24-character hex code), serial number, name, or ICCID. You can also search for a product by name.

This can be done at the top level of your sandbox to search your sandbox and all organizations you have access to. There is also a search at the top level of each organization to search only that organization.

Hovering over the left side of the window expands the left navigation, providing access to all of the console features.

Products - sandbox

The Products page shows the products that you own and also the products you have been granted access to as a team member.

If you are part of an organization, there may be additional products that you have access to by navigating into the organization first using the Sandbox popup menu in the upper left corner of the window.

Devices - sandbox

The device list shows the devices associated with your account. Note that there are multiple device lists, one for your sandbox, and one in each product that you have access to.

Clicking on My Devices in the left-hand navigation bar brings up the sandbox device list.

If the Show sandbox devices only checkbox is not checked, then the list will only show devices that are claimed to your account, both in your free developer sandbox as well as product devices in free, basic, and enterprise organization products.

When checked, the list will only include non-product devices claimed to your account in the free developer sandbox.

Total personal devices is the number of non-product devices in your free developer sandbox.
Total claimed product devices is the total number of devices claimed to your account that are in a product.

The 100-device limit in the free plan is the total of the devices claimed to your account in the developer sandbox, plus all devices in any free plan products that you are the owner of.

You can also take certain actions on devices from this view, such as renaming the device and unclaiming it from your account.

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 release ownership of your SIM to stop billing.

In this example, clicking the checkbox results in no devices, because every device is part of a product.

The product device list will be discussed in more detail below, but this is what it looks like in this account:

The product device list has a number of columns that are not present in the sandbox device list:

Firmware - Fleet-wide firmware releases only apply to products. While you can flash sandbox devices OTA, there isn't a release number associated with it.
Device OS - The Device OS version reporting is related to the fleet-wide firmware release process.
Owner - All sandbox devices are owned by you, the user logged into the account the sandbox is being viewed for.
Billing status - All sandbox devices count toward the 100-device billing limit.
Groups - Groups are only available in products.

SIM cards - sandbox

If you have cellular devices, you may have SIM cards listed in the SIM cards panel.

In most cases, however, your devices will be associated with a product, in which case the SIM cards are in the product SIM card view, instead.

When you set up a device at https://setup.particle.io/ it is set up as a product device, and Particle recommends making every device part of a product, even if it's a product of one device. There is no limit to the number of products you can have, even in the free tier.

It is unusual to have to use the Import SIM card option as adding a device to a product will also add its associated SIM card.

If you click the ... button to the right of a SIM card you will be presented with two options:

Deactivate SIM deactivates a SIM card with the mobile carrier so it will no longer be able to connect
Release SIM releases a SIM card so it will no longer be able to connect, and can be transferred to another user

Deactivated SIM behavior also varies based on your billing plan:

Free plan: still counts toward the 100 device limit
Basic plan: still counts toward the 100 device per block limit
Enterprise plans: may stop counting the device as a billable device in some cases

To remove a device so it is no longer counted against your free plan 100 device limit, or against the basic plan 100 device per block limit, you must both remove the device from its product and release its SIM card.

Unclaim (for claimed devices)
Remove from product (for product devices)
Release SIM (for cellular devices)

If you have a Boron device and have enabled using an external 3rd-party SIM card with a plastic 4FF nano SIM card, you will manage the SIM from the SIM provider or mobile carrier's web site, not from the Particle console.

Logic - sandbox

Logic Functions are bits of Javascript code that get called in response to a Logic Trigger, which can be:

A Particle event, generated by a device, Particle cloud API, or webhook response
A scheduled, periodic time event ("cron")

Logic Functions run in the cloud and are designed to perform short-running calculations such as:

Generation of new event (which might be subscribed to by a device, or trigger an integration)
Storing data in the Ledger database

In many cases, you will want to access Logic from within a product. Those logic blocks are specific to that product.

For more information, see Logic.

Ledgers - sandbox

Ledger allows data to be stored in the cloud, per-device, per-product, or per owner account.

The three types of Ledgers are:

Scope	Description
Cloud Ledger	Stores information in the cloud without syncing to the edge.
Device to Cloud Ledger	Device storage that syncs automatically to the cloud
Cloud to Device Ledger	Set data in the cloud that will sync to devices

Each ledger is a block of JSON data, up to 16 Kbytes in length. You can define the data format yourself, and it does not need to be pre-defined (no schema required). It can contain simple values (string, number, boolean) as well as nested objects and arrays. JSON does not support binary data, but you can store small binary data by encoding it, such as hex, Base64, or Base85 encoding.

Device to Cloud and Cloud to Device ledgers require Device OS 6.1.0 or later. They can be up to 16 KBytes in size.

Cloud only ledgers (not synchronized to a device) can be up to 1 Mbyte (1024 Kbyte).

In many cases, you will want to access Ledger within a product. Those ledgers are specific to that product.

For more information, see Ledger.

Integrations - sandbox

Integrations (webhooks) allow interaction with external services.

In almost all cases you should create integrations in the product it is associated with, or in the organization it is part of.

Warning:

Creating sandbox integrations will greatly complicate the process of moving from the free to the basic or enterprise plans later on.

For more information, see Integrations.

Events - sandbox

Events are published by devices, Logic, as the result of an integration (webhook), or from the Particle cloud API. They provide a secure, data-efficient way to communicate information between these things. Events are temporal and disappear if not captured by something else, like an integration that could send it to a database, or Ledger. Likewise, the Events view is live, and does not show historical events. It will only show events that pass through the cloud while the panel is open.

The sandbox Cloud services - Events panel allows viewing of published events. It shows events that were generated by claimed devices in your account. You will typically view events in one of the other places where you can view events. Since product devices are often not claimed to your account, you may not see all events in this panel.

There are also events tabs in each product, that show events from all product devices, whether claimed or not.

And also for each device, to only show events from that device. Note that the device event view does not show responses from webhooks going to that device, only events from the device.

For a comparison of the various Events panels, see More about events panels, below.

Exporting events - sandbox

The Event Viewer Tool can be used if you want to export events to a file or spreadsheet.

Authentication - sandbox

The Authentication tab allows the creation of a new OAuth client ID.

If you are providing access to the Particle cloud API for an external service, you should use API users.
You should avoid using the customer claiming feature and instead manage access for your customers through your own back-end service.
You should avoid using the Particle iOS and Android device setup SDKs, which are deprecated and not compatible with current devices.
If you do need to create an OAuth client you should do so at the product level, or organization level, not at the sandbox level.

Configuration - sandbox

Configuration is a platform‑wide capability for Particle. Configuration is the control plane for tailoring how devices, cloud, and applications behave, used to solve real-life problems like modem behavior and operating system level radio configuration, as well as to align user application needs from any vertical or use case.

Configuration scales from organization‑wide defaults, to product‑level settings, to device‑specific overrides where appropriate.

If you have access to an organization (basic, plus, or enterprise), you can set environment variables at the organization level in the Organization - Configuration - Environment section.

You can also set environment variables in Sandbox - Configuration - Environment section.

Additionally, both sandbox and organization products have their own Environment configuration.

For more information, see:

Environment: lightweight, non‑secret name - value pairs that shape the runtime environment. They are ideal for fast, system level adjustments (endpoints, feature flags, polling intervals) without changing firmware. Available in the cloud and in the firmware.
Secrets: secure, organization‑scoped values that integrations and logic can reference securely.

Billing & usage - sandbox

The Billing & Usage page shows billing information and data usage (data operations and cellular).

All accounts have a personal sandbox on the free plan. The sandbox can include up to 100 cellular and Wi-Fi devices (in any combination, not to exceed 100 total), free of charge. For the basic plan, this is in addition to devices included in your basic plan blocks.

For users who are Administrators of an organization, selecting the organization then Billing & Usage icon shows the usage for all products within the organization.

Organization Billing

In the Basic and Enterprise plans, usage is divided by the class of devices. For example: Wi-Fi and Cellular:

Wi-Fi and Cellular Usage

These panels turn yellow at 70% of your plan limits, and red when the limits have been reached.

Historical data - billing - sandbox

At the bottom of the Billing & Usage panel you can request a data usage report:

Time Range: Past week, Past month, Past 3 months, Past year
Data Requested: Data usage by device, Data usage by product, Metered devices snapshot, Metered devices changes, Devices in grace period

It will take several minutes to generate the data, and you will be emailed a csv file when done.

This option is also available for organization administrators in the organization Billing & Usage panel.

Billing limits - sandbox

You will receive warnings by email, and as a pop-up, and in the Billing & Usage tab in the console at 70%, 90%, and 100% of the allowable data operations.

In the free plan, once you reach the 100% limit you have three days to switch to the Basic plan, or data will be stopped until the end of your billing month. It will automatically resume on the free plan at the beginning of the next billing month, still on the free plan, if you do not upgrade.

In the basic plan, once you reach the 100% limit an additional block will be added to your plan. Starting at the next billing month your plan will include these additional block(s) and you will be billed accordingly. There is no additional charge at the time of the overage; it occurs only on the next billing cycle.

Upgrading to the basic plan

Following the link from the emails or Billing & Usage page leads to a contact form to initiate the upgrade process. A representative will contact you by telephone to complete the upgrade process to basic plan.

When you upgrade to the basic plan, you will get an organization, which is the collection of products and accounts in your plan. The usage limits in the basic plan apply monthly across all products of the same type in your organization. Some limits vary between cellular, Wi-Fi, and tracker products.

Additionally, all organization members still have a private sandbox in their account and can still have their own 100 free devices that do not count against your basic plan limits.

If you already have your devices in a product, the entire product can be moved into your basic organization without affecting the customers, access tokens, or cloud API endpoints, so this should be a relatively easy transition.

Products

Products are recommended for all situations, from single developer devices and experimentation to fleets of production devices for a commercial product. Using a product makes it possible to manage firmware updates for a fleet of devices, as well as answer key questions for commercial products like:

How many of my devices are online right now?
Which firmware version is running on each device?
Who of my customers are using their devices, and who isn't?
Who in my company has access to this fleet, and what information can they access?

Working with a product

You can select a product from the tiles in the My Products section of the console welcome page.

Selecting Products from the left navigation shows the products that you own and also the products you have been granted access to as a team member.

Hovering over the left side of the window expands the left navigation, providing access to all of the console features.

Note that this is very similar to the one at the top level of the sandbox, but only returns information about the product that you have opened.

New product

During setup using setup.particle.io you are typically offered the option of creating a new product. You can also create a product at any time using the New product button. There is no limit to the number of products in your account, even on the free plan, however there is a limit to the number of devices in the free plan.

Storage of geolocation data is truly optional. If not enabled, the product will function normally except the device location map will not display and the APIs for obtaining the device location will not return data.

Each product can only contain one platform. In some cases, like M-SoM or Tracker, there may be different SKUs that share a platform. In some other cases, like the B-SoM, different models may have different platforms, and would need separate products.

Devices - product

When you open a product, it will open to the Devices panel.

Along the top you will notice:

Product name ("Chivalrous Pink Borons")
Product type (Boron)
Product ID (46421)

In the device list you'll notice a number of useful fields for a device fleet.

In this example, the Name and Owner fields are none. It is normal and acceptable to have these fields be unset. Using unclaimed product devices is recommended for all products, and naming is optional. You typically only claim devices to your account (set an owner) for devices you have on your desk for active development.

Add devices - product

The controls along the top of the window include the Add devices button.

For any product you may be developing, you likely have one or more Particle development kits (i.e. a Photon) that you have been using internally for prototyping purposes. We strongly recommend importing these devices into your Product, and using them as your development group.

In addition, you'll want to have a test group of devices to serve as the guinea pigs for new versions of product firmware. You should get into the habit of uploading a new version of firmware to your product, and flashing it to your test group to ensure your code is working as expected. For more information, see firmware release process.

To add devices, click on the Devices icon in your product sidebar, then click on the Add Devices button.

You will then have several options for what to import:

Add one device - Add devices

You can add a single device by entering its Device ID, ICCID, IMEI, or Serial number. For more information about unique identifiers for devices, see serial number management.

Add many devices - Add devices

You can add multiple devices from a file in multiple formats:

.txt file: One device per line containing the Device ID, serial number, IMEI, or ICCID.
.csv file: One column must be named DEVICEID and contain the 24-character hexadecimal Device ID.

Device import CSV files - Add devices

The CSV file must have a header in the first row that specifies the columns. The only required column is DEVICEID but bulk order may include columns such as:

DEVICEID (required)
SKU
SERIAL_NUMBER
ICCID
IMEI
MAC_BLE
PACKAGE_SN
OVERPACK_SN

You can also specify the following optional fields:

DEVICE_NAME sets the device name.
GROUP specifies a device group name to set for this device. This will overwrite any existing device groups for the device.

Add from order - Add devices

If you've ordered devices in bulk, you can add all of the devices in the order.

If no orders can be found, this message will be displayed. Orders of "each" devices placed on the Particle store cannot be automatically imported.

New group - product

The New group popup allows you to create or delete device groups.

Export - product

The Export button downloads a CSV file of the devices in this product. It is typically saved in the Downloads folder on your computer by your web browser.

Device options - product

In the Devices list, clicking on the ... button on the right edge provides options:

Mark development device - product

Using Mark development does several things:

Disables fleet flashing to the device. If you are doing active development and flashing your device by USB or OTA directly from Particle Workbench you need to enable Mark Development, otherwise the cloud may immediately overwrite the firmware you flashed with the product default or pinned versions.
Enables override for all typed configuration settings for Tracker devices.
Allows local flashing by USB for devices with device protection enabled (enterprise accounts only).

You can tell which devices have Mark development set by the tool icon to the right of the version number in the product device list.

Unclaim device - product

Unclaim device removes the Owner from the device. Not all product devices need owners, but if you have one set, you can remove it with this option.

Remove device - product

Removes a device from a product.

In order to stop billing for cellular devices in the free or basic plan, make sure you release the SIM card, in addition to removing device. You should release the SIM first, from the SIM cards panel.

If the device has an owner set, it will go into that user's sandbox device list, and will count against their 100 device limit. In order to completely release a device, you must first unclaim device, then remove device. Do the unclaim first, because otherwise the device will disappear from this list before you can unclaim it.

Device details - product

Clicking on a device in the device list brings up the device details panel.

Each of the areas within this window will be discussed separately.

General information - device details - product

This panel shows general information about the device and its current status.

A transition from online to offline may be delayed by 45 minutes or more.
A handshake can last for up to 3 days, so a device that is active and working may have a last handshake in the past.

Controls - device details - product

There are three buttons in the upper right corner of the window:

Signal Tells the device to change the status LED to a rainbow ("nyan") pattern to help find a specific device if you have several.
Ping Sends a request to the device using the Particle cloud to see if it is reachable.
Edit Allows editing of some device settings, see edit device details below.

Location - device details - product

If location storage has been enabled, this panel will show the location of the device on a small map.

This setting is located in the Settings panel for the product.

For non-Tracker devices the location is generally updated once per week
Depending on the device, the location may be approximate, up to a 10,000 meter radius of uncertainty
It may take 24 hours for a device to update its location the first time after enabling location storage

See location for more information.

Events - device details - product

When you click on an event, the details are shown in the center panel.

Clicking Raw shows the raw, unformatted data, which can also be copied to the clipboard.

For a comparison of the various Events panels, see More about events panels, below.

Vitals - device details - product

The Vitals panel shows device health information for a single device. You can choose the time-frame as well.

For more information, see device vitals.

SIM card - device details - product

For cellular devices, information about the SIM card and data usage is available in the SIM card panel.

Environment - device details - product

The Environment panel shows information about environment variables that have been overridden for this device.

For more information, see environment.

Last vitals - device details - product

This panel shows the last device vitals information sent by the device.

The control to the right of Last vitals requests the device send new vitals information, if it's online.
The Download history downloads historical vitals information for this device.

For more information, see device vitals.

Notes - device details - product

Notes can be used for information about the device for your own purposes. You might store:

The specific location of the device
The batch the device came from
Notes about the customer

You can set the notes using the Particle cloud API, or from the Edit button in the upper left corner of the window.

Firmware - device details - product

This panel shows the status of OTA firmware updates for this device.

See OTA firmware updates for more information.

Functions - device details - product

This panel shows functions defined in the device firmware using Particle.function.

Tracker devices have a cmd function for controlling the device remotely. While non-Tracker devices do not include this function, you can implement a similar feature in your own firmware easily.

Monitor One devices also allow the relay on the I/O card to be controlled from a function.

Variables - device details - product

This panel shows variables defined in the device firmware using Particle.variable.

This is the panel for the Monitor One, which allows access to many fields on the I/O card.

Note that you should beware when constantly polling variables from an external service. Each variable request uses one data operation, and if you have a large fleet of devices this can add up quickly. Variables can also only be retrieved when the device is online and not in power-saving sleep mode.

Depending on your application, you may want to use features such as publish or Ledger instead of variables for fleets of devices.

Options - device details - product

These options are also available from the device list in the ... button.