硬件云（私网版）API文档

硬件云（私网版）

硬件云（私网版）API文档

姚智聪最后一次编辑

接近 4 年前 230

序号	接口名称	接口描述	版本
产品管理
1	产品发布	POST: /product/release	V1.00.00.00
2	撤销产品发布	POST: /product/cancelRelease	V1.00
3	创建产品	POST: /product/create	V1.00.00.00
4	删除产品	POST: /product/delete	V1.00.00.00
5	更新产品	POST: /product/update	V1.00.00.00
6	查询产品(单个)	GET: /product/get	V1.00.00.00
7	分页查询产品信息	GET: /product/query	V1.00.00.00
8	查询产品标签	GET: /product/listTags	V1.00.00.00
9	增量更新多个产品标签 P	POST: /product/incrementalUpdateTags	V1.00.00.00
10	全量更新多个产品标签	POST: /product/fullUpdateTags	V1.00.00.00
设备管理
11	查询设备属性值	GET: /device/queryDeviceProperty	V1.00.00.00
12	创建设备	POST: /device/create	V1.00.00.00
13	批量创建设备（随机名称）	POST: /device/batchCreate	V1.00.00.00
14	批量查询设备	GET: /device/list	V1.00.00.00
15	更新设备	POST: /device/update	V1.00.00.00
16	查询批量申请批次列表	GET: /device/queryBatchList	V1.00.00.00
17	查询批量申请批次详情	GET: /device/queryBatchInfo	V1.00.00.00
18	查询设备事件历史数据	GET: /device/queryEventData	V1.00.00.00
19	删除设备	POST: /device/delete	V1.00.00.00
20	查询设备属性历史数据	GET: /device/queryPropertyData	V1.00.00.00
21	查询设备服务历史数据	GET: /device/queryServiceData	V1.00.00.00
22	查询设备详情	GET: /device/get	V1.00.00.00
23	禁用设备	POST: /device/disableThing	V1.00.00.00
24	获取设备的统计数量	GET: /device/queryStatistics	V1.00.00.00
25	解禁设备	POST: /device/enableThing	V1.00.00.00
26	设置设备属性值	POST: /device/setDeviceProperty	V1.00.00.00
27	调用设备服务	POST: /device/invokeThingService	V1.00.00.00
分组管理
28	创建设备分组	POST: /group/create	V1.00.00.00
29	删除设备分组	POST: /group/delete	V1.00.00.00
30	更新设备分组	POST: /group/update	V1.00.00.00
31	查询设备分组(单个)	GET: /group/get	V1.00.00.00
32	查询设备分组(分页)	GET: /group/query	V1.00.00.00
33	设备分组添加设备(批量)	POST: /group/batchAddDevice	V1.00.00.00
34	设备分组移除设备(批量)	POST: /group/batchRemoveDevice	V1.00.00.00

序号	接口名称	接口描述	版本
基础HAL
1	HAL_Free	释放参数ptr指向的一块堆内存, 当传入的参数为NULL时不执行任何操作	V1.00.00.00
2	HAL_Malloc	申请一块堆内存	V1.00.00.00
3	HAL_Printf	打印函数, 用于向串口或其它标准输出打印日志或调试信息, 可参考C99的printf()函数实现	V1.00.00.00
4	HAL_Random	随机数函数, 接受一个无符号数作为范围, 返回0到region范围内的一个随机数	V1.00.00.00
5	HAL_SleepMs	睡眠函数, 使当前执行线程睡眠指定的毫秒数	V1.00.00.00
6	HAL_Snprintf	打印函数, 向内存缓冲区格式化构建一个字符串, 参考C99标准库函数	V1.00.00.00
7	HAL_Srandom	随机数播种函数, 使 HAL_Random 的返回值每个随机序列各不相同, 类似C标准库中的srand	V1.00.00.00
8	HAL_UptimeMs	获取设备从上电到当前时刻所经过的毫秒数	V1.00.00.00
9	HAL_Vsnprintf	格式化输出字符串到指定buffer中, 可参考C标准库的vsnprintf()实现	V1.00.00.00
线程HAL
10	HAL_MutexCreate	创建一个互斥量对象, 返回指向所创建互斥量的指针, 用于同步访问, 对于仅支持单线程应用, 可实现为空函数	V1.00.00.00
11	HAL_MutexDestroy	销毁一个互斥量对象, 释放资源	V1.00.00.00
12	HAL_MutexLock	锁住一个互斥量	V1.00.00.00
13	HAL_MutexUnlock	解锁一个互斥量	V1.00.00.00
14	HAL_SemaphoreCreate	创建一个计数信号量, 此接口实现必须为原子操作, 对于仅支持单线程应用, 可实现为空函数	V1.00.00.00
15	HAL_SemaphoreDestroy	销毁一个由参数sem指定的信号量, 此接口实现必须为原子操作, 此函数无返回值	V1.00.00.00
16	HAL_SemaphorePost	在指定的计数信号量上做自增操作, 解除其它线程的等待, 此接口实现必须为原子操作, 对于仅支持单线程应用, 可实现为空函数	V1.00.00.00
17	HAL_SemaphoreWait	在指定的计数信号量上等待并做自减操作, 对于仅支持单线程应用, 此接口实现必须为原子操作, 可实现为空函数	V1.00.00.00
18	HAL_ThreadCreate	按照指定入参创建一个线程	V1.00.00.00
19	HAL_ThreadDelete	删除指定的线程	V1.00.00.00
20	HAL_ThreadDelete	将指定线程设置为分离状态	V1.00.00.00
产品设备HAL
21	HAL_GetDeviceName	获取设备的DeviceName, 用于唯一标识单个设备的名字, 三元组之一, 在云端控制台注册得到并烧写到设备中	V1.00.00.00
22	HAL_GetDeviceSecret	获取设备的DeviceSecret, 用于标识单个设备的密钥, 三元组之一, 在云端控制台注册得到并烧写到设备中	V1.00.00.00
23	HAL_GetFirmwareVersion	获取设备的固件版本字符串, 此固件版本号将会用于OTA升级的版本上报。如果设备不准备支持OTA，该函数返回空串即可。	V1.00.00.00
24	HAL_GetProductKey	获取设备的ProductKey, 用于标识设备的品类, 三元组之一, 在云端控制台注册得到并烧写到设备中	V1.00.00.00
25	HAL_GetProductSecret	获取设备的ProductSecret, 用于标识品类的密钥, 在云端控制台注册得到并烧写到设备中, 在一型一密的场景下将会使用到此字符串	V1.00.00.00
26	HAL_SetDeviceName	设置设备的DeviceName, 用于标识设备单品的名字, 三元组之一	V1.00.00.00
27	HAL_SetDeviceSecret	设置设备的DeviceSecret, 用于标识设备单品的密钥, 三元组之一	V1.00.00.00
28	HAL_SetProductKey	设置设备的ProductKey, 用于标识设备的品类, 三元组之一	V1.00.00.00
29	HAL_SetProductSecret	设置设备的ProductSecret, 用于标识品类的密钥, 在一型一密场景中会使用到此字符串	V1.00.00.00
存储HAL
30	HAL_Kv_Del	删除指定KV数据, 删除key对应的KV对数据, 可以通过擦除Flash或修改文件数据的方式实现持久化数据的删除	V1.00.00.00
31	HAL_Kv_Get	获取KV数据, 获取key对应的KV对数据, 可以通过读取Flash或读取文件的方式实现持久化数据的读取	V1.00.00.00
32	HAL_Kv_Set	设置KV数据接口, 可通过写flash或写文件的方式实现数据持久化	V1.00.00.00
TCP HAL
33	HAL_TCP_Destroy	销毁由参数fd指定的TCP连接, 释放资源	V1.00.00.00
34	HAL_TCP_Establish	根据指定的服务器网络地址和端口号建立TCP连接, 并返回对应连接句柄	V1.00.00.00
35	HAL_TCP_Read	从指定的TCP连接中读取数据, 此接口为同步接口, 如果在超时时间内读取到参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回	V1.00.00.00
36	HAL_TCP_Write	从指定的TCP连接中写入数据, 此接口为同步接口, 如果在超时时间内写入了参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回	V1.00.00.00
SSL/TLS HAL
37	HAL_SSL_Destroy	销毁由参数handle指定的TLS连接	V1.00.00.00
38	HAL_SSL_Establish	根据指定的服务器网络地址, 服务器端口号和证书文件建立TLS连接, 返回对应的连接句柄	V1.00.00.00
39	HAL_SSL_Read	从指定的TLS连接中读取数据, 此接口为同步接口, 如果在超时时间内读取到参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回	V1.00.00.00
40	HAL_SSL_Write	从指定的TLS连接中写入数据, 此接口为同步接口, 如果在超时时间内写入了参数len指定长度的数据则立即返回, 否则在超时时间到时才解除阻塞返回	V1.00.00.00
物模型编程
41	IOT_Linkkit_Open	创建本地资源，在进行网络报文交互之前，必须先调用此接口，得到一个会话的句柄	V1.00.00.00
42	IOT_Linkkit_Connect	对设备来说，将会建立设备与云端的通信	V1.00.00.00
43	IOT_Linkkit_Yield	若SDK占有独立线程，该函数只将接收到的网络报文分发到用户的回调函数中，否则表示将CPU交给SDK让其接收网络报文并将消息分发到用户的回调函数中	V1.00.00.00
44	IOT_Linkkit_Close	若入参中的会话句柄为主设备/网关，则关闭网络连接并释放SDK为该会话所占用的所有资源	V1.00.00.00
45	IOT_Linkkit_TriggerEvent	向云端发送事件报文、错误码、异常告警等	V1.00.00.00
46	IOT_Linkkit_Report	向云端发送没有云端业务数据下发的上行报文，目前只包括属性值报文	V1.00.00.00
47	IOT_Linkkit_Query	向云端发送存在云端业务数据下发的查询报文，目前只支持NTP时间查询报文	V1.00.00.00
48	IOT_RegisterCallback	对SDK注册事件回调函数，如云端连接成功/失败，有属性设置/服务请求到达，答复等	V1.00.00.00
49	IOT_SetupConnInfo	MQTT认证参数配置，因私网版服务器地址部署不一致，需配置连接参数信息	V1.00.00.00
50	IOT_Ioctl	对SDK进行各种参数运行时设置和获取，以及运行状态的信息获取等，实参可以是任何数据类型	V1.00.00.00

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

{ “utCode”:”10001”, “utMsg”:”产品不存在!”, “utService”:”iot” }

硬件云私部署预置了一个用户. 用户名：admin 密码：Ut123456

调用方式：

运行jar启动硬件云私部署服务。若在本机启动，则ip:port 为 http://localhost:20007 端口为20007
打开postman（以创建产品接口为例，其余接口类似）

a.在地址栏输入http://localhost:20007/product/create 其中/product/create为创建产品接口的uri。

授权方式选择Basic Auth. 右侧输入账号admin 密码 Ut123456

b. 切换到Headers页签，增加请求头信息。key为Content-Type， value为application/json

c. 切换到Body页签，增加请求参数json串信息

d.点击send。即可请求接口成功，得到返回结果。以上步骤截图参考如下：

Path： /product/release

Method： POST

接口描述：

调用该接口发布产品。产品发布后将不允许修改。

Headers

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

Body

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

Path： /product/cancelRelease

Method： POST

接口描述：

调用该接口撤销产品发布。

Headers

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

Body

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

Path： /product/create

Method： POST

接口描述：

按输入条件创建产品。

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
productName	string	必须		产品名称
dataFormat	integer	必须		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)
networkType	string	必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
productNodeType	string	必须		节点类型，取值：0:普通设备
tags	object	非必须		产品标签JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"},
description	string	非必须		产品描述
productType	string	非必须		产品类型
productGroup	string	非必须		产品分组
imageKey	string	非必须		产品图片Key

