Skip to content

wireless/bluetooth/zblue: Add Zephyr Bluetooth host - #3977

Open
chengkai15 wants to merge 6 commits into
apache:masterfrom
chengkai15:zblue
Open

chengkai15 wants to merge 6 commits into
apache:masterfrom
chengkai15:zblue

Conversation

@chengkai15

@chengkai15 chengkai15 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add the Bluetooth host of the Zephyr project as an optional userspace stack in nuttx-apps, in the same way as NimBLE. The Zephyr source is downloaded from a Zephyr release (CONFIG_ZBLUE_REF, default v4.5.0) and built without modification. The NuttX code is the porting layer and the build files in wireless/bluetooth/zblue (about 4,200 lines including license headers).

This is the first PR of step 1 of option 1B in the [VOTE] on dev@:
https://lists.apache.org/thread/9fy6bog3dcw3do5d8wd0yyvlpkjrhxpn

The vote passed (1B, and 2B for the long-term boundary): https://lists.apache.org/thread/pbkljzzqh0zo3tc7xgdrvh6m86bvpl8v

Roadmap and tracking: apache/nuttx#21478

Previous discussion: #20686 (apache/nuttx), and the [DISCUSS] thread https://lists.apache.org/thread/c6pl46o5l1ngb2zb3qtotq38o30h6v4b

The three steps

  1. Integrate the unmodified Zephyr Bluetooth host in nuttx-apps. The kernel only provides the existing HCI transport (/dev/ttyHCIx). (this series)
  2. Move HCI core, connection management and L2CAP into the kernel, replacing wireless/bluetooth and net/bluetooth, without losing the existing functions and tools.
  3. Make the userspace host use the kernel through the socket interface and drop its own copy of these layers.

Each step is a separate patch series, reviewed on its own. Step 1 is split into these PRs:

  1. framework, LE core, PSA crypto, sim:zblue (this PR, and boards/sim: Add zblue configuration nuttx#21479)
  2. SMP, privacy
  3. persistent storage (settings)
  4. bt shell
  5. BR/EDR profiles
  6. targets other than the simulator (iterable RAM sections, see Impact)
  7. BTP tester for AutoPTS, tests in CI

Commits

  1. Add Zephyr kernel porting layer: the Zephyr kernel services used by the host on POSIX threads (threads, semaphores, mutexes, condition variables, queues, memory slabs, heaps, work queues, timeouts), logging on syslog. Zephyr cooperative threads are serialized by one lock that is released only while a thread blocks.
  2. Add HCI driver on /dev/ttyHCIx: uses the existing bt_driver_register() / CONFIG_UART_BTH4 path, so every NuttX Bluetooth controller driver can be used. No new driver interface.
  3. Add Zephyr configuration and syscall tools: the CONFIG_BT_* options are the original Zephyr ones, read from a Zephyr configuration fragment (CONFIG_ZBLUE_CONF) and resolved by the Zephyr Kconfig through the wrapper Kconfig.zephyr (kconfiglib from the downloaded tree, no extra Python package). They are not added to the NuttX Kconfig.
  4. Add build of the Zephyr Bluetooth host: CONFIG_ZBLUE, Make and CMake. Sources are selected in the same way as the upstream CMakeLists.txt files.
  5. crypto/mbedtls: Enable the minimal configuration for zblue: same as for NimBLE.
  6. Add peripheral example: zblue_peripheral.

Design notes

  • Other stacks: CONFIG_ZBLUE depends on !WIRELESS_BLUETOOTH_HOST && !NIMBLE. Nothing changes in the kernel stack or in NimBLE; one host is selected at build time.
  • Naming: the NuttX switch is CONFIG_ZBLUE*, like CONFIG_NIMBLE, so CONFIG_BT is not tied to one implementation. The Zephyr CONFIG_BT_* options only exist in the generated zblue autoconf.h. CONFIG_BT_ZBLUE was also suggested in #20686; changing the name is easy if reviewers prefer it.
  • Why NuttX equivalents are not used inside zblue: the Zephyr code is not modified, and some names mean different things. <nuttx/atomic.h> defines atomic_t as _Atomic int32_t and atomic_*() as macros, while Zephyr defines atomic_t as long and, for example, atomic_set() returns the previous value. port/include/zblue_prefix.h, included first in every zblue source, resolves these clashes, and renames the Zephyr library functions that have the same name as libc functions with another signature (crc16(), hex2bin(), ...). Zephyr's net_buf is used as is for the same reason.
  • Iterable sections (BT_CONN_CB_DEFINE(), BT_GATT_SERVICE_DEFINE(), ...) are collected with the linker generated __start_/__stop_ symbols, without changes to the board linker scripts. The zblue objects are linked into one relocatable object, because some of them (e.g. services/gap_svc.c) only add section entries and would not be pulled out of a static library.
  • Cryptography uses the PSA API of apps/crypto/mbedtls. The vectors of the upstream tests/bluetooth/bt_crypto test pass with it (run on the host against the same Mbed TLS version, outside this build).

Impact

  • New optional application, disabled by default. No change for existing configurations; the only change outside wireless/bluetooth/zblue is one default y if ZBLUE line in crypto/mbedtls/Kconfig.
  • Linux simulator only: CONFIG_ZBLUE depends on ARCH_SIM && HOST_LINUX (the iterable sections use the ELF __start_/__stop_ symbols). On other targets the initialized iterable RAM section of the host (net_buf pools) is placed after .data and is not initialized by the startup code (found with nrf52840-dk, see Testing). PR 6 adds the linker support, which needs a change in nuttx (include/nuttx/linker).
  • No bt_disable(): the HCI driver has no close(), so bt_disable() returns -ENOSYS, as with upstream drivers without close(). The RX thread waits in read() on /dev/ttyHCIx and cannot be stopped there; disable and enable again come with the shell PR (PR 4).
  • Needs CONFIG_TLS_NELEM > 0 (thread-specific data in the porting layer) and an entropy source (CONFIG_DEV_URANDOM on the simulator).
  • Build: downloads the Zephyr release with curl, checks it against CONFIG_ZBLUE_SHA256, and needs python3, like other downloaded applications.
  • Not tested yet: protected and kernel builds.
  • Security: the host runs in userspace. Fixes to the host itself, including security fixes, go to Zephyr and are picked up by changing CONFIG_ZBLUE_REF.
  • License: the porting layer and build files are new code under the ASF license header. No Zephyr file is added to the repository. The downloaded sources that are compiled are Apache-2.0; kconfiglib (ISC) is only run as a build tool.
  • Documentation: in boards/sim: Add zblue configuration nuttx#21479 (Documentation/applications/wireless/zblue).

Testing

Host: Ubuntu 22.04.5 x86_64, gcc 13.1.0, CMake 3.23.0, Python 3.10.12.

Build

  • sim:zblue (boards/sim: Add zblue configuration nuttx#21479) with Make and with CMake/Ninja, from clean trees of both repositories; tools/testbuild.sh -N with the CI entry CMake,sim:zblue.
  • sim:zblue also builds at commits 3, 4 and 5 of the series (commits 1 and 2 add no build files yet).
  • tools/checkpatch.sh -g passes for all commits.
  • nrf52840-dk with the SoftDevice Controller (sdc_nimble with NimBLE replaced by zblue, before the ARCH_SIM dependency was added): builds and links; the section map showed the RAM section problem above.

Run

sim:zblue with a CSR USB controller (0a12:0001) attached with --bt-dev, and a second controller with BlueZ as central:

$ sudo hciconfig hci2 down
$ sudo ./nuttx --bt-dev=hci2
nsh> zblue_peripheral &
I: bt_hci_core: HCI transport: HCI
I: bt_hci_core: Identity: P:00:1A:7D:DA:71:11
I: bt_hci_core: HCI: version 4.0 (0x06) revision 0x22bb, manufacturer 0x000a
I: bt_hci_core: LMP: version 4.0 (0x06) subver 0x22bb
zblue: Bluetooth ready, identity P:00:1A:7D:DA:71:11
zblue: advertising as "NuttX zblue"
$ sudo hcitool -i hci1 lescan
00:1A:7D:DA:71:11 NuttX zblue
$ sudo gatttool -i hci1 -b 00:1A:7D:DA:71:11 --primary
attr handle = 0x0001, end grp handle = 0x0008 uuid: 00001801-0000-1000-8000-00805f9b34fb
attr handle = 0x0009, end grp handle = 0x000f uuid: 00001800-0000-1000-8000-00805f9b34fb
$ sudo gatttool -i hci1 -b 00:1A:7D:DA:71:11 --char-read --uuid=0x2a00
handle: 0x000b   value: 4e 75 74 74 58 20 7a 62 6c 75 65
zblue: connected P:00:1B:DC:F4:B4:8E
zblue: disconnected P:00:1B:DC:F4:B4:8E (0x13)
zblue: advertising as "NuttX zblue"

Repeated reads of the device name: 10 with a new connection each time, 10/10; 20 on one connection, 20/20.

Not covered by this PR: pairing (PR 2), bt_disable() (PR 4), automated tests in CI (PR 7).

depends-on: apache/nuttx/pull/21479

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown

🔗 Cross-repo PR dependencies

The read-only Build run reported the following dependent PR(s) and fetched head SHA(s):

CI run: https://github.com/apache/nuttx-apps/actions/runs/42003438673

@chengkai15

Copy link
Copy Markdown
Contributor Author

@xiaoxiang781216 @acassis @jerpelea @cederom @raiden00pl @simbit18 @btashton @anchao @LingaoM could you review this PR? It is the first PR of step 1 of option 1B in the [VOTE] (https://lists.apache.org/thread/9fy6bog3dcw3do5d8wd0yyvlpkjrhxpn); the board configuration and documentation are in apache/nuttx#21479. The Windows jobs failed on a Kconfig/kconfig/ name clash, which is fixed in 821645d.

@chengkai15

Copy link
Copy Markdown
Contributor Author

@yamt @Ouss4 @masayuki2009 @johannes-nivus @Donny9 @davids5 @antmerlino you were reviewers of apache/nuttx#20686, the earlier proposal for the Zephyr Bluetooth host; your review of this userspace integration is welcome too.

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown

🔗 Cross-repo PR dependencies

The read-only Build run reported the following dependent PR(s) and fetched head SHA(s):

CI run: https://github.com/apache/nuttx-apps/actions/runs/42189036926

@casaroli casaroli left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The body says "This PR is opened as a draft so that review can start; it will be marked ready for review after the result.", but the PR is not a draft, so it can merge before the vote closes.
Fix: convert the PR to a draft until the vote result.

Comment thread wireless/bluetooth/zblue/Makefile Resolved
Comment thread wireless/bluetooth/zblue/Kconfig Resolved

@acassis acassis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@chengkai15 please analyze the cpu consumption during this busy loop

@chengkai15

Copy link
Copy Markdown
Contributor Author

Thanks. The vote closed on 9 November, 00:00 UTC, and 1B passed: https://lists.apache.org/thread/pbkljzzqh0zo3tc7xgdrvh6m86bvpl8v. I have removed that sentence from the description.

@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown

🔗 Cross-repo PR dependencies

The read-only Build run reported the following dependent PR(s) and fetched head SHA(s):

CI run: https://github.com/apache/nuttx-apps/actions/runs/42613174780

@chengkai15

Copy link
Copy Markdown
Contributor Author

Rebased both PRs onto the latest master (apps cf52652, nuttx d9b891b2be), as requested in apache/nuttx#21479.

One change was needed in the porting layer. apache/nuttx@2ca5d1c142 ("include/atomic: add atomic_ptr_t type and operations") adds atomic_ptr_t and the atomic_ptr_*() macros to <nuttx/atomic.h>. Zephyr also defines atomic_ptr_t (typedef void *atomic_ptr_t in zephyr/sys/atomic_types.h) and functions with the same names, so zblue no longer compiled.

port/include/zblue_prefix.h already handles atomic_t and atomic64_t this way; atomic_ptr_t now gets the same treatment:

  • atomic_ptr_t is renamed to nx_atomic_ptr_t while <nuttx/atomic.h> is included;
  • the atomic_ptr_*() macros are removed afterwards.

With a NuttX tree that predates 2ca5d1c142 the change has no effect. The fix is squashed into the first commit ("Add Zephyr kernel porting layer"); the other five commits are unchanged.

Verified: checkpatch.sh -g on both PRs; clean builds of sim:zblue with Make and CMake.

GUIDINGLI
GUIDINGLI previously approved these changes Nov 16, 2026
* Public Functions
****************************************************************************/

void k_work_init(struct k_work *work, k_work_handler_t handler)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not reuse work/usrwork

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked at it. The NuttX work queue covers part of k_work, but the Zephyr host relies on a few things it doesn't provide:

  1. Running state. NuttX clears work->worker before calling the worker, so there is no "running" state. Zephyr needs it: k_work_busy_get() reports RUNNING/CANCELING/FLUSHING, and submitting a work item while it runs re-queues it on the same queue and returns 2.
  2. Flush. k_work_flush() and k_work_flush_delayable() wait for a work item to finish without cancelling it. work_cancel_sync() cancels it first.
  3. Several queues. The host uses the system work queue and its own RX queue at a different priority. work_queue_create() is only available in the flat build (or in the kernel); outside it, usrwork offers a single queue, so both queues would be merged and their ordering and priority would change.

It could be built on work_queue_create() + work_queue_wq() for the flat build, keeping a flags word in struct k_work for 1 and 2. That removes the thread loop and the delayed-work timer, but the state tracking stays, and zblue would be limited to the flat build. Would you like that in this PR, or as a follow-up after it is merged?

Comment thread crypto/mbedtls/Kconfig Resolved
Implement the Zephyr kernel services used by the Zephyr Bluetooth host
on POSIX threads, without NuttX internal interfaces, so that the host
sources can be built unmodified:

- threads: Zephyr cooperative threads are serialized by one lock that
  is released only while the thread blocks; k_sched_lock() takes the
  same lock.  Zephyr priorities are mapped around
  CONFIG_ZBLUE_THREAD_PRIORITY.
- semaphores, mutexes, condition variables, FIFO/LIFO queues, memory
  slabs and heaps.
- work queues with Zephyr semantics (delayable work, cancel, flush).
- timeouts, uptime and cycle counters on CLOCK_MONOTONIC.
- logging and printk on syslog, random numbers.
- headers that replace or extend the Zephyr ones: kernel.h,
  devicetree, SYS_INIT() and iterable sections.  Iterable section
  entries go to sections named zblue_<type> and are collected with the
  linker generated __start_/__stop_ symbols, so no change to the board
  linker script is needed.
- zblue_prefix.h, included first in every Zephyr source, resolves the
  name clashes between the Zephyr and NuttX headers.

The layer is not built yet; the build is added later in this series.

Signed-off-by: Kai Cheng <chengkai@xiaomi.com>
Provide the Zephyr HCI driver (the devicetree node chosen as
zephyr,bt-hci) on a NuttX H4 character device, CONFIG_UART_BTH4, so
that any controller registered with bt_driver_register() can be used:
the simulator HCI socket, an on-chip controller or a UART controller.

A receive thread reads the H4 packet type, header and payload into
host buffers and passes them to bt_hci_recv().  Outgoing packets are
written with their H4 type.

Signed-off-by: Kai Cheng <chengkai@xiaomi.com>
The Bluetooth host is configured with its own Zephyr CONFIG_BT_*
options, kept out of the NuttX Kconfig namespace:

- zblue.conf: default Zephyr configuration fragment (LE peripheral and
  central, GATT client).
- Kconfig.zephyr: wrapper that sources the Zephyr Bluetooth Kconfig
  and defines the Zephyr kernel options the host depends on. It is not
  named Kconfig so that it stays out of the NuttX menuconfig.
- tools/zkconfig.py: resolves the fragment with the Zephyr Kconfig
  (kconfiglib from the downloaded Zephyr tree), adds the architecture
  and endianness from the NuttX configuration, and writes autoconf.h
  and a make/cmake includable list of the enabled options.
- tools/gen_syscalls.py: generates the Zephyr syscall headers as
  direct calls to the implementations (no user mode).

Signed-off-by: Kai Cheng <chengkai@xiaomi.com>
Add CONFIG_ZBLUE and the Make and CMake builds:

- download the Zephyr release CONFIG_ZBLUE_REF (default v4.5.0) from
  GitHub, check it against CONFIG_ZBLUE_SHA256 and unpack only the
  directories used by the host;
- resolve the Zephyr configuration CONFIG_ZBLUE_CONF and generate the
  syscall headers;
- select the host sources from the resolved options in the same way as
  the upstream CMakeLists.txt files;
- link the objects into one relocatable object.  Some of them (e.g.
  services/gap_svc.c) only add entries to an iterable section and have
  no symbol referenced from elsewhere, so they would not be pulled out
  of a static library.

Cryptography uses the PSA API of apps/crypto/mbedtls; the options the
host needs are selected.  The thread-specific data used by the porting
layer needs CONFIG_TLS_NELEM.

Only the Linux simulator is supported for now: the initialized
iterable RAM sections of the host (net_buf pools) are placed after
.data and are not yet initialized by the board startup code, and the
sections are found through the ELF __start_/__stop_ symbols.

Signed-off-by: Kai Cheng <chengkai@xiaomi.com>
Default CONFIG_MBEDTLS_MINIMAL to y with CONFIG_ZBLUE, as for NimBLE:
the Bluetooth host only needs the PSA algorithms it selects.

Signed-off-by: Kai Cheng <chengkai@xiaomi.com>
Add zblue_peripheral (CONFIG_ZBLUE_PERIPHERAL_EXAMPLE), written against
the unmodified Zephyr Bluetooth API: it advertises with the name
CONFIG_BT_DEVICE_NAME, accepts connections with the GAP and GATT
services and advertises again after a disconnection.

Tested on sim:zblue with a USB Bluetooth controller and a second
controller with BlueZ as central: scan, connection, primary service
discovery, read of the device name, disconnection and reconnection.

Signed-off-by: Kai Cheng <chengkai@xiaomi.com>
@chengkai15

Copy link
Copy Markdown
Contributor Author

Updated to cbd3f96: addressed the inline comments (details in each reply). checkpatch.sh -g, clean Make and CMake builds of sim:zblue, and a runtime test on real hardware (connect and GATT read, 5/5) pass.

@github-actions

Copy link
Copy Markdown

🔗 Cross-repo PR dependencies

The read-only Build run reported the following dependent PR(s) and fetched head SHA(s):

CI run: https://github.com/apache/nuttx-apps/actions/runs/43821706918

@chengkai15

Copy link
Copy Markdown
Contributor Author

The failure in the latest Build run is not related to this PR. nucleo-g431rb/nsh no longer fits in its 128 KB flash:

ld: region `flash' overflowed by 16 bytes

(job 133212529201). arm-other and arm-stm32h7 were cancelled after that job failed.

Other PRs fail on the same config, for example run 43958667026 (152 bytes over) and run 43896803000 (8 bytes over).

This PR does not change that image: zblue depends on ARCH_SIM, and the crypto/mbedtls/Kconfig change only applies when CRYPTO_MBEDTLS is enabled.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants