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

improve docu

Browse Source
This commit is contained in:
Matthias Ringwald 2015-04-26 12:59:22 +02:00
parent a29875347d
commit e126fbda14
3 changed files with 31 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
example/embedded/gatt_browser.c
View File

@ -92,12 +92,12 @@ static int service_count = 0;
static int service_index = 0; static int service_index = 0;
/* @section Setting up GATT client /* @section GATT client setup
* *
* @text In setup phase, a GATT client must register the HCI and GATT client * @text In the setup phase, a GATT client must register the HCI and GATT client
* packet handlers, as shown in Listing GATTClientSetup. * packet handlers, as shown in Listing GATTClientSetup.
* Additionally, the security manager can be setup, if signed writes, or * Additionally, the security manager can be setup, if signed writes, or
* encrypted or authenticated connection, are required to access the * encrypted, or authenticated connection are required, to access the
* characteristics, as explained in Section smp. * characteristics, as explained in Section smp.
*/ */
@ -122,8 +122,7 @@ static void gatt_client_setup(){
// Register handler for GATT client events // Register handler for GATT client events
gc_id = gatt_client_register_packet_handler(&handle_gatt_client_event); gc_id = gatt_client_register_packet_handler(&handle_gatt_client_event);
// Optionally, setup security manager for signed writes or // Optinoally, Setup security manager
// encrypted or authenticated connection
sm_init(); sm_init();
sm_set_io_capabilities(IO_CAPABILITY_NO_INPUT_NO_OUTPUT); sm_set_io_capabilities(IO_CAPABILITY_NO_INPUT_NO_OUTPUT);
} }
@ -175,7 +174,7 @@ static void fill_advertising_report_from_packet(advertising_report_t * report, u
} }
/* @section Packet handlers /* @section HCI packet handler
* *
* @text The HCI packet handler has to start the scanning, * @text The HCI packet handler has to start the scanning,
* to find the first advertising device, to stop scanning, to connect * to find the first advertising device, to stop scanning, to connect
@ -227,7 +226,9 @@ static void handle_hci_event(void * connection, uint8_t packet_type, uint16_t ch
} }
/* LISTING_END */ /* LISTING_END */
/* @text Query results and further queries are handled by the GATT client packet /* @section GATT Client event handler
*
* @text Query results and further queries are handled by the GATT client packet
* handler, as shown in Listing GATTBrowserQueryHandler. Here, upon * handler, as shown in Listing GATTBrowserQueryHandler. Here, upon
* receiving the primary services, the * receiving the primary services, the
* gatt_client_discover_characteristics_for_service() query for the last * gatt_client_discover_characteristics_for_service() query for the last

15
example/embedded/le_counter.c
View File

@ -82,8 +82,11 @@ static int le_notification_enabled;
* @text To be discoverable, LE Advertisements are enabled using direct HCI Commands. * @text To be discoverable, LE Advertisements are enabled using direct HCI Commands.
* As there's no guarantee that a HCI command can always be sent, the gap_run function * As there's no guarantee that a HCI command can always be sent, the gap_run function
* is used to send each command as requested by the $todos$ variable. * is used to send each command as requested by the $todos$ variable.
* First, the advertisement data is set, then the advertisement params incl. the * First, the advertisement data is set with hci_le_set_advertising_data.
* advertisement interval is set. Finally, advertisements are enabled. See Listing gapRun. * Then the advertisement parameters including the advertisement interval is set
* with hci_le_set_advertising_parameters.
* Finally, advertisements are enabled with hci_le_set_advertise_enable.
* See Listing gapRun.
* *
* In this example, the Advertisement contains the Flags attribute and the device name. * In this example, the Advertisement contains the Flags attribute and the device name.
* The flag 0x06 indicates: LE General Discoverable Mode and BR/EDR not supported. * The flag 0x06 indicates: LE General Discoverable Mode and BR/EDR not supported.
@ -141,7 +144,7 @@ static void gap_run(){
* *
* @text The packet handler is only used to trigger advertisements after BTstack is ready and after disconnects. * @text The packet handler is only used to trigger advertisements after BTstack is ready and after disconnects.
* See Listing packetHandler. * See Listing packetHandler.
* Advertisemetns are not automatically re-enabled after a connection was closed although it was active before. * Advertisements are not automatically re-enabled after a connection was closed even though they have been active before.
* *
*/ */
@ -207,7 +210,7 @@ static void heartbeat_handler(struct timer *ts){
/* /*
* @section ATT Read * @section ATT Read
* *
* The ATT Server handles all reads to constant data. For dynamic data like the custom characteristic, the registered * @text The ATT Server handles all reads to constant data. For dynamic data like the custom characteristic, the registered
* att_read_callback is called. To handle long characteristics and long reads, the att_read_callback is first called * att_read_callback is called. To handle long characteristics and long reads, the att_read_callback is first called
* with buffer == NULL, to request the total value lenght. Then it will be called again requesting a chunk of the value. * with buffer == NULL, to request the total value lenght. Then it will be called again requesting a chunk of the value.
* See Listing attRead. * See Listing attRead.
@ -234,8 +237,8 @@ static uint16_t att_read_callback(uint16_t con_handle, uint16_t att_handle, uint
/* /*
* @section ATT Write * @section ATT Write
* *
* @text The only valid att write in this example is to the Client Characteristic Configuration, which configures notification * @text The only valid ATT write in this example is to the Client Characteristic Configuration, which configures notification
* and indication. If the att_handle matches the client configuration handle, the new configuration value is stored and used * and indication. If the ATT handle matches the client configuration handle, the new configuration value is stored and used
* in the hearbeat handler to decide if a new value should be sent. See Listing attWrite * in the hearbeat handler to decide if a new value should be sent. See Listing attWrite
*/ */

28
example/embedded/panu_demo.c
View File

@ -43,9 +43,9 @@
/* EXAMPLE_START(panu_demo): PANU Demo /* EXAMPLE_START(panu_demo): PANU Demo
* *
* @text This example implements both a PANU client and a server. In server mode, it * @text This example implements both a PANU client and a server. In server mode, it
* setups a BNEP server and registers a PANU SDP record and wait for incoming connections. * sets up a BNEP server and registers a PANU SDP record and waits for incoming connections.
* In client mode, it connects to a remote device, does an SDP Query to identify the PANU * In client mode, it connects to a remote device, does an SDP Query to identify the PANU
* service and initiates the BNEP connection. * service and initiates a BNEP connection.
*/ */
#include "btstack-config.h" #include "btstack-config.h"
@ -128,7 +128,7 @@ static data_source_t tap_dev_ds;
/* @section TUN / TAP interface routines /* @section TUN / TAP interface routines
* *
* This example requires a TUN/TAP interface to connect the Bluetooth network interface * @text This example requires a TUN/TAP interface to connect the Bluetooth network interface
* with the native system. It has been tested on Linux and OS X, but should work on any * with the native system. It has been tested on Linux and OS X, but should work on any
* system that provides TUN/TAP with minor modifications. * system that provides TUN/TAP with minor modifications.
* *
@ -230,15 +230,15 @@ int tap_alloc(char *dev, bd_addr_t bd_addr)
} }
/* /*
* @text Listig processTapData shows how removing a data source allows to * @text Listig processTapData shows how a packet is received from the TAP network interface
* temporarily disable incoming data, providing a basic flow control. * and forwarded over the BNEP connection.
* *
* After successfully reading a network packet, the call to * After successfully reading a network packet, the call to
* \emph{bnep_can_send_packet_now} checks, if BTstack can forward * \emph{bnep_can_send_packet_now} checks, if BTstack can forward
* a network packet now. If that's not possible, the received data stays * a network packet now. If that's not possible, the received data stays
* in the network buffer and the data source elements is removed from the * in the network buffer and the data source elements is removed from the
* run loop. \emph{process_tap_dev_data} will not be called until * run loop. \emph{process_tap_dev_data} will not be called until
* the data source is registered again. * the data source is registered again. This provides a basic flow control.
*/ */
/* LISTING_START(processTapData): Process incoming network packets */ /* LISTING_START(processTapData): Process incoming network packets */
@ -416,7 +416,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha
case HCI_EVENT_PACKET: case HCI_EVENT_PACKET:
event = packet[0]; event = packet[0];
switch (event) { switch (event) {
/* @text When $BTSTACK_EVENT_STATE$ with state $HCI_STATE_WORKING$ /* @text When BTSTACK_EVENT_STATE with state HCI_STATE_WORKING
* is received and the example is started in client mode, the remote SDP BNEP query is started. * is received and the example is started in client mode, the remote SDP BNEP query is started.
*/ */
case BTSTACK_EVENT_STATE: case BTSTACK_EVENT_STATE:
@ -442,7 +442,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha
/* LISTING_RESUME */ /* LISTING_RESUME */
/* @text In server mode, $BNEP_EVENT_INCOMING_CONNECTION$ is received after a client has connected. /* @text In server mode, BNEP_EVENT_INCOMING_CONNECTION is received after a client has connected.
* and the TAP network interface is then configured. A data source is set up and registered with the * and the TAP network interface is then configured. A data source is set up and registered with the
* run loop to receive Ethernet packets from the TAP interface. * run loop to receive Ethernet packets from the TAP interface.
* *
@ -473,9 +473,9 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha
/* LISTING_PAUSE */ /* LISTING_PAUSE */
/* @text In client mode, $BNEP_EVENT_OPEN_CHANNEL_COMPLETE$ is received after a client has connected /* @text In client mode, BNEP_EVENT_OPEN_CHANNEL_COMPLETE is received after a client has connected
* or when the connection fails. The status field returs the error code. It is otherwise identical to * or when the connection fails. The status field returs the error code. It is otherwise identical to
* $BNEP_EVENT_INCOMING_CONNECTION$ before. * BNEP_EVENT_INCOMING_CONNECTION before.
*/ */
case BNEP_EVENT_OPEN_CHANNEL_COMPLETE: case BNEP_EVENT_OPEN_CHANNEL_COMPLETE:
if (packet[2]) { if (packet[2]) {
@ -505,14 +505,14 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha
/* LISTING_RESUME */ /* LISTING_RESUME */
/* @text If there is a timeout during the connection setup, $BNEP_EVENT_CHANNEL_TIMEOUT$ will be received /* @text If there is a timeout during the connection setup, BNEP_EVENT_CHANNEL_TIMEOUT will be received
* and the BNEP connection closed * and the BNEP connection closed
*/ */
case BNEP_EVENT_CHANNEL_TIMEOUT: case BNEP_EVENT_CHANNEL_TIMEOUT:
printf("BNEP channel timeout! Channel will be closed\n"); printf("BNEP channel timeout! Channel will be closed\n");
break; break;
/* @text $BNEP_EVENT_CHANNEL_CLOSED$ is received when the connection gets closed /* @text BNEP_EVENT_CHANNEL_CLOSED is received when the connection gets closed
*/ */
case BNEP_EVENT_CHANNEL_CLOSED: case BNEP_EVENT_CHANNEL_CLOSED:
printf("BNEP channel closed\n"); printf("BNEP channel closed\n");
@ -523,7 +523,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha
} }
break; break;
/* @text $BNEP_EVENT_READY_TO_SEND$ indicates that a new packet can be send. This triggers the retry of a /* @text BNEP_EVENT_READY_TO_SEND indicates that a new packet can be send. This triggers the retry of a
* parked network packet. If this succeeds, the data source element is added to the run loop again. * parked network packet. If this succeeds, the data source element is added to the run loop again.
*/ */
case BNEP_EVENT_READY_TO_SEND: case BNEP_EVENT_READY_TO_SEND:
@ -542,7 +542,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha
} }
break; break;
/* @text Ethernet packets from the remote device are received in the packet handler with type $BNEP_DATA_PACKET$ /* @text Ethernet packets from the remote device are received in the packet handler with type BNEP_DATA_PACKET.
* It is forwarded to the TAP interface. * It is forwarded to the TAP interface.
*/ */
case BNEP_DATA_PACKET: case BNEP_DATA_PACKET: