Basic HAL
Releases the block of heap memory pointed to by the ptr parameter. This operation has no effect if the parameter is NULL.
Prototype
void HAL_Free(_IN_ void *ptr);
Description
Parameters
| Parameter | Data type | Direction | Description |
| ptr | void * | Input | A pointer to the heap memory to be released. |
Return value
void
HAL_GetChipID
Prototype
char *HAL_GetChipID(_OU_ char cid_str[HAL_CID_LEN]);
Description
Retrieves the unique chip ID string. The length of the string cannot exceed the value defined by HAL_CID_LEN.
Note: This Hardware Abstraction Layer (HAL) function only needs to be implemented by chip vendors. If you are not a chip vendor, this function can return an empty string.
Parameters
| Parameter | Data type | Direction | Description |
| cid_str | char[] | Output | A string buffer to store the chip ID. |
Return value
A pointer to the string buffer.
HAL_GetDeviceID
(Implementation is not required in versions 2.3.1 and later)
Prototype
int HAL_GetDeviceID(_OU_ char device_id[DEVICE_ID_LEN]);
Description
Retrieves the DeviceID of the device. This ID uniquely identifies a device.
Parameters
| Parameter | Data type | Direction | Description |
| device_id | char[] | Output | A string buffer to store the DeviceID. |
Return value
The length of the retrieved DeviceID string.
HAL_GetDeviceName
Prototype
int HAL_GetDeviceName(_OU_ char device_name[DEVICE_NAME_LEN]);
Description
Retrieves the DeviceName of the device. This name uniquely identifies a device. It is obtained from the console and written to the device.
Parameters
| Parameter | Data type | Direction | Description |
| device_name | char[] | Output | A string buffer to store the DeviceName. |
Return value
The length of the retrieved DeviceName string.
HAL_GetDeviceSecret
Prototype
int HAL_GetDeviceSecret(_OU_ char device_secret[DEVICE_SECRET_LEN]);
Description
Retrieves the DeviceSecret of the device. This key uniquely identifies a device. It is obtained from the console and written to the device.
Parameters
| Parameter | Data type | Direction | Description |
| device_secret | char[] | Output | A string buffer to store the DeviceSecret. |
Return value
The length of the retrieved DeviceSecret string.
HAL_GetFirmwareVersion
Prototype
int HAL_GetFirmwareVersion(_OU_ char version[FIRMWARE_VERSION_MAXLEN]);
Description
Retrieves the firmware version string of the device. This version number is reported for over-the-air (OTA) updates. If the device does not support OTA, this function can return an empty string.
Parameters
| Parameter | Data type | Direction | Description |
| version | char[] | Output | A string buffer to store the FirmwareVersion. |
Return value
The length of the retrieved FirmwareVersion string.
HAL_GetModuleID
Prototype
int HAL_GetModuleID(_OU_ char mid_str[MID_STR_MAXLEN]);
Description
Retrieves the Module ID of the device. This is for close partners only. This function is used by module vendors to report the module model. Users in other roles can return an empty string.
Parameters
| Parameter | Data type | Direction | Description |
| mid_str | char[] | Output | A string buffer to store the Module ID. |
Return value
The length of the retrieved Module ID string.
HAL_GetPartnerID
Prototype
int HAL_GetPartnerID(_OU_ char pid_str[PID_STR_MAXLEN]);
Description
Retrieves the Partner ID of the device. This is for close partners only.
Parameters
| Parameter | Data type | Direction | Description |
| pid_str | char[] | Output | A string buffer to store the Partner ID. |
Return value
The length of the retrieved Partner ID string.
HAL_GetProductKey
Prototype
int HAL_GetProductKey(_OU_ char product_key[PRODUCT_KEY_LEN]);
Description
Retrieves the ProductKey of the device. This key identifies the product category. It is obtained from the console and written to the device.
Parameters
| Parameter | Data type | Direction | Description |
| product_key | char[] | Output | A string buffer to store the ProductKey. |
Return value
The length of the retrieved ProductKey string.
HAL_GetProductSecret
Prototype
int HAL_GetProductSecret(_OU_ char product_secret[DEVICE_SECRET_LEN]);
Description
Retrieves the ProductSecret of the device. This key identifies the product category. It is obtained from the console and written to the device. This string is used in per-device-per-key scenarios.
Parameters
| Parameter | Data type | Direction | Description |
| product_secret | char[] | Output | A string buffer to store the ProductSecret. |
Return value
The length of the retrieved ProductSecret string.
HAL_GetTimeStr
(Implementation is not required in versions 2.3.1 and later) Prototype
char *HAL_GetTimeStr(_OU_ char *buf, _IN_ int len);
Description
Retrieves the current time string.
Parameters
| Parameter | Data type | Direction | Description |
| buf | char * | Output | A pointer to the time string buffer. |
| len | int | Input | The length of the string buffer in bytes. |
Return value
A pointer to the time string buffer.
HAL_Kv_Del
Prototype
int HAL_Kv_Del(const char *key);
Description
Deletes the key-value (KV) pair that corresponds to the specified key. You can implement this data persistence operation by erasing flash memory or modifying file data.
Parameters
| Parameter | Data type | Direction | Description |
| key | const char * | Input | A pointer to the key string. |
| buffer | void * | Outputs | A pointer to the buffer that stores the retrieved data. |
| buffer_len | int * | Output | Reference Fetch |
Return value
| Value | Description |
| 0 | Deletion successful. |
| -1 | Deletion failed. |
HAL_Kv_Erase_All
Prototype
int HAL_Kv_Erase_All(void);
Description
To erase all KV data, you can delete the persistent data by erasing the flash memory or modifying the file.
Parameters
void
Return value
| Value | Description |
| 0 | Operation successful. |
| -1 | Operation failed. |
HAL_Kv_Get
Prototype
int HAL_Kv_Get(const char *key, void *buffer, int *buffer_len);
Description
Retrieves the key-value (KV) pair that corresponds to the specified key. You can implement this data persistence operation by reading from flash memory or a file.
Parameters
| Parameter | Data type | Direction | Description |
| key | const char * | Input | A pointer to the key string. |
| buffer | void * | Output | A pointer to store the retrieved data. |
| buffer_len | int * | Output | Pointer-based access |
Return value
| Value | Description |
| 0 | Retrieval successful. |
| -1 | Retrieval failed. |
HAL_Kv_Set
Prototype
int HAL_Kv_Set(const char *key, const void *val, int len, int sync);
Description
Sets key-value (KV) data. You can implement data persistence by writing to flash memory or a file.
Parameters
| Parameter | Data type | Direction | Description |
| key | const char * | Input | A pointer to the key string. |
| val | const void * | Input | A pointer to the data to be set. |
| len | int | Input | The length of the data to be set in bytes. |
| sync | int | Input | 0: Asynchronous. 1: Synchronous. |
Return value
| Value | Description |
| 0 | Set operation successful. |
| -1 | Set operation failed. |
HAL_Malloc
Prototype
void *HAL_Malloc(_IN_ uint32_t size);
Description
Allocates a block of heap memory.
Parameters
| Parameter | Data type | Direction | Description |
| size | uint32_t | Input | The size of the heap memory to allocate. |
Return value
| Value | Description |
| NULL | Memory allocation failed. |
| !NULL | A pointer to the start address of the heap memory. |
HAL_Printf
Prototype
void HAL_Printf(_IN_ const char *fmt, ...);
Description
Prints logs or debugging information to a serial port or another standard output. The implementation can be based on the C99 printf() function.
Parameters
| Parameter | Data type | Direction | Description |
| fmt | const char * | Input | Format string. |
| ... | Variable type | Input | Variable argument list. |
Return value
void
HAL_Random
HAL_Random prototype
uint32_t HAL_Random(_IN_ uint32_t region);
Description
Generates a random number. This function takes an unsigned number as the upper bound of a range and returns a random number from 0 to that upper bound.
Parameters
| Parameter | Data type | Direction | Description |
| region | uint32_t | Input | An unsigned number that specifies the range for the random number. |
Return value
A random number within the specified range.
HAL_Reboot
Prototype
void HAL_Reboot(void);
Description
Restarts the device.
Parameters
void
Return value
void
HAL_SetDeviceName
Prototype
int HAL_SetDeviceName(_IN_ char *device_name);
Description
Sets the DeviceName of the device. This name uniquely identifies a device.
Parameters
| Parameter | Data type | Direction | Description |
| device_name | char * | Output | A pointer to the DeviceName string to be passed. |
Return value
The length of the DeviceName string to be set.
HAL_SetDeviceSecret
Prototype
int HAL_SetDeviceSecret(_IN_ char *device_secret);
Description
Sets the DeviceSecret of the device. This key uniquely identifies a device.
Parameters
| Parameter | Data type | Direction | Description |
| device_secret | char * | Output | A pointer to the DeviceSecret string to be passed. |
Return value
The length of the DeviceSecret string to be set.
HAL_SetProductKey
Prototype
int HAL_SetProductKey(_IN_ char *product_key);
Description
Sets the ProductKey of the device. This key identifies the product category.
Parameters
| Parameter | Data type | Direction | Description |
| product_key | char * | Input | A pointer to the ProductKey string to be set. |
Return value
The length of the ProductKey string to be set.
HAL_SetProductSecret
Prototype
int HAL_SetProductSecret(_IN_ char *product_secret);
Description
Sets the ProductSecret of the device. This key identifies the product category. This string is used in per-device-per-key scenarios.
Parameters
| Parameter | Data type | Direction | Description |
| product_secret | char * | Output | A pointer to the ProductSecret string to be passed. |
Return value
The length of the ProductSecret string to be set.
HAL_SleepMs
Prototype
void HAL_SleepMs(_IN_ uint32_t ms);
Description
Suspends the current thread for a specified number of milliseconds.
Parameters
| Parameter | Data type | Direction | Description |
| ms | uint32_t | Input | The time to suspend the thread, in milliseconds. |
Return value
void
HAL_Snprintf
Prototype
int HAL_Snprintf(_OU_ char *str, _IN_ const int len, _IN_ const char *fmt, ...);
Description
Formats and builds a string in a memory buffer. The implementation can be based on the C99 standard library function.
Parameters
| Parameter | Data type | Direction | Description |
| str | char * | Input | A pointer to the character buffer. |
| len | int | Input | The length of the buffer in characters. |
| fmt | const char * | Input | Format string. |
| ... | Input | Variable argument list. |
Return value
The length of the string written to the buffer.
HAL_Srandom
Prototype
void HAL_Srandom(_IN_ uint32_t seed);
Description
Seeds the random number generator. This ensures that each random sequence returned by `HAL_Random` is different. This function is similar to srand in the C standard library.
Parameters
| Parameter | Data type | Direction | Description |
| seed | uint32_t | Input | A seed to generate a new random number sequence. |
Return value
void
HAL_Sys_reboot
Prototype
void HAL_Sys_reboot(void);
Description
Restarts the system immediately.
Parameters
void
Return value
void
HAL_Timer_Create
Prototype
void *HAL_Timer_Create(const char *name, void (*func)(void *), void *user_data);
Description
Creates a timer with a specified name and registers a user callback function and user data.
Parameters
| Parameter | Data type | Direction | Description |
| name | const char * | Input | Timer name string. |
| func | void (*func)(void *) | Input | User callback function. |
| user_data | void * | Input | A pointer to user data. |
Return value
| Value | Description |
| NULL | Creation failed. |
| !NULL | Creation successful. Returns the timer handle. |
HAL_Timer_Delete
Prototype
int HAL_Timer_Delete(void *timer);
Description
Deletes a timer created by HAL_Timer_Create() and releases its resources.
Parameters
| Parameter | Data type | Direction | Description |
| timer | void * | Input | The timer handle. This handle is returned by a call to HAL_Timer_Create(). |
Return value
| Value | Description |
| 0 | Operation successful. |
| -1 | Operation failed. |
HAL_Timer_Start
Prototype
int HAL_Timer_Start(void *t, int ms);
Description
Starts a timer.
Parameters
| Parameter | Data type | Direction | Description |
| timer | void * | Input | The timer handle. This handle is returned by a call to HAL_Timer_Create(). |
| ms | int | Input | The timer duration, in milliseconds. |
Return value
| Value | Description |
| 0 | Operation successful. |
| -1 | Operation failed. |
HAL_Timer_Stop
Prototype
int HAL_Timer_Stop(void *t);
Description
Stops a timer.
Parameters
| Parameter | Data type | Direction | Description |
| timer | void * | Input | The timer handle. This handle is returned by a call to HAL_Timer_Create(). |
Return value
| Value | Description |
| 0 | Operation successful. |
| -1 | Operation failed. |
HAL_UptimeMs
Prototype
uint64_t HAL_UptimeMs(void);
Description
Retrieves the number of milliseconds that have elapsed since the device was powered on.
Parameters
void
Return value
The number of milliseconds that have elapsed since the device was powered on.
HAL_UTC_Get
Prototype
long long HAL_UTC_Get(void);
Description
Retrieves the Coordinated Universal Time (UTC). The value is the time that has elapsed since the epoch (00:00:00 UTC on January 1, 1970).
Parameters
void
Return value
The UTC in milliseconds.
HAL_UTC_Set
Prototype
void HAL_UTC_Set(long long ms);
Description
Sets the UTC. The parameter is the time that has elapsed since the epoch (00:00:00 UTC on January 1, 1970).
Parameters
| Parameter | Data type | Direction | Description |
| ms | long long | Input | The UTC in milliseconds. |
Return value
void
HAL_Vsnprintf
Prototype
int HAL_Vsnprintf(_OU_ char *str, _IN_ const int len, _IN_ const char *fmt, _IN_ va_list ap);
Description
Formats and prints a string to a specified buffer. The implementation can be based on the C standard library function vsnprintf().
Parameters
| Parameter | Data type | Direction | Description |
| str | char * | Output | A buffer to store the written string. |
| len | const int | Input | The maximum length of the string that can be written. |
| fmt | const char | Input | Format string. |
| ap | va_list | Input | Variable argument list. |
Return value
The length of the successfully written string.