LED

LED control interface for hardware platforms. More...

Collaboration diagram for LED:

Data Structures
struct	hw_led_t
	LED structure definition for hardware control. More...

Enumerations
enum	hw_led_cap_t { HW_LED_CAP_NONE = 0, HW_LED_CAP_BINARY = (1 << 0), HW_LED_CAP_LINEAR = (1 << 1), HW_LED_CAP_GPIO = (1 << 2) }
	LED capabilities flags. More...

Functions
hw_led_t	hw_led_init (uint8_t gpio, hw_pwm_t *pwm)
	Initialize an LED unit. More...
uint8_t	hw_led_status_gpio ()
	Return the GPIO pin number for the on-board status LED. More...
void	hw_led_finalize (hw_led_t *led)
	Finalize and release an LED. More...
bool	hw_led_valid (hw_led_t *led)
	Check if an LED handle is valid and initialized. More...
hw_led_cap_t	hw_led_capabilities (hw_led_t *led)
	Return LED capabilities. More...
bool	hw_led_set_state (hw_led_t *led, bool on)
	Set the LED binary state (full on or off). More...
bool	hw_led_set_brightness (hw_led_t *led, uint8_t brightness)
	Set the LED brightness (linear LEDs only). More...
bool	hw_led_blink (hw_led_t *led, uint32_t period_ms, bool repeats)
	Blink the LED (toggle full on/off). More...
bool	hw_led_fade (hw_led_t *led, uint32_t period_ms, bool repeats)
	Fade (breathe) the LED (PWM LEDs only). More...

Detailed Description

LED control interface for hardware platforms.

Enumeration Type Documentation

hw_led_cap_t

enum hw_led_cap_t

LED capabilities flags.

This enum defines the capabilities of an LED unit, such as whether it supports binary on/off control or linear brightness control via PWM.

Enumerator
HW_LED_CAP_NONE	No capabilities.
HW_LED_CAP_BINARY	Supports binary on/off control.
HW_LED_CAP_LINEAR	Supports linear brightness control via PWM.
HW_LED_CAP_GPIO	GPIO pin control.

Definition at line 43 of file led.h.

             {
  HW_LED_CAP_NONE = 0,          
  HW_LED_CAP_BINARY = (1 << 0), 
  HW_LED_CAP_LINEAR = (1 << 1), 
  HW_LED_CAP_GPIO = (1 << 2),   
} hw_led_cap_t;

Function Documentation

hw_led_blink()

bool hw_led_blink	(	hw_led_t *	led,
		uint32_t	period_ms,
		bool	repeats
	)

Blink the LED (toggle full on/off).

Parameters

led	Pointer to the LED structure.
period_ms	Full ON+OFF cycle period in milliseconds.
repeats	True to continue indefinitely, false to perform a single full cycle (ending in OFF).

Returns

True on success, false otherwise.

• period_ms defines the total time for ON then OFF (two half-periods).
• The implementation enforces a minimum full cycle (currently 200 ms) for stability; shorter requests are clamped.
• Cancels any prior blink/fade before starting.

Examples:

examples/runtime/led/main.c.

hw_led_capabilities()

hw_led_cap_t hw_led_capabilities

(

hw_led_t *

led

)

Return LED capabilities.

Parameters

led	Pointer to the LED structure to check.

Returns

Bitmask of hw_led_cap_t values describing supported operations.

Notes:

• HW_LED_CAP_BINARY implies on/off control (present for every valid LED).
• HW_LED_CAP_LINEAR implies brightness (0..255) via PWM.
• HW_LED_CAP_GPIO indicates a directly drivable GPIO (as distinct from a virtual / module-managed status LED).

Examples:

examples/runtime/led/main.c.

hw_led_fade()

bool hw_led_fade	(	hw_led_t *	led,
		uint32_t	period_ms,
		bool	repeats
	)

Fade (breathe) the LED (PWM LEDs only).

Parameters

led	Pointer to the LED structure.
period_ms	Full up+down brightness cycle period in milliseconds.
repeats	True to continue indefinitely, false to perform one full cycle.

Returns

True on success, false otherwise.

• period_ms spans a full 0→255→0 traversal.
• Interval per brightness step ~ period_ms / 510 (minimum 1 ms).
• If linear (PWM) capability is absent, this function transparently falls back to hw_led_blink() using the same period.
• Cancels any prior blink/fade before starting.

Examples:

examples/runtime/led/main.c.

hw_led_finalize()

void hw_led_finalize

(

hw_led_t *

led

)

Finalize and release an LED.

Parameters

led	Pointer to the LED structure to finalize.

This function disables the LED unit. If a PWM structure was used, it will stop the PWM output and release the GPIO pin associated with the LED.

Examples:

examples/runtime/led/main.c.

hw_led_init()

hw_led_t hw_led_init	(	uint8_t	gpio,
		hw_pwm_t *	pwm
	)

Initialize an LED unit.

Parameters

gpio	The GPIO pin number for the LED.
pwm	Optional pointer to a PWM structure for linear control.

Returns

A LED structure representing the initialized unit.

This function initializes an LED unit. If linear control is supported (non-NULL PWM pointer associated with the GPIO pin), it will set up the PWM channel for the LED.

If the pin number is 0xFF then it assumes the platform on-board status LED is being initialized (which may be implemented via a Wi‑Fi / radio module rather than a raw GPIO). If the PWM structure is NULL, the LED will be controlled in a simple on/off manner (binary) without PWM.

Examples:

examples/runtime/led/main.c.

hw_led_set_brightness()

bool hw_led_set_brightness	(	hw_led_t *	led,
		uint8_t	brightness
	)

Set the LED brightness (linear LEDs only).

Parameters

led	Pointer to the LED structure.
brightness	Desired brightness (0 = off, 255 = full on).

Returns

True on success (including the degenerate binary case when only 0 or 255 are meaningful), false if unsupported or invalid.

Cancels any ongoing blink or fade before applying the new brightness. For non-PWM LEDs this degenerates to binary on/off; intermediate values are coerced to 0 or 255.

Examples:

examples/runtime/led/main.c.

hw_led_set_state()

bool hw_led_set_state	(	hw_led_t *	led,
		bool	on
	)

Set the LED binary state (full on or off).

Parameters

led	Pointer to the LED structure.
on	True to turn on the LED to full brightness, false to turn it off.

Returns

True on success, false on invalid handle or hardware failure.

Cancels any ongoing blink or fade before applying the new state. For a linear (PWM) LED, "on" maps to brightness 255 and "off" maps to 0.

Examples:

examples/runtime/led/main.c.

hw_led_status_gpio()

uint8_t hw_led_status_gpio

(

)

Return the GPIO pin number for the on-board status LED.

Returns

The GPIO pin number used for the status LED, or 0xFF if not available: for example, if the GPIO is controlled through the Wi-Fi subsystem.

Examples:

examples/runtime/led/main.c.

hw_led_valid()

bool hw_led_valid

(

hw_led_t *

led

)

Check if an LED handle is valid and initialized.

Parameters

led	Pointer to the LED structure to check.

Returns

True if the LED has been successfully initialized and not yet finalized; false otherwise.

Examples:

examples/runtime/led/main.c.