Gatt server and client docs #555
Conversation
|
Can't seem to be able to add anyone as reviewer :/ |
|
I can add people. Who should review this? |
|
thanks, https://jira.arm.com/browse/IOTMORF-1315 says we should add sg- |
|
@jen3andruska Could you please do an initial copy edit of these two files on Monday morning? |
|
|
||
| #### Discovery procedures | ||
|
|
||
| A GattServer hosts a fixed set of services. These services are a logical composition of characteristics that may be discovered, read, written or also broadcast their state to a connected client. These characteristics may also contain metainformation named characteristic descriptors. A characteristic descriptor may be used to indicate the unit used for a characteristic value, describe in a textual form the characteristic purpose or allow a client to register for notification of updates of the characteristic value. |
There was a problem hiding this comment.
The switch from the passive to active voice in the 2nd sentence is confusing ("may be discovered, read, written" (passive) and "broadcast their state" (active).) Maybe break up the tenses with a conjunction: "These services are a logical composition of characteristics that may be discovered, read or written, and can broadcast their state to a connect client."
Conunction missing between 'metainformation' and 'named characteristic descriptors.' (3rd sentence)
"Used" is repetitive in the beginning of the 4th sentence
|
|
||
| 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. |
There was a problem hiding this comment.
I don't understand what 'most' is doing in this 1st sentence (so deleted). 'read and write' is repetitive, but I am also confused about the overall meaning of the sentence. I'm assuming you means that the abstracts read/write operations, and that these operations offer a single API?
2nd sentence: "attribute value to transported" something is wrong here. Is it the attribute value to be transported (that will be transported)?
|
|
||
| A characteristic can notify or indicate a property set, and a client may register to this notification or indication from the characteristic. When the server updates the characteristic value, the server can also forward the new value to the registered clients. The notification/indication mechanism prevents polling from the client, and therefore, minimizes the transactions 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. |
There was a problem hiding this comment.
Clarification needed on this 1st sentence. At present, it sounds like 'writing to' the client characteristic configuration descriptor' (also why capitals here?), or do you mean writing the descriptor itself? And if so, writing it where? The 2nd sentence is more confusing. It sounds like you're trying to say that if the notify/indicate properties are set, then this descriptor is present in the characteristic, and the client can find this descriptor and use it to register by writing something somewhere. Please clarify and I can restructure the sentences a bit.
There was a problem hiding this comment.
It's capitalised to indicate a specific term often abbreviated. Give me a moment to rework this.
There was a problem hiding this comment.
hopefully that's clearer
|
@AnotherButler Did initial copy edit and left comments |
Copy edit for active voice, US spelling and minor style nits.
Make minor formatting changes.
|
|
||
| #### 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 was a problem hiding this comment.
Query: Who or what should use this handle to read or write these components?
There was a problem hiding this comment.
The application. Code written by the user.
|
|
||
| #### 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. |
There was a problem hiding this comment.
Query: Who or what must access the values of the characteristic and the characteristic descriptor present in the GattServer? Also, who or what has registered the service?
Note to self: Remove the "u" from "flavors" for U.S. spelling.
There was a problem hiding this comment.
The user registers a service. When this happens a handle is created. This handle must be used to read and write the attribute both by the user code (local application) and by clients (remote applications).
|
|
||
| #### Events | ||
|
|
||
| The GattServer allows application code to register several event handlers that can be used to monitor client and server activities: |
There was a problem hiding this comment.
Query: Who or what can use the event handlers to monitor client and server activities? You, the user?
There was a problem hiding this comment.
Yes, application code means code written by users.
|
|
||
| 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. |
There was a problem hiding this comment.
Query: Who or what calls the event handler? You, the user? Or someone else? Also, who or what sends a characteristic value update to a client?
There was a problem hiding this comment.
For the record I find the naming confusing too. This function lets you register a handler. You, the user, call this function and pass in a handler that we, the GattServer will call later.
The server (our code) calls the handler you registered (users code).
The server sends updates to clients.
| 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. |
There was a problem hiding this comment.
Query: Who or what calls the event handler? Also, who or what writes an attribute of the server?
There was a problem hiding this comment.
The server (our code) calls the handler you registered (users code).
Clients write attributes.
|
|
||
| - `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. |
There was a problem hiding this comment.
Query: Who or what calls the event handler? Also, who or what reads an attribute of the server?
There was a problem hiding this comment.
Server calls the handler when a client has read an attribute.
Clients read attributes.
| - `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. |
There was a problem hiding this comment.
Query: Who or what calls the event handler?
There was a problem hiding this comment.
The server (our code) calls the handler you registered (users code).
| - `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. |
There was a problem hiding this comment.
Query: Who or what calls the event handler?
There was a problem hiding this comment.
The server (our code) calls the handler you registered (users code).
| - `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. |
There was a problem hiding this comment.
Query: Who or what calls the event handler?
There was a problem hiding this comment.
The server (our code) calls the handler you registered (users code).
| - `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. |
There was a problem hiding this comment.
Query: Could we say "The term "characteristic value update" represents Characteristic..."?
There was a problem hiding this comment.
@paul-szczepanek-arm Thanks for the updates 👍 They look great.
|
|
||
| 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 | ||
|
|
There was a problem hiding this comment.
Do we have an example created for this?
| - `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 | ||
|
|
There was a problem hiding this comment.
Do we have an example created for this?
|
|
|
@paul-szczepanek-arm Yes, let's add the examples before merging because they're arriving soon. |
Add example transcluded from teams repo.
Add example from teams.
Fix broken link.
No description provided.