Files

T

wangyan 9ceb218f80 Initial commit: CCU621_M firmware project with BLE debug link support.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-08 17:28:36 +08:00

21 KiB

Raw Blame History

TCP调试服务器通信协议说明

协议概述

本协议用于CCU601E充电桩TCP调试服务器与客户端之间的通信。协议基于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 服务器发送心跳

{
  "command": "Heartbeat",
  "data": {
    "sequence": 123,
    "source": "device"
  },
  "timestamp": "2025-12-27 14:48:27.000",
  "version": "2.0"
}

字段说明：

sequence: 序列号，每次递增
source: 来源，固定为"device"

1.2 客户端回复心跳

{
  "command": "Heartbeat",
  "data": {
    "sequence": 123,
    "source": "client"
  },
  "timestamp": "2025-12-27 14:48:27.100",
  "version": "2.0"
}

2. 系统信息 (SystemInfo)

2.1 服务器发送系统信息

{
  "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 服务器发送枪信息

{
  "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 客户端发送充电控制

{
  "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 服务器响应充电控制

{
  "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 参数查询请求

{
  "command": "ParamQuery",
  "data": {
    "type": "BasicParameters"
  },
  "timestamp": "2025-12-27 14:48:31.000",
  "version": "2.0"
}

5.3 参数查询响应

{
  "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 参数修改请求

{
  "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 参数修改响应

{
  "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 文件查询请求

{
  "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 文件查询响应

{
  "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：直接指定完整路径

{
  "command": "FileOperations",
  "data": {
    "subCommand": "Delete",
    "path": "/config.txt",
    "force": 0
  },
  "timestamp": "2025-12-29 14:01:00.000",
  "version": "2.0"
}

格式2：指定路径和文件名（推荐格式）

{
  "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中，path字段包含完整的文件路径（如/config.txt）
格式2中，path字段为目录路径，fileName为文件名，系统会自动组合为完整路径：path + "/" + fileName
如果同时提供path和fileName字段，优先使用格式2（组合路径）
force字段为可选字段，默认为0（不强制删除）。当设置为1时，允许删除系统文件

7.5 文件删除响应

{
  "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 文件下载请求

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

下载流程说明：

客户端首次请求时，设置offset=0，chunkSize建议设置为1024（最大支持值）
服务器返回文件的第一块数据，包含fileSize（文件总大小）和isLastChunk标志
客户端根据返回的dataLen计算下一次请求的偏移：offset = offset + dataLen
重复步骤1-3，直到isLastChunk=1表示下载完成
如果下载中断，可以从上次的偏移位置继续下载（断点续传）

7.7 文件下载响应

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

技术细节：

分块限制：每块数据最大1024字节。如果请求的chunkSize超过1024，会自动限制为1024
Base64编码：所有文件数据都使用Base64编码传输，确保二进制数据的安全传输
进度计算：下载进度可通过公式计算：进度 = (offset + dataLen) / fileSize * 100%
错误处理：
- 如果文件不存在，返回错误
- 如果offset超过文件大小，返回错误
- 如果读取文件失败，返回错误
内存管理：客户端需要及时释放接收到的数据内存，避免内存泄漏

7.8 文件上传请求

{
  "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 文件上传响应

{
  "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 连接建立

客户端连接TCP服务器（端口9699）
服务器接受连接（仅允许一个客户端）
开始周期性通信

8.2 周期性消息

心跳：每10秒发送一次
系统信息：每10秒发送一次
充电枪数据：每1秒发送一次（两把枪分别发送）

8.3 心跳超时

客户端超过60秒未发送心跳，服务器主动断开连接

8.4 命令交互

客户端发送命令请求
服务器处理命令并返回响应
错误时返回相应的错误信息

9. 错误处理

9.1 通用错误格式

{
  "command": "原命令",
  "data": {
    "error": {
      "code": 1001,
      "message": "错误描述"
    }
  },
  "timestamp": "2025-12-27 14:48:33.000",
  "version": "2.0"
}

9.2 错误码定义

错误码	说明
1000	参数解析错误
1001	命令不支持
1002	参数缺失
1003	参数值无效

21 KiB Raw Blame History Unescape Escape

TCP调试服务器通信协议说明

协议概述

基本协议格式

命令类型列表

1. 心跳消息 (Heartbeat)

1.1 服务器发送心跳

1.2 客户端回复心跳

2. 系统信息 (SystemInfo)

2.1 服务器发送系统信息

3. 充电枪信息 (GunInfo)

3.1 服务器发送枪信息

4. 充电控制 (ChargeControl)

4.1 客户端发送充电控制

4.2 服务器响应充电控制

5. 参数查询与修改

5.1 参数分类(type字段)

5.2 参数查询请求

5.3 参数查询响应

5.4 参数修改请求

5.5 参数修改响应

6. 参数详细列表

6.1 BasicParameters（系统基本参数）

6.2 NetworkParameters（网络参数）

6.3 MeterParameters（电表参数）

6.4 EnableParameters（使能参数）

6.5 FeeParameters（费率参数）

6.6 SDKParameters（SDK参数）

6.7 QRCodeParameters（二维码参数）

7. 文件操作 (FileOperations)

7.1 文件操作子命令

7.2 文件查询请求

7.3 文件查询响应

7.4 文件删除请求

格式1：直接指定完整路径

格式2：指定路径和文件名（推荐格式）

7.5 文件删除响应

7.6 文件下载请求

7.7 文件下载响应

7.8 文件上传请求

7.9 文件上传响应

7.10 文件操作状态码

8. 数据类型说明

8. 通信流程

8.1 连接建立

8.2 周期性消息

8.3 心跳超时

8.4 命令交互

9. 错误处理

9.1 通用错误格式

9.2 错误码定义

21 KiB

Raw Blame History