硬件云（公网版）API文档

硬件云（公网版）

硬件云（公网版）API文档

伟最后一次编辑

4 年多前 304

序号	接口名称	接口描述	版本
设备管理（开发者）
1	创建设备	调用该接口在指定产品下注册设备。此接口需要权限：设备开发者	V1.00
2	批量创建设备（随机名称）	调用该接口在指定产品下批量创建多个设备（随机生成设备名）。此接口需要权限：设备开发者	V1.00
3	批量更新设备	调用该接口批量修改设备。此接口需要权限：设备拥有者	V1.00
4	删除设备	调用该接口删除指定设备。此接口需要权限：设备拥有者	V1.00
5	解绑设备	调用该接口解绑设备。此接口需要权限：设备开发者。注：此接口清谨慎使用	V1.00
6	禁用设备	调用该接口禁用设备。此接口需要权限：设备拥有者	V1.00
7	解禁设备	调用该接口解禁设备。此接口需要权限：设备拥有者	V1.00
8	查询设备详情	调用该接口查询指定设备的详细信息。此接口需要权限：设备拥有者	V1.00
9	批量查询设备	调用该接口批量查询设备。此接口需要权限：设备开发者	V1.00
10	批量查询设备状态	调用该接口查看指定设备的运行状态。此接口需要权限：设备拥有者	V1.00
11	查询子设备(分页)	调用该接口查询网关子设备列表(分页)。此接口需要权限：设备开发者	V1.00
12	查询批量申请批次列表	调用该接口查询批量申请设备列表。此接口需要权限：设备开发者	V1.00
13	查询批量申请批次详情	调用该接口查询批量申请设备详情。此接口需要权限：设备开发者	V1.00
14	查询批量申请批次详情(全量)	调用该接口查询批量申请设备详情(全量)。此接口需要权限：设备开发者	V1.00
15	调用设备服务	同步调用服务，最大超时时间为5秒。若5秒内服务器未收到回复，则返回超时错误。此接口需要权限：设备拥有者	V1.00
16	批量调用设备服务	只支持异步调用该接口。此接口需要权限：设备拥有者	V1.00
17	查询设备属性值	调用该接口查询指定设备的属性。此接口需要权限：设备拥有者	V1.00
18	查询设备期望属性值	调用该接口为指定设备批量设置期望属性值。限制说明:只读属性不支持设置期望属性值。一次调用最多可设置10个期望属性值。设备创建后，期望属性值的版本（Version）为0。首次设置期望属性值时，如果指定Version参数，则需指定Version值为0。此接口需要权限：设备拥有者	V1.00
19	设置设备属性值	因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。需设备端SDK成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功。此接口需要权限：设备拥有者	V1.00
20	批量设置设备属性值	调用该接口批量设置设备属性值。此接口需要权限：设备拥有者	V1.00
21	批量查询设备属性历史数据	调用该接口批量查询指定设备的属性上报数据。注：一次调用最多可查询10个属性的历史数据。每个属性最多返回100条数据。仅能查询最近30天内的属性数据此接口需要权限：设备拥有者	V1.00
22	批量设置设备期望属性值	调用该接口为指定设备批量设置期望属性值。限制说明:只读属性不支持设置期望属性值。一次调用最多可设置10个期望属性值。设备创建后，期望属性值的版本（Version）为0。首次设置期望属性值时，如果指定Version参数，则需指定Version值为0。此接口需要权限：设备拥有者	V1.00
23	查询设备属性历史数据	调用该接口查询指定设备的属性记录。仅能查询最近30天内的属性数据。此接口需要权限：设备拥有者	V1.00
24	查询设备服务历史数据	调用该接口查询指定设备的服务记录。仅能查询最近30天内的属性数据。此接口需要权限：设备拥有者	V1.00
25	查询设备事件历史数据	调用该接口查询指定设备的事件记录。此接口需要权限：设备拥有者	V1.00
26	查询设备标签列表	调用该接口查询指定设备的标签列表。此接口需要权限：设备开发者	V1.00
27	全量更新设备标签	调用该接口为指定设备全量更新标签，设备最大标签数为10个。此接口需要权限：设备开发者	V1.00
28	增量更新设备标签	调用该接口为指定设备增量更新标签，产品最大标签数为10个。此接口需要以下功能权限：设备开发者	V1.00
设备管理（用户）
29	批量更新设备	调用该接口批量修改设备。此接口需要权限：设备拥有者	V1.00
30	绑定设备	调用该接口绑定设备。此接口需要以下功能权限：设备用户	V1.00
31	解绑设备	调用该接口解绑设备。此接口需要以下功能权限：设备用户	V1.00
32	批量解绑设备	调用该接口批量解绑设备。此接口需要以下功能权限：设备用户	V1.00
33	批量更新设备备注名称	调用该接口批量修改设备备注名称。此接口需要权限：设备拥有者	V1.00
34	查询设备详情	调用该接口查询指定设备的详细信息。此接口需要以下功能权限：设备用户	V1.00
35	批量查询设备	调用该接口批量批量查询设备。此接口需要以下功能权限：设备用户	V1.00
36	批量查询设备详情	调用该接口批量查询指定设备的详细信息。此接口需要以下功能权限：设备用户	V1.00
37	批量查询设备状态	调用该接口查看指定设备的运行状态。此接口需要权限：设备用户	V1.00
38	查询子设备(分页)	调用该接口查询网关子设备列表(分页)。此接口需要权限：设备用户	V1.00
39	全量更新设备标签	调用该接口为指定设备全量更新标签，设备最大标签数为10个。此接口需要权限：设备用户	V1.00
40	增量更新设备标签	调用该接口为指定设备增量更新标签，产品最大标签数为10个。此接口需要以下功能权限：设备用户	V1.00
41	查询设备标签列表	调用该接口查询指定设备的标签列表。此接口需要权限：设备用户	V1.00
42	查询设备属性值	调用该接口查询指定设备的属性。此接口需要权限：设备用户	V1.00
43	设置设备属性值	因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。需设备端SDK成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功此接口需要权限：设备用户	V1.00
44	批量设置设备属性值	调用该接口批量设置设备属性值。此接口需要权限：设备用户	V1.00
45	批量设置设备期望属性值	调用该接口为指定设备批量设置期望属性值。限制说明:只读属性不支持设置期望属性值。一次调用最多可设置10个期望属性值。设备创建后，期望属性值的版本（Version）为0。首次设置期望属性值时，如果指定Version参数，则需指定Version值为0。此接口需要权限：设备用户	V1.00
46	查询设备期望属性值	调用该接口为指定设备批量设置期望属性值。限制说明:只读属性不支持设置期望属性值。一次调用最多可设置10个期望属性值。设备创建后，期望属性值的版本（Version）为0。首次设置期望属性值时，如果指定Version参数，则需指定Version值为0。此接口需要权限：设备用户	V1.00
47	调用设备服务	同步调用服务，最大超时时间为5秒。若5秒内服务器未收到回复，则返回超时错误。此接口需要权限：设备用户	V1.00
48	批量调用设备服务	只支持异步调用该接口。此接口需要权限：设备用户	V1.00
49	全量更新设备标签	调用该接口为指定设备全量更新标签，设备最大标签数为10个。此接口需要权限：设备用户	V1.00
50	查询设备标签列表	调用该接口查询指定设备的标签列表。此接口需要权限：设备用户	V1.00
产品管理（开发者）
51	查询产品(单个)	根据产品key查询产品详细信息。此接口需要以下功能权限：产品拥有者	V1.00
52	分页查询产品信息	返回产品信息分页数据。此接口需要以下功能权限：产品拥有者	V1.00
53	查询产品标签	根据产品key返回产品标签列表	V1.00
54	全量更新多个产品标签	根据产品key全量更新产品标签信息，产品最大标签数为10个。此接口需要以下功能权限：产品拥有者	V1.00
55	增量更新多个产品标签	根据产品key增量更新产品标签信息，标签值为null即删除标签，产品最大标签数为10个。此接口需要以下功能权限：产品拥有者	V1.00
产品管理（用户）
56	查询产品信息(分页)	返回产品信息分页数据。	V1.00

序号	接口名称	接口描述	版本
基础HAL			V3.2
1	HAL_Free	释放参数ptr指向的一块堆内存, 当传入的参数为NULL时不执行任何操作
2	HAL_GetChipID	获取唯一的芯片ID字符串, 字符串长度不能超过HAL_CID_LEN定义的数值注：该HAL只需要芯片商进行适配，如果用户不是芯片商，该HAL返回空字符串即可
3	HAL_GetDeviceID	获取设备的DeviceID, 用于标识设备单品的ID
4	HAL_GetDeviceName	获取设备的DeviceName, 用于唯一标识单个设备的名字, 三元组之一, 在云端控制台注册得到并烧写到设备中
5	HAL_GetDeviceSecret	获取设备的DeviceSecret, 用于标识单个设备的密钥, 三元组之一, 在云端控制台注册得到并烧写到设备中
6	HAL_GetFirmwareVersion	获取设备的固件版本字符串, 此固件版本号将会用于OTA升级的版本上报。如果设备不准备支持OTA，该函数返回空串即可。
7	HAL_GetModuleID	获取设备的Module ID, 仅用于紧密合作伙伴。该函数用于模组商上报模组型号，其它角色的用户返回空串即可。
8	HAL_GetPartnerID	获取设备的Partner ID, 仅用于紧密合作伙伴。
9	HAL_GetProductKey	获取设备的ProductKey, 用于标识设备的品类, 三元组之一, 在云端控制台注册得到并烧写到设备中
10	HAL_GetProductSecret	获取设备的ProductSecret, 用于标识品类的密钥, 在云端控制台注册得到并烧写到设备中, 在一型一密的场景下将会使用到此字符串
11	HAL_GetTimeStr	获取当前时间字符串
12	HAL_Kv_Del	删除指定KV数据, 删除key对应的KV对数据, 可以通过擦除Flash或修改文件数据的方式实现持久化数据的删除
13	HAL_Kv_Erase_All	擦除所有的KV数据, 可以通过擦除Flash或修改文件数据的方式实现持久化数据的删除
14	HAL_Kv_Get	获取KV数据, 获取key对应的KV对数据, 可以通过读取Flash或读取文件的方式实现持久化数据的读取
15	HAL_Kv_Set	设置KV数据接口, 可通过写flash或写文件的方式实现数据持久化
16	HAL_Malloc	申请一块堆内存
17	HAL_Printf	打印函数, 用于向串口或其它标准输出打印日志或调试信息, 可参考C99的printf()函数实现
18	HAL_Random	随机数函数, 接受一个无符号数作为范围, 返回0到region范围内的一个随机数
19	HAL_Reboot	设备重启, 调用该接口能实现复位功能
20	HAL_SetDeviceName	设置设备的DeviceName, 用于标识设备单品的名字, 三元组之一
21	HAL_SetDeviceSecret	设置设备的DeviceSecret, 用于标识设备单品的密钥, 三元组之一
22	HAL_SetProductKey	设置设备的ProductKey, 用于标识设备的品类, 三元组之一
23	HAL_SetProductSecret	设置设备的ProductSecret, 用于标识品类的密钥, 在一型一密场景中会使用到此字符串
24	HAL_SleepMs	睡眠函数, 使当前执行线程睡眠指定的毫秒数
25	HAL_Snprintf	打印函数, 向内存缓冲区格式化构建一个字符串, 参考C99标准库函数
26	HAL_Srandom	随机数播种函数, 使 HAL_Random 的返回值每个随机序列各不相同, 类似C标准库中的srand
27	HAL_Sys_reboot	系统立即重启
28	HAL_Timer_Create	创建指定名称的定时器, 同时注册用户回调函数和用户数据
29	HAL_Timer_Delete	删除由HAL_Timer_Create()创建的定时器, 释放资源
30	HAL_Timer_Start	启动定时器
31	HAL_Timer_Start	关闭定时器
32	HAL_UptimeMs	获取设备从上电到当前时刻所经过的毫秒数
33	HAL_UTC_Get	获取UTC时间, 数值为从Epoch(1970年1月1日00:00:00 UTC)开始所经过的秒数单位
34	HAL_UTC_Set	设置UTC时间, 设置参数为从Epoch(1970年1月1日00:00:00 UTC)开始所经过的秒数单位
35	HAL_Vsnprintf	格式化输出字符串到指定buffer中, 可参考C标准库的vsnprintf()实现
MQTT连云HAL
36	HAL_SSL_Destroy	销毁由参数handle指定的TLS连接
37	HAL_SSL_Establish	根据指定的服务器网络地址, 服务器端口号和证书文件建立TLS连接, 返回对应的连接句柄
38	HAL_SSL_Read	从指定的TLS连接中读取数据, 此接口为同步接口, 如果在超时时间内读取到参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回
39	HAL_SSL_Write	从指定的TLS连接中写入数据, 此接口为同步接口, 如果在超时时间内写入了参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回
40	HAL_TCP_Destroy	销毁由参数fd指定的TCP连接, 释放资源
41	HAL_TCP_Establish	根据指定的服务器网络地址和端口号建立TCP连接, 并返回对应连接句柄
42	HAL_TCP_Read	从指定的TCP连接中读取数据, 此接口为同步接口, 如果在超时时间内读取到参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回
43	HAL_TCP_Write	从指定的TCP连接中写入数据, 此接口为同步接口, 如果在超时时间内写入了参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回
线程HAL
44	HAL_MutexCreate	创建一个互斥量对象, 返回指向所创建互斥量的指针, 用于同步访问, 对于仅支持单线程应用, 可实现为空函数
45	HAL_MutexDestroy	销毁一个互斥量对象, 释放资源
46	HAL_MutexLock	锁住一个互斥量
47	HAL_MutexUnlock	解锁一个互斥量
48	HAL_SemaphoreCreate	创建一个计数信号量, 此接口实现必须为原子操作, 对于仅支持单线程应用, 可实现为空函数
49	HAL_SemaphoreDestroy	销毁一个由参数sem指定的信号量, 此接口实现必须为原子操作, 此函数无返回值
50	HAL_SemaphorePost	在指定的计数信号量上做自增操作, 解除其它线程的等待, 此接口实现必须为原子操作, 对于仅支持单线程应用, 可实现为空函数
51	HAL_SemaphoreWait	在指定的计数信号量上等待并做自减操作, 对于仅支持单线程应用, 此接口实现必须为原子操作, 可实现为空函数
52	HAL_ThreadCreate	按照指定入参创建一个线程
53	HAL_ThreadDelete	删除指定的线程
54	HAL_ThreadDelete	将指定线程设置为分离状态

