This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 348a31a58171a979e8a004e88aedfbad14c67dba Author: Alan Carvalho de Assis <[email protected]> AuthorDate: Sat Nov 14 18:34:20 2026 -0300 Documentation/applications: Add gnsspps GNSS PPS clock discipline. Document the gnsspps application of nuttx-apps, which disciplines a PTP clock to the PPS output of a GNSS receiver so that NuttX boards share the GNSS time scale without a network. The page explains why the PPS is time stamped with timer input capture instead of a (zero latency) interrupt, the servo, the hardware connections, the options, how to test on the simulator and how to write a capture lower half when the PPS can only reach a GPIO. Assisted-by: Claude Code:claude-opus-5-5 Signed-off-by: Alan Carvalho de Assis <[email protected]> --- .../applications/system/gnsspps/index.rst | 259 +++++++++++++++++++++ 1 file changed, 259 insertions(+) diff --git a/Documentation/applications/system/gnsspps/index.rst b/Documentation/applications/system/gnsspps/index.rst new file mode 100644 index 00000000000..6726ad25f57 --- /dev/null +++ b/Documentation/applications/system/gnsspps/index.rst @@ -0,0 +1,259 @@ +========================================= +``gnsspps`` GNSS PPS clock discipline +========================================= + +Overview +======== + +``gnsspps`` synchronizes NuttX boards to GNSS time using the PPS (pulse per +second) output of a GNSS receiver. Each board has its own receiver (or they +share one PPS signal), and each board disciplines a local PTP clock +(``/dev/ptpX``) to the pulses. All the boards then share the UTC time scale, +to within the accuracy of the receivers' PPS, without any network. + +It complements the Ethernet PTP support (``ptpd``): PTP needs a network and a +master clock, while GNSS PPS gives every board an absolute reference directly. + +The chain is made of three parts: + +#. A PTP clock with an *external time stamp* (EXTTS) input. The PPS edge + latches the clock counter in hardware and the driver queues the time stamp + as a ``struct ptp_extts_event`` (Linux compatible ``PTP_EXTTS_REQUEST`` + API). ``CONFIG_PTP_PPS`` provides such a clock on top of a capture lower + half with a 32-bit timer, see :doc:`/os/drivers/special/ptp`. +#. ``gnsspps`` reads the time stamps. Their fractional second is the phase + error of the clock; a PI servo steers the clock frequency with + ``clock_adjtime(ADJ_FREQUENCY)`` to drive it to zero. +#. The whole seconds come from the NMEA ``RMC`` or ``ZDA`` sentences that the + receiver sends after each pulse. Without NMEA, ``gnsspps`` still locks the + phase (all boards agree on the second boundaries) and takes the seconds + from ``CLOCK_REALTIME``. + +Applications read the disciplined time with ``clock_gettime()`` on the PTP +clock. Optionally (``-r``) ``CLOCK_REALTIME`` follows the clock as well. + +.. code-block:: c + + int fd = open("/dev/ptp0", O_RDONLY); + clockid_t clk = (fd << CLOCK_SHIFT) | CLOCK_FD; + struct timespec ts; + + clock_gettime(clk, &ts); /* GNSS time, ~12 ns resolution on STM32F4 */ + +Design: how to time stamp the PPS +================================= + +The accuracy of the whole system is set by how the PPS edge is time stamped. +The possible methods on a microcontroller are, from worst to best: + +.. list-table:: + :header-rows: 1 + :widths: 30 35 35 + + * - Method + - Error sources + - Typical result (STM32F4) + * - GPIO interrupt, then ``clock_gettime(CLOCK_REALTIME)`` + - NuttX interrupt dispatch (about 2 us), critical sections and higher + priority interrupts (jitter of tens of us), and the resolution of + ``CLOCK_REALTIME``, which is one system tick (10 ms by default) unless + tickless mode is used + - 10 us to 10 ms + * - Zero latency interrupt (``CONFIG_ARCH_HIPRI_INTERRUPT``) that reads a + free running counter (e.g. DWT ``CYCCNT``) on entry + - Not masked by critical sections, but the hardware entry latency still + varies: completion of multi-cycle instructions, flash wait states and + cache misses, bus contention, tail chaining, other zero latency + interrupts. Plus the GPIO/EXTI synchronizer. The handler cannot call + the OS, so the value must be handed over through PendSV or a software + interrupt + - 50 to 200 ns jitter, more complex code + * - **Timer input capture** (``CONFIG_PTP_PPS``) + - The timer copies its counter into ``CCRx`` on the edge, in hardware. + Only quantization (one timer clock) and a constant input synchronizer + delay, which is identical on identical boards + - **11.9 ns resolution at 84 MHz, no software jitter** + +With input capture the interrupt latency does not matter at all: the edge +was already time stamped by the hardware, and the handler only has to read +``CCRx`` before the next edge, one second later. This is why the STM32 driver +uses an ordinary interrupt at the default priority. A zero latency interrupt +would add complexity (no OS calls, a PendSV hand-over) and would still be +less accurate. It is only worth considering as a fallback on a chip or board +where the PPS cannot reach a timer capture input; see +`Fallback without input capture`_. + +The same reasoning applies to the clock itself. ``CLOCK_REALTIME`` is driven +by the system tick: it is read with the resolution of one tick (10 ms by +default) unless tickless mode is used, and ``adjtime()`` only changes the +tick period (``up_adjtime()`` changes the SysTick reload, a step of about +0.6 ppm with a 10 ms tick at 168 MHz) for a limited time. The PPS clock +instead converts the 32-bit counter to nanoseconds with a 64-bit fixed point +factor, giving a frequency resolution better than 1 ppb and a read resolution +of one counter clock. That is why the GNSS time is kept in a +dedicated PTP clock and ``CLOCK_REALTIME`` only follows it. + +The servo +========= + +#. **Acquire.** Two consecutive pulses give the frequency error of the local + oscillator (the phase change in one second, in ns, is the error in ppb). + The frequency is corrected and the phase is removed with one step + (``ADJ_SETOFFSET``). +#. **Locked.** A PI controller runs on every pulse: + ``freq = I - (Kp + Ki) * offset`` and ``I -= Ki * offset``, with + ``Kp = 0.7`` and ``Ki = 0.3`` by default (the values used by linuxptp for + hardware time stamps at 1 Hz). +#. **Outliers.** When locked, an offset larger than the step threshold + (``-S``, 20 us by default) is ignored. After 4 consecutive outliers the + servo acquires again. +#. **Holdover.** If the PPS disappears the last frequency is kept, so the + clock keeps running at the GNSS-calibrated rate. When the PPS returns the + servo acquires again. +#. **Seconds.** When an NMEA time arrives less than one second after a pulse, + it is the UTC time of that pulse. If it differs from the second given by + the clock in two consecutive sentences, the clock is stepped by whole + seconds. + +Hardware +======== + +* Connect the PPS output of the receiver to a timer input capture pin (3.3 V + logic, use a level shifter for a 5 V PPS). Keep the wire short or + terminated. +* Connect the receiver TX (NMEA) to a UART RX. +* For the best agreement between boards, use the same receiver model and + firmware, and compensate the antenna cable delay (about 5 ns per metre of + coax, ``-D``). The PPS of the receiver itself is typically accurate to + 20-60 ns RMS (see its datasheet); timing receivers are better. + +STM32F4Discovery +---------------- + +The ``stm32f4discovery:gnsspps`` configuration uses the TIM5 capture +(32-bit, 84 MHz) with the PPS on **PA1** (TIM5_CH2) and the NMEA on +**USART3 RX, PB11** (``/dev/ttyS1``, 9600 baud). The console is on USART2 +(PA2/PA3). + +.. code-block:: console + + $ ./tools/configure.sh stm32f4discovery:gnsspps + $ make + +Other STM32 boards need ``CONFIG_CAPTURE_NOTIFY``, the capture of a 32-bit +timer (``CONFIG_STM32_TIM2_CAP`` or ``CONFIG_STM32_TIM5_CAP``) on channel 1 +or 2 with ``CONFIG_STM32_TIMx_CLOCK`` set to the timer clock, a +``GPIO_TIMx_CHyIN`` definition in ``board.h`` and a call to +``ptp_pps_register()`` with the lower half returned by +``stm32_cap_initialize()`` in the board bring-up. + +Usage +===== + +Example on the STM32F4Discovery, just after boot: + +.. code-block:: console + + nsh> gnsspps -s /dev/ttyS1 & + gnsspps [4:200] + gnsspps: /dev/ptp0 channel 0, NMEA from /dev/ttyS1 + gnsspps: locked, offset +292956130 ns stepped, freq -71107 ppb + gnsspps: stepping +27368958 s to NMEA time + gnsspps: rms 203 ns max 521 ns freq -71185 ppb + gnsspps: rms 95 ns max 147 ns freq -71549 ppb + +Every 16 pulses the RMS and maximum phase error and the frequency correction +are printed. ``-v`` prints every sample. + +Options: + +``-d <dev>`` + PTP clock with the PPS input (default ``CONFIG_SYSTEM_GNSSPPS_DEVPATH``, + ``/dev/ptp0``). +``-c <n>`` + External time stamp channel that receives the PPS (default 0). +``-s <tty>`` + NMEA serial port of the receiver, for the time of day. +``-b <baud>`` + Set the baud rate of the NMEA port (needs ``CONFIG_SERIAL_TERMIOS``). +``-D <ns>`` + Delay of the PPS to compensate: antenna cable, receiver, level shifter. +``-P <kp>``, ``-I <ki>`` + Servo gains. Lower gains filter the PPS jitter more and make the clock + smoother, at the cost of a slower response to temperature changes. +``-S <ns>`` + Outlier and re-acquisition threshold when locked (default 20000). +``-r`` + Keep ``CLOCK_REALTIME`` synchronized to the clock: it is stepped when the + error exceeds ``-R`` (default 1 ms) and slewed with ``adjtime()`` + otherwise. Its accuracy is limited by the resolution of + ``CLOCK_REALTIME`` (one tick unless tickless). +``-R <ns>`` + ``CLOCK_REALTIME`` step threshold. +``-n <n>`` + Exit after ``n`` pulses. +``-v`` + Print every sample. + +NSH accepts 7 arguments by default; the ``stm32f4discovery:gnsspps`` +configuration raises ``CONFIG_NSH_MAXARGUMENTS`` to 12. + +Testing on the simulator +======================== + +``CONFIG_PTP_PPS_FAKE`` registers the clock on the fake capture driver, which +simulates a counter whose oscillator has a frequency error +(``CONFIG_FAKE_CAPTURE_ERROR_PPB``) and a PPS with a jitter +(``CONFIG_FAKE_CAPTURE_JITTER_NS``), using the host time as the reference: + +.. code-block:: console + + $ ./tools/configure.sh sim:nsh + $ kconfig-tweak --enable CAPTURE --enable CAPTURE_NOTIFY --enable PTP_CLOCK \ + --enable PTP_PPS --enable FAKE_CAPTURE --enable PTP_PPS_FAKE \ + --set-val FAKE_CAPTURE_ERROR_PPB 37000 \ + --set-val FAKE_CAPTURE_JITTER_NS 20 \ + --enable CLOCK_ADJTIME --enable SYSTEM_GNSSPPS + $ make olddefconfig && make + $ ./nuttx + nsh> gnsspps -v -n 40 + +With a +37 ppm oscillator error and 20 ns of PPS jitter the servo locks in +about 10 s, measures -37.00 ppm and keeps an RMS phase error of about 13 ns, +which is the jitter of the simulated PPS. With -123 ppm and 50 ns of jitter it +measures +123.45 ppm and keeps 38 ns RMS. + +Fallback without input capture +============================== + +If the PPS can only reach a plain GPIO, a capture lower half for +``CONFIG_PTP_PPS`` can still be written with a zero latency interrupt: + +#. Use a free running counter for ``getcount()`` (for example DWT ``CYCCNT`` + or a 32-bit timer). +#. Attach the GPIO interrupt as a zero latency interrupt + (``CONFIG_ARCH_HIPRI_INTERRUPT``, ``CONFIG_ARCH_RAMVECTORS``, + ``arm_ramvec_attach()``, highest priority) whose first instruction reads the + counter and stores it in a variable, returned later by ``getcapture()``, + then pends a normal interrupt (PendSV or an unused IRQ with + ``up_trigger_irq()``). +#. In that normal interrupt call the notification callback set by + ``bind()``, which is not allowed from the zero latency handler. + +Expect 50 to 200 ns of jitter instead of one timer clock. See +:doc:`/guides/concurrency/zerolatencyinterrupts`. + +Possible improvements +===================== + +* A periodic output (``PTP_PEROUT_REQUEST``) on a timer compare channel, to + produce a PPS from the disciplined clock and measure the skew between + boards with an oscilloscope. +* Quantization error correction: u-blox receivers report the error of the + next pulse (``qErr`` in ``UBX-TIM-TP``), which removes their own + ``sawtooth`` error of a few ns to some tens of ns. +* Use the GNSS disciplined clock as the grandmaster of ``ptpd`` (clock class + 6, time source GPS) to distribute GNSS time over Ethernet to boards without + a receiver. +* External time stamp inputs on Ethernet MAC PTP clocks that have an + auxiliary snapshot input, so the PPS disciplines the MAC clock directly.
