doc: sdh: extend documentation #515

lemrey · 2025-11-26T14:24:10Z

Extend SoftDevice handler documentation.

github-actions · 2025-11-26T14:25:20Z

You can find the documentation preview for this PR here.

doc/nrf-bm/libraries/nrf_sdh.rst

Extend SoftDevice handler documentation. Signed-off-by: Emanuele Di Santo <[email protected]>

peknis · 2025-11-27T14:19:06Z

doc/nrf-bm/libraries/nrf_sdh.rst

+Usage
+*****
+
+The SoftDevice handler API can be used to declare observers, changing the SoftDevice state, and enabling the SoftDevice Bluetooth stack.


Suggested change

The SoftDevice handler API can be used to declare observers, changing the SoftDevice state, and enabling the SoftDevice Bluetooth stack.

You can use the SoftDevice handler API to declare observers, change the SoftDevice state, and enable the SoftDevice Bluetooth stack.

peknis · 2025-11-27T14:19:46Z

doc/nrf-bm/libraries/nrf_sdh.rst

+Declaring observers
+===================
+
+You can declare an observer in any part of your application by using a macro and specifying an event handler function, an optional parameter and a priority.


Suggested change

You can declare an observer in any part of your application by using a macro and specifying an event handler function, an optional parameter and a priority.

You can declare an observer in any part of your application by using a macro and specifying an event handler function, an optional parameter, and a priority.

peknis · 2025-11-27T14:20:00Z

doc/nrf-bm/libraries/nrf_sdh.rst

+* :c:enumerator:`NRF_SDH_STATE_EVT_ENABLED` - SoftDevice is enabled.
+* :c:enumerator:`NRF_SDH_STATE_EVT_BLE_ENABLED` -  Bluetooth is enabled.
+* :c:enumerator:`NRF_SDH_STATE_EVT_DISABLE_PREPARE` - SoftDevice is going to be disabled.
+* :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` - SoftDevice is disabled


Suggested change

* :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` - SoftDevice is disabled

* :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` - SoftDevice is disabled.

peknis · 2025-11-27T14:20:23Z

doc/nrf-bm/libraries/nrf_sdh.rst

+
+A state observer is declared using the :c:macro:`NRF_SDH_STATE_EVT_OBSERVER` macro.
+
+The following snippet shows how to declare a state observer.


Suggested change

The following snippet shows how to declare a state observer.

The following snippet shows how to declare a state observer:

peknis · 2025-11-27T14:20:47Z

doc/nrf-bm/libraries/nrf_sdh.rst

+
+A Bluetooth observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.
+
+The following snippet shows how to declare a Bluetooth observer.


Suggested change

The following snippet shows how to declare a Bluetooth observer.

The following snippet shows how to declare a Bluetooth observer:

peknis · 2025-11-27T14:26:24Z

doc/nrf-bm/libraries/nrf_sdh.rst

+The observers can return ``0`` from the event handler to let the SoftDevice change the state, or return a non-zero value to halt the SoftDevice state change.
+When an observer returns non-zero to the :c:enumerator:`NRF_SDH_STATE_EVT_DISABLE_PREPARE` event, it must call the :c:func:`nrf_sdh_observer_ready` function when it becomes ready for the SoftDevice state change.
+
+When the last state observer becomes ready for the SoftDevice state change, the SoftDevice changes the state and the :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` event is sent.


Suggested change

When the last state observer becomes ready for the SoftDevice state change, the SoftDevice changes the state and the :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` event is sent.

When the last state observer is ready for the SoftDevice state change, the state is changed and the :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` event is sent.

peknis · 2025-11-27T14:27:18Z

doc/nrf-bm/libraries/nrf_sdh.rst

+Fault handling
+==============
+
+You can override the SoftDevice fault handler function by defining the following function, as shown in the snippet below:


Suggested change

You can override the SoftDevice fault handler function by defining the following function, as shown in the snippet below:

You can override the SoftDevice fault handler function by defining the following function:

peknis · 2025-11-27T14:28:43Z

doc/nrf-bm/libraries/nrf_sdh.rst

+A Bluetooth observer receives Bluetooth events coming from the SoftDevice.
+
+A Bluetooth observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.


Suggested change

A Bluetooth observer receives Bluetooth events coming from the SoftDevice.

A Bluetooth observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

A Bluetooth observer receives Bluetooth events coming from the SoftDevice and is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

peknis · 2025-11-27T14:29:13Z

doc/nrf-bm/libraries/nrf_sdh.rst

+An SoC observer receives SoC events coming from the SoftDevice.
+
+An SoC observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.


Suggested change

An SoC observer receives SoC events coming from the SoftDevice.

An SoC observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

An SoC observer receives SoC events coming from the SoftDevice and is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

peknis · 2025-11-27T14:30:01Z

doc/nrf-bm/libraries/nrf_sdh.rst

+The SoftDevice handler has several options to control the clock configuration passed to the :c:func:`sd_softdevice_enable` function.
+
+These options are used automatically when you enable the SoftDevice by calling the :c:func:`nrf_sdh_enable_request` function.


Suggested change

The SoftDevice handler has several options to control the clock configuration passed to the :c:func:`sd_softdevice_enable` function.

These options are used automatically when you enable the SoftDevice by calling the :c:func:`nrf_sdh_enable_request` function.

The SoftDevice handler has several options to control the clock configuration passed to the :c:func:`sd_softdevice_enable` function.

These options are used automatically when you enable the SoftDevice by calling the :c:func:`nrf_sdh_enable_request` function.

lemrey requested review from a team as code owners November 26, 2025 14:24

github-actions bot added changelog-entry-required Update changelog before merge. Remove label if entry is not needed or already added. doc-required PR must not be merged without tech writer approval. labels Nov 26, 2025

peknis requested changes Nov 27, 2025

View reviewed changes

lemrey force-pushed the sdh-doc branch 3 times, most recently from 02292f2 to 6df3bcb Compare November 27, 2025 14:08

doc: sdh: extend documentation

4b71ab3

Extend SoftDevice handler documentation. Signed-off-by: Emanuele Di Santo <[email protected]>

lemrey force-pushed the sdh-doc branch from 6df3bcb to 4b71ab3 Compare November 27, 2025 14:14

peknis requested changes Nov 27, 2025

View reviewed changes

	The SoftDevice handler API can be used to declare observers, changing the SoftDevice state, and enabling the SoftDevice Bluetooth stack.
	You can use the SoftDevice handler API to declare observers, change the SoftDevice state, and enable the SoftDevice Bluetooth stack.

	You can declare an observer in any part of your application by using a macro and specifying an event handler function, an optional parameter and a priority.
	You can declare an observer in any part of your application by using a macro and specifying an event handler function, an optional parameter, and a priority.

	* :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` - SoftDevice is disabled
	* :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` - SoftDevice is disabled.


		A state observer is declared using the :c:macro:`NRF_SDH_STATE_EVT_OBSERVER` macro.

		The following snippet shows how to declare a state observer.


		A Bluetooth observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

		The following snippet shows how to declare a Bluetooth observer.

	When the last state observer becomes ready for the SoftDevice state change, the SoftDevice changes the state and the :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` event is sent.
	When the last state observer is ready for the SoftDevice state change, the state is changed and the :c:enumerator:`NRF_SDH_STATE_EVT_DISABLED` event is sent.

	You can override the SoftDevice fault handler function by defining the following function, as shown in the snippet below:
	You can override the SoftDevice fault handler function by defining the following function:

		A Bluetooth observer receives Bluetooth events coming from the SoftDevice.

		A Bluetooth observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

		An SoC observer receives SoC events coming from the SoftDevice.

		An SoC observer is declared using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro.

		The SoftDevice handler has several options to control the clock configuration passed to the :c:func:`sd_softdevice_enable` function.

		These options are used automatically when you enable the SoftDevice by calling the :c:func:`nrf_sdh_enable_request` function.

doc: sdh: extend documentation #515

Are you sure you want to change the base?

doc: sdh: extend documentation #515

Conversation

lemrey commented Nov 26, 2025

Uh oh!

github-actions bot commented Nov 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants