Getting Started with ESP32 IDF and Bytebeam Part 5 - update configurations

Learn to update configuration on remote device using Bytebeam

In Earlier parts of this getting started guide, we understood some basic concepts of bytebeam cloud that can be very helpful for your IoT application.

• Earlier in Part 1 we discussed device management and data visualization.
• In Part 2 we performed over the air firmware update on our ESP32 device.
• In Part 3 we created an action on Bytebeam Cloud to toggle the LED on ESP32
• In Part 4 we set up the Logs on ESP32 and created a panel in Bytebeam dashboard to monitor Logs.

Within this article, we will be focusing on updating configurations using the Bytebeam cloud. We will create an application to control the brightness of ESP32 built-in LED using an update configuration feature.

Update configurations using Bytebeam

Bytebeam offers this cool feature to update the configurations of your IoT device. Next, we will guide you through the procedure to receive configurations from actions and to update device configurations using the bytebeam cloud using the following simple steps.

• Setup ESP32 hardware: We will set up ESP32 Built-In LED.
• Configuring update config action on ESP32: We will go through configuring the update configuration action handler in ESP32.
• Creating an action handler to receive configurations: We will create an action handler to receive configurations.
• Configuring  Update Configuration JSON: We will create an update configuration JSON on Bytebeam cloud.
• Monitor Action progress on Bytebeam cloud: In the last section, we will trigger action and monitor its progress on Bytbeam cloud.

So let's get started.

Hardware Requirements

• ESP 32 dev module

Setup ESP32 hardware

• Navigate to esp-bytebeam-sdk -> examples -> update_config -> main -> app_main.c.
• First, declare bytebeam_client_t variable. It is a structure containing host, port, certificates, project id and device id information.

static bytebeam_client_t bytebeam_client;

• ESP32 comes with a built-in LED which is configured at GPIO 2. Define your led GPIO for this example

#define UPDATE_GPIO 2

• Next define the timer, channel, mode and other configurations for the LED

#define LEDC_TIMER              LEDC_TIMER_0            // ledc timer 0 peripheral  
#define LEDC_MODE               LEDC_LOW_SPEED_MODE     // ledc low speed mode 
#define LEDC_OUTPUT_IO          UPDATE_GPIO             // define the output gpio
#define LEDC_CHANNEL            LEDC_CHANNEL_0          // ledc channel0
#define LEDC_DUTY_RES           LEDC_TIMER_13_BIT       // set duty resolution to 13 bits
#define LEDC_FREQUENCY          (5000)                  // frequency in hz Set frequency at 5 kHz
#define LEDC_STEP_SIZE          255                     // set the step size with 8 bits resolution

• Now configure the frequency at which data will be updated to the cloud. We are providing a delay of 1 sec.

#define APP_DELAY_ONE_SEC 1000u

• Initialize led configurations like timer configuration, and channel configurations using   ledc_init().

static void ledc_init(void)
{
    // prepare and then apply the ledc pwm timer configuration
    ledc_timer_config_t ledc_timer = {
        .speed_mode       = LEDC_MODE,
        .timer_num        = LEDC_TIMER,
        .duty_resolution  = LEDC_DUTY_RES,
        .freq_hz          = LEDC_FREQUENCY,
        .clk_cfg          = LEDC_AUTO_CLK
    };
    ESP_ERROR_CHECK(ledc_timer_config(&ledc_timer));

    // prepare and then apply the ledc pwm channel configuration
    ledc_channel_config_t ledc_channel = {
        .speed_mode     = LEDC_MODE,
        .channel        = LEDC_CHANNEL,
        .timer_sel      = LEDC_TIMER_0,
        .intr_type      = LEDC_INTR_DISABLE,
        .gpio_num       = LEDC_OUTPUT_IO,
        .duty           = 0,
        .hpoint         = 0
    };
    ESP_ERROR_CHECK(ledc_channel_config(&ledc_channel));
}

• update_led() function sets the duty cycle for led and updates the set duty cycle.

static void update_led(void) 
{
    // set the new duty cycle for update gpio led
    ledc_set_duty(LEDC_MODE, LEDC_CHANNEL, led_duty_cycle);
    ESP_LOGI(TAG, " LED Duty Cycle Value is %d!", (int)led_duty_cycle);

    // update the new duty cycle for update gpio led
    ledc_update_duty(LEDC_MODE, LEDC_CHANNEL);
}

Configuring update config action on ESP32

In this section, we will start the bytebeam client, add the action handler and provide a name to our handler

• Navigate to app_main(), and call ledc_init() to initialise the led configuration.
• Next, initialise the bytebeam client.

// initialize the bytebeam client
bytebeam_init(&bytebeam_client);

• Add an action handler using the bytebeam_add_action_handler function. It contains the following arguments
  • bytebeam_client: reference to bytebeam client. this is a structure containing host, port, certificates and device id information
  • handle_update_config: handler function to update configurations
  • update_config: action name.

 // add the handler for update config action
 bytebeam_add_action_handler(&bytebeam_client, handle_update_config, "update_config");

• Next, start the bytebeam client

// start the bytebeam client
bytebeam_start(&bytebeam_client);

Creating an action handler to receive configurations

In this section, we will create an action handler to parse action arguments and control the LED duty cycle.

• In the last section, we added a handle_update_config action handler function using bytebeam_add_action_handler

• handle_update_config contains the following arguments
  • bytebeam_client: reference to bytebeam client. this is a structure containing host, port, certificates and device id information
  • args: configuration JSON received for bytebeam cloud.
  • action_id: id of update_config action.

int handle_update_config(bytebeam_client_t *bytebeam_client, char *args, char *action_id) 

• Inside the handle_update_config function, first, parse the update config JSON.

cJSON *root = NULL;
root = cJSON_Parse(args);

• In the received JSON we have the step_value object which contains the duty cycle information for led. parse step_value and set up the duty cycle of led accordingly.

step_value = cJSON_GetObjectItem(root, "step_value");

ESP_LOGI(TAG, "Checking update config step value %d\n", (int)step_value->valuedouble);

// Generate the duty cycle for the led
uint32_t ledc_res = (uint32_t)round(pow(2,LEDC_DUTY_RES)) - 1;
led_duty_cycle = ((ledc_res) * (step_value->valuedouble/LEDC_STEP_SIZE));

Configuring  Update Configuration JSON

In this section, we will create update configuration JSON for the respective device id. Before going further create a new device in the bytebeam cloud.

• Provision your ESP32 device with device_config.json as we did in Part 1 of this series.
• Now navigate to the Device Configs panel and click on NewDevice Config.

• Here provide Version Name and Configuration JSON.

• Configuration JSON can be configured according to your use case. For this example, Configuration JSON contains the following objects
  • name: name of your configuration
  • version: version of your configuration
  • step_value: step value can be any integer in the range of 0 to 255

{
  "name": "update_config",
  "version": "v1",
  "step_value": 30
}

• Click on Create to create device configurations.
• Next, check the respective device and click on Update Configurations.

• Select your device configuration version and hit Update.

Monitor Action progress on Bytebeam cloud

• 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

Using update configuration feature of bytebeam you can serve many use cases in run time. Check out our other guides on Data visualization, OTA, Handling actions and Remote Debugging as well. I hope you find this guide useful. We will come up with more interesting tutorials and maker content. Stay tuned.