设备管理与控制

API 列表

分类	API	说明
设备信息	getDeviceList	获取家庭下的设备列表
	getDeviceInfo	获取设备详细信息
	renameDeviceName	修改设备名称
	getDeviceProperty	获取自定义设备属性
	setDeviceProperty	设置自定义设备属性
	syncDeviceInfo	同步设备信息
	onDeviceOnlineStatusUpdate	注册设备在线状态变更通知事件
	offDeviceOnlineStatusUpdate	注销设备在线状态变更通知事件
	onDeviceInfoUpdated	注册设备信息变化监听
	offDeviceInfoUpdated	注销设备信息变化监听
	registerDeviceListListener	配置监听设备范围
	unregisterDeviceListListener	取消配置监听设备范围
设备控制	queryDps	查询功能点（DP）状态
	publishDps	下发 DP
	publishCommands	下发标准指令集
	onDpDataChange	注册 DP 变更事件
	offDpDataChange	注销 DP 变更事件
MQTT	publishMqttMessage	发送 MQTT 消息
	onMqttMessageReceived	注册 MQTT 消息通道消息上报事件
	offMqttMessageReceived	注销 MQTT 消息通道消息上报事件
	onMqttConnectState	注册 MQTT 连接状态变化事件
	offMqttConnectState	注销 MQTT 连接状态变化事件
	getMqttConnectState	获取 MQTT 连接状态
	connectMqtt	连接 MQTT
	disconnectMqtt	断开 MQTT
设备移除	removeDevice	移除设备
	resetFactory	移除设备并清除数据
	onDeviceRemoved	注册设备移除事件
	offDeviceRemoved	注销设备移除事件
蓝牙能力	getBLEDeviceRSSI	获取蓝牙外设的信号
	connectBLEDevice	连接蓝牙设备
	disconnectBLEDevice	断开蓝牙设备连接
	getBLEOnlineState	获取蓝牙连接状态
	bluetoothCapabilityOfBLEBeacon	是否支持蓝牙 Beacon
	bluetoothIsPowerOn	判断手机蓝牙是否开启
	onBLEConnectStatusChange	注册蓝牙连接状态变更通知事件
	offBLEConnectStatusChange	注销蓝牙连接状态变更通知事件
	onBLEBigDataChannelProgressEventthis	注册蓝牙大数据通道传输进度
	offBLEBigDataChannelProgressEvent	注销蓝牙大数据通道传输进度
	postBLEBigDataChannelWithProgress	大数据通道操作，支持进度反馈
OAT 能力	checkOTAUpgradeStatus	获取设备的固件版本状态
	getOTAInfo	获取设备 OTA 升级状态
	checkOTAUpgrading	检测设备是否在 OTA 升级中
	getOTAUpgradingInfo	获取设备在 OTA 升级中的模组
	getOTAUpgradingDevices	返回正在升级的设备
	onOTAUpgradeStatus	注册 OTA 升级状态变化事件
	offOTAUpgradeStatus	注销 OTA 升级状态变化事件
	upgradeOTAInfo	执行 OTA 升级
网关	startGWActivation	使网关进入配网模式，对其子设备进行配网
	stopGWActivation	停止网关的配网模式
	getSubDeviceInfoList	获取子设备信息
	removeSubDevice	移除网关子设备

设备信息

获取家庭下的设备列表

getDeviceList

入参

属性	类型	必填	说明
homeId	Number	是	家庭 ID

返回数据

res Promise<DeviceListItem[]>

DeviceListItem 类型

名称	类型	说明
id	String	设备 ID
lat	String	设备所在地纬度
lon	String	设备所在地经度
icon	String	设备图标
localKey	String	设备 localKey
name	String	设备名称
online	Boolean	设备是否云端在线
ownerId	String	所属家庭
productId	String	产品 ID（PID）
isSub	Boolean	是否是子设备
timeZone	String	所在时区
updateTime	Number	设备信息更新时间
createTime	Number	设备信息创建时间
activeTime	Number	激活时间
uuid	String	设备 UUID
category	String	所属三级品类
capability	Number	能力值
status	{ code: String; value: any }[]	DP 状态

获取设备详细信息

getDeviceInfo

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise<DeviceInfo> 类型

