bluekitchen/btstack: a Bluetooth stack you port with three functions, and a licence you have to ask about

The entire porting contract is UART, CPU and CLOCK

Most of what a Bluetooth stack asks of a platform is a large surface of vendor specific glue, and the claim this project makes is that its surface is three functions. The README states that targeting a variety of platforms is as simple as providing the necessary UART, CPU and CLOCK implementations, and that is the whole contract. For an 8 or 16 bit part with a serial interface to a Bluetooth module, that is a tractable amount of work, and it is the reason the stack is described as suitable for small, resource constrained devices. The description gives the reason as high configurability and an ultra small memory footprint, and it is worth noticing that neither claim comes with a number. There is no table of flash usage or RAM usage per feature set anywhere in this material, so the footprint claim has to be taken on trust or measured on your own configuration, which for a stack of this kind varies enormously depending on which profiles are compiled in. The runtime story is equally small. On a small system a minimal run loop implementation is provided so the stack can be used with no real time operating system at all. If you already have one, the stack integrates and runs as a single thread. There is no scheduler requirement, no task per profile, and nothing that assumes you have a kernel, which is the difference between a library you can use on a part with 8 KB of RAM and one you cannot.

H2, H4 with eHCILL, and H5: the stack talks to a module

The connection to the radio is the second thing that shapes a port, and the README is specific about it. BTstack is currently capable of connecting to Bluetooth modules over three transports, named by their HCI transport identifiers. H2 is HCI over USB. H4 is HCI over UART, including TI's eHCILL flow control variant. H5 is HCI over a three wire UART. That list is short and the implication is clear. This is a host side stack that drives an external module, not a stack bound to an on-chip radio, so your board needs a serial link or USB to a module and the porting work is about that link rather than about a driver for a particular silicon peripheral. The eHCILL mention is the sort of detail that saves a week, because that vendor variant changes the framing on the same UART and a port written without knowing about it fails in a way that looks like a timing bug. It also means the module you choose constrains you, since the module has to speak one of these three transports and has to implement the Bluetooth features you intend to use. The feature list at the top of the README is the compatibility target to check against that module rather than a general statement: two megabit LE, coded PHY, isochronous channels, extended advertising, periodic advertising, LE Secure Connections and classic audio. A module without isochronous channel support, for example, rules out the LE Audio features further down the page no matter what the stack supports.

Three deployment shapes: a run loop, a thread, or a socket server

The same stack appears in three shapes depending on what you are building, and the README describes each. On a small system it is driven by the minimal run loop with no operating system underneath it, so the application and the stack share one loop and you call into it from your own main. Where a real time operating system already exists, the stack runs as a single thread, which is the arrangement most firmware teams end up with because the rest of the product already has one. On larger systems, BTstack provides a server that connects to a Bluetooth module, and multiple applications talk to that server over inter-process communication. The detail that makes the third shape practical is that sockets are used for the client to server communication, which means a client does not have to be C and does not have to link against the stack. The README says this makes it easy to interact from higher level languages and notes that a Java binding already exists for desktop environments. So the same codebase can be a firmware component on one product and a background service with a desktop client on another, with the socket boundary as the contract. For an evaluation the useful question is which of the three you need, because it changes the integration work from a linker script and an interrupt handler into a protocol, and it changes where the Bluetooth logic lives relative to your application.

Free for non-commercial use, a quote for commercial: the licence is the gate

The licensing position is stated in two sentences and it is the first thing to settle, because it can end an evaluation on its own. BTstack is free for non-commercial use. For commercial use, the README asks you to describe your project and get a quote. There is no version number attached to that statement, no grant text in the README, and the licence file in the repository is a custom one that the forge cannot classify, so the README sentence is the summary of a document you have to read rather than a substitute for it. What that means practically is that this is not a permissive open source licence in the sense most companies mean, it is a dual arrangement where one half is free and the other half is negotiated, and a procurement process that expects a recognised identifier will not find one. The counterweight is that the commercial path is not a dead end, it is a conversation with a company that has been doing this long enough to have a SIG declaration, and a quote is a normal way to license embedded components. Two supporting facts make that conversation easier. The repository carries a directory for third party components with its own readme listing the libraries used and their licences, so the dependency licence position is documented rather than left for you to discover in a build. And the project is published by a company rather than by a hobbyist, which is what you would expect to mean both of the above.

SIG qualification Q331293, and the capabilities still behind a contact