名称	类型	是否必须	默认值	备注	其他信息
productKey	string	非必须		产品Key
createTime	integer	非必须		创建时间	format: int64

Path： /product/delete

Method： POST

接口描述：

根据产品key删除产品。

Headers

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

Body

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

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	非必须		产品描述
imageKey	string	非必须		产品图片Key

Path： /product/get

Method： GET

接口描述：

根据产品key查询产品详细信息。

Headers

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

名称	类型	是否必须	默认值	备注	其他信息
tags	object	非必须		返回的设备标签信息JSON对象。key为标签键,value为标签值，例：{"tagKey":"tagValue"}
productKey	string	非必须		产品Key
productName	string	非必须		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)
dataFormat	integer	非必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
networkType	string	非必须		节点类型，取值：0:普通设备
productNodeType	string	非必须		节点类型，取值：0:普通设备
description	string	非必须		产品描述
productType	string	非必须		产品类型
productGroup	string	非必须		产品分组
imageKey	string	非必须		产品图片Key。
userId	string	非必须		用户Id
productStatus	string	非必须		产品状态，枚举值：开发中：DEVELOPMENT_STATUS,已发布：RELEASE_STATUS
createTime	integer	非必须		创建时间

Path： /product/get

Method： GET

接口描述：

返回产品信息分页数据。

Query

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

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ productKey	string	非必须		产品KEY
├─ productName	string	非必须		产品名称
├─ dataFormat	integer	非必须		数据格式。取值： 0：透传/自定义格式 1：ICA 标准数据格式 (Alink JSON)
├─ networkType	string	非必须		联网方式。取值： 'WIFI'：WiFi 'ETHERNET'：以太网 'BLUETOOTH'：蓝牙
├─ description	string	非必须		产品描述
├─ productType	string	非必须		产品类型
├─ productGroup	string	非必须		产品分组
├─ imageKey	string	非必须		产品图片Key
├─ createTime	integer	非必须		产品创建时间
├─ productNodeType	string	非必须		节点类型，取值：0:普通设备
├─ productStatus	string	非必须		产品状态，枚举值：开发中：DEVELOPMENT_STATUS,已发布：RELEASE_STATUS
empty	boolean	非必须
first	boolean	非必须
last	boolean	非必须
number	integer	非必须
numberOfElements	integer	非必须
pageable	object	非必须
├─ pageNumber	integer	非必须		查询的页码(0..N)
├─ pageSize	integer	非必须		页大小
├─ sort	string []	非必须		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
├─		非必须
size	integer	非必须
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须
totalPages	integer	非必须

Path：/product/listTags

Method： GET

接口描述：

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

Query

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

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

Path：/product/incrementalUpdateTags

Method： POST

接口描述：

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

Headers

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

Body

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

Path： /product/fullUpdateTags

Method： POST

接口描述：

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

Headers

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

Body

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

Path： /device/queryDeviceProperty

Method： GET

接口描述：

调用该接口查询指定设备的属性。

Query

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

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

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
remark	string	非必须		备注

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

Path： /device/queryDeviceProperty

Method： GET

接口描述：

调用该接口在指定产品下批量创建多个设备（随机生成设备名）。

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/list

Method： GET

接口描述：

调用该接口批量查询设备。

Query

参数名称	是否必须	示例	备注
deviceName	否		设备名称(模糊查询)
groupId	否		分组Id,需要查询未分组设备则传空字符串””
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). 默认按升序排序.支持多个排序条件.
status	否		设备状态取值： ONLINE：设备在线。 OFFLINE：设备离线。 UNACTIVE：设备未激活。 DISABLE：设备已禁用。
sub	否		是否子设备
tagList[0].tagKey	否		标签键
tagList[0].tagValue	否		标签值
tagsOr	否		多个过滤标签之间是否OR操作。 true：使用OR操作，结果为并集 false：使用AND操作，结果为交集默认为false

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			开发者用户Id
├─ deviceName	string	非必须		设备名称
├─ group	object []	非必须		分组ID集合,保存设备所属分组的id	开发者用户Id
├─ imageKey	string	非必须		产品图片Key。通过该图片Key可以从文件服务中获取图片内容
├─ index	integer	非必须		自定义下标,通过维护此字段实现自定义排序	开发者用户Id
├─ 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	非必须		产品类型
├─ remark	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	非必须
├─ pageNumber	integer	非必须		format: int32	format: int32
├─ pageSize	integer	非必须		format: int32	format: int32
├─ sort	string []	非必须		format: int32	format: int32
├─		非必须
size	integer	非必须			format: int32
sort	object	非必须
├─ empty	boolean	非必须
├─ sorted	boolean	非必须
├─ unsorted	boolean	非必须
totalElements	integer	非必须			format: int32
totalPages	integer	非必须			format: int32