DeviceInfo 类型

属性	类型	说明
schema	DPSchema[]	产品信息，schema，包括功能定义
dps	Object	设备的 DP 状态，根据 dpid，获取具体的状态值来实现业务逻辑
attribute	Number	产品属性定义，使用二进制位运算的方式进行管理
capability	Number	产品能力值，整体业务逻辑会根据该数据进行划分。设备类型也可以根据该属性进行调整，按二进制位运算的方式进行管理
dpName	Object	自定义 DP 的名称，通常在面板里会使用到
ability	Number	目前业务很少使用，用于区分特殊类型的设备
icon	String	设备图标的 URL
devId	String	设备的唯一 ID
verSw	String	设备固件版本号
isShare	Boolean	是否为分享设备，true 表示是分享设备
bv	String	设备的基线版本号
uuid	String	设备的固件唯一标识
activeTime	Number	设备激活时间戳
devAttribute	Object	设备的业务能力拓展，二进制位的方式进行运算
pcc	String	涂鸦自研蓝牙 Mesh 产品的分类标识
nodeId	String	子设备的短地址
parentId	String	上级节点 ID。子设备或蓝牙 Mesh 设备通常会有该字段，用于内部寻找相关的网关或上级模型，来进行业务处理
category	String	产品的品类
standSchemaModel	Object	标准产品功能集定义模型
productId	String	设备对应的产品 ID
bizAttribute	Number	设备自主上报的能力位
meshId	String	涂鸦自研的蓝牙 Mesh ID
sigmeshId	String	当前设备所属行业属性对应的蓝牙 Mesh ID
meta	Object	设备自定义配置元属性，用于存放业务数据
isLocalOnline	Boolean	本地局域网是否在线
isOnline	Boolean	设备总体在线情况，无论是本地在线，还是云端在线
cloudOnline	Boolean	是否云端在线
name	String	设备名称
groupId	String	群组 ID
dpCodes	Object	标准功能集数据
mac	String	设备的 MAC 地址
localKey	String	设备的 localKey
communicationModes	{pv: String; type: Number}[]	硬件通讯类型
ownerId	Number	设备所属家庭 ID
iconUrl	String	原始属性，可使用图标属性，来获取头像地址
dpsTime	Object	DP 最后一次上报的时间
onlineType	OnlineType	设备通讯通道
capabilities	{id: Number, name: String, short: String}[]	支持的通讯类型
dpsByCode	Object	DP Code => ID 映射集
dpsById	Object	DP ID => Code 映射集
schemaByCode	Object	schema 对象集，key 为 DP 的 Code
virtual	Boolean	是否为虚拟设备
otaInfo	Object	固件信息

DPSchema 说明

属性	类型	说明
id	Number	DP ID
name	String	DP 名称
code	String	DP Code
iconname	String	DP 图标
mode	String	下发上报类型： rw：可下发上报 wr：只下发 ro：只上报
property	Property	DP 配置
type	String	DP 配置类型，取值：obj 和 raw

Property 说明

属性	类型	说明
type	String	DP 类型，包括 bool、value、enum、raw、string 和 bitmap
max	Number	最大值。DP 类型为 value 时，该参数有值
min	Number	最小值。DP 类型为 value 时，该参数有值
scale	Number	倍数。DP 类型为 value 时，该参数有值
step	Number	步进。DP 类型为 value 时，该参数有值
unit	String	单位。DP 类型为 value 时，该参数有值
range	String[]	枚举值范围。DP 类型为 enum 时，该参数有值
maxlength	Number	最大长度。DP 类型为 string 时，该参数有值

修改设备名称

renameDeviceName

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID
name	String	是	设备名称

返回数据

res Promise 类型

获取自定义设备属性

getDeviceProperty

入参

object Object

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise<Objecjt> 类型

属性	类型	说明
properties	Object	自定义的设备属性数据

设置自定义设备属性

setDeviceProperty

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID
code	String	是	属性名称
value	String	是	属性数据

返回数据

res Promise 类型

同步设备信息

syncDeviceInfo

入参

无

返回数据

res Promise 类型

注册设备在线状态变更通知事件

