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.

Note

If a configuration does not support Bluetooth (CONFIG_CAF_BLE_COMMON_EVENTS is disabled), the Bluetooth peer state will not be notified. In that case, the Bluetooth peer state LED is set only once during the boot. The set LED effect represents LED_PEER_STATE_DISCONNECTED state for the default peer.

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 a sink module for led_state.

For every board that has this option enabled, you must define the module configuration. The configuration must be defined in the file named CONFIG_DESKTOP_LED_STATE_DEF_PATH located in the board-specific directory in the application configuration directory. By default, the file is named as led_state_def.h.

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_ARG_PASS(...)

Pass a color value as a macro argument.

LED_COLOR macro contains commas in its body. This means that after the argument is expanded, the macro is to be treated as multiple arguments. This also makes it impossible to pass an argument from macro level to another macro. The macro allows the usage of the color argument as an argument to another macro level.

Parameters:

• ... – Any list of arguments that have to be treated as a single argument for the macro.

LED_COLOR(_r, _g, _b)

Create LED color initializer for LED turned on.

Note

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

Note

The macro returns the structure initializer that once expanded contains commas not placed in brackets. This means that when passed as an argument, this argument cannot be passed simply to another macro. Use LED_COLOR_ARG_PASS macro for the preprocessor to treat it as a single argument again.

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).

LED_EFFECT_LED_BLINK2(_period_on, _period_off, _color)

Create LED blinking effect initializer with two periods as arguments.

LED color is periodically changed between the selected color and the LED turned off. This macro takes two periods: for on and off time.

See also

LED_EFFECT_LED_BLINK

Parameters:

• _period_on – Period of time for which LED is on.

• _period_off – Period of time for which LED is off.

• _color – Selected LED color.

LED_EFFECT_LED_BLINK(_period, _color)

Create LED blinking effect initializer with one period given

LED color is periodically changed between the selected color and the LED turned off. The same time is used for both: on and off time.

See also

LED_EFFECT_LED_BLINK

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.

LED_CLOCK_BLINK_PERIOD

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

const struct led_effect_step *steps

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

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.