From 37113e139380e8323e21814eaefbd91f80a4b4d9 Mon Sep 17 00:00:00 2001 From: Matthias Ringwald Date: Fri, 24 Apr 2015 22:44:13 +0200 Subject: [PATCH] review docu in examples --- example/embedded/gap_inquiry.c | 16 +++++++++++++--- example/embedded/led_counter.c | 12 ++++-------- example/embedded/sdp_general_query.c | 28 +++++++++++++++++++--------- 3 files changed, 36 insertions(+), 20 deletions(-) diff --git a/example/embedded/gap_inquiry.c b/example/embedded/gap_inquiry.c index 9f97984bc..a03d07a18 100644 --- a/example/embedded/gap_inquiry.c +++ b/example/embedded/gap_inquiry.c @@ -155,6 +155,8 @@ static void packet_handler (uint8_t packet_type, uint8_t *packet, uint16_t size) start_scan(); state = ACTIVE; } + break; + /* @text In ACTIVE, the following events are processed: * - Inquiry result event: the list of discovered devices is processed and the * Class of Device (CoD), page scan mode, clock offset, and RSSI are stored in a table. @@ -233,13 +235,20 @@ static void packet_handler (uint8_t packet_type, uint8_t *packet, uint16_t size) } } -/* @text For more details please check Section DiscoverRemoteDevices in the - * BTstack manual and the source code. +/* @text For more details on discovering remote devices, please see + * Section DiscoverRemoteDevices */ + +/* @section Main app setup + * + * @text Listing MainConfiguration shows main application code. + * It registers the HCI packet handler and starts the Bluetoth stack + */ + +/* LISTING_START(MainConfiguration): Setup heartbeat timer */ int btstack_main(int argc, const char * argv[]); int btstack_main(int argc, const char * argv[]) { - hci_register_packet_handler(packet_handler); // turn on! @@ -247,4 +256,5 @@ int btstack_main(int argc, const char * argv[]) { return 0; } +/* LISTING_END */ /* EXAMPLE_END */ diff --git a/example/embedded/led_counter.c b/example/embedded/led_counter.c index 2ca985c5c..4d6e4ee9c 100644 --- a/example/embedded/led_counter.c +++ b/example/embedded/led_counter.c @@ -38,9 +38,8 @@ // ***************************************************************************** /* EXAMPLE_START(led_counter): Hello World: blinking LED without Bluetooth * - * @text The example uses the BTstack run loop to blink an LED. - * The example demonstrates how to provide a periodic timer to toggle an LED - * and send debug messages to the console as a minimal BTstack test. + * @text The example demonstrates how to provide a periodic timer to toggle an + * LED and send debug messages to the console as a minimal BTstack test. */ // ***************************************************************************** @@ -81,13 +80,10 @@ static void heartbeat_handler(timer_source_t *ts){ } /* LISTING_END */ -/* @section Turn On and Go +/* @section Main app setup * * @text Listing MainConfiguration shows main application code. - * It is called after hardware and BTstack configuration (memory, run loop and - * transport layer) by the platform main in - * \path{platforms/PLATFORM/src/main.c}. - */ + * It configures the heartbeat tier and adds it to the run loop. /* LISTING_START(MainConfiguration): Setup heartbeat timer */ int btstack_main(int argc, const char * argv[]); diff --git a/example/embedded/sdp_general_query.c b/example/embedded/sdp_general_query.c index 13c46f843..37706e5bb 100644 --- a/example/embedded/sdp_general_query.c +++ b/example/embedded/sdp_general_query.c @@ -69,15 +69,13 @@ int attribute_id = -1; static uint8_t attribute_value[1000]; static const int attribute_value_buffer_size = sizeof(attribute_value); -static bd_addr_t remote = {0x04,0x0C,0xCE,0xE4,0x85,0xD3}; - /* @section SDP Client Setup * * @text SDP is based on L2CAP. To receive SDP query events you must register a * callback, i.e. query handler, with the SPD parser, as shown in - * Listing SDPClientInit. Via this handler, the SDP client will receive events: + * Listing SDPClientInit. Via this handler, the SDP client will receive the following events: * - SDP_QUERY_ATTRIBUTE_VALUE containing the results of the query in chunks, - * - SDP_QUERY_COMPLETE reporting the status and the end of the query. + * - SDP_QUERY_COMPLETE indicating the end of the query and the status */ /* LISTING_START(SDPClientInit): SDP client setup */ @@ -96,12 +94,18 @@ static void sdp_client_init(){ /* @section SDP Client Query * - * @text To get the a list of service records on a remote device, you need to - * call sdp_general_query_for_uuid() with the remote address and the + * @text To trigger an SDP query to get the a list of service records on a remote device, + * you need to call sdp_general_query_for_uuid() with the remote address and the * UUID of the public browse group, as shown in Listing SDPQueryUUID. - * In this example we used fixed address of the remote device. + * In this example we used fixed address of the remote device shown in Listing Remote. + * Please update it with the address of a device in your vicinity, e.g., one reported + * by the GAP Inuiry example in the previous s-e-c-t-i-o-n. */ +/* LISTING_START(Remote): Address of remote device in big-endian order */ +static bd_addr_t remote = {0x04,0x0C,0xCE,0xE4,0x85,0xD3}; +/* LISTING_END */ + /* LISTING_START(SDPQueryUUID): Quering a list of service records on a remote device. */ static void packet_handler (void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size){ // printf("packet_handler type %u, packet[0] %x\n", packet_type, packet[0]); @@ -127,11 +131,17 @@ static void assertBuffer(int size){ } } -/* @section Handling SDP Client Query Result +/* @section Handling SDP Client Query Results * * @text The SDP Client returns the results of the query in chunks. Each result * packet contains the record ID, the Attribute ID, and a chunk of the Attribute - * value, see Listing HandleSDPQUeryResult. + * value. + * In this example, we append new chunks for the same Attribute ID in a large buffer, + * see Listing HandleSDPQUeryResult. + * + * To save memory, it's also possible to process these chunks directly by a custom stream parser, + * similar to the way XML files are parsed by a SAX parser. Have a look at \emph{src/sdp_query_rfcomm.c} + * which retrieves the RFCOMM channel number and the service name. */ /* LISTING_START(HandleSDPQUeryResult): Handling query result chunks. */