Path： /device/update

Method： POST

接口描述：

调用该接口更新指定设备。

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceName	string	必须		设备名称
nickname	string	非必须		设备名称,长度为4-32个字符，可以包含英文字母、数字和特殊字符：连字符（-）、下划线（_）、at符号（@）、点号（.）、和英文冒号（:）。	最大长度: 32 最小长度: 4
productKey	string	必须		产品Key
remark	string	非必须		备注

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	非必须		设备的创建时间
├─ deviceName	string	非必须		设备名称
├─ deviceSecret	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	非必须
totalPages	integer	非必须			format: int32

Path： /device/queryBatchInfo

Method： GET

接口描述：

调用该接口查询批量申请设备详情。

Query

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

返回数据

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

Path：/device/queryEventData

Method： GET

接口描述：

调用该接口查询指定设备的事件记录。

Query

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

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

Path：/device/delete

Method： POST

接口描述：

调用该接口删除指定设备。

Headers

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

Body

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

Path：/device/queryPropertyData

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，继续查询本次查询不显示的数据。
queryPropertyDataInfoList	object []	非必须		属性集合	item 类型: object
├─ time	string	非必须		属性上报时间
├─ 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/get

Method： GET

接口描述：

调用该接口查询指定设备的详细信息。

Query

名称	类型	是否必须	默认值	备注	其他信息
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	非必须		备注名称
ownerId	string	非必须		设备用户Id
parentDeviceName	string	非必须		父设备名称
parentProductKey	string	非必须		父产品Key
productKey	string	非必须		产品key
productName	string	非必须		产品名称
productNodeType	string	非必须		节点类型，取值：0:普通设备，1：普通网关，2：边缘网关，4：虚拟子设备
remark	string	非必须		备注
status	string	非必须		设备状态。取值： ONLINE：设备在线。 OFFLINE：设备离线。 UNACTIVE：设备未激活。 DISABLE：设备已禁用。
subDeviceName	string	非必须		子设备名称
subProductKey	string	非必须		子产品Key
utcActive	string	非必须		设备的激活时间（UTC）
utcCreate	string	非必须		设备的创建时间（UTC）
utcOnline	string	非必须		设备最近一次上线的时间（UTC）

Path： /device/disableThing

Method： POST

接口描述：

调用该接口禁用设备。

Headers

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

Body

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

Path： /device/queryStatistics

Method：GET

接口描述：

调用该接口禁用设备。

Query

参数名称	是否必须	示例	备注
productKey	否		产品key,不传则统计所有设备

返回数据

名称	类型	是否必须	默认值	备注	其他信息
activeCount	integer	非必须		激活设备总数	format: int64
deviceCount	integer	非必须		设备总数	format: int64
onlineCount	integer	非必须		在线设备总数	format: int64

Path： /device/enableThing

Method：POST

接口描述：

调用该接口解禁设备。

Headers

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

Body

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

Path： /device/setDeviceProperty

Method：POST

接口描述：

此接口需要权限：设备拥有者。

Headers

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

Body

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

Path： /device/invokeThingService

Method：POST

接口描述：

此接口需要权限：设备拥有者。

Headers

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

Body

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


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

基本信息

Path： /group/create

Method： POST

接口描述：

按输入条件创建设备分组