序号	接口名称	接口描述	版本
基础HAL接口			v4.x
1	core_sysdep_malloc	释放内存
2	core_sysdep_free	释放内存
3	core_sysdep_time	获取当前时间戳，SDK用于计算差值
4	core_sysdep_sleep	睡眠指定的毫秒数
5	core_sysdep_network_init	创建一个网络会话
6	core_sysdep_network_setopt	配置一个网络会话的连接参数
7	core_sysdep_network_establish	建立一个网络会话，作为MQTT/HTTP等协议的底层承载
8	core_sysdep_network_send	在指定的网络会话上发送
9	core_sysdep_network_deinit	销毁一个网络会话
10	core_sysdep_rand	随机数的生成方法
11	core_sysdep_mutex_init	创建互斥锁
12	core_sysdep_mutex_lock	申请互斥锁
13	core_sysdep_mutex_unlock	释放互斥锁
14	core_sysdep_mutex_deinit	core_sysdep_mutex_deinit
MQTT连云接口
15	aiot_mqtt_init	创建mqtt客户端实例并设置默认参数
16	aiot_mqtt_setopt	设置mqtt连接参数
17	aiot_mqtt_deinit	释放mqtt客户端实例的资源
18	aiot_mqtt_connect	与mqtt服务器建立连接, 同步接口
19	aiot_mqtt_disconnect	与mqtt服务器断开连接但保留客户端实例的资源, 同步接口
20	aiot_mqtt_heartbeat	向mqtt服务器发送PINGREQ报文, 维持连接, 仅在特殊场景使用
21	aiot_mqtt_process	包含定时心跳发送和QoS1消息的重传, 同步接口, 需要用户周期性调用
22	aiot_mqtt_pub	发送一条PUBLISH消息到mqtt服务器, 异步接口, 用于设备上报, 消息QoS为0
23	aiot_mqtt_sub	发送一条SUBSCRIBE消息到mqtt服务器, 异步接口, 用于启动对云端消息的接收
24	aiot_mqtt_unsub	发送一条UNSUBSCRIBE消息到mqtt服务器, 异步接口, 用于停止对云端消息的接收
25	aiot_mqtt_recv	尝试收取mqtt报文并分发给用户的订阅回调函数, 同步接口
物模型接口
26	aiot_dm_init	初始化data-model会话实例
27	aiot_dm_setopt	设置data-model会话参数
28	aiot_dm_send	发送一条data-model消息到物联网平台, 消息类型和消息内容由msg参数决定
29	aiot_dm_deinit	销毁data-model实例, 释放资源
时间同步接口
30	aiot_ntp_init	初始化ntp实例并设置默认参数
31	aiot_ntp_setopt	配置ntp实例
32	aiot_ntp_deinit	释放ntp实例句柄的资源
33	aiot_ntp_send_request	向MQTT服务器发送ntp查询请求
OTA接口
34	aiot_ota_init	创建ota客户端实例并设置默认参数
35	aiot_ota_deinit	销毁ota客户端实例, 回收资源
36	aiot_ota_report_version	用MQTT报文向云平台上报自身设备的固件版本号, 这是云端判断升级是否启动和成功的依据
37	aiot_ota_report_version_ext	用MQTT报文向云平台上报指定设备的固件版本号, 用于网关代理子设备上报的场景
38	aiot_ota_setopt	设置ota连接参数
39	aiot_download_init	创建download客户端实例并设置默认参数
40	aiot_download_deinit	销毁download客户端实例, 回收资源
41	aiot_download_setopt	设置download连接参数
42	aiot_download_report_progress	用MQTT报文向云平台上报下载的进度, 也可以上报升级过程中发生的异常, 例如烧写失败, 网络断开等
43	aiot_download_send_request	向aiot_download_setopt()指定的固件存储服务器, 发起HTTP GET请求, 要求下载一段固件内容
44	aiot_download_recv	从网络上收取来自服务器的固件内容, 然后进入AIOT_DLOPT_RECV_HANDLER选项设置的用户回调, 将下载内容传给用户
子设备接口
45	aiot_subdev_init	初始化subdev实例并设置默认参数。
46	aiot_subdev_setopt	配置subdev实例
47	aiot_subdev_deinit	释放subdev实例句柄的资源。
48	aiot_subdev_send_topo_add	向云端发送添加子设备与网关的拓扑关系的请求。
49	aiot_subdev_send_topo_delete	向云端发送删除子设备与网关的拓扑关系的请求。
50	aiot_subdev_send_topo_get	向云端发送获取子设备与网关的拓扑关系的请求。
51	aiot_subdev_send_batch_login	向云端发送子设备批量登录的请求。
52	aiot_subdev_send_batch_logout	向云端发送子设备批量登出的请求。
53	aiot_subdev_send_sub_register	向云端发送子设备动态注册的请求。
54	aiot_subdev_send_product_register	向云端发送子设备动态注册的请求（可从其他网关抢绑）。

查询数据使用GET方式，新增、修改、删除数据使用POST方式
返回数据统一使用JSON格式，请参考每个API具体说明
访问API出现异常需返回统一错误信息，返回JSON格式和响应码

{
    "utCode":"parameter invalid", //错误码
    "utMsg":"参数非法", //错误说明
    "utService":"iot-cloud-app-service" //API服务提供方
}

错误码说明一览

注：更详细的接口规范请参考：点我查看

基本信息

Path： /device/create

Method： POST

接口描述：调用该接口在指定产品下注册设备。此接口需要权限：设备开发者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	非必须		设备名称,长度为4-32个字符，可以包含英文字母、数字和特殊字符：连字符（-）、下划线（_）、at符号（@）、点号（.）、和英文冒号（:）。	最大长度: 32最小长度: 4
index	integer	非必须		自定义下标,通过维护此字段实现自定义排序	format: int64
nickname	string	非必须		备注名称,长度为4-64个字符，可包含中文汉字、英文字母、数字和下划线（_）。一个中文汉字算2字符。	最大长度: 64最小长度: 4
productKey	string	必须		隶属的产品key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	非必须		设备名称
deviceSecret	string	非必须		设备密钥

基本信息

Path： /device/batchCreate

Method： POST

接口描述：调用该接口在指定产品下批量创建多个设备（随机生成设备名）。此接口需要权限：设备开发者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
count	integer	必须		要创建的设备数量，取值不能大于1,000	format: int32
index	integer	非必须		自定义下标，若传入则批量创建设备的自定义下标将根据此值依次递增	format: int64
productKey	string	必须		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
applyId	integer	非必须		申请批次ID	format: int64

基本信息

Path： /device/batchUpdate

Method： POST

接口描述： 调用该接口批量修改设备。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
updateDeviceInfos	object []	必须			item 类型: object
├─ deviceName	string	必须		设备名称
├─ index	integer	必须		自定义下标	format: int64
├─ productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/delete

Method： POST

接口描述：调用该接口删除指定设备。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/unbind

Method： POST

接口描述：调用该接口解绑设备。此接口需要权限：设备开发者。注：此接口清谨慎使用

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/disableThing

Method： POST

接口描述：调用该接口禁用设备。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/enableThing

Method： POST

接口描述：调用该接口解禁设备。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/get

Method： GET

接口描述：调用该接口查询指定设备的详细信息。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	非必须		设备名称
deviceSecret	string	非必须		设备密钥
gmtActive	string	非必须		设备的激活时间
gmtCreate	string	非必须		创建时间
gmtOnline	string	非必须		设备最近一次上线的时间
imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
index	integer	非必须		自定义下标,通过维护此字段实现自定义排序	format: int64
instanceId	string	非必须		实例ID
ipAddress	string	非必须		设备IP地址
nickname	string	非必须		备注名称
parentDeviceName	string	非必须		父设备名称
parentProductKey	string	非必须		父产品Key
productKey	string	非必须		产品key
productName	string	非必须		产品名称
productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关，4：虚拟子设备
status	string	非必须		设备状态。取值：ONLINE：设备在线。OFFLINE：设备离线。UNACTIVE：设备未激活。DISABLE：设备已禁用。
subDeviceName	string	非必须		子设备名称
subProductKey	string	非必须		子产品Key
tags	object	非必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}
utcActive	string	非必须		设备的激活时间（UTC）
utcCreate	string	非必须		设备的创建时间（UTC）
utcOnline	string	非必须		设备最近一次上线的时间（UTC）

基本信息

Path： /device/list

Method： GET

接口描述：调用该接口批量查询设备。此接口需要权限：设备开发者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	否		设备名称(模糊查询)
networkType	否		联网方式。取值：‘WIFI’：WiFi、‘ETHERNET’：以太网、‘BLUETOOTH’：蓝牙
nickname	否		备注名称
ownerId	否		设备用户Id
pageNumber	否		查询的页码(0..N)
pageSize	否		页大小
productGroup	否		产品分组
productKey	否		产品Key
productName	否		产品名称
productNodeType	否		节点类型，取值：0:普通设备，2：边缘网关，4：虚拟子产品
productNodeTypes	否		查询节点类型集合，取值：0:普通设备，2：边缘网关，4：虚拟子产品
productType	否		产品类型
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
sub	否		是否子设备
tagList[0].tagKey	否		标签键
tagList[0].tagValue	否		标签值
tagsOr	否		多个过滤标签之间是否OR操作。true：使用OR操作，结果为并集。false：使用AND操作，结果为交集。默认为false。

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ deviceName	string	非必须		设备名称
├─ imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
├─ index	integer	非必须		自定义下标,通过维护此字段实现自定义排序	format: int64
├─ lastOnlineTime	string	非必须		设备最近一次上线的时间
├─ networkType	string	非必须		联网方式。取值：'WIFI'：WiFi、'ETHERNET'：以太网、'BLUETOOTH'：蓝牙
├─ nickname	string	非必须		设备备注名称
├─ ownerId	string	非必须		设备用户Id
├─ productGroup	string	非必须		产品分组
├─ productKey	string	非必须		产品Key
├─ productName	string	非必须		产品名称
├─ productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关,4: 虚拟子设备
├─ productType	string	非必须		产品类型
├─ tags	object	非必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}
├─ status	string	非必须		设备状态。取值：ONLINE：设备在线。OFFLINE：设备离线。UNACTIVE：设备未激活。DISABLE：设备已禁用。
├─ sub	boolean	非必须		是否子设备
├─ userId	string	非必须		开发者用户Id
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNumber	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型: string
├─		非必须			format: int32
size	integer	非必须
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /device/batchGetStatus

Method： GET

接口描述：调用该接口查看指定设备的运行状态。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称列表,单次查询最多50个设备,数据类型：list
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
deviceStatusList	object []	非必须		设备状态信息列表	item 类型: object
├─ deviceName	string	非必须		设备名称
├─ lastOnlineTime	string	非必须		最近一次上线时间
├─ status	string	非必须		设备状态

基本信息

Path： /device/querySubDevice

Method： GET

接口描述：调用该接口查询网关子设备列表(分页)。此接口需要权限：设备开发者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
pageNumber	否		查询的页码(0..N)
pageSize	否		页大小
productKey	是		产品key
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
subDeviceName	否		子设备名称

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ deviceName	string	非必须		设备名称
├─ lastOnlineTime	string	非必须		设备最近一次上线的时间
├─ productKey	string	非必须		产品Key
├─ productName	string	非必须		产品名称
├─ status	string	非必须		设备状态。取值： ONLINE：设备在线。OFFLINE：设备离线。UNACTIVE：设备未激活。DISABLE：设备已禁用。
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNumber	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型: string
├─	非必须	非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /device/queryBatchList

Method： GET

接口描述：调用该接口查询批量申请设备列表。此接口需要权限：设备开发者

请求参数

Query

参数名称	是否必须	示例	备注
pageNumber	否		查询的页码(0..N)
pageSize	否		页大小
productKey	否		产品Key,不传则统计所有设备
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ applyId	integer	非必须		申请批次ID	format: int64
├─ count	integer	非必须		申请总数	format: int32
├─ createTime	string	非必须		设备的创建时间
├─ productKey	string	非必须		产品Key
├─ productName	string	非必须		产品名称
├─ status	string	非必须		申请单的处理状态和结果，取值：CHECK：校验。CHECK_SUCCESS：校验成功。CHECK_FAILED：校验失败。CREATE：创建。CREATE_SUCCESS：创建成功。CREATE_FAILED：创建失败。
├─ userId	string	非必须		申请人ID
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNumber	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型: string
├─	非必须	非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /device/queryBatchInfo

Method： GET

接口描述：调用该接口查询批量申请设备详情。此接口需要权限：设备开发者

请求参数

Query

参数名称	是否必须	示例	备注
applyId	是		申请批次ID
pageNumber	否		查询的页码(0..N)
pageSize	否		页大小
productKey	是		产品Key
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ deviceName	string	非必须		设备名称
├─ deviceSecret	string	非必须		设备密钥
├─ productKey	string	非必须		产品Key
├─ status	string	非必须		设备状态。取值：ONLINE：设备在线。OFFLINE：设备离线。UNACTIVE：设备未激活。DISABLE：设备已禁用。
├─ utcActive	string	非必须		设备的激活时间（UTC）
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNumber	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型: string
├─	非必须	非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /device/queryBatchInfoList

Method： GET

接口描述：调用该接口查询批量申请设备详情(全量)。此接口需要权限：设备开发者

请求参数

Query

参数名称	是否必须	示例	备注
applyId	是		申请批次ID

返回数据

名称	类型	是否必须	默认值	备注	其他信息
deviceInfos	object []	非必须		设备信息列表	item 类型: object
├─ deviceName	string	非必须		设备名称
├─ deviceSecret	string	非必须		设备密钥
├─ productKey	string	非必须		产品Key

基本信息

Path： /device/invokeThingService

Method： POST

接口描述：同步调用服务，最大超时时间为5秒。若5秒内服务器未收到回复，则返回超时错误。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
args	string	必须		要启用服务的入参信息，数据格式为JSON String，如， Args={"param1":1}。若此参数为空时，需传入 Args={} 。
deviceName	string	必须		设备名称
identifier	string	必须		服务的标识符。
productKey	string	必须		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
result	string	非必须		同步调用服务，返回的调用结果。异步调用服务，则此参数为空。

基本信息

Path： /device/invokeThingsService

Method： POST

接口描述：只支持异步调用该接口。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
args	string	必须		要启用服务的入参信息，数据格式为JSON String，如， Args={"param1":1}。若此参数为空时，需传入 Args={} 。
deviceName	string []	必须		要设置属性值的设备名称列表,最多支持100个设备	item 类型: string
├─		非必须
identifier	string	必须		服务的标识符。
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/queryDeviceProperty

Method： GET

接口描述：调用该接口查询指定设备的属性。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
propertyDataList	object []	非必须		设备属性信息列表	item 类型: object
├─ dataType	string	非必须		属性格式类型，取值： int：整型。float：单精度浮点型。double：双精度浮点型。enum：枚举型。bool：布尔型。text：字符型。date：时间型（String类型的UTC时间戳，单位是毫秒）。array：数组型。struct：结构体类型。
├─ identifier	string	非必须		属性标识符
├─ name	string	非必须		属性名称
├─ time	string	非必须		属性修改的时间，单位是毫秒。
├─ unit	string	非必须		属性单位
├─ value	string	非必须		属性值

基本信息

Path： /device/queryDesiredProperty

Method： GET

接口描述：调用该接口为指定设备批量设置期望属性值。限制说明:只读属性不支持设置期望属性值。一次调用最多可设置10个期望属性值。设备创建后，期望属性值的版本（Version）为0。首次设置期望属性值时，如果指定Version参数，则需指定Version值为0。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
identifiers	是		要查询期望值的属性的标识符 (identifier) 列表。单次调用，最多能传入10个identifie，如不传入则将返回该设备所有属性的期望值
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
propertyDataList	object []	非必须		设备属性信息列表	item 类型: object
├─ dataType	string	非必须		属性格式类型，取值： int：整型。float：单精度浮点型。double：双精度浮点型。enum：枚举型。bool：布尔型。text：字符型。date：时间型（String类型的UTC时间戳，单位是毫秒）。array：数组型。struct：结构体类型。
├─ identifier	string	非必须		属性标识符
├─ name	string	非必须		属性名称
├─ time	string	非必须		属性修改的时间，单位是毫秒。
├─ unit	string	非必须		属性单位
├─ value	string	非必须		属性值
├─ version	integer	非必须		当前期望属性值的版本号	format: int64

基本信息

Path： /device/setDeviceProperty

Method： POST

接口描述：因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。需设备端SDK成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

参数名称	类型	是否必须	示例	备注	其他信息
deviceName	string	必须		设备名称
identifiers	string	必须		要设置的属性信息，组成为key:value，数据格式为 JSON String。其中key:要设置的属性的标识符（identifier），value:属性值,取值需和您定义的属性的数据类型和取值范围保持一致
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/setDevicesProperty

Method： POST

接口描述：调用该接口批量设置设备属性值。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

参数名称	类型	是否必须	默认值	备注	其他信息
deviceName	strig []	必须		要设置属性值的设备名称列表,最多支持100个设备	item 类型: string
├─		非必须
items	string	必须		要设置的属性信息，组成为key:value，数据格式为 JSON String。其中key: 要设置的属性的标识符（identifier），value:属性值, 取值需和您定义的属性的数据类型和取值范围保持一致
productKey	string	必须		产品Key

返回数据

基本信息

Path： /device/queryPropertiesData

Method： GET

接口描述：调用该接口批量查询指定设备的属性上报数据。注：一次调用最多可查询10个属性的历史数据。每个属性最多返回100条数据。仅能查询最近30天内的属性数据此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
asc	是		返回结果中，属性记录按时间排序的方式。取值： 0：倒序。倒序查询时，StartTime必须大于EndTime。 1：正序。正序查询时，StartTime必须小于EndTime。
deviceName	是		设备名称
endTime	是		属性记录的结束时间。取值为13位毫秒值时间戳。
identifier	是		属性的标识符列表。最大只能同时传入10个属性，数据类型List
pageSize	是		单个属性可返回的数据记录数量。最大值为100。任意一个属性返回的数据记录数量不超过该值。
productKey	是		产品Key
startTime	是		属性记录的开始时间。取值为13位毫秒值时间戳。

返回数据

名称	类型	是否必须	默认值	备注	其他信息
nextTime	integer	非必须		下一页属性记录的起始时间。可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。	format: int64
nextValid	boolean	非必须		是否有下一页属性记录。true表示有，false表示没有。返回NextValid为true时，可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。
propertyDataInfos	object []	非必须		属性信息列表	item 类型: object
├─ identifier	string	非必须		属性标识符
├─ propertyInfoList	object []	非必须		属性数据列表	item 类型: object
├─ time	string	非必须		属性上报时间	format: int64
├─ value	string	非必须		属性值

基本信息

Path： /device/setDesiredProperty

Method： POST

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

参数名称	类型	是否必须	默认值	备注	其他信息
deviceName	strig	必须		要设置属性值的设备名称列表,最多支持100个设备	item 类型: string
├─		非必须
items	string	必须		要设置的属性信息，组成为key:value，数据格式为 JSON String。其中key: 要设置的属性的标识符（identifier），value:属性值, 取值需和您定义的属性的数据类型和取值范围保持一致
productKey	string	必须		产品Key

返回数据

名称	类型	是否必须	备注	其他信息
version	string	非必须	本次设置期望属性值后，期望属性值的当前版本号。

基本信息

Path： /device/queryPropertyData

Method： GET

接口描述：调用该接口查询指定设备的属性记录。仅能查询最近30天内的属性数据。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
asc	是		返回结果中，属性记录按时间排序的方式。取值： 0：倒序。倒序查询时，StartTime必须大于EndTime。 1：正序。正序查询时，StartTime必须小于EndTime。
deviceName	是		设备名称
endTime	是		属性记录的结束时间。取值为13位毫秒值时间戳。
identifier	是		要查询的属性标识符。
pageSize	是		单个属性可返回的数据记录数量。最大值为100。任意一个属性返回的数据记录数量不超过该值。
productKey	是		产品Key
startTime	是		属性记录的开始时间。取值为13位毫秒值时间戳。

返回数据

名称	类型	是否必须	默认值	备注	其他信息
nextTime	integer	非必须		下一页属性记录的起始时间。可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。	format: int64
nextValid	boolean	非必须		是否有下一页属性记录。true表示有，false表示没有。返回NextValid为true时，可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。
queryPropertyDataInfoList	object []	非必须		属性集合	item 类型: object
├─ time	string	非必须		属性上报时间	format: int64
├─ value	string	非必须		属性值

基本信息

Path： /device/queryServiceData

Method： GET

接口描述：调用该接口查询指定设备的服务记录。仅能查询最近30天内的属性数据。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
asc	是		返回结果中，属性记录按时间排序的方式。取值： 0：倒序。1：正序。
deviceName	是		设备名称
endTime	是		属性记录的结束时间。取值为13位毫秒值时间戳。
identifier	否		要查询的属性标识符。
pageSize	是		单个属性可返回的数据记录数量。最大值为100。任意一个属性返回的数据记录数量不超过该值。
productKey	是		产品Key
startTime	是		属性记录的开始时间。取值为13位毫秒值时间戳。

返回数据

名称	类型	是否必须	默认值	备注	其他信息
nextTime	integer	非必须		下一页属性记录的起始时间。可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。	format: int64
nextValid	boolean	非必须		是否有下一页属性记录。true表示有，false表示没有。返回NextValid为true时，可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。
serviceInfoList	object []	非必须		服务记录集合。	item 类型: object
├─ identifier	string	非必须		服务标识符。
├─ inputData	string	非必须		服务的输入参数，map格式的字符串，结构为 key:value。
├─ name	string	非必须		服务名称。
├─ outputData	string	非必须		服务的输出参数，map格式的字符串，结构为 key:value。
├─ time	string	非必须		服务执行的时间。

基本信息

Path： /device/queryEventData

Method： GET

接口描述：调用该接口查询指定设备的事件记录。此接口需要权限：设备拥有者

请求参数

Query

参数名称	是否必须	示例	备注
asc	是		返回结果中，属性记录按时间排序的方式。取值： 0：倒序。1：正序。
deviceName	是		设备名称
endTime	是		属性记录的结束时间。取值为13位毫秒值时间戳。
eventType	否		要查询的事件类型。取值： info：信息。 alert：告警。error：故障。
identifier	否		要查询的属性标识符。
pageSize	是		单个属性可返回的数据记录数量。最大值为100。任意一个属性返回的数据记录数量不超过该值。
productKey	是		产品Key
startTime	是		属性记录的开始时间。取值为13位毫秒值时间戳。

返回数据

名称	类型	是否必须	默认值	备注	其他信息
nextTime	integer	非必须		下一页属性记录的起始时间。可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。	format: int64
nextValid	boolean	非必须		是否有下一页属性记录。true表示有，false表示没有。返回NextValid为true时，可以将NextTime的值作为下次查询的StartTime，继续查询本次查询不显示的数据。
eventInfoList	object []	非必须		事件集合。	item 类型: object
├─ identifier	string	非必须		事件标识符。
├─ inputData	string	非必须		服务的输入参数，map格式的字符串，结构为 key:value。
├─ name	string	非必须		服务名称。
├─ outputData	string	非必须		服务的输出参数，map格式的字符串，结构为 key:value。
├─ time	string	非必须		服务执行的时间。

基本信息

Path： /device/listTags

Method： GET

接口描述：调用该接口查询指定设备的标签列表。此接口需要权限：设备开发者

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
tagMap	object	非必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}

基本信息

Path： /device/fullUpdateTags

Method： POST

接口描述：调用该接口为指定设备全量更新标签，设备最大标签数为10个。此接口需要权限：设备开发者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key
tagMap	object	必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}

返回数据

基本信息

Path： /device/updateTags

Method： POST

接口描述：调用该接口为指定设备增量更新标签，产品最大标签数为10个。此接口需要以下功能权限：设备开发者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key
tagMap	object	必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}

返回数据

基本信息

Path： /deviceOwner/batchUpdate

Method： POST

接口描述：调用该接口批量修改设备。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
updateDeviceInfos	object []	必须			item 类型: object
├─ deviceName	string	必须		设备名称
├─ index	integer	必须		自定义下标	format: int64
├─ productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/bind

Method： POST

接口描述：调用该接口绑定设备。此接口需要以下功能权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
deviceSecret	string	必须		设备密钥
productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/unbind

Method： POST

接口描述：调用该接口解绑设备。此接口需要以下功能权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/batchUnbind

Method： POST

接口描述：调用该接口批量解绑设备。此接口需要以下功能权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceKeys	object []	必须		解绑设备标识列表，单次最大解绑设备数：50	item 类型: object
├─ deviceName	string	必须		设备名称
├─ productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/batchUpdateNickname

Method： POST

接口描述：调用该接口批量修改设备备注名称。此接口需要权限：设备拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
updateDeviceNicknameInfos	object []	必须			item 类型: object
├─ deviceName	string	必须		设备名称
├─ nickname	string	必须		新的备注名称,长度为4-64个字符，可包含中文汉字、英文字母、数字和下划线（_）。一个中文汉字算2字符。	最大长度: 64 最小长度: 4
├─ productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/get

Method： GET

