feat(touch_digit): add ci for example

Author: YanKE01

.gitlab/ci/build.yml

@@ -69,6 +69,14 @@ build_example_ai_esp_dl_human_activity_recognition:
     IMAGE: espressif/idf:release-v5.3
     EXAMPLE_DIR: examples/ai/esp_dl/human_activity_recognition
 
+build_example_ai_esp_dl_touchpad_digit_recognition:
+  extends:
+    - .build_examples_template
+    - .rules:build:example_ai_esp_dl_touchpad_digit_recognition
+  variables:
+    IMAGE: espressif/idf:release-v5.3
+    EXAMPLE_DIR: examples/ai/esp_dl/touchpad_digit_recognition
+
 build_example_audio_wav_player:
   extends:
     - .build_examples_template

.gitlab/ci/rules.yml

@@ -407,6 +407,9 @@
 .patterns-example_ai_esp_dl_human_activity_recognition: &patterns-example_ai_esp_dl_human_activity_recognition
   - "examples/ai/esp_dl/human_activity_recognition/**/*"
 
+.patterns-example_ai_esp_dl_touchpad_digit_recognition: &patterns-example_ai_esp_dl_touchpad_digit_recognition
+  - "examples/ai/esp_dl/touchpad_digit_recognition/**/*"
+
 .patterns-example_audio_wav_player: &patterns-example_audio_wav_player
   - "examples/audio/**/*"
 
@@ -699,6 +702,16 @@
     - <<: *if-dev-push
       changes: *patterns-example_ai_esp_dl_human_activity_recognition
 
+.rules:build:example_ai_esp_dl_touchpad_digit_recognition:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+    - <<: *if-dev-push
+      changes: *patterns-example_ai_esp_dl_touchpad_digit_recognition
+
 .rules:build:example_audio_wav_player:
   rules:
     - <<: *if-protected

examples/.build-rules.yml

@@ -7,6 +7,10 @@ examples/ai/esp_dl/human_activity_recognition:
   enable:
     - if: IDF_TARGET in ["esp32s3","esp32p4"] and (IDF_VERSION_MAJOR == 5 and IDF_VERSION_MINOR == 3)
 
+examples/ai/esp_dl/touchpad_digit_recognition:
+  enable:
+    - if: IDF_TARGET in ["esp32s3"] and (IDF_VERSION_MAJOR == 5 and IDF_VERSION_MINOR == 3)
+
 examples/audio/wav_player:
   enable:
     - if: INCLUDE_DEFAULT == 1

examples/ai/esp_dl/touchpad_digit_recognition/README.md

@@ -14,7 +14,7 @@ In this example, we will demonstrate how to implement the touch driver, train an
 
 ### Touch Processing Flow
 
-
+When a finger moves on the Touchpad, it changes the capacitance value of the Touch channel. By detecting changes in capacitance, the finger's position can be determined. Additionally, through a software interpolation algorithm, the original 6x7 Touch data is expanded to 30x25 for model training. For more details on Touch, you can refer to [Touch Digit Recognition](https://docs.espressif.com/projects/esp-iot-solution/en/latest/ai/touch_digit_recognition.html).
 
 ### AI Processing Flow
 

examples/ai/esp_dl/touchpad_digit_recognition/main/include/normalization_save.h

@@ -8,6 +8,20 @@
 #include "esp_err.h"
 #include "touch_digit.h"
 
+/**
+ * @brief Set the normalization data object
+ *
+ * @param data Pointer to the touch_digit_data_t structure containing
+ *             the normalization data to be saved.
+ * @return esp_err_t Returns ESP_OK on success, or an error code on failure.
+ */
 esp_err_t set_normalization_data(touch_digit_data_t *data);
 
+/**
+ * @brief Get the normalization data object
+ *
+ * @param data Pointer to the touch_digit_data_t structure where the
+ *             retrieved normalization data will be stored.
+ * @return esp_err_t Returns ESP_OK on success, or an error code on failure.
+ */
 esp_err_t get_normalization_data(touch_digit_data_t *data);

