nerves_time v0.4.0 NervesTime View Source

Keep time in sync on Nerves devices

NervesTime keeps the system clock on Nerves devices in sync when connected to the network and close to in sync when disconnected. It's especially useful for devices lacking a Battery-backed real-time clock and will advance the clock at startup to a reasonable guess.

Nearly all configuration is via the application config (config.exs). The following keys are available:

  • :servers - a list of NTP servers for time synchronization. Specifying an empty list turns off NTP
  • :time_file - a file path for tracking the time. It allows the system to start with a reasonable time quickly on boot and before the Internet is available for NTP to work.
  • :earliest_time - times before this are considered invalid and adjusted
  • :latest_time - times after this are considered invalid and adjusted
  • :ntpd - the absolute path to the Busybox ntpd. This only needs to be set if your system does not provide ntpd in the $PATH.

Link to this section Summary

Functions

Return the current NTP servers

Manually restart the NTP daemon

Set the list of NTP servers

Check whether NTP is synchronized with the configured NTP servers

Link to this section Functions

Link to this function

ntp_servers()

View Source
ntp_servers() :: [String.t()] | {:error, term()}

Return the current NTP servers

Link to this function

restart_ntpd()

View Source
restart_ntpd() :: :ok | {:error, term()}

Manually restart the NTP daemon

This is normally not necessary since NervesTime handles restarting it automatically. An example of a reason to call this function is if you know when the Internet becomes available. For this case, calling restart_ntp will cancel ntpd's internal timeouts and cause it to immediately send time requests. If using NTP Pool, be sure not to violate its terms of service by calling this function too frequently.

Link to this function

set_ntp_servers(servers)

View Source
set_ntp_servers([String.t()]) :: :ok

Set the list of NTP servers

Use this function to replace the list of NTP servers that are queried for time. It is also possible to set this list in your config.exs by doing something like the following:

config :nerves_time, :servers, [
  "0.pool.ntp.org",
  "1.pool.ntp.org",
  "2.pool.ntp.org",
  "3.pool.ntp.org"
]

NervesTime uses NTP Pool by default. To disable this and configure servers solely at runtime, specify an empty list in config.exs:

config :nerves_time, :servers, []
Link to this function

synchronized?()

View Source
synchronized?() :: boolean()

Check whether NTP is synchronized with the configured NTP servers

It's possible that the time is already set correctly when this returns false. NervesTime decides that NTP is synchronized when ntpd sends a notification that the device's clock stratum is 4 or less. Clock adjustments occur before this, though.

Once NTP is synchronized, it will remain that way until the nerves_time application is restarted.