接口描述：调用该接口查询指定设备的详细信息。此接口需要以下功能权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	必须		设备名称
productKey	必须		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	非必须		设备名称
deviceSecret	string	非必须		设备密钥
gmtActive	string	非必须		设备的激活时间
gmtCreate	string	非必须		创建时间
gmtOnline	string	非必须		设备最近一次上线的时间
imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
index	integer	非必须		自定义下标,通过维护此字段实现自定义排序	format: int64
instanceId	string	非必须		实例ID
ipAddress	string	非必须		设备IP地址
nickname	string	非必须		备注名称
parentDeviceName	string	非必须		父设备名称
parentProductKey	string	非必须		父产品Key
productKey	string	非必须		产品key
productName	string	非必须		产品名称
productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关，4：虚拟子设备
status	string	非必须		设备状态。取值： ONLINE：设备在线。OFFLINE：设备离线。UNACTIVE：设备未激活。DISABLE：设备已禁用。
subDeviceName	string	非必须		子设备名称
subProductKey	string	非必须		子产品Key
utcActive	string	非必须		设备的激活时间（UTC）
utcCreate	string	非必须		设备的创建时间（UTC）
utcOnline	string	非必须		设备最近一次上线的时间（UTC）

基本信息

Path： /deviceOwner/list

Method： GET

接口描述：调用该接口批量批量查询设备。此接口需要以下功能权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	否		设备名称(模糊查询)
networkType	否		联网方式。取值： ‘WIFI’：WiFi ‘ETHERNET’：以太网 ‘BLUETOOTH’：蓝牙
nickname	否		备注名称
ownerId	否		设备用户Id
pageNum	否		查询的页码(0..N)
pageSize	否		页大小
productGroup	否		产品分组
productKey	否		产品Key
productName	否		产品名称
productNodeType	否		节点类型，取值：0:普通设备，2：边缘网关，4：虚拟子产品
productNodeTypes	否		查询节点类型集合，取值：0:普通设备，2：边缘网关，4：虚拟子产品
productType	否		产品类型
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
sub	否		是否子设备
tagList[0].tagKey	否		标签键
tagList[0].tagValue	否		标签值
tagsOr	否		多个过滤标签之间是否OR操作。true：使用OR操作，结果为并集。 false：使用AND操作，结果为交集默认为false。

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ deviceName	string	非必须		设备名称
├─ imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
├─ index	integer	非必须		自定义下标,通过维护此字段实现自定义排序	format: int64
├─ lastOnlineTime	string	非必须		设备最近一次上线的时间
├─ networkType	string	非必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
├─ nickname	string	非必须		设备备注名称
├─ ownerId	string	非必须		设备用户Id
├─ productGroup	string	非必须		产品分组
├─ productKey	string	非必须		产品Key
├─ productName	string	非必须		产品名称
├─ productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关,4: 虚拟子设备
├─ productType	string	非必须		产品类型
├─ status	string	非必须		设备状态。取值： ONLINE：设备在线。 OFFLINE：设备离线。 UNACTIVE：设备未激活。 DISABLE：设备已禁用。
├─ sub	boolean	非必须		是否子设备
├─ userId	string	非必须		开发者用户Id
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNum	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型:string
├─		非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /deviceOwner/batchGet

Method： GET

接口描述：调用该接口批量查询指定设备的详细信息。此接口需要以下功能权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	是		设备名称列表,单次查询最多100个设备,数据类型：list
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
	object []	非必须			item 类型: object
├─ deviceName	string	非必须		设备名称
├─ deviceSecret	string	非必须		设备密钥
├─ gmtActive	string	非必须		设备的激活时间
├─ gmtCreate	string	非必须		创建时间
├─ gmtOnline	string	非必须		设备最近一次上线的时间
├─ instanceId	string	非必须		实例ID
├─ ipAddress	string	非必须		设备IP地址
├─ nickname	string	非必须		备注名称
├─ parentDeviceName	string	非必须		父设备名称
├─ parentProductKey	string	非必须		父产品Key
├─ productKey	string	非必须		产品key
├─ productName	string	非必须		产品名称
├─ productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关,4: 虚拟子设备
├─ status	string	非必须		设备状态。取值： ONLINE：设备在线。 OFFLINE：设备离线。 UNACTIVE：设备未激活。 DISABLE：设备已禁用。
├─ subDeviceName	string	非必须		子设备名称
├─ subProductKey	string	非必须		子产品Key
├─ utcActive	string	非必须		设备的激活时间（UTC）
├─ utcCreate	string	非必须		设备的创建时间（UTC）
├─ utcOnline	string	非必须		设备最近一次上线的时间（UTC）

基本信息

Path： /deviceOwner/batchGetStatus

Method： GET

接口描述：调用该接口查看指定设备的运行状态。此接口需要权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	是		设备名称列表,单次查询最多50个设备,数据类型：list
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
deviceStatusList	object []	非必须		设备状态信息列表	item 类型: object
├─ deviceName	string	非必须		设备名称
├─ lastOnlineTime	string	非必须		最近一次上线时间
├─ status	string	非必须		设备状态

基本信息

Path： /deviceOwner/querySubDevice

Method： GET

接口描述：调用该接口查询网关子设备列表(分页)。此接口需要权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	是		设备名称
pageNum	否		查询的页码(0..N)
pageSize	否		页大小
productKey	是		产品Key
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
subDeviceName	否		子设备名称

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ deviceName	string	非必须		设备名称
├─ lastOnlineTime	string	非必须		设备最近一次上线的时间
├─ productKey	string	非必须		产品key
├─ productName	string	非必须		产品名称
├─ status	string	非必须		设备状态。取值： ONLINE：设备在线。 OFFLINE：设备离线。 UNACTIVE：设备未激活。 DISABLE：设备已禁用。
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNum	integer	非必须	查询的页码(0..N)		format: int32
├─ pageSize	integer	非必须	页大小		format: int32
├─ sort	string []	非必须	排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.		item 类型: string
├─		非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /deviceOwner/fullUpdateTags

Method： POST

接口描述：调用该接口为指定设备全量更新标签，设备最大标签数为10个。此接口需要权限：设备用户

请求参数

Headers

名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key
tagMap	object	必须		覆盖更新的标签JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"},

返回数据

基本信息

Path： /deviceOwner/updateTags

Method： POST

接口描述：调用该接口为指定设备增量更新标签，产品最大标签数为10个。此接口需要以下功能权限：设备用户

请求参数

Headers

名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key
tagMap	object	必须		覆盖更新的标签JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"},

返回数据

基本信息

Path： /deviceOwner/listTags

Method： GET

接口描述：调用该接口查询指定设备的标签列表。此接口需要权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	是		设备名称
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
tagMap	object	必须		覆盖更新的标签JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"},

基本信息

Path： /deviceOwner/queryDeviceProperty

Method： GET

接口描述：调用该接口查询指定设备的属性。此接口需要权限：设备用户

请求参数

Query

名称	是否必须	示例	备注
deviceName	是		设备名称
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
propertyDataList	object []	非必须		设备属性信息列表	item 类型: object
├─ dataType	string	非必须		属性格式类型，取值： int：整型。 float：单精度浮点型。 double：双精度浮点型。 enum：枚举型。 bool：布尔型。 text：字符型。 date：时间型（String类型的UTC时间戳，单位是毫秒）。 array：数组型。 struct：结构体类型。
├─ identifier	string	非必须		属性标识符
├─ name	string	非必须		属性名称
├─ time	string	非必须		属性修改的时间，单位是毫秒。
├─ unit	string	非必须		属性单位
├─ value	string	非必须		属性值

基本信息

Path： /deviceOwner/setDeviceProperty

Method： POST

接口描述：因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。需设备端SDK成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功。此接口需要权限：设备用户

请求参数

Headers

名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
items	string	必须		要设置的属性信息，组成为key:value，数据格式为 JSON String。其中key:要设置的属性的标识符（identifier），value:属性值,取值需和您定义的属性的数据类型和取值范围保持一致
productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/setDevicesProperty

Method： POST

接口描述：调用该接口批量设置设备属性值。此接口需要权限：设备用户

请求参数

Headers

名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string []	必须		要设置属性值的设备名称列表,最多支持100个设备	item 类型: string
├─		非必须
items	string	必须		要设置的属性信息，组成为key:value，数据格式为 JSON String。其中key:要设置的属性的标识符（identifier），value:属性值,取值需和您定义的属性的数据类型和取值范围保持一致
productKey	string	必须		产品Key

返回数据

基本信息

Path： /deviceOwner/queryDesiredProperty

Method： GET

接口描述：

调用该接口为指定设备批量设置期望属性值。限制说明:只读属性不支持设置期望属性值。一次调用最多可设置10个期望属性值。设备创建后，期望属性值的版本（Version）为0。首次设置期望属性值时，如果指定Version参数，则需指定Version值为0。此接口需要权限：设备用户

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
identifiers	是		要查询期望值的属性的标识符 (identifier) 列表。单次调用，最多能传入10个identifie，如不传入则将返回该设备所有属性的期望值
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
desiredPropertyDataList	object []	非必须		期望值属性信息列表	item 类型: object
├─ dataType	string	非必须		属性格式类型，取值： int：整型。 float：单精度浮点型。 double：双精度浮点型。 enum：枚举型。 bool：布尔型。 text：字符型。 date：时间型（String类型的UTC时间戳，单位是毫秒）。 array：数组型。 struct：结构体类型。
├─ identifier	string	非必须		属性标识符
├─ name	string	非必须		属性名称
├─ time	string	非必须		属性修改的时间，单位是毫秒。
├─ unit	string	非必须		属性单位
├─ value	string	非必须		属性值
├─ version	integer	非必须		当前期望属性值的版本号	format: int64

基本信息

Path： /deviceOwner/setDesiredProperty

Method： POST

接口描述：

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
items	string	必须		要设置的期望属性值，组成为key:value，key取值为属性的标识符（identifier）,value取值为要设置的期望属性值,数据格式为 JSON String，如{"Power":1}。
productKey	string	必须		产品Key
versions	string	必须		当前期望属性值版本，组成为key:value，key取值为属性的标识符（identifier）,value取值为当前期望属性值的版本号。数据格式为 JSON String，如{"Power":2}。若您不确定当前期望值的版本号，可以不传入版本号，但仍需传入{}

返回数据

名称	类型	是否必须	默认值	备注	其他信息
version	string	非必须		本次设置期望属性值后，期望属性值的当前版本号。

基本信息

Path： /deviceOwner/invokeThingService

Method： POST

接口描述：

同步调用服务，最大超时时间为5秒。若5秒内服务器未收到回复，则返回超时错误。此接口需要权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
args	string	必须		要启用服务的入参信息，数据格式为JSON String，如， Args={"param1":1}。若此参数为空时，需传入 Args={} 。
deviceName	string	必须		设备名称
identifier	string	必须		服务的标识符。
productKey	string	必须		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
result	string	非必须		同步调用服务，返回的调用结果。异步调用服务，则此参数为空。

基本信息

Path： /deviceOwner/invokeThingsService

Method： POST

接口描述：

只支持异步调用该接口。此接口需要权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
args	string	必须		要启用服务的入参信息，数据格式为JSON String，如， Args={"param1":1}。若此参数为空时，需传入 Args={} 。
deviceNames	string []	必须		要设置属性值的设备名称列表,最多支持100个设备	item 类型: string
├─		非必须
identifier	string	必须		服务标识符。
productKey	string	必须		产品key

返回数据

基本信息

Path： /deviceOwner/fullUpdateTags

Method： POST

接口描述：

调用该接口为指定设备全量更新标签，设备最大标签数为10个。此接口需要权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key
tagMap	object	必须		覆盖更新的标签JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"},

Path： /deviceOwner/updateTags

Method： POST

接口描述：

调用该接口为指定设备增量更新标签，产品最大标签数为10个。此接口需要以下功能权限：设备用户

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
productKey	string	必须		产品Key
tagMap	object	必须		增量更新的标签JSON对象。key为标签键,value为标签值，需要删除标签，请将键值设为空值，例：{"tagKey":"tagValue"},

返回数据

基本信息

Path： /deviceOwner/listTags

Method： GET

接口描述：

调用该接口查询指定设备的标签列表。此接口需要权限：设备用户

请求参数

Query

参数名称	是否必须	示例	备注
deviceName	是		设备名称
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
tagMap	object	非必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}

> 返回数据 ```javascript OK ``` ## 增量更新设备标签 > 基本信息

基本信息

Path： /product/get

Method： GET

接口描述：

根据产品key查询产品详细信息。此接口需要以下功能权限：产品拥有者

请求参数

Query

参数名称	是否必须	示例	备注
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
createTime	integer	非必须		产品创建时间	format: int64
dataFormat	integer	非必须		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)	format: int32
description	string	非必须		产品描述
deviceCount	integer	非必须		该产品下的设备数量	format: int64
imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
networkType	string	非必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
parentProductKey	string	非必须		父产品Key
productGroup	string	非必须		产品分组
productKey	string	非必须		产品KEY
productName	string	非必须		产品名称
productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关,4: 虚拟子设备
productStatus	string	非必须		产品状态，枚举值：开发中：DEVELOPMENT_STATUS,已发布：RELEASE_STATUS
productType	string	非必须		产品类型
sub	boolean	非必须		是否子设备
subProductKey	string	非必须		子产品KEY
tagList	object []	非必须		标签列表	item 类型: object
├─ tagKey	string	非必须		标签键
├─ tagValue	string	非必须		标签值
userId	string	非必须		产品所属开发者账号id

基本信息

Path： /product/list

Method： GET

接口描述：

返回产品信息分页数据。此接口需要以下功能权限：产品拥有者

请求参数

Query

