added btstack manual tex files

docs/manual/Makefile

@@ -0,0 +1,2 @@
+clean:
+	rm -f $ *.pdf *.log *.aux *.gz *.toc *.out

docs/manual/api_events_and_errors.tex

@@ -0,0 +1,112 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{Events and Errors}
+\label{appendix:api_events_and_errors}
+
+L2CAP events and data packets are delivered to the packet handler specified by \emph{l2cap\_register\_service} resp. \emph{l2cap\_create\_channel\_internal}. Data packets have the L2CAP\_DATA\_PACKET packet type. L2CAP provides the following events:
+\begin{itemize}
+\item L2CAP\_EVENT\_CHANNEL\_OPENED - sent if channel establishment is done. Status not equal zero indicates an error. Possible errors: out of memory; connection terminated by local host, when the connection to remote device fails.
+\item L2CAP\_EVENT\_CHANNEL\_CLOSED - emitted when channel is closed. No status information is provided.
+\item L2CAP\_EVENT\_INCOMING\_CONNECTION - received when the connection is requested  by remote. Connection accept and decline are performed with \emph{l2cap\_accept\_connection\_internal} and \emph{l2cap\_decline\_connecti-on\_internal} respectively.
+\item L2CAP\_EVENT\_CREDITS - emitted when there is a chance to send a new L2CAP packet. BTstack does not buffer packets. Instead, it requires the application to retry sending if BTstack cannot deliver a packet to the Bluetooth module. In this case, the l2cap\_send\_internal will return an error. 
+\item L2CAP\_EVENT\_SERVICE\_REGISTERED - Status not equal zero indicates an error. Possible errors: service is already registered; MAX\_NO-\_L2CAP\_SERVICES (defined in config.h) already registered.
+\end{itemize}
+ 
+\begin{table*}[bp]
+\caption{L2CAP Events}
+\begin{tabular}{p{1cm}p{10cm}c}\toprule
+\multicolumn{2}{c}{Event / Event Parameters (size in bits) } & Event Code\\ 
+\midrule
+\multicolumn{2}{l}{L2CAP\_EVENT\_CHANNEL\_OPENED} & 0x70\\
+&\emph{event(8), len(8), status(8), address(48), handle(16)}\\
+&\emph{psm(16), local\_cid(16), remote\_cid(16), local\_mtu(16), }\\
+&\emph{remote\_mtu(16)}\\
+\\
+\multicolumn{2}{l}{L2CAP\_EVENT\_CHANNEL\_CLOSED} & 0x71\\
+&\emph{event (8), len(8), channel(16)}\\
+\\
+\multicolumn{2}{l}{L2CAP\_EVENT\_INCOMING\_CONNECTION}& 0x72\\
+&\emph{event(8), len(8), address(48), handle(16), psm (16), }\\
+&\emph{local\_cid(16), remote\_cid (16)}\\
+\\
+\multicolumn{2}{l}{L2CAP\_EVENT\_CREDITS} & 0x74\\
+&\emph{event(8), len(8), local\_cid(16), credits(8)}\\
+\\
+\multicolumn{2}{l}{L2CAP\_EVENT\_SERVICE\_REGISTERED} & 0x75\\
+&\emph{event(8), len(8), status(8), psm(16)}\\
+\\
+\bottomrule
+ \label{table:l2capEvents}
+\end{tabular}
+\end{table*}
+
+\pagebreak
+
+All RFCOMM events and data packets are currently delivered to the packet handler specified by \emph{rfcomm\_register\_packet\_handler}. Data packets have the \mbox{RFCOMM}\_DATA\_PACKET packet type. Here is the list of events provided by RFCOMM:
+\begin{itemize}
+\item RFCOMM\_EVENT\_INCOMING\_CONNECTION - received when the connection is requested by remote. Connection accept and decline are performed with \emph{rfcomm\_accept\_connection\_internal} and \emph{rfcomm\_decline\_con-nection\_internal} respectively.
+\item RFCOMM\_EVENT\_CHANNEL\_CLOSED - emitted when channel is closed. No status information is provided.
+\item RFCOMM\_EVENT\_OPEN\_CHANNEL\_COMPLETE - sent if channel establishment is done. Status not equal zero indicates an error. Possible errors: an L2CAP error, out of memory.
+\item RFCOMM\_EVENT\_CREDITS - The application can resume sending when this even is received. See Section \ref{section:flowcontrol} for more on RFCOMM credit-based flow-control.
+\item RFCOMM\_EVENT\_SERVICE\_REGISTERED - Status not equal zero indicates an error. Possible errors: service is already registered; MAX-\_NO\_RFCOMM\_SERVICES (defined in config.h) already registered.
+\end{itemize}
+
+\begin{table*}[bp]
+\caption{RFCOMM Events}
+\begin{tabular}{p{1cm}p{10cm}c}\toprule
+\multicolumn{2}{c}{Event / Event Parameters (size in bits)} & Event Code\\ 
+\midrule
+
+\multicolumn{2}{l}{RFCOMM\_EVENT\_OPEN\_CHANNEL\_COMPLETE} & 0x80\\
+&\emph{event(8), len(8), status(8), address(48), handle(16), }\\
+&\emph{server\_channel(8), rfcomm\_cid(16), max\_frame\_size(16)}\\
+\\
+\multicolumn{2}{l}{RFCOMM\_EVENT\_CHANNEL\_CLOSED} & 0x81\\
+&\emph{event(8), len(8), rfcomm\_cid(16)}\\
+\\
+\multicolumn{2}{l}{RFCOMM\_EVENT\_INCOMING\_CONNECTION}& 0x82\\
+&\emph{event(8), len(8), address(48), channel (8),} \\
+& \emph{rfcomm\_cid(16)}\\
+\\
+\multicolumn{2}{l}{RFCOMM\_EVENT\_CREDITS} & 0x84\\
+&\emph{event(8), len(8), rfcomm\_cid(16), credits(8)}\\
+\\
+\multicolumn{2}{l}{RFCOMM\_EVENT\_SERVICE\_REGISTERED} & 0x85\\
+&\emph{event(8), len(8), status(8), rfcomm server channel\_id(8)}\\
+\bottomrule
+ \label{table:rfcommEvents}
+\end{tabular}
+\end{table*}
+
+
+\begin{table}
+\caption{Errors}
+\begin{tabular}{lc}\toprule
+Error & Error Code\\ 
+\midrule
+{\tiny BTSTACK\_MEMORY\_ALLOC\_FAILED} & {\tiny 0x56}\\
+{\tiny BTSTACK\_ACL\_BUFFERS\_FULL} & {\tiny 0x57}\\
+{\tiny L2CAP\_COMMAND\_REJECT\_REASON\_COMMAND\_NOT\_UNDERSTOOD} & {\tiny 0x60}\\
+{\tiny L2CAP\_COMMAND\_REJECT\_REASON\_SIGNALING\_MTU\_EXCEEDED} & {\tiny 0x61}\\
+{\tiny L2CAP\_COMMAND\_REJECT\_REASON\_INVALID\_CID\_IN\_REQUEST} & {\tiny 0x62}\\
+{\tiny L2CAP\_CONNECTION\_RESPONSE\_RESULT\_SUCCESSFUL} & {\tiny 0x63}\\
+{\tiny L2CAP\_CONNECTION\_RESPONSE\_RESULT\_PENDING} & {\tiny 0x64}\\
+{\tiny L2CAP\_CONNECTION\_RESPONSE\_RESULT\_REFUSED\_PSM} & {\tiny 0x65}\\
+{\tiny L2CAP\_CONNECTION\_RESPONSE\_RESULT\_REFUSED\_SECURITY} & {\tiny 0x66}\\
+{\tiny L2CAP\_CONNECTION\_RESPONSE\_RESULT\_REFUSED\_RESOURCES} & {\tiny 0x65}\\
+{\tiny L2CAP\_CONFIG\_RESPONSE\_RESULT\_SUCCESSFUL} & {\tiny 0x66}\\
+{\tiny L2CAP\_CONFIG\_RESPONSE\_RESULT\_UNACCEPTABLE\_PARAMS} & {\tiny 0x67}\\
+{\tiny L2CAP\_CONFIG\_RESPONSE\_RESULT\_REJECTED} & {\tiny 0x68}\\
+{\tiny L2CAP\_CONFIG\_RESPONSE\_RESULT\_UNKNOWN\_OPTIONS} & {\tiny 0x69}\\
+{\tiny L2CAP\_SERVICE\_ALREADY\_REGISTERED} & {\tiny 0x6a}\\
+{\tiny RFCOMM\_MULTIPLEXER\_STOPPED} & {\tiny 0x70}\\
+{\tiny RFCOMM\_CHANNEL\_ALREADY\_REGISTERED} & {\tiny 0x71}\\
+{\tiny RFCOMM\_NO\_OUTGOING\_CREDITS} & {\tiny 0x72}\\
+{\tiny SDP\_HANDLE\_ALREADY\_REGISTERED} & {\tiny 0x80}\\
+\bottomrule
+\label{table:sdpErrors}
+\end{tabular}
+\end{table}
+
+\begin{minipage}[t][5cm][t]{\textwidth}
+\end{minipage}
+\pagebreak

