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 示例

{
  "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 示例

{
  "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 下行同步对象模型

4.2 KiB Raw Blame History Unescape Escape