feat(dialect)!: address the messages that direct a specific system

[TSC21]

Eleven of the dialect's messages order one system to act, but every message is broadcast, so none of them can say which system it's for. This PR gives them MAVLink's standard target_system and target_component, so a router delivers each one to its recipient, and says what that means for stops, gateways and acknowledgments. It settles the points raised in the RFC discussion and the gaps an adversarial review found after it, gateways first among them.

This is a definitions change and adds no capability. It lets the directives the dialect already defines name their recipient, using the two field names core MAVLink reserves for that, and pins down the rules those definitions left open. The integration behind it is in QGC, which consumes the situational-awareness messages and originates sensor tasking and nothing else, so SENSOR_TASKING is the only one of these messages it exercises. The rest of the list is covered because a definitions change should treat every directive in the dialect the same way, not because I implement them or plan to.

FIRES, SPLASH_CORRECTION, TARGET_HANDOVER, ESAD_ARMING, ESAD_CONFIG, SENSOR_TASKING, CAS_9LINE, TERMINAL_CONTROL, ENGAGEMENT_DIRECTIVE, CALL_FOR_FIRE and LOITER_MUNITION_CONTROL carry the two fields; the messages that describe the world stay broadcast. MAVLINK_M_ACK goes back to the sender of the message it acknowledges and echoes that message's time_usec, so each directive gets its own answer, and every addressed directive is acknowledged. Sending to every system is valid only for actions that stop or hold, and a receiver acts only on the stop in such a message. A stop applies to every engagement it matches, with 0xFFFF meaning all of them, ENGAGEMENT_DIRECTIVE ABORT and CHECK_FIRE are the stop every system that can engage or guide a weapon honours, and a stop always wins over an earlier start. SENSOR_TASKING, TERMINAL_CONTROL and LOITER_MUNITION_CONTROL say how each direction is addressed, a sensor tells a requester when its task is interrupted, and a DISARM applies whatever the ESAD challenge holds. ESAD_ARMING, SENSOR_TASKING and CAS_9LINE gain track_uid, and CAS_9LINE gains the sequence TERMINAL_CONTROL refers to.

Addressing only works where routers can deliver. A router forwards an addressed message only on links where it has heard the recipient, so the dialect header states the rules for that: a stop for a recipient that may be silent, under emission control or behind a receive-only link, goes to every system and selects with its own fields. A gateway to another network or protocol (UCI, VMF, Link 16, or another MAVLink network) re-originates messages, presents each far-side participant as a proxy system ID with its own HEARTBEAT, returns acknowledgments and responses to it, and only reports what the far side reported. System IDs are unique across joined networks, and routers and gateways move to the new definition along with everything else.

This breaks the wire format for twelve messages, and the stop and DISARM rules change what receivers must do. Each of the twelve changes CRC_EXTRA; FIRES, for example, generates as {53020, 124, 64, 64, 3, 40, 41} and MAVLINK_M_ACK as {53004, 167, 77, 77, 3, 24, 25}, with flag 3 telling a router where the target sits. The target fields are base fields on purpose. As extensions, a sender built from the old definition would leave them out and the receiver would read zero, which means every system. As base fields, old and new definitions drop each other's messages instead, an ABORT included, so every system, routers and gateways too, has to move to this definition together.

@mrpollo, ryanjAA has reviewed the design and the wire format, and the review follow-ups are in this push. Could you review it and merge when you're happy? Merging republishes the C library with the twelve new CRC_EXTRA values, so anything built from the current headers has to regenerate at the same time.

I ran the checks from #11 locally with mavlink 87da370 and pymavlink 19880422 on each of the thirteen commits: the dialect validates, generates C and Python with strict units and compiles at -Werror, the ID checks pass, the wire report against main lists exactly the twelve messages, and the docs site builds with no new dead links.

Assisted-by: Claude-Code:claude-opus-5-5

---

[ryanjAA]

Q1 - not an oversight. The design assumes addressing.

The MAVLink-M swarm dataflow concept specifies "Addressed TARGET_HANDOVER per target to the chosen shooter's sysid", and lists "addressed handoff" among the things the dialect already provides.

It explicitly rules out the alternative: "What is explicitly not supported is a third, unsafe pattern - broadcasting one target to everyone and letting whoever arrives strike it. That produces convergence: multiple munitions wasted on one target, and multiple armed aircraft meeting at one point in space."
So addressed delivery is a design requirement with a stated safety rationale. The gap is that it was left to the frame's source sysid - which isn't something a router can act on. That's exactly what this PR fixes.
Addressing already exists, just below system level.

