Tutorial - ESP32 Firmware¶

Files of a Backend Module¶

Each backend module will be represented by a C++ class. The name of this class is deviated by the module name. Tutorial Phase 1 will lead to TutorialPhase1 (all spaces removed).

The backend module class has to be declared in a header file. The name of this file has to be the name of the module directory appended by .h. For our example the name of the header file is tutorial_phase_1.h.

All other files in the module directory which ends with .cpp, .c or .h will be compiled with the firmware independent of their file names.

Files of a Frontend Module¶

Each frontend module can contain the following files (optional):

• api.ts: TypeScript definition of the backend API used by the frontend module.
• main.tsx: TypeScript code of the Preact component for this module.
• translation_de.json: German text translations.
• translation_en.json: English text translations.

Backend Communication Part¶

The backend module represent the data which should be communicated to the frontend module. These data are structured as a ConfigRoot object. In our case it is only one element named color which has a string with exactly 7 byte length. With that we can describe the color in HTML notation #RRGGBB. The value #FF0000 describes color red. This is the corresponding part of tutorial_phase_2.cpp:

void TutorialPhase2::pre_setup()
{
    config = Config::Object({
        {"color", Config::Str("#FF0000", 7, 7)}
    });
}

To communicate the color to the frontend module, the ConfigRoot object has to be published to the API manager. To do that the name tutorial_phase_2/config will be used. API manager automatically polls ConfigRoot every 1000 milliseconds and sends it data to the frontend module. This is the corresponding part of tutorial_phase_2.cpp:

void TutorialPhase2::register_urls()
{
    api.addState("tutorial_phase_2/config", &config);
}

Frontend Communication Part¶

In file api.ts the structure of the data which should be received from the backend is specified:

export interface config
{
    color: string
}

In file main.tsx a event listener for the state of tutorial_phase_2/config is created, to allow the Preact component to receive value changes from the API manager. Inside the lambda function the current value of the tutorial_phase_2/config state is received and the contained color value color is saved in the state of the Preact component:

util.addApiEventListener('tutorial_phase_2/config', () => {
    let config = API.get("tutorial_phase_2/config");

    this.setState({color: config.color});
});

Communication Test¶

To test the communication the color value in tutorial_phase_2.cpp can be changed from #FF0000 (red) to #0000FF (blue):

 void TutorialPhase2::pre_setup()
 {
     config = Config::Object({
         {"color", Config::Str("#0000FF", 7, 7)}
     });
 }

Now in the webinterface blue should be shown:

Frontend Communication Part¶

In main.tsx the code reacts to the change event of the HTML element. On change the current color value of the HTML element is mapped to a new value of tutorial_phase_3/config and transfered to the backend module:

<input class="form-control" type="color" value={this.state.color} onChange={(event) => {
    let config = {color: (event.target as HTMLInputElement).value.toString()};

    API.save("tutorial_phase_3/config", config, __("tutorial_phase_3.script.save_config_failed"));
}} />

Backend Communication Part¶

The backend module represents the data which could be received from the frontend module, structured as a ConfigRoot object. This object is simply a copy of the config_update of the first ConfigRoot object, since it has the same structure. This is the relevant part of tutorial_phase_3.cpp:

 void TutorialPhase3::pre_setup()
 {
     config = Config::Object({
         {"color", Config::Str("#FF0000", 7, 7)}
     });

     config_update = config;
 }

To receive the color value from the frontend module a second ConfigRoot object has to be announced to the API Manager as a command. To do that the name tutorial_phase_3/config_update is used. API Manager receives the data from the frontend module and call a lambda function to handle the data. A message will be printed in the serial console and a new color is saved. This is the relevant part of tutorial_phase_3.cpp:

 void TutorialPhase3::register_urls()
 {
     api.addState("tutorial_phase_3/config", &config);

     api.addCommand("tutorial_phase_3/config_update", &config_update, {}, [this]() {
         String color = config_update.get("color")->asString();

         logger.printfln("Tutorial (Phase 3) module received color update: %s", color.c_str());
         config.get("color")->updateString(color);
     }, false);
 }

Communication Test¶

As a test the color value can be changed from #FF0000 (red) to #00FF00 (green) in the webinterface:

You will find the following message in the serial console: Tutorial (Phase 3) module received color update: #00ff00

Communication Test¶

As a test the color value can be changed in the webinterface from #FF0000 (red) to #00FF00 (green).

Before changing the color to green:

After changing the color to green:

Communicating the Button State¶

For that the file api.ts of the frontend module will be extended to receive the state of the button. We do that by introducing a variable called button. This can't be done by adding it to the existing config state since this can be changed by the frontend module which should not be possible. It should only be readable by the frontend module:

 export interface config
 {
     color: string
 }

 export interface state
 {
     button: boolean
 }

