From c6615f029eb5f43b5333c5b815127f7e52e979ea Mon Sep 17 00:00:00 2001 From: anlicheng Date: Fri, 18 Aug 2023 15:17:00 +0800 Subject: [PATCH] fix docs --- docs/R.md | 2 - docs/host-mqtt-jiaohu.md | 315 --------------------------------------- docs/host_mocker.html | 31 ---- docs/publish_command.md | 76 ++++++++++ docs/websocket.md | 127 ++++++++++++++-- 5 files changed, 187 insertions(+), 364 deletions(-) delete mode 100644 docs/R.md delete mode 100644 docs/host-mqtt-jiaohu.md delete mode 100644 docs/host_mocker.html create mode 100644 docs/publish_command.md diff --git a/docs/R.md b/docs/R.md deleted file mode 100644 index 32a21ae..0000000 --- a/docs/R.md +++ /dev/null @@ -1,2 +0,0 @@ -## -here diff --git a/docs/host-mqtt-jiaohu.md b/docs/host-mqtt-jiaohu.md deleted file mode 100644 index 00d8903..0000000 --- a/docs/host-mqtt-jiaohu.md +++ /dev/null @@ -1,315 +0,0 @@ -# 交互流程数据格式说明 - -## 主题说明 - -### system/upstream qos = 1 - 用于主机注册到平台 - -### host/upstream/$uuid qos = 1 - 用于主机向平台汇报数据 -### host/downstream/$uuid qos = 2 - 用于平台向主机下发所有的指令信息 - -## 需要注意的点 - 1. 主机的uuid是采用主动发现的机制，因此host主机在启动时需要先subscribe主题: host/downstream/${uuid} - -## register主机注册会话 - -1. 请求: 设备端向主题`system/upstream`发送注册信息 - -```json -{ - "method": "register", - "params": { - "uuid": "$uuid", - "os_version": "系统版本", - } -} -``` - -2. 响应: `host/downstream/$uuid` - -t = 0 - -```json - { - "code": 0 | 1, // 0表示失败，1：表示成功 - // 内容 - "m": "$bytes" -} -``` - -## 主机授权消息格式 - -t = 8 - -```json - -// 数据采用明文传输，主机在收到通知后，需要通过create_session操作重新协商aes - -{ - "auth": true/false, // true表示授权，此时aes的值不为空；false表示取消授权 - "reply": { - "topic": "", // 主机端操作成功后需要回写的topic名称 - "assoc": "" // 关联的信息，回写的时候需要带上 - } -} - -// 回写的消息格式, 其中topic为: reply.topic的值; reply的值可能为空，当为空时，不需要回写 - -{ - "code": 0 | 1, // 0表示操作失败，1表示成功 - message: "", - assoc: "下发给你值" -} - -``` - -## 命令下发结构 -命令下发，用于服务端或者其他的系统，通过调用接口，向设备端发送消息，设备端会监听`host/downstream/$uuid`的消息。 -服务端在发送之前，应先用该客户端的aes密钥进行加密，将加密之后的二进制数据发送到该topic。 -TODO 命令下发是需要增加当前的时间戳，host主机用来协调任务的一致性 - -加密前的消息结构如下： -// 消息类型，目前支持四种消息类型: -// 1代表参数下发，就是向该设备端的微服务发送消息,该消息会辗转发送给微服务进行处理，比如，设置modbus微服务的波特率等消息 -// 2代表采集向下发，比如，设置某个设备短上的modbus微服务采集某个地址的数据 -// 3代表下发微服务文件。 -// 4代表下发数据流图，这个指令用于设置设备端上各个微服务之间的逐句流转。 - -占用数据项的第一个字节 - -"t": 1|2|3|4, - -```json -{ - // 针对不同的命令类型，这个字段里的`to`和`m`数据有所不同，具体在下面的小节描述 - // 任务id，服务端在下发数据的时候，需要生成一个唯一的uuid， - // 用于标识一个任务 - "t_id": "任务id", - // 表示发给哪个微服务，这里是服务的标识，即服务名称 - "to": "", - // 命令执行的超时时间，单位为秒 - "t": 10, - // 实际内容 - "m": "$bytes", -} - -``` - -下面介绍几种下发类型： - -### 参数下发的结构 -对于参数下发，下发内容中的m为一个`map[string]interface{}`结构，用于向某个微服务发送参数，具体参数内容由微服务的参数配置提供。 - -### 微服务的启动和停止 -微服务的启动和停止由内置服务`service-monitor`管理，所以，实际启动和停止，只需要给该服务发送参数就行，其他流程（返回的step和result等）保持一致。实际下发的结构为： - -```json -{ - // 针对不同的命令类型，这个字段里的`to`和`m`数据有所不同，具体在下面的小节描述 - // 任务id，服务端在下发数据的时候，需要生成一个唯一的uuid， - // 用于标识一个任务 - "t_id": "任务id", - // 表示发给哪个微服务，启动和停止，都是发给内置服务service-monitor - "to": "service-monitor", - // 命令执行的超时时间，单位为秒 - "t": 10, - // 实际内容 - "m": { - "service_name": "需要启动或者停止的服务名， ${name}${copy}-${version}的格式", - "action": "start|stop", - "command": "如果是start，则需要传递启动命令，启动命令由config.yaml配置文件的boot字段指定" - }, -} - -``` - -### 采集项下发的结构 -采集项下发时，下发内容中的m为一个`[]map[string]interface{}`结构的列表，每一个条目是一个采集项内容，具体采集向内容由微服务的采集项配置提供。 - -### 微服务下发的结构 -在微服务下发中，`to`字段会被忽略，可以填写空字符串，而m字段为json化之后的数据，json化之前结构如下： - -```json -{ - "f": "微服务名", - "v": "微服务版本" - "k": "微服务下载的token" - "md5": "微服务的md5值，用于验证下载完整性" - // ms表示是微服务，config表示配置文件，self表示efka的新版本 - "t": "ms|config|self" - // o代表oldversion，老版本，如果t为ms，且o不为空字符串， - // 则表示要升级微服务版本，老版本的内容会被删除和替换。 - "o": "old-version" -} -``` - -# 主机主动数据交互逻辑 - -## create_session主机注册会话 - -### 请求 - -上报类型标识: 0x01 -数据部分公钥明文("该客户端自己生成的公钥"), 该公钥用于与服务端交换aes密钥。 -采用的RSA 2048 PKCS1 - -### 响应(响应体整体部分采用了请求中的公钥，基于rsa加密) - -需要注意，这里的交互逻辑有变更(topic: host/downstream/$uuid) -1. 当主机未激活时，返回: #{<<"a">> => false, <<"aes">> => <<"">>}, -2. 当主机已经激活时，返回: #{<<"a">> => true, <<"aes">> => Aes} -3. 当主机超过一定的时间没有收到任何返回的时候，需要重试执行create_session操作 - -t = 10 - -```json -{ - "a": true/false, // 表示是授权还是拒绝授权 - "aes": "", // 如果a字段为true，表示服务端允许授权，该aes为一个加密字符串，以后的通信，服务端和设备端都使用该aes密钥进行加解密。 -} -``` - -## 数据上传结构 -设备端在采集到数据之后，会向topic为`host/upstream/$uuid`发送消息，消息格式如下： - -上报类型标识: 0x02 -数据部分为下面描述的json格式(aes加密) - -```json: -{ - "service_name": "从该设备端的哪个服务采集的数据", - // 如果为空，就表明是微服务产生的数据，如果有值，表示是设备产生的数据 - "device_id": $uuid 非设备产生的device_id为空 - "at": int, 精确到毫秒 - // 该微服务采集的数据，是一个包含map的列表类型，map的内容可以由微服务自己指定 - // 目前一般的格式是"metric-name": $value样式的数据 - "fields": [ - { - "name1": "test" - "name2": 124, - "name3": false, - - } - ], - // 微服务自身可以生成tag，用于微服务指定自己的一些性质，目前使用得不多，以后可以扩展， - // 是一个map[string]string类型的数据 - "tags": { - "tag1": "value1", - "tag2", "value2" - } - // todo 在insert数据到influxdb的时候需要增加service_name + host_uuid -} - -``` - -## ping结构 -ping结构会上传到topic为"host/upstream/$uuid", ping结构每隔20秒发送一次 - -上报类型标识: 0x03 -数据部分为下面描述的json格式(aes加密) - -```json -{ - // 硬件信息，目前有剩余内存，剩余磁盘和cpu负载 - // 剩余内存，单位为mb - - "memory": { - "total": 1024, // 内存数，mb - "used": "$int" // 剩余内存数 - }, - "disk": { - "total": 1024, // 硬盘容量GB - "used": "$int" // 剩余硬盘内容GB - }, - - "cpu_load": $float, // 浮点数 - "cpu_temperature": $float // 稳定信息 - "cpu_core": $int, - - "boot_time": 2000, // 启动时间 - "efka_version": "1.0.0", // 客户端版本 - "kernel_arch": "arm64", // 客户端硬件架构 - "province": "", // 所在省 - "city": "", // 所在市 - "adcode": 100, // 所在城市的编号 - "ips": [ - "ip地址1", - "ip地址2" - ], - // 接口信息 - "interfaces": [ - { - "status": 0|1, "接口状态，0离线，1在线" - "name": "接口名称", - "desc": "接口描述", - } - ] -} -``` - -## inform结构 -inform用于客户端主动通知服务端本地事情的发生，比如，自身的某个微服务下线了，就会发送一个inform信息给服务端。 topic: host/upstream/$uuid - -上报类型标识: 0x04 -数据部分为下面描述的json格式(aes加密) - -```json -{ - "at": $int64, - // 微服务信息 - "services": [{ - "scene_id": $int "场景的编号", - "name": "微服务名称", - "version": "微服务版本", - "version_copy": "微服务副本", - // 微服务是否在线，0表示离线，1表示在线 - "status": 0|1 - }] -} -``` - -## 命令下发步骤上报结构(feedback_step) -在任务下发之后，设备端会根据命令到哪个环节，进行步骤上报，上报的消息写入到topic为`host/upstream/$uuid` - -上报类型标识: 0x05 -数据部分为下面描述的json格式(aes加密) - -```json - { - "task_id": "任务的task id", - // sc为step code，具体地： - // 0代表该任务开始了，服务端创建该任务之后，是这个代码 - // 1代表任务被分发了，服务端向nats(mqtt)发送消息之后，是这个代码 - // 2代表任务被设备端接收到了 - // 3代表该任务已经被发送给微服务进行处理了 - // 4代表该任务已经被微服务收到了，微服务正在处理 - // 5代表任务已经完成，微服务已经处理完成。 - "code": $int -} -``` - -有了这个步骤，最后任务超时等情况，就可以知道任务卡在哪里。 - -## 命令下发结果上报结构(feedback_result) -任务在微服务处理完成之后，设备端会向服务端反馈任务执行的结果。该结果会写入`host/upstream/$uuid`，上报的结构如下： - -上报类型标识: 0x06 -数据部分为下面描述的json格式(aes加密) - -```json -{ - "task_id": "任务id", - // unix nano类型 - "time": $int, - // 返回的结果码，0代表成功，其他代表出错 - "code": $int, - "reason": "任务执行的结果", - "error": "错误消息，当c为非0时，这个字段会表示出错消息", - // 返回任务类型，1表示任务是微服务下发，0代表是命令下发 - "type": 0 | 1, -} -``` - - diff --git a/docs/host_mocker.html b/docs/host_mocker.html deleted file mode 100644 index 6edd5c8..0000000 --- a/docs/host_mocker.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - Title - - -
-

