Device Claiming

A long treatise on Particle device claiming

What is claiming?

Claiming associates a device with a developer account or customer account. It sets the device's owner.

It's different than:

  • Product membership, which associates a device with a product.
  • SIM activation, which associates a SIM with a developer account or a product.

Each device is identified by its unique Device ID, the 24-character hexadecimal string that uniquely identifies each device. The Device ID never changes, even if the ownership of the device changes.

Do I need to claim my devices?

Probably!

Developer Devices:

For developer (non-product devices), the device must be claimed in order to use any Particle cloud features.

This includes Particle primitives (publish, subscribe, functions, variables) and over-the-air code flashing.

Product Devices:

For devices in a product, you can use unclaimed product devices if:

  • The device firmware does not subscribe to events (including webhook responses)
  • You do not need to use the Wi-Fi device setup SDK for the Photon/P1

However, you still will need to handle product membership and SIM activation even if you do not need to claim the device.

It's also common for cellular products to claim all devices to a single account controlled by the product owner instead of using unclaimed product devices.

When do I need to do it?

Developer Devices:

For developer (non-product devices), the device must be online and breathing cyan in order to claim the device.

Product Devices:

For devices in a product, you can claim the device either:

  • After adding the device to the product (even if it's offline)
  • When the device is online and breathing cyan

The device can be online while unclaimed?

Yes! Device claiming is unrelated to whether a device is online (breathing cyan) or not.

For cellular devices, SIM activation is necessary in order for the device to get online. If the SIM is not activated, then the device will be stuck in blinking green and you will not be able to claim a non-product device until it's online and breathing cyan.

Developer Devices:

For developer (non-product) devices, there's a limit of 100 devices in the developer sandbox in the Free Tier. The device ownership (who claimed it) determines which account this device counts toward the limit for.

Product Devices:

For product devices, claiming is irrelevant. It's the total number of devices that are members of the product that count toward the block limit.

  • Devices that are both claimed to an account and in a product, the device shows up in the developer sandbox device list but does not count toward the 100 device limit, except...
  • If the account has free tier products in it, every device in those product count against the 100 device limit, but may or may not show up in the sandbox device list.

How do I claim a device?

Particle mobile app claiming

Most developers setting up a small number of development kits will use the Particle mobile app to claim their device. For the Argon and Photon (Wi-Fi) the mobile app also sets the Wi-Fi credentials, and sets the setup done bit.

Particle CLI claiming

You can claim the device using the Particle CLI:

particle device add <device-id>

You'll need to know the device ID to add the device this way, and the device must be online and breathing cyan.

A common sequence of events for setting up a Wi-Fi device using the CLI is:

particle identify
particle usb dfu
particle update
particle serial wifi
particle device add <device-id>
particle device rename <device-id> <name>
particle usb setup-done
  • When a new device reboots, it should go into listening mode (blinking dark blue), if not, it can be done by holding down the MODE (or SETUP) button until the status LED blinks dark blue, or by using particle usb listen.

  • The particle identify command prints out the Device ID, which you will need in a later step.

  • The particle usb dfu command puts the device in DFU (blinking yellow) mode. If you have a very old device, this may fail and you will need to use the buttons. Hold down MODE (or SETUP) and tap RESET. Continue to hold down MODE while the status LED blinks magenta (red and blue at the same time) until it blinks yellow, then release.

  • The particle update command updates Device OS on the device.

  • The particle serial wifi command sets the Wi-Fi credentials. This is only necessary for the Photon, P1, and Argon.

  • The particle device add command claims the device to your account.

  • The particle device rename command sets the name of the device (optional).

  • The particle usb setup-done command is only needed for Gen 3 devices such as the Argon or Boron.

setup.particle.io claiming

  • Using setup.particle.io you can set up cellular devices, and also the Photon, as developer devices.

  • This is also the recommended way to set up a small number of Tracker One devices.

  • This is also a good way to activate a small number of developer SIM cards not part of a product.

Web IDE claiming

You can claim a device from the Web IDE. Open the Devices tab and at the bottom is an Add Device option. You'll need to know the device ID to add the device this way, and the device must be online and breathing cyan.

Particle cloud API claiming

You can claim a device using the Particle cloud API claim a device endpoint.

An example of doing this from node.js (Javascript) is node-example-device-cloud-setup. The example can be run locally on your computer, or in your web browser (even if you don't have node installed).

Customer claiming

If you are using customers you will most likely use claim codes, described below.

Product claiming

Product Devices:

For product devices, you can claim the devices while offline by using the Particle cloud API claim a device endpoint. You would typically do this as part of your manufacturing flow.

Unclaiming a device

Console unclaiming

Developer Devices:

For developer (non-product devices), you can unclaim a device from the top level Devices tab. Click the ... button and select Unclaim Device.

Product Devices:

For a product device, open the product then the product devices tab. Click the ... button and select Unclaim Device.

  • Unclaim Device removes the device owner for a product device. This works regardless of whether it's a single owner account, team member, or customer.

  • Remove Device removes the Device ID from the product, making it no longer a product device. If the device still has product firmware on it, it will go into Quarantine until it is flashed with non-product firmware and comes online again.

  • If you want to do both, unclaim first. Otherwise, the device will disappear from the console and you won't have an easy way to unclaim it.

Additionally:

  • Unclaiming a device does not deactivate its SIM!

  • You can unclaim a device while it is offline as it's entirely a cloud-based operation.

Particle CLI unclaiming

You can unclaim the device using the Particle CLI:

particle device remove <device-id>

You must be logged in as the owner of the device to remove it. The device does not need to be online to unclaim.

Particle mobile app unclaiming

You can unclaim developer devices from the Particle mobile app device list, click on the device, then the gear icon, then Unclaim device.

Web IDE unclaiming

You can unclaim developer devices from the Web IDE. Click on the Devices tab, then the device you want to unclaim, the > icon, then the red trash can icon ("Remove devices from account").

Particle cloud API unclaiming

The Particle cloud API unclaim device endpoint is used to unclaim a device. There are two different endpoints, one for developer devices and one for product devices.

Note about Photon unclaiming

When you unclaim a device, it's a cloud-only operation. However, the Photon (and P1) also have a bit on the device that indicates the device has been claimed. If this bit is set the mobile app will warn you that the device has been claimed to another account when you try to claim it. This is merely a user interface issue. The device may in fact be unclaimed, and the mobile app will still allow you to claim it, regardless.

The reason this occurs is that in order to find the Device ID, the mobile app needs to connect to the Photon Wi-Fi configuration network. At this point, it it can no longer access the Particle Cloud to see if the device is really claimed, so it uses the bit on the device as a user interface hint, but it doesn't really affect operation beyond an extraneous warning.

Transferring a device

Developer Devices:

  • You can unclaim the device, then claim it to the new account.

  • If you use the mobile app with the Photon that is not in a product, you can transfer the device immediately.

  • Using the Particle CLI or Web IDE, you can claim the device. If already claimed, you can request a transfer. The the original owner will be emailed and has to respond affirmatively for the transfer to take place.

Product Devices:

  • For product devices, you can unclaim a device from the console whether it's claimed to a single account, team member account, or customer account.

  • Once unclaimed, you can leave it that way, or use one of the claiming methods above to claim it to a different account.

Product membership

Product membership determines whether a given device (identified by its Device ID) can join the product. You generally want some control over this, because it may have billing implications!

Each product can have only one device platform in it. For example, the Argon and Boron need to be in separate products because they have different firmware binaries. However, it then gets more confusing:

  • The Electron and E Series are the same platform and can be in the same product.
  • The Boron and B Series are different platforms and must be in different products.
  • The B4xx (bsom) and B5xx (b5som) are different platforms and must be in different products.
  • The Photon and P1 are different platforms and must be in different products.
  • All Tracker SoM devices (Tracker One and Tracker SoM, both T4xx and T5xx) can be in the same product.

Products are typically identified by their Product ID which is an integer that is unique across all products.

Product firmware

Generally speaking, all devices in a product will be running similar firmware, often the same firmware, though it is possible to subdivide the devices in a product to use different firmware by using Device Groups.

Firmware is uploaded the the console and identified by a version number. This version number is also embedded in the binary by using a macro in the main .cpp or .ino file:

PRODUCT_VERSION(2);

The version number is a 16-bit unsigned integer (1 - 65535).

When a device connects to the cloud, the version in the binary is compared to the version specified for the product default, device group, or a specific device (lock firmware version). If there is a version mismatch, the correct version will be flashed. It's an equality test, so this will either move the version up or down.

Version upgrades and downgrades

You can change the product firmware version by the fleet-wide default, a device group, or for a specific device. This will either happen immediately (intelligent OTA), at the next cloud connection (standard release), immediately on a device-specific basis (lock and flash), or when the device reconnects to the cloud (if offline).

This will either upgrade (move to a higher version number) or downgrade as necessary.

Device firmware includes a target system version. This is the minimum version of Device OS that is required for the firmware to run. If the target system version is greater than the version on the device, the device will go into safe mode (breathing magenta, red and blue at the same time), and then the cloud will update required dependencies such as Device OS (multiple parts if necessary), bootloader, Soft Device (Gen 3), and NCP (Gen 3, rarely).

However, since target system version is a minimum, it is never downgraded. Your firmware that targets an older version of Device OS should generally work on newer versions of Device OS, however the full environment may vary from the way it was before upgrade then downgrade.

Wildcard product firmware

With Device OS 4.0 and later, you must omit the PRODUCT_ID. Essentially all devices behave as if the wildcard product ID was used, and you must pre-add all Device IDs to your product prior to their connecting. It is not possible to use quarantine mode or auto-add with Device OS 4.0 and later.

With Device OS 3.x and earlier, the Product ID is also embedded in the firmware binary:

#ifndef SYSTEM_VERSION_v400ALPHA1
PRODUCT_ID(1234);
#endif

With Device OS 1.5.x, 2.x, and 3.x, it is also possible to use a wildcard product ID:

#ifndef SYSTEM_VERSION_v400ALPHA1
PRODUCT_ID(PLATFORM_ID);
#endif

This is handy if you have multiple products running the same firmware. However, it requires that you add all device IDs to the product ahead of time,

Adding device IDs to a product in advance

You should add Device IDs to products during manufacture. When you order devices in tray or reel quantities from the Particle wholesale store, you get a list of device IDs in the order. You can import the file into the Particle console.

You could also do this on a per-device basis as part of your manufacturing flow.

This is required when using Device OS 4.0 or later, or if using the wildcard PRODUCT_ID macro. Since it is required for later versions, you should plan to switch to pre-adding Device IDs if you have not already done so.

For information about how this affects billing, see Billing for added devices.

Quarantine

Quarantine is only supported for devices running Device OS 3.x and earlier. It is not supported in Device OS 4.0 and later and you should move to pre-adding your Device IDs instead of using quarantine.

If a device has product firmware flashed to it with an explicit PRODUCT_ID defined, but the Device ID has not been added, it will be put into Quarantine by default.

The reason is that without quarantine, anyone who knows your product ID could take any random device and add it to your product.

Quarantine

  • Select a product, then Devicess (1).
  • Expand Denied Devices (2) if necessary.
  • Click Approve if desired.

If a device appears in Denied Devices and you do not want to approve it, make sure it's flashed with non-product firmware. The default Tinker app can be used. The next time the device comes online with non-product firmware it will disappear from the denied devices list.

Auto-approve

Auto-approve is only supported for devices running Device OS 3.x and earlier. It is not supported in Device OS 4.0 and later and you should move to pre-adding your Device IDs instead of using auto-approve or quarantine.

Quarantine Settings

  • Select a product, then Settings (1).
  • Select Auto-Approve (2). This is not recommended and not supported in Device OS 4.0 and later.

SIM activation

setup.particle.io SIM activation

From setup.particle.io you can activate a SIM:

  • In a device with a built-in SIM (Boron, B Series SoM, E Series, Tracker, Electron LTE) from its serial number.
  • A Particle SIM card for use in an Electron 2G/3G from the ICCID on the plastic SIM card.

Mobile app SIM activation

  • As part of the setup process for the Boron, B Series SoM, Electron, or E Series you can activate the SIM from the Particle mobile app.
  • You cannot set up a Tracker One using the mobile app.

Product SIM activation

  • If you add cellular device with an embedded MFF2 SIM to a product, the SIM is automatically activated so you don't need to add a separate step to do that.

  • However for the Electron G350, Electron U260, Electron U270, or Electron ELC314 with a 4FF plastic SIM card, you do need to separately activate the SIM card from the console or cloud API.

Console SIM activation

If you order a 50-pack of Particle SIM cards (plastic 4FF nano SIM cards) you will receive an email with the ICCIDs in the order. You can upload this file from the console to activate all of the SIM cards in bulk. Open the product, SIM Cards, then Import SIM Cards.

You can also activate a single SIM card this way, whether a 4FF plastic SIM card or a built-in MFF2 SMD SIM, using its ICCID.

Cloud API SIM activation

You can activate SIMs using the Particle cloud API:

SIM activation speed

The amount of time it takes to activate or reactivate a SIM may depend on:

  • The device
  • Local conditions (the mobile carrier in your location)
  • Whether you are activating the SIM the first time, or reactivating it after deactivating or releasing ownership of the SIM
SKU Device SIM Activation Speed Lifecycle Replacement
ASSET3G270V2 Asset Tracker 3G (Eur/Asia/Afr) Generally fast2 End of life
ASSET3G260V2 Asset Tracker 3G (Americas/Aus) Generally fast2 End of life
ASSET2GV2 Asset Tracker 2G Generally fast2 End of life
B524MTY B Series LTE CAT-1/3G/2G (EMEAA), Tray [x50] Fast1 GA
B524MEA B Series LTE CAT-1/3G/2G (EMEAA) [x1] Fast1 GA
B523MTY B Series LTE CAT-1/3G/2G (Europe), Tray [x50] Sometimes slow3 Deprecated B524MTY
B523MEA B Series LTE CAT-1/3G/2G (Europe) [x1] Sometimes slow3 NRND B524MEA
B404XMTY B Series LTE CAT-M1 (NorAm), Tray [x50] Fast1 In development
B404XMEA B Series LTE CAT-M1 (NorAm), [x1] Fast1 In development
B404MTY B Series LTE CAT-M1 (NorAm), Tray [x50] Fast1 Deprecated
B404MEA B Series LTE CAT-M1 (NorAm), [x1] Fast1 GA
B402MTY B Series LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 Deprecated B404MTY
B402MEA B Series LTE CAT-M1 (NorAm), [x1] Sometimes slow3 NRND B404MEA
BRN404XTRAY50 Boron LTE CAT-M1 (NorAm), Tray [x50] Fast1 In development
BRN404XKIT Boron LTE CAT-M1 (NorAm) Starter Kit, [x1] Fast1 In development
BRN404X Boron LTE CAT-M1 (NorAm), [x1] Fast1 In development
BRN404TRAY50 Boron LTE CAT-M1 (NorAm), Tray [x50] Fast1 Deprecated
BRN404KIT Boron LTE CAT-M1 (NorAm), Starter Kit [x1] Fast1 GA
BRN404 Boron LTE CAT-M1 (NorAm), [x1] Fast1 GA
BRN402TRAY50 Boron LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 Deprecated BRN404TRAY50
BRN402KIT Boron LTE CAT-M1 (NorAm), Starter Kit [x1] Sometimes slow3 NRND BRN404KIT
BRN402-AQKT Boron LTE CAT-M1 (NorAm) Air Quality Monitor Kit, [x1] Sometimes slow3 End of life
BRN402 Boron LTE CAT-M1 (NorAm), [x1] Sometimes slow3 NRND BRN404
BRN314TRAY50 Boron 2G/3G (Global), Tray [x50] Fast1 Deprecated
BRN314KIT Boron 2G/3G (Global) Starter Kit, [x1] Fast1 NRND-US
BRN310TRAY50 Boron 2G/3G (Global), Tray [x50] Sometimes slow3 Deprecated BRN314TRAY50
BRN310KIT Boron 2G/3G (Global) Starter Kit, [x1] Sometimes slow3 End of life BRN314KIT
E404TRAY50 E Series LTE CAT-M1 (NorAm), Tray [x50] Fast1 Deprecated
E404MOD1 E Series LTE CAT-M1 (NorAm), [x1] Fast1 NRND-US
E404KIT E Series LTE CAT-M1 (NorAm) Evaluation Kit, [x1] Fast1 NRND-US
E402TRAY50 E Series LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 Deprecated E404TRAY50
E402MOD1 E Series LTE CAT-M1 (NorAm), [x1] Sometimes slow3 End of life E404MOD1
E402KIT E Series LTE CAT-M1 (NorAm) Evaluation Kit, [x1] Sometimes slow3 End of life E404KIT
E314TRAY50 E Series 2G/3G (Global - E314), Tray [x50] Fast1 Deprecated
E314MOD1 E Series 2G/3G (Global - E314), [x1] Fast1 NRND-US
E314KIT E Series 2G/3G (Global - E314) Evaluation Kit, [x1] Fast1 NRND-US
E313TRAY50 E Series 2G/3G (Global - E313), Tray [x50] Sometimes slow3 End of life
E313EA E Series 2G/3G (Global - E313), [x1] Sometimes slow3 End of life
E310TRAY50 E Series 2G/3G (Global - E310), Tray [x50] Generally fast2 Deprecated
E310MOD1 E Series 2G/3G (Global - E310), [x1] Generally fast2 End of life E314MOD1
E310KIT E Series 2G/3G (Global - E310) Evaluation Kit, [x1] Generally fast2 End of life E314KIT
E260KIT Electron 2G/3G (Americas/Aus) Starter Kit, [x1] Generally fast2 End of life ELC314TY
E260TRAY50 Electron 2G/3G (Americas/Aus), Tray [x50] Generally fast2 End of life ELC314TY
E270KIT Electron 2G/3G (EMEA) Starter Kit, [x1] Generally fast2 End of life ELC314TY
E270TRAY50 Electron 2G/3G (EMEA), Tray [x50] Generally fast2 End of life ELC314TY
E350KIT Electron 2G Kit (Global) Generally fast2 End of life
E350TRAY50 Electron 2G (Global), Tray [x50] Generally fast2 End of life ELC314TY
ELC314TY Electron 2G/3G (Global - U201) , Tray [x50] Fast1 Deprecated
ELC402EA Electron LTE CAT-M1 (NorAm), [x1] Sometimes slow3 Deprecated ELC404EA
ELC402TY Electron LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 Deprecated ELC404TY
ELC404TY Electron LTE CAT-M1 (NorAm), Tray [x50] Fast1 NRND-US
SNSRKIT3G270 Electron 3G (Eur/Asia/Afr) Sensor Kit, [x1] Generally fast2 End of life
SNSRKIT3G260 Electron 3G (Americas/Aus) Sensor Kit, [x1] Generally fast2 End of life
ONE402MEA Tracker One LTE M1 (NorAm), [x1] Sometimes slow3 NRND ONE404MEA
ONE402MTY Tracker One LTE M1 (NorAm), Bulk [x40] Sometimes slow3 Deprecated ONE404MTY
ONE404MEA Tracker One LTE M1 (NorAm), [x1] Fast1 GA
ONE404MTY Tracker One LTE M1 (NorAm), Bulk [x40] Fast1 Deprecated
ONE523MEA Tracker One LTE CAT1/3G/2G (Europe), [x1] Sometimes slow3 NRND ONE524MEA
ONE523MTY Tracker One CAT1/3G/2G (Europe), Bulk [x40] Sometimes slow3 Deprecated ONE524MTY
ONE524MEA Tracker One LTE CAT1/3G/2G (EMEAA), [x1] Fast1 GA
ONE524MTY Tracker One CAT1/3G/2G (EMEAA), Bulk [x40] Fast1 Deprecated
T402MEA Tracker SoM LTE M1 (NorAm), [x1] Sometimes slow3 NRND T404MEA
T402MKIT Tracker SoM LTE M1 (NorAm) Evaluation Kit, [x1] Sometimes slow3 NRND T404MKIT
T402MTY Tracker SoM LTE M1 (NorAm), Tray [x50] Sometimes slow3 Deprecated T404MTY
T404MEA Tracker SoM LTE M1 (NorAm), [x1] Fast1 GA
T404MKIT Tracker SoM LTE M1 (NorAm) Evaluation Kit, [x1] Fast1 GA
T404MTY Tracker SoM LTE M1 (NorAm), Tray [x50] Fast1 Deprecated
T523MEA Tracker SoM LTE CAT1/3G/2G (Europe), [x1] Sometimes slow3 NRND T524MEA
T523MKIT Tracker SoM LTE CAT1/3G/2G (Europe) Evaluation Kit, [x1] Sometimes slow3 NRND T524MKIT
T523MTY Tracker SoM LTE CAT1/3G/2G (Europe), Tray [x50] Sometimes slow3 Deprecated T524MTY
T524MEA Tracker SoM LTE CAT1/3G/2G (EMEAA), [x1] Fast1 GA
T524MKIT Tracker SoM LTE CAT1/3G/2G (EMEAA) Evaluation Kit, [x1] Fast1 GA
T524MTY Tracker SoM LTE CAT1/3G/2G (EMEAA), Tray [x50] Fast1 Deprecated
  • Fast1, you can generally activate the SIMs and the operation will occur within seconds.

  • Generally fast2 SIM activation generally takes seconds, or up to a minute. On rare occasions, initial SIM activation can take longer, up to a day.

  • Sometimes slow3, the initial activation of a SIM from the factory generally occurs quickly. However, if you've deactivated the SIM, or released ownership of the SIM, reactivation can take tens of minutes, or sometimes days, to complete. Avoid situations where activation will be time-sensitive if possible.

Note that moving a SIM from a developer account (free sandbox) into a product can be done without releasing ownership if the original SIM owner is also a team member. This allows the operation to proceed without disrupting the cellular connection.

Customers

Customers are an optional feature. They allow API access to specific devices typically from a mobile app. They are more common for Wi-Fi products that use the Photon Device Setup SDK and Particle SDK for iOS or Android.

In lieu of customers, many cellular products claim all devices to a single account or use unclaimed product devices. Not using customers does not preclude having a mobile app, it just requires you handle authentication and API access control from your servers instead of having Particle handle it for you. This may be preferable if you are contracting out your development as you can make a generic mobile app using native APIs or a framework with no specific Particle dependencies, which widens the possible number of mobile developers you can use.

There are two types of customers:

  • Simple auth customers
  • Two-legged shadow customers

With simple auth, the user registers with an email address and a password, and Particle handles storing this information and authenticating the user. While theoretically simple, in practice you likely won't be able to avoid having a server at some point. For example, there is no built-in way of handling password reset for simple auth users. MFA (multi-factor authentication) is not supported for simple auth.

With two-legged shadow customers you handle the authentication on your server. This allows you to keep all of the personally identifiable information about your customers on your servers. It's initially more complicated to set up, but in practice the flexibility makes it much more useful.

In both cases, customers are different than normal Particle users in that they are specific to your product and only allow access to certain APIs. Customers cannot access things like the console or Web IDE, OTA code flashing, and cannot access product-level APIs.

Customers normally only get variables and call functions on their own devices. They cannot access other devices in the product fleet.

Remembers that customers are optional! If you already have your own server to handle authentication, you may prefer to make the Particle API calls from your own server. This is especially true for web apps, but is also applicable for mobile apps. It's often a significantly simpler design, especially for cellular devices.

Claim codes

When using the Photon Device Setup SDK for iOS and Android you don't have to worry about claim codes, since it's handled automatically behind the scenes.

However, claim codes solve the problem of having a device add itself to a product and claim without having to divulge a product authentication key to the mobile app. This keeps your product authentication tokens more secure.

The claim code is generated by a cloud API call. This requires an oAuth create customer client ID and secret that only is used for claiming and does not allow access to anything else, so it's safe to hardcode it into your mobile app.

The claim code is passed to the cloud when the device first connects to the cloud. This claims the device to a user or customer.

A claim code alone may also may associate a device with a product. It's still best to associate devices with a product at time of manufacture, but it is also possible to do so with a claim code.

Setting Wi-Fi credentials

Mobile app - Wi-Fi credentials

The Particle mobile app is intended to set up developer devices, and thus it both sets Wi-Fi credentials and claims the device. This is what you want for developer use, but is probably not what you want for products.

Photon setup SDK custom mobile app - Wi-Fi credentials

The Photon setup SDK allows you to create your own white label iOS or Android mobile app that can set up a Photon or P1. It can set up both developer devices as well as simple auth or two-legged shadow auth customers.

It cannot set up an Argon!

Particle CLI - Wi-Fi credentials

With the device in listening mode (blinking dark blue):

particle serial wifi

Setup Done

On Gen 3 devices running Device OS 3.x and earlier, the setup done bit determines if setup has been completed. Until the setup done bit is set, the device will boot into listening mode (blinking dark blue), even if it has valid Wi-Fi credentials (Argon) or SIM activation (Boron, B Series SoM, Tracker).

If you are using Device OS 4.0 and later, there is no setup done bit so you must skip this step.

Mobile app - setup done

If you use the Particle mobile app to set up your devices, the setup done bit will be set upon successful completion of setup.

Particle CLI - setup done

Using the Particle CLI, you can set the setup done bit of a device connected by USB:

particle usb setup-done

This should be done with the device in normal operating mode or listening mode.

Device identifiers

Device ID

This is what is used internally for most device identification. It never changes. It's required for many cloud API calls.

It's always 24 hexadecimal characters (96 bits). You always need to use the whole Device ID, because all of the bits are significant.

Serial number

The Particle serial number uniquely identifies a Particle device and can be used in many places to set up a device instead of the Device ID or ICCID.

It's typically printed under the data matrix (2D barcode, looks like a QR code) on most newer Particle devices.

Newer serial numbers begin with P followed by a 3-digit number. There are also other serial number formats that begin with a model identifier (such as E310).

The serial number is programmed into one-time-programmable (OTP) memory and cannot be changed. Some older Gen 2 devices do not have a serial number.

Data matrix

Most Particle device serial number stickers contain a data matrix code, a 2D barcode that looks like a QR code. This can be decoded by many handheld scanners and phone apps.

On Gen 3 devices the data matrix contains the serial number, a space, and the mobile secret (used during setup over BLE).

On other devices the data matrix only contains the serial number.

Mobile secret

This is used on Gen 3 devices for setup over Bluetooth LE (BLE). It's not unique, but when combined with the serial number, is used for encrypted communication between the mobile app and the device over BLE.

ICCID

This is the 19 to 21 digit number that identifies a SIM card. It always begins with 89.

This is typically used when activating a SIM card, particularly 4FF plastic SIM cards. The number is printed both on the small (4FF nano) as well as the larger plastic card.

IMEI

The IMEI is a unique identifier associated with the cellular modem. While devices with removable SIM card (Electron, Boron) you can swap the SIM card, which changes the ICCID, the IMEI remains constant.

Older Electrons with a u-blox sticker on the modem module, instead of a Particle serial number sticker, have the IMEI encoded in the 2D barcode.

If your device is banned from mobile networks, for example in Turkey if you do not register your device with its telecommunications authority, your device can be banned by IMEI. Thus even changing SIM cards will not allow the device to get online.

Device name

The device name is optional. Within a developer account, the device name is unique.

In products, however, the device name is not unique if devices are claimed to multiple users or customers. Different users or customers can have devices with the same name.

MAC Address

The MAC (media access control) Address uniquely identifies the Wi-Fi radio on the Photon, P1, Argon, and Tracker. It is assigned during manufacture and is typically 12 hexadecimal digits (48 bits).

The Particle Ethernet FeatherWing has a separate MAC address that is randomly assigned a site-local address that is not necessarily globally unique.