BLE 开发者文档

设备默认始终进入正常模式，安全配网模式需由 Web 端主动触发：

XXXXXX = eFuse MAC 后 3 字节十六进制

正常模式下注册 5 个 GATT 服务：

HSV 颜色 — 0000ff01 R/W/Notify 3字节

// 示例: 红色半亮
write([0x00, 0xFF, 0x80])

电源开关 — 0000ff02 R/W/Notify 1字节

灯效模式 — 0000ff03 R/W/Notify 1字节

灯效 100-111 详表：柔和呼吸(100)、色相漫游(101)、调色板呼吸(102)、烛光摇曳(103)、潮汐渐变(104)、日落渐变(105)、极光流转(106)、心跳脉冲(107)、月光涟漪(108)、色彩交融(109)、萤火虫(110)、四季流转(111)

灯效参数 — 0000ff04 R/W/Notify 3字节

时间灯效配置 — 0000ff05 R/W/Notify

写入 14 字节：

读取 18 字节： 前 14 字节配置 + 4 字节状态（阶段, 当前亮度, 日出时, 日落时）

// JavaScript 写入示例
const cfg = new Uint8Array(14);
cfg[0] = 206; cfg[1] = 0; cfg[2] = 255; cfg[3] = 30;
new DataView(cfg.buffer).setInt16(4, -1, true);     // startTime
new DataView(cfg.buffer).setInt16(6, 1260, true);   // peakTime
new DataView(cfg.buffer).setInt16(8, 1290, true);   // nightTime
new DataView(cfg.buffer).setInt16(10, -1, true);    // offTime
cfg[12] = 0; cfg[13] = 30;

WiFi 配置 — 0000ff11 R/W

写入： UTF-8 字符串 SSID\nPASSWORD（换行分隔）

读取： 返回当前存储的 SSID（不含密码）

特殊指令： 写入单字节 0x00 → 清除凭据并重启进入安全配网模式

// 设置 WiFi
write(encode("MyWiFi\n12345678"))
// 重置 WiFi → 进入配网模式
write([0x00])

WiFi 状态 — 0000ff12 R/Notify 1字节

时间同步 — 0000ff21 R/W/Notify 4字节

uint32 小端序，UTC epoch 秒数。

// 写入当前时间
const epoch = Math.floor(Date.now() / 1000);
const buf = new ArrayBuffer(4);
new DataView(buf).setUint32(0, epoch, true);
await char.writeValue(buf);

Current Time — 0x2A2B R/W/Notify 10字节

写入至少 7 字节可设时间，字节 7-9 可选。

Local Time Info — 0x2A0F Read 2字节

BLE OTA 服务用于远程固件更新的交互控制。设备定期自动检查更新，发现新版本后通知客户端，由用户确认后下载升级。

OTA Control — 0000ff31 Write/Notify 1字节

写入命令：

Notify：状态变化时推送 1 字节状态码。

OTA 状态码

OTA Info — 0000ff32 Read/Notify JSON

返回 UTF-8 JSON 字符串，包含版本信息和更新详情：

// 有可用更新
{"cur":"1.0.0","new":"1.2.0","size":483200,"log":"修复BLE断连","force":false,"state":2}

// 无更新
{"cur":"1.0.0","new":"","state":0}

OTA Progress — 0000ff33 Read/Notify 2字节

完整交互序列

// JavaScript OTA 交互示例
const service = await server.getPrimaryService('0000ff30-0000-1000-8000-00805f9b34fb');
const charCtrl = await service.getCharacteristic('0000ff31-0000-1000-8000-00805f9b34fb');
const charInfo = await service.getCharacteristic('0000ff32-0000-1000-8000-00805f9b34fb');
const charProg = await service.getCharacteristic('0000ff33-0000-1000-8000-00805f9b34fb');

// 订阅通知
await charCtrl.startNotifications();
charCtrl.addEventListener('characteristicvaluechanged', e => {
  const state = new Uint8Array(e.target.value.buffer)[0];
  console.log('OTA state:', state);
});

await charProg.startNotifications();
charProg.addEventListener('characteristicvaluechanged', e => {
  const data = new Uint8Array(e.target.value.buffer);
  console.log(`Progress: ${data[0]}%, state: 0x${data[1].toString(16)}`);
});

// 检查更新
await charCtrl.writeValueWithResponse(new Uint8Array([0x01]));

// 读取更新信息
const infoData = await charInfo.readValue();
const info = JSON.parse(new TextDecoder().decode(infoData.buffer));

