You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2018/01/15 18:55:19 UTC
[GitHub] aditihilbert closed pull request #370: Updated BLE Peripheral Project Service Registration Page
aditihilbert closed pull request #370: Updated BLE Peripheral Project Service Registration Page
URL: https://github.com/apache/mynewt-site/pull/370
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/os/tutorials/bleprph/bleprph-svc-reg.md b/docs/os/tutorials/bleprph/bleprph-svc-reg.md
index d55e70ea3..cf929794a 100644
--- a/docs/os/tutorials/bleprph/bleprph-svc-reg.md
+++ b/docs/os/tutorials/bleprph/bleprph-svc-reg.md
@@ -22,30 +22,26 @@ so let's take a look at that now. The attribute table is called
```c
static const struct ble_gatt_svc_def gatt_svr_svcs[] = {
{
- /*** Service: GAP. */
- .type = BLE_GATT_SVC_TYPE_PRIMARY,
- .uuid128 = BLE_UUID16(BLE_GAP_SVC_UUID16),
- .characteristics = (struct ble_gatt_chr_def[]) { {
- /*** Characteristic: Device Name. */
- .uuid128 = BLE_UUID16(BLE_GAP_CHR_UUID16_DEVICE_NAME),
- .access_cb = gatt_svr_chr_access_gap,
- .flags = BLE_GATT_CHR_F_READ,
- }, {
- /*** Characteristic: Appearance. */
- .uuid128 = BLE_UUID16(BLE_GAP_CHR_UUID16_APPEARANCE),
- .access_cb = gatt_svr_chr_access_gap,
- .flags = BLE_GATT_CHR_F_READ,
+ /*** Service: Security test. */
+ .type = BLE_GATT_SVC_TYPE_PRIMARY,
+ .uuid = &gatt_svr_svc_sec_test_uuid.u,
+ .characteristics = (struct ble_gatt_chr_def[]) { {
+ /*** Characteristic: Random number generator. */
+ .uuid = &gatt_svr_chr_sec_test_rand_uuid.u,
+ .access_cb = gatt_svr_chr_access_sec_test,
+ .flags = BLE_GATT_CHR_F_READ,
}, {
+ /*** Characteristic: Static value. */
+ .uuid = &gatt_svr_chr_sec_test_static_uuid.u,
+ .access_cb = gatt_svr_chr_access_sec_test,
+ .flags = BLE_GATT_CHR_F_READ,
// [...]
```
<br>
As you can see, the table is an array of service definitions (
-`struct ble_gatt_svc_def`). This code excerpt contains a small part of the
-*GAP service*. The GAP service exposes generic information about a device,
-such as its name and appearance. Support for the GAP service is mandatory for
-all BLE peripherals. Let's now consider the contents of this table in more
+`struct ble_gatt_svc_def`). Let's now consider the contents of this table in more
detail.
A service definition consists of the following fields:
@@ -53,57 +49,47 @@ A service definition consists of the following fields:
| *Field* | *Meaning* | *Notes* |
| ------- | --------- | ------- |
| type | Specifies whether this is a primary or secondary service. | Secondary services are not very common. When in doubt, specify *BLE_GATT_SVC_TYPE_PRIMARY* for new services. |
-| uuid128 | The 128-bit UUID of this service. | If the service has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the `BLE_UUID16()` macro. |
+| uuid | The UUID of this characteristic. | This field accepts a pointer to a variable of type `ble_uuid_t`. You could directly use the `BLE_UUID16_DECLARE()` macro or to pass a pointer to a `ble_uuid16_t` variable you could type `&uuid_variable.u` |
| characteristics | The array of characteristics that belong to this service. | |
<br>
A service is little more than a container of characteristics; the
-characteristics themselves are where the real action happens. A characteristic
+characteristics themselves are where the real action happens. A characteristic
definition consists of the following fields:
| *Field* | *Meaning* | *Notes* |
| ------- | --------- | ------- |
-| uuid128 | The 128-bit UUID of this characteristic. | If the characteristic has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the `BLE_UUID16()` macro. |
+| uuid | The UUID of this characteristic. | This field accepts a pointer to a variable of type `ble_uuid_t`. You could directly use the `BLE_UUID16_DECLARE()` macro or to pass a pointer to a `ble_uuid16_t` variable you could type `&uuid_variable.u` |
| access\_cb | A callback function that gets executed whenever a peer device accesses this characteristic. | *For reads:* this function generates the value that gets sent back to the peer.<br>*For writes:* this function receives the written value as an argument. |
| flags | Indicates which operations are permitted for this characteristic. The NimBLE stack responds negatively when a peer attempts an unsupported operation. | The full list of flags can be found under `ble_gatt_chr_flags` in [net/nimble/host/include/host/ble_gatt.h](https://github.com/apache/mynewt-core/blob/master/net/nimble/host/include/host/ble_gatt.h).|
-The access callback is what implements the characteristic's behavior. Access
+The access callback is what implements the characteristic's behavior. Access
callbacks are described in detail in the next section:
[BLE Peripheral - Characteristic Access](bleprph-chr-access/).
The service definition array and each characteristic definition array is
-terminated with an empty entry, represented with a 0. The below code listing
+terminated with an empty entry, represented with a 0. The below code listing
shows the last service in the array, including terminating zeros for the
characteristic array and service array.
<br>
-```c hl_lines="26 31"
+```c hl_lines="16 21"
{
- /*** Alert Notification Service. */
+ /*** Service: Security test. */
.type = BLE_GATT_SVC_TYPE_PRIMARY,
- .uuid128 = BLE_UUID16(GATT_SVR_SVC_ALERT_UUID),
+ .uuid = &gatt_svr_svc_sec_test_uuid.u,
.characteristics = (struct ble_gatt_chr_def[]) { {
- .uuid128 = BLE_UUID16(GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID),
- .access_cb = gatt_svr_chr_access_alert,
+ /*** Characteristic: Random number generator. */
+ .uuid = &gatt_svr_chr_sec_test_rand_uuid.u,
+ .access_cb = gatt_svr_chr_access_sec_test,
.flags = BLE_GATT_CHR_F_READ,
}, {
- .uuid128 = BLE_UUID16(GATT_SVR_CHR_NEW_ALERT),
- .access_cb = gatt_svr_chr_access_alert,
- .flags = BLE_GATT_CHR_F_NOTIFY,
- }, {
- .uuid128 = BLE_UUID16(GATT_SVR_CHR_SUP_UNR_ALERT_CAT_UUID),
- .access_cb = gatt_svr_chr_access_alert,
+ /*** Characteristic: Static value. */
+ .uuid = &gatt_svr_chr_sec_test_static_uuid.u,
+ .access_cb = gatt_svr_chr_access_sec_test,
.flags = BLE_GATT_CHR_F_READ,
- }, {
- .uuid128 = BLE_UUID16(GATT_SVR_CHR_UNR_ALERT_STAT_UUID),
- .access_cb = gatt_svr_chr_access_alert,
- .flags = BLE_GATT_CHR_F_NOTIFY,
- }, {
- .uuid128 = BLE_UUID16(GATT_SVR_CHR_ALERT_NOT_CTRL_PT),
- .access_cb = gatt_svr_chr_access_alert,
- .flags = BLE_GATT_CHR_F_WRITE,
}, {
0, /* No more characteristics in this service. */
} },
@@ -122,31 +108,44 @@ After you have created your service table, your app needs to register it with th
```c
int
-ble_gatts_register_svcs(const struct ble_gatt_svc_def *svcs,
- ble_gatt_register_fn *cb, void *cb_arg)
+ble_gatts_add_svcs(const struct ble_gatt_svc_def *svcs)
```
The function parameters are documented below.
| *Parameter* | *Meaning* | *Notes* |
| ----------- | --------- | ------- |
-| svcs | The table of services to register. | |
-| cb | A callback that gets executed each time a service, characteristic, or descriptor is registered. | Optional; pass NULL if you don't want to be notified. |
-| cb\_arg | An argument that gets passed to the callback function on each invocation. | Optional; pass NULL if there is no callback or if you don't need a special argument. |
+| svcs | An array of service definitions to queue for registration. This array must be terminated with an entry whose 'type' equals 0. | |
The `ble_gatts_register_svcs()` function returns 0 on success, or a
*BLE_HS_E[...]* error code on failure.
-More detailed information about the registration callback function can be found
-in the [BLE User Guide](../../../network/ble/ble_intro/) (TBD).
-
The *bleprph* app registers its services as follows:
```c
- rc = ble_gatts_register_svcs(gatt_svr_svcs, gatt_svr_register_cb, NULL);
- assert(rc == 0);
+ rc = ble_gatts_add_svcs(gatt_svr_svcs);
+ if (rc != 0) {
+ return rc;
+ }
```
+More detailed information about the registration function can be found
+in the BLE User Guide: [ble_gatts_add_svcs](../../../network/ble/ble_hs/ble_gatts/functions/ble_gatts_add_svcs/).
+
+<br>
+
+#### Registration callback function
+
+It is possible to set a callback function that gets executed each time a service, characteristic, or descriptor is registered. This is done by setting the following attribute:
+
+```c
+ble_hs_cfg.gatts_register_cb = gatt_svr_register_cb;
+```
+In the above example `gatt_svr_register_cb` is the function that will be called. This line can be found in *bleprph*'s `main.c` file
+
+More detailed information about the registration callback function can be found
+in the [BLE User Guide](../../../network/ble/ble_intro/) (TBD).
+
<br>
#### Descriptors and Included Services
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services