李外 / Protocol

Commit e1c766698b46185f20aec827811aca0f612ee520

Authored by 何征华
1 parent 11420fa5

a,完善了usbjson 基础通信协议；b,增加了固件升级相关协议

Inline Side-by-side
Showing 1 changed file with 240 additions and 177 deletions
通讯协议-教育新版-基站部分usb json.md
  View file @e1c7666
1 1 [TOC]
2   -# 一、概述
  2 +# 概述
3 3 ### 通信流程
4 4 相对usb 64byte传输，json格式命令数据长度大多都是比较长的。使用常规的一问一答的方式效率较低；
5 5 所以设计了如下通信方式：
... ... @@ -10,226 +10,289 @@
10 10 - 错误->接收方从step 1开始重发;
11 11  
12 12 ### 说明：
13   -为了避免通信失败时重发的代价太大，在step 1中将数据包拆分成N个以1024bytes为单位的小数据包；
  13 +- 为了避免通信失败时重发的代价太大，在step 1中将数据包拆分成N个以1024bytes为单位的小数据包；
14 14 当如上传输出错时，只需重传当前的1024bytes即可;
  15 +- 为了解决通信双方随时都可以主动发起，通信双方在所有数据头上加上明显辨识，用于接收方识别收到的数据是对方主动发送还是ack;
15 16  
16   -### 通信机制
17   -在"通信流程" step 2中传输的是纯数据，接收方会把所有当前收到的数据都当作是纯数据，这样在收发双方通信时就会有如下限制：
18   - - 发送方必须在完成当前数据传输流程后才可以开始下一个传输流程；
19   - - 接收方必须在完成当前数据传输流程后才可以主动发起传输。
  17 +如下是基站主动发送的数据头
  18 +| **基站发送数据头** | **描述** | **sdk回复数据头** |
  19 +| --- | --- | --- |
  20 +| 0xB1 | 基站主动发送数据信息 | 0xB1 |
  21 +| 0xB2 | 基站主动发送纯数据 | 无需回复 |
  22 +| 0xB3 | 基站主动发送询问 | 0xB3 |
  23 +
  24 +如下是SDK主动发送的数据头
  25 +| **SDK发送数据头** | **描述** | **基站回复数据头** |
  26 +| --- | --- | --- |
  27 +| 0xD1 | SDK主动发送数据信息 | 0xD1 |
  28 +| 0xD2 | SDK主动发送纯数据 | 无需回复 |
  29 +| 0xD3 | SDK主动发送询问 | 0xD3 |
20 30  
21 31  
22   -# 二，
23 32  
24   -## 1.1 sdk下载多包给基站
  33 +# 一， 协议描述
25 34  
26 35  
27   -### 1.1.1 sdk发送数据信息
28   -电脑向基站发送：
  36 +## 1.1 发送数据信息
  37 +发送方发送数据：(所有非1字节数据都是高字节在前)
29 38 | **字节** | **标识符** | **描述** |
30 39 | --- | --- | --- |
31   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
32   -| 2-3 | Len | 有效数据长度 |
33   -| 4 | Direct | 0x01 : sdk主动发起的通信 |
34   -| 5-6 | com seq | 通信序号 |
35   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
36   -| 8 | type | 1 要下载的数据信息 |
37   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
38   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
39   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
40   -| 18 | transfer total | 总传输次数 |
41   -| 19 | transfer cur | 当前传输次数 |
42   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
43   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
  40 +| 0 | Header | 数据包头：基站主动发送0xB1;sdk主动发送0xD1 |
  41 +| 1-2 | defualt | |
  42 +| 3-4 | com seq | 通信序号 |
  43 +| 5 | BASEID | 指定的基站编号，为0时候不指定 |
  44 +| 6 | DATA-type | 1：json数据 <br>2：普通数据; |
  45 +| 7-10 | DATA_total| 数据总字节数 |
  46 +| 11-14 | total DATA crc32 | 总数据(DATA_total长度)crc32|
  47 +| 15 | transfer total | 总传输次数 |
  48 +| 16 | transfer cur | 当前传输次数 |
  49 +| 17-18 | This PACK Len |本次要传输的数据包长度 |
  50 +| 19-22 | This Pack crc32 | 本次要传输的数据(This PACK Len长度)crc32 |
