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

何征华
1 parent 11420fa5
Showing 1 changed file with 240 additions and 177 deletions
通讯协议-教育新版-基站部分usb json.md
 [TOC]
-# 一、概述
+# 概述
 ### 通信流程
 相对usb 64byte传输，json格式命令数据长度大多都是比较长的。使用常规的一问一答的方式效率较低；
 所以设计了如下通信方式：
@@ -10,226 +10,289 @@
   - 错误->接收方从step 1开始重发;
 ### 说明：
-为了避免通信失败时重发的代价太大，在step 1中将数据包拆分成N个以1024bytes为单位的小数据包；
+- 为了避免通信失败时重发的代价太大，在step 1中将数据包拆分成N个以1024bytes为单位的小数据包；
 当如上传输出错时，只需重传当前的1024bytes即可;
+- 为了解决通信双方随时都可以主动发起，通信双方在所有数据头上加上明显辨识，用于接收方识别收到的数据是对方主动发送还是ack;
-### 通信机制
-在"通信流程" step 2中传输的是纯数据，接收方会把所有当前收到的数据都当作是纯数据，这样在收发双方通信时就会有如下限制：
- - 发送方必须在完成当前数据传输流程后才可以开始下一个传输流程；
- - 接收方必须在完成当前数据传输流程后才可以主动发起传输。
+如下是基站主动发送的数据头
+| **基站发送数据头** | **描述** | **sdk回复数据头** |
+| --- | --- | --- |
+| 0xB1 | 基站主动发送数据信息 | 0xB1 |
+| 0xB2  | 基站主动发送纯数据 | 无需回复 |
+| 0xB3 | 基站主动发送询问 | 0xB3 |
+
+如下是SDK主动发送的数据头
+| **SDK发送数据头** | **描述** | **基站回复数据头** |
+| --- | --- | --- |
+| 0xD1 | SDK主动发送数据信息 | 0xD1 |
+| 0xD2  | SDK主动发送纯数据 | 无需回复 |
+| 0xD3 | SDK主动发送询问 | 0xD3 |
-# 二，
-## 1.1 sdk下载多包给基站
+# 一， 协议描述
-### 1.1.1 sdk发送数据信息
-电脑向基站发送：
+## 1.1 发送数据信息
+发送方发送数据：(所有非1字节数据都是高字节在前)
 | **字节** | **标识符** | **描述** |
 | --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x01 : sdk主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 1 要下载的数据信息 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
+| 0 | Header | 数据包头：基站主动发送0xB1;sdk主动发送0xD1 |
+| 1-2 | defualt |  |
+| 3-4 | com seq | 通信序号 |
+| 5 | BASEID | 指定的基站编号，为0时候不指定 |
+| 6 | DATA-type | 1：json数据 <br>2：普通数据;  |
+| 7-10 | DATA_total| 数据总字节数  |
+| 11-14 | total DATA crc32 | 总数据(DATA_total长度)crc32|
+| 15 | transfer total | 总传输次数 |
+| 16 | transfer cur | 当前传输次数 |
+| 17-18 | This PACK Len |本次要传输的数据包长度  |
+| 19-22 | This Pack crc32 | 本次要传输的数据(This PACK Len长度)crc32 |
 |default  |   |  |
 |60-63  | crc32  | 此数据包的crc32；从byte0-59共60个字节 |
-举例：sdk要发送(1024X2 +512 bytes)数据给基站 
+举例：sdk要发送(1071 * 2 +512 bytes)数据给基站 
 第一个发送单元：
     step1: 
-        5-6：100 
-        10-13 bytes： (1024*2 +512 bytes)
-        14-17 ：数据总长度的crc
-        18 : 3 
-        19 : 0
-        20-21 : 1024 
-        22-25 ：1024数据的crc       
+        3-4：100 
+        7-10 bytes： (1071 * 2 +512 bytes)
+        11-14 ：数据总长度的crc
+        15 : 3 
+        16 : 0 
+        17-18 : 1071 
+        19-22 ：1071数据的crc       
         60-63 : crc
     step2: 基站ack
-    step3: sdk发送1024长度数据；64byte*16包；
+    step3: sdk发送1071长度数据；63byte * 17包；
     step4: sdk发送询问信息 
     step5: 基站ack
 第二个发送单元：
     step1: 
-        5-6：101 
-        10-13 bytes： (1024*2 +512 bytes)
-        14-17 ：数据总长度的crc
-        18 : 3 
-        19 : 1
-        20-21 : 1024 
-        22-25 ：1024数据的crc       
+        3-4：100 
+        7-10 bytes： (1071 * 2 +512 bytes)
+        11-14 ：数据总长度的crc
+        15 : 3 
+        16 : 1
+        17-18 : 1071 
+        19-22 ：1071数据的crc       
         60-63 : crc
     step2: 基站ack
-    step3: sdk发送1024长度数据；64byte*16包；
+    step3: sdk发送1071长度数据；63byte * 17包；
     step4: sdk发送询问信息 
     step5: 基站ack
 第三个发送单元：
     step1: 
