LED state module

The LED state module is used to set LED effects based on the Bluetooth® peer state and the system state.

Controlled LEDs

The module controls LEDs defined by enumerators in led_id:

  • LED_ID_SYSTEM_STATE - Shows the system state. The system can be in one of the following states:

    • LED_SYSTEM_STATE_IDLE - Device is not being charged.

    • LED_SYSTEM_STATE_CHARGING - Device is being charged.

    • LED_SYSTEM_STATE_ERROR - Fatal application error occurred (a module reported error state or battery state error was reported).

  • LED_ID_PEER_STATE - Shows the Bluetooth peer state. The Bluetooth peer can be in one of the following states:

    • LED_PEER_STATE_DISCONNECTED - Bluetooth peer is disconnected.

    • LED_PEER_STATE_CONNECTED - Bluetooth peer is connected.

    • LED_PEER_STATE_PEER_SEARCH - Device is looking for a peer, either by scanning or advertising.

    • LED_PEER_STATE_CONFIRM_SELECT - Bluetooth peer is being selected (the device is waiting for confirmation).

    • LED_PEER_STATE_CONFIRM_ERASE - Device is waiting for user confirmation to erase peers (for Bluetooth® Central) or start erase advertising (for Bluetooth® Peripheral).

    • LED_PEER_STATE_ERASE_ADV - Device is advertising for peer erase.

For the complete description of peer management, see Bluetooth LE bond module.

Module events

Source Module

Input Event

This Module

Output Event

Sink Module

Battery charger module

battery_state_event

led_state

Bluetooth LE advertising module

ble_peer_event

Bluetooth LE state module

Bluetooth LE bond module

ble_peer_operation_event

Bluetooth LE advertising module

ble_peer_search_event

Bluetooth LE scanning module

Source modules for module_state_event

module_state_event

led_event

LED stream module

LEDs module

Note

See the Overview: Firmware architecture for more information about the event-based communication in the nRF Desktop application and about how to read this table.

Configuration

The LED state module is enabled when you set the CONFIG_CAF_LEDS option. You must also configure CAF: LEDs module, which is used as sink module for led_state.

For every board that has this option enabled, you must define the module configuration. Do this in the led_state_def.h file located in the board-specific directory in the application configuration directory.

The configuration consists of the following elements:

  • led_map - Maps the led_id values to IDs used by CAF: LEDs module. If no physical LED is assigned to a led_id value, assign LED_UNAVAILABLE as the ID used by CAF: LEDs module.

  • led_system_state_effect - Defines the LED effects used to show the system states. The effect must be defined for every system state.

  • led_peer_state_effect - Defines the LED effects used to show the Bluetooth peer states. The effect must be defined for every state of every peer.

The LED effects are defined in the caf/led_effect.h file in the common configuration directory.

LED effect API

group led_effect_CAF

LED Effect.

Defines

COLOR_BRIGHTNESS_TO_PCT(_val)

Transform color brightness from 8-bit space to percentage representation.

Parameters

  • _val – Color brightness in 0-255 range

Returns

Color brightness in 0-100 range

LED_COLOR(_r, _g, _b)

Create LED color initializer for LED turned on.

Note

As arguments, pass the brightness levels for every color channel.

LED_NOCOLOR()

Create LED color initializer for LED turned off.

LED_EFFECT_LED_ON(_color)

Create LED turned on effect initializer.

LED color remains constant.

Parameters

  • _color – Selected LED color.

LED_EFFECT_LED_OFF()

Create LED turned off effect initializer.

LED_EFFECT_LED_ON_GO_OFF(_color, _on_time, _off_delay)

Create LED turned on for a brief period effect initializer.

LED color remains constant for a defined time, then goes off.

Parameters

  • _color – Selected LED color.

  • _on_time – Time LED will remain on in milliseconds.

  • _off_delay – Time in which LED will gradually switch to off (in milliseconds).

Create LED blinking effect initializer.

LED color is periodically changed between the selected color and the LED turned off.

Parameters

  • _period – Period of time between LED color switches.

  • _color – Selected LED color.

LED_EFFECT_LED_BREATH(_period, _color)

Create LED breathing effect initializer.

LED color is smoothly, gradually changed between the LED turned off and the selected color.

Parameters

  • _period – Period of time for single substep.

  • _color – Selected LED color.

Period of time between color changes while the LED is blinking (LED clock effect).

LED_CLOCK_SLEEP_PERIOD

Period of time when the LED is turned off (LED clock effect).

LED_EFFECT_LED_CLOCK(_ticks, _color)

Create LED clock effect initializer.

LED blinks a defined number of times, then it is turned off for a defined period of time. The sequence is repeated periodically.

Note

You can pass only one additional argument to the UTIL_LISTIFY macro, which in this case is LED color. Period is defined separately.

Parameters

  • _ticks – Number of ticks.

  • _color – Selected LED color.

struct led_color
#include <led_effect.h>

Color of LED.

Public Members

uint8_t c[3]

Values for color channels.

struct led_effect_step
#include <led_effect.h>

Single step of a LED effect.

During a single step, color of LED changes from the color before the step to the color defined in the step. The color update may be done in multiple substeps to achieve smooth, gradual change.

Public Members

struct led_color color

LED color at the end of the step.

uint16_t substep_count

Number of substeps.

uint16_t substep_time

Duration of a single substep.

struct led_effect
#include <led_effect.h>

Single LED effect.

Public Members

uint16_t step_count

Number of steps for the given effect.

bool loop_forever

Flag that indicates if the sequence should start again after it finishes.

const struct led_effect_step *steps

Sequence of LED color changes. It is defined by subsequent steps.