? ?零知派（零知開源）是一個(gè)專為電子初學(xué)者/電子興趣愛好者設(shè)計(jì)的開源軟硬件平臺(tái)，在硬件上提供超高性價(jià)比STM32系列開發(fā)板、物聯(lián)網(wǎng)控制板。取消了Bootloader程序燒錄，讓開發(fā)重心從“配置環(huán)境”轉(zhuǎn)移到“創(chuàng)意實(shí)現(xiàn)”，極大降低了技術(shù)門檻。零知開源編程軟件，內(nèi)置上千個(gè)覆蓋多場(chǎng)景的示例代碼，支持項(xiàng)目源碼一鍵下載，項(xiàng)目文章在線瀏覽。零知派(零知開源)平臺(tái)通過軟硬件協(xié)同創(chuàng)新，讓你的創(chuàng)意快速轉(zhuǎn)化為實(shí)物，來動(dòng)手試試吧！

?訪問零知實(shí)驗(yàn)室，獲取更多實(shí)戰(zhàn)項(xiàng)目和教程資源吧！

www.lingzhilab.com

?

項(xiàng)目概述

本項(xiàng)目以零知派ESP32（ESP32-WROOM-32）為核心主控，構(gòu)建了一套五節(jié)點(diǎn)的BLE Mesh智能照明控制系統(tǒng)。區(qū)別于傳統(tǒng)的主從藍(lán)牙（BLE Central/Peripheral）方案，本項(xiàng)目采用Bluetooth SIG Mesh標(biāo)準(zhǔn)協(xié)議，實(shí)現(xiàn)了真正意義上的無中心多跳自組網(wǎng)：任意一個(gè)節(jié)點(diǎn)可以作為消息的中繼節(jié)點(diǎn)，將控制指令轉(zhuǎn)發(fā)給距離更遠(yuǎn)的設(shè)備，網(wǎng)絡(luò)具備自修復(fù)能力。

項(xiàng)目難點(diǎn)及解決方案

問題描述：NVS配網(wǎng)數(shù)據(jù)在固件更新后被意外清除

解決方案：僅在ESP_ERR_NVS_NO_FREE_PAGES（分區(qū)物理寫滿）時(shí)才執(zhí)行擦除，版本不匹配時(shí)保留現(xiàn)有數(shù)據(jù)

一、系統(tǒng)接線部分

1.1 硬件清單

1.2 接線方案表

以下引腳定義嚴(yán)格依據(jù) project_config.h 中的宏定義，五臺(tái)設(shè)備接線完全相同。

1.3 具體接線圖

OLED VCC務(wù)必接3.3V引腳，ESP32的5V引腳會(huì)損壞OLED、GPIO 21和GPIO 22之間無需外接上拉電阻

1.4 接線實(shí)物圖

二、核心代碼講解

本項(xiàng)目代碼聚焦四個(gè)核心部分：BLE Mesh節(jié)點(diǎn)模型定義、Generic Server多消息處理回調(diào)、系統(tǒng)初始化流程、LED PWM平滑漸變

2.1 節(jié)點(diǎn)模型定義

這是整個(gè)BLE Mesh系統(tǒng)的基礎(chǔ)，定義了節(jié)點(diǎn)向網(wǎng)絡(luò)"注冊(cè)"的功能清單

/* ============================================================
 * Config Server：BLE Mesh規(guī)范要求每個(gè)節(jié)點(diǎn)必須包含此模型
 * 它管理節(jié)點(diǎn)的網(wǎng)絡(luò)配置，使能GATT Proxy和Relay功能
 * ============================================================ */
