1.MQTT应用部分首次上传。

DMchen
1 parent 197ddbbf
Showing 1 changed file with 58 additions and 90 deletions
通讯协议-MQTT应用部分[内部].md
@@ -3,12 +3,12 @@
 <br>
  
 <div  style="text-align: center;font-size: 70px;">
-WSCmdApp协议接口说明
+MQTT协议接口说明
 </div>
  
  
 <div  style="text-align: center;font-size: 30px;">
-Ver5.1.6
+Ver1.1.0
 </div>
 <br>
 <br>
@@ -24,7 +24,7 @@ Ver5.1.6
 <br>
  
 <div  style="text-align: center;font-size: 30px;">
-二〇二三年十月
+二〇二四年三月
 </div>
  
 <br>
@@ -34,132 +34,100 @@ Ver5.1.6
  
 文件控制：
  
-文件名：WSCmdApp接口说明
+文件名：MQTT接口说明
  
-起草人：陈定敏
+起草人：
  
-最新版本作者： 陈定敏
+最新版本作者： 
 <br>
 <br>
 | 文档版本 | 日期 | 作者 | 版本说明 |
 |---|---|---|---|
-|5.1.1| 2023年10月09日|陈定敏|1.  初始版|
-|5.1.2| 2023年11月07日|陈定敏|1.  增加配对模式设置接口|
-|5.1.3| 2023年11月15日|陈定敏|1.  更新语音题接口参数|
-|5.1.5| 2023年12月28日|陈定敏|1.  增加Json指令支持基站id和基站SN两种模式|
-|5.1.6| 2024年02月19日|陈定敏|1.  增加keypadRemoteControl接口<br>2.  增加举手功能接口|
+|5.1.1| 2024年03月27日|软件组|1.  初始版|
+
  
 <br>
  
 [TOC]
  
-# 系统概述
-
-WSCmdApp
-无线反馈系统是由手持的键盘、通讯基站、WSCmdApp（控制台程序）、控制电脑组成的。控制电脑通过USB接口与基站连接。控制指令由控制电脑通过基站发送给键盘。
-
-WSCmdApp可以让用户开发的应用程序与WSCmdApp无线反馈系统通讯。WSCmdApp控制台程序（下文用WSCmdApp代替）提供websocket通讯方式，使用JSON通信格式，来实现互动系统的管理及投票指令的发送和接收功能。调用结构图如下：![](img/image1.png)
-
-如果用户想开发互联网应用，可以参考如下设计：
+# 1. 前言
  
-![](img/image2.png)
+  
+## 1.1 背景
  
-目前WSCmdApp只支持Windows系统。用户只需运行WSCmdApp程序即可。
+方便客户基于C200K基站设备使用 通信基站数据接收及解析。
  
-WSCmdApp程序中config.ini配置文件中可设置WebSocket的端口，见以下位置：
+  
+## 1.2 编写目的
  
-![](img/image3.png)
+此说明书是为了说明协议内容，开发流程，方便基于此进行二次开发。
  
-config.ini 文件关键字解释说明：
-role： WSCmdApp当前WebSocket运行模式；client：客户端模式，server：服务端模式。
-ip: 需要访问的WebSocket服务器的ip地址，此参数在客户端模式下有效
-port: WebSocket通讯的端口地址
-heartBeatOnOf:心跳判定开关，此参数配合协议文档中的“心跳”指令使用。
-当参数配置为0: WSCmdApp会配合的回复对应参数，不进入心跳检测程序，
-当参数配置为1: WSCmdApp会配合的回复对应参数，进入心跳检测程序。
-heartbeat: 心跳间隔时长 范围：10-60 单位秒
-当heartBeatOnOff配置为1，并且WebSocket运行模式为客户端时，进入心跳检测程序后，在单位时间没有收到心跳指令，WebSocket客户端会重启，重新连接服务器。
-language：切换WSCmdApp使用的语言，0:简体中文 1:英文
-jsonBase：切换Json指令中使用基站ID还是基站SN， 0:基站ID生效，基站SN无效，1:基站SN生效，基站ID无效。
+ 
+##  1.3 读者对象
  
-# 设计目的
+1. 相关研发人员
+2. 方案制定人员
+3. 决策人员
  
-1、协议通过Websocket封装后将具有更好的扩展空间和跨应用使用能力，为平台应用开发提供数据通讯基础。
  
-2、应用程序（后续基于WSCmdApp开发的程序称为应用程序），基于业务发送指令到WSCmdApp，WSCmdApp收到指令后，完成对基站或键盘的操作后回复应用程序。
+# 2. 开发流程
  
-![](img/image4.png)
-
-# 通讯接口设计概要
-
-应用程序和WSCmdApp之间采用Json数据通信，通信的基本格式如下：
+C200K基站，采用MQTT协议进行开发，基站接入MQTT服务器，应用从MQTT服务器下发指令和接收数据
  
-关于baseId和baseSn的使用说明：二者使用切换可以在config.ini 文件的关键字jsonBase中切换，0:基站ID生效[baseId的值有效]，基站SN无效，1:基站SN生效[baseSn的值有效]，基站ID无效，baseSn是字符串数字类型,可以传递一个基站SN。
+整个交互图如下:
  
