增加英文题、短消息、在线列表和遥控器事件的协议

刘琴
1 parent d04a2c7f
Showing 1 changed file with 338 additions and 10 deletions
通讯协议-B200W-MQTT协议[内部].md
@@ -32,7 +32,7 @@ SunVote B200W &lt;br&gt;MQTT通讯协议
 <br>
 <br>
 <div  style="text-align: center;font-size: 30px;">
-Ver 1.0.2
+Ver 1.0.3
 </div>
 <br>
 <br>
@@ -48,7 +48,7 @@ Ver 1.0.2
 <br>
  
 <div  style="text-align: center;font-size: 30px;">
-二〇二四年十二月
+二〇二五年二月
 </div>
  
 <br>
@@ -67,7 +67,8 @@ Ver 1.0.2
 | 文档版本 | 日期 | 作者 | 版本说明 |
 |---|---|---|---|
 |1.0.1| 2024年10月22日|刘琴|1.  初始版|
-|1.0.2| 2024年12月27日|刘琴|1. 增加测验题中自判题题型<br>2. 多科测验的科目数量为从9增加至11<br>3. 增加测验自定义题型标题下发和清除<br>4. 增加自定义tag，可自定义最长128位的数据包标签<br><font color=red>注：(基站版本需高于0.0.8)</font>|
+|1.0.2| 2024年12月27日|刘琴|1. 增加测验题和多科测验中自判题题型<br>2. 多科测验的科目数量为从9增加至11<br>3. 增加测验自定义题型标题下发和清除<br>4. 可自定义最长128位的数据包标签<br><font color=red>注：(基站固件版本需不低于0.0.9)</font>|
+|1.0.3| 2025年2月20日|刘琴|1. 增加英文题和短消息题型<br>2. 增加键盘在线列表读取<br>3. 增加遥控器事件上报 <br><font color=red>注：(基站固件版本需不低于0.0.10)</font>|
  
 <br>
 <br>
