Here is a list of 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

$ run 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_open(..) 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

  • BTstack's TLV persisten storage via Flash memory is not implemented yet.
  • SPI Fullduplex: Newer Apollo 2 revisions supports SPI Full Duplex. The Ambiq Suite 1.2.11 does not cover Full Duplex with IRQ callback. It could be emulated by setting the Full Duplex mode and doing a regular write operation. When the write is complete, the received data can be read from the IOM FIFO.
  • During MCU sleep without an ongoing SPI operation, the SPI could be fully disabled, which would reduce enrgey consumption.

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

  • Follow Espressif IoT Development Framework (ESP-IDF) setup to install XTensa toolchain and the ESP-IDF.
  • Make sure your checkout is newer than 4654278b1bd6b7f7f55013f7edad76109f7ee944 from Aug 25th, 2017
  • In port/esp32/template, configure the serial port for firmware upload as described in the ESP-IDF setup guides.

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

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:

  • btstack_run_loop_freertos_execute_code_on_main_thread allows to directly schedule a function callback, i.e. 'do BTstack tasks' function, from the BTstack thread.
  • Setup a BTstack Data Source (btstack_data_source_t): Set 'do BTstack tasks' function as its process function and enable its polling callback (DATA_SOURCE_CALLBACK_POLL). The process function will be called in every iteration of the BTstack Run Loop. To trigger a run loop iteration, you can call btstack_run_loop_freertos_trigger.

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 for iOS

BTstack for iOS provides an alternative Bluetooth stack for iOS devices with a public API.

It supports the following Bluetooth Classic protocols: - L2CAP - RFCOMM - SDP

Based on these protocols, applications or daemons can implement various Bluetooth profiles. Packages that already use BTstack are: BTstack GPS, Blutrol, WeBe++, and various game emulators.

Note: As BTstack directly uses the Bluetooth hardware, the iOS Bluetooth is automatically disabled for BTstack applications & services. You can always turn BTstack off in Settings->BTstack.

Please visit the project page at GitHub for technical information and check the port/ios subfolder.

How to develop

To write BTstack-based applications, you don't need to compile the BTstack Cydia package. You can just install it on your JB iOS device and copy /usr/lib/libBTstack.dylib into your project and add btstack/include to your project includes.

While it's possible to use Xcode, I highly recommend to use theos to create apps & daemons for JB iOS devices instead.

Compile Instructions for BTstack package

Install the following tools: Xcode csu-ios libraries for deployment targets < 6.0 (BTstack compiles againt iOS 3.0 by default) * rpetrich's or new official theos fork with "lippoplastic" support

Set the $THEOS environment variable to the location of the theos checkout, e.g. like:

export THEOS=/Projects/theos

Go to btstack/port/ios and run make

cd btstack/port/ios
make package

If everything went right, you'll end up with a .deb package that you could install via:

make install

Console Examples

With THEOS set-up as before, you can compile and install a set of command line examples in the example folder:

cd btstack/port/ios/example
make

You can copy the created examples to your device using scp and run it from there.

Wii Mote CoocaTouch example

Similar as before, you can compile the WiiMoteOpenGLDemo by running make:

cd btstack/port/ios/example/WiiMoteOpenGLDemo
make package

You'll end up with a deb file that you can install with

make install

Note: as with any other JB application, you need to refresh the SpringBoard icon cache on the device to make the icon show up. After SSH to your device as root, you can execute these commands:

su mobile
uicache
exit

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

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"

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

  • Support for BTSTACK_STDIN
  • Add flash-openocd to Makefile template
  • Add Eclipse CDT projects for max32630fthr
  • Implement hal_led.h to control LED on board

