Migrating NCP projects#

Migrating an NCP application is usually easy, since the stack and the application are well-separated. While the stack is running on the NCP target, the application is running on the NCP host. Therefore, a stack update usually does not affect the application except that the API changes must be respected.

An SDK update in the NCP use case means that:

  1. The NCP target device must be programmed with the Bluetooth Mesh - NCP Empty sample app of the new SDK.

  2. UART pins must be configured in the sample app.

  3. The GATT database must be imported in the sample app.

    Furthermore,

  4. The NCP host device must include the new BGAPI header files, so that it can communicate with the target.

  5. Deprecated API calls must be updated, if there are any.

Upgrading the NCP target code from Bluetooth Mesh SDK v1.x to v2.x is easy. A new Bluetooth Mesh - NCP Empty project must be generated with Bluetooth Mesh SDK v2.x. The UART pins can be easily configured with the Pin Tool, and the GATT database can be easily imported with the GATT Configurator. Should you use deep sleep mode in the NCP target, you must install the Wake Lock component and configure it. For more information about the NCP mode, see AN1259: Using the Silicon Labs v3.x Bluetooth® Stack in Network Co-Processor Mode.

The NCP host update involves more changes. After updating the header files, not only the full Bluetooth Mesh API has to be updated but also some BGLIB commands and macros.

An NCP host code using Bluetooth Mesh SDK v1.x must contain the following header files:

  • bg_errorcodes.h

  • bg_types.h

  • host_gecko.h

  • gecko_bglib.h

and the following source file:

  • gecko_bglib.c

An NCP host code using Bluetooth Mesh SDK v2.x must contain the following header files:

  • sl_status.h (in SDK_DIR/platform/common/inc)

  • sl_bt_types.h (in SDK_DIR/protocol/bluetooth/inc)

  • sl_bt_api.h (in SDK_DIR/protocol/bluetooth/inc)

  • sl_btmesh_api.h (in SDK_DIR/protocol/bluetooth/inc)

  • sl_bt_ncp_host.h (in SDK_DIR/protocol/bluetooth/inc)

and the following source files:

  • sl_bt_ncp_host_api.c (in SDK_DIR/protocol/bluetooth/src)

  • sl_bt_ncp_host.c (in SDK_DIR/protocol/bluetooth/src)

The new header files use the new nomenclature (commands/events starting with sl_bt_...) even if the underlying BGAPI packet content, which is sent to the target device via UART, may be unchanged in some cases. Therefore NCP host code must be completely updated according the description in Bluetooth Mesh API, using the new BGAPI.

Beside the changes in BGAPI (Bluetooth commands and events), the host API is also changed similarly to the changes in C API. The following table summarizes the changes in the host API:

Table Changes in the Host API

API 1.x

API 2.0

Notes

BGLIB_DEFINE

SL_BT_API_DEFINE

BGLIB_INITIALIZE

SL_BT_API_INITIALIZE

BGLIB_INITIALIZE_NONBLOCK

SL_BT_API_INITIALIZE_NONBLOCK

struct gecko_cmd_packet

sl_bt_msg_t

BGLIB_MSG_ID

SL_BT_MSG_ID

struct gecko_cmd_packet* gecko_wait_event()

sl_status_t sl_bt_wait_event(sl_bt_msg_t* evt)

In API 2.0, an event object is copied into the memory provided by application.

struct gecko_cmd_packet* gecko_peek_event()

sl_status_t sl_bt_pop_event(sl_bt_msg_t* evt)

int gecko_event_pending()

bool sl_bt_event_pending()

The NCP host code must be updated according to these changes. For example fetching an event changes from:

struct gecko_cmd_packet *p;
p = gecko_wait_event();
switch (BGLIB_MSG_ID(p->header)) {…}

to:

sl_bt_msg_t evt;
sl_bt_msg_t *p = &evt;
sl_bt_wait_event(&evt);
switch (SL_BT_MSG_ID(p->header)) {…}

Regarding the software architecture, the empty host example created for PCs (in <SDK_DIR>/app/bluetooth/example_host/empty) is updated to align with the new SoC software architecture. While it is not necessary to update the architecture on the NCP host, it is recommended to use this new architecture on newly created NCP host projects, so that it aligns with SoC code.