docs: Update metadata (#26167)

.github/instructions/docs.en.instructions.md

@@ -25,7 +25,24 @@ applyTo: "docs/en/**"
   - **Inline Code:** Use backticks for file paths, parameters, and CLI commands (e.g., `prettier`).
 - **Structure:** End every line at the end of a sentence (Semantic Line Breaks).
 
+## Linking & Navigation
+
+- **Standard Links:** Use standard inline syntax: `[link text](../category/filename.md)`.
+  Note relative link. 
+- **Table Links:** To keep tables readable, use reference-style links.
+  - Definition: `[Link Name]: https://example.com` (placed below the table).
+  - Usage: `[Link Name]` within the table cell.
+- **Images:** All image links must include a descriptive, accessible alt-text in the brackets: `![Detailed description of the image content](../../assets/path/to/image.png)`.
+  Note that all images should be relative references to images stored in the assets folder, which should be two folders below the any markdown file (as they are stored in a "category" subfolder) 
+
+- **Standard Links:** Use standard inline syntax: `[link text](../category/filename.md)`. Note the use of relative links.
+- **Table Links:** To keep tables easier to edit, prefer reference-style links.
+  - Definition: `[Link Name]: https://example.com` (placed below the table).
+  - Usage: `[Link Name]` within the table cell.
+- **Images:** All image links must include a descriptive, accessible alt-text: `![Detailed description of the image content](../../assets/path/to/image.png)`.
+  - **Note:** All images must be relative references to the `/docs/assets/` folder. Since documents are nested in a category folder, this is usually two levels up (`../../assets/`).
+
 ## Quality Control
 
-- **Formatting:** Ensure Prettier rules have been applied.
+- **Prettier Check:** Ensure Prettier rules have been applied. If there is evidence of inconsistent indentation or spacing, request the author run `npx prettier --write .` before merging.
 - **Language:** Enforce **UK English** spelling and grammar.

docs/en/SUMMARY.md

@@ -564,6 +564,7 @@
         - [DebugKeyValue](msg_docs/DebugKeyValue.md)
         - [DebugValue](msg_docs/DebugValue.md)
         - [DebugVect](msg_docs/DebugVect.md)
+        - [DeviceInformation](msg_docs/DeviceInformation.md)
         - [DifferentialPressure](msg_docs/DifferentialPressure.md)
         - [DistanceSensor](msg_docs/DistanceSensor.md)
         - [DistanceSensorModeChangeRequest](msg_docs/DistanceSensorModeChangeRequest.md)

docs/en/assembly/_assembly.md

@@ -284,7 +284,7 @@ A particular vehicle might have more/fewer motors and actuators, but the wiring
 The following sections explain each part in more detail.
 
 ::: tip
-If you're using [DroneCAN ESC](../peripherals/esc_motors.md#dronecan) the control signals will be connected to the CAN BUS instead of the PWM outputs as shown.
+If you're using [DroneCAN ESC](../dronecan/escs.md) the control signals will be connected to the CAN BUS instead of the PWM outputs as shown.
 :::
 
 ### Flight Controller Power
@@ -425,7 +425,6 @@ They recommend sensors, power systems, and other components from the same manufa
 - [Drone Components & Parts](../getting_started/px4_basic_concepts.md#drone-components-parts) (Basic Concepts)
 - [Payloads](../getting_started/px4_basic_concepts.md#payloads) (Basic Concepts)
 - [Hardware Selection & Setup](../hardware/drone_parts.md) — information about connecting and configuring specific flight controllers, sensors and other peripherals (e.g. airspeed sensor for planes).
-
   - [Mounting the Flight Controller](../assembly/mount_and_orient_controller.md)
   - [Vibration Isolation](../assembly/vibration_isolation.md)
   - [Mounting a Compass](../assembly/mount_gps_compass.md)

docs/en/config_mc/filter_tuning.md

@@ -70,7 +70,7 @@ Airframes with more than two frequency noise spikes typically clean the first tw
 Dynamic notch filters use ESC RPM feedback and/or the onboard FFT analysis.
 The ESC RPM feedback is used to track the rotor blade pass frequency and its harmonics, while the FFT analysis can be used to track a frequency of another vibration source, such as a fuel engine.
 
-ESC RPM feedback requires ESCs capable of providing RPM feedback such as [DShot](../peripherals/esc_motors.md#dshot) with telemetry connected, a bidirectional DShot set up ([work in progress](https://github.com/PX4/PX4-Autopilot/pull/23863)), or [UAVCAN/DroneCAN ESCs](../dronecan/escs.md).
+ESC RPM feedback requires ESCs capable of providing RPM feedback such as [DShot](../peripherals/dshot.md) with telemetry connected, a bidirectional DShot set up ([work in progress](https://github.com/PX4/PX4-Autopilot/pull/23863)), or [UAVCAN/DroneCAN ESCs](../dronecan/escs.md).
 Before enabling, make sure that the ESC RPM is correct.
 You might have to adjust the [pole count of the motors](../advanced_config/parameter_reference.md#MOT_POLE_COUNT).
 
@@ -92,10 +92,10 @@ To reduce the control latency, we want to increase the cutoff frequency for the
 The effect on latency of increasing `IMU_GYRO_CUTOFF` is approximated below.
 
 | Cutoff (Hz) | Delay approx. (ms) |
-| ------------ | ------------------ |
+| ----------- | ------------------ |
-| 30           | 8                  |
+| 30          | 8                  |
-| 60           | 3.8                |
+| 60          | 3.8                |
-| 120          | 1.9                |
+| 120         | 1.9                |
 
 However this is a trade-off as increasing `IMU_GYRO_CUTOFF` will also increase the noise of the signal that is fed to the motors.
 Noise on the motors has the following consequences:

docs/en/dronecan/escs.md

@@ -1,7 +1,14 @@
 # DroneCAN ESCs
 
 PX4 supports DroneCAN compliant ESCs.
-For more information, see the following articles for specific hardware/firmware:
+
+## Supported ESC
+
+:::info
+[Supported ESCs](../peripherals/esc_motors#supported-esc) in _ESCs & Motors_ may include additional devices that are not listed below.
+:::
+
+The following articles have specific hardware/firmware information:
 
 - [PX4 Sapog ESC Firmware](sapog.md)
   - [Holybro Kotleta 20](holybro_kotleta.md)

docs/en/modules/modules_driver.md

@@ -15,38 +15,6 @@ Subcategories:
 - [Rpm Sensor](modules_driver_rpm_sensor.md)
 - [Transponder](modules_driver_transponder.md)
 
-## MCP23009
-
-Source: [drivers/gpio/mcp23009](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/gpio/mcp23009)
-
-### Usage {#MCP23009_usage}
-
-```
-MCP23009 <command> [arguments...]
- Commands:
-   start
-     [-I]        Internal I2C bus(es)
-     [-X]        External I2C bus(es)
-     [-b <val>]  board-specific bus (default=all) (external SPI: n-th bus
-                 (default=1))
-     [-f <val>]  bus frequency in kHz
-     [-q]        quiet startup (no message if no device found)
-     [-a <val>]  I2C address
-                 default: 37
-     [-D <val>]  Direction
-                 default: 0
-     [-O <val>]  Output
-                 default: 0
-     [-P <val>]  Pullups
-                 default: 0
-     [-U <val>]  Update Interval [ms]
-                 default: 0
-
-   stop
-
-   status        print status info
-```
-
 ## atxxxx
 
 Source: [drivers/osd/atxxxx](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/osd/atxxxx)
@@ -749,6 +717,40 @@ lsm303agr <command> [arguments...]
    status        print status info
 ```
 
+## mcp230xx
+
+Source: [lib/drivers/mcp_common](https://github.com/PX4/PX4-Autopilot/tree/main/src/lib/drivers/mcp_common)
+
+### Usage {#mcp230xx_usage}
+
+```
+mcp230xx <command> [arguments...]
+ Commands:
+   start
+     [-I]        Internal I2C bus(es)
+     [-X]        External I2C bus(es)
+     [-b <val>]  board-specific bus (default=all) (external SPI: n-th bus
+                 (default=1))
+     [-f <val>]  bus frequency in kHz
+     [-q]        quiet startup (no message if no device found)
+     [-a <val>]  I2C address
+                 default: 39
+     [-D <val>]  Direction (1=Input, 0=Output)
+                 default: 0
+     [-O <val>]  Output
+                 default: 0
+     [-P <val>]  Pullups
+                 default: 0
+     [-U <val>]  Update Interval [ms]
+                 default: 0
+     [-M <val>]  First minor number
+                 default: 0
+
+   stop
+
+   status        print status info
+```
+
 ## mcp9808
 
 Source: [drivers/temperature_sensor/mcp9808](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/temperature_sensor/mcp9808)
@@ -899,8 +901,6 @@ fetching the latest mixing result and write them to PCA9685 at its scheduling ti
 It can do full 12bits output as duty-cycle mode, while also able to output precious pulse width
 that can be accepted by most ESCs and servos.
 
-The I2C bus and address can be configured via parameters `PCA9685_EN_BUS` and `PCA9685_I2C_ADDR`, or via command line arguments.
-
 ### Examples
 
 It is typically started with:

docs/en/modules/modules_system.md

@@ -127,6 +127,10 @@ commander <command> [arguments...]
 
    check         Run preflight checks
 
+   safety        Change prearm safety state
+     on|off      [on] to activate safety, [off] to deactivate safety and allow
+                 control surface movements
+
    arm
      [-f]        Force arming (do not run preflight checks)
 

docs/en/msg_docs/BatteryStatus.md

@@ -2,7 +2,7 @@
 
 Battery status
 
-Battery status information for up to 4 battery instances.
+Battery status information for up to 3 battery instances.
 These are populated from power module and smart battery device drivers, and one battery updated from MAVLink.
 Battery instance information is also logged and streamed in MAVLink telemetry.
 
@@ -11,7 +11,7 @@ Battery instance information is also logged and streamed in MAVLink telemetry.
 ```c
 # Battery status
 #
-# Battery status information for up to 4 battery instances.
+# Battery status information for up to 3 battery instances.
 # These are populated from power module and smart battery device drivers, and one battery updated from MAVLink.
 # Battery instance information is also logged and streamed in MAVLink telemetry.
 
@@ -33,9 +33,9 @@ uint8 cell_count           # [-] [@invalid 0] Number of cells
 
 
 uint8 source                   # [@enum SOURCE] Battery source
-uint8 SOURCE_POWER_MODULE = 0  # Power module
+uint8 SOURCE_POWER_MODULE = 0  # Power module (analog ADC or I2C power monitor)
-uint8 SOURCE_EXTERNAL = 1      # External
+uint8 SOURCE_EXTERNAL = 1      # External (MAVLink, CAN, or external driver)
-uint8 SOURCE_ESCS = 2          # ESCs
+uint8 SOURCE_ESCS = 2          # ESCs (via ESC telemetry)
 
 uint8 priority                # [-] Zero based priority is the connection on the Power Controller V1..Vn AKA BrickN-1
 uint16 capacity               # [mAh] Capacity of the battery when fully charged

docs/en/msg_docs/BatteryStatusV0.md

@@ -32,9 +32,9 @@ uint8 cell_count # [@invalid 0] Number of cells
 
 
 uint8 source # [@enum SOURCE] Battery source
-uint8 SOURCE_POWER_MODULE = 0 # Power module
+uint8 SOURCE_POWER_MODULE = 0 # Power module (analog ADC or I2C power monitor)
-uint8 SOURCE_EXTERNAL = 1 # External
+uint8 SOURCE_EXTERNAL = 1 # External (MAVLink, CAN, or external driver)
-uint8 SOURCE_ESCS = 2 # ESCs
+uint8 SOURCE_ESCS = 2 # ESCs (via ESC telemetry)
 
 uint8 priority # Zero based priority is the connection on the Power Controller V1..Vn AKA BrickN-1
 uint16 capacity # [mAh] Capacity of the battery when fully charged

docs/en/msg_docs/DeviceInformation.md

@@ -0,0 +1,45 @@
+# DeviceInformation (UORB message)
+
+Device information
+
+Can be used to uniquely associate a device_id from a sensor topic with a physical device using serial number.
+as well as tracking of the used firmware versions on the devices.
+
+[source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/DeviceInformation.msg)
+
+```c
+# Device information
+#
+# Can be used to uniquely associate a device_id from a sensor topic with a physical device using serial number.
+# as well as tracking of the used firmware versions on the devices.
+
+uint64 timestamp  # time since system start (microseconds)
+
+uint8 device_type  # [@enum DEVICE_TYPE] Type of the device. Matches MAVLink DEVICE_TYPE enum
+
+uint8 DEVICE_TYPE_GENERIC = 0                 # Generic/unknown sensor
+uint8 DEVICE_TYPE_AIRSPEED = 1                # Airspeed sensor
+uint8 DEVICE_TYPE_ESC = 2                     # ESC
+uint8 DEVICE_TYPE_SERVO = 3                   # Servo
+uint8 DEVICE_TYPE_GPS = 4                     # GPS
+uint8 DEVICE_TYPE_MAGNETOMETER = 5            # Magnetometer
+uint8 DEVICE_TYPE_PARACHUTE = 6               # Parachute
+uint8 DEVICE_TYPE_RANGEFINDER = 7             # Rangefinder
+uint8 DEVICE_TYPE_WINCH = 8                   # Winch
+uint8 DEVICE_TYPE_BAROMETER = 9               # Barometer
+uint8 DEVICE_TYPE_OPTICAL_FLOW = 10           # Optical flow
+uint8 DEVICE_TYPE_ACCELEROMETER = 11          # Accelerometer
+uint8 DEVICE_TYPE_GYROSCOPE = 12              # Gyroscope
+uint8 DEVICE_TYPE_DIFFERENTIAL_PRESSURE = 13  # Differential pressure
+uint8 DEVICE_TYPE_BATTERY = 14                # Battery
+uint8 DEVICE_TYPE_HYGROMETER = 15             # Hygrometer
+
+char[32] vendor_name  # Name of the device vendor
+char[32] model_name   # Name of the device model
+
+uint32   device_id         # [-] [@invalid 0 if not available] Unique device ID for the sensor. Does not change between power cycles.
+char[24] firmware_version  # [-] [@invalid empty if not available] Firmware version.
+char[24] hardware_version  # [-] [@invalid empty if not available] Hardware version.
+char[33] serial_number     # [-] [@invalid empty if not available] Device serial number or unique identifier.
+
+```

docs/en/msg_docs/EstimatorStatus.md

@@ -21,6 +21,7 @@ uint8 GPS_CHECK_FAIL_MAX_VERT_DRIFT = 7		# 7 : maximum allowed vertical position
 uint8 GPS_CHECK_FAIL_MAX_HORZ_SPD_ERR = 8	# 8 : maximum allowed horizontal speed fail - requires stationary vehicle
 uint8 GPS_CHECK_FAIL_MAX_VERT_SPD_ERR = 9	# 9 : maximum allowed vertical velocity discrepancy fail
 uint8 GPS_CHECK_FAIL_SPOOFED = 10		# 10 : GPS signal is spoofed
+uint8 GPS_CHECK_FAIL_JAMMED = 11		# 11 : GPS signal is jammed
 
 uint64 control_mode_flags	# Bitmask to indicate EKF logic state
 uint8 CS_TILT_ALIGN = 0		# 0 - true if the filter tilt alignment is complete

docs/en/msg_docs/GpioIn.md

@@ -6,6 +6,7 @@ GPIO mask and state
 
 ```c
 # GPIO mask and state
+uint8 MAX_INSTANCES = 8
 
 uint64 timestamp			# time since system start (microseconds)
 uint32 device_id			# Device id

docs/en/msg_docs/GpsDump.md

@@ -9,11 +9,15 @@ This message is used to dump the raw gps communication to the log.
 
 uint64 timestamp # time since system start (microseconds)
 
+uint8 INSTANCE_MAIN = 0
+uint8 INSTANCE_SECONDARY = 1
+
 uint8 instance   # Instance of GNSS receiver
+uint32 device_id
 uint8 len        # length of data, MSB bit set = message to the gps device,
                  # clear = message from the device
 uint8[79] data   # data to write to the log
 
-uint8 ORB_QUEUE_LENGTH = 8
+uint8 ORB_QUEUE_LENGTH = 16
 
 ```

docs/en/msg_docs/VehicleCommand.md

@@ -108,6 +108,7 @@ uint16 VEHICLE_CMD_LOGGING_START = 2510 # Start streaming ULog data.
 uint16 VEHICLE_CMD_LOGGING_STOP = 2511 # Stop streaming ULog data.
 uint16 VEHICLE_CMD_CONTROL_HIGH_LATENCY = 2600 # Control starting/stopping transmitting data over the high latency link.
 uint16 VEHICLE_CMD_DO_VTOL_TRANSITION = 3000 # Command VTOL transition.
+uint16 VEHICLE_CMD_DO_SET_SAFETY_SWITCH_STATE = 5300 # Command safety on/off. |1 to activate safety, 0 to deactivate safety and allow control surface movements|Unused|Unused|Unused|Unused|Unused|Unused|
 uint16 VEHICLE_CMD_ARM_AUTHORIZATION_REQUEST = 3001 # Request arm authorization.
 uint16 VEHICLE_CMD_PAYLOAD_PREPARE_DEPLOY = 30001 # Prepare a payload deployment in the flight plan.
 uint16 VEHICLE_CMD_PAYLOAD_CONTROL_DEPLOY = 30002 # Control a pre-programmed payload deployment.
@@ -187,6 +188,10 @@ int8 ARMING_ACTION_ARM = 1
 uint8 GRIPPER_ACTION_RELEASE = 0
 uint8 GRIPPER_ACTION_GRAB = 1
 
+# Used as param1 in DO_SET_SAFETY_SWITCH_STATE command.
+uint8 SAFETY_OFF = 0
+uint8 SAFETY_ON = 1
+
 uint8 ORB_QUEUE_LENGTH = 8
 
 float32 param1 # Parameter 1, as defined by MAVLink uint16 VEHICLE_CMD enum.

docs/en/msg_docs/index.md

@@ -105,6 +105,7 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m
 - [DebugKeyValue](DebugKeyValue.md)
 - [DebugValue](DebugValue.md)
 - [DebugVect](DebugVect.md)
+- [DeviceInformation](DeviceInformation.md) — Device information
 - [DifferentialPressure](DifferentialPressure.md) — Differential-pressure (airspeed) sensor
 - [DistanceSensor](DistanceSensor.md) — DISTANCE_SENSOR message data
 - [DistanceSensorModeChangeRequest](DistanceSensorModeChangeRequest.md)

docs/en/peripherals/dshot.md

@@ -11,6 +11,10 @@ DShot is an alternative ESC protocol that has several advantages over [PWM](../p
 
 This topic shows how to connect and configure DShot ESCs.
 
+## Supported ESC
+
+[ESCs & Motors > Supported ESCs](../peripherals/esc_motors#supported-esc) has a list of supported ESC (check "Protocols" column for DShot ESC).
+
 ## Wiring/Connections {#wiring}
 
 DShot ESC are wired the same way as [PWM ESCs](pwm_escs_and_servo.md).
@@ -76,7 +80,6 @@ The most important ones are:
   ```
 
 - Permanently set the spin direction of a motor connected to FMU output pin 1 (while motors are _not_ spinning):
-
   - Set spin direction to `reversed`:
 
     ```sh
@@ -104,7 +107,6 @@ The most important ones are:
     ```
 
   ::: info
-
   - The commands will have no effect if the motors are spinning, or if the ESC is already set to the corresponding direction.
   - The ESC will revert to its last saved direction (normal or reversed) on reboot if `save` is not called after changing the direction.
 

docs/en/peripherals/esc_motors.md

@@ -9,13 +9,14 @@ PX4 supports a number of [common protocols](../esc/esc_protocols.md) for sending
 
 The following list is non-exhaustive.
 
-| ESC Device                   | Protocols                            | Firmwares                | Notes                                                 |
+| ESC Device                     | Protocols                            | Firmwares                | Notes                                                 |
-| ---------------------------- | ------------------------------------ | ------------------------ | ----------------------------------------------------- |
+| ------------------------------ | ------------------------------------ | ------------------------ | ----------------------------------------------------- |
-| [ARK 4IN1 ESC]               | [Dshot], [PWM]                       | [AM32]                   | Has versions with/without connnectors                 |
+| [ARK 4IN1 ESC]                 | [Dshot], [PWM]                       | [AM32]                   | Has versions with/without connnectors                 |
-| [Holybro Kotleta 20]         | [DroneCAN], [PWM]                    | [PX4 Sapog ESC Firmware] |                                                       |
+| [Holybro Kotleta 20]           | [DroneCAN], [PWM]                    | [PX4 Sapog ESC Firmware] |                                                       |
-| [Vertiq Motor & ESC modules] | [Dshot], [OneShot], Multishot, [PWM] | Vertiq firmware          | Larger modules support DroneCAN, ESC and Motor in one |
+| [Vertiq Motor & ESC modules]   | [Dshot], [OneShot], Multishot, [PWM] | Vertiq firmware          | Larger modules support DroneCAN, ESC and Motor in one |
-| [VESC ESCs]                  | [DroneCAN], [PWM]                    | VESC project firmware    |                                                       |
+| [RaccoonLab CAN PWM ESC nodes] | [DroneCAN], Cyphal                   |                          | Cyphal and DroneCAN notes for PWM ESC                 |
-| [Zubax Telega]               | [DroneCAN], [PWM]                    | Telega-based             | ESC and Motor in one                                  |
+| [VESC ESCs]                    | [DroneCAN], [PWM]                    | VESC project firmware    |                                                       |
+| [Zubax Telega]                 | [DroneCAN], [PWM]                    | Telega-based             | ESC and Motor in one                                  |
 
 <!-- Links for table above -->
 
@@ -29,6 +30,7 @@ The following list is non-exhaustive.
 [PWM]: ../peripherals/pwm_escs_and_servo.md
 [Holybro Kotleta 20]: ../dronecan/holybro_kotleta.md
 [Vertiq Motor & ESC modules]: ../peripherals/vertiq.md
+[RaccoonLab CAN PWM nodes]: ../dronecan/raccoonlab_nodes.md
 [Zubax Telega]: ../dronecan/zubax_telega.md
 
 ## See Also