NTP1061

Example Path: examples/PlatformSpecific/NTP1061

GPS-Disciplined NTP Server (SOMRT1061)

Overview

This example is a complete GPS-disciplined Stratum-1 NTP server built on the NetBurner SOMRT1061. The device reads UTC time from an onboard GPS module, uses the GPS's once-per-second pulse (PPS) to discipline the iMX RT1060's IEEE 1588 hardware timer, and answers NTP queries on UDP port 123 with timestamps accurate to microseconds of the GPS reference.

A configuration and status web UI is served over HTTP and HTTPS. Auto-generated SSL certificates are created once GPS time is known (certificates need a valid wall-clock time at signing time). A factory-reset button and remote console are provided for field recovery.

The application builds as SOM_NTP and targets SOMRT1061 exclusively.

What This Example Does

1. Initializes the SOMRT1061 IEEE 1588 timer and enables PPS capture.
2. Brings up the GPS chip and attaches it to the 1588 timer, so each GPS PPS edge latches a hardware timestamp.
3. Starts the NTPServer class listening on UDP port 123. Incoming client requests are answered using the PPS-disciplined 1588 timer for the transmit timestamp.
4. Reads (or initializes) non-volatile settings from user parameter flash (nvsettings.cpp). On first boot, sets a default mDNS name (nbntp.local).
5. Decides how to obtain an SSL certificate:
   • If the user has installed a cert through the web UI, load it from flash.
   • Otherwise use the auto-generated cert stored in HAL flash, if valid.
   • If neither is available, start HTTP only; generate and install a self-signed cert once GPS time is acquired, then enable HTTPS.
6. Starts the web server (HTTP on 80, HTTPS on 443 – either or both per WebUIConfig).
7. Enables the remote console, registers a factory-reset button handler on the GPS_RST pin (press to reboot; hold 5 s to wipe all settings and regenerate certs), and starts a GPS temperature monitor.

Hardware / Platform

• Platform: SOMRT1061 (NXP iMX RT1061 Cortex-M7) – no other platform is supported; the makefile sets SUPPORTED_PLATFORMS = SOMRT1061.
• GPS chip: driven through the GPSChip class (src/class/GPSChip.h). Provides absolute UTC time and a 1 PPS hardware edge.
• IEEE 1588 timer: the RT1060 ENET_1588 timer captures the PPS edge with nanosecond resolution; see IEEE1588Timer (src/class/IEEE1588Timer.h).
• Factory-reset button: wired to PIN_GPS_RST. Short press -> reboot; hold >=5 s -> factory reset (erases SSL certs, config, and NV settings).
• Status LED: pin 47. The /pulse.html endpoint blinks it as a connectivity check.

Key Classes

Class	Purpose
GPSChip	UART + PPS driver for the onboard GPS; exposes time and fix state.
IEEE1588Timer	Wrapper around the RT1060 IEEE 1588 timer with PPS capture.
NTPServer	NTP v3/v4 server; builds responses from 1588 timer state.
TempMonitor	Periodically reads GPS chip die temperature.
WebUIConfig	Persistent web-UI settings (config_obj under appdata).

Project Structure

NTP1061/
    |
    +-- src/
    |   +-- main.cpp               Startup, reset button, web endpoints
    |   +-- certificatekey.cpp     Auto-generated self-signed cert/key logic
    |   +-- nvsettings.cpp/h       Non-volatile settings record
    |   +-- somntp_cfg.h           Build-time version / config macros
    |   +-- ssl_config.h           SSL/TLS build-time configuration
    |   +-- ssluser.cpp/h          User-installed cert management
    |   +-- webfunctions.cpp       HTTP callbacks for the web UI
    |   +-- webui_config.h         WebUIConfig class declaration
    |   +-- htmldata.cpp           Generated from html/ by comphtml at build time
    |   +-- class/
    |       +-- GPSChip.*          GPS UART + PPS driver
    |       +-- GPSLocation.*      Parsed location record
    |       +-- GPSTime.*          GPS time conversion helpers
    |       +-- GPSSat.*           Per-satellite fix info
    |       +-- IEEE1588Timer.*    Hardware PTP timer wrapper
    |       +-- NTPServer.*        NTP request/response handling
    |       +-- TempMonitor.*      GPS chip temperature polling task
    |
    +-- html/                      Web UI (index, config, setup, status pages)
    +-- makefile                   Build configuration (SOM_NTP / SOMRT1061)
    +-- ReadMe.txt                 This file

Network Services

Port	Protocol	Service
80	TCP	HTTP web UI (optional – disable via WebUIConfig).
443	TCP	HTTPS web UI (requires a cert; auto-generated after GPS sync if none installed).
123	UDP	NTP server (always on).

mDNS advertises the device as nbntp.local by default on first boot.

First-Boot Behavior

1. Device boots, attempts to get an IP via DHCP.
2. GPS begins its cold-start fix. NTP responses are suppressed until the 1588 timer is disciplined.
3. HTTP web UI comes up immediately on port 80 for configuration.
4. Once GPS time is valid, the firmware generates a self-signed certificate (20-year expiration) and starts HTTPS on 443. Clients will see a self-signed-cert warning – that's expected. A user cert can be installed later via the web UI.

Recovery

• Short-press the reset button: reboot (equivalent to power-cycling).
• Hold the reset button >=5 seconds: full factory reset – erases user-installed certs, the auto-generated HAL cert, all config_obj records, and the NV settings blob. The device reboots into first-boot state.

Build / Load

make PLATFORM=SOMRT1061
make load PLATFORM=SOMRT1061 DEVIP=<device-ip>

The makefile auto-runs comphtml on the html/ folder to regenerate src/htmldata.cpp whenever a web asset changes.

Important Notes

• No EnableOnboardCertificateCreation(). As an NTP server the device cannot rely on an external time source to decide when to generate its own certs – it needs GPS time first. Cert generation is therefore managed manually in UserMain after the GPS lock.
• Self-signed warnings are expected unless the user installs their own cert. A manual-regenerate button is provided in the web UI.
• Any time() below 2026-01-01 is treated as invalid (MIN_VALID_UNIX_TIME sentinel in src/main.cpp) – the firmware refuses to sign certificates until the GPS clock is trusted.