diff --git a/docs/manual/markdown/docs/how_to.md b/docs/manual/markdown/docs/how_to.md index 4b888db98..916f66830 100644 --- a/docs/manual/markdown/docs/how_to.md +++ b/docs/manual/markdown/docs/how_to.md @@ -11,10 +11,9 @@ an overview is provided here. Finally, we describe the RFCOMM credit-based flow-control, which may be necessary for resource-constraint devices. - + -Memory configuration ------------------------------------------------------------- +## Memory configuration The structs for services, active connections and remote devices can be allocated in two different manners: @@ -53,10 +52,9 @@ The memory is set up by calling *btstack_memory_init* function: btstack_memory_init(); - + -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 @@ -112,12 +110,10 @@ communication over the UART. -BTstack initialization ----------------------- +## BTstack initialization -To initialize BTstack you need to initialize the memory and the run loop -as explained in Sections [section:memory~c~onfiguration] and -[section:run~l~oop] respectively, then setup HCI and all needed higher +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 level protocols. The HCI initialization has to adapt BTstack to the used platform and @@ -145,10 +141,11 @@ requires four arguments. These are: module can be connected via USB or an UART port. BTstack implements two UART based protocols: HCI UART Transport Layer (H4) and H4 with eHCILL support, a lightweight low-power variant by Texas - Instruments. These are accessed by linking the appropriate file ( - resp. and then getting a pointer to HCI Transport implementation. + Instruments. These are accessed by linking the appropriate file + [src/hci_transport_h4_dma.c]() resp. [src/hci_transport_h4_ehcill_dma.c]() + and then getting a pointer to HCI Transport implementation. For more information on adapting HCI Transport to different - environments, see Section [section:hci~t~ransport]. + environments, see [here](porting/#hci-transport-implementation). @@ -175,7 +172,7 @@ requires four arguments. These are: keys or remote device names. This commonly requires platform specific code to access the MCU’s EEPROM of Flash storage. For the first steps, BTstack provides a (non) persistent store in memory. - For more see [here](#sec:persistent_storage). + For more see [here](porting/#persistent-storage-api). @@ -194,8 +191,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 @@ -209,8 +205,8 @@ 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 now on everything is event driven. The application calls BTstack @@ -287,8 +283,8 @@ 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 between BTstack and the Bluetooth chipset often helps. diff --git a/docs/manual/markdown/docs/integration.md b/docs/manual/markdown/docs/integration.md index 64699fdb5..7d422b82f 100644 --- a/docs/manual/markdown/docs/integration.md +++ b/docs/manual/markdown/docs/integration.md @@ -10,10 +10,11 @@ contains the packet handler (PH) that handles all asynchronous events and data packets from BTstack. The Main Application makes use of the Communication Logic for its Bluetooth communication. -Adapting BTstack for Single-Threaded Environments -------------------------------------------------- +## Adapting BTstack for Single-Threaded Environments + + In a single-threaded environment, all application components run on the same (single) thread and use direct function calls as shown in Figure [below](#fig:BTstackSingle). @@ -39,10 +40,10 @@ Currently, we have two examples for this: managed in a linked list. Then, the*select* function is used to wait for the next file descriptor to become ready or timer to expire. -Adapting BTstack for Multi-Threaded Environments ------------------------------------------------- +## Adapting BTstack for Multi-Threaded Environments + The basic execution model of BTstack is a general while loop. Aside from interrupt-driven UART and timers, everything happens in sequence. When diff --git a/docs/manual/markdown/docs/porting.md b/docs/manual/markdown/docs/porting.md index 416f084a7..9540b63da 100644 --- a/docs/manual/markdown/docs/porting.md +++ b/docs/manual/markdown/docs/porting.md @@ -1,19 +1,21 @@ In this section, we highlight the BTstack components that need to be adjusted for different hardware platforms. -Time Abstraction Layer ----------------------- +## Time Abstraction Layer + BTstack requires a way to learn about passing time. *run_loop_embedded.c* supports two different modes: system ticks or a system clock with millisecond resolution. BTstack’s timing requirements are quite low as only Bluetooth timeouts in the second range need to be handled. -### Tick Hardware Abstraction +### Tick Hardware Abstraction + + If your platform doesn’t require a system clock or if you already have a system tick (as it is the default with CMSIS on ARM Cortex devices), you can use that to implement BTstack’s time abstraction in @@ -36,9 +38,11 @@ After BTstack calls *hal_tick_init()* and *tick_handler* gets called every *hal_tick_get_tick_period_in_ms()* ms. -### Time MS Hardware Abstraction +### Time MS Hardware Abstraction + + If your platform already has a system clock or it is more convenient to provide such a clock, you can use the Time MS Hardware Abstraction in *include/btstack/hal_time_ms.h*. @@ -54,10 +58,11 @@ future. It has to return the time in milliseconds. uint32_t hal_time_ms(void); -Bluetooth Hardware Control API ------------------------------- +## Bluetooth Hardware Control API + + The Bluetooth hardware control API can provide the HCI layer with a custom initialization script, a vendor-specific baud rate change command, and system power notifications. It is also used to control the @@ -72,19 +77,22 @@ that is not covered by the Bluetooth specification. As an example, the struct suitable for the CC256x chipset. -HCI Transport Implementation ----------------------------- +## HCI Transport Implementation + + On embedded systems, a Bluetooth module can be connected via USB or an UART port. BTstack implements two UART based protocols for carrying HCI commands, events and data between a host and a Bluetooth module: HCI UART Transport Layer (H4) and H4 with eHCILL support, a lightweight low-power variant by Texas Instruments. -### HCI UART Transport Layer (H4) +### HCI UART Transport Layer (H4) + + Most embedded UART interfaces operate on the byte level and generate a processor interrupt when a byte was received. In the interrupt handler, common UART drivers then place the received data in a ring buffer and @@ -135,10 +143,10 @@ callback for CTS interrupts. void hal_uart_dma_set_cts_irq_handler(void(*cts_irq_handler)(void)); void hal_uart_dma_set_sleep(uint8_t sleep); -Persistent Storage API ----------------------- +## Persistent Storage API + On embedded systems there is no generic way to persist data like link keys or remote device names, as every type of a device has its own capabilities, particularities and limitations. The persistent storage diff --git a/docs/manual/markdown/docs/profiles.md b/docs/manual/markdown/docs/profiles.md index d67442c35..782a191b6 100644 --- a/docs/manual/markdown/docs/profiles.md +++ b/docs/manual/markdown/docs/profiles.md @@ -1,8 +1,8 @@ In the following, we explain how the various Bluetooth profiles are used in BTstack. -GAP - Generic Access Profile: Classic -------------------------------------- +## GAP - Generic Access Profile: Classic + The GAP profile defines how devices find each other and establish a secure connection for other profiles. As mentioned before, the GAP @@ -162,8 +162,8 @@ purpose of bonding the device. After the bonding process is over, the connection will be automatically terminated. BTstack supports dedicated bonding via the *gap_dedicated_bonding* function. -SPP - Serial Port Profile -------------------------- +## SPP - Serial Port Profile + The SPP profile defines how to set up virtual serial ports and connect two Bluetooth enabled devices. @@ -188,8 +188,10 @@ and publish it with the SDP server by calling approximately 200 bytes, the service channel number, and a service name. Have a look at the SPP Counter example in Section [example:sppcounter]. -PAN - Personal Area Networking Profile {#section:pan_profile} --------------------------------------- + + +## PAN - Personal Area Networking Profile + The PAN profile uses BNEP to provide on-demand networking capabilities between Bluetooth devices. The PAN profile defines the following roles: @@ -237,8 +239,8 @@ calling *sdp_register_service_internal*. BTstack provides the empty buffer of approximately 200 bytes, a description, and a security description. -GAP LE - Generic Access Profile for Low Energy ----------------------------------------------- +## GAP LE - Generic Access Profile for Low Energy + As with GAP for Classic, the GAP LE profile defines how to discover and how to connect to a Bluetooth Low Energy device. There are several GAP @@ -301,8 +303,8 @@ into the Connected state. However, it does not start broadcasting advertisements on disconnect again. To re-enable it, please send the *hci_le_set_advertise_enable* again . -GATT - Generic Attribute Profile --------------------------------- +## GATT - Generic Attribute Profile + The GATT profile uses ATT Attributes to represent a hierarchical structure of GATT Services and GATT Characteristics. Each Service has @@ -313,7 +315,9 @@ Services are queried and modified via ATT operations. GATT defines both a server and a client role. A device can implement one or both GATT roles. -### GATT Client {#section:GATTClient} + + +### GATT Client The GATT Client is used to discover services, and their characteristics and descriptors on a peer device. It can also subscribe for @@ -340,10 +344,12 @@ perform a GATT query on a particular connection using *le_event*s are returned before a *GATT_QUERY_COMPLETE* event completes the query. -For more details on the available GATT queries, please consult Appendix -[appendix:api~g~att~c~lient]. +For more details on the available GATT queries, please consult +[GATT Client API](#appendix:api_gatt_client). -### GATT Server {#section:GATTServer} + + +### GATT Server The GATT server stores data and accepts GATT client requests, commands and confirmations. The GATT server sends responses to requests and when diff --git a/docs/manual/markdown/docs/protocols.md b/docs/manual/markdown/docs/protocols.md index ae8f621d3..862c2748b 100644 --- a/docs/manual/markdown/docs/protocols.md +++ b/docs/manual/markdown/docs/protocols.md @@ -67,7 +67,7 @@ fields, called the OpCode Group Field (OGF) and OpCode Command Field (OCF), see [Bluetooth Specification](https://www.bluetooth.org/Technical/Specifications/adopted.htm) - Core Version 4.0, Volume 2, Part E, Chapter 5.4. -Listing [below](#lst:hciOGFs) shows the OGFs provided by BTstack in file: +Listing [below](#lst:hciOGFs) shows the OGFs provided by BTstack in file [src/hci.h](): @@ -88,7 +88,8 @@ In a HCI command packet, the OpCode is followed by parameter total length, and the actual parameters. The OpCode of a command can be calculated using the OPCODE macro. BTstack provides the *hci_cmd_t* struct as a compact format to define HCI command packets, see -Listing [below](#lst:HCIcmdTemplate): +Listing [below](#lst:HCIcmdTemplate), and [include/btstack/hci_cmds.h]() +file in the source code. diff --git a/docs/manual/markdown/docs/quick_start.md b/docs/manual/markdown/docs/quick_start.md index 7590f0aef..8e936ffcc 100644 --- a/docs/manual/markdown/docs/quick_start.md +++ b/docs/manual/markdown/docs/quick_start.md @@ -1,5 +1,4 @@ -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. @@ -10,7 +9,7 @@ and optionally git : - [GNU Make](http://gnuwin32.sourceforge.net/packages/make.htm) for Windows: Add its bin folder to the Windows Path in Environment Variables. The bin folder is where make.exe resides, and it’s - usually located in . + usually located in [C:\Program Files\GnuWin32\bin](). - [Python](http://www.python.org/getit/) for Windows: Add Python installation folder to the Windows Path in @@ -18,20 +17,18 @@ and optionally git : Adding paths to the Windows Path variable : -- Go to: Control Panel->System->Advanced - tab->Environment Variables. +- Go to: Control Panel->System->Advanced tab->Environment Variables. - The top part contains a list of User variables. - Click on the Path variable and then click edit. -- Go to the end of the line, then append the path to the list., for - example, for GNU Make. +- Go to the end of the line, then append the path to the list, for + example, [C:\Program Files\GnuWin32\bin]() for GNU Make. -- Ensure that there is a semicolon before and after . +- 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: @@ -42,31 +39,27 @@ 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 tool. For TI’s CC256x chipsets, you also need the correct init script, or “Service Pack” in TI nomenclature. Assuming that these are provided, -go to folder in command prompt and run make. If all the paths are -correct, it will generate several firmware files. These firmware files +go to folder [btstack/platforms/$PLATFORM$]() in command prompt and run make. +If all the paths are correct, it will generate several firmware files. These firmware files 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 (see Section -[example:sppcounter]). During the startup, for TI chipsets, the init +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, 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. @@ -74,7 +67,7 @@ setups, toolchains, programmers, and init scripts. ### libusb The quickest way to try BTstack is on a Linux or OS X system with an -additional USB Bluetooth module. The Makefile in requires +additional USB Bluetooth module. The Makefile [platforms/libusb]() in requires [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/) and [libusb-1.0](www.libusb.org) or higher to be installed. @@ -92,7 +85,7 @@ It’s also possible to run the examples on Win32 systems. For this: - Install [MSYS](www.mingw.org/wiki/msys) and [MINGW32](www.mingw.org) using the MINGW installer -- Compile and install libusb-1.0.19 to /usr/local/ in msys command +- Compile and install libusb-1.0.19 to [/usr/local/]() in msys command shell - Setup a USB Bluetooth dongle for use with libusb-1.0: @@ -118,8 +111,8 @@ and installation instructions are provided on the [MSPGCC Wiki](http://sourceforge.net/apps/mediawiki/mspgcc/index.php?title=MSPGCC_Wiki). On Windows, you need to download and extract [mspgcc](http://sourceforge.net/projects/mspgcc/files/Windows/mingw32/) -to ??. Add folder to the Windows Path in Environment variable as explained -[here](#sec:windowsPath). +to [C:\mspgcc](). Add [C:\mspgcc\bin]() folder to the Windows Path in Environment +variable as explained [here](#sec:windowsPath). **Loading Firmware.** To load firmware files onto the MSP430 MCU for the MSP-EXP430F5438 Experimeneter board, you need a programmer like the @@ -127,10 +120,10 @@ MSP430 MSP-FET430UIF debugger or something similar. The eZ430-RF2560 and MSP430F5529LP contain a basic debugger. Now, you can use one of following software tools: -- [MSP430Flasher](http://processors.wiki.ti.com/index.php/MSP430_Flasher_-_Command_Line_Programmer) +- [MSP430Flasher](http://processors.wiki.ti.com/index.php/MSP430_Flasher_Command_Line_Programmer) (windows-only): - - Use the following command, where you need to replace the with + - Use the following command, where you need to replace the [BINARY_FILE_NAME.hex]() with the name of your application: @@ -161,7 +154,7 @@ obtained separately as follows: - Copy the included .bts file into -- In ??, run the Python script: +- In [chipset-cc256x](), run the Python script: @@ -181,7 +174,9 @@ the BLE part. The conversion script has been updated to detect *bluetooth_init_cc256x_1.2.bts* and adds *BLE_init_cc256x_1.2.bts* if present and merges them into a single .c file. -### MSP-EXP430F5438 + CC256x Platform {#platform:msp430} + + +### 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 @@ -191,7 +186,7 @@ Guide](http://processors.wiki.ti.com/index.php/PAN1315EMK_User_Guide#RF3_Connect ### STM32F103RB Nucleo + CC256x Platform To try BTstack on this platform, you’ll need a simple adaptor board. For -details, please read the documentation in ??. +details, please read the documentation in [platforms/stm32-f103rb-nucleo/README.md](). ### PIC32 Bluetooth Audio Development Kit @@ -200,7 +195,7 @@ 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. -In ??, a project file for the MPLAB X IDE is provided as well as a regular +In [platforms/pic32-harmony](), a project file for the MPLAB X IDE is provided as well as a regular Makefile. Both assume that the MPLAB XC32 compiler is installed. 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. For