doc: add missing APIs

doc/manual/update_apis.py

@@ -8,39 +8,68 @@ class State:
 
 # [file_name, api_title, api_label]
 apis = [ 
-    ["src/ble/ancs_client.h", "BLE ANCS Client", "ancsClient"],
-    ["src/ble/att_db_util.h", "BLE ATT Database", "attDb"],
-    ["src/ble/att_server.h", "BLE ATT Server", "attServer"],
-    ["src/ble/gatt_client.h", "BLE GATT Client", "gattClient"],
-    ["src/ble/le_device_db.h", "BLE Device Database", "leDeviceDb"],
-    ["src/ble/sm.h", "BLE Security Manager", "sm"],
-
-    ["src/classic/bnep.h", "BNEP", "bnep"],
-    ["src/classic/btstack_link_key_db.h","Link Key DB","lkDb"],
-    ["src/classic/hsp_hs.h","HSP Headset","hspHS"],
-    ["src/classic/hsp_ag.h","HSP Audio Gateway","hspAG"],   
-    ["src/classic/hfp_hf.h","HFP Hands-Free","hfpHF"],
-    ["src/classic/hfp_ag.h","HFP Audio Gateway","hfpAG"],
-    ["src/classic/pan.h", "PAN", "pan"],
-    ["src/classic/rfcomm.h", "RFCOMM", "rfcomm"],
-    ["src/classic/sdp_client.h", "SDP Client", "sdpClient"],
-    ["src/classic/sdp_client_rfcomm.h", "SDP RFCOMM Query", "sdpQueries"],
-    ["src/classic/sdp_server.h", "SDP Server", "sdpSrv"],
-    ["src/classic/sdp_util.h","SDP Utils", "sdpUtil"],
-
     ["src/ad_parser.h", "BLE Advertisements Parser", "advParser"],
     ["src/btstack_chipset.h","BTstack Chipset","btMemory"],
     ["src/btstack_control.h","BTstack Hardware Control","btControl"],
     ["src/btstack_event.h","HCI Event Getter","btEvent"],
-    ["src/btstack_memory.h","BTstack Memory Management","btMemory"],
     ["src/btstack_linked_list.h","BTstack Linked List","btList"],
+    ["src/btstack_memory.h","BTstack Memory Management","btMemory"],
     ["src/btstack_run_loop.h", "Run Loop", "runLoop"],
+    ["src/btstack_tlv.h", "Tag Value Length Persistent Storage (TLV)", "tlv"],
     ["src/btstack_util.h", "Common Utils", "btUtil"],
     ["src/gap.h", "GAP", "gap"],
     ["src/hci.h", "HCI", "hci"],
     ["src/hci_dump.h","HCI Logging","hciTrace"],
     ["src/hci_transport.h","HCI Transport","hciTransport"],
     ["src/l2cap.h", "L2CAP", "l2cap"],
+
+    ["src/ble/ancs_client.h", "BLE ANCS Client", "ancsClient"],
+    ["src/ble/att_db_util.h", "BLE ATT Database", "attDb"],
+    ["src/ble/att_server.h", "BLE ATT Server", "attServer"],
+    ["src/ble/gatt_client.h", "BLE GATT Client", "gattClient"],
+    ["src/ble/le_device_db.h", "BLE Device Database", "leDeviceDb"],
+    ["src/ble/le_device_db_tlv.h", "BLE Device Database TLV", "leDeviceDbTLV"],
+    ["src/ble/sm.h", "BLE Security Manager", "sm"],
+
+    ["src/ble/gatt-service/battery_service_server.h", "Battery Service Server", "batteryServiceServer"],
+    ["src/ble/gatt-service/cycling_power_service_server.h", "Cycling Power Service Server", "cyclingPowerServiceServer"],
+    ["src/ble/gatt-service/cycling_speed_and_cadence_service_server.h", "Cycling Speed and Cadence Service Server", "cyclingSpeedCadenceServiceServer"],
+    ["src/ble/gatt-service/device_information_service_server.h", "Device Information Service Server", "deviceInformationServiceServer"],
+    ["src/ble/gatt-service/heart_rate_service_server.h", "Heart Rate Service Server", "heartRateServiceServer"],
+    ["src/ble/gatt-service/hids_device.h", "HID Device Service Server", "hidsDevice"],
+    ["src/ble/gatt-service/mesh_provisioning_service_server.h", "Mesh Provisioning Service Server", "meshProvisioningServiceServer"],
+    ["src/ble/gatt-service/mesh_proxy_service_server.h", "Mesh Proxy Service Server", "meshProxyServiceServer"],
+    ["src/ble/gatt-service/nordic_spp_service_server.h", "Nordic SPP Service Server", "nordicSppServiceServer"],
+    ["src/ble/gatt-service/ublox_spp_service_server.h", "u-blox SPP Service Server", "ubloxSppServiceServer"],
+
+    ["src/classic/a2dp_sink.h", "A2DP Sink", "a2dpSink"],
+    ["src/classic/a2dp_source.h", "A2DP Source", "a2dpSource"],
+    ["src/classic/avdtp_sink.h", "AVDTP Sink", "avdtpSink"],
+    ["src/classic/avdtp_source.h", "AVDTP Source", "avdtpSource"],
+    ["src/classic/avrcp_browsing_controller.h", "AVRCP Browsing Controller", "avrcpBrowsingController"],
+    ["src/classic/avrcp_browsing_target.h", "AVRCP Browsing Target", "avrcpBrowsingTarget"],
+    ["src/classic/avrcp_controller.h", "AVRCP Controller", "avrcpController"],
+    ["src/classic/avrcp_target.h", "AVRCP Target", "avrcpTarget"],
+    ["src/classic/bnep.h", "BNEP", "bnep"],
+    ["src/classic/bnep.h", "BNEP", "bnep"],
+    ["src/classic/btstack_link_key_db.h","Link Key DB","lkDb"],
+    ["src/classic/btstack_sbc.h", "SBC", "sbc"],
+    ["src/classic/device_id_server.h", "Device ID Server", "deviceIdServer"],
+    ["src/classic/gatt_sdp.h", "GATT SDP", "gattSdp"],
+    ["src/classic/goep_client.h", "GOEP Client", "goepClient"],
+    ["src/classic/hfp_ag.h","HFP Audio Gateway","hfpAG"],
+    ["src/classic/hfp_hf.h","HFP Hands-Free","hfpHF"],
+    ["src/classic/hid_device.h", "HID Device", "hidDevice"],
+    ["src/classic/hsp_ag.h","HSP Audio Gateway","hspAG"],   
+    ["src/classic/hsp_hs.h","HSP Headset","hspHS"],
+    ["src/classic/pan.h", "PAN", "pan"],
+    ["src/classic/pan.h", "PAN", "pan"],
+    ["src/classic/pbap_client.h", "PBAP Client", "pbapClient"],
+    ["src/classic/rfcomm.h", "RFCOMM", "rfcomm"],
+    ["src/classic/sdp_client.h", "SDP Client", "sdpClient"],
+    ["src/classic/sdp_client_rfcomm.h", "SDP RFCOMM Query", "sdpQueries"],
+    ["src/classic/sdp_server.h", "SDP Server", "sdpSrv"],
+    ["src/classic/sdp_util.h","SDP Utils", "sdpUtil"],
 ]
 
 functions = {}