Hello World

-
- - - - - - \ No newline at end of file diff --git a/docs/publish_command.md b/docs/publish_command.md new file mode 100644 index 0000000..471f070 --- /dev/null +++ b/docs/publish_command.md @@ -0,0 +1,76 @@ +# 命令下发结构 + +## 1. 服务器端和边缘主机采用websocket协议通讯 + +## 2. 下发的数据格式如下 + <>, 其中 + + "t": 1|2|3|4, + Body: + + ```json + { + // 针对不同的命令类型，这个字段里的`to`和`m`数据有所不同，具体在下面的小节描述 + // 任务id，服务端在下发数据的时候，需要生成一个唯一的uuid， + // 用于标识一个任务 + "t_id": "任务id", + // 表示发给哪个微服务，这里是服务的标识，即服务名称 + "to": "", + // 命令执行的超时时间，单位为秒 + "t": 10, + // 实际内容 + "m": "$bytes", + } + ``` +## 3. 加密前的消息结构如下： + 消息类型，目前支持四种消息类型: + * 1代表参数下发，就是向该设备端的微服务发送消息,该消息会辗转发送给微服务进行处理，比如，设置modbus微服务的波特率等消息 + * 2代表采集向下发，比如，设置某个设备短上的modbus微服务采集某个地址的数据 + * 3代表下发微服务文件。 + * 4代表下发数据流图，这个指令用于设置设备端上各个微服务之间的逐句流转。 + +### 3.1 参数下发的结构 + 对于参数下发，下发内容中的m为一个`map[string]interface{}`结构，用于向某个微服务发送参数，具体参数内容由微服务的参数配置提供。 + +### 3.2 微服务的启动和停止 + 微服务的启动和停止由内置服务`service-monitor`管理，所以，实际启动和停止，只需要给该服务发送参数就行，其他流程（返回的step和result等）保持一致。实际下发的结构为： + + ```json + { + // 针对不同的命令类型，这个字段里的`to`和`m`数据有所不同，具体在下面的小节描述 + // 任务id，服务端在下发数据的时候，需要生成一个唯一的uuid， + // 用于标识一个任务 + "t_id": "任务id", + // 表示发给哪个微服务，启动和停止，都是发给内置服务service-monitor + "to": "service-monitor", + // 命令执行的超时时间，单位为秒 + "t": 10, + // 实际内容 + "m": { + "service_name": "需要启动或者停止的服务名， ${name}${copy}-${version}的格式", + "action": "start|stop", + "command": "如果是start，则需要传递启动命令，启动命令由config.yaml配置文件的boot字段指定" + } + } + + ``` + +### 3.3 采集项下发的结构 + 采集项下发时，下发内容中的m为一个`[]map[string]interface{}`结构的列表，每一个条目是一个采集项内容，具体采集向内容由微服务的采集项配置提供。 + +### 3.4 微服务下发的结构 + 在微服务下发中，`to`字段会被忽略，可以填写空字符串，而m字段为json化之后的数据，json化之前结构如下： + + ```json + { + "f": "微服务名", + "v": "微服务版本" + "k": "微服务下载的token" + "md5": "微服务的md5值，用于验证下载完整性" + // ms表示是微服务，config表示配置文件，self表示efka的新版本 + "t": "ms|config|self" + // o代表oldversion，老版本，如果t为ms，且o不为空字符串， + // 则表示要升级微服务版本，老版本的内容会被删除和替换。 + "o": "old-version" + } + ``` \ No newline at end of file diff --git a/docs/websocket.md b/docs/websocket.md index 2f2396a..8054dc9 100644 --- a/docs/websocket.md +++ b/docs/websocket.md @@ -42,30 +42,136 @@ Reply: {a: bool, aes: "服务器生成的aes的值"} <<0x01, PacketId:4, 0x02, Body:任意长度>> PacketId: 4字节整数, 值为0; +Body: + ```json: + { + "service_name": "从该设备端的哪个服务采集的数据", + // 如果为空，就表明是微服务产生的数据，如果有值，表示是设备产生的数据 + "device_id": $uuid 非设备产生的device_id为空 + "at": int, 精确到毫秒 + // 该微服务采集的数据，是一个包含map的列表类型，map的内容可以由微服务自己指定 + // 目前一般的格式是"metric-name": $value样式的数据 + "fields": [ + { + "key": "test" + "value": 124, + "unit": "U", + "type": "AI：遥测值，DI：遥信值，SOE：事件", + "timestamp": int + } + ], + // 微服务自身可以生成tag，用于微服务指定自己的一些性质，目前使用得不多，以后可以扩展， + // 是一个map[string]string类型的数据 + "tags": { + "tag1": "value1", + "tag2", "value2" + } + // todo 在insert数据到influxdb的时候需要增加service_name + host_uuid + } + + ``` ### ping数据上传(无响应) <<0x01, PacketId:4, 0x03, Body:任意长度>> PacketId: 4字节整数, 值为0; -Body: 公钥信息 +Body: + ```json + { + // 硬件信息，目前有剩余内存，剩余磁盘和cpu负载 + // 剩余内存，单位为mb + + "memory": { + "total": 1024, // 内存数，mb + "used": "$int" // 剩余内存数 + }, + "disk": { + "total": 1024, // 硬盘容量GB + "used": "$int" // 剩余硬盘内容GB + }, + + "cpu_load": $float, // 浮点数 + "cpu_temperature": $float // 稳定信息 + "cpu_core": $int, + + "boot_time": 2000, // 启动时间 + "efka_version": "1.0.0", // 客户端版本 + "kernel_arch": "arm64", // 客户端硬件架构 + "province": "", // 所在省 + "city": "", // 所在市 + "adcode": 100, // 所在城市的编号 + "ips": [ + "ip地址1", + "ip地址2" + ], + // 接口信息 + "interfaces": [ + { + "status": 0|1, "接口状态，0离线，1在线" + "name": "接口名称", + "desc": "接口描述", + } + ] + } + ``` ### inform数据上传(无响应) <<0x01, PacketId:4, 0x04, Body:任意长度>> PacketId: 4字节整数, 值为0; -Body: 公钥信息 +Body: + ```json + { + "at": $int64, + // 微服务信息 + "services": [{ + "scene_id": $int "场景的编号", + "name": "微服务名称", + "version": "微服务版本", + "version_copy": "微服务副本", + // 微服务是否在线，0表示离线，1表示在线 + "status": 0|1 + }] + } + ``` ### feedback_step数据上传(无响应) <<0x01, PacketId:4, 0x05, Body:任意长度>> PacketId: 4字节整数, 值为0; -Body: 公钥信息 +Body: + ```json + { + "task_id": "任务的task id", + // sc为step code，具体地： + // 0代表该任务开始了，服务端创建该任务之后，是这个代码 + // 1代表任务被分发了，服务端向nats(mqtt)发送消息之后，是这个代码 + // 2代表任务被设备端接收到了 + // 3代表该任务已经被发送给微服务进行处理了 + // 4代表该任务已经被微服务收到了，微服务正在处理 + // 5代表任务已经完成，微服务已经处理完成。 + "code": $int + } + ``` ### feedback_result数据上传(无响应) <<0x01, PacketId:4, 0x06, Body:任意长度>> PacketId: 4字节整数, 值为0; -Body: 公钥信息 +Body: + ```json + { + "task_id": "任务id", + // unix nano类型 + "time": $int, + // 返回的结果码，0代表成功，其他代表出错 + "code": $int, + "reason": "任务执行的结果", + "error": "错误消息，当c为非0时，这个字段会表示出错消息", + // 返回任务类型，1表示任务是微服务下发，0代表是命令下发 + "type": 0 | 1, + } + ``` ### 主机上传终端设备的相关事件 <<0x01, PacketId:4, 0x07, Body:任意长度>> @@ -85,15 +191,4 @@ Body: 事件内容，AES加密 } } -``` - -### data北向数据上传 (无响应) - -#### 微服务产生的数据，点位信息为主机的点位信息 -<<0x01, PacketId:4, 0x08, 0x00, Body:任意长度>> -PacketId: 4字节整数, 值为0; - -#### 终端设备产生的数据，点位信息为设备信息点位信息 -<<0x01, PacketId:4, 0x08, Type:1byte, Body:任意长度>> -PacketId: 4字节整数, 值为0; -Type: 第一bit为1，后7个bit标识后面的device_uuid的长度, 即: <<1:1, Len:7>>, 总共8个bit \ No newline at end of file +``` \ No newline at end of file