| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Board Support Package
SDK common libraries

BSP module. More...

## Modules
| BSP: BLE Button Module
| Module for controlling BLE behavior through button actions.
| BSP: ANT Button Module
| Module for controlling ANT behavior through button actions.
| NFC BSP Module
| Module for setting the NFCT peripheral as a wakeup source.

## Data Structures
struct | bsp_button_event_cfg_t

## Macros
#define | BSP_BUTTON_ACTION_PUSH (APP_BUTTON_PUSH)
#define | BSP_BUTTON_ACTION_RELEASE (APP_BUTTON_RELEASE)
#define | BSP_BUTTON_ACTION_LONG_PUSH (2)
#define | BUTTON_ERASE_BONDING BSP_BUTTON_0_MASK
#define | BUTTON_ERASE_ALL BSP_BUTTON_1_MASK
#define | BUTTON_ADVERTISE BSP_BUTTON_0_MASK
#define | BUTTON_CLEAR_EVT BSP_BUTTON_1_MASK
#define | BUTTON_CAPSLOCK BSP_BUTTON_2_MASK
#define | BSP_BUTTONS_ALL 0xFFFFFFFF
#define | BSP_BUTTONS_NONE 0
#define | BSP_INIT_NONE 0
| Types of BSP initialization. More...
#define | BSP_INIT_LED (1 << 0)
#define | BSP_INIT_BUTTONS (1 << 1)
#define | BSP_LONG_PUSH_TIMEOUT_MS (1000)
#define | BSP_INDICATIONS_LIST

## Typedefs
typedef uint8_t | bsp_button_action_t
typedef void(* | bsp_event_callback_t )(bsp_event_t)
| BSP module event callback function type. More...

## Enumerations
enum | bsp_indication_t { BSP_INDICATE_FIRST = 0, BSP_INDICATE_IDLE = BSP_INDICATE_FIRST, BSP_INDICATE_SCANNING, BSP_INDICATE_ADVERTISING, BSP_INDICATE_ADVERTISING_WHITELIST, BSP_INDICATE_ADVERTISING_SLOW, BSP_INDICATE_ADVERTISING_DIRECTED, BSP_INDICATE_BONDING, BSP_INDICATE_CONNECTED, BSP_INDICATE_SENT_OK, BSP_INDICATE_SEND_ERROR, BSP_INDICATE_RCV_OK, BSP_INDICATE_RCV_ERROR, BSP_INDICATE_FATAL_ERROR, BSP_INDICATE_ALERT_0, BSP_INDICATE_ALERT_1, BSP_INDICATE_ALERT_2, BSP_INDICATE_ALERT_3, BSP_INDICATE_ALERT_OFF, BSP_INDICATE_USER_STATE_OFF, BSP_INDICATE_USER_STATE_0, BSP_INDICATE_USER_STATE_1, BSP_INDICATE_USER_STATE_2, BSP_INDICATE_USER_STATE_3, BSP_INDICATE_USER_STATE_ON, BSP_INDICATE_LAST = BSP_INDICATE_USER_STATE_ON }
| BSP indication states. More...
enum | bsp_event_t { BSP_EVENT_NOTHING = 0, BSP_EVENT_DEFAULT, BSP_EVENT_CLEAR_BONDING_DATA, BSP_EVENT_CLEAR_ALERT, BSP_EVENT_DISCONNECT, BSP_EVENT_ADVERTISING_START, BSP_EVENT_ADVERTISING_STOP, BSP_EVENT_WHITELIST_OFF, BSP_EVENT_BOND, BSP_EVENT_RESET, BSP_EVENT_SLEEP, BSP_EVENT_WAKEUP, BSP_EVENT_DFU, BSP_EVENT_KEY_0, BSP_EVENT_KEY_1, BSP_EVENT_KEY_2, BSP_EVENT_KEY_3, BSP_EVENT_KEY_4, BSP_EVENT_KEY_5, BSP_EVENT_KEY_6, BSP_EVENT_KEY_7, BSP_EVENT_KEY_LAST = BSP_EVENT_KEY_7 }
| BSP events. More...

## Functions
uint32_t | bsp_init (uint32_t type, uint32_t ticks_per_100ms, bsp_event_callback_t callback)
| Function for initializing BSP. More...
uint32_t | bsp_buttons_state_get (uint32_t *p_buttons_state)
| Function for getting buttons states. More...
uint32_t | bsp_button_is_pressed (uint32_t button, bool *p_state)
| Function for checking buttons states. More...
uint32_t | bsp_event_to_button_action_assign (uint32_t button, bsp_button_action_t action, bsp_event_t event)
| Function for assigning a specific event to a button. More...
uint32_t | bsp_indication_set (bsp_indication_t indicate)
| Function for configuring indicators to required state. More...
uint32_t | bsp_indication_text_set (bsp_indication_t indicate, const char *p_text)
| Function for configuring indicators to required state. More...
uint32_t | bsp_buttons_enable (void)
| Function for enabling all buttons. More...
uint32_t | bsp_buttons_disable (void)
| Function for disabling all buttons. More...
uint32_t | bsp_wakeup_buttons_set (uint32_t wakeup_buttons)
| Function for configuring wakeup buttons before going into sleep mode. More...
uint32_t | bsp_wakeup_nfc_set (void)
| Function for configuring the NFCT peripheral as a wakeup source. More...

## Detailed Description

BSP module.

This module provides a layer of abstraction from the board. It allows the user to indicate certain states on LEDs in a simple way. Module functionality can be modified by additional defines:

- BSP_SIMPLE reduces functionality of this module to enable and read state of the buttons
- BSP_UART_SUPPORT enables support for UART

## Macro Definition Documentation

#define BSP_BUTTON_ACTION_LONG_PUSH (2)

Represents pushing and holding a button for BSP_LONG_PUSH_TIMEOUT_MS milliseconds. See also bsp_button_action_t.

#define BSP_BUTTON_ACTION_PUSH (APP_BUTTON_PUSH)

Represents pushing a button. See bsp_button_action_t.

#define BSP_BUTTON_ACTION_RELEASE (APP_BUTTON_RELEASE)

Represents releasing a button. See bsp_button_action_t.

#define BSP_INDICATIONS_LIST

Value:
{ \
"BSP_INDICATE_IDLE\r\n", \
"BSP_INDICATE_SCANNING\r\n", \
"BSP_INDICATE_ADVERTISING\r\n", \
"BSP_INDICATE_ADVERTISING_WHITELIST\r\n", \
"BSP_INDICATE_ADVERTISING_SLOW\r\n", \
"BSP_INDICATE_ADVERTISING_DIRECTED\r\n", \
"BSP_INDICATE_BONDING\r\n", \
"BSP_INDICATE_CONNECTED\r\n", \
"BSP_INDICATE_SENT_OK\r\n", \
"BSP_INDICATE_SEND_ERROR\r\n", \
"BSP_INDICATE_RCV_OK\r\n", \
"BSP_INDICATE_RCV_ERROR\r\n", \
"BSP_INDICATE_FATAL_ERROR\r\n", \
"BSP_INDICATE_ALERT_0\r\n", \
"BSP_INDICATE_ALERT_1\r\n", \
"BSP_INDICATE_ALERT_2\r\n", \
"BSP_INDICATE_ALERT_3\r\n", \
"BSP_INDICATE_ALERT_OFF\r\n", \
"BSP_INDICATE_USER_STATE_OFF\r\n", \
"BSP_INDICATE_USER_STATE_0\r\n", \
"BSP_INDICATE_USER_STATE_1\r\n", \
"BSP_INDICATE_USER_STATE_2\r\n", \
"BSP_INDICATE_USER_STATE_3\r\n", \
"BSP_INDICATE_USER_STATE_ON\r\n" \
}

See BSP indication states for a list of how these states are indicated for the PCA10028/PCA10040 board and the PCA10031 dongle.

#define BSP_INIT_BUTTONS (1 << 1)

This bit enables buttons during initialization (bsp_init).

#define BSP_INIT_LED (1 << 0)

This bit enables LEDs during initialization (bsp_init).

#define BSP_INIT_NONE 0

Types of BSP initialization.

This define specifies the type of initialization without support for LEDs and buttons (bsp_init).

#define BSP_LONG_PUSH_TIMEOUT_MS (1000)

The time to hold for a long push (in milliseconds).

## Typedef Documentation

typedef uint8_t bsp_button_action_t

The different actions that can be performed on a button.

typedef void(* bsp_event_callback_t)(bsp_event_t)

BSP module event callback function type.

Upon an event in the BSP module, this callback function will be called to notify the application about the event.

Parameters

  [in] | bsp_event_t | BSP event type.

## Enumeration Type Documentation

enum bsp_event_t

BSP events.

Note
  Events from BSP_EVENT_KEY_0 to BSP_EVENT_KEY_LAST are by default assigned to buttons.

