API documentation

BLE Controller

group blectlr

Typedefs

typedef void (*host_signal_t)(void)

Host signal handler function pointer type.

Functions

void blectlr_assertion_handler(const char *const file, const uint32_t line)

Function prototype for the blectlr assertion handler. To be implemented by the application.

Note
The implementation of this function should not return. This function may be called from different interrupt priorities and should be preemptive or disable interrupts.
Parameters
  • file: The filename where the assertion occurred
  • line: The line number where the assertion occurred

uint32_t blectlr_init(host_signal_t host_signal)

Initialize the BLE Controller.

Parameters
  • host_signal: The host signal handler, this will be called by the BLE controller when data or event is available.
Return Value
  • NRF_SUCCESS: Initialized successfully
  • NRF_ERROR_NO_MEM: Not enough memory to support the current configuration.

void blectlr_signal(void)

Process all pending signals in the BLE Controller.

Note
The higher priority interrupts will notify that the signals are ready to be processed by setting the SWI5 IRQ pending.

void C_RADIO_Handler(void)

BLE Controller RADIO interrupt handler.

Note
This handler should be called from the ISR. The interrupt priority level should be priority 0.

void C_RTC0_Handler(void)

BLE Controller RTC0 interrupt handler.

Note
This handler should be called from the ISR. The interrupt priority level should be priority 0

void C_TIMER0_Handler(void)

BLE Controller TIMER0 interrupt handler.

Note
This handler should be called from the ISR The interrupt priority level should be priority 0

void C_RNG_Handler(void)

BLE Controller RNG interrupt handler.

Note
This handler should be called from the ISR. The interrupt priority level should be lower than priority 0.

void C_POWER_CLOCK_Handler(void)

BLE Controller POWER_CLOCK interrupt handler.

Note
This handler should be called from the ISR. The interrupt priority level should be lower than priority 0.

BLE Controller HCI

group blectlr_hci

Defines

HCI_CMD_HEADER_SIZE

The size of a command packet header.

HCI_DATA_HEADER_SIZE

The size of a data packet header.

HCI_EVENT_HEADER_SIZE

The size of an event packet header.

HCI_CMD_MAX_SIZE

The maximum size of a command.

HCI_DATA_MAX_SIZE

The maximum size of data.

HCI_EVENT_MAX_SIZE

The maximum size of an event.

HCI_CMD_PACKET_MAX_SIZE

The maximum size of an HCI command packet.

HCI_DATA_PACKET_MAX_SIZE

The maximum size of an HCI data packet.

HCI_EVENT_PACKET_MAX_SIZE

The maximum size of an HCI event packet.

HCI_MSG_BUFFER_MAX_SIZE

The maximum size of an HCI packet.

Typedefs

typedef uint8_t hci_element_t

HCI message packet element definition.

Functions

bool hci_cmd_packet_put(hci_element_t const *buffer)

Send an HCI command packet to the Controller.

Return
True if the HCI command is valid and was sent to the Controller
Parameters
  • buffer: HCI command packet in octet format according the HCI specification.

bool hci_data_packet_put(hci_element_t const *buffer)

Send an HCI data packet to the Controller.

Return
True if the HCI data is valid and was sent to the Controller
Parameters
  • buffer: HCI data packet in octet format according to the HCI specification.

bool hci_data_packet_get(hci_element_t *buffer)

Receive an HCI data packet from the Controller.

Return
True if a data packet was received from the Controller.
Parameters
  • buffer: HCI data packet in octet format according to the HCI specification.

bool hci_event_packet_get(hci_element_t *buffer)

Receive an HCI event packet from the Controller.

Return
True if an event packet was received from the Controller.
Parameters
  • buffer: HCI event packet in octet format according to the HCI specification.

BLE Controller utilities

group blectlr_util

Functions

void blectlr_set_default_evt_length(void)
void cal_init(void)
void soc_rand_prio_low_vector_get_blocking(uint8_t *p_buff, uint8_t length)
void ll_util_revcpy(uint8_t *dest, const uint8_t *src, uint8_t size)
void ll_util_block_encrypt(const uint8_t key[16], const uint8_t plaintext[16], bool is_result_le, uint8_t ciphertext[16])

nRF Errors

group NRF_ERRORS_BASE

Defines

NRF_ERROR_BASE_NUM

Global error base.

NRF_ERROR_SDM_BASE_NUM

SDM error base.

NRF_ERROR_SOC_BASE_NUM

SoC error base.

NRF_ERROR_STK_BASE_NUM

STK error base.

group NRF_ERRORS

Defines

NRF_SUCCESS

Successful command.

NRF_ERROR_SVC_HANDLER_MISSING

SVC handler is missing.

NRF_ERROR_SOFTDEVICE_NOT_ENABLED

SoftDevice has not been enabled.

NRF_ERROR_INTERNAL

Internal Error.

NRF_ERROR_NO_MEM

No Memory for operation.

NRF_ERROR_NOT_FOUND

Not found.

NRF_ERROR_NOT_SUPPORTED

Not supported.

NRF_ERROR_INVALID_PARAM

Invalid Parameter.

NRF_ERROR_INVALID_STATE

Invalid state, operation disallowed in this state.

NRF_ERROR_INVALID_LENGTH

Invalid Length.

NRF_ERROR_INVALID_FLAGS

Invalid Flags.

NRF_ERROR_INVALID_DATA

Invalid Data.

NRF_ERROR_DATA_SIZE

Invalid Data size.

NRF_ERROR_TIMEOUT

Operation timed out.

NRF_ERROR_NULL

Null Pointer.

NRF_ERROR_FORBIDDEN

Forbidden Operation.

NRF_ERROR_INVALID_ADDR

Bad Memory Address.

NRF_ERROR_BUSY

Busy.

NRF_ERROR_CONN_COUNT

Maximum connection count exceeded.

NRF_ERROR_RESOURCES

Not enough resources for operation.

nRF SoC

group NRF_SOC_DEFINES

Defines

NRF_RADIO_MINIMUM_TIMESLOT_LENGTH_EXTENSION_TIME_US

The minimum allowed timeslot extension time.

NRF_RADIO_MAX_EXTENSION_PROCESSING_TIME_US

The maximum processing time to handle a timeslot extension.

NRF_RADIO_MIN_EXTENSION_MARGIN_US

The latest time before the end of a timeslot the timeslot can be extended.

SD_EVT_IRQn

SoftDevice Event IRQ number. Used for both protocol events and SoC events.

SD_EVT_IRQHandler

SoftDevice Event IRQ handler. Used for both protocol events and SoC events. The default interrupt priority for this handler is set to 6

NRF_RADIO_LENGTH_MIN_US

The shortest allowed radio timeslot, in microseconds.

NRF_RADIO_LENGTH_MAX_US

The longest allowed radio timeslot, in microseconds.

NRF_RADIO_DISTANCE_MAX_US

The longest timeslot distance, in microseconds, allowed for the distance parameter (see nrf_radio_request_normal_t) in the request.

NRF_RADIO_EARLIEST_TIMEOUT_MAX_US

The longest timeout, in microseconds, allowed when requesting the earliest possible timeslot.

NRF_RADIO_START_JITTER_US

The maximum jitter in NRF_RADIO_CALLBACK_SIGNAL_TYPE_START relative to the requested start time.

group NRF_SOC_ENUMS

Enums

enum NRF_RADIO_CALLBACK_SIGNAL_TYPE

The Radio signal callback types.

Values:

NRF_RADIO_CALLBACK_SIGNAL_TYPE_START

This signal indicates the start of the radio timeslot.

NRF_RADIO_CALLBACK_SIGNAL_TYPE_TIMER0

This signal indicates the NRF_TIMER0 interrupt.

NRF_RADIO_CALLBACK_SIGNAL_TYPE_RADIO

This signal indicates the NRF_RADIO interrupt.

NRF_RADIO_CALLBACK_SIGNAL_TYPE_EXTEND_FAILED

This signal indicates extend action failed.

NRF_RADIO_CALLBACK_SIGNAL_TYPE_EXTEND_SUCCEEDED

This signal indicates extend action succeeded.

enum NRF_RADIO_SIGNAL_CALLBACK_ACTION

The actions requested by the signal callback.

This code gives the SOC instructions about what action to take when the signal callback has returned.

Values:

NRF_RADIO_SIGNAL_CALLBACK_ACTION_NONE

Return without action.

NRF_RADIO_SIGNAL_CALLBACK_ACTION_EXTEND

Request an extension of the current timeslot. Maximum execution time for this action: NRF_RADIO_MAX_EXTENSION_PROCESSING_TIME_US. This action must be started at least NRF_RADIO_MIN_EXTENSION_MARGIN_US before the end of the timeslot.

NRF_RADIO_SIGNAL_CALLBACK_ACTION_END

End the current radio timeslot.

NRF_RADIO_SIGNAL_CALLBACK_ACTION_REQUEST_AND_END

Request a new radio timeslot and end the current timeslot.

enum NRF_RADIO_HFCLK_CFG

Radio timeslot high frequency clock source configuration.

Values:

NRF_RADIO_HFCLK_CFG_XTAL_GUARANTEED

The SoftDevice will guarantee that the high frequency clock source is the external crystal for the whole duration of the timeslot. This should be the preferred option for events that use the radio or require high timing accuracy.

Note
The SoftDevice will automatically turn on and off the external crystal, at the beginning and end of the timeslot, respectively. The crystal may also intentionally be left running after the timeslot, in cases where it is needed by the SoftDevice shortly after the end of the timeslot.

NRF_RADIO_HFCLK_CFG_NO_GUARANTEE

This configuration allows for earlier and tighter scheduling of timeslots. The RC oscillator may be the clock source in part or for the whole duration of the timeslot. The RC oscillator’s accuracy must therefore be taken into consideration.

Note
If the application will use the radio peripheral in timeslots with this configuration, it must make sure that the crystal is running and stable before starting the radio.

enum NRF_RADIO_PRIORITY

Radio timeslot priorities.

Values:

NRF_RADIO_PRIORITY_HIGH

High (equal priority as the normal connection priority of the SoftDevice stack(s)).

NRF_RADIO_PRIORITY_NORMAL

Normal (equal priority as the priority of secondary activities of the SoftDevice stack(s)).

enum NRF_RADIO_REQUEST_TYPE

Radio timeslot request type.

Values:

NRF_RADIO_REQ_TYPE_EARLIEST

Request radio timeslot as early as possible. This should always be used for the first request in a session.

NRF_RADIO_REQ_TYPE_NORMAL

Normal radio timeslot request.

enum NRF_SOC_EVTS

SoC Events.

Values:

NRF_EVT_HFCLKSTARTED

Event indicating that the HFCLK has started.

NRF_EVT_POWER_FAILURE_WARNING

Event indicating that a power failure warning has occurred.

NRF_EVT_FLASH_OPERATION_SUCCESS

Event indicating that the ongoing flash operation has completed successfully.

NRF_EVT_FLASH_OPERATION_ERROR

Event indicating that the ongoing flash operation has timed out with an error.

NRF_EVT_RADIO_BLOCKED

Event indicating that a radio timeslot was blocked.

NRF_EVT_RADIO_CANCELED

Event indicating that a radio timeslot was canceled by SoftDevice.

NRF_EVT_RADIO_SIGNAL_CALLBACK_INVALID_RETURN

Event indicating that a radio timeslot signal callback handler return was invalid.

NRF_EVT_RADIO_SESSION_IDLE

Event indicating that a radio timeslot session is idle.

NRF_EVT_RADIO_SESSION_CLOSED

Event indicating that a radio timeslot session is closed.

NRF_EVT_POWER_USB_POWER_READY

Event indicating that a USB 3.3 V supply is ready.

NRF_EVT_POWER_USB_DETECTED

Event indicating that voltage supply is detected on VBUS.

NRF_EVT_POWER_USB_REMOVED

Event indicating that voltage supply is removed from VBUS.

NRF_EVT_NUMBER_OF_EVTS
group NRF_SOC_STRUCTURES

Typedefs

typedef volatile uint8_t nrf_mutex_t

Represents a mutex for use with the nrf_mutex functions.

Note
Accessing the value directly is not safe, use the mutex functions!

typedef nrf_radio_signal_callback_return_param_t *(*nrf_radio_signal_callback_t)(uint8_t signal_type)

The radio timeslot signal callback type.

Note
In case of invalid return parameters, the radio timeslot will automatically end immediately after returning from the signal callback and the NRF_EVT_RADIO_SIGNAL_CALLBACK_INVALID_RETURN event will be sent.
Note
The returned struct pointer must remain valid after the signal callback function returns. For instance, this means that it must not point to a stack variable.
Return
Pointer to structure containing action requested by the application.
Parameters
  • signal_type: Type of signal, see NRF_RADIO_CALLBACK_SIGNAL_TYPE.

Functions

uint32_t sd_evt_get(uint32_t *p_evt_id)

Gets any pending events generated by the SoC API.

The application should keep calling this function to get events, until NRF_ERROR_NOT_FOUND is returned.

Parameters
  • p_evt_id: Set to one of the values in NRF_SOC_EVTS, if any events are pending.
Return Value
  • NRF_SUCCESS: An event was pending. The event id is written in the p_evt_id parameter.
  • NRF_ERROR_NOT_FOUND: No pending events.

uint32_t sd_radio_session_open(nrf_radio_signal_callback_t p_radio_signal_callback)

Opens a session for radio timeslot requests.

Note
Only one session can be open at a time.
Note
p_radio_signal_callback(NRF_RADIO_CALLBACK_SIGNAL_TYPE_START) will be called when the radio timeslot starts. From this point the NRF_RADIO and NRF_TIMER0 peripherals can be freely accessed by the application.
Note
p_radio_signal_callback(NRF_RADIO_CALLBACK_SIGNAL_TYPE_TIMER0) is called whenever the NRF_TIMER0 interrupt occurs.
Note
p_radio_signal_callback(NRF_RADIO_CALLBACK_SIGNAL_TYPE_RADIO) is called whenever the NRF_RADIO interrupt occurs.
Note
p_radio_signal_callback() will be called at ARM interrupt priority level 0. This implies that none of the sd_* API calls can be used from p_radio_signal_callback().
Parameters
  • p_radio_signal_callback: The signal callback.
Return Value
  • NRF_ERROR_INVALID_ADDR: p_radio_signal_callback is an invalid function pointer.
  • NRF_ERROR_BUSY: If session cannot be opened.
  • NRF_ERROR_INTERNAL: If a new session could not be opened due to an internal error.
  • NRF_SUCCESS: Otherwise.

uint32_t sd_radio_session_close(void)

Closes a session for radio timeslot requests.

Note
Any current radio timeslot will be finished before the session is closed.
Note
If a radio timeslot is scheduled when the session is closed, it will be canceled.
Note
The application cannot consider the session closed until the NRF_EVT_RADIO_SESSION_CLOSED event is received.
Return Value
  • NRF_ERROR_FORBIDDEN: If session not opened.
  • NRF_ERROR_BUSY: If session is currently being closed.
  • NRF_SUCCESS: Otherwise.

uint32_t sd_radio_request(nrf_radio_request_t const *p_request)

Requests a radio timeslot.

Note
The request type is determined by p_request->request_type, and can be one of NRF_RADIO_REQ_TYPE_EARLIEST and NRF_RADIO_REQ_TYPE_NORMAL. The first request in a session must always be of type NRF_RADIO_REQ_TYPE_EARLIEST.
Note
For a normal request (NRF_RADIO_REQ_TYPE_NORMAL), the start time of a radio timeslot is specified by p_request->distance_us and is given relative to the start of the previous timeslot.
Note
A too small p_request->distance_us will lead to a NRF_EVT_RADIO_BLOCKED event.
Note
Timeslots scheduled too close will lead to a NRF_EVT_RADIO_BLOCKED event.
Note
See the SoftDevice Specification for more on radio timeslot scheduling, distances and lengths.
Note
If an opportunity for the first radio timeslot is not found before 100 ms after the call to this function, it is not scheduled, and instead a NRF_EVT_RADIO_BLOCKED event is sent. The application may then try to schedule the first radio timeslot again.
Note
Successful requests will result in nrf_radio_signal_callback_t(NRF_RADIO_CALLBACK_SIGNAL_TYPE_START). Unsuccessful requests will result in a NRF_EVT_RADIO_BLOCKED event, see NRF_SOC_EVTS.
Note
The jitter in the start time of the radio timeslots is +/- NRF_RADIO_START_JITTER_US us.
Note
The nrf_radio_signal_callback_t(NRF_RADIO_CALLBACK_SIGNAL_TYPE_START) call has a latency relative to the specified radio timeslot start, but this does not affect the actual start time of the timeslot.
Note
NRF_TIMER0 is reset at the start of the radio timeslot, and is clocked at 1MHz from the high frequency (16 MHz) clock source. If p_request->hfclk_force_xtal is true, the high frequency clock is guaranteed to be clocked from the external crystal.
Note
The SoftDevice will neither access the NRF_RADIO peripheral nor the NRF_TIMER0 peripheral during the radio timeslot.
Parameters
  • p_request: Pointer to the request parameters.
Return Value
  • NRF_ERROR_FORBIDDEN: Either:
  • NRF_ERROR_INVALID_ADDR: If the p_request pointer is invalid.
  • NRF_ERROR_INVALID_PARAM: If the parameters of p_request are not valid.
  • NRF_SUCCESS: Otherwise.

struct nrf_radio_request_earliest_t
#include <nrf_soc.h>

Parameters for a request for a timeslot as early as possible.

struct nrf_radio_request_normal_t
#include <nrf_soc.h>

Parameters for a normal radio timeslot request.

struct nrf_radio_request_t
#include <nrf_soc.h>

Radio timeslot request parameters.

struct nrf_radio_signal_callback_return_param_t
#include <nrf_soc.h>

Return parameters of the radio timeslot signal callback.