From 6ed5067df4685da05c5cb41542091fadf5a00c63 Mon Sep 17 00:00:00 2001 From: anlicheng Date: Tue, 20 Jun 2023 16:59:31 +0800 Subject: [PATCH] fix docs --- apps/iot/include/iot.hrl | 12 +- docs/host-mqtt-jiaohu.md | 318 +++++++++++++++++++-------------------- 2 files changed, 169 insertions(+), 161 deletions(-) diff --git a/apps/iot/include/iot.hrl b/apps/iot/include/iot.hrl index 4bb69bd..8fb6d7a 100644 --- a/apps/iot/include/iot.hrl +++ b/apps/iot/include/iot.hrl @@ -20,4 +20,14 @@ -record(router, { router_id -}). \ No newline at end of file +}). + +-define(METHOD_CREATE_SESSION, 16#01). +-define(METHOD_DATA, 16#02). +-define(METHOD_PING, 16#03). +-define(METHOD_INFORM, 16#04). +-define(METHOD_FEEDBACK_STEP, 16#05). +-define(METHOD_FEEDBACK_RESULT, 16#06). + + + diff --git a/docs/host-mqtt-jiaohu.md b/docs/host-mqtt-jiaohu.md index 6997633..47857ef 100644 --- a/docs/host-mqtt-jiaohu.md +++ b/docs/host-mqtt-jiaohu.md @@ -39,35 +39,6 @@ t = 0 } ``` -## create_session主机注册会话 - -register的时候，设备端向主题`host/upstream/${uuid}`发送注册信息，由于topic里面已经携带了主机标识，因此body里面不需要$uuid, 该信息格式如下： - -```json -{ - "method": "create_session", - "params": { - "pub_key": "该客户端自己生成的公钥" - } -} -``` - -其中，`pub_key`表示客户端自身的公钥，该公钥用于与服务端交换aes密钥。 - -需要注意，这里的交互逻辑有变更(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密钥进行加解密。 -} -``` - ## 主机授权消息格式 t = 8 @@ -94,44 +65,6 @@ t = 8 ``` -## 数据上传结构 -设备端在采集到数据之后，会向topic为`host/upstream/$uuid`发送消息，消息格式如下： - -```json -{ - "methods": "data", - "params": "$bytes" -} -``` - -其中`params`代表具体的采集信息，这部分数据通过与服务端交互商量的: base64:encode(aes加密)，加密之前是一个列表，列表里面的数据格式如下: - -```json: -[ - { - "service_name": "从该设备端的哪个服务采集的数据", - "at": int, 精确到毫秒 - // 该微服务采集的数据，是一个包含map的列表类型，map的内容可以由微服务自己指定 - // 目前一般的格式是"metric-name": $value样式的数据 - "fields": [ - { - "name1": "test" - "name2": 124, - "name3": false, - "device_id": $uuid 非设备产生的device_id为空 - } - ], - // 微服务自身可以生成tag，用于微服务指定自己的一些性质，目前使用得不多，以后可以扩展， - // 是一个map[string]string类型的数据 - "tags": { - "tag1": "value1", - "tag2", "value2" - } - // todo 在insert数据到influxdb的时候需要增加service_name + host_uuid - } -] -``` - ## 命令下发结构 命令下发，用于服务端或者其他的系统，通过调用接口，向设备端发送消息，设备端会监听`host/downstream/$uuid`的消息。 服务端在发送之前，应先用该客户端的aes密钥进行加密，将加密之后的二进制数据发送到该topic。 @@ -189,112 +122,177 @@ TODO 命令下发是需要增加当前的时间戳，host主机用来协调任 } ``` +# 主机主动数据交互逻辑 + +## create_session主机注册会话 + +### 请求 + +上报类型标识: 0x01 +数据部分为下面描述的json格式(aes加密) + +```json +{ + "pub_key": "该客户端自己生成的公钥" +} +``` + +其中，`pub_key`表示客户端自身的公钥，该公钥用于与服务端交换aes密钥。 + +### 响应(响应体整体部分采用了rsa加密，加密的公钥为请求中的: pub_key) + +需要注意，这里的交互逻辑有变更(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": "从该设备端的哪个服务采集的数据", + "at": int, 精确到毫秒 + // 该微服务采集的数据，是一个包含map的列表类型，map的内容可以由微服务自己指定 + // 目前一般的格式是"metric-name": $value样式的数据 + "fields": [ + { + "name1": "test" + "name2": 124, + "name3": false, + "device_id": $uuid 非设备产生的device_id为空 + } + ], + // 微服务自身可以生成tag，用于微服务指定自己的一些性质，目前使用得不多，以后可以扩展， + // 是一个map[string]string类型的数据 + "tags": { + "tag1": "value1", + "tag2", "value2" + } + // todo 在insert数据到influxdb的时候需要增加service_name + host_uuid + } +] +``` + ## ping结构 -ping结构会上传到topic为"host/upstream/$uuid", 结构体由msgpack格式编码, ping结构每隔20秒发送一次, 其中params的数据格式为: base64:encode(aes("加密")) +ping结构会上传到topic为"host/upstream/$uuid", ping结构每隔20秒发送一次 + +上报类型标识: 0x03 +数据部分为下面描述的json格式(aes加密) ```json { - "method": "ping", - "params": { - // 硬件信息，目前有剩余内存，剩余磁盘和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": "接口描述", - } - ] + // 硬件信息，目前有剩余内存，剩余磁盘和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": "接口描述", } -} -``` - -## 命令下发步骤上报结构 -在任务下发之后，设备端会根据命令到哪个环节，进行步骤上报，上报的消息写入到topic为`host/upstream/$uuid`，上报结构如下： - -```json -{ - "method": "feedback_step", - "params": { - "task_id": "任务的task id", - // sc为step code，具体地： - // 0代表该任务开始了，服务端创建该任务之后，是这个代码 - // 1代表任务被分发了，服务端向nats(mqtt)发送消息之后，是这个代码 - // 2代表任务被设备端接收到了 - // 3代表该任务已经被发送给微服务进行处理了 - // 4代表该任务已经被微服务收到了，微服务正在处理 - // 5代表任务已经完成，微服务已经处理完成。 - "code": $int - } -} -``` - -有了这个步骤，最后任务超时等情况，就可以知道任务卡在哪里。 - -## 命令下发结果上报结构 -任务在微服务处理完成之后，设备端会向服务端反馈任务执行的结果。该结果会写入`host/upstream/$uuid`，上报的结构如下： - -```json -{ - "method": "feedback_result", - "params": { - "task_id": "任务id", - // unix nano类型 - "time": $int, - // 返回的结果码，0代表成功，其他代表出错 - "code": $int, - "reason": "任务执行的结果", - "error": "错误消息，当c为非0时，这个字段会表示出错消息", - // 返回任务类型，1表示任务是微服务下发，0代表是命令下发 - "type": 0 | 1, - } + ] } ``` ## inform结构 inform用于客户端主动通知服务端本地事情的发生，比如，自身的某个微服务下线了，就会发送一个inform信息给服务端。 topic: host/upstream/$uuid -inform信息会发送给``, 结构如下： +上报类型标识: 0x04 +数据部分为下面描述的json格式(aes加密) ```json { - "method": "inform", - "params": { - "at": $int64, - // 微服务信息 - "services": [{ - "scene_id": $int "场景的编号", - "name": "微服务名称", - "version": "微服务版本", - "version_copy": "微服务副本", - // 微服务是否在线，0表示离线，1表示在线 - "status": 0|1 - }] - } + "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, +} +``` + +