manual: updated indentation

docs/manual/markdown/docs/architecture.md

@@ -27,8 +27,7 @@ for providing timers and processing incoming data.
 
 <a name="fig:BTstackArchitecture"></a>![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

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.
+
+<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;
     

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

docs/manual/markdown/docs/how_to.md

@@ -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

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.
 

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.
 

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,

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 <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

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, Examples]
-- [examples/generated.md, List of Examples]
+- [porting.md, Porting]
-- [porting.md, Porting to Other Platforms]
 - [integration.md, Integrating with Existing Systems]
 - [appendix/apis.md, APIs]
 - [appendix/events_errors.md, Events and Errors]
-- [revision_history.md, Revision History]
 theme: readthedocs

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,6 +312,7 @@ 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="])
@@ -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:])