onDeviceOnlineStatusUpdate

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
online	Boolean	在线状态
onlineType	Number	通讯通道： 0：离线 1：Wi-Fi 2：LAN 4：蓝牙 LE 8：Mesh 16：Beacon

返回数据

无

注销设备在线状态变更通知事件

offDeviceOnlineStatusUpdate

入参

Callback Function 类型，格式同 onDeviceOnlineStatusUpdate。

返回数据

无

注册设备信息变化监听

onDeviceInfoUpdated

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
devInfo	DeviceInfo	设备详细信息

DeviceInfo 说明

请参考 getDeviceInfo API。

返回数据

无

注销设备信息变化监听

offDeviceInfoUpdated

入参

Callback Function，格式同 onDeviceInfoUpdated。

返回数据

无

配置监听设备范围

registerDeviceListListener

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceIdList	String[]	设备 ID 列表

返回数据

无

取消配置监听设备范围

unregisterDeviceListListener

入参

Callback Function 类型，格式同 registerDeviceListListener。

返回数据

无

设备控制

查询 DP 状态

queryDps

向设备发起 DP 状态同步。

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID
dpIds	Number[]	否	待同步的 DP

返回数据

res Promise 类型

下发 DP 数据给设备

publishDps

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID
dps	Object	是	待下发的 DP 数据，格式为：{[code]:[value]} 和 {[id]: [value]}

返回数据

res Promise 类型

下发标准指令集

publishCommands

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID
dps	Object	是	待下发的 DP 数据，格式为：{[code]:[value]}

返回数据

res Promise 类型

注册 DP 变更事件

onDpDataChange

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
dps	Object	上报的 DP 数据，格式为：{[dpID]: [value]}
dpsMapCode	Object	上报的 DP 数据，格式为：{[dpCode]: [value]}

返回数据

无

注销 DP 变更事件

offDpDataChange

入参

Callback Function 类型，格式同 onDpDataChange。

返回数据

无

MQTT

发送 MQTT 消息

publishMqttMessage

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID
protocol	NUmber	是	协议号
message	Object	是	消息数据

返回数据

res Promise 类型

注册 MQTT 消息通道消息上报事件

onMqttMessageReceived

用于监听获取 MQTT 消息。

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
message	Object	原始消息体
messageData	Object	消息体
protocol	Number	协议号
topic	String	主题

返回数据

无

注销 MQTT 消息通道消息上报事件

offMqttMessageReceived

入参

Callback Function 类型，格式同 onMqttMessageReceived。

返回数据

无

获取 MQTT 连接状态

getMqttConnectState

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Object 类型

名称	类型	说明
connectState	Number	连接状态 0：断开连接 1：已连接

注册 MQTT 连接状态变化事件

onMqttConnectState

入参

Callback Function 类型

回调函数的入参 data Object

名称	类型	说明
connectState	Number	连接状态 0：断开连接 1：已连接

返回数据

无

注销 MQTT 连接状态变化事件

offMqttConnectState

入参

Callback Function 类型，格式同 onMqttConnectState。

返回数据

无

连接 MQTT

connectMqtt

用于连接 MQTT，一般只需要进行一次连接即可。若 MQTT 为非主动断开，则 SDK 会尝试重连。

入参

params Object 类型：

名称	类型	必填	说明
needReopen	String	否	未连接时，是否强制重连
homeId	String[]	否	家庭 ID 集合
devices	Device[]	是	需要订阅主题的设备 ID 集合

Device 类型结构：

名称	类型	必填	说明
devId	String	是	设备 ID
localKey	String	是	设备 localKey，可在设备信息中获取
pv	String	是	消息协议版本，可在设备信息中获取

返回数据

res Promise 类型

断开 MQTT

disconnectMqtt

入参

无

返回数据

无

设备移除

移除设备

removeDevice

只移除设备，设备数据仍然存在。

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise 类型

移除设备并清除设备数据

resetFactory

入参

params Object 类型

属性	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise 类型

注册设备移除事件

onDeviceRemoved

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID

返回数据

无

注销设备移除事件

offDeviceRemoved

入参

Callback Function，格式同 onDeviceRemoved。

返回数据

无

蓝牙

获取蓝牙外设的信号

getBLEDeviceRSSI

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise<Object> 类型