请求参数

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
groupName	string	必须		设备分组名称	最大长度: 30；最小长度: 4；
imageKey	string	非必须		设备分组图片Key
description	string	非必须		设备分组描述	最大长度: 2147483647；最小长度: 5；

返回数据

名称	类型	是否必须	默认值	备注	其他信息
groupId	string	非必须		分组ID

基本信息

Path： /group/delete

Method： POST

接口描述：

根据设备分组ID删除设备分组

请求参数

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
groupId	string	必须		分组ID

返回数据

OK

基本信息

Path： /group/update

Method： POST

接口描述：

根据设备分组ID更新设备分组信息

请求参数

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
groupId	string	必须		分组ID
groupName	string	非必须		设备分组名称	最大长度: 3；最小长度: 4；
imageKey	string	非必须		设备分组图片Key
description	string	非必须		设备分组描述	最大长度: 2147483647；最小长度: 5；

返回数据

OK

基本信息

Path： /group/get

Method： GET

接口描述：

根据分组ID查询设备分组详细信息

请求参数

Query

参数名称	是否必须	示例	备注
groupId	是		分组ID

返回数据

名称	类型	是否必须	默认值	备注	其他信息
groupId	string	非必须		设备分组ID
groupName	string	非必须		设备分组名称
imageKey	string	非必须		设备分组图片Key
onlineCount	integer	非必须		在线设备数量	format: int64
offlineCount	integer	非必须		在线设备数量	format: int64
unactivatedCount	integer	非必须		未激活设备数量	format: int64
disabledCount	integer	非必须		禁用设备数量	format: int64
createTime	integer	非必须		创建时间	format: int64
userId	string	非必须		创建人
description	string	非必须		设备分组描述

基本信息

Path： /group/query

Method： GET

接口描述：

返回设备分组信息分页数据

请求参数

Query

参数名称	是否必须	示例	备注
endTime	否		查询结束时间（按创建时间查询）
groupName	否		设备分组名称(模糊查询)
pageNumber	否		查询的页码(0..N)
pageSize	否		页大小
sort	否		排序条件,格式: 排序字段(,asc/desc). 默认按升序排序.支持多个排序条件.
startTime	否		查询起始时间（按创建时间查询）
userId	否		创建人

返回数据

名称	类型	是否必须	默认值	备注	其他信息
content	object []	非必须			item 类型: object
├─ groupId	string	非必须		设备分组ID
├─ groupName	string	非必须		设备分组名称
├─ imageKey	string	非必须		设备分组图片Key
├─ onlineCount	integer	非必须		在线设备数量	format: int64
├─ offlineCount	integer	非必须		离线设备数量	format: int64
├─ createTime	integer	非必须		创建时间	format: int64
├─ userId	string	非必须		创建人
├─ description	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： /group/batchAddDevice

Method： POST

接口描述：

调用该接口批量添加设备到分组

请求参数

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceKeys	object []	必须		添加设备标识列表。单次最大可绑定设备数：20	item 类型: object
├─ deviceName	string	必须		设备名称
├─ productKey	string	必须		产品Key
groupId	string	必须		设备分组ID

返回数据

OK

基本信息

Path： /group/batchRemoveDevice

Method： POST

接口描述：

调用该接口批量添加从分组移除设备

请求参数

Headers

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

Body

名称	类型	是否必须	默认值	备注	其他信息
deviceKeys	object []	必须		添加设备标识列表。单次最大可绑定设备数：20	item 类型: object
├─ deviceName	string	必须		设备名称
├─ productKey	string	必须		产品Key
groupId	string	必须		设备分组ID

返回数据

OK

文件定位：wrappers/wrapper.c

原型

void HAL_Free(_IN_ void *ptr);

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

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

返回值说明 void

原型

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_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

原型

uint64_t HAL_UptimeMs(void);

接口说明获取设备从上电到当前时刻所经过的毫秒数
参数说明 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	输入	可变参数列表

返回值说明成功写入的字符串长

文件定位：wrappers/wrapper_thread.c

原型

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

文件定位：wrappers/wrapper_product.c

