智能终端（充电柜类）通信协议用户手册

User Manual of Communication Protocol for Intelligent Terminal (charging Cabinet)

版本2.0 2018 年05 月

Version 2.0, 201805

 版本历史 Version History
版本 日期 修改内容 Amendment
Date 修改人 章节
Version Modifier Chapter 内容 Content
1.0 2017-02-12 Huang.sir All 创建文本 Create text
2.0 2018-05-12 Zhong.Sir All 补充 supplement
3.3 2018-07-10 Zhong.sir All 补充 supplement

2
目录 Content
版本历史 Version Histor.y..........................................................................................................................................................
II
1 基本名词定义 Basic Noun Definition ...........................................................................................................................................
5
1.1 基本名字定义 Basic....N ...a..m ....e...D ...e ...f.i.n..i.t..i.o..n.............................................................................................
5
1.2 功能码表 Function code table .........................................................................................
5
2 通讯协议模板 Commun.i.c.a..t.i.o..n...p..r.o..t.o..c..o..l..t.e..m ...p..l.a..t.e.......................................................................................
6
2.1 通讯协议模板C ...o..m ...m ...u..n..ic..a..t.i.o..n...p..r.o..t.o..c..o..l..t.e..m ...p..l.a..t.e............................................................................
6
3 通讯协议规
范.C..o..m
...m
...u
..n
...ic..a..t.i.o..n...p..r.o..t.o..c..o..l..s..p..e..c.i.f.i.c..a..t.i.o..n................................................................................
7
3.1 登陆及响应.L.o ...g..in...a..n..d...r..e..s.p..o..n..s..e......................................................................................................
7
3.1.1 机柜上行报文.C ...a..b..i.n..e..t..U..p..l.i.n..k...M ...e..s.s..a..g..e......................................................................................
7
3.1.2 服务器下行报文..S..e..r.v..e..r..d..o..w ...n..l.in..k...m
...e..s..s..a..g..e...............................................................................
8
3.1.3 报文示例...M...e..s.s..a..g..e...e..x..a..m ...p..l.e......................................................................................................
8
3.2 心跳及响应.H ...e..a..r.t.b..e..a..t..a..n..d...R...e..s.p..o..n..s..e.............................................................................................
8
3.2.1 机柜上行报文.C..a..b..i.n..e..t..U ...p..l.in..k...M...e..s..s..a..g..e......................................................................................
8
3.2.2 服务器下行报文.S..e..r.v..e..r..d..o..w ...n..l.i.n..k..m...e..s..s..a..g..e................................................................................
9
3.2.3 报文示例.M ...e..s..s.a..g..e...e..x..a..m ...p..l.e........................................................................................................
9
3.3 查询机柜软件版本号.Q..u..e..r..y..c..a..b..i.n..e..t..s..o..f.t.w..a..r..e...v.e ..r..s.i.o..n....................................................................
9
3.3.1 服务器下行报文..S..e..r.v..e..r..d..o..w ...n..l.in..k...m
...e..s..s..a..g..e...............................................................................
9
3
3.3.2 机柜上行报文C ...a..b..i.n..e..t..U..p..l.i.n..k...M...e..s.s..a..g..e.....................................................................................
10
3.3.3 报文示例.M ...e..s..s..a..g..e...e..x..a..m ...p..le......................................................................................................
10
3.4 设置服务器地址及响应..S..e..t..s..e..r.v..e..r..a..d..d..r.e..s..s...a..n..d...r.e..s..p..o..n..s..e.........................................................
10
3.4.1 服务器下行报文.S..e ..r..v.e ..r...d..o..w..n..l.i.n..k...m...e..s..s.a..g..e..............................................................................
10
3.4.2 机柜上行报文.C ...a..b..i.n..e..t..U..p..l.i.n..k...M ...e..s.s..a..g..e....................................................................................
11
3.4.3 报文示例.M ...e..s..s..a..g..e...e..x..a..m ...p..le......................................................................................................
11
3.5 查询机柜库存及响应.I.n..q..u..ir..y..c..a..b..i.n..e..t..i.n..v..e..n..t.o..r.y...a..n..d...r.e..s..p..o..n..s.e ......................................................
11
3.5.1 服务器下行报文..S..e..r.v..e..r..d..o..w ...n..l.in..k...m...e..s..s..a..g..e.............................................................................
11
3.5.2 机柜上行报文...C..a..b..i.n..e..t..U ...p..l.in..k...M...e..s..s..a..g..e..................................................................................
12
3.5.3 报文示例..M ...e..s..s..a..g..e...e..x.a ..m...p..l.e.....................................................................................................
12
3.6 借充电宝..B..o..r.r..o..w...p..o..w...e..r..b..a..n..k.......................................................................................................
12
3.6.1 服务器下行报文.S..e ..r..v.e ..r...d..o..w..n..l.i.n..k...m...e..s..s.a..g..e..............................................................................
13
3.6.2 机柜上行报文.C ...a..b..in..e..t..U...p..l.i.n..k..M...e..s..s..a..g..e....................................................................................
13
M e ss a g e e x a m p le
3.6.3 报文示例.... .. .............. .. ... .. .......................................................................................................
13
3.7 还充电宝..R..e..t.u..r.n
...p..o..w...e..r..b..a..n..k........................................................................................................
14
3.7.1 机柜上行报文C ...a..b..i.n..e..t..U..p..l.i.n..k...M
...e..s.s..a..g..e.....................................................................................
14
Server downlink message
3.7.2 服务器下行报文......................................................................................................................
14
Message example
3.7.3 报文示例 ..................................................................................................................................
15
3.8 远程重启机柜..R ...e..m ...o..t.e...r.e..s..t.a..r.t..c..a..b..i.n..e..t........................................................................................
15
3.8.1 服务器下行报文.S ...e..r.v..e..r..d..o..w ...n..li.n..k...m...e..s..s..a..g..e.............................................................................
15
3.8.2 机柜上行报文..C ...a..b..i.n..e..t..U...p..li.n..k...M ...e..s..s..a..g..e..................................................................................
15
3.8.3 报文示例.M ...e..s..s..a..g..e...e..x..a..m...p..le......................................................................................................
16
3.9 远程升级..R..e..m...o..t.e...u..p..g..r..a..d..e...........................................................................................................
16
4
3.9.1 服务器下行报文..S ...e..r.v..e..r..d..o..w ...n..li.n..k...m...e..s..s..a..g..e............................................................................
16
3.9.2 机柜上行报文..C..a..b..i.n..e..t..U ...p..li.n..k...M...e..s..s..a..g..e...................................................................................
17
3.9.3 报文示例...M ...e..s.s..a..g..e...e..x..a..m ...p..l.e....................................................................................................
17 3.10 查询 query
ICCID.................................................................................................................................17
3.10.1 服务器下行报文..S ...e..r.v..e..r..d..o..w..n ..l.i.n..k...m
...e..s..s.a
..g
..e
.............................................................................
17
3.10.2 机柜上行报文.C ...a..b..in..e..t..U
...p..l.i.n..k..M ...e..s..s..a..g..e....................................................................................
17
3.10.3 报文示例.M ...e..s..s..a..g..e...e..x..a..m ...p..le......................................................................................................
18
3.11 查询服务器地址及响应 ..in..q..u..i.r.y...s..e..r.v..e..r..a..d..d..r.e..s..s...a..n..d...r.e..s..p..o..n..s..e................................................ 18
3.11.1 服务器下行报文S..e..r.v..e..r..d..o..w ...n..l.in..k...m
...e..s..s..a..g..e...............................................................................
18
3.11.2 机柜上行报文.C ...a..b..in..e..t..U
...p..l.i.n..k..M...e..s..s..a..g..e....................................................................................
18
3.11.3 报文示例.M
...e..s..s..a..g..e...e..x..a..m...p..le......................................................................................................
19
3.12 查询机柜库存充电宝数量..I.n..q..u..i.r.y...c..a..b..in..e..t..i.n..v..e..n..t.o..r.y...a..n..d...t.h..e...n..u..m ...b..e..r..o..f..p..o..w
...e..r..b..a..n..k..s..... 19
3.12.1 服务器下行报文S ...e..r.v..e..r..d..o..w..n..l.i.n..k...m...e..s..s.a..g..e...............................................................................
19
3.12.2 机柜上行报文..C ...a..b..in..e..t..U
...p..l.i.n..k..M...e..s..s..a..g..e...................................................................................
19
3.12.3 报文示例M
...e..s..s.a
...g..e...e..x.a..m ...p..l.e.......................................................................................................
20
3.13 强制弹出充电宝f.o..r..c.e..d...t.o...p..o..p...o..f..p..o..w ...e..r..b..a..n..k..s.............................................................................. 20
3.13.1 服务器下行报文S ...e..r.v..e..r..d..o..w...n..li.n..k...m
...e..s..s..a..g..e..............................................................................
20
3.13.2 机柜上行报文C ...a..b..in..e..t..U...p..l.i.n..k..M...e..s..s..a..g..e.....................................................................................
20
3.13.3 报文示例.M ...e..s..s..a..g..e...e..x..a..m ...p..le......................................................................................................
21
4 机柜唯一码 SN
C
...a..b..i.n..e..t..u..n..i.q..u..e...c.o..d..e...S ...N...................................................................................................
22
4.1 定义规则.D..e..f.i.n..i.t.i.o..n...r.u..l.e.................................................................................................................
22 4.2 设备类型 device type
...................................................................................................................................... 22
4.3 示例 ....a..m
e x ...p..l.e................................................................................................................................................ 22
5 终端唯一码
t e r m i n a l u n i q u e c o d e I D
ID .... .... ... .. .. .. .. ... .. ... ..............................................................................................................
23
5.1 定义规则 D ...e..f.i.n..it.i.o..n...r.u
..l.e..................................................................................................................
23
5
5.2 示例e..x..a..m
...p..l.e..................................................................................................................................
23