44 51 |default | | |
45 52 |60-63 | crc32 | 此数据包的crc32；从byte0-59共60个字节 |
46 53  
47   -举例：sdk要发送(1024X2 +512 bytes)数据给基站
  54 +举例：sdk要发送(1071 * 2 +512 bytes)数据给基站
48 55 第一个发送单元：
49 56 step1:
50   - 5-6：100
51   - 10-13 bytes： (1024*2 +512 bytes)
52   - 14-17 ：数据总长度的crc
53   - 18 : 3
54   - 19 : 0
55   - 20-21 : 1024
56   - 22-25 ：1024数据的crc
  57 + 3-4：100
  58 + 7-10 bytes： (1071 * 2 +512 bytes)
  59 + 11-14 ：数据总长度的crc
  60 + 15 : 3
  61 + 16 : 0
  62 + 17-18 : 1071
  63 + 19-22 ：1071数据的crc
57 64 60-63 : crc
58 65 step2: 基站ack
59   - step3: sdk发送1024长度数据；64byte*16包；
  66 + step3: sdk发送1071长度数据；63byte * 17包；
60 67 step4: sdk发送询问信息
61 68 step5: 基站ack
62 69  
63 70 第二个发送单元：
64 71 step1:
65   - 5-6：101
66   - 10-13 bytes： (1024*2 +512 bytes)
67   - 14-17 ：数据总长度的crc
68   - 18 : 3
69   - 19 : 1
70   - 20-21 : 1024
71   - 22-25 ：1024数据的crc
  72 + 3-4：100
  73 + 7-10 bytes： (1071 * 2 +512 bytes)
  74 + 11-14 ：数据总长度的crc
  75 + 15 : 3
  76 + 16 : 1
  77 + 17-18 : 1071
  78 + 19-22 ：1071数据的crc
72 79 60-63 : crc
73 80 step2: 基站ack
74   - step3: sdk发送1024长度数据；64byte*16包；
  81 + step3: sdk发送1071长度数据；63byte * 17包；
75 82 step4: sdk发送询问信息
76 83 step5: 基站ack
77 84  
78 85 第三个发送单元：
79 86 step1:
80   - 5-6：102
81   - 10-13 bytes： (1024*2 +512 bytes)
82   - 14-17 ：数据总长度的crc
83   - 18 : 3
84   - 19 : 2
85   - 20-21 : 512
86   - 22-25 ：512数据的crc
87   - 60-63 : crc
  87 + 3-4：100
  88 + 7-10 bytes： (1071 * 2 +512 bytes)
  89 + 11-14 ：数据总长度的crc
  90 + 15 : 3
  91 + 16 : 2
  92 + 17-18 : 512
  93 + 19-22 ：512数据的crc
  94 + 60-63 : crc
88 95 step2: 基站ack
89   - step3: sdk发送512长度数据；64byte*8包；
  96 + step3: sdk发送512长度数据；63byte * 9包；
90 97 step4: sdk发送询问信息
91 98 step5: 基站ack
92 99  
93   -基站应答：
  100 +接收方应答：
94 101 | **字节** | **标识符** | **描述** |
95 102 | --- | --- | --- |
96   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
97   -| 2-3 | Len | 有效数据长度 |
98   -| 4 | Direct | 0x01 : sdk主动发起的通信 |
99   -| 5-6 | com seq | 通信序号 |
100   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
101   -| 8 | type | 1 要下载的数据信息 |
102   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
103   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
104   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
105   -| 18 | transfer total | 总传输次数 |
106   -| 19 | transfer cur | 当前传输次数 |
107   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
108   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
109   -|default | | |
110   -|60-63 | crc32 | 此数据包的crc32 |
  103 +| 0 | Header | 数据包头：sdk应答0xB1;基站应答0xD1 |
  104 +| 1-2 | defualt | |
  105 +| 3-4 | com seq | 通信序号 |
  106 +| 5 | BASEID | 指定的基站编号，为0时候不指定 |
  107 +| 6 | DATA-type | 1：json数据 <br>2：普通数据; |
  108 +| 7-10 | DATA_total| 数据总字节数 |
  109 +| 11-14 | total DATA crc32 | 总数据crc32 |
  110 +| 15 | transfer total | 总传输次数 |
  111 +| 16 | transfer cur | 当前传输次数 |
  112 +| 17-18 | This PACK Len |本次要传输的数据包长度 |
  113 +| 19-22 | This Pack crc32 | 本次要传输的数据crc32 |