-        5-6：102 
-        10-13 bytes： (1024*2 +512 bytes)
-        14-17 ：数据总长度的crc
-        18 : 3 
-        19 : 2
-        20-21 : 512 
-        22-25 ：512数据的crc       
-        60-63 : crc
+        3-4：100 
+        7-10 bytes： (1071 * 2 +512 bytes)
+        11-14 ：数据总长度的crc
+        15 : 3 
+        16 : 2
+        17-18 : 512 
+        19-22 ：512数据的crc       
+        60-63 : crc        
     step2: 基站ack
-    step3: sdk发送512长度数据；64byte*8包；
+    step3: sdk发送512长度数据；63byte * 9包；
     step4: sdk发送询问信息 
     step5: 基站ack
-基站应答：
+接收方应答：
 | **字节** | **标识符** | **描述** |
 | --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x01 : sdk主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 1 要下载的数据信息 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-|default  |   |  |
-|60-63  | crc32  | 此数据包的crc32 |
+| 0 | Header | 数据包头：sdk应答0xB1;基站应答0xD1 |
+| 1-2 | defualt |  |
+| 3-4 | com seq | 通信序号 |
+| 5 | BASEID | 指定的基站编号，为0时候不指定 |
+| 6 | DATA-type | 1：json数据 <br>2：普通数据;  |
+| 7-10 | DATA_total| 数据总字节数  |
+| 11-14 | total DATA crc32 | 总数据crc32 |
+| 15 | transfer total | 总传输次数 |
+| 16 | transfer cur | 当前传输次数 |
+| 17-18 | This PACK Len |本次要传输的数据包长度  |
+| 19-22 | This Pack crc32 | 本次要传输的数据crc32 |
-### 1.1.2 sdk连续发送N包纯数据包，基站无需回复
-
-### 1.1.3 sdk发送询问
+## 1.2 发送方连续发送N包数据包，接收方无需回复
+每个数据包都带一个字节的数据头：
+- 基站主动发送0xB2;
+- sdk主动发送0xD2
+## 1.3 发送方发送询问
 | **字节** | **标识符** | **描述** |
 | --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x01 : sdk主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 2 询问基站 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-|default  |   |  |
-|60-63  | crc32  | 此数据包的crc32 |
+| 0 | Header | 数据包头：基站主动发送0xB3;sdk主动发送0xD3 |
+| 1-2 | defualt |  |
+| 3-4 | com seq | 通信序号 |
+| 5 | BASEID | 指定的基站编号，为0时候不指定 |
+| 6 | DATA-type | 1：json数据 <br>2：普通数据;  |
+| 7-10 | DATA_total| 数据总字节数  |
+| 11-14 | total DATA crc32 | 总数据crc32 |
+| 15 | transfer total | 总传输次数 |
+| 16 | transfer cur | 当前传输次数 |
+| 17-18 | This PACK Len |本次要传输的数据包长度 |
+| 19-22 | This Pack crc32 | 本次要传输的数据crc32 |
-基站应答：
+接收方应答：
 | **字节** | **标识符** | **描述** |
 | --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x01 : sdk主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 2 询问基站 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-| 26  | result  | 1：成功 <br>2：失败; |
