Devices, configuration, and state

Device registration

In order for a device to connect, it must first be registered in the device manager. The device manager lets you create and configure device registries and the devices within them. The device manager can be used through the Cloud Platform Console, gcloud commands, or the REST-style API.

Device registries

A device registry is a container of devices.

Each device registry is created in a specific cloud region, and belongs to a cloud project.
A registry is identified in the cloudiot.googleapis.com service by its full name as: projects/{project-id}/locations/{cloud-region}/registries/{registry-id}.
The device registry is configured with one or more Cloud Pub/Sub topics to which telemetry events are published for all devices in that registry. A single topic can be used to collect data across all regions.
Stackdriver monitoring is automatically enabled for each registry.
Identity and Access Management (IAM) can be used for access control, granting users permission to view, provision, or fully manage devices. Note that Cloud IoT Core automatically grants the role cloudiot.serviceAgent to the corresponding service account for each project, in order to enable publishing to Pub/Sub topics.
For information on device registry ID naming and size requirements, see Permitted characters and size requirements.

For details, see the DeviceRegistry resource reference.

Devices

When you create a device within a registry, you define the device as a Cloud IoT Core resource. You can then view device details and control some properties.

A device can be blocked from communicating with Cloud IoT Core. This can be useful when a sensor fails or a device is misconfigured.
Device timestamps show the most recent heartbeat and telemetry event received.
Each device can be identified by its full resource name: projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-id} or projects/{project-id}/locations/{cloud-region}/registries/{registry-id}/devices/{device-numeric-id}. See the next section for more information on the device ID and device numeric ID.

For details, see the Device resource reference.

Be sure to observe the Cloud IoT Core quotas and limits when working with devices.

Device identifiers

Each device has the following identifiers:

A device ID defined by the user. For more information on device ID naming and size requirements, see Permitted characters and size requirements.
A server-generated device numeric ID. The device numeric ID is automatically created by Cloud IoT Core; it's globally unique and not editable. To view a device numeric ID, go to the Device details page.
The full path of the device, as described in the preceding section.

Device metadata

You can define metadata for a device, such as hardware thumbprint, serial number, manufacturer information, or any other attribute. Cloud IoT Core does not interpret or index device metadata. In theory, device metadata is more secure than device state or device configuration because device metadata is never sent to or from a device. This means that, if a device is compromised, the device metadata cannot be read.

Device metadata shouldn't change often; for best results, update it no more often than once per day.

You can define up to 500 key-value pairs when you add or edit a device. Each key must be unique.

For information on device metadata key-value naming and size requirements, see Permitted characters and size requirements.

Device configuration

With Cloud IoT Core, you can control a device by sending it a device configuration. A device configuration is an arbitrary user-defined blob of data sent from Cloud IoT Core to a device. The data can be structured or unstructured. It can also be of any format, such as arbitrary binary data, text, JSON, or serialized protocol buffers.

Device configuration is persisted in storage by Cloud IoT Core. The maximum size for configuration data is 64 KB. For additional limits, see Quotas and Limits.

For best results, a device configuration should focus on desired values or results, rather than on a sequence of commands. If you specify commands, intermediate configuration versions may create conflicts, and it won't be possible to restore the state of a device (without executing every sequence of commands since the device was first initialized). If your configurations emphasize values and results, you'll be able to more easily restore the device state.

Configuration versions

MQTT bridge

For a given MQTT connection, a device receives configurations only in increasing order of version numbers; in other words, it will never be sent a configuration older than its current version. However, if the device reconnects to the MQTT bridge, it may receive an older configuration than it did during the earlier connection (but this should be rare, and the device will eventually receive the latest version).

Note that a device is not guaranteed to receive every configuration update; rather, it will always receive the latest update. If a configuration is being updated rapidly, devices may not receive intermediate versions.

When modifying a device configuration, you can specify the version number to be modified. This protects against overwriting a configuration with concurrent changes.

HTTP bridge

Devices connecting over HTTP can specify the local version (the configuration version on the device). Cloud IoT Core will return only a more recent version, as described in the section on the HTTP bridge.

Device state

Device state information captures the current status of the device, not the environment. Devices can describe their state with an arbitrary user-defined blob of data sent from the device to the cloud. The data can be structured or unstructured. It can also be of any format, such as binary data, text, JSON, or serialized protocol buffers.

Some examples of device state include the health of the device or its firmware version. Typically, device state information is not updated frequently.

Differences between device metadata, configuration, and state

Using configuration and state together, you can answer questions like: What does the device currently "think" it should be doing? How does that compare to the most recent configuration for the device? In contrast, metadata serves primarily as a label or identifier for devices.