111 114  
112   -### 1.1.2 sdk连续发送N包纯数据包，基站无需回复
113   -
114   -### 1.1.3 sdk发送询问
  115 +## 1.2 发送方连续发送N包数据包，接收方无需回复
  116 +每个数据包都带一个字节的数据头：
  117 +- 基站主动发送0xB2;
  118 +- sdk主动发送0xD2
115 119  
  120 +## 1.3 发送方发送询问
116 121 | **字节** | **标识符** | **描述** |
117 122 | --- | --- | --- |
118   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
119   -| 2-3 | Len | 有效数据长度 |
120   -| 4 | Direct | 0x01 : sdk主动发起的通信 |
121   -| 5-6 | com seq | 通信序号 |
122   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
123   -| 8 | type | 2 询问基站 |
124   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
125   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
126   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
127   -| 18 | transfer total | 总传输次数 |
128   -| 19 | transfer cur | 当前传输次数 |
129   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
130   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
131   -|default | | |
132   -|60-63 | crc32 | 此数据包的crc32 |
  123 +| 0 | Header | 数据包头：基站主动发送0xB3;sdk主动发送0xD3 |
  124 +| 1-2 | defualt | |
  125 +| 3-4 | com seq | 通信序号 |
  126 +| 5 | BASEID | 指定的基站编号，为0时候不指定 |
  127 +| 6 | DATA-type | 1：json数据 <br>2：普通数据; |
  128 +| 7-10 | DATA_total| 数据总字节数 |
  129 +| 11-14 | total DATA crc32 | 总数据crc32 |
  130 +| 15 | transfer total | 总传输次数 |
  131 +| 16 | transfer cur | 当前传输次数 |
  132 +| 17-18 | This PACK Len |本次要传输的数据包长度 |
  133 +| 19-22 | This Pack crc32 | 本次要传输的数据crc32 |
133 134  
134   -基站应答：
  135 +接收方应答：
