Receiving Actions

TL;DR

Subscribe to /tenants/{tenant_id}/devices/{device_id}/actions to receive actions and publish the reponse to /tenants/{tenant_id}/devices/{device_id}/action/status in JSON array format.

Introduction

To trigger an action from the cloud follow the guides on Creating new Action Types and Triggering an Action. Let us assume an action called print has been created that prints the payload:

Receiving Action

Actions or commands can be received from Bytebeam by subscribing to the actions MQTT topic:

/tenants/{tenant_id}/devices/{device_id}/actions

Replace {tenant_id} with your project name and {device_id} with the device id.

A device should only subscribe to the topic with tenant it is connected.
_Device will be disconnected if device connected to tenant demo, tries to subscribe to topic with other tenant, say mytenant, e.g. /tenants/mytenant/devices/1/actions

Once the action is triggered you will receive a message on MQTT:

{
  "id": "3620695",
  "name": "print",
  "payload": "Hello World!",
}

here:

• id: An unique identifier generated for this event which will be used to ack back.
• name: Name of the action that is triggered
• payload: Optional payload that is provided while triggering the action

Responding to Action with Action Status

We need to send a response back to the cloud to indicate progress of executing the command. This response must be published to:

/tenants/{tenant_id}/devices/{device_id}/action/status

And the payload should look like this:

[
  {
    "id": "3620695",
    "timestamp": 1710774583249,
    "state": "Completed",
    "errors": [],
    "progress": 100
  }
]

In the above action response:

• id: Must be a string and the same id which was received with action
• timestamp: Timestamp in milliseconds
• state: can be any text to indicuate current status. e.g. A long running commands, like OTA, might have multiple states “Downloading”, “Updating ECU 1”, “Updating ECU 2” so on so forth as statuses.

"Failed" and "Completed" are special terminal states that indicate that the action is complete

• errors: is an array of strings and is looked at only if the state is sent as "Failed". The UI displays these errors. e.g. ["File not found"]
• progress: Percentage in range 0 to 100 indicating progress within a given state. e.g. if state is “Downloading” and progress is 50 it means 50% of Downlaod is complete.

progress is ignored if state is "Completed" or "Failed"

For long running actions, periodically send the action status.

Sending action status as "Received" to notify the server that the action is received is optional but a good practice. Send "Completed" or "Failed" status at the end of the action.

Receiving actions using MQTTX

Open MQTTX and click on the + New Subscription button:

Enter the topic (Replace tenant and device_id) and set QoS to 1:

Hit confirm. You should see the subscription now:

From the device management screen on your project trigger the print command:

This will open up a dialog as shown below. Enter payload and click on “Yes”:

You will see the action get created with status as “Initiated”

On MQTTX you should now receive a message like below:

Notice the id in the payload matches the id on the you see on the UI. Ignore the additional field kind. That field has been deprecated.

You can send progress back as shown below:

Do not forget to set the id to what was received in the message by you and also change demo and device id 2 to your tenant and device id

You should now be able to see the action as completed on the UI