-下发：应用程序 -> WSCmdApp
+![](img/MQTT1.png)
  
-```json
-{
-	fun: "" // 功能定义
-	baseId: 1 // 基站id,数字类型
-	baseSn:"2023031402"	//基站SN，字符串
-	params： {} //参数对象/数组
-	packetTag: "" //数据包标签字符串
-}
-```
+  
+## 2.1 MQTT服务器准备
  
-fun 为功能对应的名称 如："readBaseStationID" 读取基站的id,"startChoices" //开始选择题, "stopChoices" //停止选择题.
+MQTT服务器要求：
  
-baseId：基站ID，用来区分基站标志,参数范围1~32，基站对应的baseId 可以通过readConnectBase指令获取。[此参数请和config.ini 文件的关键字jsonBase的值配合使用]
-baseSn：基站SN列表，用来区分基站标志。[此参数请和config.ini 文件的关键字jsonBase的值配合使用]
-params：参数，功能相对于的参数，可以是数组或字段。
-packerTag:这个是扩展字段，内容需要应用程序管理，功能相应的反馈指令packerTag位置会反馈相同字符串，方便应用程序跟踪记录。
+能够正常收发MQTT数据。
  
-反馈：WSCmdApp-> 应用程序
+服务器的性能参数由业务决定。
  
-```json
-{
-	fun: "" //功能定义
-	baseId: 1 //基站id,数字类型
-	baseSn:"2023031402" //基站SN
-	infos: {} //信息对象/数组
-	packetTag: "" // 数据包标签字符串。
-}
-```
+域名：
  
-fun： 功能对应的名称,如:"BaseStationID"读取基站id, " answerChoices" //选择题键盘反馈值.
-baseId: 基站ID，用来区分基站标志；参数范围1~32，基站对应的baseId 可以通过readConnectBase指令获取。
-baseSn: 基站SN，用来区分基站标志。
-infos: WSCmdApp反馈给APP层的数据。具体详见具体功能定义。
-packetTag:这个是扩展字段，内容需要应用程序管理，反馈接收到的字符串。
+公网域名或ip或者基站所处局域网ip。
  
-字段值说明：
-反馈infos中的状态字段state，OK表示成功，FAIL表示失败。
-反馈infos中的硬件参数字段的值，FAIL表示失败，其他值为成功。
-X\~Y:范围内的值特指整数。
+MQTT服务器配置结果检查
  
-# 通信方式
-数据交互采取发送<-->应答的方式。应用程序发送数据到WSCmdApp，WSCmdApp收到后执行完成后回复。
+使用MQTT.FX客户端，配置域名，端口，用户名和密码信息，然后连接，如果提示连接成功，则表示MQTT服务器可用。基站client id 是基站编号。
  
-应用程序没有数据发送给WSCmdApp时，可通过向WSCmdApp发送心跳指令。
+![](img/MQTT2.png)
  
-WSCmdApp端被设置为Websocket 服务端模式时，应用程序可通过WSCmdApp回复的心跳来确认与WSCmdApp的连接状态。
+## 3.2 协议简介
  
-WSCmdApp端被设置为Websocket 客户端模式时， WSCmdApp将自动根据心跳判定开关及心跳参数的设置内容进行重连的自动判断。
+    
+### 3.2.1 MQTT
  
+关于MQTT说明，请参考 https://mqtt.org/
  
+${clinetId} clinetId 是基站编号，为替换字符串。
  
-# 编程流程说明
+      
+#### 3.2.1.1 应用程序发布的主题
  
-用户使用WSCmdApp编程的基本流程如下：
-配置参数：(可配置、详情见配置文件config.ini)
+| 主题 | 功能 |
+| --- | --- |
+| /client/${clientId}/operate | 基站的设置，查询等指令 |
+| /lesson/class/${clinetId}/receive | 接收答题的指令 |
  
-编程开发：
+      
+#### 3.2.1.2 应用程序订阅的主题
  
-1、使用websocket通讯，IP为IP地址
-2、启动WSCmdApp.exe（WSCmdApp）进程
-3、业务软件连接服务器后就可直接通信，通信的数据格式为JSON(UTF-8编码)。具体参数请看JSON指令说明部分。
-4、业务软件发送退出指令，WSCmdApp.exe（WSCmdApp）收到指令后退出。
+| 主题 | 功能 |
+| --- | --- |
+| /client/${clientId}/online | 基站上线通知。 |
+| /client/${clientId}/offline | 基站下线通知。 |
+| /client/${clientId}/card/online | 答题器上线通知。 |
+| /client/${clientId}/card/offline | 答题器离线通知。 |
+| /client/${clientId}/card/swipe | 答题器刷卡事件 |
+| /client/${clientId}/report | 基站主动上报状态，或者对设置指令的回应。 |
+| /lesson/class/${clinetId}/send | 基站对答题/签到数据的反馈 |
+| /client/${clientId}/card/fingerprint | 指纹事件 |
+| /client/${clientId}/error | 基站错误信息上报 |
  
 # JSON指令说明