Experimental port of BTstack to Zephyr 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

  • printf is configured by patching `drivers/serial/uart_nrf5.c' to use 115200 (default: 100000). There should be a better way to set baud rate.
  • enable/configure DLE for max packet size for LE Streamer

Experimental port for Nordic nRF5 Series

Overview

This port targets the bare Nordic nRF5-Series chipsets without the proprietary SoftDevice implementations.

Instead of taking shortcuts within BTstack, the idea here is to provide a complete HCI Controller interface. This requires to implement an HCI Command parser, an LE Link Layer.

Status

Only tested on the pca10028 dev board.

Only supports LE Scanning at the moment, e.g. with the gap_le_advertisements example.

Getting Started

To integrate BTstack into the nRF5 SDK, please move the BTstack project into nRF5_SDK_X/components. Then create projects for the BTstack examples in nRF5_SDK_X/examples/btstack by running:

./create_examples.py

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

cd examples/btstack/gap_le_advertisements/pca10028/armgcc
make

to build the gap_le_advertisements example for the pca10028 dev kit using the ARM GCC compiler.

See nRF5 SDK documentation about how to install it.

BTstack Port for the Microchip PIC32 Harmony Platform

Status: All examples working, polling UART driver. Tested on Bluetooth Audio Development Kit only. Created with Harmony v1.07, does not compile with new v2.x versions.

Hardware

The PIC32 Bluetooth Audio Development Kit comes with the CSR8811-based BTM805 Bluetooth module. In the port, the UART on the DAC daughter board was used for the debug output. Please remove the DAC board and connect a 3.3V USB-2-UART converter to GND and TX to get the debug output.

Software

Microchip MPLAB X IDE and the MPLAB XC32 compiler needs to be installed.

Setup

  • Place BTstack tree into harmony/framework folder.
  • Run port/pic32-harmony/create_examples.py to create examples in harmony/apps/btstack folder.

Usage

The examples can be opened and compiled in Microchip MPLAB X IDE or from the command line using the Makefile generated by it.

Modifications to the GATT Database

After changing the GATT definition in $example.gatt, please run ./update_gatt_db.h to regenerate example.h in the $example folder.

Compiler Warnings:

The project is set to use -Os optimization which will cause warnings if you only have the Free version. It will still compile a working example.

POSIX H4 Port for Atmel ATWILC3000

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

POSIX H4 Port for Dialog Semiconductor DA14581

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.

POSIX H4 Port for Dialog Semiconductor DA14585

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 Zephyr Controller with HCI UART Firmware Connectected To POSIX System

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 -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 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_open(..) 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.

STM32 F103RB Nucleo with CC256x

BTstack port for STM32 F103RB Nucleo board and CC256x Bluetooth chipset based on GNU Tools for ARM Embedded Processors and libopencm3

Requirements: - GNU Tools for ARM Embedded Processors: https://launchpad.net/gcc-arm-embedded - libopencm3 is automatically fetched and build from its git repository by make - openocd 0.8.0 (or higher) is used to upload firmware

Components: - STM32 F103RB Nucleo Board - User's Manual: http://www.st.com/web/en/resource/technical/document/user_manual/DM00105823.pdf - CC2564B Bluetooth Controller: 1. The best option is to get it as a BoostPack - Info: BOOST-CC2564MODA: http://www.ti.com/tool/BOOST-CC2564MODA 2. Alternatively, get the evaluation module together with the EM Wireless Booster pack and a 32.768 kHz oscillator - EM Wireless Booster Pack: - Info: http://www.ti.com/tool/boost-ccemadapter - User Guide: http://www.ti.com/lit/ug/swru338a/swru338a.pdf - Booster Pack Pinout: http://www.ti.com/ww/en/launchpad/dl/boosterpack-pinout-v2.pdf - CC256x Evaluation Module: - Info: http://www.ti.com/tool/cc256xqfnem

Configuration: - Sys tick 250 ms - LED on PA5, on when MCU in Run mode and off while in Sleep mode - Debug UART: USART2 - 9600/8/N/1, TX on PA2 - Bluetooth: USART3 with hardware flowcontrol RTS. IRQ on CTS Rising. TX PB10, RX PB11, CTS PB13 (in), RTS PB14 (out), N_SHUTDOWN PB15

Setup with CC2564 BoosterPack (BOOST-CC2564MODA): - Connect STM32 Nucleo Board to EM Wireless Board (see BoosterPack pinout) - GND: CN10-9 - 20 (J2) - VCC: CN7 -16 - 1 (J1) - RX3: CN10-18 - 3 (J1) - TX3: CN10-25 - 4 (J1) - CTS3: CN10-30 - 36 (J4) - RTS3: CN10-28 - 37 (J4) - N_SHUTDOWN: CN10-26 - 19 (J2)

Setup with EM Wireless BoosterPack + CC256x Evaluation Module: - Solder 32.768 kHz quarz oscillator to EM Adapter Booster Pack 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. - Connect STM32 Nucleo Board to EM Wireless Board (see BoosterPack pinout) - GND: CN10-9 - 20 (LP2) - VCC: CN7 -16 - 1 (LP1) - RX3: CN10-18 - 3 (LP1) - TX3: CN10-25 - 4 (LP1) - CTS3: CN10-30 - 11 (LP2) - RTS3: CN10-28 - 12 (LP2) - N_SHUTDOWN: CN10-26 - 10 (LP1)

TODO: - figure out how to compile multiple examples with single Makefile/folder

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 and initialize the device. Finally, Eclipse CDT + GNU ARM Eclipse projects for all examples are provided. GNU ARM Eclipse OpenOCD was used to flash and debug the examples.

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 CC2564B. When using the CC2564C, bluetooth_init_cc2564C_1.0.c should be use as cc256x_init_script, see ./create_examples.py.

Software

To compile and flash the examples, Eclipse CDT with GNU ARM Eclipse is used. Please follow the installation instructions here: http://gnuarmeclipse.github.io You also need to install the GNU ARM Eclipse OpenOCD debugger plug-in.

Create Example Projects

Eclipse requires a separate project per example. To create all example projects, navigate to this directory (btstack/port/stm32-f4discovery-cc256x) and run:

./create_examples.py

This will create an example subfolder with one project per example. Note: it currently requires about 500 MB.

Import Example Project

In Eclipse CDT, select "File -> Import...", then choose General->Existing Project into Workspace and click Next>. In the "Import Projects" dialog, select either the generated examples folder to import all projects or pick a single example.

Run Example Project

Build one of the examples by clicking on the 'Hammer' icon, then start it via the provided Debug Launch configuration "example-debug". Note: It's not clear why there are two debug configurations for an example project sometimes.

Debug output

printf is routed to USART2. To get the console output, 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_open(..) 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. Before it can be used, run the provided update_gatt_db.sh script in each project folder.

Note: In theory, this can be integrated into the Eclipse project, in fact, it's easy to configure it as an Eclipse Builder, but it got tricky to correctly add it to the create_examples.py tool. So, whenever you're updating the .gatt file, please run ./update_gatt_db.sh manually.

TODOs

  • move unmodified STM32 Cube files provided by ST32CubeMx into 3rd-party/STM32
  • link to sources instead of copying into every example project
  • support on-board DAC in A2DP Sink Demo

Maintainer Notes - Updating The Port

This paragraph is mainly for the maintainers. It describes the steps to make changes to the CubeMX configuration and how to update the Eclipse template after that.

Update cubemx-f4discovery-cc256x from STM32CubeMX project

  • open ST32CubeMX
  • load project file cubemx-f4discovery-cc256x/cubemx-f4discovery-cc256x.ioc
  • generate code and documentation
  • patch generated sources: ./patch-cubemx-project.sh

Update local Eclipse project from cubemx-f4discovery-cc256x

This uses local Eclipse project generated manually from STM32 template provided by GNU ARM Eclipse using the CubeMX Importer

./import_cubemx_into_eclipse.sh

Update eclipse-template from local Eclipse project

./update_from_eclipse.sh

BTstack port for STM32 Nucleo-L053R8 Board with an EM9304 Shield - EM9304 DVK

This port uses the STM32 Nucleo-L053R8 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. An examples can be uploaded onto the device by copying it to the Nucleo virtual mass storage drive.

Hardware

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

Software

To build all examples, go to the cubemx-l053r8-em9304 folder

$ cd cubemx-l053r8-em9304

and run make

$ make

All examples are placed in the 'build' folder.

Debug output

printf is routed to USART2. To get the console output, open a terminal at 115200 for the virtual serial port of the Nucleo board.

Additional debug information can be enabled by uncommenting ENABLE_LOG_INFO in btstack_config.h.

Also, the full packet log can be enabled in port.c by uncommenting the hci_dump_open(..) 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.

Stability

When sending at full speed, it's possible that the EM9304 hangs up. This patch (connection_event_overlay.emp) fixes this problems in our tests. It can be applied with the EM ConfigEditor available via the EM Technical Support.

Multiple LE Peripheral/Central Roles

It should be possible to use the EM9304 in multiple roles. In the default configuration, it only supports a single connection. For multiple roles, it needs to be configured for more connections at least.

Performace

With the patch, the LE Streamer example is able to send up to 10 packets per Connection Event to an iPhone SE with iOS 10.2, resulting in around 6.5 kB/s throughput for this direction.

Image

EM9304 DVK

BTstack port for WICED platform

Tested with: - WICED SDK 3.4-5.2 - RedBear Duo: Please install RedBear WICED Add-On - Inventek Systems ISM4334x: Please install Inventek WICED Patches

To integrate BTstack into the WICED SDK, please move the BTstack project into WICED-SDK-5.2/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 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 WICED platform using H5 transport and Broadcom/Cypress Bluetooth chipsets.

BTstack port for WICED platform

Tested with: - WICED SDK 3.4-5.2 - RedBear Duo: Please install RedBear WICED Add-On - Inventek Systems ISM4334x: Please install Inventek WICED Patches

To integrate BTstack into the WICED SDK, please move the BTstack project into WICED-SDK-5.2/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 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.

Additoinal notes on the H5 port

If the CTR/RTS hardware control lines of the Bluetooth Controller is connected to your MCU, we recommend using the wiced-h4 port instead. If they are not connected, H5 is required to provide a reliable connection including retransmissions in both directions.

There are a few oddities so far that had to be worked around in H5 mode:

  • It does not seem possible to upload the FW Mini Driver a.k.a. patchram a.k.a. init script via H5. BTstack uses btstack_chipset_bcm_download_firmware.c to upload the FW Mini Driver via a minimal H4 implementation, before starting up in H5 mode. BCM/CYP chipsets are able to switch to H5.

  • With the AP6212A on the RedBear Duo and the FW Mini Driver from WICED-SDK-3.5.2/libraries/drivers/bluetooth/firmware/43438A1/26MHz/bt_firmware_image.c, the HCI LE Encrypt command to perform an AES128 encryption hangs in H5 (but works in H4). See Bug Report in Community Forum As a work around, BTstack was configured to use a CPU implementation of AES128 (#define HAVE_AES128).

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

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 Zephyr Controller with HCI UART Firmware Connectected To POSIX System

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

  • Download Zadig
  • Start Zadig
  • Select Options -> “List all devices”
  • Select USB Bluetooth dongle in the big pull down list
  • Select WinUSB (libusb) in the right pull pull down list
  • Select “Replace Driver”

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

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