Enumerator
BSP_EVENT_NOTHING | Assign this event to an action to prevent the action from generating an event (disable the action).
BSP_EVENT_DEFAULT | Assign this event to an action to assign the default event to the action.
BSP_EVENT_CLEAR_BONDING_DATA | Persistent bonding data should be erased.
BSP_EVENT_CLEAR_ALERT | An alert should be cleared.
BSP_EVENT_DISCONNECT | A link should be disconnected.
BSP_EVENT_ADVERTISING_START | The device should start advertising.
BSP_EVENT_ADVERTISING_STOP | The device should stop advertising.
BSP_EVENT_WHITELIST_OFF | The device should remove its advertising whitelist.
BSP_EVENT_BOND | The device should bond to the currently connected peer.
BSP_EVENT_RESET | The device should reset.
BSP_EVENT_SLEEP | The device should enter sleep mode.
BSP_EVENT_WAKEUP | The device should wake up from sleep mode.
BSP_EVENT_DFU | The device should enter DFU mode.
BSP_EVENT_KEY_0 | Default event of the push action of BSP_BUTTON_0 (only if this button is present).
BSP_EVENT_KEY_1 | Default event of the push action of BSP_BUTTON_1 (only if this button is present).
BSP_EVENT_KEY_2 | Default event of the push action of BSP_BUTTON_2 (only if this button is present).
BSP_EVENT_KEY_3 | Default event of the push action of BSP_BUTTON_3 (only if this button is present).
BSP_EVENT_KEY_4 | Default event of the push action of BSP_BUTTON_4 (only if this button is present).
BSP_EVENT_KEY_5 | Default event of the push action of BSP_BUTTON_5 (only if this button is present).
BSP_EVENT_KEY_6 | Default event of the push action of BSP_BUTTON_6 (only if this button is present).
BSP_EVENT_KEY_7 | Default event of the push action of BSP_BUTTON_7 (only if this button is present).

enum bsp_indication_t

BSP indication states.

See BSP indication states for a list of how these states are indicated for the PCA10028/PCA10040 board and the PCA10031 dongle.

Enumerator
BSP_INDICATE_IDLE | See BSP_INDICATE_IDLE.
BSP_INDICATE_SCANNING | See BSP_INDICATE_SCANNING.
BSP_INDICATE_ADVERTISING | See BSP_INDICATE_ADVERTISING.
BSP_INDICATE_ADVERTISING_WHITELIST | See BSP_INDICATE_ADVERTISING_WHITELIST.
BSP_INDICATE_ADVERTISING_SLOW | See BSP_INDICATE_ADVERTISING_SLOW.
BSP_INDICATE_ADVERTISING_DIRECTED | See BSP_INDICATE_ADVERTISING_DIRECTED.
BSP_INDICATE_BONDING | See BSP_INDICATE_BONDING.
BSP_INDICATE_CONNECTED | See BSP_INDICATE_CONNECTED.
BSP_INDICATE_SENT_OK | See BSP_INDICATE_SENT_OK.
BSP_INDICATE_SEND_ERROR | See BSP_INDICATE_SEND_ERROR.
BSP_INDICATE_RCV_OK | See BSP_INDICATE_RCV_OK.
BSP_INDICATE_RCV_ERROR | See BSP_INDICATE_RCV_ERROR.
BSP_INDICATE_FATAL_ERROR | See BSP_INDICATE_FATAL_ERROR.
BSP_INDICATE_ALERT_0 | See BSP_INDICATE_ALERT_0.
BSP_INDICATE_ALERT_1 | See BSP_INDICATE_ALERT_1.
BSP_INDICATE_ALERT_2 | See BSP_INDICATE_ALERT_2.
BSP_INDICATE_ALERT_3 | See BSP_INDICATE_ALERT_3.
BSP_INDICATE_ALERT_OFF | See BSP_INDICATE_ALERT_OFF.
BSP_INDICATE_USER_STATE_OFF | See BSP_INDICATE_USER_STATE_OFF.
BSP_INDICATE_USER_STATE_0 | See BSP_INDICATE_USER_STATE_0.
BSP_INDICATE_USER_STATE_1 | See BSP_INDICATE_USER_STATE_1.
BSP_INDICATE_USER_STATE_2 | See BSP_INDICATE_USER_STATE_2.
BSP_INDICATE_USER_STATE_3 | See BSP_INDICATE_USER_STATE_3.
BSP_INDICATE_USER_STATE_ON | See BSP_INDICATE_USER_STATE_ON.

## Function Documentation

uint32_t bsp_button_is_pressed | ( | uint32_t | button,
|  | bool * | p_state
| ) |  |

Function for checking buttons states.

This function checks if the button is pressed. If the button ID iss out of range, the function returns false.

Parameters

  [in] | button | Button ID to check.
  [in] | p_state | This variable will store the information whether the specified button is pressed (true) or not.

Return values

  NRF_SUCCESS | If the button state was successfully read.

uint32_t bsp_buttons_disable | ( | void |  | ) |

Function for disabling all buttons.

After calling this function, no buttons will generate events when pressed, and no buttons will be able to wake the system up from sleep mode.

Return values

  NRF_SUCCESS | If the buttons were successfully disabled.
  NRF_ERROR_NOT_SUPPORTED | If the board has no buttons or BSP_SIMPLE is defined.

Returns
  A propagated error.

uint32_t bsp_buttons_enable | ( | void |  | ) |

Function for enabling all buttons.

After calling this function, all buttons will generate events when pressed, and all buttons will be able to wake the system up from sleep mode.

Return values

  NRF_SUCCESS | If the buttons were successfully enabled.
  NRF_ERROR_NOT_SUPPORTED | If the board has no buttons or BSP_SIMPLE is defined.

Returns
  A propagated error.

uint32_t bsp_buttons_state_get | ( | uint32_t * | p_buttons_state | ) |

Function for getting buttons states.

This function allows to get the state of all buttons.

Parameters

  [in] | p_buttons_state | This variable will store buttons state. Button 0 state is represented by bit 0 (1=pressed), Button 1 state by bit 1, and so on.

Return values

  NRF_SUCCESS | If buttons state was successfully read.

uint32_t bsp_event_to_button_action_assign | ( | uint32_t | button,
|  | bsp_button_action_t | action,
|  | bsp_event_t | event
| ) |  |

Function for assigning a specific event to a button.

This function allows redefinition of standard events assigned to buttons. To unassign events, provide the event @ ref BSP_EVENT_NOTHING.

Parameters

  [in] | button | Button ID to be redefined.
  [in] | action | Button action to assign event to.
  [in] | event | Event to be assigned to button.

Return values

  NRF_SUCCESS | If the event was successfully assigned to button.
  NRF_ERROR_INVALID_PARAM | If the button ID or button action was invalid.

uint32_t bsp_indication_set | ( | bsp_indication_t | indicate | ) |

Function for configuring indicators to required state.

This function indicates the required state by means of LEDs (if enabled).

Note
  Alerts are indicated independently.

Parameters

  [in] | indicate | State to be indicated.

Return values

  NRF_SUCCESS | If the state was successfully indicated.
  NRF_ERROR_NO_MEM | If the internal timer operations queue was full.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized, or internal timer has not been created.

uint32_t bsp_indication_text_set | ( | bsp_indication_t | indicate,
|  | const char * | p_text
| ) |  |

Function for configuring indicators to required state.

This function indicates the required state by means of LEDs (if enabled) and UART (if enabled).

Note
  Alerts are indicated independently.

Parameters

  [in] | indicate | State to be indicated.
  [in] | p_text | Text to be output on UART.

Return values

  NRF_SUCCESS | If the state was successfully indicated.
  NRF_ERROR_NO_MEM | If the internal timer operations queue was full.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized, or timer has not been created.

uint32_t bsp_init | ( | uint32_t | type,
|  | uint32_t | ticks_per_100ms,
|  | bsp_event_callback_t | callback
| ) |  |

Function for initializing BSP.

The function initializes the board support package to allow state indication and button reaction. Default events are assigned to buttons.

Note
  Before calling this function, you must initiate the following required modules:
  - Application Timer for LED support
  - GPIOTE Handler for button support
  - UART module for UART support

Parameters

  [in] | type | Type of peripherals used.
  [in] | ticks_per_100ms | Number of RTC ticks for 100 ms.
  [in] | callback | Function to be called when button press/event is detected.

Return values

  NRF_SUCCESS | If the BSP module was successfully initialized.
  NRF_ERROR_INVALID_STATE | If the application timer module has not been initialized.
  NRF_ERROR_NO_MEM | If the maximum number of timers has already been reached.
  NRF_ERROR_INVALID_PARAM | If GPIOTE has too many users.
  NRF_ERROR_INVALID_STATE | If button or GPIOTE has not been initialized.

uint32_t bsp_wakeup_buttons_set | ( | uint32_t | wakeup_buttons | ) |

Function for configuring wakeup buttons before going into sleep mode.

After calling this function, only the buttons that are set to 1 in wakeup_buttons can be used to wake up the chip. If this function is not called before going to, sleep either all or no buttons can wake up the chip.

This function should only be called immediately before going into sleep.

Parameters

  [in] | wakeup_buttons | Mask describing which buttons should be able to wake up the chip.

Return values

  NRF_SUCCESS | If the buttons were successfully enabled.
  NRF_ERROR_NOT_SUPPORTED | If the board has no buttons or BSP_SIMPLE is defined.

uint32_t bsp_wakeup_nfc_set | ( | void |  | ) |

Function for configuring the NFCT peripheral as a wakeup source.

This function must be called before going to sleep, otherwise NFCT will not be able to wake up the chip.

Note
  You can use this function only if NFCT is not used for other purposes than wakeup.

This function should only be called immediately before going into sleep.

Return values

  NRF_SUCCESS | If NFCT peripheral was successfully enabled.
  NRF_ERROR_NOT_SUPPORTED | If the board has no NFCT peripheral or NRF52 is not defined.