Getting Started with ESP32 Arduino and ByteBeam Part 3 - Handling Actions

Vaibhav Sharma

Mar 29, 2023 • 4 min read

Learn to create and handle actions on your IoT devices using Bytebeam cloud

Earlier in Part 1 and Part 2, we understood some basic concepts of bytebeam cloud that can be very helpful for your IoT application.

In Part 1 we set up the bytebeam cloud console and Arduino SDK.
In Part 1 we also created a simple touch application and created a dashboard in the bytebeam cloud
In Part 2 we created a bin for new firmware and performed over-the-air firmware updates on our ESP32 device.

Within this article, we will be focusing on action handling using the Bytebeam cloud.

What are Actions

turn on your AC remotely so that you get a nice environment when you reach your home or turn off your lights remotely to save energy bills.

These are some examples of actions that you can add using the bytebeam cloud. An Action has a command-response model. It contains a set of commands that can be used to perform tasks or operations and generates a response on completion. These actions become very handy when you want to control your IoT devices remotely.

How Bytebeam helps with Action Handling

Bytebeam offers this cool feature to create an action using simple steps. Next, we will guide you through the procedure to create an action using the bytebeam cloud and handle the action on your IoT device. Here in this tutorial, we will be using action to toggle ESP32 built-in led

So let's get started.

Hardware Requirements

ESP 32 dev module

Software Requirements

We recommend installing the latest version of all the tools and IDE.

Configuring actions in ESP32

To understand action we will toggle the state of ESP32 built-in led. We will write an action handler to receive action from the bytebeam cloud.

Navigate to File->Examples->BytebeamArduino->ESP32->ToggleLED.
To Setup your Wifi credentials navigate to arduino_secrets.h and place your SSID and password here

//
// Place all the sensitive data here
//

#define SECRET_SSID ""
#define SECRET_PASS ""

Define ESP32 GPIO. ESP32 built-in led is configured at GPIO 2

#define BOARD_LED 2

In setupLED function, we have configured the GPIO mode as OUTPUT

void setupLED() {
  pinMode(BOARD_LED, OUTPUT);
  digitalWrite(BOARD_LED, ledState);
}

Add an action handler using Bytebeam.addActionHandler function. It contains the following arguments
- ToggleLED_Handler: handler function to toggle led
- ToggleLED: action name.

ToggleLED_Hanlder is a handler function to toggle LED. in this callback we will receive action id and custom args.

int ToggleLED_Hanlder(char* args, char* actionId) {
  Serial.println("ToggleLED Action Received !");
  Serial.printf("<--- args : %s, actionId : %s --->\n", args, actionId);

  // toggle the led
  toggleLED();

  // publish led state to device shadow
  if(!publishToDeviceShadow()) {
    // publish action failed status
    if(!Bytebeam.publishActionFailed(actionId)) {
      Serial.println("Failed to publish action failed response for Toggle LED action");
    }

    Serial.println("Failed to publish led state to device shadow");
    return -1;
  }

  // publish action completed status
  if(!Bytebeam.publishActionCompleted(actionId)) {
    Serial.println("Failed to publish action completed response for Toggle LED action");
    return -1;
  }

  return 0;
}

Now upload your example

In the next section, we will add "ToggleLED" action on the bytebeam cloud.

Adding action on bytebeam cloud

Login to your bytebeam cloud account and go to the Device Management tab
Here you can see preconfigured actions like Update Firmware, Update Configuration, and Push File.
To create a new action Click on the Admin tab and then navigate to Actions. Then click on Create Action to configure a new action.

On the next screen, you can see a Type edit text and a drop-down to select Icon.
In Type edit text we need to write down the action name i.e. ToggleLED in our case. Earlier in Configuring actions in the ESP32 section we created an action handler with ToggleLED as the action name.
Then select an icon from the drop-down. We have selected power cord icon for this example. You can choose any from the list. Then hit submit

Now you can find newly created actions on the action.

Triggering an Action

We need to follow these easy steps to trigger an action:

Navigate to the Devices tab under Device Management
Click on the checkboxes to select the list of devices you want to trigger the Action
Click on the Action button you want to trigger. In our case, we have selected a device with #id 1 and triggered 'ToggleLED' Action.
In the Last Action column, you can see the Action status as Queued and you can monitor the progress of the action from the progress bar

In the Last Action column, you can see the Action status as Queued and you can monitor the progress of the action from the progress bar. Next when the device receives the action the status will change to initiated.

After successful execution of the action, the Action status will be charged to Completed.

Conclusion

Actions can be very handy in many use cases. I hope you find this guide useful. We will come up with more interesting tutorials and maker content. Stay tuned.