名称	类型	说明
signal	Number	RSSI 值

连接蓝牙设备

connectBLEDevice

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise 类型

断开蓝牙设备连接

disconnectBLEDevice

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise 类型

获取蓝牙连接状态

getBLEOnlineState

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Object 类型

名称	类型	说明
isOnline	Boolean	是否连接

是否支持蓝牙 Beacon

bluetoothCapabilityOfBLEBeacon

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise<Boolean> 类型

判断手机蓝牙是否开启

bluetoothIsPowerOn

入参

无

返回数据

res Promise<Boolean> 类型

注册蓝牙连接状态变更通知事件

适用于涂鸦生态的设备。

onBLEConnectStatusChange

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
status	String	连接状态 CONNECTING：正在连接 CONNECTED：已连接 CONNECT_BREAK：断开连接

返回数据

无

注销蓝牙连接状态变更通知事件

适用于涂鸦生态的设备。

offBLEConnectStatusChange

入参

Callback Function，格式同 onBLEConnectStatusChange。

返回数据

无

注册蓝牙大数据通道传输进度

适用于涂鸦生态的设备。

onBLEBigDataChannelProgressEvent

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
progress	Number	传输百分比

返回数据

无

注销蓝牙大数据通道传输进度

适用于涂鸦生态的设备。

offBLEBigDataChannelProgressEvent

入参

Callback Function 类型，格式同 onBLEBigDataChannelProgressEvent。

返回数据

无

大数据通道操作，支持进度反馈

postBLEBigDataChannelWithProgress

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID
requestParams	RequestParams	是	建立数据传输所需相关参数

RequestParams 说明

名称	类型	必填	说明
command	String	是	通道操作的具体指令：stop 和 start
type	number	是	要上传的数据类型

返回数据

res Promise 类型

OTA 能力

获取设备的固件版本状态

checkOTAUpgradeStatus

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Object 类型

名称	类型	说明
status	Number	升级状态 0：不需要升级 1：硬件准备就绪 2：升级中 3：升级完成 4：升级异常

获取设备 OTA 模组及当前状态

getOTAInfo

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID

返回数据

res Promise<Object> 类型

名称	类型	说明
moduleList	OTAInfo[]	固件模组信息
upgradeStatus	Number	升级状态 0：不需要升级 1：硬件准备就绪 2：升级中 3：升级完成 4：升级异常

OTAInfo 类型

名称	类型	说明
controlType	Number	升级是否可控 0：升级不可控 1：升级可控
currentVersion	String	当前模组版本
lastUpgradeTime	Number	最近一次更新的时间
moduleDesc	String	模组描述
moduleType	Number	模组类型 0：Wi-Fi 1：蓝牙 2：GPRS
upgradeDesc	String	升级版本的更新描述
upgradeStatus	Number	升级状态 0：不需要升级 1：硬件准备就绪 2：升级中 3：升级完成 4：升级异常
upgradeType	Number	升级方式 0：App 建议升级 1：硬件强制升级 2：App 强制升级 3：App 检测升级
upgradeVersion	String	最新版本号
url	String	资源地址

是否 OTA 升级中

checkOTAUpgrading

检测设备是否在 OTA 升级中，此方法只检测本地状态。

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID
moduleType	Number	否	模组类型 0：Wi-Fi 1：蓝牙 2：GPRS
controlType	Number	否	升级是否可控 0：升级不可控 1：升级可控

返回数据

res Promise<OTAInfo[]> 类型

OTAInfo 类型

名称	类型	说明
controlType	Number	升级是否可控 0：升级不可控 1：升级可控
currentVersion	String	当前模组版本
lastUpgradeTime	Number	最近一次更新的时间
moduleDesc	String	模组描述
moduleType	Number	模组类型 0：Wi-Fi 1：蓝牙 2：GPRS
upgradeDesc	String	升级版本的更新描述
upgradeStatus	Number	升级状态 0：不需要升级 1：硬件准备就绪 2：升级中 3：升级完成 4：升级异常
upgradeType	Number	升级方式 0：App 建议升级 1：硬件强制升级 2：App 强制升级 3：App 检测升级
upgradeVersion	String	最新版本号
url	String	资源地址
progress	Number	升级百分比

