Highlights of this release:

• there is a new PHC synchronization architecture, including a GNSS/PHC simulator (which has a CLI)
• it supports seven vendor protocols in addition to UBX
• it is evolving beyond the original PTP use case to become an alternative to gpsd for some server-side use cases, in particular it can now be used as a source of time for an NTP server (either chrony or ntpd-rs) without needing a PHC
• it has had extensive testing on a wide range of hardware

I created a discussion thread where you can ask questions, share experiences and suggest new features.

Generating samples includes the following tasks:

• pulse edge filtering: some Intel NICs generate timestamps for both edges of a pulse; in this case, we have to identify which edges are leading edges
• sample completion: the timestamp for a leading edge marks the top of a second; completing the sample means determining which second that is
• sawtooth correction: a GPS receiver can only generate a pulse on an edge of its internal clock, but there can be an offset between the edge of its internal clock and the top of the second; a timing-grade GPS receiver will output a message for each pulse giving the size of this offset; the sample then needs to be adjusted for this offset

0.1 PHC synchronization architecture

My initial implementation of PHC synchronization followed the approach of the ts2phc program, included in LinuxPTP. The approach consists of a 2-stage pipeline. The initial stage generates samples by combining timestamps from the PHC with time-of-day information from GPS messages. The samples are fed into a second stage, which uses a PI servo to adjust the phase and frequency of the PHC.

This approach evolved to add a monitoring stage to the pipeline between the sample-generation stage and the servo. This monitoring stage had a variety of responsibilities. It determined whether the PHC was in sync with GNSS time, and used this to dynamically update the PTP grandmaster’s clock quality. It also performed outlier detection using a MAD algorithm.

I found two major problems with this pipeline approach. The first problem was that each stage in the pipeline ended up maintaining its own state, but these states were not coordinated.

• the sample-generation stage had an initialization state for analyzing the intervals between edges; this was used with Intel NICs that timestamp both edges of a pulse to ensure that trailing edges were ignored
• the monitoring stage maintained state of whether the PHC was synchronized to GNSS time
• the servo stage maintained state related to deciding whether to step the PHC

This became particularly problematic for the sample-generation stage. It’s important for PHC synchronization to be as reliable as possible. I found that GPS messages were not completely reliable for determining time-of-day information. Perhaps the most common problem is that the GPS emits too many messages for the available serial bandwidth, which causes messages to be delayed or dropped. When in a synchronized state, a more reliable way is to use the PHC, since the PHC will be accurate to within a microsecond or so, but this doesn’t work at all when the PHC is not synchronized. However, the sample-generation stage doesn’t have access to the synchronization state of downstream stages. The sample-generation stage became increasingly complex over time, using ad hoc heuristics to decide whether to prefer information from the PHC or from messages.

This ties into the second main problem. I had very limited ability to test the pipeline as a whole. My main approach was to save the inputs and outputs of the sample-generation stage; I could then replay the inputs to make sure they produced the same outputs. But if the sample-generation stage was affected by the monitoring stage, this would no longer be possible.

The first problem meant that a rewrite was needed: I hadn’t decomposed the problem in the best way. And if I was going to do a rewrite, then I should solve the second problem once and for all, and that meant I needed a simulator.

The most significant open source project in the timing simulation space that I know of is Miroslav Lichvar’s clknetsim. In fact, this project is what made me realise that serious testing needed a simulator. However, clknetsim would not work for SatPulse, because it relies on being able to redirect system calls using LD_PRELOAD, but SatPulse is written in Go and on Linux Go usually produces statically linked executables; system calls are raw kernel syscalls, which do not go through a dynamic library. So that meant I needed to develop my own simulator. Also clknetsim does not handle the GPS side of things.

Simulator

The goal of the simulator is not to be perfect, but to be realistic enough to enable closed-loop testing of synchronization algorithms.

The simulator is initialized with a configuration and performs a simulation for some period of time. The simulator is driven by the progress of simulated time, which represents true time. As simulated time progresses, the simulator emits timestamps and GPS messages. It also implements a PHC interface that can be used to adjust the phase and frequency of the simulated PHC. There is a crucial feedback loop: each timestamp is measured with respect to the PHC and has to take account of any phase and frequency adjustments made through the PHC interface. Another complicating factor is that GPS messages can include sawtooth corrections for the PPS signal and these corrections have to match the timestamps being generated.

When run under a simulator, the code under test produces its normal output, but the simulator can observe the offsets between the simulated true time and the simulated PHC. It can produce a log of these offsets and also generate statistics such as the maximum offset and the Allan deviation. These statistics could only be produced in real-world testing by using a reference clock that tracks UTC with much greater accuracy than a GPS PPS signal. This would require expensive hardware such as a caesium clock or better still, a hydrogen maser; a rubidium clock would not be sufficient.

The configuration includes error models for the PHC oscillator and the GPS PPS signal. Each error model consists of a number of components that describe different sources of error, which are combined additively. For example, the PHC error model has components for white, flicker and random walk FM noise. The GPS PPS error model includes a component for sawtooth error, which is used in generating both the timestamp for the PPS edge and the sawtooth correction in the corresponding GPS message.

In Go, the error models are represented by func(t float64) float64: the return value gives the instantaneous error at simulated time t. The return value for the PHC error model is a frequency error, whereas the return value for the GPS PPS error model is a phase error. This reflects the underlying physical reality that an oscillator is a continuous process whose state at any instant is a rate, whereas a PPS signal is a discrete process whose state for each pulse is a position in time.

The error models can be derived from physical measurements made of the PHC oscillator and the GPS PPS signal. (A PHC oscillator can be measured by making the PHC output a PPS signal while free-running.) In a future post, I will go into more detail about how I made measurements and used them to derive error models.

0.2 PHC synchronization architecture

The approach in 0.2 is modal. There are three modes: reset, converging and tracking. At a high level, these modes work as follows. Reset is the initial mode: its job is to generate a single, reliable sample; it does this by collecting a batch of timestamps and GPS messages. After generating the sample, reset mode will perform a step of the PHC so as to guarantee that the PHC is close to the GNSS time. At that point, it transitions to converging mode. Its job is to aggressively adjust the frequency so as to bring the PHC into as precise as possible alignment with GNSS time. When the offsets between the PHC and timestamps are no longer decreasing, it transitions to tracking mode. Its job is to continually tweak the PHC frequency so as to keep the offsets as small as possible. It remains in tracking mode so long as the offsets indicate that the PHC is still synchronized to GNSS time. If synchronization is lost, it transitions to reset mode.

Each mode is associated with a clock quality notified to the PTP grandmaster: tracking mode is associated with a clock quality representing a synchronized state; reset and converging mode are associated with a clock quality representing an unsynchronized state.

The following table summarizes the operation of the modes.

The key point to notice in the table is that each mode performs its tasks very differently. I want to focus particularly on sample completion, which is the most fundamental part of sample generation. In production, SatPulse should be spending 99.9999% of its time in tracking mode, and in tracking mode sample completion is utterly trivial: the PHC clock will be accurate to a microsecond, so you can just round the timestamp to know which second the timestamp is for.

In contrast, sample completion in reset mode is quite elaborate. If reset mode makes the wrong choice of second, then that will persist throughout the operation of the daemon, so the implementation takes a lot of care to ensure that it is right. It collects time messages and timestamps for several seconds, and then performs multiple consistency and quality checks.

