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:
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
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
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. Select each device you want to delete, then click Delete.
5. Confirm you want to delete the selected devices, then click Delete.
API
Use these methods to delete devices and registries:
Deleting a device from a registry code samples
Node.js
C#
Python
Go
Deleting a registry code samples
Node.js
C#
Python