From 040b885dbd5b3ef8345101efb91d3e947d5bb5df Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 5 Mar 2026 10:43:41 +1100 Subject: [PATCH] docs: DroneCAN Lights (#26641) --- docs/en/SUMMARY.md | 1 + docs/en/dronecan/index.md | 16 +++------ docs/en/dronecan/lights.md | 61 +++++++++++++++++++++++++++++++++++ docs/en/peripherals/vertiq.md | 2 +- 4 files changed, 67 insertions(+), 13 deletions(-) create mode 100644 docs/en/dronecan/lights.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 53a72b0079..7574e4601e 100644 --- a/docs/en/SUMMARY.md +++ b/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) diff --git a/docs/en/dronecan/index.md b/docs/en/dronecan/index.md index d351aff110..4d4f1343d6 100644 --- a/docs/en/dronecan/index.md +++ b/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 diff --git a/docs/en/dronecan/lights.md b/docs/en/dronecan/lights.md new file mode 100644 index 0000000000..579fe1f5a6 --- /dev/null +++ b/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) | diff --git a/docs/en/peripherals/vertiq.md b/docs/en/peripherals/vertiq.md index dc81c1a377..f9b350f474 100644 --- a/docs/en/peripherals/vertiq.md +++ b/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.