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.
CMakeSettings.json JSON file for configuring Visual Studio to use CMake with the correct command-line options.
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 building, debugging, and deploying the application.
HardwareDefinitions Folder containing the hardware definition files for various Azure Sphere boards.

Prerequisites

The sample requires the following hardware:

Note: By default, this sample targets MT3620 reference development board (RDB) hardware, such as the MT3620 development kit from Seeed Studios. To build the sample for different Azure Sphere hardware, change the Target Hardware Definition Directory in the CMakeLists.txt file. For detailed instructions, see the README file in the HardwareDefinitions folder.

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 21.04 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 following line at the command prompt:

    azsphere device enable-development

  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 and add an Ethernet adapter to your development board.

    • 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, change "eth0" to "wlan0":

      static const char NetworkInterface[] = "eth0";

      is changed to

      static const char NetworkInterface[] = "wlan0";

  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

Open a command prompt on your computer and type ipconfig. You should see that the DHCP server has issued an IP address in the 192.168.100.xxx range to your computer for its network connection:

<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 . . . . . . . . . :

If an IP address was not issued to your computer, then type the following at the command prompt: ipconfig /renew. This will cause the DHCP server to update the adapter configuration and issue a new IP address.

You could also find, download, and use a DHCP client test tool (not provided) on your computer to inspect the DHCP server response in more detail — such as to look at the NTP server address(es) returned.

Test the device's SNTP server

  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 and type the following command:

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

    This command invokes the Windows Time tool to query the device's SNTP server and to display the calculated difference between your computer's time and the device's time:

    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
    
  3. If the SNTP server doesn't respond, then you may see the following output. Check that the app is running and that the Azure Sphere device is connected to the internet.

    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

Ensure that the sample app is still running on your Azure Sphere device. Then, on your computer, use a terminal application to open a raw TCP connection to the Azure Sphere application's TCP server at 192.168.100.10 port 11000. You can open this connection with a third-party terminal application such as PuTTY (using a "raw" connection type), or with the built-in Telnet client for Windows.

To use the built-in Telnet client for Windows:

  1. Open Control Panel and click Programs and Features > Turn Windows features on or off to launch the Windows Features window.
  2. Ensure Telnet Client is selected and click OK.
  3. Open a command prompt and type telnet 192.168.100.10 11000.

The characters that you type will appear in the debug console in Visual Studio—either immediately or when you enter a newline—showing that they have been received by the example TCP server on the MT3620. When you enter a newline, the MT3620 sends the following string back to the terminal:

Received "<last-received-line>"

The sample server can hold 15 characters. If another character arrives before a newline has been received, the existing characters will be discarded and the newly-arrived character will be placed at the start of the buffer. The Output window in Visual Studio will display:

Input data overflow. Discarding 15 characters.

Next steps