docs: DroneCAN Lights (#26641)

docs/en/SUMMARY.md

@@ -379,6 +379,7 @@
     - [PX4 DroneCAN Firmware](dronecan/px4_cannode_fw.md)
     - [ARK CANnode](dronecan/ark_cannode.md)
     - [RaccoonLab CAN Nodes](dronecan/raccoonlab_nodes.md)
+    - [DroneCAN Lights](dronecan/lights.md)
   - [Cable Wiring](assembly/cable_wiring.md)
   - [Companion Computers](companion_computer/index.md)
     - [Pixhawk + Companion Setup](companion_computer/pixhawk_companion.md)

docs/en/dronecan/index.md

@@ -283,19 +283,11 @@ Note that DroneCAN ESCs should be on their own dedicated CAN interface(s) becaus
 
 ### Lights
 
-PX4 can control LEDs via DroneCAN [LightsCommand](https://dronecan.github.io/Specification/7._List_of_standard_data_types/#lightscommand) messages.
+PX4 can control external LEDs on a connected DroneCAN peripheral using the standard DroneCAN [LightsCommand](https://dronecan.github.io/Specification/7._List_of_standard_data_types/#lightscommand) message.
+Up to 2 lights acan be controlled.
+Each light can independently show [system status colours](../getting_started/led_meanings.md#ui-led), a fixed colour (commonly used for indciating aircraft orientation), or switch between both depending on arm state.
 
-Configuration:
-
-1. Set [UAVCAN_LGT_NUM](../advanced_config/parameter_reference.md#UAVCAN_LGT_NUM) to the number of lights (0 disables, maximum 2). You need to reboot and reopen the ground station to have parameters for new instances available.
-2. [UAVCAN_LGT_MODE](../advanced_config/parameter_reference.md#UAVCAN_LGT_MODE) controls when lights should be in active state (always off, when armed, when prearmed, always on).
-3. For each light slot (0 to NUM-1), set:
-   - `UAVCAN_LGT_IDx`: The `light_id` matching your peripheral.
-   - `UAVCAN_LGT_FNx`: The light function. Available options:
-     - System status light
-     - Static colors which light up when `UAVCAN_LGT_MODE` is active.
-     - Hybrid modes where the Status is shown when `UAVCAN_LGT_MODE` is inactive, and a static color when active.
-4. Reboot for changes to take effect.
+See [DroneCAN Lights](lights.md) for full configuration details.
 
 ## QGC CANNODE Parameter Configuration
 

docs/en/dronecan/lights.md

@@ -0,0 +1,61 @@
+# DroneCAN Lights
+
+PX4 can control external LEDs on a connected DroneCAN peripheral using the standard DroneCAN [LightsCommand](https://dronecan.github.io/Specification/7._List_of_standard_data_types/#lightscommand) message.
+
+Up to 2 lights are supported.
+These can show [system status colours](../getting_started/led_meanings.md#ui-led), a fixed colour (used for indicating aircraft orientation), or switch between both depending on arm state.
+
+## Supported Devices
+
+Any DroneCAN peripheral implementing the standard `LightsCommand` message type should work.
+
+The following have been tested:
+
+- **Vertiq ESC LED add-ons**: Each ESC exposes two light IDs — one RGB (for status) and one white.
+  The `light_id` for each is calculated as `esc_index × 3 + BASE_ID`, where `BASE_ID` is 1 for RGB and 2 for white.
+  See [Vertiq](../peripherals/vertiq.md) for other ESC setup details.
+
+## PX4 Configuration
+
+1. Set up DroneCAN as described in [DroneCAN](index.md) (`UAVCAN_ENABLE` ≥ 2).
+2. Set [UAVCAN_LGT_NUM](../advanced_config/parameter_reference.md#UAVCAN_LGT_NUM) to the number of lights (1 or 2).
+   Then reboot and reopen the ground station so that parameters for the new instances become visible.
+3. Set the `light_id` and [light functions](#light_functions) of each light:
+   - [UAVCAN_LGT_ID0](../advanced_config/parameter_reference.md#UAVCAN_LGT_ID0) / [UAVCAN_LGT_ID1](../advanced_config/parameter_reference.md#UAVCAN_LGT_ID1): Set to a `light_id` value (as defined by the specific product).
+   - [UAVCAN_LGT_FN0](../advanced_config/parameter_reference.md#UAVCAN_LGT_FN0) / [UAVCAN_LGT_FN1](../advanced_config/parameter_reference.md#UAVCAN_LGT_FN1): Choose the desired [light function](#light_functions).
+4. Set [UAVCAN_LGT_MODE](#UAVCAN_LGT_MODE) to control when fixed "orientation" colours activate.
+5. Reboot for changes to take effect.
+
+### Light Functions {#light_functions}
+
+The functions of enabled lights are configured using [UAVCAN_LGT_FN0](../advanced_config/parameter_reference.md#UAVCAN_LGT_FN0) and [UAVCAN_LGT_FN1](../advanced_config/parameter_reference.md#UAVCAN_LGT_FN1), respectively.
+Each function is represented by a value that defines two behaviours: one when the activation mode is **inactive** and one when it is **active**.
+
+| Value | Name          | When mode inactive   | When mode active     |
+| ----- | ------------- | -------------------- | -------------------- |
+| 0     | Status/Status | System status colour | System status colour |
+| 1     | Off/White     | Off                  | White                |
+| 2     | Off/Red       | Off                  | Red                  |
+| 3     | Off/Green     | Off                  | Green                |
+| 4     | Status/White  | System status colour | White                |
+| 5     | Status/Red    | System status colour | Red                  |
+| 6     | Status/Green  | System status colour | Green                |
+| 7     | Status/Off    | System status colour | Off                  |
+
+Notes:
+
+- The [system status colours](../getting_started/led_meanings.md#ui-led) is the same LED pattern used by the flight controller's onboard status LED (e.g. red when disarmed, green when armed and ready).
+- A fixed colour, commonly used to indicate aircraft orientation. For example it is a common convention to have a red light on the port side, green on starboard, or white to the rear.
+  These colours do not change with flight controller state.
+- For _hybrid_ functions, such as `Status/Red`, the light shows the Status colour while the activation mode is inactive, then switches to the "fixed" light colour once the mode becomes active.
+
+### Activation Mode (`UAVCAN_LGT_MODE`) {#UAVCAN_LGT_MODE}
+
+The activation mode parameter ([UAVCAN_LGT_MODE](#UAVCAN_LGT_MODE)) controls when each light switches from its _inactive_ to its _active_ behaviour (configured with the [Light function](#light_functions)):
+
+| Value | Meaning                                                  |
+| ----- | -------------------------------------------------------- |
+| 0     | Always inactive (lights always show the inactive column) |
+| 1     | Active when armed (default)                              |
+| 2     | Active when prearmed or armed                            |
+| 3     | Always active (lights always show the active column)     |

docs/en/peripherals/vertiq.md

@@ -46,7 +46,7 @@ Standard Vertiq ESC modules do not include LEDs.
 :::
 
 Vertiq LED Add-on modules have two LEDs per ESC (RGB for status, White for anti-collision).
-See [DroneCAN Lights](../dronecan/index.md#lights) for configuration instructions.
+See [DroneCAN Lights](../dronecan/lights.md) for configuration instructions.
 
 The `light_id` for each LED is calculated as: `esc_index × 3 + BASE_ID`, where `BASE_ID` is 1 for RGB and 2 for White.