SoC Mode vs NCP Mode

The Bluetooth SDK supports two developing modes, System-On-Chip (SoC) and Network Co-Processor (NCP). For SoC mode, all the application will run on a single EFR32 device. For NCP mode, a EFR32 device acts as the coprocessor, working together with a host controller. AN1042: Using the Silicon Labs Bluetooth® Stack in Network Co-Processor Mode has detailed description of the NCP mode. It’s recommended to read this application note before reading this article, which can give you a better understanding of NCP mode.

Figure 1. SoC Mode

Figure 2. NCP Mode

BGLib and BGAPI

• BGAPI is a custom binary protocol used to externally control our chipset and modules. BGAPI is a protocol specification only.
• BGLib is an ANSI C reference implementation of the BGAPI binary protocol. BGLib only runs outside of our chipset and modules. BGLib assumes the host MCU is little-endian.

When using SoC mode, it allows you to run an application right on the chipset or module and call the BGAPI directly. However, if using the NCP mode, the application runs on an external device – typically a microcontroller, everything can communicate over UART between the NCP host and NCP target.

BGLIB_DEFINE

BGLib uses a set of global variables that are defined using macro BGLIB_DEFINE(), found in gecko_bglib.h. The host application that uses BGLib must include BGLIB_DEFINE() in global scope (i.e. it must be placed outside any function implementation).

BGLIB_DEFINE() is used to declare variables used for BGLib, it must be define globally.

#define BGLIB_DEFINE()                                      \
  struct gecko_cmd_packet _gecko_cmd_msg;                   \
  struct gecko_cmd_packet _gecko_rsp_msg;                   \
  struct gecko_cmd_packet *gecko_cmd_msg = &_gecko_cmd_msg; \
  struct gecko_cmd_packet *gecko_rsp_msg = &_gecko_rsp_msg; \
  void (*bglib_output)(uint32_t len1, uint8_t* data1);      \
  int32_t (*bglib_input)(uint32_t len1, uint8_t* data1);    \
  int32_t (*bglib_peek)(void);                              \
  struct gecko_cmd_packet gecko_queue[BGLIB_QUEUE_LEN];     \
  int    gecko_queue_w = 0;                                 \
  int    gecko_queue_r = 0;

• _gecko_cmd_msg – The instance to store the command message.
• _gecko_rsp_msg – The instance to store the response message.
• gecko_cmd_msg – Pointer to _gecko_cmd_msg instance.
• gecko_rsp_msg – Pointer to _gecko_rsp_msg instance.
• gecko_queue[BGLIB_QUEUE_LEN] – FIFO buffer to store the messages received from the NCP target.
• gecko_queue_w – FIFO buffer write index, working with gecko_queue_r to indicate if there is new message stored in the queue, it offsets by one if a new message is received.
• gecko_queue_r – FIFO buffer read index, working with gecko_queue_w to indicate if there is new message stored in the queue, it offsets by one if a new message is read out from the queue.
• bglib_output, bglib_input, bglib_peek – Function pointers to writing to / reading from / peek UART.

The symbol BGLIB_QUEUE_LEN defines the length of queue, it’s 30 by default and depends on the real use cases and allowed host memory usage.

Operation Modes

• Blocking mode – If this mode is used, BGLib will get blocked in waiting events from NCP target if there is no data to send nor events to handle. To use this mode, use gecko_wait_event() to check events and call the function BGLIB_INITIALIZE(OFUNC, IFUNC) in your initialization code.
• Nonblocking mode – If this mode is used, BGLib will not get blocked if there is no data to send nor data to receive. To use this mode, use gecko_peek_event() to check events and call the function BGLIB_INITIALIZE_NONBLOCK(OFUNC, IFUNC, PFUNC) in your initialization code.

It depends on the real use case which mode should be used. If there are many tasks not related to Bluetooth, nonblocking mode should be a better choice, because it will bypass the BGLib functions if there are no Bluetooth events to be handled and allows the MCU to process other tasks. The reason BGLib supports blocking mode is for symmetry purpose that the same code should work in both SoC and NCP modes, it’s recommended to use nonblocking mode because it gives the user better control of their application in most of the use cases.

Figure 3. Blocking vs Nonblocking

Function Mapping

Below functions are used to read from and write to UART. BGLib accesses UART through function pointers so that the code is platform independent. User must map the function pointers to platform-specific UART transmit / receive routines when initializing BGLIb. This is done using macro BGLIB_INITIALIZE() or BGLIB_INITIALIZE_NONBLOCK(), depending if blocking or non-blocking mode is used.

• void(*bglib_output)(uint32_t len1, uint8_t* data1);

This is the callback function to send “len1” amount of data out via UART

• int32_t (*bglib_input)(uint32_t len1, uint8_t* data1);

This is the callback function to receive “len1” amount of data via UART

• int32_t(*bglib_peek)(void);

This is only required if using the nonblocking mode, this function is to peek the UART if there is any data valid.

How BGLib works?

Below 3 flowcharts show how BGLib works in details.

Figure 4. Flowchart of Nonblocking function calling

Figure 5. Flowchart of blocking function calling

Figure 6. Flowchart of API calling

Adding BGLib to Host MCU Project

Preparation

• Install Simplicity Studio 4 to your PC
• Install Bluetooth SDK 2.7.0, which is available from the software update of Simplicity Studio 4

