设备管理

RealMQ 提供产品管理和设备管理功能，在创建产品后，支持调用API进行动态注册设备，同时支持匿名、常规的用户名密码认证和阿里云的三元组加密方式认证，可以通过配置开启设备管理功能。 设备管理功能需要借助外部数据库进行存储，需要手动开启enabled设置为true, 支持的数据库类型有MySQL和PostgreSQL，配置数据库连接之前，需要提前创建数据库:

创建数据库
CREATE DATABASE rmq_dm;

数据库表可以根据auto_create_tables配置自动创建，在参数设置中配置数据库连接信息后，点击应用即可 配置完即可启动设备管理功能

如果没有创建数据库表权限，那需要手动创建数据库表，表结构如下:

进入到数据库中
USR rmq_dm;

DROP TABLE IF EXISTS `rmq_products`;
    CREATE TABLE `rmq_products` (
        `id` bigint NOT NULL AUTO_INCREMENT,
        `name` varchar(255) DEFAULT NULL COMMENT 'product name',
        `type` tinyint DEFAULT '1' COMMENT 'product type',
        `product_key` varchar(255) DEFAULT NULL COMMENT 'product key',
        `product_secret` varchar(255) DEFAULT NULL COMMENT 'product secret',
        `dynamic_reg` tinyint DEFAULT '0' COMMENT 'product dynamic_reg flag',
        `auth_type` tinyint DEFAULT '0' COMMENT '',
        `status` tinyint DEFAULT '0' COMMENT '',
        `model_status` tinyint DEFAULT '0' COMMENT '',
        `description` varchar(255) DEFAULT NULL COMMENT 'product description',
        `create_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Created timestamp',
        `update_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Updated timestamp',
        PRIMARY KEY (`id`),
        UNIQUE KEY `name` (`name`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

        DROP TABLE IF EXISTS `rmq_devices`;
        CREATE TABLE `rmq_devices` (
        `id` bigint NOT NULL AUTO_INCREMENT,
        `mqtt_client_id` varchar(255) DEFAULT NULL COMMENT 'mqtt client id',
        `product_key` varchar(255) DEFAULT NULL COMMENT 'product key',
        `name` varchar(255) DEFAULT NULL COMMENT 'device name',
        `username` varchar(255) DEFAULT NULL COMMENT 'device username',
        `nickname` varchar(255) DEFAULT NULL COMMENT 'device nickname',
        `password` varchar(255) DEFAULT NULL COMMENT 'device password',
        `enable` tinyint DEFAULT '0' COMMENT '0 - disable 1 - enable',
        `log_trace` tinyint DEFAULT '0' COMMENT '0 - disable 1 - enable',
        `status` tinyint DEFAULT '0' COMMENT '',
        `ip` varchar(255) DEFAULT NULL COMMENT 'Client IP Address',
        `description` varchar(255) DEFAULT NULL COMMENT 'product description',
        `create_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Created timestamp',
        `update_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Updated timestamp',
        `connected_at` timestamp NULL DEFAULT NULL COMMENT 'Client connected timestamp',
        `disconnected_at` timestamp NULL DEFAULT NULL COMMENT 'Client disconnected timestamp. NULL means client is online and never disconnected',
        PRIMARY KEY (`id`),
        UNIQUE KEY `product_key_name` (`product_key`, `name`),
        INDEX `product_key_index` (`product_key`),
        INDEX `mqtt_client_id_index` (`mqtt_client_id`),
        INDEX `name_index` (`name`),
        INDEX `product_key_status_index` (`product_key`, `status`),
        INDEX `product_key_client_id` (`product_key`, `mqtt_client_id`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

        DROP TABLE IF EXISTS `rmq_sub_devices`;
        CREATE TABLE `rmq_sub_devices` (
        `id` bigint NOT NULL AUTO_INCREMENT,
        `device_id` bigint NOT NULL COMMENT 'device id',
        `mqtt_client_id` varchar(255) DEFAULT NULL COMMENT 'mqtt client id',
        `name` varchar(255) DEFAULT NULL COMMENT 'sub device name',
        `nickname` varchar(255) DEFAULT NULL COMMENT 'sub device nickname',
        `sn` varchar(255) DEFAULT NULL COMMENT 'sub device sn',
        `status` tinyint DEFAULT '0' COMMENT '',
        `create_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Created timestamp',
        `update_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Updated timestamp',
        `online_at` timestamp NULL DEFAULT NULL COMMENT 'Client connected timestamp',
        `offline_at` timestamp NULL DEFAULT NULL COMMENT 'Client disconnected timestamp. NULL means client is online and never disconnected',
        PRIMARY KEY (`id`),
        INDEX `device_id_index` (`device_id`),
        INDEX `mqtt_client_id_sn_index` (`device_id`, `sn`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

        DROP TABLE IF EXISTS `rmq_device_status_logs`;
        CREATE TABLE `rmq_device_status_logs` (
        `id` bigint NOT NULL AUTO_INCREMENT,
        `device_id` bigint NOT NULL COMMENT 'Device id',
        `type` tinyint DEFAULT '0' COMMENT '',
        `reason` varchar(255) DEFAULT NULL COMMENT 'offline reason',
        `create_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Created timestamp',
        PRIMARY KEY (`id`),
        INDEX `device_id` (`device_id`),
        INDEX `create_at` (`create_at`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;


        DROP TABLE IF EXISTS `rmq_tags`;
        CREATE TABLE `rmq_tags` (
        `id` bigint NOT NULL AUTO_INCREMENT,
        `device_id` bigint NOT NULL COMMENT 'device id',
        `name` varchar(255) DEFAULT NULL COMMENT 'tag name',
        `value` varchar(255) DEFAULT NULL COMMENT 'tag value',
        `create_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Created timestamp',
        PRIMARY KEY (`id`),
        UNIQUE KEY `device_id_name` (`device_id`, `name`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;


        DROP TABLE IF EXISTS `rmq_device_shadows`;
        CREATE TABLE `rmq_device_shadows` (
        `id` bigint NOT NULL AUTO_INCREMENT,
        `device_id` bigint NOT NULL COMMENT 'device id',
        `pub_topic` varchar(255) DEFAULT NULL COMMENT 'Publish Topic',
        `sub_topic` varchar(255) DEFAULT NULL COMMENT 'Subscribe Topic',
        `data` text DEFAULT NULL COMMENT 'Device Shadow Data',
        `status` tinyint DEFAULT '0' COMMENT 'Shadow Status',
        `version` int DEFAULT '1' COMMENT 'Shadow Version',
        `description` varchar(255) DEFAULT NULL COMMENT 'Shadow description',
        `create_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Created timestamp',
        `update_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'Updated timestamp',
        PRIMARY KEY (`id`),
        UNIQUE KEY `device_id` (`device_id`),
        INDEX `pub_topic_index` (`pub_topic`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

设备认证

默认情况下，添加的设备后是使用用户名密码进行认证，如果需要开启阿里云三元组认证可以在配置中选择阿里云认证模式。

阿里云认证模式

clientid: productKey.deviceUserName|securemode=2,signmethod=hmacsha256,timestamp=1720057806414|

username: deviceUserName&productKey

password: signmethod(clientId${productKey}.${deviceUserName}deviceName${deviceName}productKey${productKey}timestamp${timestamp})

productKey = b1b25172e1
username = aaa
securemode = 2
signmethod = hmacsha256
timestamp = 1714120054045
deviceSecret = aaa
MQTT 连接登录信息
clientid: b1b25172e1.aaa|securemode=2,signmethod=hmacsha256,timestamp=1714120054045|
username: aaa&b1b25172e1
## hmacsha256("aaa", "clientIdb1b25172e1.aaadeviceNameaaaproductKeyb1b25172e1timestamp1714120054045")
password: 71a45ae7fc7e46fda5324a4784da5d6723d8698240964c1c58a849aea30178a8

可以通过设备详情页面查看MQTT连接参数信息

通用认证模式

productKey = dccf2f8f73
clientid = dccf2f8f73.test3
username = test3
deviceSecret = 3fb8169398958a3bde7f95d21090864d

MQTT 连接登录信息
clientid: dccf2f8f73.test3
username: test3&dccf2f8f73
password: 3fb8169398958a3bde7f95d21090864d

可以通过设备详情页面查看MQTT连接参数信息

产品管理

产品页面支持分页和模糊查询，对产品进行添加和管理

产品添加

产品添加支持配置 产品类型、动态注册、加密类型等，开启动态注册后，可以调用API进设备的动态创建。

动态注册API

POST /api/v1/register_device

Parameters (json):

Name	Type	Required	Default	Description
productKey	String	Required		产品key
deviceName	String	Required		设备名称
deviceUserName	String	Optional		如果不填，使用deviceName填充
deviceSecret	String	Optional		如果不填，系统自动生成
random	String	Required		随机数
Sign	String	Required		deviceName+productKey+random拼接的字符后用signMethod进行加密,signMethod(${product_secret}, deviceName${deviceName}productKey${productKey}random${random})
signMethod	String	Required		hmacmd5|hmacsha1|hmacsha256

Success Response Body (JSON)

Name	Type	Description
code	Integer	0
message	String	success
data	object

Examples:

$ curl -i --basic -u root:123456 -X POST "http://localhost:8090/api/v1/register_device" -d '{"productKey":"2e044f1c20","deviceName":"test111","deviceSecret":"123456", "random": "123456", "sign": "8bb21ff136a8e3e3e0d20ab2a1bdce7dc054b903", "signMethod": "hmacsha1"}'

{"code":0,"message": "success", "data": {"productKey":"2e044f1c20","deviceName":"test111","deviceSecret":"123456"}}

Topic 定义

定义Topic后，设备可以通过Topic与设备和平台进行通信，从而实现设备、平台、业务服务器、其他云产品之间的通信

• 设备操作权限 设备对该Topic的操作权限，可设置为：发布 | 订阅 | 发布和订阅
• 主题名称 Topic格式必须以 / 进行分层，区分每个类目。支持使用${clientId} | ${username} | ${deviceName} | ${deviceId} | ${productKey}。
• 是否开启代理订阅 开启代理订阅后设备与平台建连时，平台查询已开启代理订阅的Topic，帮助设备完成订阅。
• 描述 可输入文字，描述该Topic类，用于区分不同Topic类的功能

预置规则

设备登录和离线时，支持设置规则，异步操作数据库的SQL语句，更新数据库表结构

• 名称 规则名称
• 类型 连接 | 断开连接
• 描述 SQL语句模板

SQL语句模板支持的参数

字段	描述
clientid	客户端id
username	用户名
peername	终端的 IPAddress 和 Port
connected_at	客户端连接完成时间 (ms)
disconnected_at	客户端断开连接时间 (ms)
timestamp	事件触发时间 (ms)

设备管理

设备页面支持分页和模糊查询，对设备进行添加和管理，给设备添加和删除标签

设备添加

• 设备名称
• 产品
• MQTT用户名
• MQTT 密码
• 设备昵称
• MQTT 客户端ID

设备标签

可以给设备设置标签，设置的标签可以在数据转换中进行过滤操作,通过headers.tags.xxx获取

设备影子

用户可以在设备详情里面开启设备影子功能，开启设备影子后，RealMQ 会把设备影子数据存储在数据库中，不管设备在线还是离线，都可以通过HTTP API 或者 MQTT消息 获取设备影子数据和管理影子数据。

设备影子 REST-API

插入影子数据

POST /api/v1/device_shadow
Params: {
  "device_id": xxx,
  "product_key": "xxx",
  "username": "xxx"
}
Response: {code: 200}

获取影子数据

GET /api/v1/device_shadow
Params: {
  "device_id": xxx
}
Response: {
    "id": 3,
    "device_id": xxx,
    "status": true,
    "sub_topic": "shadow/xxx/reply",
    "pub_topic": "shadow/xxx",
    "data": {
        "info": "xxx"
    },
    "create_at": "xxx",
    "update_at": "xxx",
}

修改影子数据

PUT /api/v1/device_shadow
Params: {
  "device_id": xxx,
  "product_key": "xxx",
  "username": "xxx",
  "data": {
    "xxx": xxx
  }
}
Response: {code: 200}

设备影子 MQTT API

插入影子数据

向 topic: shadow/${id} publish 下面的 payload
topic: shadow/${id}
payload: {
  "method": "PUT",
  "payload": {
    "info": "xxx"
  }
}

给影子追加数据

向 topic: shadow/${id} publish 下面的 payload
payload: {
  "method": "PATCH",
  "payload": {
    "info1": "xxx"
  }
}

获取影子数据

首先需要 subscribe topic: shadow/${id}/reply
在向 topic: shadow/${id} publish 下面的payload
payload: {
  "method": "GET"
}

单个设备统计

通过设备详情页面可以启动单个设备的消息收发统计和内容查看，有助于调试和排查问题，开启统计后系统会存储该客户端2小时内发布和接收的消息，如果没有手动关闭，系统会在2个小时后自动关闭。

设备模拟器

离线设备可以使用设备模拟器进行连接、上行指令调试和下行指令发布，实时查看消息收发日志。