%E6%B5%B7%E4%BA%AE%E5%AE%9A%E5%88%B6.md

# 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 = 61 文本预设 |
| 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
}
```
| 名词 | 备注 |
| --- | --- | 
| t | 当前时间轴秒 |
    
### 基站管理
      
#### 基站上线
由基站发给应用程序，应用需要订阅主题
主题 ： /client/${clientId}/online 
指令内容：
``` 
{
	"i": 40
} 
``` 
      
#### 基站下线
由服务器发给应用程序，应用需要订阅主题
主题：/client/${clientId}/offline 
指令内容：
```json 
{ 
	"i": 41
} 
``` 
      
#### 基站信息设置与读取
应用程序发送给基站
主题： /client/${client}/operate 
指令内容：
```json 
{
	"i": 20,
	"m": {
		"f": 0,
		"ap": 0,
		"rssi": 0,
		"khs": "on",
		"mm": 1,
		"pm": 0,
		"arti": 30,
		"mqtt_ip": "edunew.sunvotecloud.cn",
		"mqtt_port": 8443,
		"mqtt_username": "admin",
		"mqtt_password": "1223456789",
		"heartbeat": 0,
		"keypad_af": 0,
		"keypad_ap": 0
	}
}
```
| 主题 | 备注 |
| --- | --- |
| f |基站频点 |
| ap |考勤功率 |
| rssi |答题器考勤的RSSI阈值 |
| khs |键盘心跳开关 |
| mm |基站配对模式| 
| arti |考勤上报时间间隔 |
| pm |键盘关机模式 | 
| mqtt\_ip | 连接服务器的IP(只能是IP，不能是域名) | 
| mqtt\_port | 连接mqtt服务器的端口 |
| mqtt\_username | 连接mqtt服务器的用户名 |
| mqtt\_password | 连接mqtt服务器的密码 | 
| heartbeat |心跳 0 关闭 1 开启 |
| keypad\_af | 考勤频率（0-3） | 
| keypad\_ap | 考勤功率（0-5）|
| 注意 | 如果没有该字段则不设置该值，保持原值下发对有需要修改的值设置完成后，基站信息会自动上报一次 |
      
#### 基站信息上报
基站发送给应用程序
主题: /client/${client}/report
指令内容：
```json
{
	"i": 21,
	"cId": "2024010282",
	"m": {
		"f": 1,
		"ap": 1,
		"rssi": 1,
		"khs": "off",
		"mc": "AFCEABCD",
		"mm": 4,
		"sn": "32121234",
		"arti": 30,
		"pm": 1,
		"cm": "1.0.0",
		"cv": "1.0.0",
		"mqtt_ip": "edunew.sunvotecloud.cn",
		"mqtt_port": 8443,
		"mqtt_username": "admin",
		"mqtt_password": "1223456789",
		"heartbeat": 0,
		"keypad_af": 0,
		"keypad_ap": 0
	}
}
```
| 名词 | 备注 |
| --- | --- |
| f |基站频点 |
| ap |考勤功率 |
| rssi |答题器考勤的RSSI阈值 |
| khs |键盘心跳开关 |
| mm |基站配对模式| 
| arti |考勤上报时间间隔 |
| pm |键盘关机模式 | 
| mqtt\_ip | 连接服务器的IP(只能是IP，不能是域名) | 
| mqtt\_port | 连接mqtt服务器的端口 |
| mqtt\_username | 连接mqtt服务器的用户名 |
| mqtt\_password | 连接mqtt服务器的密码 | 
| heartbeat |心跳 0 关闭 1 开启 |
| keypad\_af | 考勤频率（0-3） | 
| keypad\_ap | 考勤功率（0-5）|
| 注意 | 如果没有该字段则不设置该值，保持原值下发对有需要修改的值设置完成后，基站信息会自动上报一次 |
      
#### 基站错误信息上报
基站发送给应用程序
主题：/client/${client}/error
指令内容：
```json
{
	"i": 22,
	"m": {
		"et": 1,
		"em": "3"
	}
}
```
| 名词 | 备注 |
| --- | --- |
| 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内包含白名单键盘按编号 |
|||
      
#### 删除白名单
应用程序发送给基站
主题: /lesson/class/${clinetId}/receive
指令内容：
```json
{
	"i": 4,
	"m": ["12345", "56789"]
}
```
| 名词 | 备注 |
| --- | --- |
| i = 4 |删除白名单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": 60,
	"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": 61,
	"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": 61,
	"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失败 |
|||