原型

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[]	输出	存放FirmwareVesion的字符串缓冲区

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

原型

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字符串长度

原型

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字符串的长度

文件定位：wrappers/wrapper_kv.c

原型

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_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	设置失败

文件定位：wrappers/wrapper_tcp.c

原型

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	输入

返回值说明

参数	数据类型
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写入成功

文件定位：wrappers/wrapper_tls.c

原型

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写入成功

设备的身份认证支持一机一密。

一机一密在设备上烧写设备的ProductKey、DeviceName、DeviceSecret，然后适配相应的HAL并调用SDK提供的连接云端的函数即可，这种方式要求对设备的产线工具进行一定的修改，需要对每个设备烧写不同的DeviceName和DeviceSecret。

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

HAL_GetProductKey
HAL_GetDeviceName
HAL_GetDeviceSecret

硬件云（私网版）因部署服务器不固定，只要配置三元组则可在设备签名时自由配置认证和签名。

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

获取设备认证时设置的三元组信息：

    HAL_GetProductKey(PRODUCT_KEY);
    HAL_GetDeviceName(DEVICE_NAME);
    HAL_GetDeviceSecret(DEVICE_SECRET);

因硬件云（私网版）的连接参数信息不固定，需手动变更配置。

通过IOT_SetupConnInfo重新配置配置MQTT连接参数。

参数配置结构体：

typedef struct {
    uint16_t        port;
    uint8_t         init;
    char            *host_name;
    char            *client_id;
    char            *username;
    char            *password;
    const char      *pub_key;
} iotx_conn_info_t, *iotx_conn_info_pt;

参数	含义
port	可以连接的MQTT服务器端口
init	是否已经初始化配置，配置完应置为1
host_name	可以连接的MQTT服务器域名地址
client_id	连接MQTT服务器时标识设备的自定义ID，规则定义：ProductKey&DeviceName&Timestamp,即为：产品Key、设备名、时间戳的拼接
username	连接MQTT服务器时将要使用的用户名，规则定义：ProductKey&DeviceName
password	连接MQTT服务器时将要使用的密码, 和用户名一一对应，规则定义：DeviceSecret
pub_key	连接MQTT服务器时，SSL/TLS签名

示例：

    iotx_conn_info_pt pconn_info = NULL;

    /* Device AUTH */
    if (0 != IOT_SetupConnInfo(PRODUCT_KEY, DEVICE_NAME, DEVICE_SECRET, (void **)&pconn_info))
    {
        EXAMPLE_TRACE("AUTH request failed!");
    }

    pconn_info->host_name = "192.168.105.161";
    pconn_info->port = 1883;

    char _client_id[120] = {0};
    HAL_Snprintf(_client_id, sizeof(_client_id), "%s&%s&%ld", PRODUCT_KEY, DEVICE_NAME, _get_sys_ms());
    pconn_info->client_id = _client_id;

    char _username[60] = {0};
    HAL_Snprintf(_username, sizeof(_username), "%s&%s", PRODUCT_KEY, DEVICE_NAME);
    pconn_info->username = _username;
    pconn_info->password = DEVICE_SECRET;

    pconn_info->init = 1;

注意：当前认证需在IOT_Linkkit_Open前设置。

优模型管理功能是指使用属性/事件/服务的方式对产品支持的能力进行描述，在设备开发时也需要以优模型的方式进行编程。

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 向云端发送存在云端业务数据下发的查询报文，目前只支持NTP时间查询报文
IOT_RegisterCallback 对SDK注册事件回调函数，如云端连接成功/失败，有属性设置/服务请求到达，答复等
IOT_SetupConnInfo MQTT认证参数配置，因私网版服务器地址部署不一致，需配置连接参数信息
IOT_Ioctl 对SDK进行各种参数运行时设置和获取，以及运行状态的信息获取等，实参可以是任何数据类型

示例代码位置：iot-privatization-sdk/examples/linkkit_example_solo.c。

属性上报

