好的！为了方便你开发上位机，我为你整理了一份详细的**物流小车 TCP 通信协议文档**。这份文档完全基于我们目前代码中的逻辑实现。

---

# 🚚 物流小车 TCP 通信协议文档 (v1.2)

## 1. 协议基础格式
所有数据包（上行和下行）均采用以下固定包装结构：
`LOGI:<PAYLOAD>:<CS>#`

*   **`LOGI:`**: 固定帧头。
*   **`<PAYLOAD>`**: 有效载荷文本。
*   **`:`**: 有效载荷与校验位之间的分隔符。
*   **`<CS>`**: 2字节 ASCII 十六进制校验和（CheckSum）。
    *   *计算规则*：从 `L` 开始（下标0）累加到最后一个冒号 `:` 之前的所有字节。
*   **`#`**: 固定帧尾。

---

## 2. 下行指令 (上位机 -> 小车)

| 指令前缀 | 示例 | 说明 |
| :--- | :--- | :--- |
| **ST:RUN** | `LOGI:ST:RUN:3B#` | **启动**: 开始自动运输。必须先发 `GS` 设置目标站。 |
| **ST:STOP**| `LOGI:ST:STOP:8C#`| **停止**: 立即停止所有电机，清除到站锁存。 |
| **SP:xxx** | `LOGI:SP:050:D7#` | **速度**: 设置速度百分比 (000~100)。 |
| **GS:xxx** | `LOGI:GS:001:CA#` | **站点**: 设置目标站点 (目前支持 001/002)。会清除到站锁存并响铃。 |

---

## 3. 上行遥测 (小车 -> 上位机)

### 3.1 周期状态报告 (下位机每 500ms 自动推送)
**格式：** `LOGI:STAT:SP:速度,STA:站点,RUN:运行,DIS:距离,TRK:循迹:CS#`
**示例：** `LOGI:STAT:SP:050,STA:001,RUN:1,DIS:52.4,TRK:00100:B2#`

| 字段 | 示例值 | 说明 |
| :--- | :--- | :--- |
| **SP** | `050` | 当前速度百分比 (0~100)。 |
| **STA**| `001` | 当前设置的目标站点编号。 |
| **RUN**| `1` | 运行状态 (1:运动中, 0:停止/待机)。 |
| **DIS**| `12.5`| 超声波测距 (单位: cm，保留1位小数)。 |
| **TRK**| `00100`| 5位循迹灯状态 (0: 未触发感应, 1: 感应到黑线)。从左到右对应 IR1-IR5。 |

### 3.2 指令执行反馈 (收到指令后立即回复)
**格式：** `LOGI:FB:指令类型:状态值:CS#`
**示例：** `LOGI:FB:GS:1:A5#` (代表站点设置成功)

| 字段 | 值意义 | 说明 |
| :--- | :--- | :--- |
| **指令类型** | `ST` / `SP` / `GS` | 对应上位机发来的指令头。 |
| **状态值** | `1` / `0` | 1: 执行成功；0: 失败（如未设站点就点运行等）。 |

---

## 4. 特殊业务逻辑说明 (供上位机逻辑参考)

1.  **到站锁死机制**：
    *   小车到达 `STA` 对应的 RFID 站点后，会自动进入 `STOP` 状态并推送 `RUN:0`。
    *   **此时直接发 `ST:RUN` 会被拒绝**（收到 `FB:ST:0` 反馈），蜂鸣器响两声。
    *   **解锁方式**：必须重新发送 `GS:xxx` 指令覆盖目标站点（即使设成同一个号也可以），然后再发 `ST:RUN`。

2.  **安全保护**：
    *   若上位机未发送过任何 `GS` 指令，尝试发 `ST:RUN` 会触发失败反馈。

3.  **校验和计算 Python 参考代码**：
    ```python
    def calculate_cs(data_str):
        # 如 data_str 为 "LOGI:ST:RUN"
        return sum(data_str.encode('ascii')) & 0xFF
    ```

---

你可以直接复制到你的上位机开发笔记里。如需增加更多字段（如电池电压、电机电流等），我可以随时在底层代码里帮你补齐。