BTstack Port for POSIX Systems with H4 Bluetooth Controller

This port runs BTstack on a POSIX host with a Bluetooth Controller connected via UART/H4.

Configuration

Most Bluetooth Bluetooth Controllers connected via UART/H4 require some special configuration, e.g. to set the UART baud rate, and/or require firmware patches during startup. In this port, we've tried to do most of these automatically based on information gathered from the Bluetooth Controller. Here's some Controller specific details:

TI CC256x

The CC2564x needs the correct init script to start up. The Makfile already has entries for most silicon revisions:

Please pick the correct one. The main.c verifies that the correct script is loaded, but the init script is linked to the executable.

Broadcom/Cypress/Infineon Controllers

The correct firmware file needs to be provided in the current working directory. The Makefile / CMake build downloads the firmware for the BCM43430, e.g. found on later Raspberry Pi editions, and the PatchRAM for the Vela IF310 / CYW55310.

Nordic Controller with HCI UART firmware

We maintain an enhanced / configured version of the official HCI UART example here: https://github.com/bluekitchen/hci_uart_iso_timesync/tree/main

The main difference of Zephyr-based Nordic Bluetooth Controllers is that: - the nRF52- and nRF54-Series use 1000000 as baud rate instead of 115200 - they don't have a public BD_ADDR.

You can use these by setting the baudrate to 1000000, e.g. like this

$ ./gatt_counter -u /dev/tty.usbmodem1234 --baud 1000000

The fixed random static address used automatically.

Build with Make

BTstack's POSIX-H4 does not have additional dependencies. You can directly run make

$ make

Build with CMake on the command line

To configure and build all examples with CMake/Ninja from the repository root, use:

$ cmake -S port/posix-h4 -B build/posix-h4 -G Ninja
$ cmake --build build/posix-h4

To build a single example only, specify the target explicitly, for example:

$ cmake --build build/posix-h4 --target gatt_counter

Build with CMake in Visual Studio Code

The repository contains a shared VS Code workspace file for this port:

port/posix-h4/btstack-posix-h4.code-workspace

Open this workspace file in Visual Studio Code using File->Open Workspace from File.

It shows the full BTstack repository in the file explorer, but configures CMake to use port/posix-h4/CMakeLists.txt.

Setup

Build an example

  1. Open the Command Palette
  2. Run CMake: Configure
  3. Run CMake: Select Build Target
  4. Pick an example, e.g. gatt_counter
  5. Run CMake: Build

The executable will be created in:

port/posix-h4/build

Run an example

Open a terminal in Visual Studio Code and start the example from the build directory, for example:

$ cd port/posix-h4/build
$ ./gatt_counter

Running from the build directory is useful as controller-specific firmware and init files downloaded by the CMake build are placed there as well.

Command-line options

All examples provide the following command line options:

--help               | -h                       print (this) help.
--logfile            | -l  LOGFILE              set file to store debug output and HCI trace.
--logformat          | -f  btsnoop|bluez|pklg   set file format to store debug output in.
--reset-tlv          | -r                       reset bonding information stored in TLV.
--tty                | -u  TTY                  set path to Bluetooth Controller.
--bd-addr            | -m  BD_ADDR              set random static Bluetooth address.
--baudrate           | -b  BAUDRATE             set initial baudrate.
--airoc-download-mode| -d                       enable AIROC Download Mode for newer CYW55xx Controller

Infineon AIROC Controller

Newer Infineon Airoc (tm) Controllers like the CYW55xx series accept PatchRAM upload only in a so-called 'Download Mode' or 'Auto-Baud Mode' which is entered by asserting CTS (low) and starting/resetting the controller via BT_REG_EN. The PatchRAM name is retrieved via a custom HCI Command from the Controller and loaded from the current folder.

To enable this mode, please provide '--airoc-download-mode' on the command line.

As this doing a power cycle is usually not possible on a desktop system, this port request the user to press the "RESET" button while showing a countdown.

Running the examples

On start, BTstack prints the path to the packet log and prints the information on the detected Buetooth Controller.

$ ./gatt_counter
Packet Log: /tmp/hci_dump.pklg
BTstack counter 0001
BTstack up and running on 00:1A:7D:DA:71:13.

Please note that BTstack will increase the baudrate. Before starting again, you should reset or power-cycle the Bluetooth Controller.