mirror of
https://github.com/bluekitchen/btstack.git
synced 2025-03-30 16:20:24 +00:00
Merge branch 'master' of https://github.com/bluekitchen/btstack
This commit is contained in:
Matthias Ringwald
commit
be74c046e1
docs/manual/markdown/docs
@ -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.
|
||||
|
||||
<a name ="sec:memory_configuration"></a>
|
||||
<a name ="section:memory_configuration"></a>
|
||||
|
||||
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();
|
||||
|
||||
<a name"sec:run_loop"></a>
|
||||
<a name"section:run_loop"></a>
|
||||
|
||||
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.
|
||||
|
||||
<a nam="sec:btstack_initialization"></a>
|
||||
|
||||
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.
|
||||
|
||||
<a name="sec:services"></a>
|
||||
|
||||
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.
|
||||
|
||||
<a name="sec:packetHandlers"></a>
|
||||
|
||||
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.
|
||||
|
||||
<a name="sec:packetlogs"></a>
|
||||
|
||||
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.
|
||||
|
||||
@ -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
|
||||
-------------------------------------------------
|
||||
<a name="sec:singlethreading"></a>
|
||||
|
||||
## 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
|
||||
------------------------------------------------
|
||||
<a name="sec:multithreading"></a>
|
||||
|
||||
## 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
|
||||
|
||||
@ -1,19 +1,21 @@
|
||||
In this section, we highlight the BTstack components that need to be
|
||||
adjusted for different hardware platforms.
|
||||
|
||||
Time Abstraction Layer
|
||||
----------------------
|
||||
<a name="sec:timeAbstraction"></a>
|
||||
|
||||
## 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
|
||||
<a name="sec:tickAbstraction"></a>
|
||||
|
||||
### 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
|
||||
<a name="sec:timeMSAbstraction"></a>
|
||||
|
||||
### 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
|
||||
------------------------------
|
||||
<a name="sec:bt_hw_control"></a>
|
||||
|
||||
## 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
|
||||
----------------------------
|
||||
<a name="sec:hci_transport"></a>
|
||||
|
||||
## 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)
|
||||
<a name="sec:hciUART"></a>
|
||||
|
||||
### 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
|
||||
----------------------
|
||||
<a name="sec:persistent_storage"></a>
|
||||
|
||||
## 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
|
||||
|
||||
@ -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}
|
||||
--------------------------------------
|
||||
<a name="section:pan_profile"></a>
|
||||
|
||||
## 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}
|
||||
<a name = "section:GATTClient"></a>
|
||||
|
||||
### 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}
|
||||
<a name="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
|
||||
|
||||
@ -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]():
|
||||
|
||||
<a name "lst:hciOGFs"></a>
|
||||
<!-- -->
|
||||
@ -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.
|
||||
|
||||
<a name "lst:HCIcmdTemplate"></a>
|
||||
<!-- -->
|
||||
|
||||
@ -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 <a name="sec:windowsPath"></a>:
|
||||
|
||||
- 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}
|
||||
<a name="platform:msp430"></a>
|
||||
|
||||
### 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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user