李外 / Protocol

  # C200K
  
  # 1. 前言
  
    
  ## 1.1 背景
  
  方便客户基于C200K基站设备使用 通信基站数据接收及解析。
  
    
  ## 1.2 编写目的
  
  此说明书是为了说明协议内容，开发流程，方便基于此进行二次开发。
  
   
  ##  1.3 读者对象
  
  1. 相关研发人员
  2. 方案制定人员
  3. 决策人员
  
  
  # 2. 开发流程
  
  C200K基站，采用MQTT协议进行开发，基站接入MQTT服务器，应用从MQTT服务器下发指令和接收数据
  
  整个交互图如下:
  
  ![](img/mqtt_1.png)
  
    
  ## 2.1 MQTT服务器准备
  
  MQTT服务器要求：
  
  能够正常收发MQTT数据。
  
  服务器的性能参数由业务决定。
  
  域名：
  
  公网域名或ip或者基站所处局域网ip。
  
  MQTT服务器配置结果检查
  

  使用MQTT.FX客户端，配置域名，端口，用户名和密码信息，然后连接，如果提示连接成功，则表示MQTT服务器可用。基站clientid 是基站编号。

  
  ![](img/mqtt_2.png)
  
    
  ## 2.2 基站配置
  
  通过USB连接基站，打开基站服务器配置软件。
  

  ![](img/mqtt_3.png)

  
  如果基站没有连接电脑，工具显示检测基站中，这时候读写无效。
  
  连接正常后，按照各个信息进行写入。
  
  设置基站服务器域名（ip）、端口，用户信息、密码信息，写入基站。
  
  如果MQTT服务器没有启用用户密码验证，用户密码信息可以随机设置。
  
  拔掉USB，连接网线，接入网络，查看网络是否连接正常。（基站上面的灯是否蓝色闪烁）
  
  基站说明
  

  ![](img/mqtt_4.png)

  
    
  ## 2.3 应用开发
  
  整体开发流程图如下：
  

  ![](img/mqtt_5.png)

  
  
  # 3. 功能清单
  
    
  ## 3.1 支持的功能清单
  
  | **功能** | **说明** |
  | --- | --- |
  | 授时 | 给基站校时 |
  | 基站上下线 | 基站上下线信息 |
  | 键盘上下线 | 键盘上下线信息 |
  | 签到 | 答题器按键签到 |
  | 单题 | 下发一题测验 |
  | 多级编号题 | 下发多题测验 |
  | 基站升级 | 基站固件升级 |
  | 键盘升级 | 键盘固件升级 |
  | 基站错误信息上报 | 基站错误信息上报 |
  
    
  ## 3.2 协议简介
  
      
  ### 3.2.1 MQTT
  
  关于MQTT说明，请参考 https://mqtt.org/
  
  ${clinetId} clinetId 是基站编号，为替换字符串。
  
        
  #### 3.2.1.1 应用程序发布的主题
  
  | 主题 | 功能 |
  | --- | --- |
  | /client/${clientId}/operate | 基站的设置，查询等指令 |
  | /lesson/class/${clinetId}/receive | 接收答题的指令 |
  
        
  #### 3.2.1.2 应用程序订阅的主题
  
  | 主题 | 功能 |
  | --- | --- |
  | /client/${clientId}/online | 基站上线通知。 |
  | /client/${clientId}/offline | 基站下线通知。 |
  | /client/${clientId}/card/online | 答题器上线通知。 |
  | /client/${clientId}/card/offline | 答题器离线通知。 |

  | /client/${clientId}/report | 基站主动上报状态，或者对设置指令的回应。 |
  | /lesson/class/${clinetId}/send | 基站对答题/签到数据的反馈 |

  | /client/${clientId}/error | 基站错误信息上报 |
  
      
  ### 3.2.2 协议格式
  

  ![](img/mqtt_6.png)

  
  协议采用json格式，数据中字段见属性介绍。
  
      
  ### 3.2.3 指令属性介绍
  
  | 名称 | 类型 | 说明 |
  | --- | --- | --- |

  | i | number | 消息指令类型（instruction），取值范围： 1-9999。 <br> I=3 添加白名单 <br> I=4 删除白名单 <br> I=5 清除白名单 <br> i = 11 停止 <br> i = 12开启答题 <br> i = 13 接收答题数据 <br> i = 14 键盘上线 <br> i = 15 键盘下线 <br> i = 17 基站升级 <br> i = 18 升级报告 <br> i = 19 授时 <br>  i=20 设置基站信息 <br> i=21基站信息上报 <br> i=22基站错误信息上报 <br> i = 28 键盘升级 <br> i = 29 键盘升级报告 <br> I= 30 读取白名单 <br> I= 31 白名单上传 <br> i = 40 基站上线 <br> i = 41 基站下线  <br> i = 60 下发姓名 <br> i = 61 下发姓名设置返回 <br> i = 62 文本预设 <br> i = 63 文本预设返回|

  | m | object | 答题消息的内容(message) 对象或数组 |
  | c | string | 答题器的序号(card) |
  | t | number | 时间戳(10位timestamp) |
  | qm | number | 模式(question model)取值范围：<br> 0：停止 <br> 1：单题 <br> 7：签到 <br> 14：多级编号答题 |

  | qt | number | 题型（question type），取值范围： 0：字母单选 1：字母多选 2：数字题 3：判断题 4: 填空题 5：抢答 7:自判题判断题 |
  | qs | number | 该题型数量（question sum），单题为1，多题则为实际数量。 |

  | qn | number | 题型序号(question No) |

  | a | string | 答案（answer）示例：字母单选：A字母多选：A|B文本题：hex: 标记是gbk编码的hex内容 |
  | en | string | 练习（考试）编号(exercise No)每次考试或者练习的唯一编号，用于确定提交的答案属于那次练习。 |

  | on | number | 单选和多选题的选项数量(option no) |

  | cid | string | 客户端ID(client Id) |
  | cm | string | 客户端型号(client Model) |
  | cv | string | 客户端版本(client Version)基站软件版本号 |
  | f | number | 信道频点(frequency)基站频点取值：1-80 |
  | ap | number | 考勤功率(attend Power)取值：0-31，值约小，基站的接收能力约强。 |
  | rssi | number | 答题器考勤的RSSI阈值，软件实现的过滤。RSSI高于该值的答题器的该次考勤会丢弃。默认0，不过滤。 |
  | khs | string | 键盘心跳开关(keyboard Heartbeat Switch)，on开启，off关闭 |
  | arti | number | 考勤上报时间间隔(attend Reoprt Time Interval),默认30秒 |
  | content | string | 题干内容（选项信息都包含在此），中文信息用hex进行传输。内容前面需要 hex:详见后面示例 |

  | at | number | auto test自动测试，at = 1 |
  | sn | string | SN  序列号 |

  | mc | string | Match code 基站配对码 |
  | el | number | Electricity 键盘电量 百分比 0.75 75% |

  | pm | number | Power mode 关机模式 pm = 0 在线不关机Pm = 1 在线超时关机 |

  | et | number | 错误类型et =1 基站频点冲突 |

  | em | string | 错误消息em = "3" 配合et使用，如et=1 em=3 表示3号频点冲突 |

  | success | number | 0 成功 非0：错误码 |
  
    
  ## 功能说明
  
      
  ### 授时
  
  对客户端授时，发送指令即可，基站会完成校时。
  

  主题 : /client/${client}/operate 
  
  ```

  {
  	"i": 19,
  	"t": 1634802943
  }

  ```

  | 名词 | 备注 |

  | --- | --- | 

  | i = 19 | 授时 |

  | t | 当前时间轴秒 |
  

  
      
  ### 基站管理
  
        

  #### 基站上线(待完成-可能修改)

  
  由基站发给应用程序，应用需要订阅主题
  

  主题 ： /client/${clientId}/online 
  
  指令内容：
  ``` 
  {
  	"i": 40
  } 
  ``` 

  #### 基站下线(待完成-可能修改)

  
  由服务器发给应用程序，应用需要订阅主题
  

  主题：/client/${clientId}/offline 
  指令内容：
  ```json 
  { 
  	"i": 41
  } 
  ``` 

  
        
  #### 基站信息设置与读取
  
  应用程序发送给基站
  

  主题： /client/${client}/operate 

  指令内容：

  ```json 
  {
  	"i": 20,
  	"m": {
  		"f": 0,

  		"mqtt_ip": "edunew.sunvotecloud.cn",
  		"mqtt_port": 8443,
  		"mqtt_username": "admin",

  		"mqtt_password": "1223456789"

  	}
  }
  ```
  
  | 主题 | 备注 |
  | --- | --- |

  | f |基站频点 |

  | mqtt\_ip | 连接服务器的IP(只能是IP，不能是域名) | 
  | mqtt\_port | 连接mqtt服务器的端口 |
  | mqtt\_username | 连接mqtt服务器的用户名 |

  | mqtt\_password | 连接mqtt服务器的密码 | 

  | 注意 | 如果没有该字段则不设置该值，保持原值下发对有需要修改的值设置完成后，基站信息会自动上报一次 |

  
        
  #### 基站信息上报
  
  基站发送给应用程序
  

  主题: /client/${client}/report
  指令内容：
  ```json
  {
  	"i": 21,
  	"cId": "2024010282",
  	"m": {
  		"f": 1,

  		"mqtt_ip": "edunew.sunvotecloud.cn",
  		"mqtt_port": 8443,
  		"mqtt_username": "admin",

  		"mqtt_password": "1223456789"

  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | f |基站频点 |

  | mqtt\_ip | 连接服务器的IP(只能是IP，不能是域名) | 
  | mqtt\_port | 连接mqtt服务器的端口 |
  | mqtt\_username | 连接mqtt服务器的用户名 |
  | mqtt\_password | 连接mqtt服务器的密码 | 

  #### 基站错误信息上报(待完成-可能修改)

  
  基站发送给应用程序

  主题：/client/${client}/error
  指令内容：
  ```json
  {
  	"i": 22,
  	"m": {
  		"et": 1,
  		"em": "3"
  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |

  | i = 22 | 基站错误信息上报 |

  | et |错误类型 et = 1 ：基站频点冲突 |
  | em |错误消息 em=3 ：3号频点示例 基站频点3冲突 |

  ### 键盘管理
  
        
  #### 键盘上线
  
  由基站发给应用程序，应用需要订阅主题

  主题: /client/${clientId}/card/online
  指令内容：
  ```json
  {
  	"i": 14,
  	"m": [{
  		"c": "12345",
  		"el": 0.75,
  		"t": 1626016299
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 14 |键盘上线 |
  | el |电量信息答题器编号和上线时间及电量信息 |

  #### 键盘下线
  
  由基站发给应用程序，应用需要订阅主题

  主题: /client/${clientId}/card/offline
  指令内容：
  ```json
  {
  	"i": 15,
  	"m": [{
  		"c": "12345",
  		"t": 1626016299
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 15 |键盘下线 |
  | t |答题器编号和下线时间 |

  
        
  #### 键盘在线检测

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 16
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 16 |应用主动通知键盘发送在线键盘信息 |

  
        
  #### 读取白名单
  
  应用程序发送给基站

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 30
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 30 |读取白名单 |

  
  基站发给应用程序

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 31,
  	"total": 1,
  	"current": 1,
  	"m": ["2126932551"]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 31 |白名单上传 |

  
        
  #### 添加白名单
  
  应用程序发送给基站

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 3,
  	"m": ["12345", "56789"]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 3 |添加白名单m内包含白名单键盘按编号 |

  | m |键盘列表 |

  
        
  #### 删除白名单
  
  应用程序发送给基站

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 4,
  	"m": ["12345", "56789"]
  }
  ```

  | 名词 | 备注 |
  | --- | --- |
  | i = 4 |删除白名单m内包含白名单键盘按编号 |

  | m |键盘列表 |

  
        
  #### 清空白名单
  
  应用程序发送给基站

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 5
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 5 |清空白名单 |

  
      
  ### 单题
  
        
  #### 开启答题
  
  由应用程序发给基站，应用按照主题发送

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 12,
  	"en": "12340",
  	"qm": 1,
  	"m": {
  		"qt": 0,
  		"on": 4,
  		"content": "hex: c7ebbbd8b4f0cfc2c3e633b5c0cad4cce2"
  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 12 |下发答题/签到指令  |
  | qm = 1 |单题模式 示例为单题模式的字母单选 |
  | qt  |字母单选 |
  | on  |选项数 |
  | content = 1 |题目主干内容 |

  
        
  #### 接收答题数据
  
  由基站发给应用程序，应用订阅主题

  主题: /lesson/class/${clinetId}/send
  指令内容：
  ```json
  {
  	"i": 13,
  	"en": "12340",
  	"qm": 1,
  	"c": "12345",
  	"m": [{
  		"qn": 1,
  		"a": "A",
  		"t": 1626016299
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 13 | 答题数据 |
  | qn = 1 |上报答题数据，单题题号固定为1 |
  | t  |提交答案时间 |
  | a  | 答题数据 |

        
  #### 停止答题

  由应用程序发给基站，应用按照主题发送

  主题：/lesson/class/${clinetId}/receive 
  指令内容：
  ```json
  {
  	"i": 11,
  	"en": "12340"
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 11 | 停止答题 |
  | en |停止对序号12340的测验 |

  ### 抢答(待完成-可能修改)

  #### 开启答题(待完成-可能修改)

  
  由应用程序发给基站，应用按照主题发送

  主题:  /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 12,
  	"en": "12341",
  	"qm": 4
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 12 | 开启答题 |
  | en |12341测验 |
  | qm | qm =4 抢答题 |

  #### 接收答题数据(待完成-可能修改)

  
  由基站发给应用程序，应用订阅主题

  主题： /lesson/class/${clinetId}/send
  指令内容：
  ```json
  {
  	"i": 13,
  	"en": "12341",
  	"qm": 4,
  	"c": "12345",
  	"m": [{
  		"qn": 1,
  		"a": "A",
  		"t": 1626016299
  	}]
  }
  ```

  | 名词 | 备注 |
  | --- | --- |
  | i = 12 | 开启答题 |
  | en |12341测验 |
  | qm | qm =4 抢答题 |
  | c | 键盘编号 |
  | qn |上报答题数据，单题题号固定为1 |
  | t  |提交答案时间 |
  | a  | 答题数据 |

  #### 停止答题(待完成-可能修改)

  由应用程序发给基站，应用按照主题发送

  主题：/lesson/class/${clinetId}/receive 
  指令内容：
  ```json
  {
  	"i": 11,
  	"en": "12341"
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 11 | 停止答题 |
  | en |停止对序号12341的测验 |

  ### 多题题号多题
  

  #### 开启答题
  
  由应用程序发给基站，应用按照主题发送

  主题： /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 12,
  	"en": "12341",
  	"qm": 14,
  	"qs": 3,
  	"m": [{
  		"qt": 0,
  		"on": 4,
  		"qn": "1-1-1"
  	}, {
  		"qt": 0,
  		"on": 4,
  		"qn": "2-1"
  	}, {
  		"qt": 0,
  		"on": 4,
  		"qn": "3"
  	}]
  }
  ```

  | 名词 | 备注 |
  | --- | --- |
  | i = 12 | 开启答题 |
  | qm = 14 | 多题多级编号模式 |
  | qt = 0 | 字母单选 |
  | on | 选项数量 |
  | qn | 题目多级编号 |

        
  #### 接收答题数据
  
  由基站发给应用程序，应用订阅主题

  主题: /lesson/class/${clinetId}/send
  指令内容：
  ```json
  {
  	"i": 13,
  	"en": "12341",
  	"qm": 14,
  	"c": "12345",
  	"m": [{
  		"qn": "1",
  		"a": "A",
  		"t": 1626016299
  	}]
  }
  ```

  | 名词 | 备注 |
  | --- | --- |
  | i = 13 | 接收答题数据 |
  | qm = 14 | 多题多级编号模式 |
  | c | 键盘编号 |
  | qn |上报答题数据 |
  | t  |提交答案时间 |
  | a  | 答题数据 |

  
        
  #### 停止答题

  由应用程序发给基站，应用按照主题发送

  主题：/lesson/class/${clinetId}/receive 
  指令内容：
  ```json
  {
  	"i": 11,
  	"en": "12341"
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 11 | 停止答题 |
  | en |停止对序号12341的测验 |

  
      
  ### 下发姓名

        
  #### 姓名下发

  主题: /lesson/class/${clinetId}/receive
  指令内容：
  ```json
  {
  	"i": 60,
  	"total": 1,
  	"current": 1,
  	"en": "12342",
  	"qs": 2,
  	"m": [{
  		"sn": "202308093214",
  		"name": "张三"
  	}, {
  		"sn": "202308093215",
  		"name": "李四"
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 60 | 姓名下发 |
  | en |序号12342的测验 |
  | current |当前第几包数据 |
  | total |一共几包数据 |
  | qs |总数 |
  | sn |键盘sn号 |
  | name |姓名 |

  #### 姓名下发成功失败返回 (待完成-可能修改)

  主题：/lesson/class/${clinetId}/send
  指令内容：
  ```json
  {

  	"i": 61,

  	"total": 1,
  	"current": 1,
  	"m": [{
  		"sn": "202308093214",
  		"success": 0
  	}, {
  		"sn": "202308093215",
  		"success": 0
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 60 | 姓名下发 |
  | en |序号12342的测验 |
  | current |当前第几包数据 |
  | total |一共几包数据 |
  | qs |总数 |
  | sn |键盘sn号 |
  | name |姓名 |

  
      
  ### 基站升级
  

  #### 开始升级

  主题: /client/${client}/operate
  指令内容：
  ```json
  {
  	"i": 17,
  	"en": "12342",
  	"m": {
  		"url": "",
  		"version": "",
  		"CRC": ""
  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 17 | 基站升级 |
  | en |序号 |
  | url |固件包地址，基站能访问到的路径 |
  | version |新固件的版本 |
  | CRC |新关键计算的CRC |

  
        
  #### 升级进度报告

  主题： /client/${client}/report
  指令内容：
  ```json
  {
  	"i": 18,
  	"m": {
  		"cId": "123456",
  		"percent": 0,
  		"status": 0
  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 18 | 升级进度报告 |
  | cId |基站编号 |
  | percent |升级百分比 |
  | status |升级状态信息。 <br> 0：未开始<br> 1：升级中<br> 2：升级成功<br> 4固件版本号错误<br> 5：不在升级名单内<br> 6：升级指令错误<br> \>127：升级中的错误码。 |

      
  ### 键盘升级

        
  #### 开始升级

  主题: /client/${client}/operate
  指令内容：
  ```json
  {
  	"i": 28,
  	"m": {
  		"url": "",
  		"version": "",
  		"CRC": ""
  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 28 | 键盘升级 |
  | url |固件包地址，基站能访问到的路径 |
  | version |新固件的版本号 |
  | CRC |新关键计算的CRC |

        
  #### 升级进度报告

  主题： /client/${client}/report
  指令内容：
  ```json
  {
  	"i": 29,
  	"m": {
  		"cId": "123456",
  		"percent": 0,
  		"status": 0
  	}
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 18 | 升级进度报告 |
  | cId |基站编号 |
  | percent |升级百分比 |
  | status |升级状态信息。 <br> 0：未开始<br> 1：升级中<br> 2：升级成功<br> 4固件版本号错误<br> 5：不在升级名单内<br> 6：升级指令错误<br> \>127：升级中的错误码。 |

  ### 文本预设
  

  #### 文本设置

  主题： /client/${client}/operate
  指令内容：
  ```json
  {

  	"i": 62,

  	"en": "123552",
  	"sn": ["12345", "56789"],
  	"m": [{
  		"cmd": 81,
  		"text": "hex:"
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 18 | 升级进度报告 |
  | sn |键盘列表 |
  | cmd |下发的命令 <br> 4  第二行文本 <br> 81 单选 <br> 82 多选 <br> 83 数字 <br> 84 判断 <br> 85 自判题判断  <br> 87 清除 |
  | text |标题信息，以hex:开头添加的内容 内容为GBK的hex编码 |

  
  ```java
   public static String bytesToHexString(byte[] src) {
  	StringBuilder stringBuilder = new StringBuilder("");
  	if (src == null || src.length <= 0) {
  		return null;
  	}
  	for (int i = 0; i < src.length; i++) {
  		int v = src[i] & 0xFF;
  		String hv = Integer.toHexString(v);
  		if (hv.length() < 2) {
  			stringBuilder.append(0);
  		}
  		stringBuilder.append(hv);
  		stringBuilder.append("");
  	}
  	return stringBuilder.toString();
  }
  ```

  #### 设置返回(待完成-可能修改)

  主题: /client/${client}/report
  指令内容：
  ```json
  {

  	"i": 63,

  	"en": "123552",
  	"sn": ["12345", "56789"],
  	"m": [{
  		"cmd": 81,
  		"success": 0
  	}]
  }
  ```
  | 名词 | 备注 |
  | --- | --- |
  | i = 61 | 升级进度报告 |
  | sn |键盘列表 |
  | cmd |下发的命令 <br> 4  第二行文本 <br> 81 单选 <br> 82 多选 <br> 83 数字 <br> 84 判断 <br> 85 自判题判断  <br> 87 清除 |
  | success | 是否成功。<br> 0 表示成功 <br> 非0 表示失败  -1失败 |