From 61e3db5c3f1203fcb5a2f92cd4ef3668d83d18e5 Mon Sep 17 00:00:00 2001 From: liuqin Date: Thu, 4 Sep 2025 11:39:25 +0800 Subject: [PATCH] 1. 增加白名单模式下的键盘登录信息，用作上线信息的补充 2. 增加答题反馈事件中的时间戳返回 3. 修改拍照反馈及返回事件的接口参数 --- 通讯协议-平台化-应用部分[内部].md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------ 1 file changed, 75 insertions(+), 48 deletions(-) diff --git a/通讯协议-平台化-应用部分[内部].md b/通讯协议-平台化-应用部分[内部].md index 6c1d7ba..5d8d859 100644 --- a/通讯协议-平台化-应用部分[内部].md +++ b/通讯协议-平台化-应用部分[内部].md @@ -32,7 +32,7 @@ SunVote 二次开发
通讯协议

-Ver 1.0.11 +Ver 1.0.12


@@ -48,7 +48,7 @@ Ver 1.0.11
-二〇二五年七月 +二〇二五年九月

@@ -78,6 +78,7 @@ Ver 1.0.11 |1.0.9| 2025年7月17日|刘琴|1. 基站自检项增加字库检测
2. 键盘扫描指令增加键盘id返回
3. 修改设置键盘ID和返回事件为外部指令| |1.0.10| 2025年7月24日|刘琴|1. 增加写键盘OEM型号名称| |1.0.11| 2025年7月30日|刘琴|1. 增加表决功能(暂只有三键表决)| +|1.0.12| 2025年9月4日|刘琴|1. 增加白名单模式下的键盘登录信息，用作上线信息的补充
2. 增加答题反馈事件中的时间戳返回
3. 修改拍照反馈及返回事件的接口参数|

