Contiki-NG
Files | Functions
LED Hardware Abstraction Layer

The LED HAL provides a set of functions that can manipulate LEDS. More...

Files

file  leds.c
 Implementation of the platform-independent aspects of the LED HAL.
 

Functions

void leds_init ()
 Initialise the LED HAL. More...
 
void leds_single_on (leds_num_t led)
 Turn a single LED on. More...
 
void leds_single_off (leds_num_t led)
 Turn a single LED off. More...
 
void leds_single_toggle (leds_num_t led)
 Toggle a single LED. More...
 
void leds_on (leds_mask_t leds)
 Turn on multiple LEDs. More...
 
void leds_off (leds_mask_t leds)
 Turn off multiple LEDs. More...
 
void leds_toggle (leds_mask_t leds)
 Toggle multiple LEDs. More...
 
void leds_set (leds_mask_t leds)
 Set all LEDs to a specific state. More...
 
leds_mask_t leds_get ()
 Get the status of LEDs. More...
 

Detailed Description

The LED HAL provides a set of functions that can manipulate LEDS.

Currently, the LED HAL supports two APIs:

The two APIs use very similar semantics and have an overlapping set of function calls. This is done so that platform-independent examples can work on all platforms, irrespective of which API each platform supports.

The legacy API can be enabled by the platform code by defining LEDS_CONF_LEGACY_API 1.

Once all platforms supported in contiki-ng/contiki-ng have been ported to the new API, the legacy API will be deleted without warning. For this reason, it is strongly recommended to use the new API for new platforms and for platforms hosted in external repositories.

The new API provides a set of common LED manipulation functions that can be used in a platform-independent fashion. Functions exist to manipulate one LED at a time (leds_single_XYZ), as well as to manipulate multiple LEDs at a time (leds_XYZ).

The assumption is that each LED is connected to a GPIO pin using either positive or negative logic.

LEDs on a device are numbered incrementally, starting from 0 and counting upwards. Thus, if a device has 3 LEDs they will be numbered 0, 1 and 2. Convenience macros (LEDS_LED_n) are provided to refer to LEDs. These macros can be used as arguments to functions that manipulate a single LED, such as leds_single_on() but not leds_on().

The legacy scheme that uses colours to refer to LEDs is maintained, without semantic changes, but with minor changes in logic:

Note that, in order to avoid changes to LED colour semantics between the two APIs, references to LED by colour are bitwise OR masks and should therefore only be used as argument to functions that manipulate multiple LEDS (e.g. leds_off() and not leds_single_off()).

In terms of porting for new platforms, developers simply have to:

Function Documentation

◆ leds_get()

leds_mask_t leds_get ( void  )

Get the status of LEDs.

Returns
A bitwise mask indicating whether each individual LED is on or off

The return value is a bitwise mask. If a bit is set then the corresponding LED is on.

Definition at line 224 of file leds.c.

◆ leds_init()

void leds_init ( void  )

Initialise the LED HAL.

This function will set corresponding LED GPIO pins to output and will also set the initial state of all LEDs to off.

Definition at line 113 of file leds.c.

References LEDS_COUNT.

◆ leds_off()

void leds_off ( leds_mask_t  leds)

Turn off multiple LEDs.

Parameters
ledsThe leds to be turned off as an OR mask

The led argument should be a bitwise mask of the LEDs to be changed. For example, to turn on LEDs 1 and 3, you should pass LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5

This function will not change the state of other LEDs.

Definition at line 186 of file leds.c.

References LEDS_COUNT.

Referenced by leds_set().

◆ leds_on()

void leds_on ( leds_mask_t  leds)

Turn on multiple LEDs.

Parameters
ledsThe leds to be turned on as an OR mask

The led argument should be a bitwise mask of the LEDs to be changed. For example, to turn on LEDs 1 and 3, you should pass LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5

This function will not change the state of other LEDs.

Definition at line 168 of file leds.c.

References LEDS_COUNT.

Referenced by leds_set().

◆ leds_set()

void leds_set ( leds_mask_t  leds)

Set all LEDs to a specific state.

Parameters
ledsThe state of all LEDs afer this function returns

The led argument should be a bitwise mask of the LEDs to be changed. For example, to turn on LEDs 1 and 3, you should pass LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5

This function will change the state of all LEDs. LEDs not set in the leds mask will be turned off.

Definition at line 217 of file leds.c.

References LEDS_ALL, leds_off(), and leds_on().

◆ leds_single_off()

void leds_single_off ( leds_num_t  led)

Turn a single LED off.

Parameters
ledThe led

The led argument should be the LED's number, in other words one of the LED_Ln macros.

This function will not change the state of other LEDs.

Definition at line 141 of file leds.c.

References LEDS_COUNT.

◆ leds_single_on()

void leds_single_on ( leds_num_t  led)

Turn a single LED on.

Parameters
ledThe led

The led argument should be the LED's number, in other words one of the LED_Ln macros.

This function will not change the state of other LEDs.

Definition at line 125 of file leds.c.

References LEDS_COUNT.

◆ leds_single_toggle()

void leds_single_toggle ( leds_num_t  led)

Toggle a single LED.

Parameters
ledThe led

The led argument should be the LED's number, in other words one of the LED_Ln macros.

This function will not change the state of other LEDs.

Definition at line 157 of file leds.c.

References LEDS_COUNT.

◆ leds_toggle()

void leds_toggle ( leds_mask_t  leds)

Toggle multiple LEDs.

Parameters
ledsThe leds to be toggled as an OR mask

The led argument should be a bitwise mask of the LEDs to be changed. For example, to turn on LEDs 1 and 3, you should pass LED_NUM_TO_MASK(LED_L1) | LED_NUM_TO_MASK(LED_L3) = 1 | 4 = 5

This function will not change the state of other LEDs.

Definition at line 204 of file leds.c.

References LEDS_COUNT.