Prepare Azure Sphere for Ethernet

  • Article

To communicate over Ethernet, an Azure Sphere device requires an external Ethernet adapter and a board configuration image. The following steps are required to prepare your device for networking over Ethernet:

  1. Connect the adapter to your device.

  2. Create and deploy the board configuration image.

  3. Enable the Ethernet interface.

Caution

If your device is connected through Ethernet, a low-traffic network is required to prevent either data loss or poor performance. The device will lose data from incoming non-TCP packets when there is significant incoming traffic on the network. Data is typically not lost from incoming TCP packets, regardless of traffic volume, because TCP will retransmit dropped packets. However, the re-transmit is at the cost of performance.

Connect the adapter to your device

See Supported Ethernet adapters boards and modules for a list of supported Ethernet adapters and instructions for how to connect them to an Azure Sphere development board.

Create and deploy the board configuration image

A board configuration image is required for each Ethernet adapter used with Azure Sphere. The board configuration image contains information that the Azure Sphere Security Service requires to add support for Ethernet to the Azure Sphere OS. You must create a board configuration image package for your Ethernet adapter and deploy it along with your application image package. You can sideload the board configuration image package for development and debugging. You can also deploy the board configuration image package from the cloud, along with your Azure Sphere application, for field use. The board configuration does not count against the Flash memory or RAM reserved for high-level apps.

Create a board configuration image package

To create a board configuration image package, use the azsphere image-package pack-board-config CLI command.

Note

pack-board-config isn't currently supported in the Azure CLI extension.

Sideload a board configuration image package

To use a board configuration image package during development and debugging:

  1. Prepare the device for development and debugging:

    az sphere device enable-development --resource-group MyResourceGroup --catalog MyCatalog --device <DeviceIdValue>

  2. Delete any existing applications from the device using the az sphere device sideload delete command. It's important to delete existing applications before you load the board configuration image package to avoid resource conflicts between existing applications and the board configuration.

  3. Sideload the board configuration image package. If you created a custom board configuration file in the previous section, that can be sideloaded now. Preset options include the following:

    Seeed MT3620 Ethernet Shield for Microchip ENC28J60 NIC:

    az sphere device sideload deploy --image-package lan-enc28j60-isu0-int5.imagepackage

    Avnet Rev1 Devkit Click Module for Wiznet W5500 NIC:

    az sphere device sideload deploy --image-package lan-w5500-isu1-int2.imagepackage

    Avnet Rev2 Devkit Click Module for Wiznet W5500 NIC:

    az sphere device sideload deploy --image-package lan-w5500-isu0-int5.imagepackage

  4. Sideload the application, either by using Visual Studio or by using the az sphere device sideload deploy command.

Cloud deploy a board configuration image package

To deploy a board configuration image package through the cloud, your device must have a product, belong to a device group, and must not have the AppDevelopment capability installed. See Create a deployment to find out how to set these up.

After your device is ready, you can deploy the board configuration image along with the application image in a single deployment.

To create a deployment:

  1. Upload the image package to your Azure Sphere catalog using az sphere image add.
  2. Create a new deployment for a device group for the uploaded images using az sphere deployment create.
az sphere deployment create --resource-group <resource-group-name> --catalog <catalog-name> --product <product-name> --device-group <device-group-name> --images <image-ID>

Replace <image-ID> with the image ID of the image package.

Remove a sideloaded board configuration

If you sideload a board configuration during development, you might later need to remove that configuration so that other applications can use the resources that the board reserves. If you try to run an application that uses these resources while the board configuration is loaded on the Azure Sphere device, pin conflict errors will occur.

To remove a board configuration, follow these steps:

  1. List the images installed on the device:

    az sphere device image list-installed

  2. Find the component ID for the board configuration in the list:

     {
 "does_image_type_require_restart": true,
 "image_type": "Board configuration",
 "images": [
   {
     "length_in_bytes": 428,
     "replica_type": 0,
     "uid": "839e699a-1b23-44de-bc56-f2b19e472098",
     "uncompressed_length_in_bytes": 428
   }
 ],
 "is_update_staged": false,
 "name": "lan-enc28j60-isu0-int5_29f10d",
 "uid": "29f10d1e-29aa-4ae0-a48c-cc24305b288a"
 }

    The component ID is the uid associated with the board configuration, so for example in the above output it starts "29f10...".

  3. Delete the board configuration image package by specifying its component ID:

    az sphere device sideload delete --component-id 29f10d1e-29aa-4ae0-a48c-cc24305b288a

  4. Restart the device by either pressing the Reset button or issuing the az sphere device restart command.

Enable the Ethernet interface

Once the board configuration is loaded and the device is rebooted, the interface will be enabled automatically. If you would like to disable the interface, use the az sphere device network disable command or call the Networking_SetInterfaceState function, which is part of the network configuration API.

All interfaces use dynamic IP addresses by default. See Use network services for details about the types of services an Azure Sphere application can use.

Configure Azure Sphere for Ethernet

After connecting your Azure Sphere device to a supported Ethernet adapter and deploying the board configuration image, you can configure your Azure Sphere device to connect to a network from the command line (CLI) or from your application using the Azure Sphere SDK Application Libraries (Applibs).

Ethernet configuration using the CLI

To manage Ethernet configuration from the command line, use the az sphere device network CLI commands. For example, the device network enable command enables an ethernet interface on the attached device.

az sphere device network enable --interface "eth0"

To use the configured Ethernet network, the network interface (eth0) must be active. Use the device network list-interfaces command to determine if the interface is active.


az sphere device network list-interfaces

Use the device network enable command to activate it if necessary.


az sphere device network enable --interface eth0

Ethernet configuration using Applibs

To configure Ethernet, your application must use the applibs networking API.

Include this header file in your application:

#include <applibs/networking.h>

The application manifest must include the NetworkConfig capability.

 "Capabilities": {
  "NetworkConfig" : true
}

Use the Networking_GetInterfaceConnectionStatus function to determine if the network interface is active.

Networking_GetInterfaceConnectionStatus("eth0", &currentInterfaceStatus);

To activate the network interface, use the Networking_SetInterfaceState function.

Networking_SetInterfaceState("eth0", true);

Note

If both network interfaces (wlan0 and eth0) are active and connected, the specific interface the device will use for communication is non-deterministic. If you want to control which network interface is used at any given time your application must use the Networking_SetInterfaceState() function to explicitly turn the desired interface on and the other interface off. The DHCP client high-level app sample demonstrates among other things, how to switch between interfaces by assigning a value representing one of the two interfaces to a global variable.

Samples

Azure IoT demonstrates how to use the Azure IoT SDK C APIs in an Azure Sphere application to communicate with Azure IoT Hub or Azure IoT Central.

DHCP client high-level app demonstrates how to renew or release the current IP address that the network's DHCP server has assigned to the MT3620 device.

HTTPS cURL Easy demonstrates fetching content over HTTPS using cURL's 'easy' API

HTTPS cURL Multi demonstrates fetching content over HTTPS using cURL's 'multi' API.

Power Down high-level app demonstrates Power Down functionality for the Azure Sphere platform.

Private network services demonstrates how to connect an Azure Sphere device to a private network and use network services.

WolfSSL high-level app demonstrates using WolfSSL for SSL handshake in a high-level application.

Note

The following samples are from the Azure Sphere Gallery, which is a collection of unmaintained software and hardware samples from Microsoft. For more information, see Azure Sphere Gallery.

Print MAC and IP address of network interface prints the MAC and IP addresses of a specified network interface.

OSNetworkRequirementChecker-HLApp performs two device (MT3620) networking diagnostic tests.