Creating registries and devices

This page explains how to create, edit, and delete device registries and devices within them.

A device is a Thing in The Internet of Things. It is a processing unit capable of connecting to the internet (directly or indirectly) and exchanging data with the cloud. A device registry is a device container with shared properties. See Devices for more device and registry details.

If you still need to, complete the Getting started steps before proceeding.

Creating a device registry

To use ClearBlade IoT Core, you must create at least one device registry.

Console

1. Go to the ClearBlade IoT Core console’s Registries page.

2. At the top of the page, click ADD REGISTRY, then select Create registry.

3. Enter a registry ID and select a cloud region. For registry naming and size requirements, see Permitted characters and size requirements.

4. Select the protocols that devices in this registry will use to connect to ClearBlade IoT Core: MQTT, HTTP, or both.

5. Use the Pub/Sub service to create new Pub/Sub topics.

6. Click Create to continue.

API

Creating a registry code samples

Use the DeviceRegistry create method to create a registry.

Node.js

// Client retrieved in callback
// const cloudRegion = 'us-central1';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
import { DeviceManagerClient } from '@clearblade/iot';

// Lookup the pubsub topic
const topicPath = `projects/${projectId}/topics/${pubsubTopicId}`;

const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function createDeviceRegistry() {
  // Construct request
  const newParent = iotClient.locationPath(projectId, cloudRegion);
  const deviceRegistry = {
    eventNotificationConfigs: [
      {
        pubsubTopicName: topicPath
      }
    ],
    id: registryId
  };
  const request = {
    parent: newParent,
    deviceRegistry: deviceRegistry
  };

  const [response] = await iotClient.createDeviceRegistry(request);

  console.log('Successfully created registry');
  console.log(response);
}

createDeviceRegistry();

C#

{
    logger.LogInformation("Create a registry");

    string parent = "projects/developmentenv/locations/us-central1";
    string name = "Sample-New-Registry-2";
    string pubsubTopic = "projects/developmentenv/topics/pubsubTopic";

    RegistryConfigModel registryConfigModel = new RegistryConfigModel()
    {
        Id = name,
    };

    registryConfigModel.EventNotificationConfigs = new List<EventNotificationConfig>();
    var toAdd = new EventNotificationConfig()
    {
        PubsubTopicName = pubsubTopic
    };
    registryConfigModel.EventNotificationConfigs.Add(toAdd);

    var result = await mClient.CreateRegistry(4, parent, registryConfigModel);
    if (!result.Item1 || (result.Item2 == null))
        logger.LogError("Failed to get a device states");
    else
    {
        logger.LogInformation("Successfully obtained the list of device configuration versions");

        // Use the obtained information
    }
}

Python

import os
from clearblade.cloud import iot_v1

def create_registry():
    project_id = 'YOUR_PROJECT_ID'
    cloud_region = 'us-central1'
    pubsub_topic = 'your-pubsub-topic'
    registry_id = 'your-registry-id'
    client = iot_v1.DeviceManagerClient()
    parent = f"projects/{project_id}/locations/{cloud_region}"
    
    if not pubsub_topic.startswith("projects/"):
        pubsub_topic = "projects/{}/topics/{}".format(project_id, pubsub_topic)

    registry = iot_v1.DeviceRegistry(
        eventNotificationConfigs = [{ "pubsubTopicName": pubsub_topic }],
        id = registry_id
    )

    request = iot_v1.CreateDeviceRegistryRequest(parent=parent, device_registry=registry)

    try:
        response = client.create_device_registry(
            request=request
        )
        print("Created registry")
        return response
    except Exception as e:
        print(e)
        raise

os.environ["CLEARBLADE_CONFIGURATION"] = "/path/to/your-credentials.json"
create_registry()

Go

Creating device key pairs

Before creating a device, create a public/private key pair for it. When connecting to ClearBlade IoT Core, each device creates a JSON Web Token (JWT) signed with its private key, which ClearBlade IoT Core authenticates using the device's public key.

Creating or editing a device

Console

1. Go to the ClearBlade IoT Core console’s Registries page.

2. Click the device registry’s ID.