135 136 | **字节** | **标识符** | **描述** |
136 137 | --- | --- | --- |
137   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
138   -| 2-3 | Len | 有效数据长度 |
139   -| 4 | Direct | 0x01 : sdk主动发起的通信 |
140   -| 5-6 | com seq | 通信序号 |
141   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
142   -| 8 | type | 2 询问基站 |
143   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
144   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
145   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
146   -| 18 | transfer total | 总传输次数 |
147   -| 19 | transfer cur | 当前传输次数 |
148   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
149   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
150   -| 26 | result | 1：成功 <br>2：失败; |
151   -|60-63 | crc32 | 此数据包的crc32 |
152   -
153   -
154   -## 1.2 基站上传多包给SDK
155   -
156   -### 1.2.1 sdk发送数据信息
157   -基站主动发送：
158   -| **字节** | **标识符** | **描述** |
159   -| --- | --- | --- |
160   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
161   -| 2-3 | Len | 有效数据长度 |
162   -| 4 | Direct | 0x81：基站主动发起的通信 |
163   -| 5-6 | com seq | 通信序号 |
164   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
165   -| 8 | type | 1 要下载的数据信息 |
166   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
167   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
168   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
169   -| 18 | transfer total | 总传输次数 |
170   -| 19 | transfer cur | 当前传输次数 |
171   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
172   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
173   -|default | | |
174   -|60-63 | crc32 | 此数据包的crc32 |
  138 +| 0 | Header | 数据包头：基站主动发送0xB3;sdk主动发送0xD3 |
  139 +| 1-2 | defualt | |
  140 +| 3-4 | com seq | 通信序号 |
  141 +| 5 | BASEID | 指定的基站编号，为0时候不指定 |
  142 +| 6 | DATA-type | 1：json数据 <br>2：普通数据; |
  143 +| 7-10 | DATA_total| 数据总字节数 |
  144 +| 11-14 | total DATA crc32 | 总数据crc32 |
  145 +| 15 | transfer total | 总传输次数 |
  146 +| 16 | transfer cur | 当前传输次数 |
  147 +| 17-18 | This PACK Len |本次要传输的数据包长度 |
  148 +| 19-22 | This Pack crc32 | 本次要传输的数据crc32 |
  149 +| 23 | result | 接收方验证后回复结果：1-成功；2-失败 |
  150 +
  151 +
  152 +# 二， 功能协议
  153 +
  154 +## 2.1 固件升级类协议
  155 +### 2.1.0 固件升级类的流程：
  156 +- step1: 上层软件发送固件升级指令信息：
  157 + - 升级对象(基站，键盘，字库...)
  158 + - 固件字节数
  159 + - 固件crc32
  160 + - 其他
  161 +- step2: 基站回复表示收到命令，开始为固件升级做准备
  162 +- step3: 基站发送数据申请信息：
  163 + - 固件起始位置
  164 + - 固件数据长度
  165 +- step4: 上层软件根据基站申请读取对应数据发送给基站；
  166 + - 固件起始地址
  167 + - 固件数据长度
  168 + - 数据数据
  169 +- 重复step3,step4直到基站获取到全部固件数据
  170 +- step5: 基站发送固件升级完成信息，通知上层可以退出固件升级模式
  171 + - 升级对象
  172 +
  173 +
  174 +### 2.1.1 固件升级协议
  175 +#### 2.1.1.1 setFwUpdateState
  176 +
  177 +- **功能描述**:固件升级
  178 +- **参数说明**
  179 +
  180 +|参数名|类型|限制|是否必填|说明|
  181 +|---|---|---|---|---|
  182 +|fun|string|-|是|指令名称|
  183 +|dataTag|string|-|否|数据包标识,可为空字符串|
  184 +|baseSn|string||是|基站的出厂编码|
  185 +|data|object|-|是|传送参数的对象|
  186 +|+state|string||是|状态<br>"start"-开始升级<br>"stop"-停止升级
  187 +|+partition|string||是|"base_fw" 基站固件 <br> "base_fw_bk" 基站备份固件 <br> "keypad_fw" 键盘固件<br> "front" 字库文件|
  188 +|+file len|uint||是|升级固件文件的大小(字节数)，10进制数字|
  189 +|+version|string||是|待升级的基站固件版本|
  190 +|+crc|uint||是|固件CRC校验码，10进制数字|
  191 +<!-- |+time|string||是|时间，yyyyMMddHHmmss|
  192 +|+verCode|string||是|内部主题校验码，时间+固定key加密| -->
  193 +
  194 +- **示例代码**
  195 +```json
  196 +{
  197 + "fun":"setFwUpdateState",
  198 + "dataTag":"1",
  199 + "baseSn":"2024061101",
  200 + "data":{
  201 + "state":"start",
  202 + "partition":"base_fw",
  203 + "file_len":12000,
  204 + "version":"1.0.3",
  205 + "crc":1429319861
  206 + }
  207 +}
  208 +```
  209 +
  210 +#### 2.1.1.2 fEvtFwUpateState
  211 +- **功能描述**：返回升级状态
  212 +- **参数说明**
  213 +
  214 +|参数名|类型|限制|非空|说明|
  215 +|---|---|---|---|---|
  216 +|fun|string|-|是|指令名称|
  217 +|dataTag|string|-|否|数据包标识,可为空字符串|
  218 +|baseSn|string||是|基站的出厂编码|
  219 +|data|object|-|是|传送参数的对象|
  220 +|+state|string||是|状态<br>"start"-开始升级<br>"stop"-停止升级 <br>"complete"-完成升级
  221 +|+msg|string||否|返回的失败原因
  222 +
  223 +- **示例代码**
  224 +```json
  225 +{
  226 + "fun":"fEvtFwUpateState",
  227 + "dataTag":"1",
  228 + "baseSn":"2024061101",
  229 + "data":{
  230 + "state":"start",
  231 + "msg":"error msg"
  232 + }
  233 +}
  234 +```
  235 +
  236 +#### 2.1.1.3 sEvtReqeustFwData
  237 +- **功能描述**：返回升级状态
  238 +- **参数说明**
  239 +
  240 +|参数名|类型|限制|非空|说明|
  241 +|---|---|---|---|---|
  242 +|fun|string|-|是|指令名称|
  243 +|dataTag|string|-|否|数据包标识,可为空字符串|
  244 +|baseSn|string||是|基站的出厂编码|
  245 +|data|object|-|是|传送参数的对象|
  246 +|+offset|uint||是|数据段的起始地址
  247 +|+len|uint||是|数据段长度
  248 +
  249 +- **示例代码**
  250 +```json
  251 +{
  252 + "fun":"sEvtReqeustFwData",
  253 + "dataTag":"1",
  254 + "baseSn":"2024061101",
  255 + "data":{
  256 + "offset":0,
  257 + "len":5
  258 + }
  259 +}
  260 +```
  261 +
  262 +
  263 +#### 2.1.1.4 fwDataInfo
  264 +- **功能描述**：返回升级状态
  265 +- **参数说明**
  266 +
  267 +|参数名|类型|限制|非空|说明|
  268 +|---|---|---|---|---|
  269 +|fun|string|-|是|指令名称|
  270 +|dataTag|string|-|否|数据包标识,可为空字符串|
  271 +|baseSn|string||是|基站的出厂编码|
  272 +|data|object|-|是|传送参数的对象|
  273 +|+offset|uint||是|数据段的起始地址
  274 +|+len|uint||是|数据段长度，指十六进制字节个数
  275 +|+data|string||是|数据段,十六进制字符串
  276 +- **示例代码**
  277 +```json
  278 +{
  279 + "fun":"fwDataInfo",
  280 + "dataTag":"1",
  281 + "baseSn":"2024061101",
  282 + "data":{
  283 + "offset":0,
  284 + "len":5,
  285 + "data": "bc1234ffff"
  286 + }
  287 +}
  288 +```
  289 +
  290 +
  291 +
  292 +
