Module Integration Guides
Building a custom client

Receiving Actions

7min

Introduction

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. You can find these in the JSON file downloaded in the section on Connect to Bytebeam cloud

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:

Document image


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

JSON


In the above JSON id is a unique identifier generated each time an action is triggered from the cloud. payload is the text payload that was entered on the cloud.

We need to send a response back to the cloud to indicate progress of executing the command. The response needs to be published on the below topic: /tenants/{tenant_id}/devices/{device_id}/action/status

And the payload will look like this:

JSON


In the above action response

  • id needs to be the same id that was received from Bytebeam.
  • state can be any text to indicuate current status. A long running command might have multiple states. For eg an OTA action might have 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.
  • progress is a number from 1 to 100 and indicates the progress within a given state. For eg if state is "Downloading" and progress is 50 it means 50% of Downlaod is complete. progress is ignored if state is "Completed" or "Failed"

Receiving actions using MQTTX

Open MQTTX and click on the + New Subscription button:



Document image


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

Document image


Hit confirm. You should see the subscription now:

Document image


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

Document image


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



Document image


You will see the action get created with status as "Initiated"

Document image


On MQTTX you should now receive a message like below:

Document image




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:

Document image


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



Document image


Implementing actions in your client

You can implement the below logic for implementing actions

  1. On startup subscribe to the actions topic
  2. When you receive a message from the cloud on the actions topic then
    1. Send action status as "Received" to notify the client that the action has received. This is optional but a good practice.
    2. Parse it as json
    3. Extract the name, id and payload fields
    4. Execute the action based on the name and payload
    5. For long running actions periodically send status on the action status topic
    6. Send "Completed" or "Failed" status at the end of the action.