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?

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:

  • You do not need to use the Wi-Fi device setup SDK for the Photon/P1
  • You do not use webhooks in the sandbox of the user who claimed the device

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

It was previously common for cellular products to claim all devices to a single account controlled by the product owner instead of using unclaimed product devices, but this is no longer necessary.

  • Prior to March 2023, claiming was required if the device firmware subscribed to events on-device. This is no longer necessary.
  • You still need to claim a device is if you are using a webhook in the sandbox of the user who claimed the device. It is recommended that you use product webhooks instead, which do not require claiming.
  • If you are using a device with Mark as Development device, you may want to claim the device to your account so you can easily OTA flash it from Particle Workbench or other development environments.
  • If you previously had firmware that subscribed to events but was the device was unclaimed, the events previously disappeared. This is no longer the case and the device will now start receiving those events, and each event will count as a data operation.
  • Claiming is still allowed, if you prefer to continue to use claiming, but not recommended.

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 plan. 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 plan 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 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. This can be used to upgrade or downgrade to a specific version by using the --target option.

  • 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.

Particle mobile app claiming

The Particle mobile app will be deprecated in the future and should not be used as part of your normal setup flow at this time.

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.

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 Particle 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.
  • Tracker One and Monitor One devices can be in the same product, however because they use Tracker Edge and Monitor Edge firmware, respectively, it's usually not practical to do so.

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 Device OS version. This is the minimum version of Device OS that is required for the firmware to run. If the target Device OS 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 Device OS 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.

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 Deprecated
ASSET3G260V2 Asset Tracker 3G (Americas/Aus) Generally fast2 Deprecated
ASSET2GV2 Asset Tracker 2G Generally fast2 Deprecated
B524MTY B-Series LTE CAT-1/3G/2G (Europe, EtherSIM), Tray [x50] Fast1 GA
B524MEA B-Series LTE CAT-1/3G/2G (Europe, EtherSIM) [x1] Fast1 GA
B523MTY B-Series LTE CAT-1/3G/2G (Europe), Tray [x50] Sometimes slow3 NRND B524MTY
B523MEA B-Series LTE CAT-1/3G/2G (Europe) [x1] Sometimes slow3 Deprecated B524MEA
B404XMTY B-Series LTE CAT-M1 (NorAm, EtherSIM), Tray [x50] Fast1 GA
B404XMEA B-Series LTE CAT-M1 (NorAm, EtherSIM), [x1] Fast1 GA
B404MTY B-Series LTE CAT-M1 (NorAm, EtherSIM), Tray [x50] Fast1 NRND B404XMTY
B404MEA B-Series LTE CAT-M1 (NorAm, EtherSIM), [x1] Fast1 NRND B404XMEA
B402MTY B-Series LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 NRND B404XMTY
B402MEA B-Series LTE CAT-M1 (NorAm), [x1] Sometimes slow3 Deprecated B404XMEA
BRN404XTRAY50 Boron LTE CAT-M1 (NorAm), Tray [x50] Fast1 GA
BRN404XKIT Boron LTE CAT-M1 (NorAm, EtherSIM), Starter Kit [x1] Fast1 GA
BRN404X Boron LTE CAT-M1 (NorAm), [x1] Fast1 GA
BRN404TRAY50 Boron LTE CAT-M1 (NorAm, EtherSIM), Tray [x50] Fast1 Deprecated BRN404XTRAY50
BRN404KIT Boron LTE CAT-M1 (NorAm, EtherSIM), Starter Kit [x1] Fast1 Deprecated BRN404XKIT
BRN404 Boron LTE CAT-M1 (NorAm), [x1] Fast1 Deprecated BRN404X
BRN402TRAY50 Boron LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 NRND BRN404XTRAY50
BRN402KIT Boron LTE CAT-M1 (NorAm), Starter Kit [x1] Sometimes slow3 Deprecated BRN404XKIT
BRN402-AQKT Boron LTE CAT-M1 (NorAm) Air Quality Monitor Kit, [x1] Sometimes slow3 Deprecated
BRN402 Boron LTE CAT-M1 (NorAm), [x1] Sometimes slow3 Deprecated BRN404X
BRN314TRAY50 Boron 2G/3G (Global), Tray [x50] Fast1 NRND
BRN314KIT Boron 2G/3G (Global) Starter Kit, [x1] Fast1 Deprecated
BRN310TRAY50 Boron 2G/3G (Global), Tray [x50] Sometimes slow3 NRND
BRN310KIT Boron 2G/3G (Global) Starter Kit, [x1] Sometimes slow3 Deprecated
E404XTRAY50 E-Series LTE CAT-M1 (NorAm, EtherSIM), Tray [x50] Fast1 GA
E404TRAY50 E-Series LTE CAT-M1 (NorAm, EtherSIM), Tray [x50] Fast1 Deprecated E404XTRAY50
E404MOD1 E-Series LTE CAT-M1 (NorAm, EtherSIM), [x1] Fast1 NRND
E404KIT E-Series LTE CAT-M1 (NorAm, EtherSIM) Evaluation Kit, [x1] Fast1 NRND
E402TRAY50 E-Series LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 NRND E404XTRAY50
E402MOD1 E-Series LTE CAT-M1 (NorAm), [x1] Sometimes slow3 Deprecated
E402KIT E-Series LTE CAT-M1 (NorAm) Evaluation Kit, [x1] Sometimes slow3 NRND
E314TRAY50 E-Series 2G/3G (Global - E314), Tray [x50] Fast1 NRND
E314MOD1 E-Series 2G/3G (Global - E314), [x1] Fast1 Deprecated
E314KIT E-Series 2G/3G (Global - E314) Evaluation Kit, [x1] Fast1 NRND
E313EA E-Series 2G/3G (Global - E313), [x1] Sometimes slow3 Deprecated
E310TRAY50 E-Series 2G/3G (Global - E310), Tray [x50] Generally fast2 Deprecated
E310MOD1 E-Series 2G/3G (Global - E310), [x1] Generally fast2 Deprecated
E310KIT E-Series 2G/3G (Global - E310) Evaluation Kit, [x1] Generally fast2 NRND E314KIT
E260KIT Electron 2G/3G (Americas/Aus) Starter Kit, [x1] Generally fast2 Deprecated BRN404XKIT
E260TRAY50 Electron 2G/3G (Americas/Aus), Tray [x50] Generally fast2 Deprecated BRN404XTRAY50
E270KIT Electron 2G/3G (EMEA) Starter Kit, [x1] Generally fast2 Deprecated B524MEA
E270TRAY50 Electron 2G/3G (EMEA), Tray [x50] Generally fast2 NRND B524MTY
E350KIT Electron 2G Kit (Global) Generally fast2 Deprecated B524MEA
E350TRAY50 Electron 2G (Global), Tray [x50] Generally fast2 Deprecated B524MTY
ELC314TY Electron 2G/3G (Global - U201) , Tray [x50] Fast1 NRND
ELC402EA Electron LTE CAT-M1 (NorAm), [x1] Sometimes slow3 Deprecated BRN404XKIT
ELC402TY Electron LTE CAT-M1 (NorAm), Tray [x50] Sometimes slow3 NRND BRN404XTRAY50
ELC404TY Electron LTE CAT-M1 (NorAm, EtherSIM), Tray [x50] Fast1 Deprecated
SNSRKIT3G270 Electron 3G (Eur/Asia/Afr) Sensor Kit, [x1] Generally fast2 Deprecated
SNSRKIT3G260 Electron 3G (Americas/Aus) Sensor Kit, [x1] Generally fast2 Deprecated
M635MEA M-Series LTE M1/2G/Satellite Kit (Global, EtherSIM), [x1] Fast1 In development
M524MTY M-Series LTE CAT1/3G/2G (Europe, EtherSIM), Tray [x50] Fast1 In development
M524MEA M-Series LTE CAT1/3G/2G (Europe, EtherSIM), [x1] Fast1 In development
M404MTY M-Series LTE M1/2G (Global, EtherSIM), Tray [x50] Fast1 In development
M404MEA M-Series LTE M1/2G (Global, EtherSIM), [x1] Fast1 In development
MON404E01C01KIT Monitor One LTE CAT-M1 (NorAm, EtherSIM), Particle Transparent Enclosure, IO Card, Developer Edition [x1] Fast1 GA
MON404E02C01KIT Monitor One LTE CAT-M1 (NorAm, EtherSIM), Particle Blue Enclosure, IO Card, Developer Edition [x1] Fast1 In development
MON524E01C01KIT Monitor One LTE CAT-1/3G/2G (Europe, EtherSIM), Particle Transparent Enclosure, IO Card, Developer Edition [x1] Fast1 GA
MUONCB Muon Carrier Board Fast1 In development
MUON6XXEA Muon LTE M1/2G/Satellite Kit (Global, EtherSIM), [x1] Fast1 In development
MUON635KIT Muon LTE M1/2G/Satellite Kit (Global, EtherSIM), [x1] Fast1 In development
MUON524KIT Muon LTE CAT1/3G/2G Kit (Europe, EtherSIM), [x1] Fast1 In development
MUON524EA Muon LTE CAT1/3G/2G Kit (Europe, EtherSIM), [x1] Fast1 In development
MUON404KIT Muon LTE M1/2G Kit (Global, EtherSIM), [x1] Fast1 In development
MUON404EA Muon LTE M1/2G Kit (Global, EtherSIM), [x1] Fast1 In development
ONE402MEA Tracker One LTE M1 (NorAm), [x1] Sometimes slow3 Deprecated ONE404MEA
ONE402MTY Tracker One LTE M1 (NorAm), Bulk [x40] Sometimes slow3 Deprecated ONE404MTY
ONE404MEA Tracker One LTE M1 (NorAm, EtherSIM), [x1] Fast1 GA
ONE404MTY Tracker One LTE M1 (NorAm, EtherSIM), Bulk [x40] Fast1 GA
ONE523MEA Tracker One LTE CAT1/3G/2G (Europe), [x1] Sometimes slow3 GA ONE524MEA
ONE523MTY Tracker One CAT1/3G/2G (Europe), Bulk [x40] Sometimes slow3 GA ONE524MTY
ONE524MEA Tracker One LTE CAT1/3G/2G (Europe, EtherSIM), [x1] Fast1 GA
ONE524MTY Tracker One CAT1/3G/2G (Europe, EtherSIM), Bulk [x40] Fast1 GA
T402MEA Tracker SoM LTE M1 (NorAm), [x1] Sometimes slow3 Deprecated T404MEA
T402MKIT Tracker SoM LTE M1 (NorAm) Evaluation Kit, [x1] Sometimes slow3 Deprecated T404MKIT
T402MTY Tracker SoM LTE M1 (NorAm), Tray [x50] Sometimes slow3 NRND T404MTY
T404MEA Tracker SoM LTE M1 (NorAm, EtherSIM), [x1] Fast1 GA
T404MKIT Tracker SoM LTE M1 (NorAm, EtherSIM) Evaluation Kit, [x1] Fast1 GA
T404MTY Tracker SoM LTE M1 (NorAm, EtherSIM), Tray [x50] Fast1 GA
T523MEA Tracker SoM LTE CAT1/3G/2G (Europe), [x1] Sometimes slow3 Deprecated 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 (Europe, EtherSIM), [x1] Fast1 GA
T524MKIT Tracker SoM LTE CAT1/3G/2G (Europe, EtherSIM) Evaluation Kit, [x1] Fast1 GA
T524MTY Tracker SoM LTE CAT1/3G/2G (Europe, EtherSIM), Tray [x50] Fast1 GA
  • 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.

We generally recommend not using customers, unless you are using the device setup SDK for the P1 or Photon. It's generally unnecessary in other cases.

Show older information

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.