Skip to main content

Crate sntpc

Crate sntpc 

Source
Expand description

Rust SNTP client implementation

§Overview

This crate provides an async-first SNTP client for sending requests to NTP servers and processing responses to extract accurate timestamps.

Supported protocol version: SNTPv4 (RFC 5905)

Note: RFC 5905 §14 defines SNTPv4 and references RFC 4330 for SNTP client operational semantics.

§Quick Start

Add to your Cargo.toml:

[dependencies]
sntpc = "0.11"

For common usage patterns, choose a network adapter:

§Features

  • std - Standard library support (includes [StdTimestampGen])
  • sync - Synchronous API in sync module (default is async)
  • utils - OS-specific utilities for system time sync ⚠️ Unstable API
  • log - Debug logging via log crate
  • defmt - Debug logging via defmt (mutually exclusive with log)
  • dispersion - Compute total dispersion per RFC 5905 §9.2, exposed via NtpResult::dispersion

Warning: log and defmt are mutually exclusive features. If both are enabled, defmt takes priority.

§Architecture

The library is designed to work in both std and no_std environments through two key traits:

For std environments, [StdTimestampGen] is provided.

§API Approaches

  • get_time - Complete request/response in a single call (suitable for most cases)
  • sntp_send_request and sntp_process_response - Split send/receive workflow (useful when the TCP/IP stack requires polling or has custom timing requirements)

§Limitations

  • Broadcast mode (NTP mode 5) is not supported. The library only supports unicast client mode (mode 3 → mode 4). For broadcast client requirements, see RFC 5905 §14.
  • Minimum poll interval: Clients should not send requests at intervals less than one minute per RFC 4330 §5. The library does not enforce this; it is the caller’s responsibility.
  • NTP era rollover: NtpResult.seconds is u64. Wire timestamps roll over every 2^32 seconds; sntpc reconstructs the era as whichever of the nearest three eras (±2^31 seconds, ~68 years) around the timestamp generator’s timestamp_sec() best matches the wire value. A pivot more than half an era off silently produces a wrong-era result — no error is raised. See the README’s “NTP era rollover and embedded cold start” section for embedded cold-start guidance.

§Examples

See the examples directory for complete examples:

  • simple-request - Basic synchronous usage
  • tokio - Async with tokio runtime
  • embassy-net - Embedded async with embassy
  • smoltcp-request - Custom no_std networking
  • And more…

Refer to individual function documentation for minimal code examples

Modules§

sync
Synchronous interface for the SNTP client

Structs§

NtpContext
SNTP client context that contains of objects that may be required for client’s operation
NtpResult
SNTP request result representation
SendRequestResult
Preserve SNTP request sending operation result required during receiving and processing state

Enums§

Error
The error type for SNTP client Errors originate on network layer or during processing response from a NTP server
KissOfDeathCode
Kiss-o’-Death code received from an NTP server (RFC 5905 §7.4).

Traits§

NtpTimestampGenerator
A trait encapsulating timestamp generator’s operations
NtpUdpSocket
A trait encapsulating UDP socket interface required for SNTP client operations

Functions§

fraction_to_microseconds
Convert second fraction value to microseconds value
fraction_to_milliseconds
Convert second fraction value to milliseconds value
fraction_to_nanoseconds
Convert second fraction value to nanoseconds value
fraction_to_picoseconds
Convert second fraction value to picoseconds value
get_time
Retrieves the current time from an NTP server.
sntp_process_response
Processes the response from an NTP server.
sntp_send_request
Sends an SNTP request to an NTP server.

Type Aliases§

Result
SNTP library result type