From 1ea30d1b446f98d1f402813e0d01452037f1e414 Mon Sep 17 00:00:00 2001 From: Milanka Ringwald Date: Wed, 19 May 2021 09:55:26 +0200 Subject: [PATCH] docu: extract GATT clients and services documentation from source code --- doc/manual/.gitignore | 2 + doc/manual/Makefile | 5 +- doc/manual/docs/.gitignore | 2 + doc/manual/docs/gatt_clients.md | 29 ---- doc/manual/docs/gatt_services.md | 119 -------------- doc/manual/docs/ports/.gitignore | 1 + doc/manual/mkdocs-template.yml | 1 + doc/manual/ports2markdown.py | 9 +- .../intro.md => template/examples_intro.md} | 0 doc/manual/template/gatt_clients_intro.md | 3 + doc/manual/template/gatt_services_intro.md | 10 ++ .../intro.md => template/ports_intro.md} | 0 doc/manual/update_apis.py | 2 +- doc/manual/update_gatt_services.py | 155 ++++++++++++++++++ doc/manual/update_listings.py | 9 +- src/ble/gatt-service/ancs_client.h | 11 +- src/ble/gatt-service/battery_service_client.h | 7 +- src/ble/gatt-service/battery_service_server.h | 10 +- .../cycling_power_service_server.h | 12 +- ...cycling_speed_and_cadence_service_server.h | 12 +- .../device_information_service_client.h | 14 +- .../device_information_service_server.h | 12 +- .../gatt-service/heart_rate_service_server.h | 20 +-- src/ble/gatt-service/hids_client.h | 12 +- src/ble/gatt-service/hids_device.h | 2 +- .../mesh_provisioning_service_server.h | 4 +- .../gatt-service/mesh_proxy_service_server.h | 4 +- .../gatt-service/nordic_spp_service_server.h | 4 +- .../scan_parameters_service_client.h | 7 + .../scan_parameters_service_server.h | 4 +- .../gatt-service/ublox_spp_service_server.h | 4 +- 31 files changed, 273 insertions(+), 213 deletions(-) create mode 100644 doc/manual/docs/.gitignore delete mode 100644 doc/manual/docs/gatt_clients.md delete mode 100644 doc/manual/docs/gatt_services.md rename doc/manual/{docs/examples/intro.md => template/examples_intro.md} (100%) create mode 100644 doc/manual/template/gatt_clients_intro.md create mode 100644 doc/manual/template/gatt_services_intro.md rename doc/manual/{docs/ports/intro.md => template/ports_intro.md} (100%) create mode 100755 doc/manual/update_gatt_services.py diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore index 3c9e12c0b..a547622b6 100644 --- a/doc/manual/.gitignore +++ b/doc/manual/.gitignore @@ -4,3 +4,5 @@ docs_final docs_tmp latex mkdocs.yml +api_index.md +tmp diff --git a/doc/manual/Makefile b/doc/manual/Makefile index c5d957e5a..9da66461c 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -36,13 +36,16 @@ update_content: ./update_listings.py # create docs/ports/existing_ports.md ./ports2markdown.py + # create docs/gatt_clients.md and docs/gatt_services.md + ./update_gatt_services.py # re-create docs_final rm -rf docs_final cp -r docs docs_final clean: rm -rf docs_final tmp btstack *.pdf latex/btstack_generated.* latex/btstack_final.tex mkdocs.yml - rm -rf docs/appendix/apis.md docs/appendix/index.md docs/examples/examples.md docs/chipsets.md + rm -rf docs/appendix/apis.md api_index.md docs/examples/examples.md docs/chipsets.md + rm -rf docs/gatt_clients.md docs/gatt_services.md rm -rf latex btstack help diff --git a/doc/manual/docs/.gitignore b/doc/manual/docs/.gitignore new file mode 100644 index 000000000..8a125d638 --- /dev/null +++ b/doc/manual/docs/.gitignore @@ -0,0 +1,2 @@ +gatt_clients.md +gatt_services.md \ No newline at end of file diff --git a/doc/manual/docs/gatt_clients.md b/doc/manual/docs/gatt_clients.md deleted file mode 100644 index de2df55a9..000000000 --- a/doc/manual/docs/gatt_clients.md +++ /dev/null @@ -1,29 +0,0 @@ - -BTstack allows to implement and use GATT Clients in a modular way. - -### Battery Service Client {#sec:BatteryServiceClient}} - -The Battery Service Client connects to the Battery Services of a remote device and queries its battery level values. Level updates are either received via notifications (if supported by the remote Battery Service), or by manual polling. - -See [Battery Service Client API](appendix/apis/#battery-service-client-api). - -### Device Information Service Client {#sec:DeviceInformationServiceClient}} - -The Device Information Service Client retrieves the following information from a remote device: -- manufacturer name -- model number -- serial number -- hardware revision -- firmware revision -- software revision -- system ID -- IEEE regulatory certification -- PNP ID - -See [Device Information Service Client API](appendix/apis/#device-information-service-client-api). - -### Scan Parameters Service Client {#sec:ScanParametersServiceClient}} - -The Scan Parameters Service Client allows to store its LE scan parameters on a remote device such that the remote device can utilize this information to optimize power consumption and/or reconnection latency. - -See [Scan Parameters Service Client API](appendix/apis/#scan-parameters-service-client-api). \ No newline at end of file diff --git a/doc/manual/docs/gatt_services.md b/doc/manual/docs/gatt_services.md deleted file mode 100644 index 19170b99a..000000000 --- a/doc/manual/docs/gatt_services.md +++ /dev/null @@ -1,119 +0,0 @@ - -BTstack allows to implement and use GATT Services in a modular way. - -To use an already implemented GATT Service Server, you only have to add it to your application's -GATT file with: - - - `#import ` for .gatt files located in *src/ble/gatt-service* - - `#import "service_name.gatt"` for .gatt files located in the same folder as your application's .gatt file. - -Each service will have an API at *src/ble/gatt-service/service_name_server.h. To activate it, you need -to call *service_name_init(..)*. Please see the .h file for details. - -### Battery Service Server {#sec:BatteryServiceServer}} - -The Battery Service allows to query your device's battery level in a standardized way. - -To use with your application, add `#import ` to your .gatt file. -After adding it to your .gatt file, you call *battery_service_server_init(value)* with the -current value of your battery. The valid range for the battery level is 0-100. - -If the battery level changes, you can call *battery_service_server_set_battery_value(value)*. The service supports sending Notifications if the client enables them. - -See [Battery Service Server API](appendix/apis/#battery-service-server-api). - -### Cycling Power Service Server {#sec:CyclingPowerServiceServer} - -The Cycling Power Service allows to query device's power- and force-related data and optionally speed- and cadence-related data for use in sports and fitness applications. - -To use with your application, add `#import ` to your .gatt file. - -See [Cycling Power Service Server API](appendix/apis/#cycling-power-service-server-api). - -### Cycling Speed and Cadence Service Server {#sec:CyclingSpeedAndCadenceServiceServer} - -The Cycling Speed and Cadence Service allows to query device's speed- and cadence-related data for use in sports and fitness applications. - -To use with your application, add `#import ` to your .gatt file. - -See [Cycling Speed and Cadence Service Server API](appendix/apis/#cycling-speed-and-cadence-service-server-api). - -### Device Information Service Server {#sec:DeviceInformationServiceServer} - -TheDevice Information Service allows to query manufacturer and/or vendor information about a device. - -To use with your application, add `#import ` to your .gatt file. - -See [Device Information Service Server API](appendix/apis/#device-information-service-server-api). - - -### Heart Rate Service Server {#sec:HeartRateServiceServer}} - -The heart rate service server provides heart rate measurements via notifications. - -Each notification reports the heart rate measurement in beats per minute, and if enabled, -the total energy expended in kilo Joules, as well as RR-intervals in 1/1024 seconds resolution. - -The Energy Expended field represents the accumulated energy expended -in kilo Joules since the last time it was reset. If the maximum value of 65535 -kilo Joules is reached, it will remain at this value, until a reset command -from the client is received. - -The RR-Interval represents the time between two consecutive R waves in -an Electrocardiogram (ECG) waveform. If needed, the RR-Intervals are sent in -multiple notifications. - -To use with your application, add `#import ` to your .gatt file. -After adding it to your .gatt file, you call *heart_rate_server_init(body_sensor_location, energy_expended_supported)* -with the intended sensor location, and a flag indicating if energy expanded is supported. - -If heart rate measurement changes, you can call -*heart_rate_service_server_update_heart_rate_values(heart_rate_bpm, service_sensor_contact_status, rr_interval_count, rr_intervals)*. -This function will trigger sending Notifications if the client enables them. - -If energy expanded is supported, you can call *heart_rate_service_add_energy_expended(energy_expended_kJ)* -with the newly expanded energy. The accumulated energy expended value -will be emitted with the next heart rate measurement. - -See [Heart Rate Service Server API](appendix/apis/#heart-rate-service-server-api). - - -### Mesh Provisioning Service Server {#sec:MeshProvisioningServiceServer} - -The Mesh Provisioning Service allows a Provisioning Client to provision a device to participate in the mesh network. - -To use with your application, add `#import ` to your .gatt file. - -See [Mesh Provisioning Service Server API](appendix/apis/#mesh-provisioning-service-server-api). - -### Mesh Proxy Service Server {#sec:MeshProxyServiceServer} - -The Mesh Proxy Service is used to enable a server to send and receive Proxy PDUs with a client. - -To use with your application, add `#import ` to your .gatt file. - -See [Mesh Proxy Service Server API](appendix/apis/#mesh-proxy-service-server-api). - -### Nordic SPP Service Server {#sec:NordicSPPServiceServer} - -The Nordic SPP Service is implementation of the Nordic SPP-like profile. - -To use with your application, add `#import ` to your .gatt file. - -See [Nordic SPP Service Server API](appendix/apis/#nordic-spp-service-server-api). - -### Scan Parameters Service Server {#sec:ScanParametersServiceServer} - -The Scan Parameters Service enables a remote GATT Client to store the LE scan parameters it is using locally. These parameters can be utilized by the application to optimize power consumption and/or reconnection latency. - -To use with your application, add `#import ` to your .gatt file. - -See [Scan Parameters Service Server API](appendix/apis/#scan-parameters-server-api). - -### u-blox SPP Service Server {#sec:ubloxSPPServiceServer} - -The u-blox SPP Service is implementation of the u-Blox SPP-like profile. - -To use with your application, add `#import ` to your .gatt file. - -See [u-blox SPP Service Server API](appendix/apis/#ublox-spp-service-server-api). \ No newline at end of file diff --git a/doc/manual/docs/ports/.gitignore b/doc/manual/docs/ports/.gitignore index 1c140c202..4d6a648cf 100644 --- a/doc/manual/docs/ports/.gitignore +++ b/doc/manual/docs/ports/.gitignore @@ -22,3 +22,4 @@ stm32-f103rb-nucleo stm32-f4discovery-cc256x stm32-l053r8-em9304 windows-winusb +*.jpg diff --git a/doc/manual/mkdocs-template.yml b/doc/manual/mkdocs-template.yml index e807ddebc..134df5b3b 100644 --- a/doc/manual/mkdocs-template.yml +++ b/doc/manual/mkdocs-template.yml @@ -11,6 +11,7 @@ nav: - 'Protocols': protocols.md - 'Profiles': profiles.md - 'Implemented GATT Services': gatt_services.md +- 'Implemented GATT Clients': gatt_clients.md - 'Examples': examples/examples.md - 'Chipsets': chipsets.md - 'Porting to Other Platforms': porting.md diff --git a/doc/manual/ports2markdown.py b/doc/manual/ports2markdown.py index 6978349f0..311933e55 100755 --- a/doc/manual/ports2markdown.py +++ b/doc/manual/ports2markdown.py @@ -73,11 +73,12 @@ def process_readmes(intro_file, port_folder, ports_file, ports_folder): def main(argv): btstackfolder = "../../" docsfolder = "docs/" + template_folder = "template/" - inputfolder = btstackfolder + "port/" - portsfolder = docsfolder + "ports/" - introfile = portsfolder + "intro.md" - outputfile = portsfolder + "existing_ports.md" + inputfolder = btstackfolder + "port/" + portsfolder = docsfolder + "ports/" + introfile = template_folder + "ports_intro.md" + outputfile = portsfolder + "existing_ports.md" process_readmes(introfile, inputfolder, outputfile, portsfolder) if __name__ == "__main__": diff --git a/doc/manual/docs/examples/intro.md b/doc/manual/template/examples_intro.md similarity index 100% rename from doc/manual/docs/examples/intro.md rename to doc/manual/template/examples_intro.md diff --git a/doc/manual/template/gatt_clients_intro.md b/doc/manual/template/gatt_clients_intro.md new file mode 100644 index 000000000..8429126e6 --- /dev/null +++ b/doc/manual/template/gatt_clients_intro.md @@ -0,0 +1,3 @@ + +BTstack allows to implement and use GATT Clients in a modular way. + diff --git a/doc/manual/template/gatt_services_intro.md b/doc/manual/template/gatt_services_intro.md new file mode 100644 index 000000000..581bd3e27 --- /dev/null +++ b/doc/manual/template/gatt_services_intro.md @@ -0,0 +1,10 @@ + +BTstack allows to implement and use GATT Services in a modular way. + +To use an already implemented GATT Service Server, you only have to add it to your application's GATT file with: + - `#import ` for .gatt files located in *src/ble/gatt-service* + - `#import "service_name.gatt"` for .gatt files located in the same folder as your application's .gatt file. + +Each service will have an API at *src/ble/gatt-service/service_name_server.h*. To activate it, you need to call *service_name_init(..)*. + +Please see the .h file for details. diff --git a/doc/manual/docs/ports/intro.md b/doc/manual/template/ports_intro.md similarity index 100% rename from doc/manual/docs/ports/intro.md rename to doc/manual/template/ports_intro.md diff --git a/doc/manual/update_apis.py b/doc/manual/update_apis.py index 6a222c5e8..ab2cc6bb4 100755 --- a/doc/manual/update_apis.py +++ b/doc/manual/update_apis.py @@ -221,7 +221,7 @@ def main(argv): docsfolder = "docs/" apifile = docsfolder + "appendix/apis.md" - indexfile = docsfolder + "appendix/index.md" + indexfile = "api_index.md" cmd = 'update_apis.py [-b ] [-a ] [-g ] [-i ]' try: diff --git a/doc/manual/update_gatt_services.py b/doc/manual/update_gatt_services.py new file mode 100755 index 000000000..e8ef5010e --- /dev/null +++ b/doc/manual/update_gatt_services.py @@ -0,0 +1,155 @@ +#!/usr/bin/env python3 +import os, sys, getopt, re +import subprocess + +class State: + SearchIntro = 0 + IntroFound = 1 + SearchAPI = 2 + +btstack_root = os.path.abspath(os.path.dirname(sys.argv[0]) + '/../../') +inputfolder = btstack_root + "/src/ble/gatt-service/" + +manual_folder = btstack_root + "/doc/manual/" +docsfolder = manual_folder + "docs/" +template_folder = manual_folder + "template/" + +mdfiles = { + # source file sufix : docu file, [white list od source files] + "_server.h" : ["gatt_services.md", ["hids_device.h"]], + "_client.h" : ["gatt_clients.md", []] +} + +abrevations = { + "Ancs" : "ANCS", + "Hids" : "HIDS", + "Ublox": "u-blox", + "Spp" : "SPP", + "And" : "and" +} + +description_template = """ +### NAME {#sec:REFERENCE} + +""" + +description_api = """ + +See [NAME API](appendix/apis/#REFERENCE). + +""" + +def isEmptyCommentLine(line): + return re.match('(\s*\*\s*)\n',line) + +def isCommentLine(line): + return re.match('(\s*\*\s*).*',line) + +def isEndOfComment(line): + return re.match('\s*\*/.*', line) + +def isNewItem(line): + return re.match('(\s*\*\s*\-\s*)(.*)',line) + +def isTextTag(line): + return re.match('.*(@text).*', line) + +def isItemizeTag(line): + return re.match("(\s+\*\s+)(-\s)(.*)", line) + +def processTextLine(line): + if isEmptyCommentLine(line): + return "\n\n" + + line.rstrip() + + if isTextTag(line): + text_line_parts = re.match(".*(@text\s*)(.*)", line) + return text_line_parts.group(2).lstrip() + " " + + if isItemizeTag(line): + text_line_parts = re.match("(\s*\*\s*\-\s*)(.*)", line) + return "- " + text_line_parts.group(2) + + if isEmptyCommentLine(line): + return "\n" + + text_line_parts = re.match("(\s+\*\s+)(.*)", line) + if text_line_parts: + return text_line_parts.group(2) + " " + return "" + +def handle_abrevations(basename): + name_parts = [item.capitalize() for item in basename.split("_")] + for i in range(len(name_parts)): + try: + name_parts[i] = abrevations[name_parts[i]] + except KeyError: + continue + + return " ".join(name_parts) + + +def process_file(basename, inputfile_path, outputfile_path): + reference = basename.replace("_", "-") + name = handle_abrevations(basename) + + title = description_template.replace("NAME", name).replace("REFERENCE", reference) + api = description_api.replace("NAME", name).replace("REFERENCE", reference) + + text_block = "" + with open(inputfile_path, 'r') as fin: + state = State.SearchIntro + for line in fin: + if state == State.SearchIntro: + if isTextTag(line): + state = State.IntroFound + text_block = text_block + processTextLine(line) + continue + + if state == State.IntroFound: + text_block = text_block + processTextLine(line) + + if isEndOfComment(line): + state = State.SearchIntro + fin.close() + + with open(outputfile_path, 'a+') as fout: + fout.write(title) + fout.write(text_block) + fout.write(api) + fout.close() + +def main(argv): + for source_filename_sufix, [outputfile, white_list] in mdfiles.items(): + outputfile_path = docsfolder + outputfile + introfile_path = template_folder + outputfile[:-3] + "_intro.md" + print('Code folder: ', inputfolder) + print('Intro file: ', introfile_path) + print('Output file: ', outputfile_path) + + with open(outputfile_path, 'w') as fout: + with open(introfile_path, 'r') as fin: + for line in fin: + fout.write(line) + + fin.close() + fout.close() + + files_to_process = [] + for root, dirs, files in os.walk(inputfolder, topdown=True): + for f in files: + if not f.endswith(source_filename_sufix): + if f not in white_list: + continue + files_to_process.append(root + "/"+ f) + + files_to_process.sort() + + for inputfile_path in files_to_process: + basename = os.path.basename(inputfile_path)[:-2] + process_file(basename, inputfile_path, outputfile_path) + + +if __name__ == "__main__": + main(sys.argv[1:]) diff --git a/doc/manual/update_listings.py b/doc/manual/update_listings.py index a8ceb78b3..bd5ef698f 100755 --- a/doc/manual/update_listings.py +++ b/doc/manual/update_listings.py @@ -341,10 +341,11 @@ def processExamples(intro_file, examples_folder, examples_ofile, git_branch_name def main(argv): btstackfolder = "../../" docsfolder = "docs/" + template_folder = "template/" git_branch_name = "master" inputfolder = btstackfolder + "example/" - introfile = docsfolder + "examples/intro.md" + introfile = template_folder + "examples_intro.md" outputfile = docsfolder + "examples/examples.md" cmd = 'update_listings.py [-f ] [-i ] [-o ]' @@ -363,9 +364,9 @@ def main(argv): introfile = arg elif opt in ("-o", "--ofile"): outputfile = arg - print ('Input folder is : ', inputfolder) - print ('Intro file is : ', introfile) - print ('Output file is : ', outputfile) + print ('Input folder: ', inputfolder) + print ('Intro file: ', introfile) + print ('Output file: ', outputfile) try: output = subprocess.check_output("git symbolic-ref --short HEAD", stderr=subprocess.STDOUT, timeout=3, shell=True) diff --git a/src/ble/gatt-service/ancs_client.h b/src/ble/gatt-service/ancs_client.h index 6290b1887..1798c4144 100644 --- a/src/ble/gatt-service/ancs_client.h +++ b/src/ble/gatt-service/ancs_client.h @@ -38,13 +38,18 @@ #ifndef ANCS_CLIENT_H #define ANCS_CLIENT_H + +#include +#include "btstack_defines.h" + #if defined __cplusplus extern "C" { #endif -#include -#include "btstack_defines.h" - +/** + * @text The ANCS Client implements Notification Consumer (NC) of the [Apple Notification Center Service (ANCS)](https://developer.apple.com/library/archive/documentation/CoreBluetooth/Reference/AppleNotificationCenterServiceSpecification/Introduction/Introduction.html). + */ + /* API_START */ void ancs_client_init(void); diff --git a/src/ble/gatt-service/battery_service_client.h b/src/ble/gatt-service/battery_service_client.h index f64a4d4c7..2dcdc40c1 100644 --- a/src/ble/gatt-service/battery_service_client.h +++ b/src/ble/gatt-service/battery_service_client.h @@ -44,11 +44,16 @@ #include "btstack_linked_list.h" #include "ble/gatt_client.h" - #if defined __cplusplus extern "C" { #endif +/** + * @text The Battery Service Client connects to the Battery Services of a remote device + * and queries its battery level values. Level updates are either received via notifications + * (if supported by the remote Battery Service), or by manual polling. + */ + #ifndef MAX_NUM_BATTERY_SERVICES #define MAX_NUM_BATTERY_SERVICES 3 #endif diff --git a/src/ble/gatt-service/battery_service_server.h b/src/ble/gatt-service/battery_service_server.h index d5825125e..74c0ea2c0 100644 --- a/src/ble/gatt-service/battery_service_server.h +++ b/src/ble/gatt-service/battery_service_server.h @@ -44,8 +44,14 @@ extern "C" { #endif /** - * Implementation of the GATT Battery Service Server - * To use with your application, add '#import ` to your .gatt file. + * After adding it to your .gatt file, you call *battery_service_server_init(value)* with the + * current value of your battery. The valid range for the battery level is 0-100. + * + * If the battery level changes, you can call *battery_service_server_set_battery_value(value)*. + * The service supports sending Notifications if the client enables them. */ /* API_START */ diff --git a/src/ble/gatt-service/cycling_power_service_server.h b/src/ble/gatt-service/cycling_power_service_server.h index 9d39b55a1..5126e37ad 100644 --- a/src/ble/gatt-service/cycling_power_service_server.h +++ b/src/ble/gatt-service/cycling_power_service_server.h @@ -44,15 +44,13 @@ extern "C" { #endif /** - * Implementation of the GATT Cycling Power Service Server - */ - -// ***************************************************************************** -/* GATT_SERVICE_SERVER_START(cycling_power_service_server){Cycling PowerService} + * @text The Cycling Power Service allows to query device's power- and + * force-related data and optionally speed- and cadence-related data for + * use in sports and fitness applications. * + * To use with your application, add `#import ` + * to your .gatt file. */ -// ***************************************************************************** -/* GATT_SERVICE_SERVER_END */ /* API_START */ #define CYCLING_POWER_MANUFACTURER_SPECIFIC_DATA_MAX_SIZE 16 diff --git a/src/ble/gatt-service/cycling_speed_and_cadence_service_server.h b/src/ble/gatt-service/cycling_speed_and_cadence_service_server.h index badb4b130..897ce6a07 100644 --- a/src/ble/gatt-service/cycling_speed_and_cadence_service_server.h +++ b/src/ble/gatt-service/cycling_speed_and_cadence_service_server.h @@ -44,15 +44,13 @@ extern "C" { #endif /** - * Implementation of the GATT Cycling Speed and Cadence Service Server - */ - -// ***************************************************************************** -/* GATT_SERVICE_SERVER_START(cycling_speed_and_cadence_service_server){Cycling Speed and Cadence Service} + * @text The Cycling Speed and Cadence Service allows to query + * device's speed- and cadence-related data for use in sports and + * fitness applications. * + * To use with your application, add `#import ` + * to your .gatt file. */ -// ***************************************************************************** -/* GATT_SERVICE_SERVER_END */ /* API_START */ diff --git a/src/ble/gatt-service/device_information_service_client.h b/src/ble/gatt-service/device_information_service_client.h index c5d4a199c..d9fc60e7d 100644 --- a/src/ble/gatt-service/device_information_service_client.h +++ b/src/ble/gatt-service/device_information_service_client.h @@ -43,11 +43,23 @@ #include "bluetooth.h" #include "ble/gatt_client.h" - #if defined __cplusplus extern "C" { #endif +/** + * @text The Device Information Service Client retrieves the following information from a remote device: + * - manufacturer name + * - model number + * - serial number + * - hardware revision + * - firmware revision + * - software revision + * - system ID + * - IEEE regulatory certification + * - PNP ID + */ + /* API_START */ /** diff --git a/src/ble/gatt-service/device_information_service_server.h b/src/ble/gatt-service/device_information_service_server.h index ebb9981f4..72ffa1904 100644 --- a/src/ble/gatt-service/device_information_service_server.h +++ b/src/ble/gatt-service/device_information_service_server.h @@ -46,13 +46,13 @@ extern "C" { /* API_START */ /** - * Implementation of the Device Information Service Server + * @text Th eDevice Information Service allows to query manufacturer and/or + * vendor information about a device. + * + * To use with your application, add `#import ` to your .gatt file. * - * To use with your application, add '#import ` to your .gatt file. * After adding it to your .gatt file, you call *heart_rate_server_init(body_sensor_location, energy_expended_supported)* * with the intended sensor location, and a flag indicating if energy expanded is supported. - * + * * If heart rate measurement changes, you can call * *heart_rate_service_server_update_heart_rate_values(heart_rate_bpm, service_sensor_contact_status, rr_interval_count, rr_intervals)*. * This function will trigger sending Notifications if the client enables them. @@ -76,10 +69,7 @@ extern "C" { * If energy expanded is supported, you can call *heart_rate_service_add_energy_expended(energy_expended_kJ)* * with the newly expanded energy. The accumulated energy expended value * will be emitted with the next heart rate measurement. - * */ -// ***************************************************************************** -/* GATT_SERVICE_SERVER_END */ /* API_START */ diff --git a/src/ble/gatt-service/hids_client.h b/src/ble/gatt-service/hids_client.h index cb80a375c..e03ac5e4f 100644 --- a/src/ble/gatt-service/hids_client.h +++ b/src/ble/gatt-service/hids_client.h @@ -38,10 +38,6 @@ #ifndef HIDS_CLIENT_H #define HIDS_CLIENT_H -#if defined __cplusplus -extern "C" { -#endif - #include #include "btstack_defines.h" #include "btstack_hid.h" @@ -49,6 +45,14 @@ extern "C" { #include "btstack_linked_list.h" #include "ble/gatt_client.h" +#if defined __cplusplus +extern "C" { +#endif + +/** + * @text The HID Service Client is used on the HID Host to receive reports and other HID data. + */ + #ifndef MAX_NUM_HID_SERVICES #define MAX_NUM_HID_SERVICES 3 #endif diff --git a/src/ble/gatt-service/hids_device.h b/src/ble/gatt-service/hids_device.h index e2b0b8eb0..0f29729fe 100644 --- a/src/ble/gatt-service/hids_device.h +++ b/src/ble/gatt-service/hids_device.h @@ -46,7 +46,7 @@ extern "C" { #endif /** - * Implementation of the GATT HIDS Device + * @text Implementation of the GATT HIDS Device * To use with your application, add '#import ' to your .gatt file */ diff --git a/src/ble/gatt-service/mesh_provisioning_service_server.h b/src/ble/gatt-service/mesh_provisioning_service_server.h index 4276dacff..e48f45d97 100644 --- a/src/ble/gatt-service/mesh_provisioning_service_server.h +++ b/src/ble/gatt-service/mesh_provisioning_service_server.h @@ -46,7 +46,9 @@ extern "C" { #endif /** - * Implementation of the Mesh Provisioning Service Server + * @text The Mesh Provisioning Service allows a Provisioning Client to provision a device to participate in the mesh network. + * + * To use with your application, add `#import ` to your .gatt file. */ /* API_START */ diff --git a/src/ble/gatt-service/mesh_proxy_service_server.h b/src/ble/gatt-service/mesh_proxy_service_server.h index 43763069b..8a334e5d8 100644 --- a/src/ble/gatt-service/mesh_proxy_service_server.h +++ b/src/ble/gatt-service/mesh_proxy_service_server.h @@ -46,7 +46,9 @@ extern "C" { #endif /** - * Implementation of the Mesh Proxy Service Server + * @text The Mesh Proxy Service is used to enable a server to send and receive Proxy PDUs with a client. + * + * To use with your application, add `#import ` to your .gatt file. */ /* API_START */ diff --git a/src/ble/gatt-service/nordic_spp_service_server.h b/src/ble/gatt-service/nordic_spp_service_server.h index 99ed9c4ec..42feb8350 100644 --- a/src/ble/gatt-service/nordic_spp_service_server.h +++ b/src/ble/gatt-service/nordic_spp_service_server.h @@ -48,9 +48,9 @@ extern "C" { /* API_START */ /** - * Implementation of the Nordic SPP-like profile + * @text The Nordic SPP Service is implementation of the Nordic SPP-like profile. * - * To use with your application, add '#import