第4章 写入冲突类型识别：并发写入、队列溢出、MTU协商不一致、ATT层超时

4.1 现象识别

四种写入冲突在应用层表现相似——写入失败或数据丢失，但日志与链路层行为有本质区别。下表列出每种类型的典型现象：

4.2 数据采集

针对每种类型，需要采集的关键数据不同。以下为最小采集清单：

// 示例：并发写入场景的关键日志采集配置（NimBLE）
#define LOG_GATT_WRITE  1
static void on_write_complete(uint16_t conn_handle, int status) {
    ESP_LOGI("GATT", "write complete: conn=%d status=%d time_ms=%lld",
             conn_handle, status, esp_timer_get_time() / 1000);
}

4.3 原因定位（故障树 + 排查表）

使用以下故障树从现象逐级定位到根因：

配合以下排查表进行定位：

4.4 修复动作

确认冲突类型后，按以下步骤执行修复：

4.4.1 并发写入修复

1. 加锁：在 GATT 写入 API 外层增加互斥锁，防止同一连接的多线程并发写入。
2. 排队：使用 FIFO 队列将写入请求串行化，由单一线程处理。
3. 等待前一完成：每次写入前检查上一写入是否已完成（通过回调标志位）。

// NimBLE 示例：基于回调标志位防并发写入
static bool write_busy = false;
static void write_cb(uint16_t conn_handle, int status, void *arg) {
    write_busy = false;
    // 处理结果
}
int safe_gatt_write(uint16_t conn_handle, uint16_t attr_handle,
                    uint8_t *data, size_t len) {
    if (write_busy) return BLE_HS_EBUSY;
    write_busy = true;
    return ble_gattc_write(conn_handle, attr_handle, data, len, write_cb, NULL);
}

4.4.2 队列溢出修复

1. 降低写入频率：在应用层控制写入间隔 ≥ 20ms（推荐 50ms）。
2. 增大队列深度：在 NimBLE 配置中调整 BLE_ATT_MAX_WRITE_QUEUE（默认 6，可调至 12）。
3. 批量写入：使用 Prepare Write + Execute Write 替代多次独立写入。

// menuconfig 调整 NimBLE ATT 队列深度
// Component config → NimBLE → Max ATT write queue depth
// 将默认 6 改为 12（需评估内存变化）
CONFIG_BLE_ATT_MAX_WRITE_QUEUE=12

4.4.3 MTU 协商不一致修复

1. 主动协商：在连接建立后立即执行 MTU 协商，确保双方使用一致值。
2. 分片发送：若数据长度 > MTU-3，应用层手动分片，每片 ≤ MTU-3。
3. 缓存对端 MTU：协商后保存 conn_mtu，写入时动态截断。

// 连接建立后主动 MTU 协商（NimBLE）
static void on_sync(void) {
    // 对每个连接发起 MTU 协商
    ble_gattc_exchange_mtu(conn_handle, NULL, NULL);
}
// 写入时动态分片
#define MAX_PAYLOAD (conn_mtu - 3)
if (len > MAX_PAYLOAD) {
    // 分片发送
    for (int offset = 0; offset < len; offset += MAX_PAYLOAD) {
        size_t chunk = MIN(MAX_PAYLOAD, len - offset);
        ble_gattc_write(conn_handle, attr_handle, data + offset, chunk, cb, NULL);
    }
}

4.4.4 ATT 层超时修复

1. 缩短连接间隔：将连接间隔从 30ms 降至 10ms，提高重传效率。
2. 增加重传次数：在 NimBLE 中增大 BLE_L2CAP_RETX_COUNT（默认 3 → 6）。
3. 启动保活：每 5s 发送一次空包或读取请求，防止链路静默超时。

// 调整连接参数示例
ble_gap_upd_params(conn_handle, &(struct ble_gap_upd_params){
    .itvl_min = 8,   // 10ms
    .itvl_max = 12,  // 15ms
    .latency = 0,
    .supervision_timeout = 100, // 1s
});

4.5 复测

修复后按以下验证矩阵确认问题已消除：

// 并发写入自动化验证脚本（Python + pyserial）
import serial, threading, time
success = 0; fail = 0; lock = threading.Lock()
def write_task():
    global success, fail
    for _ in range(250):
        # 发送写入命令到被测设备
        ser.write(b'write attr_handle 0x12 0x34\n')
        resp = ser.readline()
        with lock:
            if b'OK' in resp: success += 1
            else: fail += 1
threads = [threading.Thread(target=write_task) for _ in range(4)]
for t in threads: t.start()
for t in threads: t.join()
print(f"success={success}, fail={fail}")

4.6 预防

• 编码规范：强制所有 GATT 写入入口使用“单线程 + 回调等待”模式，禁止裸写。
• 配置基线：将 BLE_ATT_MAX_WRITE_QUEUE、BLE_L2CAP_RETX_COUNT 等参数纳入产品配置清单，并做压力测试。
• MTU 自动协商：在连接回调中自动触发 MTU 协商，并保存协商结果供写入模块查询。
• 看门狗监控：为 ATT 写入操作设置应用层看门狗（超时 15s），超时后主动重置连接。
• 写频限制器：在应用层实现令牌桶算法，限制写入频率 ≤ 50 次/秒。

// 预防性写频限制器示例（令牌桶）
typedef struct {
    int32_t tokens;
    int64_t last_fill_us;
    int rate;          // 每秒写入次数
} rate_limiter_t;
bool rate_limiter_acquire(rate_limiter_t *rl) {
    int64_t now = esp_timer_get_time();
    int64_t elapsed = now - rl->last_fill_us;
    rl->tokens = MIN(rl->tokens + elapsed * rl->rate / 1000000, rl->rate);
    rl->last_fill_us = now;
    if (rl->tokens > 0) { rl->tokens--; return true; }
    return false; // 超过速率限制
}