opc source code

docs/UPLINK_WIRE_PROTOCOL.md

@@ -0,0 +1,130 @@
+# 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` 下行同步对象模型