Api
A package and CLI for WWVB timecodes
This is the full featured library suitable for use on 'real computers'.
For a reduced version suitable for use on MicroPython & CircuitPython,
see uwwvb.
This package also includes the commandline programs listed in the documentation,
perhaps most importantly wwvbgen for generating WWVB timecodes.
A stateful decoder of WWVB signals
main(am_data)
Read symbols on stdin and print any successfully-decoded minutes
wwvbreceive()
Decode WWVB signals statefully.
Create a decoder, then send it AmplitudeModulation values:
decoder = wwvbreceive()
next(decoder) # Must always discard first output before sending
for symbol in amplitude_modulation_signals:
decoded: WWVBTimecodeAM | None = decoder.send(symbol)
if decoded is not None:
... # Minute passed basic verification checks, do something with it
Retrieve iers data, possibly from user or site data or from the wwvbpy distribution
A command-line program for generating wwvb timecodes
main(
*, iers, leap_second, dut1, minutes, style, channel, all_timecodes, timespec
)
Generate WWVB timecodes
TIMESPEC: one of "year yday hour minute" or "year month day hour minute", or else the current minute
parse_timespec(ctx, param, value)
Parse a time specifier from the commandline
print_timecodes(w, minutes, channel, style, file, *, all_timecodes=False)
Print a range of timecodes with a header. This header is in a format understood by WWVBMinute.fromstring
print_timecodes_json(w, minutes, channel, file)
Print a range of timecodes in JSON format.
The result is a json array of minute data. Each minute data is an object with the following members:
- year (int)
- days (int)
- hour (int)
- minute (int)
- amplitude (string; only if channel is amplitude or both)
- phase: (string; only if channel is phase or both)
The amplitude and phase strings are of length 60 during most minutes, length 61 during a minute that includes a (positive) leap second, and theoretically length 59 in the case of a negative leap second.
Definition of the WWVBMinute and WWVBMinuteIERS classes
dataclass
WWVBMinute(year, days, hour, minute, dst=None, ut1=None, *, ls=None, ly=None)
Uniquely identifies a minute of time in the WWVB system.
To use ut1 and ls information from IERS, create a WWVBMinuteIERS
object instead.
Construct a WWVBMinute
Parameters:
-
year(int) –The 2- or 4-digit year. This parameter is converted by the
full_yearmethod. -
days(int) –1-based day of year
-
hour(int) –UTC hour of day
-
minute(int) –Minute of hour
-
dst(DstStatus | int | None, default:None) –2-bit DST code
-
ut1(int | None, default:None) –UT1 offset in units of 100ms, range -900 to +900ms
-
ls(bool | None, default:None) –Leap second warning flag
-
ly(bool | None, default:None) –Leap year flag
property
am_timecode
Fill the amplitude (AM) portion of a timecode object
instance-attribute
days
1-based day of year
instance-attribute
dst
2-bit DST code
instance-attribute
hour
UTC hour of day
instance-attribute
ls
Leap second warning flag
instance-attribute
ly
Leap year flag
instance-attribute
minute
Minute of hour
property
minute_of_century
Return the minute of the century
property
pm_timecode
Fill the phase portion of a timecode object
instance-attribute
ut1
UT1 offset in units of 100ms, range -900 to +900ms
instance-attribute
year
Full ("4-digit") year
__str__()
Implement str()
as_datetime_local(standard_time_offset=7 * 3600, *, dst_observed=True)
Convert to a local datetime according to the DST bits
The returned object has tz=datetime.timezone(computed_offset).
Parameters:
-
standard_time_offset(int, default:7 * 3600) –The UTC offset of local standard time, in seconds west of UTC. The default value,
7 * 3600, is for Colorado, the source of the WWVB broadcast. -
dst_observed(bool, default:True) –If
Truethen the locale observes DST, and a one hour offset is applied according to WWVB rules. IfFalse, then the standard time offset is used at all times.
as_datetime_utc()
Convert to a UTC datetime
The returned object has tzinfo=datetime.timezone.utc.
as_timecode()
Fill a WWVBTimecode structure representing this minute. Fills both the amplitude and phase codes.
as_timecode_am()
Fill a WWVBTimecodeAM structure representing this minute.
as_timecode_pm()
Fill a WWVBTimecodePM structure representing this minute.
classmethod
from_datetime(d, *, newut1=None, newls=None, old_time=None)
Construct a WWVBMinute from a datetime, possibly specifying ut1/ls data or propagating it from an old time
classmethod
from_timecode_am(t)
Construct a WWVBMinute from a WWVBTimecode
classmethod
fromstring(s)
Construct a WWVBMinute from a string representation created by print_timecodes
classmethod
full_year(year)
Convert a (possibly two-digit) year to a full year.
If the argument is above 100, it is assumed to be a full year. Otherwise, the intuitive method is followed: Say the epoch is 1970, then 70..99 means 1970..99 and 00..69 means 2000..2069.
To actually use a different epoch, derive a class from WWVBMinute (or WWVBMinuteIERS) and give it a different epoch property. Then, create instances of that class instead of WWVBMinute.
staticmethod
get_dst(year, days)
Get the 2-bit WWVB DST value for the given day
minute_length()
Return the length of the minute, 60, 61, or (theoretically) 59 seconds
next_minute(*, newut1=None, newls=None)
Return an object representing the next minute
previous_minute(*, newut1=None, newls=None)
Return an object representing the previous minute
dataclass
WWVBMinuteIERS(
year, days, hour, minute, dst=None, ut1=None, *, ls=None, ly=None
)
Timecode classes for WWVB timecodes
dataclass
WWVBTimecode(am, phase)
Bases: WWVBTimecodePhase, WWVBTimecodeAM
Represent the WWVB amplitude and phase signal, usually over 1 minute
__str__()
Implement str()
to_both_string(charset)
Convert both channels to a string
dataclass
WWVBTimecodeAM(am)
Represent the WWVB amplitude signal (only), usually over 1 minute
instance-attribute
am
The amplitude modulation data
__repr__()
Implement repr()
__str__()
Implement str()
to_am_string(charset)
Convert the amplitude signal to a string
dataclass
WWVBTimecodePhase(phase)
Represent the WWVB phase signal, usually over 1 minute
instance-attribute
phase
The phase modulation data
__repr__()
Implement repr()
__str__()
Implement str()
to_pm_string(charset)
Convert the phase signal to a string
Enumerated types and sequences thereof for WWVB timecodes
Bases: IntEnum
Constants that describe an Amplitude Modulation value
class-attribute
instance-attribute
MARK
A mark bit (reduced carrier during the first 800ms of the second)
class-attribute
instance-attribute
ONE
A one bit (reduced carrier during the first 500ms of the second)
class-attribute
instance-attribute
ZERO
A zero bit (reduced carrier during the first 200ms of the second)
Bases: IntEnum
The status of daylight saving time (DST)
class-attribute
instance-attribute
DST_ENDS_TODAY
DST ends during this UTC day
class-attribute
instance-attribute
DST_IN_EFFECT
DST in effect during the entire UTC day
class-attribute
instance-attribute
DST_NOT_IN_EFFECT
DST not in effect in any part of this UTC day
class-attribute
instance-attribute
DST_STARTS_TODAY
DST starts during this UTC day
Bases: IntEnum
Constants that describe a Phase Modulation value
class-attribute
instance-attribute
ONE
A zero bit (No phase shift during the second)
class-attribute
instance-attribute
ZERO
A one bit (180° phase shift during the second)
Implementation of a WWVB state machine & decoder for resource-constrained systems
This version is intended for use with MicroPython & CircuitPython.
WWVBDecoder()
A state machine for receiving WWVB timecodes.
Construct a WWVBDecoder
__str__()
Return a string representation of self
update(value)
Update the _state machine when a new symbol is received.
If a possible complete _minute is received, return it; otherwise, return None
apply_dst(dt, dst_bits, standard_time_offset=7 * 3600, dst_observed=True)
Apply time zone and DST (if applicable) to the given moment
as_datetime_local(
decoded_timestamp, standard_time_offset=7 * 3600, dst_observed=True
)
Convert a WWVBMinute to a local datetime with tzinfo=None
as_datetime_utc(decoded_timestamp)
Convert a WWVBMinute to a UTC datetime
decode_wwvb(t)
Convert a received minute of wwvb symbols to a WWVBMinute. Returns None if any error is detected.
get_am_bcd(seq, *poslist)
Convert the bits in the given positions (poslist[0] is MSB) from BCD to decimal
is_dst(dt, dst_bits, standard_time_offset=7 * 3600, dst_observed=True)
Return True iff DST is observed at the given moment