6
6
 深圳市皓乐科技有限公司 技术文档

1 基本名词定义
Basic noun definition

1.1 基本名字定义 Basic name definition

名称 Item 说明 description
机柜 ID Cabinet ID 长度机柜的唯一身份标识，和机身上的二维码有一一对应
The unique identity of the length cabinet has a one-to-one correspondence
with the QR code on the cabinet
充电宝 ID 终端设备的唯一身份标识，可租赁的终端设备包括充电宝、MiFi 等
Power banks ID 各种终端产品。
The unique identification of the terminal equipment, and the leased terminal
equipment includes various end products such as power banks, MiFi, etc.

TCP 机柜和服务器之间的通信基于 TCP 协议栈

the communication between the cabinet and the server is based on the TCP protocol stack
FTP 机柜的升级文件使用 FTP 进行传输
Cabinet upgrade files are transferred by FTP

1.2 功能码表
Function code table
名称 Item 功能码 function
code 备 注 Action
机柜登陆及响应 Cabinet login
and response 0x60 机柜-->服务器 Cabinet--->Server
心跳及响应 Heartbeat and response 0x61 机柜-->服务器 Cabinet--->Server
查询机柜软件版本号及响应 0x62
Query cabinet software version and respo nse
服务器-->机柜 Server--->Cabinet

