LED Support

A board architecture may or may not have LEDs. If the board does have LEDs, then most architectures provide similar LED support that is enabled when CONFIG_ARCH_LEDS is selected in the NuttX configuration file. This LED support is part of architecture-specific logic and is not managed by the core NuttX logic. However, the support provided by each architecture is sufficiently similar that it can be documented here.

Header Files

LED-related definitions are provided in two header files:

  • LED definitions are provided for each board in the board.h that resides in the <board-name>/include/board.h file (which is also linked to include/arch/board/board.h when the RTOS is configured). Those definitions are discussed below.

  • The board-specific logic provides unique instances of the LED interfaces. This is because the implementation of LED support may be very different on different boards. Prototypes for these board-specific implementations are, however, provided in architecture-common header files. That header file is usually at <arch-name>/src/common/up_internal.h, but could be at other locations in particular architectures. These prototypes are discussed below.

LED Definitions

The implementation of LED support is very specific to a board architecture. Some boards have several LEDS, others have only one or two. Some have none. Others LED matrices and show alphanumeric data, etc. The NuttX logic does not refer to specific LEDS, rather, it refers to an event to be shown on the LEDS in whatever manner is appropriate for the board; the way that this event is presented depends upon the hardware available on the board.

The model used by NuttX is that the board can show 8 events defined as follows in <board-name>/include/board.h:

#define LED_STARTED       ??
#define LED_HEAPALLOCATE  ??
#define LED_IRQSENABLED   ??
#define LED_STACKCREATED  ??
#define LED_INIRQ         ??
#define LED_SIGNAL        ??
#define LED_ASSERTION     ??
#define LED_PANIC         ??

The specific value assigned to each pre-processor variable can be whatever makes the implementation easiest for the board logic. The meaning associated with each definition is as follows:

  • LED_STARTED is the value that describes the setting of the LEDs when the LED logic is first initialized. This LED value is set but never cleared.

  • LED_HEAPALLOCATE indicates that the NuttX heap has been configured. This is an important place in the boot sequence because if the memory is configured wrong, it will probably crash leaving this LED setting. This LED value is set but never cleared.

  • LED_IRQSENABLED indicates that interrupts have been enabled. Again, during bring-up (or if there are hardware problems), it is very likely that the system may crash just when interrupts are enabled, leaving this setting on the LEDs. This LED value is set but never cleared.

  • LED_STACKCREATED is set each time a new stack is created. If set, it means that the system attempted to start at least one new thread. This LED value is set but never cleared.

  • LED_INIRQ is set and cleared on entry and exit from each interrupt. If interrupts are working okay, this LED will have a dull glow.

  • LED_SIGNAL is set and cleared on entry and exit from a signal handler. Signal handlers are tricky so this is especially useful during bring-up or a new architecture.

  • LED_ASSERTION is set if an assertion occurs.

  • LED_PANIC will blink at around 1Hz if the system panics and hangs.

Common LED interfaces

The include/nuttx/board.h includes the following declarations:

void board_autoled_initialize(void)

Called early in power-up initialization to initialize the LED hardware.

Note

In most architectures, board_autoled_initialize() is called from board-specific initialization logic. But there are a few architectures where this initialization function is still called from common chip architecture logic. This interface is not, however, a common board interface in any event.

Warning

This interface name will eventually be removed; do not use it in new board ports. New implementations should not use the naming convention for common board interfaces, but should instead use the naming conventions for microprocessor-specific interfaces or the board-specific interfaces (such as stm32_led_initialize()).

void board_autoled_on(int led)

Called to instantiate the LED presentation of the event. The led argument is one of the definitions provided in <board-name>/include/board.h.

void board_autoled_off(int led)

Called to terminate the LED presentation of the event. The led argument is one of the definitions provided in <board-name>/include/board.h. Note that only LED_INIRQ, LED_SIGNAL, LED_ASSERTION, and LED_PANIC indications are terminated.