Connect Azure Sphere to Ethernet

An Azure Sphere device can communicate on a 10-Mbps Ethernet network through standard TCP or UDP networking. This topic describes how to configure an Azure Sphere device to use an external Ethernet controller by deploying a board configuration image to your device and then enabling the Ethernet interface. You can connect an Ethernet-enabled device to a public (internet-connected) network and communicate with Azure IoT or your own cloud services, or you can connect it to a private network and use network services. In addition to communicating through Ethernet, you can connect Azure Sphere to Wi-Fi.

Caution

Azure Sphere doesn't have a low-level filter for broadcast messages, so a quiet network is required if your device is connected through Ethernet. If the device is connected to a noisy network through Ethernet, it can lead to poor performance on the device.

Hardware instructions

Connecting Ethernet adapters to the MT3620 development board describes how to connect an Ethernet adapter to the MT3620. The adapter referenced in those instructions uses the board configuration described here.

Board configuration

Use of Ethernet requires a board configuration image in addition to the application image. The board configuration image contains information that the Azure Sphere Security Service requires to add support for Ethernet to the Azure Sphere OS. Microsoft supplies a board configuration for the Microchip ENC286J60 Ethernet chip, which must be attached via SPI to ISU0 with interrupts on GPIO5. For development, we recommend the Olimex ENC28J60-H module.

To use Ethernet on Azure Sphere, you package a board configuration image for the ENC28J60 and deploy this image package in addition to your application image package.

Create a board configuration image package

Use azsphere image-package pack-board-config to create a board configuration image package for the ENC28J60:

azsphere image-package pack-board-config --preset lan-enc28j60-isu0-int5 --output enc28j60-isu0-int5.imagepackage

The --preset flag identifies the Microsoft-supplied board configuration to package, and the --output flag specifies a name for the package.

Sideload a board configuration image package

You can sideload a board configuration image package for development and debugging, or you can deploy such a package from the cloud along with your Azure Sphere application for field use.

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

  1. Prepare the device for development and debugging:

    azsphere device enable-development

  2. Delete any existing applications from the device, using the azsphere 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. For example, the following command sideloads the ENC286J60 Ethernet board configuration image package:

    azsphere device sideload deploy --imagepackage enc28j60-isu0-int5.imagepackage

  4. Sideload the application, either by using Visual Studio or by using the azsphere 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. Use the azsphere device-group deployment create command to deploy both images. For example, the following deploys the enc28j60-isu0-int5 board configuration image package and the EthernetSample application image package to devices in the Production device group for the DW100 product:

azsphere device-group deployment create --devicegroupname Production --productname DW100 --filepath=enc28j60-isu0-int5.imagepackage,EthernetSample.imagepackage

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. For example, the lan-enc28j60-isu0-int5 board configuration reserves ISU0 and GPIO 5. 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:

    azsphere device image list-installed

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

     --> lan-enc28j60-is
       --> Image type:   Board configuration
       --> Component ID: 75a3dbfe-3fd2-4776-b7fe-c4c91de902c6
       --> Image ID:     a726b919-bdbe-4cf4-8360-2e37af9407e1
    
  3. Delete the board configuration image package by specifying its component ID:

    azsphere device sideload delete --componentid 75a3dbfe-3fd2-4776-b7fe-c4c91de902c6

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

Remove a board configuration from cloud deployment

To remove a board configuration from the cloud deployment, create a new deployment that only delivers the application image package and doesn't include the board config image package. For example, the following deployment removes the board configuration from the cloud deployment created in the earlier section and uploads a different image package that does not rely on Ethernet:

azsphere device-group deployment create --devicegroupname Production --productname DW100 --filepath WiFiSample.imagepackage

Caution

Don't remove a cloud-deployed board configuration if your device relies on Ethernet for internet connectivity. This will take the device offline and prevent internet connectivity from being restored through the cloud. To restore connectivity you'll need physical access to the device to sideload the board config or to set up alternative internet access, such as Wi-Fi.

Enable the Ethernet interface

To use Ethernet, your high-level application must enable the interface by calling the Networking_SetInterfaceState function, which is part of the network configuration API. Use of network configuration functions requires the NetworkConfig capability in the application manifest.

For example, the following enables the "eth0" interface:

    err = Networking_SetInterfaceState("eth0", true);

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.

Samples

  • The Private Network Services sample demonstrates how to connect Azure Sphere to a private network and use several network services.
  • The AzureIoT sample demonstrates how to use the Azure IoT SDK C APIs in an Azure Sphere application to communicate with Azure IoT Central or Azure IoT Hub.
  • The HTTPS samples demonstrate how to use the cURL APIs with Azure Sphere over a secure HTTPS connection.