Calling Softdevice API functions

[p143]

Hi.

I am working with an nRF52840. How should I call Softdevice API functions from my app?

and more precisely this GAP function: 

uint32_t

sd_ble_gap_tx_power_set (uint8_t role, uint16_t handle, int8_t tx_power)

In addition to this function call, is there any #include, initialization, or any other statement I should issue to get this function working?

Thanks

[awneil]

The SDK contains a wealth of examples illustrating how to call the SoftDevice - and other API - functions.

Specifically for sd_ble_gap_tx_power_set see also: 

https://devzone.nordicsemi.com/f/nordic-q-a/37928/just-set-tx-power

[p143]

" wealth of examples illustrating how to ..."

Hi awneil.

Just to make sure I understand the process, could you then mention just 2 or 3  SDK 15.2.0 examples calling the sd_ble_gap_tx_power_set API function?

Thanks

Juan

[awneil]

If https://devzone.nordicsemi.com/f/nordic-q-a/37928/just-set-tx-power is not sufficient, just do a text search (eg, grep) through the examples ...

[p143]

What do you mean by (eg, grep)? I am working in a Windows environment and a Segger IDE.

[wpaul]

SoftDevice APIs are in a sense logically separate from the rest of the SDK. Assume we're talking about the S140 BLE SoftDevice for the nRF52840. Within the SDK package, there is a components/softdevice/s140 directory. This contains a "hex" directory which includes the object code for the SoftDevice in .hex format and a "headers" directory which includes all of the .h files that define the APIs provided by the SoftDevice code.

Note also that components/softdevice/common contains some C files which basically contain "glue" code to interface the SoftDevice APIs to the rest of the SDK. The SDK itself provides various component libraries that facilitate using BLE and the various peripherals in the nRF52840 chip, and the SDK examples are built on top of all that.

The sd_ble_gap_tx_power_set() funcion is a GAP routine. The ble_gap.h file under components/softdevice/s140/headers contains the function prototype for all the GAP-related SoftDevice APIs and the various macros and structures that those APIs use. So you would need to include at least that header file, as well as ble.h and maybe one or two others.

Note that you can download the SoftDevice package from the Nordic website separately from the SDK. That package basically just includes the SoftDevice object code and headers described above, which makes it easier to see where the SoftDevice leaves off and the rest of the SDK begins.

Note also that these APIs are not just function calls. If you look at the headers closely, you'll see that they're defined using a special SVCALL() macro, which is defined in nrf_svc.h. They're actually implemented as system calls. When you call one, you're actually executing an ARM SVC instruction, which generates a system call trap. The SoftDevice has a trap handler which captures these taps, looks at the system call number, and then jumps to the right internal function to service it.

Lastly, some SoftDevice only  have meaning in certain states. For example, you can't call sd_ble_gap_tx_power_set() until you've also done sd_softdevice_enable() and sd_ble_enable() (along with some other dependent functions). The SDK libraries try to take of these things for you.

-Bill