Azure Sphere – Private network services

This sample application demonstrates how you can connect an Azure Sphere device to a private network and use network services. It configures the Azure Sphere device to run a DHCP server and an SNTP server, and implements a basic TCP server.

The DHCP and SNTP servers are managed by the Azure Sphere OS and configured by the high-level application. The servers start only upon request from the application but continue to run even after the application stops.

The TCP server runs in the application process and stops when the application stops. Note that this sample TCP server implementation is basic, for illustration only, and that it does not authenticate or encrypt connections; you should replace it with your own production logic.

The sample uses the following Azure Sphere libraries.

Library Purpose
eventloop Invokes handlers for timer events.
log Displays messages in the Device Output window during debugging.
networking Gets and sets network interface configuration.

Contents

File/folder Description
app_manifest.json Application manifest file, which describes the resources.
CMakeLists.txt CMake configuration file, which Contains the project information and is required for all builds.
CMakePresets.json CMake presets file, which contains the information to configure the CMake project.
launch.vs.json JSON file that tells Visual Studio how to deploy and debug the application.
LICENSE.txt The license for this sample application.
main.c Main C source code file.
README.md This README file.
.vscode Folder containing the JSON files that configure Visual Studio Code for deploying and debugging the application.
HardwareDefinitions Folder containing the hardware definition files for various Azure Sphere boards.

Prerequisites

The sample requires the following hardware:

Setup

  1. Set up your Azure Sphere device and development environment as described in the Azure Sphere documentation.

  2. Even if you've performed this set up previously, ensure that you have Azure Sphere SDK version 23.05 or above. At the command prompt, run azsphere show-version to check. Install the Azure Sphere SDK as needed.

  3. Connect your Azure Sphere device to your computer by USB.

  4. Enable application development, if you have not already done so, by entering the azsphere device enable-development command at the command prompt.

  5. Clone the Azure Sphere samples repository and find the PrivateNetworkServices sample in the PrivateNetworkServices folder or download the zip file from the Microsoft samples browser.

  6. Configure the sample for your network interface. This sample will run on any supported network interface. However, it is configured by default for a private Ethernet network.

    • To use Ethernet, you must connect and configure an Ethernet adapter to your MT3620 development board. See Connect Azure Sphere to Ethernet for instructions.

    • To use a different network interface, change the value of the global constant NetworkInterface in the source file PrivateNetworkServices\main.c. For example, to specify a Wi-Fi network, replace eth0 with wlan0 in the following code in main.c:

      static const char NetworkInterface[] = "eth0";
      
  7. If you want the sample to set and retreive the sizes of the socket send/receive buffers, add code that uses the standard getsockopt and setsockopt functions.

Build and run the sample

To build and run this sample, follow the instructions in Build a sample application.

Test the sample

This sample configures the Azure Sphere device to run a DHCP server and an SNTP server, and implements a basic TCP server.

Complete the following steps to test this functionality:

  1. Connect your computer to the same private network to which you connected your device. If using an Ethernet private network, attach an Ethernet cable from the Ethernet adapter on the device to the Ethernet connection on your computer.

  2. If your computer is managed by policies that prevent it from being connected to multiple network interfaces at once, you may need to disable other network interfaces while using this sample.

  3. Perform the following operations, which are described in the sections below:

Note: The sample uses the IP address range 192.168.100.xxx. If you have another network adapter that uses the same range, you will need to either modify the sample or disable the other network adapter temporarily.

Test the device's DHCP server

To test the device's DHCP server, verify that the server has issued an IP address to your computer for its network connection.

  1. Open a command prompt on your computer.

  2. Enter a command that displays the IP addresses for the adapters. For example, enter ipconfig if you're using Windows.

    You should see that the DHCP server has issued an IP address in the 192.168.100.xxx range to your computer, as shown in the following sample output of ipconfig:

    <network interface type> adapter <name>:
    
       Connection-specific DNS Suffix  . :
       Link-local IPv6 Address . . . . . : fe80::8c67:be24:4d9a:d4bb%9
       IPv4 Address. . . . . . . . . . . : 192.168.100.11
       Subnet Mask . . . . . . . . . . . : 255.255.255.0
       Default Gateway . . . . . . . . . :
    
  3. If an IP address was not issued to your computer, enter a command that requests the DHCP server to issue a new IP address. For example, enter ipconfig /renew if you're using Windows.

