You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/05/03 09:12:19 UTC
[3/3] incubator-mynewt-site git commit: pull requests #75-77 and
minor changes to ble peripheral tutorials
pull requests #75-77 and minor changes to ble peripheral tutorials
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/c23164b2
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/c23164b2
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/c23164b2
Branch: refs/heads/asf-site
Commit: c23164b258f16fac7e2b279e2a1bd419c36eb2f0
Parents: e5bb88f
Author: aditihilbert <ad...@runtime.io>
Authored: Tue May 3 00:12:07 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Tue May 3 00:12:07 2016 -0700
----------------------------------------------------------------------
mkdocs/search_index.json | 163 +++-
os/modules/hal/hal_uart/hal_uart/index.html | 8 +-
os/modules/testutil/testutil/index.html | 2 +-
os/os_user_guide/index.html | 4 +-
os/tutorials/STM32F303/index.html | 11 +
os/tutorials/add_repos/index.html | 11 +
os/tutorials/air_quality_sensor/index.html | 11 +
os/tutorials/arduino_zero/index.html | 11 +
os/tutorials/bleprph/bleprph-adv/index.html | 760 ++++++++++++++++
.../bleprph/bleprph-chr-access/index.html | 874 +++++++++++++++++++
os/tutorials/bleprph/bleprph-conn/index.html | 790 +++++++++++++++++
os/tutorials/bleprph/bleprph-intro/index.html | 664 ++++++++++++++
os/tutorials/bleprph/bleprph-svc-reg/index.html | 830 ++++++++++++++++++
os/tutorials/bletiny_project/index.html | 11 +
os/tutorials/blinky_sram_olimex/index.html | 11 +
os/tutorials/create_repo/index.html | 11 +
os/tutorials/event_queue/index.html | 15 +-
os/tutorials/nRF52/index.html | 11 +
os/tutorials/olimex/index.html | 11 +
os/tutorials/project-slinky/index.html | 11 +
os/tutorials/project-target-slinky/index.html | 11 +
os/tutorials/tutorials/index.html | 11 +
os/tutorials/unit_test/index.html | 11 +
os/tutorials/upgrade_repo/index.html | 11 +
sitemap.xml | 26 +-
25 files changed, 4264 insertions(+), 26 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index 67760a0..137f975 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -1036,6 +1036,161 @@
"title": "Code for the example"
},
{
+ "location": "/os/tutorials/bleprph/bleprph-intro/",
+ "text": "BLE Peripheral Project\n\n\nIntroduction\n\n\n\n\nOverview\n\n\nbleprph\n is an example app included in the apache-mynewt-core repository. This app implements a simple BLE peripheral with the following properties:\n\n\n\n\nSupports three services: GAP, GATT, and alert notification service (ANS).\n\n\nSupports a single concurrent connection.\n\n\nAutomatically advertises connectability when not connected to a central device.\n\n\n\n\nThis tutorial aims to provide a guided tour through the \nbleprph\n app source\ncode. This document builds on some concepts described elsewhere in the Apache\nMynewt documentation. Before proceeding with this tutorial, you might want to\nfamiliarize yourself with the following pages:\n\n\n\n\nCreate Your First Mynewt Project\n\n\nNimBLE Stack Initialization\n\n\n\n\n\n\nServices, Characteristics, Descriptors\n\n\nA BLE peripheral interfaces with other BLE devices by exposing \nservices\n,\n\ncharacteristics\n, and \ndescriptors\n.
All three of these entities are\nimplemented at a lower layer via \nattributes\n. If you are not familiar with\nthese concepts, you will probably want to check out this\n\noverview\n\nfrom the Bluetooth Developer's site before proceeding.\n\n\nNow let's dig in to some C code.",
+ "title": "toc"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-intro/#ble-peripheral-project",
+ "text": "",
+ "title": "BLE Peripheral Project"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-intro/#introduction",
+ "text": "",
+ "title": "Introduction"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-intro/#overview",
+ "text": "bleprph is an example app included in the apache-mynewt-core repository. This app implements a simple BLE peripheral with the following properties: Supports three services: GAP, GATT, and alert notification service (ANS). Supports a single concurrent connection. Automatically advertises connectability when not connected to a central device. This tutorial aims to provide a guided tour through the bleprph app source\ncode. This document builds on some concepts described elsewhere in the Apache\nMynewt documentation. Before proceeding with this tutorial, you might want to\nfamiliarize yourself with the following pages: Create Your First Mynewt Project NimBLE Stack Initialization",
+ "title": "Overview"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-intro/#services-characteristics-descriptors",
+ "text": "A BLE peripheral interfaces with other BLE devices by exposing services , characteristics , and descriptors . All three of these entities are\nimplemented at a lower layer via attributes . If you are not familiar with\nthese concepts, you will probably want to check out this overview \nfrom the Bluetooth Developer's site before proceeding. Now let's dig in to some C code.",
+ "title": "Services, Characteristics, Descriptors"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-svc-reg/",
+ "text": "BLE Peripheral Project\n\n\nService Registration\n\n\n\n\nAttribute Set\n\n\nThe NimBLE host uses a table-based design for GATT server configuration. The\nset of supported attributes are expressed as a series of tables that resides in\nyour C code. When possible, we recommend using a single monolithic table, as\nit results in code that is simpler and less error prone. Multiple tables\ncan be used if it is impractical for the entire attribute set to live in one\nplace in your code.\n\n\nbleprph\n uses a single attribute table located in the \ngatt_svr.c\n file,\nso let's take a look at that now. The attribute table is called\n\ngatt_svr_svcs\n; here are the first several lines from this table:\n\n\n\n\nstatic\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \ngatt_svr_svcs\n[] \n=\n {\n {\n \n/*** Service: GAP. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nBLE_GAP_SVC_UU
ID16\n),\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n \n/*** Characteristic: Device Name. */\n\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nBLE_GAP_CHR_UUID16_DEVICE_NAME\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_gap\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n \n/*** Characteristic: Appearance. */\n\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nBLE_GAP_CHR_UUID16_APPEARANCE\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_gap\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n \n// [...]\n\n\n\n\n\n\n\n\nAs you can see, the table is an array of service definitions (\n\nstruct ble_gatt_svc_def\n). This code excerpt contains a small part of the\n\nGAP service\n. The GAP service exposes generic information about a device,\nsuch as its name and appearance. Support for the
GAP service is mandatory for\nall BLE peripherals. Let's now consider the contents of this table in more\ndetail.\n\n\nA service definition consists of the following fields:\n\n\n\n\n\n\n\n\nField\n\n\nMeaning\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\ntype\n\n\nSpecifies whether this is a primary or secondary service.\n\n\nSecondary services are not very common. When in doubt, specify \nBLE_GATT_SVC_TYPE_PRIMARY\n for new services.\n\n\n\n\n\n\nuuid128\n\n\nThe 128-bit UUID of this service.\n\n\nIf the service has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the \nBLE_UUID16()\n macro.\n\n\n\n\n\n\ncharacteristics\n\n\nThe array of characteristics that belong to this service.\n\n\n\n\n\n\n\n\n\n\n\n\nA service is little more than a container of characteristics; the\ncharacteristics themselves are where the real action happens. A characteristic\ndefinition consists of the following fields:\n\n\n\n\n\n\n\n\nField\n\n\nMeaning\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nuuid12
8\n\n\nThe 128-bit UUID of this characteristic.\n\n\nIf the characteristic has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the \nBLE_UUID16()\n macro.\n\n\n\n\n\n\naccess_cb\n\n\nA callback function that gets executed whenever a peer device accesses this characteristic.\n\n\nFor reads:\n this function generates the value that gets sent back to the peer.\nFor writes:\n this function provides the written value as an argument.\n\n\n\n\n\n\nflags\n\n\nIndicates which operations are permitted for this characteristic. The NimBLE stack responds negatively when a peer attempts an unsupported operation.\n\n\nThe full list of flags can be found under \nble_gatt_chr_flags\n in \nnet/nimble/host/include/host/ble_gatt.h\n.\n\n\n\n\n\n\n\n\nThe access callback is what implements the characteristic's behavior. Access\ncallbacks are described in detail in the next section:\n\nBLE Peripheral - Characteristic Access\n.\n\n\nThe service definition array and each characte
ristic definition array is\nterminated with an empty entry, represented with a 0. The below code listing\nshows the last service in the array, including terminating zeros for the\ncharacteristic array and service array.\n\n\n\n\n {\n \n/*** Alert Notification Service. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_SVC_ALERT_UUID\n),\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_NEW_ALERT\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_NOTIFY\n,\n }, {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_SUP_UNR_AL
ERT_CAT_UUID\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_UNR_ALERT_STAT_UUID\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_NOTIFY\n,\n }, {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_ALERT_NOT_CTRL_PT\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_WRITE\n,\n }, {\n\n \n0\n, \n/* No more characteristics in this service. */\n\n\n } },\n },\n\n {\n\n \n0\n, \n/* No more services. */\n\n\n },\n\n\n\n\n\n\n\nRegistration function\n\n\nAfter you have created your service table, your app needs to register it with the NimBLE stack. This is done by calling the following function:\n\n\nint\n\n\nble_gatts_register_svcs\n(\nconst\n \nstru
ct\n \nble_gatt_svc_def\n \n*svcs\n,\n \nble_gatt_register_fn\n \n*cb\n, \nvoid\n \n*cb_arg\n)\n\n\n\n\n\nThe function parameters are documented below.\n\n\n\n\n\n\n\n\nParameter\n\n\nMeaning\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nsvcs\n\n\nThe table of services to register.\n\n\n\n\n\n\n\n\ncb\n\n\nA callback that gets executed each time a service, characteristic, or descriptor is registered.\n\n\nOptional; pass NULL if you don't want to be notified.\n\n\n\n\n\n\ncb_arg\n\n\nAn argument that gets passed to the callback function on each invocation.\n\n\nOptional; pass NULL if there is no callback or if you don't need a special argument.\n\n\n\n\n\n\n\n\nThe \nble_gatts_register_svcs()\n function returns 0 on success, or a\n\nBLE_HS_E[...]\n error code on failure.\n\n\nMore detailed information about the registration callback function can be found\nin the \nBLE User Guide\n (TBD).\n\n\nThe \nbleprph\n app registers its services as follows:\n\n\n \nrc\n \n=\n \nble_
gatts_register_svcs\n(\ngatt_svr_svcs\n, \ngatt_svr_register_cb\n, \nNULL\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n\n\n\n\nDescriptors and Included Services\n\n\nYour peripheral can also expose descriptors and included services. These are\nless common, so they are not covered in this tutorial. For more information,\nsee the \nBLE User Guide\n.",
+ "title": "Service Registration"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-svc-reg/#ble-peripheral-project",
+ "text": "",
+ "title": "BLE Peripheral Project"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-svc-reg/#service-registration",
+ "text": "",
+ "title": "Service Registration"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-svc-reg/#attribute-set",
+ "text": "The NimBLE host uses a table-based design for GATT server configuration. The\nset of supported attributes are expressed as a series of tables that resides in\nyour C code. When possible, we recommend using a single monolithic table, as\nit results in code that is simpler and less error prone. Multiple tables\ncan be used if it is impractical for the entire attribute set to live in one\nplace in your code. bleprph uses a single attribute table located in the gatt_svr.c file,\nso let's take a look at that now. The attribute table is called gatt_svr_svcs ; here are the first several lines from this table: static const struct ble_gatt_svc_def gatt_svr_svcs [] = {\n {\n /*** Service: GAP. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid128 = BLE_UUID16 ( BLE_GAP_SVC_UUID16 ),\n . characteristics = ( struct ble_gatt_chr_def []) { {\n /*** Characteristic: Device
Name. */ \n . uuid128 = BLE_UUID16 ( BLE_GAP_CHR_UUID16_DEVICE_NAME ),\n . access_cb = gatt_svr_chr_access_gap ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n /*** Characteristic: Appearance. */ \n . uuid128 = BLE_UUID16 ( BLE_GAP_CHR_UUID16_APPEARANCE ),\n . access_cb = gatt_svr_chr_access_gap ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n // [...] 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,\nsuch as its name and appearance. Support for the GAP service is mandatory for\nall BLE peripherals. Let's now consider the contents of this table in more\ndetail. 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. characteristics The array of characteristics that belong to this service. A service is little more than a container of characteristics; the\ncharacteristics themselves are where the real action happens. A characteristic\ndefinition 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. 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. For writes: this function provides 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 . The access callback is what implements the characteristic's behavior. Access\ncallbacks are described in detail in the next section: BLE Peripheral - Characteristic Access . The service definition array and each characteristic definition array is\nterminated with an empty entry, represented with a 0. The below code listing\nshows the last service in the array, including terminating zeros for the\ncharacteristic array and service array. {\n /*** Alert Notification Service. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid128 = BLE_UUID16 ( GATT_SVR_SVC_ALERT_UUID ),\n . characteri
stics = ( struct ble_gatt_chr_def []) { {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_NEW_ALERT ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_NOTIFY ,\n }, {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_SUP_UNR_ALERT_CAT_UUID ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_UNR_ALERT_STAT_UUID ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_NOTIFY ,\n }, {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_ALERT_NOT_CTRL_PT ),\n . access_cb = gatt_svr_chr_access_alert ,\n .
flags = BLE_GATT_CHR_F_WRITE ,\n }, { 0 , /* No more characteristics in this service. */ } },\n },\n\n { 0 , /* No more services. */ },",
+ "title": "Attribute Set"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-svc-reg/#registration-function",
+ "text": "After you have created your service table, your app needs to register it with the NimBLE stack. This is done by calling the following function: int ble_gatts_register_svcs ( const struct ble_gatt_svc_def *svcs ,\n ble_gatt_register_fn *cb , void *cb_arg ) 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. 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\nin the BLE User Guide (TBD). The
bleprph app registers its services as follows: rc = ble_gatts_register_svcs ( gatt_svr_svcs , gatt_svr_register_cb , NULL );\n assert ( rc == 0 );",
+ "title": "Registration function"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-svc-reg/#descriptors-and-included-services",
+ "text": "Your peripheral can also expose descriptors and included services. These are\nless common, so they are not covered in this tutorial. For more information,\nsee the BLE User Guide .",
+ "title": "Descriptors and Included Services"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/",
+ "text": "BLE Peripheral Project\n\n\nCharacteristic Access\n\n\n\n\nReview\n\n\nA characteristic's access callback implements its behavior. Recall that\nservices and characteristics are registered with NimBLE via attribute tables.\nEach characteristic definition in an attribute table contains an \naccess_cb\n\nfield. The \naccess_cb\n field is an application callback that gets executed\nwhenever a peer device attempts to read or write the characteristic.\n\n\nEarlier in this tutorial, we looked at how \nbleprph\n implements the GAP\nservice. Let's take another look at how \nbleprph\n specifies the first few\ncharacteristics in this service.\n\n\n\n\nstatic\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \ngatt_svr_svcs\n[] \n=\n {\n {\n \n/*** Service: GAP. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nBLE_GAP_SVC_UUID16\n),\n .\ncharacteristics\n \n=\n (\nstruct\n \nb
le_gatt_chr_def\n[]) { {\n \n/*** Characteristic: Device Name. */\n\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nBLE_GAP_CHR_UUID16_DEVICE_NAME\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_gap\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n \n/*** Characteristic: Appearance. */\n\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nBLE_GAP_CHR_UUID16_APPEARANCE\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_gap\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n \n// [...]\n\n\n\n\n\n\nAs you can see, \nbleprph\n uses the same \naccess_cb\n function for all the GAP\nservice characteristics, but the developer could have implemented separate\nfunctions for each characteristic if they preferred. Here is the \naccess_cb\n\nfunction that the GAP service characteristics use:\n\n\n\n\nstatic\n \nint\n\n\ngatt_svr_chr_access_
gap\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n, \nuint8_t\n \nop\n,\n \nunion\n \nble_gatt_access_ctxt\n \n*ctxt\n, \nvoid\n \n*arg\n)\n{\n \nuint16_t\n \nuuid16\n;\n\n \nuuid16\n \n=\n \nble_uuid_128_to_16\n(\nctxt-\nchr_access\n.\nchr-\nuuid128\n);\n \nassert\n(\nuuid16\n \n!=\n \n0\n);\n\n \nswitch\n (\nuuid16\n) {\n \ncase\n \nBLE_GAP_CHR_UUID16_DEVICE_NAME\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nctxt-\nchr_access\n.\ndata\n \n=\n (\nvoid\n \n*\n)\nbleprph_device_name\n;\n \nctxt-\nchr_access\n.\nlen\n \n=\n \nstrlen\n(\nbleprph_device_name\n);\n \nbreak\n;\n\n \ncase\n \nBLE_GAP_CHR_UUID16_APPEARANCE\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nctxt-\nchr_access\n.\ndata\n \n=\n (\nvoid\n \n*\n)\nbleprph_appearance\n;\n \nctxt-\nchr_access\n.\nlen\n \n=\n \nsizeof\n \nbleprph_appearance\n;\n \nbreak\n;\n\n \ncas
e\n \nBLE_GAP_CHR_UUID16_PERIPH_PRIV_FLAG\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nctxt-\nchr_access\n.\ndata\n \n=\n (\nvoid\n \n*\n)\nbleprph_privacy_flag\n;\n \nctxt-\nchr_access\n.\nlen\n \n=\n \nsizeof\n \nbleprph_privacy_flag\n;\n \nbreak\n;\n\n \ncase\n \nBLE_GAP_CHR_UUID16_RECONNECT_ADDR\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_WRITE_CHR\n);\n \nif\n (\nctxt-\nchr_access\n.\nlen\n \n!=\n \nsizeof\n \nbleprph_reconnect_addr\n) {\n \nreturn\n \nBLE_ATT_ERR_INVALID_ATTR_VALUE_LEN\n;\n }\n \nmemcpy\n(\nbleprph_reconnect_addr\n, \nctxt-\nchr_access\n.\ndata\n,\n \nsizeof\n \nbleprph_reconnect_addr\n);\n \nbreak\n;\n\n \ncase\n \nBLE_GAP_CHR_UUID16_PERIPH_PREF_CONN_PARAMS\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nctxt-\nchr_access\n.\ndata\n \n=\n (\nvoid\n \n*\n)\nbleprph_pref_conn_params\n;\n \nctxt-\nch
r_access\n.\nlen\n \n=\n \nsizeof\n \nbleprph_pref_conn_params\n;\n \nbreak\n;\n\n \ndefault\n:\n\n \nassert\n(\n0\n);\n \nbreak\n;\n }\n\n \nreturn\n \n0\n;\n}\n\n\n\n\n\nAfter you've taken a moment to examine the structure of this function, let's explore some details.\n\n\n\n\nFunction signature\n\n\n\n\nstatic\n \nint\n\n\ngatt_svr_chr_access_gap\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n, \nuint8_t\n \nop\n,\n \nunion\n \nble_gatt_access_ctxt\n \n*ctxt\n, \nvoid\n \n*arg\n)\n\n\n\n\n\nA characteristic access function always takes this same set of parameters and\nalways returns an int. The parameters to this function type are documented\nbelow.\n\n\n\n\n\n\n\n\n\n\nParameter\n\n\nPurpose\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nIndicates which connection the characteristic access was sent over.\n\n\nUse this value to determine which peer is accessing the characteristic.\n\n\n\n\n\n\nattr_handle\n\n\nT
he low-level ATT handle of the characteristic value attribute.\n\n\nCan be used to determine which characteristic is being accessed if you don't want to perform a UUID lookup.\n\n\n\n\n\n\nop\n\n\nIndicates whether this is a read or write operation\n\n\nValid values are:\nBLE_GATT_ACCESS_OP_READ_CHR\nBLE_GATT_ACCESS_OP_WRITE_CHR\n\n\n\n\n\n\nctxt\n\n\nContains the characteristic value pointer that the application needs to access.\n\n\nFor characteristic accesses, use the \nctxt-\nchr_access\n member; for descriptor accesses, use the \nctxt-\ndsc_access\n member.\n\n\n\n\n\n\n\n\nThe return value of the access function tells the NimBLE stack how to respond\nto the peer performing the operation. A value of 0 indicates success. For\nfailures, the function returns the specific ATT error code that the NimBLE\nstack should respond with. The ATT error codes are defined in\n\nnet/nimble/host/include/host/ble_att.h\n.\n\n\n\n\nDetermine characteristic being accessed\n\n\n\n\n{\n \nuint
16_t\n \nuuid16\n;\n\n \nuuid16\n \n=\n \nble_uuid_128_to_16\n(\nctxt-\nchr_access\n.\nchr-\nuuid128\n);\n \nassert\n(\nuuid16\n \n!=\n \n0\n);\n\n \nswitch\n (\nuuid16\n) {\n \n// [...]\n\n\n\n\n\n\nThis function uses the UUID to determine which characteristic is being\naccessed. There are two alternative methods \nbleprph\n could have used to\naccomplish this task:\n\n\n\n\nMap characteristics to ATT handles during service registration; use the \nattr_handle\n parameter as a key into this table during characteristic access.\n\n\nImplement a dedicated function for each characteristic; each function inherently knows which characteristic it corresponds to.\n\n\n\n\nAll the GAP service characteristics have 16-bit UUIDs, so this function uses\nthe \nble_uuid_128_to_16()\n function to convert the 128-bit UUID to its\ncorresponding 16-bit UUID. This conversion function returns the corresponding\n16-bit UUID on success, or 0 on failure. Success is asserted here to ensur
e\nthe NimBLE stack is doing its job properly; the stack should only call this\nfunction for accesses to characteristics that it is registered with, and all\nGAP service characteristics have valid 16-bit UUIDs.\n\n\n\n\nRead access\n\n\n\n\n \ncase\n \nBLE_GAP_CHR_UUID16_DEVICE_NAME\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nctxt-\nchr_access\n.\ndata\n \n=\n (\nvoid\n \n*\n)\nbleprph_device_name\n;\n \nctxt-\nchr_access\n.\nlen\n \n=\n \nstrlen\n(\nbleprph_device_name\n);\n \nbreak\n;\n\n\n\n\n\nThis code excerpt handles read accesses to the device name characteristic. The\n\nassert()\n here is another case of making sure the NimBLE stack is doing its\njob; this characteristic was registered as read-only, so the stack should have\nprevented write accesses.\n\n\nTo fulfill a characteristic read request, the application needs to assign the\n\nctxt-\nchr_access.data\n field to point to the attribute data to respond with,\nand fi
ll the \nctxt-\nchr_access.len\n field with the length of the attribute data.\n\nbleprph\n stores the device name in read-only memory as follows:\n\n\n\n\nconst\n \nchar\n \n*bleprph_device_name\n \n=\n \nnimble-bleprph\n;\n\n\n\n\n\nThe cast to pointer-to-void is a necessary annoyance to remove the \nconst\n\nqualifier from the device name variable. You will need to \"cast away const\"\nwhenever you respond to read requests with read-only data.\n\n\nIt is not shown in the above snippet, but this function ultimately returns 0.\nBy returning 0, \nbleprph\n indicates that the characteristic data in\n\nctxt-\nchr_access\n is valid and that NimBLE should include it in its response\nto the peer.\n\n\n\n\nA word of warning:\n The attribute data that \nctxt-\nchr_access.data\n points to\nmust remain valid after the access function returns, as the NimBLE stack needs\nto use it to form a GATT read response. In other words, you must not\nallocate the characteristic value data on the stack o
f the access function.\nTwo characteristic accesses never occur at the same time, so it is OK to use\nthe same memory for repeated accesses.\n\n\n\n\nWrite access\n\n\n\n\n \ncase\n \nBLE_GAP_CHR_UUID16_RECONNECT_ADDR\n:\n \nassert\n(\nop\n \n==\n \nBLE_GATT_ACCESS_OP_WRITE_CHR\n);\n \nif\n (\nctxt-\nchr_access\n.\nlen\n \n!=\n \nsizeof\n \nbleprph_reconnect_addr\n) {\n \nreturn\n \nBLE_ATT_ERR_INVALID_ATTR_VALUE_LEN\n;\n }\n \nmemcpy\n(\nbleprph_reconnect_addr\n, \nctxt-\nchr_access\n.\ndata\n,\n \nsizeof\n \nbleprph_reconnect_addr\n);\n \nbreak\n;\n\n\n\n\n\nThis code excerpt handles writes to the reconnect address characteristic. This\ncharacteristic was registered as write-only, so the \nassert()\n here is just a\nsafety precaution to ensure the NimBLE stack is doing its job.\n\n\nFor writes, the roles of the \nctxt-\nchr_access.data\n and \nctxt-\nchr_access.len\n\nfields are the reverse of the read case. The NimB
LE stack uses these fields to\nindicate the data written by the peer.\n\n\nMany characteristics have strict length requirements for write operations.\nThis characteristic has such a restriction; if the written data is not a 48-bit\nBR address, the application tells NimBLE to respond with an invalid attribute\nvalue length error.\n\n\nFor writes, the \nctxt-\nchr_access.data\n pointer is only valid for the duration\nof the access function. If the application needs to save the written data, it\nshould store it elsewhere before the function returns. In this case, \nbleprph\n\nstores the specified address in a global variable called\n\nbleprph_reconnect_addr\n.",
+ "title": "Characteristic Access"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#ble-peripheral-project",
+ "text": "",
+ "title": "BLE Peripheral Project"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#characteristic-access",
+ "text": "",
+ "title": "Characteristic Access"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#review",
+ "text": "A characteristic's access callback implements its behavior. Recall that\nservices and characteristics are registered with NimBLE via attribute tables.\nEach characteristic definition in an attribute table contains an access_cb \nfield. The access_cb field is an application callback that gets executed\nwhenever a peer device attempts to read or write the characteristic. Earlier in this tutorial, we looked at how bleprph implements the GAP\nservice. Let's take another look at how bleprph specifies the first few\ncharacteristics in this service. static const struct ble_gatt_svc_def gatt_svr_svcs [] = {\n {\n /*** Service: GAP. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid128 = BLE_UUID16 ( BLE_GAP_SVC_UUID16 ),\n . characteristics = ( struct ble_gatt_chr_def []) { {\n /*** Characteristic: Device Name. */ \n . uuid128 = BLE_UUID
16 ( BLE_GAP_CHR_UUID16_DEVICE_NAME ),\n . access_cb = gatt_svr_chr_access_gap ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n /*** Characteristic: Appearance. */ \n . uuid128 = BLE_UUID16 ( BLE_GAP_CHR_UUID16_APPEARANCE ),\n . access_cb = gatt_svr_chr_access_gap ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n // [...] As you can see, bleprph uses the same access_cb function for all the GAP\nservice characteristics, but the developer could have implemented separate\nfunctions for each characteristic if they preferred. Here is the access_cb \nfunction that the GAP service characteristics use: static int gatt_svr_chr_access_gap ( uint16_t conn_handle , uint16_t attr_handle , uint8_t op ,\n union ble_gatt_access_ctxt *ctxt , void *arg )\n{\n uint16_t uuid16 ;\n\n uuid16 =
ble_uuid_128_to_16 ( ctxt- chr_access . chr- uuid128 );\n assert ( uuid16 != 0 );\n\n switch ( uuid16 ) {\n case BLE_GAP_CHR_UUID16_DEVICE_NAME :\n assert ( op == BLE_GATT_ACCESS_OP_READ_CHR );\n ctxt- chr_access . data = ( void * ) bleprph_device_name ;\n ctxt- chr_access . len = strlen ( bleprph_device_name );\n break ;\n\n case BLE_GAP_CHR_UUID16_APPEARANCE :\n assert ( op == BLE_GATT_ACCESS_OP_READ_CHR );\n ctxt- chr_access . data = ( void * ) bleprph_appearance ;\n ctxt- chr_access . len = sizeof bleprph_appearance ;\n break ;\n\n case BLE_GAP_CHR_UUID16_PERIPH_PRIV_FLAG :\n assert ( op == BLE_GATT_ACCESS_OP_READ_CHR );\n ctxt- chr_access . data = ( void * ) bleprph_privacy_flag ;\n ctxt- chr_access . len = sizeof bleprph_privacy_flag ;\n break ;\n\n case BLE_GAP_CHR_UUID16_RECONNECT_ADDR :\n a
ssert ( op == BLE_GATT_ACCESS_OP_WRITE_CHR );\n if ( ctxt- chr_access . len != sizeof bleprph_reconnect_addr ) {\n return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN ;\n }\n memcpy ( bleprph_reconnect_addr , ctxt- chr_access . data ,\n sizeof bleprph_reconnect_addr );\n break ;\n\n case BLE_GAP_CHR_UUID16_PERIPH_PREF_CONN_PARAMS :\n assert ( op == BLE_GATT_ACCESS_OP_READ_CHR );\n ctxt- chr_access . data = ( void * ) bleprph_pref_conn_params ;\n ctxt- chr_access . len = sizeof bleprph_pref_conn_params ;\n break ;\n\n default : \n assert ( 0 );\n break ;\n }\n\n return 0 ;\n} After you've taken a moment to examine the structure of this function, let's explore some details.",
+ "title": "Review"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#function-signature",
+ "text": "static int gatt_svr_chr_access_gap ( uint16_t conn_handle , uint16_t attr_handle , uint8_t op ,\n union ble_gatt_access_ctxt *ctxt , void *arg ) A characteristic access function always takes this same set of parameters and\nalways returns an int. The parameters to this function type are documented\nbelow. Parameter Purpose Notes conn_handle Indicates which connection the characteristic access was sent over. Use this value to determine which peer is accessing the characteristic. attr_handle The low-level ATT handle of the characteristic value attribute. Can be used to determine which characteristic is being accessed if you don't want to perform a UUID lookup. op Indicates whether this is a read or write operation Valid values are: BLE_GATT_ACCESS_OP_READ_CHR BLE_GATT_ACCESS_OP_WRITE_CHR ctxt Contains the characteristic value pointer that the application needs to access. For characteristic ac
cesses, use the ctxt- chr_access member; for descriptor accesses, use the ctxt- dsc_access member. The return value of the access function tells the NimBLE stack how to respond\nto the peer performing the operation. A value of 0 indicates success. For\nfailures, the function returns the specific ATT error code that the NimBLE\nstack should respond with. The ATT error codes are defined in net/nimble/host/include/host/ble_att.h .",
+ "title": "Function signature"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#determine-characteristic-being-accessed",
+ "text": "{\n uint16_t uuid16 ;\n\n uuid16 = ble_uuid_128_to_16 ( ctxt- chr_access . chr- uuid128 );\n assert ( uuid16 != 0 );\n\n switch ( uuid16 ) {\n // [...] This function uses the UUID to determine which characteristic is being\naccessed. There are two alternative methods bleprph could have used to\naccomplish this task: Map characteristics to ATT handles during service registration; use the attr_handle parameter as a key into this table during characteristic access. Implement a dedicated function for each characteristic; each function inherently knows which characteristic it corresponds to. All the GAP service characteristics have 16-bit UUIDs, so this function uses\nthe ble_uuid_128_to_16() function to convert the 128-bit UUID to its\ncorresponding 16-bit UUID. This conversion function returns the corresponding\n16-bit UUID on success, or 0 on failure. Success is asserted here to ensure\nthe NimBLE stack is doing i
ts job properly; the stack should only call this\nfunction for accesses to characteristics that it is registered with, and all\nGAP service characteristics have valid 16-bit UUIDs.",
+ "title": "Determine characteristic being accessed"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#read-access",
+ "text": "case BLE_GAP_CHR_UUID16_DEVICE_NAME :\n assert ( op == BLE_GATT_ACCESS_OP_READ_CHR );\n ctxt- chr_access . data = ( void * ) bleprph_device_name ;\n ctxt- chr_access . len = strlen ( bleprph_device_name );\n break ; This code excerpt handles read accesses to the device name characteristic. The assert() here is another case of making sure the NimBLE stack is doing its\njob; this characteristic was registered as read-only, so the stack should have\nprevented write accesses. To fulfill a characteristic read request, the application needs to assign the ctxt- chr_access.data field to point to the attribute data to respond with,\nand fill the ctxt- chr_access.len field with the length of the attribute data. bleprph stores the device name in read-only memory as follows: const char *bleprph_device_name = nimble-bleprph ; The cast to pointer-to-void is a necessary annoyance to remove the const \nqualifier
from the device name variable. You will need to \"cast away const\"\nwhenever you respond to read requests with read-only data. It is not shown in the above snippet, but this function ultimately returns 0.\nBy returning 0, bleprph indicates that the characteristic data in ctxt- chr_access is valid and that NimBLE should include it in its response\nto the peer. A word of warning: The attribute data that ctxt- chr_access.data points to\nmust remain valid after the access function returns, as the NimBLE stack needs\nto use it to form a GATT read response. In other words, you must not\nallocate the characteristic value data on the stack of the access function.\nTwo characteristic accesses never occur at the same time, so it is OK to use\nthe same memory for repeated accesses.",
+ "title": "Read access"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-chr-access/#write-access",
+ "text": "case BLE_GAP_CHR_UUID16_RECONNECT_ADDR :\n assert ( op == BLE_GATT_ACCESS_OP_WRITE_CHR );\n if ( ctxt- chr_access . len != sizeof bleprph_reconnect_addr ) {\n return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN ;\n }\n memcpy ( bleprph_reconnect_addr , ctxt- chr_access . data ,\n sizeof bleprph_reconnect_addr );\n break ; This code excerpt handles writes to the reconnect address characteristic. This\ncharacteristic was registered as write-only, so the assert() here is just a\nsafety precaution to ensure the NimBLE stack is doing its job. For writes, the roles of the ctxt- chr_access.data and ctxt- chr_access.len \nfields are the reverse of the read case. The NimBLE stack uses these fields to\nindicate the data written by the peer. Many characteristics have strict length requirements for write operations.\nThis characteristic has such a restriction; if the written data is not a 48
-bit\nBR address, the application tells NimBLE to respond with an invalid attribute\nvalue length error. For writes, the ctxt- chr_access.data pointer is only valid for the duration\nof the access function. If the application needs to save the written data, it\nshould store it elsewhere before the function returns. In this case, bleprph \nstores the specified address in a global variable called bleprph_reconnect_addr .",
+ "title": "Write access"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-adv/",
+ "text": "BLE Peripheral Project\n\n\nAdvertising\n\n\n\n\nOverview\n\n\nA peripheral announces its presence to the world by broadcasting\nadvertisements. An advertisement typically contains additional information\nabout the peripheral sending it, such as the device name and an abbreviated\nlist of supported services. The presence of this information helps a listening\ncentral to determine whether it is interested in connecting to the peripheral.\nAdvertisements are quite limited in the amount of information they can contain,\nso only the most important information should be included.\n\n\nWhen a listening device receives an advertisement, it can choose to connect to\nthe peripheral, or query the sender for more information. This second action\nis known as an \nactive scan\n. A peripheral responds to an active scan with\nsome extra information that it couldn't fit in its advertisement. This\nadditional information is known as \nscan response data\n. \nbleprph\n does
not\nconfigure any scan response data, so this feature is not discussed in the\nremainder of this tutorial.\n\n\nbleprph\n constantly broadcasts advertisements until a central connects to it.\nWhen a connection is terminated, \nbleprph\n resumes advertising.\n\n\nLet's take a look at \nbleprph\n's advertisement code (\nmain.c\n):\n\n\n\n\n/**\n\n\n * Enables advertising with the following parameters:\n\n\n * o General discoverable mode.\n\n\n * o Undirected connectable mode.\n\n\n */\n\n\nstatic\n \nvoid\n\n\nbleprph_advertise\n(\nvoid\n)\n{\n \nstruct\n \nble_hs_adv_fields\n \nfields\n;\n \nint\n \nrc\n;\n\n \n/* Set the advertisement data included in our advertisements. */\n\n \nmemset\n(\nfields\n, \n0\n, \nsizeof\n \nfields\n);\n \nfields\n.\nname\n \n=\n (\nuint8_t\n \n*\n)\nbleprph_device_name\n;\n \nfields\n.\nname_len\n \n=\n \nstrlen\n(\nbleprph_device_name\n);\n \nfields\n.\nname_is_complete\n \n=\n \n1\n;\n \nrc\n \n=\n \nble_gap_adv_set_f
ields\n(\nfields\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror setting advertisement data; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n\n \n/* Begin advertising. */\n\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_GAP_DISC_MODE_GEN\n, \nBLE_GAP_CONN_MODE_UND\n,\n \nNULL\n, \n0\n, \nNULL\n, \nbleprph_on_connect\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror enabling advertisement; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n}\n\n\n\n\n\nNow let's examine this code in detail.\n\n\n\n\nSetting advertisement data\n\n\nA NimBLE peripheral specifies what information to include in its advertisements with the following function:\n\n\n\n\nint\n\n\nble_gap_adv_set_fields\n(\nstruct\n \nble_hs_adv_fields\n \n*adv_fields\n)\n\n\n\n\n\n\n\nThe \nadv_fields\n argument specifies the fields and their contents to include in\nsubsequent advertisements. The Bluetooth \nCore Spe
cification\nSupplement\n\ndefines a set of standard fields that can be included in an advertisement; the\nmember variables of the \nstruct ble_hs_adv_fields\n type correspond to these\nstandard fields. Information that doesn't fit neatly into a standard field\nshould be put in the \nmanufacturing specific data\n field.\n\n\nAs you can see in the above code listing, the \nstruct ble_hs_adv_fields\n\ninstance is allocated on the stack. It is OK to use the stack for this struct\nand the data it references, as the \nble_gap_adv_set_fields()\n\nfunction makes a copy of all the advertisement data before it returns.\n\nbleprph\n doesn't take full advantange of this; it stores its device name in a\nstatic array.\n\n\nThe code sets three members of the \nstruct ble_hs_adv_fields\n instance:\n\n\n\n\nname\n\n\nname_len\n\n\nname_is_complete\n\n\n\n\nThe first two fields are used to communicate the device's name and are quite\nstraight-forward. The third field requires some explanation. Bl
uetooth\nspecifies two name-related advertisement fields: \nShortened Local Name\n and\n\nComplete Local Name\n. Setting the \nname_is_complete\n variable to 1 or 0 tells\nNimBLE which of these two fields to include in advertisements. Some other\nadvertisement fields also correspond to multiple variables in the field struct,\nso it is a good idea to review the \nble_hs_adv_fields\n reference to\nmake sure you get the details right in your app.\n\n\n\n\nBegin advertising\n\n\nAn app starts advertising with the following function:\n\n\n\n\nint\n\n\nble_gap_adv_start\n(\nuint8_t\n \ndiscoverable_mode\n, \nuint8_t\n \nconnectable_mode\n,\n \nuint8_t\n \n*peer_addr\n, \nuint8_t\n \npeer_addr_type\n,\n \nstruct\n \nhci_adv_params\n \n*adv_params\n,\n \nble_gap_conn_fn\n \n*cb\n, \nvoid\n \n*cb_arg\n)\n\n\n\n\n\nThis function allows a lot of flexibility, and it might seem daunting at first\nglance. \nbleprph\n specifies a simple set of
arguments that is appropriate for\nmost peripherals. When getting started on a typical peripheral, we recommend\nyou use the same arguments as \nbleprph\n, with the exception of the last two\n(\ncb\n and \ncb_arg\n). These last two arguments will be specific to your app, so\nlet's talk about them.\n\n\ncb\n is a callback function. It gets executed when a central connects to your\nperipheral after receiving an advertisement. The \ncb_arg\n argument gets passed\nto the \ncb\n callback. If your callback doesn't need the \ncb_arg\n parameter,\nyou can do what \nbleprph\n does and pass \nNULL\n. Once a connection is\nestablished, the \ncb\n callback becomes permanently associated with the\nconnection. All subsequent events related to the connection are communicated\nto your app via calls to this callback function. Connection callbacks are an\nimportant part of building a BLE app, and we examine \nbleprph\n's connection\ncallback in detail in the next section of this tutorial.\n\n
\n\n\nOne final note:\n Your peripheral automatically stops advertising when a central connects to it. You can immediately resume advertising if you want to allow another central to connect, but you will need to do so explicitly by calling \nble_gap_adv_start()\n again. Also, be aware NimBLE's default configuration only allows a single connection at a time. NimBLE supports multiple concurrent connections, but you must configure it to do so first.",
+ "title": "Advertising"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-adv/#ble-peripheral-project",
+ "text": "",
+ "title": "BLE Peripheral Project"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-adv/#advertising",
+ "text": "",
+ "title": "Advertising"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-adv/#overview",
+ "text": "A peripheral announces its presence to the world by broadcasting\nadvertisements. An advertisement typically contains additional information\nabout the peripheral sending it, such as the device name and an abbreviated\nlist of supported services. The presence of this information helps a listening\ncentral to determine whether it is interested in connecting to the peripheral.\nAdvertisements are quite limited in the amount of information they can contain,\nso only the most important information should be included. When a listening device receives an advertisement, it can choose to connect to\nthe peripheral, or query the sender for more information. This second action\nis known as an active scan . A peripheral responds to an active scan with\nsome extra information that it couldn't fit in its advertisement. This\nadditional information is known as scan response data . bleprph does not\nconfigure any scan response data, so this feature is not discussed
in the\nremainder of this tutorial. bleprph constantly broadcasts advertisements until a central connects to it.\nWhen a connection is terminated, bleprph resumes advertising. Let's take a look at bleprph 's advertisement code ( main.c ): /** * Enables advertising with the following parameters: * o General discoverable mode. * o Undirected connectable mode. */ static void bleprph_advertise ( void )\n{\n struct ble_hs_adv_fields fields ;\n int rc ;\n\n /* Set the advertisement data included in our advertisements. */ \n memset ( fields , 0 , sizeof fields );\n fields . name = ( uint8_t * ) bleprph_device_name ;\n fields . name_len = strlen ( bleprph_device_name );\n fields . name_is_complete = 1 ;\n rc = ble_gap_adv_set_fields ( fields );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error setting advertisement data; rc=%d\\n , rc );\n return ;\n }\n\n /* Begin adverti
sing. */ \n rc = ble_gap_adv_start ( BLE_GAP_DISC_MODE_GEN , BLE_GAP_CONN_MODE_UND ,\n NULL , 0 , NULL , bleprph_on_connect , NULL );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error enabling advertisement; rc=%d\\n , rc );\n return ;\n }\n} Now let's examine this code in detail.",
+ "title": "Overview"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-adv/#setting-advertisement-data",
+ "text": "A NimBLE peripheral specifies what information to include in its advertisements with the following function: int ble_gap_adv_set_fields ( struct ble_hs_adv_fields *adv_fields ) The adv_fields argument specifies the fields and their contents to include in\nsubsequent advertisements. The Bluetooth Core Specification\nSupplement \ndefines a set of standard fields that can be included in an advertisement; the\nmember variables of the struct ble_hs_adv_fields type correspond to these\nstandard fields. Information that doesn't fit neatly into a standard field\nshould be put in the manufacturing specific data field. As you can see in the above code listing, the struct ble_hs_adv_fields \ninstance is allocated on the stack. It is OK to use the stack for this struct\nand the data it references, as the ble_gap_adv_set_fields() \nfunction makes a copy of all the advertisement data before it returns. bleprph doesn't take full advantange of this; it st
ores its device name in a\nstatic array. The code sets three members of the struct ble_hs_adv_fields instance: name name_len name_is_complete The first two fields are used to communicate the device's name and are quite\nstraight-forward. The third field requires some explanation. Bluetooth\nspecifies two name-related advertisement fields: Shortened Local Name and Complete Local Name . Setting the name_is_complete variable to 1 or 0 tells\nNimBLE which of these two fields to include in advertisements. Some other\nadvertisement fields also correspond to multiple variables in the field struct,\nso it is a good idea to review the ble_hs_adv_fields reference to\nmake sure you get the details right in your app.",
+ "title": "Setting advertisement data"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-adv/#begin-advertising",
+ "text": "An app starts advertising with the following function: int ble_gap_adv_start ( uint8_t discoverable_mode , uint8_t connectable_mode ,\n uint8_t *peer_addr , uint8_t peer_addr_type ,\n struct hci_adv_params *adv_params ,\n ble_gap_conn_fn *cb , void *cb_arg ) This function allows a lot of flexibility, and it might seem daunting at first\nglance. bleprph specifies a simple set of arguments that is appropriate for\nmost peripherals. When getting started on a typical peripheral, we recommend\nyou use the same arguments as bleprph , with the exception of the last two\n( cb and cb_arg ). These last two arguments will be specific to your app, so\nlet's talk about them. cb is a callback function. It gets executed when a central connects to your\nperipheral after receiving an advertisement. The cb_arg argument gets passed\nto the cb callback. If your callback doesn't need the c
b_arg parameter,\nyou can do what bleprph does and pass NULL . Once a connection is\nestablished, the cb callback becomes permanently associated with the\nconnection. All subsequent events related to the connection are communicated\nto your app via calls to this callback function. Connection callbacks are an\nimportant part of building a BLE app, and we examine bleprph 's connection\ncallback in detail in the next section of this tutorial. One final note: Your peripheral automatically stops advertising when a central connects to it. You can immediately resume advertising if you want to allow another central to connect, but you will need to do so explicitly by calling ble_gap_adv_start() again. Also, be aware NimBLE's default configuration only allows a single connection at a time. NimBLE supports multiple concurrent connections, but you must configure it to do so first.",
+ "title": "Begin advertising"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-conn/",
+ "text": "BLE Peripheral Project\n\n\nConnection callbacks\n\n\n\n\nOverview\n\n\nEvery BLE connection has a \nconnection callback\n associated with it. A\nconnection callback is a bit of application code which NimBLE uses to inform\nyou of connection-related events. For example, if a connection is terminated,\nNimBLE lets you know about it with a call to that connection's callback.\n\n\nIn the \nadvertising section\n of this tutorial, we saw how the\napplication specifies a connection callback when it begins advertising. NimBLE\nuses this callback to notify the application that a central has connected to\nyour peripheral after receiving an advertisement. Let's revisit how \nbleprph\n specifies its connection callback when advertising:\n\n\n\n\n \n/* Begin advertising. */\n\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_GAP_DISC_MODE_GEN\n, \nBLE_GAP_CONN_MODE_UND\n,\n \nNULL\n, \n0\n, \nNULL\n, \nbleprph_on_connect\n, \nNULL\n);\n \nif\
n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror enabling advertisement; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n\n\n\n\n\n\n\nbleprph_on_connect()\n\n\nThe \nbleprph_on_connect()\n function is \nbleprph\n's connection callback; NimBLE\ncalls this function when the advertising operation leads to connection\nestablishment. Upon connecting, this callback becomes permanently associated\nwith the connection; all subsequent events related to this connection are\ncommunicated through this callback.\n\n\nNow let's look at the function that \nbleprph\n uses for all its connection\ncallbacks: \nbleprph_on_connect()\n.\n\n\nstatic\n \nint\n\n\nbleprph_on_connect\n(\nint\n \nevent\n, \nint\n \nstatus\n, \nstruct\n \nble_gap_conn_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n)\n{\n \nswitch\n (\nevent\n) {\n \ncase\n \nBLE_GAP_EVENT_CONN\n:\n \nBLEPRPH_LOG\n(\nINFO\n, \nconnection %s; status=%d \n,\n \nstatus\n \n==\n \n0\
n \n?\n \nup\n \n:\n \ndown\n, \nstatus\n);\n \nbleprph_print_conn_desc\n(\nctxt-\ndesc\n);\n \nBLEPRPH_LOG\n(\nINFO\n, \n\\n\n);\n\n \nif\n (\nstatus\n \n!=\n \n0\n) {\n \n/* Connection terminated; resume advertising. */\n\n \nbleprph_advertise\n();\n }\n \nbreak\n;\n }\n\n \nreturn\n \n0\n;\n}\n\n\n\n\n\n\n\nConnection callbacks are used to communicate a variety of events related to a\nconnection. An application determines the type of event that occurred by\ninspecting the value of the \nevent\n parameter. The full list of event codes\ncan be found in \nnet/nimble/host/include/host/ble_gatt.h\n.\n\nbleprph\n only concerns itself with a single event type: \nBLE_GAP_EVENT_CONN\n.\nThis event indicates that a new connection has been established, or an existing\nconnection has been terminated; the \nstatus\n parameter clarifies which. As you\ncan see, \nbleprph\n uses the \nstatus\n parameter to determine if it should r
esume\nadvertising.\n\n\nThe \nctxt\n parameter contains additional information about the connection\nevent. \nbleprph\n does nothing more than log some fields of this struct, but\nsome apps will likely want to perform further actions, e.g., perform service\ndiscovery on the connected device. The \nstruct ble_gap_conn_ctxt\n type is\ndefined as follows:\n\n\nstruct\n \nble_gap_conn_ctxt\n {\n \nstruct\n \nble_gap_conn_desc\n \n*desc\n;\n\n \nunion\n {\n \nstruct\n {\n \nstruct\n \nble_gap_upd_params\n \n*self_params\n;\n \nstruct\n \nble_gap_upd_params\n \n*peer_params\n;\n } \nupdate\n;\n\n \nstruct\n \nble_gap_sec_params\n \n*sec_params\n;\n };\n};\n\n\n\n\n\n\n\nAs shown, a connection context object consists of two parts:\n\n\n\n\ndesc:\n The connection descriptor; indicates properties of the connection.\n\n\nanonymous union:\n The contents are event-specific; check the \nevent\n code to determine which member field (if any) i
s relevant.\n\n\n\n\nFor events of type \nBLE_GAP_EVENT_CONN\n, the anonymous union is not used at all, so the only information carried by the context struct is the connection descriptor. The \nstruct ble_gap_conn_desc\n type is defined as follows:\n\n\nstruct\n \nble_gap_conn_desc\n {\n \nuint8_t\n \npeer_addr\n[\n6\n];\n \nuint16_t\n \nconn_handle\n;\n \nuint16_t\n \nconn_itvl\n;\n \nuint16_t\n \nconn_latency\n;\n \nuint16_t\n \nsupervision_timeout\n;\n \nuint8_t\n \npeer_addr_type\n;\n};\n\n\n\n\n\n\n\nWe will examine these fields in a slightly different order from how they appear\nin the struct definition.\n\n\n\n\n\n\n\n\n\n\nField\n\n\nPurpose\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\npeer_addr\n\n\nThe 48-bit address of the peer device.\n\n\n\n\n\n\n\n\npeer_addr_type\n\n\nWhether the peer is using a public or random address.\n\n\nThe address type list is documented in \nnet/nimble/include/nimble/hci_common.h\n.\n\n\n\n\n\n\nconn_handle\n\n\nThe 16-bit handle associa
ted with this connection.\n\n\nThis number is how your app and the NimBLE stack refer to this connection.\n\n\n\n\n\n\nconn_itvl,\nconn_latency,\nsupervision_timeout\n\n\nLow-level properties of the connection.\n\n\n\n\n\n\n\n\n\n\n\n\nGuarantees\n\n\nIt is important to know what your application code is allowed to do from within\na connection callback.\n\n\nNo restrictions on NimBLE operations\n\n\nYour app is free to make calls into the NimBLE stack from within a connection\ncallback. \nbleprph\n takes advantage of this freedom when it resumes\nadvertising upon connection termination. All other NimBLE operations are also\nallowed (service discovery, pairing initiation, etc).\n\n\nAll context data is transient\n\n\nPointers in the context object point to data living on the stack. Your\ncallback is free to read (or write, if appropriate) through these pointers, but\nyou should not store these pointers for later use. If your application needs\nto retain some data from a context o
bject, it needs to make a copy.",
+ "title": "Connection Callbacks"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-conn/#ble-peripheral-project",
+ "text": "",
+ "title": "BLE Peripheral Project"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-conn/#connection-callbacks",
+ "text": "",
+ "title": "Connection callbacks"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-conn/#overview",
+ "text": "Every BLE connection has a connection callback associated with it. A\nconnection callback is a bit of application code which NimBLE uses to inform\nyou of connection-related events. For example, if a connection is terminated,\nNimBLE lets you know about it with a call to that connection's callback. In the advertising section of this tutorial, we saw how the\napplication specifies a connection callback when it begins advertising. NimBLE\nuses this callback to notify the application that a central has connected to\nyour peripheral after receiving an advertisement. Let's revisit how bleprph specifies its connection callback when advertising: /* Begin advertising. */ \n rc = ble_gap_adv_start ( BLE_GAP_DISC_MODE_GEN , BLE_GAP_CONN_MODE_UND ,\n NULL , 0 , NULL , bleprph_on_connect , NULL );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error enabling advertisement; rc=%d\\n , rc );\n re
turn ;\n }",
+ "title": "Overview"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-conn/#bleprph_on_connect",
+ "text": "The bleprph_on_connect() function is bleprph 's connection callback; NimBLE\ncalls this function when the advertising operation leads to connection\nestablishment. Upon connecting, this callback becomes permanently associated\nwith the connection; all subsequent events related to this connection are\ncommunicated through this callback. Now let's look at the function that bleprph uses for all its connection\ncallbacks: bleprph_on_connect() . static int bleprph_on_connect ( int event , int status , struct ble_gap_conn_ctxt *ctxt ,\n void *arg )\n{\n switch ( event ) {\n case BLE_GAP_EVENT_CONN :\n BLEPRPH_LOG ( INFO , connection %s; status=%d ,\n status == 0 ? up : down , status );\n bleprph_print_conn_desc ( ctxt- desc );\n BLEPRPH_LOG ( INFO , \\n );\n\n if ( status != 0 ) {\n /* Connection terminated; resume advertising. */
\n bleprph_advertise ();\n }\n break ;\n }\n\n return 0 ;\n} Connection callbacks are used to communicate a variety of events related to a\nconnection. An application determines the type of event that occurred by\ninspecting the value of the event parameter. The full list of event codes\ncan be found in net/nimble/host/include/host/ble_gatt.h . bleprph only concerns itself with a single event type: BLE_GAP_EVENT_CONN .\nThis event indicates that a new connection has been established, or an existing\nconnection has been terminated; the status parameter clarifies which. As you\ncan see, bleprph uses the status parameter to determine if it should resume\nadvertising. The ctxt parameter contains additional information about the connection\nevent. bleprph does nothing more than log some fields of this struct, but\nsome apps will likely want to perform further actions, e.g., perform service\ndiscovery on the connected device. The
struct ble_gap_conn_ctxt type is\ndefined as follows: struct ble_gap_conn_ctxt {\n struct ble_gap_conn_desc *desc ;\n\n union {\n struct {\n struct ble_gap_upd_params *self_params ;\n struct ble_gap_upd_params *peer_params ;\n } update ;\n\n struct ble_gap_sec_params *sec_params ;\n };\n}; As shown, a connection context object consists of two parts: desc: The connection descriptor; indicates properties of the connection. anonymous union: The contents are event-specific; check the event code to determine which member field (if any) is relevant. For events of type BLE_GAP_EVENT_CONN , the anonymous union is not used at all, so the only information carried by the context struct is the connection descriptor. The struct ble_gap_conn_desc type is defined as follows: struct ble_gap_conn_desc {\n uint8_t peer_addr [ 6 ];\n uint16_t conn_handle ;\n uint16_t conn_itvl ;\n
uint16_t conn_latency ;\n uint16_t supervision_timeout ;\n uint8_t peer_addr_type ;\n}; We will examine these fields in a slightly different order from how they appear\nin the struct definition. Field Purpose Notes peer_addr The 48-bit address of the peer device. peer_addr_type Whether the peer is using a public or random address. The address type list is documented in net/nimble/include/nimble/hci_common.h . conn_handle The 16-bit handle associated with this connection. This number is how your app and the NimBLE stack refer to this connection. conn_itvl, conn_latency, supervision_timeout Low-level properties of the connection.",
+ "title": "bleprph_on_connect()"
+ },
+ {
+ "location": "/os/tutorials/bleprph/bleprph-conn/#guarantees",
+ "text": "It is important to know what your application code is allowed to do from within\na connection callback. No restrictions on NimBLE operations Your app is free to make calls into the NimBLE stack from within a connection\ncallback. bleprph takes advantage of this freedom when it resumes\nadvertising upon connection termination. All other NimBLE operations are also\nallowed (service discovery, pairing initiation, etc). All context data is transient Pointers in the context object point to data living on the stack. Your\ncallback is free to read (or write, if appropriate) through these pointers, but\nyou should not store these pointers for later use. If your application needs\nto retain some data from a context object, it needs to make a copy.",
+ "title": "Guarantees"
+ },
+ {
"location": "/os/os_user_guide/",
"text": "OS User Guide\n\n\nThis guide provides comprehensive information about Mynewt OS, the real-time operating system for embedded systems.\n\n\nIt is intended both for an embedded real-time software developer as well as higher-level applications developer wanting to understand the features and benefits of the system. \n\n\nMynewt OS is highly composable and flexible. Only those features actually used by the application are compiled into the run-time image. Hence, the actual size of Mynewt is completely determined by the application. The guide covers all the features and services available in the OS and contains several examples showing how they can be used.\n\n\nSend us an email on the dev@ mailing list if you have comments or suggestions!\n If you haven't joined the mailing list, you will find the links \nhere\n.",
"title": "toc"
@@ -5417,7 +5572,7 @@
},
{
"location": "/os/modules/hal/hal_uart/hal_uart/",
- "text": "hal_uart\n\n\nThe hardware independent UART interface for Mynewt.\n\n\nDescription\n\n\nContains the basic operations to send and receive data over a UART\n(Universal Asynchronous Receiver Transmitter). \n\n\nDefinition\n\n\nhal_uart.h\n\n\nExamples\n\n\nThis example shows a user writing a character to the uart\n\n\n/* write to the console with blocking */\n{\n char *str = \nHello World!\n;\n char *ptr = str;\n\n while(*ptr++) {\n hal_uart_blocking_tx(MY_UART, *ptr); \n }\n hal_uart_blocking_tx(MY_UART, \n\\n\n); \n}",
+ "text": "hal_uart\n\n\nThe hardware independent UART interface for Mynewt.\n\n\nDescription\n\n\nContains the basic operations to send and receive data over a UART\n(Universal Asynchronous Receiver Transmitter).\n\n\nDefinition\n\n\nhal_uart.h\n\n\nExamples\n\n\nThis example shows a user writing a character to the uart\n\n\n/* write to the console with blocking */\n{\n char *str = \nHello World!\n;\n char *ptr = str;\n\n while(*ptr) {\n hal_uart_blocking_tx(MY_UART, *ptr++);\n }\n hal_uart_blocking_tx(MY_UART, \n\\n\n);\n}",
"title": "UART"
},
{
@@ -5437,7 +5592,7 @@
},
{
"location": "/os/modules/hal/hal_uart/hal_uart/#examples",
- "text": "This example shows a user writing a character to the uart /* write to the console with blocking */\n{\n char *str = Hello World! ;\n char *ptr = str;\n\n while(*ptr++) {\n hal_uart_blocking_tx(MY_UART, *ptr); \n }\n hal_uart_blocking_tx(MY_UART, \\n ); \n}",
+ "text": "This example shows a user writing a character to the uart /* write to the console with blocking */\n{\n char *str = Hello World! ;\n char *ptr = str;\n\n while(*ptr) {\n hal_uart_blocking_tx(MY_UART, *ptr++);\n }\n hal_uart_blocking_tx(MY_UART, \\n );\n}",
"title": "Examples"
},
{
@@ -5477,7 +5632,7 @@
},
{
"location": "/os/modules/testutil/testutil/",
- "text": "testutil\n\n\nThe testutil package is a test framework that provides facilities for specifying test cases and recording test results.\n\n\nYou would use it to build regression tests for your library.\n\n\nDescription\n\n\nA package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its \nsrc/test\n directory. For example, the nffs package's test code is located in the following directory:\n\n\n * fs/nffs/src/test/\n\n\n\n\n\nThis directory contains the source and header files that implement the nffs test code.\n\n\nThe test code has access to all the header files in the following directories:\n\n\n * src\n * src/arch/\ntarget-arch\n\n * include\n * src/test\n * src/test/arch/\ntarget-arch\n\n * include directories of all package dependencies\n\n\n\n\n\nPackage test code typ
ically depends on the testutil package, described later in this document. If a package's test code uses testutil, then the package itself needs to have testutil in its dependency list.\n\n\nSome test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory.\n\n\nWhile building the test code (i.e., when the \ntest\n identity is specified), the newt tool defines the \nTEST\n macro. This macro is defined during compilation of all C source files in all projects and packages.\n\n\nTests are structured according to the following hierarchy:\n\n\n [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case]\n\n\n\n\n\nI.e., a test consists of test suites, and a test suite consists of test cases.\n\n\nThe test code uses testutil to define test suites and test cases.\n\n\nReg
ression test can then be executed using 'newt target test' command, or by including a call to your test suite from \nproject/test/src/test.c\n.\n\n\nExample\n\n\nThis Tutorial\n shows how to create a test suite\nfor a Mynewt package.\n\n\nData structures\n\n\nstruct tu_config {\n int tc_print_results;\n int tc_system_assert;\n\n tu_case_init_fn_t *tc_case_init_cb;\n void *tc_case_init_arg;\n\n tu_case_report_fn_t *tc_case_fail_cb;\n void *tc_case_fail_arg;\n\n tu_case_report_fn_t *tc_case_pass_cb;\n void *tc_case_pass_arg;\n\n tu_suite_init_fn_t *tc_suite_init_cb;\n void *tc_suite_init_arg;\n\n tu_restart_fn_t *tc_restart_cb;\n void *tc_restart_arg;\n};\nextern struct tu_config tu_config;\n\n\n\n\n\nThe global \ntu_config\n struct contains all the testutil package's settings.\nThis should be populated before \ntu_init()\n is called.\n\n\nList of Functions\n\n\n\n\nThe functions, and macros available in \ntestutil\n are:\n\n\n\n\ntu_init\n\n\nTEST_
ASSERT\n\n\nTEST_PASS\n\n\nTEST_SUITE\n\n\nTEST_CASE\n\n\nTEST_CASE_DECL\n\n\ntu_restart",
+ "text": "testutil\n\n\nThe testutil package is a test framework that provides facilities for specifying test cases and recording test results.\n\n\nYou would use it to build regression tests for your library.\n\n\nDescription\n\n\nA package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its \nsrc/test\n directory. For example, the nffs package's test code is located in the following directory:\n\n\n * fs/nffs/src/test/\n\n\n\n\n\nThis directory contains the source and header files that implement the nffs test code.\n\n\nThe test code has access to all the header files in the following directories:\n\n\n * src\n * src/arch/\ntarget-arch\n\n * include\n * src/test\n * src/test/arch/\ntarget-arch\n\n * include directories of all package dependencies\n\n\n\n\n\nPackage test code typ
ically depends on the testutil package, described later in this document.\n\n\nSome test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory.\n\n\nWhile building the test code (i.e., when the \ntest\n identity is specified), the newt tool defines the \nTEST\n macro. This macro is defined during compilation of all C source files in all projects and packages.\n\n\nTests are structured according to the following hierarchy:\n\n\n [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case]\n\n\n\n\n\nI.e., a test consists of test suites, and a test suite consists of test cases.\n\n\nThe test code uses testutil to define test suites and test cases.\n\n\nRegression test can then be executed using 'newt target test' command, or by including a call to your test suite fr
om \nproject/test/src/test.c\n.\n\n\nExample\n\n\nThis Tutorial\n shows how to create a test suite\nfor a Mynewt package.\n\n\nData structures\n\n\nstruct tu_config {\n int tc_print_results;\n int tc_system_assert;\n\n tu_case_init_fn_t *tc_case_init_cb;\n void *tc_case_init_arg;\n\n tu_case_report_fn_t *tc_case_fail_cb;\n void *tc_case_fail_arg;\n\n tu_case_report_fn_t *tc_case_pass_cb;\n void *tc_case_pass_arg;\n\n tu_suite_init_fn_t *tc_suite_init_cb;\n void *tc_suite_init_arg;\n\n tu_restart_fn_t *tc_restart_cb;\n void *tc_restart_arg;\n};\nextern struct tu_config tu_config;\n\n\n\n\n\nThe global \ntu_config\n struct contains all the testutil package's settings.\nThis should be populated before \ntu_init()\n is called.\n\n\nList of Functions\n\n\n\n\nThe functions, and macros available in \ntestutil\n are:\n\n\n\n\ntu_init\n\n\nTEST_ASSERT\n\n\nTEST_PASS\n\n\nTEST_SUITE\n\n\nTEST_CASE\n\n\nTEST_CASE_DECL\n\n\ntu_restart",
"title": "toc"
},
{
@@ -5487,7 +5642,7 @@
},
{
"location": "/os/modules/testutil/testutil/#description",
- "text": "A package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its src/test directory. For example, the nffs package's test code is located in the following directory: * fs/nffs/src/test/ This directory contains the source and header files that implement the nffs test code. The test code has access to all the header files in the following directories: * src\n * src/arch/ target-arch \n * include\n * src/test\n * src/test/arch/ target-arch \n * include directories of all package dependencies Package test code typically depends on the testutil package, described later in this document. If a package's test code uses testutil, then the package itself needs to have testutil in its dependency list. Some test cases or test initialization code may be platform-specific. In
such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory. While building the test code (i.e., when the test identity is specified), the newt tool defines the TEST macro. This macro is defined during compilation of all C source files in all projects and packages. Tests are structured according to the following hierarchy: [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case] I.e., a test consists of test suites, and a test suite consists of test cases. The test code uses testutil to define test suites and test cases. Regression test can then be executed using 'newt target test' command, or by including a call to your test suite from project/test/src/test.c .",
+ "text": "A package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its src/test directory. For example, the nffs package's test code is located in the following directory: * fs/nffs/src/test/ This directory contains the source and header files that implement the nffs test code. The test code has access to all the header files in the following directories: * src\n * src/arch/ target-arch \n * include\n * src/test\n * src/test/arch/ target-arch \n * include directories of all package dependencies Package test code typically depends on the testutil package, described later in this document. Some test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package tes
t directory. While building the test code (i.e., when the test identity is specified), the newt tool defines the TEST macro. This macro is defined during compilation of all C source files in all projects and packages. Tests are structured according to the following hierarchy: [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case] I.e., a test consists of test suites, and a test suite consists of test cases. The test code uses testutil to define test suites and test cases. Regression test can then be executed using 'newt target test' command, or by including a call to your test suite from project/test/src/test.c .",
"title": "Description"
},
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/modules/hal/hal_uart/hal_uart/index.html
----------------------------------------------------------------------
diff --git a/os/modules/hal/hal_uart/hal_uart/index.html b/os/modules/hal/hal_uart/hal_uart/index.html
index 721f8ca..1f34bf4 100644
--- a/os/modules/hal/hal_uart/hal_uart/index.html
+++ b/os/modules/hal/hal_uart/hal_uart/index.html
@@ -700,7 +700,7 @@
<p>The hardware independent UART interface for Mynewt.</p>
<h3 id="description">Description<a class="headerlink" href="#description" title="Permanent link">¶</a></h3>
<p>Contains the basic operations to send and receive data over a UART
-(Universal Asynchronous Receiver Transmitter). </p>
+(Universal Asynchronous Receiver Transmitter).</p>
<h3 id="definition">Definition<a class="headerlink" href="#definition" title="Permanent link">¶</a></h3>
<p><a href="https://github.com/apache/incubator-mynewt-larva/blob/master/hw/hal/include/hal/hal_uart.h">hal_uart.h</a></p>
<h3 id="examples">Examples<a class="headerlink" href="#examples" title="Permanent link">¶</a></h3>
@@ -710,10 +710,10 @@
char *str = "Hello World!";
char *ptr = str;
- while(*ptr++) {
- hal_uart_blocking_tx(MY_UART, *ptr);
+ while(*ptr) {
+ hal_uart_blocking_tx(MY_UART, *ptr++);
}
- hal_uart_blocking_tx(MY_UART, '\n');
+ hal_uart_blocking_tx(MY_UART, '\n');
}
</pre></div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/modules/testutil/testutil/index.html
----------------------------------------------------------------------
diff --git a/os/modules/testutil/testutil/index.html b/os/modules/testutil/testutil/index.html
index 58e8213..840b151 100644
--- a/os/modules/testutil/testutil/index.html
+++ b/os/modules/testutil/testutil/index.html
@@ -568,7 +568,7 @@ when the "test" identity is specified. All of a package's test code goes in its
</pre></div>
-<p>Package test code typically depends on the testutil package, described later in this document. If a package's test code uses testutil, then the package itself needs to have testutil in its dependency list.</p>
+<p>Package test code typically depends on the testutil package, described later in this document.</p>
<p>Some test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory.</p>
<p>While building the test code (i.e., when the <code>test</code> identity is specified), the newt tool defines the <code>TEST</code> macro. This macro is defined during compilation of all C source files in all projects and packages.</p>
<p>Tests are structured according to the following hierarchy:</p>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/os_user_guide/index.html
----------------------------------------------------------------------
diff --git a/os/os_user_guide/index.html b/os/os_user_guide/index.html
index 1b70c3a..fd8cb9b 100644
--- a/os/os_user_guide/index.html
+++ b/os/os_user_guide/index.html
@@ -543,9 +543,9 @@
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
- <a href=../tutorials/event_queue/>
+ <a href=../tutorials/bleprph/bleprph-conn/>
<span class="fa fa-arrow-left"></span>
- Previous: Add task to manage multiple events
+ Previous: Connection Callbacks
</a>
</li>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/STM32F303/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/STM32F303/index.html b/os/tutorials/STM32F303/index.html
index 368a1cf..e38616a 100644
--- a/os/tutorials/STM32F303/index.html
+++ b/os/tutorials/STM32F303/index.html
@@ -370,6 +370,17 @@
+
+
+
+
+ <li ><a href="../bleprph/bleprph-intro/">BLE peripheral project</a></li>
+
+
+ </li>
+
+
+
</ul>
</li>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/add_repos/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/add_repos/index.html b/os/tutorials/add_repos/index.html
index 4cc331e..ddd7119 100644
--- a/os/tutorials/add_repos/index.html
+++ b/os/tutorials/add_repos/index.html
@@ -370,6 +370,17 @@
+
+
+
+
+ <li ><a href="../bleprph/bleprph-intro/">BLE peripheral project</a></li>
+
+
+ </li>
+
+
+
</ul>
</li>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/air_quality_sensor/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/air_quality_sensor/index.html b/os/tutorials/air_quality_sensor/index.html
index e1b9049..8bf0652 100644
--- a/os/tutorials/air_quality_sensor/index.html
+++ b/os/tutorials/air_quality_sensor/index.html
@@ -370,6 +370,17 @@
+
+
+
+
+ <li ><a href="../bleprph/bleprph-intro/">BLE peripheral project</a></li>
+
+
+ </li>
+
+
+
</ul>
</li>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/arduino_zero/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/arduino_zero/index.html b/os/tutorials/arduino_zero/index.html
index 2be2df4..03ce87d 100644
--- a/os/tutorials/arduino_zero/index.html
+++ b/os/tutorials/arduino_zero/index.html
@@ -370,6 +370,17 @@
+
+
+
+
+ <li ><a href="../bleprph/bleprph-intro/">BLE peripheral project</a></li>
+
+
+ </li>
+
+
+
</ul>
</li>