|
Back to main page |
|---|
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.19.0 [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. Topology structure
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 1 /** 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 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
The default Net 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_NET_DHCP 1 /** String defining Wi-Fi hostname */ #define W6X_NET_HOSTNAME "ST67W61_WiFi" /** 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:
/** HTTP Client thread stack size */ #define W6X_HTTP_CLIENT_THREAD_STACK_SIZE 1536 /** HTTP Client thread priority */ #define W6X_HTTP_CLIENT_THREAD_PRIO 30 /** 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 9216
The default utilities configuration can be modified in the "ST67W6X/Target/w6x_config.h" file:
/** Enable LittleFS */ #define LFS_ENABLE 0
The Shell can be configured in the "ST67W6X/Target/shell_config.h" file:
/** Enable the shell component */ #define SHELL_ENABLE 1 /** Default shell commands list level (0: Minimal, 1: Full) */ #define SHELL_CMD_LEVEL 0 /** Shell command maximum size */ #define SHELL_CMD_SIZE 256 /** 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
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 20 /** Enable/Disable Wi-Fi module logging */ #define WIFI_LOG_ENABLE 1 /** Enable/Disable Network module logging */ #define NET_LOG_ENABLE 1 /** Maximum SPI buffer size */ #define W61_MAX_SPI_XFER 1520 /** Debugging only: Enable AT log, i.e. logs the AT commands incoming/outcoming from/to the NCP */ #define W61_AT_LOG_ENABLE 0 /** Enable/Disable System module logging */ #define SYS_LOG_ENABLE 1
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 "Appli/App/app_config.h":
/** SSID of the local Access Point */ #define WIFI_SSID "MY_SSID" /** Password of the local Access Point */ #define WIFI_PASSWORD "MY_PASSWORD" /** Define the default factor to apply to AP DTIM interval when connected and power save mode is enabled */ #define WIFI_DTIM 1
The logging output mode can be modified in "Appli/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 "Appli/App/app_config.h":
/** Low power configuration [0: disable / 1: sleep / 2: stop / 3: standby] */ #define LOW_POWER_MODE 0
The host debugger pins can be modified in "Appli/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 Security and certificates).
- 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. Security and certificates
The NCP utilizes littlefs to read certificates and keys from the host processor that are then store internally.
This guide outlines the process for loading certificates and keys onto the NCP using the HTTPS client demonstration.
The guide will also show the process for configuring the host processor and NCP for using the different security schemes for HTTP over TLS.
This guide is similar to both MQTT Security and certificates chapter and HTTPS Client Application Security and certificates chapter.
The X-Cube-ST67W61 expansion package provides multiple certificates and keys to test with.
These can be found in the directory:
Projects\ST67W6X_Utilities\LittleFS\Certificates\lfs
The client-server certificate and key pairs are shown are named with a numerical identifier to signify their relationship. (i.e. ca_1.crt, client_1.crt, client_1.key, server_1.crt, server_1.key).
3.5.3.1. If the define LFS_ENABLE equals 0
To load the weather certificate onto the NCP the content file must be copied as weather_cert[] buffer content in the Appli\App\https_client.c
3.5.3.2. If the define LFS_ENABLE equals 1
To load the weather certificate onto the NCP the file must be placed within the lfs folder in the HTTPS client demonstration folder located here: Projects\NUCLEO-U575ZI-Q\Applications\ST67W6X\ST67W6X_HTTPS_Client\littlefs\lfs
The certificate is loaded onto the device as a littlefs.bin binary using linker input specified in the project settings.
To build this binary from the desired certificate once it is placed in the lfs folder specified above the build.bat (Windows) or build.sh (Linux) must be run to update the binary. This batch script is located in the directory above lfs:
Projects\NUCLEO-U575ZI-Q\Applications\ST67W6X\ST67W6X_HTTPS_Client\littlefs
it may be necessary to modify the script if you wish to add more files than those already present:
mklfs.exe -c lfs -b 2048 -p 256 -r 256 -s 0x4000 -i littlefs.bin
- The -b 2048 parameter is used to define the size of a block in the binary. This size must be equal to or greater than the size of each certificate.
- The -s 0x4000 parameter is used to define the binary file size (16kb). It is suitable for storing 6 certificates. If you wish to add more, you need to increase the size in block steps (0x500 by default).
The size parameter must be aligned to the define in Projects\NUCLEO-U575ZI-Q\Applications\ST67W6X\ST67W6X_HTTPS_Client\littlefs\Target\lfs_flash.c:
/** This value must be aligned with prebuild script argument */ #define LITTLEFS_SECTION_SIZE 0x4000
Once run, the binary will be updated.
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.