static esp_ble_mesh_cfg_srv_t config_server = {
    .relay        = ESP_BLE_MESH_RELAY_ENABLED,    // 開啟中繼：本節(jié)點(diǎn)轉(zhuǎn)發(fā)他人消息
    .beacon       = ESP_BLE_MESH_BEACON_ENABLED,   // 開啟網(wǎng)絡(luò)信標(biāo)廣播
    .friend_state = ESP_BLE_MESH_FRIEND_ENABLED,   // 開啟Friend功能
    .gatt_proxy   = ESP_BLE_MESH_GATT_PROXY_ENABLED, // 開啟GATT代理：手機(jī)可連接
    .default_ttl  = 7,  // 消息最多轉(zhuǎn)發(fā)7跳，覆蓋多跳拓?fù)?    .net_transmit     = ESP_BLE_MESH_TRANSMIT(2, 20), // 原始消息重傳2次，間隔20ms
    .relay_retransmit = ESP_BLE_MESH_TRANSMIT(2, 20), // 中繼消息重傳2次
};

/* ============================================================
 * Generic OnOff Server：處理開關(guān)指令
 * AUTO_RSP表示協(xié)議棧自動(dòng)回復(fù)Get消息，無需應(yīng)用層干預(yù)
 * ============================================================ */
static esp_ble_mesh_gen_onoff_srv_t onoff_server = {
    .rsp_ctrl = {
        .get_auto_rsp = ESP_BLE_MESH_SERVER_AUTO_RSP, // 自動(dòng)回復(fù)狀態(tài)查詢
        .set_auto_rsp = ESP_BLE_MESH_SERVER_AUTO_RSP, // 自動(dòng)回復(fù)Set指令
    },
};

/* ============================================================
 * Generic Level Server：處理亮度調(diào)節(jié)指令
 * Level范圍：-32768~32767，映射到PWM亮度0~255
 * ============================================================ */
static esp_ble_mesh_gen_level_srv_t level_server = {
    .rsp_ctrl = {
        .get_auto_rsp = ESP_BLE_MESH_SERVER_AUTO_RSP,
        .set_auto_rsp = ESP_BLE_MESH_SERVER_AUTO_RSP,
    },
};

/* ============================================================
 * 將三個(gè)模型打包進(jìn)一個(gè)Element（元素）
 * 每個(gè)節(jié)點(diǎn)至少有一個(gè)Element，本項(xiàng)目每個(gè)節(jié)點(diǎn)只有Primary Element
 * ============================================================ */
static esp_ble_mesh_model_t root_models[] = {
    ESP_BLE_MESH_MODEL_CFG_SRV(&config_server),          // Config Server
    ESP_BLE_MESH_MODEL_GEN_ONOFF_SRV(&onoff_pub, &onoff_server), // OnOff Server
    ESP_BLE_MESH_MODEL_GEN_LEVEL_SRV(&level_pub, &level_server), // Level Server
};

static esp_ble_mesh_elem_t elements[] = {
    ESP_BLE_MESH_ELEMENT(0, root_models, ESP_BLE_MESH_MODEL_NONE),
};

/* 節(jié)點(diǎn)組合數(shù)據(jù)：告訴Provisioner本節(jié)點(diǎn)有哪些Element和Model */
static esp_ble_mesh_comp_t composition = {
    .cid           = MESH_COMPANY_ID,  // 0x02E5 = Espressif公司ID
    .elements      = elements,
    .element_count = ARRAY_SIZE(elements),
};

default_ttl消息存活跳數(shù)設(shè)置為7，每經(jīng)過一個(gè)中繼節(jié)點(diǎn)減1，為0時(shí)丟棄

2.2 多消息處理回調(diào)

nRF Mesh App在不同操作場(chǎng)景下發(fā)送的消息類型不同，必須全部處理才能實(shí)現(xiàn)完整的控制體驗(yàn)

/* ============================================================
 * 三個(gè)內(nèi)聯(lián)輔助函數(shù)：做好Level與亮度的雙向映射
 *
 * BLE Mesh Level范圍：-32768 ~ 32767（int16_t）
 * LED亮度范圍：0 ~ 255（uint8_t）
 * 映射公式：bri = (level + 32768) * 255 / 65535
 * ============================================================ */
static inline int16_t clamp16(int32_t v) {
    if (v >  32767) return  32767;
    if (v < -32768) return -32768;
    return (int16_t)v;
}
static inline uint8_t level_to_bri(int16_t lv) {
    return (uint8_t)(((int32_t)lv + 32768) * 255 / 65535);
}
static inline int16_t bri_to_level(uint8_t bri) {
    return (int16_t)((int32_t)bri * 65535 / 255 - 32768);
}