设置机柜服务器地址及响应 0x63 服务器-->机柜 Server--->Cabinet

Set up cabinet server address and response
查询机柜库存及响应 0x64 服务器-->机柜 Server--->Cabinet
Inquiry cabinet inventory and response
借充电宝及响应 0x65 服务器-->机柜 Server--->Cabinet
Borrow power banks and respond
还充电宝及响应 0x66 机柜-->服务器 Cabinet--->Server
Returning power banks and response
远程重启机柜及响应 0x67 服务器-->机柜 Server--->Cabinet
Remote restart cabinet and response
远程升级及响应 0x68 服务器-->机柜 Server--->Cabinet
Remote upgrade and response
查 询 ICCID Inquiry ICCID 0x69 服务器-->机柜 Server--->Cabinet
查询服务器地址及响应 0x6A 服务器-->机柜 Server--->Cabinet
Query server address and response
查询机柜库存充电宝数量 0x6B 服务器-->机柜 Server--->Cabinet
Query the quantity of power banks
in the inventory of cabinets
强制弹出充电宝
Forced to pop of the power ban ks 0x80 服务器-->机柜 Server--->Cabinet

2 通讯协议模板Communication protocol template

2.1 通讯协议模板 C ommunication protocol template
字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)

PacketLen
数据包的长度
Uint16 2
Length of data packet

7
 深圳市皓乐科技有限公司 技术文档

Comman 命令字
d Byte 1
CW (Command word)
VSN 协议版本号 1
Protocol version number
Byte
CheckSu 有效数据的字节异或 Byte 1
m The byte of valid data
Token 会话令牌 Session token Uint32 4
Payload 有效数据，不定长 Byte
Valid data, variable length
注意：所有的字符串数据内容都需要以 0x00 结束，字符串的长度包含 0x00。
Remark: All string data conten t needs to end with 0x00 and the length of the string contains 0x00

3 通讯协议规范 Communication protocol specification

3.1 登陆及响应 Login and response
机柜每次开机或重启后向服务器发送登陆消息并携带机柜唯一身份标识，服务器根据
该标识判断是否为合法机柜并将结果告知机柜。
After each boot or restart, the cabinet sends a login message to the server and carries the unique identity of the cabinet,
according to the identity, the server determines whether the cabinet is legal or not and informs the cabinet of the results.

3.1.1 机柜上行报文 Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节

Field data type Length (bytes)
数据包的长度
PacketLen Length of data packet
Uint16 2

命令字，0x60
Command Byte 1
CW (Command word), 0x60
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4
Rand 随机数 random number Uint32 4

Magic 魔术字 magic word Uint16 2