Therefore we introduce a new ConfigRoot object. Here the corresponding lines of tutorial_phase_5.cpp:

 void TutorialPhase5::pre_setup()
 {
     config = Config::Object({
         {"color", Config::Str("#FF0000", 7, 7)}
     });

     config_update = config;

     state = Config::Object({
         {"button", Config::Bool(false)}
     });
 }

The new ConfigRoot object has to be also introduced to the API Manager. For that the name tutorial_phase_5/state will be used, corresponding to the changes in api.ts in the frontend module. Here the lines of tutorial_phase_5.cpp:

 void TutorialPhase5::register_urls()
 {
     api.addState("tutorial_phase_5/config", &config);

     api.addCommand("tutorial_phase_5/config_update", &config_update, {}, [this]() {
         String color = config_update.get("color")->asString();

         logger.printfln("Tutorial (Phase 5) module received color update: %s", color.c_str());
         config.get("color")->updateString(color);
         set_bricklet_color(color);
     }, false);

     api.addState("tutorial_phase_5/state", &state, {}, true);
 }

If the button is pressed we react to this event by introducing the function button_state_changed_handler as a handler for the Button-State-Changed-Callback of the RGB LED Button Bricklet. That means that this function is called if the button is pressed or released and we can react to these events.

Here the corresponding lines of tutorial_phase_5.cpp:

 static void button_state_changed_handler(TF_RGBLEDButton *rgb_led_button, uint8_t state, void *user_data)
 {
     TutorialPhase5 *tutorial = (TutorialPhase5 *)user_data;
     tutorial->state.get("button")->updateBool(state == TF_RGB_LED_BUTTON_BUTTON_STATE_PRESSED);
 }

 void TutorialPhase5::setup()
 {
     if (tf_rgb_led_button_create(&rgb_led_button, nullptr, &hal) != TF_E_OK) {
         logger.printfln("No RGB LED Button Bricklet found, disabling Tutorial (Phase 5) module");
         return;
     }

     set_bricklet_color(config.get("color")->asString());

     tf_rgb_led_button_register_button_state_changed_callback(&rgb_led_button, button_state_changed_handler, this);
     uint8_t state;

     if (tf_rgb_led_button_get_button_state(&rgb_led_button, &state) != TF_E_OK) {
         logger.printfln("Could not get RGB LED Button Bricklet button state");
     } else {
         state.get("button")->updateBool(state == TF_RGB_LED_BUTTON_BUTTON_STATE_PRESSED);
     }

     logger.printfln("Tutorial (Phase 5) module initialized");

     initialized = true;
 }

In main.tsx any change of the tutorial_phase_5/state state will be handled as the color changes are handled before:

util.addApiEventListener('tutorial_phase_5/state', () => {
    let state = API.get("tutorial_phase_5/state");

    this.setState({button: state.button});
});

A button press will be shown in the webinterface:

React to External Color Changes¶

With the standard firmware of the ESP32 Brick all Bricklets connected to the Brick are externally accessible by the the API Bindings. These Bindings are also used by the Brick Viewer. This feature is implemented by the Proxy module. External color changes by the API Bindings are yet not handled by our tutorial module, therefore external color changes will not be shown in the webinterface. We will now fix that.

To handle external color changes by the tutorial module the color of the RGB LED Button Bricklet will be requested all 1000 milliseconds and changes are transmitted by the API manager to the webinterface. Here the corresponding lines of tutorial_phase_5.cpp:

 void TutorialPhase5::setup()
 {
     // ...

     uint8_t button_state;

     if (tf_rgb_led_button_get_button_state(&rgb_led_button, &button_state) != TF_E_OK) {
         logger.printfln("Could not get RGB LED Button Bricklet button state");
     } else {
         state.get("button")->updateBool(button_state == TF_RGB_LED_BUTTON_BUTTON_STATE_PRESSED);
     }

     task_scheduler.scheduleWithFixedDelay([this]() {
         poll_bricklet_color();
     }, 0, 1000);

     logger.printfln("Tutorial (Phase 5) module initialized");

     initialized = true;
 }

 void TutorialPhase5::poll_bricklet_color()
 {
     uint8_t red, green, blue;

     if (tf_rgb_led_button_get_color(&rgb_led_button, &red, &green, &blue) != TF_E_OK) {
         logger.printfln("Could not get RGB LED Button Bricklet color");
         return;
     }

     String color = "#" + num2hex(red) + num2hex(green) + num2hex(blue);
     config.get("color")->updateString(color);
 }

Color change from red to yellow in Brick Viewer:

Now the webinterface will show yellow:

With that the whole communication path between hardware and webinterface is convered by this tutorial.