Adding and claiming devices

There are several ways to get a device into your organisation. This page covers the three you use most: adding a device by hand, letting devices register themselves with the profile’s provisioning key, and claiming a licensed device. For files with many devices see Importing devices in bulk; for LoRaWAN sensors see Add an OTAA device.

The New device drawer

Open Devices and select New device. When your organisation has several ways in, the drawer asks What are you adding?:

A choice appears only when its module is on and you hold its permissions. Choose another way returns to the list.

Add a device by hand

1. In the drawer, choose Other device.
2. Enter a Name (unique in your organisation, up to 128 characters), an optional Label, and pick the Device profile (The default profile when you pick none).
3. Turn on This device is a gateway only for a device that reports for other devices.
4. Select Create device.
5. Copy the access token now: it is shown only once. Select I have stored it when done, or Open device.

Your organisation’s device settings decide whether a new device gets an access token at once: Issue an access token for new devices (on by default; Devices > ⋯ > Settings). If your devices use MQTT basic or X.509, switch it off: the device is then created without a credential and you set one through the API. See Device credentials.

Self-provisioning with a provisioning key

The device knows its profile’s provisioning key and secret. On first start it asks Hermetry for its own credential, so you do not have to create each device beforehand.

Set up the profile

1. Open the profile and its Provisioning tab.
2. Pick the Provisioning strategy:

1. Save, then select Create key in Provisioning keys. Copy the secret: “Copy the secret now. You will not see it again.” Select I have copied it.

The keys table shows each Key id, its State (In use, Old, still accepted, Revoked), Created, Accepted until and Last used. The key buttons act at once; they are not part of Save changes.

What the device sends

Connect over TLS with the username provision and an empty password, subscribe to v1/provision/res, then publish to v1/provision/req:

{"deviceName": "boiler-07", "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60", "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"}

The answer on v1/provision/res:

{"status": "SUCCESS", "credentialsType": "ACCESS_TOKEN", "credentialsValue": "aZ3…"}

The device then logs in with its new credential. Over HTTPS, send the same body to POST /api/v1/provision without a bearer header; a refusal also answers 200, with "status": "FAILURE".

Limits: successful provisions per key per hour (60 by default), 5 requests per device name per hour, and 10 requests per source address per minute.

Replace or revoke a key

• Replace key makes a new key and secret. The old key stays accepted for Days the old key keeps working (30 by default, 0 to 365; 0 stops it at once), then it is revoked automatically. Devices you set up from now on need the new key.
• Revoke stops a key at once and for good. You type the key id and give a reason (“For example: the secret was shared by mistake.”). Devices that already registered keep working.

Claim a licensed device

Licensed routers, gateways and controllers leave the factory with their own identity: a serial number, a certificate and a claim secret. Before you claim one it belongs to no organisation, and Hermetry drops its data.

Claim it

1. Sign in to the device’s local panel and open its Cloud page. Turn on the cloud connection if it is off; the device then connects to Hermetry by itself.
2. Press Open claim window on the same page. The window stays open for 15 minutes.
3. In Hermetry, open Devices > New device and pick the licensed-device choice.
4. Choose how to enter the code:
   • Scan the code on the device’s screen: point your phone’s camera at the QR on the Cloud page and copy the text it shows into the field.
   • Type serial and code: type the Serial (6 to 32 letters, digits and dashes, for example RT420-2610-000123) and the Claim code (20 characters, for example 7KQ2-M9XH-D4TB-6WRA-1NZC).
5. Select Check. On Ready to add, enter a Device name (empty = the serial).
6. Select Add device. “The device was added. It connects within a few seconds when it is online.”

The device is added with a copy of its model’s profile and its X.509 certificate credential. Its connection restarts inside your organisation.

When a claim fails

Claim by API

{
    "serial": "RT420-2610-000123",
    "secret": "7KQ2M9XHD4TB6WRA1NZC",
    "name": "Pump house router"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
  -H 'Content-Type: application/json' \
  -d '{"serial":"RT420-2610-000123","secret":"7KQ2M9XHD4TB6WRA1NZC","name":"Pump house router"}'

{
    "status": "claimed",
    "serial": "RT420-2610-000123",
    "deviceId": "…",
    "model": "…",
    "profileId": "…"
}

{
    "status": "claimable",
    "serial": "RT420-2610-000123",
    "model": "…",
    "type": "…",
    "hw": "…"
}

{
    "message": "The serial or claim code is not correct.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "bad_secret"
    }
}

{
    "message": "…",
    "code": "FEATURE_NOT_AVAILABLE",
    "details": {
        "reason": "device_limit"
    }
}

{
    "message": "Open the claim window on the device's Cloud page (it stays open for 15 minutes), then try again.",
    "code": "CONFLICT",
    "details": {
        "reason": "press_claim_button"
    }
}

{
    "message": "…",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "rate_limited"
    }
}

The 200 answer with "status": "claimable" answers a dry run. A claim of a device your organisation already owns answers 200 with "status": "claimed" and "alreadyOwned": true. A claim still in progress answers {"status": "in_progress", "serial": "…"}. 409 with not_claimable means the serial is unknown, retired or owned by another account.

The Ownership tab and releasing a device

A claimed device’s Ownership tab shows its Serial, Model, Certificate (valid until), and when it was Added to this account. A device created in your account rather than claimed says Not a factory device.

To pass a licensed device to another owner, select Release device on the Ownership tab. The dialog Release this device? explains:

• The device leaves this account and its connection is closed.
• Its data stays in this account’s history.
• The next owner needs physical access to the device to add it.
• A factory reset of the device does not release it: only this action does.

Type the serial to confirm and give an optional reason. The device returns to the factory pool.

A device can also be released with the Release button on its own Cloud page. You then receive a notice “A device released itself from your account”. If nobody in your team did this, contact support.

Related

• Licensed devices
• Device identity and claiming security
• The Devices list and the device page