BoxIDLen BoxID 的长度 Uint16 2

The length of BoxID
BoxID 柜机ID和柜身的二维码对应 String BoxIDLen
The id of the cabinet correspond
to the QR code on the cabinet.
ReqDataLen 加密数据体的长度 Uint16 2
Length of encrypted data
ReqData 加密的数据体 Encrypted data String ReqDataLen

8
 深圳市皓乐科技有限公司 技术文档

注意：Token/Rand/ReqDataLen/ReqData 字段需要携带，但是并未对数据进行处理，
待后续添加。Token 字段标识当前时间，如果时间与当前时间相差超过 3 秒，则服务器会返回
登录失败，机柜时间错误，需要机柜去更新当前时间为北京时间。Rand 字段机柜带 4 个字节
的随机数。ReqData 字段为如下算法计算的值：AES(Rand+ruilianbox1818168),加密密码为：
zhuohua19199+Token
Remark: Token/Rand/Re。 qDataLen/ReqData the fields needs to be carried, but the data is not processed
and is to be added later. The token field identifies the current time. If the difference between the time and
the current time is more than 3 seconds, the server will return to login failure, the cabinet time is wrong,
and the cabinet needs to update the current time to Beijing time. Random number of 4 bytes in rand field
cabinet. The regdata field is the value calculated by the following algorithm:
AES(Rand+ruilianbox1818168), The encryption password is: zhuohua19199+Token

3.1.2 服务器下行报文 Server downlink message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16
Length of data packet 2
Command 命令字，0x60 Byte
CW (Command word), 0x60 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data

Token 会话令牌 Session token Uint32 4

Result 登陆结果 Login result 0： Byte 1
失 败 Login failed 1：成
功Login succeeded
2：失败，时间错误
2: Login failed, time error

3.1.3 报文示例Message example

机柜 00 20 60 01 80 11 22 33 44 55 66 77 88 02 33 00 11 52 4c
Cabinet 31 41 30 33 31 37 31 32 30 30 30 30 31 35 00

服务器 00 08 60 01 00 12 34 43 21 01
Server

3.2 心跳及响应 Heartbeat and response

机柜登陆成功后每隔 30 秒向服务器发送一次心跳消息，服务器收到心跳消息后原样回

复，机柜以此探测服务器是否工作正常。如果机柜连续几个心跳包没有收到回应则认为服务
器异常，此时机柜关闭之前的连接并启用新的连接进行通信。服务器也可根据心跳来判断机
柜是否通信正常。
After the successful login of the cabinet, the heartbeat message is sent to the server every 30 seconds, the server receives
the heartbeat message and responds as it is. According to this, the cabinet detects whether the server is working properly.
If the cabinet does not receive a response from several heartbeat packets in a row, the server is considered abnormal,
at which point the cabinet closes the previous connection and enables a new connection to communicate
The server can also determine whether the cabinet is in communication according to the heartbeat
 深圳市皓乐科技有限公司 技术文档

3.2.1 机柜上行报文 Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节
Field data type Length (bytes)
数据包的长度
PacketLen Uint16
Length of data packet 2
Command 命令字，0x61 Byte
CW (Command word), 0x61 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.2.2 服务器下行报文 Server downlink message

字段 定义 definition 数据类型 长度（字节
Field data type Length (bytes)
数据包的长度
PacketLen Length of data packet
Uint16
2
Command 命令字，0x61 Byte
CW (Command word), 0x61 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.2.3 报文示例 Message example

机柜 Cabinet 00 07 61 01 00 11 22 33 44

服务器Server 00 07 61 01 00 11 22 33 44

3.3 查询机柜软件版本号Query cabinet software version number

服务器可根据需要来查询机柜软件版本号信息，以此作为是否给机柜发送远程升级消
息的依据。
The server can query the cabinet software version number as demand, as a basis for sending remote upgrade messages
to the cabinet.

3.3.1 服务器下行报 Server downlink message

文 字段 定义 数据类型 长度（字节）
definition
Field data type Length (bytes)
PacketLen 数据包的长度
Uint16 Short
Length of data packet

10
 深圳市皓乐科技有限公司 技术文档

Command 命令字，0x62 Byte

CW (Command word), 0x62 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌Session token Uint32 4

3.3.2 机柜上行报文Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x62 Byte 1
CW (Command word), 0x62
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异 Byte 1
The byte of valid data
Token 会话令牌Session token Uint32 4
SoftVerLen 机柜软件版本号字 Uint16 2
Cabinet software version number wo rd
SoftVer 机柜软件版本号 String SoftVerL
Cabinet software version number

3.3.3 报文示例 Message example

机柜 Cabinet 00 07 62 01 33 00 00 12 34

