From 9d873a98ea9d8e502e39435b3bb7844c8cd60f79 Mon Sep 17 00:00:00 2001 From: Milanka Ringwald Date: Wed, 20 May 2015 22:03:17 +0200 Subject: [PATCH] manual: updated indentation --- docs/manual/markdown/docs/architecture.md | 12 +-- .../markdown/docs/examples/generated.md | 75 ++++++++++++++++--- docs/manual/markdown/docs/examples/intro.md | 2 + docs/manual/markdown/docs/how_to.md | 12 +-- docs/manual/markdown/docs/porting.md | 2 + docs/manual/markdown/docs/profiles.md | 3 + docs/manual/markdown/docs/protocols.md | 3 + docs/manual/markdown/docs/quick_start.md | 22 +++--- docs/manual/markdown/mkdocs.yml | 6 +- docs/manual/markdown/update_listings.py | 13 +++- 10 files changed, 109 insertions(+), 41 deletions(-) diff --git a/docs/manual/markdown/docs/architecture.md b/docs/manual/markdown/docs/architecture.md index 903763c14..05aa71d60 100644 --- a/docs/manual/markdown/docs/architecture.md +++ b/docs/manual/markdown/docs/architecture.md @@ -27,8 +27,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 @@ -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 diff --git a/docs/manual/markdown/docs/examples/generated.md b/docs/manual/markdown/docs/examples/generated.md index c0e8075ba..440a70bd2 100644 --- a/docs/manual/markdown/docs/examples/generated.md +++ b/docs/manual/markdown/docs/examples/generated.md @@ -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. + + + + 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 @@ - 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 @@ - 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; diff --git a/docs/manual/markdown/docs/examples/intro.md b/docs/manual/markdown/docs/examples/intro.md index 6d6599f5e..33cd563b5 100644 --- a/docs/manual/markdown/docs/examples/intro.md +++ b/docs/manual/markdown/docs/examples/intro.md @@ -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 diff --git a/docs/manual/markdown/docs/how_to.md b/docs/manual/markdown/docs/how_to.md index 8542490a7..227d5f6b1 100644 --- a/docs/manual/markdown/docs/how_to.md +++ b/docs/manual/markdown/docs/how_to.md @@ -13,7 +13,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 +54,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 +110,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 +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 @@ -205,7 +205,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 +283,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/porting.md b/docs/manual/markdown/docs/porting.md index 9540b63da..c5de43d9c 100644 --- a/docs/manual/markdown/docs/porting.md +++ b/docs/manual/markdown/docs/porting.md @@ -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. diff --git a/docs/manual/markdown/docs/profiles.md b/docs/manual/markdown/docs/profiles.md index 782a191b6..08ff0227d 100644 --- a/docs/manual/markdown/docs/profiles.md +++ b/docs/manual/markdown/docs/profiles.md @@ -1,3 +1,6 @@ + +# 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 862c2748b..3761d1534 100644 --- a/docs/manual/markdown/docs/protocols.md +++ b/docs/manual/markdown/docs/protocols.md @@ -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, diff --git a/docs/manual/markdown/docs/quick_start.md b/docs/manual/markdown/docs/quick_start.md index 8e936ffcc..f446a2bfc 100644 --- a/docs/manual/markdown/docs/quick_start.md +++ b/docs/manual/markdown/docs/quick_start.md @@ -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 : - 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. -### 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/mkdocs.yml b/docs/manual/markdown/mkdocs.yml index 4c82f54d2..959bc4fe1 100644 --- a/docs/manual/markdown/mkdocs.yml +++ b/docs/manual/markdown/mkdocs.yml @@ -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 \ No newline at end of file diff --git a/docs/manual/markdown/update_listings.py b/docs/manual/markdown/update_listings.py index ab98f45c5..0b16a7d4f 100755 --- a/docs/manual/markdown/update_listings.py +++ b/docs/manual/markdown/update_listings.py @@ -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:])