Existing ports

BTstack Port for Ambiq Apollo2 with EM9304

This port uses the Ambiq Apollo2 EVB and the Ambiq EM9304 (AM BLE) shield. HAL and BSP from Ambiq Suite 1.2.11 were used together with the regular ARM GCC toolchain. Firmware upload is possible via the internal J-Link interface or the 10-pin Mini ARM-JTAG Interface.

Hardware

Ambiq Apollo2 EVB + AM_BLE Shield - http://ambiqmicro.com/apollo-ultra-low-power-mcus/apollo2-mcu/

Software

AmbiqSuite: - http://ambiqmicro.com/apollo-ultra-low-power-mcus/apollo2-mcu/

Please clone BTstack as AmbiqSuite/third-party/bstack folder into the AmbiqSuite.

Create Example Projects

To create example GCC projects, go to the Apollo2-EM9304 folder

$ cd port/apollo2-em9304

and run make

$ ./create_examples.py

All examples are placed in the boards/apollo2_evb_am_ble/examples folder with btstack_ prefix.

Compile & Run Example Project

Go to to the gcc folder of one of the example folders and run make

$ make

To upload, please follow the instructions in the Apollo Getting Started documents.

Debug output

printf is routed over the USB connector of the EVB at 115200.

In port/apollo2-em9304/btstack_config.h additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in src/btstack_port.c by uncommenting the hci_dump_init(..) line. The console output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

TODO

Archive of earlier ports

The ports in this folder are not recommended for new designs. This does not mean that the target hardware is not suitable for new designs, just that the ports would need to reworked/refreshed.

List of ports with reason for move to this archive:

BTstack Port for the Espressif ESP32 Platform

Status: Basic port incl. all examples. BTstack runs on dedicated FreeRTOS thread. Multi threading (calling BTstack functions from a different thread) is not supported.

Setup

Usage

In port/esp32, run

./integrate_btstack.py

The script will copy parts of the BTstack tree into the ESP-IDF as $IDF_PATH/components/btstack and then create project folders for all examples.

Each example project folder, e.g. port/esp32/examples/spp_and_le_counter, contains a Makefile. Please run the command again after updating the BTstack tree (e.g. by git pull) to also update the copy in the ESP-IDF.

To compile an example, run:

make

To upload the binary to your device, run:

make flash

To get the debug output, run:

make monitor

You can quit the monitor with CTRL-].

Old Make Versions

Compilation fails with older versions of the make tool, e.g. make 3.8.1 (from 2006) provided by the current Xcode 9 on macOS or Ubuntu 14.04.1 LTS.

Interestingly, if you run make a second time, it completes the compilation.

Configuration

The sdkconfig of the example template disables the original Bluedroid stack by disabling the CONFIG_BLUEDROID_ENABLED kconfig option.

Limitations

Issues with the Bluetooth Controller Implementation

There are different issues in the Bluetooth Controller of the ESP32 that is provided in binary. We've submitted appropriate issues on the GitHub Issues page here: https://github.com/espressif/esp-idf/issues/created_by/mringwal

Audio playback

Audio playback is implemented by btstack_audio_esp32.c. It assumes an I2S Codec connected as follows:

ESP32 pin I2S Pin
GPIO25 LRCK
GPIO26 BCLK
GPIO22 DATA

We've used the MAX98357A on the Adafruit breakout board. The simplest example is the mod_player, which plays back an 8 kB sound file and the a2dp_sink_demo implements a basic Bluetooth loudspeaker.

Audio input via I2S or ADC is not supported yet. We might have a look at it when HFP/SCO via VHCI is working on the ESP32.

Multi-Threading

BTstack is not thread-safe, but you're using a multi-threading OS. Any function that is called from BTstack, e.g. packet handlers, can directly call into BTstack without issues. For other situations, you need to provide some general 'do BTstack tasks' function and trigger BTstack to execute it on its own thread. To call a function from the BTstack thread, there are currently two options:

With both options, the called function should check if there are any pending BTstack tasks and execute them.

The 'run on main thread' method is only provided by a few ports and requires a queue to store the calls. This should be used with care, since calling it multiple times could cause the queue to overflow.

We're considering different options to make BTstack thread-safe, but for now, please use one of the suggested options.

Acknowledgments

First HCI Reset was sent to Bluetooth chipset by @mattkelly

BTstack Port for POSIX Systems with libusb Library

Compilation

The quickest way to try BTstack is on a Linux or OS X system with an additional USB Bluetooth dongle. It requires pkg-config and libusb-1.0 or higher to be installed.

On a recent Debian-based system, all you need is:

apt-get install gcc git libusb-1.0 pkg-config

When everything is ready, you compile all examples with:

make

Environment Setup

Linux

On Linux, the USB Bluetooth dongle is usually not accessible to a regular user. You can either: - run the examples as root - add a udev rule for your dongle to extend access rights to user processes

To add an udev rule, please create /etc/udev/rules.d/btstack.rules and add this

# Match all devices from CSR
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a12", MODE="0666"

# Match Cypress Semiconductor / Broadcom BCM20702A, e.g. DeLOCK Bluetooth 4.0 dongle
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a5c", ATTRS{idProduct}=="21e8", MODE="0666"

# Match Asus BT400
SUBSYSTEM=="usb", ATTRS{idVendor}=="0b05", ATTRS{idProduct}=="17cb", MODE="0666"

# Match Laird BT860 / Cypress Semiconductor CYW20704A2
SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="f901", MODE="0666"

macOS

On macOS, the OS will try to use a plugged-in Bluetooth Controller if one is available. It's best to to tell the OS to always use the internal Bluetooth Contoller.

For this, execute:

sudo nvram bluetoothHostControllerSwitchBehavior=never

and then reboot to activate the change.

Note: if you get this error,

libusb: warning [darwin_open] USBDeviceOpen: another process has device opened for exclusive access
libusb: error [darwin_reset_device] ResetDevice: device not opened for exclusive access

and you didn't start another instance and you didn't assign the USB Controller to a virtual machine, macOS uses the plugged-in Bluetooth Controller. Please configure NVRAM as explained and try again after a reboot.

Running the examples

BTstack's HCI USB transport will try to find a suitable Bluetooth module and use it.

On start, BTstack will try to find a suitable Bluetooth module. It will also print the path to the packet log as well as the USB path.

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

If you want to run multiple examples at the same time, it helps to fix the path to the used Bluetooth module by passing -u usb-path to the executable.

Example running le_streamer and le_streamer_client in two processes, using Bluetooth dongles at USB path 6 and 4:

./le_streamer -u 6
Specified USB Path: 06
Packet Log: /tmp/hci_dump_6.pklg
USB Path: 06
BTstack up and running on 00:1A:7D:DA:71:13.
To start the streaming, please run the le_streamer_client example on other device, or use some GATT Explorer, e.g. LightBlue, BLExplr.

$ ./le_streamer_client -u 4
Specified USB Path: 04
Packet Log: /tmp/hci_dump_4.pklg
USB Path: 04
BTstack up and running on 00:1A:7D:DA:71:13.
Start scanning!