服务器 Server 00 14 62 01 6a 11 22 33 44 00 0b 41 2e 30 39 2e 30 31 2e 30 36 00

3.4 设置服务器地址及响应 Set server address and response

服务器地址需要发生变更时可通过该命令来配置机柜登陆的服务器地址，配置完成后
发送远程重启命令给机柜使其生效。
This command can be used to configure the server address that the cabinet logs in to when the server address needs
to be changed, when the config uration is complete, send a remote restart command to the cabinet for it to take effect.

3.4.1 服务器下行报文 Server downlink message

字段 Field
数据类型 长度（字节）
定义definition data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x63 Byte 1
CW (Command word), 0x63
VSN 协议版本号 Byte 1
Protocol version number
11
 深圳市皓乐科技有限公司 技术文档

CheckSum 有效数据的字节异或 Byte 1

The byte of valid data
Token 会话令牌 Session token Uint32 4

AddressLen 服务器地址长度 Uint16 2

Server address length
Address 服务器地址 String AddressLen
Server address
PortLen 服务器端口长度 Uint16 2
Server port length
Port 服务器端口 String PortLen
Server port
Heartbeat 心跳间隔(1~255有效) Byte 1
Heartbeat interval (1--255 effective)

3.4.2 机柜上行报文 Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x63 Byte 1
CW (Command word), 0x63
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.4.3 报文示例 Message example

00 22 63 01 33 00 00 12 34 00 11 78 2e 70 6f 77 65 72 70 6f 77 65 72
服务器 Server 2e 6e 65 74 00 00 05 38 39 39 32 00 1E

机柜 Cabinet 00 07 63 01 00 11 22 33 44

3.5 查询机柜库存及响应 Inquiry cabinet inventory and response

服务器查询机柜充电宝库存信息，在借用充电宝时根据充电宝电量的多少选择弹出指定充电宝。
The server queries the power banks inventory information from the cabinet, when borrowing the
power banks, the specified power bank will pop up according to the amount of electricity of them.

3.5.1 服务器下行报文 Server downlink message

字段 Field 数据类型 长度（字节）
定义 data type Length (bytes)
definiton

PacketLen 数据包的长度 Uint16 2

Length of data packet
Command 命令字，0x64 Byte 1
CW (Command word), 0x64

12
 深圳市皓乐科技有限公司 技术文档

VSN 协议版本号 Byte 1

Protocol version number

13
 深圳市皓乐科技有限公司 技术文档

CheckSum 有效数据的字节异或 Byte 1

The byte of valid data
Token 会话令牌 Session token Uint32 4

3.5.2 机柜上行报文 Cabinet Uplink Message

字 段 Field 定义 definition 数据类型 长度（字节）
data type
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x64 Byte 1
CW (Command word), 0x64
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

RemainNum 剩余充电宝个数 Byte 1

Number of remaining power banks
Slot 槽位编号 Slot serial number Byte 1

TerminalID 充电宝 ID Power banks ID Byte 8

Level 充电宝电量 Byte 1

Power banks electricity quantity
Slot 槽位编号 Slot serial number Byte 1

TerminalID 充电宝 ID Power banks ID Byte 8

Power banks
Level 充电宝电量 Byte 1
electricity quantity
0 20%电量 0 20% electricity
1 40%电量 1 20% electricity
2 60%电量 2 20% electricity
3 80%电量 3 20% electricity
4 100%电 量 4 20% electricity
（其他类似）
Other similar

3.5.3 报文示例 Message example

服务器 Server 00 07 64 01 33 00 00 12 34
00 1c 64 01 06 11 22 33 44 02 02 52 4c 31 41 7c 00 00 41 04 03 52 4c
机柜 Cabinet
31 41 7c 00 00 44 04

3.6 借充电宝 Borrow power banks

用户扫描机身上的二维码后，服务器弹出机柜内的充电宝( 根据充电宝电量多少选择弹出哪个)
After the user scans the QR code on the cabinet, the server will pop of power banks from the cabinet
(which will pop of according to the electricity quantity of power banks).
14
 深圳市皓乐科技有限公司 技术文档

3.6.1 服务器下行报文 Server downlink message

字 段 Field 定义 definition 数据类型 长度（字节）

data type Length (bytes)
PacketLen 数据包的长度
Length of data packet Uint16 2

Command 命令字，0x65 Byte

CW (Command word), 0x65 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token Uint32 4
会话令牌 Session token
Slot Byte 1
槽位编号 Slot serial number

3.6.2 机柜上行报文 Cabinet Uplink Message

