Getting Started with Silicon Labs BGAPI: How Can a Linux Host Control a Bluetooth Mesh Module over UART?

Connect a Linux host to Silicon Labs Bluetooth Mesh NCP: align firmware and XAPI, check UART flow control and boot events, then distinguish node and provisioner roles.

In an earlier article about choosing a Bluetooth Mesh gateway chip, I mentioned one division of responsibilities: the Linux host handles application logic, the Silicon Labs module handles the wireless protocol stack, and the two communicate over a serial port.

That sounds simple enough in one sentence. But when you start connecting the pieces, it is easy to get stuck at “the serial port opens, but the module does not respond to commands.”

The problem is often not a missing magic command to turn on a light. Instead, several prerequisites have not been aligned: the firmware flashed onto the module, the API definitions used by the host, serial flow control, and the Mesh device’s role in the network.

Starting from the official NCP documentation and Python examples, this article breaks down that connection. This is an integration guide grounded in source code; it does not report hardware testing or end-to-end debugging on a development board. Check the specific pins, baud rate, and firmware components against your hardware and SDK.

The Linux Host Controls an Entry Point to the Protocol Stack

In NCP, or network co-processor, mode, application logic runs on the host while the Bluetooth protocol stack runs on the target chip. Silicon Labs uses BGAPI to define commands, responses, and events between them, with UART being a common transport.[1][2]

You can think of the path as:

Linux application → BGAPI host library → serial port → Silicon Labs NCP firmware → Bluetooth Mesh network.

BGAPI is Silicon Labs’ host interface protocol. It is neither the over-the-air Mesh protocol nor a set of AT commands that any Bluetooth serial module will understand.

After the host sends a command, the target returns a response and may also report events asynchronously. You cannot simply write a loop that “sends bytes and sleeps for one second,” then treat the absence of an exception as proof that the operation completed.

There are also different levels of completion: successfully writing to the serial port, the target accepting the command, the Mesh peer returning a status, and the light actually changing are not the same result. Troubleshooting logs should record these levels separately.

Step One: Confirm That the Firmware and Host API Match

A chip model supporting Bluetooth does not mean the firmware currently flashed onto it provides the Mesh NCP capabilities you need.

The official pyBGAPI examples distinguish ordinary Bluetooth examples from Bluetooth Mesh examples. The Mesh examples use two API definitions, sl_bt.xapi and sl_btmesh.xapi. Ordinary BLE firmware, Mesh node firmware, and firmware intended for provisioning management are not interchangeable just because they all carry the term “NCP.”[1]

XAPI describes how the host library encodes commands and parses returned data. If the target firmware and host API definitions do not match, you may encounter unsupported commands, missing parameters, or parsing errors. The official examples compare some version information at startup and print a warning, but that warning check is no substitute for a full compatibility check.

Before starting, it helps to write down four things:

  1. The development board and chip model, and the hardware interface in use.
  2. The firmware example name, SDK version, and enabled Mesh components.
  3. The host program version, the source of the API definition files, and the Python library version.
  4. The intended role: a node to be provisioned, or a Provisioner that manages other nodes.

This short checklist is more useful than repeatedly upgrading every component after something goes wrong. An upgrade may change interfaces; you cannot assume that the newest host library will always work with older firmware.

Step Two: Align UART and Flow Control

The existence of a serial device node only tells you that Linux has detected a serial interface. It does not tell you that the target firmware is ready.

Before wiring, check the board documentation for signal levels, ground, TX/RX, and RTS/CTS if hardware flow control is enabled. Do not connect an RS-232-level interface directly to chip UART pins. If you are using a development board’s virtual serial port, also check the onboard debugger’s serial configuration.

The older AN1259 NCP example enables hardware flow control by default and specifically emphasizes that the target and development board flow-control settings must match.[2] This can explain a common symptom: the serial port opens, but data does not move forward because one side is waiting for flow-control signals from the other.

That does not make “all BGAPI interfaces require four wires” a protocol rule. The transport and flow-control configuration depend on the firmware and hardware. The recommendation here is that, if you start from an example with RTS/CTS enabled by default, you should initially retain and match that complete configuration. Do not connect only the two data wires while leaving the software waiting for flow control.

Also confirm that a terminal program and the application process are not using the serial port at the same time, and that the current user has access permission. If you encounter a permissions problem, check the device permissions and user groups first; do not treat running as root indefinitely as the default fix.

Step Three: Verify the Startup Path with the Official Minimal Example

The official pybgapi-examples commit examined for this article is 87d004f.[1] Pinning a commit helps with reproducibility, but this commit does not itself guarantee compatibility with every SDK you may have. First check its included API definitions against the target firmware.

In a new local directory, you can prepare an isolated Python environment and inspect the example’s arguments:

git clone https://github.com/SiliconLabs/pybgapi-examples.git
cd pybgapi-examples
git checkout 87d004f1db3993bfa35783bec1ac58c32b5303e4
python3 -m venv .venv
. .venv/bin/activate
python -m pip install pybgapi
python example/btmesh_empty/app.py -h

After installation succeeds, record the library version that was actually installed. No unverified “universal version combination” is offered here. If the SDK does not match, use the examples and API files supplied for your firmware, then check the interfaces again.

Once you have confirmed that you are using a test board that can be rebooted, that the firmware matches, and that the serial configuration is consistent, the official example accepts a serial port as a positional argument, for example:

python example/btmesh_empty/app.py /dev/ttyACM0

/dev/ttyACM0 is only an example path; replace it with your actual device. The repository’s connector convenience function targets the development board’s default settings. Custom serial parameters must be adjusted through the library interface; you cannot simply invent a baud-rate or flow-control command-line option.[3]

This program acts on the target device; it is not a read-only probe. In the code examined, the startup flow requests a reboot, calls btmesh.node.init() after receiving bt_evt_system_boot, and then lets the example handle the node initialization event. If the node is not provisioned, it starts unprovisioned advertising.[3][4]

The goal at this stage is to see the host and target complete startup and node initialization, not to control the lights in your home immediately.

The official repository README still says that a Mesh example reset clears the node’s original configuration, whereas the BtMeshApp.reset() code examined here calls bt.system.reboot(). These descriptions are inconsistent. This article interprets the code at the pinned commit and does not equate starting the example with a factory reset. You should still check the version you actually use, and in particular avoid experimenting with a reset whose semantics you do not understand on a device already joined to a production network.[1][3]

Step Four: Decide Who Provisions and Who Controls

The btmesh_empty base class initializes the Node role. Unprovisioned advertising means “this node is waiting to join a network,” not “it has started provisioning other lights.”

If your gateway needs to scan for unprovisioned devices, assign them network identities, and configure them, you need to design around the SDK’s Host Provisioner path and check the corresponding firmware, role, and host application. Adding a single light-on call after the Empty example is not enough.[1][2]

Even after a device has been provisioned, its application-layer configuration is not automatically complete. To control a light, you need to know which elements and models it supports, which AppKey to use, how the model is bound, whether to send control messages to a unicast or group address, and whether the subscription relationships are correct.

These relationships are covered in Bluetooth Mesh Provisioning Succeeded, So Why Is the Light Still Unresponsive?. A serial NCP provides an entry point to the protocol stack; it does not let you skip those steps.

For the first round of integration work, use just one controller and one test node. Establish the model configuration first, then complete one operation and check one status response. Once the single-device path is clear, introduce group messaging, retries, and multi-device synchronization.

Step Five: Keep the Event Loop Available for Communication

The official example’s shared class receives events and passes them to the corresponding handlers.[1][3] This is also where host programs can quickly become tangled: an event arrives, its handler calls a cloud API, writes to a database, and performs a time-consuming calculation, leaving subsequent events blocked.

My recommendation is to keep communication handling brief: parse and validate the message, record the necessary context, and hand time-consuming work to another worker. This is an application design suggestion, not a performance guarantee about every threading behavior of the example.

Command handling also needs an explicit policy for timeouts. A missing result does not necessarily mean the target device did nothing; sending the command again immediately may cause a second operation. Whether to retry, and how to correlate requests with status, depends on the specific API, model, and application semantics.

A host process restart and an NCP restart must not be conflated. After reconnecting, confirm the target’s state before deciding what to restore. Do not unconditionally clear the node, rebuild the network, or repeat provisioning on every reconnection. Before moving to multiple devices, decide where keys, address assignments, and device mappings will be stored and how they will be backed up.

When You Get Stuck, Troubleshoot by Layer

Observed symptom Check first What you cannot yet conclude
No serial device, or cannot open it Driver, connection, permissions, whether the device is in use The chip does not support Mesh
Serial port opens, but no startup event arrives Firmware type, baud rate, flow control, reset method, API parsing The wireless signal is too weak
Startup event arrives, but a command is unsupported API and firmware versions, components, role, initialization order Sending it more often will fix it
Mesh initialization succeeds, but the light remains unresponsive Provisioning, AppKey, model binding, destination address, subscriptions The BGAPI connection must be broken
Small-scale operation works, but becomes unstable under load Event-processing time, buffers, flow control, retry strategy Every problem comes from wireless relaying

Leaving an observable result at each step makes problems easier to locate than building a complete gateway from the outset. First establish that the host can communicate correctly with the NCP, then establish that the Mesh configuration is correct, and only then connect it to Matter and the higher-level application.

This also connects to the earlier Gateway Integration Acceptance Checklist: between “serial send succeeded” and seeing the correct device state on a phone, there are several stages that need to be verified separately.

References

Date checked: 2026-11-09. The official online SDK documentation pages timed out during this review. This article relies on the official examples at a pinned commit and an application note with an explicitly identified version; it does not claim to cover every interface in the latest SDK.

  1. Silicon Labs pyBGAPI Examples: README at pinned commit, NCP division of responsibilities, API alignment, Node and Provisioner roles, and example descriptions.
  2. AN1259: Bluetooth Stack v3.x and Higher in NCP Mode, Rev. 1.5, including pages 2, 16, 41, and 47–49. The PDF’s first page states that it was deprecated after the release of Simplicity SDK Suite 2024.12.2. This article uses it only to explain the architecture and flow control of the corresponding older examples; it does not treat its UI, paths, or commands as guarantees for the latest version.
  3. Official shared host class and serial connector.
  4. Official Bluetooth Mesh Empty example.

AI-generated concept illustration, not a product test photograph, actual interface or wiring diagram.

Discussion

Share a question or your experience. Comments appear after moderation. Your email is never displayed publicly. Comment privacy

Loading comments…