Reset mode has to correlate time messages with timestamps. For time messages, we record the monotonic time at which we read the first character of the message. But these monotonic times cannot be compared directly with the timestamps, which are in the PHC time domain. The natural way to handle this is to record the monotonic time immediately after the timestamp is read. But the Raspberry Pi CM4/CM5 ethernet PHY driver has a quirk which makes this insufficient by itself: the driver can deliver the timestamp to user space up to 0.25s after the pulse occurred. To handle this, we also record the PHC time immediately after reading the timestamp, and then adjust the post-read monotonic time by the difference between the post-read PHC time and the timestamp. We also have to account for the possibility that the PHC is fast or slow. The average interval in PHC time between successive pulses tells us how much PHC time corresponds to one second, and we use this to scale the PHC difference before using it to adjust the monotonic time.

The decomposition of responsibilities is as follows. The main implementation package is phcsync. It has a controller, which is responsible for orchestrating the modes. For each mode, there is a sample-generator and a sample-processor. The sample-generator is responsible for pulse edge filtering, sample completion and sawtooth correction; in tracking mode it uses the pulse width discovered in reset mode. The sample-processor is responsible for outlier detection, and for determining when and how to adjust the PHC and change mode; these PHC adjustments and mode changes are then performed by the controller. The sample-processors for converging and tracking mode share a PI servo implementation; in tracking mode, the servo is initialized using the PHC frequency error discovered in reset mode. The controller feeds samples from the sample-generator to the sample-processor. The controller also synthesizes missing samples and feeds them to the sample-processor. The controller notifies the PTP grandmaster for mode changes that imply a change in clock quality. Thus, as in 0.1, there is a 3-stage pipeline: sample-generator then sample-processor then controller. But the pipeline is driven by the controller, and the sample-generator and sample-processor are mode-specific.

The other implementation package is timemsg, which serves as a bridge between phcsync and the GPS subsystem. timemsg maintains a buffer of recent time-related messages from the GPS receiver. phcsync defines an interface which captures what it needs to know about time messages, and timemsg implements this. Reset mode obviously depends on this interface, but tracking mode also uses it for sawtooth corrections. This separation between phcsync and timemsg was also designed to enable timemsg to be reused for a new feature in 0.2: samples can be provided to an NTP server based on serial timing, without needing a PHC.

The benefits in terms of user-visible features of the 0.2 implementation are relatively modest. Reset mode can disambiguate leading and trailing edges even with a 50% duty cycle. PHC synchronization parameters are now fully configurable using a new [sync] section of the config file. The simulator has a CLI that can be used to tune these parameters, in particular the Kp/Ki constants for the tracking servo.

But the major wins from the new architecture are in terms of improving reliability and providing a foundation for future development. The most important missing feature at the moment is holdover: the modal architecture can accommodate this in a natural way. Sample generation has a clean and principled architecture that solves the problems this had in 0.1; in tracking mode, it does not depend on time messages and so should be more reliable. The most important aspect of the architecture is, I believe, the simulator. This solves the testability problem we had in 0.1 and improves the reliability of 0.2. But it is also crucial for future development: without a simulator, it would be very difficult to develop a reliable implementation of complex features like holdover.

More details:

abondance

ASUS S500SD desktop (Intel B660 chipset) with an Intel i5-12400 and 64 GB RAM. It has two Intel I225-T1 PCIe cards: one is connected to an internal ArduSimple simpleRTK2B M.2, which has a u-blox ZED-F9P, and the other is connected over RS232 to a BG7TBL CM55 GPSDO, which has a LEA-M8T. This supports cross-timestamping with PTM.

brie

MSI Z690I motherboard with an Intel i9-12900K and 32 GB RAM. It has an Intel E810-XXVDA4T PCIe card. GPS is a u-blox EVK-F10T connected by USB.

gubbeen

Raspberry Pi 5 with 16 GB RAM in a Geekworm X1010 expansion board with PCIe slot, which contains an Intel I210-T1. GPS is a u-blox M10050-KB (u-blox M10 standard-precision) connected to UART0.

maasdam

Minisforum MS-01 with an Intel i5-12600H and 32 GB RAM. It has an I226-T1 PCIe card. GPS is a u-blox ZED-F9T-20B in a gnss.store USB dongle. This supports cross-timestamping with PTM.

morbier

Raspberry Pi CM4 with 8 GB RAM and 32 GB eMMC, on the official IO board. GPS is a u-blox LEA-M8F on a Timebeat sandwich board.

pecorino

Raspberry Pi CM4 with 8 GB RAM and 32 GB eMMC, on the official IO board. GPS is a u-blox LEA-6T connected to UART3.

roquefort

Raspberry Pi CM4 with 4 GB RAM and 8 GB eMMC, on a Waveshare PoE board. GPS is a u-blox EVK-X20P connected by USB.

serpa

Raspberry Pi CM5 with 2 GB RAM and NVMe SSD, on a Geekworm X1500 carrier board. GPS is a Unicore UM980 connected to UART0.

taleggio

Raspberry Pi 5 with 4 GB RAM with a Timebeat TimeHAT, which uses an Intel I226-LM. GPS is a u-blox NEO-M9N in the TimeHAT’s M.2 slot.

valencay

Raspberry Pi CM5 with 2 GB RAM and 16 GB eMMC, on the official IO board. GPS is a u-blox LEA-M8T connected to UART0.

valtellina

Raspberry Pi CM5 Lite with 8 GB RAM and NVMe SSD, on the official IO board. GPS is a u-blox NEO-F10N connected to UART0.

wensleydale

Raspberry Pi CM4 with 8 GB RAM and 8 GB eMMC, on the official IO board. GPS is a Unicore UM960 connected to UART0.

The testing uses the Ansible playbooks in the systest directory. It runs both satpulsed and chrony on the target machines, with satpulsed supplying samples for chrony. The main checks are that

• satpulsed logs show that synchronization has been established and not lost; and
• chrony has selected the satpulsed refclock; chrony is also configured to use highly-accurate NTP servers on the LAN, and won’t select the satpulsed refclock if it diverges too much from those NTP servers.

It also uses the clocklog.py script to produce some statistics from the clock.log about the quality of synchronization.

I also have a Grafana dashboard which shows metrics from each test machine.

This is a native app running on macOS. It uses the same GPS library that satpulsed and satpulsetool use. The code is on the desktop-gui branch of the repo.

It uses a tabbed layout, with tabs for:

• monitoring - this is conceptually quite similar to what the Web monitoring app does, but has a richer set of components
• log-level monitoring - this is similar to what you get with the packet log in satpulsetool or with the --packet-log option in satpulsed; but instead of giving a stream of packets, it groups packets by protocol and message ID; it also allows decoding of packets similar to what is provided by satpulsetool decode
• high-level configuration - this allows you to configure the GPS receiver in a high-level, device-independent way, without needing any knowledge of the receiver protocol, similar to satpulsetool gps
• low-level configuration - this uses message files to provide a lower-level device-dependent way, similar to -m and -t options of satpulsetool gps
• corrections - this allows you to pull RTCM corrections from an NTRIP caster or TCP server and feed them to the receiver, with a live view of the corrections stream; I plan to provide this functionality in a future release of satpulsed using a [stream.pull] section in the configuration file

This is built using Wails, which supports Linux and Windows, as well as macOS. But my initial testing has focused on macOS, partly because that’s what I use day-to-day for desktop work, and partly because there’s a gap on macOS, since GNSS vendors provide their proprietary apps only for Windows.

This is still very much in the preview phase: some aspects of the UI are rough, particularly the monitoring tab. With Wails, the UI is written using standard Web technologies (HTML, CSS and JavaScript), which run in the platform’s native webview component. The desktop GUI and the satpulsed Web monitoring app are both written using Preact and Tailwind CSS; this should make it possible in the future for the monitoring tab to share Preact components with satpulsed.

Why bother with writing a GUI at all? I developed the device-independent configuration approach to give the best possible user experience for satpulsed. But it turned out to be a lot more engineering effort than I anticipated. And to be honest, from the point of view of satpulsed, it doesn’t really earn its keep: the added benefit to users is too small to justify the effort that went into it. I added satpulsetool to help unlock the value of device-independent configuration to a wider audience. But satpulsetool can’t fully do this. Most users only have one GNSS receiver, so the value to users of this configuration model isn’t so much that it’s device-independent, but that it avoids requiring the user to know anything about the receiver’s native protocol; and the kind of user that benefits most from this is a non-technical user, who will want a GUI not a CLI.

At the moment, support for GPS receivers in Linux is almost universally based on GPSd. In this post I want to explain some key design choices I made for SatPulse that are different from those made by GPSd. My goal is to help people understand when it might be worth considering SatPulse as an alternative to GPSd. I want to emphasize that SatPulse is not attempting to be a replacement for GPSd. GPSd does what it sets out to do very well, as evidenced by its popularity.

TL;DR: Consider SatPulse for server-side use of a GPS receiver, or when GPS receiver configuration is needed.

Let me start by giving a brief overview of how GPSd works. For a fuller description, see the GPSd chapter from the Architecture of Open Source Applications book. GPSd is both a daemon, written in C, and a suite of related tools. It is centered around a device-independent data model of the information provided by periodic messages emitted by GPS receivers. A single instance of the daemon acts as a multiplexer. Streams of messages are read from multiple sources such as serial devices, converted to the device-independent data model and provided to multiple clients. GPSd’s primary API is a service API: a client runs as a separate process and interacts with GPSd over a TCP socket using a JSON protocol; it also provides a client library API that wraps the service API. In the GPSd architecture, the daemon does not perform application-level work on the data; its role is restricted to multiplexing and conversion into the device-independent data model. GPSd has a zero-configuration philosophy: when a user plugs in a GPS receiver, a GPSd client should work without requiring the user to perform any configuration. GPSd provides only a very limited device-independent abstraction for GPS receiver configuration; most importantly it has the concept of enabling a binary mode, which configures the receiver to output messages using its vendor-specific binary protocol instead of NMEA. Instead it provides a separate Python program, ubxtool, for configuring u-blox receivers using the UBX protocol.

Like GPSd, SatPulse is also both a daemon and a suite of related tools, and it is also centered around a similar device-independent data model. SatPulse is written in Go. Its codebase is comparable in size to GPSd’s. SatPulse compiles into two executables: satpulsed, which is a daemon, and satpulsetool, which is a command line tool. All the application-level functionality that SatPulse provides is included in satpulsed or satpulsetool depending on whether that functionality needs to work as a daemon or not. The daemon is configured using a file in TOML syntax. One instance of the daemon runs for each device to which a receiver is attached. This allows each instance to have its own configuration file, and for systemd to manage the daemon lifecycle. SatPulse does not attempt to discover GPS receivers: it opens a serial device only when explicitly configured to do so. The configuration file has a modular structure, with separate TOML tables to configure each aspect of application-level functionality. The second executable, satpulsetool, is a suite of command-line tools. It uses a subcommand syntax, so for example satpulsetool gps runs the gps tool. These separate tools are bundled into a single executable because the Go language has a runtime that makes executables quite large. The GPS subsystem of SatPulse is structured as a reusable library of Go packages. Both satpulsed and satpulsetool use this library for their GPS-related functionality: satpulsetool does not need satpulsed to be running.

The most significant GPS functionality in SatPulse that goes beyond what GPSd provides is support for GPS receiver configuration. For basic GPS usage, the factory default configuration is often sufficient. But modern GPS receivers even at modest price points have started to offer more advanced features, such as RTK, PPP-HAS or OSNMA, which typically require some configuration to be used. SatPulse provides a device-independent abstraction for GPS receiver configuration. This allows you to choose which specific aspects of the configuration should be changed. So, for example, you can specify that a time pulse should be enabled with a specific pulse width, that the time pulse should be enabled only when the receiver has a lock, and that it should be aligned to the system time of a particular GNSS; or you can specify that the receiver should operate in time mode with specific fixed ECEF coordinates. The changes to be made are given to the configuration engine which figures out how to apply them to a specific receiver. This often involves reading the existing configuration of the receiver, so that only the specified aspects of the configuration are changed. An important part of configuring a GPS receiver is enabling the right set of periodic messages. Each receiver divides up information in different ways. So instead of specifying particular named device-dependent messages (e.g. UBX-NAV-PVT), you specify the needed information in data-model terms (e.g. the time in UTC and position in geodetic coordinates). The engine then enables the best set of messages that provide this information. The configuration engine is part of the library and is used both by satpulsed and satpulsetool. Having satpulsed perform receiver configuration works well because it can infer some aspects of receiver configuration from the application-level configuration. For example, if the configuration file specifies a PHC to be disciplined, then the daemon will ensure a 1PPS time pulse is enabled. But configuration changes that affect the receiver’s non-volatile memory or interrupt receiver operation (such as changing the enabled GNSS constellations) are only done when specifically requested by the user with satpulsetool. Implementing device-independent configuration is significantly more complex than implementing the device-independent data model for periodic messages. In the Go package that implements the device-independent abstractions for the u-blox UBX protocol, about 70% of the code is devoted to configuration. SatPulse also provides an alternative lower-level approach to configuration, which is less challenging to implement: see this blog post for more detail.

The device-independent data model provided by the GPS subsystem can be serialized as JSON. The daemon uses this for its Web dashboard feature. It includes an HTTP server with an endpoint that exposes this data model as JSON-encoded server-sent events (SSE). Another endpoint serves an HTML page which uses JavaScript to connect to the SSE endpoint and display a dashboard. The daemon does not yet expose this data model over a network socket for consumption by third-party applications. This will be straightforward to do, but I want to stabilize the data model first.

However, SatPulse emphasizes a different approach to allowing multiple independent applications to share access to a single receiver, based on providing network access to packet streams. The daemon can be configured to make TCP ports or Unix domain sockets proxy the packets emitted by the receiver, optionally filtering packets by protocol, and optionally also allowing writing to the receiver, with a configurable locking strategy to prevent conflicts between writers. This provides functionality similar to ser2net, but is protocol-aware. Streams of native-protocol packets are already a well-defined wire-format. Exposing this directly on a network endpoint allows receiver sharing without the need to define a new daemon-dependent wire-format. Many applications already exist that can work with such packet streams. Here are three examples.

1. Every vendor that I know of provides an application for configuring their receivers, typically Windows-only. Many of these applications, notably u-center, allow the receiver to be accessed over a TCP socket. These can be used with SatPulse by taking advantage of the read-write feature.
2. IANA has registered the service name nmea-0183 and port 10110 for NMEA over TCP or UDP. GeoClue is a D-Bus service that provides location information. It includes an NMEA backend that uses DNS-based service discovery (RFC 6763 as implemented by Avahi) to discover nmea-0183 services on the network. SatPulse can be configured to expose the NMEA service on port 10110, Avahi can be configured to advertise it and then the GeoClue NMEA backend can discover it and expose it to desktop apps over D-Bus.
3. RTK works by providing the rover’s receiver with a stream of RTCM packets emitted by a base station’s receiver. In a production environment, NTRIP is typically used to move packets from a base to a rover. An RTK base station uses a NTRIP server to provide RTCM packets to an NTRIP caster; an RTK rover uses an NTRIP client to get RTCM packets from the caster. NTRIP support is planned for a future release of SatPulse. But one popular open-source caster, the BKG NtripCaster can pull RTCM data from a TCP port without using NTRIP. This allows SatPulse to be used today as the GPS component of a combined RTK and time server.

We can summarize the key design choices for SatPulse that are different from GPSd as follows:

1. it is written in Go
2. the primary GPS API is a library API
3. the daemon does application-level work
4. the daemon has a configuration file
5. the daemon has a separately configured instance per receiver
6. it provides a device-independent model for GPS configuration
7. it emphasizes packet streams as a foundational layer

So why did I make these choices? They were not independent. The initial PTP use case requires a daemon to do substantial application-level work: it uses timestamp events from the Linux PHC subsystem in combination with messages from the GPS receiver to discipline the PHC and send metadata updates to the PTP daemon. I didn’t want this use case to require two independent daemons. Once the daemon is doing application-level work, then there needs to be a way to configure it. Having one daemon instance per serial device makes things straightforward: each instance can have its own configuration file and systemd can ensure that the daemon is not started until the serial device is ready.

Even with the initial PTP use case, the daemon has significant internal concurrency: reading from the serial device, reading timestamp events, and updating the PTP daemon are naturally concurrent with the main PHC-disciplining loop. Other features like packet proxying or HTTP monitoring involve additional concurrency. I would not attempt implementing a daemon with this level of concurrency except in a modern language like Go, which is memory safe and has language support for concurrency. The implementation of satpulsetool also uses concurrency, although to a lesser extent than satpulsed. Go makes it relatively straightforward to have a library that supports concurrency in a flexible way.

I hope this post has made it clear that GPSd and SatPulse are very different programs, which have made different design choices for good reasons. SatPulse would not be a suitable replacement for many uses of GPSd. But I think there are several use-cases, particularly on the server side, where SatPulse’s more integrated approach and support for GPS configuration offers significant advantages.

In this post, I will explain how to do this, using two different NTP servers: chrony and ntpd-rs.

Hardware

Before we get into the details of configuration, let me say something about GPS hardware. When using a Raspberry Pi, the PPS signal is connected to a GPIO pin on the Pi. This means that the time of the PPS edge is measured in software by the kernel, rather than in hardware. The accuracy you will get is in the microsecond range. Basic GPS receivers can achieve an accuracy of 50ns in normal conditions. So my main hardware advice is that in this context a fancy, expensive GPS receiver will not deliver any measurable benefit.

GPS receivers are available in a Pi HAT form factor, which plugs into the 40-pin GPIO header. These HATs typically wire the GPS PPS signal to pin 12 (GPIO 18). I do not recommend these when using PHC hardware, because the GPS PPS signal needs to be wired to the SYNC_OUT pin on a different header. But when using a normal Raspberry Pi, they are very convenient, although you typically pay a premium for this convenience.

Setup

The following steps can be done exactly as described in SatPulse Setup Guide.

1. Install Raspberry Pi OS
2. Configure the UART
3. Install SatPulse but choose the 0.2 pre-release
4. Verify the GPS serial connection; the device will be /dev/ttyAMA0

Configuration of kernel PPS is different. First, configure pin 12 (GPIO 18) as a PPS pin, by adding the following at the bottom of /boot/firmware/config.txt

dtoverlay=pps-gpio,gpiopin=18

Reboot after this. To verify the PPS signal is working, install pps-tools using

sudo apt install pps-tools

Then do:

sudo ppstest /dev/pps0

It should show PPS events once per second:

trying PPS source "/dev/pps0"
found PPS source "/dev/pps0"
ok, found 1 source(s), now start fetching data...
source 0 - assert 1775392263.000000336, sequence: 170178 - clear  0.000000000, sequence: 0
source 0 - assert 1775392264.000000215, sequence: 170179 - clear  0.000000000, sequence: 0
source 0 - assert 1775392264.999998780, sequence: 170180 - clear  0.000000000, sequence: 0
source 0 - assert 1775392265.999999085, sequence: 170181 - clear  0.000000000, sequence: 0

Exit with Ctrl-C.

Now you need to edit /etc/satpulse.toml. Most important point is to remove the [phc] section. All you need is this:

[serial]
device = "/dev/ttyAMA0"
# fix to match your serial device speed
speed = 9600

[gps]
config = true
vendor = "u-blox"

# Enable HTTP monitoring on port 2000
[[http]]
listen = ":2000"

[ntp]
# Use this for chrony
sock.path = "/var/run/chrony.satpulse.sock"
# Use this for ntpd-rs
# sock.path = "/run/ntpd-rs/satpulse.ttyAMA0.sock"

Uncomment the sock.path line for whichever of chrony or ntpd-rs you use.

You can now start SatPulse using

sudo systemctl start satpulse@ttyAMA0

You can point a browser at port 2000 and you should get a page showing information from the GPS receiver.

Chrony

To configure chrony, first install with

sudo apt install chrony

Then create a file /etc/chrony/conf.d/satpulse.conf with the following:

refclock PPS /dev/pps0 poll 2 lock GPS refid PPS
refclock SOCK /var/run/chrony.satpulse.sock offset 0.1 delay 0.2 refid GPS noselect

The refclock PPS line makes chrony use the kernel PPS API to read PPS samples from /dev/pps0. These are accurate but lack time-of-day information. The refclock SOCK line makes chrony read samples generated by satpulsed. These are inaccurate but include time-of-day. The offset 0.1 corrects for serial messages coming 0.1 second after the top of the second.

Chrony can use the samples from satpulsed to complete the PPS samples. Chrony can also use samples from other NTP servers to complete the samples, so if you want to check that this is really working, you should at least temporarily comment out the pool line from /etc/chrony/chrony.conf.

ntpd-rs

Ubuntu has announced plans to adopt ntpd-rs as its default NTP server, replacing chrony, primarily because of memory safety. Since SatPulse is written in Go, the combination of ntpd-rs and SatPulse provides a fully memory-safe timing stack. Like SatPulse, ntpd-rs uses TOML for its configuration files and supports Prometheus, so the combination makes for a pleasantly harmonious configuration and observability experience.

To install, download a deb file from the Releases page. You need at least version 1.7.2. (The version in Raspberry Pi OS will not work.)

Next, you will need to remove your existing NTP daemon (e.g. systemd-timesyncd or chrony):

sudo apt remove systemd-timesyncd chrony

Then install ntpd-rs

sudo dpkg -i ./ntpd-rs_1.7.2-1_arm64.deb

Now you need to set things up so that ntpd-rs can access /dev/pps0. Create a file /etc/udev/rules.d/99-ntpd-rs-pps.rules containing the line

KERNEL=="pps0", GROUP="ntpd-rs", MODE="0640"

This ensures that when /dev/pps0 is created at boot time it will have a group and permissions that enables ntpd-rs to access it. To make this take effect without booting, do

sudo udevadm control --reload
sudo udevadm trigger /dev/pps0

Now we need to configure ntpd-rs. Put the following in /etc/ntpd-rs/ntp.toml:

[observability]
log-level = "debug"
observation-path = "/var/run/ntpd-rs/observe"

[[source]]
mode = "pps"
path = "/dev/pps0"
precision = 1e-7
accuracy = 1e-6

[[source]]
mode = "sock"
precision = 1e-2
path = "/run/ntpd-rs/satpulse.ttyAMA0.sock"
accuracy = 0.2

[synchronization]
minimum-agreeing-sources = 1

[[server]]
listen = "0.0.0.0:123"

When I tried initially to get this working with version 1.7.1 of ntpd-rs, it didn’t work. I submitted an issue, and within a day one of the developers, David Venhoek, had added a feature to enable this configuration. This was included in version 1.7.2, released a few days ago. It adds the ability to specify the accuracy of sources as distinct from their precision. Accuracy means how close measurements are to true time. Precision means how much measurements vary from each other. The serial timing measurements from satpulsed are quite precise but are extremely inaccurate. Specifying a low accuracy for samples from satpulsed ensures that ntpd-rs uses the PPS samples as the primary source, and uses the satpulsed samples just to complete the PPS samples. But note that if you specify an accuracy of 0.25 or worse, you need to increase maximum-source-uncertainty from its default of 0.25.

Now you can start ntpd-rs using

sudo systemctl start ntpd-rs

You can verify it’s working by using

ntp-ctl status

The release notes have more information.

I would be grateful if you could try it out and let me know how you get on.

I created a discussion thread where you can ask questions and share experiences.

Before getting into the details of the supported modules, I want to talk about what supporting a GPS module means. All GPS modules support NMEA which provides information about navigation solutions as they are computed by the module. GPS modules also support RTCM, which is used both to consume corrections provided to the module and to provide corrections for use by other modules. Apart from that, every GPS module supports one or more vendor-specific protocols. The messages used by these protocols can be divided into two groups. The first group performs a similar function to NMEA: they are messages periodically emitted by the module to provide information about the navigation solutions computed and other aspects of the ongoing operation of the module. The second group performs configuration: these include both requests that are input to the module to query and alter configuration, and messages that are output by the module as responses to these requests. Supporting a module involves enabling SatPulse to make use of both kinds of message.

SatPulse supports vendor-specific periodic messages in the obvious way, by converting vendor-specific messages into a uniform abstraction. In the source code, this abstraction is defined by the gpsprot (GPS protocol) package. In 0.1, there were abstract messages that provide information about

• the current time in either UTC or TAI; also includes sawtooth error/quantization error and time accuracy
• the progress of a survey-in operation
• the next scheduled leap second
• satellite positions and signal strengths

In 0.2, there are additional messages that provide information about

• the characteristics of a navigation solution; this includes
  • the technique used to compute the solution (e.g. ranging code or carrier phase)
  • dimensionality of the fix i.e. 3D, 2D or time only
  • what sensors beyond GNSS contributed to the solution (e.g. INS)
  • kinds of corrections used (e.g. SBAS, RTK, PPP)
  • accuracy (position, velocity)
  • DOP in all its flavours
  • age of differential corrections
  • GNSS constellations and bands used in computing the solution
• position, in ECEF or geodetic coordinates
• velocity, in ECEF or geodetic coordinates (i.e speed and course-over-ground, or NED)

These abstract messages can be serialized as JSON, and can be seen in the event log, which also includes information about pulse edges. The messages also feed the observability subsystem, which exposes them as Prometheus metrics.

For configuration, there are now two kinds of configuration support as I described in more detail in my earlier blog.

• high-level configuration, intent-based configuration, where you describe what you want, and SatPulse turns that into the appropriate messages for the specific module
• low-level configuration, which is based on message files

High-level configuration in 0.2 provides a similar set of features as in 0.1. There are a couple of new properties that can be set:

• minimum elevation angle for satellites to be used in the navigation solution
• RTCM base ID - the reference station ID for the RTCM messages that the module generates

I have added a few features to the message file implementation since the last blog:

• the message file implementation now understands the request/response patterns of various protocols, which allows it to identify which messages from the module are responses to messages sent
• there is a file inclusion capability, which is useful for allowing model-specific message files to share messages that work across multiple vendor models

The high/low-level configuration split leads naturally to two tiers of support. In both tiers, there is

• support for generating the full range of abstract messages from the vendor-specific messages
• support for the protocol in the message file implementation

The difference is that Tier 1 provides configuration support primarily via the high-level mechanism; message files are used to supplement this to support vendor-specific features that are not exposed via high-level configuration, whereas Tier 2 uses message files to provide configuration support. For Tier 2, the provided message files use a common set of conventions for tags, which provides a degree of vendor-independence in the user interface.

SatPulse 0.1 had support only for u-blox. In 0.2, there is support for the following vendors

1. u-blox - tier 1
2. Unicore - tier 1
3. Quectel - tier 2
4. Zhongke/CASIC - tier 2
5. Allystar - tier 2
6. Techtotop/Taidou - tier 2
7. ByNav - tier 2
8. ComNav/SinoGNSS - tier 2

Apart from u-blox, these vendors are all based in China. There are other Western vendors, but they are all either much more expensive than u-blox (Septentrio, Trimble, NovAtel) or the chips are designed to be integrated into mobile phones and are not available as modules that you can buy separately (e.g. Broadcom). Septentrio has recently come down in price a bit and they also have an excellent reputation for timing, so I hope to add support for Septentrio in the future. I already have some support for NovAtel, because some Chinese vendors have adopted the NovAtel OEM 6/7 series protocol.

I have chosen which Chinese modules to support based on a number of factors:

• Are they at least dual-band? Given the low cost of dual-band modules, there are relatively few cases where single-band modules remain interesting.
• Do they have any features that are particularly interesting for precision timing and/or positioning?
• How common and popular are they on Taobao?
• Are there any Western vendors that resell them?

Taobao recently started supporting direct shipping to my country of residence, which makes using Taobao much more convenient. I have found Taobao vendors to be considerably more knowledgeable about what they are selling than AliExpress vendors. If you can buy from Taobao, I recommend it.

u-blox

SatPulse supports all u-blox modules starting from LEA-6T all the way through to ZED-X20P. I have tested it on all timing modules:

• LEA-6T
• LEA-M8T
• LEA-M8F
• ZED-F9T (both L1/L2 and L1/L5 variants)
• NEO-F10T

and on both current high-precision modules:

• ZED-F9P
• ZED-X20P

and on many standard precision modules, including:

• NEO-M9N
• M10050-KB
• NEO-F10N (which is L1/L5)

In 0.2, the improvements in u-blox support are:

• support for richer information (navigation solution characteristics, position, velocity)
• support for additional configuration properties (minimum elevation and RTCM base id)
• support for ZED-X20P

I have done much more testing on u-blox modules than on any other brand.

Unicore

There is tier 1 support for the UM980 family, which consists of

• UM980, base model, which includes support for Galileo HAS (which is promised but not yet available for u-blox ZED-X20P)
• UM981, adds INS
• UM982, adds dual antennas
• UM960, lower end version, without PPP support

These use a protocol which is similar to that used by NovAtel OEM6/7 messages. Periodic data messages have dual binary/ASCII formats; the packet formats are similar, but the binary packet format has different sync bytes. Configuration messages are ASCII lines, similar but different from NovAtel. These modules also have some undocumented support for some periodic data messages that use the same packet format as NovAtel. This includes the RANGECMPB raw message which can be used by RTKLIB to generate RINEX observation files.

In the West, these modules are distributed by ArduSimple, gnss.store and SparkFun.

SparkFun have a GitHub repo with the latest UM980 firmware.

Unicore have another range of modules UM6XX, which uses a completely different protocol, which is not yet supported.

Quectel

Quectel have a bewildering array of GNSS modules. There are two families that I find interesting and that SatPulse supports:

• LG290P family - this is Quectel’s high-end module which includes support for Galileo HAS in the most recent firmware
  • LG290P is the base model
  • LG580P is the dual antenna variant
  • LG680P is the LG290P in the 22x17mm u-blox ZED form factor
• LC29H family - this is a relatively inexpensive L1/L5 model based on the Airoha AG3335 chipset; there are several variants, of which the most interesting are:
  • LC29H(AA) is the best fit for base-station case; it can produce RTCM corrections but does not have the RTK engine that can consume them; it is supposed to get OSNMA support at some point
  • LC29H(DA) is the one that is suitable for use as an RTK rover

Quectel’s vendor specific protocol uses the NMEA proprietary extension mechanism. The NMEA sentences start with $PQTM (The P is the NMEA proprietary extension mechanism, and QTM is Quectel’s 3-letter identifier). The LG290P supports a richer set of PQTM messages than the LC29H. The LC29H also supports some NMEA proprietary sentences defined by Airoha; these start with $PAIR.

In the West, SparkFun sell an LG290P board. They also have a GitHub repo with the latest LG290P firmware.

On Taobao, a good shop to buy from is Mozi Technology/Mozihao.

Zhongke/CASIC

Zhongke Microelectronics is best known for the ATGM332D and ATGM336H series of modules. The difference between these is the form-factor: ATGM332D uses the u-blox NEO form factor, whereas the ATGM336H uses the MAX form factor. The notable feature of these modules is that they are extraordinarily cheap. The bare module (without a board) is about $1.25 on Taobao.

The vendor-specific protocol is CASIC. CAS stands for Chinese Academy of Sciences, and Zhongke in Chinese also refers to the Chinese Academy of Sciences. The CASIC protocol is UBX-like.

There are literally dozens of different versions of these modules, and there are some very significant differences between them.

The most common version is ATGM332D-5N31. These module names follow a common pattern. The ‘5’ indicates the generation of the chip used (in this case, the AT6558). ‘N’ likely stands for navigation. The ‘3’ designates which constellations are supported: 1 means GPS, 2 means BeiDou, 4 means GLONASS, and these are added together to indicate the set of constellations supported. So 3 means GPS+BeiDou and 7 means GPS+BeiDou+GLONASS. I haven’t figured out how the final digit works.

There is a more recent and less common 6 series (e.g. the ATGM332D-6N74) which adds support for Galileo. This uses the AT6668 chip. More interestingly, there is also an F8 series (e.g. ATGM332D-F8N76), which is dual-band. This uses the AT9880 chip. It is not common yet but I expect it will become common: like the rest of the ATGM332D series this is extraordinarily cheap, about $2.15 on Taobao; it seems to be the cheapest dual-band module in the world.

The 5 series use a default baud rate of 9600, whereas the 6 and F8 series use 115200. More significantly, although they all use the same packet format, the 6 and F8 series support a different set of messages. The 5 series uses NAV class messages, whereas the 6 and F8 series uses NAV2 class messages.

There is some English language documentation available for the version of CASIC that uses NAV messages; there is nothing available on the NAV2 messages. Fortunately, one of my Taobao sellers was able to supply me with a Chinese language protocol manual which describes this version of CASIC. SatPulse has support for both the NAV messages and the NAV2 messages.

As well as the low-end ATGM332D/ATGM336H modules, Zhongke also make higher-end modules designed explicitly for timing. I have the AT632-6T-30. This is similar to the 6 series of the ATGM332D, and is L1 only, but has a full set of timing features, which makes it interesting. These use a TIM2 class of message. In particular it has a TIM2-TPX message including quantization error. It is interesting to have a modern L1 timing module; u-blox have not done an L1 timing module since the LEA-M8T. One noticeable difference is that the peak-to-peak amplitude of the sawtooth error is about 6ns on the AT632 compared to 21ns on the M8T, presumably reflecting the higher clock speed of the more modern module.

Zhongke provide a GnssToolkit3 application for Windows for configuring their modules.

Allystar

I first came across Allystar because of their TAu1201 module, which has been one of the cheapest L1/L5 modules available. The StarRiver store on Taobao sell a variant of their SR1723 board with the TAU1201. This costs about $7.50. With various fees, shipping and tax to Thailand, the all-in cost is about $10.50. In the West, it will be a bit more. The TAU1201 uses their Cynosure III chip. Their latest chip is Cynosure IV, which is available in the TAU951M-P200. This is a more expensive module that also does RTK.

Allystar provide a Windows app called Satrack for working with Allystar modules.

Allystar’s binary protocol is UBX-like. They haven’t done a particularly thorough job of it. For example, the message that provides information about satellite positions and signals provides less information than is available via NMEA, and Satrack doesn’t make use of it.

Bynav

Bynav makes M20/M10 series of modules based on their own Alice 22nm SoC. They are strong in the automotive industry. I have been mainly testing with the M20, but have also tried the M10. The M21 adds an IMU on top of the M20; the M22 adds a slightly better grade of IMU. The M20D adds dual antennas. The M10 is a smaller-footprint, cheaper, lower-end version of the M20 (update rate of 10Hz vs 50Hz on the M20). They seem pretty decent for RTK.

Bynav’s vendor-specific protocol is NovAtel-style. Their binary and ASCII packet formats for periodic messages (called logs in NovAtel parlance) are exactly the same as documented by NovAtel for the OEM6/7 range. Bynav support some messages defined by NovAtel and add some messages of their own. The configuration commands are NovAtel-style, but not compatible.

In the West, they are sold by gnss.store.

ComNav/SinoGNSS

This company brands itself as ComNav Technology for Western audiences, but uses SinoGNSS for Chinese audiences. Their latest modules are the K9xx series. Base module is K901. K902 adds an IMU. K922 adds dual antennas. They all have support for Galileo HAS. These are widely available on Taobao.

The protocol documentation on the ComNav site is rather out of date. My Taobao seller gave me the current Chinese-language protocol documentation, which was from another company called Qeetek, which also advertises these modules. So I suspect these modules are actually made by Qeetek.

The situation with the protocol is very similar to Bynav. Their binary and ASCII packet formats for periodic messages are exactly the same as NovAtel. They support some messages defined by NovAtel and some of their own. The configuration commands are NovAtel-style, but not compatible. But the configuration system is not in my view well-designed. One major deficiency is that it does not allow the current configuration to be queried. Another problem is that responses to configuration commands are not designed to be machine readable: they are not wrapped in a protocol packet that allows them to be distinguished from other traffic from the module.

Apart from the weakness in the configuration protocol, I found convergence of both Galileo HAS and its BeiDou equivalent (B2b-PPP) to be flaky.

Techtotop/Taidou

I had not heard of Techtotop, known in Chinese as Taidou, until a month or so ago. They make their own GNSS silicon, but they seem to be almost completely unknown outside China.

I find them interesting because they have relatively inexpensive modules specifically designed for timing. The one I have is the T303-5D, which is an L1/L5 module. This isn’t on their web site, but I believe it is just a smaller footprint version of the T302-5D. I got this module from this shop on Taobao.

It uses a UBX-style protocol called SDBP, about which there appears to be exactly zero information available in English. My Taobao seller was able to provide a Chinese language protocol manual with full details. The quality of documentation and protocol design seem good to me: it has everything I expect of a timing module, including quantization error reporting.

Techtotop also provide the TDMonitor application for Windows, which is similar to u-center (although the UI is all Chinese).

Where SatPulse is heading

My vision for SatPulse 0.1 was quite narrow: to transfer time from a GPS module to a PTP hardware clock. But it turns out doing a really good job of that requires a complex and sophisticated GPS subsystem. The subsystem should work for GPS modules from many vendors not just from u-blox. When monitoring a timing GPS, you want rich information about the current state of GPS, including the characteristics of the navigation solution. And it turns out that getting position information from the GPS is also useful: for example, you may want to use HAS to establish the fixed position to be used in timing. If you have done the work to create a GPS subsystem that works well for timing, you have done at least 80% of the work to create a GPS subsystem that works well for a wide variety of other applications. It makes sense to do that extra work, because the market for timing is relatively small: many more people care about precision positioning than care about precision timing. So this is where I am heading with SatPulse: precision timing is still a core part of the mission; but I want to add the few extra features that are needed to make SatPulse useful for a broader range of applications, in particular precision positioning.

I have hooked this up to SatPulse’s GPS auto-configuration system (enabled with config=true in the [gps] section). So when you have an [ntp] and no [phc] section, it will configure the GPS appropriately (e.g enable a PPS, enable time mode, enable messages reporting UTC time). I think this will provide quite a nice way of running an NTP server: as well as auto-configuration, you get the other SatPulse conveniences like a Web dashboard and Prometheus metrics.

I have only tested this very lightly. I used the chrony PHC extpps option to test, since all my machines are currently set up with the PPS connected to a PHC. I used the following as the satpulsed configuration:

[serial]
device = "/dev/ttyACM0"
speed = 38400
[gps]
config = true
vendor = "u-blox"
[ntp]
sock.path = "/var/run/chrony.satpulse.clk.sock"

and then used this as my chrony configuration:

refclock PHC /dev/ptp0:extpps:pin=1 width 0.1 poll 2 lock NMEA refid PPS
refclock SOCK /var/run/chrony.satpulse.clk.sock offset 0.1 delay 0.2 refid NMEA noselect

The lock NMEA option tells chrony to use the samples from SatPulse to complete the PHC samples; the noselect option tells chrony not to use the SatPulse samples as an independent time source.

Using chrony to read the PHC like this has one advantage over using SatPulse with a [phc] section: SatPulse will adjust the phase and frequency of the PHC, which is what you want for PTP, whereas chrony will leave it free-running. This makes it easy to use the hardware-timestamping feature of chrony, which requires a free-running PHC. With SatPulse, you would need to use a virtual PHC, which I have not yet implemented support for. So using chrony like this is right now the best approach if you want NTP hardware timestamping and are not interested in PTP.

How GPS receivers communicate

To understand why this feature is useful, it helps to understand how GPS receivers work at the protocol level. There are three layers: packet format, periodic messages, and configuration.

GPS receivers communicate over a serial connection by sending and receiving a byte stream consisting of a sequence of packets. Each packet has a specific format, and the stream can mix packets in different formats. A packet format defines how to represent a message type and a type-specific structured payload as a sequence of bytes with a checksum. NMEA 0183 is the most important standard packet format. A NMEA packet is called a sentence: it starts with $ and ends with a two-character hex checksum and CR/LF. The payload is represented as comma-delimited ASCII fields. RTCM 3 is another standard packet format, used for GPS correction data such as RTK base station observations. It uses a binary encoding with a 24-bit checksum. Many vendors define their own proprietary binary packet formats. For example, u-blox defines the UBX format.

GPS receivers compute position-velocity-time (PVT) solutions periodically, typically once per second. For each solution, they output messages with the results of the solution, and other information about how the solution was computed (such as the satellites used). These messages will be represented as message types in a packet format. NMEA defines standard sentence types, such as RMC, GGA, GSV for this and all GPS receivers support them. Almost all GPS receivers can also emit other periodic messages that provide information beyond what can be expressed by standard NMEA sentences. Some GPS receivers make use of the extensibility mechanism provided by NMEA (“proprietary sentences” beginning with $P), but many others use messages in proprietary binary packet formats.

All GPS receivers provide a configuration mechanism. At a minimum they provide a way to control the speed of the serial connection and which messages are emitted. But most GPS receivers allow for many aspects of their operation to be configured, for example, which constellations they should use or the width of the PPS pulse that they should generate. For GPS configuration, it is completely vendor-dependent: there is no standard. Configuration requires communication in both directions: from host to GPS receiver and well as from GPS receiver to host. As with periodic messages, configuration uses packets. RTCM 3 messages go both from host to receiver as well as from receiver to host, so GPS receivers need to be able to deal with a mix of packet formats in the input they receive.

I have seen three different approaches to configuration.

• Configuration uses the same binary packet format used for periodic messages. UBX is the most common example of this. A few other vendors use UBX-like protocols: CASIC (Zhongke Microsystems) and Allystar
• Configuration requests (from host to receiver) use NMEA proprietary sentences; responses may be either standard NMEA TXT sentences or proprietary sentences. Quectel is one vendor that uses this approach.
• Configuration requests use plain ASCII lines (usually CRLF terminated); responses are typically some sort of ASCII packet. Septentrio and NovAtel both use this approach. Their products are both very high-end, but several Chinese vendors have adopted protocols based on NovAtel, notably Unicore, SinoGNSS (ComNav) and ByNAV, in more affordable products.

SatPulse 0.1

SatPulse 0.1 internally uses protocol-independent interfaces for all three layers, but they are implemented only for UBX.

It might seem unnecessary to have such abstraction for only one protocol, but in fact UBX has many versions which have major differences. Only the packet layer of UBX remains constant between versions. The periodic message layer has significant differences: different versions of receivers support different messages. With the configuration layer, u-blox receivers from generation 9 onwards use a completely different approach from receivers of generation 8 and earlier. The earlier generations have separate message types for each aspect of configuration. The later generation uses a single message that wraps a completely separate key-value configuration system: this allows multiple configuration changes to be performed atomically by a single message.

The fundamental idea in 0.1 is to create protocol independent representation of all the configuration that needs to be done. This representation has two parts:

• it specifies the desired values for various properties; for example, it might say that the time pulse should have a pulse width of 0.1s,
• it specifies various operations that should be performed; for example, it might say that the configuration of the receiver should be saved to non-volatile memory This representation is handed over to a protocol-specific subsystem, which does as much of what was requested as the receiver supports. It then returns the actual properties that the receiver was able to implement. For example, there is a property for the set of GNSS signals that should be enabled. If you request that L1 and L5 signals should be enabled, but the receiver only supports L1, then it will enable L1 and return a property with only L1 being enabled.

You might ask: why bother with all this? SatPulse works best if the receiver is configured in very specific ways. My goal is to provide a “just works” experience: so I want SatPulse to be able to detect what kind of receiver it is and automatically configure it so that it works optimally. SatPulse 0.1 does achieve this for a broad range of UBX receivers.

Multi-protocol support

One of my main goals for SatPulse after version 0.1 is to make it truly multi-protocol. It is one thing to design an interface to be protocol-independent. It is another thing for it to actually work well for a range of protocols. In choosing the second protocol to support, I wanted a protocol that was rich and sophisticated, completely different from UBX and has decent documentation.

I decided on the protocol implemented by the UM98x series of GPS receivers from Unicore, which is based on the NovAtel OEM 6 and 7 protocols. This is primarily designed for the RTK market, but it works well for timing also. Periodic messages (which are called logs in the NovAtel world) have dual binary/ASCII representations. Configuration requests use plain ASCII lines; responses are NMEA-like.

In implementing the configuration support for the UM98x, I substantially reworked the configuration interface. The objective is to make the protocol-specific code as simple and testable as possible. The protocol-specific code is completely deterministic and does no IO. An intermediate protocol-independent orchestration layer does IO and manages retries and timeouts.

The documented UM98x packet formats and logs are similar but distinct from the NovAtel OEM6/7 ones. But it turns out that UM98x can also be configured to generate packet formats and logs that are exactly as defined in the NovAtel documentation. These packet formats and logs are also implemented by a couple of other recent Chinese GNSS receivers (Bynav M20 and SinoGNSS K901), so I also implemented support for these.

GPS message files

The approach to configuration in 0.1 has some fundamental limitations:

• it’s a lot of work to implement configuration support
• if this work has not been done for a receiver, then SatPulse provides no help at all in configuration
• if you want to configure a receiver feature that SatPulse does not support, then again SatPulse provides no help

Most vendors provide a proprietary, but free-to-use Windows GUI app that can be used to configure their receivers. For example, u-blox provides u-center. In practice, for many configuration tasks with SatPulse 0.1, users would have to rely on these Windows apps. For users living on Linux or macOS, this is not a good situation.

The multi-protocol support is a nice addition but does not address these limitations.

In the last week, I have implemented an alternative, more pragmatic approach to configuration that tries to address these limitations. The approach is a simple one: have a file that defines messages that can be sent to the GPS receiver. There is a new -m/--msg-file option for satpulsetool gps that specifies the message definition file. This does not use the configuration abstraction at all and allows arbitrary messages to be sent to the receiver. Since the main SatPulse configuration file is TOML, I also chose TOML for the format of this definition file.

Here’s a simple example. The Unicore UM980 supports Galileo HAS, but SatPulse configuration abstraction does not yet have anything for this. To enable Galileo HAS, create a file um980-has.toml.

[[line]]
text = "CONFIG PPP ENABLE E6-HAS"
[[line]]
text = "CONFIG PPP CONVERGE 10 20"

Each [[line]] block defines a text command. Run it with:

satpulsetool gps -d /dev/ttyUSB0 -s 115200 -m um980-has.toml

This will send each line, terminated with CR/LF by default. When used in this simple way, the main problem that this solves is enabling the user to see how the GPS receiver responded to the message. Since SatPulse knows about packet formats, it can intelligently identify which packets might be responses to the message and display only those. If you use cat and stty, you have no idea how the receiver responded. If you try to use a terminal emulator, the periodic messages being continually output by the receiver (which may include binary) makes it difficult to see the responses. There is also a --packet-log option that allows you to capture all packets sent and received.

NMEA message type

The nmea message type is similar to line, but it knows about NMEA checksums. For example, this is how to configure PPS on a Quectel LG290P.

[[nmea]]
text = "PQTMCFGPPS,W,1,1,100,2,1,0"

The tool prepends $ if missing and appends the checksum automatically.

Message libraries

The message file can also be used to create a library of messages. Each message can be given a tag and a description.

[[nmea]]
text = "PQTMCFGMSGRATE,W,RMC,1"
tag = "nmea-daemon"
description = "Enable NMEA messages understood by satpulse daemon"
[[nmea]]
text = "PQTMCFGMSGRATE,W,GGA,1"
tag = "nmea-daemon"
[[nmea]]
text = "PQTMCFGMSGRATE,W,GSA,1"
tag = "nmea-daemon"
[[nmea]]
text = "PQTMCFGMSGRATE,W,GSV,1"
tag = "nmea-daemon"
[[nmea]]
text = "PQTMSAVEPAR"
tag = "save"
description = "Save configuration to NVM"

Run specific tags with -t:

satpulsetool gps -d /dev/ttyUSB0 -s 460800 -m quectel.toml -t nmea-daemon,save

The --show-tags flag lists available tags with descriptions.

satpulsetool gps -m quectel.toml --show-tags

Binary messages

Sending binary messages is a less straightforward.

You can specify the exact bytes to send. For example, with u-blox L5 receivers, there is a special command you need to send get GPS L5 signal to work. The u-blox docs give it as a hex string.

[[binary]]
hex = "B562068A0900000100000100321001DEED"
tag = "gps-l5-health"
description = "Use GPS L5 signal regardless of health status"

But usually it is not convenient to specify the full byte sequence directly.

When SatPulse has support for a binary packet format, you can use this to specify things in a more readable way. For example, let’s take the CASIC binary protocol, which is similar to UBX. SatPulse has support for the packet format layer, but does not have configuration support. There’s a CFG-TP message for controlling the time pulse. The CASIC specification describes it like this.

CFG-TP (0x06 0x03)

Payload Content

We can use this to define a message as follows:

[[casbin]]
tag = "pps-gps"
description = "Enable PPS aligned to GPS time"
class = 0x06
id = 0x03
payload.types = "U4U4U1I1U1U1R4"
payload.values = [1000000, 100000, 3, 0, 1, 0, 0.0]

Each type descriptor in the payload.types string specifies how to encode corresponding entry in payload.values. SatPulse doesn’t know about the CFG-TP message but it does know how CASIC binary packets work, and it can use this to produce the right packet from this higher-level description (the packet has two sync bytes, the payload length, the class, the message id, the payload with values in little-endian byte-order and then a checksum).

Using AI to create message libraries

I have had good success using AI to create message libraries. The workflow is:

1. convert the protocol spec from PDF into a more AI-friendly format such as Markdown
2. prompt a coding agent (e.g., Claude Code) to generate a message library, giving it:
   • the protocol spec
   • description of the message file format
   • a few examples of a message library
3. allow the agent to use satpulsetool to access the GPS receiver:
   • try a message in the message library and see whether the receiver ACKs it
   • capture output from the receiver before and after to see whether the configuration message has had the expected effect on the output (use --capture N with --packet-log to capture packets for N seconds)

Examples

The configs/gpsmsg directory in the repository has some example message libraries.