字段 Field 定义 definition 数据类型 长度（字节）
data type Length (bytes)
PacketLen 数据包的长度
Length of data packet Uint16 2
Command 命令字，0x65 Byte
CW (Command word), 0x65 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

Slot 槽位编号 Slot serial number Byte 1

Result 借用结果：B orrowing result Byte 1

0：失败 0: fail
1：成功 1: success

TerminalID 充电宝 ID Power bank ID Byte 8

3.6.3 报文示例 Message example

服务器 Server 00 08 65 01 33 00 00 12 34 03

机柜 Cabinet 00 11 65 01 74 11 22 33 44 03 01 52 4c 31 41 7c 00 00 64

14
 深圳市皓乐科技有限公司 技术文档

3.7 还充电宝 Returning power banks

用户将充电宝归还到机柜内后，机柜检测充电宝后将归还信息发送到服务器，服务器
返回归还结果，并结束用户计费。
After the user returns the power bank to the cabinet, the cabinet detects the power bank and sends the return information
to the server, the server returns the return result, and ends the user charging.

机柜每次登陆成功后都会将每个槽位的充电宝逐个上报归还，避免客户在关机/无信号
等场景下归还充电宝后不结束订单的情况。
After each successful login of the cabinet, power bank of each slot will be reported and returned one by one
so as to avoid the situation that the customer will not end the deduction after returning power banks
in the scene of mobile phone shutdown or no signal.

3.7.1 机柜上行报文 Cabinet Uplink Message

数据类型 长度（字节）
字 段 Field 定义 definition data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x66 Byte 1
CW (Command word), 0x66
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
会话令牌 token
Token Session Uint32 4
Slot 槽位编号Slot serial number Byte 1

TerminalID 充电宝 ID Power bank ID Byte 8

3.7.2 服务器下行报文 Server downlink message

字段 定 义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16
Length of data packet 2
Command 命令字，0x66 Byte 1
CW (Command word), 0x66
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌Session token Uint32 4
Slot 槽位编号Slot serial number Byte 1

15
 深圳市皓乐科技有限公司 技术文档

Result 归还结果 Return result Byte 1

0：归还失败(一般是服务
器状态有错误，比如服务
器访问不了数据库
0: The return failure)(t ypically the server state has an error,
such as the server can't acce ss the database)
1：归还
成功 1: Successful return
2：
充电宝状态异常 2: Power bank's abnormal state
3：重复归还 3: Repeat retu rn
4：非法充电宝 ID 4: Illegal power bank ID
5：归还的槽位不为空
5: The slot which had returned power bank cannot be empty

3.7.3 报文示例 Message example

机柜 Cabin et 00 10 66 01 41 11 22 33 44 01 52 4c 31 41 7c 00 00 52

服务器 Server 00 09 66 01 41 11 22 33 44 01 01

3.8 远程重启机柜 Remote restart cabinet

服务器可通过该命令远程重启机柜。机柜的返回仅表示接收到重启指令。
The server can remotely restart the cabinet through this command. The return of the cabinet only
indicates that a restart instruction has been received

3.8.1 服务器下行报 Server downlink message

文 字段 定义 数据类型 长度（字节）
Field
definition data type Length (bytes)
数据包的长度
PacketLen Uint16 2
Length of data packet

Command 命令字，0x67 Byte 1

CW (Command word), 0x67
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.8.2 机柜上行报文 Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet

Command 命令字，0x67 Byte 1

CW (Command word), 0x67
VSN 协议版本号 Byte 1
Protocol version number

16
 深圳市皓乐科技有限公司 技术文档

CheckSum 有效数据的字节异或 Byte 1

The byte of valid data
Token 会话令牌 Session token Uint32 4

3.8.3 报文示 Message example

例
服务器 Server 00 07 67 01 33 00 00 12 34
00 07 67 01 33 00 00 12 34
机柜 Cabinet

3.9 远程升级 Remote upgrade

当机柜需要更新软件时，服务器可远程发送指令告知机柜升级。升级用的文件需要放
到 FTP 服务器上。
When the cabinet needs t o update the software, the server can remotely send instructions to inform the cabinet of the upgrade.
Upgrade files need to be placed on the FTP server

3.9.1 服务器下行报文 Server downlink message

字段 定义 数据类型 长度（字节）
Field definition data type Length (bytes)
数据包的长度
PacketLen Uint16
Length of data packet 2
Command 命令字，0x68 Byte
CW (Command word), 0x68 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4
FTPAddressLe FTP 服务器地址长度 Uint16 2
FTP server address length
n FTP 服务器地址 String FTPAddressLen
FTPAddress FTP server address
FTPPortLen FTP 服务器端口长度 Uint16 2
FTP server port length
FTPPort FTP 服务器端口 String FTPPortLen
FTP server port
FileNameLen 文件名长度 Uint16 2
File name length
FileName 文件名 File name String FileNameLen
UsernameLen 用户名长度 Uint16 2
User name length
Username 用户名 String UsernameLen
User name
PasswordLen 密码长度 Uint16 2
Password length
Password 密 码 Password String PasswordLen

17
 深圳市皓乐科技有限公司 技术文档

3.9.2 机柜上行报文 Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16
Length of data packet 2

Command 命令字，0x68 Byte 1

CW (Command word), 0x68
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

18
 深圳市皓乐科技有限公司 技术文档

3.9.3 报文示例 Message example

服务器 00 3c 68 01 33 00 00 12 34 00 0e 31 32 31 2e 34 31 2e 36 30 2e 32 33
Server 32 00 00 03 32 31 00 00 07 33 33 2e 62 69 6e 00 00 06 73 68 61 72 65
00 00 0d 73 68 61 72 65 33 34 35 40 31 32 33 00
00 07 68 01 33 00 00 12 34
机柜 Cabinet

3.10 查询ICCID Query ICCID

该命令可查询机柜中 SIM 卡对应的 ICCID，便于对 SIM 卡的维护管理。

The command can query the ICCID corresponding to SIM card in the cabinet for maintenance and management of SIM card.

3.10.1 服务器下行报文 Server downlink message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
数据包的长度
PacketLen Length of data packet
Uint16
2
Command 命令字，0x69 Byte
CW (Command word), 0x69 1

VSN 协议版本号 Byte 1

Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.10.2 机柜上行报文 Cabinet Uplink Message

数据包的长度
PacketLen Length of data packet
Uint16
2
Command 命令字，0x69 Byte
CW (Command word), 0x69 1

VSN 协议版本号 Byte 1

Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4
ICCIDLen ICCID的长度 Uint16 2
Length of ICCID
ICCID SIM 卡的 ICCID String ICCIDLen
The ICCID of SIM card

3.10.3 报文示例 Message example

00 07 69 01 33 00 00 12 34
服务器 Server
00 1e 69 01 1e 11 22 33 44 00 15 38 39 38 36 30 34 30 31 31 30 31 37
机柜 Cabinet 37 30 39 38 32 38 33 39 00

字段 定义 definition 数据类型 长度（字节）

Field data type Length (bytes)

19
 深圳市皓乐科技有限公司 技术文档

3.11 查询服务器地址及响应 Query server address and response

可通过该命令来查询机柜内置的服务器地址信息。
This command can be used to query the server address information which had built into the cabinet

3.11.1 服务器下行报文 Server downlink message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)