docs/manual/api_gatt_client.tex

@@ -0,0 +1,154 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{GATT Client API}
+\label{appendix:api_gatt_client}
+$ $
+\begin{lstlisting}
+// Set up GATT client.
+void gatt_client_init();
+
+// Register callback (packet handler) for gatt client. Returns gatt client ID.
+uint16_t gatt_client_register_packet_handler (gatt_client_callback_t callback);
+
+// Unregister callback (packet handler) for gatt client.
+void gatt_client_unregister_packet_handler(uint16_t gatt_client_id);
+
+// Returns the GATT client context for the specified handle.
+// gatt_client_t * get_gatt_client_context_for_handle(uint16_t con_handle);
+
+// Returns if the gatt client is ready to receive a query. It is used with daemon.
+int gatt_client_is_ready(uint16_t handle);
+
+// Discovers all primary services. For each found service, an
+// le_service_event_t with type set to GATT_SERVICE_QUERY_RESULT
+// will be generated and passed to the registered callback.
+// The gatt_complete_event_t, with type set to GATT_QUERY_COMPLETE,
+// marks the end of discovery.
+le_command_status_t gatt_client_discover_primary_services(uint16_t gatt_client_id, uint16_t con_handle);
+
+// Discovers a specific primary service given its UUID. This service
+// may exist multiple times. For each found service, an
+// le_service_event_t with type set to GATT_SERVICE_QUERY_RESULT
+// will be generated and passed to the registered callback.
+// The gatt_complete_event_t, with type set to GATT_QUERY_COMPLETE,
+// marks the end of discovery.
+le_command_status_t gatt_client_discover_primary_services_by_uuid16(uint16_t gatt_client_id, uint16_t con_handle, uint16_t uuid16);
+le_command_status_t gatt_client_discover_primary_services_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, const uint8_t * uuid);
+
+// Finds included services within the specified service. For each
+// found included service, an le_service_event_t with type set to
+// GATT_INCLUDED_SERVICE_QUERY_RESULT will be generated and passed
+// to the registered callback. The gatt_complete_event_t with type
+// set to GATT_QUERY_COMPLETE, marks the end of discovery.
+//
+// Information about included service type (primary/secondary) can
+// be retrieved either by sending an ATT find information request
+// for the returned start group handle (returning the handle and
+// the UUID for primary or secondary service) or by comparing the
+// service to the list of all primary services.
+le_command_status_t gatt_client_find_included_services_for_service(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service);
+
+// Discovers all characteristics within the specified service. For
+// each found characteristic, an le_characteristics_event_t with 
+// type set to GATT_CHARACTERISTIC_QUERY_RESULT will be generated 
+// and passed to the registered callback. The gatt_complete_event_t 
+// with type set to GATT_QUERY_COMPLETE, marks the end of discovery.
+le_command_status_t gatt_client_discover_characteristics_for_service(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service);
+
+// The following four functions are used to discover all 
+// characteristics within the specified service or handle range, and 
+// return those that match the given UUID. For each found
+// characteristic, an le_characteristic_event_t with type set to   
+// GATT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to 
+// the registered callback. The gatt_complete_event_t with type set
+// to GATT_QUERY_COMPLETE, marks the end of discovery.
+le_command_status_t gatt_client_discover_characteristics_for_handle_range_by_uuid16(uint16_t gatt_client_id, uint16_t con_handle, uint16_t start_handle, uint16_t end_handle, uint16_t uuid16);
+le_command_status_t gatt_client_discover_characteristics_for_handle_range_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, uint16_t start_handle, uint16_t end_handle, uint8_t * uuid);
+le_command_status_t gatt_client_discover_characteristics_for_service_by_uuid16 (uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service, uint16_t  uuid16);
+le_command_status_t gatt_client_discover_characteristics_for_service_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service, uint8_t * uuid128);
+
+// Discovers attribute handle and UUID of a characteristic 
+// descriptor within the specified characteristic. For each found
+// descriptor, an le_characteristic_descriptor_event_t with 
+// type set to GATT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be  
+// generated and passed to the registered callback. The  
+// gatt_complete_event_t with type set to GATT_QUERY_COMPLETE, marks 
+// the end of discovery.
+le_command_status_t gatt_client_discover_characteristic_descriptors(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic);
+
+// Reads the characteristic value using the characteristic's value
+// handle. If the characteristic value is found, an 
+// le_characteristic_value_event_t with type set to 
+// GATT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and
+// passed to the registered callback. The gatt_complete_event_t 
+// with type set to GATT_QUERY_COMPLETE, marks the end of read.
+le_command_status_t gatt_client_read_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic);
+le_command_status_t gatt_client_read_value_of_characteristic_using_value_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle);
+
+// Reads the long characteristic value using the characteristic's 
+// value handle. The value will be returned in several blobs. For 
+// each blob, an le_characteristic_value_event_t with type set to 
+// GATT_CHARACTERISTIC_VALUE_QUERY_RESULT and updated value offset
+// will be generated and passed to the registered callback. The 
+// gatt_complete_event_t with type set to GATT_QUERY_COMPLETE, marks
+// the end of read.
+le_command_status_t gatt_client_read_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic);
+le_command_status_t gatt_client_read_long_value_of_characteristic_using_value_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle);
+    
+// Writes the characteristic value using the characteristic's value
+// handle without an acknowledgement that the write was successfully
+// performed.
+le_command_status_t gatt_client_write_value_of_characteristic_without_response(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data);
+
+// Writes the authenticated characteristic value using the
+// characteristic's value handle without an acknowledgement
+// that the write was successfully performed.
+le_command_status_t gatt_client_signed_write_without_response(uint16_t gatt_client_id, uint16_t con_handle, uint16_t handle, uint16_t message_len, uint8_t * message, sm_key_t csrk, uint32_t sgn_counter);
+
+// Writes the characteristic value using the characteristic's value
+// handle. The gatt_complete_event_t with type set to
+// GATT_QUERY_COMPLETE, marks the end of write. The write is
+// successfully performed, if the event's status field is set to 0.
+le_command_status_t gatt_client_write_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data);
+le_command_status_t gatt_client_write_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data);
+
+// Writes of the long characteristic value using the
+// characteristic's value handle. It uses server response to
+// validate that the write was correctly received.
+// The gatt_complete_event_t with type set to GATT_QUERY_COMPLETE
+// marks the end of write. The write is successfully performed, if
+// the event's status field is set to 0.
+le_command_status_t gatt_client_reliable_write_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data);
+
+// Reads the characteristic descriptor using its handle. If the
+// characteristic descriptor is found, an
+// le_characteristic_descriptor_event_t with type set to
+// GATT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated
+// and passed to the registered callback. The gatt_complete_event_t
+// with type set to GATT_QUERY_COMPLETE, marks the end of read.
+le_command_status_t gatt_client_read_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor);
+
+// Reads the long characteristic descriptor using its handle. It
+// will be returned in several blobs.  For each blob, an
+// le_characteristic_descriptor_event_t with type set to
+// GATT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated
+// and passed to the registered callback. The gatt_complete_event_t
+// with type set to GATT_QUERY_COMPLETE, marks the end of read.
+le_command_status_t gatt_client_read_long_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor);
+
+// Writes the characteristic descriptor using its handle.
+// The gatt_complete_event_t with type set to
+// GATT_QUERY_COMPLETE, marks the end of write. The write is
+// successfully performed, if the event's status field is set to 0.
+le_command_status_t gatt_client_write_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor, uint16_t length, uint8_t * data);
+le_command_status_t gatt_client_write_long_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor, uint16_t length, uint8_t * data);
+
+// Writes the client characteristic configuration of the specified 
+// characteristic. It is used to subscribe for notifications or 
+// indications of the characteristic value. For notifications or 
+// indications specify:
+// GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION resp. 
+// GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 
+// as configuration value.
+le_command_status_t gatt_client_write_client_characteristic_configuration(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t * characteristic, uint16_t configuration);
+\end{lstlisting}
+\pagebreak

