From 9d6ba381e711c693f2bff44214e38fb30f54aab2 Mon Sep 17 00:00:00 2001 From: Matthias Ringwald Date: Thu, 2 Feb 2017 15:55:38 +0100 Subject: [PATCH] doc: add info on Windows run loop --- doc/manual/docs/how_to.md | 14 +++++++++++--- doc/manual/docs/integration.md | 14 +++++++++----- doc/manual/docs/quick_start.md | 11 +++++------ 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/doc/manual/docs/how_to.md b/doc/manual/docs/how_to.md index 2439ddeaa..b4c5e7c2e 100644 --- a/doc/manual/docs/how_to.md +++ b/doc/manual/docs/how_to.md @@ -73,6 +73,8 @@ ENABLE_LOG_DEBUG | Enable log_debug messages ENABLE_LOG_ERROR | Enable log_error messages ENABLE_LOG_INFO | Enable log_info messages ENABLE_SCO_OVER_HCI | Enable SCO over HCI for chipsets (only CC256x/WL18xx and USB CSR controllers) +ENBALE_LE_PERIPHERAL | Enable support for LE Peripheral Role in HCI and Security Manager +ENBALE_LE_CENTRAL | Enable support for LE Central Role in HCI and Security Manager ENABLE_LE_SECURE_CONNECTIONS | Enable LE Secure Connections using [mbed TLS library](https://tls.mbed.org) ENABLE_LE_DATA_CHANNELS | Enable LE Data Channels in credit-based flow control mode ENABLE_LE_SIGNED_WRITE | Enable LE Signed Writes in ATT/GATT @@ -193,10 +195,11 @@ BTstack provides different run loop implementations that implement the *btstack_ - Embedded: the main implementation for embedded systems, especially without an RTOS. - POSIX: implementation for POSIX systems based on the select() call. - CoreFoundation: implementation for iOS and OS X applications -- WICED: implementation for the Broadcom WICED SDK RTOS abstraction that warps FreeRTOS or ThreadX. +- WICED: implementation for the Broadcom WICED SDK RTOS abstraction that wraps FreeRTOS or ThreadX. +- Windows: implementation for Windows based on Event objects and WaitForMultipleObjects() call. Depending on the platform, data sources are either polled (embedded), or the platform provides a way -to wait for a data source to become ready for read or write (POSIX, CoreFoundation), or, +to wait for a data source to become ready for read or write (POSIX, CoreFoundation, Windows), or, are not used as the HCI transport driver and the run loop is implemented in a different way (WICED). In any case, the callbacks must be to explicitly enabled with the *btstack_run_loop_enable_data_source_callbacks(..)* function. @@ -254,8 +257,13 @@ It supports ready to read and write similar to the POSIX implementation. The cal To enable the use of timers, make sure that you defined HAVE_POSIX_TIME in the config file. -### Run loop WICED +### Run loop Windows +The data sources are Event objects. In the run loop implementation WaitForMultipleObjects() call +is all is used to wait for the Event object to become ready while waiting for the next timeout. + + +### Run loop WICED WICED SDK API does not provide asynchronous read and write to the UART and no direct way to wait for one or more peripherals to become ready. Therefore, BTstack does not provide direct support for data sources. diff --git a/doc/manual/docs/integration.md b/doc/manual/docs/integration.md index 019d377cb..71c44f939 100644 --- a/doc/manual/docs/integration.md +++ b/doc/manual/docs/integration.md @@ -30,16 +30,20 @@ system. Currently, we have two examples for this: +- *btstack_run_loop_posix.c* is an implementation for POSIX compliant + systems. The data sources are modeled as file descriptors and + 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. + - *btstack_run_loop_cocoa.c* is an implementation for the CoreFoundation Framework used in OS X and iOS. All run loop functions are implemented in terms of CoreFoundation calls, data sources and timers are modeled as CFSockets and CFRunLoopTimer respectively. -- *btstack_run_loop_posix.c* is an implementation for POSIX compliant - systems. The data sources are modeled as file descriptors and - 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. - +- *btstack_run_loop_windows* is an implementation for Windows environment. + The data sources are modeled with Event objects and managed in a linked list. + Then, the *WaitForMultipleObjects* is used to wait for the next Event to + becomre ready or timer to expire. ## Adapting BTstack for Multi-Threaded Environments {#sec:multithreadingIntegration} diff --git a/doc/manual/docs/quick_start.md b/doc/manual/docs/quick_start.md index b73d1fb95..52125b2df 100644 --- a/doc/manual/docs/quick_start.md +++ b/doc/manual/docs/quick_start.md @@ -10,9 +10,9 @@ On Windows, there is no packet manager, but it's easy to download and install al - [Python](http://www.python.org/getit/) for Windows. When using the official installer, please confirm adding Python to the Windows Path. - [MSYS2](https://msys2.github.io) is used to provide the bash shell and most standard POSIX command line tools. -- [MinGW64](https://mingw-w64.org/doku.php) GCC for Windows 64 & 32 bits incl. make. To install with MYS2: pacman -S mingw-w64-x86_64-gcc -- [git](https://git-scm.com) is used to download BTstack source code. To install with MYS2: pacman -S git -- [winpty](https://github.com/rprichard/winpty) a wrapper to allow for console input when running in msys2: To install with MYS2: pacman -S winpty +- [MinGW64](https://mingw-w64.org/doku.php) GCC for Windows 64 & 32 bits incl. make. To install with MSYS2: pacman -S mingw-w64-x86_64-gcc +- [git](https://git-scm.com) is used to download BTstack source code. To install with MSYS2: pacman -S git +- [winpty](https://github.com/rprichard/winpty) a wrapper to allow for console input when running in MSYS2: To install with MSYS2: pacman -S winpty ## Getting BTstack from GitHub @@ -68,7 +68,7 @@ Bluetooth. For this, execute: ## Windows-WinUSB -While libusb basically also works on Windows, we recommend to use the Windows-WinUSB port that uses a native run loop and the native WinUSB API to access the USB Bluetooth dongle. +Although libusb basically works with the POSIX Run Loop on Windows, we recommend to use the Windows-WinUSB port that uses a native run loop and the native WinUSB API to access a USB Bluetooth dongle. For libusb or WinUSB, you need to install a special device driver to make the USB dongle accessible to user space. It works like this: @@ -78,8 +78,7 @@ For libusb or WinUSB, you need to install a special device driver to make the US - Select WinUSB (libusb) in the right pull pull down list - Select “Replace Driver” -When running the examples in the MSYS2, the console input (via btstack_stdin_support) doesn't work. It works in the older MSYS and also the regular -CMD.exe environment. Another option is to install WinPTY and then start the example via WinPTY like this: +When running the examples in the MSYS2 shell, the console input (via btstack_stdin_support) doesn't work. It works in the older MSYS and also the regular CMD.exe environment. Another option is to install WinPTY and then start the example via WinPTY like this: $ winpty ./hfp_hf_demo.exe