Package: es100-wwvb
es100-wwvbWWVB60Khz Full functionality receiver/parser for i2c bus basedES100-MODDescriptionA time and date decoder for theES100-MODWWVBreceiver.
This code implements tracking (for daytime reception) and full receive decoding (for nighttime reception).
It provides Daylight Saving information and Leap Second information, if WWVB provides it.It's written 100% in Python and tested on theRaspberry Pi4and on theRaspberry Pi Pico W(usingmicropython) with, or without an OLED display.The core ES100 library fully implements all the features described inES100 Data Sheet - Ver 0.97.InstallUse PyPi (seepackagefor details) or GitHub (seepackagefor details).Via PyPI$pipinstalles100-wwvb$The sudo version of that command may be needed in some cases. YMMVSetting boot options and permissions on Raspberry Pi (or other similar O/S's)The program requires access to the GPIO and I2C subsystems. The following provides that access.$sudoadduserpigpio;sudoadduserpii2c
Addinguser`pi' to group `gpio'...
Addinguserpitogroupgpio
Done.
Addinguser`pi' to group `i2c'...
Addinguserpitogroupi2c
Done.
$

$iduid=1000(pi)gid=1000(pi)groups=...,997(gpio),998(i2c),...
$Additionally, like all uses of theaddusercommand, the user should logout and log back in for this to take effect; however, the following step will force that action.For GPIO on a Raspberry Pi, adding this package does everything required.$sudoapt-getinstallrpi.gpio
...
$On the Raspberry Pi, theraspi-configcommand should be used to enable the I2C subsystem.
Click onInterface Optionsand thenAdvanced Options.
There you will see anI2Coption.
Enable it.
Exit.$sudoraspi-config
...
$A reboot is required via thesudo reboot nowcommand for this to take effect..NTP supportThewwvbcommand line tool provides support for setting the system time viantpd's shared memory driver.
The short instructions are:Add a shared memory server to/etc/ntp.conffile.server 127.127.28.2
fudge 127.127.28.2 time1 0.0 time2 0.0 stratum 0 refid WWVB flag4 1The.2at the end of the address tellsntpdpick a shared memory segment that's2above the base value of0x4E545030.
If you use0or1for the unit number; then the shared memory area is only readable asroot.
This is not recommended in any way; hence the reason to recommend2(or above) as those are read/write by any user.
Seehttps://www.ntp.org/documentation/drivers/driver28/for the full details.Then add--ntpd=2to the running version ofwwvb.$wwvb-v-n--ntpd=2See the section on setting location, as latency from WWVB is important to calculate correctly.See the section ofwwvb.iniconfiguration file.HardwareThis code requires aUNIVERSAL-SOLDER® Everset® ES100-MOD WWVB-BPSK Receiver Module V1.1board/chipset and antenna(s).ES100-MOD is a receiver module for the phase-modulated time signal broadcasted by the NIST radio
station WWVB near Fort Collins, Colorado, and is based on Everset® Technology’s fully
self-contained receiver-demodulator-decoder Chip ES100.Ordering fromUNIVERSAL-SOLDER, along with more information, can me found here:The chipset:EverSet ES100-MOD WWVB BPSK Phase Modulation Receiver Modulepresently at C$22.90The starter kit:EverSet ES100 WWVB BPSK Atomic Clock Starter Kitpresently at C$34.90The full Arduino-based board:Application Development Kit for EverSet ES100-MOD Atomic Clock Receiverpresently at C$59.90The starter kit is the easiest way to get up-n-running with this software.Information about the chip's reception process and operational configuration can be found viaEverset Technologies:EversetES100 Data Sheet – Ver 0.97EversetAntenna ConsiderationsEverSetES100 Energy Consumption MinimizationEverSet is a fabless IC company (based in Richardson, Texas).
UNIVERSAL-SOLDER (based in Yorkton Saskatchewan Canada) is the exclusive maker of receiver kits.[1] Image and PDF's are Copyright UNIVERSAL-SOLDER Electronics Ltd. 2016-2022. All Rights Reserved.WiringThe ES100 connections are:ES100 Pin 1 == VCC 3.6V (2.0-3.6V recommended)ES100 Pin 2 == IRQ Interrupt RequestES100 Pin 3 == SCLES100 Pin 4 == SDAES100 Pin 5 == EN EnableES100 Pin 6 == GNDIt's recommended that IRQ goes to GPIO-17 (pin 11) and EN goes to GPIO-4 (pin 7). This can be changed via command line arguments.Radio Station WWVBWWVBis located in Ft Collins Colorado USA and is operated byNIST.
To quote the website:WWVB continuously broadcasts digital time codes on a 60 kHz carrier that may serve as a stable frequency
reference traceable to the national standard at NIST. The time codes are synchronized with the 60 kHz
carrier and are broadcast continuously in two different formats at a rate of 1 bit per second using pulse
width modulation (PWM) as well as phase modulation (PM).Further readinghttps://www.nist.gov/pml/time-and-frequency-division/time-distribution/radio-station-wwvbhttps://tsapps.nist.gov/publication/get_pdf.cfm?pub_id=914904LocationTo use the service; you will need to be within receiving distance (see below) of WWVB inWWVB, 5701 CO-1, Fort Collins, Colorado 80524.It's geographic coordinates are:40.678062N, 105.046688W; however, to be be more accurate; there are two antennas as follows:North antenna coordinates:40° 40' 51.3" N, 105° 03' 00.0" W==40.680917 N, 105.050000 WSouth antenna coordinates:40° 40' 28.3" N, 105° 02' 39.5" W==40.674528 N, 105.044306 WSpeed of radio waves ...Light (or radio waves) travel at the speed of light (or close to the speed of light).
In order to know your own accurate time; you need to know the speed of the signal and the distance from the transmitter.
Speed of ground level radio waves was explained in the 1950 paperThe Speed of Radio Waves and Its Importance in Some Applicationsby R.L. Smith-Rose Department of Scientific and Industrial Research, Radio Research Station, DSIR, Slough, UK.The key number from the paper are:299,775 km/sin a vacuum299,250 km/sfor 100 Khz at ground level299,690 km/sfor cm waves299,750 km/sfor aircraft at 30,000 feet (9,800 meters)I choose299,250 km/sas that matches the WWVB configuration as close as needed.Best propagation is during nighttimeThis code calculates if the transmitter and receiver are at nighttime or not.
This could help decide if the receiver can produce a result. Very Long Wavelength signals propagate better at night.The 2014 paperWWVB Time Signal Broadcast: A New Enhanced Broadcast Format and Multi-Mode Receiver[1] provides a diagram of the potential propagation of the WWVB signal.
It's calculated for 2am (i.e. middle of night).Figure 1.Simulated coverage area for the legacy WWVB broadcast at 0800
UTC (Coordinated Universal Time) in October, where the shaded area is
the day-night boundary. The simulated coverage assumes the use of a
properly oriented antenna and the absence of interference and shielding
losses. These three assumptions are often invalid in indoor applications.[1] Lowe, J. , Liang, Y. , Eliezer, O. and Rajan, D. (2014), WWVB Time Signal Broadcast: A New Enhanced Broadcast Format and Multi-Mode Receiver, IEEE Communications Magazine, [online],https://tsapps.nist.gov/publication/get_pdf.cfm?pub_id=915289(Accessed March 5, 2023)Antenna placement and orientation is vital in order to receive a signal. Indoors with a noisy RF environment will limit reception. Have either one antenna perfectly oriented with the WWVB transmitter site; however, that means the other antenna will not receive anything. A better plan is to have the two antennas splitting the direction - that way, both antennas can work.This is my reception in California during daytime/nighttime.Clearly, my antenna placement is biased towards antenna 1. Local interference could also affect how each antenna performs.The program calculates and prints the direction to point (in degrees clockwise from North) for optimum reception.Time transmission timesNIST'sWWVB60 Khz signal broadcasts 24/7. However, during the hour cycle, the PM (Phase Modulation) signal changes as follows [1]:Every half-hour, for a duration of six minutes, the normal WWVB-PM 1-minute frames are replaced by the WWVBPM
extended-mode time code sequences. The ES100 is not capable of receiving during these six-minute intervals that
occur from HH:10 to HH:16 and HH:40 to HH:46 each hour (i.e. HH= 00, 01,…, 23).This means you should not expect to see full reception or time for 5 minutes plus 5 minutes per hour.
Presently the code does not take this into account; it just keeps trying to receive.
As power consumption isn't a prime factor for a Raspberry Pi based systems, this is not a large issue.[1] EverSetES100 Energy Consumption MinimizationSystem time vs WWVB receive timeIt is assumed that any modern-day Linux environment has a stable clock and also runs some form of NTP (Network Time Protocol) such that the system time is pretty close to the real time.
The code uses that fact to manage the tracking mode reception.Getting StartedThe package comes with a command line tool calledwwvb.
This provides a way to run the ES100 hardware in continuous mode while printing the received date and time upon a successful decode by the hardware.
There are various command options. This example shows how a location (as in Lat/Long) can be passed on the command line.$wwvb-l39.861667N,104.673056WThegreatcircledistancetoWWVB:1501.6Kmanddirectionis70.6degrees;hencelatency5.018Milliseconds...WWVB:2023-03-0412:58:22.005018+00:00WWVB:2023-03-0413:00:36.005018+00:00WWVB:2023-03-0413:05:04.005018+00:00WWVB:2023-03-0413:07:18.005018+00:00...^C$Full usage of the command line tool can be found with the--helpoption:$wwvb--helpusage:wwvb[-V|--version][-h|--help][-v|--verbose][-d|--debug][-b|--bus={0-1}][-a|--address={8-127}][-i|--irq={1-40}][-e|--en={1-40}][-l|--location=lat,long][-m|--masl={0-99999}][-n|--nighttime][-t|--tracking][-A|--antenna={0-1}][-N|--ntpd={0-255}]$The--busand--addressoptions refer to thei2cbus position for the ES100 module. These rarely change and in fact are presently unused.
The--irqand--enoptions are needed if you connect the ES100 module differently than shown above. Any available GPIO port can be used.
Note that if the lines are wired incorrectly the program will simply hang.
The--locationand--maslprovide locations and MASL (Meters Above Sea Level) information.The--locationis required as the program needs to know its accurate location in order to calculate latency. If you don't provide it, your time could be off by many milliseconds. Available formats so far are:--location37.4,-121.9--location37.363056,-121.928611--location37.363056N,121.928611WIf a location is not provided; then it defaults to my local airport:SJC(San José Mineta International Airport). This is possibly incorrect.The--nighttimeoption enables the tracking vs reception mode logic for daytime/nighttime reception.
If the flag is not used, then full reception is operating 24/7.
This flag is normally only needed in power-saving situations.The--trackingflag forces tracking reception 24/7. This will only provide second-resolution responses.The--antennaflag can force the antenna to be locked into1or2.
Without this flag, the antenna swap between each reception.The--ntpflag enables the setting of system time via NTP. See the NTP section above.Config fileThewwvbcommand will read awwvb.iniconfiguration file, either from the current directory, your home directory or/etc/wwvb.ini.
This allow setting to be stored without using command line options.
If you provide a command line option, it will override the configuration file.Here's a sample configuration file.$catwwvb.ini[WWVB]# I2C valuesbus=1address=50# GPIO pinsirq=11en=7# flags,, as needednighttime=Falsetracking=False# select where the receiver is. Add a section below to match your choice# SJC & Denver are simply examplesstation=SJC#station = Denver[DEBUG]# should you want to debug anythingdebug=Falseverbose=False[NTPD]# remove comment to connect to NTPD via shared memory on unit 2# unit = 2[SJC]# Where's our receiver?name=SanJoséMinetaInternationalAirportlocation=[37.363056,-121.928611]masl=18.9antenna=[Denver]# If we had a receiver in Colorado, this is its informationname=ColoradoStateCapitolBuildinglocation=[39.7393N,104.9848W]masl=1609antenna=$A mimimalwwvb.inifile could be:$catwwvb.ini[WWVB]station=SJC[SJC]location=[37.363056,-121.928611]masl=18.9
$If you are runingwwvbas a daemon, then the/etc/wwvb.inifile would be a better choice.Raspberry Pi Pico WThe Pico support runs without features likeNTP, it does set the RTC (Real Time Clock) on thePicobased on theWWVBtime.
At the present time, there's minimal instruction for this. See below.To run the code on aRaspberry Pi Pico Wusingmicropython, first clone the github repo.$gitclonehttps://github.com/mahtin/es100-wwvb.git
...
$Copy thees100andpicofolder and it's content to/flashon the Pico. Producing this file layout:$rshell
Connectingto/dev/cu.usbmodem1101(buffer-size512)...
TryingtoconnecttoREPLconnected
Retrievingsysname...rp2
...
/Users/martin>cp-res100/flash/
/Users/martin>cp-rpico/flash/
/Users/martin>ls-l/flash/es100/flash/pico
/flash/es100:198Mar2209:49__init__.py28509Mar2209:50es100.py4808Mar2209:49gpio_control.py4479Mar2209:50i2c_control.py

/flash/pico:259Mar2209:50board_led.py6418Mar2209:50datetime.py977Mar2209:50irq_wait_for_edge.py2764Mar2209:50logging.py254Mar2209:50main.py2028Mar2209:50wwvb_lite.py
/Users/martin>repl
EnteringREPL.UseControl-Xtoexit.
>
MicroPythonv1.19.1-966-g05bb26010on2023-03-13;RaspberryPiPicoWwithRP2040
Type"help()"formoreinformation.
>>>
>>>importflash.pico.main
WWVB:2023-03-2214:20:29.000+00:002023-03-2214:20:29.033+00:00Antenna2-0.033
WWVB:2023-03-2214:24:55.000+00:002023-03-2214:24:55.001+00:00Antenna2-0.001
...Adding an OLED display to the PicoThe code includes basic code to drive an OLED I2C display.
Presently tested with anI2C 0.96 Inch OLED I2C 128x64 Pixel Display Modulepurchased from Amazon athttps://www.amazon.com/dp/B09C5K91H7.
This code will operate silently without that display attached.
The code expects to be wired to I2Cbus0using pinsGP8&GP9(this can be changed in code).
Refer to theoled_display.pyfile for more information.The display will update the screen once a WWVB signal has been received.This software port will be expanded upon over time.Other ES100 projects foundAdditional software is out there; here are some of what I found.
I believe my code is presently the most complete code.UNIVERSAL-SOLDERhttps://universal-solder.ca/downloads/wwvb_bpsk_es100.zip(usecurl -Oto grab)Fio Cattaneo Nov 2019 - es100-wwvb-refclockhttps://github.com/fiorenzo1963/es100-wwvb-refclockKeith Greiner April 2019 - How to Receive 60 KHz Time Signals with Arduino Due and ES100 Modulehttps://sites.google.com/site/wwvbreceiverwitharduino/home?authuser=0https://sites.google.com/site/wwvbreceiverwitharduino/home/es100_starter_code_with_amendments?authuser=0Author & CopyrightCopyright (C) 2023 Martin J Levy - W6LHI/G8LHI - @mahtin -https://github.com/mahtin