Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

PyPI

Purpose

Python package and command line programs for interacting with WWVB timecodes.

Where possible, wwvbpy uses existing facilities for calendar and time manipulation (datetime and dateutil).

It uses DUT1/leap second data derived from IERS Bulletin "A" and from NIST's "Leap second and UT1-UTC information" page. With regular updates to the "iersdata", wwvbpy should be able to correctly encode the time anywhere within the 100-year WWVB epoch. (yes, WWVB uses a 2-digit year! In order to work with historical data, the epoch is arbitrarily assumed to run from 1970 to 2069.)

Programs include:

  • wwvbgen, the main commandline generator program
  • wwvbdecode, the main commandline decoder program
  • wwvbtk, visualize the simulated WWVB signal in real-time using Tkinter
  • dut1table, print the full history of dut1 values, including estimated future values
  • updateiers, download the latest dut1 data including prospective data from IERS and NIST

The package includes:

  • wwvb, for generating WWVB timecodes
  • wwvb.decode, a generator-based state machine for decoding WWVB timecodes (amplitude modulation only)
  • uwwvb, a version of the decoder intended for use on constrained environments such as CircuitPython.

Development status

The author (@jepler) occasionally develops and maintains this project, but issues are not likely to be acted on. They would be interested in adding co-maintainer(s).

WWVB Timecodes

The National Institute of Standards and Technology operates the WWVB time signal service near Fort Collins, Colorado. The signal can be received in most of the continental US. Each minute, the signal transmits the current time, including information about leap years, daylight saving time, and leap seconds. The signal is composed of an amplitude channel and a phase modulation channel.

The amplitude channel can be visualized as a sequence of (usually) 60 symbols, which by default wwvbgen displays as 0, 1, or 2. The 0s and 1s encode information like the current day of the year, while the 2s appear in fixed locations to allow a receiver to determine the start of a minute.

The phase channel (which is displayed with --channel=phase or --channel=both) consists of the same number of symbols per minute. This channel is substantially more complicated than the phase channel. It encodes the current time as minute-of-the-century, provides extended DST information, and includes error-correction information not available in the amplitude channel.

Usage

For example, to display the leap second that occurred at the end of 1998,

$ wwvbgen -m 7 1998 365 23 56
WWVB timecode: year=98 days=365 hour=23 min=56 dst=0 ut1=-300 ly=0 ls=1
'98+365 23:56  210100110200100001120011001102010100010200110100121000001002
'98+365 23:57  210100111200100001120011001102010100010200110100121000001002
'98+365 23:58  210101000200100001120011001102010100010200110100121000001002
'98+365 23:59  2101010012001000011200110011020101000102001101001210000010022
'99+001 00:00  200000000200000000020000000002000100101201110100121001000002
'99+001 00:01  200000001200000000020000000002000100101201110100121001000002
'99+001 00:02  200000010200000000020000000002000100101201110100121001000002

(the leap second is the extra digit at the end of the 23:59 line; that minute consists of 61 seconds, instead of the normal 60)

How wwvbpy handles DUT1 data

wwvbpy stores a compact representation of DUT1 values in iersdata.json, the format of which is an implementation detail.

Since 2001, NIST has published the actual DUT1 values broadcast, and the date of each change, though it in the format of an HTML table and not designed for machine readability.

NIST does not update the value daily and does not seem to follow any specific rounding rule. Rather, in WWVB "the resolution of the DUT1 correction is 0.1 s, and represents an average value for an extended range of dates. Therefore, it will not agree exactly with the weekly UT1-UTC(NIST) values shown in the earlier table, which have 1 ms resolution and are updated weekly." Like wwvbpy's compact representation of DUT1 values, the real WWVB does not appear to ever broadcast DUT1=-0.0.

For a larger range of dates spanning 1973 through approximately one year from now, IERS publishes historical and prospective UT1-UTC values to multiple decimal places, in a machine readable fixed length format.

wwvbpy merges the WWVB and IERS datasets, favoring the WWVB dataset for dates when it is available. There are some caveats to this, which are mostly commented in the wwvb/updateiers.py script.

The git version of iersdata.json is updated monthly from forgejo actions or with updateiers --dist from within the wwvbpy source tree. However, at this time, releases are not regularly made from the updated information.

A site or user version of the file, wwvb_iersdata.py can be created or updated with updateiers --site or updateiers --user. If the distributed iersdata is out of date, the generator will prompt you to run the update command.

Leap seconds are inferred from the DUT1 data as follows: If X and Y are the 1-digit-rounded DUT1 values for consecutive dates, and X*Y<0, then there is a leap second at the end of day X. The direction of the leap second can be inferred from the sign of X, a 59-second minute if X is positive and a 61-second minute if it is negative. As long as DUT1 changes slowly enough during other times that there is at least one day of DUT1=+0.0, no incorrect (negative) leapsecond will be inferred. (something that should remain true for the next few centuries, until the length of the day is 100ms different from 86400 seconds)

The phase modulation channel

This should be considered more experimental than the AM channel, as the tests only cover a single reference minute. Further tests could be informed by the other implementation I know of, except that implementation appears incomplete.

Testing wwvbpy

Run the testsuite, check coverage & type annotations with gmake.

There are several test suites:

  • testwwvb.py: Check output against expected values. Uses hard coded leap seconds. Tests amplitude and phase data, though the phase testcases are dubious as they were also generated by wwvbpy.
  • testuwwvb.py: Test the reduced-functionality version against the main version
  • testls.py: Check the IERS data through 2020-1-1 for expected leap seconds
  • testpm.py: Check the phase modulation data against a test case from NIST documentation
  • testcli.py: Check the commandline programs work as expected (limited tests to get 100% coverage)

Metadata

Release files for wwvb 10.0.0a0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wwvb 10.0.0a0
File Size Uploaded Provenance Actions
wwvb-10.0.0a0.tar.gz 60.3 kB Without provenance Details for wwvb-10.0.0a0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wwvb 10.0.0a0
File Interpreter ABI Platform Actions
wwvb-10.0.0a0-py3-none-any.whl Python 3 none any Details for wwvb-10.0.0a0-py3-none-any.whl

Total release size: 90.1 kB

Release files / wwvb-10.0.0a0.tar.gz

Download URL wwvb-10.0.0a0.tar.gz
Size 60.3 kB
Tags Source
SHA-256 checksum
How to use checksums
281877c9c00f7799572137261a21aa5ca6aea09ef470679ede38d9ebdcc26c59
BLAKE2b-256 checksum
How to use checksums
07168fdb5dd5a45a864fca790a5fa5f8f0910193f3688676fa2457da93f5f221
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / wwvb-10.0.0a0-py3-none-any.whl

Download URL wwvb-10.0.0a0-py3-none-any.whl
Size 29.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6d83fa8befc2ff30e62334aff2ed8077b8dc3608ad4ad399b256be5b5e7a46a4
BLAKE2b-256 checksum
How to use checksums
b2ba39750e81fdcc0dc2c7dad73b7df4520a1c2795872f8bdc87b4cbab54ac8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for wwvb 10.0.0a0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page