HAL overview-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

This topic describes the Hardware Abstraction Layer (HAL).

Device-side C-SDK layers

    +---------------------------+
    |                           |
    |   C-SDK Example Program   |
    |                           |
    +---------------------------+
    |                           |
    |   C-SDK Interface Layer   |
    |                           |
    |     IOT_XXX_YYY() APIs    |
    |                           |
    +---------------------------+
    |                           |
    |   C-SDK Core Implements   |
    |   : =>                    |
    |   : You SHOULD NOT Focus  |
    |   : on this unless        |
    |   : you're debugging SDK  |
    |                           |
    +---------------------------+
    |                           |
    |  Hardware Abstract Layer  |
    |                           |
    |     HAL_XXX_YYY() APIs    |
    |                           |
    |  : You MUST Implement     |
    |  : this part for your     |
    |  : target device first    |
    +---------------------------+

The device-side C-SDK has three layers, as shown in the figure above.

The first layer, Link Kit Interface Layer, is the SDK interface declaration layer.

This layer contains the prototype declarations for C functions. After you port the software development kit (SDK) to a different platform, you can use these APIs to write business logic and communicate with Alibaba Cloud servers.
The examples folder contains sample programs that use these APIs for business logic. You can run the programs on a Linux host after you enter the required device information.

The second layer, Link Kit Core Implements, is the SDK core implementation layer.

This is the core implementation of the SDK. It encapsulates features such as MQTT and CoAP channels based on HAL interfaces. These features include establishing connections, sending and receiving messages over MQTT and CoAP channels, querying over-the-air (OTA) firmware status, and downloading OTA firmware.

The third layer is the Hardware Abstraction Layer, also known as the HAL.

The HAL abstracts the support functions that an operating system on an embedded target board provides for the SDK. These functions include network data transmission, TLS/DTLS channel establishment and read/write operations, memory allocation and release, and mutex locking and unlocking.

Note

You must implement the HAL for cross-platform porting.

Versions 2.3.0 and earlier

All HAL function declarations are listed in the include/iot_import.h header file.
The HAL interface dependencies for each feature are listed in include/imports/iot_import_*.h.
The subfiles in the include/imports folder are included in include/iot_import.h.
The function declarations correspond to the reference implementation for the Ubuntu desktop system, which is provided in src/ref-impl/hal/os/ubuntu/. This implementation is compiled into output/release/lib/libiot_hal.a.

HAL interface list

Complete interface list

The following command lists all HAL interfaces that you must implement for cross-platform porting.

include$ grep -ro "HAL_[_A-Za-z0-9]*(" *|awk -F':' '{ print $NF }'|awk '{ print $NF }'|sed 's!(!!g'|sort -u|awk '{ printf("%03d  %s\n", NR, $0); }'

