sendCommandToDevice: projects.locations.registries.devices

Sends a command to the specified device.

For a device to receive commands, it must: 1) be connected to ClearBlade 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 and commands for subfolders like /devices/{device-id}/commands/subfolder. Subscribing to specific subfolders is not supported.

If the command cannot 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 one delivery will be guaranteed; for QoS 0, no acknowledgment is expected from the device.

Note: This is a regional API.

You can find the URL, SystemKey, and token required in the call by clicking API Keys (key icon) at the top-right of the Registry Details page. Use the Registry Keys section.

HTTP request

POST {URL}/api/v/4/webhook/execute/{SystemKey}/cloudiot_devices

Query parameters

Parameters

name

string

The device’s name. For example, projects/p0/locations/us-central1/registries/registry0/devices/device0

or

projects/p0/locations/us-central1/registries/registry0/devices/{numId}.

The device’s name can be set to the deviceId or numId (i.e., without the project, location, and registry info. prepended).

method

string
The value must be sendCommandToDevice

Header parameters

Parameters
`ClearBlade-UserToken`	See the note at the start of this document on where to find the token.

Request body

The request body contains data with the following structure:

JSON representation
CODE `{ "binaryData": string, "subfolder": string }`

Fields

binaryData

string (bytes format)

The command data to send to the device.

A base64-encoded string.

subfolder

string

The command’s optional subfolder. The command will be delivered to the /devices/{device-id}/commands topic if empty. 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 not contain any MQTT wildcards ("+" or "#") or null characters.

Response status codes

Code	Meaning
204	Success

Response body

If successful, the response body will be empty.