3. Click Devices in the left registry menu.

4. Click Create a device. To edit an existing device, click its ID on the Devices page and click Edit device at the top of the page.

5. Enter a device ID that describes or identifies the device. This field can't be edited later.

6. For Device communication, select Allow or Block. This option allows you to block communication when needed, such as when a device is not functioning properly. You'll most likely want to enable communication when creating the device.

7. If you're creating a new device, select the Input method you wish to use to enter the public key:

Manual: Copy and paste the public key into the Public key value field.
Upload: In the Public key value field, click Browse to select a file on your device.

8. Select the public key format that matches this device’s key pair. Paste the certificate or key in the Public key value field. You can also set the key’s expiration date. To add a key to an existing device, click Add public key on the Device details page.

9. Use the Key and Value fields to add optional device metadata, such as a serial number.

10. Select a Cloud Logging level to determine which device events are sent to Cloud Logging.

11. Click Submit to create the device or Update to save changes to an existing device.

API

Use these methods to create or edit devices:

Device create method to add devices to registries
Device patch method to edit existing devices

Public keys are specified in the Device resource’s credentials field in the ClearBlade IoT Core API when creating a device. You can add or modify this field when updating the device resource. If one or more registry-level certificates are present when adding a new device credential (via device creation or modifications), the public key credential must be signed by one of the registry-level certificates. See the device resource’s DeviceCredential for more information.

For RSA, theDevice.credentials[i].public_key.key field must be set to the rsa_cert.pem contents (including the header and the footer). The Device.credentials[i].public_key.format field must be set to RSA_PEM or RSA_X509_PEM.

For ES256, the Device.credentials[i].public_key.key field must be set to the ec_public.pem contents (including the header and the footer). The Device.credentials[i].public_key.format field must be set to ES256_PEM or ES256_X509_PEM.

Creating a device with RSA credentials code samples

Node.js

C#

Python

Go

Creating a device with Elliptic Curve (EC) credentials code samples

Node.js

C#

Python

Go

Patching a device with RSA credentials code samples

Node.js

C#

Python

Go

Credential and certificate expiration dates

When you create a device and add a public key, you can set the key’s expiration date. If the key was generated with a self-signed X.509 certificate, then the certificate has an expiration date. However, these two expiration dates are separate.

If the key or the self-signed X.509 certificate on the key expires, the device cannot connect to ClearBlade IoT Core. Additionally, if you try to create or update a device with an expired X.509 certificate, ClearBlade IoT Core returns an error.

Getting device details

Console

1. Go to the ClearBlade IoT Core console’s Registries page.

2. Click the device registry’s ID.

3. Click Devices in the left menu.

4. Click the device ID to go to the Device details page. This page summarizes recent device activity, including the last time a message was published and the most recent error time. This page also shows the device numeric ID.

5. Click the Configuration & state history tab to see the device's recent configuration versions and update times.

The fields for the last heartbeat time and the last time a configuration was ACKed are for the MQTT bridge only. The HTTP bridge does not support heartbeat or explicit ACKs.

API

Use these methods to get device details:

Device list method to list a registry’s devices
Device get method to get a device’s details
Device states.list method to list the device state’s last few versions in descending order

Creating registries and devices

Creating a device registry

Console

API

Creating a registry code samples

Node.js

C#

Python

Go

Creating device key pairs

Creating or editing a device

Console

API

Creating a device with RSA credentials code samples

Node.js

C#

Python

Go

Creating a device with Elliptic Curve (EC) credentials code samples

Node.js

C#

Python

Go

Patching a device with RSA credentials code samples

Node.js

C#

Python

Go

Credential and certificate expiration dates

Getting device details

Console

API

Listing the devices in a registry code samples

Node.js

C#

Python

Go

Retrieving a device and its metadata from a device registry code samples

Node.js

C#

Python

Go

Retrieving a device’s state from a device registry code samples

Node.js

C#

Python

Go

Deleting devices and registries

Console

Delete devices

API

Deleting a device from a registry code samples

Node.js

C#

Python

Go

Deleting a registry code samples

Node.js

C#

Python

Go

What's next