@@ -117,7 +118,6 @@ Ver 1.0.2
   {
     "fun":"xxx", 
     "dataTag":"xxx", 
-    "tag":"",  //此字段非必需
     "data":{    
        //内容
     }
@@ -127,8 +127,7 @@ Ver 1.0.2
 |参数	|说明	|约束|
 |---|---|---|
 |fun|	指令或事件名称||
-|dataTag|	数据标签，用于对应收发数据|长度不超过4个字符，可为字母数字的组合，区分大小写|
-|tag|	自定义标签|长度不超过128个字符，可以为字母数字下划线"_"的组合,区分大小写,非必填，可不传本字段|
+|dataTag|	数据标签，用于对应收发数据|长度不超过128个字符，可以为字母数字下划线"_"的组合，区分大小写|
 |data|	数据内容|对象或者数组，可为空|
  
 <font color="red">注意：基站接收指令数据单次不超过2K长度，在指定键盘发送指令时，如果指令长度超出限制，建议将指令进行拆分，分次发送，如果是所有键盘执行的指令，可将keySns设为空数组不使用指定键盘的模式</font>
@@ -150,8 +149,10 @@ Ver 1.0.2
 |公共事件|基站信道冲突|-|[sEvtBsChannelConflict](#sevtbschannelconflict)|
 |公共事件|键盘上线通知|-|[sEvtBsKpOnlineMsg](#sevtbskponlinemsg)|
 |公共事件|键盘刷卡事件|-|[sEvtBsNfcResults](#sevtbsnfcresults)|
+|公共事件|在线键盘列表|-|[sEvtBsKpOnlineList](#sevtbskponlinelist)|
 |公共事件|键盘待机实时按键反馈|-|[sEvtKpRtFeedback](#sevtkprtfeedback)|
 |公共事件|键盘举手键实时按键反馈|-|[sEvtKpHandUp](#sevtkphandup)|
+|公共事件|遥控器实时按键反馈|-|[sEvtKpRemoteControl](#sevtkpremotecontrol)|
  
 ### 基站管理
 |功能归类|功能|API指令|指令/系统事件|
@@ -187,6 +188,8 @@ Ver 1.0.2
 ||设置状态语工作状态|[setBsKpStbMsgMode](#setbskpstbmsgmode)|[fEvtBsKpStbMsgMode](#fevtbskpstbmsgmode)|||
 |键盘统一设置 - 登录菜单|获取键盘登录菜单状态|[getBsKpLoginMenu](#getbskploginmenu)|[fEvtBsKpLoginMenu](#fevtbskploginmenu)|
 ||设置键盘登录菜单状态|[setBsKpLoginMenu](#setbskploginmenu)|[fEvtBsKpLoginMenu](#fevtbskploginmenu)|||
+|键盘统一设置 - 长距考勤|获取键盘长距考勤状态|[getBsKpRFIDState](#getbskprfidstate)|[fEvtBsKpRFIDState](#fevtbskprfidstate)|
+||设置键盘长距考勤状态|[setBsKpRFIDState](#setbskprfidstate)|[fEvtBsKpRFIDState](#fevtbskprfidstate)|
 |键盘统一设置 - 键盘休眠|<font color="red">设置键盘休眠等级(内)</font>|[setBsKpSleepLevel](#setbskpsleeplevel)|[fEvtBsKpSleepLevel](#fevtbskpsleeplevel)|
 ||<font color="red">获取键盘休眠等级(内)</font>|[getBsKpSleepLevel](#getbskpsleeplevel)|[fEvtBsKpSleepLevel](#fevtbskpsleeplevel)|
 ||<font color="red">设置键盘暂停休眠状态(内)</font>|[setBsKpPauseSleep](#setbskppausesleep)|[fEvtBsKpPauseSleep](#fevtbskppausesleep)|
@@ -222,6 +225,7 @@ Ver 1.0.2
 |交互设置 - 用户实时提示反馈信息|实时设置提示反馈信息|[rtSetKpUserPrompt](#rtsetkpuserprompt)|[sEvtStateCode](#sevtstatecode)<br>[fEvtSetKpUserPrompt](#fevtsetkpuserprompt)|
 |在线状态获取|开启扫描在线键盘|[startGetKpOnline](#startgetkponline)|[sEvtStateCode](#sevtstatecode)<br>[fEvtKpOnlineMsg](#fevtkponlinemsg)|
 ||停止扫描在线键盘|[stopGetKpOnline](#stopgetkponline)|[sEvtStateCode](#sevtstatecode)|
+||实时获取在线键盘列表|[rtGetKpOnlineList](#rtgetkponlinelist)|[sEvtBsKpOnlineList](#sevtbskponlinelist)|
 |维护功能 - 遥控功能|遥控键盘休眠|[remoteKpSleep](#remotekpsleep)|[sEvtStateCode](#sevtstatecode)|
 |维护功能 - 键盘升级|<font color="red">启动键盘无线升级(内)|[startKpFWUpdate](#startkpfwupdate)|[sEvtStateCode](#sevtstatecode)<br>[fEvtKpFWUpdateState](#fevtkpfwupdatestate)<br>[fEvtKpUpdateProgress](#fevtkpupdateprogress)<br>[sEvtBsKpOnlineMsg](#sevtbskponlinemsg)|
 ||<font color="red">停止键盘无线升级(内)|[stopKpFWUpdate](#stopkpfwupdate)|[sEvtStateCode](#sevtstatecode)<br>[fEvtKpFWUpdateState](#fevtkpfwupdatestate)|
@@ -249,6 +253,9 @@ Ver 1.0.2
 ||停止数字题答题|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)|
 |抢答题|启动抢答题答题|[startQAQuicker](#startqaquicker)|[sEvtStateCode](#sevtstatecode)<br>[fEvtQAQuicker](#fevtqaquicker)|
 ||停止抢答题答题|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)|
+|英文题|启动英文题答题|[startQAEText](#startqaetext)|[sEvtStateCode](#sevtstatecode)<br>[fEvtQAEText](#fevtqaetext)|
+||停止英文题答题|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)|
+|短消息|发送短消息|[sendKpMsg](#sendkpmsg)|[sEvtStateCode](#sevtstatecode)<br>[fEvtKpMsg](#fevtkpmsg)|
 |待机实时反馈|设置待机实时反馈状态|[setKpStbResponse](#setkpstbresponse)|[fEvtKpStbResponse](#fevtkpstbresponse)<br>[sEvtKpRtFeedback](#sevtkprtfeedback)<br>[sEvtKpHandUp](#sevtkphandup)|
 ||获取待机实时反馈状态|[getKpStbResponse](#getkpstbresponse)|[fEvtKpStbResponse](#fevtkpstbresponse)|
 ### 在线测验
@@ -397,6 +404,39 @@ Ver 1.0.2
     }
 }
 ```
+### sEvtBsKpOnlineList
+- **主题**: /basestation/{baseSN}/receive
+- **功能描述**：键盘在线列表发生变化时主动上报
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|事件名称|
+|dataTag|string|-|否|数据包标识|
+|data|array|-|是|传送参数的对象数组|
+|++keySn|string||是|键盘SN|
+|++version|string||是|键盘固件版本|
+|++model|int||是|键盘型号|
+|++voltage|double||是|键盘电压|
+
+- **示例代码**
+```json
+{
+    "fun":"sEvtBsKpOnlineList",
+    "dataTag":"1",
+    "data":[{ 
+        "keySn":"1234567890",
+        "version":"1.0.0",
+        "model":67,
+        "voltage":2.8
+    },{ 
+        "keySn":"1234567891",
+        "version":"1.0.0",
+        "model":67,
+        "voltage":2.8
+    }]
+}
+```
 ### sEvtKpRtFeedback
 - **主题**: /basestation/{baseSN}/receive
 - **功能描述**：开启键盘实时反馈后，键盘按键时上报
@@ -447,6 +487,30 @@ Ver 1.0.2
     }
 }
 ```
+### sEvtKpRemoteControl
+- **主题**: /basestation/{baseSN}/receive
+- **功能描述**：遥控器按键实时上报
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|事件名称|
+|dataTag|string|-|否|数据包标识|
+|data|object|-|是|传送参数的对象|
+|+keySn|string||是|遥控器SN|
+|+keyValue|string||是|遥控器提交的按键值，按键值含义参见遥控器说明|
+
+- **示例代码**
+```json
+{
+    "fun":"sEvtKpRemoteControl",
+    "dataTag":"1",
+    "data":{ 
+        "keySn":"1234567890",
+        "keyValue":"1"
+    }
+}
+```
 ### sEvtStateCode
 - **主题**: /basestation/{baseSN}/receive
 - **功能描述**：返回基站接收指令状态信息
@@ -1001,7 +1065,7 @@ Ver 1.0.2
     "fun":"fEvtBsPairCode",
     "dataTag":"1",
     "data":{        
-        "value":"123456"
+        "value":"12345678"
     }
 }
 ```
@@ -1401,6 +1465,47 @@ Ver 1.0.2
   }
 }
 ```
+
+##### getBsKpRFIDState
+- **主题**：/client/{baseSN}/send
+- **功能描述**：获取键盘长距离考勤开启状态
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+
+- **示例代码**
+```json
+{
+  "fun":"getBsKpRFIDState",
+  "dataTag":"1"
+}
+```
+##### setBsKpRFIDState
+- **主题**：/client/{baseSN}/send
+- **功能描述**：设置键盘长距离考勤开启状态
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|data|object|-|是|传送参数的对象|
+|+value|string||是|设置键盘长距离考勤开启状态<br>0-不开启<br>1-开启|
+
+- **示例代码**
+```json
+{
+  "fun":"setBsKpRFIDState",
+  "dataTag":"1",
+  "data":{
+    "value":"1"
+  }
+}
+```
+
 ##### getBsKpSleepLevel
 - **主题**：<sapn class="yellowFill">/manage/{baseSN}/send</span>
 - **功能描述**：获取键盘休眠时间等级
@@ -1550,6 +1655,30 @@ Ver 1.0.2
   }
 }
 ```
+
+##### fEvtBsKpRFIDState
+- **主题**: /basestation/{baseSN}/receive
+- **功能描述**：返回键盘长距离考勤开启状态
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|data|object|-|是|传送参数的对象|
+|+value|string||是|返回键盘长距离考勤开启状态<br>0-不开启<br>1-开启|
+
+- **示例代码**
+```json
+{
+  "fun":"fEvtBsKpRFIDState",
+  "dataTag":"1",
+  "data":{
+    "value":"0"
+  }
+}
+```
+
 ##### fEvtBsKpSleepLevel
 - **主题**: <sapn class="yellowFill">/manage/{baseSN}/receive</span>
 - **功能描述**：返回键盘休眠时间等级
@@ -2745,10 +2874,33 @@ Ver 1.0.2
   "dataTag":"1"
 }
 ```
+
+##### rtGetKpOnlineList
+- **主题**：/client/{baseSN}/send
+- **功能描述**：实时获取基站存储的键盘在线列表
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+
+- **示例代码**
+
+```json
+{
+  "fun":"rtGetKpOnlineList",
+  "dataTag":"1"
+}
+```
+
 #### 事件
 ##### [sEvtStateCode](#sevtstatecode)
 发送指令后返回此事件
  
+##### [sEvtBsKpOnlineList](#sevtbskponlinelist)
+实时获取基站存储的键盘在线列表时返回此事件
+
 ##### fEvtKpOnlineMsg
 - **主题**: /basestation/{baseSN}/receive
 - **功能描述**：主动获取在线键盘时，在线键盘状态报告
@@ -3332,7 +3484,7 @@ Ver 1.0.2
 |dataTag|string|-|否|数据包标识,可为空字符串|
 |data|object|-|是|传送参数的对象|
 |+keySns|array||是|指定的键盘SN数组，空数组表示全部在线键盘|
-|+count|int||是|题目数量，1-16，>1多题快答<br>optionalN >1时无效|
+|+count|int||是|题目数量，1-16，>1多题快答<br><font color="red">注意：多题快答只适用于单选题，count>1时optionalN 默认为1，且options需 >1，显示模式mode默认为1</font>|
 |+mode|int||是|显示模式<br>1:显示字母(默认值) </br>2:显示数字 |
 |+lessMode|int||是|迫选模式<br>0:可缺选(默认值) </br>1:不可缺选</br>2:允许重复输入</br>3:允许重复输入且不可缺选 |
 |+options|int||是|选项数量，1≤M≤10(默认值4)|
@@ -3603,6 +3755,182 @@ Ver 1.0.2
     }]
 }
 ```
+### 英文题
+#### 方法
+##### startQAEText
+- **主题**：/client/{baseSN}/send
+- **功能描述**：启动英文题答题
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|data|object|-|是|传送参数的对象|
+|+keySns|array||是|指定的键盘SN数组，空数组表示全部在线键盘|
+|+mode|int||是|模式<br>0:自由输入|
+|+allowModify|int||是|修改模式<br>0 - 不允许修改<br>1 - 允许修改|
+|+tip|string||否|提示的标题，长度不超过16字符|
+|+simParams|object||否|内部模拟测试参数设置对象|
+|++answer|string||是|预设提交的按键值|
+
+- **示例代码**
+```json
+{
+  "fun":"startQAEText",
+  "dataTag":"1",
+  "data":{
+    "keySns":[],
+    "mode": 0,
+    "allowModify":1,
+    "tip":"请输入英文文本",
+    "simParams":{
+      "answer":"AAAAAAA"
+    }
+  }
+}
+```
+<!--##### stopQAEText
+- **主题**：/client/{baseSN}/send
+- **功能描述**：停止英文题答题
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+
+- **示例代码**
+```json
+{
+  "fun":"stopQAEText",
+  "dataTag":"1"
+}
+```-->
+
+##### [stopKpVote](#stopkpvote)
+停止英文题答题
+
+#### 事件
+##### [sEvtStateCode](#sevtstatecode)
+发送指令后返回接收状态
+
+##### fEvtQAEText
+- **主题**：/basestation/{baseSN}/receive
+- **功能描述**：返回键盘提交答题信息
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|data|array|-|是|传送参数的对象数组|
+|++keySn|string||是|键盘SN|
+|++keyValue|string||是|键盘提交的按键值|
+|++keyTime|double||是|答题时间，从启动开始计算，单位秒|
+
+- **示例代码**
+```json
+{
+  "fun":"fEvtQAEText",
+  "dataTag":"1",
+  "data": [{
+      "keySn": "1234567890",
+      "keyValue":"hello",
+      "keyTime":3.2
+    }]
+}
+```
+
+### 短信息
+#### 方法
+##### sendKpMsg
+- **主题**：/client/{baseSN}/send
+- **功能描述**：指定键盘发送短信息
+- **参数说明**
+
+|参数名|类型|限制|是否必填|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|data|array|-|是|传送参数的对象数组，不可为空|
+|++keySn|string||是|需要设置绑定信息的键盘SN<br>空字符串且只有一条信息时代表群发所有在线键盘|
+|++month|int||是|月份，范围1-12|
+|++day|int||是|日期,范围1-31|
+|++info|string||是|信息内容|
+
+- **示例代码**
+```json
+//指定键盘发送信息
+{
+  "fun":"sendKpMsg",
+  "dataTag":"1",
+  "data": [
+    {
+      "keySn": "1479824643",
+      "month":6,
+      "day":10,
+      "info": "短信息1"
+    },
+    {
+      "keySn": "1479824644",
+      "month":6,
+      "day":10,
+      "info": "短信息2"
+    }
+  ]
+}
+
+//广播信息
+{
+  "fun":"sendKpMsg",
+  "dataTag":"1",
+  "data": [
+    {
+      "keySn": "",
+      "month":6,
+      "day":10,
+      "info": "广播信息"
+    }
+  ]
+}
+```
+
+#### 事件
+##### [sEvtStateCode](#sevtstatecode)
+发送指令后返回接收状态
+
+##### fEvtKpMsg
+- **主题**：/basestation/{baseSN}/receive
+- **功能描述**：返回短信息是否成功发送至键盘
+- **参数说明**
+
+|参数名|类型|限制|非空|说明|
+|---|---|---|---|---|
+|fun|string|-|是|指令名称|
+|dataTag|string|-|否|数据包标识,可为空字符串|
+|data|array|-|否|传送参数的对象数组|
+|++keySn|string||是|键盘SN|
+|++state|string||是|短信息是否成功发送<br>0 - 成功<br>1 - 失败|
+
+- **示例代码**
+```json
+{
+  "fun":"fEvtKpMsg",
+  "dataTag":"1",
+  "data": [
+    {
+      "keySn": "1479824643",
+      "state": "0"
+    },
+    {
+      "keySn": "1479824644",
+      "state": "1"
+    }
+  ]
+}
+```
+
 ### 待机实时反馈
 #### 方法
 ##### setKpStbResponse
@@ -4309,7 +4637,7 @@ Ver 1.0.2
 |dataTag|string|-|否|数据包标识,可为空字符串|
 |data|object|-|是|传送参数的对象数组，不可为空|
 |+keySns|array||是|需要设置标题的键盘SN数组，为空代表全部在线键盘<br><font color="red">注意：指定键盘下发才有单个键盘下发是否成功的事件，全部在线键盘下发只有统一回复事件</font>|
-|+type|int||是|需要设置的题目类型<br>1-单选题<br>2-多选题<br>3-数字题<br>4-判断题<br>5-对错题(自判题)|
+|+type|int||是|需要设置的题目类型<br>1-单选题<br>2-多选题<br>3-数字题<br>4-判断题<br>5-自判题|
 |+title|string||是|设置的标题内容，长度不大于15个字符|
  
  
@@ -4369,7 +4697,7 @@ Ver 1.0.2
  
 ##### fEvtKpExamQuesTitle
 - **主题**：/basestation/{baseSN}/receive
-- **功能描述**：返回键盘实时设置绑定信息的状态是否成功
+- **功能描述**：返回键盘设置自定义题型标题的状态是否成功
 - **参数说明**
  
 |参数名|类型|限制|非空|说明|