李外 / Protocol

  [TOC]

  # 概述

  ### 通信流程
  相对usb 64byte传输，json格式命令数据长度大多都是比较长的。使用常规的一问一答的方式效率较低；
  所以设计了如下通信方式：
  - step 1,发送方先发送整个数据包的信息；接收方回复； 
  - step 2,发送方发送纯数据，此时接收方只接收不回复；
  - step 3,发送方发送询问"接收方是否正确的接收到刚刚的数据"，接收方回复：
    - 正确->本次通信结束;
    - 错误->接收方从step 1开始重发;

  ### 说明：

  - 为了避免通信失败时重发的代价太大，在step 1中将数据包拆分成N个以1024bytes为单位的小数据包；

  当如上传输出错时，只需重传当前的1024bytes即可;

  - 为了解决通信双方随时都可以主动发起，通信双方在所有数据头上加上明显辨识，用于接收方识别收到的数据是对方主动发送还是ack;

  如下是基站主动发送的数据头
  | **基站发送数据头** | **描述** | **sdk回复数据头** |
  | --- | --- | --- |
  | 0xB1 | 基站主动发送数据信息 | 0xB1 |
  | 0xB2  | 基站主动发送纯数据 | 无需回复 |
  | 0xB3 | 基站主动发送询问 | 0xB3 |
  
  如下是SDK主动发送的数据头
  | **SDK发送数据头** | **描述** | **基站回复数据头** |
  | --- | --- | --- |
  | 0xD1 | SDK主动发送数据信息 | 0xD1 |
  | 0xD2  | SDK主动发送纯数据 | 无需回复 |
  | 0xD3 | SDK主动发送询问 | 0xD3 |

  # 一， 协议描述

  ## 1.1 发送数据信息
  发送方发送数据：(所有非1字节数据都是高字节在前)

  | **字节** | **标识符** | **描述** |
  | --- | --- | --- |

  | 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要发送(1071 * 2 +512 bytes)数据给基站 

  第一个发送单元：
      step1: 

          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发送1071长度数据；63byte * 17包；

      step4: sdk发送询问信息 
      step5: 基站ack
  
  第二个发送单元：
      step1: 

          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发送1071长度数据；63byte * 17包；

      step4: sdk发送询问信息 
      step5: 基站ack
  
  第三个发送单元：
      step1: 

          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长度数据；63byte * 9包；

      step4: sdk发送询问信息 
      step5: 基站ack
  

  接收方应答：

  | **字节** | **标识符** | **描述** |
  | --- | --- | --- |

  | 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.2 发送方连续发送N包数据包，接收方无需回复
  每个数据包都带一个字节的数据头：

  - 基站主动发送0xB2;下一字节表示当次传输序号从1开始 1-N
  - sdk主动发送0xD2下一字节表示当次传输序号从1开始 1-N

  ## 1.3 发送方发送询问

  | **字节** | **标识符** | **描述** |
  | --- | --- | --- |

  | 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 | 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-失败 |

  | 24-N | result_information | 接收到的包号，依次往下写。接收方判断result为失败的时候查看这里可以直接做补传，后续直接发送0XB2 or0XD2 补传对应包 再询问|
  
  
  
  ## 1.4 事务短包通信
  基站发送数据头：0XB5  SDK回复：0XB5
  数据量小于64字节的做精简通信，若需则可扩展的话增加第三字节（SDK&基站自己判断收齐做事情）  默认可以设定《64还是《128使用该协议  ，其他使用流通信。
  
  | **字节** | **标识符** | **描述** |
  | --- | --- | --- |
  | 0 | Header | 数据包头：基站主动发送0x B5;sdk主动发送0Xd5 |
  | 1-2 | com seq | 通信序号 |
  | 3 | control bit| bit0-2:当前包总传输次数 <br>bit3-5:当前包传输次数<br>bit6-8:指定的基站编号，为0时候不指定|
  | default | data | 数据包 |
  | 60-63 | crc32 | 此数据包的crc32；从byte0-59共60个字节 |
  
  
  ## 1.5 问询精简通信
  该协议只在纯询问阶段使用。其他开始结束等等 通过原始指令 使用流模式或者事务模式
  | **字节** | **标识符** | **描述** |
  | --- | --- | --- |
  | 0 | Header | 数据包头：基站主动发送0x B6;sdk主动发送0Xd6 |
  | 1-2 | com seq | 通信序号 |
  | 3 | BASEID| 指定的基站编号，为0时候不指定|
  | 4 | CMD| 索要数据包数据类型==》对应具体事务从1开始往下排根据数据类型来区分接收的数据长度等等数据类型|
  | 5-6 | PACK| 数据编号|
  | default |  |  |
  | 60-63 | crc32 | 此数据包的crc32；从byte0-59共60个字节 |
  
  
  回复该包之后 后续跟着0XB2/0XD2 的长透传数据包
  | **字节** | **标识符** | **描述** |
  | --- | --- | --- |
  | 0 | Header | 数据包头：基站主动发送0x B6;sdk主动发送0Xd6 |
  | 1-2 | com seq | 通信序号 |
  | 3 | BASEID| 指定的基站编号，为0时候不指定|
  | 4 | CMD| 索要数据包数据类型==》对应具体事务从1开始往下排根据数据类型来区分接收的数据长度等等数据类型|
  | 5-6 | PACK| 数据编号|
  | 7-8 | This PACK Len| 本次要传输的数据包长度|
  | 9-12 | This Pack crc32| 本次要传输的数据crc32|
  | default |  |  |
  | 60-63 | crc32 | 此数据包的crc32；从byte0-59共60个字节 |

  
  
  # 二， 功能协议
  
  ## 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"
    }
  }
  ```