All Products
Search
Document Center

WiFi Provisioning

Last Updated: May 13, 2020

Background instructions

Wi-Fi devices need to connect to a Wi-Fi hotspot (Wi-Fi AP) before they can communicate with other devices over IP. The procedure for Wi-Fi devices to obtain the SSID or password to connect to a Wi-Fi hotspot is called the Wi-Fi Provision. For mobile phones, computers, and tablets, users can enter the Wi-Fi hotspot’s SSID/password using the keyboard or touch screen. Obtaining the Wi-Fi hotspot’s SSID or password is the first key step to realizing remote device management for Wi-Fi IoT devices without a keyboard or touch screen.

In order to save Wi-Fi device vendors’ provision solutions development costs, Alibaba Cloud IoT provides several provision solutions for Wi-Fi IoT devices. Vendors can integrate the best solution for their needs.

Note: Currently, provision solutions provided by Alibaba are only for home Wi-Fi networks (that is, devices use SSID/password to connect to Wi-Fi hotspots). They do not support provisioning corporate Wi-Fi network scenarios (that is, devices use SSID, username or password to connect to Wi-Fi hotspots) at this time.

Description of provision solutions

The following is a brief description of the provision solutions provided by Alibaba Cloud IoT:

One-click provision

The one-click provision solution broadcasts and transmits the Wi-Fi hotspot’s SSID or password with a special encoding method on the Wi-Fi management frame through a mobile phone. The device decodes the SSID or password by monitoring the Wi-Fi management frame, and then connects to the Wi-Fi hotspot through the SSID/password it obtains. It works as follows:

image.png | left | 733x158

Note:

  • The mobile phone connects to the Wi-Fi hotspot and broadcasts the SSID or password on a fixed channel.
  • The device polls all the Wi-Fi channels to detect a provision notice, and if it finds one, decodes the Wi-Fi hotspot’s SSID or password from the provision notice.

Note: Currently, most Wi-Fi IoT devices only support 2.4 GHz bands, so the current device implementation for a one-click provision solution only detects provision frames on the 1~11 channels of Wi-Fi 2.4 GHz.

Mobile phone hotspot provision

The mobile phone hotspot solution starts a provision hotspot on the mobile phone, where the SSID/password is fixed. The Wi-Fi device then connects to the mobile phone’s provision hotspot through the preset SSID/password, and the mobile phone sends the Internet hotspot’s SSID/password to the Wi-Fi device. Finally, the Wi-Fi device connects to the Wi-Fi Internet hotspot using the SSID or password sent from the mobile phone. It works as follows:

image.png | left | 676x108

Note:

  • Users need to manually configure the mobile phone provision hotspot information on their mobile phone, and enter the Internet hotspot information for the wireless router. This can be difficult for some users.

Zero-configuration

Both the one-click provision and the mobile phone hotspot provision require users to enter the SSID or password of one or two hotspots. This may easily result in users mistakenly entering wrong information. Zero-configuration is a provision solution that does not require users to input hotspot information. The idea is for a device connected to an Internet hotspot to send the hotspot’s SSID or password to the device to be provisioned. A simple description of Zero-configuration steps is as follows:

image.png | left | 656x409

The previous steps show that users do not need to enter the Internet hotspot’s SSID or password. Instead, they just select and determine the device that needs to be provisioned. This delivers a better user experience, provided the user has a network-connected device that supports zero-configuration and has already been provisioned.

Note: Tmall Genie speakers support provisioning Wi-Fi devices through zero-configuration. If you want the devices to be provisioned by Tmall Genie, they must have an integrated zero-configuration solution.

Router provision

The idea of router provision is to let the router start a fixed provision hotspot, preset the provision hotspot’s SSID or password on the device to be provisioned, connect to the router when the device to be provisioned is powered on, and then report the information of the device to be provisioned to the cloud through the router. The mobile phone can obtain the list of devices to be provisioned, select the devices to be provisioned, and then ask the router to send the Internet hotspot’s SSID or password to the devices to be provisioned. The steps for this solution are shown in the following figure:

image.png | left | 609x321

The router provision also does not require users to enter the Internet hotspot’s SSID or password on their mobile phones, provided the router supports Alibaba’s router provision solution. Router vendors who want to integrate the solution on their router can contact Alibaba’s business department to apply for implementation.

Configuration

Linkkit-sdk-c/make.settings files specify related macros that users can configure through make menuconfig

  1. # Enable Wi-Fi provision
  2. FEATURE_WIFI_PROVISION_ENABLED=y
  3. #
  4. # AWSS configurations
  5. #
  6. # SmartConfig with bcast and WPS
  7. FEATURE_AWSS_SUPPORT_SMARTCONFIG=y
  8. # Phone as hotspot (AHA)
  9. FEATURE_AWSS_SUPPORT_PHONEASAP=y
  10. # Router solution (ADHA for discovery, AHA for setup)
  11. FEATURE_AWSS_SUPPORT_ROUTER=y
  12. # Zero Config
  13. FEATURE_AWSS_SUPPORT_ZEROCONFIG=y

Description of HAL porting provision


sdk-encap/imports/iot_import_product.h

No. Function name Description
01 HAL_GetDeviceName Gets the DeviceName of the device, which is used to identify the name of the device and is one of the quadruple
02 HAL_GetDeviceSecret Gets the DeviceSecret of the device, which is used to identify the secret of the device item and is one of the quadruple
03 HAL_GetProductKey Gets the ProductKey of the device, which is used to identify the category of the device and is one of the quadruple
04 HAL_GetProductSecret Gets the ProductSecret of the device, which is used to identify the category of the device and is one of the quadruple

sdk-encap/imports/iot_import_awss.h

No. Function name Description
01 HAL_Aes128_Cbc_Decrypt Decrypts the specified ciphertext in AES-CBC-128 mode based on the secret passed in when executing HAL_Aes128_Init()
02 HAL_Aes128_Cbc_Encrypt Encrypts the specified plaintext in AES-CBC-128 mode based on the secret passed in when executing HAL_Aes128_Init()
03 HAL_Aes128_Cfb_Decrypt Decrypts the specified ciphertext in AES-CFB-128 mode based on the secret passed in when executing HAL_Aes128_Init()
04 HAL_Aes128_Cfb_Encrypt Encrypts the specified plaintext in AES-CFB-128 mode based on the secret passed in when executing HAL_Aes128_Init()
05 HAL_Aes128_Destroy Destroys AES encrypted structure
06 HAL_Aes128_Init Initializes AES encrypted structure
07 HAL_Awss_Get_Channelscan_Interval_Ms Gets the length of time scanned on each channel in milliseconds
08 HAL_Sys_Net_Is_Ready Checks if the current IP address of the Wi-Fi network card, chip, or module is valid
09 HAL_Awss_Get_Encrypt_Type Gets the security level of the smartconfig service
10 HAL_Awss_Get_Conn_Encrypt_Type Gets the security level of connection-based provision services (hotspot provision, router provision or zero-configuration)
11 HAL_Awss_Get_Timeout_Interval_Ms Gets the timeout interval of the provision service (AWSS) in milliseconds
12 HAL_Awss_Open_Monitor The device operates in Monitor mode and calls the incoming callback function when it receives 802.11 frames (including management frames and data frames)
13 HAL_Awss_Close_Monitor Turn off Monitor mode
14 HAL_Awss_Switch_Channel Sets the Wi-Fi device to switch to the specified channel
15 HAL_Wifi_Scan Start a Wi-Fi Scan
16 HAL_Wifi_Send_80211_Raw_Frame Sends raw 802.11 frames (raw 802.11 frame) on the current channel at the basic data rate (1 Mbit/s)
17 HAL_Wifi_Enable_Mgmt_Frame_Filter Enables or disables filtering of management frames in Station mode
18 HAL_Wifi_Get_Ap_Info Gets information about the hotspot (Access Point) that the device is connected to
19 HAL_Wifi_Get_IP Gets the IP address of the device, which is stored in Dotted Decimal Notation format in the outgoing parameters of the string array. Meanwhile, its binary format is used as a return value and expressed in network byte order (big-endian)
20 HAL_Wifi_Get_Mac Gets the MAC address of the device in the format "XX:XX:XX:XX:XX:XX"
21 HAL_Kv_Set Writes the key–value pair (Key–Value) in Flash
22 HAL_Kv_Get Reads thevalueof the key–value pair in Flash
23 HAL_Kv_Del Deletes the key–value pair in Flash
24 HAL_Kv_Erase_All Erases the entire area where the key–value pair is stored
25 HAL_Timer_Create Create Timer fromName,TimerFunc, and the user context
26 HAL_Timer_Start Timer starts timing. Timer calls the TimerFunc callback function when it times out
27 HAL_Timer_Stop Stops the Timer
28 HAL_Timer_Delete Deletes Timer and releases resources

HAL API instructions:

1) HAL_Wifi_Get_Mac

  1. #define HAL_MAC_LEN (17 + 1)
  2. /**
  3. *@brief gets the MAC address of the Wi-Fi network interface in "XX:XX:XX:XX:XX:XX" format
  4. *
  5. *@param mac_str: a buffer array for storing MAC address strings
  6. *@return a character pointer to the beginning of the buffer array
  7. */
  8. char *HAL_Wifi_Get_Mac(char mac_str[HAL_MAC_LEN]);

2) HAL_Wifi_Get_IP

  1. #define HAL_IP_LEN (15 + 1)
  2. /**
  3. *@brief gets the IP address of the Wi-Fi network interface, which is stored in Dotted Decimal Notation format in the string array,
  4. * while its binary format is used as a return value and expressed in network byte order (big-endian)
  5. *
  6. *@param ifname: specifies the name of the Wi-Fi network interface. Single-port Wi-Fi can ignore
  7. * this parameter, which may be NULL
  8. *@param ip_str: An array that holds IP address strings in Dotted Decimal Notation format
  9. *@return IP addresses in binary form organized in network byte order (big-endian)
  10. */
  11. uint32_t HAL_Wifi_Get_IP(char ip_str[HAL_IP_LEN], const char *ifname);

3) HAL_Wifi_Scan

  1. /**
  2. *@brief starts a Wi-Fi Scan
  3. *
  4. *@param[in] the CB module or chip scans all channels for AP,
  5. * and informs AWSS one by one through the callback function after all the AP lists have been collected;
  6. *@return 0 for Wi-Fi scan is done, otherwise return -1
  7. *@see None.
  8. *@note
  9. * The API is a block operation and the scan cannot be finished until the operation is completed. Once the function returns, it means the scan has finished;
  10. * In addition, due to memory optimization, each module or chip limits the number of APs that can be contained in the AP list, but not less than 50;
  11. * This rule is similar to the following:
  12. * HAL_Wifi_Scan() is invoked...
  13. * ...
  14. * for (ap = first_ap; ap<= last_ap; ap = next_ap){
  15. * cb(ap)
  16. * }
  17. * ...
  18. * HAL_Wifi_Scan() exit...
  19. */
  20. int HAL_Wifi_Scan(awss_wifi_scan_result_cb_t cb);
  21. Description of scanning the callback function:
  22. typedef int (*awss_wifi_scan_result_cb_t)(
  23. const char ssid[HAL_MAX_SSID_LEN],
  24. const uint8_t bssid[ETH_ALEN],
  25. enum AWSS_AUTH_TYPE auth,
  26. enum AWSS_ENC_TYPE encry,
  27. uint8_t channel,
  28. signed char rssi,
  29. int is_last_ap);
  30. /**
  31. * ssid: the SSID of the AP, which must end with "\0";
  32. * bssid: the BSSID of the AP
  33. * auth: the authentication method of the AP
  34. * encry: the encryption method of the AP
  35. * channel: the working channel of the AP, which can be parsed from IE in Beacon or Probe response
  36. * rssi: the RSSI for the AP, the value range of which is [-1,-127]
  37. * is_last_ap: indicates if the current AP is the last AP in the AP list
  38. * Note:
  39. * SSID must end with "\0", otherwise the earlier AOS 1.3.0 or AOS 1.2. * versions may experience memory out-of-bounds access issues
  40. * that cause crashes. The latest AOS 1.3.1 and AOS 1.3.2 versions avoid the defects of HAL implementation;
  41. */

4) HAL_Wifi_Get_Ap_Info

  1. /**
  2. *@brief gets information about the connected hotspot (Access Point)
  3. *
  4. *@param[out] ssid: the SSID of the AP, which may be NULL
  5. *@param[out] passwd: the PASSWD for the AP, which may be NULL
  6. *@param[out] bssid: the BSSID of the AP, which may be NULL
  7. *@return:0:succeeded,1: failed
  8. *@see None.
  9. *@note
  10. * If the device does not successfully connect to the AP, the function returns -1, and the AP information is invalid;
  11. * SSID and BSSID must be correct, otherwise the zero-configuration function will be affected,
  12. * resulting in the provision application being unable to find the device to be provisioned;
  13. */
  14. int HAL_Wifi_Get_Ap_Info(
  15. char ssid[HAL_MAX_SSID_LEN],
  16. char passwd[HAL_MAX_PASSWD_LEN],
  17. uint8_t bssid[ETH_ALEN]);

5) HAL_Wifi_Send_80211_Raw_Frame

  1. /*80211 frame type */
  2. typedef enum HAL_Awss_Frame_Type {
  3. FRAME_ACTION,
  4. FRAME_BEACON,
  5. FRAME_PROBE_REQ,
  6. FRAME_PROBE_RESPONSE,
  7. FRAME_DATA
  8. } HAL_Awss_Frame_Type_t;
  9. /**
  10. *@brief sends raw 802.11 frames on the current channel at the basic data rate (1 Mbit/s).
  11. * Currently, only Beacon, Probe-Request, and Probe-Response frames are used.
  12. *
  13. *@param[in] type @n see enum HAL_Awss_frame_type
  14. *@param[in] buffer @n complete raw frame, including MAC header and FCS
  15. *@param[in] len @n length of 802.11 raw frame
  16. *@return,0: success, -1: failure, -2: unsupported.
  17. *@see None.
  18. * @note
  19. *AWSS uses this function to send RAW frames in Monitor mode and STA mode. The API
  20. *is not implemented, and the device does not support zero-configuration (including Tmall Genie voice provision or Tmall Genie Direct Connect) or
  21. *router provision
  22. */
  23. int HAL_Wifi_Send_80211_Raw_Frame(enumHAL_Awss_Frame_Type type,
  24. uint8_t* buffer, int len);

6) HAL_Wifi_Enable_Mgmt_Frame_Filter

  1. /**
  2. *@brief the handler callback function of the management frame
  3. *
  4. *@param[in] buffer @n 80211 RAW frame buffer or vendor IE buffer
  5. *@param[in] len @n Length
  6. *@param[in] rssi_dbm @n the RSSI of the current frame, the value range of which is: [-127, -1]
  7. *@param[in] buffer_type @n 0: 80211 RAW frame, 1: vendor IE
  8. *@return None.
  9. *@see None.
  10. *@note None.
  11. */
  12. typedef void (*awss_wifi_mgmt_frame_cb_t)(
  13. uint8_t *buffer,
  14. int len,
  15. signed char rssi_dbm,
  16. int buffer_type);
  17. #define FRAME_ACTION_MASK (1<< FRAME_ACTION)
  18. #define FRAME_BEACON_MASK (1<< FRAME_BEACON)
  19. #define FRAME_PROBE_REQ_MASK (1<< FRAME_PROBE_REQ)
  20. #define FRAME_PROBE_RESP_MASK (1<< FRAME_PROBE_RESPONSE)
  21. #define FRAME_DATA_MASK (1<< FRAME_DATA)
  22. /**
  23. * @brief enables or disables the filtering of management frames in STA mode
  24. *
  25. * @param[in] filter_mask @n see mask macro in enum HAL_Awss_frame_type
  26. * @param[in] vendor_oui @n the vendor OUI assigned by the Wi-Fi Alliance. If OUI is NULL,
  27. * it means that the OUI is not filtered, otherwise it is filtered according to the OUI;
  28. * @param[in] callback @n see awss_wifi_mgmt_frame_cb_t, passing 80211
  29. * frame or IE to callback. When callback is NULL
  30. * disable sniffer feature, otherwise enable it.
  31. * @return,0: success, -1: failure, -2: unsupported.
  32. * @see None.
  33. * @note AWSS uses the API in STA mode to filter specific management frames containing specific vendor IE.
  34. * If the API is not implemented, it will not support the provisioned device in the zero-configuration solution;
  35. */
  36. int HAL_Wifi_Enable_Mgmt_Frame_Filter(
  37. uint32_t filter_mask,
  38. uint8_t vendor_oui[3],
  39. awss_wifi_mgmt_frame_cb_t callback);

7) HAL_Awss_Get_Timeout_Interval_Ms

  1. /**
  2. *@brief gets the timeout interval of the provision service ("AWSS") scan, in milliseconds
  3. *
  4. *@return timeout interval, in milliseconds
  5. *@note the recommended interval is 180,000 milliseconds
  6. * Vendors can implement this function according to the needs of the project, if all Tmall projects are uniformly set to 10 minutes
  7. */
  8. int HAL_Awss_Get_Timeout_Interval_Ms(void);

8) HAL_Awss_Get_Connect_Default_Ssid_Timeout_Interval_Ms

  1. This function has been deprecated and returns 0 directly in AOS 1.3.1

9) HAL_Awss_Get_Channelscan_Interval_Ms

  1. /**
  2. *@brief gets the time interval, in milliseconds, to scan on each "channel"
  3. *
  4. *@return the time interval, in milliseconds
  5. *@note the recommended time range is 200 ms to 400 ms, and 250 ms is recommended
  6. */
  7. int HAL_Awss_Get_Channelscan_Interval_Ms(void);

10) HAL_Awss_Open_Monitor

  1. /*link type */
  2. enum AWSS_LINK_TYPE {
  3. AWSS_LINK_TYPE_NONE, // AliOS & FreeRTOS selection, RTOS HAL choose this type
  4. /* Linux HAL may choose the following type */
  5. AWSS_LINK_TYPE_PRISM,
  6. AWSS_LINK_TYPE_80211_RADIO,
  7. AWSS_LINK_TYPE_80211_RADIO_AVS,
  8. };
  9. /**
  10. *@brief the handler function of the 802.11 frame, which passes the 802.11 frame received by the sniffer module to this function
  11. *
  12. *@param[in] buf @n the 80211 frame buffer (FreeRTOS and AliOS) and buf stores
  13. frame contents starting with the 802.11 header;
  14. *@param[in] length @n length of 802.11 frame buffer
  15. *@param[in] link_type @n with FreeRTOS and AliOS, select AWSS_LINK_TYPE_NONE
  16. * Linux HAL users can select the supported link_type
  17. *@param[in] with_fcs @n whether the length of the 80211 frame buffer contains FCS, 1: contains
  18. *@param[in] rssi @n the RSSI of the current packet, the value range of which is [-127, -1]
  19. *@Note:
  20. * 1) FreeRTOS and AliOS operating systems, and buf stores frame contents starting with the 802.11 header,
  21. * which cannot be automatically aligned in 4 bytes;
  22. * 2) The length field must correspond to the content of buf and witch_fcs. If the length includes the length of the 802.11 header,
  23. * payload and FCS, then with_fcs must be equal to 1;
  24. * 3) Although the length field contains the length of the 802.11 payload, AWSS only parses the 802.11 header fields in buf
  25. * and does not parse 802.11 payload and FCS fields. Chip or module vendors can make relevant specific optimization;
  26. */
  27. typedef int (*awss_recv_80211_frame_cb_t)(
  28. char *buf, int length,
  29. enum AWSS_LINK_TYPE link_type,
  30. int with_fcs,
  31. signed char rssi);
  32. /**
  33. *@brief sets the Wi-Fi network card to work in Monitor mode and calls the incoming callback function when receiving 802.11 frames.
  34. * Both the data frame and the management frame should be passed to the callback function according to the format requirements,
  35. * and the control frame is not currently used;
  36. *
  37. *@param[in] cb @n callback function.
  38. */
  39. void HAL_Awss_Open_Monitor(awss_recv_80211_frame_cb_t cb);

11) HAL_Awss_Close_Monitor

  1. /**
  2. *@brief sets the Wi-Fi network card to close Monitor mode, and begin working in STA mode
  3. */
  4. void HAL_Awss_Close_Monitor(void);

12) HAL_Awss_Switch_Channel

  1. /**
  2. *@brief sets the Wi-Fi network card, module, or chip to switch to the specified channel
  3. *
  4. *@param[in] primary_chan @n preferred channel
  5. *@param[in] sec_chan @n secondary channel (this parameter can only be used when the channel bandwidth is 40 MHz and can be ignored when the channel width is 20 MHz)
  6. *@param[in] bssid @n this parameter was originally planned for HAL to filter packets according to the BSSID. Currently, most modules or chip vendors have not implemented this plan, so it has been abandoned and can be ignored
  7. */
  8. void HAL_Awss_Switch_Channel(
  9. char primary_channel,
  10. char secondary_channel,
  11. uint8_t bssid[ETH_ALEN]);

13) HAL_Awss_Connect_Ap

  1. /**
  2. *@brief a function that requires a Wi-Fi network card, module, or chip to connect to a specified hotspot (Access Point)
  3. *
  4. *@param[in] connection_timeout_ms @n timeout for connecting to the AP
  5. *@param[in] ssid @n the SSID of the target AP
  6. *@param[in] passwd @n the PASSWD
  7. of the target AP
  8. *@param[in] auth @n the encryption method of the target AP, which can be ignored by HAL
  9. *@param[in] encry @n the authentication method of the target AP, which can be ignored by HAL
  10. * @ Param [in] bssid @ n the BSSID of the target AP, which may be null or set to all zeros.
  11. * If this field is null or set to all zeros, HAL matches hotspots according to SSID and PASSWD.
  12. * If this field is a valid value, HAL matches hotspots according to SSID, PASSWD, and BSSID
  13. *@param[in] channel @n the channel of the target hotspot, which can be ignored
  14. *@return
  15. * @verbatim
  16. * = 0: connect AP & DHCP success
  17. * = -1: connect AP or DHCP fail/timeout
  18. * @endverbatim
  19. *@see None.
  20. *@note
  21. * 1) If the chip or module is currently connected to a hotspot, HAL first checks whether the currently connected hotspot is the same as the target hotspot
  22. * (matching SSID, PASSWD, and BSSID (if valid)), and if so, success can be returned;
  23. * if not, HAL should disconnect the current connection before connecting to the target hotspot
  24. * 2) If the BSSID field is valid, HAL should match hotspots based on SSID and BSSID;
  25. */
  26. int HAL_Awss_Connect_Ap(
  27. uint32_t connection_timeout_ms,
  28. char ssid[HAL_MAX_SSID_LEN],
  29. char passwd[HAL_MAX_PASSWD_LEN],
  30. enum AWSS_AUTH_TYPE auth,
  31. enum AWSS_ENC_TYPE encry,
  32. uint8_t bssid[ETH_ALEN],
  33. uint8_t channel);

14) HAL_Awss_Get_Encrypt_Type

  1. /**
  2. *@brief gets the security level of the SmartConfig one-click provision
  3. *
  4. *@param None.
  5. *@return The security level:
  6. * @verbatim
  7. * 0~2: abandoned
  8. * 3: unique-certificate-per-product
  9. * 4: unique-certificate-per-device
  10. * @endverbatim
  11. *@Note, adopt unique-certificate-per-product by default
  12. */
  13. int HAL_Awss_Get_Encrypt_Type();

15) HAL_Awss_Get_Conn_Encrypt_Type

  1. /**
  2. *@brief gets the security level of zero-configuration, hotspot provision, and router provision
  3. *
  4. *@param None.
  5. *@return The security level:
  6. * @verbatim
  7. * 3: unique-certificate-per-product
  8. * 4: unique-certificate-per-device
  9. * @endverbatim
  10. *@see None.
  11. */
  12. int HAL_Awss_Get_Conn_Encrypt_Type();

16) HAL_Sys_Net_Is_Ready

  1. /**
  2. *@brief checks if the current IP address of the Wi-Fi network card, chip, or module is valid
  3. *
  4. *@param None.
  5. *@return, 0: invalid IP address; 1: the IP address is valid, and a network connection can be initiated
  6. *@see None.
  7. *@note
  8. *There is a problem with the API docking, in which AWSS may fail to exit consistently. It is possible
  9. *that the device will resume scanning after successfully connecting to the AP
  10. */
  11. int HAL_Sys_Net_Is_Ready();

17) HAL_Aes128_Init

  1. typedef enum {
  2. HAL_AES_ENCRYPTION = 0,
  3. HAL_AES_DECRYPTION = 1,
  4. } AES_DIR_t;
  5. typedef void *p_HAL_Aes128_t;
  6. /**
  7. *@brief initializes AES encrypted structure
  8. *
  9. *@param[in] @n, the key of AES 128;
  10. *@param[in] @n, the IV of AES 128;
  11. *@param[in] @n, for whether AES 128 is encrypted or decrypted, see AES_DIR_t
  12. *@return p_HAL_Aes128_t, NULL: failure
  13. *@see None.
  14. *@note None.
  15. */
  16. p_HAL_Aes128_t HAL_Aes128_Init(
  17. const uint8_t *key,
  18. const uint8_t *iv,
  19. AES_DIR_t dir);

18) HAL_Aes128_Destroy

  1. /**
  2. *@brief destroys AES128 encrypted structure
  3. *
  4. *@param[in] aes:
  5. *@return, 0: succeeded; -1: failed;
  6. *@see None.
  7. *@note None.
  8. */
  9. int HAL_Aes128_Destroy(_IN_ p_HAL_Aes128_t aes);

19) HAL_Aes128_Cbc_Encrypt

  1. /**
  2. *@brief encrypts the specified plaintext in AES 128-CBC mode based on the secret passed when executing HAL_Aes128_Init()
  3. *@param[in] aes: the handle to AES, returned by HAL_Aes128_Init()
  4. *@param[in] src: the plaintext requiring encryption
  5. *@param[in] blockNum: the number of blocks in the original plaintext. blockNum=1 indicates the length of the plaintext is 16 bytes
  6. *@param[out] dst: the encrypted ciphertext (the length of the ciphertext is the same as the length of the plaintext)
  7. *@return, 0: succeeded; -1: failed
  8. *@see None.
  9. *@note None.
  10. */
  11. int HAL_Aes128_Cbc_Encrypt(
  12. p_HAL_Aes128_t aes,
  13. const void *src,
  14. size_t blockNum,
  15. void *dst);

20) HAL_Aes128_Cbc_Decrypt

  1. /**
  2. *@brief decrypts the specified ciphertext in AES 128-CBC mode based on the secret passed when executing HAL_Aes128_Init()
  3. *
  4. *@param[in] aes: the handle to AES, returned by HAL_Aes128_Init()
  5. *@param[in] src: the ciphertext requiring decryption
  6. *@param[in] blockNum: the number of blocks in the ciphertext. blockNum=1 indicates the length of the ciphertext is 16 bytes
  7. *@param[out] dst: the decrypted plaintext (the length of the ciphertext is the same as the length of the plaintext)
  8. *@return, 0: succeeded; -1: failed
  9. *@see None.
  10. *@note None.
  11. */
  12. int HAL_Aes128_Cbc_Decrypt(
  13. p_HAL_Aes128_t aes,
  14. const void *src,
  15. size_t blockNum,
  16. void *dst);

