Azure Sphere Wi-Fi configuration

Azure Sphere devices rely on network connectivity to receive over-the-air OS and application updates and to connect to application-specific services. Wi-Fi connections may need to be configured during app development, in the manufacturing stage, or after a device has been deployed. Options for configuring Wi-Fi differ depending on whether you have physical access to the Azure Sphere device, or are updating the Wi-Fi configuration remotely.

This Application Note is written around WPA2-PSK authentication (such as a shared key). In addition, Azure Sphere supports EAP-TLS for secure enterprise networks. Every mechanism described here that could be used to send a PSK could also be used to send a cert for EAP-TLS.

Configure Wi-Fi with service port access to a device

If you have a device that includes the USB/FTDI programming and debug interface, or can add an external board that includes the USB/FTDI programming and debug interface, the Azure Sphere Command-Line Interface (CLI) and development tools are available to you. The service port option only make sense for manufacturing. After manufacturing, during normal use, we recommend using one of the other options described below instead of using service port, because service port requires access to the Azure Sphere catalog to obtain a field servicing capability.

• Azure CLI

  If you are connecting an Azure Sphere device that includes the USB/FTDI programming and debug interface to your development PC and have the Azure Sphere SDK installed, you can use the Azure CLI, which includes commands for configuring Wi-Fi. You can also get [network diagnostics](../reference/az sphere-device.md), and [manage certificates for EAP-TLS networks](../reference/az sphere-device.md).

• External programming board

  If you have a device that does not include an on-board Azure Sphere programming and debug interface, but have the ability to temporarily connect a stand-alone FTDI interface board, you can use the Azure CLI commands mentioned above. This approach enables you to ship your production devices without an FTDI interface (which saves cost), and only requires a programming/debug board per engineer.

Configure Wi-Fi with local access to a device (without service port)

For devices that do not include (or have the ability to add) a USB/FTDI programming and debug interface, you have several options for configuring Wi-Fi if you have local access to the device. The best local option depends on the type of user using it and the resources you expect them to have. For example, for consumer products where end users configure Wi-Fi, NFC or Bluetooth may result in more user-friendly experiences, while for products that are installed by professional installers or sysadmins who can use a hardware dongle to interface with the product, the UART option has lowest cost overhead.

• Bluetooth

  If your Azure Sphere device exposes a Bluetooth connection, you can provision Wi-Fi using Bluetooth. The WifiSetupAndDeviceControlViaBle reference solution uses an nRF52 Bluetooth controller (which is included in the USI Global Azure Sphere module). The sample includes an Azure Sphere high-level application and a Windows desktop application (written in C#).

• UART

  In a production environment you may need to update the Wi-Fi configuration for a device that does not include or have support for temporarily adding a USB/FTDI programming and debug board. You may decide to expose a UART/Serial interface from your device to enable an engineer to update Wi-Fi settings for a device. The Azure Sphere Gallery WifiConfigurationViaUart project shows how to develop a UART-based menu interface that enables: device reboot, listing the current Wi-Fi configuration, and the ability to add a new network configuration. The sample can be extended to add additional functionality.

• Bootstrap network configuration

  It may be possible to use a network connection to bootstrap Wi-Fi configuration. There are two steps:

1. Get the Azure Sphere device connected to the bootstrap network.

2. Obtain the new Wi-Fi provisioning information and configure the device.

   Get a device connected to a bootstrap network

   • The Wi-Fi network that a device connects to may not be known at the point of manufacture and may be configured by a device installer or engineer during on-site setup. You might consider provisioning a Wi-Fi connection to your device as part of the manufacturing process. Engineers can configure a mobile device as a Wi-Fi Access Point that matches the manufacturing provisioned SSID and passkey which then enables the Azure Sphere device to be connected.

   • The device may initially connect using a cellular or Ethernet connection.

   Provision the Wi-Fi connection from the bootstrap network

   Once a device is connected to the bootstrap network there are several options for obtaining the new Wi-Fi configuration:

   • The Azure Sphere device could host a simple TCP or HTTP server that enabled a client on the bootstrap network to configure the network.
   • The Azure Sphere device could use a pre-determined TCP/IP port or hostname to connect to a server/service that provides the Wi-Fi credentials.
   • The service used to provide Wi-Fi credentials may need to be determined at runtime, in which case technologies such as DNS-SD might be used.
   • One of the remote configuration options listed below might also be used.

• NFC

  NFC-based Wi-Fi configuration has the advantage of requiring few steps and being fast. Unlike the command-line method, which requires connecting a cable and possibly typing a command, the only action is for the operator to hold up a mobile phone against the device that needs to be configured. NFC is faster compared to most other configuration techniques since it relies solely on proximity and does not need to be paired and unpaired. Both Android and Apple stores have applications that can be used during development and testing to provision Wi-Fi credentials to a device.

  The Azure Sphere Gallery WifiConfigurationViaNfc project shows how to add a new network configuration based on NFC tap event.

Remotely configuring Wi-Fi

Once a device is in production, or is at a remote location you may still need to provision or update the Wi-Fi credentials, options include:

• Azure Device Twin properties (Recommended option)

  Azure IoT Hub and Azure IoT Central support Device Twins, device twins are a JSON document that is mirrored between the Azure IoT Hub/Central service and a device, on the Azure side a device operator can set a desired state that a device should then attempt to achieve (a temperature setpoint for a thermostat for example), the device then sends its reported state back to Azure IoT Hub/Central. The ability to set a new desired property for one or many devices within Azure IoT Hub/Central (this can be achieved programmatically) would allow a device operator to set a new Wi-Fi configuration as a desired property for one or many devices, pairing knowledge of devices within a specific Azure Sphere device group with devices within an Azure IoT Hub/Central application gives fine control over which devices are updated.

• Updates to your application software

  Azure Sphere device applications can be updated by the device maker. The IoT Show video Developing for Azure Sphere OTA updates demonstrates over-the-air application deployment and application update deferral.

  There are a several options for updating Wi-Fi configuration from an updated application:

  • You might consider having strings in your application code that are updated for each change in Wi-Fi configuration. This is relatively simple to implement and doesn't require loading/parsing of an embedded resource file. It does mean that code files are touched as part of updating the Wi-Fi configuration, which might have an impact on code history.
  • You might use an embedded resource file in the application, changing the resource doesn't touch code, and if you choose a data format like JSON, the content of the file can be easily parsed and validated during automated build and test. The WifiConfigurationViaAppResource Gallery project demonstrates how to use the contents of a JSON resource file to configure Wi-Fi.
  • You might use a well-known web endpoint (Azure App service, for example) for your devices to obtain their Wi-Fi configuration.

  Be aware that embedding Wi-Fi configuration directly into the application (in source, or resource file) means that updated devices will receive the same Wi-Fi configuration information. If you want to set Wi-Fi configurations on individual devices, the Azure IoT Hub/Central Device Twin method or well-known web endpoint options should be used.

Wi-Fi configuration considerations

When modifying the Wi-Fi configuration of a device, you may want to add the new Wi-Fi configuration, disable the existing connection, enable the new connection, and confirm that the new connection is working before deleting the previous connection information.