mirror of
https://github.com/bluekitchen/btstack.git
synced 2025-01-26 12:35:25 +00:00
Merge branch 'master' of https://github.com/bluekitchen/btstack
This commit is contained in:
Matthias Ringwald
commit
679e905b75
@ -27,8 +27,7 @@ for providing timers and processing incoming data.
|
||||
|
||||
<a name="fig:BTstackArchitecture"></a>
|
||||
|
||||
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
|
||||
@ -42,8 +41,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,8 +55,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
|
||||
@ -72,8 +69,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
|
||||
|
||||
@ -1,4 +1,61 @@
|
||||
# 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
|
||||
the hardware configuration has been extracted to the various
|
||||
*platforms/PLATFORM/main.c* files. The examples only contain the
|
||||
platform-independent Bluetooth logic. But let’s have a look at the
|
||||
common init code.
|
||||
|
||||
Listing [below](#lst:btstackInit) shows a minimal platform setup for an
|
||||
embedded system with a Bluetooth chipset connected via UART.
|
||||
|
||||
<a name="lst:btstackInit"></a>
|
||||
|
||||
int main(){
|
||||
// ... hardware init: watchdoch, IOs, timers, etc...
|
||||
|
||||
// setup BTstack memory pools
|
||||
btstack_memory_init();
|
||||
|
||||
// select embedded run loop
|
||||
run_loop_init(RUN_LOOP_EMBEDDED);
|
||||
|
||||
// use logger: format HCI_DUMP_PACKETLOGGER, HCI_DUMP_BLUEZ or HCI_DUMP_STDOUT
|
||||
hci_dump_open(NULL, HCI_DUMP_STDOUT);
|
||||
|
||||
// init HCI
|
||||
hci_transport_t * transport = hci_transport_h4_dma_instance();
|
||||
remote_device_db_t * remote_db = (remote_device_db_t *) &remote_device_db_memory;
|
||||
hci_init(transport, NULL, NULL, remote_db);
|
||||
|
||||
// setup example
|
||||
btstack_main(argc, argv);
|
||||
|
||||
// go
|
||||
run_loop_execute();
|
||||
}
|
||||
|
||||
First, BTstack’s memory pools are setup up. Then, the standard run loop
|
||||
implementation for embedded systems is selected.
|
||||
|
||||
The call to *hci_dump_open* configures BTstack to output all Bluetooth
|
||||
packets and it’s own debug and error message via printf. The Python
|
||||
script *tools/create_packet_log.py* can be used to convert the console
|
||||
output into a Bluetooth PacketLogger format that can be opened by the OS
|
||||
X PacketLogger tool as well as by Wireshark for further inspection. When
|
||||
asking for help, please always include a log created with HCI dump.
|
||||
|
||||
The *hci_init* function sets up HCI to use the HCI H4 Transport
|
||||
implementation. It doesn’t provide a special transport configuration nor
|
||||
a special implementation for a particular Bluetooth chipset. It makes
|
||||
use of the *remote_device_db_memory* implementation that allows for
|
||||
re-connects without a new pairing but doesn’t persist the bonding
|
||||
information.
|
||||
|
||||
Finally, it calls *btstack_main()* of the actual example before
|
||||
executing the run loop.
|
||||
|
||||
|
||||
- Hello World example:
|
||||
@ -166,7 +223,7 @@
|
||||
static void packet_handler (void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
|
||||
static void handle_sdp_client_query_result(sdp_query_event_t * event);
|
||||
|
||||
static void sdp_client_init(){
|
||||
static void sdp_client_init(void){
|
||||
// init L2CAP
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(packet_handler);
|
||||
@ -284,7 +341,7 @@
|
||||
static void packet_handler (void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
|
||||
static void handle_sdp_client_query_result(sdp_query_event_t * event);
|
||||
|
||||
static void sdp_client_init(){
|
||||
static void sdp_client_init(void){
|
||||
// init L2CAP
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(packet_handler);
|
||||
@ -412,7 +469,7 @@
|
||||
<a name="sppcounter:SPPSetup"></a>
|
||||
<!-- -->
|
||||
|
||||
void spp_service_setup(){
|
||||
void spp_service_setup(void){
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(packet_handler);
|
||||
|
||||
@ -463,7 +520,7 @@
|
||||
run_loop_add_timer(ts);
|
||||
}
|
||||
|
||||
static void one_shot_timer_setup(){
|
||||
static void one_shot_timer_setup(void){
|
||||
// set one-shot timer
|
||||
heartbeat.process = &heartbeat_handler;
|
||||
run_loop_set_timer(&heartbeat, HEARTBEAT_PERIOD_MS);
|
||||
@ -554,7 +611,7 @@
|
||||
<a name="sppflowcontrol:explicitFlowControl"></a>
|
||||
<!-- -->
|
||||
|
||||
static void spp_service_setup(){
|
||||
static void spp_service_setup(void){
|
||||
// init L2CAP
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(packet_handler);
|
||||
@ -637,7 +694,7 @@
|
||||
static void packet_handler (void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
|
||||
static void handle_sdp_client_query_result(sdp_query_event_t *event);
|
||||
|
||||
static void panu_setup(){
|
||||
static void panu_setup(void){
|
||||
// Initialize L2CAP
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(packet_handler);
|
||||
@ -844,7 +901,7 @@
|
||||
// GAP disconnect command when the querying is done.
|
||||
void handle_gatt_client_event(le_event_t * event);
|
||||
|
||||
static void gatt_client_setup(){
|
||||
static void gatt_client_setup(void){
|
||||
// Initialize L2CAP and register HCI event handler
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(&handle_hci_event);
|
||||
@ -993,7 +1050,7 @@
|
||||
static int att_write_callback(uint16_t con_handle, uint16_t att_handle, uint16_t transaction_mode, uint16_t offset, uint8_t *buffer, uint16_t buffer_size);
|
||||
static void heartbeat_handler(struct timer *ts);
|
||||
|
||||
static void le_counter_setup(){
|
||||
static void le_counter_setup(void){
|
||||
l2cap_init();
|
||||
l2cap_register_packet_handler(packet_handler);
|
||||
|
||||
@ -1041,7 +1098,7 @@
|
||||
};
|
||||
static uint16_t todos = 0;
|
||||
|
||||
static void gap_run(){
|
||||
static void gap_run(void){
|
||||
|
||||
if (!hci_can_send_command_packet_now()) return;
|
||||
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
# 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
|
||||
|
||||
@ -13,7 +13,7 @@ resource-constraint devices.
|
||||
|
||||
<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:
|
||||
@ -54,7 +54,7 @@ The memory is set up by calling *btstack_memory_init* function:
|
||||
|
||||
<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
|
||||
@ -110,7 +110,7 @@ communication over the UART.
|
||||
|
||||
<a nam="sec:btstack_initialization"></a>
|
||||
|
||||
## 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 +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
|
||||
@ -205,7 +205,7 @@ 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
|
||||
@ -283,7 +283,7 @@ 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
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
# Porting to Other Platforms
|
||||
|
||||
In this section, we highlight the BTstack components that need to be
|
||||
adjusted for different hardware platforms.
|
||||
|
||||
|
||||
@ -1,3 +1,6 @@
|
||||
|
||||
# Supported Profiles
|
||||
|
||||
In the following, we explain how the various Bluetooth profiles are used
|
||||
in BTstack.
|
||||
|
||||
|
||||
@ -1,3 +1,6 @@
|
||||
|
||||
# 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,
|
||||
|
||||
@ -1,4 +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.
|
||||
@ -28,7 +28,7 @@ Adding paths to the Windows Path variable <a name="sec:windowsPath"></a>:
|
||||
|
||||
- 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 +39,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 +51,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 +59,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 +103,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 +142,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 +176,19 @@ if present and merges them into a single .c file.
|
||||
|
||||
<a name="platform:msp430"></a>
|
||||
|
||||
### 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
|
||||
|
||||
@ -7,11 +7,9 @@ pages:
|
||||
- [how_to.md, How to use BTstack]
|
||||
- [protocols.md, Protocols]
|
||||
- [profiles.md, Profiles]
|
||||
- [examples/intro.md, Examples]
|
||||
- [examples/generated.md, List of Examples]
|
||||
- [porting.md, Porting to Other Platforms]
|
||||
- [examples/generated.md, Examples]
|
||||
- [porting.md, Porting]
|
||||
- [integration.md, Integrating with Existing Systems]
|
||||
- [appendix/apis.md, APIs]
|
||||
- [appendix/events_errors.md, Events and Errors]
|
||||
- [revision_history.md, Revision History]
|
||||
theme: readthedocs
|
||||
@ -262,8 +262,13 @@ def writeListings(aout, infile_name, ref_prefix):
|
||||
|
||||
|
||||
# write list of examples
|
||||
def processExamples(examples_folder, examples_ofile):
|
||||
def processExamples(intro_file, examples_folder, examples_ofile):
|
||||
with open(examples_ofile, 'w') as aout:
|
||||
|
||||
with open(intro_file, 'rb') as fin:
|
||||
for line in fin:
|
||||
aout.write(line)
|
||||
|
||||
for group_title in list_of_groups:
|
||||
if not list_of_examples.has_key(group_title): continue
|
||||
examples = list_of_examples[group_title]
|
||||
@ -307,7 +312,8 @@ def main(argv):
|
||||
docs_folder = "docs/examples/"
|
||||
inputfolder = btstack_folder + "example/embedded/"
|
||||
outputfile = docs_folder + "generated.md"
|
||||
|
||||
intro_file = "docs/examples/intro.md"
|
||||
|
||||
try:
|
||||
opts, args = getopt.getopt(argv,"hiso:",["ifolder=","ofile="])
|
||||
except getopt.GetoptError:
|
||||
@ -323,7 +329,8 @@ def main(argv):
|
||||
outputfile = arg
|
||||
print 'Input folder is ', inputfolder
|
||||
print 'Output file is ', outputfile
|
||||
processExamples(inputfolder, outputfile)
|
||||
|
||||
processExamples(intro_file, inputfolder, outputfile)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main(sys.argv[1:])
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user