Incremental convention. Cartesian payloads remain fully compatible. The
geodetic form is implemented by the DJI Wayline driver; other drivers opt in
by declaring their navigation capabilities.
Goal
Cyberwave uses one navigation lifecycle for every autonomous asset:
The command topic, action_id, commands (goto, path, stop, pause, and
resume), and status lifecycle are shared. What differs by asset is the
coordinate representation:
- Ground robots normally navigate in a Cartesian
map frame, in metres.
- GPS-native vehicles, such as a DJI aircraft executing a Wayline mission,
navigate using latitude, longitude, and altitude.
The coordinate representation must therefore be explicit in the command
payload. A driver must never infer it from the robot model or from the numeric
values.
Proposed coordinate_frame
New navigation payloads include a coordinate_frame object with a required
kind. The coordinate values themselves do not contain unit suffixes: their
units are declared once by the frame.
coordinate_frame is the single source of truth for units. Do not mix it with
field names such as latitude_deg or altitude_m.
Cartesian waypoint example
frame_id identifies the local coordinate frame. The existing navigation
anchor transform applies only to this representation.
Geodetic waypoint example
For geodetic, latitude and longitude use standard GPS/WGS84 decimal degrees.
For the first DJI implementation, altitude is measured relative to the takeoff
point. orientation.heading is clockwise from true north (0 = north,
90 = east). yaw remains accepted as a legacy input alias during migration,
but the backend publishes the canonical orientation object.
Single-target goto
goto always means “reach one target”. Cartesian drivers receive the target
in position; geodetic drivers receive it in geodetic_position:
A DJI driver expands a geodetic goto into an internal two-point Wayline: its
current GPS position followed by the requested target. It must reject the
command when its current GPS position is unavailable.
Compatibility and driver behaviour
Existing Cartesian clients and drivers remain compatible. During migration, a
payload without coordinate_frame is treated as the legacy Cartesian
representation and follows the existing frame-transform behaviour.
Drivers declare the coordinate kinds they support. A driver must reject a
command whose coordinate_frame.kind it does not support and publish a
failed response on navigate/status using the received action_id.
A geodetic payload must never be passed through a Cartesian navigation-anchor
transform. Conversely, a Cartesian payload must not be treated as GPS merely
because it targets a GPS-capable vehicle.
Orientation capabilities
capabilities.navigation.orientation tells clients which target-orientation
members a hardware profile can actually command, and which are owned by the
provider. For the DJI Mini 4 Pro Wayline profile:
This is a static hardware profile, not an availability result. The separate
Wayline probe reports whether the connected aircraft/firmware is currently
READY, NOT_SUPPORTED, or INCONCLUSIVE. A UI should expose only the
commandable fields; the driver remains the final validation boundary.
Implementation scope
Implementing this convention requires coordinated changes to the backend
navigation schema and service, driver capability metadata, and each supporting
driver. Workflow authoring is intentionally separate: a future workflow node
can select a coordinate representation based on the target driver’s declared
capabilities while continuing to use the same navigation topic and action
lifecycle.
