Connect Azure Sphere to private Ethernet

An Azure Sphere device can communicate with devices on a private, 10-Mbps Ethernet network via standard TCP or UDP networking in addition to communicating over the internet via Wi-Fi. Your Azure Sphere application will need to use the Azure Sphere networking API to configure the network. The Azure Sphere device does not act as a router in this scenario. It will never automatically pass packets received on the private Ethernet network to the public Wi-Fi network, or vice versa. Your application must implement all logic that sends and receives information on both networks.

Azure Sphere can act as a dynamic host configuration protocol (DHCP) server and a simple network time protocol (SNTP) server for use with private Ethernet. The DHCP server enables Azure Sphere applications to configure network parameters for an external device on the private Ethernet network. Using the SNTP server, the external device can synchronize its time with Azure Sphere.

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 Monitor requires to add support for Ethernet to the Azure Sphere OS. Microsoft supplies a board configuration for the Microchip ENC286J60 Ethernet chip, which is 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

In an Azure Sphere Developer Command Prompt, use azsphere image package-board-config to create a board configuration image package for the ENC28J60:

azsphere image package-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 or deploy a board configuration image package

You can sideload a board configuration image package for development and debugging, or you can deploy such a package over the air (OTA) 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 prep-debug

  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.

OTA deployment of the board configuration image requires the 18.11.1 or newer SDK. To deploy a board configuration image package OTA:

  1. Prepare the device for field use:

    azsphere device prep-field --devicegroupid <devicegroup-GUID> --skuid <sku-GUID>

    Replace <devicegroup-GUID> and <sku-GUID> with the device group and product SKU IDs, respectively, for the devices that should receive the OTA deployment. To create a new device group and a new product SKU, use the --newdevicegroupname and --newskuname parameters instead, with appropriate names for the device group and product SKU.

  2. Deploy the board configuration image along with the application image in a single over-the-air deployment. Use the azsphere device link-feed command to create a new feed that contains both images. For example:

    azsphere device link-feed --newfeedname MyEthernetAppFeed --dependentfeedid 3369f0e1-dedf-49ec-a602-2aa98669fd61 --imagepath=enc28j60-isu0-int5.imagepackage,EthernetSample.imagepackage

    This command creates a new feed named MyEthernetAppFeed, which depends on the Retail Azure Sphere software feed, and supplies software to devices in the same device group as the attached device. The feed delivers two image packages: the enc28j60-isu0-int5 board configuration image package and the EthernetSample application image package.

Remove a 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.

Network configuration

The Azure Sphere application that you use with the Ethernet board configuration image must set up the IP configuration for the private Ethernet network. There is currently no DHCP client support on private Ethernet networks to set this up automatically. To set up the IP configuration, your application must call the configuration functions in applibs/networking.h, and the application manifest must enable the NetworkConfig capability.

DHCP server

An external client device that is connected to Azure Sphere through a private Ethernet interface must be assigned an IP address and other network parameters so that it can communicate to a server application on the Azure Sphere device. However, some external devices do not support a way to configure these parameters. Azure Sphere supports a DHCP server through which an application can provide this configuration. The application must enable the NetworkConfig capability in its application manifest.

The Azure Sphere application calls Networking_InitDhcpServerConfiguration() to configure the server to provide an IP address, subnet mask, gateway address, lease duration, and up to three NTP server addresses to a client device. Only one IP address can be configured in the current release. It then calls Networking_StartDhcpServer() to start the server on a particular network interface. After the DHCP server starts, the client device can send out broadcast DHCP messages to discover and request IP addresses from the DHCP server on the specified subnet.

SNTP server

The SNTP server enables client devices to synchronize their system time with that of the Azure Sphere device. To use the server, the Azure Sphere application must enable the NetworkConfig capability in its application manifest.

To start the server, the Azure Sphere application calls Networking_StartSntpServer() and specifies the network interface on which the server will run. The client device and the Azure Sphere device must be in the same local subnet of the network on which the server is running. The Azure Sphere device must be connected to Wi-Fi in addition to the private network, so that it can get the current time from a public network time protocol (NTP) server. The SNTP server does not respond to queries until it has the current time.

Note

Although an application can set the system time directly, this is not recommended because the time does not persist when the device loses power. Using the real-time clock with Azure Sphere has more information.

Listening ports

If the Azure Sphere application listens for incoming TCP or UDP connections, the application manifest must specify the ports that the application uses. Incoming UDP connections are allowed only on the private Ethernet network, and not on the public Wi-Fi network.

Ethernet setup sample

The Private Ethernet sample shows how to connect Azure Sphere to an Olimex ENC28J60-H module. It includes a sample Azure Sphere application that demonstrates how to set up a static IP configuration for the private Ethernet, how to configure and start the DHCP and SNTP servers, and how to use listening sockets to respond to an incoming TCP connection.