参数名称	是否必须	示例	备注
dataFormat	否		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)
description	否		产品描述
networkType	否		联网方式。取值： ‘WIFI’：WiFi ‘ETHERNET’：以太网 ‘BLUETOOTH’：蓝牙
pageNumber	否		查询的页码(0..N)
pageSize	否		页大小
productGroup	否		产品分组
productName	否		产品名称(模糊查询)
productNodeType	否		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关
productType	否		产品类型
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
sub	否		是否子设备
tagList[0].tagKey	否		标签键
tagList[0].tagValue	否		标签值
tagsOr	否		多个过滤标签之间是否OR操作。 true：使用OR操作，结果为并集 false：使用AND操作，结果为交集默认为false

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ createTime	integer	非必须		产品创建时间	format: int64
├─ dataFormat	integer	非必须		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)	format: int32
├─ description	string	非必须		产品描述
├─ imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
├─ networkType	string	非必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
├─ productGroup	string	非必须		产品分组
├─ productKey	string	非必须		产品KEY
├─ productName	string	非必须		产品名称
├─ productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关,4: 虚拟子设备
├─ productType	string	非必须		产品类型
├─ sub	boolean	非必须		是否子设备
├─ tagList	object []	非必须		标签列表	item 类型: object
├─ tagKey	string	非必须		标签键
├─ tagValue	string	非必须		标签值
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNumber	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型: string
├─		非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

基本信息

Path： /product/listTags

Method： GET

接口描述：

根据产品key返回产品标签列表

请求参数

Query

参数名称	是否必须	示例	备注
productKey	是		产品Key

返回数据

名称	类型	是否必须	默认值	备注	其他信息
	object []	非必须			item 类型: object
├─ tagKey	string	非必须		标签键
├─ tagValue	string	非必须		标签值

基本信息

Path：/product/fullUpdateTags

Method： POST

接口描述：

根据产品key全量更新产品标签信息，产品最大标签数为10个。此接口需要以下功能权限：产品拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

body

名称	类型	是否必须	默认值	备注	其他信息
productKey	string	必须		产品KEY
tagList	object []	必须		增量更新产品标签列表，最多10个	item 类型: object
├─ tagKey	string	非必须		标签键
├─ tagValue	string	非必须		标签值

返回数据

基本信息

Path：/product/incrementalUpdateTags

Method： POST

接口描述：

根据产品key增量更新产品标签信息，标签值为null即删除标签，产品最大标签数为10个。此接口需要以下功能权限：产品拥有者

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
productKey	string	必须		产品KEY
tagList	object []	必须		增量更新产品标签列表，最多10个	item 类型: object
├─ tagKey	string	非必须		标签键
├─ tagKey	string	非必须		标签值

返回数据

基本信息

Path：/product/update

Method： POST

接口描述：

根据产品key更新产品信息

请求参数

Headers

参数名称	参数值	是否必须	示例	备注
Content-Type	application/json	是

Body

名称	类型	是否必须	默认值	备注	其他信息
productKey	string	必须		产品KEY
productName	string	非必须		产品名称	最大长度: 30；最小长度: 4
productType	string	非必须		产品类型
productGroup	string	非必须		产品分组
description	string	非必须		产品描述.长度必须在0-100之间	最大长度: 100；最小长度: 0
imageKey	string	非必须		产品图片Key

返回数据

日期	修改描述	作者
2019-09-26	创建文档	姚海明

基本信息

Path：/productUser/list

Method： GET

接口描述：

请求参数

Query

参数名称	是否必须	示例	备注
dataFormat	否		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)
description	否		产品描述
networkType	否		联网方式。取值： ‘WIFI’：WiFi ‘ETHERNET’：以太网 ‘BLUETOOTH’：蓝牙
pageNum	否		查询的页码(0..N)
pageSize	否		页大小
productGroup	否		产品分组
productName	否		产品名称(模糊查询)
productNodeType	否		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关
productType	否		产品类型
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
sub	否		是否子设备
tagList[0].tagKey	否		标签键
tagList[0].tagValue	否		标签值
tagsOr	否		多个过滤标签之间是否OR操作。 true：使用OR操作，结果为并集 false：使用AND操作，结果为交集默认为false

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ createTime	integer	非必须		产品创建时间	format: int64
├─ dataFormat	integer	非必须		数据格式。取值： 0：透传/自定义格式。1：ICA 标准数据格式 (Alink JSON)	format: int32
├─ description	string	非必须		产品描述
├─ imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
├─ networkType	string	非必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
├─ productGroup	string	非必须		产品分组
├─ productKey	string	非必须		产品Key
├─ productName	string	非必须		产品名称
├─ productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关,4: 虚拟子设备
├─ productType	string	非必须		产品类型
├─ sub	boolean	非必须		是否子设备
├─ tagList	object []	非必须		标签列表
├─ tagKey	string	非必须		标签键
├─ tagValue	string	非必须		标签值	item 类型: object
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须			format: int32
numberOfElements	integer	非必须			format: int32
pageable	object	非必须
├─ pageNum	integer	非必须		查询的页码(0..N)	format: int32
├─ pageSize	integer	非必须		页大小	format: int32
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.	item 类型:string
├─		非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int64
totalPages	integer	非必须			format: int32

原型

void HAL_Free(_IN_ void *ptr);

接口说明释放参数ptr指向的一块堆内存, 当传入的参数为NULL时不执行任何操作
参数说明

参数	数据类型	方向	说明
ptr	void *	输入	指向将要释放的堆内存的指针

返回值说明 void