Configuration data is sent to the device from Cloud IoT Core. State data is sent by the device to Cloud IoT Core. You can think of configuration as an external instruction sent to a device, and of state as a device's internal representation. Configuration and state data can have the same schema and encoding, or they can be different.

Information that needs to be sent to or from a device should not be stored as device metadata because device metadata stays in the cloud. That information should be in a device configuration if you need to send it to a device, or in device state data if you need to report it back to Cloud IoT Core.

The following example explains the different uses of metadata, configuration, and state using the scenario of devices in a building:

Suppose that you have several devices on each floor in a building. To identify devices on the seventh floor, you could add a 'floor': '7' metadata key-value pair to the devices on the seventh floor. Applying this metadata information provides a way of identifying the devices, but because metadata is not interpreted or indexed, the metadata can only be used for identification purposes.
If you wanted to change the state of the devices in the building, you could send a device configuration to each device. This configuration would comprise an arbitrary blob of data that contains the desired temperature for the device as well as whether the device's lights are turned on or off:
```
{
  temperature: 50
  lights: off
}
```
The configuration alone does not change the temperature of the device or turn its lights on or off; it is up to the device to interpret the configuration and use its own logic to carry out the command. Over the next several hours, the device configuration will not change (unless you update and send a new configuration), but the device's state should change as the temperature increases or decreases and the device turns its lights off.
To verify that the configuration was correctly applied and that the devices are in the correct state, each device can report its state (whether it's on or off, what its temperature is, and that its temperature is less than or equal to 50 degrees) to Cloud IoT Core.

The following table shows the main differences between device metadata, configuration, and state:

	Device metadata	Device configuration	Device state
Description	Defines and classifies devices	Updates a device's state by sending the expected state as a configuration Controls a device by providing commands in a configuration	Captures the current state of a device
Content	Key-value string pairs	Arbitrary user-defined blob of data	Arbitrary user-defined blob of data
Limitations	Keys: Permitted characters: `[a-zA-Z][-a-zA-Z0-9._+~%]+` First character must be a letter (`[a-zA-Z]`) Minimum length: 1 character Maximum length: 128 characters Values: Minimum size: 0 KB Maximum size: 32 KB Maximum combined total size of all device metadata key-value pairs: 256 KB	Maximum size: 64 KB Limited to 1 QPS per device	Maximum size: 64 KB Limited to 1 QPS per device
Use cases	Store a device's serial number and manufacturer information as a key-value pair	Send a configuration containing a firmware version to tell a device which firmware version it should be on Send a reboot command to a device	Retrieve a device's health (such as the frequency of crashes)
Message direction	None	Cloud IoT Core-to-device only	Device-to-Cloud IoT Core only
Recommended frequency	No more often than once per day per device	Less than 0.1 QPS	Less than 0.1 QPS

Changing device behavior or state using configuration data

As noted in the table above, the primary use cases of configuration data are as follows:

Sending a device's expected state as a configuration
Sending a command to a device

Sending the desired state as configuration data

Device configuration data stored in Cloud IoT Core can be used to change the state of a device. For example, suppose the configuration of a device is represented as follows:

DeviceConfig

{
    firmwareVersionRequest: 1.11
}

Your MQTT or HTTP client could interpret this configuration data as instructions for changing the device's state — in this case, check that the device is on firmware version 1.11. The device can then send its state to Cloud IoT Core to show which firmware version it has:

DeviceState

{
    firmwareVersion: 1.11
}

Modeling commands using configuration and state data

Device configuration data stored in Cloud IoT Core can be used to model device commands. For example, suppose the configuration of a device is represented as follows:

DeviceConfig

{
  rebootRequested: true
}

Your MQTT or HTTP client could interpret this configuration data as instructions to execute actions — in this case, send a reboot command. The device can then show the results by reporting its state and showing that one second has elapsed since its last reboot:

DeviceState

{
  last_reboot: 1
}

Structuring configuration data

Configuration data can also be more structured and can include details about the expiration of commands:

DeviceConfig

{
  commands: {
    id1: {
      type: REBOOT
      requestedTimestamp: xxxx
      expirationTimestamp: yyyy
    }
    id2: ...
  }
}

Your client could read these commands and update the device state accordingly, supplying a timestamp for the reboot, and potentially an error message.

DeviceState

{
  commandResults: {
    id1: {
      type: REBOOT
      completedTimestamp: zzzz
      errorMessage: >empty<
    }
    id2: ...
  }
}

This model can be thought of as a command-and-response relationship between the client and devices. If expiration time is used, make sure the device's clock is synchronized.