# BTstack Port for POSIX Systems with H4 Bluetooth Controller

## 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:

- CC2560:  bluetooth_init_cc2564_2.14.c
- CC2564B: bluetooth_init_cc2564B_1.8_BT_Spec_4.1.c
- CC2564C: bluetooth_init_cc2564C_1.5.c

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

- Install the `CMake Tools` extension
- Open `port/posix-h4/btstack-posix-h4.code-workspace`

### 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.

	$ ./le_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.