static void mesh_generic_server_cb(
        esp_ble_mesh_generic_server_cb_event_t event,
        esp_ble_mesh_generic_server_cb_param_t *param)
{
    /* 只處理狀態(tài)變化事件，忽略其他類型 */
    if (event != ESP_BLE_MESH_GENERIC_SERVER_STATE_CHANGE_EVT) return;

    uint32_t op = param-?>ctx.recv_op; // 獲取具體操作碼

    /* ── ① Generic OnOff Set ────────────────────────────────
     * 觸發(fā)場(chǎng)景：App中的ON/OFF開關(guān)按鈕（單節(jié)點(diǎn)或分組均可觸發(fā)）
     * 關(guān)鍵處理：關(guān)燈時(shí)保留當(dāng)前亮度值，下次開燈時(shí)恢復(fù)
     * ─────────────────────────────────────────────────────── */
    if (op == ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET ||
        op == ESP_BLE_MESH_MODEL_OP_GEN_ONOFF_SET_UNACK) {
        bool on = (param->value.state_change.onoff_set.onoff != 0);
        g_local_led_on = on;
        if (on) {
            // 開燈：恢復(fù)上次亮度，若無歷史亮度則默認(rèn)78%（200/255）
            uint8_t bri = g_local_brightness ? g_local_brightness : 200;
            g_local_brightness = bri;
            led_pwm_set(true, bri);
        } else {
            led_pwm_set(false, 0);  // 關(guān)燈：PWM占空比置0
        }
    }

    /* ── ② Generic Level Set（絕對(duì)值）──────────────────────
     * 觸發(fā)場(chǎng)景：App單節(jié)點(diǎn)控制界面的Level滑塊
     * 注意：Level是int16_t絕對(duì)值，需要映射到uint8_t亮度
     * ─────────────────────────────────────────────────────── */
    if (op == ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET ||
        op == ESP_BLE_MESH_MODEL_OP_GEN_LEVEL_SET_UNACK) {
        int16_t lv  = param->value.state_change.level_set.level;
        uint8_t bri = level_to_bri(lv);
        g_local_brightness = bri;
        g_local_led_on     = (bri > 0);
        led_pwm_set(g_local_led_on, bri);
    }

    /* ── ③ Generic Level Delta Set（相對(duì)增量）──────────────
     * 觸發(fā)場(chǎng)景：App分組控制界面的"+""-"按鈕
     *
     * state_change結(jié)構(gòu)體里存的是協(xié)議棧計(jì)算后的【結(jié)果Level值】
     * 字段名是 .level（int16_t），不是 .delta_level
     * 直接讀取結(jié)果值即可，無需自己做加減運(yùn)算
     * ─────────────────────────────────────────────────────── */
    if (op == ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET ||
        op == ESP_BLE_MESH_MODEL_OP_GEN_DELTA_SET_UNACK) {
        int16_t new_lv = param->value.state_change.delta_set.level; // 直接取結(jié)果
        uint8_t bri    = level_to_bri(new_lv);
        g_local_brightness = bri;
        g_local_led_on     = (bri > 0);
        led_pwm_set(g_local_led_on, bri);
    }

    /* ── ④ Generic Level Move Set（連續(xù)移動(dòng)）───────────────
     * 觸發(fā)場(chǎng)景：長(zhǎng)按分組控制界面的"+""-"按鈕
     * 同樣讀取 .level 字段，邏輯與Delta Set完全一致
     * ─────────────────────────────────────────────────────── */
    if (op == ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET ||
        op == ESP_BLE_MESH_MODEL_OP_GEN_MOVE_SET_UNACK) {
        int16_t new_lv = param->value.state_change.move_set.level;
        uint8_t bri    = level_to_bri(new_lv);
        g_local_brightness = bri;
        g_local_led_on     = (bri > 0);
        led_pwm_set(g_local_led_on, bri);
    }
}

操作碼對(duì)應(yīng)關(guān)系速查表：

2.3 系統(tǒng)初始化與NVS持久化

void app_main(void)
{
    /* ── 步驟1：NVS初始化（含關(guān)鍵保護(hù)邏輯）─────────────────
     * BLE Mesh協(xié)議棧將以下數(shù)據(jù)自動(dòng)存入NVS：
     *   - NetKey（網(wǎng)絡(luò)密鑰）
     *   - AppKey（應(yīng)用密鑰）
     *   - 單播地址（Unicast Address）
     *   - 序列號(hào)（防重放攻擊）
     *   - 分組訂閱地址
     *
     * 關(guān)鍵修復(fù)：區(qū)分兩種錯(cuò)誤碼
     *   ESP_ERR_NVS_NO_FREE_PAGES → 分區(qū)物理寫滿，必須擦除
     *   ESP_ERR_NVS_NEW_VERSION_FOUND → 固件更新版本不匹配，【不擦除】保留數(shù)據(jù)
     * ─────────────────────────────────────────────────────── */
    esp_err_t ret = nvs_flash_init();
    if (ret == ESP_ERR_NVS_NO_FREE_PAGES) {
        ESP_LOGW(TAG, "NVS partition full - erasing (provisioning lost)");
        ESP_ERROR_CHECK(nvs_flash_erase());
        ret = nvs_flash_init();
    } else if (ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        // 固件更新后版本號(hào)不匹配，但數(shù)據(jù)仍然有效，保留不擦
        ESP_LOGW(TAG, "NVS version mismatch - keeping existing data");
        ret = ESP_OK;
    }
    ESP_ERROR_CHECK(ret);

    /* ── 步驟2：LED PWM初始化 ─────────────────────────────
     * 參數(shù)：GPIO 25，LEDC_CHANNEL_0，TIMER_0，5kHz，8bit分辨率
     * 8bit = 256級(jí)調(diào)光，對(duì)應(yīng)占空比0~255
     * ─────────────────────────────────────────────────────── */
    led_pwm_init(LED_GPIO, LED_PWM_CHANNEL, LED_PWM_TIMER,
                 LED_PWM_FREQ_HZ, LED_PWM_RESOLUTION);

    /* ── 步驟3：OLED初始化 ───────────────────────────────── */
    oled_init(OLED_I2C_PORT, OLED_SDA_GPIO, OLED_SCL_GPIO, OLED_I2C_ADDR);

    /* ── 步驟4：BLE Mesh初始化（含NVS狀態(tài)檢測(cè)）──────────── */
    ESP_ERROR_CHECK(ble_mesh_init());

    /* ── 步驟5：?jiǎn)?dòng)兩個(gè)后臺(tái)任務(wù) ─────────────────────────── */
    xTaskCreate(oled_refresh_task, "oled_refresh", 2560, NULL, 3, NULL);
    xTaskCreate(led_fade_task,     "led_fade",     1024, NULL, 5, NULL);
}

在ble_mesh_init()函數(shù)末尾，通過esp_ble_mesh_node_is_provisioned()檢測(cè)NVS中是否存有配網(wǎng)數(shù)據(jù)，已配網(wǎng)節(jié)點(diǎn)跳過node_prov_enable()直接恢復(fù)運(yùn)行

if (esp_ble_mesh_node_is_provisioned()) {
    // 已配網(wǎng)：直接以原單播地址恢復(fù)，不廣播未配網(wǎng)信標(biāo)
    g_provisioned = true;
    ESP_LOGI(TAG, "Node %d ALREADY PROVISIONED - resuming", NODE_ID);
} else {
    // 未配網(wǎng)（首次或出廠重置）：?jiǎn)?dòng)ADV廣播，等待App配網(wǎng)
    esp_ble_mesh_node_prov_enable(ESP_BLE_MESH_PROV_ADV | ESP_BLE_MESH_PROV_GATT);
}

2.4 PWM平滑漸變

/* 漸變參數(shù) */
#define FADE_STEP     4    // 每次漸變步長(zhǎng)（占空比單位）
#define FADE_INTERVAL 15   // 漸變更新間隔（毫秒）

