Devices, configuration, and state

Device registration

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 ClearBlade IoT Core or REST-style API.

Device registries

A device registry is a device container.

• Each device registry is created in a specific cloud region and belongs to a cloud project.

• A registry is identified in the ClearBlade IoT Core 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 that registry's devices. A single topic can be used to collect data across all regions.

• Integrated monitoring, logging, and trace managed services are automatically enabled for each registry.

• Identity and Access Management (IAM) manages access to Google Cloud Pub/Sub, Google Cloud Logging, and Google Cloud Monitoring.

• For 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 it as a ClearBlade IoT Core resource. You can then view device details and control some properties.

• A device can be blocked from communicating with ClearBlade 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 numeric ID.

For details, see the Device resource reference.

Observe the ClearBlade IoT Core device quotas and limits.

Device identifiers

Each device has the following identifiers:

• A user-defined device ID. For device ID naming and size requirements, see Permitted characters and size requirements.

• A server-generated device numeric ID. ClearBlade IoT Core automatically creates the device numeric ID; it's globally unique and not editable. To view a device numeric ID, go to the Device details page.

• The device’s full path is described in the preceding section.

Device metadata

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

Device metadata shouldn't change often; update it no more often than once daily for the best results.

When you add or edit a device, you can define up to 500 key-value pairs, and each key must be unique.

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

Device configuration

With ClearBlade IoT Core, you can control a device by sending it a device configuration. A device configuration is an arbitrary user-defined data blob sent from ClearBlade 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 ClearBlade IoT Core. The maximum configuration data size is 64 KB. For additional limits, see Quotas and limits.

A device configuration should focus on desired values or results rather than a command sequence. If you specify commands, intermediate configuration versions may create conflicts, and restoring the device's state won't be possible (without executing every command sequence since the device was first initialized). You can easily restore the device state if your configurations emphasize values and results.

Configuration versions

MQTT bridge

For a given MQTT connection, a device receives configurations only in increasing order of version numbers; 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).

A device is not guaranteed to receive every configuration update; rather, it will always receive the latest update. Devices may not receive intermediate versions if a configuration is being updated rapidly.

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). ClearBlade IoT Core will return only a more recent version, as described in the HTTP bridge section.

Device state

Device state information captures the device’s status, not the environment. Devices can describe their state with an arbitrary user-defined data blob 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 device state examples include the device’s health and 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 think it should be doing? How does that compare to the most recent device configuration? In contrast, metadata serves primarily as a device label or identifier.

Configuration data is sent to the device from ClearBlade IoT Core. The device sends state data to ClearBlade IoT Core. Configuration is an external instruction sent to a device, and state is a device's internal representation. Configuration and state data can have the same schema and encoding or 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 send it to a device or in device state data if you report it back to ClearBlade 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. Still, because metadata is not interpreted or indexed, the metadata can only be used for identification purposes.

• You could send a configuration to each device to change the building's device state. This would comprise an arbitrary data blob containing the device's desired temperature and whether the device's lights are turned on or off:

  CODE

  {
    temperature: 50
    lights: off
  }

  The configuration alone does not change the device’s temperature or turn its lights on or off; it is up to the device to interpret the configuration and use its 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). Still, the device's state should change as the temperature increases or decreases and the device turns its lights off.

• To verify the configuration was correctly applied, and 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 ClearBlade IoT Core.

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

Changing device behavior or state using configuration data

Sending the desired state as configuration data

Device configuration data stored in ClearBlade IoT Core can be used to change the device’s state. For example, suppose the device’s configuration 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 ClearBlade 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 ClearBlade IoT Core can be used to model device commands. For example, suppose the device’s configuration 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 include command expiration details:

DeviceConfig

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

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

DeviceState

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

This model can be a command-and-response relationship between the client and devices. If the expiration time is used, synchronize the device's clock.