Jeff Epler's blog

CWWVB: Putting what I've learned about WWVB to use in a new decoder

It's time to write a new WWVB decoder from scratch. This one relies on regular sampling of the amplitude output of a low-cost WWVB receiver. Since these receivers already introduce up to 100ms of phase shift, trying to "home in on" the exact start of second isn't too useful, but sampling at 20ms is quite enough to tell the 0/1/Mark symbols apart.

Unlike other decoders I've read about (or written), this one is neither based on simple pulse lengths (PulseIn) nor does it have a "start of second acquisition" phase separate from the "receive & decode a full minute" phase. Instead, the 'start of second' is continuously tracked by statistics over the last 30-60 seconds of data, and then at the end of each second a symbol is decoded.

The start of the second is the sample where the discrete derivative of the signal strength is greatest, at an offset of 0.16 here (based on a rather noisy set of input data):

Because the statistic is continuously (but efficiently) tracked, it doesn't matter if the local sampling clock has an error relative to WWVB. This just causes the offset to slowly shift, but doesn't affect decoding.

It's targeted at Cortex M microcontrollers, though it might fit on smaller micros like those on the classic Arduino. So far, I've only run it against logs from the WWVB Observatory, but it far outperforms my existing CircuitPython WWVB decoder (source code not online)---In an hour where my existing clock (using a PulseIn-like strategy) recieved 0 minutes successfully due to storms in the area, the new algorithm decoded 39 out of 59 minutes.

The C++ code is called CWWVB and it is up on github! It's not fully commented, but it does explain things more closely that this blog post does. My fresh receiver modules aren't coming before the end of the month, but I'm thinking of doing a very simple display, such as just showing MM:SS on a 4-digit 8-segment display, with an Adafruit Feather M4 for the microcontroller.

WWVB Observatory

A lot of my play coding lately has been related to WWVB, a 60kHz radio time signal broadcast from near Fort Collins, Colorado, USA.

I'm calling my latest work the "WWVB Observatory": I'm capturing the amplitude signal from an inexpensive "MAS6180C" receiver connected to a Raspberry Pi 50 times a second, and uploading the result to github hourly. The Pi is well-synchronized to the accurate time using NTP, and while it's not running as real-time software, the 20ms sample rate doesn't seem to pose any practical problems.

I'm mostly interested in using the data "ex post facto" to develop and measure the performance of different decoder algorithms, though I haven't started on that part yet. Others may have their own ideas.

In principle, this software infrastructure can also be used with other clock signals compatible with the MAS6180C: DCF77, HGB, MSF, JJY and BPC.

The code and data are on github. Right now I'm hoping to operate it for at least months, and if there's ever another leap second I fully intend to un-mothball it to try to record that very special moment that happens only rarely in the past few years.

One sub-part of the WWVB Observatory is an independent library for working with the leap second database known as "leap-seconds.list". I've uploaded it to github & pypi.

I still need to break out my "advanced Linux timekeeping APIs" library, erroneously called "clock_nanosleep.py". It wraps clock_nanosleep, clock_gettime, clock_settime and ntp_adjtime. clock_nanosleep is interesting because you can sleep until a particular deadline specified against a particular timesource (UTC, TAI, or monotonic being the useful options). Sleeping until a deadline is a fundamental building block of "realtime-ish" code like the WWVB Observatory.

My experience adding type annotations to a 2.5k-line Python library

The wwvb package for Python has been a focus of my recent hobby-time programming. I've used it as a place to educate myself about the ins and outs of maintaining a Python package. In the past, I used it to learn about using pylint, black & code coverage to improve the quality of Python code. Most recently, I added type annotations through the whole package until mypy --strict was happy with the whole wwvb package and uwwvb module.

The annotations were added in two steps: See pull requests #7 and #8. Together, these PRs contained 320 insertions and 223 deletions across 14 python files, plus 6 insertions in 2 other files related to CI. I did the work during a part of a day, probably under 4 hours of time spent. Since the package currently contains exactly 2500 physical lines of Python code, adding type annotations touched or added over 10% of physical lines!

Quick CircuitPython Driver for ES100 WWVB Receiver

I picked up an ES100 WWVB receiver kit and wrote a quick & dirty library to interact with it in CircuitPython.

I'm not super thrilled with how the chip works; I imagined that the date & time registers would act like an RTC after a successful reception, but instead they just mark the second when reception & decoding completed and are cleared to zero as soon as a new reception attempt is kicked off.

Still, I'll have to figure out a clock to put it inside. I am still thinking of doing an edge-lit display version of the Roman Solar Clock, so maybe that's where it'll go.

The library is jepler_es100.py and the example is code_es100.py (rename to code.py). I ran it on a Feather nRF52840 Expess with CircuitPython 6.3, but it should work on a range of boards.

Because the ES100 just locks up the I2C bus if you "repeated-start" it, I had to use my custom rolled register library instead of adafruit_register. I did build it on top of adafruit_bus_device.

Files currently attached to this page:

code_es100.py	1.1kB
jepler_es100.py	3.3kB

WWVB clock progress

Chris was kind enough to pass along to me a commercial WWVB receiver. This module was a bit of a pain to develop for, because most of the time the interference from a nearby laptop computer is enough to seriously compromise reception, and almost all of the time having a USB cable running from the microcontroller to the laptop will kill reception outright.

wwvbpy: WWVB timecode generator in python

Timecode for the 1998 leap second

A few weeks ago, I posted about a WWVB timecode generator written in C. Unfortunately, this timecode generator did not have a clear license permitting modification or redistribution, so I felt I was unable to incorporate it into a project of my own.

Thus was born my own timecode generator, called wwvbpy. Its primary output mode is compatible with the "wwvb2.c" that inspired it. It also has a few features that wwvb2.c didn't: automatic handling of DST, DUT1, and leap seconds. DST is handled according to the operating system's rules for Denver. DUT1 and leap seconds are handled using data from IERS (As a result, my program's DUT1 does not exactly match past broadcast data on WWVB, as the data NIST broadcasts is "an average value for an extended range of dates").

It also has a set of tests of interesting times, such as the first and second days after a DST change, the last and last-but-one days of leap and non-leap years, a historical leap second, etc. (where possible, these test vectors were originally generated by wwvb2; however, some of the tests—such as the DST tests—had to be hand-generated, as wwvb2 couldn't generate them; besides this limitation, I also uncovered a bug in wwvb2 where non-leap years were treated as having 364 days and leap-years were treated as having 365!)

An option to output the timecode data to a serial device is contemplated but not finished; ultimately, this would work together with an Arduino/AVR firmware to produce a logic-level and/or 60kHz modulated version of the signal for testing hardware devices.

wwvbpy is covered by the GNU GPL v2+. It can be obtained from my public git repository: http://git.unpy.net/view?p=wwvbpy.git;a=summary.