PacketLen 数据包的长度 Uint16 2

Length of data packet
Command 命令字，0x6A Byte 1
CW (Command word), 0x6A

VSN 协议版本号 Byte 1

Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.11.2 机柜上行报文 Cabinet Uplink Message

字段 Field 数据类型 长度（字节）
定义 definition data type Length (bytes)

PacketLen 数据包的长度 Uint16 2

Length of data packet
Command 命令字，0x6A Byte 1
CW (Command word), 0x6A
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token Uint32 4
会话令牌 Session token
AddressLen 服务器地址长度 Uint16 2
Server address length
Address 服务器地址 String AddressLen
Server address
PortLen 服务器端口长度 Uint16 2
Server port length.
Port 服务器端口 String PortLen
Server port
Heartbeat 心跳间隔(1~255 有效) Byte 1
Heartbeat interval (1--255 effect ive)

3.11.3 报文示例 Message example

00 07 6A 01 00 11 22 33 44
服务器 Server
00 22 6A 01 33 00 00 12 34 00 11 78 2e 70 6f 77 65 72 70 6f 77 65 72
机柜 Cabinet 2e 6e 65 74 00 00 05 38 39 39 32 00 1E

20
 深圳市皓乐科技有限公司 技术文档

3.12 查询机柜库存充电宝数量 Query the quantity of power banks in the inventory of cabinets

可通过该命令来查询机柜当前库存充电宝数量。
The command can query the current inventory of power banks from the cabinets

3.12.1 服务器下行报文 Server downlink message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x6B Byte 1
CW (Command word), 0x6B
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

3.12.2 机柜上行报文 Cabinet Uplink Message

字段 Field
数据类型 长度（字节）
定义 definiton data type Length (bytes)
PacketLen 数据包的长度 Uint16 2
Length of data packet
Command 命令字，0x6B Byte 1
CW (Command word), 0x6B
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4

TerminalNum 终端库存数量（0~255） Byte 1

Terminal inventory quantity
(0-255)

3.12.3 报文示例 Message example

