MQTT设备厂家接入thinglinks二次开发指南

xiaonannet 2022-05-06 18:26:45
加精

 

目录

LINK 南向接口(MQTT 消息)

添加网关子设备

主题 Topic:/v1/devices/{deviceId}/topo/add

主题 Topic:/v1/devices/{deviceId}/topo/addResponse

删除网关子设备

主题 Topic:/v1/devices/{deviceId}/topo/delete

 主题 Topic:/v1/devices/{deviceId}/topo/deleteResponse

更新网关子设备状态

主题 Topic:/v1/devices/{deviceId}/topo/update

主题 Topic:/v1/devices/{deviceId}/topo/updateResponse

设备数据上报

主题 Topic:/v1/devices/{deviceId}/datas

设备命令下发

主题 Topic:/v1/devices/{deviceId}/command

主题 Topic:/v1/devices/{deviceId}/commandResponse

查询设备信息(待更新)

产品模型Profile详细设计说明

Profile简介

什么是Profile

Profile使用

快速了解ThingLinks平台,MQTT设备接入

 注册子设备

更新子设备状态

 设备业务数据上报


 

 

LINK 南向接口(MQTT 消息

说明:Topic中,以正斜线(/)进⾏分层,区分每个类⽬。其中,有两个类⽬为既定类⽬:deviceId为网关设备的设备唯一标识(即deviceIdentification)
设备操作权限:发布表⽰设备可以往该Topic发布消息;订阅表⽰设备可以订阅该Topic获取消息;遗言用于通知同一主题下的其他设备发送遗言的设备已经断开了连接。

 

平台默认协议主题(Topic)

Topic

Publisher

(发布者)

Subscribe r

(订阅者)

用途

/v1/devices/{deviceId}/topo/add

边设备

物联网平台

边设备添加子设备

/v1/devices/{deviceId}/topo/addResponse

物联网平台

边设备

物联网平台返回的添加子设备的响应

/v1/devices/{deviceId}/topo/delete

边设备

物联网平台

边设备删除子设备

/v1/devices/{deviceId}/topo/deleteResponse

物联网平台

边设备

物联网平台返回的删除子设备的响应

/v1/devices/{deviceId}/topo/update

边设备

物联网平台

边设备更新子设备状态

/v1/devices/{deviceId}/topo/updateResponse

物联网平台

边设备

物联网平台返回的更新子设备状态的响应

/v1/devices/{deviceId}/datas

边设备

物联网平台

边设备上报数据

/v1/devices/{deviceId}/command

物联网平台

边设备

物联网平台给设备或边设备下发命令

    
  • 添加网关子设备

主题 Topic/v1/devices/{deviceId}/topo/add

参数说明

字段名

必选/可选

类型

参数描述

mid

必选

Integer

命令 Id

deviceInfos

必选

List<DeviceInfos>

子设备信息列表,列表大小 1~100

DeviceInfos 结构体说明

字段名

必选/可选

类型

参数描述

nodeId

必选

String(256)

设备自身的唯一标识

name

必选

String(256)

设备名称

description

可选

String(256)

设备描述

manufacturerId

必选

String(256)

厂商 ID

model

必选

String(256)

设备型号

 

示例

{
    "mid":1,
    "deviceInfos":[
        {
            "nodeId":"MN012",
            "name":"温度计",
            "description":"测温",
            "manufacturerId":"TestUtf8ManuId",
            "model":"NBIoTDevice"
        }
    ]
}

主题 Topic/v1/devices/{deviceId}/topo/addResponse

响应参数说明

字段名

必选/可选

类型

参数描述

mid

必选

Integer

命令 Id

statusCode

必选

Integer

请求处理的结果码。“0”表示成功。

非“0”表示失败。详见附录。

statusDesc

可选

String

响应状态描述。

data

必选

List< AddDeviceRsp>

添加子设备的结果信息。

AddDeviceRsp 结构体说明

字段名

必选/可选

类型

参数描述

statusCode

必选

Integer

请求处理的结果码。“0”表示成功。

非“0”表示失败。详见附录。

statusDesc

可选

String

响应状态描述。

deviceInfo

可选

DeviceInfo

设备信息

DeviceInfo 结构体说明

字段名

必选/可选

类型

参数描述

nodeId

必选

String(256)

设备自身的唯一标识

deviceId

必选

String

平台生成的设备唯一标识

name

必选

String(256)

设备名称

description

可选

String(256)

设备描述

manufacturerId

必选

String(256)

厂商 ID

model

必选

String(256)

设备型号

示例

{
    "statusDesc":"successful",
    "data":[
        {
            "statusDesc":"successful",
            "deviceInfo":{
                "name":"温度计",
                "manufacturerId":"TestUtf8ManuId",
                "description":"测温",
                "model":"NBIoTDevice",
                "deviceId":"685270feb3e044d98df028b9d482e51f",
                "nodeId":"MN012"
            },
            "statusCode":0
        }
    ],
    "mid":1,
    "statusCode":0
}

 

  • 删除网关子设备

主题 Topic/v1/devices/{deviceId}/topo/delete

参数说明

字段名

必选/可选

类型

参数描述

mid

必选

Integer

命令 Id

deviceIds

必选

List<String>

设备 ID 列表,列表大小 1~100

 

示例

{
    "mid":1,
    "deviceIds":[
        "b629fdf52f5643a38bc3357bd3dc5c35",
        "4699e7d8207e4627999a52d9a854ef1d"
    ]
}

 主题 Topic/v1/devices/{deviceId}/topo/deleteResponse

响应参数说明

字段名

必选/可选

类型

参数描述

mid

必选

Integer

命令 Id

statusCode

必选

Integer

请求处理的结果码。“0”表示成功。

非“0”表示失败。详见附录。

statusDesc

可选

String

响应状态描述。

data

可选

List< DelDeviceRsp>

设备删除的结果信息。

DelDeviceRsp 结构体说明

字段名

必选/可选

类型

参数描述

statusCode

必选

Integer

请求处理的结果码。“0”表示成功。

非“0”表示失败。详见附录。

statusDesc

可选

String

结果描述

deviceId

必选

设备 ID

平台生成的设备唯一标识

示例

{
    "statusDesc":"successful",
    "data":[
        {
            "statusDesc":"successful",
            "deviceId":"b629fdf52f5643a38bc3357bd3dc5c35",
            "statusCode":0
        },
        {
            "statusDesc":"successful",
            "deviceId":"4699e7d8207e4627999a52d9a854ef1d",
            "statusCode":0
        }
    ],
    "mid":"1",
    "statusCode":0
}
  • 更新网关子设备状态

主题 Topic/v1/devices/{deviceId}/topo/update

参数说明

字段名

必选/可选

类型

参数描述

mid

必选

Integer

命令 Id

deviceStatuses

必选

List<DeviceStatus>

设备状态列表,列表大小 1~100

DeviceStatus结构体说明

字段名

必选/可选

类型

参数描述

deviceId

必选

String

平台生成的设备唯一标识

status

必选

String

子设备状态:

OFFLINE:设备离线

ONLINE: 设备上线;

示例

{
    "mid":1,
    "deviceStatuses":[
        {
            "deviceId":"0338dc9b-ab11-4673-a886-17e94eede6ec",
            "status":"OFFLINE"
        },
        {
            "deviceId":"0338dc9b-ab11-4673-a886-17e94eede6e4",
            "status":"OFFLINE"
        }
    ]
}

主题 Topic/v1/devices/{deviceId}/topo/updateResponse

响应参数说明

字段名

必选/可选

类型

参数描述

mid

必选

Integer

命令 Id

statusCode

必选

Integer

请求处理的结果码。“0”表示成功。

非“0”表示失败。详见附录。

statusDesc

可选

String

响应状态描述。

data

可选

List< UpdateStatusRsp >

更新设备状态信息。

UpdateStatusRsp 结构体说明

字段名

必选/可选

类型

参数描述

statusCode

必选

Integer

请求处理的结果码。“0”表示成功。

非“0”表示失败。详见附录。

statusDesc

可选

String

结果描述

deviceId

必选

设备 ID

平台生成的设备唯一标识

 示例

{
    "statusDesc":"successful",
    "data":[
        {
            "statusDesc":"successful",
            "deviceId":"b629fdf52f5643a38bc3357bd3dc5c35",
            "statusCode":0
        },
        {
            "statusDesc":"successful",
            "deviceId":"4699e7d8207e4627999a52d9a854ef1d",
            "statusCode":0
        }
    ],
    "mid":"1",
    "statusCode":0
}
  • 设备数据上报

主题 Topic/v1/devices/{deviceId}/datas

参数说明

字段名

必选/可选

类型

参数描述

devices

必选

DeviceS[]

设备数据

DeviceS 结构体说明

字段名

必选/可选

类型

参数描述

deviceId

必选

String(256)

平台生成的设备唯一标识

services

必选

List<Services>

服务列表

Services 结构体说明

字段名

必选/可选

类型

参数描述

serviceId

必选

String(256)

服务 ID

data

必选

ObjectNode

服务数据

eventTime

必选

String(256)

时间格式:yyyyMMddTHHmmssZ’ 如 : 20220505T121212Z

示例

{
    "devices":[
        {
            "deviceId":"87ba80dbdb4d4f97ad8be1f7ec78e812",
            "services":[
                {
                    "serviceId":"service1",
                    "data":{
                        "wendu":11,
                        "time":79
                    },
                    "eventTime":"20220506T162112Z"
                }
            ]
        }
    ]
}

设备命令下发

主题 Topic/v1/devices/{deviceId}/command

参数说明

字段名

必选/可选

类型

参数描述

deviceId

必选

String

平台生成的设备唯一标识,对应设备客户端ID。

msgType

必选

String

固定值"cloudReq",表示平台下发的请求。

serviceId

必选

String

服务ID。

cmd

必选

String

服务的命令名。

paras

必选

ObjectNode

命令的参数。

mid

必选

Int

命令ID。

示例

{
    "msgType":"cloudReq",
    "mid":1,
    "cmd":"command1",
    "paras":{
        "temperature":123
    },
    "serviceId":"service1",
    "deviceId":"1532a311ce554052936f64f3dd3fff88"
}

主题 Topic/v1/devices/{deviceId}/commandResponse

参数说明

字段名

必选/可选

类型

参数描述

msgType

必选

String

固定值"deviceRsp",表示设备的应答消息

mid

必选

Int

命令 id

errcode

必选

Int

请求处理的结果码。

0 表示成功,1 表示失败

body

可选

ObjectNod e

命令的应答

示例

{
    "body":{
        "orginParameters":{
            "temperature":123
        },
        "state":"ok"
    },
    "errcode":0,
    "mid":54132,
    "msgType":"deviceRsp"
}

 

查询设备信息(待更新)

 

产品模型Profile详细设计说明

Profile简介

什么是Profile

 

产品Profile是一个json格式的文件,用于描述产品是什么,能做什么,可以对外提供哪些服务。

Profile是一个设备接入的关键内容,里面包含了这个设备上报的数据格式。将产品的Profile文件上传到ThingLinks平台后,当设备上报数据到平台,平台会根据上报数据的关键字进行匹配。如果匹配不成功,平台会将上报的数据作为非法数据进行抛弃。

 

规范

 

  1. 设计规范

要注重名称的通用性,简洁性;对于服务能力描述,还要考虑其功能性;如:对于多传感器设备,就可以命名为Multi(多)Sensor(传感器);对于某设备具有显示电量的服务,就可以命名为Battery。

  1. 打包规范

Profile写作完成后,需要命名为JSON文件,下面以Default_TestUtf8ManuId_NBIoTDevice.json为例介绍。

  1. 关于上图有几点说明:
    • 一个产品模型对应一个json文件,json文件的命名无严格要求,建议按照deviceType_manufacturerId_model.json的格式命名。
    • Profile文件中的文档格式都是json,在编辑完成后可以在互联网上查找一些格式校验网站,检查json的合法性。
    • json文件编码格式要求为UTF-8,否则导入Thinglinks平台可能会存在乱码。

示例

Profile文件(deviceType_manufacturerId_model.json)示例如下:

{
    "productName":"product_n",
    "productType":"COMMON",
    "manufacturerId":"TestUtf8ManuId",
    "manufacturerName":"HZYB",
    "model":"NBIoTDevice",
    "dataFormat":"JSON",
    "deviceType":"WaterMeter",
    "protocolType":"MQTT",
    "remark":"",
    "services":[
        {
            "serviceId":"service1",
            "description":"",
            "commands":[

            ],
            "properties":[
                {
                    "datatype":"int",
                    "description":"",
                    "enumlist":"",
                    "max":"65536",
                    "maxlength":10,
                    "method":"R",
                    "min":"0",
                    "name":"wendu",
                    "required":1,
                    "step":1,
                    "unit":""
                },
                {
                    "datatype":"int",
                    "description":"",
                    "enumlist":"",
                    "max":"65536",
                    "maxlength":10,
                    "method":"R",
                    "min":"0",
                    "name":"time",
                    "required":1,
                    "step":1,
                    "unit":""
                }
            ]
        },
        {
            "serviceId":"service2",
            "description":"",
            "commands":[
                {
                    "name":"command1",
                    "description":"",
                    "requests":[
                        {
                            "datatype":"int",
                            "enumlist":"",
                            "max":"65536",
                            "maxlength":10,
                            "min":"0",
                            "parameterDescription":"",
                            "parameterName":"wendu",
                            "required":1,
                            "step":1,
                            "unit":""
                        }
                    ],
                    "responses":[

                    ]
                }
            ],
            "properties":[

            ]
        }
    ]
}

字段

必选/可选

描述

productName

必选

产品名称。

自定义,支持中文、英文大小写、数字、下划线和中划线,长度[2,64]。

 

productType

必选

支持以下两种产品类型:

  • COMMON:普通产品,需直连设备。
  • GATEWAY:网关产品,可挂载子设备。

manufacturerId

必选

厂商ID。

支持英文大小写,数字,下划线和中划线,长度[2,50]。

manufacturerName

必选

厂商名称 。

支持中文、英文大小写、数字、下划线和中划线,长度[2,64]。

model

必选

产品型号,建议包含字母或数字来保证可扩展性。

支持英文大小写、数字、下划线和中划线,长度[2,50]。

dataFormat

必选

数据格式,默认为JSON无需修改。

deviceType

必选

设备类型。

支持英文大小写、数字、下划线和中划线,长度[3,50]。

protocolType

必选

设备接入平台的协议类型,默认为MQTT无需修改。

remark

可选

产品描述。

services

-

必选

包含了产品具备的服务能力描述。

如果无服务,则配置为[]。

serviceId

必选

服务名称。

支持英文小写、数字及下划线,全部小写命名,禁止出现英文大写,多个单词用下划线,分隔长度[2,50]

description

可选

服务的描述信息。

文本描述,不影响实际功能,可配置为空字符串""。

commands

-

必选

指示设备可以执行的命令,如果本服务无命令则配置为[]。

name

必选

指示命令的名字,如门磁的LOCK命令、摄像头的VIDEO_RECORD命令,命令名与参数共同构成一个完整的命令。

支持英文小写、数字及下划线,全部小写命名,禁止出现英文大写,多个单词用下划线,分隔长度[2,50]

description

可选

命令描述。

requests

-

必选

下发命令字段。

datatype

必选

指示数据类型。

取值范围:string、int、decimal

enumlist

必选

指示枚举值。

如开关状态status可有如下取值

"enumList" : ["OPEN","CLOSE"]

目前本字段是非功能性字段,仅起到描述作用。建议准确定义。

max

必选

指示最大值。

仅当dataType为int、decimal时生效,逻辑小于等于。

maxlength

必选

指示字符串长度。

仅当dataType为string、binary时生效。(string最长为4093,binary最长为 16000 字节)

min

必选

指示最小值。

仅当dataType为int、decimal时生效,逻辑大于等于。

parameterDescription

可选

命令中参数的描述,不影响实际功能,可配置为空字符串""。

parameterName

必选

命令中参数的名字。

required

必选

指示本条属性是否必填,取值为0或1,默认取值1(必填)。

目前本字段是非功能性字段,仅起到描述作用。

step

必选

指示步长。

unit

必选

指示单位。

取值根据参数确定,如:

  • 温度单位:“C”或“K”
  • 百分比单位:“%”
  • 压强单位:“Pa”或“kPa”

responses

必选

响应命令字段,该字段下参数与requests相同,如果无该字段,则配置为[]。

properties

-

datatype

必选

指示数据类型。

取值范围:string、binary、int、bool、decimal(float和double都可以使用此类型)、timestamp、json

上报数据时,复杂类型数据格式如下:

  • json:自定义json结构体,平台不理解只透传

description

可选

属性描述,不影响实际功能,可配置为空字符串""。

enumlist

必选

指示枚举值。

如开关状态status可有如下取值

"enumList" : ["OPEN","CLOSE"]

目前本字段是非功能性字段,仅起到描述作用。建议准确定义。

max

必选

指示最大值。支持长度不超过50的数字。

仅当dataType为int、decimal时生效,逻辑小于等于。

maxlength

必选

指示字符串长度。

仅当dataType为string、binary时生效。每个服务总计数据长度不能超过 48KB(string最长为4093字节,binary最长为 16000 字节)

method

必选

指示访问模式。

R:可读;W:可写;E属性值更改时上报数据

取值范围:R、RW、RE、RWE

min

必选

指示最小值。支持长度不超过50的数字。

仅当dataType为int、decimal时生效,逻辑大于等于。

name

必选

指示属性名称。

支持英文小写、数字及下划线,全部小写命名,禁止出现英文大写,多个单词用下划线,分隔长度[2,50]

required

必选

指示本条属性是否必填,取值为0或1,默认取值1(必填)。

目前本字段是非功能性字段,仅起到描述作用。

step

必选

指示步长。

unit

必选

指示单位。支持长度不超过50。

取值根据参数确定,如:

  • 温度单位:“C”或“K”
  • 百分比单位:“%”
  • 压强单位:“Pa”或“kPa”

datatype指示数据类型详解(详细设计标准TAOS官方指导手册

#类型Bytes说明
1TIMESTAMP8时间戳。缺省精度毫秒,可支持微秒和纳秒。从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始,计时不能早于该时间。(开始支持纳秒精度)
2INT4整型,范围 [-2^31+1, 2^31-1], -2^31 用作 NULL
3BIGINT8长整型,范围 [-2^63+1, 2^63-1], -2^63 用于 NULL
4FLOAT4浮点型,有效位数 6-7,范围 [-3.4E38, 3.4E38]
5DOUBLE8双精度浮点型,有效位数 15-16,范围 [-1.7E308, 1.7E308]
6BINARY自定义记录单字节字符串,建议只用于处理 ASCII 可见字符,中文等多字节字符需使用 nchar。理论上,最长可以有 16000 字节。binary 仅支持字符串输入,字符串两端需使用单引号引用。使用时须指定大小,如 binary(20) 定义了最长为 20 个单字节字符的字符串,每个字符占 1 byte 的存储空间,总共固定占用 20 bytes 的空间,此时如果用户字符串超出 20 字节将会报错。对于字符串内的单引号,可以用转义字符反斜线加单引号来表示,即 \’。虽然 Binary 类型在底层存储上支持字节型的二进制字符,但不同编程语言对二进制数据的处理方式并不保证一致,因此建议在 Binary 类型中只存储 ASCII 可见字符,而避免存储不可见字符。多字节的数据,例如中文字符,则需要使用 nchar 类型进行保存。如果强行使用 Binary 类型保存中文字符,虽然有时也能正常读写,但并不带有字符集信息,很容易出现数据乱码甚至数据损坏等情况。
7SMALLINT2短整型, 范围 [-32767, 32767], -32768 用于 NULL
8TINYINT1单字节整型,范围 [-127, 127], -128 用于 NULL
9BOOL1布尔型,{true, false}
10NCHAR自定义记录包含多字节字符在内的字符串,如中文字符。每个 nchar 字符占用 4 bytes 的存储空间。字符串两端使用单引号引用,字符串内的单引号需用转义字符 \’。nchar 使用时须指定字符串大小,类型为 nchar(10) 的列表示此列的字符串最多存储 10 个 nchar 字符,会固定占用 40 bytes 的空间。如果用户字符串长度超出声明长度4093,将会报错。
11JSON json数据类型, 只有tag类型可以是json格式

 

Profile使用

定义好产品模型json文件后在thinglinks平台设备集成-》产品管理中导入该文件

快速了解ThingLinks平台,MQTT设备接入

创建设备档案,点击设备集成-》设备管理-》新增(前提是产品模型已导入至ThingLinks平台)

 

 

 

通过MQTTX工具连接该设备

 

可以看到设备已连接成功,通过页面可以看到在线,下面需要订阅设备需要接收消息的Topic 

 网关设备上线成功后最重要的就是注册子设备信息,维护子设备的状态,并且进行数据的上报(顺序很重要)

 注册子设备

 

 平台响应子设备注册的相关信息,deviceId是子设备的唯一识别码,需要保存好,TDengine中也会生成该设备的数据表

 因为该网关设备关联的产品模型下有2个服务,分别是service1,service2,平台会根据不同的服务属性生成不同的表,用于分辨子设备上报的不同属性的业务数据。

 

更新子设备状态

 接下来更新子设备状态,使子设备上线,离线自然也需要进行上报更新

 设备业务数据上报

 数据上报演示

上报属性值与产品模型服务属性不一致的情况下的演示,INT属性不在产品服务定义中,且命名不符合标准。

 

 上报属性值与产品模型服务属性一致的情况下的演示

 

 

 

 

...全文
969 回复 打赏 收藏 举报
写回复
回复
切换为时间正序
请发表友善的回复…
发表回复
相关推荐
发帖
ThingLinks社区

162

社区成员

ThingLinks物联网一体化平台社区 版本将持续迭代更新,支持商业二开; 欢迎你分享物联网及平台相关技术文档;
物联网能源 开源
社区管理员
  • xiaonannet
  • jian436
  • 很久是多久
加入社区
帖子事件
编辑了帖子
2022-06-28 14:37
编辑了帖子 (查看)
2022-06-24 18:09
编辑了帖子 (查看)
2022-06-24 17:58
编辑了帖子 (查看)
2022-06-24 17:46
编辑了帖子 (查看)
2022-06-24 17:33
编辑了帖子 (查看)
2022-06-23 13:18
展开
社区公告

ThingLinks物联网一体化平台社区

https://gitee.com/mqttsnet/thinglinks

https://github.com/mqttsnet/thinglinks