Skip to content

Announce guidance track data (DDI 507-511, 513) to implements - #84

Open
gunicsba wants to merge 3 commits into
feature/gnss-quality-announcementfrom
feature/guidance-track-announcement
Open

gunicsba wants to merge 3 commits into
feature/gnss-quality-announcementfrom
feature/guidance-track-announcement

Conversation

@gunicsba

@gunicsba gunicsba commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Third of four PRs split out of #73. Stacked on #83 (base is feature/gnss-quality-announcement, so this diff shows only this PR's changes; GitHub retargets it to develop once #83 merges). It reuses #83's DDI-mapping loop.

Parses AOG's guidance track context (PGN 0xF4) and field name (PGN 0xF3) and pushes the current track to every client whose DDOP declares the DDIs as settable, every 250 ms while AOG has a valid track:

DDI Value
507 GuidanceTrackSequenceNumber Advances when the track number or reference line changes (a line switch can land on the same track index).
508 UniqueGuidanceReferenceLineID AOG's 16-bit ID in the low 16 bits, a persistent per-field index in the high 16 bits — unique across fields. Index comes from FieldRegistry (field_registry.csv next to settings.json).
509-511 Actual / right / left track number, with the +1 offset field testing showed implements need to stay in phase with AOG's on/off state.
512 GuidanceLineSwathWidth AOG's track spacing (tool width minus overlap, the same spacing the track numbers use) from the optional bytes 10-11 of 0xF4. Not sent when AOG omits it or reports 0, so AOG builds without the field keep working. Needs AgOpenGPS-Official/AgOpenGPS#1218, which adds the field.
513 GuidanceLineDeviation AOG's XTE.

Nothing here is gated on track-control negotiation — the TC pushes these values, so any implement that declares the DDI as settable gets it.

Things worth knowing

  • Mapping only, no OnChange subscription (same as Send GNSS quality (DDI 514) to implements #83). The tramline branch subscribed to these DDIs when the implement offered an OnChange trigger. Nothing should depend on it since the TC owns these values, but it is a difference from what was field-tested — worth checking on hardware.
  • Like the other DDI mappings, only clients with sections are considered.
  • Adds a unit test for the 0xF4 parser (sequence freshness/wrap, offset, validity, swath width, reset). test_guidance_track is made a dependency of iop_validator so the validation workflow, which only builds that target, builds it too (no workflow edit, so no conflict with Add Tractor Facilities (PGN 65033) for the TECU #82's).
  • Docs: docs/PROTOCOL.md (0xEF/0xF3/0xF4, new §5.4.1) and the readme's guidance subsection from Send GNSS quality (DDI 514) to implements #83.

Test plan

  • Release build, AOG_TC_VALIDATE_IOP=ON build with only --target iop_validator (as CI does), ctest 6/6 including guidance_track_parsing.
  • clang-format and cmake-format clean locally.
  • Real-bus check that an implement receives 507-513 and stays in phase — not run against hardware.

🤖 Generated with Claude Code

@gunicsba gunicsba added the enhancement New feature or request label Sep 19, 2026
@gunicsba gunicsba added this to the Tramlines milestone Sep 19, 2026
@gunicsba
gunicsba force-pushed the feature/guidance-track-announcement branch from 3cd61c4 to ef9fbb9 Compare September 19, 2026 22:02
@gunicsba
gunicsba added this pull request to stack #86 September 19, 2026 22:08
@gunicsba
gunicsba force-pushed the feature/guidance-track-announcement branch from ef9fbb9 to 54bfe97 Compare September 19, 2026 22:58
Parses AOG's guidance track context (PGN 0xF4) and field name (PGN 0xF3) and
pushes the current track to every client whose DDOP declares the DDIs, every
250 ms while AOG has a valid track:

- 507 GuidanceTrackSequenceNumber: advances whenever the track number or the
  reference line changes (a line switch can land on the same track index).
- 508 UniqueGuidanceReferenceLineID: AOG's 16-bit line ID in the low 16 bits and
  a persistent per-field index in the high 16 bits, so it is unique across
  fields. The index comes from FieldRegistry (field_registry.csv next to
  settings.json).
- 509-511 actual/right/left track number, with the +1 offset field testing
  showed implements need to stay in phase with AOG's on/off state.
- 512 GuidanceLineSwathWidth: AOG's track spacing (tool width minus overlap),
  read from the optional bytes 10-11 of PGN 0xF4. Not sent when AOG omits it or
  reports 0, so older AOG builds keep working.
- 513 GuidanceLineDeviation from AOG's XTE.

The DDIs are mapped in request_measurement_commands() by extending the loop
that maps GNSS quality, so, as for DDI 514, only DDIs an implement declares as
settable are mapped. Nothing is gated on track-control negotiation: the TC
pushes these values and any implement declaring them receives them.

Adds unit tests for the PGN 0xF4 parser (sequence freshness and wrap, offset,
validity, swath width). test_guidance_track is a dependency of iop_validator so the
validation workflow, which builds only that target, builds it too.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@gunicsba
gunicsba force-pushed the feature/guidance-track-announcement branch from 54bfe97 to 46fe425 Compare September 19, 2026 23:04
gunicsba and others added 2 commits September 27, 2026 16:03
…nnouncement

Resolve conflict in request_measurement_commands(): keep this branch's
generalized guidance-DDI mapping and use log() as the base branch now
does. Also switch the FieldRegistry and TRACK prints to log() to match
the async logging from #79.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
guidance_track_context.cpp now logs through log(), which needs
async_log.cpp; the standalone test target only compiled the parser, so
the IOP validation build failed to link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant