# think-light-protocol

**Repository Path**: osheyx/think-light-protocol

## Basic Information

- **Project Name**: think-light-protocol
- **Description**: ThinkLight 板端↔网关报文契约唯一来源：JSON Schema + Rust crate + Python 包
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/osheyx/think-light
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# think-light-protocol

ThinkLight **板端 ↔ 主机网关**通信报文的**唯一契约来源**。

固件（C）、网关（Rust / Python）三方都从这里派生类型；任何一方想改报文，先改这里。

[← 返回编排仓 think-light](https://gitee.com/osheyx/think-light)

## 状态

✅ 协议 schema、Rust crate、Python 包均已落地，`python3 scripts/validate.py` 可做三方自洽校验（零依赖）。

## 目录

```
think-light-protocol/
├── protocol/schema/messages.schema.json   # JSON Schema（权威）
├── rust/                                  # Rust crate（serde）
├── python/                                # Python 包（dataclass）
└── scripts/validate.py                    # schema 自洽性校验
```

## 报文总览

所有报文共用一个头：

```json
{ "msg_id": 1001, "type": "task_update", "ts": 1728000000 }
```

`msg_id` 用于下行去重（板端收到重复 msg_id 直接丢弃）；`ts` 为 Unix 秒。

### 上行（板 → 网关）

| type | 触发 | 核心字段 |
| --- | --- | --- |
| `sensor_report` | 周期上报传感器（默认 500ms） | `light` `proximity` `accel` `step` `mic` |
| `board_heartbeat` | 5s 保活 | `fw_version` `hw_version` `heap_free` `link_status` `task_count` |
| `key_event` | 按键按下/长按 | `key` `action` |
| `cmd_ack` | 下行命令执行确认 | `code` `msg` |

### 下行（网关 → 板）

| type | 触发 | 核心字段 |
| --- | --- | --- |
| `task_update` | 任务状态变化 | `task_id` `agent_type` `state` `progress` `brief` |
| `task_add` | 新增任务 | `task_id` `agent_type` `brief` |
| `task_cancel` | 取消任务 | `task_id` |
| `sys_cmd` | 系统控制 | `cmd`（`reboot` / `calibrate` / `set_brightness` / …） |

### 任务状态机

```
IDLE → SAMPLING → SEND → THINKING → RECV_CMD → IDLE
                          ↓
                        ERROR
```

`progress` 为 0–100 整数；`brief` 为不超过 64 字节的 UTF-8 摘要（整条报文 ≤ 256 字节）。

## MQTT 主题

```
thinklight/{board_id}/up/sensor
thinklight/{board_id}/up/heartbeat
thinklight/{board_id}/up/event
thinklight/{board_id}/down/task
thinklight/{board_id}/down/sys
```

USB 串口链路使用**完全相同**的 JSON 报文格式（换行 `\n` 分帧），保证链路切换业务无感。

## 版本策略

- 协议有**独立版本号**，与固件版本、网关版本三者分开维护。
- **向后兼容**：高版本网关必须能解析低版本固件的报文。
- 破坏性变更 = 增删字段或改字段语义 → 升协议主版本；加可选字段 → 升次版本。

## 使用

### 安装

```bash
# Rust（library crate）
cargo add thinklight-protocol

# Python
pip install ./python
```

### 用法

```rust
// rust
use thinklight_protocol::{UpMessage, DownMessage};
let msg = UpMessage::sensor_report(1, &sensor);
```

```python
# python
from thinklight_protocol import UpMessage
msg = UpMessage.sensor_report(1, sensor)
```

### 校验 schema

`scripts/validate.py` 会交叉校验 schema / Rust / Python 三方是否一致（报文类型、协议版本、枚举取值、长度上限）：

```bash
python3 scripts/validate.py
```

装了 `jsonschema` 还会额外用 schema 校验 8 条样例报文：

```bash
pip install jsonschema && python3 scripts/validate.py
```

## 相关仓库

| 仓库 | 职责 |
| --- | --- |
| [think-light](https://gitee.com/osheyx/think-light) | 编排仓：方案总纲、ADR、安装脚本、统一命令入口 |
| [think-light-firmware](https://gitee.com/osheyx/think-light-firmware) | 板端 C 固件 |
| [think-light-gateway-rs](https://gitee.com/osheyx/think-light-gateway-rs) | Rust 网关（生产版） |
| [think-light-gateway-py](https://gitee.com/osheyx/think-light-gateway-py) | Python 网关（调试版） |
| [think-light-dashboard](https://gitee.com/osheyx/think-light-dashboard) | Web 仪表盘 |
| [think-light-plugins](https://gitee.com/osheyx/think-light-plugins) | 官方插件样例 |

## License

[MIT](LICENSE) © 2026 heyongxian