DK Buttons and LEDs

The DK Buttons and LEDs library is a simple module to interface with the buttons and LEDs on a Nordic Semiconductor development kit. It supports reading the state of up to four buttons or switches and controlling up to four LEDs.

Configuration

To enable the library in your project, set the CONFIG_DK_LIBRARY Kconfig option to y.

If you want to retrieve information about the button state, initialize the library with dk_buttons_init(). You can pass a callback function during initialization. This function is then called every time the button state changes.

If you want to control the LEDs on the development kit, initialize the library with dk_leds_init(). You can then set the value of a single LED, or set all of them to a state specified through bitmasks.

To use this library on your own hardware, see Use on non-DK boards below.

API documentation

Header file: include/dk_buttons_and_leds.h
Source files: lib/dk_buttons_and_leds/
group dk_buttons_and_leds

Defines

DK_NO_LEDS_MSK
DK_LED1
DK_LED2
DK_LED3
DK_LED4
DK_LED1_MSK
DK_LED2_MSK
DK_LED3_MSK
DK_LED4_MSK
DK_ALL_LEDS_MSK
DK_NO_BTNS_MSK
DK_BTN1
DK_BTN2
DK_BTN3
DK_BTN4
DK_BTN1_MSK
DK_BTN2_MSK
DK_BTN3_MSK
DK_BTN4_MSK
DK_ALL_BTNS_MSK

Typedefs

typedef void (*button_handler_t)(uint32_t button_state, uint32_t has_changed)

Callback that is executed when a button state change is detected.

Param button_state:

Bitmask of button states.

Param has_changed:

Bitmask that shows which buttons have changed.

Functions

int dk_leds_init(void)

Initialize the library to control the LEDs.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int dk_buttons_init(button_handler_t button_handler)

Initialize the library to read the button state.

Parameters:
  • button_handler – Callback handler for button state changes.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

void dk_button_handler_add(struct button_handler *handler)

Add a dynamic button handler callback.

In addition to the button handler function passed to dk_buttons_init, any number of button handlers can be added and removed at runtime.

Parameters:
  • handler[in] Handler structure. Must point to statically allocated memory.

int dk_button_handler_remove(struct button_handler *handler)

Remove a dynamic button handler callback.

Parameters:
  • handler[in] Handler to remove.

Return values:
  • 0 – Successfully removed the handler.

  • -ENOENT – This button handler was not present.

void dk_read_buttons(uint32_t *button_state, uint32_t *has_changed)

Read current button states.

Parameters:
  • button_state – Bitmask of button states.

  • has_changed – Bitmask that shows which buttons have changed.

uint32_t dk_get_buttons(void)

Get current button state from internal variable.

Returns:

Bitmask of button states.

int dk_set_leds(uint32_t leds)

Set value of LED pins as specified in one bitmask.

Parameters:
  • leds – Bitmask that defines which LEDs to turn on and off.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int dk_set_leds_state(uint32_t leds_on_mask, uint32_t leds_off_mask)

Set value of LED pins as specified in two bitmasks.

Parameters:
  • leds_on_mask – Bitmask that defines which LEDs to turn on. If this bitmask overlaps with leds_off_mask, leds_on_mask has priority.

  • leds_off_mask – Bitmask that defines which LEDs to turn off. If this bitmask overlaps with leds_on_mask, leds_on_mask has priority.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int dk_set_led(uint8_t led_idx, uint32_t val)

Set a single LED value.

This function turns a single LED on or off.

Parameters:
  • led_idx – Index of the LED.

  • val – Value for the LED: 1 - turn on, 0 - turn off

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int dk_set_led_on(uint8_t led_idx)

Turn a single LED on.

Parameters:
  • led_idx – Index of the LED.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int dk_set_led_off(uint8_t led_idx)

Turn a single LED off.

Parameters:
  • led_idx – Index of the LED.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

struct button_handler
#include <dk_buttons_and_leds.h>

Button handler list entry.

Public Members

button_handler_t cb

Callback function.

sys_snode_t node

Linked list node, for internal use.

Use on non-DK boards

You can define buttons and LEDs in your own board’s devicetree to use this library with custom hardware.

To define your own buttons, adapt this example to your board’s hardware in your board’s devicetree file. The example shows different ways to define buttons to show how to handle different hardware.

/ {
        buttons {
                compatible = "gpio-keys";
                /*
                 * Add up to 4 total buttons in child nodes as shown here.
                 */
                button0: button_0 {
                        /* Button 0 on P0.11. Enable internal SoC pull-up
                         * resistor and treat low level as pressed button. */
                        gpios = <&gpio0 11 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
                        label = "Button 0";
                };
                button1: button_1 {
                        /* Button 1 on P0.12. Enable internal pull-down resistor.
                         * Treat high level as pressed button. */
                        gpios = <&gpio0 12 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>;
                        label = "Button 1";
                };
                button2: button_2 {
                        /* Button 2 on P1.12, enable internal pull-up,
                         * low level is pressed. */
                        gpios = <&gpio1 12 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
                        label = "Button 2";
                };
                button3: button_3 {
                        /* Button 3 on P1.15, no internal pull resistor,
                         * low is pressed. */
                        gpios = <&gpio1 15 GPIO_ACTIVE_LOW>;
                        label = "Button 3";
                };
        };
};

To define your own LEDs, adapt this example:

/ {
        leds {
                compatible = "gpio-leds";
                led_0 {
                        /* LED 0 on P0.13, LED on when pin is high */
                        gpios = < &gpio0 13 GPIO_ACTIVE_HIGH >;
                        label = "LED 0";
                };
                led_1 {
                        /* LED 1 on P0.14, LED on when pin is low */
                        gpios = < &gpio0 14 GPIO_ACTIVE_LOW >;
                        label = "LED 1";
                };
                led_2 {
                        /* LED 2 on P1.0, on when low */
                        gpios = < &gpio1 0 GPIO_ACTIVE_LOW >;
                        label = "LED 2";
                };
                led_3 {
                        /* LED 3 on P1.1, on when high */
                        gpios = < &gpio1 1 GPIO_ACTIVE_HIGH >;
                        label = "LED 3";
                };
     };
};