Alternatively, you can use a DHCP client test tool (not provided) on your computer to inspect the DHCP server response in more detail. For example, you may want to look at the NTP server addresses returned.

Test the device's SNTP server

To test the device's SNTP server, verify that the server responds to a query for the offset between your computer's time and the device's time.

  1. Ensure the Azure Sphere device is connected to the internet via a different network interface (for example, Wi-Fi if using private Ethernet), so that it can obtain time settings from a public NTP server. The SNTP server won't respond until it knows the current time.

  2. Open a command prompt on your computer.

  3. Enter a command that displays the difference between your computer's time and the device's time. For example, enter the following command if you're using Windows:

    w32tm /stripchart /computer:192.168.100.10 /dataonly /samples:1
    

    Sample output of the w32tm command is as follows:

    Tracking 192.168.100.10 [192.168.100.10:123].
    Collecting 1 samples.
    The current time is 06/02/2019 14:18:09.
    14:18:09, +00.0349344s
    

    For details about the w32tm command, see Windows Time tool w32tm.

  4. If the SNTP server doesn't respond, check that the app is running and that the Azure Sphere device is connected to the internet.

    You may see an error similar to the one shown in the following w32tm command output when the SNTP server doesn't respond.

    Tracking 192.168.100.10 [192.168.100.10:123].
    Collecting 1 samples.
    The current time is 06/02/2019 14:16:50.
    14:16:50, error: 0x800705B4
    

Test the application's TCP server

To test the application's TCP server, verify that the characters you type are received and acknowledged by the server.

  1. Ensure that the sample app is still running on your Azure Sphere device.

  2. On your computer, use a terminal emulator to open a raw TCP connection to the application's TCP server at 192.168.100.10 port 11000. You can open this connection with a third-party terminal emulator, such as PuTTY (using a raw connection type), or with the Windows Telnet client.

    To use the Windows built-in Telnet client:

    1. Open Control Panel and select Programs and Features > Turn Windows features on or off to launch the Windows Features window.
    2. Ensure Telnet Client is selected and select OK.
    3. Open a command prompt and enter telnet 192.168.100.10 11000.
  3. Type characters in the terminal. The application's TCP server can hold a maximum of 15 characters before it expects a newline character.

    If you're using Visual Studio, the characters that are received by the server will appear in the debug console—either immediately or when you press the Enter key, which puts a newline character in the buffer.

    If the server receives a 16th character before a newline character has been received, the previous 15 characters are discarded, the newly-arrived character is placed at the start of the buffer, and the output window in Visual Studio displays the following text:

    Input data overflow. Discarding 15 characters.

  4. Watch the terminal for a response from the server when you press the Enter key. You should see the following response from the server:

    Received "<last-received-line-of-text>"

Further reference

You may also be interested in the following related projects on the Azure Sphere Gallery:

  • EAP-TLS_Solution | A library & demo solution implementation for Azure Sphere-based devices connecting to Extensible Authentication Protocol – Transport Layer Security (EAP-TLS) networks.
  • NetworkInterfaceAddresses | A minimal Azure Sphere app that prints the MAC and IP address of the given network interface.
  • OSNetworkRequirementChecker-HLApp | A sample app that performs DNS resolver and custom NTP test for diagnosing networking connectivity problems.
  • OSNetworkRequirementChecker-PC | A PC command line utility for diagnosing networking connectivity issues.
  • UdpDebugLog | Code that demonstrates how to override Log_Debug to broadcast on a UDP Socket, includes a Desktop Viewer application.

Next steps