chore: initial commit

components/platform/internal/lcd.h

@@ -0,0 +1,65 @@
+#pragma once
+
+#include "esp_err.h"
+#include "platform.h"
+
+/**
+ * @brief Initialize the LCD device and LVGL display pipeline.
+ */
+esp_err_t lcd_init_device(void);
+
+/**
+ * @brief Enable LCD backlight.
+ */
+void lcd_backlight_on(void);
+
+/**
+ * @brief Start the LVGL render loop and show the default screen.
+ *
+ * This function is blocking and is expected to run in a dedicated task.
+ * Calling it while the render loop is already running is a no-op.
+ */
+void lcd_start_render_loop(void);
+
+/**
+ * @brief Request the running LVGL render loop to stop.
+ *
+ * This API is idempotent; calling it when the render loop is not running is safe.
+ * `timeout_ms < 0` is invalid; `0` requests async stop; positive values wait
+ * up to the bound and force-delete the render task on timeout.
+ */
+esp_err_t lcd_stop_render_loop(int timeout_ms);
+
+/**
+ * @brief Queue a LCD presentation request.
+ *
+ * This API is non-blocking and safe to call from non-LVGL tasks.
+ */
+esp_err_t lcd_request_presentation(const platform_lcd_presentation_request_t *request);
+
+/**
+ * @brief Queue a LCD presentation asset preload.
+ *
+ * This API is non-blocking and safe to call from non-LVGL tasks.
+ */
+esp_err_t lcd_preheat_presentation(const platform_lcd_presentation_request_t *request);
+
+/**
+ * @brief Read the LCD presentation completion counter.
+ *
+ * Incremented each time a finite asset-sequence presentation finishes its
+ * configured cycles. Safe to call from non-LVGL tasks.
+ */
+uint32_t lcd_presentation_completion_count(void);
+
+/**
+ * @brief Block until the completion counter advances past @p since_count or
+ *        @p timeout_ms elapses.
+ *
+ * Pair with a lcd_presentation_completion_count() snapshot taken before queuing
+ * a finite asset sequence. Returns ESP_OK on completion, ESP_ERR_TIMEOUT on
+ * timeout, ESP_ERR_INVALID_STATE if the LCD is not running or is stopping. A
+ * zero timeout polls once. Safe to call from non-LVGL tasks; never call from
+ * the LVGL render task.
+ */
+esp_err_t lcd_wait_presentation_completion(uint32_t since_count, uint32_t timeout_ms);

components/platform/internal/lcd_face.h

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+#include "lvgl.h"
+
+typedef struct {
+    const char *asset_dir;
+    const uint8_t *frame_order;
+    size_t frame_order_count;
+    uint16_t repeat_count;
+    uint32_t frame_ms;
+    bool return_to_idle;
+} lcd_face_asset_sequence_t;
+
+/**
+ * @brief Create the default cat-face idle screen on the active LVGL screen.
+ */
+esp_err_t lcd_face_create_idle_screen(lv_obj_t *screen);
+
+/**
+ * @brief Restore the default cat-face idle screen.
+ */
+esp_err_t lcd_face_show_idle(lv_obj_t *screen);
+
+/**
+ * @brief Play a frame sequence from an animation asset directory.
+ */
+esp_err_t lcd_face_play_asset_sequence(lv_obj_t *screen, const lcd_face_asset_sequence_t *sequence);
+
+/**
+ * @brief Preload a frame sequence into the animation cache.
+ *
+ * `decode_budget` limits how many compressed frames are decoded during this
+ * call. Pass `SIZE_MAX` to finish synchronously.
+ */
+esp_err_t lcd_face_preheat_asset_sequence(const lcd_face_asset_sequence_t *sequence,
+                                          size_t decode_budget,
+                                          bool *out_complete);
+
+/**
+ * @brief Consume a completed finite asset-sequence signal.
+ */
+bool lcd_face_take_completed(bool *out_return_to_idle);

components/platform/internal/multimodal/audio_pipeline.h

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef esp_err_t (*multimodal_audio_uplink_cb_t)(const uint8_t *data, size_t len, void *ctx);
+
+typedef enum {
+    MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_STARTED = 0,
+    MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_COMPLETED,
+    MULTIMODAL_AUDIO_DOWNSTREAM_PLAYBACK_STOPPED,
+} multimodal_audio_downstream_playback_event_type_t;
+
+typedef struct {
+    multimodal_audio_downstream_playback_event_type_t type;
+} multimodal_audio_downstream_playback_event_t;
+
+typedef void (*multimodal_audio_downstream_playback_callback_t)(
+        const multimodal_audio_downstream_playback_event_t *event,
+        void *ctx);
+
+esp_err_t multimodal_audio_init(void);
+void multimodal_audio_deinit(void);
+
+esp_err_t multimodal_audio_start_uplink(multimodal_audio_uplink_cb_t cb, void *cb_ctx);
+esp_err_t multimodal_audio_stop_uplink(int timeout_ms);
+bool multimodal_audio_is_uplink_running(void);
+bool multimodal_audio_is_initialized(void);
+
+esp_err_t multimodal_audio_handle_downstream_opus(const uint8_t *data, size_t len);
+esp_err_t multimodal_audio_begin_downstream_response(void);
+esp_err_t multimodal_audio_finish_downstream_response(void);
+esp_err_t multimodal_audio_stop_downstream_playback(void);
+esp_err_t multimodal_audio_register_downstream_playback_callback(
+        multimodal_audio_downstream_playback_callback_t cb,
+        void *cb_ctx);
+
+#ifdef __cplusplus
+}
+#endif

components/platform/internal/multimodal/transport_ws.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    MULTIMODAL_WS_EVENT_CONNECTED = 0,
+    MULTIMODAL_WS_EVENT_DISCONNECTED,
+    MULTIMODAL_WS_EVENT_ERROR,
+    MULTIMODAL_WS_EVENT_TEXT_MESSAGE,
+    MULTIMODAL_WS_EVENT_BINARY_MESSAGE,
+} multimodal_ws_event_type_t;
+
+typedef struct {
+    multimodal_ws_event_type_t type;
+    const uint8_t *data;
+    size_t data_len;
+} multimodal_ws_event_t;
+
+typedef void (*multimodal_ws_event_callback_t)(const multimodal_ws_event_t *event,
+                                               void *user_data);
+
+esp_err_t multimodal_ws_start(const char *bearer_token,
+                              const char *workspace_id,
+                              multimodal_ws_event_callback_t cb,
+                              void *user_data);
+esp_err_t multimodal_ws_stop(int timeout_ms);
+bool multimodal_ws_is_connected(void);
+
+esp_err_t multimodal_ws_send_text(const char *label, const char *text);
+esp_err_t multimodal_ws_send_text_realtime(const char *label, const char *text);
+esp_err_t multimodal_ws_send_binary_realtime(const uint8_t *data, size_t len);
+
+#ifdef __cplusplus
+}
+#endif

components/platform/internal/platform_internal.h

@@ -0,0 +1,20 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include "esp_err.h"
+#include "platform.h"
+
+esp_err_t platform_stepper_driver_init(void);
+esp_err_t platform_stepper_driver_rotate_angle_with_accel(float angle,
+                                                          int target_delay_us,
+                                                          int timeout_ms);
+void platform_stepper_driver_power_off(void);
+void platform_power_hold_init(void);
+esp_err_t platform_digital_input_driver_configure(const platform_digital_input_config_t *config);
+bool platform_digital_input_driver_is_active(const platform_digital_input_config_t *config);

components/platform/internal/power_manager.h

@@ -0,0 +1,13 @@
+#pragma once
+
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void power_manager_set_keep_awake(bool keep_awake);
+
+#ifdef __cplusplus
+}
+#endif

components/platform/internal/voice_prompt.h

@@ -0,0 +1,13 @@
+#pragma once
+
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+esp_err_t voice_prompt_play_file(const char *path);
+
+#ifdef __cplusplus
+}
+#endif

components/platform/internal/wifi_portal.h

@@ -0,0 +1,74 @@
+#pragma once
+
+#include "esp_err.h"
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    void (*set_keep_awake)(bool keep_awake);
+    esp_err_t (*play_prompt_file)(const char *path);
+} wifi_portal_behavior_hooks_t;
+
+/**
+ * @brief Initialize Wi-Fi portal defaults and seed credentials.
+ *
+ * This writes the provided SSID/password into NVS if no credentials exist yet.
+ * The underlying Wi-Fi manager is initialized lazily when starting STA or AP.
+ */
+esp_err_t wifi_portal_init_defaults(const char *seed_ssid, const char *seed_password);
+
+/**
+ * @brief Check if any Wi-Fi credentials are stored in NVS.
+ */
+bool wifi_portal_has_saved_credentials(void);
+
+/**
+ * @brief Check whether the STA interface is connected (has an IP).
+ *
+ * This does not start/stop Wi-Fi; it only reports the current connection
+ * state.
+ */
+bool wifi_portal_sta_is_connected(void);
+
+/**
+ * @brief Start the captive portal configuration AP.
+ *
+ * Stops the STA interface if running and launches the SoftAP/web portal.
+ */
+esp_err_t wifi_portal_start_config_ap(const char *ssid_prefix);
+
+/**
+ * @brief Attempt to connect to a saved Wi-Fi network.
+ *
+ * Stops the portal if it is running, starts the station interface and waits
+ * for the connection to succeed within the provided timeout (milliseconds).
+ */
+esp_err_t wifi_portal_connect_sta(int timeout_ms);
+
+/**
+ * @brief Save Wi-Fi credentials into NVS.
+ *
+ * The saved credentials become the highest priority network.
+ */
+esp_err_t wifi_portal_save_credentials(const char *ssid, const char *password);
+
+/**
+ * @brief Clear all saved Wi-Fi credentials.
+ *
+ * This wipes the SsidManager list (Wi-Fi driver stays initialized).
+ */
+esp_err_t wifi_portal_clear_saved_credentials(void);
+
+/**
+ * @brief Register behavior hooks for keep-awake and voice prompts.
+ *
+ * Passing NULL clears registered hooks and falls back to no-op behavior.
+ */
+void wifi_portal_set_behavior_hooks(const wifi_portal_behavior_hooks_t *hooks);
+
+#ifdef __cplusplus
+}
+#endif