Merge pull request #555 from paul-szczepanek-arm/new_engine

Gatt server and client docs

Author: Amanda Butler

docs/reference/api/connectivity/bluetooth/Gap.md

@@ -26,6 +26,19 @@ Privacy is a feature that allows a device to avoid being tracked by other (untru
 
 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
+ 
+ When supported by the host and controller you can select different modulation schemes:
+ - LE 1M PHY
+ - LE 2M PHY
+ - LE coded PHY
+ 
+ These provide different compromises between bandwidth, power usage and error resiliency (see BLUETOOTH SPECIFICATION Version 5.0 Vol 1, Part A - 1.2).
+ 
+ You may set preferred PHYs (separately for RX and TX) using `setPreferredPhys()`. You may also set the currently used PHYs on a selected connection using `setPhy()`. Both of these settings are only advisory and the controller is allowed to make its own decision on the best PHY to use based on your request, the peer's supported features and the connection's physical conditions.
+ 
+ You may query the currently used PHY using `readPhy()` which will return 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 may be triggered autonomously by the controller or by the peer.
+ 
 ### GAP class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_gap.html)

docs/reference/api/connectivity/bluetooth/GattClient.md

@@ -1,11 +1,31 @@
 ## GattClient
 
-[Add description here.]
+GattClient defines procedures required for interacting with a remote GattServer.
+
+#### 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
+
+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.
+
+#### 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
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_gatt_client.html)
 
 ### GattClient example
 
-[Add example here.]
+[![View code](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/71d7cec222eb/main.cpp)

docs/reference/api/connectivity/bluetooth/GattServer.md

@@ -1,11 +1,36 @@
 ## GattServer
 
-[Add description here.]
+A GattServer is a collection of GattServices. These services contain characteristics that a peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
+
+#### 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
+
+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.
+
+#### 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:
+
+- `onDataSent`: Register an event handler with the GattServer that it will call to notify you when it sends a characteristic value update to a client.
+- `onDataWriten`: Register an event handler with the GattServer that it will call to notify you when a client has written an attribute of the server.
+- `onDataRead`: Register an event handler with the GattServer that it will call to notify you when a client has read an attribute of the server.
+- `onUpdatesEnabled`: Register an event handler with the GattServer that it will call to notify you when a client subscribes to updates for a characteristic.
+- `onUpdatesDisabled`: Register an event handler with the GattServer that it will call to notify you when a client unsubscribes from updates for a characteristic.
+- `onConfimationReceived`: Register an event handler with the GattServer that it will call to notify you when a client acknowledges a characteristic value notification.
+
+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
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_gatt_server.html)
 
 ### GattServer example
 
-[Add example here.]
+[![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/8fbed496a023/main.cpp)