examples/ai/esp_dl/touchpad_digit_recognition/main/include/touch_channel.h

@@ -8,19 +8,30 @@
 #include <cstdio>
 #include <iostream>
 
+/**
+ * @brief Touch channel class for managing touch channel data
+ */
 class TouchChannel {
 public:
-    uint32_t max;
-    uint32_t min;
-    uint32_t data;
-    double normalized_data;
-
-    // TouchChannel() :
-    //     max(0), min(UINT32_MAX), normalized_data(0), data(0) {}
+    uint32_t max;            /*!< Maximum value of the channel data */
+    uint32_t min;            /*!< Minimum value of the channel data */
+    uint32_t data;           /*!< Current raw data of the channel */
+    double normalized_data;  /*!< Normalized data in range [0,1] */
 
+    /**
+     * @brief Construct a new Touch Channel object
+     *
+     * @param max Initial maximum value, defaults to 0
+     * @param min Initial minimum value, defaults to UINT32_MAX
+     */
     TouchChannel(uint32_t max = 0, uint32_t min = UINT32_MAX)
         : max(max), min(min),  data(0), normalized_data(0) {}
 
+    /**
+     * @brief Normalize the input data
+     *
+     * @param input_data Raw input data to be normalized
+     */
     void normalize(uint32_t input_data)
     {
         data = input_data;
@@ -33,6 +44,11 @@ class TouchChannel {
         }
     }
 
+    /**
+     * @brief Update the maximum and minimum values of the channel
+     *
+     * @param input_data Raw input data to update max/min values
+     */
     void update_max_min(uint32_t input_data)
     {
         if (input_data > max) {
@@ -44,6 +60,9 @@ class TouchChannel {
         }
     }
 
+    /**
+     * @brief Reset the channel data
+     */
     void reset()
     {
         max = 0;
@@ -52,6 +71,9 @@ class TouchChannel {
         data = 0;
     }
 
+    /**
+     * @brief Print the maximum and minimum values
+     */
     void print()
     {
         std::cout << " max:" << max << " min:" << min << std::endl;

examples/ai/esp_dl/touchpad_digit_recognition/main/include/touch_digit.h

@@ -8,21 +8,50 @@
 #include "esp_err.h"
 #include "touch_channel.h"
 
-#define ROW_CHANNEL_NUM 7
-#define COL_CHANNEL_NUM 6
-#define PRECISION 5
+#define ROW_CHANNEL_NUM 7    /*!< Number of row channels */
+#define COL_CHANNEL_NUM 6    /*!< Number of column channels */
+#define PRECISION 5          /*!< Precision for data processing */
 
+/**
+ * @brief Touch digit data structure
+ */
 typedef struct {
-    TouchChannel row_data[ROW_CHANNEL_NUM];    // 1,3,5,7,9,11,13
-    TouchChannel col_data[COL_CHANNEL_NUM];    // 8,6,4,2,10,12
+    TouchChannel row_data[ROW_CHANNEL_NUM];  /*!< Row channel data array */
+    TouchChannel col_data[COL_CHANNEL_NUM];  /*!< Column channel data array */
 } touch_digit_data_t;
 
+/**
+ * @brief Initialize touch digit recognition
+ *
+ * @return esp_err_t ESP_OK on success, otherwise an error code
+ */
 esp_err_t touch_digit_init(void);
 
+/**
+ * @brief Print touch digit data
+ *
+ * @return esp_err_t ESP_OK on success, otherwise an error code
+ */
 esp_err_t printf_touch_digit_data(void);
 
+/**
+ * @brief Start normalization process
+ *
+ * @return esp_err_t ESP_OK on success, otherwise an error code
+ */
 esp_err_t touch_dight_begin_normalize(void);
 
+/**
+ * @brief End normalization process
+ *
+ * @return esp_err_t ESP_OK on success, otherwise an error code
+ */
 esp_err_t touch_dight_end_normalize(void);
 
+/**
+ * @brief Get normalization state
+ *
+ * @return true if normalization is in progress
+ * @return false if normalization is not in progress
+ */
 bool get_touch_dight_normalize_state(void);

examples/ai/esp_dl/touchpad_digit_recognition/main/include/touch_image.h

@@ -10,19 +10,28 @@
 #include <iostream>
 #include "touch_digit.h"
 
+/**
+ * @brief Touch image class for handling touch data visualization
+ */
 class TouchImage {
 public:
-    uint32_t row_length;
-    uint32_t col_length;
-    uint8_t *data;
+    uint32_t row_length;    /*!< Length of the image row */
+    uint32_t col_length;    /*!< Length of the image column */
+    uint8_t *data;          /*!< Image data buffer */
 
+    /**
+     * @brief Construct a new Touch Image object
+     */
     TouchImage() :
         row_length((ROW_CHANNEL_NUM - 1) * PRECISION), col_length((COL_CHANNEL_NUM - 1) * PRECISION), data(nullptr)
     {
         data = new uint8_t[row_length * col_length];
         this->clear();
     }
 
+    /**
+     * @brief Destroy the Touch Image object
+     */
     ~TouchImage()
     {
         if (data != nullptr) {
@@ -31,23 +40,36 @@ class TouchImage {
         }
     }
 
+    /**
+     * @brief Set pixel value at specified position
+     *
+     * @param x X coordinate
+     * @param y Y coordinate
+     * @param value Pixel value
+     */
     void set_pixel(uint8_t x, uint8_t y, uint8_t value)
     {
         data[x + y * row_length] = value;
     }
 
+    /**
+     * @brief Clear all pixels to zero
+     */
     void clear()
     {
         memset(data, 0, sizeof(uint8_t) * row_length * col_length);
     }
 
+    /**
+     * @brief Print image to console
+     */
     void print()
     {
-        for (int y = 0; y < col_length; y++) { // 遍历行
-            for (int x = 0; x < row_length; x++) { // 遍历列
+        for (int y = 0; y < col_length; y++) {
+            for (int x = 0; x < row_length; x++) {
                 printf(" %c ", data[y * row_length + x] == 0 ? ' ' : '*');
             }
-            printf("\n"); // 换行
+            printf("\n");
         }
     }
 };

examples/ai/esp_dl/touchpad_digit_recognition/main/main.cpp

@@ -27,6 +27,8 @@ static void button_event_cb(void *arg, void *data)
 extern "C" void app_main(void)
 {
     esp_err_t ret;
+
+    /* Initialize NVS */
     ret = nvs_flash_init();
     if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
         ESP_ERROR_CHECK(nvs_flash_erase());
@@ -39,15 +41,20 @@ extern "C" void app_main(void)
     const button_gpio_config_t btn_gpio_cfg = {
         .gpio_num = 0,
         .active_level = 0,
+        .enable_power_save = false,
         .disable_pull = false,
     };
 
+    /* Initialize button for normalization calibration */
     button_handle_t btn = NULL;
     ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_cfg, &btn);
+    // Register callback for button press down to start normalization calibration
     iot_button_register_cb(btn, BUTTON_PRESS_DOWN, NULL, button_event_cb, NULL);
 
+    /* Initialize touch digit */
     touch_digit_init();
 
+    /* Initialize digital tube */
     digital_tube_driver_install(I2C_NUM_0, GPIO_NUM_37, GPIO_NUM_38);
     digital_tube_enable();
 }

examples/ai/esp_dl/touchpad_digit_recognition/main/touch_digit.cpp

@@ -285,7 +285,6 @@ void touch_digit_recognition_task(void *arg)
 
     while (1) {
         if (xQueueReceive(xImageQueue, &image_data, portMAX_DELAY) == pdTRUE) {
-            printf("Result:%d\n", touch_digit_recognition->predict(image_data.data));
             digital_tube_write_num(0, touch_digit_recognition->predict(image_data.data));
             delete [] image_data.data;
         }