Wi-Fi Provisioning HAL
In AES-CBC-128 encryption/decryption mode, this function uses the key passed when HAL_Aes128_Init() is called. The function decrypts blockNum blocks of ciphertext from the src location and stores the resulting plaintext in the memory buffer at the dst location.
Prototype
typedef void *p_HAL_Aes128_t;
int HAL_Aes128_Cbc_Decrypt(
_IN_ p_HAL_Aes128_t aes,
_IN_ const void *src,
_IN_ size_t blockNum,
_OU_ void *dst);
Description
Parameters
| Parameter | Data type | Direction | Description |
| aes | void * | Input | The handle returned from a successful call to HAL_Aes128_Init(). This handle is a required input parameter for all subsequent HAL interfaces related to AES encryption and decryption. |
| src | const void * | Input | The starting address of the source data buffer to be decrypted. This is the starting address of the AES ciphertext. |
| blockNum | size_t | Input | The length of the source data buffer to be decrypted. The length is measured in blocks, where one block is 16 bytes. This parameter specifies the total length of the ciphertext in multiples of 16 bytes. |
| dst | void * | Output | The starting address of the destination data buffer. This is where the plaintext is stored after AES decryption. |
Return values
| Value | Description |
| 0 | Decryption successful. |
| -1 | Decryption failed. |
HAL_Aes128_Cbc_Encrypt
Prototype
int HAL_Aes128_Cbc_Encrypt(
_IN_ p_HAL_Aes128_t aes,
_IN_ const void *src,
_IN_ size_t blockNum,
_OU_ void *dst);
Description
Encrypts plaintext data using the AES-CBC-128 mode. This function uses the key that was passed when HAL_Aes128_Init() was called. It encrypts a number of blocks, specified by blockNum, from the src location. The resulting ciphertext is stored in the memory buffer at the dst location.
Parameters
| Parameter | Data type | Direction | Description |
| aes | void * | Input | The handle returned from a successful call to HAL_Aes128_Init(). This handle is a required input parameter for all subsequent HAL interfaces related to AES encryption and decryption. |
| src | const void * | Input | The starting address of the source data buffer to be encrypted. This is the starting address of the plaintext. |
| blockNum | size_t | Input | The length of the source data buffer to be encrypted. The length is measured in blocks, where one block is 16 bytes. This parameter specifies the total length of the plaintext in multiples of 16 bytes. |
| dst | void * | Output | The starting address of the destination data buffer. This is where the AES ciphertext is stored after encryption. |
Return values
| Value | Description |
| 0 | Encryption successful. |
| -1 | Encryption failed. |
HAL_Aes128_Cfb_Decrypt
Prototype
int HAL_Aes128_Cfb_Decrypt(
_IN_ p_HAL_Aes128_t aes,
_IN_ const void *src,
_IN_ size_t length,
_OU_ void *dst);
Description
Performs AES-128 decryption in Cipher Feedback (CFB) mode. Before you call this function, you must call HAL_Aes128_Init() to create an AES context struct.
The length parameter specifies the number of blocks, not the number of bytes. One AES-128 block is 128 bits, or 16 bytes.
You do not need to handle padding when you implement this function. The software development kit (SDK) handles padding before calling this interface.
Parameters
| Parameter | Data type | Direction | Description |
| aes | void * | Input | A pointer to the context struct returned by HAL_Aes128_Init(). |
| src | const void * | Input | A pointer to the ciphertext data buffer. |
| blockNum | size_t | Input | The number of blocks of ciphertext data. One AES-128 block is 16 bytes. |
| dst | void * | Output | A pointer to the ciphertext data buffer. |
Return values
| Value | Description |
| 0 | Decryption successful. |
| -1 | Decryption failed. |
HAL_Aes128_Cfb_Encrypt
Prototype
int HAL_Aes128_Cfb_Encrypt(
_IN_ p_HAL_Aes128_t aes,
_IN_ const void *src,
_IN_ size_t length,
_OU_ void *dst);
Description
Performs AES-128 encryption in CFB mode. Before you call this function, you must call HAL_Aes128_Init() to create an AES context struct.
The length parameter specifies the number of blocks, not the number of bytes. One AES-128 block is 128 bits, or 16 bytes.
You do not need to handle padding when you implement this function. The SDK handles padding before calling this interface.
Parameters
| Parameter | Data type | Direction | Description |
| aes | p_HAL_Aes128_t | Input | A pointer to the context struct returned by HAL_Aes128_Init(). |
| src | const void * | Input | A pointer to the plaintext data buffer. |
| length | size_t | Input | The number of blocks of plaintext data. One AES-128 block is 16 bytes. |
| dst | void * | Output | A pointer to the buffer for the encrypted ciphertext data. |
Return values
| Value | Description |
| 0 | Encryption successful |
| -1 | Encryption failure |
HAL_Aes128_Destroy
Prototype
int HAL_Aes128_Destroy(_IN_ p_HAL_Aes128_t aes);
Description
Destroys the AES context struct and releases memory resources.
Parameters
| Parameter | Data type | Direction | Description |
| aes | p_HAL_Aes128_t | Input | A pointer to the context struct returned by HAL_Aes128_Init(). |
Return values
| Value | Description |
| 0 | Operation successful. |
| -1 | Operation failed. |
HAL_Aes128_Init
Prototype
p_HAL_Aes128_t HAL_Aes128_Init(
_IN_ const uint8_t *key,
_IN_ const uint8_t *iv,
_IN_ AES_DIR_t dir);
Description
Initializes the context struct for the AES encryption and decryption algorithm. This function also initializes the AES algorithm based on the dir parameter. You can customize the struct type, but the struct must contain context data, such as the key and the initialization vector (IV).
Parameters
| Parameter | Data type | Direction | Description |
| key | const uint8_t * | Input | The starting address of the AES key array. The key array must be at least 16 bytes long. |
| iv | const uint8_t * | Input | The starting address of the AES IV array. The IV array must be at least 16 bytes long. |
| dir | AES_DIR_t | Input | Specifies the purpose of the AES algorithm. `HAL_AES_ENCRYPTION` indicates encryption. `HAL_AES_DECRYPTION` indicates decryption. |
typedef enum {
HAL_AES_ENCRYPTION = 0, // For encryption
HAL_AES_DECRYPTION = 1, // For decryption
} AES_DIR_t;
Return values
A pointer to the initialized AES context struct. The type p_HAL_Aes128_t is defined as follows:
typedef void *p_HAL_Aes128_t;
HAL_Awss_Close_Monitor
Prototype
void HAL_Awss_Close_Monitor(void);
Description
Disables monitor mode on the Wi-Fi network interface card (NIC) and switches it to station mode. This action stops packet sniffing.
Parameters
void
Return values
void
HAL_Awss_Connect_Ap
Prototype
int HAL_Awss_Connect_Ap(
_IN_ uint32_t connection_timeout_ms,
_IN_ char ssid[HAL_MAX_SSID_LEN],
_IN_ char passwd[HAL_MAX_PASSWD_LEN],
_IN_OPT_ enum AWSS_AUTH_TYPE auth,
_IN_OPT_ enum AWSS_ENC_TYPE encry,
_IN_OPT_ uint8_t bssid[ETH_ALEN],
_IN_OPT_ uint8_t channel);
Description
Connects the Wi-Fi NIC to a specified access point (AP). The `bssid` parameter specifies a particular AP. The `bssid` can be empty or have an invalid value, such as all zeros or all 0xFF.
Parameters
| Parameter | Data type | Direction | Description |
| connection_timeout_ms | uint32_t | Input | The timeout period for connecting to the AP. |
| ssid | char | Input | The SSID of the destination AP. |
| passwd | char | Input | The password for the destination AP. |
| auth | enum | Input | The authentication type of the destination AP. The HAL can ignore this parameter. |
| encry | enum | Input | The encryption type of the destination AP. The HAL can ignore this parameter. |
| bssid | uint8_t | Input | The BSSID of the destination AP. This field can be NULL or set to all zeros. |
| channel | uint8_t | Input | The channel of the destination AP. This field can be ignored. |
Return values
| Value | Description |
| 0 | Successfully connected to the AP and obtained an IP address using DHCP. |
| -1 | Failed to connect to the AP or obtain an IP address using DHCP. |
HAL_Awss_Get_Channelscan_Interval_Ms
Prototype
int HAL_Awss_Get_Channelscan_Interval_Ms(void);
Description
Retrieves the duration for scanning on each channel, in milliseconds. The recommended duration is 200 ms to 400 ms. The default value is 250 ms.
Parameters
void
Return values
The duration in milliseconds.
HAL_Awss_Get_Connect_Default_Ssid_Timeout_Interval_Ms
Prototype
int HAL_Awss_Get_Connect_Default_Ssid_Timeout_Interval_Ms(void);
Description
Retrieves the timeout interval, in milliseconds, for connecting to the default SSID after the AWSS service times out. This interface is deprecated and no longer used. You do not need to implement it.
Parameters
void
Return values
The timeout interval in milliseconds.
HAL_Awss_Get_Conn_Encrypt_Type
Prototype
int HAL_Awss_Get_Conn_Encrypt_Type(void);
Description
Retrieves the security level for zero-configuration, hot spot, and router provisioning.
Parameters
void
Return values
| Value | Description |
| 3 | aes128cfb with a per-product AES key and a random AES IV. |
| 4 | aes128cfb with a per-device AES key and a random AES IV. |
| 5 | aes128cfb with a per-manufacture AES key and a random AES IV. |
| others | Invalid. |
HAL_Awss_Get_Encrypt_Type
Prototype
int HAL_Awss_Get_Encrypt_Type(void);
Description
Retrieves the security level for the smartconfig service.
Parameters
void
Return values
| Value | Description |
| 0 | Open (no encryption). |
| 1 | aes256cfb with the default AES key and AES IV. |
| 2 | aes128cfb with the default AES key and AES IV. |
| 3 | aes128cfb with a per-product AES key and an AES IV of 0. |
| 4 | aes128cfb with a per-device AES key and an AES IV of 0. |
| 5 | aes128cfb with a per-manufacture AES key and an AES IV of 0. |
| others | Invalid. |
HAL_Awss_Get_Timeout_Interval_Ms
Prototype
int HAL_Awss_Get_Timeout_Interval_Ms(void);
Description
Retrieves the timeout interval for the AWSS service, in milliseconds. The recommended value is 60 s, or 60,000 ms.
Parameters
void
Return values
The timeout interval in milliseconds.
HAL_Awss_Open_Monitor
Prototype
void HAL_Awss_Open_Monitor(_IN_ awss_recv_80211_frame_cb_t cb);
Description
Configures the Wi-Fi NIC to operate in monitor mode. When an 802.11 frame is received, the specified callback function is invoked.
Parameters
| Parameter | Data type | Direction | Description |
| cb | awss_recv_80211_frame_cb_t | Input | A pointer to the callback function. This function is called when the Wi-Fi NIC receives a frame. |
/**
* @brief A handler for 802.11 frames. You can pass 802.11 frames to this function.
*
* @param[in] buf @n The 802.11 frame buffer, or a pointer to the ht40_ctrl struct.
* @param[in] length @n The length of the 802.11 frame buffer.
* @param[in] link_type @n Use AWSS_LINK_TYPE_NONE for most RTOS HALs.
* For a Linux HAL, check which header type the driver supports.
* @param[in] with_fcs @n Specifies whether the 802.11 frame buffer includes the 4-byte Frame Check Sequence (FCS).
* @param[in] rssi @n The Received Signal Strength Indicator (RSSI) of the packet. The range is from -127 to -1.
*/
typedef int (*awss_recv_80211_frame_cb_t)(char *buf, int length,
enum AWSS_LINK_TYPE link_type, int with_fcs, signed char rssi);
Return values
void
HAL_Awss_Switch_Channel
Prototype
void HAL_Awss_Switch_Channel(
_IN_ char primary_channel,
_IN_OPT_ char secondary_channel,
_IN_OPT_ uint8_t bssid[ETH_ALEN]);
Description
Switches the Wi-Fi NIC to a specified channel.
Parameters
| Parameter | Data type | Direction | Description |
| primary_channel | char | Input | The primary channel. |
| secondary_channel | char | Input | The secondary channel. This is used only when the channel bandwidth is 40 MHz. You can ignore this parameter for 20 MHz bandwidth. |
| bssid | uint8_t | Input | This parameter is deprecated and can be ignored. |
Return values
void
HAL_RF433_Get_Rssi_Dbm
Prototype
int HAL_RF433_Get_Rssi_Dbm(void);
Description
Retrieves the RSSI for RF433. This API is deprecated and does not need to be implemented.
Parameters
void
Return values
The signal strength value in dBm.
HAL_Sys_Net_Is_Ready
Prototype
int HAL_Sys_Net_Is_Ready(void);
Description
Checks whether the system network is available. A network is considered available if the device has successfully obtained an IP address and the IP address is active.
Parameters
void
Return values
| Value | Description |
| 0 | Network is not available. |
| 1 | Network is available. |
HAL_Wifi_Enable_Mgmt_Frame_Filter
Prototype
int HAL_Wifi_Enable_Mgmt_Frame_Filter(
_IN_ uint32_t filter_mask,
_IN_OPT_ uint8_t vendor_oui[3],
_IN_ awss_wifi_mgmt_frame_cb_t callback);
Description
Enables or disables filtering for specific management frames in station mode. When filtering is enabled, only management frames that contain a specific Organizationally Unique Identifier (OUI) are accepted.
Parameters
| Parameter | Data type | Direction | Description |
| filter_mask | uint32_t | Input | Frame filtering parameter |
| vendor_oui | uint8_t | Input | The vendor OUI assigned by the Wi-Fi Alliance. If the OUI is NULL, OUI filtering is not performed. Otherwise, frames are filtered based on the OUI. |
| callback | awss_wifi_mgmt_frame_cb_t | Input | The callback function for receiving 802.11 frames or Information Elements (IEs). |
Return values
| Value | Description |
| = 0 | Success. |
| = -1 | Failure. |
| = -2 | Not supported. |
HAL_Wifi_Get_Ap_Info
Prototype
int HAL_Wifi_Get_Ap_Info(
_OU_ char ssid[HAL_MAX_SSID_LEN],
_OU_ char passwd[HAL_MAX_PASSWD_LEN],
_OU_ uint8_t bssid[ETH_ALEN]);
Description
Retrieves information about the connected AP.
Parameters
| Parameter | Data type | Direction | Description |
| ssid | char | Output | The SSID of the AP. This parameter can be NULL. |
| passwd | char | Output | The password of the AP. This parameter can be NULL. |
| bssid | uint8_t | Output | The BSSID of the AP. This parameter can be NULL. An incorrect BSSID will cause zero-configuration device discovery to fail. |
Return values
| Value | Description |
| = 0 | Operation successful. |
| = -1 | Operation failed. |
HAL_Wifi_Get_IP
Prototype
uint32_t HAL_Wifi_Get_IP(_OU_ char ip_str[HAL_IP_LEN], _IN_ const char *ifname);
Description
Retrieves the IP address of the Wi-Fi interface. The IP address is saved as a string in dotted decimal notation in the output parameter. The function also returns the IP address in binary format and in network byte order (big-endian).
Parameters
| Parameter | Data type | Direction | Description |
| ip_str | char[] | Output | An array to store the IP address string in dotted decimal notation. |
| ifname | const char* | Input | The name of the Wi-Fi network interface. If there is only one network interface, you can ignore this parameter. This parameter can be NULL. |
Return values
The IP address in binary format. The value is in network byte order (big-endian).
HAL_Wifi_Get_Mac
Prototype
char *HAL_Wifi_Get_Mac(_OU_ char mac_str[HAL_MAC_LEN]);
Description
Retrieves the MAC address of the Wi-Fi interface. The MAC address is in the `XX:XX:XX:XX:XX:XX` format.
Parameters
| Parameter | Data type | Direction | Description |
| mac_str | char | Output | A character pointer to the start of the buffer array. |
Return values
A pointer to the first character of the buffer array.
HAL_Wifi_Low_Power
Prototype
int HAL_Wifi_Low_Power(_IN_ int timeout_ms);
Description
Puts the Wi-Fi module into power-saving mode for a specified period. This API is not currently in use and does not yet require implementation.
Parameters
| Parameter | Data type | Direction | Description |
| timeout_ms | int | Input | The duration, in milliseconds, for the Wi-Fi module to stay in power-saving mode. |
Return values
| Value | Description |
| 0 | Success. |
| -1 | Failure. |
HAL_Wifi_Scan
Prototype
int HAL_Wifi_Scan(awss_wifi_scan_result_cb_t cb);
Description
This function starts a Wi-Fi scan. This is a blocking API call and does not return until the scan is complete. After the scan is complete, the function reports all discovered APs one by one to AWSS through the callback function. Do not limit the number of APs, because this may cause provisioning to fail for hot spots with SSIDs that use GBK encoding.
Parameters
| Parameter | Data type | Direction | Description |
| cb | awss_wifi_scan_result_cb_t | Input | The scan notification callback function. |
Return values
| Value | Description |
| 0 | Scan completed normally. |
| -1 | Other cases. |
HAL_Wifi_Send_80211_Raw_Frame
Prototype
int HAL_Wifi_Send_80211_Raw_Frame(_IN_ enum HAL_Awss_Frame_Type type,
_IN_ uint8_t *buffer, _IN_ int len);
Description
Transmits a raw 802.11 frame on the current channel at the basic data rate of 1 Mbps.
Parameters
| Parameter | Data type | Direction | Description |
| type | enum HAL_Awss_Frame_Type | Input | See the definition of HAL_Awss_Frame_Type_t. Currently, only FRAME_BEACON and FRAME_PROBE_REQ |
| buffer | uint8_t * | Input | The raw 802.11 data frame, including the complete MAC header and FCS field. |
| len | int | Input | The length of the raw 802.11 frame in bytes. |
/* 802.11 frame type definitions */
typedef enum HAL_Awss_Frame_Type {
FRAME_ACTION,
FRAME_BEACON,
FRAME_PROBE_REQ,
FRAME_PROBE_RESPONSE,
FRAME_DATA
} HAL_Awss_Frame_Type_t;
Return values
| Value | Description |
| = 0 | Send successful. |
| = -1 | Send failed. |
HAL_Awss_Open_Ap
Prototype
int HAL_Awss_Open_Ap(const char *ssid, const char *passwd, int beacon_interval, int hide);
Description
Starts the device hot spot in SoftAP mode.
Parameters
| Parameter | Data type | Direction | Description |
| ssid | const char * | Input | The SSID of the hot spot. |
| passwd | const char * | Input | Hotspot password |
| beacon_interval | int | Input | The beacon broadcast interval for the hot spot. |
| hide | int | Input | 0: Not hidden. Other values: Hidden. |
| Value | Description |
| 0 | Success |
| -1 | Unsupported. |
| -2 | Failure due to a system error. |
| -3 | Failure due to insufficient memory. |
| -4 | Failure due to invalid parameters. |
HAL_Awss_Close_Ap
Prototype
int HAL_Awss_Close_Ap(void);
Description
This operation stops the device hot spot.
Parameters
void
Return values
| Value | Description |
| 0 | Success |
| -1 | Unsupported. |
| -2 | Failure. |