/* led_fade_task每15ms調(diào)用一次此函數(shù) */
void led_pwm_fade_tick(void)
{
    uint32_t now = xTaskGetTickCount() * portTICK_PERIOD_MS;
    if (now - s_last_tick < FADE_INTERVAL) return; // 未到更新時(shí)刻
    s_last_tick = now;

    if (s_current == s_target) return; // 已到達(dá)目標(biāo)值

    /* 非線性逼近：剩余差值大于步長(zhǎng)時(shí)固定步進(jìn)，接近目標(biāo)時(shí)精確到達(dá) */
    if (s_current < s_target) {
        uint8_t d = s_target - s_current;
        s_current += (d > FADE_STEP) ? FADE_STEP : d; // 最后一步精確對(duì)齊
    } else {
        uint8_t d = s_current - s_target;
        s_current -= (d > FADE_STEP) ? FADE_STEP : d;
    }

    /* 將當(dāng)前亮度值寫入LEDC外設(shè) */
    ledc_set_duty(LEDC_LOW_SPEED_MODE, s_channel, s_current);
    ledc_update_duty(LEDC_LOW_SPEED_MODE, s_channel);
}

總漸變時(shí)間從0~100%約960ms完成全程

系統(tǒng)流程圖

調(diào)光控制依賴庫(kù)

esp_ble_mesh_generic_model_api 定義了BLE Mesh Generic Model的全部服務(wù)端（Server）和客戶端（Client）API

// 服務(wù)端回調(diào)注冊(cè)函數(shù)
esp_err_t esp_ble_mesh_register_generic_server_callback(
    esp_ble_mesh_generic_server_cb_t callback);

// 服務(wù)端回調(diào)參數(shù)中的狀態(tài)變化聯(lián)合體
typedef union {
    struct { uint8_t onoff; }    onoff_set;   // OnOff結(jié)果
    struct { int16_t level; }    level_set;   // Level絕對(duì)值結(jié)果
    struct { int16_t level; }    delta_set;   // Delta應(yīng)用后的結(jié)果
    struct { int16_t level; }    move_set;    // Move應(yīng)用后的結(jié)果
} esp_ble_mesh_server_state_change_t;

BLE Mesh Generic Level模型的三種Set消息

Generic Level Set：設(shè)置絕對(duì)Level值，適用于已知目標(biāo)亮度的精確控制場(chǎng)景

Generic Level Delta Set：相對(duì)當(dāng)前Level值進(jìn)行偏移，適用于增減調(diào)節(jié)場(chǎng)景（旋鈕、+/-按鈕）；同一手勢(shì)的多次消息會(huì)疊加（累積Delta），協(xié)議棧自動(dòng)維護(hù)基準(zhǔn)值

三、項(xiàng)目結(jié)果演示

3.1 操作流程

（1）編譯與燒錄

①打開 main/project_config.h，將 #define NODE_ID0修改為對(duì)應(yīng)設(shè)備編號(hào)（0~4）

②設(shè)置目標(biāo)芯片，點(diǎn)擊底部任務(wù)欄"Set Espressif Device Target"設(shè)置IDF_TARGET芯片為ESP32

③燒錄并打開串口監(jiān)視器，通過日志和操作數(shù)據(jù)進(jìn)行調(diào)試

（2）手機(jī)配網(wǎng)

①打開nRF Mesh App → Network → 右上角“+”掃描

通過UUID第三字節(jié)（00,01,02,03,04）識(shí)別節(jié)點(diǎn)，依次配網(wǎng)（選擇No OOB）

②配網(wǎng)成功后，節(jié)點(diǎn)LED閃爍三次，OLED顯示變?yōu)橐雅渚W(wǎng)狀態(tài)，為每個(gè)節(jié)點(diǎn)的OnOff Server和Level Server綁定App Key 1

?

（3）創(chuàng)建分組與訂閱

在Groups界面創(chuàng)建Node 0,1、Node 2,3、Node 4、Node 0~4四個(gè)分組，為每個(gè)節(jié)點(diǎn)的OnOff Server和Level Server訂閱相應(yīng)分組

（4）功能控制

單燈控制：在Network中選擇節(jié)點(diǎn)，使用ON/OFF和Level滑塊；分組控制：在Groups中選擇分組，使用ON/OFF和+/-按鈕

3.3 Android系統(tǒng)配網(wǎng)說明

由于 nRF Mesh 官方版本主要通過 Google Play 分發(fā)，部分國(guó)內(nèi)或無代理環(huán)境的Android設(shè)備無法下載安裝，因此本教程提供兩種安裝方式：

方式一：APK直裝(推薦)
https://pan.baidu.com/s/1aLj1wjDjVDlJmRzwJ0b21Q?pwd=qtc5

下載APK到手機(jī)→打開“允許安裝未知應(yīng)用”→安裝完成

方式二：GooglePlay下載

打開GooglePlay→搜索nRFMesh→安裝NordicSemiconductor官方版本

nRFMeshApp(iOS/Android)不會(huì)自動(dòng)與節(jié)點(diǎn)重建Proxy連接。因此用戶需要在App中手動(dòng)觸
發(fā)重新連接或執(zhí)行一次Reprovision操作才能恢復(fù)控制

3.2 視頻演示

?https://live.csdn.net/v/524280?spm=1001.2014.3001.5501

本視頻演示了基于零知ESP32的五節(jié)點(diǎn)BLE Mesh智能照明系統(tǒng)的完整操作流程，包括：五臺(tái)ESP32設(shè)備的固件燒錄、nRF Mesh Android App的配網(wǎng)全過程（從掃描發(fā)現(xiàn)到AppKey綁定）、創(chuàng)建三個(gè)自定義分組并為各節(jié)點(diǎn)配置訂閱、分組控制下的LED同步開關(guān)與PWM漸變調(diào)光效果，以及OLED顯示屏實(shí)時(shí)狀態(tài)反饋

四、ESP-BLE-MESH技術(shù)講解

BLE Mesh構(gòu)建了一個(gè)無中心多跳自組網(wǎng)，一條消息可以通過多跳跨越很遠(yuǎn)的距離，即使個(gè)別節(jié)點(diǎn)離線，消息也能找到替代路徑到達(dá)目標(biāo)

4.1 協(xié)議棧架構(gòu)

Mesh Networking 功能的實(shí)現(xiàn)是基于層級(jí)結(jié)構(gòu)，每一層功能框架如圖，

4.2 組播訂閱與分組控制

組播地址由 nRF Mesh App 分配并寫入節(jié)點(diǎn)模型的 Subscription List，節(jié)點(diǎn)收到發(fā)往已訂閱組播地址的消息后觸發(fā) mesh_generic_server_cb

4.3 Relay多跳轉(zhuǎn)發(fā)

對(duì)應(yīng) Networking 層的 Relay Feature：Flooding 泛洪機(jī)制、TTL 逐跳遞減、消息緩存去重

本項(xiàng)目配置 default_ttl=7、relay_retransmit=TRANSMIT(2,20)

五、常見問題解答（FAQ）

Q1：多臺(tái)設(shè)備如何區(qū)分？UUID有什么規(guī)律？

A：本項(xiàng)目Device UUID格式為 DD:DD:XX:00:00:...，第三字節(jié)XX即為 NODE_ID（0~4的十六進(jìn)制值）。節(jié)點(diǎn)0的UUID為 DD:DD:00:...，節(jié)點(diǎn)1為 DD:DD:01:...，以此類推，在nRF Mesh App掃描界面可以直接看到UUID從而區(qū)分設(shè)備

Q2：手機(jī)App無法掃描到設(shè)備？

A：①確認(rèn)ESP32已上電且串口日志顯示 Open nRF Mesh App -> Scanner -> find ESP-BLE-MESH；②iOS需要在系統(tǒng)設(shè)置中開啟nRF Mesh的藍(lán)牙權(quán)限；③若該設(shè)備已被配網(wǎng)，需要先在App中將其重置（Reset Node）才能重新掃描到。

項(xiàng)目資源整合

ESP-BLE-MESH 架構(gòu)： ble-mesh-architecture

BLE Mesh API： bluetooth/esp-ble-mesh

審核編輯 黃宇