Below is the step by step guide to add BGLib to a host MCU project.

• Create a base project of the specified MCU.
• There are some source and header files need to be added to the project, shown as below.
  • C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.1\protocol\bluetooth_2.7\ble_stack\inc\common
    • bg_errorcodes.h
    • bg_gattdb_def.h
    • bg_types.h
    • gecko_configuration.h
  • C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.1\protocol\bluetooth_2.7\ble_stack\inc\host
    • gecko_bglib.h
    • host_gecko.h
  • C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.1\protocol\bluetooth_2.7\ble_stack\src\host
    • gecko_bglib.c
• Implement the callback functions mentioned above.
• Add “BGLIB_DEFINE();” to the macro definition area in your project.
• Add BGLIB_INITIALIZE(user_output, user_input) or BGLIB_INITIALIZE_NONBLOCK(user_output, user_input, user_peek) to the initialization code, after that, it’s recommended to call gecko_cmd_system_reset(0); function to reset the NCP target.
• Add below template to the while loop to handle all the events received from NCP target.

static void appHandleEvents(struct gecko_cmd_packet *evt) {
	if (NULL == evt) {
		return;
	}

	/* Handle events */
	switch (BGLIB_MSG_ID(evt->header)) {
		case xxx:
		break;
		case xxx:
		break;

		…

		default:
		break;
	}
}

While(1){
    ...
    /* Check for stack event. */
    evt = gecko_peek_event();
	/* Run application and event handler. */
	appHandleEvents(evt);
	...
}

Example

Contents

Attachment is an example running on EFR32PG1 kit – BRD2500 Rev A01 (NCP host) and EFR32BG13 kit – BRD4104a Rev A00 (NCP target).

• KBA_ncp_host_pg – Project for NCP host
• KBA_ncp_host_example – Project for NCP target
• KBA_ncp_host_pg.map – Map file of the KBA_ncp_host_pg project under compiler IAR and high size optimization.

UART configuration

• Baud rate: 115200
• Data bits: 8
• Stop bit: 1
• Flow control: False
• NCP host (EFR32PG1) UART pin configuration
  • TX pin – PD10, EXP_HEADER 9
  • RX pin – PD11, EXP_HEADER 11
• NCP target (EFR32BG13) UART pin configuration
  • TX pin – PA0, EXP_HEADER 12
  • RX pin – PA1, EXP_HEADER 14

Connection between NCP host and NCP target is shown below, see figure 5.

NCP host expansion header                                NCP target expansion header

         GND                                                       GND

PIN 9 (PD10) – UART TX                                    PIN 14 (PA1) – UART RX

PIN 11 (PD11) – UART RX                                   PIN 12 (PA0) – UART TX

Figure 7. Connection between NCP host and target

Verifying the example

This example uses the nonblocking mode. You can import them to your Simplicity Studio, compile and download to your devices. The example is a very simple one, which only provides the skeleton showing the usage of both NCP host and NCP target. You can verify the example using a smartphone to scan and connect to it. It will advertise after boot or disconnected.

Memory Usage

GBGLib needs RAM for the variables defined in BGLIB_DEFINE(); as well as flash, below is the detailed RAM and flash usage of the example, the compiler is IAR with “High size” optimization.

    Module                 ro code  ro data  rw data

    ------                 -------  -------  -------

C:\Users\zhfu\SimplicityStudio\v4_mesh_mcu\KBA_ncp_host_pg\IAR ARM - Debug\CMSIS\EFM32PG1B: [1]

    startup_efm32pg1b.o        348

    system_efm32pg1b.o         136       16       16

    ------------------------------------------------

    Total:                     484       16       16

C:\Users\zhfu\SimplicityStudio\v4_mesh_mcu\KBA_ncp_host_pg\IAR ARM - Debug\emlib: [2]

    em_cmu.o                   756        4        4

    em_gpio.o                  156

    em_system.o                 52

    em_usart.o                 340

    ------------------------------------------------

    Total:                   1 304        4        4

C:\Users\zhfu\SimplicityStudio\v4_mesh_mcu\KBA_ncp_host_pg\IAR ARM - Debug\src: [3]

    app.o                      400       20    8 348

    gecko_bglib.o              336

    main.o                     116

    ------------------------------------------------

Total:                     852       20    8 348

RAM

The RAM usage for the unit gecko_cmd_packet is 0x104. For 32-bit MCU, each point occupies 4-byte. The length of the queue is 30, so it takes 0x104 * 30 = 0x1e78.

Total = 0x104 * 2 + 0x4 * 7 + 0x1e78 = 0x209c = 8348 bytes

Flash

The total flash of the example is 484+1304+852= 2640 bytes. They can be split by functionalities.

• Basic part - It is required for any EFM32PG1 projects. startup_efm32pg1b.o, system_efm32pg1b.o and main.o and em_system.o, the flash occupation is 484+116+52 = 652 bytes. This part is platform-specific.
• UART related part -  Driver of UART. em_cmu.o, em_gpio.o and em_usart.o, the flash occupation is 756+156+340 = 1252 bytes. This part is platform-specific.
• BGLib and application part – App.o has the basic skeleton of the Bluetooth event handler, which is the minimal requirement of application. The flash occupation is 400+336 = 736 bytes.