获取 OTA 升级中的模组

getOTAUpgradingInfo

入参

params Object

名称	类型	必填	说明
deviceId	String	是	设备 ID
moduleType	Number	否	模组类型 0：Wi-Fi 1：蓝牙 2：GPRS

返回数据

res Promise<OTAInfo[]> 类型

OTAInfo 类型

名称	类型	说明
controlType	Number	升级是否可控 0：升级不可控 1：升级可控
currentVersion	String	当前模组版本
lastUpgradeTime	Number	最近一次更新的时间
moduleDesc	String	模组描述
moduleType	Number	模组类型 0：Wi-Fi 1：蓝牙 2：GPRS
upgradeDesc	String	升级版本的更新描述
upgradeStatus	Number	升级状态 0：不需要升级 1：硬件准备就绪 2：升级中 3：升级完成 4：升级异常
upgradeType	Number	升级方式 0：App 建议升级 1：硬件强制升级 2：App 强制升级 3：App 检测升级
upgradeVersion	String	最新版本号
url	String	资源地址
progress	Number	升级百分比

返回正在升级的设备列表

getOTAUpgradingDevices

入参

无

返回数据

res Promise<Record<String, OTAInfo[]>> 类型

OTAInfo 类型

名称	类型	说明
controlType	Number	升级是否可控 0：升级不可控 1：升级可控
currentVersion	String	当前模组版本
lastUpgradeTime	Number	最近一次更新的时间
moduleDesc	String	模组描述
moduleType	Number	模组类型 0：Wi-Fi 1：蓝牙 2：GPRS
upgradeDesc	String	升级版本的更新描述
upgradeStatus	Number	升级状态 0：不需要升级 1：硬件准备就绪 2：升级中 3：升级完成 4：升级异常
upgradeType	Number	升级方式 0：App 建议升级 1：硬件强制升级 2：App 强制升级 3：App 检测升级
upgradeVersion	String	最新版本号
url	String	资源地址

注册 OTA 升级状态变化事件

onOTAUpgradeStatus

入参

Callback Function 类型

回调函数的入参 data Object 类型

名称	类型	说明
deviceId	String	设备 ID
version	String	版本
status	Number	升级状态
moduleType	Number	模组类型
controlType	Number	升级是否可控 0：升级不可控 1：升级可控
moduleDesc	String	模组描述
upgradeType	Number	升级方式
progress	Number	更新进度百分比

返回数据

无

注销 OTA 升级状态变化事件

offOTAUpgradeStatus

入参

Callback Function 类型，格式同 onOTAUpgradeStatus。

返回数据

无

执行 OTA 升级

upgradeOTAInfo

入参

prams Object 类型

名称	类型	必填	说明
deviceId	String	是	设备 ID
otaInfo	OTAInfo	是	需要升级的模组数据，请使用 getOTAInfo 获取到的模组数据传入

返回数据

res Promise 类型

网关

网关进入配网模式

startGWActivation

使网关进入配网模式，对其子设备进行配网。

入参

params Object 类型

名称	类型	必填	说明
gateway	{gwId: String}	是	网关设备 ID 信息
timeout	Number	是	超时时间，单位：秒

返回数据

res Promise 类型

停止网关配网

stopGWActivation

入参

params Object 类型

名称	类型	必填	说明
gwId	String	是	网关设备 ID

返回数据

res Promise 类型

获取子设备信息

getSubDeviceInfoList

入参

params Object 类型

名称	类型	必填	说明
meshId	String	是	网关设备 ID 或上级节点 ID

返回数据

res Promise<SubDevice[]> 类型

SubDevice 说明

名称	类型	说明
activeTime	Number	设备激活时间
category	String	设备所属品类 Code
icon	String	设备图标
iconUrl	String	设备图标完整地址
devId	String	设备 ID
name	String	设备名称
parentId	String	设备上级节点 ID
isOnline	Boolean	设备总体在线情况，无论是本地在线，还是云端在线
cloudOnlie	Boolean	是否云端在线
productId	String	产品 ID（PID）

移除网关子设备

removeSubDevice

入参

params Object 类型

名称	类型	必填	说明
deviceId	String	是	子设备 ID

返回数据

res Promise 类型