store_id, effector_id and esad_id all carry "0 = all" semantics.
The dialect addresses sub-components in-band, but not the system that owns them.
Related gap, probably a separate PR: several of the same command messages can't say what they're about.

No track_uid on ESAD_ARMING, ESAD_CONFIG, SENSOR_TASKING, TERMINAL_CONTROL, CAS_9LINE.
Sharpest case: ESAD_STATE reports track_uid ("armed against track X"), but ESAD_ARMING cannot specify it - the binding is set out-of-band and then assumed to hold.

Q2 - agree with the split; ESAD_ARMING especially.

Q3 - yes, use the reserved names on MAVLINK_M_ACK.

[TSC21]

Thanks @ryanjAA, that answers all three.

Q1: that settles it. Addressing was always the design, it just was not in a place a router can act on. Good point on store_id, effector_id and esad_id as well. Those pick the device inside an aircraft, these new fields pick the aircraft, and 0 still means all at both levels.

Q2: good, the split stays as posted and TARGET_CUE stays broadcast.

Q3: I will add it to this PR. Concretely, origin_sysid becomes target_system, since it already names the system the ack has to get back to, target_component goes next to it, and ack_sysid goes away because the frame header already says who is sending. That leaves MAVLINK_M_ACK looking like COMMAND_ACK in common. Tell me if ack_sysid is there for a reason I am missing, otherwise I will push that here.

On track_uid, agreed, and I think it belongs in its own PR because it answers a different question: these fields say who has to act, track_uid says what the message is about. Your ESAD_ARMING against ESAD_STATE example is the clearest one. It hits SENSOR_TASKING too, where you cannot tell a sensor which track to watch, so a ground station ends up sending coordinates and the task cannot follow a moving target. Happy to write that one up if nobody else is on it.

So: the ack change lands here, this PR covers who has to act, and what the message is about comes separately. If that works for you, an approval once the ack commit is up and this can stop being an RFC.

[TSC21]

@ryanjAA pushed as c55620e.

MAVLINK_M_ACK carries target_system and target_component, and ack_sysid is gone because the frame header already says who is sending. It generates as {53004, 224, 69, 69, 3, 16, 17}, so a router can place it, and the payload stays at 69 bytes since two fields go in and two come out. Every other message in the dialect generates a byte-identical entry row.

I left origin_sysid alone on TRACK_IDENTITY, TARGET_CUE, PARTICIPANT_POSITION and ENGAGEMENT_DIRECTIVE. Those say who a report is about, not where it goes, so they are not the same field wearing a different name.

[ryanjAA]

@TSC21

I reviewed c55620e. The generated ACK entry is:

{53004, 224, 69, 69, 3, 16, 17}

CRC_EXTRA moves from 47 to 224, the payload remains 69 bytes, and target_system/target_component land at offsets 16 and 17. No wire-format objection.

Worth stating explicitly that the message ID and payload length are both unchanged. Offset 16 retains the same effective value, while offset 17 changes meaning from ack_sysid to target_component.CRC_EXTRA is therefore the only on-wire compatibility guard between the old and new definitions. That is correct and fail-closed, but it is not the usual case where a changed payload length makes the incompatibility obvious, and a reader will assume it is.

There is also a stronger argument for keeping the target fields in the base definition than the one in the PR body. Extension fields are excluded from CRC_EXTRA. An old sender omits them, a new receiver decodes the omission as zero, and zero targets mean broadcast. Extension-placed addressing would therefore let mixed definitions stay CRC-compatible while silently degrading to the exact behavior this PR exists to prevent. Base fields force a CRC mismatch instead. That is the case to make.

Four immediate description clarifications beloww. As currently framed, none changes the wire format. The SENSOR_TASKING question, plus the separate ENGAGEMENT_DIRECTIVE.origin_sysid question below, could reveal that a field change is warranted, which is why I would rather settle both before merge.

1. MAVLINK_M_ACK.target_system and target_component should explicitly say they are copied from the source sysid and compid in the frame header of the acknowledged message, and should not be zero. A conforming ACK has exactly one requester as its destination, and the current "0 addresses every system/component" text presents broadcast as a valid ACK construction. The current wording also leaves open the implementation mistake of copying the acknowledged message's own target fields instead of its source header.

2. SENSOR_TASKING is both a task request and a task-status response, and this PR gives it one target pair without defining how that pair is populated in each direction. Please state that a request targets the sensor or payload, while a status response targets the source sysid and compid from the request frame. Otherwise one implementation reverses the address and another echoes the request destination and routes the response back to the responder. PING documents its request/response addressing explicitly and is good precedent. This is the message you are actually shipping in QGC, so it is the one most likely to get codified before anyone notices.

