1. Wi-Fi® Commissioning presentation
This application gives an example of a Wi-Fi® Commissioning project, using an HTTP server over Wi-Fi®, hosted by a device configured as a soft access point (soft-AP) and station (STA).
It provides a starting point for an HTTP server solution with basic requests to allow the client to interact with the server.
The application starts in soft-AP mode, with a set SSID and password for WPA2 connection, and then shows its IP address. Once the device is connected, open a preferred web browser, and enter the IP address of the server/soft-AP. The client sends a request to the server which returns the main HTML page. This page features input fields to enter the SSID and the password of the AP for connecting the STA.
If the target AP operates on a different channel than the soft-AP, the soft-AP adjusts to match that channel. To achieve this, connected stations are disconnected, and the soft-AP is stopped and then restarted after establishing the STA connection.
Once the STA is connected, a ping button becomes clickable to send a ping to the default gateway of the STA.
2. Requirements
2.1. Software and system requirements
The software requirements are the following (minimum IDEs version):
- STM32CubeIDE toolchain V1.18.1 [1].
- IAR Embedded Workbench for ARM (EWARM) toolchain V9.30.1
- RealView Microcontroller Development Kit (MDK-ARM) toolchain V5.39
Programmer:
- STM32CubeProgrammer [2] to program the board with pre-generated binary file
HyperTerminal:
- Use the application through the serial link
- Open a HyperTerminal client connected to the host ST-LINK COM port
The serial COM port must be configured as below:
| Baudrate | 921600 |
| Data | 8b |
| Stopbit | 1b |
| Parity | None |
| Flow control | None |
| Rx | LF |
| Tx | LF |
| Local Echo | Off |
For more details, refer to the HyperTerminal setup page.
2.2. Hardware requirements
This example runs on the NUCLEO-U575ZI-Q [3] board combined with the X-NUCLEO-67W61M1 board.
The X-NUCLEO-67W61M1 board is connected to the NUCLEO-U575ZI-Q board via the Arduino® connectors:
- The 5V, 3V3, GND through the CN6
- The SPI (CLK, MOSI, MISO), SPI_CS and USER_BUTTON signals through the CN5
- The BOOT, CHIP_EN, SPI_RDY and UART TX/RX signals through the CN9
3. ST67W6X_WiFi_Commissioning application description
3.1. Project directory
The "ST67W6X_WiFi_Commissioning" application is available by downloading the X-CUBE-ST67W61 Package.
Refer to the Project directory wiki page for more information on the project directory.
3.2. Project description
3.2.1. Structure - Topology
The topology consists of the following elements:
- A PC equipped HyperTerminal to collect connection information about the soft-AP, including the SSID and its IP address.
- A station with a browser, such as a PC or a smartphone, to request the credentials HTML page hosted by the HTTP server.
- An access point (hotspot, gateway, and more) on which the device can connect.
3.2.2. Project initialization
The different steps of the application initialization are described below:
The common initialization steps shared by all applications are highlighted in light blue. The remaining steps are specific to the Commissioning and HTTP server applications.
3.3. Build and install
Refer to the build and install chapter for detailed instructions on how to build and download the software onto the device.
3.4. User setup
3.4.1. ST67W6X default configuration
The default system configuration can be modified in "ST67W6X/Target/w6x_config.h":
/** NCP will go by default in low power mode when NCP is in idle mode */ #define W6X_POWER_SAVE_AUTO 0 /** NCP clock mode : 1: Internal RC oscillator, 2: External passive crystal, 3: External active crystal */ #define W6X_CLOCK_MODE 1
The default Wi-Fi® configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Define the DHCP configuration : 0: NO DHCP, 1: DHCP CLIENT STA, 2:DHCP SERVER AP, 3: DHCP STA+AP */
#define W6X_WIFI_DHCP 3
/** Define the max number of stations that can connect to the Soft-AP */
#define W6X_WIFI_SAP_MAX_CONNECTED_STATIONS 4
/** String defining Soft-AP subnet to use.
* Last digit of IP address automatically set to 1 */
#define W6X_WIFI_SAP_IP_SUBNET {192, 168, 8}
/** String defining Soft-AP subnet to use in case of conflict with the AP the STA is connected to.
* Last digit of IP address automatically set to 1 */
#define W6X_WIFI_SAP_IP_SUBNET_BACKUP {192, 168, 9}
/** Define if the DNS addresses are set manually or automatically */
#define W6X_WIFI_DNS_MANUAL 0
/** String defining DNS IP 1 address to use
* @note: This address will be used only if W6X_WIFI_DNS_MANUAL equals 1 */
#define W6X_WIFI_DNS_IP_1 {208, 67, 222, 222}
/** String defining DNS IP 2 address to use
* @note: This address will be used only if W6X_WIFI_DNS_MANUAL equals 1 */
#define W6X_WIFI_DNS_IP_2 {8, 8, 8, 8}
/** String defining DNS IP 3 address to use
* @note: This address will be used only if W6X_WIFI_DNS_MANUAL equals 1 */
#define W6X_WIFI_DNS_IP_3 {0, 0, 0, 0}
/** Define the region code, supported values : [CN, JP, US, EU, 00] */
#define W6X_WIFI_COUNTRY_CODE "00"
/** Define if the country code will match AP's one.
* 0: match AP's country code,
* 1: static country code */
#define W6X_WIFI_ADAPTIVE_COUNTRY_CODE 0
/** String defining Wi-Fi hostname */
#define W6X_WIFI_HOSTNAME "ST67W61_WiFi"
The default net configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Timeout in ticks when calling W6X_Net_Recv() */ #define W6X_NET_RECV_TIMEOUT 10000 /** Timeout in ticks when calling W6X_Net_Send() */ #define W6X_NET_SEND_TIMEOUT 10000 /** Default Net socket receive buffer size * @note In the NCP, the LWIP recv function is used with a static buffer with * a fixed length of 4608 (3 * 1536). The data is read in chunks of 4608 bytes * So in order to get optimal performances, the buffer on NCP side should be twice as big */ #define W6X_NET_RECV_BUFFER_SIZE 4608
The AT driver can be configured in "ST67W6X\Target\w61_driver_config.h":
/** Maximum number of detected AP during the scan. Cannot be greater than 50 */ #define W61_WIFI_MAX_DETECTED_AP 50 /** Debugging only: Enable AT log, i.e. logs the AT commands incoming/outcoming from/to the NCP */ #define W61_AT_LOG_ENABLE 0
Additionally, some other options can be modified in the "ST67W6X/Target" directory with different configuration files, as outlined below:
- logging_config.h: This file provides configuration for the logging component, enabling the setting of the log level.
- shell_config.h: This file provides configuration for Shell component.
- w6x_config.h: This file provides configuration for the W6X APIs (used during init).
- w61_driver_config.h: This file provides configuration for the W61 configuration module.
All the available defines are available in template directory "Middlewares/ST/ST67W6X_Network_Driver/Conf"
3.4.2. Application configuration
The Wi-Fi® soft-AP configuration used in this application is defined in "App_WiFi_Commissioning/App/app_config.h":
/* Soft-AP connection parameters */ #define WIFI_SAP_SSID "ST67W6X_AP" #define WIFI_SAP_PASSWORD "12345678" #define WIFI_SAP_CHANNEL 1 #define WIFI_SAP_SECURITY W6X_WIFI_AP_SECURITY_WPA2_PSK #define WIFI_SAP_MAX_CONNECTIONS 4
The logging output mode can be modified in "App_WiFi_Commissioning/App/app_config.h":
/** Select output log mode [0: printf / 1: UART / 2: ITM] */ #define LOG_OUTPUT_MODE 1
The host low power mode can be modified in "App_WiFi_Commissioning/App/app_config.h":
/** Low power configuration [0: disable / 1: sleep / 2: stop / 3: standby] */ #define LOW_POWER_MODE 1
The host debugger pins can be modified in "App_WiFi_Commissioning/App/app_config.h":
/** * Enable/Disable MCU Debugger pins (dbg serial wires) * @note by HW serial wires are ON by default, need to put them OFF to save power */ #define DEBUGGER_ENABLED 1
3.5. How to use
3.5.1. Overview
The device always starts the soft-AP first to initiate the HTTP server and receive credentials.
To connect to the soft-AP using a smartphone, scan the QR code provided below for automatic connection.
By default, the soft-AP SSID is ST67W6X_AP, and the password is 12345678.
Use a device with an embedded web browser to connect to the server using the IP address provided in the logs.
Multiple clients can be connected to the server (up to two clients at the same time). The topology of the system is as following:
The main HTML page displays a form that requests the credentials needed for the STA to connect to the AP.
Once the credentials are submitted, the HTTP server stops to connect the STA to the AP.
Once connected, the "Disconnect" and "Ping" buttons become clickable, allowing the STA to disconnect from the AP or ping the AP. The results are shown in a table below the ping button.
3.5.2. HTTP requests flow
3.5.2.1. Initial HTTP requests
Once the application has started, it creates a new socket (that acts as server socket), binds it to the IP address of the soft-AP, and listens for incoming connections. In a while loop, when a new connection to the server socket is received, the server creates a new socket to manage the connection within a dedicated thread, while the server socket continues to listen for incoming connections. In this thread, the received request is parsed and processed to send the appropriate response and/or execute the actions implied by the request.
3.5.2.2. User actions
When sending the credentials (SSID and password) via the "Connect" button, it generates a POST request "POST /credentials" .
The server parses the request, sends the response to the client and then stops the HTTP server to try to connect the STA.
Since the connection state of the STA is available only on the server, it must be communicated to the client. In HTTP protocol, the requests come from the client to the server, which is the opposite of our use case.
To address this issue, the client automatically generates a request at startup through the HTML page ( "GET /connect_status" in the diagram below), which remains until the server notices a state change (connection or disconnection) of the station.
At that point, the server responds to the pending request with the connection state.
This method puts the server in control of the connection with the client, facilitating the sending of asynchronous responses.
Below is the request diagram illustrating the interaction between the server and the client:
3.5.3. File conversion
The device must be capable of handling various elements such as pages, images, and icons to send them effectively. Without a file system on our devices, these files must be converted to ASCII format for storage on the host device and transmission to the client. To achieve this, a Python script executed during pre-build performs the conversion ("Html/html_to_h.py").
It takes as input the list of the different files needed by the application, located in "Html/conf.txt". The Python script processes these files, converting them to ASCII and storing the results in pre-formatted HTTP responses, ready for transmission to the client
All the responses are stored in the file "App_WiFi_Commissioning/App/html_pages.h", which manages the HTML pages, images and icons.
This Python script is common to both ST67W6X Wi-Fi Commissioning Application and ST67W6X HTTP Server applications.
To add a new file in the conversion process, add a specific header with the response name and a new entry in the file dictionary.
html_desc_dict = {
'index_httpserver.html': [index_httpserver_header, index_httpserver_middle],
'404.html': [error_404_header, error_404_middle],
'favicon.svg': [favicon_header, svg_middle],
'ST_logo_2020_white_no_tagline_rgb.svg': [st_logo_header, svg_middle]
}
This dictionary aims to link the correct header and HTML file's type field (text/html, image/svg here named xxx_middle) to build valid responses.
This generation tool facilitates the development by using HTML files directly, bypassing the need for manual conversion and insertion of outputs into the code.
3.6. Memory footprint
| Module | Description |
|---|---|
| [Driver] HAL/CMSIS/BSP | STM32 CMSIS Cortex, HAL and LL, Board Specific Package drivers |
| [Project] Core | Native STM32 core components |
| [Project] App | Main part of the application |
| [Project] Target | Configuration files for ST67W6X_Network_Driver component |
| [MW] ST67W6X_Network_Driver | Core and API System, Wi-Fi® and Network components Util/Logging: Utility to process shell and trace messages onto the UART interface (can be changed by ITM) |
| [MW] FreeRTOS | FreeRTOS kernel source |
| [Utility] lpm | Tiny low-power management |
| [Toolchain] Startup | Int_vect, init routines, init table, CSTACK and HEAP |
| [Toolchain] EWARM Libraries | Native compiler libraries |
These values depend on the chosen toolset, and they can change in next releases.
3.6.1. ROM/flash memory footprint
The picture below shows the sum of the read only memory (flash) of the Wi-Fi® Commissioning application.
The picture below shows the middleware ST67W6X_Network_Driver read-only memory (flash) used by the Wi-Fi® Commissioning application.
3.6.2. Read/write (RW) memory footprint
The picture below shows only the sum of the static read/write memory (static RAM) of the Wi-Fi® Commissioning application.