001  HAL_Aes128_Cbc_Decrypt
002  HAL_Aes128_Cbc_Encrypt
003  HAL_Aes128_Cfb_Decrypt
004  HAL_Aes128_Cfb_Encrypt
005  HAL_Aes128_Destroy
006  HAL_Aes128_Init
016  HAL_Config_Read
017  HAL_Config_Write
018  HAL_DTLSSession_create
019  HAL_DTLSSession_free
020  HAL_DTLSSession_read
021  HAL_DTLSSession_write
022  HAL_Firmware_Persistence_Start
023  HAL_Firmware_Persistence_Stop
024  HAL_Firmware_Persistence_Write
025  HAL_Free
026  HAL_GetChipID
027  HAL_GetDeviceID(Not required for versions 2.3.1 and later)
028  HAL_GetDeviceName
029  HAL_GetDeviceSecret
030  HAL_GetFirmwareVersion
031  HAL_GetModuleID
032  HAL_GetPartnerID
033  HAL_GetProductKey
034  HAL_GetProductSecret
035  HAL_GetTimeStr(Not required for versions 2.3.1 and later)
036  HAL_Kv_Del
037  HAL_Kv_Erase_All
038  HAL_Kv_Get
039  HAL_Kv_Set
040  HAL_Malloc
041  HAL_MutexCreate
042  HAL_MutexDestroy
043  HAL_MutexLock
044  HAL_MutexUnlock
045  HAL_Printf
046  HAL_Random
047  HAL_Reboot
048  HAL_RF433_Get_Rssi_Dbm
049  HAL_SemaphoreCreate
050  HAL_SemaphoreDestroy
051  HAL_SemaphorePost
052  HAL_SemaphoreWait
053  HAL_SetDeviceName
054  HAL_SetDeviceSecret
055  HAL_SetProductKey
056  HAL_SetProductSecret
057  HAL_SleepMs
058  HAL_Snprintf
059  HAL_Srandom
060  HAL_SSL_Destroy
061  HAL_SSL_Establish
062  HAL_SSL_Read
063  HAL_SSL_Write
064  HAL_Sys_Net_Is_Ready
065  HAL_Sys_reboot(Not required for versions 2.3.0 and later)
066  HAL_TCP_Destroy
067  HAL_TCP_Establish
068  HAL_TCP_Read
069  HAL_TCP_Write
070  HAL_ThreadCreate
071  HAL_ThreadDelete
072  HAL_ThreadDetach
073  HAL_Timer_Create
074  HAL_Timer_Delete
075  HAL_Timer_Start
076  HAL_Timer_Stop
077  HAL_UDP_bindtodevice
078  HAL_UDP_close
079  HAL_UDP_close_without_connect
080  HAL_UDP_connect
081  HAL_UDP_create
082  HAL_UDP_create_without_connect
083  HAL_UDP_joinmulticast
084  HAL_UDP_read
085  HAL_UDP_readTimeout
086  HAL_UDP_recv
087  HAL_UDP_recvfrom
088  HAL_UDP_send
089  HAL_UDP_sendto
090  HAL_UDP_write
091  HAL_UptimeMs
092  HAL_UTC_Get
093  HAL_UTC_Set
094  HAL_Vsnprintf
095  HAL_Wifi_Enable_Mgmt_Frame_Filter
096  HAL_Wifi_Get_Ap_Info
097  HAL_Wifi_Get_IP
098  HAL_Wifi_Get_Mac
099  HAL_Wifi_Get_Os_Version
100  HAL_Wifi_Get_Rssi_Dbm
101  HAL_Wifi_Low_Power
102  HAL_Wifi_Scan
103  HAL_Wifi_Send_80211_Raw_Frame

For function implementations, see the sample code provided in src/ref-impl/hal/os/ubuntu and src/ref-impl/hal/os/win7.

src/ref-impl/hal$ tree -A
.
+-- CMakeLists.txt
+-- iot.mk
+-- iotx_hal_internal.h
+-- os
|   +-- macos
|   |   +-- HAL_Crypt_MacOS.c
|   |   +-- HAL_OS_MacOS.c
|   |   +-- HAL_TCP_MacOS.c
|   |   +-- HAL_UDP_MacOS.c
|   +-- ubuntu
|   |   +-- base64.c
|   |   +-- base64.h
|   |   +-- cJSON.c
|   |   +-- cJSON.h
|   |   +-- HAL_Crypt_Linux.c
|   |   +-- HAL_OS_linux.c
|   |   +-- HAL_TCP_linux.c
|   |   +-- HAL_UDP_linux.c
|   |   +-- kv.c
|   |   +-- kv.h
|   +-- win7
|       +-- HAL_OS_win7.c
|       +-- HAL_TCP_win7.c
+-- ssl
    +-- itls
    |   +-- HAL_TLS_itls.c
    +-- mbedtls
    |   +-- HAL_DTLS_mbedtls.c
    |   +-- HAL_TLS_mbedtls.c
    +-- openssl
        +-- HAL_TLS_openssl.c

Basic

Function name	Required	Description
`HAL_Malloc`	Yes	Allocates a block of memory from the heap.
`HAL_Free`	Yes	Frees a block of memory from the heap.
`HAL_SleepMs`	Yes	Sleeps the current execution thread for a specified number of milliseconds.
`HAL_Snprintf`	Yes	Formats and stores a series of characters and values in a memory buffer. For more information, see the C99 standard library function `snprintf`.
`HAL_Printf`	Yes	Prints logs or debug information to a serial port or other standard output.
`HAL_Vsnprintf`	Yes	Prints a variable of the `va_list` type to a specified destination string.
`HAL_UptimeMs`	Yes	Gets the number of milliseconds that have elapsed since the device was powered on.
`HAL_Kv_Set`	Yes	Writes the specified key-value (KV) data.
`HAL_Kv_Get`	Yes	Reads the specified KV data.
`HAL_Kv_Del`	Yes	Deletes the specified KV data.
`HAL_Kv_Erase_All`	Yes	Erases all KV data.

Multi-threading