docs/manual/api_hci.tex

@@ -0,0 +1,26 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{Host Controller Interface (HCI) API}
+\label{appendix:api_hci}
+$ $
+\begin{lstlisting}
+// Set up HCI.
+void hci_init(hci_transport_t *transport, void *config, bt_control_t *control, remote_device_db_t const* remote_device_db);
+
+// Used if L2CAP is not used (rarely). 
+void hci_register_packet_handler(void (*handler)(uint8_t packet_type, uint8_t *packet, uint16_t size));
+
+// Requests the change of BTstack power mode.
+int  hci_power_control(HCI_POWER_MODE mode);
+
+// Allows to control if device is dicoverable. OFF by default.
+void hci_discoverable_control(uint8_t enable);
+
+// Creates and sends HCI command packets based on a template and 
+// a list of parameters. Will return error if outgoing data buffer 
+// is occupied. 
+int hci_send_cmd(const hci_cmd_t *cmd, ...);
+
+// Deletes link key for remote device with baseband address.
+void hci_drop_link_key_for_bd_addr(bd_addr_t *addr);
+\end{lstlisting}
+\pagebreak

docs/manual/api_l2cap.tex

@@ -0,0 +1,40 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{L2CAP API}
+\label{appendix:api_l2cap}
+$ $
+\begin{lstlisting}
+// Set up L2CAP and register L2CAP with HCI layer.
+void l2cap_init(void);
+
+// Registers a packet handler that handles HCI and general BTstack
+// events.
+void l2cap_register_packet_handler(void (*handler)(void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size));
+
+// Creates L2CAP channel to the PSM of a remote device with baseband
+// address. A new baseband connection will be initiated if needed.
+void l2cap_create_channel_internal(void * connection, btstack_packet_handler_t packet_handler, bd_addr_t address, uint16_t psm, uint16_t mtu);
+
+// Disconencts L2CAP channel with given identifier. 
+void l2cap_disconnect_internal(uint16_t local_cid, uint8_t reason);
+
+// Queries the maximal transfer unit (MTU) for L2CAP channel with
+// given identifier. 
+uint16_t l2cap_get_remote_mtu_for_local_cid(uint16_t local_cid);
+
+// Sends L2CAP data packet to the channel with given identifier.
+int l2cap_send_internal(uint16_t local_cid, uint8_t *data, uint16_t len);
+
+// Registers L2CAP service with given PSM and MTU, and assigns a
+// packet handler. On embedded systems, use NULL for connection
+// parameter.
+void l2cap_register_service_internal(void *connection, btstack_packet_handler_t packet_handler, uint16_t psm, uint16_t mtu);
+
+// Unregisters L2CAP service with given PSM.  On embedded systems,
+// use NULL for connection parameter.
+void l2cap_unregister_service_internal(void *connection, uint16_t psm);
+
+// Accepts/Deny incoming L2CAP connection.
+void l2cap_accept_connection_internal(uint16_t local_cid);
+void l2cap_decline_connection_internal(uint16_t local_cid, uint8_t reason);
+\end{lstlisting}
+\pagebreak

