Troubleshoot network problems

  • Article

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

Networking problems can be notoriously difficult to diagnose and resolve. For example, you might find that your Wi-Fi network is working fine locally, but is disconnected from the internet. In such a case, you might find that your Azure Sphere device is not updating correctly. This topic provides some suggestions that may help diagnose networking problems.

Check the network interface status

  1. Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell.

  2. Run azsphere device network list-interfaces to list the details of the network interfaces for the attached device.

    The output displays all the interfaces set up for your device. For each interface on the device, the output shows the following:

    azsphere device network list-interfaces
------------- ----------- ------------------ ---------- ------------- ------------------- ------------ -----------------
InterfaceName InterfaceUp ConnectedToNetwork IpAcquired IpAddresses   ConnectedToInternet IpAssignment HardwareAddress
========================================================================================================================
azspheresvc   True        False              False      <value>       False               None         None
------------- ----------- ------------------ ---------- ------------- ------------------- ------------ -----------------
eth0         True        True               True       <value>        True                dynamic      <value>
------------- ----------- ------------------ ---------- ------------- ------------------- ------------ -----------------
lo            True        False              False      <value>       False               None         None
------------- ----------- ------------------ ---------- ------------- ------------------- ------------ -----------------
wlan0         True        True               True       <value>       True                dynamic      <value>
------------- ----------- ------------------ ---------- ------------- ------------------- ------------ -----------------

  3. Verify that the following settings for the interface are True.

  • Network interface up. If this setting is False:

  • Connected to network. If this setting is False:

    • Run azsphere device wifi show-status to check that the Wi-Fi SSID value matches the device Wi-Fi settings.
    • Scan for networks to verify that the SSID in the device settings match the SSID on your network. For more information, see wifi scan command.
    • If the SSID for your Wi-Fi network is hidden and your application relies on a targeted scan, check that targeted scan is enabled.

  • Acquired IP address. If this setting is False:

    • Wait for a connection to be made
    • Check your network to see if the access point and other devices on the network are fully connected. For more information, see Networking_IsNetworkingReady Function.
    • Check the range of allowed IP addresses or limit of allowed connections on your access point and network.

  • Connected to internet. If this setting is False:

    • Check that your network is connected to the internet.

Verify Wi-Fi status

  1. Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell.
  2. Run azsphere device wifi show-status to view information about the current Wi-Fi connection on the device.

You should see output similar to the following:

 azsphere device wifi show-status
 ----- ------------------ --------------- ------------- --------- ------- ------------- --------- ------------- -----------------
 SSID  ConfigurationState ConnectionState SecurityState Frequency Mode    KeyManagement WpaState  IpAddress     MacAddress
 ================================================================================================================================
 <value> enabled            connected       psk           2412      station WPA2-PSK      COMPLETED <value>      <value>
 ----- ------------------ --------------- ------------- --------- ------- ------------- --------- ------------- -----------------

If the Connection state is set to disconnected, enable Wi-Fi on your device.

Verify network status

Run azsphere device network show-status to view the network status for the attached device.

You should see output similar to the following:

azsphere device network show-status
 --------------------------- --------------- --------
 DeviceAuthenticationIsReady NetworkTimeSync Proxy
 ====================================================
 True                        complete        disabled
 --------------------------- --------------- --------
  • If Is device authentication ready returns False,
  • If the Network time sync status returns Incomplete,
    • Wait for a connection to be made
    • Ensure that your network is configured to allow inbound and outbound traffic. For more information, see Ports and Protocols.

Verify the firewall settings

If your application fails to connect to a remote host:

  • Check the application's firewall settings. The application manifest must specify the host names or IP addresses to which the application is allowed to connect, by setting the AllowedConnections capability.
  • If the application has been configured to perform service discovery, in addition to the entries in the application manifest, the discovered endpoints should also be listed in the firewall configuration.

If remote hosts are unable to connect to your server application:

  • Check the application's firewall settings. The application manifest must specify the UDP and TCP ports to which the application is open for inbound connections, by setting the AllowedTcpServerPorts, and AllowedUdpServerPorts capabilities.

If you are still having difficulties:

Get network diagnostics

When a network failure occurs, you can get diagnostic information about the failure in two ways: through a call to the WifiConfig API and from the command line.

A high-level application can call WifiConfig_GetNetworkDiagnostics to gather information about the problem. This function returns a WifiConfig_NetworkDiagnostics structure that contains details about the most recent failure on the specified network. Combine the information from the diagnostics structure with the tips that follow to diagnose and recover from common network failures.

The WiFi_HighLevelApp sample shows how to use the diagnostics.

You can also use the azsphere device network show-diagnostics command to display diagnostic information about the last error.

Incorrect network connection

If your device is connected to the incorrect network or is connected but with the wrong attributes, make sure that the network configuration is correct. If you changed the configuration, you must reload it. In an application, call WifiConfig_ReloadConfig or on the command line, use the azsphere device wifi reload-config command to reload the current configuration. To ensure that the network configuration persists across reboots, an app can call WifiConfig_PersistConfig.

Problems updating a Root CA certificate

If your device can't connect to an EAP-TLS network after updating the Root CA certificate, start with the status returned by the WifiConfig_SetNetworkEnabled function.

If the status indicates a Root CA certificate error, one of the following may be the cause:

  • Did the old Root CA1 expire or change on the RADIUS server during the update process? If so, the new Root CA2 may be incorrect.
  • Did some other failure occur on the server side? Check with your network administrator. The administrator might have used a different or incorrect certificate authority, and might need to fix this centrally.

If the status indicates a client certificate error:

  • Was the configuration of the new Network2 out of sync with Network1 properties? If the properties changed on Network 1 but you tried to connect using outdated properties on Network2, Network2 may fail to connect. Ensure that key properties are identical for the two networks.
  • Did the client certificate change during the network update process? Check the certificates that are associated with Network1 and Network2 and ensure that they're the same. An app can use functions in the CertStore API to inspect certificate details.

If both the Root CA and the client certificate are correct, the failure could be related to your Wi-Fi access point or some other problem.

Continue to check the data returned by WifiConfig_GetNetworkDiagnostics after each failed attempt to learn more about the problem.

Problems updating a client certificate

If your device can't connect to an EAP-TLS network after updating the client certificate, start with the status returned by the WifiConfig_SetNetworkEnabled function.

If the status indicates a client certificate error:

  • Revert to the previous certificate and try to reconnect. Success indicates a problem with the new client certificate; failure indicates that either the new certificate is invalid or that the old certificate expired in the interim.

If the status indicates some other type of error:

  • Is the network experiencing other problems? Continue trying to connect with either client certificate.

Continue to check the data returned by WifiConfig_GetNetworkDiagnostics after each failed attempt to learn more about the problem.

Problems connecting to a 5GHz network that does not broadcast an SSID

There is a known issue on the MT3620 where devices may be unable to connect to 5GHz networks that do not broadcast an SSID, despite using Targeted Scan. We recommend either not disabling SSID broadcast or doing so on a 2.4GHz-only network.