Function	Required	Description
`HAL_MutexCreate`	No	Creates a mutex for synchronization control. For single-threaded applications, you can implement this as an empty function.
`HAL_MutexDestroy`	No	Destroys a mutex for synchronization control. For single-threaded applications, you can implement this as an empty function.
`HAL_MutexLock`	No	Locks a mutex for synchronization control. For single-threaded applications, you can implement this as an empty function.
`HAL_MutexUnlock`	No	Unlocks a mutex for synchronization control. For single-threaded applications, you can implement this as an empty function.
`HAL_ThreadCreate`	No	Creates a thread based on the specified input parameters. For single-threaded applications, you can implement this as an empty function.
`HAL_ThreadDelete`	No	Terminates the specified thread. For single-threaded applications, you can implement this as an empty function.
`HAL_ThreadDetach`	No	Sets the specified thread to the `Detach` state. For single-threaded applications, you can implement this as an empty function.
`HAL_SemaphoreCreate`	No	Creates a counting semaphore. For single-threaded applications, you can implement this as an empty function.
`HAL_SemaphoreDestroy`	No	Destroys a counting semaphore. For single-threaded applications, you can implement this as an empty function.
`HAL_SemaphorePost`	No	Increments the specified counting semaphore to release other waiting threads. For single-threaded applications, you can implement this as an empty function.
`HAL_SemaphoreWait`	No	Waits on and decrements the specified counting semaphore. For single-threaded applications, you can implement this as an empty function.

MQTT and HTTP channel features

Function Name	Required	Description
`HAL_SSL_Destroy`	No	Destroys a TLS connection. Used for MQTT and HTTPS features.
`HAL_SSL_Establish`	No	Establishes a TLS connection. Used for MQTT and HTTPS features.
`HAL_SSL_Read`	No	Reads data from a TLS connection. Used for MQTT and HTTPS features.
`HAL_SSL_Write`	No	Writes data to a TLS connection. Used for MQTT and HTTPS features.
`HAL_TCP_Destroy`	No	Terminates a TLS connection used for the MQTT and HTTPS features.
`HAL_TCP_Establish`	No	Establishes a TCP connection. This includes domain name resolution and TCP connection establishment.
`HAL_TCP_Read`	No	Reads stream data from a TCP connection within a specified time and returns the number of bytes read.
`HAL_TCP_Write`	No	Sends stream data to a TCP connection within a specified time and returns the number of bytes sent.
`HAL_Random`	No	Accepts an unsigned number as a range and returns a random unsigned number within the range of 0 to the specified value.
`HAL_Srandom`	No	Seeds the random number generator so that `HAL_Random` returns a different value in each execution sequence. This is similar to `srand`.

CoAP channel features

Function name	Required	Description
`HAL_DTLSSession_create`	No	Initializes DTLS resources and establishes a DTLS session. Used for the CoAP feature.
`HAL_DTLSSession_free`	No	Destroys a DTLS session and releases DTLS resources. Used for the CoAP feature.
`HAL_DTLSSession_read`	No	Reads data from a DTLS connection. Used for the CoAP feature.
`HAL_DTLSSession_write`	No	Writes data to a DTLS connection. Used for the CoAP feature.
`HAL_Aes128_Cbc_Decrypt`	No	Decrypts data using AES-128 in CBC mode. Used for CoAP message encryption and decryption.
`HAL_Aes128_Cbc_Encrypt`	No	Encrypts data using AES-128 in CBC mode. Used for CoAP message encryption and decryption.
`HAL_Aes128_Cfb_Decrypt`	No	Decrypts data using AES-128 in CFB mode. Used for CoAP message encryption and decryption.
`HAL_Aes128_Cfb_Encrypt`	No	Encrypts data using AES-128 in CFB mode. Used for CoAP message encryption and decryption.
`HAL_Aes128_Destroy`	No	Deinitializes AES-128.
`HAL_Aes128_Init`	No	Initializes AES-128.
`HAL_UDP_close`	No	Closes a UDP socket.
`HAL_UDP_create`	No	Creates a UDP socket.
`HAL_UDP_read`	No	Reads a packet from a UDP socket in blocking mode and returns the number of bytes read.
`HAL_UDP_readTimeout`	No	Reads a packet from a UDP socket within a specified time and returns the number of bytes read.
`HAL_UDP_write`	No	Sends a packet to a UDP socket in blocking mode and returns the number of bytes sent.

Local communication features

