init

main/platform/README.md

@@ -0,0 +1,13 @@
+# Platform Layer
+
+Purpose: hardware and system resource abstraction only.
+
+Allowed examples:
+- Wi-Fi/BLE driver wrappers
+- NVS/time/RTOS/system adapters
+- board-specific IO and transport bindings
+
+Rules:
+- Expose stable APIs in `include/`.
+- Keep private headers in `internal/`.
+- Do not depend on `domain`, `control_plane`, or `app_composition`.

main/platform/include/ble_printer_client.h

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_err.h"
+
+typedef void (*ble_frame_rx_cb_t)(const uint8_t *data, size_t len);
+
+typedef struct {
+    bool connected;
+    bool notify_ready;
+    uint16_t mtu;
+} ble_link_state_t;
+
+esp_err_t ble_printer_client_init(ble_frame_rx_cb_t rx_cb);
+
+esp_err_t ble_printer_client_connect(const char *target_name, uint32_t timeout_ms);
+void ble_printer_client_disconnect(void);
+
+bool ble_printer_client_is_connected(void);
+void ble_printer_client_get_link_state(ble_link_state_t *out_state);
+
+esp_err_t ble_printer_client_write(const uint8_t *data, size_t len);

main/platform/include/platform_bootstrap.h

@@ -0,0 +1,5 @@
+#pragma once
+
+#include "esp_err.h"
+
+esp_err_t platform_bootstrap_init(void);

main/platform/include/wifi_manager.h

@@ -0,0 +1,11 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include "esp_err.h"
+
+esp_err_t wifi_manager_start(void);
+
+bool wifi_manager_is_ready(void);
+
+void wifi_manager_get_ip(char *buf, size_t buf_len);

main/platform/src/ble_printer_client.c

