LiSAC 智能循迹小车：软件系统技术综述

三个计算单元（ESP32 / STM32 / 上位机）的工程实现与通信协议
组会技术汇报 · 2026-08-04

一、系统总体架构：三个计算单元的分工

整台车的控制功能被拆解到三个物理上独立的计算单元上，这种设计在嵌入式领域称为分布式控制。拆分的依据是：不同任务对实时性（毫秒级响应）、算力（能否跑复杂算法）与开发成本的要求不同，一块芯片同时承担所有任务往往顾此失彼。

1.1 为什么这样分工

• 实时性隔离：电机调速要求 200 Hz 的稳定控制周期。WiFi 收发、网页请求这类操作耗时不确定，若与闭环混在同一处理器上，系统会出现"突然卡一下"。把闭环放在 STM32 上，周期有硬件定时器保证。
• 职责边界清晰：ESP32 只负责"决策"（去哪、多快），把目标车速发给 STM32；STM32 只负责"执行"（让轮子真转到那个速度）。两部分逻辑可独立开发、独立测试。
• 调试便利：上位机可以绕过 ESP32 直接连 STM32 串口，单独调试底盘，把问题隔离在最小范围。

1.2 单元之间的"对话链"

链路①（主）：上位机经 WiFi TCP 连上 ESP32 上的 tcp_bridge 桥组件，桥再把字节流原样转发到 STM32 的 UART——这条链上整车完全无线。链路②（备用，开发调试）：上位机也可经 USB 转串口直接连 STM32，单独调试底盘，把问题隔离在最小范围。

第二章讲帧协议（链路①②共用同一套 COBS 帧），第三章讲上位机与 tcp_bridge，第四章讲 ESP32 的 OTA。

---

二、单元间通信协议：COBS 帧与校验和

2.1 帧（Frame）结构

本系统在"芯片之间"与"上位机与芯片之间"统一采用一套帧约定：

帧 = [命令字 cmd 1字节] [载荷 payload] [校验和 checksum 1字节]

命令共 6 条：STOP 停车、SET_SPEED 设定车速、ESTOP 紧急停止、SET_PID 设定调速参数、PING 探活、STATUS 回传状态。载荷中的多元数据按小端字节序（低位字节在前）排列，两端严格一致。

2.2 COBS 定界：如何保证帧内不出 0x00

我们规定字节 0x00 是帧结束标志，因此帧内部绝不能出现 0x00。但业务数据（如车速为 0、角度为 0）里出现 0 字节是常有的事。COBS（Consistent Overhead Byte Stuffing，一致开销字节填充）解决此问题：

• 把数据流中每个 0x00 替换为一个 code 字节，该字节的数值表示"从当前位置往前数 $N$ 个字节都是非零"。
• 每 254 个连续非零字节需要额外插一个 code 字节，最坏开销为 $1/254 \approx 0.4\%$，故称"一致开销"——以极小代价换来确定性的定界能力。
• 本实现为无损变体：标准 COBS 还原时会丢失 0x00 的位置信息，本系统在解码时把 0x00 精确插回原位，保证二进制数据（含负数补码）完全还原。该细节在 STM32、ESP32、上位机三端实现完全一致。

2.3 校验和（checksum）：如何发现错误帧

传输中可能因电气干扰丢失或改写字节。我们在帧尾附加"整帧字节求和后取低 8 位"的校验和：

$$\text{checksum} = \left( \sum_{i=0}^{n-1} b_i \right) \bmod 256$$

接收方重新求和，若与帧尾不一致，判定"这一帧脏了"，整帧丢弃并累加一次坏帧计数 $e_{\text{rx}}$（rx_errors），随 STATUS 帧回传给上位机，使通信质量可观测。

2.4 工程鲁棒性机制（不止"能通"，还要"可靠"）

2.5 速度闭环中的 PID 公式（附）

执行单元的核心算法是增量式 PID，在 5ms 控制周期内由编码器测得实际转速 $v(n)$，与目标 $v^*$ 比较得误差 $e(n) = v^* - v(n)$：

$$u(n) = u(n-1) + K_p \left[ e(n) - e(n-1) \right] + K_i \, e(n) + K_d \left[ e(n) - 2e(n-1) + e(n-2) \right]$$

其中 $u(n)$ 为输出 PWM 占空比对应的控制量，$K_p, K_i, K_d$ 为可在线调参的三项增益。初始参数 $(0.5, 0.05, 0.01)$，待真机整定。

---

三、上位机网页与 Flask 后端

3.1 架构：Flask 后端 + Jinja2 模板 + 静态资源

• 后端框架 Flask（Python 轻量 Web 框架），共注册 21 条路由，覆盖 5 个页面及配套 API。
• 页面渲染：Jinja2 模板引擎做服务端渲染（后端把数据填进 HTML 模板再发给浏览器）。
• 前端资源（CSS/JS）由 /static/ 目录提供，状态页用 ECharts 绘制实时曲线。
• 数据刷新：页面每 1 秒轮询一次 GET /api/status，即"轮询机制"。

3.2 五个页面（路由表）

3.3 后端数据逻辑：真实数据优先 + MOCK 降级

后端内置一个 MOCK_STATUS 模拟数据源。读取状态时先判断"真机是否在线"：

• 在线：用链路（串口或 TCP）读取的真实数据覆盖模拟字段；
• 不在线：退回显示模拟数据，页面仍可开发调试。

在线判定：后台线程每 0.5s 读一次链路，能持续收到状态帧即认为在线。这套"真实优先、模拟兜底"的设计使前端开发完全不等硬件。

3.4 帧链路 device_link.py：双传输模式（串口 / TCP）

device_link.py 是后端与芯片之间的"接线员"，把两种物理传输方式抽象成同一套接口，上层协议处理（切帧→解码→校验→解析）完全复用：

两种模式都维护一个独立后台线程：

读链路 → 按 0x00 切帧 → COBS 解码 → 校验和 → 解析为字典 → 更新状态缓存

发命令时把字典打包为 COBS 帧写入链路。传输循环与网页请求完全解耦，互不阻塞；传输层自动重连，掉线不影响网页服务。

3.5 无线桥组件 tcp_bridge：ESP32 上的"透传桥"

纯无线调试需要一个把 WiFi TCP 转为 STM32 UART 的桥梁，它就是 ESP32 上的 tcp_bridge 组件（新端口，默认 5005）：

• 只透传、不解析：TCP 收到的字节原样写入 STM32 UART，STM32 回传的字节原样发回 TCP。桥不理解帧内容，因此三端的 COBS 帧格式完全不变，复用第二章全部协议逻辑。
• 逐字回传 + 禁用 Nagle 算法：UART 一收到字节就立即转发，并关闭 TCP 的 Nagle 合并（否则 1~2 字节的小帧会被网络层攒包几十毫秒，破坏控制实时性）。
• 单客户端模式：同一时刻只服务一个上位机，新连接自动顶掉旧连接，防止两个客户端同时抢控。
• 断线自愈：上位机异常掉线时，桥通过 TCP keepalive 快速感知并回收连接，重连后立即恢复。

实现参考：乐鑫官方示例 esp-idf/examples/protocols/sockets/tcp_server（socket 生命周期管理）与开源项目 mtoolstec/esp32-uart-bridge（Nagle 关闭），均已在 components/tcp_bridge/ 内注释注明。

---

四、空中升级 OTA（Over-The-Air Update）

4.1 为什么要做 OTA

• 机器装车后难以开盖接线，网络是唯一现实的发布渠道；
• 把"烧录"从物理操作变成软件操作，可批量升级多台设备；
• 内置校验与回滚，坏包不会写入，设备不会"变砖"。

4.2 一次 OTA 的完整流程（5 步）

4.3 关键技术点

• A/B 双分区：Flash 划分为两块等大小区域。新固件写入当前未运行的那块，写废了随时放弃，正在运行的旧固件不受影响。
• 完整性校验：下载过程校验摘要（SHA/CRC），数据不完整则不切换。
• 版本管理：服务器维护"当前版本号 + 文件列表"，ESP32 携带"我的版本号"比对，逻辑简单可靠。
• 回滚保护：新固件启动失败（看门狗/启动标记）自动切回旧分区，保证设备可用。

---

五、关键代码实现（源码高亮）

以下摘录本系统三端的关键代码片段，展示通信协议、控制算法、OTA 客户端三大核心模块的实际工程实现。语法高亮由 highlight.js 渲染，代码与仓库完全一致。

5.1 STM32 端速度闭环：位置式 PID（pid.c）

文件：stm32f103v1.0/Core/Src/pid.c

static float clampf(float v, float limit)
{
    if (v > limit)  return limit;
    if (v < -limit) return -limit;
    return v;
}

/* 位置式 PID：P + 积分（带限幅，防 windup）+ 微分 */
float pid_update(pid_t *pid, float setpoint, float measurement)
{
    const float error = setpoint - measurement;

    const float p_term = pid->kp * error;

    /* 积分项：先累加再限幅，防止积分饱和后停车猛冲 */
    pid->integral += pid->ki * error * pid->dt;
    pid->integral = clampf(pid->integral, pid->integral_limit);

    const float d_term = pid->kd * (error - pid->last_error) / pid->dt;
    pid->last_error = error;

    /* 输出同样限幅，保护电机驱动器 */
    return clampf(p_term + pid->integral + d_term, pid->output_limit);
}

图 5-1：STM32 端速度闭环：位置式 PID（pid.c）（highlight.js 高亮渲染）

5.2 STM32 端 COBS 编解码（cobs.c）

文件：stm32f103v1.0/Core/Src/cobs.c

/* 编码：帧内每个 0x00 用 code 字节替代，0x00 只留给帧尾 */
size_t cobs_encode(const uint8_t *src, size_t src_len, uint8_t *dst)
{
    size_t read_idx = 0, write_idx = 1, code_idx = 0;
    uint8_t code = 1;

    if (src_len == 0) { dst[0] = 0x01; dst[1] = 0x00; return 2; }

    for (;;) {
        if (read_idx >= src_len) {          /* 数据结束：回填 code + 终止符 */
            dst[code_idx] = code;
            dst[write_idx] = 0x00;
            return write_idx + 1;
        }
        if (src[read_idx] == 0x00) {        /* 遇 0x00：结束本块，重新计数 */
            dst[code_idx] = code;
            code_idx = write_idx++;
            code = 1;
            read_idx++;
        } else {
            dst[write_idx++] = src[read_idx];
            read_idx++;
            if (++code == 0xFF) {           /* 连续 254 个非零，强制终结 */
                dst[code_idx] = code;
                code_idx = write_idx++;
                code = 1;
            }
        }
    }
}

/* 解码：块间补回隐藏的 0x00（无损变体），越界即返回 0 */
size_t cobs_decode(const uint8_t *src, size_t src_len,
                   uint8_t *dst, size_t dst_cap)
{
    size_t read_idx = 0, write_idx = 0;

    while (read_idx < src_len) {
        const uint8_t code = src[read_idx++];
        if (code == 0x00) break;                    /* 帧终止符 */
        if (read_idx + (code - 1) > src_len) return 0;
        if (write_idx + (code - 1) > dst_cap ||
            (code != 0xFF && write_idx + code > dst_cap))
            return 0;                               /* 输出越界防护 */
        for (uint8_t i = 1; i < code; i++)
            dst[write_idx++] = src[read_idx++];
        if (code != 0xFF) {
            if (read_idx >= src_len) return 0;      /* 帧不完整 */
            if (src[read_idx] == 0x00) break;       /* 真正的帧尾 */
            dst[write_idx++] = 0x00;                /* 补回隐藏 0x00 */
        }
    }
    return write_idx;
}

图 5-2：STM32 端 COBS 编解码（cobs.c）（highlight.js 高亮渲染）

5.3 STM32 端帧接收与周期任务（protocol.c）

文件：stm32f103v1.0/Core/Src/protocol.c

/* 逐字节接收：0x00 是帧终止符，连同该字节一起 COBS 解码 */
void proto_rx_byte(uint8_t b)
{
    rx_last_byte_ms = HAL_GetTick();

    if (b == 0x00) {
        if (rx_len == 0) return;                    /* 空帧丢弃 */

        rx_buf[rx_len++] = 0x00;                    /* 帧尾是编码帧一部分 */

        uint8_t raw[64];
        const size_t raw_len = cobs_decode(rx_buf, rx_len, raw, sizeof(raw));

        if (raw_len >= 2 &&
            calc_checksum(raw, raw_len - 1) == raw[raw_len - 1]) {
            handle_cmd(raw[0], &raw[1], raw_len - 2, rx_last_byte_ms);
        } else {
            g_state.rx_errors++;                    /* 坏帧计数 */
        }
        rx_len = 0;
        return;
    }

    if (rx_len >= RX_BUF_MAX - 1) {                 /* 溢出重同步 */
        rx_len = 0;
        g_state.rx_errors++;
        return;
    }
    rx_buf[rx_len++] = b;
}

/* 5ms 周期任务：半帧超时重同步 + 通信超时停车 + PING 应答 */
void proto_periodic_5ms(uint32_t now_ms)
{
    if (rx_len > 0 && (now_ms - rx_last_byte_ms) > PROTO_RX_RESYNC_MS) {
        rx_len = 0;                                 /* 丢弃残留半帧 */
        g_state.rx_errors++;
    }

    if (g_state.last_cmd_ms != 0 &&
        (now_ms - g_state.last_cmd_ms) > PROTO_TIMEOUT_MS) {
        g_state.left_target = 0;                    /* 200ms 无指令停车 */
        g_state.right_target = 0;
        g_state.status = PROTO_STATUS_TIMEOUT;
        pid_reset(&g_pid_left);
        pid_reset(&g_pid_right);
        g_state.last_cmd_ms = 0;
    }

    if (ping_pending) {                             /* PING 立即应答 */
        ping_pending = 0;
        proto_send_status();
    }
}

图 5-3：STM32 端帧接收与周期任务（protocol.c）（highlight.js 高亮渲染）

5.4 ESP32 端 UART 接收任务与状态解析（motor_uart.c）

文件：esp32ev1.0/components/motor_uart/motor_uart.c

/* 接收任务：UART 事件驱动，逐字节喂给协议栈 */
static void uart_rx_task(void *arg)
{
    uart_event_t ev;
    QueueHandle_t uart_queue = (QueueHandle_t)arg;
    uint8_t byte;

    for (;;) {
        if (xQueueReceive(uart_queue, &ev, portMAX_DELAY)) {
            if (ev.type == UART_DATA) {
                while (uart_read_bytes(CONFIG_MOTOR_UART_PORT, &byte, 1, 0) > 0)
                    rx_byte(byte);
            } else if (ev.type == UART_FIFO_OVF || ev.type == UART_FRAME_ERR ||
                       ev.type == UART_PARITY_ERR || ev.type == UART_BREAK ||
                       ev.type == UART_DATA_BREAK) {
                /* 硬件错误：清空 FIFO 重新同步（ESP-IDF v6.0 拆分类） */
                uart_flush_input(CONFIG_MOTOR_UART_PORT);
                rx_len = 0;
                g_status.rx_errors++;
            }
        }

        /* 半帧超时重同步：50ms 内没等到帧尾 0x00 */
        if (rx_len > 0) {
            const uint32_t now_ms = esp_timer_get_time() / 1000;
            if ((now_ms - rx_last_byte_ms) > 50) {
                rx_len = 0;
                g_status.rx_errors++;
            }
        }
    }
}

/* STATUS 帧解析：15 字节 payload = 6×int16 + status + uint16 rx_errors */
static void parse_status(const uint8_t *payload, size_t plen)
{
    if (plen < 15) return;

    const int16_t fields[6] = {
        (int16_t)(payload[0] | (payload[1] << 8)),
        (int16_t)(payload[2] | (payload[3] << 8)),
        (int16_t)(payload[4] | (payload[5] << 8)),
        (int16_t)(payload[6] | (payload[7] << 8)),
        (int16_t)(payload[8] | (payload[9] << 8)),
        (int16_t)(payload[10] | (payload[11] << 8)),
    };
    g_status.left_speed  = fields[0];
    g_status.right_speed = fields[1];
    g_status.left_pwm    = fields[2];
    g_status.right_pwm   = fields[3];
    g_status.left_target = fields[4];
    g_status.right_target = fields[5];
    g_status.status      = payload[12];
    g_status.rx_errors   = (uint16_t)(payload[13] | (payload[14] << 8));
}

图 5-4：ESP32 端 UART 接收任务与状态解析（motor_uart.c）（highlight.js 高亮渲染）

5.5 上位机侧 COBS 解码与状态解析（device_link.py）

文件：LiSAC_Car_Console/device_link.py

def cobs_decode(data: bytes) -> bytes:
    """无损 COBS 解码：块间补回 0x00，读到帧尾 0x00 结束"""
    out = bytearray()
    read_idx, n = 0, len(data)

    while read_idx < n:
        code = data[read_idx]
        read_idx += 1
        if code == 0x00:
            break                                  # 帧终止符
        if read_idx + (code - 1) > n:
            return b&#x27;&#x27;                             # 数据不足，非法帧
        out += data[read_idx:read_idx + code - 1]
        read_idx += code - 1
        if code != 0xFF:
            if read_idx >= n:
                return b&#x27;&#x27;                         # 帧不完整
            if data[read_idx] == 0x00:
                break                              # 真正的帧尾
            out.append(0x00)                       # 补回隐藏 0x00
    return bytes(out)


def _parse_frame(self, encoded: bytes):
    raw = cobs_decode(encoded)
    if len(raw) < 2:
        return
    if (sum(raw[:-1]) & 0xFF) != raw[-1]:          # 校验和
        return
    cmd, payload = raw[0], raw[1:-1]

    if cmd == CMD_STATUS and len(payload) >= 15:   # STATUS: 6×int16 + ...
        fields = struct.unpack(&#x27;<6h&#x27;, payload[:12])
        self._status.update({
            &#x27;left_speed&#x27;: fields[0], &#x27;right_speed&#x27;: fields[1],
            &#x27;left_pwm&#x27;: fields[2], &#x27;right_pwm&#x27;: fields[3],
            &#x27;left_target&#x27;: fields[4], &#x27;right_target&#x27;: fields[5],
            &#x27;status&#x27;: payload[12],
            &#x27;rx_errors&#x27;: payload[13] | (payload[14] << 8),
            &#x27;last_recv&#x27;: time.time(),
        })


def send_speed(self, left: int, right: int, mode: int = MODE_CLOSED) -> bool:
    &quot;&quot;&quot;闭环模式单位 counts/5ms，开环模式单位 PWM %&quot;&quot;&quot;
    payload = struct.pack(&#x27;<hhB&#x27;, int(left), int(right), mode)
    return self._send(CMD_SET_SPEED, payload)

图 5-5：上位机侧 COBS 解码与状态解析（device_link.py）（highlight.js 高亮渲染）

5.6 ESP32 端 OTA 版本检测（ota_client.c）

文件：esp32ev1.0/components/ota_client/ota_client.c

static const char *CURRENT_VERSION = "1.0.0";

/* 向服务器查询最新版本号，与本地对比决定是否触发升级 */
static esp_err_t check_version(char *server_version, size_t len)
{
    char url[128];
    snprintf(url, sizeof(url),
             "http://%s:%d/version",
             CONFIG_OTA_SERVER_IP, CONFIG_OTA_SERVER_PORT);

    esp_http_client_config_t config = {
        .url = url,
        .timeout_ms = 5000,
    };
    esp_http_client_handle_t client = esp_http_client_init(&config);
    if (client == NULL) {
        ESP_LOGE(TAG, "Failed to init HTTP client");
        return ESP_FAIL;
    }

    esp_err_t err = esp_http_client_open(client, 0);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "HTTP open failed: %s", esp_err_to_name(err));
        esp_http_client_cleanup(client);
        return err;
    }

    /* 读取服务器返回的版本串，与 CURRENT_VERSION 做字符串比较 */
    int len_recv = esp_http_client_read_response(client, server_version, len);
    esp_http_client_cleanup(client);

    if (len_recv <= 0) return ESP_FAIL;
    if (strcmp(CURRENT_VERSION, server_version) >= 0)
        return ESP_ERR_NOT_FOUND;                  /* 本地已是最新 */
    return ESP_OK;                                 /* 有新版本可升级 */
}

图 5-6：ESP32 端 OTA 版本检测（ota_client.c）（highlight.js 高亮渲染）

六、开源库与第三方依赖

本系统并非全部从零实现：三端的协议（COBS 帧/校验和）为本项目自研，其余大量底层能力来自成熟的第三方开源组件。下表为工程实际使用到的开源库清单（均已保留原始版权声明）。

6.1 芯片 / 固件层面

6.2 上位机（Python / 前端）层面

6.3 关于移植与合规

• 所有第三方组件均保留原始版权与许可证声明，改动处另行标注；
• ESP_OTA 从 Arduino 生态移植到 ESP-IDF 时，重写了 ota_client 组件（HTTP 客户端改用 ESP-IDF 官方 esp_http_client / esp_https_ota API），上层"连网 → 查版本 → 下载 → 切分区 → 重启"流程保持一致；
• 三端协议（COBS 帧 / 校验和 / 超时重同步）为本项目自研实现，其余模块尽量复用成熟厂商与社区代码，减少重复造轮子。

---

七、各工程源码结构

以下是三个工程的主要目录结构（已略去 build 产物与厂商驱动细节，★ 标记核心自研模块）。

7.1 执行单元：stm32f103v1.0/

7.2 指挥单元：esp32ev1.0/

7.3 监控单元：LiSAC_Car_Console/

---

八、开发进度与资源占用实测

8.1 已完成交付项

8.2 资源占用（编译期实测）

STM32 Flash 余 60%、RAM 余 33%；ESP32 应用分区余 55%。均有充足升级与调试余量，无内存溢出风险，且足以支撑 OTA 双分区布局。

8.3 测试策略

• 单元测试：COBS 往返、帧解析、半帧重同步等在 Python 侧直接构造用例断言，不依赖硬件。
• 集成测试：上位机可用模拟数据跑通全部页面。
• 待做：真机联调（上电 → 通信 → 电机 → 循迹）后，PID 与循迹参数需实地整定。

---

九、当前风险与后续工作

9.1 风险与处置

9.2 后续里程碑

本报告为 LiSAC 开发小组内部技术综述，用于组会汇报与研发管理。编译与资源数据为当前工程实测值，可能随开发迭代而变化。