21) HAL_Aes128_Cfb_Encrypt

  1. /**
  2. *@brief encrypts the specified plaintext in AES 128-CFB mode based on the secret passed when executing HAL_Aes128_Init() (streaming encryption)
  3. *
  4. *@param[in] aes: the handle to AES, returned by HAL_Aes128_Init()
  5. *@param[in] src: the plaintext requiring encryption
  6. *@param[in] length: the length of the plaintext in bytes
  7. *@param[out] dst: the encrypted ciphertext (the length of the ciphertext is the same as the length of the plaintext)
  8. *@return
  9. * @verbatim
  10. * = 0: succeeded
  11. * = -1: failed
  12. * @endverbatim
  13. *@see None.
  14. *@note None.
  15. */
  16. int HAL_Aes128_Cfb_Encrypt(
  17. p_HAL_Aes128_t aes,
  18. const void *src,
  19. size_t length,
  20. void *dst);

22) HAL_Aes128_Cfb_Decrypt

  1. /**
  2. *@brief decrypts the specified ciphertext in AES 128-CFB mode based on the secret passed in when executing HAL_Aes128_Init()
  3. *@param[in] aes: the handle to AES, returned by HAL_Aes128_Init()
  4. *@param[in] src: the ciphertext requiring decryption
  5. *@param[in] length: the length of the ciphertext
  6. *@param[out] dst: the decrypted plaintext (the length of the ciphertext is the same as the length of the plaintext)
  7. *@return, 0: succeeded; -1: failed
  8. *@see None.
  9. *@note None.
  10. */
  11. int HAL_Aes128_Cfb_Decrypt(
  12. p_HAL_Aes128_t aes,
  13. const void *src,
  14. size_t length,
  15. void *dst);

23) HAL_GetProductKey

  1. /**
  2. *@brief gets the product key of the device, which is used to identify the device category and is one of the quadruple
  3. *
  4. *@param product_key: the array used to hold the product key string
  5. *@return the length of characters written to the product_key[] array in bytes
  6. */
  7. int HAL_GetProductKey(char product_key[PRODUCT_KEY_MAXLEN]);

24) HAL_GetProductSecret

  1. /**
  2. *@brief gets the product secret of the device, which is used to identify the device category secret and is one of the quadruple
  3. *
  4. *@param product_secret: the array used to hold the product secret string
  5. *@return the length of characters written to the product_secret[] array in bytes
  6. *@Note:
  7. * The product key and product secret of the device must be written, or the one-click provision will definitely fail;
  8. */
  9. int HAL_GetProductSecret(char product_secret[PRODUCT_SECRET_MAXLEN]);

25) HAL_GetDeviceName

  1. /**
  2. *@brief gets the device name of the device, which is used to identify the device item name and is one of the quadruple
  3. *
  4. *@param device_name: the array used to hold the device name string
  5. *@return the length of characters written to the device_name[] array in bytes
  6. */
  7. int HAL_GetDeviceName(char device_name[DEVICE_NAME_MAXLEN]);

26) HAL_GetDeviceSecret

  1. /**
  2. *@brief gets the device secret of the device, which is used to identify the device item secret and is one of the quadruple
  3. *
  4. *@param device_secret: the array used to hold the device secret string
  5. *@return the length of characters written to the device_secret[] array in bytes
  6. *@Note:
  7. * The device name and device secret must be written, or the zero-configuration, router provision, and hotspot provision will definitely fail;
  8. */
  9. int HAL_GetDeviceSecret(char device_secret[DEVICE_SECRET_MAXLEN]);

27) HAL_Kv_Set

  1. /**
  2. *@brief writes the key–value pair (Key–Value) in Flash
  3. *
  4. *@param[in] key: @n the key
  5. of the key–value pair
  6. *@param[in] key: @n the value
  7. of the key–value pair
  8. *@param[in] len: @n the length, in bytes, of the value of the key–value pair
  9. *@param[in] sync: @n synchronous operation or asynchronous operation, which can be ignored
  10. *@return 0: Success; -1: Failure.
  11. *@note
  12. * 1) When using Flash, it is better to store key–value pairs in a separate area where erasing individual pairs is supported without affecting other preset product parameters;
  13. * 2) When writing a key–value pair for the first time, HAL completes the creation of the key–value pair. When writing later, HAL completes the modification of the value in the key–value pair;
  14. */
  15. int HAL_Kv_Set(const char *key, const void *val, int len, int sync);