docs/manual/api_rfcomm.tex

@@ -0,0 +1,58 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{RFCOMM API}
+\label{appendix:api_rfcomm}
+$ $
+\begin{lstlisting}
+// Set up RFCOMM.
+void rfcomm_init(void);
+
+// Register packet handler.
+void rfcomm_register_packet_handler(void (*handler)(void *connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size));
+
+// Creates RFCOMM connection (channel) to a given server channel on 
+// a remote device with baseband address. A new baseband connection 
+// will be initiated if necessary.
+// This connection is an RFCOMM channel. The channel will 
+// automatically provide enough credits to the remote side.
+void rfcomm_create_channel_internal(void *connection, bd_addr_t *addr, uint8_t channel);
+
+// Creates RFCOMM connection (channel) to a given server channel on
+// a remote device with baseband address. A new baseband connection
+// will be initiated if necessary. 
+// This channel will use explicit credit management. During channel 
+// establishment, an initial amount of credits is provided.
+void rfcomm_create_channel_with_initial_credits_internal(void *connection, bd_addr_t *addr, uint8_t server_channel, uint8_t initial_credits);
+
+// Disconencts RFCOMM channel with given identifier. 
+void rfcomm_disconnect_internal(uint16_t rfcomm_cid);
+
+// Registers RFCOMM service for a server channel and a maximum frame 
+// size, and assigns a packet handler. On embedded systems, use NULL 
+// for connection parameter. This channel will automatically provide 
+// enough credits to the remote side.
+void rfcomm_register_service_internal(void *connection, uint8_t channel, uint16_t max_frame_size);
+
+// Registers RFCOMM service for a server channel and a maximum frame
+// size, and assigns a packet handler. On embedded systems, use NULL 
+// for connection parameter.  This channel will use explicit credit
+// management. During channel establishment, an initial amount of 
+// credits is provided.
+void rfcomm_register_service_with_initial_credits_internal(void *connection, uint8_t channel, uint16_t max_frame_size, uint8_t initial_credits);
+
+// Unregister RFCOMM service.
+void rfcomm_unregister_service_internal(uint8_t service_channel);
+
+// Accepts/Deny incoming RFCOMM connection.
+void rfcomm_accept_connection_internal(uint16_t rfcomm_cid);
+void rfcomm_decline_connection_internal(uint16_t rfcomm_cid);
+
+
+// Grant more incoming credits to the remote side for the given 
+// RFCOMM channel identifier.
+void rfcomm_grant_credits(uint16_t rfcomm_cid, uint8_t credits);
+
+// Sends RFCOMM data packet to the RFCOMM channel with given
+// identifier.
+int  rfcomm_send_internal(uint16_t rfcomm_cid, uint8_t *data, uint16_t len); 
+\end{lstlisting}
+\pagebreak

docs/manual/api_run_loop.tex

@@ -0,0 +1,42 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{Run Loop API}
+\label{appendix:api_run_loop}
+$ $
+\begin{lstlisting}
+// Set timer based on current time in milliseconds.
+void run_loop_set_timer(timer_source_t *a, uint32_t timeout_in_ms);
+
+// Set callback that will be executed when timer expires.
+void run_loop_set_timer_handler(timer_source_t *ts, void (*process)(timer_source_t *_ts));
+
+// Add/Remove timer source.
+void run_loop_add_timer(timer_source_t *timer); 
+int  run_loop_remove_timer(timer_source_t *timer);
+
+// Init must be called before any other run_loop call. 
+// Use RUN_LOOP_EMBEDDED for embedded devices.
+void run_loop_init(RUN_LOOP_TYPE type);
+
+// Set data source callback.
+void run_loop_set_data_source_handler(data_source_t *ds, int (*process)(data_source_t *_ds));
+
+// Add/Remove data source.
+void run_loop_add_data_source(data_source_t *dataSource);
+int  run_loop_remove_data_source(data_source_t *dataSource);
+
+// Execute configured run loop. This function does not return.
+void run_loop_execute(void);
+
+// Sets how many milliseconds has one tick.
+uint32_t embedded_ticks_for_ms(uint32_t time_in_ms);
+
+// Queries the current time in ticks.
+uint32_t embedded_get_ticks(void);
+
+// Sets an internal flag that is checked in the critical section
+// just before entering sleep mode. Has to be called by the 
+// interrupt handler of a data source to signal the run loop that  
+// a new data is available.
+void embedded_trigger(void);
+\end{lstlisting}
+\pagebreak

docs/manual/api_sdp.tex

@@ -0,0 +1,20 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{SDP API}
+\label{appendix:api_sdp}
+$ $
+\begin{lstlisting}
+// Set up SDP.
+void sdp_init(void);
+
+// Register service record internally - this version does not copy
+// the record therefore it must be forever accessible.
+// Preconditions:
+//     - AttributeIDs are in ascending order;
+//     - ServiceRecordHandle is first attribute and valid.
+// @returns ServiceRecordHandle or 0 if registration failed.
+uint32_t sdp_register_service_internal(void *connection, service_record_item_t * record_item);
+
+// Unregister service record internally.
+void sdp_unregister_service_internal(void *connection, uint32_t service_record_handle);
+\end{lstlisting}
+\pagebreak

docs/manual/api_sdp_client.tex

@@ -0,0 +1,48 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{SDP Client API}
+\label{appendix:api_sdp_client}
+$ $
+\begin{lstlisting}
+/* SDP Client */
+
+// Queries the SDP service of the remote device given a service 
+// search pattern and a list of attribute IDs. The remote data is 
+// handled by the SDP parser. The SDP parser delivers attribute 
+// values and done event via a registered callback.
+void sdp_client_query(bd_addr_t remote, uint8_t * des_serviceSearchPattern, uint8_t * des_attributeIDList);
+
+
+
+/* SDP Parser */
+
+// Basic SDP Parser event type.
+typedef enum sdp_parser_event_type {
+    SDP_PARSER_ATTRIBUTE_VALUE = 1,
+    SDP_PARSER_COMPLETE,
+} sdp_parser_event_type_t;
+
+typedef struct sdp_parser_event {
+    uint8_t type;
+} sdp_parser_event_t;
+
+// SDP Parser event to deliver an attribute value byte by byte.
+typedef struct sdp_parser_attribute_value_event {
+    uint8_t type;
+    int record_id;
+    uint16_t attribute_id;
+    uint32_t attribute_length;
+    int data_offset;
+    uint8_t data;
+} sdp_parser_attribute_value_event_t;
+
+// SDP Parser event to indicate that parsing is complete.
+typedef struct sdp_parser_complete_event {
+    uint8_t type;
+    uint8_t status; // 0 == OK
+} sdp_parser_complete_event_t;
+
+// Registers a callback to receive attribute value data and parse  
+// complete event. 
+void sdp_parser_register_callback(void (*sdp_callback)(sdp_parser_event_t* event));
+\end{lstlisting}
+\pagebreak

docs/manual/api_sdp_queries.tex

@@ -0,0 +1,43 @@
+% !TEX root = btstack_gettingstarted.tex
+\section{SDP Query API}
+\label{appendix:api_sdp_query}
+$ $
+ \begin{lstlisting}
+/* SDP Queries */
+
+// Basic SDP Query event type.
+typedef struct sdp_query_event {
+    uint8_t type;
+} sdp_query_event_t;
+
+// SDP Query event to indicate that query is complete.
+typedef struct sdp_query_complete_event {
+    uint8_t type;
+    uint8_t status; // 0 == OK
+} sdp_query_complete_event_t;
+
+
+
+/* SDP Query for RFCOMM */
+
+// SDP Query RFCOMM event to deliver channel number and service 
+// name byte by byte.
+typedef struct sdp_query_rfcomm_service_event {
+    uint8_t type;
+    uint8_t channel_nr;
+    uint8_t * service_name;
+} sdp_query_rfcomm_service_event_t;
+
+// Searches SDP records on a remote device for RFCOMM services with
+// a given UUID.
+void sdp_query_rfcomm_channel_and_name_for_uuid(bd_addr_t remote, uint16_t uuid);
+
+// Searches SDP records on a remote device for RFCOMM services with 
+// a given service search pattern.
+void sdp_query_rfcomm_channel_and_name_for_search_pattern(bd_addr_t remote, uint8_t * des_serviceSearchPattern);
+
+// Registers a callback to receive RFCOMM service and query complete
+// event. 
+void sdp_query_rfcomm_register_callback(void(*sdp_app_callback)(sdp_query_event_t * event, void * context), void * context);
+\end{lstlisting}
+\pagebreak

docs/manual/booktabs.sty

@@ -0,0 +1,182 @@
+%%
+%% This is file `booktabs.sty',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% booktabs.dtx  (with options: `package')
+%% 
+%% -----------------------------------------------------------------
+%% Author:     Simon Fear
+%% Maintainer: Danie Els (dnjels@sun.ac.za)
+%% 
+%% This file is part of the booktabs package for publication
+%% quality tables for LaTeX
+%% 
+%%       Copyright (C) 1995--2005 Simon Fear
+%% 
+%% This program is free software; you can redistribute it and/or
+%% modify it under the terms of the GNU General Public License as
+%% published by the Free Software Foundation; either version 2 of
+%% the License, or (at your option) any later version.
+%% 
+%% This program is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+%% GNU General Public License for more details.
+%% 
+%% You should have received a copy of the GNU General Public
+%% License along with this program; if not, write to the Free
+%% Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+%% MA 02111-1307 USA
+%% -----------------------------------------------------------------
+\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+\ProvidesPackage{booktabs}
+    [2005/04/14 v1.61803 publication quality tables]
+\newdimen\heavyrulewidth
+\newdimen\lightrulewidth
+\newdimen\cmidrulewidth
+\newdimen\belowrulesep
+\newdimen\belowbottomsep
+\newdimen\aboverulesep
+\newdimen\abovetopsep
+\newdimen\cmidrulesep
+\newdimen\cmidrulekern
+\newdimen\defaultaddspace
+\heavyrulewidth=.08em
+\lightrulewidth=.05em
+\cmidrulewidth=.03em
+\belowrulesep=.65ex
+\belowbottomsep=0pt
+\aboverulesep=.4ex
+\abovetopsep=0pt
+\cmidrulesep=\doublerulesep
+\cmidrulekern=.5em
+\defaultaddspace=.5em
+\newcount\@cmidla
+\newcount\@cmidlb
+\newdimen\@aboverulesep
+\newdimen\@belowrulesep
+\newcount\@thisruleclass
+\newcount\@lastruleclass
+\@lastruleclass=0
+\newdimen\@thisrulewidth
+\def\futurenonspacelet#1{\def\@BTcs{#1}%
+   \afterassignment\@BTfnslone\let\nexttoken= }
+\def\@BTfnslone{\expandafter\futurelet\@BTcs\@BTfnsltwo}
+\def\@BTfnsltwo{\expandafter\ifx\@BTcs\@sptoken\let\next=\@BTfnslthree
+   \else\let\next=\nexttoken\fi \next}
+\def\@BTfnslthree{\afterassignment\@BTfnslone\let\next= }
+\def\toprule{\noalign{\ifnum0=`}\fi
+  \@aboverulesep=\abovetopsep
+  \global\@belowrulesep=\belowrulesep %global cos for use in the next noalign
+  \global\@thisruleclass=\@ne
+  \@ifnextchar[{\@BTrule}{\@BTrule[\heavyrulewidth]}}
+\def\midrule{\noalign{\ifnum0=`}\fi
+  \@aboverulesep=\aboverulesep
+  \global\@belowrulesep=\belowrulesep
+  \global\@thisruleclass=\@ne
+  \@ifnextchar[{\@BTrule}{\@BTrule[\lightrulewidth]}}
+\def\bottomrule{\noalign{\ifnum0=`}\fi
+  \@aboverulesep=\aboverulesep
+  \global\@belowrulesep=\belowbottomsep
+  \global\@thisruleclass=\@ne
+  \@ifnextchar[{\@BTrule}{\@BTrule[\heavyrulewidth]}}
+\def\specialrule#1#2#3{\noalign{\ifnum0=`}\fi
+  \@aboverulesep=#2\global\@belowrulesep=#3\global\@thisruleclass=\tw@
+  \@BTrule[#1]}
+\def\addlinespace{\noalign{\ifnum0=`}\fi
+  \@ifnextchar[{\@addspace}{\@addspace[\defaultaddspace]}}
+\def\@addspace[#1]{\global\@belowrulesep=#1\global\@thisruleclass=\tw@
+  \futurelet\@tempa\@BTendrule}
+\def\@BTrule[#1]{%
+  \global\@thisrulewidth=#1\relax
+  \ifnum\@thisruleclass=\tw@\vskip\@aboverulesep\else
+  \ifnum\@lastruleclass=\z@\vskip\@aboverulesep\else
+  \ifnum\@lastruleclass=\@ne\vskip\doublerulesep\fi\fi\fi
+  \ifx\longtable\undefined
+     \let\@BTswitch\@BTnormal
+  \else\ifx\hline\LT@hline
+     \let\@BTswitch\@BLTrule
+  \else
+     \let\@BTswitch\@BTnormal
+  \fi\fi
+  \@BTswitch}
+\AtBeginDocument{%
+   \providecommand*\CT@arc@{}}%% colortbl support
+\def\@BTnormal{%
+    {\CT@arc@\hrule\@height\@thisrulewidth}%
+    \futurenonspacelet\@tempa\@BTendrule}
+\def\@BLTrule{\@ifnextchar({\@@BLTrule}{\@@BLTrule()}}
+\def\@@BLTrule(#1){\@setrulekerning{#1}%
+\global\@cmidlb\LT@cols
+\ifnum0=`{\fi}%
+\@cmidruleb
+\noalign{\ifnum0=`}\fi
+\futurenonspacelet\@tempa\@BTendrule}
+\def\@BTendrule{\ifx\@tempa\toprule\global\@lastruleclass=\@thisruleclass
+  \else\ifx\@tempa\midrule\global\@lastruleclass=\@thisruleclass
+  \else\ifx\@tempa\bottomrule\global\@lastruleclass=\@thisruleclass
+  \else\ifx\@tempa\cmidrule\global\@lastruleclass=\@thisruleclass
+  \else\ifx\@tempa\specialrule\global\@lastruleclass=\@thisruleclass
+  \else\ifx\@tempa\addlinespace\global\@lastruleclass=\@thisruleclass
+  \else\global\@lastruleclass=\z@\fi\fi\fi\fi\fi\fi
+  \ifnum\@lastruleclass=\@ne\relax\else\vskip\@belowrulesep\fi
+  \ifnum0=`{\fi}}
+\def\@setrulekerning#1{%
+   \global\let\cmrkern@l\z@
+   \global\let\cmrkern@r\z@
+   \@tfor\@tempa :=#1\do
+  {\def\@tempb{r}%
+   \ifx\@tempa\@tempb
+      \global\let\cmrkern@r\cmidrulekern
+      \def\cmrsideswitch{\cmrkern@r}%
+   \else
+      \def\@tempb{l}%
+      \ifx\@tempa\@tempb
+         \global\let\cmrkern@l\cmidrulekern
+         \def\cmrsideswitch{\cmrkern@l}%
+      \else
+         \global\expandafter\let\cmrsideswitch\@tempa
+      \fi
+   \fi}}
+\def\cmidrule{\noalign{\ifnum0=`}\fi
+    \@ifnextchar[{\@cmidrule}{\@cmidrule[\cmidrulewidth]}}
+\def\@cmidrule[#1]{\@ifnextchar({\@@cmidrule[#1]}{\@@cmidrule[#1]()}}
+\def\@@cmidrule[#1](#2)#3{\@@@cmidrule[#3]{#1}{#2}}
+\def\@@@cmidrule[#1-#2]#3#4{\global\@cmidla#1\relax
+    \global\advance\@cmidla\m@ne
+    \ifnum\@cmidla>0\global\let\@gtempa\@cmidrulea\else
+    \global\let\@gtempa\@cmidruleb\fi
+    \global\@cmidlb#2\relax
+    \global\advance\@cmidlb-\@cmidla
+    \global\@thisrulewidth=#3
+    \@setrulekerning{#4}
+    \ifnum\@lastruleclass=\z@\vskip \aboverulesep\fi
+    \ifnum0=`{\fi}\@gtempa
+    \noalign{\ifnum0=`}\fi\futurenonspacelet\@tempa\@xcmidrule}
+\def\@xcmidrule{%
+   \ifx\@tempa\cmidrule
+       \vskip-\@thisrulewidth
+       \global\@lastruleclass=\@ne
+   \else \ifx\@tempa\morecmidrules
+       \vskip \cmidrulesep
+       \global\@lastruleclass=\@ne\else
+       \vskip \belowrulesep
+       \global\@lastruleclass=\z@
+   \fi\fi
+   \ifnum0=`{\fi}}
+\def\@cmidrulea{%
+   \multispan\@cmidla&\multispan\@cmidlb
+   \unskip\hskip\cmrkern@l%
+  {\CT@arc@\leaders\hrule \@height\@thisrulewidth\hfill}%
+   \hskip\cmrkern@r\cr}%
+\def\@cmidruleb{%
+    \multispan\@cmidlb
+    \unskip\hskip \cmrkern@l%
+   {\CT@arc@\leaders\hrule \@height\@thisrulewidth\hfill}%
+    \hskip\cmrkern@r\cr}%
+\def\morecmidrules{\noalign{\relax}}
+\endinput
+%%
+%% End of file `booktabs.sty'.

docs/manual/hwsetup_msp430.tex

@@ -0,0 +1,118 @@
+% !TEX root = btstack_gettingstarted.tex
+\newcommand{\urlfoot}[2]{\href{#1}{{\color{blue} #2}}\footnote{#1}}
+
+\newcommand{\UserGuide}{\urlfoot{http://processors.wiki.ti.com/index.php/PAN1315EMK\_User\_Guide\#RF3\_Connector}{User Guide}{}}
+\newcommand{\MSPGCCWiki}{\urlfoot{http://sourceforge.net/apps/mediawiki/mspgcc/index.php?title=MSPGCC\_Wiki}{MSPGCC Wiki}}
+\newcommand{\Subversion}{\urlfoot{http://www.sliksvn.com/en/download}{Subversion}}
+\newcommand{\Tortoise}{\urlfoot{http://tortoisesvn.net/downloads.html}{Tortoise SVN}}
+\newcommand{\GNUMake}{\urlfoot{http://gnuwin32.sourceforge.net/packages/make.htm}{GNU Make}}
+\newcommand{\Python}{\urlfoot{http://www.python.org/getit/}{Python}}
+\newcommand{\mspgcc}{\urlfoot{http://sourceforge.net/projects/mspgcc/files/Windows/mingw32/}{mspgcc}}
+\newcommand{\BTSfile}{\urlfoot{http://processors.wiki.ti.com/index.php/CC256x\_Downloads}{BTS file}}
+\newcommand{\MSPFlasher}{\urlfoot{http://processors.wiki.ti.com/index.php/MSP430\_Flasher\_-\_Command\_Line\_Programmer}{MSP430Flasher software}}
+\newcommand{\MSPDebug}{\urlfoot{http://mspdebug.sourceforge.net/}{MSPDebug}}
+
+\section{Get started with BTstack and MSP-EXP430F5438 + CC256x}
+
+\subsection{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 \UserGuide{}. 
+
+\subsection{General Tools}
+
+The MSP430 port of BTstack is developed using the Long Term Support (LTS) version of mspgcc. General information about it and installation instructions are provided on the \MSPGCCWiki{}.
+
+On Unix-based systems, Subversion, make, and Python are usually installed. If not, use the system's packet manager to install them. 
+
+On Windows, you need to install and configure Subversion, mspgcc, GNU Make, and Python manually:
+ \begin{itemize}
+ \item \Subversion{} for Windows.
+ \item Optionally \Tortoise{}: This is a GUI front-end for Subversion that makes checkouts and other operations easier by integrating them into the Windows Explorer.
+ \ref{sec:windowsPath}). For example, for one Python installation the path is  \path{C:\Python27}. 
+ \item \mspgcc{} for Windows:  Download and extract to \path{C:\mspgcc}. Add \path{C:\mspgcc\bin} folder to the Windows Path in Environment variable as explained in Section \ref{sec:windowsPath}.
+ \item \GNUMake{} for Windows: Add its bin folder to the Windows Path in Environment Variables. The bin folder is where make.exe resides, and it's usually located in \path{C:\Program Files\GnuWin32\bin}. 
+ \item \Python{} for Windows: Add Python installation folder to the Windows Path in Environment Variables.
+ \end{itemize}
+
+\subsubsection{Adding paths to the Windows Path variable}\label{sec:windowsPath}
+\begin{itemize} 
+   \item Go to: Control Panel$\rightarrow$System$\rightarrow$Advanced tab$\rightarrow$Environment Variables.
+   \item The top part contains a list of User variables. 
+   \item Click on the Path variable and then click edit.
+   \item Go to the end of the line, then append the path to the list., for example, \path{C:\mspgcc\bin} for mspgcc.
+   \item Ensure that there is a semicolon before and after \path{C:\mspgcc\bin}. 
+\end{itemize}
+
+
+\subsection{Getting BTstack from SVN}
+
+Use Subversion to check out the latest version. There are two approaches:
+\begin{itemize}
+\item On Windows: Use Tortoise SVN to checkout using the URL:
+\end{itemize}
+	\begin{lstlisting}
+ 		http://btstack.googlecode.com/svn/trunk/
+	\end{lstlisting}
+\begin{itemize}
+\item Use Subversion in a shell: Navigate to a folder where you would like to checkout BTstack, then type:
+\end{itemize}
+	\begin{lstlisting}
+ 		svn checkout http://btstack.googlecode.com/svn/trunk/
+	\end{lstlisting}
+In both cases, Subversion will create the \path{btstack} folder and place the code there.
+
+
+\subsection{CC256x Init Scripts}
+
+In order to use the CC256x chipset on the PAN13xx modules, an initialization script must be obtained. Due to licensing restrictions, this initialization script must be obtained separately as follows:
+\begin{itemize}
+\item Download the \BTSfile{} for your PAN13xx module.
+\item Copy the included .bts file into \path{btstack/chipset-cc256x}
+\item In \path{chipset-cc256x}, run the Python script: $./convert\_bts\_init\_scripts.py$
+\end{itemize}
+
+The common code for all CC256x chipsets is provided by $bt\_control\_cc256x.c$. During the setup, $bt\_control\_cc256x\_instance$ function is used to get  a $bt\_control\_t$ instance and passed to $hci\_init$ function. 
+
+Note: Depending on the PAN13xx module you're using, you'll need to update \path{bluetooth_init_cc25...} in the Makefile to match the downloaded file.
+
+\subsection{Compiling the Examples}
+
+Go to \path{btstack/MSP-EXP430F5438-CC256x/example} folder in command prompt and run make. If all the paths are correct, it will generate several .hex files. These .hex files are the firmware for the MSP430 and can be loaded onto the device, as described in the next section.
+
+\subsection{Loading Firmware}
+
+To load firmware files onto the MSP430 MCU, you need a programmer like the MSP430 MSP-FET430UIF debugger or something similar. Now, you can use one of following software tools:
+
+ \begin{itemize}
+ \item  \MSPFlasher{} (windows-only):
+ 	\begin{itemize}
+ 	   \item Use the following command, where you need to replace the \path{BINARY_FILE_NAME.hex} with the name of your application:
+	\end{itemize} 
+\end{itemize}
+	
+	   \begin{lstlisting}
+ 		MSP430Flasher.exe -n MSP430F5438A -w "BINARY_FILE_NAME.hex" -v -g -z [VCC]
+	   \end{lstlisting}
+
+ \begin{itemize}
+	
+	\item \MSPDebug{}: An example session with the MSP-FET430UIF connected on OS X is given in following listing:
+\end{itemize}
+
+\begin{lstlisting}
+mspdebug -j -d /dev/tty.FET430UIFfd130 uif
+... 
+prog blink.hex
+run
+\end{lstlisting}
+
+
+\subsection{Run the Example}
+
+As a first test, we recommend the SPP Counter example (see Section \ref{section:sppcounter}). During the startup, the LEDs flash rapidly while the init script is transferred to the CC256x chipset. After that, the Experimenter 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.
+
+After this quick intro, the main manual starts now.
+
+ 
+