gcloud Examples

This section provides examples of using the gcloud API to perform several common operations on Cloud IoT Core devices and registries.

Full details are available in the gcloud iot command reference.

Create a registry

gcloud iot registries create my-registry \
    --project=my-iot-project \
    --region=us-central1 \
    --event-notification-config=topic=projects/my-iot-project/topics/device-events

Creates a registry in projects/my-iot-project/locations/us-central1. The telemetry events will be published to the Cloud Pub/Sub topic projects/my-iot-project/topics/device-events.

Create a registry with multiple Cloud Pub/Sub topics

gcloud iot registries create my-registry \
    --project=my-iot-project \
    --region=us-central1 \
    --event-notification-config=topic=projects/my-iot-project/topics/device-events,subfolder=deviceEventsSubfolder \
    --event-notification-config=topic=projects/my-iot-project/topics/default-topic

Creates a registry in projects/my-iot-project/locations/us-central1. The telemetry events published to the deviceEventsSubfolder subfolder will be forwarded to the Cloud Pub/Sub topic projects/my-iot-project/topics/device-events. Any telemetry events published without a subfolder, or with a subfolder that doesn't have a matching Pub/Sub topic, will be forwarded to the default Cloud Pub/Sub topic projects/my-iot-project/topics/default-topic.

Describe a registry

gcloud iot registries describe my-registry \
    --project=my-iot-project \
    --region=us-central1

Describes the device manager attributes of my-registry.

Update a registry

gcloud iot registries update my-registry \
    --project=my-iot-project \
    --region=us-central1 \
    --event-notification-config=topic=projects/my-iot-project/topics/device-events-2

Updates the existing registry my-registry to begin publishing on Cloud Pub/Sub topic projects/my-iot-project/topics/device-events-2.

gcloud iot registries update my-registry \
    --project=my-iot-project \
    --region=us-central1 \
    --enable-mqtt-config \
    --enable-http-config

Updates the existing registry my-registry to enable device connections over MQTT and HTTP.

Delete a registry

gcloud iot registries delete my-registry \
    --project=my-iot-project \
    --region=us-central1

Deletes the registry my-registry. Note that you must delete all of the devices in the registry before you can delete the registry itself; otherwise, the command will fail with an error.

List registries

gcloud iot registries list --project=my-iot-project \
    --region=us-central1

Lists all registries in the project my-iot-project.

Create an RS256 authenticated device

gcloud iot devices create my-rs256-device \
    --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry \
    --public-key path=/path/to/rsa_cert.pem,type=rs256

Creates a device my-rs256-device that will use RS256 authentication in registry my-registry. The public key X509 certificate should be located in /path/to/rsa_cert.pem. The certificate is used for only its public key, and its expiration value is ignored.

Create an ES256 authenticated device

gcloud iot devices create my-es256-device \
    --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry \
    --public-key path=/path/to/ec_public.pem,type=es256

Creates a device my-es256-device that will use ES256 authentication in registry my-registry. The PEM format elliptic curve public key should be located at /path/to/ec_public.pem.

Block or allow communication from a device

gcloud iot devices update my-device \
    --project=example-project \
    --region=us-central1 \
    --registry=my-registry \
    --blocked

Blocks communication from the device my-device. When a device is blocked, it will be disconnected from Cloud IoT Core and will be unable to reconnect. To allow communication, pass --no-blocked to the above command.

Describe a device

gcloud iot devices describe my-device --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry

Describes the device manager attributes of my-device.

List devices

gcloud iot devices list --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry

Lists all devices in registry my-registry.

Delete a device

gcloud iot devices delete my-device --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry

Deletes the device my-device from registry my-registry.

List device configurations

gcloud iot devices configs list --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry \
    --device=my-device \
    --limit=5

Retrieves the latest 5 configurations for your device. Note that Cloud IoT Core stores only the latest 10 versions of your device's configuration; a limit greater than 10 still returns at most 10 configurations.

Retrieve latest device configuration

gcloud iot devices configs describe --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry \
    --device=my-device

Retrieves the latest configuration for the device.

Update device configuration

gcloud iot devices configs update --project=my-iot-project \
    --region=us-central1 \
    --registry=my-registry \
    --device=my-device \
    --config-data="configuration data"

Updates the configuration data for the device, using the data passed in --config-data. You can alternatively use --config-file=my_config.txt to send the contents of a file instead. The config file can use any encoding; the contents will always be sent to the device as raw bytes. Note that configurations are limited to 32 KB.

This command also accepts a --version_to_update argument, which should be the latest version of the config to update. If you include this argument and a newer config version has been pushed (for example, if another user updated the config in the meantime), the update command will fail. To make sure you're specifying the latest version, use the gcloud iot devices configs describe command to retrieve the latest config version. (To update the device's configuration version regardless of the latest version, omit --version_to_update.)

If the device is connected over MQTT and subscribed to the config topic, the config will be pushed to the device immediately. Otherwise, it will be pushed to the device the next time it connects and subscribes to the config topic.

Devices using the HTTP bridge must explicitly request new configurations.

Was this page helpful? Let us know how we did:

Send feedback about...

Google Cloud Internet of Things Core