example/a2dp_sink_demo.c

@@ -172,6 +172,7 @@ static btstack_packet_callback_registration_t hci_event_callback_registration;
 static uint8_t  sdp_avdtp_sink_service_buffer[150];
 static uint8_t  sdp_avrcp_target_service_buffer[150];
 static uint8_t  sdp_avrcp_controller_service_buffer[200];
+static uint8_t  device_id_sdp_service_buffer[100];
 
 static uint16_t a2dp_cid = 0;
 static uint8_t  a2dp_local_seid = 0;
@@ -217,7 +218,7 @@ static btstack_resample_t resample_instance;
  * - handle_pcm_data - handles PCM audio frames. Here, they are stored a in wav file if STORE_TO_WAV_FILE is defined, and/or played using the audio library.
  */
 
-/* LISTING_START(MainConfiguration): Setup Audio Sink and AVRCP Controller services */
+/* LISTING_START(MainConfiguration): Setup Audio Sink and AVRCP services */
 static void hci_packet_handler(uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
 static void a2dp_sink_packet_handler(uint8_t packet_type, uint16_t channel, uint8_t * event, uint16_t event_size);
 static void handle_l2cap_media_data_packet(uint8_t seid, uint8_t *packet, uint16_t size);
@@ -235,6 +236,7 @@ static int a2dp_and_avrcp_setup(void){
     a2dp_sink_register_packet_handler(&a2dp_sink_packet_handler);
     a2dp_sink_register_media_handler(&handle_l2cap_media_data_packet);
 
+    // Create stream endpoint
     avdtp_stream_endpoint_t * local_stream_endpoint = a2dp_sink_create_stream_endpoint(AVDTP_AUDIO, 
         AVDTP_CODEC_SBC, media_sbc_codec_capabilities, sizeof(media_sbc_codec_capabilities), 
         media_sbc_codec_configuration, sizeof(media_sbc_codec_configuration));
@@ -242,9 +244,11 @@ static int a2dp_and_avrcp_setup(void){
         printf("A2DP Sink: not enough memory to create local stream endpoint\n");
         return 1;
     }
+
+    // Store stream enpoint's SEP ID, as it is used by A2DP API to indentify the stream endpoint
     a2dp_local_seid = avdtp_local_seid(local_stream_endpoint);
 
-    // Initialize AVRCP service.
+    // Initialize AVRCP service
     avrcp_init();
     avrcp_register_packet_handler(&avrcp_packet_handler);
     
@@ -258,12 +262,13 @@ static int a2dp_and_avrcp_setup(void){
     
     // Initialize SDP 
     sdp_init();
-    // setup AVDTP sink
+
+    // Create A2DP Sink service record and register it with SDP
     memset(sdp_avdtp_sink_service_buffer, 0, sizeof(sdp_avdtp_sink_service_buffer));
     a2dp_sink_create_sdp_record(sdp_avdtp_sink_service_buffer, 0x10001, AVDTP_SINK_FEATURE_MASK_HEADPHONE, NULL, NULL);
     sdp_register_service(sdp_avdtp_sink_service_buffer);
     
-    // setup AVRCP Controller
+    // Create AVRCP Controller service record and register it with SDP
     memset(sdp_avrcp_controller_service_buffer, 0, sizeof(sdp_avrcp_controller_service_buffer));
     uint16_t controller_supported_features = AVRCP_FEATURE_MASK_CATEGORY_PLAYER_OR_RECORDER;
 #ifdef AVRCP_BROWSING_ENABLED
@@ -272,17 +277,25 @@ static int a2dp_and_avrcp_setup(void){
     avrcp_controller_create_sdp_record(sdp_avrcp_controller_service_buffer, 0x10002, controller_supported_features, NULL, NULL);
     sdp_register_service(sdp_avrcp_controller_service_buffer);
     
-    // setup AVRCP Target
+    // Create AVRCP Target service record and register it with SDP
     memset(sdp_avrcp_target_service_buffer, 0, sizeof(sdp_avrcp_target_service_buffer));
     uint16_t target_supported_features = AVRCP_FEATURE_MASK_CATEGORY_MONITOR_OR_AMPLIFIER;
     avrcp_target_create_sdp_record(sdp_avrcp_target_service_buffer, 0x10003, target_supported_features, NULL, NULL);
     sdp_register_service(sdp_avrcp_target_service_buffer);
 
+    // Create Device ID (PnP) service record and register it with SDP
+    memset(device_id_sdp_service_buffer, 0, sizeof(device_id_sdp_service_buffer));
+    device_id_create_sdp_record(device_id_sdp_service_buffer, 0x10004, DEVICE_ID_VENDOR_ID_SOURCE_BLUETOOTH, BLUETOOTH_COMPANY_ID_BLUEKITCHEN_GMBH, 1, 1);
+    sdp_register_service(device_id_sdp_service_buffer);
+
+    // Set local name with a template Bluetooth address, that will be automatically
+    // replaced with a actual address once it is available, i.e. when BTstack boots
+    // up and starts talking to a Bluetooth module.
     gap_set_local_name("A2DP Sink Demo 00:00:00:00:00:00");
     gap_discoverable_control(1);
     gap_set_class_of_device(0x200408);
 
-    /* Register for HCI events */
+    // Register for HCI events
     hci_event_callback_registration.callback = &hci_packet_handler;
     hci_add_event_handler(&hci_event_callback_registration);
 
@@ -445,9 +458,9 @@ static void media_processing_close(void){
 
 /* @section Handle Media Data Packet 
  *
- * @text Media data packets, in this case the audio data, are received through the handle_l2cap_media_data_packet callback.
+ * @text Here the audio data, are received through the handle_l2cap_media_data_packet callback.
  * Currently, only the SBC media codec is supported. Hence, the media data consists of the media packet header and the SBC packet.
- * The SBC frame will be stored in a ring buffer for later processing (instead of decoding it to PCM right away which would require a much larger buffer)
+ * The SBC frame will be stored in a ring buffer for later processing (instead of decoding it to PCM right away which would require a much larger buffer).
  * If the audio stream wasn't started already and there are enough SBC frames in the ring buffer, start playback.
  */ 
 

example/a2dp_source_demo.c

@@ -276,27 +276,29 @@ static void stdin_process(char cmd);
 static void a2dp_demo_hexcmod_configure_sample_rate(int sample_rate);
 
 static int a2dp_source_and_avrcp_services_init(void){
-    // request role change on reconnecting headset to always use them in slave mode
+    // Request role change on reconnecting headset to always use them in slave mode
     hci_set_master_slave_policy(0);
 
     l2cap_init();
-    // Initialize  A2DP Source.
+    // Initialize  A2DP Source
     a2dp_source_init();
     a2dp_source_register_packet_handler(&a2dp_source_packet_handler);
 
-    // Create stream endpoint.
+    // Create stream endpoint
     avdtp_stream_endpoint_t * local_stream_endpoint = a2dp_source_create_stream_endpoint(AVDTP_AUDIO, AVDTP_CODEC_SBC, media_sbc_codec_capabilities, sizeof(media_sbc_codec_capabilities), media_sbc_codec_configuration, sizeof(media_sbc_codec_configuration));
     if (!local_stream_endpoint){
         printf("A2DP Source: not enough memory to create local stream endpoint\n");
         return 1;
     }
+
+    // Store stream enpoint's SEP ID, as it is used by A2DP API to indentify the stream endpoint
     media_tracker.local_seid = avdtp_local_seid(local_stream_endpoint);
     avdtp_source_register_delay_reporting_category(media_tracker.local_seid);
 
-    // Initialize AVRCP Service.
+    // Initialize AVRCP Service
     avrcp_init();
     avrcp_register_packet_handler(&avrcp_packet_handler);
-    // Initialize AVRCP Target.
+    // Initialize AVRCP Target
     avrcp_target_init();
     avrcp_target_register_packet_handler(&avrcp_target_packet_handler);
     // Initialize AVRCP Controller
@@ -306,12 +308,12 @@ static int a2dp_source_and_avrcp_services_init(void){
     // Initialize SDP, 
     sdp_init();
     
-    // Create  A2DP Source service record and register it with SDP.
+    // Create A2DP Source service record and register it with SDP
     memset(sdp_a2dp_source_service_buffer, 0, sizeof(sdp_a2dp_source_service_buffer));
     a2dp_source_create_sdp_record(sdp_a2dp_source_service_buffer, 0x10001, AVDTP_SOURCE_FEATURE_MASK_PLAYER, NULL, NULL);
     sdp_register_service(sdp_a2dp_source_service_buffer);
     
-    // Create AVRCP target service record and register it with SDP.
+    // Create AVRCP target service record and register it with SDP
     memset(sdp_avrcp_target_service_buffer, 0, sizeof(sdp_avrcp_target_service_buffer));
     uint16_t supported_features = AVRCP_FEATURE_MASK_CATEGORY_PLAYER_OR_RECORDER;
 #ifdef AVRCP_BROWSING_ENABLED
@@ -320,12 +322,14 @@ static int a2dp_source_and_avrcp_services_init(void){
     avrcp_target_create_sdp_record(sdp_avrcp_target_service_buffer, 0x10002, supported_features, NULL, NULL);
     sdp_register_service(sdp_avrcp_target_service_buffer);
 
-    // setup AVRCP Controller
+    // Register AVRCP Controller
     memset(sdp_avrcp_controller_service_buffer, 0, sizeof(sdp_avrcp_controller_service_buffer));
     uint16_t controller_supported_features = AVRCP_FEATURE_MASK_CATEGORY_PLAYER_OR_RECORDER;
     avrcp_controller_create_sdp_record(sdp_avrcp_controller_service_buffer, 0x10003, controller_supported_features, NULL, NULL);
     sdp_register_service(sdp_avrcp_controller_service_buffer);
 
+    // Register Device ID (PnP) service SDP record
+    memset(device_id_sdp_service_buffer, 0, sizeof(device_id_sdp_service_buffer));
     device_id_create_sdp_record(device_id_sdp_service_buffer, 0x10004, DEVICE_ID_VENDOR_ID_SOURCE_BLUETOOTH, BLUETOOTH_COMPANY_ID_BLUEKITCHEN_GMBH, 1, 1);
     sdp_register_service(device_id_sdp_service_buffer);
 
@@ -399,8 +403,6 @@ static void produce_sine_audio(int16_t * pcm_buffer, int num_samples_to_write){
             default:
                 break;
         }   
-        
-        
     }
 }
 
@@ -432,7 +434,7 @@ static void produce_audio(int16_t * pcm_buffer, int num_samples){
 }
 
 static int a2dp_demo_fill_sbc_audio_buffer(a2dp_media_sending_context_t * context){
-    // perform sbc encodin
+    // perform sbc encoding
     int total_num_bytes_read = 0;
     unsigned int num_audio_samples_per_sbc_buffer = btstack_sbc_encoder_num_audio_frames();
     while (context->samples_ready >= num_audio_samples_per_sbc_buffer