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