28) HAL_Kv_Get

  1. /**
  2. *@brief reads the value of the key–value pair in Flash
  3. *
  4. *@param[in] key: @n the key
  5. of the key–value pair
  6. *@param[in] val: @n the buffer that stores the value of the key–value pair
  7. *@param[in] len: @n the buffer length that stores the value of the key–value pair. The function returns the actual value stored in the length field;
  8. *@return 0: Success; -1: Failure.
  9. *@see None.
  10. */
  11. int HAL_Kv_Get(const char *key, void *buffer, int *len);

29) HAL_Kv_Del

  1. /**
  2. *@brief deletes the key–value pair in Flash
  3. *
  4. *@param[in] key: @n the key
  5. of the key–value pair
  6. *@return 0: Success; -1: Failure.
  7. *@see None.
  8. */
  9. int HAL_Kv_Del(const char *key);

30) HAL_Kv_Erase_All

  1. /**
  2. *@brief erases the entire area where the key–value pair is stored
  3. *
  4. *@param None.
  5. *@return 0: Success; -1: Failure.
  6. *@Note:
  7. * 1) When using Flash, it is better to store key–value pairs in a separate area where erasing individual pairs is supported without affecting other preset product parameters;
  8. */
  9. int HAL_Kv_Del(const char *key);

31) HAL_Timer_Create

  1. /*
  2. *@brief creates Timer based on Name, TimerFunc, and the user context
  3. *
  4. *@param[in] name: @n the name of the timer
  5. *@param[in] func: @n the callback function TimerFunc called when the timer is triggered
  6. *@param[in] user_data: @n the user context data
  7. *@return not NULL: Success; NULL: Failure.
  8. *@Note:
  9. * When the timer triggers, a callback function is called. The parameter of the callback function is the user context data user_data passed in when the timer was created
  10. */
  11. void *HAL_Timer_Create(
  12. const char*name,
  13. void(*func)(void *user_data),
  14. void* user_data);

32) HAL_Timer_Start

  1. /*
  2. *@brief Timer starts timing. Timer calls callback function TimerFunc when it times out
  3. *
  4. *@param[in] timer: @n the handle to the timer, created by HAL_Timer_Create
  5. *@param[in] ms: @n Timer timeout: the timeout period relative to the current time, in milliseconds
  6. *@return 0: Success; -1: Failure.
  7. *@see None.
  8. *@Note:
  9. * 1) If the timer doesn't time out, stop the last timer first and start timing again;
  10. * 2) If the timer has timed out and has not yet been executed (the corresponding function has not yet been called), terminate the call to the callback function;
  11. * 3) The user can start the timer again using the Timer callback function, by calling HAL_Timer_Start(Timer) in the Timer callback function
  12. */
  13. int HAL_Timer_Start(void *timer, int ms);

33) HAL_Timer_Stop

  1. /*
  2. *@brief stop the timer from timing
  3. *
  4. *@param[in] timer: @n the handle to the timer, created by HAL_Timer_Create
  5. *@return 0: Success; -1: Failure.
  6. *@Note:
  7. * 1) If the timer does not time out, stop the timer directly
  8. * 2) If the timer has timed out and has not yet been executed (the corresponding function has not yet been called), terminate the call to the callback function;
  9. */
  10. int HAL_Timer_Stop(void *timer);

34) HAL_Timer_Delete

  1. /*
  2. *@brief delete the timer and release resources
  3. *
  4. *@param[in] timer: @n the handle to the timer, created by HAL_Timer_Create
  5. *@return 0: Success; -1: Failure.
  6. *@Note:
  7. * 1) If the timer does not time out, stop the timer first and release resources
  8. * 2) If the timer has timed out and has not yet been executed (the corresponding function has not yet been called), terminate the call to the callback function and release resources;
  9. */
  10. int HAL_Timer_Delete(void *timer);

Provision programming

  1. uint8_t bssid[ETH_ALEN] = {0};
  2. char ssid[HAL_MAX_SSID_LEN] = {0};
  3. char passwd[HAL_MAX_PASSWORD_LEN] = {0};
  4. // die or chipset uses itself API to get SSID/PASSWD/BSSID
  5. if (INVALID_SSID(ssid) || INVALID_BSSID(bssid) || AP_NOT_EXIST(ssid, bssid) {
  6. awss_start();
  7. } else {
  8. HAL_Awss_Connect_Ap(TIMEOUT_MS, ssid, passwd, 0, 0, bssid, 0);
  9. }