Use network services

Article
09/26/2024

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.

Azure Sphere can run a static IP address, dynamic host configuration protocol (DHCP) server, and a simple network time protocol (SNTP) server for a network interface. The DHCP server enables Azure Sphere applications to configure network parameters for an external device on the network. The external device can use the SNTP server to synchronize its time with Azure Sphere.

Network configuration

You can configure an Ethernet and a Wi-Fi network interface to run simultaneously on an Azure Sphere device. Ethernet and Wi-Fi network interfaces can be connected to public (internet connected) or private networks. At least one interface must be connected to a public network. Only one Ethernet interface can be configured at a time.

Private and public network interfaces

If you use both public and private network interfaces, such as private Ethernet with public Wi-Fi, the Azure Sphere device will not act as a router. It won't automatically pass packets received on the Ethernet network to the Wi-Fi network, or vice versa. Your application must implement all logic that sends and receives information on both networks.

Dual public network interfaces

If you use two network interfaces that have dynamic IP addressing enabled, the OS attempts to use the first interface that connected to the network when it selects DNS server addresses for host name resolution. If an interface disconnects from the network, the DNS server addresses from the other connected interface are automatically used.

Static IP address

You can configure a static IP address on an Ethernet or Wi-Fi interface. To set up a static IP address configuration, your application must use the applibs networking API, and the application manifest must enable the NetworkConfig capability.

When configuring a static IP address, custom DNS must also be set to ensure the Azure Sphere OS continues to function as expected.

The Private Network Services sample demonstrates how to connect Azure Sphere to a private network and use several network services.

This code snippet demonstrates how to configure a network interface with a static IP address.

Include the following line in the Capabilities section of the app_manifest.json file as follows:

"Capabilities": {
  "NetworkConfig": true
}

Include these header files in your application:

#include <arpa/inet.h>
#include <errno.h>
#include <string.h>
#include <applibs/log.h>
#include <applibs/networking.h>

Set the IP address, subnet mask, and gateway for the IP configuration.

static const char staticIpInDotNotation[] = "yourStaticIp"; // Your static IP in x.x.x.x notation.
static const char subnetMaskInDotNotation[] =
    "yourSubnetMask"; // Your subnet mask in x.x.x.x notation.
static const char gatewayIpInDotNotation[] = "yourGatewayIp"; // Your gateway IP in x.x.x.x notation.

Specify the network interface to configure:

static const char networkInterfaceToConfigure[] = "yourNetworkInterface"; // Your network interface.

Convert the network addresses to integers and apply this to the specified network interface.

struct in_addr staticIpAddress;
struct in_addr subnetMask;
struct in_addr gatewayIpAddress;

Networking_IpConfig ipConfig;

// Convert the addresses from the numbers-and-dots notation into integers.
if (inet_pton(AF_INET, staticIpInDotNotation, &staticIpAddress) != 1) {
    Log_Debug("ERROR: Invalid static IP address or address family specified.\n");
    return -1;
}
if (inet_pton(AF_INET, subnetMaskInDotNotation, &subnetMask) != 1) {
    Log_Debug("ERROR: Invalid subnet mask or address family specified.\n");
    return -1;
}
if (inet_pton(AF_INET, gatewayIpInDotNotation, &gatewayIpAddress) != 1) {
    Log_Debug("ERROR: Invalid gateway IP address or address family specified.\n");
    return -1;
}

Networking_IpConfig_Init(&ipConfig);
Networking_IpConfig_EnableStaticIp(&ipConfig, staticIpAddress, subnetMask, gatewayIpAddress);

int result =
    Networking_IpConfig_EnableCustomDns(&ipConfig, dnsServers, numOfDnsServerAddressSpecified);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_EnableCustomDns: %d (%s)\n", errno, strerror(errno));
    Networking_IpConfig_Destroy(&ipConfig);
    return -1;
}

int result = Networking_IpConfig_Apply(networkInterfaceToConfigure, &ipConfig);
Networking_IpConfig_Destroy(&ipConfig);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_Apply: %d (%s)\n", errno, strerror(errno));
    return -1;
}

Static DNS address

If you have configured a device with a static IP and require name resolution your application must set a static DNS address. Use Networking_IpConfig_EnableCustomDns and set one or more valid DNS resolvers. If multiple resolvers are set, they will all be queried, and the first valid DNS response will satisfy the query. Networking_IpConfig_EnableCustomDns may also be used to override the current resolver if one is set via DHCP.

To configure a network interface with custom DNS servers, the application manifest must enable the NetworkConfig capability.

Include the following line in the Capabilities section of the app_manifest.json file as follows:

"Capabilities": {
  "NetworkConfig": true
}

This code snippet demonstrates how to configure a network interface with custom DNS servers.

Include these header files in your application:

#include <arpa/inet.h>
#include <errno.h>
#include <string.h>
#include <applibs/log.h>
#include <applibs/networking.h>

Specify the number of DNS servers. Up to three DNS servers can be specified. The following code sets up the array of three DNS server IP addresses to use.

// A maximum of 3 DNS server addresses can be specified.
static const size_t numOfDnsServerAddressSpecified = 3;
static const char *dnsServerIpAddress[] = {
    "yourDnsServer1", "yourDnsServer2", "yourDnsServer3"}; // Your DNS servers in x.x.x.x notation.

Specify the network interface to configure.

static const char networkInterfaceToConfigure[] = "yourNetworkInterface"; // Your network interface.

Convert the network addresses to integers and apply the configuration. This DNS configuration overrides any DNS servers specified by DHCP.

Networking_IpConfig ipConfig;

// Convert the addresses from the numbers-and-dots notation into integers.
struct in_addr dnsServers[numOfDnsServerAddressSpecified];
for (int i = 0; i < numOfDnsServerAddressSpecified; i++) {
    if (inet_pton(AF_INET, dnsServerIpAddress[i], &dnsServers[i]) != 1) {
        Log_Debug("ERROR: Invalid DNS server address or address family specified.\n");
        return -1;
    }
}

Networking_IpConfig_Init(&ipConfig);

int result =
    Networking_IpConfig_EnableCustomDns(&ipConfig, dnsServers, numOfDnsServerAddressSpecified);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_EnableCustomDns: %d (%s)\n", errno, strerror(errno));
    Networking_IpConfig_Destroy(&ipConfig);
    return -1;
}

result = Networking_IpConfig_Apply(networkInterfaceToConfigure, &ipConfig);
Networking_IpConfig_Destroy(&ipConfig);

if (result != 0) {
    Log_Debug("ERROR: Networking_IpConfig_Apply: %d (%s)\n", errno, strerror(errno));
    return -1;
}

DHCP server

An external client device that is connected to Azure Sphere through an Ethernet interface must be assigned an IP address and other network parameters so that it can communicate with 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 DhcpService capability in its application manifest.

The Azure Sphere application calls Networking_DhcpServerConfig_Init 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_DhcpServer_Start 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 SntpService capability in its application manifest.

To start the server, the Azure Sphere application calls Networking_SntpServer_Start 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 at least one public 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. Manage system time and the RTC on 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. For example:

"Capabilities": {
  "AllowedTcpServerPorts": [ 11000 ],
  "AllowedUdpServerPorts": [ 1024, 50000 ]
}

Samples

The DNS Service Discovery sample demonstrates how to query and process responses from a DNS server.
The Private Network Services sample demonstrates how to connect Azure Sphere to a private network and use several network services.

Share via