00 07 6B 01 00 11 22 33 44
服务器 Server
00 08 6B 01 33 00 00 12 34 09
机柜 Cabinet

3.13 强制弹出充电宝 Forced to pop of the power banks

该命令可强制弹出机柜中的充电宝，便于对机柜的维护管理。
This command can force power banks to pop of the cabinet, which is convenient for the maintenance
and management of the cabinet.
21
 深圳市皓乐科技有限公司 技术文档

3.13.1 服务器下行报文 Server downlink message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
PacketLen 数据包的长度 Uint16
Length of data packet 2
Command 命令字，0x80 Byte
CW (Command word), 0x80 1
VSN 协议版本号 Byte 1
Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4
Slot 槽位编号 slot number Byte 1

3.13.2 机柜上行报文 Cabinet Uplink Message

字段 定义 definition 数据类型 长度（字节）
Field data type Length (bytes)
数据包的长度
PacketLen Length of data packet
Uint16
2
Command 命令字，0x80 Byte
CW (Command word), 0x80 1

VSN 协议版本号 Byte 1

Protocol version number
CheckSum 有效数据的字节异或 Byte 1
The byte of valid data
Token 会话令牌 Session token Uint32 4
Slot 槽位编号 slot number Byte 1
Result 借用结果：Borrowing result Byte 1
0：失败 0: fail

1：成功 1: success
充电宝 ID power bank ID
TerminalID Byte 8

3.13.3 报文示例 Message example

00 08 80 01 33 00 00 12 34 24
服务器 Server
00 11 80 01 35 11 22 33 44 24 01 59 44 31 41 7c 00 01 40
机 柜 Cabinet

22
 深圳市皓乐科技有限公司 技术文档

4 机柜唯一码 SN Cabinet unique code SN

机柜设备出厂会配置好唯一的设备识别码，服务器根据此码进行设备管理。
The cabinet will be equipped with a unique device identification number, according to which the server
will manage the equipment.

4.1 定义规则 Definition rule

客户代码 设备型号 设备子型号 批次年月 批次序列号
Customer code Equipment model Equipment submodel Batch year & month Batch serial number
3 个字符 1 个字母 2 个数字 4 个数字 6 个数字 0~999999
3 characters 1 letter 2 numbers 4 numbers 6 numbers 0~999999

4.2 设备类型 Equipment type

设备类型 设备定义 备注
Equipment type Definition of equipment Remark
A~D 智能充电机柜系列
Intelligent charging cabinet series
E/F/G 智能擦鞋机系列
Series of intelligent shoeshine machines
其他 暂未使用
Other Not used yet

4.3 示 Exampl
例 e
客户代码 设备型号 设备子型号 批次年月 批次序列号
Customer Equipment model Batch year & month Batch serial number
code Equipment submodel
3 个字符 1 个字母 2 个数字 4 个数字 6 个数字 0~999999
3 c haracters 1 letter 2 numbers 4 numbers 6 numbers 0~999999
RL1 A 03 1711 000123

RL1A031711000123 充电柜类产品
RL1A031711000123 Charging cabinet products

5 终端唯一码 IDTerminal unique code ID

终端设备出厂会配置好唯一的设备识别码，服务器根据此码进行终端设备管理，终端
唯一存储和传输均是 8 个字节（bytes）。
The terminal equipment will be equipped with a unique device identification code, and the server will manage the terminal
device according to this code. The terminal unique storage and transmission are both 8 bytes of (bytes).

5.1 定义规则 Definition rule

客户代码 产品子型号 批次年 批次月 批次序列号
Customer Product submodel Batch year Batch month Batch serial number
code

23
 深圳市皓乐科技有限公司 技术文档

3 个大写字母 1 个大写字母 1个数字 1 number 1

1
个十六进制数
6 位流水号
henxuam
debceirmal
3 up percase letters 7-2017 /8-2018 /9- 1~12 月对应 000000~999999 BCD
1 uppercase letters 2019 /0-2020 January-Decembe 码
1~9ABC r correspondence

5.2 示例 Example
客户代码 产品子型号 批次年 批次月 批次序列号
Customer Product Batch year Batch month Batch serial number
code Submodel
3 个大写字母 1 个大写字母 1 个数字 1 个十六进制数 6 位流水号
3 up percase letters 1 uppercase le tters 1 hexadecimal 6 bit serial number
1 number number
RL1 A 7（2017 年） B（11 月） 000123
7 (year of 2017) 8 ( Nov.)
RL1A7B000123 终端 ID
16 进制存储/传输内容：52 4C 31 41 7B 00 01 23

RL1A78000123Terminal ID
Hexadecimal storage/Transmission content: 52 4C 31 41 7B 00 01 23

24