(在3.0.1及以后版本中不需要实现）

原型

char *HAL_GetChipID(_OU_ char cid_str[HAL_CID_LEN]);

接口说明获取唯一的芯片ID字符串, 字符串长度不能超过HAL_CID_LEN定义的数值。注：该HAL只需要芯片商进行适配，如果用户不是芯片商，该HAL返回空字符串即可
参数说明

参数	数据类型	方向	说明
cid_str	char【】	输出	存放芯片ID的字符串缓冲区

返回值说明指向字符串缓冲区的指针

(在2.3.1及以后版本中不需要实现）

原型

int HAL_GetDeviceID(_OU_ char device_id[DEVICE_ID_LEN]);

接口说明获取设备的DeviceID, 用于标识设备单品的ID

参数	数据类型	方向	说明
device_id	char[]	输出	存放`DeviceID`的字符串缓冲区

返回值说明实际获取到的DeviceID字符串长度

原型

int HAL_GetDeviceName(_OU_ char device_name[DEVICE_NAME_LEN]);

接口说明获取设备的DeviceName, 用于唯一标识单个设备的名字, 三元组之一, 在云端控制台注册得到并烧写到设备中
参数说明

参数	数据类型	方向	说明
device_name	char【】	输出	存放`DeviceName`的字符串缓冲区

返回值说明实际获取到的DeviceName字符串长度

原型

int HAL_GetDeviceSecret(_OU_ char device_secret[DEVICE_SECRET_LEN]);

接口说明获取设备的DeviceSecret, 用于标识单个设备的密钥, 三元组之一, 在云端控制台注册得到并烧写到设备中

参数	数据类型	方向	说明
device_secret	char[]	输出	存放`DeviceSecret`的字符串缓冲区

返回值说明实际获取到的DeviceSecret字符串长度

原型

int HAL_GetFirmwareVersion(_OU_ char version[FIRMWARE_VERSION_MAXLEN]);

接口说明获取设备的固件版本字符串, 此固件版本号将会用于OTA升级的版本上报。如果设备不准备支持OTA，该函数返回空串即可。
参数说明

参数	数据类型	方向	说明
version	char[]	输出	存放`FirmwareVersion`的字符串缓冲区

返回值说明实际获取到的FirmwareVersion字符串长度

(在3.0.1+sp1及以后版本中不需要实现）

原型

int HAL_GetModuleID(_OU_ char mid_str[MID_STR_MAXLEN]);

接口说明获取设备的Module ID, 仅用于紧密合作伙伴。该函数用于模组商上报模组型号，其它角色的用户返回空串即可
参数说明

参数	数据类型	方向	说明
mid_str	char[]	输出	存放`Module ID`的字符串缓冲区

返回值说明实际获取到的Module ID字符串长度

(在3.0.1+sp1及以后版本中不需要实现）

原型

int HAL_GetPartnerID(_OU_ char pid_str[PID_STR_MAXLEN]);

接口说明获取设备的Partner ID, 仅用于紧密合作伙伴。
参数说明

参数	数据类型	方向	说明
pid_str	char[]	输出	存放`Partner ID`的字符串缓冲区

返回值说明实际获取到的Partner ID字符串长度

原型

int HAL_GetProductKey(_OU_ char product_key[PRODUCT_KEY_LEN]);

接口说明获取设备的ProductKey, 用于标识设备的品类, 三元组之一, 在云端控制台注册得到并烧写到设备中
参数说明

参数	数据类型	方向	说明
product_key	char[]	输出	存放`ProductKey`的字符串缓冲区

返回值说明实际获取到的ProductKey字符串长度

原型

int HAL_GetProductSecret(_OU_ char product_secret[DEVICE_SECRET_LEN]);

接口说明获取设备的ProductSecret, 用于标识品类的密钥, 在云端控制台注册得到并烧写到设备中, 在一型一密的场景下将会使用到此字符串
参数说明

参数	数据类型	方向	说明
product_secret	char[]	输出	存放`ProductSecret`的字符串缓冲区

返回值说明实际获取到的ProductSecret字符串长度

(在2.3.1及以后版本中不需要实现）

原型

char *HAL_GetTimeStr(_OU_ char *buf, _IN_ int len);

接口说明获取当前时间字符串
参数说明

参数	数据类型	方向	说明
output	uint8_t *	输出	指向时间字符串缓冲区的指针
output_len	uint32_t	输入	字符串缓冲区的字节长度

返回值说明指向时间字符串缓冲区的指针

原型

int HAL_Kv_Del(const char *key);

接口说明删除指定KV数据, 删除key对应的KV对数据, 可以通过擦除Flash或修改文件数据的方式实现持久化数据的删除
参数说明

参数	数据类型	方向	说明
key	const char *	输入	指向key字符串的指针
buffer	void *	输出	指向存放获取数据的指针
buffer_len	int *	输出	指向存放获取

返回值说明

值	说明
0	删除成功
1	删除失败

原型

int HAL_Kv_Erase_All(void);

接口说明擦除所有的KV数据, 可以通过擦除Flash或修改文件数据的方式实现持久化数据的删除
参数说明 void
返回值说明

值	说明
0	删除成功
1	删除失败

原型

int HAL_Kv_Get(const char *key, void *buffer, int *buffer_len);

接口说明获取KV数据, 获取key对应的KV对数据, 可以通过读取Flash或读取文件的方式实现持久化数据的读取
参数说明

参数	数据类型	方向	说明
key	const char *	输入	指向key字符串的指针
buffer	void *	输出	指向存放获取数据的指针
buffer_len	int *	输出	指向存放获取

返回值说明

值	说明
0	删除成功
1	删除失败

原型

int HAL_Kv_Set(const char *key, const void *val, int len, int sync);

接口说明设置KV数据接口, 可通过写flash或写文件的方式实现数据持久化
参数说明

参数	数据类型	方向	说明
key	const char *	输入	指向key字符串的指针
val	const void *	输入	指向待设置数据的指针
len	int	输入	待设置数据的字节长度
sync	int	输入	0: 异步接口. 1: 同步接口

返回值说明

值	说明
0	设置成功
-1	设置失败

原型

void *HAL_Malloc(_IN_ uint32_t size);

接口说明申请一块堆内存
参数说明

参数	数据类型	方向	说明
size	uint32_t	输入	申请的堆内存大小

返回值说明

值	说明
NULL	内存申请失败
!NULL	指向堆内存首地址的指针

原型

void HAL_Printf(_IN_ const char *fmt, ...);

接口说明打印函数, 用于向串口或其它标准输出打印日志或调试信息, 可参考C99的printf()函数实现
参数说明

参数	数据类型	方向	说明
fmt	const char *	输入	格式化字符串
…	可变类型	输入	可变参数列表

返回值说明

void

原型

uint32_t HAL_Random(_IN_ uint32_t region);

接口说明随机数函数, 接受一个无符号数作为范围, 返回0到region范围内的一个随机数
参数说明

参数	数据类型	方向	说明
region	uint32_t	输入	用于指定随机数范围的无符号数

返回值说明

在指定范围的随机数

原型

void HAL_Reboot(void);

接口说明

设备重启, 调用该接口能实现复位功能

参数说明 void

返回值说明 void

原型

int HAL_SetDeviceName(_IN_ char *device_name);

接口说明设置设备的DeviceName, 用于标识设备单品的名字, 三元组之一
参数说明

参数	数据类型	方向	说明
device_name	char *	输出	指向待传入DeviceName字符串的指针

返回值说明

待设置DeviceName字符串的长度

原型

int HAL_SetDeviceSecret(_IN_ char *device_secret);

接口说明设置设备的DeviceSecret, 用于标识设备单品的密钥, 三元组之一
参数说明

参数	数据类型	方向	说明
device_secret	char *	输出	指向待传入DeviceSecret字符串的指针

返回值说明

待设置DeviceSecret字符串的长度

原型

int HAL_SetProductKey(_IN_ char *product_key);

接口说明

设置设备的ProductKey, 用于标识设备的品类, 三元组之一

参数说明

参数	数据类型	方向	说明
product_key	char *	输出	指向待设置ProductKey字符串的指针

返回值说明

待设置ProductKey字符串的长度

原型

int HAL_SetProductSecret(_IN_ char *product_secret);

接口说明

设备的ProductSecret, 用于标识品类的密钥, 在一型一密场景中会使用到此字符串

参数说明

参数	数据类型	方向	说明
product_secret	char *	输出	指向待传入ProductSecret字符串的指针

返回值说明

待设置ProductSecret字符串的长度

原型

void HAL_SleepMs(_IN_ uint32_t ms);

接口说明

睡眠函数, 使当前执行线程睡眠指定的毫秒数

参数说明

参数	数据类型	方向	说明
ms	uint32_t	输出	线程挂起的时间, 单位ms

返回值说明

void

原型

int HAL_Snprintf(_OU_ char *str, _IN_ const int len, _IN_ const char *fmt, ...);

接口说明

打印函数, 向内存缓冲区格式化构建一个字符串, 参考C99标准库函数

参数说明

参数	数据类型	方向	说明
str	char *	输入	指向字符缓冲区的指针
len	int	输入	缓冲区的字符长度
fmt	const char *	输入	格式化字符串
…		输入	可变参数列表

返回值说明

实际写入缓冲区的字符串长度

原型

void HAL_Srandom(_IN_ uint32_t seed);

接口说明

随机数播种函数, 使 HAL_Random 的返回值每个随机序列各不相同, 类似C标准库中的srand

参数说明

参数	数据类型	方向	说明
seed	uint32_t	输入	用于产生新随机序列的种子

返回值说明

void

原型

void HAL_Sys_reboot(void);

接口说明

系统立即重启

参数说明

void

返回值说明

void

原型

void *HAL_Timer_Create(const char *name, void (*func)(void *), void *user_data);

接口说明

创建指定名称的定时器, 同时注册用户回调函数和用户数据

参数说明

参数	数据类型	方向	说明
name	char *	输入	定时器名称字符串
func	void (func)(void )	输入	用户回调函数
user_data	void *	输入	指向用户数据的指针

返回值说明

参数	数据类型
NULL	创建失败
!NULL	创建成功, 返回定时器句柄

原型

int HAL_Timer_Delete(void *timer);

接口说明

删除由HAL_Timer_Create()创建的定时器, 释放资源

参数说明

参数	数据类型	方向	说明
timer	void *	输入	定时器句柄, 此句柄由调用HAL_Timer_Create()时返回

返回值说明

参数	数据类型
0	操作成功
-1	操作失败

原型

int HAL_Timer_Start(void *t, int ms);

接口说明

启动定时器

参数说明

参数	数据类型	方向	说明
timer	void *	输入	定时器句柄, 此句柄由调用HAL_Timer_Create()时返回
ms	int	输入	定时器定时时间, 单位ms

原型

int HAL_Timer_Stop(void *t);

接口说明

关闭定时器

参数说明

参数	数据类型	方向	说明
timer	void *	输入	定时器句柄, 此句柄由调用HAL_Timer_Create()时返回

返回值说明

参数	数据类型
0	操作成功
-1	操作失败

原型

uint64_t HAL_UptimeMs(void);

接口说明

获取设备从上电到当前时刻所经过的毫秒数

参数说明

void

返回值说明

设备从上电到当前时刻所经过的毫秒数

原型

long long HAL_UTC_Get(void);

接口说明

获取设备从上电到当前时刻所经过的毫秒数

参数说明

void

返回值说明单位为ms的UTC时间

单位为ms的UTC时间

原型

void HAL_UTC_Set(long long ms);

接口说明

设置UTC时间, 设置参数为从Epoch(1970年1月1日00:00:00 UTC)开始所经过的秒数单位

参数说明

参数	数据类型	方向	说明
ms	long long	输入	单位为ms的UTC时间

返回值说明

void

原型

int HAL_Vsnprintf(_OU_ char *str, _IN_ const int len, _IN_ const char *fmt, _IN_ va_list ap);

接口说明

格式化输出字符串到指定buffer中, 可参考C标准库的vsnprintf()实现

参数说明

参数	数据类型	方向	说明
str	char *	输出	用于存放写入字符串的buffer
len	const int	输入	允许写入的最大字符串长度
fmt	const char	输入	格式化字符串
ap	va_list	输入	可变参数列表

返回值说明

成功写入的字符串长

原型

int32_t HAL_SSL_Destroy(_IN_ uintptr_t handle);

接口说明

销毁由参数handle指定的TLS连接

参数说明

参数	数据类型	方向	说明
handle	uintptr_t	输入	TLS连接句柄

返回值说明

参数	数据类型
< 0	操作失败
= 0	操作成功

原型

uintptr_t HAL_SSL_Establish(
            _IN_ const char *host,
            _IN_ uint16_t port,
            _IN_ const char *ca_crt,
            _IN_ size_t ca_crt_len);

接口说明

根据指定的服务器网络地址, 服务器端口号和证书文件建立TLS连接, 返回对应的连接句柄

参数说明

参数	数据类型	方向	说明
host	const char	输入	指定的TLS服务器网络地址
port	uint16_t	输入	指定的TLS服务器端口
ca_crt	const char	输入	指向PEM编码的X.509证书的指针
ca_crt_len	size_t	输入	证书字节长度

返回值说明

参数	数据类型
NULL	创建失败
!NULL	创建成功, 返回TLS连接句柄

原型

int32_t HAL_SSL_Read(_IN_ uintptr_t handle, _OU_ char *buf, _OU_ int len, _IN_ int timeout_ms);

接口说明

从指定的TLS连接中读取数据, 此接口为同步接口, 如果在超时时间内读取到参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回

参数说明

参数	数据类型	方向	说明
handle	uintptr_t	输入	TLS连接句柄
buf	char *	输出	指向数据接收缓冲区的指针
len	int	输入	数据接收缓冲区的字节大小
timeout_ms	int	输入	超时时间

返回值说明

参数	数据类型
-2	TLS连接发生错误
-1	TLS连接被远程设备关闭
0	TLS读超时, 且没有接收到任何数据
> 0	TLS读取到的字节数, TLS读取成功

原型

int32_t HAL_SSL_Write(_IN_ uintptr_t handle, _IN_ const char *buf, _IN_ int len, _IN_ int timeout_ms);

接口说明

从指定的TLS连接中写入数据, 此接口为同步接口, 如果在超时时间内写入了参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回

参数说明

参数	数据类型	方向	说明
handle	uintptr_t	输入	TLS连接句柄
buf	char *	输出	指向数据接收缓冲区的指针
len	int	输入	数据接收缓冲区的字节大小
timeout_ms	int	输入	超时时间

返回值说明

参数	数据类型
< 0	TLS连接发生错误
0	TLS写超时, 且没有写入任何数据
> 0	TLS写入的字节数, TLS写入成功

原型

int32_t HAL_TCP_Destroy(_IN_ uintptr_t fd);

接口说明

销毁由参数fd指定的TCP连接, 释放资源

参数说明

参数	数据类型	方向	说明
fd	uintptr_t	输入	TLS连接句柄

返回值说明

参数	数据类型
< 0	操作失败
= 0	操作成功

原型

uintptr_t HAL_TCP_Establish(_IN_ const char *host, _IN_ uint16_t port);

接口说明

根据指定的服务器网络地址和端口号建立TCP连接, 并返回对应连接句柄

参数说明

参数	数据类型	方向	说明
host	const char *	输入	指定TCP服务器的网络地址
port	uint16_t	输入	指定TCP服务器的端口号

返回值说明

参数	数据类型
NULL	TCP连接建立失败
!NULL	TCP连接建立成功, 返回对应的连接句柄

原型

int32_t HAL_TCP_Read(_IN_ uintptr_t fd, _OU_ char *buf, _IN_ uint32_t len, _IN_ uint32_t timeout_ms);

接口说明

从指定的TCP连接中读取数据, 此接口为同步接口, 如果在超时时间内读取到参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回

参数说明

参数	数据类型	方向	说明
fd	uintptr_t	输入	TCP连接句柄
buf	char *	输出	指向数据接收缓冲区的指针
len	int	输入	数据接收缓冲区的字节大小
timeout_ms	int	输入	超时时间

返回值说明

参数	数据类型
-2	TLS连接发生错误
-1	TLS连接被远程设备关闭
0	TLS读超时, 且没有接收到任何数据
> 0	TLS读取到的字节数, TLS读取成功

原型

int32_t HAL_TCP_Write(_IN_ uintptr_t fd, _IN_ const char *buf, _IN_ uint32_t len, _IN_ uint32_t timeout_ms);

接口说明

从指定的TCP连接中写入数据, 此接口为同步接口, 如果在超时时间内写入了参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回

参数说明

参数	数据类型	方向	说明
fd	uintptr_t	输入	TLS连接句柄
buf	char *	输出	指向数据接收缓冲区的指针
len	int	输入	数据接收缓冲区的字节大小
timeout_ms	int	输入	超时时间

返回值说明

参数	数据类型
< 0	TLS连接发生错误
0	TLS写超时, 且没有写入任何数据
> 0	TLS写入的字节数, TLS写入成功

原型

void *HAL_MutexCreate(void);

接口说明

创建一个互斥量对象, 返回指向所创建互斥量的指针, 用于同步访问, 对于仅支持单线程应用, 可实现为空函数

参数说明

void

返回值说明

void

原型

void HAL_MutexDestroy(_IN_ void *mutex);

接口说明

锁住一个互斥量

参数说明

参数	数据类型	方向	说明
mutex	void *	输入	互斥量指针

返回值说明

void

原型

void HAL_MutexLock(_IN_ void *mutex);

接口说明

解锁一个互斥量

参数说明

参数	数据类型	方向	说明
mutex	void *	输入	互斥量指针

返回值说明

void

原型

void HAL_MutexUnlock(_IN_ void *mutex);

接口说明

解锁一个互斥量

参数说明

参数	数据类型	方向	说明
mutex	void *	输入	互斥量指针

返回值说明

void

原型

void *HAL_SemaphoreCreate(void);

接口说明

创建一个计数信号量, 此接口实现必须为原子操作, 对于仅支持单线程应用, 可实现为空函数

参数说明

void

返回值说明

参数	数据类型
NULL	创建失败
!NULL	创建成功, 返回信号量句柄

原型

void HAL_SemaphoreDestroy(_IN_ void *sem);

接口说明

销毁一个由参数sem指定的信号量, 此接口实现必须为原子操作, 此函数无返回值

参数说明

参数	数据类型	方向	说明
sem	void *	输入	信号量指针

返回值说明

void

原型

void HAL_SemaphorePost(_IN_ void *sem);

接口说明

在指定的计数信号量上做自增操作, 解除其它线程的等待, 此接口实现必须为原子操作, 对于仅支持单线程应用, 可实现为空函数

参数说明

参数	数据类型	方向	说明
sem	void *	输入	信号量句柄

返回值说明

void

原型

int HAL_SemaphoreWait(_IN_ void *sem, _IN_ uint32_t timeout_ms);

接口说明

在指定的计数信号量上等待并做自减操作, 对于仅支持单线程应用, 此接口实现必须为原子操作, 可实现为空函数

参数说明

参数	数据类型	方向	说明
sem	void *	输入	信号量句柄
timeout_ms	uint32_t	输入	信号量等待超时时间, 单位ms, 如果参数为PLATFORM_WAIT_INFINITE, 则函数返回只能由获取信号量触发

返回值说明

参数	数据类型
0	函数返回是由信号量触发
-1	函数返回是由超时触发

原型

int HAL_ThreadCreate(
            _OU_ void **thread_handle,
            _IN_ void *(*work_routine)(void *),
            _IN_ void *arg,
            _IN_ hal_os_thread_param_t *hal_os_thread_param,
            _OU_ int *stack_used);

接口说明

按照指定入参创建一个线程

参数说明

参数	数据类型	方向	说明
thread_handle	void **	输出	指向线程句柄变量的指针
work_routine	void (work_routine)(void *)	输入	指向线程执行函数的函数指针
arg	void *	输入	传递给运行程序的单个参数
hal_os_thread_param	hal_os_thread_param_t *	输入	指向线程初始化参数的指针
stack_used	int *	输出	指示平台是否使用栈缓冲区, 0: 未使用. 1: 使用

线程初始化参数定义:

typedef struct _hal_os_thread {
    hal_os_thread_priority_t priority;     /* initial thread priority */
    void                    *stack_addr;   /* thread stack address malloced by caller, use system stack by . */
    size_t                   stack_size;   /* stack size requirements in bytes; 0 is default stack size */
    int                      detach_state; /* 0: not detached state; otherwise: detached state. */
    char                    *name;         /* thread name. */
} hal_os_thread_param_t;

线程优先级定义:

typedef enum {
    os_thread_priority_idle = -3,        /* priority: idle (lowest) */
    os_thread_priority_low = -2,         /* priority: low */
    os_thread_priority_belowNormal = -1, /* priority: below normal */
    os_thread_priority_normal = 0,       /* priority: normal (default) */
    os_thread_priority_aboveNormal = 1,  /* priority: above normal */
    os_thread_priority_high = 2,         /* priority: high */
    os_thread_priority_realtime = 3,     /* priority: realtime (highest) */
    os_thread_priority_error = 0x84,     /* system cannot determine priority or thread has illegal priority */
} hal_os_thread_priority_t;

返回值说明

参数	数据类型
-1	创建失败
0	创建成功

原型

void HAL_ThreadDelete(_IN_ void *thread_handle);

接口说明

删除指定的线程

参数说明

参数	数据类型	方向	说明
thread_handle	void *	输入	线程句柄, NULL表示当前线程

返回值说明

void

原型

void HAL_ThreadDetach(_IN_ void *thread_handle);

接口说明

将指定线程设置为分离状态

参数说明

参数	数据类型	方向	说明
thread_handle	void *	输入	线程句柄, NULL表示当前线程

返回值说明

void

设备的身份认证分为一机一密以及一型一密两种：

一机一密：在设备上烧写设备的ProductKey、DeviceName、DeviceSecret，然后适配相应的HAL并调用SDK提供的连接云端的函数即可，这种方式要求对设备的产线工具进行一定的修改，需要对每个设备烧写不同的DeviceName和DeviceSecret；
一型一密：设备上烧写设备的ProductKey、ProductSecret，每个设备需要具备自己的唯一标识并将该标识预先上传到阿里云IoT物联网平台，然后调用SDK提供的函数连接云端。这种方式每个设备上烧写的信息是固定的ProductKey、ProductSecret

设备厂商需要实现下面的三个HAL，用于让SDK获取设备三元组：

HAL_GetProductKey
HAL_GetDeviceName
HAL_GetDeviceSecret

代码示例：

int main(int argc, char *argv[])
{
    void                   *pclient = NULL;
    int                     res = 0;
    int                     loop_cnt = 0;
    iotx_mqtt_param_t       mqtt_params;

    memset(&mqtt_params, 0x0, sizeof(mqtt_params));
    mqtt_params.handle_event.h_fp = example_event_handle;

    pclient = IOT_MQTT_Construct(&mqtt_params);
    if (NULL == pclient) {
        EXAMPLE_TRACE("MQTT construct failed");
        return -1;
    }
    ...

｝

++注：IOT_MQTT_Construct()将会调用上面提到的HAL_GetProductKey()等三个HAL函数去获取设备的身份信息。++

它工作时, IoT设备端和外界发生网络通信的交互过程是:(简写说明)

PK: ProductKey, 设备品类标识字符串
PS: ProductSecret, 设备品类密钥
DN: DeviceName, 某台设备的标识字符串
DS: DeviceSecret, 某台设备的设备密钥

1.设备使用PK、PS和设备标识（DN）到阿里云物联网获取该设备对应的DS 2.阿里云物联网的动态注册Server将查找该设备的标识（DN）是否在该PK对应的设备列表，如果该设备在列表中则将该设备的DS返回 3.设备收到DS之后，将使用一机一密的方式计算MQTT连接参数以及签名 4.设备使用计算出来的MQTT连接参数连接阿里云物联网平台

注:

1、用户必须将获取的DeviceSecret持久化到设备, 以备后续使用. 若获取的DeviceSecret丢失可能导致设备无法上线等严重后果, 云端服务器不会接受已激活设备重复的动态注册请求
2、使用一型一密功能, 用户必须对每个设备进行预注册, 即在阿里云物联网平台的控制台上传每个设备的DeviceName，并且在控制台上打开对应产品的动态注册功能

一型一密功能的例子程序在 src/dynamic_register/examples/dynreg_example.c, 以下对其逐段讲解要使用一型一密功能, 要包含它的头文件 dynreg_api.h

#include <stdio.h>
#include <string.h>
#include "infra_types.h"
#include "infra_defs.h"
#include "dynreg_api.h"

准备输入参数 region 和出入参结构体 meta

iotx_http_region_types_t region = IOTX_HTTP_REGION_SHANGHAI;
HAL_Printf("dynreg example\n");

memset(&meta,0,sizeof(iotx_dev_meta_info_t));
HAL_GetProductKey(meta.product_key);
HAL_GetProductSecret(meta.product_secret);
HAL_GetDeviceName(meta.device_name);

以上例子程序用 IOTX_CLOUD_REGION_SHANGHAI 代表的华东二站点作为例子, 演示连接上海服务器时候的情况, 另一个入参 meta 其实就是填入设备的 PK/PS/DN 调用一型一密的API获取 DeviceSecret

res = IOT_Dynamic_Register(region, &meta);
if (res < 0) {
    HAL_Printf("IOT_Dynamic_Register failed\n");
    return -1;
}

HAL_Printf("\nDevice Secret: %s\n\n", meta.device_secret);

这个 IOT_Dynamic_Register() 接口就是一型一密功能点唯一提供的用户接口, 若执行成功, 在参数 meta 中将填上从服务器成功获取到的 DeviceSecret

其它（参考上面的图示）

第1步和第2步对应用户接口: IOT_Dynamic_Register()
第3步对应用户接口: IOT_Sign_MQTT()
第4步对应用户接口: IOT_MQTT_Construct() 注：
1、因为当设备获取到DeviceSecret之后再次调用IOT_Dynamic_Register()将会返回失败，因此用户编程时获取到DeviceSecret之后需要将其保存到Flash中；
2、用户的程序在调用IOT_Dynamic_Register()之前应该先调用HAL_GetDeviceSecret()查看设备是否已经获取到了DeviceSecret，如果已经获取到，则无需再次去调用IOT_Dynamic_Register()

原型

1.int32_t IOT_Dynamic_Register(iotx_http_region_types_t region, iotx_dev_meta_info_t *meta);

接口说明根据输入参数中指定的站点区域, 以及productKey和productSecret, 去云端为deviceName指定的设备去云端申请deviceSecret
参数说明

参数	数据类型	方向	说明
region	iotx_http_region_types_t	输入	表示设备将要工作的区域, 例如美西/新加坡/日本/华东2站点等
meta	iotx_dev_meta_info_t *	输入输出	输入的时候带入设备的PK/PS/DN, 输出的时候返回从服务器取到的 DS

阿里云物联网平台支持使用MQTT协议作为IoT设备和平台之间的通信协议，MQTT Client在连接阿里云物联网平台时MQTT的userName、password、clientID需要遵守阿里云IoT物联网平台的规定，物联网平台将会使用这些参数验证设备的合法性。

功能点 dev_sign 提供的就是该签名字段的计算封装, 这个功能称为”设备签名”

如上图所示:

左边的是该模块的输入参数, 三元组和region分别表达设备身份和想要连接的站点所在区域(华东2/日本/美西/新加坡…)
右边的是该模块的返回参数, hostname/port是连接服务器的域名和端口
另外3个则是IoT设备连接云平台时证明自己合法的身份认证信息, 统称为”设备签名信息” 图示正中间的是该模块提供的唯一一个用户接口API

如果需要集成SDK的设备已支持MQTT Client，并且用户打算使用MQTT Topic直接与物联网平台进行通信，并且不使用SDK的其它任何功能，可以调用设备签名API获取MQTT协议连接阿里云物联网平台时需要设置的MQTT参数，然后使用用户自己的MQTT Client去连接阿里云物联网平台。注：用户需要确保MQTT Client的KeepAlive机制正常运行。

设备签名的例子程序在 src/dev_sign/examples/dev_sign_example.c, 以下对其进行逐段讲解要使用 dev_sign 功能, 需包含它的API头文件 dev_sign_api.h

#include "dev_sign_api.h"

从IoT控制台申请到一台新的IoT设备, 记录其三元组

#define EXAMPLE_PRODUCT_KEY     "a1X2bEnP82z"
#define EXAMPLE_PRODUCT_SECRET  "7jluWm1zql7bt8qK"
#define EXAMPLE_DEVICE_NAME     "example1"
#define EXAMPLE_DEVICE_SECRET   "ga7XA6KdlEeiPXQPpRbAjOZXwG8ydgSe"

声明需要用户提供的底层接口功能点 dev_sign 是零依赖的, 不需要用户做任何HAL的适配就可以使用. 这里声明了 HAL_Printf 仅是因为例程可能需要输出字符

/* Implenment this HAL or using "printf" of your own system if you want to print something in example*/
void HAL_Printf(const char *fmt, ...);

准备出入参结构体

int main(int argc, char *argv[])
{
    iotx_mqtt_region_types_t region = IOTX_CLOUD_REGION_SHANGHAI;
    iotx_dev_meta_info_t meta;
    iotx_sign_mqtt_t sign_mqtt;

    memset(&meta,0,sizeof(iotx_dev_meta_info_t));
    memcpy(meta.product_key,EXAMPLE_PRODUCT_KEY,strlen(EXAMPLE_PRODUCT_KEY));
    memcpy(meta.product_secret,EXAMPLE_PRODUCT_SECRET,strlen(EXAMPLE_PRODUCT_SECRET));
    memcpy(meta.device_name,EXAMPLE_DEVICE_NAME,strlen(EXAMPLE_DEVICE_NAME));
    memcpy(meta.device_secret,EXAMPLE_DEVICE_SECRET,strlen(EXAMPLE_DEVICE_SECRET));

准备一个类型为 iotx_dev_meta_info_t 的结构体变量, 把需要计算签名的设备标识信息填入其中即可然后调用 dev_sign 功能点唯一的一个用户接口 IOT_Sign_MQTT(), 计算签名

if (IOT_Sign_MQTT(region,&meta,&sign_mqtt) < 0) {
        return -1; 
    }

结果就在输出参数 sign_mqtt 中, 它是一个 iotx_sign_mqtt_t 类型的结构体变量打印签名结果或者去连MQTT服务器

#if 0   /* Uncomment this if you want to show more information */
    HAL_Printf("sign_mqtt.hostname: %s\n",sign_mqtt.hostname);
    HAL_Printf("sign_mqtt.port    : %d\n",sign_mqtt.port);
    HAL_Printf("sign_mqtt.username: %s\n",sign_mqtt.username);
    HAL_Printf("sign_mqtt.password: %s\n",sign_mqtt.password);
    HAL_Printf("sign_mqtt.clientid: %s\n",sign_mqtt.clientid);
#endif
    }

为了减轻用户对接实现 HAL_Printf 的负担, IOT_Sign_MQTT() 在执行的过程中不会做任何打印动作, 如果想观察结果可打开上述注释

输出参数中的各个成员意义如下:

成员名	含义
sign_mqtt.hostname	可以连接的MQTT服务器域名地址, 根据入参 region 自动计算
sign_mqtt.port	可以连接的MQTT服务器端口号, 根据标准MQTT协议一般是 1883 或者 443
sign_mqtt.username	连接MQTT服务器时将要使用的用户名
sign_mqtt.password	连接MQTT服务器时将要使用的密码, 和用户名一一对应
sign_mqtt.clientid	连接MQTT服务器时标识设备的自定义ID, 服务器对此不做校验, 鉴权通过 username 和 password 进行

原型

int32_t IOT_Sign_MQTT(iotx_mqtt_region_types_t region, iotx_dev_meta_info_t *meta, iotx_sign_mqtt_t *signout);

接口说明用于计算给定的IoT设备身份认证信息, 这些信息统称为它的”签名”, 将在输出参数 signout 中返回
参数说明

参数	数据类型	方向	说明
region	iotx_mqtt_region_types_t	输入	表示设备将要工作的区域, 例如美西/新加坡/日本/华东2站点等
meta	iotx_dev_meta_info_t *	输入	存放设备的标识字符串, 包括 productKey,deviceName 等
signout	iotx_sign_mqtt_t *	输入	存放计算好的签名信息, 包括MQTT服务器地址/端口, 连接时的用户名/密码等

功能点 dev_sign 是零依赖的, 不需要用户做任何开发动作就可以使用, 所以不需要对接HAL接口

用户可以直接通过SDK提供的MQTT API与阿里云物联网平台通信，也即用户可以通过向指定的topic发送消息的方式将数据发送到阿里云物联网平台，也可以通过订阅指定的topic从阿里云物联网平台接收数据，这些topic都是用户自己定义的。直接使用MQTT TOPIC与物联网平台通信的流程示意图如下：

说明：

通过调用 IOT_MQTT_Construct() 接口调用, 建立设备和云平台之间的长连接这个接口是用来向云平台发起连接请求的, 其参数中需要的”签名信息”可以通过 dev_sign 功能中的IOT_Sign_MQTT() 获得连接成功的话, 会返回一个 handle 参数, 这就是连接的句柄, 可用作之后所有MQTT网络接口的入参
通过 IOT_MQTT_Subscribe() 接口调用, 可以向云平台表达设备将接收哪些Topic上的报文
然后进入业务主循环通过 IOT_MQTT_Publish() 或 IOT_MQTT_Publish_Simple(), 可将消息上报到云端IOT_MQTT_Yield()用于接收云端下发的消息, 并调用用户在 IOT_MQTT_Subscribe() 时指定的回调函数，用于对数据进行处理

MQTT上云的例子程序在 src/mqtt/examples/mqtt_example.c, 在”快速体验”一章中已对其进行过逐段的讲解。

函数名	说明
IOT_MQTT_CheckStateNormal	MQTT连接后, 调用此函数检查长连接是否正常
IOT_MQTT_Construct	MQTT实例的构造函数, 入参为iotx_mqtt_param_t结构体, 连接MQTT服务器, 并返回被创建句柄
IOT_MQTT_Destroy	MQTT实例的摧毁函数, 入参为 IOT_MQTT_Construct 创建的句柄
IOT_MQTT_Publish	MQTT会话阶段, 组织一个完整的MQTT Publish报文, 向服务端发送消息发布报文
IOT_MQTT_Publish_Simple	MQTT会话阶段, 组织一个完整的MQTT Publish报文, 向服务端发送消息发布报文,参数中不含结构体等复杂数据类型
IOT_MQTT_Subscribe	MQTT会话阶段, 组织一个完整的MQTT Subscribe报文, 向服务端发送订阅请求
IOT_MQTT_Subscribe_Sync	MQTT会话阶段, 组织一个完整的MQTT Subscribe报文, 向服务端发送订阅请求,并等待应答
IOT_MQTT_Unsubscribeh	MQTT会话阶段, 组织一个完整的MQTT UnSubscribe报文, 向服务端发送取消订阅请求
IOT_MQTT_Yield	MQTT会话阶段, MQTT主循环函数, 内含了心跳的维持, 服务器下行报文的收取等

以下函数为可选实现, 如果希望SDK提供MQTT通道功能, 则需要用户对接

函数名	说明
HAL_UptimeMs	返回设备加电以来到当前时间点过去的毫秒数
HAL_SleepMs	按照入参指定的毫秒数睡眠相应时间
HAL_SSL_Destroy	销毁一个TLS连接, 用于MQTT功能, 加密连接的情况
HAL_SSL_Establish	建立一个TLS连接, 用于MQTT功能, 加密连接的情况
HAL_SSL_Read	从一个TLS连接中读数据, 用于MQTT功能, 加密连接的情况
HAL_SSL_Write	向一个TLS连接中写数据, 用于MQTT功能, 加密连接的情况
HAL_TCP_Destroy	销毁一个TLS连接, 用于MQTT功能
HAL_TCP_Establish	建立一个TCP连接, 包含了域名解析的动作和TCP连接的建立
HAL_TCP_Read	在指定时间内, 从TCP连接读取流数据, 并返回读到的字节数
HAL_TCP_Write	在指定时间内, 向TCP连接发送流数据, 并返回发送的字节数

注: SDK提供的用户API接口都列在 src/mqtt/mqtt_api.h, 可能需要对接的HAL函数都列在src/mqtt/mqtt_wrapper.h, 以代码为准

物模型管理功能是指使用属性/事件/服务的方式对产品支持的能力进行描述，在设备开发时也需要以物模型的方式进行编程下面的讲解中使用了示例代码./src/dev_model/examples/linkkit_example_solo.c 注意：

1.在Linux环境下，用户可通过修改wrappers/os/ubuntu/HAL_OS_linux.c文件中的默认三元组来使用自己在云端控制台创建的设备的身份信息
2.我们在src/dev_model/examples目录下提供了名为model_for_example.json的物模型描述文件，用户可以用自己产品的productkey替换掉该文件中的”productKey”值后，将该物模型文件导入到物联网平台上的产品定义中，这样用户可以快速的参照示例代码来体验基于物模型的编程方式。

属性上报说明用户可以调用IOT_Linkkit_Report()函数来上报属性，属性上报时需要按照云端定义的属性格式使用JSON编码后进行上报。示例中函数user_post_property展示了如何使用IOT_Linkkit_Report进行属性上报（对于异常情况的上报，详见example）:

void user_post_property(void)
{
    static int cnt = 0;
    int res = 0;

    char property_payload[30] = {0};
    HAL_Snprintf(property_payload, sizeof(property_payload), "{\"Counter\": %d}", cnt++);

    res = IOT_Linkkit_Report(EXAMPLE_MASTER_DEVID, ITM_MSG_POST_PROPERTY,
                            (unsigned char *)property_payload, strlen(property_payload));

    EXAMPLE_TRACE("Post Property Message ID: %d", res);
}

注：property_payload = “{\”Counter\”:1}” 即是将属性编码为JSON对象。

当上报属性或者事件时需要云端应答时, 通过IOT_Ioctl对IOTX_IOCTL_RECV_EVENT_REPLY选项进行设置,属性设置说明: 示例代码在回调函数user_property_set_event_handler中获取云端设置的属性值, 并原样将收到的数据发回给云端, 这样可以更新在云端的设备属性值, 用户可在此处对收到的属性值进行处理。注：该回调函数是在example初始化时使用IOT_RegisterCallback注册的ITE_SERVICE_REQUST事件对应的回调函数:

static int user_property_set_event_handler(const int devid, const char *request, const int request_len)
{
    int res = 0;
    user_example_ctx_t *user_example_ctx = user_example_get_ctx();
    EXAMPLE_TRACE("Property Set Received, Devid: %d, Request: %s", devid, request);

    res = IOT_Linkkit_Report(user_example_ctx->master_devid, ITM_MSG_POST_PROPERTY,
                            (unsigned char *)request, request_len);
    EXAMPLE_TRACE("Post Property Message ID: %d", res);

    return 0;
}

在设备端示例程序中, 当收到服务调用请求时, 会进入如下回调函数, 以下代码使用了cJSON来解析服务请求的参数值:

static int user_property_set_event_handler(const int devid, const char *request, const int request_len)
{
static int user_service_request_event_handler(const int devid, const char *serviceid, const int serviceid_len,
                                            const char *request, const int request_len,
                                            char **response, int *response_len)
{
    int add_result = 0;
    cJSON *root = NULL, *item_number_a = NULL, *item_number_b = NULL;
    const char *response_fmt = "{\"Result\": %d}";

    EXAMPLE_TRACE("Service Request Received, Service ID: %.*s, Payload: %s", serviceid_len, serviceid, request);

    /* Parse Root */
    root = cJSON_Parse(request);
    if (root == NULL || !cJSON_IsObject(root)) {
        EXAMPLE_TRACE("JSON Parse Error");
        return -1;
    }

    if (strlen("Operation_Service") == serviceid_len && memcmp("Operation_Service", serviceid, serviceid_len) == 0) {
        /* Parse NumberA */
        item_number_a = cJSON_GetObjectItem(root, "NumberA");
        if (item_number_a == NULL || !cJSON_IsNumber(item_number_a)) {
            cJSON_Delete(root);
            return -1;
        }
        EXAMPLE_TRACE("NumberA = %d", item_number_a->valueint);

        /* Parse NumberB */
        item_number_b = cJSON_GetObjectItem(root, "NumberB");
        if (item_number_b == NULL || !cJSON_IsNumber(item_number_b)) {
            cJSON_Delete(root);
            return -1;
        }
        EXAMPLE_TRACE("NumberB = %d", item_number_b->valueint);

        add_result = item_number_a->valueint + item_number_b->valueint;

        /* Send Service Response To Cloud */
        *response_len = strlen(response_fmt) + 10 + 1;
        *response = (char *)HAL_Malloc(*response_len);
        if (*response == NULL) {
            EXAMPLE_TRACE("Memory Not Enough");
            return -1;
        }
        memset(*response, 0, *response_len);
        HAL_Snprintf(*response, *response_len, response_fmt, add_result);
        *response_len = strlen(*response);
    }

    cJSON_Delete(root);
    return 0;
}
}

示例中使用 IOT_Linkkit_TriggerEvent 上报事件. 其中展示了如何使用IOT_Linkkit_Report进行事件上报（对于异常情况的上报，详见example:

void user_post_event(void)
{
    int res = 0;
    char *event_id = "HardwareError";
    char *event_payload = "{\"ErrorCode\": 0}";

    res = IOT_Linkkit_TriggerEvent(EXAMPLE_MASTER_DEVID, event_id, strlen(event_id),
                                event_payload, strlen(event_payload));
    EXAMPLE_TRACE("Post Event Message ID: %d", res);
}

上报属性时, 属性ID和值以JSON格式的形式放在IOT_Linkkit_Report()的payload中, 不同数据类型以及多个属性的格式示例如下:

/* 整型数据 */
char *payload = "{\"Brightness\":50}";

/* 浮点型数据上报 */
char *payload = "{\"Temperature\":11.11}";

/* 枚举型数据上报 */
char *payload = "{\"WorkMode\":2}";

/* 布尔型数据上报, 在物模型定义中, 布尔型为整型, 取值为0或1, 与JSON格式的整型不同 */
char *payload = "{\"LightSwitch\":1}";

/* 字符串数据上报 */
char *payload = "{\"Description\":\"Amazing Example\"}";

/* 时间型数据上报, 在物模型定义中, 时间型为字符串 */
char *payload = "{\"Timestamp\":\"1252512000\"}";

/* 复合类型属性上报, 在物模型定义中, 符合类型属性为JSON对象 */
char *payload = "{\"RGBColor:{\"Red\":11,\"Green\":22,\"Blue\":33}\"}";

/* 多属性上报, 如果需要上报以上各种数据类型的所有属性, 将它们放在一个JSON对象中即可 */
char *payload = "{\"Brightness\":50,\"Temperature\":11.11,\"WorkMode\":2,\"LightSwitch\":1,\"Description\":\"Amazing Example\",\"Timestamp\":\"1252512000\",\"RGBColor:{\"Red\":11,\"Green\":22,\"Blue\":33}\"}";

/* 属性payload准备好以后, 就可以使用如下接口进行上报了 */
IOT_Linkkit_Report(devid, ITM_MSG_POST_PROPERTY, payload, strlen(payload));

上报事件时, 与上报属性的区别是, 事件ID需要单独拿出来, 放在IOT_Linkkit_TriggerEvent()的eventid中, 而事件的上报内容, 也就是物模型定义中事件的输出参数, 则使用与上报属性相同的格式进行上报, 示例如下:

/* 事件ID为Error, 其输出参数ID为ErrorCode, 数据类型为枚举型 */
char *eventid = "Error";
char *payload = "{\"ErrorCode\":0}";

/* 事件ID为HeartbeatNotification, 其输出参数有2个. 第一个是布尔型参数ParkingState, 第二个是浮点型参数VoltageValue */
char *eventid = "HeartbeatNotification";
char *payload = "{\"ParkingState\":1,\"VoltageValue\":3.0}";

/* 事件payload准备好以后, 就可以使用如下接口进行上报了 */
IOT_Linkkit_TriggerEvent(devid, event_id, strlen(event_id), payload, strlen(payload));

/* 从上面的示例可以看出, 当事件的输出参数有多个时, payload的格式与多属性上报是相同的 */

注意: 虽然物模型编程的 API 并未返回 MQTT 编程接口 IOT_MQTT_XXX() 所需要的 pClient 参数, 但基于MQTT Topic进行数据收发仍可和物模型编程混用

所有MQTT数据收发的接口, 第1个参数都可接受参数 0 作为输入, 表示 “使用当前唯一的MQTT通道进行数据收发等操作”, 包括IOT_MQTT_ConstructIOT_MQTT_DestroyIOT_MQTT_YieldIOT_MQTT_CheckStateNormalIOT_MQTT_SubscribeIOT_MQTT_UnsubscribeIOT_MQTT_PublishIOT_MQTT_Subscribe_SyncIOT_MQTT_Publish_Simple
比如要在使用物模型编程API的程序代码段落中表示对某个Topic进行订阅, 可以用

IOT_MQTT_Subscribe(0, topic_request, IOTX_MQTT_QOS0, topic_callback, topic_context);

比如要在使用物模型编程API的程序代码段落中表示在某个Topic进行发布(数据上报), 可以用

IOT_MQTT_Publish_Simple(0, topic, IOTX_MQTT_QOS0, payload, payload_len);

函数名	说明
IOT_Linkkit_Open	创建本地资源, 在进行网络报文交互之前, 必须先调用此接口, 得到一个会话的句柄
IOT_Linkkit_Connect	对主设备/网关来说, 将会建立设备与云端的通信. 对于子设备来说, 将向云端注册该子设备(若需要), 并添加主子设备拓扑关系
IOT_Linkkit_Yield	若SDK占有独立线程, 该函数只将接收到的网络报文分发到用户的回调函数中, 否则表示将CPU交给SDK让其接收网络报文并将消息分发到用户的回调函数中
IOT_Linkkit_Close	若入参中的会话句柄为主设备/网关, 则关闭网络连接并释放SDK为该会话所占用的所有资源
IOT_Linkkit_TriggerEvent	向云端发送事件报文, 如错误码, 异常告警等
IOT_Linkkit_Report	向云端发送没有云端业务数据下发的上行报文, 包括属性值/设备标签/二进制透传数据/子设备管理等各种报文
IOT_Linkkit_Query	向云端发送存在云端业务数据下发的查询报文, 包括OTA状态查询/OTA固件下载/子设备拓扑查询/NTP时间查询等各种报文
IOT_RegisterCallback	对SDK注册事件回调函数, 如云端连接成功/失败, 有属性设置/服务请求到达, 子设备管理报文答复等
IOT_Ioctl

void *core_sysdep_malloc(uint32_t size, char *name)

接口说明申请内存
参数说明

参数	数据类型	说明
size	uint32_t	申请内存大小
name	char*	别名

返回值说明

void*

void core_sysdep_free(void *ptr)

接口说明释放内存
参数说明

参数	数据类型	说明
ptr	void*	释放内存的地址

返回值说明

void

uint64_t core_sysdep_time(void)

接口说明获取当前时间戳
参数说明

参数	数据类型	说明
void	void	无

返回值说明

返回时间戳

void core_sysdep_sleep(uint64_t time_ms)

接口说明睡眠毫秒级
参数说明

参数	数据类型	说明
time_ms	uint64_t	毫秒

返回值说明

void

void *core_sysdep_network_init(void)

接口说明创建一个网络会话
参数说明

参数	数据类型	说明
void	void	无

返回值说明

网络会话句柄

int32_t core_sysdep_network_setopt(void *handle, core_sysdep_network_option_t option, void *data)

接口说明配置一个网络会话的连接参数
参数说明

参数	数据类型	说明
handle	void*	网络会话句柄
option	core_sysdep_network_option_t	网络连接参数
data	void*	网络连接参数的配置数据

返回值说明