1. HTTPS Client presentation
This application gives an example of the HTTPS Client feature over Wi-Fi®.
It provides a starting point for an HTTPS client solution with basic GET requests to retrieve the weather from different major capitals around the globe.
The application starts in STA mode, connecting to its predefined access point (AP), which must have access to internet.
Once the station is connected, it displays the current temperature of the place whose coordinates are preconfigured in the program (by default set around Montreal).
Then, the command-line interface (CLI) mode starts, enabling users to use a new command to request weather data from a predefined list of cities via a weather API.
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 a 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_HTTPS_Client application description
3.1. Project directory
The "ST67W6X_HTTPS_Client" 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 ST67W6X_HTTPS_Client project uses the station topology:
The HyperTerminal is used to print the result of the weather request and change the location of the weather prediction.
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 HTTPS Client application.
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 1
/** 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
The default HTTP configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Timeout value in millisecond for receiving data via TCP socket used by the HTTP client. * This value is set to compensate for when the NCP get stuck for a long time (1 second or more) * when retrieving data from an HTTP server for example */ #define W6X_HTTP_CLIENT_TCP_SOCK_RECV_TIMEOUT 1000 /** Size of the TCP socket used by the HTTP client, recommended to be at least 0x2000 when fetching lots of data. * 0x2000 is the value used in the SPI host project for OTA update, which retrieves around 1 mega bytes of data. */ #define W6X_HTTP_CLIENT_TCP_SOCKET_SIZE 12288
The default utilities configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Enable LittleFS */ #define LFS_ENABLE 1
The Shell can be configured in the "ST67W6X/Target/shell_config.h" file:
/** Enable the shell component */ #define SHELL_ENABLE 1 /** Shell using color */ #define SHELL_USING_COLOR 1 /** Print an additional status message at the end of the command execution */ #define SHELL_PRINT_STATUS 0 /** Shell receive buffer size */ #define SHELL_FREERTOS_RX_BUFF_SIZE 256 /** Shell command maximum size */ #define SHELL_CMD_SIZE 256
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 to set 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 available defines are available in template directory "Middlewares/ST/ST67W6X_Network_Driver/Conf"
3.4.2. Application configuration
The Wi-Fi® configuration used in this application is defined in "App_HTTPS_Client/App/app_config.h":
#define WIFI_SSID "YOUR_SSID" #define WIFI_PASSWORD "YOUR_PASSWORD"
The logging output mode can be modified in "App_HTTPS_Client/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_HTTPS_Client/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_HTTPS_Client/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 it works
3.5.1. Overview
Once the HTTPS Client application is started, the station must connect to the registered AP, which must provide access to the Internet.
First, the application retrieves weather conditions for the upcoming week of the hardcoded location in the application. No user action is required at this stage. Once completed, the application displays a log similar to the following:
Weather forecast for the region you selected: Today: Overcast sky, Temperature between 8.2°C and 25.9°C, Wind blows up to 19.4km/h mainly at 150° (SE), 0mm of rain within a span of 0h Tomorrow: Overcast sky, Temperature between 12.2°C and 26.2°C, Wind blows up to 19.1km/h mainly at 166° (S), 0mm of rain within a span of 0h In 2 days: Light drizzle, Temperature between 13.7°C and 23.4°C, Wind blows up to 18.6km/h mainly at 183° (S), 0mm of rain within a span of 5h In 3 days: Moderate rain showers, Temperature between 15.0°C and 24.2°C, Wind blows up to 15.9km/h mainly at 188° (S), 30mm of rain within a span of 13h In 4 days: Dense drizzle, Temperature between 13.5°C and 20.6°C, Wind blows up to 20.7km/h mainly at 200° (S), 1mm of rain within a span of 7h In 5 days: Light drizzle, Temperature between 9.9°C and 13.7°C, Wind blows up to 15.3km/h mainly at 245° (SW), 2mm of rain within a span of 6h In 6 days: Overcast sky, Temperature between 7.8°C and 10.1°C, Wind blows up to 18.4km/h mainly at 351° (N), 0mm of rain within a span of 0h
Then the CLI starts, and the user can use a "weather" command to get weather conditions for the upcoming week of a registered city:
w61/>weather Paris Weather forecast for Paris: Today: Fog, Temperature between 11.5°C and 22.1°C, Wind blows up to 10.4km/h mainly at 31° (NE), 0mm of rain within a span of 0h Tomorrow: Partly cloudy sky, Temperature between 12.3°C and 25.7°C, Wind blows up to 17.4km/h mainly at 16° (N), 0mm of rain within a span of 0h In 2 days: Overcast sky, Temperature between 9.3°C and 19.2°C, Wind blows up to 16.8km/h mainly at 13° (N), 0mm of rain within a span of 0h In 3 days: Partly cloudy sky, Temperature between 9.7°C and 21.2°C, Wind blows up to 15.3km/h mainly at 19° (N), 0mm of rain within a span of 0h In 4 days: Overcast sky, Temperature between 8.7°C and 21.3°C, Wind blows up to 13.8km/h mainly at 22° (N), 0mm of rain within a span of 0h In 5 days: Partly cloudy sky, Temperature between 10.3°C and 21.8°C, Wind blows up to 12.3km/h mainly at 18° (N), 0mm of rain within a span of 0h In 6 days: Partly cloudy sky, Temperature between 9.7°C and 21.5°C, Wind blows up to 12.6km/h mainly at 14° (N), 0mm of rain within a span of 0h
If the given city is not registered, the application prints the supported list.
3.5.2. HTTPS requests
Once the application has started, it connects to the access point.
Then, the application initiates DNS resolution to obtain the IP address of the HTTPS server. This IP address, along with the port (443 for HTTPS) and other HTTPS configuration details, is stored for use by the middleware:
- Certificate: The CA certificate authenticates the server during the connection (refer to “Remote server certificate extraction” for instructions on how to extract it). This parameter can be omitted.
- Server name: The unresolved address needed during the SSL connection.
- URI: The path to the resource to GET, built using the coordinates of the location for which the temperature is requested.
- Method: GET is used to interact with the weather API.
The middleware creates an SSL socket (since the port is set to 443 in the application) and connects to the server.
Next, it sends a simple HTTP GET request to the server using the appropriate URI to obtain the temperature for a specific area.
Following this, it begins receiving data: first the HTTP header, then the actual data, which is given to the application by the middleware in chunks of 4 KB.
Since the expected data is smaller than 4 KB, it can be treated in a single call in the callback the application registered (HTTPS_recv_cb).
These steps are repeated each time the weather command is called, with an additional one: the city's coordinates are determined using a static array in the application.
3.5.3. Certificates update
In case the registered certificate has expired, or a connection to a different HTTPS server is required, follow those steps to extract the necessary certificate and integrate it into the application:
- On Windows®, install OpenSSL for Windows on your computer, and make sure to add it to your system path during the installation. Open a Git bash and run the following OpenSSL command with the options to print the certificate:
openssl.exe s_client -connect api.open-meteo.com:443 -showcerts | openssl x509 -outform PEM
Then copy the command output to weather.crt
- On Linux®, open a terminal and run the following command:
openssl s_client -connect api.open-meteo.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > weather.crt
Note: The certificate is used to authenticate the server, but it can be omitted, in which case the server is not authenticated.
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®, Bluetooth® LE, Network, HTTP and MQTT components Util/Shell: Utility to manage the API through the serial interface Util/Logging: Utility to process shell and trace messages onto the UART interface (can be changed by ITM) Util/Performance: iperf, memory allocation report, task usage utilities |
| [MW] FreeRTOS | FreeRTOS kernel source |
| [MW] LittleFS | LittleFS file system |
| [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 total read-only memory (flash) used by the HTTPS Client application.
The picture below shows the middleware ST67W6X_Network_Driver read-only memory (flash) used by HTTPS Client 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 HTTPS Client application.