Function	Required	Description
`HAL_UDP_create_without_connect`	No	Creates a local UDP socket without initiating any network interaction.
`HAL_UDP_close_without_connect`	No	Destroys the specified UDP socket and revokes its resources.
`HAL_UDP_joinmulticast`	No	Sends a request to join a multicast group on the specified UDP socket.
`HAL_UDP_sendto`	No	Sends data of a specified length from a specified buffer on the specified UDP socket. The blocking time does not exceed the specified duration. The function returns early if all data is sent.
`HAL_UDP_recvfrom`	No	Receives data of a specified length into a buffer from the specified UDP handle. The blocking time does not exceed the specified duration. The function returns early if all data is received. The source address is saved in the response parameter.

Device information settings and retrieval

Function	Required	Description
`HAL_GetChipID`	Yes	Gets the chip ID.
`HAL_GetDeviceID`	Yes	Gets the device ID. Note This function is not required for versions 2.3.1 and later.
`HAL_GetFirmwareVersion`	Yes	Gets the firmware version number.
`HAL_GetModuleID`	Yes	Gets the module ID. This is for close partners. Other customers can implement this as an empty function.
`HAL_GetPartnerID`	Yes	Gets the partner ID. This is for close partners. Other customers can implement this as an empty function.
`HAL_GetDeviceName`	Yes	Gets the DeviceName. This function must be implemented.
`HAL_GetDeviceSecret`	Yes	Gets the DeviceSecret. This function must be implemented.
`HAL_GetProductKey`	Yes	Gets the ProductKey. This function must be implemented.
`HAL_GetProductSecret`	Yes	Gets the ProductSecret. This function must be implemented.
`HAL_SetDeviceName`	Yes	Sets the DeviceName. This function must be implemented.
`HAL_SetDeviceSecret`	Yes	Sets the DeviceSecret. This function must be implemented.
`HAL_SetProductKey`	Yes	Sets the ProductKey. This function must be implemented.
`HAL_SetProductSecret`	Yes	Sets the ProductSecret. This function must be implemented.

OTA features

Function name	Required	Description
`HAL_Firmware_Persistence_Start`	No	Starts firmware persistence. This function must be implemented if the OTA feature is included.
`HAL_Firmware_Persistence_Stop`	No	Stops firmware persistence. This function must be implemented if the OTA feature is included.
`HAL_Firmware_Persistence_Write`	No	Writes data for firmware persistence. This function must be implemented if the OTA feature is included.

Local scheduled task features

Function name	Required	Description
`HAL_UTC_Set`	No	Sets the UTC time in milliseconds.
`HAL_UTC_Get`	No	Gets the UTC time in milliseconds.

Wi-Fi provisioning features

Function name	Required	Description
`HAL_Config_Read`	No	Reads data from the start of the configuration area on the device's persistent external storage, such as a flash memory, into a specified memory buffer.
`HAL_Config_Write`	No	Writes data from a specified memory buffer to the start of the configuration area on the device's persistent external storage, such as a flash memory.
`HAL_RF433_Get_Rssi_Dbm`	No	Gets the Received Signal Strength Indicator (`RSSI`) for RF433.
`HAL_Sys_Net_Is_Ready`	No	Checks if the system network is active.
`HAL_Wifi_Enable_Mgmt_Frame_Filter`	No	Enables or disables management frame filtering in Station (`STA`) mode.
`HAL_Wifi_Get_Ap_Info`	No	Gets information about the connected access point (`AP`).
`HAL_Wifi_Get_IP`	No	Gets the IP address of the Wi-Fi network interface. The address in dotted decimal notation is saved in the string array response parameter. The address in binary format is returned in network byte order.
`HAL_Wifi_Get_Mac`	No	Gets the MAC address of the Wi-Fi network interface. The format is `"XX:XX:XX:XX:XX:XX"`.
`HAL_Wifi_Get_Os_Version`	No	Gets the operating system version string on the Wi-Fi module.
`HAL_Wifi_Get_Rssi_Dbm`	No	Gets the RSSI for Wi-Fi.
`HAL_Wifi_Low_Power`	No	Puts the Wi-Fi module into power-saving mode for a period of time.
`HAL_Wifi_Scan`	No	Starts a Wi-Fi scan. This API is a blocking operation. After the list of all APs is collected, the C-SDK is notified through a callback function.
`HAL_Wifi_Send_80211_Raw_Frame`	No	Sends a raw 802.11 frame on the current channel at the basic data rate of 1 Mbps.