Topic介绍

BladeX大约 12 分钟introtopic

Topic介绍

Topic主题在物联网平台中扮演着至关重要的角色，负责设备与平台之间的数据通信和事件通知。Topic是消息发布/订阅（Publish/Subscribe）模式中的一个核心概念，设备通过订阅或发布特定的Topic来进行信息的交互。以下是对Topic主题的详细介绍。

1. Topic 主题的定义

Topic是消息中间件中用于分类和分发消息的路径或通道。它将设备和应用程序之间的通信分离，使得消息发送者和接收者可以彼此独立地工作。每个Topic都代表一种特定类型的消息，设备通过订阅这些Topic来接收相应类型的消息，或通过发布到这些Topic来发送消息。

2. Topic 主题的组成部分

Topic主题通常由以下几个部分组成：

主题路径（Topic Path）：一个唯一的标识符，用于区分不同的消息类别。路径通常采用层级结构，以便更好地组织和管理。例如，路径中可能包含以下变量：
- productKey：产品的唯一标识符，用于区分不同的产品。
- deviceName：设备的唯一标识符，用于区分同一产品下的不同设备。
- identity：特定的标识符，用于进一步区分消息类别或设备身份。
消息（Message）：通过Topic传递的数据单元，可以包含任意类型的数据信息。
发布者（Publisher）：负责将消息发布到特定Topic的设备或应用程序。
订阅者（Subscriber）：负责订阅特定Topic以接收消息的设备或应用程序。

3. Topic 主题一览

基础通信Topic

基础通信Topic是物联网平台中用于设备与云端之间进行基本数据传输和控制命令交换的主题。这些Topic通常用于设备的初始化、配置更新、状态报告和基础命令执行。通过这些Topic，设备能够实现与云端的基本通信，包括：

设备初始化和配置：设备接入网络后，通过基础通信Topic向云端报告设备状态，获取初始配置和必要的参数设定。
状态报告：设备定期或在特定事件发生时，通过基础通信Topic向云端发送当前状态信息，如在线状态、运行参数和故障报警等。
基础控制命令：云端通过基础通信Topic向设备发送控制命令，如重启设备、更新配置、开启或关闭特定功能等。

基础通信Topic的设计目的是确保设备能够稳定可靠地与云端保持通信，实现基本的管理和控制功能。其主要特点是通信内容简单、频率较高且对实时性要求较高。

功能	Topic 类	操作权限	描述信息
配置更新	/blade/sys/${productKey}/${deviceName}/thing/config/push	订阅	云端主动下推配置信息
	/blade/sys/${productKey}/${deviceName}/thing/config/get_reply	订阅	云端响应配置信息
	/blade/sys/${productKey}/${deviceName}/thing/config/get	发布	设备端查询配置信息
设备标签	/blade/sys/${productKey}/${deviceName}/thing/deviceinfo/update_reply	订阅	云端响应标签上报
	/blade/sys/${productKey}/${deviceName}/thing/deviceinfo/delete	订阅	设备删除标签信息
	/blade/sys/${productKey}/${deviceName}/thing/deviceinfo/update	发布	设备上报标签数据
	/blade/sys/${productKey}/${deviceName}/thing/deviceinfo/delete_reply	发布	云端响应标签删除
设备影子	/blade/shadow/get/${productKey}/${deviceName}	订阅	设备接收影子变更
设备影子	/blade/shadow/update/${productKey}/${deviceName}	发布	设备影子发布
时钟同步	/blade/ext/ntp/${productKey}/${deviceName}/response	订阅	NTP 时钟同步响应
时钟同步	/blade/ext/ntp/${productKey}/${deviceName}/request	发布	NTP 时钟同步请求
广播	/blade/broadcast/${productKey}/${identifier}	订阅	广播 Topic，identifier 为用户自定义字符串
OTA 升级	/blade/ota/device/upgrade/${productKey}/${deviceName}	订阅	固件升级信息下行
	/blade/ota/device/inform/${productKey}/${deviceName}	发布	设备上报固件升级信息
	/blade/ota/device/progress/${productKey}/${deviceName}		设备上报固件升级进度
	/blade/sys/${productKey}/${deviceName}/thing/ota/firmware/get		设备主动拉取固件升级信息

物模型通信Topic

物模型通信Topic是用于描述和交换物联网设备复杂数据结构的主题，涵盖设备的属性、命令和事件等信息。这些Topic基于物模型（Thing Model）的定义，使得不同类型和厂商的设备能够以统一的方式进行数据交互。物模型通信Topic的应用包括：

属性管理：通过物模型通信Topic，设备可以向云端报告其属性数据，如温度、湿度、电量等，云端也可以通过这些Topic下发属性设定指令。
命令执行：设备可以通过物模型通信Topic接收云端下发的操作命令，例如执行特定的功能或操作，完成后再通过Topic反馈执行结果。
事件上报：当设备发生特定事件时（如故障、警报触发），通过物模型通信Topic向云端上报事件信息，包括事件类型、发生时间和相关数据。

物模型通信Topic的设计旨在支持设备的复杂数据交换和控制需求，确保数据格式的一致性和通信的可靠性。其主要特点是数据结构复杂、内容丰富且对数据一致性要求较高。

功能	Topic 类	操作权限	描述信息
服务调用	/blade/sys/${productKey}/${deviceName}/thing/service/${identifier}	订阅	设备服务调用
服务调用	/blade/sys/${productKey}/${deviceName}/thing/service/${identifier}_reply	发布	设备端响应服务调用
属性获取	/blade/sys/${productKey}/${deviceName}/thing/service/property/get	订阅	云端下发设备属性获取
属性获取	/blade/sys/${productKey}/${deviceName}/thing/service/property/get_reply	发布	设备响应属性获取
属性设置	/blade/sys/${productKey}/${deviceName}/thing/service/property/set	订阅	云端下发设备属性设置
属性设置	/blade/sys/${productKey}/${deviceName}/thing/service/property/set_reply	发布	设备响应属性设置
属性上报	/blade/sys/${productKey}/${deviceName}/thing/event/property/post_reply	订阅	云端响应属性上报
属性上报	/blade/sys/${productKey}/${deviceName}/thing/event/property/post	发布	设备属性上报
事件上报	/blade/sys/${productKey}/${deviceName}/thing/event/${identifier}/post_reply	订阅	云端响应事件上报
事件上报	/blade/sys/${productKey}/${deviceName}/thing/event/${identifier}/post	发布	设备事件上报

自定义Topic

自定义Topic是在物联网平台中为特定应用场景或业务需求而专门定义的通信主题。通过自定义Topic，设备和平台可以实现更灵活和精细化的数据传输和控制，满足特定的功能需求。自定义Topic通常用于以下场景：

特定业务逻辑：实现某些特定业务逻辑，如智能家居中的自定义控制命令或特定事件通知。
数据过滤和处理：根据特定条件过滤和处理数据，例如仅在特定时间段内发送数据或仅在特定事件发生时触发操作。
设备群组管理：管理和控制一组设备，通过自定义Topic实现群组消息的发布和订阅，便于批量操作。
增强安全性：通过使用自定义Topic，实现更细粒度的权限控制和数据隔离，增强系统的安全性。

自定义Topic举例

以下是自定义topic的示例，用于描述设备和应用程序之间的高效数据交互。通过这些自定义topic，设备可以实现更灵活的控制和管理，满足特定的应用需求。

功能	自定义Topic	操作权限	描述信息
灯光控制	/blade/home/${productKey}/${deviceName}/livingroom/light/control	发布	控制客厅灯光开关
灯光控制	/blade/home/${productKey}/${deviceName}/livingroom/light/status	订阅	订阅客厅灯光状态
温度监控	/blade/home/${productKey}/${deviceName}/bedroom/temperature/set	发布	设置卧室温度
温度监控	/blade/home/${productKey}/${deviceName}/bedroom/temperature/reading	订阅	订阅卧室温度数据
安全报警	/blade/home/${productKey}/${deviceName}/security/alarm/set	发布	设置安全报警
安全报警	/blade/home/${productKey}/${deviceName}/security/alarm/status	订阅	订阅安全报警状态

