基础HAL - 设备接入Link SDK

HAL_Free

原型

void HAL_Free(_IN_ void *ptr);

接口说明

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

参数说明

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

返回值说明

void

HAL_GetChipID

原型

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

接口说明

获取唯一的芯片ID字符串, 字符串长度不能超过HAL_CID_LEN定义的数值。

注：该HAL只需要芯片商进行适配，如果用户不是芯片商，该HAL返回空字符串即可

参数说明

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

返回值说明

指向字符串缓冲区的指针

HAL_GetDeviceID

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

原型

int HAL_GetDeviceID(_OU_ char device_id[DEVICE_ID_LEN]);

接口说明

获取设备的DeviceID, 用于标识设备单品的ID

参数说明

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

返回值说明

实际获取到的DeviceID字符串长度

HAL_GetDeviceName

原型

int HAL_GetDeviceName(_OU_ char device_name[DEVICE_NAME_LEN]);

接口说明

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

参数说明

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

返回值说明

实际获取到的DeviceName字符串长度

HAL_GetDeviceSecret

原型

int HAL_GetDeviceSecret(_OU_ char device_secret[DEVICE_SECRET_LEN]);

接口说明

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

参数说明

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

返回值说明

实际获取到的DeviceSecret字符串长度

HAL_GetFirmwareVersion

原型

int HAL_GetFirmwareVersion(_OU_ char version[FIRMWARE_VERSION_MAXLEN]);

接口说明

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

参数说明

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

返回值说明

实际获取到的FirmwareVesion字符串长度

HAL_GetModuleID

原型

int HAL_GetModuleID(_OU_ char mid_str[MID_STR_MAXLEN]);

接口说明

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

参数说明

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

返回值说明

实际获取到的Module ID字符串长度

HAL_GetPartnerID

原型

int HAL_GetPartnerID(_OU_ char pid_str[PID_STR_MAXLEN]);

接口说明

获取设备的Partner ID, 仅用于紧密合作伙伴。

参数说明

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

返回值说明

实际获取到的Partner ID字符串长度

HAL_GetProductKey

原型

int HAL_GetProductKey(_OU_ char product_key[PRODUCT_KEY_LEN]);

接口说明

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

参数说明

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

返回值说明

实际获取到的ProductKey字符串长度

HAL_GetProductSecret

原型

int HAL_GetProductSecret(_OU_ char product_secret[DEVICE_SECRET_LEN]);

接口说明

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

参数说明

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

返回值说明

实际获取到的ProductSecret字符串长度

HAL_GetTimeStr

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

原型

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

接口说明

获取当前时间字符串

参数说明

参数	数据类型	方向	说明
buf	char *	输出	指向时间字符串缓冲区的指针
len	int	输入	字符串缓冲区的字节长度

返回值说明

指向时间字符串缓冲区的指针

HAL_Kv_Del

原型

int HAL_Kv_Del(const char *key);

接口说明

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

参数说明

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

返回值说明

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

HAL_Kv_Erase_All

原型

int HAL_Kv_Erase_All(void);

接口说明

擦除所有的KV数据, 可以通过擦除Flash或修改文件数据的方式实现持久化数据的删除

参数说明

void

返回值说明

值	说明
0	操作成功
-1	操作失败

HAL_Kv_Get

原型

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	获取失败

HAL_Kv_Set

原型

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

HAL_Malloc

原型

void *HAL_Malloc(_IN_ uint32_t size);

接口说明

申请一块堆内存

参数说明

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

返回值说明

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

HAL_Printf

原型

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

接口说明

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

参数说明

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

返回值说明

void

HAL_Random

原型

uint32_t HAL_Random(_IN_ uint32_t region);

接口说明

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

参数说明

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

返回值说明

在指定范围的随机数

HAL_Reboot

原型

void HAL_Reboot(void);

接口说明

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

参数说明

void

返回值说明

void

HAL_SetDeviceName

原型

int HAL_SetDeviceName(_IN_ char *device_name);

接口说明

设置设备的DeviceName, 用于标识设备单品的名字, 三元组之一

参数说明

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

返回值说明

待设置DeviceName字符串的长度

HAL_SetDeviceSecret

原型

int HAL_SetDeviceSecret(_IN_ char *device_secret);

接口说明

设置设备的DeviceSecret, 用于标识设备单品的密钥, 三元组之一

参数说明

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

返回值说明

待设置DeviceSecret字符串的长度

HAL_SetProductKey

原型

int HAL_SetProductKey(_IN_ char *product_key);

接口说明

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

参数说明

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

返回值说明

待设置ProductKey字符串的长度

HAL_SetProductSecret

原型

int HAL_SetProductSecret(_IN_ char *product_secret);

接口说明

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

参数说明

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

返回值说明

待设置ProductSecret字符串的长度

HAL_SleepMs

原型

void HAL_SleepMs(_IN_ uint32_t ms);

接口说明

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

参数说明

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

返回值说明

void

HAL_Snprintf

原型

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

接口说明

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

参数说明

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

返回值说明

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

HAL_Srandom

原型

void HAL_Srandom(_IN_ uint32_t seed);

接口说明

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

参数说明

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

返回值说明

void

HAL_Sys_reboot

原型

void HAL_Sys_reboot(void);

接口说明

系统立即重启

参数说明

void

返回值说明

void

HAL_Timer_Create

原型

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

接口说明

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

参数说明

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

返回值说明

值	说明
NULL	创建失败
!NULL	创建成功, 返回定时器句柄

HAL_Timer_Delete

原型

int HAL_Timer_Delete(void *timer);

接口说明

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

参数说明

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

返回值说明

值	说明
0	操作成功
-1	操作失败

HAL_Timer_Start

原型

int HAL_Timer_Start(void *t, int ms);

接口说明

启动定时器

参数说明

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

返回值说明

值	说明
0	操作成功
-1	操作失败

HAL_Timer_Stop

原型

int HAL_Timer_Stop(void *t);

接口说明

关闭定时器

参数说明

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

返回值说明

值	说明
0	操作成功
-1	操作失败

HAL_UptimeMs

原型

uint64_t HAL_UptimeMs(void);

接口说明

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

参数说明

void

返回值说明

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

HAL_UTC_Get

原型

long long HAL_UTC_Get(void);

接口说明

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

参数说明

void

返回值说明

单位为ms的UTC时间

HAL_UTC_Set

原型

void HAL_UTC_Set(long long ms);

接口说明

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

参数说明

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

返回值说明

void

HAL_Vsnprintf

原型

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	输入	可变参数列表

返回值说明

成功写入的字符串长