-|60-63  | crc32  | 此数据包的crc32 |
-
-
-## 1.2 基站上传多包给SDK
-
-### 1.2.1 sdk发送数据信息
-基站主动发送：
-| **字节** | **标识符** | **描述** |
-| --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x81：基站主动发起的通信  |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 1 要下载的数据信息 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-|default  |   |  |
-|60-63  | crc32  | 此数据包的crc32 |
+| 0 | Header | 数据包头：基站主动发送0xB3;sdk主动发送0xD3 |
+| 1-2 | defualt |  |
+| 3-4 | com seq | 通信序号 |
+| 5 | BASEID | 指定的基站编号，为0时候不指定 |
+| 6 | DATA-type | 1：json数据 <br>2：普通数据;  |
+| 7-10 | DATA_total| 数据总字节数  |
+| 11-14 | total DATA crc32 | 总数据crc32 |
+| 15 | transfer total | 总传输次数 |
+| 16 | transfer cur | 当前传输次数 |
+| 17-18 | This PACK Len |本次要传输的数据包长度  |
+| 19-22 | This Pack crc32 | 本次要传输的数据crc32 |
+| 23 | result | 接收方验证后回复结果：1-成功；2-失败 |
+
+
+# 二， 功能协议
+
+## 2.1 固件升级类协议
+### 2.1.0 固件升级类的流程：
+- step1: 上层软件发送固件升级指令信息：
+  - 升级对象(基站，键盘，字库...) 
+  - 固件字节数 
+  - 固件crc32 
+  - 其他
+- step2: 基站回复表示收到命令，开始为固件升级做准备
+- step3: 基站发送数据申请信息：
+  - 固件起始位置 
+  - 固件数据长度
+- step4: 上层软件根据基站申请读取对应数据发送给基站；
+  - 固件起始地址 
+  - 固件数据长度 
+  - 数据数据
+- 重复step3,step4直到基站获取到全部固件数据
+- step5: 基站发送固件升级完成信息，通知上层可以退出固件升级模式
+  - 升级对象
+  
+
+### 2.1.1 固件升级协议
+#### 2.1.1.1 setFwUpdateState
+
+- **功能描述**:固件升级
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|baseSn|string||是|基站的出厂编码|
+|data|object|-|是|传送参数的对象|
+|+state|string||是|状态<br>"start"-开始升级<br>"stop"-停止升级
+|+partition|string||是|"base_fw" 基站固件 <br> "base_fw_bk" 基站备份固件 <br> "keypad_fw" 键盘固件<br> "front" 字库文件|
+|+file len|uint||是|升级固件文件的大小(字节数)，10进制数字|
+|+version|string||是|待升级的基站固件版本|
+|+crc|uint||是|固件CRC校验码，10进制数字|
+<!-- |+time|string||是|时间，yyyyMMddHHmmss|
+|+verCode|string||是|内部主题校验码，时间+固定key加密| -->
+
+- **示例代码**
+```json
+{
+  "fun":"setFwUpdateState",
+  "dataTag":"1",
+  "baseSn":"2024061101",
+  "data":{
+    "state":"start",
+    "partition":"base_fw",
+    "file_len":12000,
+    "version":"1.0.3",
+    "crc":1429319861
+  }
+}
+```
+
+#### 2.1.1.2 fEvtFwUpateState
+- **功能描述**：返回升级状态
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|baseSn|string||是|基站的出厂编码|
+|data|object|-|是|传送参数的对象|
+|+state|string||是|状态<br>"start"-开始升级<br>"stop"-停止升级 <br>"complete"-完成升级
+|+msg|string||否|返回的失败原因
+
+- **示例代码**
+```json
+{
+  "fun":"fEvtFwUpateState",
+  "dataTag":"1",
+  "baseSn":"2024061101",
+  "data":{
+    "state":"start",
+    "msg":"error msg"
+  }
+}
+```
+
+#### 2.1.1.3 sEvtReqeustFwData
+- **功能描述**：返回升级状态
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|baseSn|string||是|基站的出厂编码|
+|data|object|-|是|传送参数的对象|
+|+offset|uint||是|数据段的起始地址
+|+len|uint||是|数据段长度
+
+- **示例代码**
+```json
+{
+  "fun":"sEvtReqeustFwData",
+  "dataTag":"1",
+  "baseSn":"2024061101",
+  "data":{
+    "offset":0,
+    "len":5
+  }
+}
+```
+
+
+#### 2.1.1.4 fwDataInfo
+- **功能描述**：返回升级状态
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|baseSn|string||是|基站的出厂编码|
+|data|object|-|是|传送参数的对象|
+|+offset|uint||是|数据段的起始地址
+|+len|uint||是|数据段长度，指十六进制字节个数
+|+data|string||是|数据段,十六进制字符串
+- **示例代码**
+```json
+{
+  "fun":"fwDataInfo",
+  "dataTag":"1",
+  "baseSn":"2024061101",
+  "data":{
+    "offset":0,
+    "len":5,
+    "data": "bc1234ffff"
+  }
+}
+```
+
+
+
+
-SDK应答：
-| **字节** | **标识符** | **描述** |
-| --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x81：基站主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 1 要下载的数据信息 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-|default  |   |  |
-|60-63  | crc32  | 此数据包的crc32 |
-### 1.2.2 基站连续发送N包纯数据包，SDK无需回复
-### 1.2.3 基站发送询问
-| **字节** | **标识符** | **描述** |
-| --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x81：基站主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 2 询问基站 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-|default  |   |  |
-|60-63  | crc32  | 此数据包的crc32 |
-基站应答：
-| **字节** | **标识符** | **描述** |
-| --- | --- | --- |
-| 0-1 | Header | 数据包头：固定0xFF 0x5A |
-| 2-3 | Len | 有效数据长度 |
-| 4 | Direct | 0x81：基站主动发起的通信 |
-| 5-6 | com seq | 通信序号 |
-| 7 | BASEID | 指定的基站编号，为0时候不指定 |
-| 8 | type | 2 询问基站 |
-| 9 | DATA-type | 1：json数据 <br>2：普通数据;  |
-| 10-13 | DATA_total| 数据总字节数 高位在前 |
-| 14-17 | total DATA crc32 | 总数据crc32 高位在前|
-| 18 | transfer total | 总传输次数 |
-| 19 | transfer cur | 当前传输次数 |
-| 20-21 | This PACK Len |本次要传输的数据包长度 高位在前 |
-| 22-25 | This Pack crc32 | 本次要传输的数据crc32 |
-| 26  | result  | 1：成功 <br>2：失败; |
-|60-63  | crc32  | 此数据包的crc32 |