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 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/reassembly process if the attribute value to be transported cannot 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 updates are sent via notifications (no confirmation from client) or indications (client confirms receipt). This mechanism minimises 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
 

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 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, and this handle should be used to subsequently 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
+
+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.
+
+If a client has subscribed to a given characteristic's value update, then the application code can query 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 for a characteristic.
+- `onUpdatesDisabled`: Register an event handler that is called when a client unsubscribes from updates for 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