Azure Sphere – Custom NTP

  • Code Sample
Browse code Download ZIP

This sample application demonstrates how to configure custom NTP servers on an MT3620 device.

The sample configures the NTP servers according to your configuration in the application manifest file. The last-time-synced information is retrieved when button A is pressed. The color of the LED indicates the time-synced status.

The sample uses the following Azure Sphere libraries.

Library Purpose
eventloop Invokes handlers for timer events.
gpio Manages button A (SAMPLE_BUTTON_1) and LED 2 on the device.
log Displays messages in the Device Output window during debugging.
networking Manages the network configuration of the device.

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

Complete the following steps to set up this sample.

  1. Ensure that your Azure Sphere device is connected to your computer, and your computer is connected to the internet.

  2. Ensure that you have Azure Sphere SDK version 24.03 or above. At the command prompt, run az sphere show-sdk-version to check. Upgrade the Azure Sphere SDK for Windows or Linux as needed.

  3. Ensure that the Azure CLI is installed. At a minimum, the Azure CLI version must be 2.45.0 or later.

  4. Install the Azure Sphere extension.

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

  6. Clone the Azure Sphere samples repository and find the CustomNTP_HighLevelApp sample in the CustomNTP folder or download the zip file from the Microsoft samples browser.

  7. Configure the sample application to work with your NTP server configuration. There are three different types of NTP server configurations possible:

    The sample can be configured with any one type at a time. For details, see the section Specifying an NTP Server in Manage system time and the RTC in high-level applications.

  8. Configure networking on your device. You must either set up WiFi or set up Ethernet on your development board, depending on the type of network connection you are using.

System default NTP server configuration

In this configuration, the sample connects to the system default (prod.time.sphere.azure.net) NTP server.

To configure the sample to connect to the system default NTP server, add "--TimeSource", "Default" in the CmdArgs field of the app_manifest.json file.

The CmdArgs field should now look like the following: "CmdArgs": [ "--TimeSource", "Default" ]

DHCP-assigned NTP server configuration

In this configuration, the sample connects to an NTP server that is assigned by DHCP.

To configure the sample to connect to a DHCP-assigned NTP server, make the following revisions in the app_manifest.json file:

  1. Add "--TimeSource", "Automatic" in the CmdArgs field.
  2. Fallback is enabled by default. To disable fallback, add "--DisableFallback" in the CmdArgs field. Configure this option only if you want fallback to be disabled.

The CmdArgs field should now look like the following:

  • With fallback enabled: "CmdArgs": [ "--TimeSource", "Automatic" ]
  • With fallback disabled: "CmdArgs": [ "--TimeSource", "Automatic", "--DisableFallback" ]

Custom NTP server configuration

In this configuration, the sample connects to up to two user-configured NTP servers. If you do not have access to an NTP server for testing, see NTP Pool Project for a list of NTP servers you can use with the sample.

To configure the sample to connect to a primary NTP server and, optionally, a secondary NTP server, make the following revisions in the app_manifest.json file:

  1. Add "--TimeSource", "Custom" in the CmdArgs field.
  2. Fallback is enabled by default. To disable fallback, add "--DisableFallback" in the CmdArgs field. Configure this option only if you want fallback to be disabled.
  3. Add "--PrimaryNtpServer", "<hostname_or_ip>" in the CmdArgs field and replace <hostname_or_ip> with the hostname or IP address of your primary NTP server.
  4. If you want the sample to connect to a secondary NTP server, add "--SecondaryNtpServer", "<hostname_or_ip>" in the CmdArgs field and replace <hostname_or_ip> with the hostname or IP address of your secondary NTP server.

The CmdArgs field should now look the following:

  • With only a primary NTP server configured:

    • With fallback enabled: "CmdArgs": [ "--TimeSource", "Custom", "--PrimaryNtpServer", "<hostname_or_ip>" ]
    • With fallback disabled: "CmdArgs": [ "--TimeSource", "Custom", "--DisableFallback", "--PrimaryNtpServer", "<hostname_or_ip>" ]

  • With a secondary NTP server configured:

    • With fallback enabled: "CmdArgs": [ "--TimeSource", "Custom", "--PrimaryNtpServer", "<hostname_or_ip>", "--SecondaryNtpServer", "<hostname_or_ip>" ]
    • With fallback disabled: "CmdArgs": [ "--TimeSource", "Custom", "--DisableFallback", "--PrimaryNtpServer", "<hostname_or_ip>", "--SecondaryNtpServer", "<hostname_or_ip>" ]

Build and run the sample

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

Test the sample

When the sample runs, it configures the NTP servers according to your configuration in the application manifest file. The output will be displayed in the terminal window. Once the device successfully syncs with the configured NTP server, it will display a log message, Successfully synced with the configured NTP server.

Use button A (SAMPLE_BUTTON_1) and the status LED as described below.

SAMPLE_BUTTON_1 does the following:

  • Gets the last-time-synced information.
  • If the device has not yet successfully time-synced, the sample logs a debug message informing the user that the device has not time-synced yet.
  • If the device has successfully time-synced, the sample logs a message displaying the time before the sync, and the new adjusted time after the successful sync.

The color of the status LED indicates the following:

  • Red — Not time-synced. This state is true on reboot till the device successfully time-syncs with the NTP server, or when the NTP server config is changed and the device has not yet synced with the NTP server.
  • Green — The device has time-synced successfully to the NTP server. This state is true when the device successfully syncs with the configured NTP server.

Next steps