Hi all,
On 11/12/25 6:48 PM, Quentin Schulz wrote:
From: Quentin Schulz <[email protected]>
This adds documentation on how to use the led shell command.
Signed-off-by: Quentin Schulz <[email protected]>
---
doc/usage/cmd/led.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 95 insertions(+)
diff --git a/doc/usage/cmd/led.rst b/doc/usage/cmd/led.rst
new file mode 100644
index 00000000000..b5623895c7e
--- /dev/null
+++ b/doc/usage/cmd/led.rst
@@ -0,0 +1,95 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+.. index::
+ single: led (command)
+
+led command
+===========
+
+Synopsis
+--------
+
+::
+
+ led <led_label> <on|off|toggle>
+ led <led_label> blink <blink-freq in ms>
+ led <led_label>
+ led list
+
+led <led_label>
+---------------
+
+Get state of the LED whose label is the one passed as ``<led_label>`` argument.
+
+Provided ``<led_label>`` is *module_led*, the possible outputs for this command
+are::
+
+ LED 'module_led': off
+ LED 'module_led': on
+ LED 'module_led': blink
+
+led <led_label> on|off|toggle
+-----------------------------
+
+Turn on, off or toggle state of the LED whose label is the one passed as
+``<led_label>`` argument.
+
+led <led_label> blink <blink-freq in ms>
+----------------------------------------
+
+Make the LED whose label is the one passed as ``<led_label>`` argument blink at
+a frequency specified by the argument ``<blink-freq in ms>``.
+
+The frequency is parsed as a decimal number and its unit is milliseconds. The
+duty cycle is 50%. Example::
+
+ led blue blink 1000
+
+will make the *blue*-labeled LED blink with a state (on or off) kept for 500ms
+before switching to the other state (respectively off or on) for 500ms,
+looping endlessly.
+
+led list
+--------
+
+List all available LEDs by their label and provide their known state, which can
+be either *off*, *on* or *blink*.
+
+If a LED has not been probed yet, its state will be shown as *<inactive>* in
the
+list.
+
+Examples
+--------
+
+::
+
+ => led list
+ module_led on
+ sd_card_led <inactive>
+ => led module_led
+ LED 'module_led': on
+ => led module_led off
+ => led module_led
+ LED 'module_led': off
+ => led module_led toggle
+ => led module_led
+ LED 'module_led': on
+ => led module_led toggle
+ => led module_led
+ LED 'module_led': off
+ => led module_led blink 1000
+ => led module_led
+ LED 'module_led': blink
+ => led sd_card_led
+ LED 'sd_card_led': off
+ => led list
+ module_led blink
+ sd_card_led off
+
+Configuration
+-------------
+
+The *led* commands are only available if ``CONFIG_CMD_LED=y``.
+
+The *led <led_label> blink* command is only available if ``CONFIG_CMD_LED=y``
+and either ``CONFIG_LED_BLINK=y`` or ``CONFIG_LED_SW_BLINK=y``.
It seems like there's another led shell command that you can build with
CONFIG_LED_STATUS_CMD=y that uses the legacy LED API... Should it be
mentioned/have its own documentation page?
Maybe we should spend time porting the 5 defconfigs that make use of
this legacy API to the new one and entirely retire the legacy LED API.
However, there seems to be some discrepancies between the LED_BOOT
behavior and that of CONFIG_LED_STATUS_BOOT. The former blinks for a
brief period of time and then is solid on once reaching U-Boot's main
loop. The latter is blinking sometime after relocation and then turned
off on first BOOTP packet.
Out of the 5 defconfigs, 3 are using GPIO LEDs with
CONFIG_LED_STATUS_GPIO=y so it shouldn't be too difficult to migrate to
the new API just to get the LEDs working (I am not talking about keeping
the same behavior). The other two are configs/eb_cpu5282_defconfig and
configs/eb_cpu5282_internal_defconfig which I assume are for the same
product, but it has not seen actual updates (aside from tree-wide
migrations) in the last 13 years. From what I could tell, this is also
GPIO leds, but controlled by writing directly to the GPIO registers
instead of using a driver. Maybe we can issue a deprecation notice and
tell the maintainers/users of that board they have X releases to migrate
else it gets support for the LEDs removed.
For the other boards, we probably need to check how to use the DT for
the LEDs that are currently configured via the legacy API.
This is at the end of my todo list though.
Cheers,
Quentin