@@ -173,6 +174,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |公共事件|基站连接状态变化|-|[sEvtBsConnectState](#sevtbsconnectstate)| |公共事件|基站信道冲突|-|[sEvtBsChannelConflict](#sevtbschannelconflict)| |公共事件|键盘上线通知|-|[sEvtBsKpOnlineMsg](#sevtbskponlinemsg)| +|公共事件|键盘登入通知|-|[sEvtBsKpLoginMsg](#sevtbskploginmsg)| |公共事件|键盘离线通知|-|[sEvtBsKpOfflineMsg](#sevtbskpofflinemsg)| |公共事件|键盘刷卡事件|-|[sEvtBsNfcResults](#sevtbsnfcresults)| |公共事件|在线键盘列表|-|[sEvtBsKpOnlineList](#sevtbskponlinelist)| @@ -317,17 +319,16 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 ### 拍照反馈 |功能归类|功能|API指令|指令事件| |---|---|---|---| -|拍照反馈-单题拍照反馈|启动单题拍照反馈|[startQAPhoto](#startqaphoto)|[sEvtStateCode](#sevtstatecode)
[fEvtPhotoFile](#fEvtphotofile)| -||停止单题拍照反馈|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)| +|拍照反馈|启动拍照反馈|[startQAPhoto](#startqaphoto)|[sEvtStateCode](#sevtstatecode)
[fEvtPhotoFile](#fEvtphotofile)| +||停止拍照反馈|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)| ### 在线测验 |功能归类|功能|API指令|指令事件| |---|---|---|---| -|标准测验|启动标准测验|[startKpExam](#startkpexam)|[sEvtStateCode](#sevtstatecode)
[fEvtKpExam](#fevtkpexam)
[fEvtFinalSubmit](#fevtfinalsubmit)| +|标准测验|启动标准测验|[startKpExam](#startkpexam)|[sEvtStateCode](#sevtstatecode)
[fEvtKpExam](#fevtkpexam)| ||停止标准测验|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)| -||允许键盘提交后退回修改|[rtAllowEdited](#rtkpallowedited)|[sEvtStateCode](#sevtstatecode)
[fEvtFinalSubmit](#fevtfinalsubmit)| -|多科测验|启动多科测验|[startKpMultiExam](#startkpmultiexam)|[sEvtStateCode](#sevtstatecode)
[fEvtKpExam](#fevtkpexam)
[fEvtFinalSubmit](#fevtfinalsubmit)| -||停止标准测验|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)| -|自主录分|启动自主录分|[startKpScoreInput](#startkpscoreinput)|[sEvtStateCode](#sevtstatecode)
[fEvtKpScore](#fevtkpscore)
[fEvtFinalSubmit](#fevtfinalsubmit)| +|多科测验|启动多科测验|[startKpMultiExam](#startkpmultiexam)|[sEvtStateCode](#sevtstatecode)
[fEvtKpExam](#fevtkpexam)| +||停止多科测验|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)| +|自主录分|启动自主录分|[startKpScoreInput](#startkpscoreinput)|[sEvtStateCode](#sevtstatecode)
[fEvtKpScore](#fevtkpscore)| ||停止自主录分|[stopKpVote](#stopkpvote)|[sEvtStateCode](#sevtstatecode)| |自定义测验题型标题|自定义测验题型标题内容|[setKpExamQuesTitle](#setkpexamquestitle)|[sEvtStateCode](#sevtstatecode)
[fEvtKpExamQuesTitle](#fevtkpexamquestitle)| ||清除自定义测验题型标题内容|[clearKpExamQuesTitle](#clearkpexamquestitle)|[sEvtStateCode](#sevtstatecode)
[fEvtClearKpExamQuesTitle](#fevtclearkpexamquestitle)| @@ -607,6 +608,35 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 } ``` +### sEvtBsKpLoginMsg +- **主题**: /basestation/{baseSN}/receive +- **功能描述**：键盘登入的通知信息，用作上线信息的补充 +- **参数说明** + +|参数名|类型|限制|非空|说明| +|---|---|---|---|---| +|fun|string|-|是|事件名称| +|dataTag|string|-|否|数据包标识| +|baseSn|string||是|基站的出厂编码| +|data|object|-|是|传送参数的对象| +|+keySn|string||是|键盘SN| +|+version|string||是|键盘固件版本| +|+model|int||是|键盘型号| + +- **示例代码** +```json +{ + "fun":"sEvtBsKpLoginMsg", + "dataTag":"1", + "baseSn":"2024061101", + "data":{ + "keySn":"1234567890", + "version":"1.0.0", + "model":67 + } +} +``` + ### sEvtBsKpOfflineMsg - **主题**: /basestation/{baseSN}/receive - **功能描述**：单个键盘离线通知，主动上报 @@ -3515,7 +3545,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |baseSn|string||是|基站的出厂编码| |data|object|-|是|传送参数的对象| |+keySns|array||否|需要执行指令的键盘SN数组，空数组表示所有键盘| -|+value|string||是|OEM定制型号名称，不超过16个字符| +|+value|string||是|OEM定制型号名称，不超过11个字符| - **示例代码** ```json @@ -3795,7 +3825,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |dataTag|string|-|否|数据包标识,可为空字符串| |baseSn|string||是|基站的出厂编码| |data|object|-|是|传送参数的对象数组| -|+keySns|array||否|需要清除分数的键盘SN数组
空数组表示清空所有键盘| +|+keySns|array||否|需要清除分数的键盘SN数组| - **示例代码** @@ -4791,6 +4821,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -4901,6 +4932,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -4984,6 +5016,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -5064,6 +5097,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -5137,6 +5171,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -5206,6 +5241,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keySn|string||是|键盘SN| |++keyValue|string||是|键盘提交的按键值| |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** ```json @@ -5354,7 +5390,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 ``` ##### [stopKpVote](#stopkpvote) -停止判断题答题 +停止表决 #### 事件 ##### [sEvtStateCode](#sevtstatecode) @@ -5376,6 +5412,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -5661,7 +5698,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 ## 拍照反馈 ### 方法 -#### 单题拍照反馈 +#### 拍照反馈 ##### startQAPhoto - **主题**：/client/{baseSN}/send - **功能描述**：启动单题拍照反馈 @@ -5674,6 +5711,10 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |baseSn|string||是|基站的出厂编码| |data|object|-|是|传送参数的对象| |+keySns|array||是|指定的键盘SN数组，空数组表示全部在线键盘| +|+tip|string||否|提示的标题，长度不超过16字符| +|+questions|array||是|需要提交照片列表, 最多9张照片| +|++index|int||是|照片的序号，1-9| +|++info|string||否|拍照的描述，如第10题-阅读理解，长度不超过20个字符| - **示例代码** ```json @@ -5682,7 +5723,21 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 "dataTag":"1", "baseSn":"2024061101", "data": { - "keySns": [] + "keySns": [], + "tip": "请拍照提交", + "questions": [{ + "index":1, + "info":"试卷1-A面左侧" + }, { + "index":2, + "info":"试卷1-A面右侧" + }, { + "index":3, + "info":"试卷1-B面左侧" + }, { + "index":4, + "info":"试卷1-B面右侧" + }] } } ``` @@ -5706,6 +5761,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |baseSn|string||是|基站的出厂编码| |data|array|-|是|传送参数的对象数组| |++keySn|string||是|键盘SN| +|++index|int||是|提交的照片序号,对应启动的题目列表中的index| |++filePath|string||是|键盘提交图片文件的路径| - **示例代码** @@ -5716,6 +5772,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 "baseSn":"2024061101", "data": [{ "keySn": "1479824643", + "index": 1, "filePath":"D:\\SunVoteSDK\\photo\\20250502\\photo_1479824643_1635832534000.jpg" }] } @@ -5971,6 +6028,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|答题时间，从启动开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** @@ -5992,35 +6050,6 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 ] } ``` -##### fEvtFinalSubmit -- **主题**：/basestation/{baseSN}/receive -- **功能描述**：返回键盘手动交卷标识 -- **参数说明** - -|参数名|类型|限制|非空|说明| -|---|---|---|---|---| -|fun|string|-|是|指令名称| -|dataTag|string|-|否|数据包标识,可为空字符串| -|baseSn|string||是|基站的出厂编码| -|data|array|-|是|传送参数的对象数组| -|++keySn|string||是|键盘SN| -|++keyValue|string||是|0 - 未提交(提交完成后，允许键盘修改答案时上报)
1 - 已交卷| -|++keyTime|double||是|提交时间，从启动开始计算，单位毫秒| - -- **示例代码** - -```json -{ - "fun":"fEvtFinalSubmit", - "dataTag":"1", - "baseSn":"2024061101", - "data": [{ - "keySn": "1234567890", - "keyValue":"1", - "keyTime":3200 - }] -} -``` ### 多科测验 #### 方法 @@ -6132,9 +6161,6 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 ##### [fEvtKpExam](#fevtkpexam) 返回测验中键盘提交答题数据 -##### [fEvtFinalSubmit](#fevtfinalsubmit) -返回键盘手动交卷标识 - ### 自主录分 #### 方法 ##### startKpScoreInput @@ -6205,6 +6231,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 |++keyTime|double||是|录分时间，从启动录分开始计算，单位毫秒| |++voltage|double||是|键盘电量| |++retryCount|int||是|键盘提交数据的重发次数| +|++timeStamp|long ||是|键盘提交数据至基站的时间戳| - **示例代码** ```json @@ -6230,7 +6257,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 #### 方法 ##### setKpExamQuesTitle - **主题**：/client/{baseSN}/send -- **功能描述**：设置自定义测验题题型标题，键盘需在线才能接收成功。
设置完成后启动测验，对应的题型显示为设置的自定义标题。
题型标题相对固定，下发成功后键盘会保存标题，标题无变化时无需重复下发 +- **功能描述**：设置自定义测验题题型标题，键盘需在线才能接收成功。
设置完成后启动测验，对应的题型显示为设置的自定义标题。
题型标题相对固定，下发成功后键盘会保存标题，标题无变化时无需重复下发。
如果没有指定键盘进行下发，基站需要一段时间进行下发的操作，强烈建议将下发操作提前完成，以免影响正常的答题流程。 - **参数说明** |参数名|类型|限制|是否必填|说明| @@ -6378,7 +6405,7 @@ WebSocket方式应用与SDK建立长连接后，通过WebSocket接口发送接 #### 方法 ##### setKpExamSubject - **主题**：/client/{baseSN}/send -- **功能描述**：设置自定义科目名称，键盘需在线才能接收成功。
设置完成后启动多科测验，对应的科目显示为设置的自定义科目名称。
科目名称相对固定，下发成功后键盘会保存科目名称，无变化时无需重复下发 +- **功能描述**：设置自定义科目名称，键盘需在线才能接收成功。
设置完成后启动多科测验，对应的科目显示为设置的自定义科目名称。
科目名称相对固定，下发成功后键盘会保存科目名称，无变化时无需重复下发。
如果没有指定键盘进行下发，基站需要一段时间进行下发的操作，强烈建议将下发操作提前完成，以免影响正常的答题流程。 - **参数说明** |参数名|类型|限制|是否必填|说明| -- libgit2 0.21.4