For a Bluetooth stack, the specification qualification is the most consequential fact on the page, and this one has a number attached. BTstack has been qualified with the Bluetooth SIG under declaration Q331293, covering ATT, GAP, GATT, IOP, L2CAP, SDP and SM from the Bluetooth Core 6.0 specification, together with a long enumerated set of profile and service versions including A2DP, AVRCP, the LE Audio profile set, HID, HFP, the battery and device information services, and others, each with its own version. For a product that needs to be sold, that declaration is what you point at. Read the list rather than the headline, because it is finite and specific, and a feature appearing in the stack is not the same as a feature being qualified. The README also states a boundary in the opposite direction, saying that for information on Apple's MFi and iAP2 profiles or the Find My profiles, or for access to LE Audio, MAP and a PBAP server, you should contact them directly. That sentence sits in tension with the feature lists above it, which do enumerate LE Audio profiles and services and do list MAP and PBAP among the supported profiles. The honest reading is that implementation and availability are different things in this project, and the items in the contact sentence are the ones to raise before you design around them, because an iOS product almost certainly depends on at least one of them.

src, chipset, port and platform, plus .gatt files and two build systems

The top-level directories describe the architecture more clearly than any paragraph would. There is a source directory for the portable core, a chipset directory for silicon specific code, a port directory for the board and module glue, a platform directory which is where the UART, CPU and CLOCK implementations live, and separate directories for documentation, tests, tools and examples. That split is the porting contract in directory form, and it means a new target is a new port rather than a fork. The example directory is where the coverage becomes visible, because it is a list of C files named after the feature each one exercises: audio source and sink demos, an Apple notification centre client, an antenna test, an attribute server with a delayed response, audio duplex, an audio player, audio remote control browsing, a classic device under test harness, dedicated bonding, inquiry, LE advertisements, link keys, a battery query and a GATT browser. Two conventions in that list are worth picking up. Several demos ship with a file whose extension is gatt sitting next to the source, which is the project's way of declaring a GATT database as text alongside the code that uses it, so the service layout is data rather than generated boilerplate and can be reviewed as a diff. And there are two build systems side by side, a CMake list and a makefile include, so you can bring the examples up in whichever build your firmware already uses. The classic device under test harness is the piece to look at if you care about qualification, since that is what running the official test suite looks like in practice.

Protocol and profile breadth, and the line the README draws

The middle of the page is a very long inventory, and reading it as a list rather than as a claim tells you where the project is strong. At the protocol layer it covers L2CAP with enhanced retransmission mode and both the credit based and enhanced credit based flow control modes, RFCOMM, SDP, BNEP, the audio distribution and control protocols, ATT, and security manager including LE Secure Connections and cross transport key derivation, which is the mechanism that lets a pairing done over one transport be trusted on another. Above that sit the familiar profiles: audio distribution and remote control, the generic and attribute profiles, hands free and headset, HID, the phone profiles, object push, serial port and PAN, with browsing and cover art extensions on remote control. Then the GATT server and client inventories, which are the part most projects actually consume, listing server sides for battery, bond management, cycling power and cadence, device information, heart rate, HID over GATT, link loss, mesh provisioning and proxy, object transfer, scan parameters, transmit power and two vendor flavoured serial services, and client sides including the Apple notification centre and HID over GATT host. The LE Audio block is the newest surface, with a dozen profiles and a dozen services, from volume and microphone control through broadcast audio scanning to hearing access. The line the README draws is at the end of that section, and it is a useful one. GATT services are generally easy to implement and require little development time, and for more of them you are pointed at the generic attribute profile implementation guidelines or told to make contact. So the practical reading is that the listed services cover the common cases, and anything specific to your product is a small amount of your own work rather than a request.

Editorial conclusion

BTstack fits a product with a real Bluetooth module, an engineering team willing to own the port, and a commercial licence conversation already in progress, because those three conditions are what the project asks for and nothing in the repository removes them. It does not fit a hobby build you intend to sell, because the terms are explicit that commercial use requires a quote, and a custom licence file that no forge can classify is not something to review against an existing policy without reading it. Two checks are worth doing before any of that. Read the qualification declaration, since the list of qualified specifications and versions is finite and does not cover everything the feature list names, and confirm which capabilities you actually need are in it, because the README routes Apple MFi and iAP2 profiles, Find My, and access to parts of the LE Audio set and two other profiles through a direct contact rather than through the download. Then look at the port contract, which is the part that decides feasibility: if you cannot supply a UART, a clock and CPU primitives for your part, the rest of the library does not apply.

Frequently asked questions

Official sources

1. bluekitchen/btstack on GitHub
2. Issues
3. Project website
4. README