chore: checkpoint 第一版

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal.h

@@ -0,0 +1,92 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_H__
+#define __VOLC_HAL_H__
+
+#include "volc_hal_button.h"
+#include "volc_hal_capture.h"
+#include "volc_hal_display.h"
+#include "volc_hal_player.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define VOLC_DEVICE_NAME_LENGTH 32
+typedef enum {
+    VOLC_HAL_CAPTURE_AUDIO = 0,  // audio capture
+    VOLC_HAL_CAPTURE_VIDEO,      // video capture
+    VOLC_HAL_CAPTURE_MAX,        // Maximum capture count
+} volc_hal_capture_e;
+
+typedef enum {
+    VOLC_HAL_PLAYER_AUDIO = 0,  // audio player
+    VOLC_HAL_PLAYER_VIDEO,      // video player
+    VOLC_HAL_PLAYER_MAX,        // Maximum player count
+} volc_hal_player_e;
+
+/**
+ * @brief All hardware resources handle and context
+ * @details generally,this structure should be singleton
+ *          you can get the Instance by volc_get_global_hal_context()
+ *          And, you just set the value when the hardware submodule be inited
+ *          the function volc_hal_init() just do some necessary initialization actions
+ *          such as, malloc the volc_hal_context_t mem and set the device_name
+ */
+typedef struct {
+    /**
+     * @brief the button handle pointer
+     * @details It should be set value when the volc_hal_button_create() is called
+     */
+    volc_hal_button_t button_handle;
+    /**
+     * @brief the capture pointer array, include audio_capture and video_capture
+     * @details  It should be set value when the volc_hal_capture_create() is called
+     */
+    volc_hal_capture_t capture_handle[VOLC_HAL_CAPTURE_MAX];
+    /**
+     * @brief the display pointer
+     * @details It should be set value when the volc_hal_display_create() is called
+     */
+    volc_hal_display_t display_handle;
+    /**
+     * @brief the player pointer array, include audio_player and video_player 
+     * @details It should be set value when the volc_hal_player_create() is called
+     */
+    volc_hal_player_t player_handle[VOLC_HAL_PLAYER_MAX];
+    /**
+     * @brief the device name, in most cases, it is a mac address
+     * @details It should be set a value when the volc_hal_init() is called
+     */    
+    char device_name[VOLC_DEVICE_NAME_LENGTH];
+} volc_hal_context_t;
+
+/**
+ * @brief Initialize the HAL module
+ * @details Do the necessary actions after the hardware is powered on
+ *          it is not necessary to initialize all the hardware modules
+ *          but it is necessary to set the device name 
+ * 
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_init(void);
+
+/**
+ * @brief return global hal context
+ * @details you can get the singleton Instance  volc_hal_context_t by volc_get_global_hal_context()
+ *          this function could help you get the hal context everywhere
+ *          please be carefully, Do not Modify the return value
+ */
+volc_hal_context_t* volc_get_global_hal_context();
+
+/**
+ * @brief Deinitialize the HAL module
+ */
+void volc_hal_fini(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_button.h

@@ -0,0 +1,59 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_BUTTON_H__
+#define __VOLC_HAL_BUTTON_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void* volc_hal_button_t;
+
+typedef enum {
+    VOLC_BUTTON_PRESS_DOWN = 0, // Button press down event
+    VOLC_BUTTON_PRESS_UP,   // Button press up event
+    VOLC_BUTTON_PRESS_REPEAT, // Button press repeat event
+    VOLC_BUTTON_PRESS_REPEAT_DONE, // Button press repeat done event
+    VOLC_BUTTON_SINGLE_CLICK, // Button single click event
+    VOLC_BUTTON_DOUBLE_CLICK, // Button double click event
+    VOLC_BUTTON_MULTIPLE_CLICK, // Button multiple click event
+    VOLC_BUTTON_LONG_PRESS_START, // Button long press start event
+    VOLC_BUTTON_LONG_PRESS_HOLD, // Button long press hold event
+    VOLC_BUTTON_LONG_PRESS_UP, // Button long press up event
+    VOLC_BUTTON_PRESS_END, // Button press end event
+    VOLC_BUTTON_EVENT_MAX, // Maximum number of button events
+} volc_hal_button_event_e;
+
+typedef void (*volc_hal_button_event_cb_t)(volc_hal_button_t button, volc_hal_button_event_e event, void* user_data);
+
+typedef struct volc_hal_button_config {
+    int gpio_num;                             // GPIO number of the button
+    int active_level;                         // Active level of the button (0 or 1)
+    int long_press_ms;                        // Long press threshold in milliseconds
+    int short_press_ms;                       // Short press threshold in milliseconds
+    int enable_power_save;                    // Whether to enable power save mode (0 or 1)
+    void* user_data;                           // User data pointer
+    volc_hal_button_event_cb_t event_cb;         // Button event callback function
+} volc_hal_button_config_t;
+
+/**
+ * @brief Create a button instance
+ * 
+ * @param config Button configuration
+ * @return volc_hal_button_t Button instance pointer
+ */
+volc_hal_button_t volc_hal_button_create(volc_hal_button_config_t* config);
+
+/**
+ * @brief Destroy a button instance
+ * 
+ * @param button Button instance pointer
+ */
+void volc_hal_button_destroy(volc_hal_button_t button);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_capture.h

@@ -0,0 +1,98 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_CAPTURE_H__
+#define __VOLC_HAL_CAPTURE_H__
+
+#include "volc_hal_type.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+/*
+ * @brief Capture instance pointer
+ */ 
+typedef void* volc_hal_capture_t;
+
+typedef struct {
+    volc_audio_data_type_e data_type; // Audio data type
+    void* user_data;                  // User data pointer
+} volc_hal_frame_info_t;
+
+typedef enum {
+    VOLC_AUDIO_MODE_WAKEUP = 0,
+    VOLC_AUDIO_MODE_CAPTURE,
+} volc_hal_audio_capture_mode_e;
+
+typedef void (*volc_hal_capture_data_cb_t)(volc_hal_capture_t capture, const void* data, int len, volc_hal_frame_info_t* frame_info);
+typedef void (*volc_hal_audio_wakeup_cb_t)(void *event, void *user_data);
+
+typedef struct volc_hal_capture_config {
+    volc_media_type_e media_type;   // Media type
+    volc_hal_capture_data_cb_t data_cb; // Data callback function
+    volc_hal_audio_wakeup_cb_t audio_wakeup_cb; // audio wakeup cb
+    void* user_data;               // User data pointer
+} volc_hal_capture_config_t;
+
+/**
+ * @brief Create a capture instance
+ * @details  To ensure a uniform rate for media capture data, we adopt the callback function approach:
+ *           frame-by-frame audio and video data is delivered asynchronously via callbacks,
+ *           instead of providing an active capture interface.
+ *           Therefore, during the function implementation, a capture thread needs to be created    
+ *           to asynchronously callback the data out.
+ * @note We do not specify specific media configurations (e.g., encoding format, sampling rate, or resolution).
+ *      This is because we expect all the aforementioned parameters to be uniquely determined and immutable across all scenarios.
+ *      Therefore, these values must be fixed at compile time; if your device supports multiple parameters,
+ *      macros should be used to select the desired ones at compile time.
+ *      We consider both voice wake-up and voice data capture to fall under the category of audio capture,
+ *      differing only in mode (internal pipeline).
+ *      For this reason, we do not redesign a separate module for voice wake-up;
+ *      instead, we add an additional mode specifically for voice wake-up.
+ *      Finally, note that acoustic echo cancellation (AEC) must be implemented for audio capture.
+ *      
+ * @param config Capture configuration pointer
+ * @return volc_hal_capture_t Capture instance pointer
+ */
+volc_hal_capture_t volc_hal_capture_create(volc_hal_capture_config_t* config);
+
+/**
+ * @brief Destroy a capture instance
+ * 
+ * @param capture Capture instance pointer
+ */
+void volc_hal_capture_destroy(volc_hal_capture_t capture);
+
+/**
+ * @brief Start a capture instance
+ * 
+ * @param capture Capture instance pointer
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_capture_start(volc_hal_capture_t capture,volc_hal_audio_capture_mode_e mode);
+
+/**
+ * @brief Stop a capture instance
+ * @details you should start your capture thread within this function.
+ * 
+ * @param capture Capture instance pointer
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_capture_stop(volc_hal_capture_t capture);
+
+/**
+ * @brief Update audio capture configuration
+ * @note this function could help you update the capture config
+ *        Please check if it is thread-safe or not;
+ * 
+ * @param capture Capture instance pointer
+ * @param config Capture configuration pointer
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_capture_update_config(volc_hal_capture_t capture, volc_hal_capture_config_t* config);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_display.h

@@ -0,0 +1,85 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_DISPLAY_H__
+#define __VOLC_HAL_DISPLAY_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Display instance pointer
+ */
+typedef void* volc_hal_display_t;
+
+/** This enumeration exists to map to distinct regions of the screen.
+ * Note: Typically, a set of screen display interfaces allows upper-layer callers
+ * to independently create and destroy regions for display purposes.
+ * However, to minimize the development effort of upper-layer business logic,
+ * we do not allow the business side to create and manage different screen regions on their own.
+ * Instead, different screen regions are divided and created during the execution of volc_hal_display_create().
+ * The business layer can only obtain different render layer objects,
+ * pass data to them, and perform rendering operations.
+ * For example, we divide the screen into a status bar(VOLC_DISPLAY_OBJ_STATUS), 
+ * main screen(VOLC_DISPLAY_OBJ_MAIN), and subtitle display bar(VOLC_DISPLAY_OBJ_SUBTITLE).
+ * You may define your own divisions, as all these codes are open-source and modifiable.
+ */
+typedef enum {
+    VOLC_DISPLAY_OBJ_STATUS = 0, // Status display object
+    VOLC_DISPLAY_OBJ_MAIN,          
+    VOLC_DISPLAY_OBJ_SUBTITLE,   // Subtitle display object
+    // VOLC_DISPLAY_OBJ_EMOJI,   // Emoji display object
+    VOLC_DISPLAY_OBJ_MAX,        // Maximum display object count
+} volc_hal_display_obj_e;
+
+typedef enum {
+    VOLC_DISPLAY_TEXT = 0, // Text display type
+    VOLC_DISPLAY_IMAGE,    // Image display type
+    VOLC_DISPLAY_EMOJI     // Emoji display type
+} volc_hal_display_type_e;
+
+typedef struct volc_hal_display_config {
+    int width;             // Width of the display
+    int height;            // Height of the display
+} volc_hal_display_config_t;
+
+/**
+ * @brief Create a Display instance
+ * 
+ * @param config Display configuration
+ * @return volc_hal_display_t Display instance pointer
+ */
+volc_hal_display_t volc_hal_display_create(volc_hal_display_config_t* config);
+
+/**
+ * @brief set brightness 
+ * 
+ * @param display Display instance pointer
+ * @param brightness the brightness value [0,100] 
+ * @return volc_hal_display_t Display instance pointer
+ */
+int volc_hal_display_set_brightness(volc_hal_display_t display, int brightness);
+
+/**
+ * @brief Destroy a Display instance
+ * 
+ * @param display Display instance pointer
+ */
+void volc_hal_display_destroy(volc_hal_display_t display);
+
+/**
+ * @brief Set the display emotion
+ * 
+ * @param display Display instance pointer
+ * @param type Display type (VOLC_DISPLAY_TEXT, VOLC_DISPLAY_IMAGE, or VOLC_DISPLAY_EMOJI)
+ * @param content Content to be displayed (string for text, image pointer for image, emoji string for emoji)
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_display_set_content(volc_hal_display_t display, volc_hal_display_obj_e obj, volc_hal_display_type_e type, const void* content);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_file.h

@@ -0,0 +1,83 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_FILE_H__
+#define __VOLC_HAL_FILE_H__
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * File systems may have different implementations on different devices,
+ * but we generally adhere to the ANSI C style.
+ * For devices without a file system, these interfaces may be left unimplemented
+ * as this is not mandatory.
+ */
+
+/**
+ * @brief file instance pointer
+ */
+typedef void* volc_hal_file_t;
+
+/**
+ * @brief init the file system
+ * @return int 0 if success, otherwise error code
+ */
+int  volc_hal_file_system_init();
+
+/**
+ * @brief open a file instance
+ * @param file_name the file name
+ * @param mode openmode, just follow ANSI C style(fopen)
+ * @return volc_hal_file_t file instance pointer
+ */
+volc_hal_file_t volc_hal_file_open(char* file_name, char* mode);
+
+/**
+ * @brief read the data from the file
+ * @param file the file instance pointer
+ * @param data the data pointer
+ * @param size the data size 
+ * @return return the real read data size 
+ */
+uint64_t volc_hal_file_read(volc_hal_file_t file, void *data, uint64_t size);
+
+/**
+ * @brief write the data from the file
+ * @param file the file instance pointer
+ * @param data the data pointer
+ * @param size the data size 
+ * @return return the real writed data size 
+ */
+uint64_t volc_hal_file_write(volc_hal_file_t file, void *data, uint64_t size);
+
+/**
+ * @brief get the file size
+ * @param file the file instance pointer
+ * @return return the file size 
+ */
+uint64_t volc_hal_file_get_size(volc_hal_file_t file);
+
+/**
+ * @brief get the file size
+ * @param file the file instance pointer
+ * @param offset the file offset (start is 0)
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_file_seek(volc_hal_file_t file,uint64_t offset);
+
+/**
+ * @brief close a file instance
+ * @param mode openmode, just follow ANSI C style(fopen)
+ * @return volc_hal_file_t file instance pointer
+ */
+int volc_hal_file_close(volc_hal_file_t file);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_led.h

@@ -0,0 +1,56 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_LED_H__
+#define __VOLC_HAL_LED_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief LED instance pointer
+ */
+typedef void* volc_led_t;
+
+/**
+ * @brief LED state enumeration
+ */
+typedef enum {
+    VOLC_LED_OFF = 0, // LED off state
+    VOLC_LED_ON,      // LED on state
+} volc_led_state_e;
+
+typedef struct volc_led_config {
+    int gpio_num;          // GPIO number of the LED
+    int active_level;      // Active level of the LED (0 or 1)
+} volc_led_config_t;
+
+/**
+ * @brief Create a LED instance
+ * 
+ * @param config LED configuration
+ * @return volc_led_t LED instance pointer
+ */
+volc_led_t volc_led_create(volc_led_config_t* config);
+
+/**
+ * @brief Destroy a LED instance
+ * 
+ * @param led LED instance pointer
+ */
+void volc_led_destroy(volc_led_t led);
+
+/**
+ * @brief Set the LED state
+ * 
+ * @param led LED instance pointer
+ * @param state LED state (VOLC_LED_OFF, VOLC_LED_ON, or VOLC_LED_BLINK)
+ */
+void volc_led_set_state(volc_led_t led, volc_led_state_e state);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_player.h

@@ -0,0 +1,98 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_PLAYER_H__
+#define __VOLC_HAL_PLAYER_H__
+
+#include "volc_hal_type.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Player instance pointer
+ */
+typedef void* volc_hal_player_t;
+
+typedef struct volc_hal_player_config {
+    volc_media_type_e media_type;   // Media type
+} volc_hal_player_config_t;
+
+/**
+ * @brief Create a player instance
+ * @details this function shoudle set the player_handle value in the volc_hal_context_t structure.
+ * @note We do not specify specific media configurations (e.g., encoding format, sampling rate, or resolution).
+ *      This is because we expect all the aforementioned parameters to be uniquely determined and immutable across all scenarios.
+ *      Therefore, these values must be fixed at compile time; if your device supports multiple parameters,
+ *      macros should be used to select the desired ones at compile time.
+ * 
+ * @param config Player configuration
+ * @return volc_hal_player_t Player instance pointer
+ */
+volc_hal_player_t volc_hal_player_create(volc_hal_player_config_t* config);
+
+/**
+ * @brief set audio player volume
+ * 
+ * @param player Player instance pointer (audio)
+ * @param volume the volume [0,100]
+ * @return int 0 if success 
+ */
+int volc_hal_set_audio_player_volume(volc_hal_player_t player, int volume);
+
+/**
+ * @brief get audio player volume
+ * 
+ * @param player Player instance pointer (audio)
+ * @return the volume
+ */
+int volc_hal_get_audio_player_volume(volc_hal_player_t player);
+
+/**
+ * @brief Destroy a player instance
+ * @details this function shoudle set the player_handle to NULL in the volc_hal_context_t structure.
+ * 
+ * @param player Player instance pointer
+ */
+void volc_hal_player_destroy(volc_hal_player_t player);
+
+/**
+ * @brief Start a player instance
+ * 
+ * @param player Player instance pointer
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_player_start(volc_hal_player_t player);
+
+/**
+ * @brief Stop a player instance
+ * 
+ * @param player Player instance pointer
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_player_stop(volc_hal_player_t player);
+
+/**
+ * @brief Play data with a player instance
+ * @note We have not specified whether this function is sync or async.
+ *       However, it is strongly recommended to implement this function as non-blocking
+ *       with a certain internal buffer, ensuring that the caller of the function
+ *       does not need to overly consider the function's call frequency.    
+ *       For example, the function can be called every 1 second to play 1.2 seconds of audio or video data.
+ * 
+ * @param player Player instance pointer
+ * @param data Data to play
+ * @param len Data length
+ * @return int 0 if success, otherwise error code
+ */
+int volc_hal_player_play_data(volc_hal_player_t player, const void* data, int len);
+void volc_hal_player_discard_pending(volc_hal_player_t player);
+/* Allow a fully received short response to start without filling the prebuffer. */
+void volc_hal_player_finish_segment(volc_hal_player_t player);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

firmware/echoear-platform-agent/components/application/platform/inc/volc_hal_type.h

@@ -0,0 +1,26 @@
+// Copyright (2025) Beijing Volcano Engine Technology Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+#ifndef __VOLC_HAL_TYPE_H__
+#define __VOLC_HAL_TYPE_H__
+
+#include "volc_conv_ai.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Media type enumeration
+ */
+typedef enum volc_media_type {
+    VOLC_MEDIA_TYPE_AUDIO = 0, // Audio media type
+    VOLC_MEDIA_TYPE_VIDEO,     // Video media type
+    VOLC_MEDIA_TYPE_MAX,       // Maximum media type count
+} volc_media_type_e;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif