131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# UplinkWire 协议 v1
|
||
|
||
本文档定义 **边缘 `softbus_edge` → 核心 `softbus_daemon`** 的 TCP JSON 行协议。Phase 1 采用简化线格式，便于快速验证 OPC UA 绑定；与 soft_bus 主项目的二进制 `SBUP` 协议（EDGE_UPLINK_PROTOCOL_v1）相互独立。
|
||
|
||
## 1. 传输
|
||
|
||
| 项 | 约定 |
|
||
|----|------|
|
||
| 传输层 | TCP |
|
||
| 连接方向 | 边缘主动连接，守护进程监听 |
|
||
| 默认地址 | `127.0.0.1:9000`（`daemon_profile.json` → `uplink`） |
|
||
| 消息分隔 | 每条消息一行 JSON，以 `\n`（0x0A）结尾 |
|
||
| 字符编码 | UTF-8 |
|
||
| Phase 1 限制 | 无 HELLO/认证握手，连接即发送 |
|
||
|
||
## 2. 消息类型枚举
|
||
|
||
| 值 | `type` 字段 | 方向 | 说明 |
|
||
|----|-------------|------|------|
|
||
| 1 | `rawPacket` | 边缘→核心 | 原始总线数据上行 |
|
||
| 2 | `executeCommand` | 核心→边缘 | 控制命令下行 |
|
||
|
||
解码时通过 JSON 根字段 `type` 区分（对应 `WireMessageType` 枚举）。
|
||
|
||
## 3. rawPacket（边缘→核心）
|
||
|
||
### 3.1 JSON 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 是 | 固定 `"rawPacket"` |
|
||
| `traceId` | string | 是 | 追踪 ID，格式 `trace-xxxxxxxx` |
|
||
| `timestampNs` | integer | 是 | 纳秒级时间戳 |
|
||
| `runtimeDeviceId` | string | 是 | 运行时设备 ID，格式 `runtime-xxxxxxxx` |
|
||
| `sourceId` | string | 是 | 对象路径，如 `DemoSite/.../Temperature` |
|
||
| `protocolTag` | string | 是 | 协议标识，如 `"modbus"` |
|
||
| `payloadBase64` | string | 是 | 原始 payload 的 Base64 编码 |
|
||
|
||
### 3.2 示例
|
||
|
||
```json
|
||
{
|
||
"type": "rawPacket",
|
||
"traceId": "trace-a1b2c3d4",
|
||
"timestampNs": 1717920000000000000,
|
||
"runtimeDeviceId": "runtime-e5f6g7h8",
|
||
"sourceId": "DemoSite/DemoSystem/DemoAsset/SimModbusDevice/Temperature",
|
||
"protocolTag": "modbus",
|
||
"payloadBase64": "MDEwMzAyMDAwMDAwMDE="
|
||
}
|
||
```
|
||
|
||
### 3.3 对应核心类型
|
||
|
||
解码后映射至 `softbus::core::RawPacket`：
|
||
|
||
| JSON 字段 | RawPacket 字段 |
|
||
|-----------|----------------|
|
||
| `traceId` | `traceId` |
|
||
| `timestampNs` | `timestampNs` |
|
||
| `runtimeDeviceId` | `runtimeDeviceId` |
|
||
| `sourceId` | `sourceId` |
|
||
| `protocolTag` | `protocolTag` |
|
||
| `payloadBase64` | `payload`（Base64 解码为 `vector<uint8_t>`） |
|
||
|
||
## 4. executeCommand（核心→边缘）
|
||
|
||
### 4.1 JSON 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 是 | 固定 `"executeCommand"` |
|
||
| `traceId` | string | 是 | 追踪 ID |
|
||
| `objectRef` | string | 是 | 目标对象路径（五层） |
|
||
| `command` | string | 是 | 命令名，如 `"write"` |
|
||
| `params` | object | 是 | 命令参数 JSON 对象 |
|
||
|
||
### 4.2 示例
|
||
|
||
```json
|
||
{
|
||
"type": "executeCommand",
|
||
"traceId": "trace-cmd-001",
|
||
"objectRef": "DemoSite/DemoSystem/DemoAsset/SimModbusDevice/Temperature",
|
||
"command": "write",
|
||
"params": {"value": 42.5}
|
||
}
|
||
```
|
||
|
||
### 4.3 校验规则
|
||
|
||
`ExecuteCommand::validate()` 要求：
|
||
|
||
- `traceId`、`objectRef`、`command` 非空
|
||
- `objectRef` 须为合法五层路径（`ObjectRef::isValid()`）
|
||
- `params` 须为 JSON 对象
|
||
|
||
### 4.4 对应核心类型
|
||
|
||
解码后映射至 `softbus::api::ExecuteCommand`。
|
||
|
||
## 5. 编解码 API
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `encodeWireMessage(RawPacket)` | 编码上行消息，追加 `\n` |
|
||
| `encodeWireMessage(ExecuteCommand)` | 编码下行消息，追加 `\n` |
|
||
| `decodeWireMessage(line)` | 解码单行，返回 `optional<WireMessage>` |
|
||
| `base64Encode(data, size)` | payload 编码 |
|
||
| `base64Decode(encoded)` | payload 解码 |
|
||
|
||
实现位置：`src/softbus_transport/src/UplinkWire.cpp`
|
||
|
||
## 6. 与 SBUP 二进制协议对比
|
||
|
||
| 维度 | UplinkWire（本项目） | SBUP（soft_bus） |
|
||
|------|---------------------|------------------|
|
||
| 帧格式 | JSON 行 + `\n` | 定长头 + 变长 payload |
|
||
| Magic | 无 | `SBUP`（4 字节） |
|
||
| 字节序 | 不适用（文本） | 大端 |
|
||
| 认证 | Phase 1 无 | HELLO + authToken |
|
||
| 树同步 | 无 | TREE_FULL / TREE_PROPOSE |
|
||
| 数据面 | `rawPacket` JSON | `DATA_RAWBUS` 二进制 |
|
||
| 适用场景 | Phase 1 原型验证 | 生产级边缘接入 |
|
||
|
||
## 7. Phase 2 规划
|
||
|
||
- 可选迁移至 SBUP 二进制帧，与 soft_bus 对齐
|
||
- 增加 HELLO 握手与 `authToken` 认证
|
||
- 支持 `TREE_FULL` 下行同步对象模型
|