NHS31xx SW API
led: LED module

Detailed Description

The LED module provides an API to control bi-state (on/off) LEDs on a board. Each LED has a "handle" (e.g. LED_(2)), and LED_On(LED_(2)) switches the third LED 'on'. In other words, the LED module abstracts which physical pin is used and the polarity of the control (active high or active low).

It is expected that each board library includes this module, and configures the diversity settings of this module (see led_dft.h) to match the LEDs on the board. The goal is that all applications can use LEDs using the same API with the same behavior.

How to use the module
  • The first step is to initialize the module (via LED_Init). Note that both the IOCON block and the GPIO block must have been initialized before.
  • Next, the LEDs are controlled via the other provided functions. All arguments are a mask. The first is always leds that identifies which LEDs will be targeted; example values are LED_(0), LED_(1) | LED_(3), LED_ALL. The second argument - if present - is states that identifies the new states for the LEDs. A bit value of 1 indicates an 'on' value, a value of 0 indicates an 'off' value.
Diversity
This module supports diversity: the number of LEDs it can control and how they are configured. Check Diversity settings for all diversity parameters and their default values.
Examples
To shorten the examples any timing is left out. You may want to single step intersperse them with calls to Chip_Clock_System_BusyWait_ms after each state change to see the full intended effect.
Example 1 - Switching two LEDs in various ways
LED_Init(); /* Should already been taken care of during board initialization. */
/* Turn two LEDs on individually and then both off together */
LED_On(LED_(0));
LED_On(LED_(1));
LED_Off(LED_(0) | LED_(1));
/* Toggle two LEDs together */
LED_SetState(LED_(0) | LED_(1), LED_(1) /* led 0 off, led 1 on */);
LED_SetState(LED_(0) | LED_(1), LED_(0) /* led 0 on, led 1 off */);
/* Toggle two LEDs together */
LED_Toggle(LED_(0) | LED_(1));
/* Turn all LEDs off */
Example 2 - Inspecting the state of LEDs
LED_Init(); /* Should already been taken care of during board initialization. */
LED_On(LED_(0));
LED_On(LED_(1));
ASSERT(LED_GetState(LED_(0) | LED_(1)) == (LED_(0) | LED_(1)));
Example 3 - Light bar
LED_Init(); /* Should already been taken care of during board initialization. */
/* growing */
for (int i = 0; i < LED_COUNT; i++) {
LED_On(LED_(i));
}
/* walking */
for (int i = 0; i < LED_COUNT; i++) {
}

Modules

 Diversity settings
 

Macros

#define LED_(n)   (1 << (n))
 
#define LED_ALL   ((1 << (LED_COUNT)) - 1)
 

Functions

void LED_Init (void)
 
void LED_SetState (int leds, int states)
 
int LED_GetState (int leds)
 
void LED_On (int leds)
 
void LED_Off (int leds)
 
void LED_Toggle (int leds)
 

Macro Definition Documentation

◆ LED_

#define LED_ (   n)    (1 << (n))

The mask for LED n.

◆ LED_ALL

#define LED_ALL   ((1 << (LED_COUNT)) - 1)

The mask for all available LEDs

Function Documentation

◆ LED_Init()

void LED_Init ( void  )

Configures the pins for LED access, and switches the LEDs off.

Precondition
The IOCON block must have been initialized before. This is already taken care of by the board library initialization function Board_Init.
The GPIO block must have been initialized before. This is already taken care of by the board library initialization function Board_Init.
See also
Chip_IOCON_Init
Chip_GPIO_Init

◆ LED_SetState()

void LED_SetState ( int  leds,
int  states 
)

Sets all the LEDs for the given bits to the corresponding given states.

Parameters
leds: A mask identifying which LEDs to change state.
Note
bits set outside LED_ALL are ignored.
Parameters
states: A mask identifying the new state for the LEDs.
Note
bits set outside LED_ALL are ignored.
This is a low-level function, there are also high-level functions: LED_On, LED_Off, and LED_Toggle.

◆ LED_GetState()

int LED_GetState ( int  leds)

Gets the state of all the LEDs for the given bits.

Parameters
leds: A mask identifying which LEDs to retrieve state.
Note
bits set outside LED_ALL are ignored.
Returns
The i-th bit in the returned value is the state of LED i. If the i-th bit in leds is 0, the state is not retrieved from the hardware, and the returned bit is 0.

◆ LED_On()

void LED_On ( int  leds)

Turn on all LEDs for the given bits.

Parameters
leds: A mask identifying which LEDs to turn on.
Note
bits set outside LED_ALL are ignored.
This function is a shorthand for
LED_SetState(leds, leds)

◆ LED_Off()

void LED_Off ( int  leds)

Turn off all LEDs for the given bits.

Parameters
leds: A mask identifying which LEDs to turn off.
Note
bits set outside LED_ALL are ignored.
This function is a shorthand for
LED_SetState(leds, 0)

◆ LED_Toggle()

void LED_Toggle ( int  leds)

Toggle all LEDs for the given bits.

Parameters
leds: A mask identifying which LEDs to toggle state.
Note
bits set outside LED_ALL are ignored.
This function is a shorthand for
LED_SetState(leds, ~LED_GetState(leds))