BTstack Port for POSIX Systems with Intel Wireless 8260/8265 Controllers

Same as port/libusb, but customized for Intel Wireless 8260 and 8265 Controllers. These controller require firmware upload and configuration to work. Firmware and config is downloaded from the Linux firmware repository.

Compilation

Requirements: - pkg-config - libusb-1.0

On a recent Debian-based system, all you need is:

apt-get install gcc git libusb-1.0 pkg-config

When everything is ready, you compile all examples with:

make

Environment

On Linux, the USB Bluetooth dongle is usually not accessible to a regular user. You can either: - run the examples as root - add a udev rule for your dongle to extend access rights to user processes

To add an udev rule, please create /etc/udev/rules.d/btstack.rules and add this

# Match all devices from CSR
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a12", MODE="0666"

# Match DeLOCK Bluetooth 4.0 dongle
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a5c", ATTRS{device}=="21e8", MODE="0666"

# Match Asus BT400
SUBSYSTEM=="usb", ATTRS{idVendor}=="0b05", ATTRS{device}=="17cb", MODE="0666"

# Match Laird BT860 / Cypress Semiconductor CYW20704A2
SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{device}=="f901", MODE="0666"

# Match Intel Wireless 8260 8265
SUBSYSTEM=="usb", ATTRS{idVendor}=="8027", ATTRS{device}=="0a2b, MODE="0666"

On macOS, the OS will try to use a plugged-in Bluetooth Controller if one is available. It's best to to tell the OS to always use the internal Bluetooth Contoller.

For this, execute:

sudo nvram bluetoothHostControllerSwitchBehavior=never

and then reboot to activate the change.

Running the examples

BTstack's HCI USB transport will try to find a suitable Bluetooth module and use it.

On start, BTstack will try to find a suitable Bluetooth module. It will also print the path to the packet log as well as the USB path.

$ ./le_counter
Packet Log: /tmp/hci_dump.pklg
USB Path: 03-01-04-03
Firwmare ./ibt-12-16.sfi
Firmware upload complete
Firmware operational
Done 1
BTstack counter 0001
USB Path: 03-01-04-03

BTstack up and running on F8:34:41:D5:BE:6F.

If you want to run multiple examples at the same time, it helps to fix the path to the used Bluetooth module by passing -u usb-path to the executable.

Example running le_streamer and le_streamer_client in two processes, using Bluetooth dongles at USB path 6 and 4:

./le_streamer -u 6
Specified USB Path: 06
Packet Log: /tmp/hci_dump_6.pklg
USB Path: 06
BTstack up and running on 00:1A:7D:DA:71:13.
To start the streaming, please run the le_streamer_client example on other device, or use some GATT Explorer, e.g. LightBlue, BLExplr.

$ ./le_streamer_client -u 4
Specified USB Path: 04
Packet Log: /tmp/hci_dump_4.pklg
USB Path: 04
BTstack up and running on 00:1A:7D:DA:71:13.
Start scanning!

BTstack Port for the Maxim MAX32630FTHR ARM Cortex-M4F

This port uses the MAX32630FTHR ARM Cortex M4F Board with the onboard TI CC2564B Bluetooth controller. It usually comes with the DAPLINK Programming Adapter. The DAPLINK allows to upload firmware via a virtual mass storage device (like mbed), provides a virtual COM port for a console, and enables debugging via the SWD interface via OpenOCD.

The port uses non-blocking polling UART communication with hardware flow control for Bluetooth controller. It was tested and achieved up to 1.8 Mbps bandwidth between two Max32630FTHR boards.

Software

The Maxim ARM Toolchain is free software that provides peripheral libraries, linker files, initial code and some board files. It also provides Eclipse Neon and Maxim modified OpenOCD to program the microcontroller together with various examples for Maxim Cortex M4F ARM processors.

For debugging, OpenOCD can be used. The regular OpenOCD does not support Maxim ARM microcontrollers yet, but a modified OpenOCD for use with Maxim devices can be found in the Maxim ARM Toolchain.

Toolchain Setup

In the Maxim Toolchain installation directory, there is a setenv.sh file that sets the MAXIM_PATH. MAXIM_PATH needs to point to the root directory where the tool chain installed. If you're lucky and have a compatible ARM GCC Toolchain in your PATH, it might work without calling setenv.sh script.

Usage

The examples can be compiled using GNU ARM Toolchain. A firmware binary can be flashed either by copying the .bin file to the DAPLINK mass storage drive, or by using OpenOCD on the command line, or from Eclipse CDT.

Build

Checkt that MAXIM_PATH points to the root directory where the tool chain installed. Then, go to the port/max32630-fthr folder and run "make" command in terminal to generate example projects in the example folder.

In each example folder, e.g. port/max323630-fthr/example/spp_and_le_streamer, you can run "make" again to build an .elf file in the build folder which is convenient for debugging using Eclipse or GDB.

For flashing via the virtual USB drive, the "make release" command will generate .bin file in the build folder.

Eclipse

Toolchain and Eclipse guide can be found in README.pdf file where the Maxim Toolchain is installed. Please note that this port was done using Makefiles.

Flashing Max32630 ARM Processor

There are two ways to program the board. The simplest way is drag and drop the generated .bin file to the DAPLINK mass storage drive. Once the file is copied to the mass storage device, the DAPLINK should program and then run the new firmware.

Alternatively, OpenOCD can be used to flash and debug the device. A suitable programming script can be found in the scripts folder.

Debugging

OpenOCD can also be used for developing and especially for debugging. Eclipse or GDB via OpenOCD could be used for step by step debugging.

Debug output

printf messages are redirected to UART2. UART2 is accessible via the DAPLINK Programming Adapter as a virtual COM port at 115200 baud with no flow control. If this doesn't work for you, you can connect P3_1 (UART TX) of the MAX32630FTHR board to a USB-to-UART adapter.

Additional debug information can be enabled by uncommenting ENABLE_LOG_INFO in the src/btstack_config.h header file and a clean rebuild.

TODOs

BTstack Port for MSP432P401 Launchpad with CC256x

This port is for the the TI MSP432P401R Launchpad with TI's CC256x Bluetooth Controller using TI's DriverLib (without RTOS). For easy development, Ozone project files are generated as well.

As the MSP432P401 does not have support for hardware RTS/CTS, this port makes use of Ping Pong DMA transfer mode (similar to circular DMA on other MCUs) to use two adjacent receive buffers and raise RTS until a completed buffer is processed.

Hardware

TI MSP432P401R LaunchPad

As Bluetooth Controller, there are two BoosterPacks that can be use: 1. BOOST-CC2564MODA CC2564B BoosterPack (USD 20) 2. Evaluation Module (EM) Adapto (USD 20) with one of the CC256x modules: - CC2564B Dual-mode Bluetooth® Controller Evaluation Module (USD 20) - CC2564C Dual-mode Bluetooth® Controller Evaluation Module (USD 60)

The CC2564B Booster pack is around USD 20 while thhe EM Adapter with the CC2564C module is around USD 80.