用户可以调用IOT_Linkkit_Report()函数来上报属性，属性上报时需要按照云端定义的属性格式使用JSON编码后进行上报。示例中函数user_post_property展示了如何使用IOT_Linkkit_Report进行属性上报。

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

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

    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 = “{"bool_param": %d}” 即是将属性编码为JSON对象。

当上报属性或者事件时需要云端应答时，通过IOT_Ioctl对IOTX_IOCTL_RECV_EVENT_REPLY选项进行设置。

注册属性上报回复： IOT_RegisterCallback(ITE_REPORT_REPLY, user_report_reply_event_handler);

属性设置

示例代码在回调函数user_property_set_event_handler中获取云端设置的属性值，并原样将收到的数据发回给云端，这样可以更新在云端的设备属性值，用户可在此处对收到的属性值进行处理。

说明：该回调函数是在example初始化时使用IOT_RegisterCallback注册的ITE_PROPERTY_SET事件对应的回调函数。

注册回调： IOT_RegisterCallback(ITE_PROPERTY_SET, user_property_set_event_handler);

/** recv property setting message from cloud **/
static int user_property_set_event_handler(const int devid, const char *request, const int request_len)
{
    int res = 0;
    EXAMPLE_TRACE("Property Set Received, Request: %s", request);

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

    return 0;
}

说明：属性设置成功通过属性上报的方式更新云端的属性值。

在示例程序中，当收到服务调用请求(包括同步服务和异步服务)时，进入下面列出的回调函数：

注：目前暂只支持异步服务。

注册回调： IOT_RegisterCallback(ITE_SERVICE_REQUEST, user_service_request_event_handler);

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("service1") == serviceid_len && memcmp("service1", serviceid, serviceid_len) == 0)
    {
        /* Parse NumberA */
        item_number_a = cJSON_GetObjectItem(root, "param1");
        if (item_number_a == NULL || !cJSON_IsNumber(item_number_a))
        {
            cJSON_Delete(root);
            return -1;
        }
        EXAMPLE_TRACE("NumberA = %d", item_number_a->valueint);

        add_result = item_number_a->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;
}

用户需要动态分配内存空间用于存放服务应答数据，并通过response参数返回给SDK，SDK在完成应答数据发送后会负责response指向内存的释放。

说明：对服务输出参数为空的情况，*response应指向存放JSON对象{}的内存，不能让*response指向空指针。

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

void user_post_event(void)
{
    int res = 0;
    char *event_id = "test_event0";
    char *event_payload = "{\"int_param\": 1}";

    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);

}

当上报属性或者事件时需要云端应答时，通过IOT_Ioctl对IOTX_IOCTL_RECV_EVENT_REPLY选项进行设置。

注册事件上报回复： IOT_RegisterCallback(ITE_TRIGGER_EVENT_REPLY, user_trigger_event_reply_event_handler);

使用IOT_Linkkit_Query通过ITM_MSG_QUERY_TIMESTAMP类型来获取当前最新的时间。

void user_timestamp_query(void)
{
    int res = 0;
    char ntp_payload[60] = {0};
    HAL_Snprintf(ntp_payload, sizeof(ntp_payload), "{\"deviceSendTime\": \"%ld\"}", _get_sys_ms());

    res = IOT_Linkkit_Query(EXAMPLE_MASTER_DEVID, ITM_MSG_QUERY_TIMESTAMP, ntp_payload, strlen(ntp_payload));
    EXAMPLE_TRACE("Device Timestamp Query Message ID: %d", res);
}

注意：时间查询payload中应带上当前的时间戳”{"deviceSendTime": "%ld"}”

注册云端应答回调： IOT_RegisterCallback(ITE_TIMESTAMP_REPLY, user_timestamp_reply_event_handler);

在回调中处理最新时间：

static int user_timestamp_reply_event_handler(const char *timestamp)
{
    EXAMPLE_TRACE("Current Timestamp: %s", timestamp);
    return 0;
}

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

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

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

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

/* 布尔型数据上报, 在物模型定义中, 布尔型为整型, 取值为0或1, 与JSON格式的整型不同 */
 *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的格式与多属性上报是相同的 */