Missionitem Identity And Progress Reporting

Andi Lamprecht ·2026-05-11· 4 min read· Accepted

Title

Context

Problem

With the introduction of Click-to-Fly and thus in-flight mission replanning, the Uncrew MissionsService is having difficulties establishing when missions complete. At the time of writing this ADR, the MissionsService decides if the mission is complete upon receiving a mission progress update (in form of a PublishCurrentMissionItemRequest message from Avatar/Onboard). It does it here with this code:

func isMissionCompleted(updateIndex int, missionItems []models.MissionItem) bool {
	return updateIndex == len(missionItems)
}

That is, when the mission progress matches the number of mission items, or, shall we say, when it’s one more than all mission items.

MissionsService sometimes leaves missions in a non-completed state because it never receives that last mission item progress. Most of times it does.

A single Uncrew mission is composed of many PX4 missions. For example, a typical delivery mission uses one px4 mission to reach the delivery site and another to return from it. It does so, because “delivery” isn’t something that can be put into a PX4 mission. Meanwhile, mission progress (PublishCurrentMissionItemRequest) are reported with monotonically increasing MissionItem indices and mavlink-shim manages that maintaining an offset. Every time it uploads a new px4 mission, it updates the offset and every time it receives mission progress from px4, it adds the offset to it before publishing it as Uncrew mission progress. So far this has worked well.

However, things got complicated with the introduction of Click-to-Fly. Given the state:

When Click-to-Fly (WaypointUAVCommand) is received by mavlink-shim, it:

1. Puts the drone into hold
2. Calculates and deconflicts the path towards the Click-to-Fly destination
3. Notifies the MissionsService about the newly replaced tail-end of the mission carrying the last completed mission item index so that the MissionsService knows where to append the tail-end.
4. Uploads a new PX4 mission to the autopilot (which updates the mission item index offset)
5. Starts the PX4 mission

Somewhere in this sequence the problem is introduced and we don’t know where.

Before rushing to fix it, we note a bigger problem. We know that the mission can be changed from the outside, i.e.: AssignMission can come to a drone mid-air - for instance when discovering a new conflict. The sender has a remote and blurry view for where the drone is and what mission item it completed last. Consider the following scenarios:

Given a mission (waypointA) ——>(waypointB) and the drone somewhere between these two mission items.

Scenario 1:

• Missions Service assigns a mission replacing (waypointB) with (waypointZ) with a different waypoint
• Onboard Uncrew receives AssignMissionRequest before i reaches (waypointB)
• Onboard Uncrew abandons (waypointB) and starts aiming at (waypointZ) emitting progress that it has started on (waypointZ)
• Onboard Uncrew reaches (waypointZ) and emits progress to that effect

Scenario 2:

• Missions Service assigns a mission replacing (waypointB) with (waypointZ) with a different waypoint
• Onboard reaches (waypointB) and emits progress that it has done so
• Onboard Uncrew receives AssignMissionRequest after it reached (waypointB)
• Onboard Uncrew starts aiming at (waypointZ) emitting progress that it has started on (waypointZ)
• Onboard Uncrew reaches (waypointZ) and emits progress to that effect

If progress were emitted solely with indices,

• Scenario 1 would have seen 0, 1
• Scenario 2 would have seen 0, 1, 2

…and at index 1, Missions Service would not be able to determine whether (waypointB) or (waypointZ) was reached, which suggests we should label mission items with unique identifiers.

Adopting unique ids updates Uncrew external APIs. Working with IDs is also a bit more complex than with indices. And there is a way to get rid of the race.

Decision

When the PX4 mission upload is complete, we know that a new mission is now being executed. Additionally PX4 mission progress reports the PX4 mission id, to which the progress applies so we can distinguish progress from previous mission from that of the new mission.

When PX4 mission upload completes, in a critical section, Onboard Uncrew:

• retrieves the last reported uncrew mission progress and puts it into AssignMissionResponse
• swaps the cached PX4 mission id for the new one so that all remaining progress for the old mission, if any, shall be ignored.

Consequences

What becomes easier or more difficult to do because of this change?

Alternatives Considered

List all alternatives you’ve considered and explain briefly why did you reject it.

Formal Impact

List any systems or services that are impacted by this architectural decision.