4. Topic 数据格式

属性上报topic: /blade/sys/${productKey}/${deviceName}/thing/event/property/post
属性数据格式

{
  "id": "1",
  "version": "1.0",
  "params": {
    "Brightness": 50,
    "BatteryLevel": 20,
    "AlarmSwitch": 1
  }
}

命令上报topic: /blade/sys/${productKey}/${deviceName}/thing/service/Reboot
注意：其中Reboot为标识符，代表对应命令所指定的物模型标识符
命令数据格式

{
  "id": "1",
  "version": "1.0",
  "params": {
    "input": {"RebootStatus":"true"},
    "output": {"RebootTime":1627584000000},
    "commandName": "重启服务"
  }
}

事件上报topic: /blade/sys/${productKey}/${deviceName}/thing/event/LowBatteyEvent/post
注意：其中LowBatteyEvent为标识符，代表对应事件所指定的物模型标识符
事件数据格式

{
  "id": "1",
  "version": "1.0",
  "params": {
    "output": {"BatteryLevel":20},
    "eventName": "电量低事件",
    "eventType": "alert"
  }
}

完整的请求数据格式：

{
  "id": "123",          // 消息ID号。String类型的字符串，每个消息ID在当前设备中具有唯一性。
  "version": "1.0",     // 协议版本号（可选），目前协议版本号唯一取值为1.0。
  "sys":{               // 扩展功能的参数，其下包含各功能字段。
      "ack":0           // 重要： 0：云端不返回响应数据。1：云端返回响应数据。部分需要回复的消息请确认该参数
  },
  "params": {},         // 参数，可能为 list 列表，也可能为 map 对象。
  "method": ""          // 请求方法，每个 topic 有对应不同的方法。对于 blade-links 来说目前不太重要。
}

完整响应的数据格式：

{
  "id": "123",          // 响应的id，一般跟请求的 id 保持一致。
  "code": 200,          // 响应的 code 编码，200 为成功，其它为失败。
  "data": []            // 响应的数据（可选），具体数据可能为 list 列表或 map 对象。
}

注意：除了 ntp 的 topic 不遵循这个格式，其他的 Topic 均采用这个格式。

数据格式请见如下工具类

/**  
 * 设备通用数据格式  
 */  
@Data  
@JsonInclude(JsonInclude.Include.NON_NULL)  
public class DataReq<T> implements Serializable {  
  
    /**  
     * 消息ID号。uuid，去掉短横线，32位，全局唯一，用于ack或系统消息追踪  
     */  
    private String id;  
  
    /**  
     * 协议版本号，目前协议版本号唯一取值为1.0  
     */  
    private String version;  
  
    /**  
     * 扩展功能的参数，其下包含各功能字段。平台可扩展，或可自行扩展，  
     * 自行扩展的参数需在自定义解析模块自行解析  
     */  
    private SysBean sys;  
  
    /**  
     * 请求方法。  
     */  
    private String method;  
  
    /**  
     * 请求参数。  
     */  
    private T params;  
  
}

/**  
 * 扩展功能  
 */  
@Data  
@NoArgsConstructor  
@AllArgsConstructor  
public class SysBean implements Serializable {  
  
    /**  
     * 不响应 ack  
     */  
    public static final int ACK_NO = 0;  
  
    /**  
     * 响应 ack  
     */  
    public static final int ACK_NEED = 1;  
  
    /**  
     * 构造方法，根据ackNeed的值设置ack字段  
     *  
     * @param ackNeed 是否需要响应ack  
     */  
    public SysBean(boolean ackNeed) {  
        this(ackNeed ? ACK_NEED : ACK_NO);  
    }  
  
    /**  
     * 扩展功能字段，表示是否返回响应数据。  
     * 0：不返回响应数据  
     * 1：返回响应数据  
     */  
    private int ack;  
  
}