Azure Sphere – Wi-Fi

This sample application demonstrates how to connect to a Wi-Fi network and check the network status on an MT3620 device.

Button A (BUTTON_1) is used by the sample to perform Wi-Fi network-management operations, such as adding and enabling a Wi-Fi network. Button B (BUTTON_2) displays network-related information such as the device's network status. Each button press executes a particular operation on the device.

The sample displays the stored and scanned networks based on their SSID, security type, and RSSID, and removes duplicates. Therefore, the output of the equivalent CLI commands azsphere device wifi list and azsphere device wifi scan might be different from the sample's output.

The sample uses the following Azure Sphere libraries.

Library Purpose
eventloop Invokes handlers for timer events.
gpio Manages button A and LED 1 on the device.
log Displays messages in the IDE device output window during debugging.
networking Manages the network configuration of the device.
wificonfig Manages Wi-Fi configuration on the device.

Contents

File/folder Description
app_manifest.json Application manifest file, which describes the resources.
CMakeLists.txt CMake configuration file, which Contains the project information and is required for all builds.
CMakeSettings.json JSON file for configuring Visual Studio to use CMake with the correct command-line options.
launch.vs.json JSON file that tells Visual Studio how to deploy and debug the application.
LICENSE.txt The license for this sample application.
main.c Main C source code file.
README.md This README file.
.vscode Folder containing the JSON files that configure Visual Studio Code for building, debugging, and deploying the application.
HardwareDefinitions Folder containing the hardware definition files for various Azure Sphere boards.

Prerequisites

The sample requires the following:

  • An Azure Sphere device

    Note: By default, this sample targets MT3620 reference development board (RDB) hardware, such as the MT3620 development kit from Seeed Studios. To build the sample for different Azure Sphere hardware, change the Target Hardware Definition Directory in the CMakeLists.txt file. For detailed instructions, see the README file in the HardwareDefinitions folder.

  • Access to a WPA2 (Wi-Fi Protected Access II), an open Wi-Fi, or an EAP-TLS network.

  • If the network is an EAP-TLS network, make sure that the Root CA certificate, the client certificate, and the private key are already installed on the device before you set up the sample for EAP-TLS.

    If you don't have certificates, follow the steps in How to generate certificates for testing to create the certificates. You can install them in either of the following ways:

Setup

  1. Even if you've performed this set up previously, ensure that you have Azure Sphere SDK version 21.04 or above. At the command prompt, run azsphere show-version to check. Install the Azure Sphere SDK if needed.

  2. Connect your Azure Sphere device to your computer by USB.

  3. Enable application development, if you have not already done so, by entering the following line at the command prompt:

    azsphere device enable-development

  4. Clone the Azure Sphere samples repository and find the WiFi_HighLevelApp sample in the WiFi folder or download the zip file from the Microsoft samples browser.

Add your network settings to the sample

The sample must be configured to use the settings for your network. To add your network settings, complete the following steps:

  1. In main.c, search for the line static const uint8_t sampleNetworkSsid[] = "WIFI_NETWORK_SSID"; and change WIFI_NETWORK_SSID to SSID of the Wi-Fi network.

  2. In main.c, search for the line static const WifiConfig_Security_Type sampleNetworkSecurityType = WifiConfig_Security_Unknown; and change WifiConfig_Security_Unknown to the security type of the Wi-Fi network, as specified in the following steps. For a WPA2-PSK network or an EAP-TLS network, complete additional steps.

    • If the network is an open Wi-Fi network, set the security type to WifiConfig_Security_Open.

    • If the network is a WPA2-PSK network:

      1. Set the security type to WifiConfig_Security_Wpa2_Psk.
      2. Search for the line static const char *sampleNetworkPsk = "WIFI_NETWORK_PASSWORD"; and change WIFI_NETWORK_PASSWORD to the password of your Wi-Fi network.
    • If the network is an EAP-TLS network:

      Note: A root CA certificate and a client certificate must be installed, as described in Prerequisites.

      1. Set the security type to WifiConfig_Security_Wpa2_EAP_TLS
      2. Search for the line const char *rootCACertStoreIdentifier = "SmplRootCACertId"; and change SmplRootCACertId to the identifier of your root CA certificate. You can use the azsphere device certificate list command to see the certificate IDs for all installed certificates.
      3. Search for the line const char *clientCertStoreIdentifier = "SmplClientCertId"; and change SmplClientCertId to the identifier of your client certificate.
      4. Search for the line const char *clientIdentity = "SmplClientId"; and change SmplClientId to your client identity.

      Caution: Because certificate IDs are system-wide, an azsphere command or a function call that adds a new certificate can overwrite a certificate that was added by an earlier command or function call, potentially causing network connection failures. We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully. See Certificate IDs for more information about how Azure Sphere uses certificate IDs.

  3. If you set the security type of the network to WifiConfig_Security_Wpa2_EAP_TLS, you must add the EnterpriseWifiConfig capability in the app_manifest.json file:

    "EnterpriseWifiConfig": true

Build and run the sample

To build and run this sample, follow the instructions in Build a sample application.

Test the sample

The output will be displayed in the terminal window. Use the buttons on the device to cycle through several operations related to Wi-Fi networks. Each button press executes a particular operation on the device.

Button A (BUTTON_1) performs the following management operations in the order specified:

  1. Adds the network.
  2. Enables the network.
  3. Disables the network.
  4. Duplicates the network.
  5. Deletes the network.

Button B (BUTTON_2) performs the following display and scan operations in the order specified:

  1. Displays the network status of the device.
  2. Displays the network diagnostic information.
  3. Lists the stored Wi-Fi networks on the device.
  4. Starts a network scan.
  5. Lists the available Wi-Fi networks.

Next steps