feat : GNSS Simulation by bnshr · Pull Request #196 · k8snetworkplumbingwg/ptp-operator

bnshr · 2026-03-16T11:03:48Z

Summary

Adds a software GNSS simulator to enable T-GM (Telco Grand Master) end-to-end testing in CI without physical GNSS receivers, Intel WPC NICs, or hardware DPLL.

Motivation / Problem

JIRA Ticket

The existing T-GM test suite (PTP_TEST_MODE=tgm) requires hardware that is unavailable in the Kind-cluster-based CI environment:

Intel E810 WPC NICs (subsystem device 000e)
Physical GNSS receivers at /dev/gnss
Hardware DPLL for clock synchronization
u-blox GPS modules controlled via ubxtool

This blocks upstream CI coverage for T-GM clock state verification, holdover scenarios, and PTP event API validation.

Solution

A new ptp-tools/gnss-sim/ Go binary generates valid NMEA sentences (GNRMC, GNGGA, GPZDA) at 1 PPS over socat virtual serial ports. It includes:

DPLL state machine — models LOCKED → HOLDOVER → FREERUN with clock class transitions (CC6 → CC7 → CC248)
HTTP control API — /api/signal/loss and /api/signal/restore replace ubxtool commands for test orchestration
socat PTY integration — ts2phc reads from /dev/ttyGNSS_TS2PHC as if it were a real GNSS device

A new test mode PTP_TEST_MODE=tgm-sim activates the simulation. WPC NIC detection functions are mocked at the test helper level so CreatePtpConfigWPCGrandMaster() — the real config creation path — runs unchanged. The only conditional is skipping the E810 plugin (pin maps, ubxtool) since netdevsim has no Intel ICE driver.

Technical Details

Architecture decision — mock detection, not config creation:
Rather than creating a separate sim-specific config function, the detection layer (getWPCEnabledIfaces, checkGNSSAvailabilityForIface) returns simulated data when IsSimulatedTGM() is true. This keeps the config creation path identical to production. L2 discovery is bypassed because netdevsim interfaces cannot satisfy the solver's StepIsWPCNic constraint.

Key files:

Area	Files
Simulator	`ptp-tools/gnss-sim/` — main, nmea, simulator, dpll, api, entrypoint, unit tests
Container	`ptp-tools/Dockerfile.gnss-sim`, `scripts/configGNSS.sh`
Detection mock	`test/pkg/ptphelper/ptphelper.go`
Config path	`test/pkg/testconfig/testconfig.go`
Conformance tests	`test/conformance/serial/ptp.go` — 3 new contexts (verification, signal loss, CloudEvents v2)
CI pipeline	`scripts/run-on-vm.sh`, `scripts/run-tests.sh`, `ptp-tools/Makefile`

Breaking changes: None. All changes are additive; existing test modes are unaffected.

New dependencies: None. The simulator is a standalone Go binary; the only runtime dependency is socat (installed in the container image).

Testing

Unit tests: 17/17 pass — NMEA generation, checksum integrity, DPLL state transitions, PPS status
make fmt + go vet: clean
Ginkgo dry-run: 5 simulated T-GM specs compile and are discoverable via --focus=".*Simulated T-GM.*"
Full e2e: requires Kind cluster with netdevsim; run with PTP_TEST_MODE=tgm-sim

Risks / Considerations

Reviewers should pay attention to:

ptphelper.go detection mocks — getWPCEnabledIfaces() and checkGNSSAvailabilityForIface() have early-return branches when IsSimulatedTGM(). Verify these don't affect real tgm mode (they are gated on PTP_TEST_MODE=tgm-sim only).
E810 plugin skip — CreatePtpConfigWPCGrandMaster() passes nil plugins in sim mode. Confirm this doesn't break createConfigWithTs2PhcAndPlugins() when plugins are nil.
gpsd/gpspipe exclusion — the simulated environment intentionally skips these processes since gnss-sim writes directly to the PTY. The sim-aware tests check only ts2phc, phc2sys, and ptp4l.

Reviewer Checklist

Assisted-by AI tool

gemini-code-assist · 2026-03-16T11:04:17Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the testing capabilities for Telco Grand Master (T-GM) clock functionality by introducing a software-based GNSS simulator. This simulator generates NMEA data and provides an API to control signal states, enabling comprehensive and repeatable validation of PTP daemon behavior, DPLL transitions, and event handling in CI environments without reliance on physical GNSS hardware. The changes include new Go application code, Dockerfile, build system integration, and extensive new test suites to leverage this simulation, ultimately improving the reliability and efficiency of T-GM related test cycles.

Highlights

GNSS Simulator Introduction: Introduced a new Go-based GNSS simulator (gnss-sim) designed to generate NMEA sentences and simulate GNSS signal behavior, crucial for testing Telco Grand Master (T-GM) clock functionality.
Containerization and CI Integration: Developed a dedicated Dockerfile (Dockerfile.gnss-sim) to containerize the GNSS simulator, integrating it into the Makefile and enabling its deployment within CI environments.
Simulated T-GM Test Mode: Added a new tgm-sim test mode to run-tests.sh and updated PTP configuration logic to support TelcoGrandMasterSimClock, allowing for execution of simulated T-GM tests without physical hardware.
API for Signal Control: Implemented an HTTP API within gnss-sim that allows test scripts to programmatically trigger GNSS signal loss and restoration, mimicking real-world scenarios for robust testing.
Enhanced Test Coverage: Added extensive test cases in test/conformance/serial/ptp.go to verify T-GM clock states, DPLL transitions (LOCKED, HOLDOVER, FREERUN), and event handling under simulated GNSS conditions.
Cleanup of Obsolete Tool: Removed the ptpmg Dockerfile, streamlining the ptp-tools directory by eliminating an apparently obsolete or refactored component.

Changelog

ptp-tools/Dockerfile.gnss-sim
- Added a new Dockerfile to build and run the gnss-sim Go application, including socat for PTY pair creation.
ptp-tools/Dockerfile.krp
- Removed a trailing newline character.
ptp-tools/Dockerfile.lptpd
- Removed a trailing newline character.
ptp-tools/Dockerfile.openvswitch
- Removed a trailing newline character.
ptp-tools/Dockerfile.ptpmg
- Removed the Dockerfile for the ptpmg tool.
ptp-tools/Makefile
- Added gnss-sim to the VALUES variable, enabling its build via podman-buildall.
ptp-tools/gnss-sim/api.go
- Added Go code defining the HTTP API for the GNSS simulator, allowing external control over simulation state.
ptp-tools/gnss-sim/dpll.go
- Added Go code implementing the DPLL (Digital Phase-Locked Loop) state machine simulator, modeling LOCKED, HOLDOVER, and FREERUN states.
ptp-tools/gnss-sim/dpll_test.go
- Added Go unit tests for the DPLL simulator's state transitions and status reporting.
ptp-tools/gnss-sim/entrypoint.sh
- Added a shell script to set up socat PTY pairs and launch the gnss-sim application within its container.
ptp-tools/gnss-sim/go.mod
- Added the Go module definition for the gnss-sim project.
ptp-tools/gnss-sim/main.go
- Added the main Go application logic for gnss-sim, handling command-line arguments, output writers, and starting the simulator components.
ptp-tools/gnss-sim/nmea.go
- Added Go code for generating standard NMEA 0183 sentences (GNRMC, GNGGA, GPZDA) based on simulator state.
ptp-tools/gnss-sim/nmea_test.go
- Added Go unit tests for NMEA sentence generation and checksum calculation.
ptp-tools/gnss-sim/simulator.go
- Added Go code defining the core Simulator and SimState structures, managing the mutable state and NMEA sentence generation loop.
ptp-tools/scripts/customize-env.sh
- Removed a trailing newline character.
scripts/configGNSS.sh
- Added a new shell script to configure and start the gnss-sim container in the CI environment, including PTY setup and health checks.
scripts/run-on-vm.sh
- Updated the script to call configGNSS.sh for GNSS simulator setup and added tgm-sim to the test modes for run-tests.sh.
scripts/run-tests.sh
- Modified the script to include a new tgm-sim mode, which focuses Ginkgo tests on "Simulated T-GM" scenarios.
test/conformance/serial/ptp.go
- Added new Ginkgo Context blocks for "Simulated T-GM Verification Tests", "Simulated T-GM GNSS signal loss tests", and "Simulated T-GM Events verification (V2)".
- Implemented processRunningSimGM to check process status specifically for simulated T-GM environments.
- Added checkStabilityOfSimGMUsingMetrics to validate simulated T-GM stability using available metrics.
test/pkg/clean/clean.go
- Added pkg.PtpSimGrandMasterPolicyName to the list of PTP configurations to be cleaned up.
test/pkg/consts.go
- Added PtpSimGrandMasterPolicyName and TelcoGrandMasterSimClockString constants for the new simulated T-GM mode.
test/pkg/ptphelper/ptphelper.go
- Added utility functions for interacting with the gnss-sim HTTP API, including GNSSSimAPIBase, GNSSSimSignalLoss, GNSSSimSignalRestore, GNSSSimGetDPLLState, GNSSSimGetStatus, and GNSSSimIsHealthy.
- Introduced IsSimulatedTGM to check if the simulated T-GM test mode is active.
- Added GetFirstWorkerNodeName to retrieve a worker node name for simulated T-GM configuration.
test/pkg/testconfig/testconfig.go
- Added TelcoGrandMasterSimClockString and TelcoGrandMasterSimClock as new PTP modes.
- Updated StringToMode and GetDesiredConfig to recognize and handle the new simulated T-GM mode.
- Implemented PtpConfigTelcoGMSim and CreatePtpConfigSimGrandMaster to configure PTP for simulated T-GM environments, bypassing L2 discovery.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a GNSS simulator, a valuable addition for testing T-GM functionality without physical hardware. The implementation is comprehensive, including a Go-based simulator that generates NMEA sentences, a Docker container to run it, and integration into the CI test suite. The code is well-structured and includes good test coverage. I've provided a few suggestions to improve robustness and adhere to best practices, such as pinning the base Docker image version, adding graceful HTTP server shutdown, and ensuring all errors are handled.

ptp-tools/Dockerfile.gnss-sim

ptp-tools/gnss-sim/api.go

ptp-tools/gnss-sim/main.go

edcdavid

Added some comments. Please add a detailed PR description for the new feature. This feature should be integrated with l2 discovery so that any scenario using gnss or telecom GM can discover this gnss.

edcdavid · 2026-03-16T22:38:53Z

ptp-tools/scripts/customize-env.sh

              value: "$IMG_PREFIX:cep"
            - name: IMAGE_PULL_POLICY
              value: "Always"
-EOF


ptp-tools/scripts/customize-env.sh‎ and ptp-tools/scripts/getoffset.sh‎ are no longer executable, this breaks the tests

ptp-tools/Dockerfile.gnss-sim

ptp-tools/Dockerfile.ptpmg

edcdavid · 2026-03-16T23:26:21Z

test/conformance/serial/ptp.go

+		Context("Simulated T-GM Verification Tests", func() {
+			BeforeEach(func() {
+				if !ptphelper.IsSimulatedTGM() {
+					Skip("test valid only for simulated T-GM (PTP_TEST_MODE=tgm-sim)")


We should not create a new tgm-sim, the existing tgm scenario should already cover it by discovering the WPC card that provides the gnss hardware. The simulator should appear to the script as real HW so that ptp-operator performs as if on real hardware. The virtual NIC supporting gnss should have a pci ID that will make it be discovered as gnrd (supporting gnss)

feat: GNSS Simulation for T-GM

bf66971

gemini-code-assist bot reviewed Mar 16, 2026

View reviewed changes

ptp-tools/Dockerfile.gnss-sim Outdated Show resolved Hide resolved

ptp-tools/gnss-sim/api.go Outdated Show resolved Hide resolved

ptp-tools/gnss-sim/main.go Show resolved Hide resolved

bnshr force-pushed the gnss branch from 58f3b4c to bf66971 Compare March 16, 2026 11:12

Address gemini-assist review comments

180d8fa

edcdavid added the ok-to-test label Mar 16, 2026

edcdavid reviewed Mar 16, 2026

View reviewed changes

gtannous-spec added ok-to-test and removed ok-to-test labels Mar 17, 2026

Merge branch 'k8snetworkplumbingwg:main' into gnss

35324e6

github-actions bot removed the ok-to-test label Mar 18, 2026

bnshr added 2 commits March 18, 2026 13:49

Add the correct base images, compatible with other dockerfiles

f2f74a9

Resurrect ptpmg dockerfile

7fe97fb

josephdrichard added the ok-to-test label Mar 18, 2026

Address review comments

6a58d51

github-actions bot removed the ok-to-test label Mar 19, 2026

bnshr added 3 commits March 19, 2026 12:46

Merge branch 'k8snetworkplumbingwg:main' into gnss

89fe985

Remove tgm-sim mode related changed

42ebdcd

Merge branch 'main' into gnss

730348f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat : GNSS Simulation#196

feat : GNSS Simulation#196
bnshr wants to merge 9 commits intok8snetworkplumbingwg:mainfrom
bnshr:gnss

bnshr commented Mar 16, 2026 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Mar 16, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edcdavid left a comment

Uh oh!

edcdavid Mar 16, 2026

Uh oh!

Uh oh!

Uh oh!

edcdavid Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

bnshr commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation / Problem

Solution

Technical Details

Testing

Risks / Considerations

Reviewer Checklist

Uh oh!

gemini-code-assist bot commented Mar 16, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edcdavid left a comment

Choose a reason for hiding this comment

Uh oh!

edcdavid Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

edcdavid Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bnshr commented Mar 16, 2026 •

edited

Loading