# The Cuckoo Escapement

**What the Raspberry Pi time-server guides get wrong, and the numbers to prove it.**

Docs: **[escapement.warehack.ing](https://escapement.warehack.ing)**

We built a GPS-disciplined Stratum 1 NTP server on a Raspberry Pi 4, followed the
published advice, and measured everything. Most of that advice is wrong on this
board. One piece of it is wrong on *every* board.

| Change | RMS offset |
|---|---|
| Baseline | 823 ns |
| chrony median `filter` + `prefer` on the PPS refclock | 440 ns |
| PREEMPT_RT, as the guides recommend | **2468 ns** ← *worse* |
| PREEMPT_RT + our `IRQF_NO_THREAD` patch | **199 ns** |

## The one thing worth stealing

[`kernel/0001-pps-gpio-keep-timestamp-in-hard-irq-under-PREEMPT_RT.patch`](kernel/)

PREEMPT_RT force-threads interrupt handlers. `pps-gpio` takes its timestamp
*inside* its handler. So the realtime kernel — the marquee upgrade in every guide
— puts a scheduler between the electrical edge and the clock, and triples your
jitter. Four lines fix it.

As far as we can tell this isn't applied anywhere, which means anyone running
GPIO-based PPS on a realtime kernel today is silently eating microseconds of
jitter with no reason to suspect it. chrony still says Stratum 1. Everything
still *looks* fine.

## What's here

| | |
|---|---|
| `kernel/` | The patch, and how to build it |
| `dashboard/` | The live status page (FastAPI + WebSocket, no build step) |
| `docs-site/` | The write-up — Astro / Starlight |

## n = 1

Every number here comes from one Pi 4 and one GPS module. This is a field report,
not a study. We're publishing the method alongside the results precisely so you
can check it against your own board rather than take our word for it.

---

A [Supported Systems](https://supported.systems) joint.