From e126fbda14b0f8db9ee4228a716cfcea204e73dd Mon Sep 17 00:00:00 2001 From: Matthias Ringwald Date: Sun, 26 Apr 2015 12:59:22 +0200 Subject: [PATCH] improve docu --- example/embedded/gatt_browser.c | 15 ++++++++------- example/embedded/le_counter.c | 15 +++++++++------ example/embedded/panu_demo.c | 28 ++++++++++++++-------------- 3 files changed, 31 insertions(+), 27 deletions(-) diff --git a/example/embedded/gatt_browser.c b/example/embedded/gatt_browser.c index 3c5a6e67a..f0b42d99f 100644 --- a/example/embedded/gatt_browser.c +++ b/example/embedded/gatt_browser.c @@ -92,12 +92,12 @@ static int service_count = 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. * 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. */ @@ -122,8 +122,7 @@ static void gatt_client_setup(){ // Register handler for GATT client events gc_id = gatt_client_register_packet_handler(&handle_gatt_client_event); - // Optionally, setup security manager for signed writes or - // encrypted or authenticated connection + // Optinoally, Setup security manager sm_init(); 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, * 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 */ -/* @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 * receiving the primary services, the * gatt_client_discover_characteristics_for_service() query for the last diff --git a/example/embedded/le_counter.c b/example/embedded/le_counter.c index 0c2d7732a..e7c5dd5d9 100644 --- a/example/embedded/le_counter.c +++ b/example/embedded/le_counter.c @@ -82,8 +82,11 @@ static int le_notification_enabled; * @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 * is used to send each command as requested by the $todos$ variable. - * First, the advertisement data is set, then the advertisement params incl. the - * advertisement interval is set. Finally, advertisements are enabled. See Listing gapRun. + * First, the advertisement data is set with hci_le_set_advertising_data. + * 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. * 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. * 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 * - * 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 * with buffer == NULL, to request the total value lenght. Then it will be called again requesting a chunk of the value. * 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 * - * @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 + * @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 * in the hearbeat handler to decide if a new value should be sent. See Listing attWrite */ diff --git a/example/embedded/panu_demo.c b/example/embedded/panu_demo.c index 5dd0e8576..3c877cca5 100644 --- a/example/embedded/panu_demo.c +++ b/example/embedded/panu_demo.c @@ -43,9 +43,9 @@ /* EXAMPLE_START(panu_demo): PANU Demo * * @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 - * service and initiates the BNEP connection. + * service and initiates a BNEP connection. */ #include "btstack-config.h" @@ -128,7 +128,7 @@ static data_source_t tap_dev_ds; /* @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 * 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 - * temporarily disable incoming data, providing a basic flow control. + * @text Listig processTapData shows how a packet is received from the TAP network interface + * and forwarded over the BNEP connection. * * After successfully reading a network packet, the call to * \emph{bnep_can_send_packet_now} checks, if BTstack can forward * 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 * 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 */ @@ -416,7 +416,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha case HCI_EVENT_PACKET: event = packet[0]; 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. */ case BTSTACK_EVENT_STATE: @@ -442,7 +442,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha /* 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 * 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 */ - /* @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 - * $BNEP_EVENT_INCOMING_CONNECTION$ before. + * BNEP_EVENT_INCOMING_CONNECTION before. */ case BNEP_EVENT_OPEN_CHANNEL_COMPLETE: if (packet[2]) { @@ -505,14 +505,14 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha /* 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 */ case BNEP_EVENT_CHANNEL_TIMEOUT: printf("BNEP channel timeout! Channel will be closed\n"); 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: printf("BNEP channel closed\n"); @@ -523,7 +523,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha } 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. */ case BNEP_EVENT_READY_TO_SEND: @@ -542,7 +542,7 @@ static void packet_handler (void * connection, uint8_t packet_type, uint16_t cha } 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. */ case BNEP_DATA_PACKET: