Gatt server and client docs

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

@@ -1,6 +1,26 @@
 ## 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 most read and write operations to offer a single API that can be used to read or write characteristics values. Application code does not have to handle the fragmentation/reassembly process necessary if the attribute value to transported cannot fit in a single data packet.
+
+#### Server Initiated events
+
+If a characteristic has to notify or indicate a property set; then, a client may register to a notification or indication from the characteristic. When the server updates the characteristic value, the server can forward the new value to the registered clients. The notification/indication mechanism prevents polling from the client and therefore minimise the transactions involved between a client and a server.
+
+Registration is made by writing the Client Characteristic Configuration Descriptor, which is present in the characteristic if the notify or indicate properties are set. The client discovers that descriptor if it intends to register to server initiated events.
 
 ### GattClient class reference
 

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

@@ -1,6 +1,30 @@
 ## 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 GattCharacteristic enclosed in the service, as well as all the characteristics descriptors (see GattAttribute) these characteristics contain. Service registration assigns a unique handle to the various attributes being part of the service; this handle should be used for subsequent read or write of these components.
+
+There are no primitives defined to remove a single service; however, a call to the function `reset()` removes all services previously registered in the GattServer.
+
+#### Characteristic and attributes access
+
+Values of the characteristic and the characteristic descriptor present in the GattServer must be accessed through the handle assigned to them when the service has been registered; the GattServer class offers several flavours of `read()` and `write()` functions that retrieve or mutate an attribute value.
+
+Application code can query if a client has subscribed to a given characteristic's value update by invoking the function `areUpdatesEnabled()`.
+
+#### Events
+
+The GattServer allows application code to register several event handlers that can be used to monitor client and server activities:
+- `onDataSent`: Register an event handler that is called when a characteristic value update has been sent to a client.
+- `onDataWriten`: Register an event handler that is called when a client has written an attribute of the server.
+- `onDataRead`: Register an event handler that is called when a client has read an attribute of the server.
+- `onUpdatesEnabled`: Register an event handler that is called when a client subscribes to updates of a characteristic.
+- `onUpdatesDisabled`: Register an event handler that is called when a client unsubscribes from updates of a characteristic.
+- `onConfimationReceived`: Register an event handler that is called when a client acknowledges a characteristic value notification.
+
+The term characteristic value update is used to represent Characteristic Value Notification and Characteristic Value Indication when the nature of the server initiated is not relevant.
 
 ### GattServer class reference