@@ -0,0 +1,655 @@
+#include "ble_printer_client.h"
+
+#include <ctype.h>
+#include <string.h>
+
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_nimble_hci.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/event_groups.h"
+#include "freertos/semphr.h"
+#include "host/ble_gatt.h"
+#include "host/ble_hs.h"
+#include "nimble/nimble_port.h"
+#include "nimble/nimble_port_freertos.h"
+#include "os/os_mbuf.h"
+#include "services/gap/ble_svc_gap.h"
+#include "services/gatt/ble_svc_gatt.h"
+
+#define PRINTER_SERVICE_UUID16 0xFFF0
+#define PRINTER_NOTIFY_UUID16 0xFFF1
+#define PRINTER_WRITE_UUID16 0xFFF2
+#define CCCD_UUID16 0x2902
+
+#define EVT_CONNECTED BIT0
+#define EVT_READY BIT1
+#define EVT_FAILED BIT2
+
+static const char *TAG = "ble_client";
+
+static EventGroupHandle_t s_evt_group;
+static SemaphoreHandle_t s_lock;
+
+static ble_frame_rx_cb_t s_rx_cb;
+
+static uint8_t s_addr_type;
+static ble_addr_t s_target_addr;
+static char s_target_name[32] = "lyfPrinter";
+static bool s_match_any_compatible;
+
+static uint16_t s_conn_handle = BLE_HS_CONN_HANDLE_NONE;
+static uint16_t s_service_start;
+static uint16_t s_service_end;
+static uint16_t s_notify_val_handle;
+static uint16_t s_write_val_handle;
+static uint16_t s_cccd_handle;
+static uint16_t s_mtu = 23;
+
+static bool s_scanning;
+static bool s_notify_ready;
+static bool s_host_synced;
+
+static uint16_t uuid16(const ble_uuid_t *uuid) {
+    if (uuid == NULL || uuid->type != BLE_UUID_TYPE_16) {
+        return 0;
+    }
+    return BLE_UUID16(uuid)->value;
+}
+
+static bool adv_has_uuid16(const struct ble_hs_adv_fields *fields, uint16_t target_uuid) {
+    if (fields == NULL || fields->uuids16 == NULL || fields->num_uuids16 == 0) {
+        return false;
+    }
+    for (uint8_t i = 0; i < fields->num_uuids16; ++i) {
+        if (fields->uuids16[i].value == target_uuid) {
+            return true;
+        }
+    }
+    return false;
+}
+
+static size_t normalize_name(const char *in, char *out, size_t out_cap) {
+    if (in == NULL || out == NULL || out_cap == 0) {
+        return 0;
+    }
+
+    const char *start = in;
+    while (*start != '\0' && isspace((unsigned char)*start)) {
+        ++start;
+    }
+    if (*start == '"' || *start == '\'') {
+        ++start;
+    }
+
+    size_t len = strlen(start);
+    while (len > 0 && isspace((unsigned char)start[len - 1])) {
+        --len;
+    }
+    if (len > 0 && (start[len - 1] == '"' || start[len - 1] == '\'')) {
+        --len;
+    }
+
+    size_t out_len = 0;
+    for (size_t i = 0; i < len && out_len + 1 < out_cap; ++i) {
+        unsigned char c = (unsigned char)start[i];
+        if (isupper(c)) {
+            c = (unsigned char)tolower(c);
+        }
+        out[out_len++] = (char)c;
+    }
+    out[out_len] = '\0';
+    return out_len;
+}
+
+static bool normalized_name_match(const char *adv_name, const char *target_name) {
+    char adv[40] = {0};
+    char target[40] = {0};
+    size_t adv_len = normalize_name(adv_name, adv, sizeof(adv));
+    size_t target_len = normalize_name(target_name, target, sizeof(target));
+    if (adv_len == 0 || target_len == 0) {
+        return false;
+    }
+    if (strcmp(adv, target) == 0) {
+        return true;
+    }
+    // Be tolerant of shortened or prefixed names.
+    return (strstr(adv, target) != NULL) || (strstr(target, adv) != NULL);
+}
+
+static void reset_discovery_state(void) {
+    s_service_start = 0;
+    s_service_end = 0;
+    s_notify_val_handle = 0;
+    s_write_val_handle = 0;
+    s_cccd_handle = 0;
+    s_notify_ready = false;
+    s_mtu = 23;
+}
+
+static void signal_failure(void) {
+    xEventGroupSetBits(s_evt_group, EVT_FAILED);
+}
+
+static void signal_ready(void) {
+    xEventGroupSetBits(s_evt_group, EVT_READY);
+}
+
+static int dsc_disc_cb(uint16_t conn_handle,
+                       const struct ble_gatt_error *error,
+                       uint16_t chr_val_handle,
+                       const struct ble_gatt_dsc *dsc,
+                       void *arg);
+
+static int chr_disc_cb(uint16_t conn_handle,
+                       const struct ble_gatt_error *error,
+                       const struct ble_gatt_chr *chr,
+                       void *arg);
+
+static int svc_disc_cb(uint16_t conn_handle,
+                       const struct ble_gatt_error *error,
+                       const struct ble_gatt_svc *service,
+                       void *arg);
+
+static int cccd_write_cb(uint16_t conn_handle,
+                         const struct ble_gatt_error *error,
+                         struct ble_gatt_attr *attr,
+                         void *arg) {
+    (void)conn_handle;
+    (void)attr;
+    (void)arg;
+
+    if (error->status != 0) {
+        ESP_LOGE(TAG, "CCCD write failed status=%d", error->status);
+        signal_failure();
+        return 0;
+    }
+
+    s_notify_ready = true;
+    ESP_LOGI(TAG, "Notify subscription enabled");
+    signal_ready();
+    return 0;
+}
+
+static int dsc_disc_cb(uint16_t conn_handle,
+                       const struct ble_gatt_error *error,
+                       uint16_t chr_val_handle,
+                       const struct ble_gatt_dsc *dsc,
+                       void *arg) {
+    (void)chr_val_handle;
+    (void)arg;
+
+    if (error->status == 0 && dsc != NULL) {
+        if (uuid16(&dsc->uuid.u) == CCCD_UUID16) {
+            s_cccd_handle = dsc->handle;
+            ESP_LOGI(TAG, "Found CCCD handle=%u", s_cccd_handle);
+        }
+        return 0;
+    }
+
+    if (error->status == BLE_HS_EDONE) {
+        if (s_cccd_handle == 0) {
+            ESP_LOGW(TAG, "CCCD not found, fallback to val_handle+1");
+            s_cccd_handle = s_notify_val_handle + 1;
+        }
+
+        uint8_t cccd[2] = {0x01, 0x00};
+        int rc = ble_gattc_write_flat(conn_handle, s_cccd_handle, cccd, sizeof(cccd), cccd_write_cb, NULL);
+        if (rc != 0) {
+            ESP_LOGE(TAG, "ble_gattc_write_flat CCCD failed rc=%d", rc);
+            signal_failure();
+        }
+        return 0;
+    }
+
+    ESP_LOGE(TAG, "Descriptor discovery failed status=%d", error->status);
+    signal_failure();
+    return 0;
+}
+
+static int chr_disc_cb(uint16_t conn_handle,
+                       const struct ble_gatt_error *error,
+                       const struct ble_gatt_chr *chr,
+                       void *arg) {
+    (void)arg;
+
+    if (error->status == 0 && chr != NULL) {
+        uint16_t id = uuid16(&chr->uuid.u);
+        if (id == PRINTER_NOTIFY_UUID16) {
+            s_notify_val_handle = chr->val_handle;
+            ESP_LOGI(TAG, "Found notify char handle=%u", s_notify_val_handle);
+        } else if (id == PRINTER_WRITE_UUID16) {
+            s_write_val_handle = chr->val_handle;
+            ESP_LOGI(TAG, "Found write char handle=%u", s_write_val_handle);
+        }
+        return 0;
+    }
+
+    if (error->status == BLE_HS_EDONE) {
+        if (s_notify_val_handle == 0 || s_write_val_handle == 0) {
+            ESP_LOGE(TAG,
+                     "Characteristic discovery incomplete notify=%u write=%u",
+                     s_notify_val_handle,
+                     s_write_val_handle);
+            signal_failure();
+            return 0;
+        }
+
+        uint16_t end_handle = (s_write_val_handle > s_notify_val_handle)
+                                  ? (uint16_t)(s_write_val_handle - 1)
+                                  : s_service_end;
+
+        if (end_handle <= s_notify_val_handle) {
+            end_handle = s_service_end;
+        }
+
+        int rc = ble_gattc_disc_all_dscs(conn_handle,
+                                         s_notify_val_handle,
+                                         end_handle,
+                                         dsc_disc_cb,
+                                         NULL);
+        if (rc != 0) {
+            ESP_LOGE(TAG, "Descriptor discovery start failed rc=%d", rc);
+            signal_failure();
+        }
+        return 0;
+    }
+
+    ESP_LOGE(TAG, "Characteristic discovery failed status=%d", error->status);
+    signal_failure();
+    return 0;
+}
+
+static int svc_disc_cb(uint16_t conn_handle,
+                       const struct ble_gatt_error *error,
+                       const struct ble_gatt_svc *service,
+                       void *arg) {
+    (void)arg;
+
+    if (error->status == 0 && service != NULL) {
+        if (uuid16(&service->uuid.u) == PRINTER_SERVICE_UUID16) {
+            s_service_start = service->start_handle;
+            s_service_end = service->end_handle;
+            ESP_LOGI(TAG, "Found printer service [%u, %u]", s_service_start, s_service_end);
+        }
+        return 0;
+    }
+
+    if (error->status == BLE_HS_EDONE) {
+        uint16_t start = s_service_start;
+        uint16_t end = s_service_end;
+        if (start == 0 || end == 0) {
+            // Android app searches all services/chars for FFF1/FFF2.
+            // Use a global fallback range for broader compatibility.
+            start = 1;
+            end = 0xFFFF;
+            ESP_LOGW(TAG, "Printer service 0x%04x not found; fallback char discovery in full handle range", PRINTER_SERVICE_UUID16);
+        }
+
+        int rc = ble_gattc_disc_all_chrs(conn_handle,
+                                         start,
+                                         end,
+                                         chr_disc_cb,
+                                         NULL);
+        if (rc != 0) {
+            ESP_LOGE(TAG, "Start characteristic discovery failed rc=%d", rc);
+            signal_failure();
+        }
+        return 0;
+    }
+
+    ESP_LOGE(TAG, "Service discovery failed status=%d", error->status);
+    signal_failure();
+    return 0;
+}
+
+static void start_service_discovery(void) {
+    int rc = ble_gattc_disc_all_svcs(s_conn_handle, svc_disc_cb, NULL);
+    if (rc != 0) {
+        ESP_LOGE(TAG, "ble_gattc_disc_all_svcs failed rc=%d", rc);
+        signal_failure();
+    }
+}
+
+static void start_scan(void);
+
+static void stop_scan_if_running(void) {
+    if (s_scanning) {
+        ble_gap_disc_cancel();
+        s_scanning = false;
+    }
+}
+
+static int gap_event_cb(struct ble_gap_event *event, void *arg) {
+    (void)arg;
+
+    switch (event->type) {
+        case BLE_GAP_EVENT_DISC: {
+            if (!s_scanning) {
+                return 0;
+            }
+            struct ble_hs_adv_fields fields;
+            memset(&fields, 0, sizeof(fields));
+
+            int rc = ble_hs_adv_parse_fields(&fields,
+                                             event->disc.data,
+                                             event->disc.length_data);
+            if (rc != 0) {
+                return 0;
+            }
+
+            char name[32] = {0};
+            bool has_name = (fields.name_len > 0 && fields.name != NULL);
+            if (has_name) {
+                size_t n = fields.name_len < sizeof(name) - 1 ? fields.name_len : sizeof(name) - 1;
+                memcpy(name, fields.name, n);
+            }
+
+            if (s_match_any_compatible) {
+                bool uuid_match = adv_has_uuid16(&fields, PRINTER_SERVICE_UUID16);
+                bool name_match = has_name && normalized_name_match(name, "lyfPrinter");
+                if (!uuid_match && !name_match) {
+                    return 0;
+                }
+                ESP_LOGI(TAG,
+                         "Found compatible device '%s' RSSI=%d (uuid_match=%d)",
+                         has_name ? name : "<no-name>",
+                         event->disc.rssi,
+                         uuid_match ? 1 : 0);
+            } else {
+                if (!has_name || !normalized_name_match(name, s_target_name)) {
+                    return 0;
+                }
+                ESP_LOGI(TAG, "Found target device '%s' RSSI=%d", name, event->disc.rssi);
+            }
+
+            s_target_addr = event->disc.addr;
+            stop_scan_if_running();
+
+            struct ble_gap_conn_params conn_params;
+            memset(&conn_params, 0, sizeof(conn_params));
+            conn_params.scan_itvl = 0x0010;
+            conn_params.scan_window = 0x0010;
+            conn_params.itvl_min = 0x0018;
+            conn_params.itvl_max = 0x0028;
+            conn_params.latency = 0;
+            conn_params.supervision_timeout = 0x0100;
+            conn_params.min_ce_len = 0x0010;
+            conn_params.max_ce_len = 0x0300;
+
+            rc = ble_gap_connect(s_addr_type,
+                                 &s_target_addr,
+                                 30000,
+                                 &conn_params,
+                                 gap_event_cb,
+                                 NULL);
+            if (rc != 0) {
+                ESP_LOGE(TAG, "ble_gap_connect failed rc=%d", rc);
+                signal_failure();
+            } else {
+                ESP_LOGI(TAG, "Connecting...");
+            }
+
+            return 0;
+        }
+
+        case BLE_GAP_EVENT_DISC_COMPLETE:
+            s_scanning = false;
+            return 0;
+
+        case BLE_GAP_EVENT_CONNECT:
+            if (event->connect.status == 0) {
+                s_conn_handle = event->connect.conn_handle;
+                xEventGroupSetBits(s_evt_group, EVT_CONNECTED);
+                ESP_LOGI(TAG, "Connected handle=%u", s_conn_handle);
+
+                ble_gattc_exchange_mtu(s_conn_handle, NULL, NULL);
+                start_service_discovery();
+            } else {
+                ESP_LOGE(TAG, "Connect failed status=%d", event->connect.status);
+                signal_failure();
+            }
+            return 0;
+
+        case BLE_GAP_EVENT_DISCONNECT:
+            ESP_LOGW(TAG, "Disconnected reason=%d", event->disconnect.reason);
+            s_conn_handle = BLE_HS_CONN_HANDLE_NONE;
+            s_notify_ready = false;
+            reset_discovery_state();
+            return 0;
+
+        case BLE_GAP_EVENT_MTU:
+            s_mtu = event->mtu.value;
+            ESP_LOGI(TAG, "MTU updated to %u", s_mtu);
+            return 0;
+
+        case BLE_GAP_EVENT_NOTIFY_RX: {
+            if (event->notify_rx.om == NULL || s_rx_cb == NULL) {
+                return 0;
+            }
+
+            uint16_t data_len = OS_MBUF_PKTLEN(event->notify_rx.om);
+            if (data_len == 0) {
+                return 0;
+            }
+
+            uint8_t buf[256];
+            uint16_t out_len = 0;
+            if (data_len > sizeof(buf)) {
+                ESP_LOGW(TAG, "Notify packet too large len=%u", data_len);
+                return 0;
+            }
+
+            int rc = ble_hs_mbuf_to_flat(event->notify_rx.om, buf, sizeof(buf), &out_len);
+            if (rc != 0) {
+                ESP_LOGW(TAG, "ble_hs_mbuf_to_flat notify failed rc=%d", rc);
+                return 0;
+            }
+
+            s_rx_cb(buf, out_len);
+            return 0;
+        }
+
+        default:
+            return 0;
+    }
+}
+
+static void start_scan(void) {
+    struct ble_gap_disc_params params;
+    memset(&params, 0, sizeof(params));
+    // Keep duplicates so we can receive scan response updates carrying full local name.
+    params.filter_duplicates = 0;
+    params.passive = 0;
+    params.itvl = 0x0010;
+    params.window = 0x0010;
+
+    stop_scan_if_running();
+
+    int rc = ble_gap_disc(s_addr_type, BLE_HS_FOREVER, &params, gap_event_cb, NULL);
+    if (rc != 0) {
+        ESP_LOGE(TAG, "ble_gap_disc failed rc=%d", rc);
+        signal_failure();
+        return;
+    }
+
+    s_scanning = true;
+    if (s_match_any_compatible) {
+        ESP_LOGI(TAG, "Scanning for compatible printer (service 0x%04x)", PRINTER_SERVICE_UUID16);
+    } else {
+        ESP_LOGI(TAG, "Scanning for %s", s_target_name);
+    }
+}
+
+static void ble_on_reset(int reason) {
+    ESP_LOGE(TAG, "BLE reset reason=%d", reason);
+}
+
+static void ble_on_sync(void) {
+    int rc = ble_hs_id_infer_auto(0, &s_addr_type);
+    if (rc != 0) {
+        ESP_LOGE(TAG, "ble_hs_id_infer_auto failed rc=%d", rc);
+    }
+    s_host_synced = true;
+}
+
+static void nimble_host_task(void *param) {
+    (void)param;
+    nimble_port_run();
+    nimble_port_freertos_deinit();
+}
+
+esp_err_t ble_printer_client_init(ble_frame_rx_cb_t rx_cb) {
+    s_rx_cb = rx_cb;
+
+    s_evt_group = xEventGroupCreate();
+    if (s_evt_group == NULL) {
+        return ESP_ERR_NO_MEM;
+    }
+
+    s_lock = xSemaphoreCreateMutex();
+    if (s_lock == NULL) {
+        return ESP_ERR_NO_MEM;
+    }
+
+    esp_err_t err = nimble_port_init();
+    if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
+        return err;
+    }
+    ble_hs_cfg.reset_cb = ble_on_reset;
+    ble_hs_cfg.sync_cb = ble_on_sync;
+
+    ble_svc_gap_init();
+    ble_svc_gatt_init();
+
+    nimble_port_freertos_init(nimble_host_task);
+
+    reset_discovery_state();
+    return ESP_OK;
+}
+
+esp_err_t ble_printer_client_connect(const char *target_name, uint32_t timeout_ms) {
+    s_match_any_compatible = false;
+    if (target_name != NULL && target_name[0] != '\0') {
+        if (strcmp(target_name, "*") == 0) {
+            s_match_any_compatible = true;
+        } else {
+            strlcpy(s_target_name, target_name, sizeof(s_target_name));
+        }
+    }
+
+    if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(3000)) != pdTRUE) {
+        return ESP_ERR_TIMEOUT;
+    }
+
+    if (s_conn_handle != BLE_HS_CONN_HANDLE_NONE && s_notify_ready) {
+        xSemaphoreGive(s_lock);
+        return ESP_OK;
+    }
+
+    xEventGroupClearBits(s_evt_group, EVT_CONNECTED | EVT_READY | EVT_FAILED);
+    reset_discovery_state();
+
+    int wait_sync_ms = 3000;
+    while (!s_host_synced && wait_sync_ms > 0) {
+        vTaskDelay(pdMS_TO_TICKS(20));
+        wait_sync_ms -= 20;
+    }
+    if (!s_host_synced) {
+        xSemaphoreGive(s_lock);
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    start_scan();
+    xSemaphoreGive(s_lock);
+
+    EventBits_t bits = xEventGroupWaitBits(s_evt_group,
+                                           EVT_READY | EVT_FAILED,
+                                           pdFALSE,
+                                           pdFALSE,
+                                           pdMS_TO_TICKS(timeout_ms));
+
+    if (bits & EVT_READY) {
+        return ESP_OK;
+    }
+    if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(500)) == pdTRUE) {
+        stop_scan_if_running();
+        xSemaphoreGive(s_lock);
+    }
+
+    // Similar to Android app behavior: quick retry when initial attempt fails or times out.
+    if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(1000)) == pdTRUE) {
+        xEventGroupClearBits(s_evt_group, EVT_CONNECTED | EVT_READY | EVT_FAILED);
+        reset_discovery_state();
+        start_scan();
+        xSemaphoreGive(s_lock);
+    }
+
+    bits = xEventGroupWaitBits(s_evt_group,
+                               EVT_READY | EVT_FAILED,
+                               pdFALSE,
+                               pdFALSE,
+                               pdMS_TO_TICKS(timeout_ms));
+    if (bits & EVT_READY) {
+        return ESP_OK;
+    }
+    if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(500)) == pdTRUE) {
+        stop_scan_if_running();
+        xSemaphoreGive(s_lock);
+    }
+    if (bits & EVT_FAILED) {
+        return ESP_FAIL;
+    }
+    return ESP_ERR_TIMEOUT;
+}
+
+void ble_printer_client_disconnect(void) {
+    if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(2000)) != pdTRUE) {
+        return;
+    }
+
+    stop_scan_if_running();
+
+    if (s_conn_handle != BLE_HS_CONN_HANDLE_NONE) {
+        ble_gap_terminate(s_conn_handle, BLE_ERR_REM_USER_CONN_TERM);
+    }
+
+    s_conn_handle = BLE_HS_CONN_HANDLE_NONE;
+    reset_discovery_state();
+    xSemaphoreGive(s_lock);
+}
+
+bool ble_printer_client_is_connected(void) {
+    return (s_conn_handle != BLE_HS_CONN_HANDLE_NONE) && s_notify_ready;
+}
+
+void ble_printer_client_get_link_state(ble_link_state_t *out_state) {
+    if (out_state == NULL) {
+        return;
+    }
+
+    out_state->connected = (s_conn_handle != BLE_HS_CONN_HANDLE_NONE);
+    out_state->notify_ready = s_notify_ready;
+    out_state->mtu = s_mtu;
+}
+
+esp_err_t ble_printer_client_write(const uint8_t *data, size_t len) {
+    if (data == NULL || len == 0) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    if (!ble_printer_client_is_connected() || s_write_val_handle == 0) {
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    int rc = ble_gattc_write_no_rsp_flat(s_conn_handle,
+                                         s_write_val_handle,
+                                         data,
+                                         len);
+    if (rc != 0) {
+        ESP_LOGW(TAG, "write_no_rsp failed rc=%d", rc);
+        return ESP_FAIL;
+    }
+
+    return ESP_OK;
+}

main/platform/src/platform_bootstrap.c

@@ -0,0 +1,23 @@
+#include "platform_bootstrap.h"
+
+#include <stdbool.h>
+
+#include "nvs_flash.h"
+
+static bool s_initialized;
+
+esp_err_t platform_bootstrap_init(void) {
+    if (s_initialized) {
+        return ESP_OK;
+    }
+
+    esp_err_t err = nvs_flash_init();
+    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        ESP_ERROR_CHECK(nvs_flash_erase());
+        err = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK(err);
+
+    s_initialized = true;
+    return ESP_OK;
+}

main/platform/src/wifi_manager.c

@@ -0,0 +1,144 @@
+#include "wifi_manager.h"
+
+#include <stdio.h>
+#include <string.h>
+
+#include "esp_event.h"
+#include "esp_log.h"
+#include "esp_netif.h"
+#include "esp_wifi.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/event_groups.h"
+
+#define WIFI_CONNECTED_BIT BIT0
+#define WIFI_FAIL_BIT BIT1
+
+static const char *TAG = "wifi_manager";
+
+static EventGroupHandle_t s_wifi_event_group;
+static int s_retry_num;
+static bool s_ready;
+static esp_netif_t *s_sta_netif;
+
+static void wifi_event_handler(void *arg,
+                               esp_event_base_t event_base,
+                               int32_t event_id,
+                               void *event_data) {
+    (void)arg;
+
+    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
+        esp_wifi_connect();
+        return;
+    }
+
+    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
+        if (s_retry_num < CONFIG_LYF_WIFI_MAXIMUM_RETRY) {
+            esp_wifi_connect();
+            s_retry_num++;
+            ESP_LOGW(TAG, "retry to connect to the AP (%d/%d)", s_retry_num, CONFIG_LYF_WIFI_MAXIMUM_RETRY);
+        } else {
+            xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT);
+        }
+        return;
+    }
+
+    if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
+        ip_event_got_ip_t *event = (ip_event_got_ip_t *)event_data;
+        ESP_LOGI(TAG, "got ip:" IPSTR, IP2STR(&event->ip_info.ip));
+        s_retry_num = 0;
+        xEventGroupSetBits(s_wifi_event_group, WIFI_CONNECTED_BIT);
+        return;
+    }
+}
+
+static esp_err_t start_sta_mode(void) {
+    wifi_config_t wifi_config = {0};
+    if (strlen(CONFIG_LYF_WIFI_SSID) == 0) {
+        ESP_LOGE(TAG, "CONFIG_LYF_WIFI_SSID is empty; STA-only mode requires valid SSID");
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    strlcpy((char *)wifi_config.sta.ssid, CONFIG_LYF_WIFI_SSID, sizeof(wifi_config.sta.ssid));
+    strlcpy((char *)wifi_config.sta.password, CONFIG_LYF_WIFI_PASSWORD, sizeof(wifi_config.sta.password));
+    wifi_config.sta.threshold.authmode = WIFI_AUTH_WPA2_PSK;
+    wifi_config.sta.pmf_cfg.capable = true;
+    wifi_config.sta.pmf_cfg.required = false;
+
+    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
+    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
+    ESP_ERROR_CHECK(esp_wifi_start());
+
+    ESP_LOGI(TAG, "wifi_init_sta finished");
+
+    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group,
+                                           WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
+                                           pdFALSE,
+                                           pdFALSE,
+                                           pdMS_TO_TICKS(15000));
+
+    if (bits & WIFI_CONNECTED_BIT) {
+        ESP_LOGI(TAG, "connected to AP SSID:%s", CONFIG_LYF_WIFI_SSID);
+        s_ready = true;
+        return ESP_OK;
+    }
+
+    if (bits & WIFI_FAIL_BIT) {
+        ESP_LOGW(TAG, "Failed to connect to SSID:%s", CONFIG_LYF_WIFI_SSID);
+        return ESP_FAIL;
+    }
+
+    ESP_LOGW(TAG, "Wi-Fi connect timeout");
+    return ESP_ERR_TIMEOUT;
+}
+
+esp_err_t wifi_manager_start(void) {
+    s_wifi_event_group = xEventGroupCreate();
+    if (s_wifi_event_group == NULL) {
+        return ESP_ERR_NO_MEM;
+    }
+
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+
+    s_sta_netif = esp_netif_create_default_wifi_sta();
+
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK(esp_wifi_init(&cfg));
+
+    ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT,
+                                               ESP_EVENT_ANY_ID,
+                                               &wifi_event_handler,
+                                               NULL));
+    ESP_ERROR_CHECK(esp_event_handler_register(IP_EVENT,
+                                               IP_EVENT_STA_GOT_IP,
+                                               &wifi_event_handler,
+                                               NULL));
+
+    esp_err_t err = start_sta_mode();
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "STA-only mode failed to connect (%s)", esp_err_to_name(err));
+    }
+    return err;
+}
+
+bool wifi_manager_is_ready(void) {
+    return s_ready;
+}
+
+void wifi_manager_get_ip(char *buf, size_t buf_len) {
+    if (buf == NULL || buf_len == 0) {
+        return;
+    }
+
+    buf[0] = '\0';
+
+    esp_netif_ip_info_t ip_info;
+    memset(&ip_info, 0, sizeof(ip_info));
+
+    if (s_sta_netif != NULL && esp_netif_get_ip_info(s_sta_netif, &ip_info) == ESP_OK) {
+        snprintf(buf, buf_len, IPSTR, IP2STR(&ip_info.ip));
+        return;
+    }
+
+    strlcpy(buf, "0.0.0.0", buf_len);
+}