730 lines
21 KiB
Markdown
730 lines
21 KiB
Markdown
# TCP调试服务器通信协议说明
|
||
|
||
## 协议概述
|
||
|
||
本协议用于CCU601E充电桩TCP调试服务器与客户端之间的通信。协议基于JSON格式，包含心跳、系统信息、充电枪数据、充电控制、参数查询与修改等功能。
|
||
|
||
## 基本协议格式
|
||
|
||
所有消息遵循以下基本格式：
|
||
```json
|
||
{
|
||
"command": "命令类型",
|
||
"data": { ... },
|
||
"timestamp": "YYYY-MM-DD HH:MM:SS.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `command`: 命令类型（字符串）
|
||
- `data`: 命令数据（对象）
|
||
- `timestamp`: 时间戳，格式为"YYYY-MM-DD HH:MM:SS.000"
|
||
- `version`: 协议版本，固定为"2.0"
|
||
|
||
## 命令类型列表
|
||
|
||
| 命令 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 心跳 | Heartbeat | 心跳消息，用于保持连接 |
|
||
| 系统信息 | SystemInfo | 系统信息查询/上报 |
|
||
| 枪信息 | GunInfo | 充电枪数据查询/上报 |
|
||
| 充电控制 | ChargeControl | 充电启停控制 |
|
||
| 参数查询 | ParamQuery | 参数查询 |
|
||
| 参数修改 | ParamModify | 参数修改 |
|
||
| 文件操作 | FileOperations | 文件系统操作（查询、删除、下载、上传） |
|
||
|
||
## 1. 心跳消息 (Heartbeat)
|
||
|
||
### 1.1 服务器发送心跳
|
||
```json
|
||
{
|
||
"command": "Heartbeat",
|
||
"data": {
|
||
"sequence": 123,
|
||
"source": "device"
|
||
},
|
||
"timestamp": "2025-12-27 14:48:27.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `sequence`: 序列号，每次递增
|
||
- `source`: 来源，固定为"device"
|
||
|
||
### 1.2 客户端回复心跳
|
||
```json
|
||
{
|
||
"command": "Heartbeat",
|
||
"data": {
|
||
"sequence": 123,
|
||
"source": "client"
|
||
},
|
||
"timestamp": "2025-12-27 14:48:27.100",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
## 2. 系统信息 (SystemInfo)
|
||
|
||
### 2.1 服务器发送系统信息
|
||
```json
|
||
{
|
||
"command": "SystemInfo",
|
||
"data": {
|
||
"systemModel": "IES-2000",
|
||
"gunCount": 2,
|
||
"devicePower": 120.0,
|
||
"networkStatus": 1,
|
||
"faultCount": 0,
|
||
"version": "V1.2.3"
|
||
},
|
||
"timestamp": "2025-12-27 14:48:28.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `systemModel`: 系统型号
|
||
- `gunCount`: 枪数量
|
||
- `devicePower`: 设备功率(kW)
|
||
- `networkStatus`: 网络状态(0:异常, 1:正常)
|
||
- `faultCount`: 故障数量
|
||
- `version`: 软件版本
|
||
|
||
## 3. 充电枪信息 (GunInfo)
|
||
|
||
### 3.1 服务器发送枪信息
|
||
```json
|
||
{
|
||
"command": "GunInfo",
|
||
"data": {
|
||
"gunNumber": 1,
|
||
"chargingStatus": 2,
|
||
"gunConnectionStatus": 1,
|
||
"chargingTime": 125,
|
||
"demandVoltage": 400.0,
|
||
"demandCurrent": 32.0,
|
||
"actualVoltage": 398.5,
|
||
"actualCurrent": 30.2,
|
||
"energy": 15.7,
|
||
"cost": 31.4,
|
||
"batterySOC": 65.0,
|
||
"userId": "user001",
|
||
"orderNumber": "ORD20231227001"
|
||
},
|
||
"timestamp": "2025-12-27 14:48:29.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `gunNumber`: 枪编号(1-2)
|
||
- `chargingStatus`: 充电状态(0:空闲, 1:已连接, 2:充电中, 3:充电完成, 4:故障)
|
||
- `gunConnectionStatus`: 枪连接状态(0:未连接, 1:已连接)
|
||
- `chargingTime`: 充电时间(分钟)
|
||
- `demandVoltage`: 需求电压(V)
|
||
- `demandCurrent`: 需求电流(A)
|
||
- `actualVoltage`: 实际电压(V)
|
||
- `actualCurrent`: 实际电流(A)
|
||
- `energy`: 充电能量(kWh)
|
||
- `cost`: 充电费用(元)
|
||
- `batterySOC`: 电池SOC(%)
|
||
- `userId`: 用户ID
|
||
- `orderNumber`: 订单号
|
||
|
||
## 4. 充电控制 (ChargeControl)
|
||
|
||
### 4.1 客户端发送充电控制
|
||
```json
|
||
{
|
||
"command": "ChargeControl",
|
||
"data": {
|
||
"gunNumber": 1,
|
||
"action": 1
|
||
},
|
||
"timestamp": "2025-12-27 14:48:30.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `gunNumber`: 枪编号(1-2)
|
||
- `action`: 动作(0:停止充电, 1:启动充电)
|
||
|
||
### 4.2 服务器响应充电控制
|
||
```json
|
||
{
|
||
"command": "ChargeControl",
|
||
"data": {
|
||
"gunNumber": 1,
|
||
"action": 1,
|
||
"result": 0,
|
||
"message": "充电启动成功"
|
||
},
|
||
"timestamp": "2025-12-27 14:48:30.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `result`: 结果(0:成功, 1:失败)
|
||
- `message`: 结果消息
|
||
|
||
## 5. 参数查询与修改
|
||
|
||
### 5.1 参数分类(type字段)
|
||
|
||
| 类型 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 系统基本参数 | BasicParameters | 桩编号、功率、电压电流等 |
|
||
| 网络参数 | NetworkParameters | IP、域名、平台配置等 |
|
||
| 电表参数 | MeterParameters | 电表数量、归属、地址等 |
|
||
| 使能参数 | EnableParameters | 门禁、枪锁、国标等使能标志 |
|
||
| 费率参数 | FeeParameters | 计费模型、费率类型等 |
|
||
| SDK参数 | SDKParameters | 产品秘钥、设备密钥等 |
|
||
| 二维码参数 | QRCodeParameters | 各枪二维码内容 |
|
||
|
||
### 5.2 参数查询请求
|
||
```json
|
||
{
|
||
"command": "ParamQuery",
|
||
"data": {
|
||
"type": "BasicParameters"
|
||
},
|
||
"timestamp": "2025-12-27 14:48:31.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
### 5.3 参数查询响应
|
||
```json
|
||
{
|
||
"command": "ParamQuery",
|
||
"data": {
|
||
"type": "BasicParameters",
|
||
"count": 18,
|
||
"params": [
|
||
{
|
||
"name": "pile_serial_num",
|
||
"type": "string",
|
||
"value": "CCU601E-001"
|
||
},
|
||
{
|
||
"name": "u8_gunCnt",
|
||
"type": "uint8",
|
||
"value": 2
|
||
}
|
||
]
|
||
},
|
||
"timestamp": "2025-12-27 14:48:31.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `count`: 参数总数
|
||
- `params`: 参数数组
|
||
- `name`: 参数名称
|
||
- `type`: 参数类型
|
||
- `value`: 参数值
|
||
|
||
### 5.4 参数修改请求
|
||
```json
|
||
{
|
||
"command": "ParamModify",
|
||
"data": {
|
||
"type": "BasicParameters",
|
||
"params": [
|
||
{
|
||
"name": "pile_serial_num",
|
||
"type": "string",
|
||
"value": "CCU601E-002"
|
||
},
|
||
{
|
||
"name": "u8_threshold_gunTemp",
|
||
"type": "int",
|
||
"value": 85
|
||
}
|
||
]
|
||
},
|
||
"timestamp": "2025-12-27 14:48:32.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
### 5.5 参数修改响应
|
||
```json
|
||
{
|
||
"command": "ParamModify",
|
||
"data": {
|
||
"type": "BasicParameters",
|
||
"received": 2,
|
||
"processed": 2,
|
||
"success": 2,
|
||
"failed": 0
|
||
},
|
||
"timestamp": "2025-12-27 14:48:32.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `received`: 接收到的参数数量
|
||
- `processed`: 已处理的参数数量
|
||
- `success`: 成功的参数数量
|
||
- `failed`: 失败的参数数量
|
||
|
||
## 6. 参数详细列表
|
||
|
||
### 6.1 BasicParameters（系统基本参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| pile_serial_num | string | 桩编号 | "CCU601E-001" |
|
||
| u8_pwd | string | 维护密码 | "123456" |
|
||
| u8_gunCnt | uint8 | 枪数量 | 2 |
|
||
| u8_pile_type | uint8 | 桩类型 | 1 |
|
||
| u8_terminal | uint8_array | 终端地址 | [0, 0] |
|
||
| e_ledType | uint8 | 灯板类型 | 0 |
|
||
| u8_threshold_gunTemp | uint8 | 枪温阈值(°C) | 90 |
|
||
| u8_soc_limit | uint8 | SOC阈值(%) | 100 |
|
||
| u16_ratePow | uint32 | 额定功率(W) | 120000 |
|
||
| u16_max_volt | uint16 | 最大电压(0.1V) | 10000 |
|
||
| u16_min_volt | uint16 | 最小电压(0.1V) | 2000 |
|
||
| u16_trickle_limit | uint16 | 涓流充电停机阈值(0.1A) | 100 |
|
||
| u16_max_cur | uint16 | 最大电流(0.1A) | 2500 |
|
||
| u8_mdu_num | uint8 | 充电模块数量 | 4 |
|
||
| u8_MduType | uint8 | 模块类型 | 1 |
|
||
| u8_mduTemp_flag | uint8 | 模块温度获取使能 | 1 |
|
||
| u8_mdu_rated_pow | uint8 | 模块额定功率(kW) | 30 |
|
||
| u16_mdu_max_vol | uint16 | 模块最大电压(0.1V) | 10000 |
|
||
| u16_mdu_max_cur | uint16 | 模块最大电流(0.1A) | 3000 |
|
||
|
||
### 6.2 NetworkParameters（网络参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| ethIp | array | IP地址(4字节数组) | [192,168,1,140] |
|
||
| ethGate | array | 网关(4字节数组) | [192,168,1,254] |
|
||
| ethMask | array | 子网掩码(4字节数组) | [255,255,255,0] |
|
||
| ethMac | array | MAC地址(6字节数组) | [0,14,234,3,165,1] |
|
||
| serverADomain | string | 服务器A域名 | "39.104.96.26,8897" |
|
||
| serverBDomain | string | 服务器B域名 | "" |
|
||
| platAPileNum | string | 平台1桩编号 | "" |
|
||
| platBPileNum | string | 平台2桩编号 | "" |
|
||
| programType | bit | 程序类型(2位) 0:社会,1:sdk,2:ocpp | 0b00 |
|
||
| netAType | bit | 平台1联网方式(2位) 0:以太网,1:GPRS | 0b00 |
|
||
| netBType | bit | 平台2联网方式(2位) 0:以太网,1:GPRS | 0b00 |
|
||
| platAEn | bit | 平台1使能(2位) 0:不使能,1:使能 | 0b01 |
|
||
| platBEn | bit | 平台2使能(2位) 0:不使能,1:使能 | 0b01 |
|
||
| platAType | bit | 平台1类型(4位) 0:云快充,1:... | 0b0000 |
|
||
| platBType | bit | 平台2类型(4位) 默认积成平台 | 0b0000 |
|
||
| simAnpType | bit | SIM卡APN类型(2位) 0:公网卡,1:国网移动,2:国网联通,3:国网电信 | 0b00 |
|
||
|
||
### 6.3 MeterParameters（电表参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| u8_meter_num | uint8 | 电表数量(0-4) | 2 |
|
||
| meter_0_inGun | uint8 | 电表0归属枪号(0:无效,1:A枪,2:B枪) | 1 |
|
||
| meter_0_highPrec | uint8 | 电表0高精度支持(0:不支持,1:支持) | 1 |
|
||
| meter_0_isAC | uint8 | 电表0是否为交流表(0:直流表,1:交流表) | 0 |
|
||
| meter_0_addr | hex_array | 电表0地址(6字节) | "00 00 00 00 00 00" |
|
||
| meter_1_inGun | uint8 | 电表1归属枪号 | 2 |
|
||
| meter_1_highPrec | uint8 | 电表1高精度支持 | 1 |
|
||
| meter_1_isAC | uint8 | 电表1是否为交流表 | 0 |
|
||
| meter_1_addr | hex_array | 电表1地址 | "00 00 00 00 00 00" |
|
||
| meter_2_inGun | uint8 | 电表2归属枪号 | 1 |
|
||
| meter_2_highPrec | uint8 | 电表2高精度支持 | 0 |
|
||
| meter_2_isAC | uint8 | 电表2是否为交流表 | 1 |
|
||
| meter_2_addr | hex_array | 电表2地址 | "00 00 00 00 00 00" |
|
||
| meter_3_inGun | uint8 | 电表3归属枪号 | 2 |
|
||
| meter_3_highPrec | uint8 | 电表3高精度支持 | 0 |
|
||
| meter_3_isAC | uint8 | 电表3是否为交流表 | 1 |
|
||
| meter_3_addr | hex_array | 电表3地址 | "00 00 00 00 00 00" |
|
||
|
||
### 6.4 EnableParameters（使能参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| bit_doorEnable | uint8 | 门禁使能 | 0 |
|
||
| bit_gunLockEna | uint8 | 枪锁使能 | 1 |
|
||
| bit_gunLockNeg | uint8 | 枪锁信号取反 | 0 |
|
||
| bit_AcContactEna | uint8 | 交流接触器使能 | 1 |
|
||
| bit_gunHoming | uint8 | 枪归位信号有无 | 1 |
|
||
| bit_GBEnable | uint8 | 国标使能 | 1 |
|
||
| bit_LcdEnable | uint8 | 液晶使能 | 1 |
|
||
| bit_auxpower | uint8 | 辅助电压返回状态使能 | 0 |
|
||
| bit_reliefen | uint8 | 泄放使能 | 1 |
|
||
| bit_YeLenEn | uint8 | 液冷通讯使能 | 0 |
|
||
| bit_ABcommEn | uint8 | 主副班通讯使能 | 0 |
|
||
| bit_ScreenSaverEn | uint8 | UI屏保使能 | 1 |
|
||
| bit_PlugEn | uint8 | 即插即充使能 | 0 |
|
||
| bit_uiEnglishEn | uint8 | UI界面英语使能 | 0 |
|
||
|
||
### 6.5 FeeParameters（费率参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| u8_model_no | string | 计费模型编号(17字节) | "FEE20231227001" |
|
||
| u8_feeCnt | uint8 | 费率条数(0-30) | 5 |
|
||
| fee_type_0_rate | uint32 | 费率类型0费率(小数点后5位) | 15000 |
|
||
| fee_type_0_sevice | uint32 | 费率类型0服务费(小数点后5位) | 500 |
|
||
| fee_type_1_rate | uint32 | 费率类型1费率 | 18000 |
|
||
| fee_type_1_sevice | uint32 | 费率类型1服务费 | 600 |
|
||
| fee_type_2_rate | uint32 | 费率类型2费率 | 20000 |
|
||
| fee_type_2_sevice | uint32 | 费率类型2服务费 | 700 |
|
||
| ... | ... | ... | ... |
|
||
| fee_type_29_rate | uint32 | 费率类型29费率 | 0 |
|
||
| fee_type_29_sevice | uint32 | 费率类型29服务费 | 0 |
|
||
| u8_fee_type_0 | uint8 | 时段0费率类型(1-30) | 1 |
|
||
| u8_fee_type_1 | uint8 | 时段1费率类型 | 1 |
|
||
| u8_fee_type_2 | uint8 | 时段2费率类型 | 1 |
|
||
| ... | ... | ... | ... |
|
||
| u8_fee_type_95 | uint8 | 时段95费率类型 | 3 |
|
||
|
||
### 6.6 SDKParameters（SDK参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| product_key | string | 产品秘钥(20字节) | "" |
|
||
| device_name | string | 资产码(32字节) | "" |
|
||
| device_secret | string | 设备密钥(64字节) | "" |
|
||
| device_reg_code | string | 注册码(64字节) | "" |
|
||
| device_uid | string | 出厂编码(64字节) | "" |
|
||
| firmware_version | string | 固件版本信息(64字节) | "V1.0.0" |
|
||
|
||
### 6.7 QRCodeParameters（二维码参数）
|
||
| 参数名 | 类型 | 说明 | 示例值 |
|
||
|--------|------|------|--------|
|
||
| qrcode_gun1 | string | 枪1二维码 | "https://example.com/qr/001" |
|
||
| qrcode_gun2 | string | 枪2二维码 | "https://example.com/qr/002" |
|
||
|
||
## 7. 文件操作 (FileOperations)
|
||
|
||
文件操作用于上位机对单片机文件系统进行操作，包含查询、删除、下载、上传四种操作。
|
||
|
||
### 7.1 文件操作子命令
|
||
|
||
| 子命令 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| 文件查询 | Query | 查询指定目录下的文件列表 |
|
||
| 文件删除 | Delete | 删除指定文件 |
|
||
| 文件下载 | Download | 下载文件内容 |
|
||
| 文件上传 | Upload | 上传文件到设备 |
|
||
|
||
### 7.2 文件查询请求
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Query",
|
||
"path": "/",
|
||
"recursive": 0
|
||
},
|
||
"timestamp": "2025-12-29 14:00:00.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `subCommand`: 子命令，固定为"Query"
|
||
- `path`: 查询路径，如"/"表示根目录
|
||
- `recursive`: 是否递归查询（0:否, 1:是）
|
||
|
||
### 7.3 文件查询响应
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Query",
|
||
"path": "/",
|
||
"fileCount": 3,
|
||
"dirCount": 2,
|
||
"totalSize": 1050624,
|
||
"files": [
|
||
{
|
||
"name": "config.txt",
|
||
"type": 0,
|
||
"size": 1024,
|
||
"modifiedTime": "2025-12-29 10:00:00",
|
||
"createdTime": "2025-12-29 10:00:00"
|
||
},
|
||
{
|
||
"name": "log.txt",
|
||
"type": 0,
|
||
"size": 2048,
|
||
"modifiedTime": "2025-12-29 11:30:00",
|
||
"createdTime": "2025-12-29 11:30:00"
|
||
},
|
||
{
|
||
"name": "firmware.bin",
|
||
"type": 0,
|
||
"size": 1048576,
|
||
"modifiedTime": "2025-12-29 12:00:00",
|
||
"createdTime": "2025-12-29 12:00:00"
|
||
}
|
||
]
|
||
},
|
||
"timestamp": "2025-12-29 14:00:00.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `fileCount`: 文件数量
|
||
- `dirCount`: 目录数量
|
||
- `totalSize`: 总文件大小（字节）
|
||
- `files`: 文件信息数组
|
||
- `name`: 文件名
|
||
- `type`: 文件类型（0:普通文件, 1:目录, 2:系统文件）
|
||
- `size`: 文件大小（字节）
|
||
- `modifiedTime`: 修改时间
|
||
- `createdTime`: 创建时间
|
||
|
||
### 7.4 文件删除请求
|
||
|
||
文件删除请求支持两种格式：
|
||
|
||
#### 格式1：直接指定完整路径
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Delete",
|
||
"path": "/config.txt",
|
||
"force": 0
|
||
},
|
||
"timestamp": "2025-12-29 14:01:00.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
#### 格式2：指定路径和文件名（推荐格式）
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Delete",
|
||
"fileName": "20260104_143116.log",
|
||
"path": "/log",
|
||
"force": 0
|
||
},
|
||
"timestamp": "2026-01-04 15:06:04.630",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `subCommand`: 子命令，固定为"Delete"
|
||
- `path`: 文件路径（格式1）或目录路径（格式2）
|
||
- `fileName`: 文件名（仅格式2需要）
|
||
- `force`: 强制删除（0:否, 1:是），可选字段，默认为0
|
||
|
||
**注意**：
|
||
1. 格式1中，`path`字段包含完整的文件路径（如`/config.txt`）
|
||
2. 格式2中，`path`字段为目录路径，`fileName`为文件名，系统会自动组合为完整路径：`path + "/" + fileName`
|
||
3. 如果同时提供`path`和`fileName`字段，优先使用格式2（组合路径）
|
||
4. `force`字段为可选字段，默认为0（不强制删除）。当设置为1时，允许删除系统文件
|
||
|
||
### 7.5 文件删除响应
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Delete",
|
||
"path": "/config.txt",
|
||
"status": 0,
|
||
"message": "File deleted successfully"
|
||
},
|
||
"timestamp": "2025-12-29 14:01:00.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `status`: 删除状态（0:成功, 1:失败, 3:文件未找到, 5:权限不足）
|
||
- `message`: 结果消息
|
||
|
||
### 7.6 文件下载请求
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Download",
|
||
"path": "/log.txt",
|
||
"offset": 0,
|
||
"chunkSize": 1024
|
||
},
|
||
"timestamp": "2025-12-29 14:02:00.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `subCommand`: 子命令，固定为"Download"
|
||
- `path`: 文件路径
|
||
- `offset`: 起始偏移（字节），用于断点续传。首次下载设置为0
|
||
- `chunkSize`: 分块大小（字节），最大1024字节，超过1024会自动限制为1024
|
||
|
||
**下载流程说明**：
|
||
1. 客户端首次请求时，设置`offset=0`，`chunkSize`建议设置为1024（最大支持值）
|
||
2. 服务器返回文件的第一块数据，包含`fileSize`（文件总大小）和`isLastChunk`标志
|
||
3. 客户端根据返回的`dataLen`计算下一次请求的偏移：`offset = offset + dataLen`
|
||
4. 重复步骤1-3，直到`isLastChunk=1`表示下载完成
|
||
5. 如果下载中断，可以从上次的偏移位置继续下载（断点续传）
|
||
|
||
### 7.7 文件下载响应
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Download",
|
||
"path": "/log.txt",
|
||
"fileSize": 2048,
|
||
"offset": 0,
|
||
"chunkSize": 1024,
|
||
"dataLen": 11,
|
||
"isLastChunk": 0,
|
||
"data": "SGVsbG8gV29ybGQ="
|
||
},
|
||
"timestamp": "2025-12-29 14:02:00.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `fileSize`: 文件总大小（字节）
|
||
- `offset`: 当前数据块的起始偏移（字节）
|
||
- `chunkSize`: 实际使用的分块大小（字节），可能与请求的chunkSize不同（受1024字节限制）
|
||
- `dataLen`: Base64编码后的数据长度（字节）
|
||
- `isLastChunk`: 是否为最后一块（0:否, 1:是）。当`offset + dataLen >= fileSize`时为1
|
||
- `data`: 数据内容（Base64编码）。实际二进制数据大小为`dataLen`字节，Base64编码后长度约为`dataLen * 4/3`
|
||
|
||
**技术细节**：
|
||
1. **分块限制**：每块数据最大1024字节。如果请求的`chunkSize`超过1024，会自动限制为1024
|
||
2. **Base64编码**：所有文件数据都使用Base64编码传输，确保二进制数据的安全传输
|
||
3. **进度计算**：下载进度可通过公式计算：`进度 = (offset + dataLen) / fileSize * 100%`
|
||
4. **错误处理**：
|
||
- 如果文件不存在，返回错误
|
||
- 如果`offset`超过文件大小，返回错误
|
||
- 如果读取文件失败，返回错误
|
||
5. **内存管理**：客户端需要及时释放接收到的数据内存，避免内存泄漏
|
||
|
||
### 7.8 文件上传请求
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Upload",
|
||
"path": "/upload/newfile.txt",
|
||
"fileSize": 4096,
|
||
"chunkSize": 1024,
|
||
"offset": 0,
|
||
"data": "SGVsbG8gV29ybGQ=",
|
||
"dataLen": 11,
|
||
"isLastChunk": 0
|
||
},
|
||
"timestamp": "2025-12-29 14:03:00.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `subCommand`: 子命令，固定为"Upload"
|
||
- `path`: 文件路径
|
||
- `fileSize`: 文件总大小
|
||
- `chunkSize`: 分块大小
|
||
- `offset`: 当前偏移
|
||
- `data`: 数据内容（Base64编码）
|
||
- `dataLen`: 数据长度
|
||
- `isLastChunk`: 是否为最后一块（0:否, 1:是）
|
||
|
||
### 7.9 文件上传响应
|
||
```json
|
||
{
|
||
"command": "FileOperations",
|
||
"data": {
|
||
"subCommand": "Upload",
|
||
"path": "/upload/newfile.txt",
|
||
"receivedSize": 1024,
|
||
"totalSize": 4096,
|
||
"status": 2,
|
||
"message": "Upload in progress"
|
||
},
|
||
"timestamp": "2025-12-29 14:03:00.500",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
- `receivedSize`: 已接收大小
|
||
- `totalSize`: 文件总大小
|
||
- `status`: 上传状态（0:成功, 1:失败, 2:进行中, 4:空间不足）
|
||
- `message`: 结果消息
|
||
|
||
### 7.10 文件操作状态码
|
||
|
||
| 状态码 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| 成功 | 0 | 操作成功 |
|
||
| 失败 | 1 | 操作失败 |
|
||
| 进行中 | 2 | 操作进行中（适用于上传/下载） |
|
||
| 文件未找到 | 3 | 文件不存在 |
|
||
| 空间不足 | 4 | 磁盘空间不足 |
|
||
| 权限不足 | 5 | 权限不足 |
|
||
|
||
## 8. 数据类型说明
|
||
|
||
| 类型 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| string | 字符串 | "CCU601E-001" |
|
||
| int | 整数 | 85 |
|
||
| uint8 | 无符号8位整数 | 2 |
|
||
| uint16 | 无符号16位整数 | 2500 |
|
||
| uint32 | 无符号32位整数 | 120000 |
|
||
| ip_address | IP地址字符串 | "192.168.1.140" |
|
||
| mac_address | MAC地址字符串 | "00:0E:EA:03:A5:01" |
|
||
| hex_array | 十六进制数组字符串 | "00 00 00 00 00 00" |
|
||
| uint8_array | 无符号8位整数数组 | [1,1,1,2,2,2,3,3,3] |
|
||
|
||
## 8. 通信流程
|
||
|
||
### 8.1 连接建立
|
||
1. 客户端连接TCP服务器（端口9699）
|
||
2. 服务器接受连接（仅允许一个客户端）
|
||
3. 开始周期性通信
|
||
|
||
### 8.2 周期性消息
|
||
- 心跳：每10秒发送一次
|
||
- 系统信息：每10秒发送一次
|
||
- 充电枪数据：每1秒发送一次（两把枪分别发送）
|
||
|
||
### 8.3 心跳超时
|
||
- 客户端超过60秒未发送心跳，服务器主动断开连接
|
||
|
||
### 8.4 命令交互
|
||
1. 客户端发送命令请求
|
||
2. 服务器处理命令并返回响应
|
||
3. 错误时返回相应的错误信息
|
||
|
||
## 9. 错误处理
|
||
|
||
### 9.1 通用错误格式
|
||
```json
|
||
{
|
||
"command": "原命令",
|
||
"data": {
|
||
"error": {
|
||
"code": 1001,
|
||
"message": "错误描述"
|
||
}
|
||
},
|
||
"timestamp": "2025-12-27 14:48:33.000",
|
||
"version": "2.0"
|
||
}
|
||
```
|
||
|
||
### 9.2 错误码定义
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 1000 | 参数解析错误 |
|
||
| 1001 | 命令不支持 |
|
||
| 1002 | 参数缺失 |
|
||
| 1003 | 参数值无效 |