Method: projects.locations.registries.devices.sendCommandToDevice

Sends a command to the specified device.

In order for a device to be able to receive commands, it must: 1) be connected to Cloud IoT Core using the MQTT protocol, and 2) be subscribed to the group of MQTT topics specified by /devices/{device-id}/commands/#. This subscription will receive commands at the top-level topic /devices/{device-id}/commands as well as commands for subfolders, like /devices/{device-id}/commands/subfolder. Note that subscribing to specific subfolders is not supported.

If the command could not be delivered to the device, this method returns an error; in particular, if the device is not subscribed, this method returns FAILED_PRECONDITION. Otherwise, this method returns OK. If the subscription is QoS 1, at least once delivery will be guaranteed; for QoS 0, no acknowledgment is expected from the device.

HTTP request

POST https://cloudiot.googleapis.com/v1/{name=projects/*/locations/*/registries/*/devices/*}:sendCommandToDevice

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

The name of the device. For example, projects/p0/locations/us-central1/registries/registry0/devices/device0 or projects/p0/locations/us-central1/registries/registry0/devices/{numId}.

Authorization requires the following Google IAM permission on the specified resource name:

  • cloudiot.devices.sendCommand

Request body

The request body contains data with the following structure:

JSON representation
{
  "binaryData": string,
  "subfolder": string
}
Fields
binaryData

string (bytes format)

The command data to send to the device.

A base64-encoded string.

subfolder

string

Optional subfolder for the command. If empty, the command will be delivered to the /devices/{device-id}/commands topic, otherwise it will be delivered to the /devices/{device-id}/commands/{subfolder} topic. Multi-level subfolders are allowed. This field must not have more than 256 characters, and must not contain any MQTT wildcards ("+" or "#") or null characters.

Response body

If successful, the response body will be empty.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloudiot
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.