This page explains how to create, edit, and delete device registries and devices within them.
A device is a "Thing" in "Internet of Things": a processing unit that is capable of connecting to the internet (directly or indirectly) and exchanging data with the cloud. A device registry is a container of devices with shared properties. For more details about devices and registries, see Devices.
If you haven't already, complete the Getting Started steps before proceeding.
Creating a device registry
To use Cloud IoT Core, you must create at least one device registry. You can create a registry using Cloud Console, the API, or gcloud.
Console
- Go to the Registries page in Cloud Console.
At the top of the page, click Create a registry.
Enter a Registry ID and select a cloud region. For information on registry naming and size requirements, see Permitted characters and size requirements.
Select the Protocols that devices in this registry will use to connect to Cloud IoT Core: MQTT, HTTP, or both.
Select a Default telemetry topic or create a new one.
The default topic is used for published telemetry events that don't have a subfolder or if the subfolder used doesn't have a matching Cloud Pub/Sub topic.
(Optional) If you want to publish separate streams of data from a device, add more telemetry topics.
Each topic maps to a subfolder specified in either the MQTT topic path or the HTTP request when the data is published.
To create additional telemetry topics:
a. Click Add more telemetry topics, then click Add topic and subfolder.
b. Select a Pub/Sub topic or create a new one.
c. Enter a descriptive subfolder name.
For information on subfolder naming and size requirements, see Permitted characters and size requirements.
(Optional) Select a Device state topic or create a new one. This topic can be the same as a telemetry topic, or can be used only for state data.
State data is published to Cloud Pub/Sub on a best-effort basis: if publication to the topic fails, it will not be retried. If no topic is defined, device state updates are still persisted internally by Cloud IoT Core, but only the last 10 states are retained.
For more information, see Getting device state.
Click Create to continue.
gcloud
To create a registry, run the gcloud iot registries create
command:
gcloud iot registries create REGISTRY_ID \ --project=PROJECT_ID \ --region=REGION \ [--event-notification-config=topic=TOPIC,[subfolder=SUBFOLDER] [--event-notification-config=...]] [--state-pubsub-topic=STATE_PUBSUB_TOPIC]
In the current release of Cloud IoT Core, the available regions are us-central1
, europe-west1
, and asia-east1
.
You can use the --enable-http-config
and --enable-mqtt-config
flags to enable and disable protocols for the registry. By default, both protocols are enabled.
You can specify multiple Pub/Sub topics and their matching subfolders by repeating the --event-notification-config
flag. If you specify multiple Pub/Sub topics, you should select one default topic that has no accompanying subfolder. This default topic will be used for published telemetry events that don't have a subfolder or if the subfolder used doesn't have a matching Pub/Sub topic. If you don't select a default topic, these telemetry events will be lost.
API
Use the DeviceRegistry create
method to create a registry:
C#
For a sample ofCreateAuthorizedClient
, see Authenticating Applications.
Go
Java
Node.js
For a sample ofgetClient
, see Authenticating Applications.
PHP
Python
This sample uses the Google API Client Library for Python. For a sample ofget client
, see Authenticating Applications.
Ruby
IAM role for Pub/Sub publishing
When you first enable the Cloud IoT Core API for a project, a new service
account for the
project is automatically assigned a role (cloudiot.serviceAgent
) that enables
publishing to all Pub/Sub topics defined in registries within the project. If
you later remove this default role from the relevant project service account, you might
encounter errors. For details,
see Troubleshooting.
Creating a device registry with multiple Pub/Sub topics
As noted in creating a device registry, you must create at least one device registry to use Cloud IoT Core. A registry can have one or more Pub/Sub topics to which devices in the registry can publish data.
You can combine Pub/Sub topics with MQTT/HTTP subfolders to publish telemetry events to separate topics. Each topic maps to a subfolder, so when you publish data to the subfolder, it gets forwarded to the topic. For example, you might have a device that publishes multiple types of data, such as temperature, humidity, and logging data. By directing these data streams to their own individual topics, you can eliminate the need to separate the data into different categories after publishing.
You can map a single Pub/Sub topic to multiple subfolders, but the reverse is not true; each subfolder must be unique and a single subfolder cannot be mapped to different topics.
For detailed information on publishing to separate Pub/Sub topics, see the sections on using the MQTT bridge and using the HTTP bridge.
Creating device key pairs
Before creating a device, first create a public/private key pair for it. When connecting to Cloud IoT Core, each device creates a JSON Web Token (JWT) signed with its private key, which Cloud IoT Core authenticates using the device's public key.
Creating or editing a device
You can create a device or edit an existing one using Cloud Console, the API, or gcloud. Make sure you've created a registry and a key pair before completing the steps in this section.
Console
- Go to the Registries page in Cloud Console.
Click the ID of the registry for the device.
In the registry menu on the left, click Devices.
Click Create a device.
To edit an existing device, click its ID on the Devices page, and then click Edit device at the top of the page.
Enter a Device ID that briefly describes the device or otherwise helps you identify it. (This field can't be edited later.) For information on device naming and size requirements, see Permitted characters and size requirements.
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. In most cases, you'll want to allow communication when first creating the device.
If you're creating a new device, select the Input method you want 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 computer.
Select the Public key format that matches the key pair for this device. Paste the certificate or key in the Public key value field. You can also set an expiration date for the key.
To add a key to an existing device, click Add public key on the Device details page.
Use the Key and Value fields to add optional device metadata, such as a serial number. For information on metadata key-value naming and size requirements, see Permitted characters and size requirements.
Select a Cloud Logging level to determine which device events are sent to Cloud Logging.
Click Create to create the device or Update to save changes to an existing device.
gcloud
To create a device, run the gcloud iot devices create
command.
To create a device with an RSA public key, run the following command:
gcloud iot devices create DEVICE_ID \ --project=PROJECT_ID \ --region=REGION \ --registry=REGISTRY_ID \ --public-key path=rsa_public.pem,type=rsa-pem
To create a device with an RSA public key certificate, run the following command:
gcloud iot devices create DEVICE_ID \ --project=PROJECT_ID \ --region=REGION \ --registry=REGISTRY_ID \ --public-key path=rsa_public.pem,type=rsa-x509-pem
To create a device with an ES256 public key, run the following command:
gcloud iot devices create DEVICE_ID \ --project=PROJECT_ID \ --region=REGION \ --registry=REGISTRY_ID \ --public-key path=ec_public.pem,type=es256-pem
To create a device with an ES256 public key certificate, run the following command:
gcloud iot devices create DEVICE_ID \ --project=PROJECT_ID \ --region=REGION \ --registry=REGISTRY_ID \ --public-key path=ec_public.pem,type=es256-x509-pem
To edit a device, run the gcloud iot devices update
command:
gcloud iot devices update DEVICE_ID \ --project=PROJECT_ID \ --region=REGION \ --registry=REGISTRY_ID \
API
Use the following methods to create or edit devices:
- Device
create
method to add devices to registries - Device
patch
method to edit existing devices
When creating a device, public keys are specified in the credentials
field of the Device
resource in the Cloud IoT Core API. You can also add or modify this field when you update the device resource. If one or more registry-level certificates are present when adding a new device credential (either via device creation or via modifications), the public key credential must be signed by one of the registry-level certificates. See DeviceCredential
in the Device resource for more information.
For RSA, theDevice.credentials[i].public_key.key
field must be set to the contents of rsa_cert.pem
(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 contents of ec_public.pem
(including the header and the footer). The Device.credentials[i].public_key.format
field must be set to ES256_PEM
or ES256_X509_PEM
.
The following sample shows how to create a device with RSA credentials:
The following sample shows how to create a device with Elliptic Curve (EC) credentials:
The following sample shows how to patch a device with RSA credentials:
See the Device Management Samples for more code samples.
Credential and certificate expiration dates
When you create a device and add a public key, you can set an expiration date for the key. If the key was generated with a self-signed X.509 certificate, then the certificate itself also has an expiration date. However, these two expiration dates are separate.
If either the key expires or the self-signed X.509 certificate on the key expires, the device will not be able to connect to Cloud IoT Core. Additionally, if you try to create or update a device with an expired X.509 certificate, Cloud IoT Core returns an error.
Getting device details
You can get details about one or more devices using Cloud Console, the API, or gcloud.
Console
- Go to the Registries page in Cloud Console.
Click the ID of the registry for the device.
In the menu on the left, click Devices.
Click the ID of the device to go to the Device details page. This page summarizes recent device activity, including the last time a message was published and the time of the most recent error. This page also shows the device numeric ID.
Click the Configuration & state history tab to see recent configuration versions and update times for the device.
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.
gcloud
To list the devices in a registry, run the gcloud iot devices list
command:
gcloud iot devices list \ --project=PROJECT_ID \ --registry=REGISTRY_ID \ --region=REGION
To get details about a device, run the gcloud iot devices describe
command:
gcloud iot devices describe DEVICE_ID \ --project=PROJECT_ID \ --registry=REGISTRY_ID \ --region=REGION
API
Use the following methods to get details about devices:
- Device
list
method to list the devices in a registry - Device
get
method to get details about a device - Device
states.list
method to list the last few versions of the device state in descending order
The following sample shows how to list the devices in a registry:
The following sample shows how to retrieve a device and its metadata from a device registry:
The following sample shows how to retrieve device state from a device registry:
See the Device Management Samples for more code samples.
Deleting devices and registries
You can delete devices and registries using Cloud Console, the API, or gcloud. To delete a registry, first delete all the devices within it.
Console
You can delete one or more devices from the registry's list of devices.
To delete devices:
- Go to the Registries page in Cloud Console.
Click the ID of the registry for the device.
In the menu on the left, click Devices.
Select each device you want to delete, then click Delete.
Confirm you want to delete the selected devices, then click Delete.
gcloud
To delete a device, run the gcloud iot devices delete
command:
gcloud iot devices delete DEVICE_ID \ --project=PROJECT_ID \ --registry=REGISTRY_ID \ --region=REGION
To delete a registry, run the gcloud iot registries delete
command:
gcloud iot registries delete REGISTRY_ID \ --project=PROJECT_ID \ --region=REGION
API
Use the following methods to delete devices and registries:
- Device
delete
method to delete a device. - Registries
delete
method to delete a registry
The following sample shows how to delete a device from a registry:
The following sample shows how to delete a registry:
See the Registry Management Samples and Device Management Samples for more code samples.
What's next
- Connect a device over MQTT or HTTP
- Review the Cloud IoT Core quotas and limits