Receiving Actions
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:
Once the action is triggered you will receive a message on MQTT:
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:
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"
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
You can implement the below logic for implementing actions
- On startup subscribe to the actions topic
- When you receive a message from the cloud on the actions topic then
- Send action status as "Received" to notify the client that the action has received. This is optional but a good practice.
- Parse it as json
- Extract the name, id and payload fields
- Execute the action based on the name and payload
- For long running actions periodically send status on the action status topic
- Send "Completed" or "Failed" status at the end of the action.