Please also define the direction discriminator, presumably status = UNSPECIFIED for a task request and a nonzero status for a response, and state which task fields are meaningful or ignored in a response. Otherwise a single frame can carry both a command and a status with no normative rule for interpreting it.

3. Across the eleven newly addressed directive messages, "System that must act on this message" overstates what the field establishes. These fields select an intended recipient for routing and processing. They do not authorize the request or oblige the receiver to execute it. "SystemID of the intended recipient" and "Component ID of the intended recipient" are clearer, and target_component should be described as meaningful within a nonzero target_system.

4. ESAD_ARMING's multi-target challenge rule needs a precise receiver scope now that system-level addressing exists. A receiver can only evaluate the ESADs it owns, so I suggest:
   For each receiving system selected by target_system, if esad_id = 0, the receiver applies the command only if every local ESAD selected by store_id advertises arming_challenge_hash; otherwise that receiver rejects the command.

For target_system = 0, each receiving system evaluates that rule against its own local ESADs. That is the only enforceable reading, and it exposes an important consequence for the broadcast-policy follow-up: a broadcastARM can partially apply. One system may accept and arm while another rejects because its local selected ESAD set does not share the supplied hash. No individual target system can determine the network-wide outcome; the originator would need to aggregate per-system ACKs and/or subsequentESAD_STATE reports. The follow-up should define that response obligation explicitly.

ESAD_CONFIG has the corresponding unresolved multi-device rule and should state how its one challenge hash is validated when esad_id = 0,store_id = 0, or both.

On ENGAGEMENT_DIRECTIVE.origin_sysid: the explanation for retaining origin_sysid fits TRACK_IDENTITY, TARGET_CUE and PARTICIPANT_POSITION, where the field records provenance or the subject of a report.ENGAGEMENT_DIRECTIVE instead describes origin_sysid as the system issuing the directive, which may duplicate the frame source. I am not asking to remove it and I am not asking for ack_sysid back. Please just say which meaning is intended. If it is the logical or original issuing authority and may differ from the immediate MAVLink sender after gateway translation, that is useful and the field should say so. If it intentionally duplicates the immediate frame source so that detached audit records stay self-contained, document that rationale. Otherwise it is accidental redundancy and worth removing while the definition is still mutable.

On broadcast validity generally: the hazard predates this PR, since these messages previously had no system-level destination at all. What this PR adds is the first explicit field against which the intended policy can be stated and enforced, so it is the right moment to open the question.

Please open and link a follow-up issue defining broadcast validity per operation and direction rather than per message ID. Several of these combine fail-safe actions such as DISARM, ABORT, CHECK_FIRE and WAVE_OFF, where network-wide delivery may be intentional, with affirmative actions such as ARM, RESUME, RETARGET and CLEARED_HOT, where it is not. To make the intended policy explicit: the convergence rationale I quoted earlier applies to affirmative multi-recipient directives as well. Broadcast ARM is not intended to be valid. The follow-up should codify broadcast ARM as invalid while separately and explicitly defining which fail-safe broadcasts, such as DISARM, ABORT, CHECK_FIRE or WAVE_OFF, are permitted.

On track_uid, agreed it belongs in a separate PR. ESAD_ARMING is the sharpest case because it has no track or engagement binding, whileESAD_STATE reports the track against which the store is armed. ThenSENSOR_TASKING, which cannot reference a persistent track: task_id identifies the transaction, not the subject, so following a moving target requires continually re-tasking with fresh coordinates or an out-of-band association. Then CAS_9LINE, which carries the 9-line geometry but no sequence and no persistent cross-message identity. ESAD_CONFIG andTERMINAL_CONTROL are weaker, and TERMINAL_CONTROL.sequence already gives an engagement binding.

For #11: check_wire_compat.py currently builds its map as{m.id: (m.name, m.crc_extra)} and compares only those tuples. Please extend it to report full generated metadata for changed messages, that isCRC_EXTRA, min_length, max_length, target flags, target_system offset and target_component offset. The #11 description also still says comparison against #10 reports eleven changed messages; after c55620e it is twelve.

No wire-format objection. Once the four descriptions and the ENGAGEMENT_DIRECTIVE.origin_sysid semantics are resolved, and the broadcast-policy issue is linked, I'd say it's ready to approve.

[TSC21]

@ryanjAA thanks, it's all in 9d332b4. I checked each point against the devguide and against what mavgen generates before taking it, and they hold.

1. MAVLINK_M_ACK: target_system and target_component are the source IDs in the frame header of the acknowledged message, never that message's own targets and never 0, the way COMMAND_ACK words it.
2. SENSOR_TASKING: status MAVLINK_M_TASKING_UNSPECIFIED marks a request, which goes to the sensor. Any other status is a response, which goes back to the requester's source IDs the way a PING response does, echoes task_id and track_uid, and reports the mode in effect; receivers ignore its point-of-interest fields.
3. The target fields say "intended recipient", and target_component counts only within a nonzero target_system, which is how the devguide's routing rules read it.
4. ESAD_ARMING and ESAD_CONFIG: each receiving system applies esad_id = 0 (and store_id = 0 for config) only if every local ESAD it selects advertises the hash, and rejects it otherwise; the originator confirms each system from its ESAD_STATE. "Broadcast" is gone from the esad_id and store_id wording, so it only ever means target_system = 0.

origin_sysid on ENGAGEMENT_DIRECTIVE is provenance: the system that issued the directive, which a relay or gateway keeps. An ABORT forwarded across a gateway still says whose abort it is.

Broadcast validity is in this PR rather than a follow-up issue, per action and direction. 0 is valid only for actions that stop or hold: ABORT, CHECK_FIRE, CEASE_FIRE, DISARM, WAVE_OFF, a STANDBY sensor request, withheld or withdrawn consent, and the CHECK_FIRING, CEASE_LOADING and END_OF_MISSION calls. Anything that starts, arms, configures, grants, briefs or hands over names its recipient, and so does SELF_DESTRUCT because it can't be undone. A DISARM sent to every system still checks the hash per system, so it disarms only where the selected ESADs share it.

I folded track_uid in as well, since these messages break on the wire here anyway and consumers then take one break instead of two: ESAD_ARMING (the track ESAD_STATE reports back), SENSOR_TASKING (a task can follow a track) and CAS_9LINE, which also gets the sequence TERMINAL_CONTROL refers to. ESAD_CONFIG and TERMINAL_CONTROL get none, because one sets a device mode and the other binds through sequence.

Your base-field argument is in the first commit and the description, together with its other side: old and new definitions drop each other's ABORTs too, so every system has to move together.

For #11: the wire report prints each changed message's generated entry row, old and new, so against this PR it lists the twelve messages with rows like MAVLINK_M_ACK {53004, 47, 69, 69, 0, 0, 0} -> {53004, 224, 69, 69, 3, 16, 17}. A row that changes while CRC_EXTRA doesn't, such as a target field added as an extension, is reported separately, and #11's description says twelve.

[TSC21]

@ryanjAA one more round on top of your review. I ran an adversarial pass over this PR from four angles (MAVLink routing, tactical comms and gateways, weapons safety, operator UX), checked each finding against the devguide, mavlink-router and what mavgen generates, and the gaps it found are in 1215ede.

• Gateways and routing: the dialect header says what addressing needs from routers. A router drops an addressed message for a recipient it hasn't heard on that link, so a stop for a silent recipient goes to every system and selects with its own fields. A gateway re-originates, gives each far-side participant a proxy system ID with its own HEARTBEAT, returns acknowledgments to it and only reports what the far side reported, and system IDs are unique across joined networks. origin_sysid reads as the system that first issued the directive, kept by a system that passes it on as its own message; routers never change a frame, so my earlier "a relay keeps this value" was wrong.
• MAVLINK_M_ACK echoes the acknowledged message's time_usec in ack_time_usec, so a CHECK_FIRE and a RESUME of the same mission get different answers ({53004, 167, 77, 77, 3, 24, 25}). Every addressed directive is acknowledged, a message sent to every system by each receiver with a new NOT_APPLICABLE result where nothing is selected, and a repeat is a duplicate.
• Stops: from a message sent to every system a receiver acts only on the stop, a stop applies to every engagement it matches, 0xFFFF means all of them, ENGAGEMENT_DIRECTIVE ABORT and CHECK_FIRE are the common stop, and a stop wins over an earlier start. SENSOR_TASKING is never sent to every system, since a STANDBY would cage a designator guiding a weapon in flight, and END_OF_MISSION stays addressed.
• TERMINAL_CONTROL and LOITER_MUNITION_CONTROL say who sends what to whom, as SENSOR_TASKING does. CLEARED_HOT and a consent grant count only from the controller or authority that tasked the aircraft or munition; a stop counts from anyone.
• A DISARM applies whatever the ESAD challenge holds, so one faulted ESAD can't block the rest and a DISARM to every system works. The texts stop calling the hash authentication, since ESAD_STATE sends it to everyone; signing authenticates the sender.
• SENSOR_TASKING tells a requester when its task is interrupted.

The base-field choice stays, and the description says what it costs: across a definition boundary an ABORT is dropped too, so every system moves together.