The project in the BTstack repo `port/msp432p401lp-cc256x' is configured for the EM Adapter + newer CC2564C module.

When using the CC2564B (either as BOOST-CC2564MODA or CC2564B Dual-mode Bluetooth® Controller Evaluation Module), the bluetooth_init_cc2564B_1.8_BT_Spec_4.1.c must be used as cc256x_init_script. See Makefile variable INIT_SCRIPT.

When using the CC2564B Booster Pack, please use uncomment the defines for the GPIO definition (search for BOOST-CC2564MODA)

When using the EM Adapter Booster Pack, please make sure to solder a 32.768 kHz quarz oscillator as explained in 4.7 of the EM Wireless Booster Pack User Guide. If you don't have an oscillator of that size, you might solder one upside done (turtle-on-back style) to the unused upper right pad and wire GCC, VCC, and clock with thin wires.

Software

To build all examples, you need the regular ARM GCC toolcahin installed. Run make

$ make

All examples and the .jdebug Ozone project files are placed in the 'gcc' folder.

Flash And Run The Examples

The Makefile builds different versions: - example.elf: .elf file with all debug information - example.bin: .bin file that can be used for flashing

There are different options to flash and debug the MSP432P401R LaunchPad. If all but the jumpers for power (the left three) are removed on J101, an external JTAG like SEGGER's J-Link can be connected via J8 'MSP432 IN'.

Run Example Project using Ozone

When using an external J-Link programmer, you can flash and debug using the cross-platform SEGGER Ozone Debugger. It is included in some J-Link programmers or can be used for free for evaluation usage.

Just start Ozone and open the .jdebug file in the build folder. When compiled with ENABLE_SEGGER_RTT, the debug output shows up in the Terminal window of Ozone.

Debug output

All debug output is send via SEGGER RTT or via USART2. To get the console from USART2, remove ENABLE_SEGGER_RTT from btstack_config.h and open a terminal to the virtual serial port of the Launchpad at 115200.

In btstack_config.h resp. in example/btstack_config.h of the generated projects, additional debug information can be disabled/enabled via ENABLE_LOG_INFO.

Also, the full packet log can be enabled in main.c by uncommenting the hci_dump_init(..) line. The output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

GATT Database

In BTstack, the GATT Database is defined via the .gatt file in the example folder. The Makefile contains rules to update the .h file when the .gatt was modified.

BTstack Port with Cinnamon for Nordic nRF5 Series

Cinnamon is BlueKitchen's minimal, yet robust Controller/Link Layer implementation for use with BTstack.

In contrast to common Link Layer implementations, our focus is on a robust and compact implementation for production use, where code size matters (e.g. current code size about 8 kB).

Status

The current implementation supports a single Peripheral role, or, passive scanning in Observer role. In the Peripheral role, channel map updates, as well as connection param updates are supported.

Support for LE Central Role as well as Encryption is planned but not supported yet.

Requirements

Supported Hardware

All nNRF5x SOCs. Built files are provided for PCA10040 (52832 DK), but others can be supported with minimal changes.

Use

BTstack Port for Zephyr RTOS running on Nordic nRF5 Series

Overview

This port targets the bare Nordic nRF5-Series chipsets with the BLE Link Layer provided by the Zephyr project.

Status

Working with nRF52 pca10040 dev board. Public BD ADDR is set to 11:22:33:44:55:66 since the default 00:00:00:00:00:00 is filtered by iOS.

Getting Started

To integrate BTstack into Zephyr, please move the BTstack project into the Zephyr root folder 'zephyr'. Please use the Zephry '1.9-branch' for now. In the master branch, Zephyr switched the build system to CMake and this port hasn't been update for that yet.

Then integrate BTstack:

cd /path/to/zephy/btstack/port/nrf5-zephyr
./integrate_btstack.sh

Now, the BTstack examples can be build from the Zephyr examples folder in the same way as other examples, e.g.:

cd /path/to/zephyr/samples/btstack/le_counter
make

to build the le_counter example for the pca10040 dev kit using the ARM GCC compiler.

You can use make flash or ./flash_nrf52_pca10040.sh to download it onto the board.

All examples that provide a GATT Server use the GATT DB in the .gatt file. Therefore you need to run ./update_gatt_db.sh in the example folder after modifying the .gatt file.

This port does not support Data Sources aside from the HCI Controller.

TODO

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:

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 BCM/CYW 43430

The correct firmware file needs to be provided in the current working directory. The Makefile downloads the one for the BCM43430 e.g. found on later Raspberry Pi editions. Please see the separate port/raspi, too.

Compilation

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

make

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.

BTstack Port for POSIX Systems with Atmel ATWILC3000 Controller

This port allows to use the ATWILC3000 connected via UART with BTstack running on a POSIX host system, see test setup below (which lacks a proper RESET button).

Compilation

$ make

The Makefile downloads the wilc3000_bt_firmware.bin firmware from the GitHub atwilc3000/firmware repo.

Usage

Just run any of the provided examples, e.g.

$ ./le_counter

At start, the firmware file is first uploaded to the ATWILC3000, before BTstack start up.

Please note that it configures the ATWILC3000 for a higher baud rate it does not detect if the firmware has already been downloaded, so you need to reset the ATWILC3000 before starting an example.

Tested with the official ATWILC3000 SHIELD on OS X.

ATWILC3000 Test Setup

BTstack Port for POSIX Systems with Dialog Semiconductor DA14581 Controller

This port allows to use the DA14581 connected via UART with BTstack running on a POSIX host system.

It first downloads the hci_581_active_uart.hex firmware from the DA14581_HCI_3.110.2.12 SDK packet, before BTstack starts up.

Please note that it does not detect if the firmware has already been downloaded, so you need to reset the DA14581 before starting an example.

For production use, the HCI firmware could be flashed into the OTP and the firmware download could be skipped.

Tested with the official DA14581 Dev Kit on OS X.

BTstack Port for POSIX Systems with Dialog Semiconductor DA14585 Controller

This port allows to use the DA14585 connected via UART with BTstack running on a POSIX host system.

It first downloads the hci_581.hex firmware from the 6.0.8.509 SDK, before BTstack starts up.

Please note that it does not detect if the firmware has already been downloaded, so you need to reset the DA14585 before starting an example.

For production use, the HCI firmware could be flashed into the OTP and the firmware download could be skipped.

Tested with the official DA14585 Dev Kit Basic on OS X.

BTstack Port for POSIX Systems with Zephyr-based Controller

The main difference to the regular posix-h4 port is that that the Zephyr Controller uses 1000000 as baud rate. In addition, the port defaults to use the fixed static address stored during production.

Prepare Zephyr Controller

Please follow this blog post about how to compile and flash samples/bluetooth/hci_uart to a connected nRF5 dev kit.

In short: you need to install an arm-none-eabi gcc toolchain and the nRF5x Command Line Tools incl. the J-Link drivers, checkout the Zephyr project, and flash an example project onto the chipset:

Configure serial port

To set the serial port of your Zephyr Controller, you can either update config.device_name in main.c or always start the examples with the -u /path/to/serialport option.

Compile Examples

$ make

Run example

Just run any of the created binaries, e.g.

$ ./le_counter

The packet log will be written to /tmp/hci_dump.pklg

BTstack Port for QT with H4 Bluetooth Controller

Uses libusb Library on macOS and Linux and WinUSB on Windows. Windows is supported with the MinGW Kit.

Windows with MSVC or Embedded (bare metal) platforms not supported yet.

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 BCM/CYW 43430

The correct firmware file needs to be provided in the current working directory. The Makefile downloads the one for the BCM43430 e.g. found on later Raspberry Pi editions. Please see the separate port/raspi, too.

Compilation

On all platforms, you'll need Qt Python 3 installed. On macOS/Linux libusb-1.0 or higher is required, too.

When everything is ready, you can open the provided CMakelists.txt project in Qt Creator and run any of the provided examples. See Qt documentation on how to compile on the command line or with other IDEs

Running the examples

BTstack's HCI USB transport will try to find a suitable Bluetooth module and use it.

On start, BTstack will try to find a suitable Bluetooth module. It will also print the path to the packet log as well as the USB path.

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

BTstack Port for QT with USB Bluetooth Dongle

Uses libusb Library on macOS and Linux and WinUSB on Windows. Windows is supported with the MinGW Kit.

Windows with MSVC or Embedded (bare metal) platforms not supported yet.

Compilation

On all platforms, you'll need Qt Python 3 installed. On macOS/Linux libusb-1.0 or higher is required, too.

When everything is ready, you can open the provided CMakelists.txt project in Qt Creator and run any of the provided examples. See Qt documentation on how to compile on the command line or with other IDEs

Environment Setup

Windows

To allow WinUSB to access an USB Bluetooth dongle, you need to install a special device driver to make it accessible to user space processes.

It works like this:

Linux

On Linux, the USB Bluetooth dongle is usually not accessible to a regular user. You can either: - run the examples as root - add a udev rule for your dongle to extend access rights to user processes

To add an udev rule, please create /etc/udev/rules.d/btstack.rules and add this

# Match all devices from CSR
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a12", MODE="0666"

# Match DeLOCK Bluetooth 4.0 dongle
SUBSYSTEM=="usb", ATTRS{idVendor}=="0a5c", ATTRS{device}=="21e8", MODE="0666"

# Match Asus BT400
SUBSYSTEM=="usb", ATTRS{idVendor}=="0b05", ATTRS{device}=="17cb", MODE="0666"

# Match Laird BT860 / Cypress Semiconductor CYW20704A2
SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{device}=="f901", MODE="0666"

macOS

On macOS, the OS will try to use a plugged-in Bluetooth Controller if one is available. It's best to to tell the OS to always use the internal Bluetooth Contoller.

For this, execute:

sudo nvram bluetoothHostControllerSwitchBehavior=never

and then reboot to activate the change.

Note: if you get this error,

libusb: warning [darwin_open] USBDeviceOpen: another process has device opened for exclusive access
libusb: error [darwin_reset_device] ResetDevice: device not opened for exclusive access

and you didn't start another instance and you didn't assign the USB Controller to a virtual machine, macOS uses the plugged-in Bluetooth Controller. Please configure NVRAM as explained and try again after a reboot.

Running the examples

BTstack's HCI USB transport will try to find a suitable Bluetooth module and use it.

On start, BTstack will try to find a suitable Bluetooth module. It will also print the path to the packet log as well as the USB path.

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

If you want to run multiple examples at the same time, it helps to fix the path to the used Bluetooth module by passing -u usb-path to the executable.

Example running le_streamer and le_streamer_client in two processes, using Bluetooth dongles at USB path 6 and 4:

./le_streamer -u 6
Specified USB Path: 06
Packet Log: /tmp/hci_dump_6.pklg
USB Path: 06
BTstack up and running on 00:1A:7D:DA:71:13.
To start the streaming, please run the le_streamer_client example on other device, or use some GATT Explorer, e.g. LightBlue, BLExplr.

$ ./le_streamer_client -u 4
Specified USB Path: 04
Packet Log: /tmp/hci_dump_4.pklg
USB Path: 04
BTstack up and running on 00:1A:7D:DA:71:13.
Start scanning!

BTstack Port for Raspberry Pi 3 with BCM4343 Bluetooth/Wifi Controller

Tested with Raspberry Pi 3 Model B V1.2, Raspberry Pi 3 Model B+, and Raspberry Pi Zero W V1.1.

With minor fixes, the port should also work with older Raspberry Pi models that use the RedBear pHAT. See TODO at the end.

Raspberry Pi 3 / Zero W Setup

There are various options for setting up the Raspberry Pi, have a look at the Internet. Here's what we did:

Install Raspian Stretch Lite:

Configure Wifi

Create the file wpa_supplicant.conf in the root folder of the SD Card with your Wifi credentials:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
network={
    ssid="YOUR_NETWORK_NAME"
    psk="YOUR_PASSWORD"
    key_mgmt=WPA-PSK
}

Alternatively, just plug-it in via Ethernet - unless you have a Raspberry Pi Zero W.

Enable SSH

Create an empty file called 'ssh' in the root folder of the SD Card to enable SSH.

Boot

If everything was setup correctly, it should now boot up and join your Wifi network. You can reach it via mDSN as 'raspberrypi.local' and log in with user: pi, password: raspberry.

Disable bluez

By default, bluez will start up using the the BCM4343. To make it available to BTstack, you can disable its system services:

$ sudo systemctl disable hciuart
$ sudo systemctl disable bthelper
$ sudo systemctl disable bluetooth

and if you don't want to restart, you can stop them right away. Otherwise, please reboot here.

$ sudo systemctl stop hciuart
$ sudo systemctl stop bthelper
$ sudo systemctl stop bluetooth

If needed, they can be re-enabled later as well.

Compilation

The Makefile assumes cross-compilation using the regular GCC Cross Toolchain for gnueabihf: arm-linux-gnueabihf-gcc. This should be available in your package manager. Read on for a heavy, but easy-to-use approach.

Compile using Docker

For non-Linux users, we recommend to use a Raspberry Pi Cross-Compiler in a Docker Container. Please follow the installation instructions in the README.

Then, setup a shared folder in Docker that contains the BTstack repository. Now, go to the BTstack repository and 'switch' to the Raspberry Pi Cross-Compiler container:

$ rpxc bash

The default images doesn't have a Python installation, so we manually install it:

$ sudo apt-get install python

Change to the port/raspi folder inside the BTstack repo:

$ cd btstack/port/raspi

and compile as usual:

$ make

For regular use, it makes sense to add Python permanently to the Docker container. See documentation at GitHub.

Running the examples

Copy one of the examples to the Rasperry Pi and just run them. BTstack will power cycle the Bluetooth Controller on models without hardware flowcontrol, i.e., Pi 3 A/B. With flowcontrol, e.g Pi Zero W and Pi 3 A+/B+, the firmware will only uploaded on first start.

pi@raspberrypi:~ $ ./le_counter
Packet Log: /tmp/hci_dump.pklg
Hardware UART without flowcontrol
Phase 1: Download firmware
Phase 2: Main app
BTstack counter 0001
BTstack up and running at B8:27:EB:27:AF:56

Bluetooth Hardware Overview

Model Bluetooth Controller UART Type UART Flowcontrol BT_REG_EN HCI Transport Baudrate
Older None
Pi 3 Model A, Model B CYW43438 Hardware No 128 H5 921600
Pi 3 Model A+, Model B + CYW43455 Hardware Yes 129 (See 1) H4 921600 (See 2)
Pi Zero W CYW43438 Hardware Yes 45 H4 921600
  1. Model A+/B+ have BT_REG_EN AND WL_REG_EN on the same (virtual) GPIO 129. A Bluetooth Controller power cycle also shuts down Wifi (temporarily). BTstack avoids a power cycle on A+/B+.
  2. Model A+/B+ support 3 mbps baudrate. Not enabled/activated yet.

TODO

BTstack Port for Renesas Target Board TB-S1JA with CC256x

This port uses the Renesas TB-S1JA with TI's CC256XEM ST Adapter Kit that allows to plug in a CC256xB or CC256xC Bluetooth module. Renesas e2 Studio (Eclise-based) was used with the SSP HAL and without an RTOS. For easy debugging, Ozone project files are generated as well.

Hardware

Renesas Target Board TB-S1JA: - TB-S1JA Target Board Kit

The projects are configured for the CC2564C. When using the CC2564B, bluetooth_init_cc2564B_1.8_BT_Spec_4.1.c should be used as cc256x_init_script. You can update this in the create_examples.py script.

Connct the Target Board to the TI Boosterpack, see Booster Pack Pinout: http://www.ti.com/ww/en/launchpad/dl/boosterpack-pinout-v2.pdf

J2 PIN S1JA PORT S1JA Signal Boosterpack
2 P301 RXD0 3 (LP1)
4 P302 TXD0 4 (LP1)
6 P304 CTS0 36 (LP2)
8 P303 RTS0 37 (LP2)
10 VCC VCC 1 (LP1)
12 VSS GND 20 (LP2)
14 P112 nShutdown 19 (LP1)

Software

Generate example projects

$ python create_examples.py

This will generate an e2 Studio project for each example.

Excluded Examples

The a2dp examples (a2dp_source_demo and a2dp_sink_demo) were disabled as the C open-source SBC codec with compile option -O2 wasn't fast enough to provide real-time encoding/decoding.

Build, Flash And Run The Examples in e2 Studio

Open the e2 Studio project and press the 'Debug' button. Debug output is only available via SEGGER RTT. You can run SEGGER's JLinkRTTViewer or use Ozone as described below.

Run Example Project using Ozone

After compiling the project with e2 Studio, the genereated .elf file can be used with Ozone (also e.g. on macOS). In Ozone, the debug output is readily available in the terminal. A .jdebug file is provided in the project folder.

Debug output

All debug output is send via SEGGER RTT.

In src/btstack_config.h resp. in example/btstack_config.h of the generated projects, additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in src/hal_entry.c by uncommenting the hci_dump_init(...) call. The console output can then be converted into .pklg files by running tool/create_packet_log.py. The .pklg file can be analyzed with the macOS X PacketLogger or WireShark.

GATT Database

In BTstack, the GATT Database is defined via the .gatt file in the example folder. The create_examples.py script converts the .gatt files into a corresponding .h for the project. After updating a .gatt file, the .h can be updated manually by running the provided update_gatt_db.sh or update_gatt_db.bat scripts.

Note: In theory, this can be integrated into the e2 Studio/Eclipse project.

Notes

Nice to have

BTstack Port for SAMV71 Ultra Xplained with ATWILC3000 SHIELD

This port uses the SAMV71 Ultra Xplained Ultra evaluation kit with an ATWILC3000 SHIELD. The code is based on the Advanced Software Framework (ASF) (previously know as Atmel Software Framework). It uses the GCC Makefiles provided by the ASF. OpenOCD is used to upload the firmware to the device.

Create Example Projects

To create all example projects in the example folder, you can run:

$ make

Compile Example

In one of the example folders:

$ make

To upload the firmware:

$ make flash

You need to connect the the Debug USB to your computer.

Debug output

printf is routed to USART1, which is connected to the virtual serial port. To get the console output, open a terminal at 115200.

In btstack_config.h, additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in the main() function on main.c by uncommenting the hci_dump_init(..) line. The console output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

TODOs

- Implement hal_flash_sector.h to persist link keys

Issues

- Bluetooth UART driver uses per-byte interrupts and doesn't work reliable at higher baud rates (921600 seems ok, 2 mbps already causes problems).
- An older XDMA-based implementation only sends 0x00 bytes over the UART. It might be better to just read incoming data into two buffers, (e.g. using a two element linked list with XDMA), and raising RTS when one buffer is full.

BTstack Port for STM32 F4 Discovery Board with CC256x

This port uses the STM32 F4 Discovery Board with TI's CC256XEM ST Adapter Kit that allows to plug in a CC256xB or CC256xC Bluetooth module. STCubeMX was used to provide the HAL, initialize the device, and the Makefile. For easy development, Ozone project files are generated as well.

Hardware

STM32 Development kit and adapter for CC256x module: - STM32 F4 Discovery Board - CC256xEM Bluetooth Adatper Kit for ST

CC256x Bluetooth module: - CC2564B Dual-mode Bluetooth® Controller Evaluation Module - CC2564C Dual-mode Bluetooth® Controller Evaluation Module

The module with the older CC2564B is around USD 20, while the one with the new CC2564C costs around USD 60. The projects are configured for the CC2564C. When using the CC2564B, bluetooth_init_cc2564B_1.8_BT_Spec_4.1.c should be used as cc256x_init_script.

Software

To build all examples, run make

$ make

All examples and the .jedbug Ozone project files are placed in the 'build' folder.

Flash And Run The Examples

The Makefile builds different versions: - example.elf: .elf file with all debug information - example.bin: .bin file that can be used for flashing

There are different options to flash and debug the F4 Discovery board. The F4 Discovery boards comes with an on-board ST-Link programmer and debugger. As an alternative, the ST-Link programmer can be replaced by an SEGGER J-Link OB. Finally, the STM32 can be programmed with any ARM Cortex JTAG or SWD programmer via the SWD jumper.

Run Example Project using Ozone

When using an external J-Link programmer or after installing J-Link OB on the F4 Discovery board, you can flash and debug using the cross-platform SEGGER Ozone Debugger. It is included in some J-Link programmers or can be used for free for evaluation usage.

Just start Ozone and open the .jdebug file in the build folder. When compiled with "ENABLE_SEGGER_RTT", the debug output shows up in the Terminal window of Ozone.

Debug output

All debug output can be either send via SEGGER RTT or via USART2. To get the console from USART2, connect PA2 (USART2 TX) of the Discovery board to an USB-2-UART adapter and open a terminal at 115200.

In src/btstack_config.h resp. in example/btstack_config.h of the generated projects, additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in src/port.c resp. btstack/port/stm32-f4discovery-cc256x/src/port.c by uncommenting the hci_dump_init(..) line. The console output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

GATT Database

In BTstack, the GATT Database is defined via the .gatt file in the example folder. The Makefile contains rules to update the .h file when the .gatt was modified.

Maintainer Notes - Updating The Port

The Audio BSP is from the STM32F4Cube V1.16 firmware and not generated from STM32CubeMX. To update the HAL, run 'generate code' in CubeMX. After that, make sure to re-apply the patches to the UART and check if the hal config was changed.

BTstack Port for STM32 F4 Discovery Board with USB Bluetooth Controller

This port uses the STM32 F4 Discovery Board with an USB Bluetooth Controller plugged into its USB UTG port. See blog post for details.

STCubeMX was used to provide the HAL, initialize the device, and the Makefile. For easy development, Ozone project files are generated as well.

Hardware

STM32 Development kit with USB OTG adapter and USB CSR8510 Bluetooth Controller - STM32 F4 Discovery Board

Software

To build all examples, run make

$ make

All examples and the .jedbug Ozone project files are placed in the 'build' folder.

Flash And Run The Examples

The Makefile builds different versions: - example.elf: .elf file with all debug information - example.bin: .bin file that can be used for flashing

There are different options to flash and debug the F4 Discovery board. The F4 Discovery boards comes with an on-board ST-Link programmer and debugger. As an alternative, the ST-Link programmer can be replaced by an SEGGER J-Link OB. Finally, the STM32 can be programmed with any ARM Cortex JTAG or SWD programmer via the SWD jumper.

Run Example Project using Ozone

When using an external J-Link programmer or after installing J-Link OB on the F4 Discovery board, you can flash and debug using the cross-platform SEGGER Ozone Debugger. It is included in some J-Link programmers or can be used for free for evaluation usage.

Just start Ozone and open the .jdebug file in the build folder. When compiled with "ENABLE_SEGGER_RTT", the debug output shows up in the Terminal window of Ozone.

Debug output

The debug output can send via SEGGER RTT.

In src/btstack_config.h resp. in example/btstack_config.h of the generated projects, additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in src/port.c resp. btstack/port/stm32-f4discovery-cc256x/src/port.c by uncommenting the hci_dump_init(..) line. The console output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

GATT Database

In BTstack, the GATT Database is defined via the .gatt file in the example folder. The Makefile contains rules to update the .h file when the .gatt was modified.

Maintainer Notes - Updating The Port

The Audio BSP is from the STM32F4Cube V1.16 firmware and not generated from STM32CubeMX. To update the HAL, run 'generate code' in CubeMX. After that, make sure to re-apply the patches to the UART and check if the hal config was changed.

BTstack Port for STM32 Nucleo L073RZ Board with EM9304 Controller

This port uses the STM32 Nucleo-L073RZ Board with EM's EM9304 Shield.

The STM32CubeMX tool was used to provide the HAL, initialize the device, and create a basic Makefile. The Makefile has been exteneded to compile all BTstack LE examples. For easy development, Ozone project files are generated as well.

Hardware

In this port, the EM9304 is conencted via the SPI1 interface and configured for 8 Mhz. Datasheet for the EM9304

It assumes that the EM9304 does not contain any patches and uploads the latest Metapatch during startup.

Software

To build all examples, run make

$ make

All examples and the .jedbug Ozone project files are placed in the 'build' folder.

Flash And Run The Examples

The Makefile builds different versions: - example.elf: .elf file with all debug information - example.bin: .bin file that can be used for flashing

There are different options to flash and debug the F4 Discovery board. The F4 Discovery boards comes with an on-board ST-Link programmer and debugger. As an alternative, the ST-Link programmer can be replaced by an SEGGER J-Link OB. Finally, the STM32 can be programmed with any ARM Cortex JTAG or SWD programmer via the SWD jumper.

Run Example Project using Ozone

When using an external J-Link programmer or after installing J-Link OB on the F4 Discovery board, you can flash and debug using the cross-platform SEGGER Ozone Debugger. It is included in some J-Link programmers or can be used for free for evaluation usage.

Just start Ozone and open the .jdebug file in the build folder. When compiled with "ENABLE_SEGGER_RTT", the debug output shows up in the Terminal window of Ozone.

Debug output

All debug output can be either send via SEGGER RTT or via USART2. To get the console from USART2, connect PA2 (USART2 TX) of the Discovery board to an USB-2-UART adapter and open a terminal at 115200.

In src/btstack_config.h resp. in example/btstack_config.h of the generated projects, additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in src/port.c by uncommenting the hci_dump_init(..) line. The console output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

GATT Database

In BTstack, the GATT Database is defined via the .gatt file in the example folder. During the build, the .gatt file is converted into a .h file with a binary representation of the GATT Database and useful defines for the application.

Image

EM9304 DVK

BTstack Port with Cinnamon for Semtech SX1280 Controller on Miromico FMLR-80

Cinnamon is BlueKitchen's minimal, yet robust Controller/Link Layer implementation for use with BTstack.

In contrast to common Link Layer implementations, our focus is on a robust and compact implementation for production use, where code size matters (e.g. current code size about 8 kB).

Overview

This port targets the Semtech SX1280 radio controller. The Host Stack and the Controller (incl. Link Layer) run on a STM32 MCU, with the SX1280 connected via SPI.

It uses the SX1280 C-Driver from Semtech to communicate with the SX1280. The main modification was to the SPI driver that uses DMA for full packets.

Status

Tested with the Miromico FMLR-80-P-STL4E module and our SX1280 Shield - see (port/stm32-l476rg-nucleo-sx1280). On the FMLR-80-P-STL4E module, the 52 Mhz clock for the SX1280 is controlled by the MCU.

SEGGER RTT is used for debug output, so a Segger J-Link programmer is required.

Uses 32.768 kHz crytstal as LSE for timing

Support for Broadcast and Peripheral roles.

The Makefile project compiles gatt_counter, gatt_streamer_server, hog_mouse and hog_keyboard examples.

Limitation

Advertising State:

Connection State:

Central Role:

Observer Role:

Low power mode - basically not implemented:

Getting Started

For the FMLR-80-P-STL4E module, just run make. You can upload the EXAMPLE.elf file created in build folder, e.g. with Ozone using the provided EXAMPLE.jdebug, and run it.

TODO

General

Low Power

BTstack Port with Cinnamon for Semtech SX1280 Controller on STM32L476 Nucleo

Cinnamon is BlueKitchen's minimal, yet robust Controller/Link Layer implementation for use with BTstack.

In contrast to common Link Layer implementations, our focus is on a robust and compact implementation for production use, where code size matters (e.g. current code size about 8 kB).

Overview

This port targets the Semtech SX1280 radio controller. The Host Stack and the Controller (incl. Link Layer) run on a STM32 MCU, with the SX1280 connected via SPI.

It uses the SX1280 C-Driver from Semtech to communicate with the SX1280. The main modification was to the SPI driver that uses DMA for full packets.

Status

Tested with theMiromico FMLR-80-P-STL4E module (see port/stm32-l451-miromico-sx1280) and the STM32 L476 Nucleo dev kit with our SX1280 Shield.

SEGGER RTT is used for debug output, so a Segger J-Link programmer is required, but the on-board ST-Link programmer and debugger can be replaced by an SEGGER J-Link OB.

Uses 32.768 kHz crytstal as LSE for timing

Support for Broadcast and Peripheral roles.

The Makefile project compiles gatt_counter, gatt_streamer_server, hog_mouse and hog_keyboard examples.

Limitation

Advertising State:

Connection State:

Central Role:

Observer Role:

Low power mode - basically not implemented:

Getting Started

Just run make. You can upload the EXAMPLE.elf file created in build folder, e.g. with Ozone using the provided EXAMPLE.jdebug, and run it.

TODO

General

Low Power

STM32 L476RG Nucleo with SX1280 Shield

BTstack Port for STM32WB55 Nucleo Boards using FreeRTOS

This port supports the Nucleo68 and the USB dongle of the P-NUCLEO-WB55 kit. Both have 1 MB of Flash memory.

The STM32Cube_FW_WB_V1.3.0 provides the HAL and WPAN, and initializes the device and the initial Makefile. For easy development, Ozone project files are generated as well.

Hardware

In this port, the Nucelo68 or the USB Dongle from the P-NUCLEO-WB55 can be used. Development was done using FUS v1.0.1 and v1.0.2 and Full BLE Stack v1.3.1. See STM32Cube_FW_WB_V1.3.0/Projects/STM32WB_Copro_Wireless_Binaries/Release_Notes.html for update instructions.

Note: Segger RTT currently doesn't work as output stops after CPU2 (radio controller) has started up.

Nucleo68

The debug output is sent over USART1 and is available via the ST-Link v2.

USB Dongle

To flash the dongle, SWD can be used via the lower 6 pins on CN1: - 3V3 - PB3 - SWO (semi hosting not used) - PA14 - SCLK - PA13 - SWDIO - NRST - GND

The debug output is sent over USART1 and is available via PB6.

Software

FreeRTOS V10.2.0 is used to run stack, you can get this example version by checking out official repo:

$ cd Middlewares
$ git submodule add https://github.com/aws/amazon-freertos.git
$ git submodule update
& cd amazon-freertos && git checkout v1.4.8

Or by specifying path to FreeRTOS

$ make FREERTOS_ROOT=path_to_freertos

To build all examples, run make

$ make

All examples and the .jedbug Ozone project files are placed in the 'build' folder.

Flash And Run The Examples

The Makefile builds different versions: - example.elf: .elf file with all debug information - example.bin: .bin file that can be used for flashing

Nucleo68

There are different options to flash and debug the Nucleo68 board. The Nucleo68 boards comes with an on-board ST-Link programmer and debugger. As an alternative, the ST-Link programmer can be replaced by an SEGGER J-Link OB. Finally, the STM32 can be programmed with any ARM Cortex JTAG or SWD programmer via the SWD jumper.

USB Dongle

Please use any ARM Cortex SWD programmer via the SWD interface desribed in the hardware section.

Run Example Project using Ozone

When using an external J-Link programmer or after installing J-Link OB on the Nucleo68 board, you can flash and debug using the cross-platform SEGGER Ozone Debugger. It is included in some J-Link programmers or can be used for free for evaluation usage.

Just start Ozone and open the .jdebug file in the build folder. When compiled with "ENABLE_SEGGER_RTT", the debug output shows up in the Terminal window of Ozone. Note: as mentioned before, Segger RTT currently stops working when CPU2 has started up.

Debug output

All debug output can be either send via SEGGER RTT or via USART1. To get the console from USART1, simply connect your board under STLink-v2 to your PC or connect PB6 (USART1 TX) of the Nucleo board to an USB-2-UART adapter and open a terminal at 115200.

In src/btstack_config.h resp. in example/btstack_config.h of the generated projects, additional debug information can be enabled by uncommenting ENABLE_LOG_INFO.

Also, the full packet log can be enabled in src/btstack_port.c by uncommenting the hci_dump_init(..) line. The console output can then be converted into .pklg files for OS X PacketLogger or WireShark by running tool/create_packet_log.py

GATT Database

In BTstack, the GATT Database is defined via the .gatt file in the example folder. During the build, the .gatt file is converted into a .h file with a binary representation of the GATT Database and useful defines for the application.

BTstack Port for WICED platform

Tested with: - WICED SDK 3.4-6.2.1 - RedBear Duo: Please install RedBear WICED Add-On - Inventek Systems ISM4334x - Please contact Inventek Systems for WICED platform files - Inventek Systems ISM4343 (BCM43438 A1) - Please contact Inventek Systems for WICED platform files

To integrate BTstack into the WICED SDK, please move the BTstack project into WICED-SDK-6.2.1/libraries.

Then create projects for BTstack examples in WICED/apps/btstack by running:

./create_examples.py

Now, the BTstack examples can be build from the WICED root in the same way as other examples, e.g.:

./make btstack.spp_and_le_counter-RB_DUO

to build the SPP-and-LE-Counter example for the RedBear Duo (or use ISM43340_M4G_L44 / ISM4343_WBM_L151 for the Inventek Systems devices).

See WICED documentation about how to upload the firmware.

It should work with all WICED platforms that contain a Broadcom Bluetooth chipset.

The maximal baud rate is currenty limited to 1 mbps.

The port uses the generated WIFI address plus 1 as Bluetooth MAC address. It persists the LE Device DB and Classic Link Keys via the DCT mechanism.

All examples that rovide a GATT Server use the GATT DB in the .gatt file. Therefore you need to run ./update_gatt_db.sh in the apps/btstack/$(EXAMPLE) folder after modifying the .gatt file.

BTstack Port for Windows Systems with Bluetooth Controller connected via Serial Port

The Windows-H4 port uses the native run loop and allows to use Bluetooth Controllers connected via Serial Port.

Make sure to manually reset the Bluetooth Controller before starting any of the examples.

Toolchain

The port requires a Unix-like toolchain. We successfully used mingw-w64 to compile and run the examples. mingw64-w64 is based on MinGW, which '...provides a complete Open Source programming tool set which is suitable for the development of native MS-Windows applications, and which do not depend on any 3rd-party C-Runtime DLLs.'

We've used the Msys2 package available from the downloads page on Windows 10, 64-bit and use the MSYS2 MinGW 64-bit start menu item to compile 64-bit binaries.

In the MSYS2 shell, you can install everything with pacman:

$ pacman -S git
$ pacman -S make
$ pacman -S mingw-w64-x86_64-toolchain
$ pacman -S python
$ pacman -S winpty

Compilation

With mingw64-w64 installed, just go to the port/windows-winusb directory and run make

$ cd btstack/port/windows-winusb
$ make

Note: When compiling with msys2-32 bit and/or the 32-bit toolchain, compilation fails as conio.h seems to be mission. Please use msys2-64 bit with the 64-bit toolchain for now.

Console Output

When running the examples in the MSYS2 shell, the console input (via btstack_stdin_support) doesn't work. It works in the older MSYS and also the regular CMD.exe environment. Another option is to install WinPTY and then start the example via WinPTY like this:

$ winpty ./spp_and_le_counter.exe

BTstack Port for Windows Systems with DA14585 Controller connected via Serial Port

This port allows to use the DA14585 connected via Serial Port with BTstack running on a Win32 host system.

It first downloads the hci_585.hex firmware from the 6.0.8.509 SDK, before BTstack starts up.

Please note that it does not detect if the firmware has already been downloaded, so you need to reset the DA14585 before starting an example.

For production use, the HCI firmware could be flashed into the OTP and the firmware download could be skipped.

Tested with the official DA14585 Dev Kit Basic on OS X and Windows 10.

Toolchain

The port requires a Unix-like toolchain. We successfully used mingw-w64 to compile and run the examples. mingw64-w64 is based on MinGW, which '...provides a complete Open Source programming tool set which is suitable for the development of native MS-Windows applications, and which do not depend on any 3rd-party C-Runtime DLLs.'

We've used the Msys2 package available from the downloads page on Windows 10, 64-bit and use the MSYS2 MinGW 64-bit start menu item to compile 64-bit binaries.

In the MSYS2 shell, you can install everything with pacman:

$ pacman -S git
$ pacman -S make
$ pacman -S mingw-w64-x86_64-toolchain
$ pacman -S python
$ pacman -S winpty

Compilation

With mingw64-w64 installed, just go to the port/windows-winusb directory and run make

$ cd btstack/port/windows-winusb
$ make

Note: When compiling with msys2-32 bit and/or the 32-bit toolchain, compilation fails as conio.h seems to be mission. Please use msys2-64 bit with the 64-bit toolchain for now.

Console Output

When running the examples in the MSYS2 shell, the console input (via btstack_stdin_support) doesn't work. It works in the older MSYS and also the regular CMD.exe environment. Another option is to install WinPTY and then start the example via WinPTY like this:

$ winpty ./spp_and_le_counter.exe

BTstack Port for Windows Systems with Zephyr-based Controller

The main difference to the regular posix-h4 port is that that the Zephyr Contoller uses 1000000 as baud rate. In addition, the port defaults to use the fixed static address stored during production.

Prepare Zephyr Controller

Please follow this blog post about how to compile and flash samples/bluetooth/hci_uart to a connected nRF5 dev kit.

In short: you need to install an arm-none-eabi gcc toolchain and the nRF5x Command Line Tools incl. the J-Link drivers, checkout the Zephyr project, and flash an example project onto the chipset:

Configure serial port

To set the serial port of your Zephyr Controller, you can either update config.device_name in main.c or always start the examples with the correct -u COMx option.

Toolchain

The port requires a Unix-like toolchain. We successfully used mingw-w64 to compile and run the examples. mingw64-w64 is based on MinGW, which '...provides a complete Open Source programming tool set which is suitable for the development of native MS-Windows applications, and which do not depend on any 3rd-party C-Runtime DLLs.'

We've used the Msys2 package available from the downloads page on Windows 10, 64-bit and use the MSYS2 MinGW 64-bit start menu item to compile 64-bit binaries.

In the MSYS2 shell, you can install everything with pacman:

$ pacman -S git
$ pacman -S make
$ pacman -S mingw-w64-x86_64-toolchain
$ pacman -S python
$ pacman -S winpty

Compile Examples

$ make

Note: When compiling with msys2-32 bit and/or the 32-bit toolchain, compilation fails as conio.h seems to be mission. Please use msys2-64 bit with the 64-bit toolchain for now.

Run example

Just run any of the created binaries, e.g.

$ ./le_counter

The packet log will be written to /tmp/hci_dump.pklg

BTstack Port for Windows Systems using the WinUSB Driver

The Windows-WinUSB port uses the native run loop and WinUSB API to access a USB Bluetooth dongle.

Access to Bluetooth USB Dongle with Zadig

To allow libusb or WinUSB to access an USB Bluetooth dongle, you need to install a special device driver to make it accessible to user space processes.

It works like this:

Toolchain

The port requires a Unix-like toolchain. We successfully used mingw-w64 to compile and run the examples. mingw64-w64 is based on MinGW, which '...provides a complete Open Source programming tool set which is suitable for the development of native MS-Windows applications, and which do not depend on any 3rd-party C-Runtime DLLs.'

We've used the Msys2 package available from the downloads page on Windows 10, 64-bit and use the MSYS2 MinGW 64-bit start menu item to compile 64-bit binaries.

In the MSYS2 shell, you can install everything with pacman:

$ pacman -S git
$ pacman -S make
$ pacman -S mingw-w64-x86_64-toolchain
$ pacman -S python
$ pacman -S winpty

Compilation

With mingw64-w64 installed, just go to the port/windows-winusb directory and run make

$ cd btstack/port/windows-winusb
$ make

Note: When compiling with msys2-32 bit and/or the 32-bit toolchain, compilation fails as conio.h seems to be mission. Please use msys2-64 bit with the 64-bit toolchain for now.

Console Output

When running the examples in the MSYS2 shell, the console input (via btstack_stdin_support) doesn't work. It works in the older MSYS and also the regular CMD.exe environment. Another option is to install WinPTY and then start the example via WinPTY like this:

$ winpty ./spp_and_le_counter.exe

BTstack Port for Windows Systems with Intel Wireless 8260/8265 Controllers

Same as port/windows-winusb, but customized for Intel Wireless 8260 and 8265 Controllers. These controller require firmware upload and configuration to work. Firmware and config is downloaded from the Linux firmware repository.

Access to Bluetooth USB Dongle with Zadig

To allow libusb or WinUSB to access an USB Bluetooth dongle, you need to install a special device driver to make it accessible to user space processes.

It works like this:

Toolchain

The port requires a Unix-like toolchain. We successfully used mingw-w64 to compile and run the examples. mingw64-w64 is based on MinGW, which '...provides a complete Open Source programming tool set which is suitable for the development of native MS-Windows applications, and which do not depend on any 3rd-party C-Runtime DLLs.'

We've used the Msys2 package available from the downloads page on Windows 10, 64-bit and use the MSYS2 MinGW 32-bit start menu item to compile 32-bit binaries that run on both 32/64-bit systems.

In the MSYS2 shell, you can install git, python, and, winpty with pacman:

$ pacman -S git
$ pacman -S python
$ pacman -S winpty

Compilation

With mingw64-w64 installed, just go to the port/windows-winusb directory and run make

$ cd btstack/port/windows-winusb
$ make

Note: When compiling with msys2-32 bit and/or the 32-bit toolchain, compilation fails as conio.h seems to be mission. Please use msys2-64 bit with the 64-bit toolchain for now.

Console Output

When running the examples in the MSYS2 shell, the console input (via btstack_stdin_support) doesn't work. It works in the older MSYS and also the regular CMD.exe environment. Another option is to install WinPTY and then start the example via WinPTY like this:

$ winpty ./spp_and_le_counter.exe