// 确认升级
if (info.new) {
  await charCtrl.writeValueWithResponse(new Uint8Array([0x02]));
}

配网模式使用 ESP-IDF protocomm 协议，与正常模式的 GATT 服务完全不同。

端点特征值（16-bit UUID）

// Web Bluetooth 连接示例
const device = await navigator.bluetooth.requestDevice({
  filters: [{ namePrefix: 'PROV_' }],
  optionalServices: ['021a9004-0382-4aea-bff4-6b3f1c5adfb4']
});
const server = await device.gatt.connect();
const service = await server.getPrimaryService('021a9004-0382-4aea-bff4-6b3f1c5adfb4');
const charSession = await service.getCharacteristic(0xFF51);
const charConfig  = await service.getCharacteristic(0xFF52);
const charScan    = await service.getCharacteristic(0xFF50);

通信模式

每次请求为 write → 等待 → read：

await characteristic.writeValueWithResponse(requestData);
await sleep(200);    // 等待设备处理
const response = await characteristic.readValue();

握手阶段明文通信；会话建立后 prov-config / prov-scan 数据自动 AES-256-CTR 加解密。

每台设备 PoP 基于 eFuse MAC 地址派生，保证唯一：

pop = SHA-256("OAKIO_POP_" + eFuse_MAC[6字节]).hex()[0:8]
// 例如 MAC = AA:BB:CC:DD:EE:FF → pop = "a3f1b20c"

即取 SHA-256 前 4 字节转为 8 位十六进制字符串。印刷在设备标签或串口输出。

自定义 PoP（固件端）

// ESP32_LED_TEST.ino 中修改 makeDevicePoP()
static String makeDevicePoP() {
  return "12345678";  // 固定 8 位
}

客户端计算 PoP（JavaScript）

async function computePoP(macBytes) {
  // macBytes: Uint8Array(6) — 设备 eFuse MAC
  const input = new Uint8Array(16);
  const prefix = new TextEncoder().encode("OAKIO_POP_");
  input.set(prefix, 0);
  input.set(macBytes, 10);
  const hash = await crypto.subtle.digest('SHA-256', input);
  return Array.from(new Uint8Array(hash).slice(0, 4))
    .map(b => b.toString(16).padStart(2, '0')).join('').toUpperCase();
}

握手通过 prov-session (0xFF51) 端点完成，共 2 轮请求：

Step 1: 发送 Command0

// 生成 X25519 密钥对
const keyPair = await crypto.subtle.generateKey(
  { name: 'X25519' }, true, ['deriveBits']
);
// 导出公钥 (32 字节 raw)
const clientPubKey = new Uint8Array(
  await crypto.subtle.exportKey('raw', keyPair.publicKey)
);
// 构建 protobuf: SessionData { sec_ver=1, sec1: Sec1Payload { msg=0, sc0: { client_pubkey } } }
const request = buildSessionCmd0(clientPubKey);
// 发送
await charSession.writeValueWithResponse(request);
await sleep(200);
const resp = await charSession.readValue();

Step 2: 解析 Response0

// 解析 protobuf → SessionResp0 { status, device_pubkey(32B), device_random(16B) }
const { devicePubKey, deviceRandom } = parseSessionResp0(resp);
// deviceRandom 即为 AES-CTR 的 IV

Step 3: 计算会话密钥

// X25519 密钥协商
const sharedBits = await crypto.subtle.deriveBits(
  { name: 'X25519', public: await importDevicePubKey(devicePubKey) },
  keyPair.privateKey, 256
);
const shared = new Uint8Array(sharedBits);      // 32 字节

// SHA-256(PoP 字符串)
const popHash = new Uint8Array(
  await crypto.subtle.digest('SHA-256', new TextEncoder().encode(popString))
);

// 会话密钥 = shared XOR popHash
const sessionKey = new Uint8Array(32);
for (let i = 0; i < 32; i++) sessionKey[i] = shared[i] ^ popHash[i];

Step 4: 双向验证 (Command1 / Response1)

// 客户端加密 device_pubkey 作为验证数据
// 使用 AES-256-CTR(sessionKey, IV=deviceRandom)
const clientVerify = await aesCTR_encrypt(sessionKey, deviceRandom, devicePubKey);
// ↑ 消耗计数器块 0-1 (32 字节)

// 构建 Command1 并发送
await charSession.writeValueWithResponse(buildSessionCmd1(clientVerify));
await sleep(200);
const resp1 = await charSession.readValue();
const { deviceVerify } = parseSessionResp1(resp1);

// 验证: 设备加密了 client_pubkey，需要解密比对
// 关键: ESP-IDF 在同一个 AES-CTR 上下文中:
//   先解密 client_verify (32B, 块 0-1)
//   再加密 device_verify (32B, 块 2-3)
// 客户端必须将 devicePubKey || deviceVerify 拼为 64B 一次性解密
const combined = concat(devicePubKey, new Uint8Array(deviceVerify.buffer));
const decrypted = await aesCTR_decrypt(sessionKey, deviceRandom, combined);
const decryptedVerify = decrypted.slice(32);  // 后 32B = 解密后的 device_verify
// 比对: decryptedVerify === clientPubKey
if (!arraysEqual(decryptedVerify, clientPubKey)) throw new Error('Verify failed');

握手完成后，所有 prov-config / prov-scan 数据需加解密。ESP-IDF 使用 mbedtls_aes_crypt_ctr 维护字节级计数器，Web Crypto API 每次从整块起始，需手动对齐。

核心实现

let ctrByteOffset = 64; // 握手消耗 64 字节

async function sessionCrypt(data) {
  const byteOff  = ctrByteOffset % 16;     // 块内已消耗字节
  const blockNum = Math.floor(ctrByteOffset / 16);
  const counter  = incrementIV(sessionIV, blockNum);

  let result;
  if (byteOff > 0) {
    // 非 16 字节对齐: 前面填零占位
    const padded = new Uint8Array(byteOff + data.length);
    padded.set(data, byteOff);
    const encrypted = await aesCTR(sessionKey, counter, padded);
    result = encrypted.slice(byteOff);
  } else {
    result = await aesCTR(sessionKey, counter, data);
  }
  ctrByteOffset += data.length;
  return result;
}

IV 递增函数

function incrementIV(iv, blocks) {
  const counter = new Uint8Array(iv);  // 复制 16 字节 IV
  // 大端序递增最后 4 字节
  let carry = blocks;
  for (let i = 15; i >= 12 && carry > 0; i--) {
    const sum = counter[i] + carry;
    counter[i] = sum & 0xFF;
    carry = sum >> 8;
  }
  return counter;
}

加密/解密通信示例

// 发送加密请求
async function sendEncrypted(characteristic, plainData) {
  const encrypted = await sessionCrypt(new Uint8Array(plainData));
  await characteristic.writeValueWithResponse(encrypted);
  await sleep(200);
  const respView = await characteristic.readValue();
  const respEncrypted = new Uint8Array(respView.buffer);
  const respPlain = await sessionCrypt(respEncrypted);
  return respPlain;
}

安全会话建立后，通过 prov-config (0xFF52) 端点发送 WiFi 凭据：

发送凭据

// 构建 CmdSetConfig protobuf
// NetworkConfigPayload { msg_type=2, cmd_set_config: { ssid, passphrase } }
const cmd = buildCmdSetConfig(ssidString, passwordString);
await sendEncrypted(charConfig, cmd);

// 应用配置
// NetworkConfigPayload { msg_type=4, cmd_apply_config: {} }
const apply = buildCmdApplyConfig();
await sendEncrypted(charConfig, apply);

轮询状态

// NetworkConfigPayload { msg_type=0, cmd_get_status: {} }
async function pollStatus() {
  for (let i = 0; i < 15; i++) {
    await sleep(2000);
    const resp = await sendEncrypted(charConfig, buildCmdGetStatus());
    const status = parseRespGetStatus(resp);
    // staState: 0=Connected, 1=Connecting, 2=Disconnected
    if (status.staState === 0) return true;   // 成功
    if (status.staState === 2) return false;  // 失败
  }
  return false; // 超时
}

安全会话建立后，可通过 prov-scan (0xFF50) 端点扫描附近 WiFi：

扫描流程

// 1. 触发扫描
const scanStart = buildCmdScanStart();  // blocking=true
await sendEncrypted(charScan, scanStart);

// 2. 等待完成
let count = 0;
while (true) {
  await sleep(1000);
  const resp = await sendEncrypted(charScan, buildCmdScanStatus());
  const status = parseRespScanStatus(resp);
  if (status.finished) { count = status.count; break; }
}

// 3. 分批获取结果 (每次 ≤4 条，避免 BLE MTU 限制)
const results = [];
for (let i = 0; i < count; i += 4) {
  const batch = Math.min(4, count - i);
  const resp = await sendEncrypted(charScan, buildCmdScanResult(i, batch));
  results.push(...parseRespScanResult(resp));
}

WiFi 扫描结果字段

WifiAuthMode： 0=Open, 1=WEP, 2=WPA_PSK, 3=WPA2_PSK, 4=WPA_WPA2_PSK, 5=WPA2_Enterprise, 6=WPA3_PSK, 7=WPA2_WPA3_PSK

本项目使用手工 Protobuf 编解码（无依赖库），以下为所有消息的字段号。

通用编解码

// Protobuf varint 编码
function pbVarint(val) {
  const bytes = [];
  while (val > 0x7f) { bytes.push((val & 0x7f) | 0x80); val >>>= 7; }
  bytes.push(val & 0x7f);
  return new Uint8Array(bytes);
}

// 编码字段: tag = (fieldNum << 3) | wireType
// wireType 0 = varint, 2 = length-delimited (bytes/string/子消息)
function pbField(fieldNum, wireType, data) {
  const tag = pbVarint((fieldNum << 3) | wireType);
  if (wireType === 0) return concat(tag, pbVarint(data));
  if (wireType === 2) {
    const d = data instanceof Uint8Array ? data : new TextEncoder().encode(data);
    return concat(tag, pbVarint(d.length), d);
  }
  return tag;
}

SessionData / Sec1Payload (prov-session)

SessionCmd/Resp 内部字段

NetworkConfigPayload (prov-config)

CmdSetConfig 内部： ssid(1, bytes), passphrase(2, bytes)

RespGetStatus 内部： status(1, varint), sta_state(2, varint: 0=Connected 1=Connecting 2=Disconnected), fail_reason(10, varint)

WiFiScanPayload (prov-scan)

CmdScanStart： blocking(1, bool) | CmdScanResult： start_index(1), count(2)

RespScanStatus： scan_finished(1, bool), result_count(2, varint)

PoP 验证失败

握手 Step 4 解密比对不通过。检查 PoP 输入是否与设备标签一致（大小写敏感）。

WiFi 连接失败

GetStatus 返回 staState=2 (Disconnected)。fail_reason 对应 ESP-IDF wifi_err_reason_t：201=AUTH_FAIL（密码错误），15=4WAY_HANDSHAKE_TIMEOUT。

BLE 通信超时

write 后 read 返回空数据：增加 sleep 到 300-500ms。部分设备 ATT MTU 协商慢，可重连解决。

AES-CTR 计数器失步

加解密结果乱码：确保 ctrByteOffset 严格按 data.length 递增，每次加密和解密都推进。握手后初始值为 64。

WiFi 扫描结果截断

BLE MTU 限制：每次 CmdScanResult 的 count 建议 ≤4。

配网完成后设备无响应

设备 WiFi 连接成功后会自动重启，BLE 断开是预期行为。重启后进入正常模式，广播名称变为 OAKIOT_XXXXXX。

设备支持通过 HTTP RESTful API 在局域网内进行配置和控制，默认关闭，需通过串口或配置命令主动开启。

启用方式

// 串口命令
{"cmd":"set_http","enabled":true,"port":80}

// 或通过 set_config
{"cmd":"set_config","http_enabled":true}

端点列表

集成示例

// 查询设备状态
curl http://192.168.1.100/api/status

// 开灯设为暖白
curl -X PUT http://192.168.1.100/api/led \
  -H "Content-Type: application/json" \
  -d '{"power":true,"h":30,"s":180,"v":255}'

// 设置呼吸灯效
curl -X PUT http://192.168.1.100/api/effect \
  -H "Content-Type: application/json" \
  -d '{"effect_mode":100,"effect_speed":80}'

// 修改NTP配置
curl -X PUT http://192.168.1.100/api/config \
  -H "Content-Type: application/json" \
  -d '{"ntp_server1":"pool.ntp.org","ntp_gmt_offset":32400}'

通过 USB 串口（115200, 8N1）发送 JSON 命令，可配置所有运行时参数。

运行时配置命令

可配置参数

// 获取运行时配置
{"cmd":"get_config"}

// 修改NTP和OTA配置
{"cmd":"set_config","ntp_server1":"pool.ntp.org","ota_check_interval":43200000}

// 开启HTTP服务
{"cmd":"set_http","enabled":true,"port":80}

// 查看综合状态
{"cmd":"get_status"}