Troubleshoot network problems

Article
08/08/2023

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

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

Run az sphere 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:

[
  {
    "connectedToInternet": false,
    "connectedToNetwork": false,
    "hardwareAddress": null,
    "interfaceName": "azspheresvc",
    "interfaceUp": true,
    "ipAcquired": false,
    "ipAddresses": [
      "192.168.35.2"
    ],
    "ipAssignment": null
  },
  {
    "connectedToInternet": false,
    "connectedToNetwork": false,
    "hardwareAddress": "b2:30:bb:f0:d1:44",
    "interfaceName": "eth0",
    "interfaceUp": true,
    "ipAcquired": false,
    "ipAddresses": null,
    "ipAssignment": "dynamic"
  },
  {
    "connectedToInternet": false,
    "connectedToNetwork": false,
    "hardwareAddress": null,
    "interfaceName": "lo",
    "interfaceUp": true,
    "ipAcquired": false,
    "ipAddresses": [
      "127.0.0.1"
    ],
    "ipAssignment": null
  },
  {
    "connectedToInternet": false,
    "connectedToNetwork": false,
    "hardwareAddress": "00:02:b5:03:69:ea",
    "interfaceName": "wlan0",
    "interfaceUp": true,
    "ipAcquired": false,
    "ipAddresses": null,
    "ipAssignment": "dynamic"
  }
]

Verify that the following settings for the interface are True.

Network interface up. If this setting is False:
- Check that the local devices using the access point are connected. For more information, see Networking_IsNetworkingReady Function.
- Check that the network interface is enabled. You can enable the required interface by using the az sphere device network enable command or by using the Networking_SetInterfaceState Function API.
Connected to network. If this setting is False:
- Run az sphere 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

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

You should see output similar to the following:

 az sphere device wifi show-status
{
  "SSID": "MSFTGUEST",
  "configurationState": "enabled",
  "connectionState": "connected",
  "frequency": 5660,
  "ipAddress": "10.106.106.40",
  "keyManagement": "NONE",
  "macAddress": "00:02:b5:03:69:ea",
  "mode": "station",
  "securityState": "open",
  "wpaState": "COMPLETED"
}

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

Verify network status

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

You should see output similar to the following:

az sphere device network show-status
{
  "deviceAuthenticationIsReady": false,
  "networkTimeSync": "incomplete",
  "proxy": "disabled"
}

If Is device authentication ready returns False,
- Restart your device and try the command again.
- Ensure that your network is configured to allow inbound and outbound traffic. For more information, see Ports and Protocols.
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:

Run az sphere device network list-firewall-rules and verify that the IP address in the firewall rules and the application manifest file match.
Check that the system default connections are present by default.

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 az sphere 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 az sphere 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.