175 293  
176   -SDK应答：
177   -| **字节** | **标识符** | **描述** |
178   -| --- | --- | --- |
179   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
180   -| 2-3 | Len | 有效数据长度 |
181   -| 4 | Direct | 0x81：基站主动发起的通信 |
182   -| 5-6 | com seq | 通信序号 |
183   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
184   -| 8 | type | 1 要下载的数据信息 |
185   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
186   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
187   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
188   -| 18 | transfer total | 总传输次数 |
189   -| 19 | transfer cur | 当前传输次数 |
190   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
191   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
192   -|default | | |
193   -|60-63 | crc32 | 此数据包的crc32 |
194 294  
195 295  
196   -### 1.2.2 基站连续发送N包纯数据包，SDK无需回复
197 296  
198   -### 1.2.3 基站发送询问
199 297  
200   -| **字节** | **标识符** | **描述** |
201   -| --- | --- | --- |
202   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
203   -| 2-3 | Len | 有效数据长度 |
204   -| 4 | Direct | 0x81：基站主动发起的通信 |
205   -| 5-6 | com seq | 通信序号 |
206   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
207   -| 8 | type | 2 询问基站 |
208   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
209   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
210   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
211   -| 18 | transfer total | 总传输次数 |
212   -| 19 | transfer cur | 当前传输次数 |
213   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
214   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
215   -|default | | |
216   -|60-63 | crc32 | 此数据包的crc32 |
217 298  
218   -基站应答：
219   -| **字节** | **标识符** | **描述** |
220   -| --- | --- | --- |
221   -| 0-1 | Header | 数据包头：固定0xFF 0x5A |
222   -| 2-3 | Len | 有效数据长度 |
223   -| 4 | Direct | 0x81：基站主动发起的通信 |
224   -| 5-6 | com seq | 通信序号 |
225   -| 7 | BASEID | 指定的基站编号，为0时候不指定 |
226   -| 8 | type | 2 询问基站 |
227   -| 9 | DATA-type | 1：json数据 <br>2：普通数据; |
228   -| 10-13 | DATA_total| 数据总字节数 高位在前 |
229   -| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
230   -| 18 | transfer total | 总传输次数 |
231   -| 19 | transfer cur | 当前传输次数 |
232   -| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
233   -| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
234   -| 26 | result | 1：成功 <br>2：失败; |
235   -|60-63 | crc32 | 此数据包的crc32 |
... ...