Merge branch 'development' into fix_remove_rollup

Author: Amanda Butler

docs.json

@@ -1,19 +1,19 @@
-# BatteryService
+## BatteryService
 
 It is often a requirement for devices operating on battery to report the battery charge level to the user.
 
 The [Bluetooth Battery Service](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245138) defines how to expose a battery charge level through a BLE link. It allows a client - usually a smartphone application - of a device to read the current battery charge level and follow its evolution.
 
 The BatteryService class implements the Bluetooth Battery Service as defined by the Bluetooth SIG. Makers of BLE devices operating on battery can use the API to expose interoperably the charge level of their products.
 
-## BatteryService class reference
+### BatteryService class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/class_battery_service.html)
 
-## BatteryService example
+### BatteryService example
 
 [![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-ble/blob/master/BLE_BatteryLevel/source)](https://github.com/ARMmbed/mbed-os-example-ble/blob/mbed-os-5.14/BLE_BatteryLevel/source/main.cpp)
 
-## Related content
+### Related content
 
 - [Bluetooth Battery Service](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245138) specification.

docs/api/bluetooth/BatteryService.md

@@ -1,11 +1,11 @@
-# EnvironmentalService
+## EnvironmentalService
 
 [Add description here.]
 
-## EnvironmentalService class reference
+### EnvironmentalService class reference
 
 [![View code](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_environmental_service.html)
 
-## EnvironmentalService example
+### EnvironmentalService example
 
 [Add example here.]

docs/api/bluetooth/EnvironmentalService.md

@@ -1,4 +1,4 @@
-# GAP
+## GAP
 
 <span class="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
 
@@ -12,19 +12,19 @@ The other side of the process is the act of scanning, which listens for advertis
 
 Advertising, scanning and connection all have parameters that let you find a compromise between desired power consumption levels, latency and efficiency of these processes.
 
-## Advertising
+### Advertising
 
 Advertising consists of broadcasting at a regular interval a small amount of data containing valuable information about the device. Peer devices listening on BLE advertising channels may scan these packets.
 
 Scanners may also request additional information from device advertising by sending a scan request. If the broadcaster accepts scan requests, it can reply with a scan response packet containing additional information.
 
-## Scanning
+### Scanning
 
 Scanning consists of listening for peer advertising packets. From a scan, a device can identify devices available in its environment.
 
 If the device scans actively, it sends scan request to scannable advertisers and collects their scan responses.
 
-## Extended and periodic advertising
+### Extended and periodic advertising
 
 BLE controllers supporting Bluetooth 5.0 may offer additional advertising and scanning options. Use `isFeatureSupported()` to check feature availability.
 
@@ -36,13 +36,13 @@ There may be many advertising sets active at one time on a single advertiser. Th
 
 Devices that do not support extended and periodic advertising will not see these advertisements. You may use legacy advertising alongside extended advertising, running at the same time, to support older devices in the environment.
 
-## Privacy
+### Privacy
 
 Privacy is a feature that allows a device to avoid being tracked by other (untrusted) devices. The device achieves it by periodically generating a new random address. The random address may be a resolvable random address, enabling trusted devices to recognize it as belonging to the same device. These trusted devices receive an Identity Resolution Key (IRK) during pairing. The SecurityManager handles this and relies on the other device accepting and storing the IRK.
 
 You need to enable privacy by calling `enablePrivacy()` after initializing the SecurityManager because privacy requires SecurityManager to handle IRKs. Set the behavior of privacy enabled devices by using `setCentralPrivacyConfiguration()`, which specifies what the device should be with devices using random addresses, and `setPeripheralPrivacyConfiguration`. Random addresses that privacy enabled devices generate can be of two types: resolvable (by devices who have the IRK) and unresolvable. You can't use unresolvable addresses for connecting and connectable advertising; therefore, use a resolvable one for these, regardless of the privacy configuration.
 
-## Modulation schemes
+### Modulation schemes
 
 When supported by the host and controller, you can select different modulation schemes:
 
@@ -56,7 +56,7 @@ You may set preferred PHYs (separately for RX and TX) using `setPreferredPhys()`
 
 You may query the currently used PHY using `readPhy()`, which returns the result through a call to the registered event handler. You may register the handler with `setEventHandler()`. The events inform about the currently used PHY and of any changes to PHYs, which the controller or the peer may trigger autonomously.
 
-## Data length (over-the-air MTU)
+### Data length (over-the-air MTU)
 
 In addition to modulation schemes, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.
 
@@ -66,11 +66,11 @@ The default value of data length supported by all controllers is 23 octets. If b
 
 `ATT_MTU` and data length are independent of each other.
 
-## GAP class reference
+### GAP class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gap.html)
 
-## GAP example
+### GAP example
 
 Here is an example demonstrating how to use the GAP API to advertise, scan, connect and disconnect and how parameters influence efficiency of these actions.
 

docs/api/bluetooth/Gap.md

@@ -1,24 +1,24 @@
-# GattClient
+## GattClient
 
 <span class="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
 
 You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction. `GattClient` defines procedures required for interacting with a remote `GattServer`.
 
-## Discovery procedures
+### Discovery procedures
 
 A GattServer hosts a fixed set of services. These services are a logical composition of characteristics that may be discovered, read or written and can broadcast their state to a connected client. These characteristics may also contain metainformation and named characteristic descriptors. A characteristic descriptor may indicate the unit used for a characteristic value, describe the characteristic purpose in a textual form or allow a client to register for update notifications for the characteristic value.
 
 Prior to any interaction with a server characteristic, a GattClient discovers the layout of the services and characteristics present on the server.
 
 The layout of the descriptors of a characteristic may also be issued as an extra discovery step.
 
-## Attribute manipulation
+### Attribute manipulation
 
 As a result of the discovery process, the client can start interacting with the characteristic discovered. Depending on the characteristic properties (acquired during discovery), a client can read or write the value of a given characteristic.
 
 Mbed BLE abstracts read and write operations to offer a single API that can be used to read or write characteristic values. The application code does not have to handle the necessary fragmentation or reassembly process if the attribute value to be transported can't fit in a single data packet.
 
-## Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
 
 `ATT_MTU` is the maximum size of the attribute protocol packet. Operation on attributes too large to fit into a single packet are split across multiple operations.
 
@@ -28,16 +28,16 @@ Only `GattClient` can trigger the exchange of `ATT_MTU` between client and serve
 
 `ATT_MTU` is at least 23 octets by default. If a larger size is negotiated, the user application will be informed through the `onAttMtuChange` function called in the `GattClient::EventHandler`. (`GattServer::EventHandler` is also informed.)
 
-## Server initiated events
+### Server initiated events
 
 When a server updates a characteristic value, it can forward the new value to any registered clients. Clients may register for these updates on a per-characteristic basis. The server sends the updates by using notifications (no confirmation from client) or indications (client confirms receipt). This mechanism minimizes the number of transactions between a client and a server by avoiding polling.
 
 Clients register for these updates by setting the Client Characteristic Configuration Descriptor (CCCD) value. This is an attribute, and the client needs to discover its descriptor. It is present in the characteristic if its notify or indicate properties are set.
 
-## GattClient class reference
+### GattClient class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gatt_client.html)
 
-## GattClient example
+### GattClient example
 
 [![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattClient/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattClient/file/38639a71a0f1/source/main.cpp)

docs/api/bluetooth/GattClient.md

@@ -1,28 +1,28 @@
-# GattServer
+## GattServer
 
 <span class="notes">**Note:** Some functions, variables or types have been deprecated. Please see the class reference linked below for details.</span>
 
 You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction.
 
 `GattServer` is a collection of GattServices. These services contain characteristics that a `GattClient` on the peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
 
-## Server layout
+### Server layout
 
 Application code can add a GattService object to the server with the help of the function `addService()`. That function registers all the GattCharacteristics enclosed in the service, as well as all the characteristic descriptors (see GattAttribute) that these characteristics contain. Service registration assigns a unique handle to the various attributes that are part of the service. The user must use this handle to read or write these components.
 
 There are no defined primitives that remove a single service; however, a call to the function `reset()` removes all services previously registered in the GattServer.
 
-## Characteristic and attributes access
+### Characteristic and attributes access
 
 You must access values of the characteristic and the characteristic descriptor present in the GattServer through the handle assigned to them when you registered the service. The GattServer class offers several types of `read()` and `write()` functions that retrieve or mutate an attribute value.
 
 You can query the server by invoking the function `areUpdatesEnabled()` to find out if a client has subscribed to a given characteristic's value update.
 
-## Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
 
 The Attribute Protocol Maximum Transmission Unit (`ATT_MTU`) is the maximum size of the attribute protocol packet. For details, please see the [GattClient Documentation](../apis/gattclient.html).
 
-## Events
+### Events
 
 You can register several event handlers with the GattServer that it will call to notify you of client (remote application connected to the server) and server activities:
 
@@ -35,10 +35,10 @@ You can register several event handlers with the GattServer that it will call to
 
 The term characteristic value update represents Characteristic Value Notification and Characteristic Value Indication when the nature of the server initiated is not relevant.
 
-## GattServer class reference
+### GattServer class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gatt_server.html)
 
-## GattServer example
+### GattServer example
 
 [![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-GattServer/file/622c672f6d5f/source/main.cpp)

docs/api/bluetooth/GattServer.md

@@ -1,4 +1,4 @@
-# HeartRateService
+## HeartRateService
 
 People practicing physical activities use heart rate monitors to track their pulse in real time and improve their physical performances.
 
@@ -8,15 +8,15 @@ The HeartRateService class implements the Bluetooth Heart Rate service as define
 
 <span class="note"> **Note:** The Bluetooth Heart Rate Service is part of the [Bluetooth Heart Rate Profile](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=239865), which defines behaviors that a Bluetooth heart rate sensor expects. You must ensure that your application conforms to the heart rate profile to guarantee interoperability of your heart rate sensors.</span>
 
-## HeartRateService class reference
+### HeartRateService class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/class_heart_rate_service.html)
 
-## HeartRateService example
+### HeartRateService example
 
 [![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-example-ble/blob/master/BLE_HeartRate/source)](https://github.com/ARMmbed/mbed-os-example-ble/blob/mbed-os-5.14/BLE_HeartRate/source/main.cpp)
 
-## Related content
+### Related content
 
 - [Bluetooth Heart Rate Service](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=239866) specification.
 - [Bluetooth Heart Rate Profile](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=239865) specification.

docs/api/bluetooth/HeartRateService.md

@@ -1,4 +1,4 @@
-# SecurityManager
+## SecurityManager
 
 SecurityManager deals with authentication and encryption for the Bluetooth Low Energy link. The pairing and optionally bonding processes provide this. The SecurityManager achieves bonding by saving the pairing information and reusing it on subsequent reconnections. This saves time because the pairing does not have to be performed again.
 
@@ -10,27 +10,27 @@ The SecurityManager stores the keys, permanently if possible, to speed security
 
 Security requests may come explicitly from the user application or implicitly from the GATT server based on attribute requirements.
 
-## Pairing
+### Pairing
 
 There are several ways to provide different levels of security during pairing depending on your requirements and the facilities the application provides. The process starts with initializing the SecurityManager with default options for new connections. You can later change some settings per link or globally.
 
 The important settings in the `init()` function are the MITM requirement and IO capabilities. MITM protection prevents an attack where one device can impersonate another device by pairing with both devices at the same time. You can achieve this protection by sharing information between the devices through an independent channel. The IO capabilities of both devices dictate what algorithm is used. For details, see BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.3.5.1. You can change the IO capabilities after initialization with `setIoCapability()`. This takes effect for all subsequent pairings.
 
 Secure Connections, which relies on elliptical curve cryptography, provides the most secure pairing. Support for Secure Connections depends on both the stack and controller on both sides supporting it. If either side doesn't support it, legacy pairing is used. This is an older standard of pairing. If you require higher security, you can disable legacy pairing by calling `allowLegacyPairing(false);`.
 
-## Out of band (OOB) data used in pairing
+### Out of band (OOB) data used in pairing
 
 Sharing this information through IO capabilities means user interaction, which limits the degree of protection due to the limit of the amount of data that you can expect to transfer. Another solution is using out of band (OOB) communication to transfer this data. OOB communication can send more data and make MITM attacks less likely to succeed. The application must exchange OOB data and provide it to the SecurityManager. Use `setOOBDataUsage()` to indicate you want to use it. With this same call, you can set whether the communication channel you are using to transmit the OOB data is itself secure against MITM protection - this sets the level of the link security achieved using pairing that uses this data.
 
-## Signing
+### Signing
 
 Applications may require a level of security providing confidence that data transfers are coming from a trusted source. You can achieve this by encrypting the link, which also provides added confidentiality. Encryption is a good choice when a device stays connected but introduces latency due to the need for encrypting the link if the device only connects periodically to transfer data. If you do not require confidentiality, the GATT server may allow writes to happen over an unencrypted link but authenticated by a signature present in each packet. This signature relies on having sent a signing key to the peer during pairing prior to sending any signed packets.
 
-## Persistence of security information
+### Persistence of security information
 
 SecurityManager stores all the data required for its operation on active links. Depending on resources available on the device, it also stores data for disconnected devices, which have bonded to be reused when reconnected. If the application has initialized a file system and the SecurityManager has received a file path during the `init()` call, SecurityManager may also provide data persistence across resets. You must enable this by calling `preserveBondingStateOnReset()`. Persistence may fail if abnormally terminated. SecurityManager may also fall back to a nonpersistent implementation if the resources are too limited.
 
-## How to use
+### How to use
 
 Call `init()` with your chosen settings before calling any other SecurityManager functions.
 
@@ -44,11 +44,11 @@ The chosen pairing algorithms depend on the IO capabilities and OOB use settings
 
 The simplest example is a pairing of a device with no IO capabilities and no OOB data available. This does not provide any MITM protection. The pairing (triggered implicitly or called explicitly) results in the generation of an event on the peer calling `pairingRequest()`. The event handler must make a decision (either in the application itself or based on user interaction) whether to accept the pairing and call `acceptPairing()` or `cancelPairing()`. An event calling `pairingResult()` in the EventHandler communicates te result on both peers.
 
-## SecurityManager class reference
+### SecurityManager class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_security_manager.html)
 
-## SecurityManager example
+### SecurityManager example
 
 The SecurityManager example demonstrates both a central and a peripheral connecting, performing basic pairing and setting up link security.