mirror/btstack
1
0
Fork 0
mirror of https://github.com/bluekitchen/btstack.git synced 2025-03-26 20:37:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

manual: update references, correct typos

Browse Source
This commit is contained in:
Milanka Ringwald 2015-04-24 23:09:32 +02:00
parent 7990b4cde2
commit 32d4eaa519
2 changed files with 21 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/manual/btstack_gettingstarted.tex
View File

@ -200,7 +200,7 @@ pic32-harmony & CSR8811 & \mplabxc{} & \PICkit{} \\ \hiderowcolors
\subsection{Run the Example}
As a first test, we recommend the SPP Counter example (see Section \ref{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.
As a first test, we recommend the SPP Counter example (see Section \ref{example:spp_counter}). 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.
% The SPP Counter doesn't use the display to keep the memory footprint small.
% The HID demo has a fancier user interface - it uses a display to show the discovery process and connection establishment with a Bluetooth keyboard, as well as the text as you type.
@ -260,7 +260,7 @@ BTstack has to keep track of services and active connections on the various prot
\section{How to use BTstack}
BTstack implements a set of basic Bluetooth protocols. To make use of these to connect to other devices or to provide own services, BTstack has to be properly configured during application startup.
In the following, we provide an overview of the memory management, the run loop, and services that are necessary to setup BTstack. From the point when the run loop is executed, the application runs as a finite state machine, which processes events received from BTstack. BTstack groups events logically and provides them over packet handlers, of which an overview is provided here. Finally, we describe the RFCOMM credit-based flow-control, which may be necessary for resource-constraint devices. Complete examples for the MSP430 platforms will be presented in Chapter \ref{examples}.
In the following, we provide an overview of the memory management, the run loop, and services that are necessary to setup BTstack. From the point when the run loop is executed, the application runs as a finite state machine, which processes events received from BTstack. BTstack groups events logically and provides them over packet handlers, of which an overview is provided here. Finally, we describe the RFCOMM credit-based flow-control, which may be necessary for resource-constraint devices. Complete examples for the MSP430 platforms will be presented in Chapter \ref{section:examples}.
\subsection{Memory configuration}
\label{section:memory_configuration}
@ -294,7 +294,7 @@ Timers are single shot: a timer will be removed from the timer list before its e
The Run loop API is provided in Appendix \ref{appendix:api_run_loop}. To enable the use of timers, make sure that you defined HAVE\_TICK in the config file.
In your code, you'll have to configure the run loop before you start it as shown in Listing \ref{RunLoopExecution}. The application can register data sources as well as timers, e.g., periodical sampling of sensors, or communication over the UART.
In your code, you'll have to configure the run loop before you start it as shown in Listing \ref{listing:btstackInit}. The application can register data sources as well as timers, e.g., periodical sampling of sensors, or communication over the UART.
The run loop is set up by calling \emph{run\_loop\_init} function for embedded systems:
\begin{lstlisting}
@ -437,12 +437,14 @@ Separate packet handlers can be used for each L2CAP service and outgoing connect
\pagebreak
\section{Examples}
\label{section:examples}
In this section, we will describe a number of examples from the \emph{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 \emph{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 \ref{lst:btstackInit} shows a minimal platform setup for an embedded system with a Bluetooth chipset connected via UART.
Listing \ref{listing:btstackInit} shows a minimal platform setup for an embedded system with a Bluetooth chipset connected via UART.
\begin{lstlisting}[float, caption=Exemplary platform init in main.c, label=lst:btstackInit]
int main(){}
\begin{lstlisting}[float, caption=Exemplary platform init in main.c, label=listing:btstackInit]
int main(){
// ... hardware init: watchdoch, IOs, timers, etc...
// setup BTstack memory pools
@ -464,15 +466,16 @@ int main(){}
// go
run_loop_execute();
}
\end{lstlisting}
First, BTstack's memory pools are setup up. Then, the standard run loop implementation for embedded systems is selected.
The call to \emph{hci\_dump\_open} configures BTstack to output all Bluetooth packets and it's own debug and error message via printf. The Python script \emph{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 of the problem.
The call to \emph{hci\_dump\_open} configures BTstack to output all Bluetooth packets and it's own debug and error message via printf. The Python script \emph{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 \emph{hci\_init} call setups HCI to use the HCI H4 Transport implementation. It doesn't provide a special transprot configuration nor a special implementation for a particular Bluetooth chipset. It makes use of the \emph{remote\_device\_db\_memory} implementation that allows for re-connects without a new pairing but doesn't persist the bonding information.
The \emph{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 \emph{remote\_device\_db\_memory} implementation that allows for re-connects without a new pairing but doesn't persist the bonding information.
Finally, it calls \emph{btstack\_main()} of the acutal example before executing the run lopp.
Finally, it calls \emph{btstack\_main()} of the actual example before executing the run loop.
The examples are grouped like this:
\input{examples}
@ -488,7 +491,7 @@ In this chapter, we highlight the BTstack components that need to be adjusted fo
BTstack requires a way to learn about passing time. \emph{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.
\subsubsection{Tick Hardware Abstraction}
\label{ssection:tickAbstraction}
\label{section:tickAbstraction}
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 \emph{include/btstack/hal\_tick.h>}.
@ -508,7 +511,7 @@ int hal_tick_get_tick_period_in_ms(void);
After BTstack calls \emph{hal\_tick\_init()} and \emph{hal\_tick\_set\_handler(tick\_handler)}, it expects that the \emph{tick\_handler} gets called every \emph{hal\_tick\_get\_tick\_period\_in\_ms()} ms.
\subsubsection{Time MS Hardware Abstraction}
\label{ssection:timeMSAbstraction}
\label{section:timeMSAbstraction}
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 \emph{include/btstack/hal\_time\_ms.h}.
For this, you need to define \emph{HAVE\_TIME\_MS} in \emph{btstack-config.h}:

14
docs/manual/protocols_profiles.tex
View File

@ -327,7 +327,7 @@ These two events represent two orthogonal mechanisms that deal with flow control
If the management of credits is manual, credits are provided by the application such that it can manage its receive buffers explicitly, see Listing \ref{explicitFlowControl}.
Manual credit management is recommended when received RFCOMM data cannot be processed immediately. In the SPP flow control example in Section \ref{example:spp_flow_control}, delayed processing of received data is simulated with the help of a periodic timer. To provide new credits, you call the \emph{rfcomm\_grant\_credits} function with the RFCOMM channel ID and the number of credits as shown in Listing \ref{NewCredits}.
Manual credit management is recommended when received RFCOMM data cannot be processed immediately. In the SPP flow control example in Section \ref{example:spp_flowcontrol}, delayed processing of received data is simulated with the help of a periodic timer. To provide new credits, you call the \emph{rfcomm\_grant\_credits} function with the RFCOMM channel ID and the number of credits as shown in Listing \ref{NewCredits}.
Please note that providing single credits effectively reduces the credit-based (sliding window) flow control to a stop-and-wait flow-control that limits the data throughput substantially. On the plus side, it allows for a minimal memory footprint. If possible, multiple RFCOMM buffers should be used to avoid pauses while the sender has to wait for a new credit.
@ -573,7 +573,7 @@ The Generic Attribute (GATT) profile is built upon ATT and provides higher level
\subsection{SMP - Security Manager Protocol }
\label{subsection:smp}
\label{section:smp}
The SMP protocol allows to setup authenticated and encrypted LE connection. After initialization and configuration, SMP handles security related functions on it's own but emits events when feedback from the main app or the user is required. The two main tasks of the SMP protocol are: bonding and identity resolving.
@ -682,7 +682,7 @@ To scan for remote devices, the \emph{hci\_inquiry} command is used. Found remot
By default, neither RSSI values nor EIR are reported. If the Bluetooth device implements Bluetooth Specification 2.1 or higher, the \emph{hci\_write\_inquiry\_mode} command enables reporting of this advanced features (0 for standard results, 1 for RSSI, 2 for RSSI and EIR).
A complete GAP inquiry example is provided in Section \ref{example:GapInquiry}.
A complete GAP inquiry example is provided in Section \ref{example:gap_inquiry}.
\begin{lstlisting}[float, caption=Discovering remote Bluetooth devices., label=DiscoverDevices]
void print_inquiry_results(uint8_t *packet){
@ -769,7 +769,7 @@ The SPP profile defines how to set up virtual serial ports and connect two Bluet
To access a remote SPP server, you first need to query the remote device for its SPP services. Section \ref{subsection:querysdp} shows how to query for all RFCOMM channels. For SPP, you can do the same but use the SPP UUID 0x1101 for the query. After you have identified the correct RFCOMM channel, you can create an RFCOMM connection as shown in Section \ref{subsubsection:rfcommlient}
\subsubsection{Providing an SPP Server}
To provide an SPP Server, you need to provide an RFCOMM service with a specific RFCOMM channel number as explained in Section \ref{section:rfcomm_service}. Then, you need to create an SDP record for it and publish it with the SDP server by calling \emph{sdp\_register\_service\_internal}. BTstack provides the \emph{sdp\_create\_spp\_service} function in \path{src/sdp_utils.c} that requires an empty buffer of approximately 200 bytes, the service channel number, and a service name. Have a look at the SPP Counter example in Section \ref{section:sppcounter}.
To provide an SPP Server, you need to provide an RFCOMM service with a specific RFCOMM channel number as explained in Section \ref{section:rfcomm_service}. Then, you need to create an SDP record for it and publish it with the SDP server by calling \emph{sdp\_register\_service\_internal}. BTstack provides the \emph{sdp\_create\_spp\_service} function in \path{src/sdp_utils.c} that requires an empty buffer of approximately 200 bytes, the service channel number, and a service name. Have a look at the SPP Counter example in Section \ref{example:spp_counter}.
\subsection{PAN - Personal Area Networking Profile}
\label{section:pan_profile}
@ -790,7 +790,7 @@ Currently, BTstack supports only PANU.
\subsubsection{Accessing a remote PANU service}
To access a remote PANU service, you first need perform an SDP query to get the L2CAP PSM for the requested PANU UUID.
With these two pieces of information, you can connect BNEP to the remote PANU service with the \emph{bnep\_connect} function. The PANU Demo example in Section \ref{subsection:panudemo} shows how this is accomplished.
With these two pieces of information, you can connect BNEP to the remote PANU service with the \emph{bnep\_connect} function. The PANU Demo example in Section \ref{example:panu_demo} shows how this is accomplished.
\subsubsection{Providing a PANU service}
To provide a PANU service, you need to provide a BNEP service with the service UUID, e.g. the PANU UUID, and a a maximal ethernet frame size, as explained in Section \ref{subsubsection:bnepserver}. Then, you need to create an SDP record for it and publish it with the SDP server by calling \emph{sdp\_register\_service\_internal}. BTstack provides the \emph{pan\_create\_panu\_service} function in \emph{src/pan.c} that requires an empty buffer of approximately 200 bytes, a description, and a security description.
@ -805,7 +805,7 @@ To better protect privacy, an LE device can choose to use a private i.e. random
To toggle privacy mode using private addresses, call the \emph{gap\_random\_address\_set\_mode} function. The update period can be set with \emph{gap\_random\_address\_set\_update\_period}.
After a connection is established, the Security Manager will try to resolve the peer Bluetooth address as explained in Section \ref{subsection:smp}.
After a connection is established, the Security Manager will try to resolve the peer Bluetooth address as explained in Section \ref{section:smp}.
\subsubsection{Advertising and Discovery}
An LE device is discoverable and connectable, only if it periodically sends out Advertisements. An advertisement contains up to 31 bytes of data. To configure and enable advertisement broadcast, the following HCI commands can be used:
@ -814,7 +814,7 @@ An LE device is discoverable and connectable, only if it periodically sends out
\item \emph{hci\_le\_set\_advertising\_parameters}
\item \emph{hci\_le\_set\_advertise\_enable}
\end{itemize}
As these are direct HCI commands, please refer to Section \ref{subsubsection:sendinghci} for details and have a look at the SPP and LE Counter example in Section \ref{subsection:sppandlecounter}.
As these are direct HCI commands, please refer to Section \ref{subsubsection:sendinghci} for details and have a look at the SPP and LE Counter example in Section \ref{example:spp_and_le_counter}.
In addition to the Advertisement data, a device in the peripheral role can also provide Scan Response data, which has to be explicitly queried by the central device. It can be provided with the \emph{hci\_le\_set\_scan\_response\_data}.