From 3406141e81cc996846b5b74277b5f9b8951ca6b9 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 1 Jul 2026 10:39:26 +1000 Subject: [PATCH] Routing: Tidy and remove unknown component processing rule --- en/guide/routing.md | 60 ++++++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index 961705c70..3ad529c3a 100644 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -6,20 +6,16 @@ This topic explains how messages should be routed by MAVLink systems. A MAVLINK network is made up of systems (vehicles, ground stations, antenna trackers, etc.), which may be composed from one or more components (autopilot, camera, servos, etc.). -Each system has a network-unique _system id_, and each component has a system-unique _component id_ that can be used for addressing/routing: - -- The _system id_ has a value between 1 and 255. - - The default autopilot system id is usually 1. Users should allocate unique increasing id values when adding new autopilots to a network. - - GCS systems and developer APIs typically use an ID at the top of the numeric range to reduce ID clashes (e.g. 255). Often their system ID is configurable to allow multi-GCS systems. -- The _component id_ is allocated by type and number from [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT). +Each system has a network-unique _system ID_, and each component has a system-unique _component ID_ that can be used for addressing/routing. +Both are values between 1 and 255. Messages can be intended for all systems, specific systems, all components in a system, or specific components within a system. -The protocol defines two 8-bit fields that can (optionally) be specified in the message payload to indicate where the message should be sent/routed. If the ids are omitted or set to zero then the message is considered a _broadcast_ (intended for all systems/components). +The protocol defines two 8-bit fields that can (optionally) be specified in the message payload to indicate where the message should be sent/routed. If the IDs are omitted or set to zero then the message is considered a _broadcast_ (intended for all systems/components). - `target_system`: System that should execute the command - `target_component`: Component that should execute the command (requires `target_system`). -MAVLink components are expected to process messages that have a matching system/component id and broadcast messages. +MAVLink components are expected to process messages that have a matching system/component ID and broadcast messages. They are expected to route/resend messages that are intended for other (or all) recipients to other active channels (i.e. MAVLink systems may be connected across different transports, connected by a MAVLink system that routes the messages). Broadcast messages are forwarded to all channels that haven't seen the message. @@ -31,30 +27,50 @@ Forwarded messages must not be changed/repackaged by the forwarding system (the ::: ::: info -Systems should, where possible, forward messages according to the routing rules _even if they are unable to process them_ (e.g. signed messages that cannot be authenticated). Messages that are not supported/understood by the library should be forwarded as though they were broadcast messages (in this case the target system/component ids cannot be read). +Systems should, where possible, forward messages according to the routing rules _even if they are unable to process them_ (e.g. signed messages that cannot be authenticated). Messages that are not supported/understood by the library should be forwarded as though they were broadcast messages (in this case the target system/component IDs cannot be read). +::: + +## ID allocation + +MAVLink does not provide mechanisms to automate allocation of system and component IDs. +Instead these are manually allocated by the system integrator. + +In order to reduce the chance of collisions (by convention): + +- Autopilots on a MAVLink network are allocated sequentially increasing system IDs from `1` (`1` is usually the default autopilot system ID). +- GCS and MAVLink developer APIs are allocated sequentially decreasing system IDs, starting from `255`. + Note that GCS will usually, but not always, have an ID in the upper range. +- Components can be allocated any unused ID in the range. + Components usually have a default value based on their type, as mapped by [MAV_COMPONENT](../messages/common.md#MAV_COMPONENT). + +::: warning +Code **must not assume** from the component ID that it knows the type of the component. +The type of a component must be determined from its [MAV_TYPE](../messages/common.md#MAV_TYPE) ::: +Components should expose mechanisms to set their system and component IDs. +Commonly a component may be configured to discover its system ID on boot by latching the system ID of the first autopilot [HEARTBEAT](../messages/common.md#HEARTBEAT) that it discovers. + ## Routing Detail -Systems/components should process a message locally if any of these conditions hold: +A component should attempt to process a message locally if any of these conditions hold: -- It is a broadcast message (`target_system` field omitted or zero). -- The `target_system` matches its system id and `target_component` is broadcast (`target_component` omitted or zero). -- The `target_system` matches its system id and has the component's `target_component` -- The `target_system` matches its system id and the component is unknown (i.e. this component has not seen any messages on any link that have the message's `target_system`/`target_component`). +- The `target_system` field is omitted or has value `0` ("network broadcast"). +- The `target_system` matches its system ID and the `target_component` field is omitted or has value `0` ("system broadcast"). +- The `target_system` and `target_component` matches its system and component IDs. -Systems should forward messages to another link if any of these conditions hold: +Components that have multiple channels should forward a message to other channels if any of these conditions hold: -- It is a broadcast message (`target_system` field omitted or zero). -- The `target_system` does not match the system id _and_ the system knows the link of the target system (i.e. it has previously seen a message from `target_system` on the link). -- The `target_system` matches its system id and has a `target_component` field, and the system has seen a message from the `target_system`/`target_component` combination on the link. +- It is a network broadcast message (`target_system` field omitted or zero). +- The `target_system` does not match the system ID _and_ the component has previously seen a message from `target_system` on the link. +- The `target_system` matches its system ID and has a `target_component` field, and the component has seen a message from the `target_system`/`target_component` combination on the link. ::: info -Non-broadcast messages must only be sent (or forwarded) to known destinations (i.e. a system must previously have received a message from the target system/component). +Non-broadcast messages must only be forwarded to channels from which the component has previously received a message from the target system/component. ::: -::: info -Systems should also check for `SYSTEM_TIME` messages with a decrease in `time_boot_ms`, as this indicates that the system has rebooted. +::: tip +Components should also check for `SYSTEM_TIME` messages with a decrease in `time_boot_ms`, as this indicates that the system has rebooted. In this case it should clear stored routing information (and might perform other actions that are useful following a reboot - e.g. re-fetching parameters and home position etc.). ::: @@ -66,7 +82,7 @@ The generated code for the MAVLink v1 C Library has no specific support for rout To extract this information you will need to use the normal methods provided for reading payload fields, and match on the field names. The MAVLink v2 generator for the C library has been updated to make it easier to get the destination system and component ID from the payload (when these are assigned). -Specifically, the `mavlink_msg_entry_t` structure contains flags to tell you if the message contains target system/component information (`FLAG_HAVE_TARGET_SYSTEM`, `FLAG_HAVE_TARGET_COMPONENT`) and offsets into the payload that you can use to get these ids (`target_system_ofs` and `target_component_ofs`, respectively). The MAVLink helper method `const mavlink_msg_entry_t*` [`mavlink_get_msg_entry(uint32_t msgid)`](https://github.com/mavlink/c_library_v2/blob/master/mavlink_helpers.h) can be used to get this structure from the message id. +Specifically, the `mavlink_msg_entry_t` structure contains flags to tell you if the message contains target system/component information (`FLAG_HAVE_TARGET_SYSTEM`, `FLAG_HAVE_TARGET_COMPONENT`) and offsets into the payload that you can use to get these IDs (`target_system_ofs` and `target_component_ofs`, respectively). The MAVLink helper method `const mavlink_msg_entry_t*` [`mavlink_get_msg_entry(uint32_t msgid)`](https://github.com/mavlink/c_library_v2/blob/master/mavlink_helpers.h) can be used to get this structure from the message ID.