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

  • 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

Typically, the Product ID is also embedded in the firmware binary:

PRODUCT_ID(1234);

With Device OS 2.0 and later, it is also possible to use a wildcard product ID:

PRODUCT_ID(PLATFORM_ID);

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

By far the most common, and recommended, way to handle adding devices to products is to add the devices 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 if using the wildcard PRODUCT_ID macro.

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.

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

Auto-approve

Instead of entering quarantine, you can also enable auto-approve so any device with firmware that specifies your product ID will be added to your product automatically. This is not recommended.

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:

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, 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).

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.