diff --git a/docs/manual/markdown/Makefile b/docs/manual/markdown/Makefile index d7dc4a457..0490a4091 100644 --- a/docs/manual/markdown/Makefile +++ b/docs/manual/markdown/Makefile @@ -2,3 +2,4 @@ all: ./update_apis.py ./update_listings.py mkdocs build --clean + echo "a.toctree-l4 { display: none; }" >> btstack/css/theme_extra.css diff --git a/docs/manual/markdown/docs/appendix/apis.md b/docs/manual/markdown/docs/appendix/apis.md index 7819a0bb6..9763c2967 100644 --- a/docs/manual/markdown/docs/appendix/apis.md +++ b/docs/manual/markdown/docs/appendix/apis.md @@ -74,7 +74,7 @@ ## HCI API - le_connection_parameter_range_t gap_le_get_connection_parameter_range(); + le_connection_parameter_range_t gap_le_get_connection_parameter_range(void); void gap_le_set_connection_parameter_range(le_connection_parameter_range_t range); /* LE Client Start */ @@ -163,6 +163,12 @@ * @brief Get addr type and address used in advertisement packets. */ void hci_le_advertisement_address(uint8_t * addr_type, bd_addr_t addr); + + /** + * @brief Set callback for Bluetooth Hardware Error + */ + void hci_set_hardware_error_callback(void (*fn)(void)); + ## L2CAP API diff --git a/docs/manual/markdown/docs/architecture.md b/docs/manual/markdown/docs/architecture.md index f077cd9db..9b2fe18a4 100644 --- a/docs/manual/markdown/docs/architecture.md +++ b/docs/manual/markdown/docs/architecture.md @@ -1,3 +1,4 @@ + As well as any other communication stack, BTstack is a collection of state machines that interact with each other. There is one or more state machines for each protocol and service that it implements. The rest of @@ -29,7 +30,7 @@ for providing timers and processing incoming data. ![Architecture of a BTstack-based application.](picts/btstack-architecture.png) -# Single threaded design +## Single threaded design BTstack does not use or require multi-threading. It uses a single run loop to handle data sources and timers. Data sources represent @@ -43,7 +44,7 @@ timers that are ready are executed. For adapting BTstack to multi-threaded environments check [here](integration/#sec:multithreading). -# No blocking anywhere +## No blocking anywhere Bluetooth logic is event-driven. Therefore, all BTstack functions are non-blocking, i.e., all functions that cannot return immediately @@ -57,7 +58,7 @@ processing should be split into smaller chunks. The packet handler could then schedule a timer that manages the sequential execution of the chunks. -# No artificially limited buffers/pools +## No artificially limited buffers/pools Incoming and outgoing data packets are not queued. BTstack delivers an incoming data packet to the application before it receives the next one @@ -71,7 +72,7 @@ Bluetooth module, the application cannot send. For RFCOMM, the mandatory credit-based flow-control limits the data sending rate additionally. The application can only send an RFCOMM packet if it has RFCOMM credits. -# Statically bounded memory +## Statically bounded memory BTstack has to keep track of services and active connections on the various protocol layers. The number of maximum diff --git a/docs/manual/markdown/docs/examples/generated.md b/docs/manual/markdown/docs/examples/generated.md index d292ef0e0..0be047104 100644 --- a/docs/manual/markdown/docs/examples/generated.md +++ b/docs/manual/markdown/docs/examples/generated.md @@ -1,5 +1,3 @@ -# Embedded Examples - In this section, we will describe a number of examples from the *example/embedded* folder. To allow code-reuse with different platforms as well as with new ports, the low-level initialization of BTstack and diff --git a/docs/manual/markdown/docs/examples/intro.md b/docs/manual/markdown/docs/examples/intro.md index 33cd563b5..6d6599f5e 100644 --- a/docs/manual/markdown/docs/examples/intro.md +++ b/docs/manual/markdown/docs/examples/intro.md @@ -1,5 +1,3 @@ -# Embedded Examples - In this section, we will describe a number of examples from the *example/embedded* folder. To allow code-reuse with different platforms as well as with new ports, the low-level initialization of BTstack and diff --git a/docs/manual/markdown/docs/how_to.md b/docs/manual/markdown/docs/how_to.md index 8e40f01ea..8d796b5fd 100644 --- a/docs/manual/markdown/docs/how_to.md +++ b/docs/manual/markdown/docs/how_to.md @@ -1,3 +1,4 @@ + BTstack implements a set of basic Bluetooth protocols. To make use of these to connect to other devices or to provide own services, BTstack has to be properly configured during application startup. @@ -13,7 +14,7 @@ resource-constraint devices. -# Memory configuration +## Memory configuration The structs for services, active connections and remote devices can be allocated in two different manners: @@ -54,7 +55,7 @@ The memory is set up by calling *btstack_memory_init* function: -# Run loop +## Run loop BTstack uses a run loop to handle incoming data and to schedule work. The run loop handles events from two different types of sources: data @@ -110,7 +111,7 @@ communication over the UART. -# BTstack initialization +## BTstack initialization To initialize BTstack you need to [initialize the memory](#section:memory_configuration) and [the run loop](#section:run_loop) respectively, then setup HCI and all needed higher @@ -191,7 +192,7 @@ following section. -# Services +## Services One important construct of BTstack is *service*. A service represents a server side component that handles incoming connections. So far, BTstack @@ -205,7 +206,7 @@ created by the application when needed. -# Where to get data - packet handlers +## Where to get data - packet handlers After the hardware and BTstack are set up, the run loop is entered. From @@ -283,7 +284,7 @@ a packet handler to accept and receive keyboard data. -# Bluetooth HCI Packet Logs +## Bluetooth HCI Packet Logs If things don't work as expected, having a look at the data exchanged diff --git a/docs/manual/markdown/docs/index.md b/docs/manual/markdown/docs/index.md index af783de29..adfdea24a 100644 --- a/docs/manual/markdown/docs/index.md +++ b/docs/manual/markdown/docs/index.md @@ -1,3 +1,4 @@ + Thanks for checking out BTstack! In this manual, we first provide a 'quick starter guide' for common platforms diff --git a/docs/manual/markdown/docs/integration.md b/docs/manual/markdown/docs/integration.md index 4ae5c7419..fcddddb04 100644 --- a/docs/manual/markdown/docs/integration.md +++ b/docs/manual/markdown/docs/integration.md @@ -1,3 +1,4 @@ + While the run loop provided by BTstack is sufficient for new designs, BTstack is often used with or added to existing projects. In this case, the run loop, data sources, and timers may need to be adapted. The diff --git a/docs/manual/markdown/docs/porting.md b/docs/manual/markdown/docs/porting.md index c5de43d9c..9540b63da 100644 --- a/docs/manual/markdown/docs/porting.md +++ b/docs/manual/markdown/docs/porting.md @@ -1,5 +1,3 @@ -# Porting to Other Platforms - In this section, we highlight the BTstack components that need to be adjusted for different hardware platforms. diff --git a/docs/manual/markdown/docs/profiles.md b/docs/manual/markdown/docs/profiles.md index 0ce074153..b761d073c 100644 --- a/docs/manual/markdown/docs/profiles.md +++ b/docs/manual/markdown/docs/profiles.md @@ -1,5 +1,4 @@ -# Supported Profiles In the following, we explain how the various Bluetooth profiles are used in BTstack. diff --git a/docs/manual/markdown/docs/protocols.md b/docs/manual/markdown/docs/protocols.md index 929d82b4b..102ebb453 100644 --- a/docs/manual/markdown/docs/protocols.md +++ b/docs/manual/markdown/docs/protocols.md @@ -1,6 +1,4 @@ -# Supported Protocols - BTstack is a modular dual-mode Bluetooth stack, supporting both Bluetooth Basic Rate/Enhanced Date Rate (BR/EDR) as well as Bluetooth Low Energy (LE). The BR/EDR technology, also known as Classic Bluetooth, @@ -726,8 +724,7 @@ registered callback, as shown in Listing [below](#lst:SDPClientRFCOMM). de_pop_sequence(des_buffer, attribute); -BNEP - Bluetooth Network Encapsulation Protocol ------------------------------------------------ +## BNEP - Bluetooth Network Encapsulation Protocol The BNEP protocol is used to transport control and data packets over standard network protocols such as TCP, IPv4 or IPv6. It is built on top @@ -768,8 +765,7 @@ A *BNEP_EVENT_INCOMING_CONNECTION* event will mark that an incoming connection is established. At this point you can start sending and receiving Ethernet packets as described in the previous section. -ATT - Attribute Protocol ------------------------- +## ATT - Attribute Protocol The ATT protocol is used by an ATT client to read and write attribute values stored on an ATT server. In addition, the ATT server can notify @@ -788,8 +784,8 @@ application needs to register read and/or write callback. In addition, notifications and indications can be sent. Please see Section [section:GATTClient] for more. -SMP - Security Manager Protocol {#section:smp} --------------------------------- +## SMP - Security Manager Protocol + The SMP protocol allows to setup authenticated and encrypted LE connection. After initialization and configuration, SMP handles security diff --git a/docs/manual/markdown/docs/quick_start.md b/docs/manual/markdown/docs/quick_start.md index f446a2bfc..f6e24ccc3 100644 --- a/docs/manual/markdown/docs/quick_start.md +++ b/docs/manual/markdown/docs/quick_start.md @@ -1,4 +1,5 @@ -# General Tools + +## General Tools On Unix-based systems, git, make, and Python are usually installed. If not, use the system’s packet manager to install them. @@ -28,7 +29,7 @@ Adding paths to the Windows Path variable : - Ensure that there is a semicolon before and after [C:\Program Files\GnuWin32\bin](). -# Getting BTstack from GitHub +## Getting BTstack from GitHub Use git to clone the latest version: @@ -39,7 +40,7 @@ Alternatively, you can download it as a ZIP archive from [BTstack’s page](https://github.com/bluekitchen/btstack/archive/master.zip) on GitHub. -# Compiling the examples and loading firmware +## Compiling the examples and loading firmware This step is platform specific. To compile and run the examples, you need to download and install the platform specific toolchain and a flash @@ -51,7 +52,7 @@ can be loaded onto the device using platform specific flash programmer. For the PIC32-Harmony platform, a project file for the MPLAB X IDE is provided, too. -# Run the Example +## Run the Example As a first test, we recommend [the SPP Counter example](examples/generated/#section:sppcounter). During the startup, for TI chipsets, the init script is transferred, and the Bluetooth stack brought up. After that, @@ -59,12 +60,12 @@ the development board is discoverable as “BTstack SPP Counter” and provides a single virtual serial port. When you connect to it, you’ll receive a counter value as text every second. -# Platform specifics +## Platform specifics In the following, we provide more information on specific platform setups, toolchains, programmers, and init scripts. -## libusb +### libusb The quickest way to try BTstack is on a Linux or OS X system with an additional USB Bluetooth module. The Makefile [platforms/libusb]() in requires @@ -103,7 +104,7 @@ It’s also possible to run the examples on Win32 systems. For this: Now, you can run the examples from the *msys* shell the same way as on Linux/OS X. -## Texas Instruments MSP430-based boards +### Texas Instruments MSP430-based boards **Compiler Setup.** The MSP430 port of BTstack is developed using the Long Term Support (LTS) version of mspgcc. General information about it @@ -142,7 +143,7 @@ following software tools: prog blink.hex run -## Texas Instruments CC256x-based chipsets +### Texas Instruments CC256x-based chipsets **CC256x Init Scripts.** In order to use the CC256x chipset on the PAN13xx modules and others, an initialization script must be obtained. @@ -176,19 +177,19 @@ if present and merges them into a single .c file. -## MSP-EXP430F5438 + CC256x Platform +### MSP-EXP430F5438 + CC256x Platform **Hardware Setup.** We assume that a PAN1315, PAN1317, or PAN1323 module is plugged into RF1 and RF2 of the MSP-EXP430F5438 board and the “RF3 Adapter board” is used or at least simulated. See [User Guide](http://processors.wiki.ti.com/index.php/PAN1315EMK_User_Guide#RF3_Connector). -## STM32F103RB Nucleo + CC256x Platform +### STM32F103RB Nucleo + CC256x Platform To try BTstack on this platform, you’ll need a simple adaptor board. For details, please read the documentation in [platforms/stm32-f103rb-nucleo/README.md](). -## PIC32 Bluetooth Audio Development Kit +### PIC32 Bluetooth Audio Development Kit The PIC32 Bluetooth Audio Development Kit comes with the CSR8811-based BTM805 Bluetooth module. In the port, the UART on the DAC daughter board diff --git a/docs/manual/markdown/docs/revision_history.md b/docs/manual/markdown/docs/revision_history.md index 85b39efa9..65e37841e 100644 --- a/docs/manual/markdown/docs/revision_history.md +++ b/docs/manual/markdown/docs/revision_history.md @@ -1,3 +1,4 @@ + Rev | Date | Comments ----|------|--------- 1.x | April 27, 2015 | Added more platforms. Replaced Recipes with Protocols and Profiles. Added more examples. diff --git a/docs/manual/markdown/mkdocs.yml b/docs/manual/markdown/mkdocs.yml index 959bc4fe1..c0f218869 100644 --- a/docs/manual/markdown/mkdocs.yml +++ b/docs/manual/markdown/mkdocs.yml @@ -5,10 +5,10 @@ pages: - [quick_start.md, Quick Start] - [architecture.md, BTstack Architecture] - [how_to.md, How to use BTstack] -- [protocols.md, Protocols] -- [profiles.md, Profiles] -- [examples/generated.md, Examples] -- [porting.md, Porting] +- [protocols.md, Supported Protocols] +- [profiles.md, Supported Profiles] +- [examples/generated.md, Embedded Examples] +- [porting.md, Porting to Other Platforms] - [integration.md, Integrating with Existing Systems] - [appendix/apis.md, APIs] - [appendix/events_errors.md, Events and Errors]