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/08/10 00:10:40 UTC
[2/6] incubator-mynewt-site git commit: Additions to ble app
documentation by ccollins476ad. This closes #110.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bdf51006/develop/os/tutorials/bleprph/bleprph-adv/index.html
----------------------------------------------------------------------
diff --git a/develop/os/tutorials/bleprph/bleprph-adv/index.html b/develop/os/tutorials/bleprph/bleprph-adv/index.html
index fa97e6e..b706a7f 100644
--- a/develop/os/tutorials/bleprph/bleprph-adv/index.html
+++ b/develop/os/tutorials/bleprph/bleprph-adv/index.html
@@ -340,7 +340,7 @@
<li >
- <a href="../bleprph-conn/">Connection Callbacks</a>
+ <a href="../bleprph-gap-event/">GAP Event Callbacks</a>
</li>
@@ -501,14 +501,43 @@ When a connection is terminated, <em>bleprph</em> resumes advertising.</p>
<span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span>
<span style="color: #000000">bleprph_advertise</span>(<span style="color: #A90D91">void</span>)
{
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_adv_params</span> <span style="color: #000000">adv_params</span>;
<span style="color: #A90D91">struct</span> <span style="color: #000000">ble_hs_adv_fields</span> <span style="color: #000000">fields</span>;
+ <span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*name</span>;
<span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
- <span style="color: #177500">/* Set the advertisement data included in our advertisements. */</span>
+ <span style="color: #177500">/**</span>
+<span style="color: #177500"> * Set the advertisement data included in our advertisements:</span>
+<span style="color: #177500"> * o Flags (indicates advertisement type and other general info).</span>
+<span style="color: #177500"> * o Advertising tx power.</span>
+<span style="color: #177500"> * o Device name.</span>
+<span style="color: #177500"> * o 16-bit service UUIDs (alert notifications).</span>
+<span style="color: #177500"> */</span>
+
<span style="color: #000000">memset</span>(<span style="color: #000000">&fields</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">sizeof</span> <span style="color: #000000">fields</span>);
- <span style="color: #000000">fields</span>.<span style="color: #000000">name</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">*</span>)<span style="color: #000000">bleprph_device_name</span>;
- <span style="color: #000000">fields</span>.<span style="color: #000000">name_len</span> <span style="color: #000000">=</span> <span style="color: #000000">strlen</span>(<span style="color: #000000">bleprph_device_name</span>);
+
+ <span style="color: #177500">/* Indicate that the flags field should be included; specify a value of 0</span>
+<span style="color: #177500"> * to instruct the stack to fill the value in for us.</span>
+<span style="color: #177500"> */</span>
+ <span style="color: #000000">fields</span>.<span style="color: #000000">flags_is_present</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
+ <span style="color: #000000">fields</span>.<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0</span>;
+
+ <span style="color: #177500">/* Indicate that the TX power level field should be included; have the</span>
+<span style="color: #177500"> * stack fill this one automatically as well. This is done by assiging the</span>
+<span style="color: #177500"> * special value BLE_HS_ADV_TX_PWR_LVL_AUTO.</span>
+<span style="color: #177500"> */</span>
+ <span style="color: #000000">fields</span>.<span style="color: #000000">tx_pwr_lvl_is_present</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
+ <span style="color: #000000">fields</span>.<span style="color: #000000">tx_pwr_lvl</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_HS_ADV_TX_PWR_LVL_AUTO</span>;
+
+ <span style="color: #000000">name</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_svc_gap_device_name</span>();
+ <span style="color: #000000">fields</span>.<span style="color: #000000">name</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">*</span>)<span style="color: #000000">name</span>;
+ <span style="color: #000000">fields</span>.<span style="color: #000000">name_len</span> <span style="color: #000000">=</span> <span style="color: #000000">strlen</span>(<span style="color: #000000">name</span>);
<span style="color: #000000">fields</span>.<span style="color: #000000">name_is_complete</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
+
+ <span style="color: #000000">fields</span>.<span style="color: #000000">uuids16</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">uint16_t</span>[]){ <span style="color: #000000">GATT_SVR_SVC_ALERT_UUID</span> };
+ <span style="color: #000000">fields</span>.<span style="color: #000000">num_uuids16</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
+ <span style="color: #000000">fields</span>.<span style="color: #000000">uuids16_is_complete</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
+
<span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_adv_set_fields</span>(<span style="color: #000000">&fields</span>);
<span style="color: #A90D91">if</span> (<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">ERROR</span>, <span style="color: #C41A16">"error setting advertisement data; rc=%d\n"</span>, <span style="color: #000000">rc</span>);
@@ -516,8 +545,11 @@ When a connection is terminated, <em>bleprph</em> resumes advertising.</p>
}
<span style="color: #177500">/* Begin advertising. */</span>
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_adv_start</span>(<span style="color: #000000">BLE_GAP_DISC_MODE_GEN</span>, <span style="color: #000000">BLE_GAP_CONN_MODE_UND</span>,
- <span style="color: #A90D91">NULL</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">NULL</span>, <span style="color: #000000">bleprph_on_connect</span>, <span style="color: #A90D91">NULL</span>);
+ <span style="color: #000000">memset</span>(<span style="color: #000000">&adv_params</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">sizeof</span> <span style="color: #000000">adv_params</span>);
+ <span style="color: #000000">adv_params</span>.<span style="color: #000000">conn_mode</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GAP_CONN_MODE_UND</span>;
+ <span style="color: #000000">adv_params</span>.<span style="color: #000000">disc_mode</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GAP_DISC_MODE_GEN</span>;
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_adv_start</span>(<span style="color: #000000">BLE_ADDR_TYPE_PUBLIC</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">NULL</span>, <span style="color: #000000">BLE_HS_FOREVER</span>,
+ <span style="color: #000000">&adv_params</span>, <span style="color: #000000">bleprph_gap_event</span>, <span style="color: #A90D91">NULL</span>);
<span style="color: #A90D91">if</span> (<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">ERROR</span>, <span style="color: #C41A16">"error enabling advertisement; rc=%d\n"</span>, <span style="color: #000000">rc</span>);
<span style="color: #A90D91">return</span>;
@@ -529,15 +561,8 @@ When a connection is terminated, <em>bleprph</em> resumes advertising.</p>
<p>Now let's examine this code in detail.</p>
<p><br></p>
<h4 id="setting-advertisement-data">Setting advertisement data</h4>
-<p>A NimBLE peripheral specifies what information to include in its advertisements with the following function:</p>
-<p><br></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">int</span>
-<span style="color: #000000">ble_gap_adv_set_fields</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">ble_hs_adv_fields</span> <span style="color: #000000">*adv_fields</span>)
-</pre></div>
-
-
-<p><br></p>
-<p>The <em>adv_fields</em> argument specifies the fields and their contents to include in
+<p>A NimBLE peripheral specifies what information to include in its advertisements with the <a href="../../../../network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields/">ble_gap_adv_set_fields()</a> function.</p>
+<p>The <em>fields</em> argument specifies the fields and their contents to include in
subsequent advertisements. The Bluetooth <a href="https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=302735">Core Specification
Supplement</a>
defines a set of standard fields that can be included in an advertisement; the
@@ -550,49 +575,42 @@ and the data it references, as the <code>ble_gap_adv_set_fields()</code>
function makes a copy of all the advertisement data before it returns.
<em>bleprph</em> doesn't take full advantange of this; it stores its device name in a
static array.</p>
-<p>The code sets three members of the <em>struct ble_hs_adv_fields</em> instance:</p>
-<ul>
-<li>name</li>
-<li>name_len</li>
-<li>name_is_complete</li>
-</ul>
-<p>The first two fields are used to communicate the device's name and are quite
-straight-forward. The third field requires some explanation. Bluetooth
-specifies two name-related advertisement fields: <em>Shortened Local Name</em> and
-<em>Complete Local Name</em>. Setting the <code>name_is_complete</code> variable to 1 or 0 tells
-NimBLE which of these two fields to include in advertisements. Some other
-advertisement fields also correspond to multiple variables in the field struct,
-so it is a good idea to review the <em>ble_hs_adv_fields</em> reference to
-make sure you get the details right in your app.</p>
+<p>The code sets several members of the <em>struct ble_hs_adv_fields</em> instance. Most
+of them are quite straight-forward. However, the <em>name_is_complete</em> field
+requires some explanation. Bluetooth specifies two name-related advertisement
+fields: <em>Shortened Local Name</em> and <em>Complete Local Name</em>. Setting the
+<code>name_is_complete</code> variable to 1 or 0 tells NimBLE which of these two fields to
+include in advertisements. Some other advertisement fields also correspond to
+multiple variables in the field struct, so it is a good idea to review the
+<em>ble_hs_adv_fields</em> reference to make sure you get the details right in your
+app.</p>
<p><br></p>
<h4 id="begin-advertising">Begin advertising</h4>
-<p>An app starts advertising with the following function:</p>
-<p><br></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">int</span>
-<span style="color: #000000">ble_gap_adv_start</span>(<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">discoverable_mode</span>, <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">connectable_mode</span>,
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">*peer_addr</span>, <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">peer_addr_type</span>,
- <span style="color: #A90D91">struct</span> <span style="color: #000000">hci_adv_params</span> <span style="color: #000000">*adv_params</span>,
- <span style="color: #000000">ble_gap_conn_fn</span> <span style="color: #000000">*cb</span>, <span style="color: #A90D91">void</span> <span style="color: #000000">*cb_arg</span>)
-</pre></div>
-
-
-<p>This function allows a lot of flexibility, and it might seem daunting at first
-glance. <em>bleprph</em> specifies a simple set of arguments that is appropriate for
-most peripherals. When getting started on a typical peripheral, we recommend
-you use the same arguments as <em>bleprph</em>, with the exception of the last two
-(<em>cb</em> and <em>cb_arg</em>). These last two arguments will be specific to your app, so
-let's talk about them.</p>
+<p>An app starts advertising with
+<a href="../../../../network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start/">ble_gap_adv_start()</a>
+function. This function allows a lot of flexibility, and it might seem
+daunting at first glance. <em>bleprph</em> specifies a simple set of arguments that
+is appropriate for most peripherals. When getting started on a typical
+peripheral, we recommend you use the same arguments as <em>bleprph</em>, with the
+exception of the last two (<em>cb</em> and <em>cb_arg</em>; <em>bleprph_gap_event</em> and <em>NULL</em> in
+this case). These last two arguments will be specific to your app, so let's
+talk about them.</p>
<p><em>cb</em> is a callback function. It gets executed when a central connects to your
peripheral after receiving an advertisement. The <em>cb_arg</em> argument gets passed
to the <em>cb</em> callback. If your callback doesn't need the <em>cb_arg</em> parameter,
you can do what <em>bleprph</em> does and pass <em>NULL</em>. Once a connection is
established, the <em>cb</em> callback becomes permanently associated with the
connection. All subsequent events related to the connection are communicated
-to your app via calls to this callback function. Connection callbacks are an
+to your app via calls to this callback function. GAP event callbacks are an
important part of building a BLE app, and we examine <em>bleprph</em>'s connection
callback in detail in the next section of this tutorial.</p>
<p><br></p>
-<p><strong>One final note:</strong> 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 <code>ble_gap_adv_start()</code> 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.</p>
+<p><strong>One final note:</strong> 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 <code>ble_gap_adv_start()</code> 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.</p>
<div class="row">
@@ -610,8 +628,8 @@ callback in detail in the next section of this tutorial.</p>
</li>
<li class="pull-right">
- <a href=../bleprph-conn/>
- Next: Connection Callbacks
+ <a href=../bleprph-gap-event/>
+ Next: GAP Event Callbacks
<span class="fa fa-arrow-right"></span>
</a>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bdf51006/develop/os/tutorials/bleprph/bleprph-chr-access/index.html
----------------------------------------------------------------------
diff --git a/develop/os/tutorials/bleprph/bleprph-chr-access/index.html b/develop/os/tutorials/bleprph/bleprph-chr-access/index.html
index 1a24b5a..86ab9d8 100644
--- a/develop/os/tutorials/bleprph/bleprph-chr-access/index.html
+++ b/develop/os/tutorials/bleprph/bleprph-chr-access/index.html
@@ -340,7 +340,7 @@
<li >
- <a href="../bleprph-conn/">Connection Callbacks</a>
+ <a href="../bleprph-gap-event/">GAP Event Callbacks</a>
</li>
@@ -480,84 +480,71 @@ services and characteristics are registered with NimBLE via attribute tables.
Each characteristic definition in an attribute table contains an <em>access_cb</em>
field. The <em>access_cb</em> field is an application callback that gets executed
whenever a peer device attempts to read or write the characteristic.</p>
-<p>Earlier in this tutorial, we looked at how <em>bleprph</em> implements the GAP
+<p>Earlier in this tutorial, we looked at how <em>bleprph</em> implements the ANS
service. Let's take another look at how <em>bleprph</em> specifies the first few
characteristics in this service.</p>
<p><br></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">const</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_svc_def</span> <span style="color: #000000">gatt_svr_svcs</span>[] <span style="color: #000000">=</span> {
{
- <span style="color: #177500">/*** Service: GAP. */</span>
- .<span style="color: #000000">type</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_SVC_TYPE_PRIMARY</span>,
- .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">BLE_GAP_SVC_UUID16</span>),
- .<span style="color: #000000">characteristics</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_chr_def</span>[]) { {
- <span style="color: #177500">/*** Characteristic: Device Name. */</span>
- .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">BLE_GAP_CHR_UUID16_DEVICE_NAME</span>),
- .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_access_gap</span>,
- .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_READ</span>,
+ <span style="color: #177500">/*** Alert Notification Service. */</span>
+ .<span style="color: #000000">type</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_SVC_TYPE_PRIMARY</span>,
+ .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">GATT_SVR_SVC_ALERT_UUID</span>),
+ .<span style="color: #000000">characteristics</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_chr_def</span>[]) { {
+ .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID</span>),
+ .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_access_alert</span>,
+ .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_READ</span>,
}, {
- <span style="color: #177500">/*** Characteristic: Appearance. */</span>
- .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">BLE_GAP_CHR_UUID16_APPEARANCE</span>),
- .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_access_gap</span>,
- .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_READ</span>,
+ .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">GATT_SVR_CHR_NEW_ALERT</span>),
+ .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_access_alert</span>,
+ .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_NOTIFY</span>,
}, {
<span style="color: #177500">// [...]</span>
</pre></div>
-<p>As you can see, <em>bleprph</em> uses the same <em>access_cb</em> function for all the GAP
+<p>As you can see, <em>bleprph</em> uses the same <em>access_cb</em> function for all the ANS
service characteristics, but the developer could have implemented separate
-functions for each characteristic if they preferred. Here is the <em>access_cb</em>
-function that the GAP service characteristics use:</p>
+functions for each characteristic if they preferred. Here is part of the
+<em>access_cb</em> function that the ANS service characteristics use:</p>
<p><br></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span>
-<span style="color: #000000">gatt_svr_chr_access_gap</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</span>, <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">attr_handle</span>, <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">op</span>,
- <span style="color: #A90D91">union</span> <span style="color: #000000">ble_gatt_access_ctxt</span> <span style="color: #000000">*ctxt</span>, <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
+<span style="color: #000000">gatt_svr_chr_access_alert</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</span>, <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">attr_handle</span>,
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_access_ctxt</span> <span style="color: #000000">*ctxt</span>,
+ <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
{
<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">uuid16</span>;
+ <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
- <span style="color: #000000">uuid16</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_uuid_128_to_16</span>(<span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">chr->uuid128</span>);
+ <span style="color: #000000">uuid16</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_uuid_128_to_16</span>(<span style="color: #000000">ctxt->chr->uuid128</span>);
<span style="color: #000000">assert</span>(<span style="color: #000000">uuid16</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
<span style="color: #A90D91">switch</span> (<span style="color: #000000">uuid16</span>) {
- <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_DEVICE_NAME</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">void</span> <span style="color: #000000">*</span>)<span style="color: #000000">bleprph_device_name</span>;
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">=</span> <span style="color: #000000">strlen</span>(<span style="color: #000000">bleprph_device_name</span>);
- <span style="color: #A90D91">break</span>;
-
- <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_APPEARANCE</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">void</span> <span style="color: #000000">*</span>)<span style="color: #000000">&bleprph_appearance</span>;
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_appearance</span>;
- <span style="color: #A90D91">break</span>;
-
- <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_PERIPH_PRIV_FLAG</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">void</span> <span style="color: #000000">*</span>)<span style="color: #000000">&bleprph_privacy_flag</span>;
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_privacy_flag</span>;
- <span style="color: #A90D91">break</span>;
-
- <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_RECONNECT_ADDR</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_WRITE_CHR</span>);
- <span style="color: #A90D91">if</span> (<span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">!=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_reconnect_addr</span>) {
- <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN</span>;
- }
- <span style="color: #000000">memcpy</span>(<span style="color: #000000">bleprph_reconnect_addr</span>, <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span>,
- <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_reconnect_addr</span>);
- <span style="color: #A90D91">break</span>;
-
- <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_PERIPH_PREF_CONN_PARAMS</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">void</span> <span style="color: #000000">*</span>)<span style="color: #000000">&bleprph_pref_conn_params</span>;
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_pref_conn_params</span>;
- <span style="color: #A90D91">break</span>;
+ <span style="color: #A90D91">case</span> <span style="color: #000000">GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID</span>:
+ <span style="color: #000000">assert</span>(<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">os_mbuf_append</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #000000">&gatt_svr_new_alert_cat</span>,
+ <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_svr_new_alert_cat</span>);
+ <span style="color: #A90D91">return</span> <span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">?</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">:</span> <span style="color: #000000">BLE_ATT_ERR_INSUFFICIENT_RES</span>;
+
+ <span style="color: #A90D91">case</span> <span style="color: #000000">GATT_SVR_CHR_UNR_ALERT_STAT_UUID</span>:
+ <span style="color: #A90D91">if</span> (<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_WRITE_CHR</span>) {
+ <span style="color: #A90D91">if</span> (<span style="color: #000000">OS_MBUF_PKTLEN</span>(<span style="color: #000000">ctxt->om</span>) <span style="color: #000000">!=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_svr_unr_alert_stat</span>) {
+ <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN</span>;
+ }
+
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_hs_mbuf_to_flat</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #000000">&gatt_svr_unr_alert_stat</span>,
+ <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_svr_unr_alert_stat</span>, <span style="color: #A90D91">NULL</span>);
+ <span style="color: #A90D91">if</span> (<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
+ <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_UNLIKELY</span>;
+ }
+
+ <span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
+
+ <span style="color: #177500">/* [...] */</span>
<span style="color: #A90D91">default</span><span style="color: #000000">:</span>
<span style="color: #000000">assert</span>(<span style="color: #1C01CE">0</span>);
- <span style="color: #A90D91">break</span>;
+ <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_UNLIKELY</span>;
}
-
- <span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
}
</pre></div>
@@ -565,17 +552,16 @@ function that the GAP service characteristics use:</p>
<p>After you've taken a moment to examine the structure of this function, let's explore some details.</p>
<p><br></p>
<h4 id="function-signature">Function signature</h4>
-<p><br></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span>
-<span style="color: #000000">gatt_svr_chr_access_gap</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</span>, <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">attr_handle</span>, <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">op</span>,
- <span style="color: #A90D91">union</span> <span style="color: #000000">ble_gatt_access_ctxt</span> <span style="color: #000000">*ctxt</span>, <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
+<span style="color: #000000">gatt_svr_chr_access_alert</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</span>, <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">attr_handle</span>,
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_access_ctxt</span> <span style="color: #000000">*ctxt</span>,
+ <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
</pre></div>
<p>A characteristic access function always takes this same set of parameters and
always returns an int. The parameters to this function type are documented
below.</p>
-<p><br></p>
<table>
<thead>
<tr>
@@ -602,23 +588,21 @@ below.</p>
</tr>
<tr>
<td>ctxt</td>
-<td>Contains the characteristic value pointer that the application needs to access.</td>
-<td>For characteristic accesses, use the <em>ctxt->chr_access</em> member; for descriptor accesses, use the <em>ctxt->dsc_access</em> member.</td>
+<td>Contains the characteristic value mbuf that the application needs to access.</td>
+<td>For characteristic accesses, use the <em>ctxt->chr</em> member; for descriptor accesses, use the <em>ctxt->dsc</em> member.</td>
</tr>
</tbody>
</table>
<p>The return value of the access function tells the NimBLE stack how to respond
to the peer performing the operation. A value of 0 indicates success. For
-failures, the function returns the specific ATT error code that the NimBLE
-stack should respond with. The ATT error codes are defined in
-<a href="https://github.com/apache/incubator-mynewt-core/blob/master/net/nimble/host/include/host/ble_att.h">net/nimble/host/include/host/ble_att.h</a>.</p>
+failures, the function returns the specific <a href="../../../../network/ble/ble_hs/ble_hs_return_codes/#return-codes-att">ATT error code</a> that the NimBLE
+stack should respond with. <em>Note:</em> The return code is a formal code, <strong>not</strong> a NimBLE value!</p>
<p><br></p>
<h4 id="determine-characteristic-being-accessed">Determine characteristic being accessed</h4>
-<p><br></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">{
<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">uuid16</span>;
- <span style="color: #000000">uuid16</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_uuid_128_to_16</span>(<span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">chr->uuid128</span>);
+ <span style="color: #000000">uuid16</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_uuid_128_to_16</span>(<span style="color: #000000">ctxt->chr->uuid128</span>);
<span style="color: #000000">assert</span>(<span style="color: #000000">uuid16</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
<span style="color: #A90D91">switch</span> (<span style="color: #000000">uuid16</span>) {
@@ -633,80 +617,68 @@ accomplish this task:</p>
<li>Map characteristics to ATT handles during service registration; use the <em>attr_handle</em> parameter as a key into this table during characteristic access.</li>
<li>Implement a dedicated function for each characteristic; each function inherently knows which characteristic it corresponds to.</li>
</ul>
-<p>All the GAP service characteristics have 16-bit UUIDs, so this function uses
+<p>All the ANS service characteristics have 16-bit UUIDs, so this function uses
the <em>ble_uuid_128_to_16()</em> function to convert the 128-bit UUID to its
corresponding 16-bit UUID. This conversion function returns the corresponding
16-bit UUID on success, or 0 on failure. Success is asserted here to ensure
the NimBLE stack is doing its job properly; the stack should only call this
function for accesses to characteristics that it is registered with, and all
-GAP service characteristics have valid 16-bit UUIDs.</p>
+ANS service characteristics have valid 16-bit UUIDs.</p>
<p><br></p>
<h4 id="read-access">Read access</h4>
-<p><br></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_DEVICE_NAME</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">void</span> <span style="color: #000000">*</span>)<span style="color: #000000">bleprph_device_name</span>;
- <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">=</span> <span style="color: #000000">strlen</span>(<span style="color: #000000">bleprph_device_name</span>);
- <span style="color: #A90D91">break</span>;
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">case</span> <span style="color: #000000">GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID</span>:
+ <span style="color: #000000">assert</span>(<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>);
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">os_mbuf_append</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #000000">&gatt_svr_new_alert_cat</span>,
+ <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_svr_new_alert_cat</span>);
+ <span style="color: #A90D91">return</span> <span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">?</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">:</span> <span style="color: #000000">BLE_ATT_ERR_INSUFFICIENT_RES</span>;
</pre></div>
-<p>This code excerpt handles read accesses to the device name characteristic. The
-<em>assert()</em> here is another case of making sure the NimBLE stack is doing its
-job; this characteristic was registered as read-only, so the stack should have
-prevented write accesses.</p>
-<p>To fulfill a characteristic read request, the application needs to assign the
-<em>ctxt->chr_access.data</em> field to point to the attribute data to respond with,
-and fill the <em>ctxt->chr_access.len</em> field with the length of the attribute data.
-<em>bleprph</em> stores the device name in read-only memory as follows:</p>
+<p>This code excerpt handles read accesses to the Supported New Alert Category
+characteristic. The <em>assert()</em> here is another case of making sure the NimBLE
+stack is doing its job; this characteristic was registered as read-only, so the
+stack should have prevented write accesses.</p>
+<p>To fulfill a characteristic read request, the application needs fill a buffer (<em>om</em>) with the characteristic value. The NimBLE host will then include the contents of this buffer in its read response. NimBLE uses <a href="../../../../os/core_os/mbuf/mbuf">mbufs</a> to exchange data between itself and the application. To fill an mbuf with data that is available in a contiguous chunk of memory, the <em>os_mbuf_append()</em> function suffices. The source of the data, <em>gatt_svr_new_alert_cat</em>, is is stored in read-only memory as follows:</p>
<p><br></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*bleprph_device_name</span> <span style="color: #000000">=</span> <span style="color: #C41A16">"nimble-bleprph"</span>;
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">const</span> <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">gatt_svr_new_alert_cat</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0x01</span>; <span style="color: #177500">/* Simple alert. */</span>
</pre></div>
-<p>The cast to pointer-to-void is a necessary annoyance to remove the <em>const</em>
-qualifier from the device name variable. You will need to "cast away const"
-whenever you respond to read requests with read-only data.</p>
<p>It is not shown in the above snippet, but this function ultimately returns 0.
By returning 0, <em>bleprph</em> indicates that the characteristic data in
-<em>ctxt->chr_access</em> is valid and that NimBLE should include it in its response
+<em>ctxt->om</em> is valid and that NimBLE should include it in its response
to the peer.</p>
<p><br></p>
-<p><strong>A word of warning:</strong> The attribute data that <em>ctxt->chr_access.data</em> points to
-must remain valid after the access function returns, as the NimBLE stack needs
-to use it to form a GATT read response. In other words, you must not
-allocate the characteristic value data on the stack of the access function.
-Two characteristic accesses never occur at the same time, so it is OK to use
-the same memory for repeated accesses.</p>
-<p><br></p>
<h4 id="write-access">Write access</h4>
-<p><br></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_CHR_UUID16_RECONNECT_ADDR</span>:
- <span style="color: #000000">assert</span>(<span style="color: #000000">op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_WRITE_CHR</span>);
- <span style="color: #A90D91">if</span> (<span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">len</span> <span style="color: #000000">!=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_reconnect_addr</span>) {
- <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN</span>;
- }
- <span style="color: #000000">memcpy</span>(<span style="color: #000000">bleprph_reconnect_addr</span>, <span style="color: #000000">ctxt->chr_access</span>.<span style="color: #000000">data</span>,
- <span style="color: #A90D91">sizeof</span> <span style="color: #000000">bleprph_reconnect_addr</span>);
- <span style="color: #A90D91">break</span>;
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">gatt_svr_unr_alert_stat</span>;
+</pre></div>
+
+
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">case</span> <span style="color: #000000">GATT_SVR_CHR_UNR_ALERT_STAT_UUID</span>:
+ <span style="color: #A90D91">if</span> (<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_WRITE_CHR</span>) {
+ <span style="color: #A90D91">if</span> (<span style="color: #000000">OS_MBUF_PKTLEN</span>(<span style="color: #000000">ctxt->om</span>) <span style="color: #000000">!=</span> <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_svr_unr_alert_stat</span>) {
+ <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN</span>;
+ }
+
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_hs_mbuf_to_flat</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #000000">&gatt_svr_unr_alert_stat</span>,
+ <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_svr_unr_alert_stat</span>, <span style="color: #A90D91">NULL</span>);
+ <span style="color: #A90D91">if</span> (<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
+ <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_UNLIKELY</span>;
+ }
+
+ <span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
+ } <span style="color: #A90D91">else</span> <span style="color: #177500">/* [...] */</span>
</pre></div>
-<p>This code excerpt handles writes to the reconnect address characteristic. This
-characteristic was registered as write-only, so the <em>assert()</em> here is just a
-safety precaution to ensure the NimBLE stack is doing its job.</p>
-<p>For writes, the roles of the <em>ctxt->chr_access.data</em> and <em>ctxt->chr_access.len</em>
-fields are the reverse of the read case. The NimBLE stack uses these fields to
-indicate the data written by the peer.</p>
+<p>This code excerpt handles writes to the New Alert characteristic. For writes,
+the role of the <em>ctxt->om</em> field is the reverse of the read case. The NimBLE
+stack uses these fields to indicate the data written by the peer.</p>
<p>Many characteristics have strict length requirements for write operations.
-This characteristic has such a restriction; if the written data is not a 48-bit
-BR address, the application tells NimBLE to respond with an invalid attribute
-value length error.</p>
-<p>For writes, the <em>ctxt->chr_access.data</em> pointer is only valid for the duration
-of the access function. If the application needs to save the written data, it
-should store it elsewhere before the function returns. In this case, <em>bleprph</em>
-stores the specified address in a global variable called
-<em>bleprph_reconnect_addr</em>.</p>
+This characteristic has such a restriction; if the written data is not a 2-byte
+value, the application tells NimBLE to respond with an invalid attribute value
+length error.</p>
+<p><em>bleprph</em> copies the data out of the supplied mbuf and writes it to a contiguous chunk of storage (the <em>gatt_svr_unr_alert_stat</em> variable). This is accomplished with the <a href="../../../../network/ble/ble_hs/other/functions/ble_hs_mbuf_to_flat">ble_hs_mbuf_to_flat()</a> function. If the application did not have a suitable destination for the data handy, it could have inherited the mbuf from the context object. This is done by saving a copy of the mbuf pointer, and assigning <em>NULL</em> to <em>ctxt->om</em>. By assigning <em>NULL</em> to the mbuf pointer, your application prevents the stack from freeing the mbuf while it is still being used. Be aware, however, that it is the application's responsibility to free inherited mbufs.</p>
<div class="row">
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/bdf51006/develop/os/tutorials/bleprph/bleprph-conn/index.html
----------------------------------------------------------------------
diff --git a/develop/os/tutorials/bleprph/bleprph-conn/index.html b/develop/os/tutorials/bleprph/bleprph-conn/index.html
deleted file mode 100644
index acb38a3..0000000
--- a/develop/os/tutorials/bleprph/bleprph-conn/index.html
+++ /dev/null
@@ -1,692 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="utf-8">
- <meta http-equiv="X-UA-Compatible" content="IE=edge">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
-
-
- <link rel="canonical" href="http://mynewt.apache.org/os/tutorials/bleprph/bleprph-conn/">
- <link rel="shortcut icon" href="../../../../img/favicon.ico">
-
- <title>Connection Callbacks - Apache Mynewt</title>
-
- <link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
- <link href="../../../../css/font-awesome-4.0.3.css" rel="stylesheet">
- <link rel="stylesheet" href="../../../../css/highlight.css">
- <link href="../../../../css/base.css" rel="stylesheet">
- <link href="../../../../css/custom.css" rel="stylesheet">
- <link href="../../../../css/v2.css" rel="stylesheet">
- <link href='https://fonts.googleapis.com/css?family=Roboto:400,500,700,900,300,100' rel='stylesheet' type='text/css'>
- <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
- <link href="../../../../extra.css" rel="stylesheet">
-
- <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
- <!--[if lt IE 9]>
- <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
- <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
- <![endif]-->
-
-
- <script>
- (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
- (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
- m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
- })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-
- ga('create', 'UA-72162311-1', 'auto');
- ga('send', 'pageview');
- </script>
-
- </head>
-
-
- <body class="Connection Callbacks">
-
-
-
-
-
-
-
-
-
-<nav id="navbar" class="navbar navbar-inverse navbar-fixed-top" role="navigation">
- <div class="container">
- <!-- Collapsed navigation -->
- <div class="navbar-header">
- <!-- Expander button -->
- <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
- <span class="sr-only">Toggle navigation</span>
- <span class="icon-bar"></span>
- <span class="icon-bar"></span>
- <span class="icon-bar"></span>
- </button>
-
- </div>
-
- <!-- Expanded navigation -->
- <div class="navbar-collapse collapse">
- <!-- Main navigation -->
- <ul class="nav navbar-nav navbar-right">
- <li
- class=""
->
- <a href="/">Home</a>
- </li>
- <li
- class="important"
->
- <a href="/quick-start/">Quick Start</a>
- </li>
- <li
- class=""
->
- <a href="/about/">About</a>
- </li>
- <li
- class="active"
->
- <a href="/latest/os/introduction">Documentation</a>
- </li>
- <li
- class=""
->
- <a href="/download/">Download</a>
- </li>
- <li
- class=""
->
- <a href="/community/">Community</a>
- </li>
- <li
- class=""
->
- <a href="/events/">Events</a>
- </li>
- </ul>
-
- <!-- Search, Navigation and Repo links -->
- <ul class="nav navbar-nav navbar-right">
-
- </ul>
- </div>
- </div>
-</nav>
-
-
-
- <div class="container">
-
- <div class="row">
- <div class="col-md-3 v2-sidebar"><div id="docSidebar" class="hidden-print" role="complementary">
- <div class="top">
- <img class="hidden-xs hidden-sm logo-small" src="/img/logo.svg" alt="MyNewt" title="MyNewt">
- <div role="search">
- <form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
- <div class="form-group">
- <input type="text" name="q" class="form-control" placeholder="Search documentation" />
- </div>
- </form>
- </div>
- </div>
- <ul class="toc-nav">
- <li class="doc-version">
-<select class="form-control" onchange="if (this.value) window.location.href=this.value">
-
- <option
- value="/develop/os/introduction"
- selected="selected"
- >
- Version: develop
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0 (latest)
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../tutorials/">Tutorials</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ../../arduino_zero/
-">Project Blinky</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../repo/add_repos/">Work with repositories</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../tasks_lesson/
-">A Sample Lesson</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../wi-fi_on_arduino/">Enable Wi-Fi on Arduino Zero</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../unit_test/">Write a Test Suite for a Package</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../air_quality_sensor/">Air-quality Sensor project</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../event_queue/">Add task to manage multiple events</a>
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../project-slinky/
-">Project Slinky for remote comms</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../add_newtmgr/">Enable newtmgr in any app</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../bletiny_project/">BLE app to check stats via console</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../bleprph-intro/">BLE peripheral project</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../bleprph-svc-reg/">Service Registration</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../bleprph-chr-access/">Characteristic Access</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../bleprph-adv/">Advertising</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">Connection Callbacks</a>
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../ibeacon/">BLE iBeacon</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../blehci_project/">BLE HCI interface</a>
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../../network/ble/ble_intro/
-">BLE User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../../faq/how_to_edit_docs/
-">Appendix</a>
-
-
- </li>
-
-
-
- </ul>
-</div></div>
-
- <div class="show-sidebar-container">
- <button class="show-sidebar">Docs Menu</button>
- </div>
-
- <div class="col-md-9" role="main">
- <div class="row doc-header">
- <div class="col-sm-12">
- <div role="navigation" aria-label="breadcrumbs navigation">
- <ul class="wy-breadcrumbs pull-right">
- <li><a href="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../tutorials/">Tutorials</a></li>
-
-
-
- <li>» <a href="../bleprph-intro/">BLE peripheral project</a></li>
-
-
-
- <li>» Connection Callbacks</li>
-
-
-
- </ul>
-</div>
- </div>
- </div>
-
- <h2 id="ble-peripheral-project">BLE Peripheral Project</h2>
-<h3 id="connection-callbacks">Connection callbacks</h3>
-<p><br></p>
-<h4 id="overview">Overview</h4>
-<p>Every BLE connection has a <em>connection callback</em> associated with it. A
-connection callback is a bit of application code which NimBLE uses to inform
-you of connection-related events. For example, if a connection is terminated,
-NimBLE lets you know about it with a call to that connection's callback.</p>
-<p>In the <a href="../bleprph-adv/">advertising section</a> of this tutorial, we saw how the
-application specifies a connection callback when it begins advertising. NimBLE
-uses this callback to notify the application that a central has connected to
-your peripheral after receiving an advertisement. Let's revisit how <em>bleprph</em> specifies its connection callback when advertising:</p>
-<p><br></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #177500">/* Begin advertising. */</span>
- <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_adv_start</span>(<span style="color: #000000">BLE_GAP_DISC_MODE_GEN</span>, <span style="color: #000000">BLE_GAP_CONN_MODE_UND</span>,
- <span style="color: #A90D91">NULL</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">NULL</span>, <span style="color: #000000">bleprph_on_connect</span>, <span style="color: #A90D91">NULL</span>);
- <span style="color: #A90D91">if</span> (<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
- <span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">ERROR</span>, <span style="color: #C41A16">"error enabling advertisement; rc=%d\n"</span>, <span style="color: #000000">rc</span>);
- <span style="color: #A90D91">return</span>;
- }
-</pre></div>
-
-
-<p><br></p>
-<h4 id="bleprph_on_connect">bleprph_on_connect()</h4>
-<p>The <code>bleprph_on_connect()</code> function is <em>bleprph</em>'s connection callback; NimBLE
-calls this function when the advertising operation leads to connection
-establishment. Upon connecting, this callback becomes permanently associated
-with the connection; all subsequent events related to this connection are
-communicated through this callback.</p>
-<p>Now let's look at the function that <em>bleprph</em> uses for all its connection
-callbacks: <code>bleprph_on_connect()</code>.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span>
-<span style="color: #000000">bleprph_on_connect</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">event</span>, <span style="color: #A90D91">int</span> <span style="color: #000000">status</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_conn_ctxt</span> <span style="color: #000000">*ctxt</span>,
- <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
-{
- <span style="color: #A90D91">switch</span> (<span style="color: #000000">event</span>) {
- <span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_EVENT_CONN</span>:
- <span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">"connection %s; status=%d "</span>,
- <span style="color: #000000">status</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">?</span> <span style="color: #C41A16">"up"</span> <span style="color: #000000">:</span> <span style="color: #C41A16">"down"</span>, <span style="color: #000000">status</span>);
- <span style="color: #000000">bleprph_print_conn_desc</span>(<span style="color: #000000">ctxt->desc</span>);
- <span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">"\n"</span>);
-
- <span style="color: #A90D91">if</span> (<span style="color: #000000">status</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
- <span style="color: #177500">/* Connection terminated; resume advertising. */</span>
- <span style="color: #000000">bleprph_advertise</span>();
- }
- <span style="color: #A90D91">break</span>;
- }
-
- <span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
-}
-</pre></div>
-
-
-<p><br></p>
-<p>Connection callbacks are used to communicate a variety of events related to a
-connection. An application determines the type of event that occurred by
-inspecting the value of the <em>event</em> parameter. The full list of event codes
-can be found in <a href="https://github.com/apache/incubator-mynewt-core/blob/master/net/nimble/host/include/host/ble_gatt.h">net/nimble/host/include/host/ble_gatt.h</a>.
-<em>bleprph</em> only concerns itself with a single event type: <em>BLE_GAP_EVENT_CONN</em>.
-This event indicates that a new connection has been established, or an existing
-connection has been terminated; the <em>status</em> parameter clarifies which. As you
-can see, <em>bleprph</em> uses the <em>status</em> parameter to determine if it should resume
-advertising.</p>
-<p>The <em>ctxt</em> parameter contains additional information about the connection
-event. <em>bleprph</em> does nothing more than log some fields of this struct, but
-some apps will likely want to perform further actions, e.g., perform service
-discovery on the connected device. The <em>struct ble_gap_conn_ctxt</em> type is
-defined as follows:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_conn_ctxt</span> {
- <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_conn_desc</span> <span style="color: #000000">*desc</span>;
-
- <span style="color: #A90D91">union</span> {
- <span style="color: #A90D91">struct</span> {
- <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_upd_params</span> <span style="color: #000000">*self_params</span>;
- <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_upd_params</span> <span style="color: #000000">*peer_params</span>;
- } <span style="color: #000000">update</span>;
-
- <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_sec_params</span> <span style="color: #000000">*sec_params</span>;
- };
-};
-</pre></div>
-
-
-<p><br></p>
-<p>As shown, a connection context object consists of two parts:</p>
-<ul>
-<li><em>desc:</em> The connection descriptor; indicates properties of the connection.</li>
-<li><em>anonymous union:</em> The contents are event-specific; check the <em>event</em> code to determine which member field (if any) is relevant.</li>
-</ul>
-<p>For events of type <em>BLE_GAP_EVENT_CONN</em>, the anonymous union is not used at all, so the only information carried by the context struct is the connection descriptor. The <em>struct ble_gap_conn_desc</em> type is defined as follows:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gap_conn_desc</span> {
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">peer_addr</span>[<span style="color: #1C01CE">6</span>];
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</span>;
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_itvl</span>;
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_latency</span>;
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">supervision_timeout</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">peer_addr_type</span>;
-};
-</pre></div>
-
-
-<p><br></p>
-<p>We will examine these fields in a slightly different order from how they appear
-in the struct definition.</p>
-<p><br></p>
-<table>
-<thead>
-<tr>
-<th><em>Field</em></th>
-<th><em>Purpose</em></th>
-<th><em>Notes</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>peer_addr</td>
-<td>The 48-bit address of the peer device.</td>
-<td></td>
-</tr>
-<tr>
-<td>peer_addr_type</td>
-<td>Whether the peer is using a public or random address.</td>
-<td>The address type list is documented in <a href="https://github.com/apache/incubator-mynewt-core/blob/master/net/nimble/include/nimble/hci_common.h">net/nimble/include/nimble/hci_common.h</a>.</td>
-</tr>
-<tr>
-<td>conn_handle</td>
-<td>The 16-bit handle associated with this connection.</td>
-<td>This number is how your app and the NimBLE stack refer to this connection.</td>
-</tr>
-<tr>
-<td>conn_itvl,<br>conn_latency,<br>supervision_timeout</td>
-<td>Low-level properties of the connection.</td>
-<td></td>
-</tr>
-</tbody>
-</table>
-<p><br></p>
-<h4 id="guarantees">Guarantees</h4>
-<p>It is important to know what your application code is allowed to do from within
-a connection callback.</p>
-<p><strong>No restrictions on NimBLE operations</strong></p>
-<p>Your app is free to make calls into the NimBLE stack from within a connection
-callback. <em>bleprph</em> takes advantage of this freedom when it resumes
-advertising upon connection termination. All other NimBLE operations are also
-allowed (service discovery, pairing initiation, etc).</p>
-<p><strong>All context data is transient</strong></p>
-<p>Pointers in the context object point to data living on the stack. Your
-callback is free to read (or write, if appropriate) through these pointers, but
-you should not store these pointers for later use. If your application needs
-to retain some data from a context object, it needs to make a copy.</p>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../bleprph-adv/>
- <span class="fa fa-arrow-left"></span>
- Previous: Advertising
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../../ibeacon/>
- Next: BLE iBeacon
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </li>
-</ul>
- </div>
- <div class="row">
- <footer>
- <div class="row">
- <div class="col-md-12">
-
- <p class="copyright">Copyright © 2015 The Apache Software Foundation, Licensed under the Apache License, Version 2.0 Apache and the Apache feather logo are trademarks of The Apache Software Foundation.<br>The Apache Software Foundation Apache Incubator</p>
-
- </div>
- </div>
- <div class="copyright-logos">
- <div class="row">
- <div class="col-xs-6 text-right">
- <img src="/img/apache-feather.png" alt="Apache" title="Apache">
- </div>
- <div class="col-xs-6 text-left">
- <img src="/img/apache-logo.png" alt="Apache Incubator" title="Apache Incubator">
- </div>
- </div>
- </div>
- <div class="row">
- <div class="col-md-12">
- <small class="footnote">
- MyNewt is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
- </small>
- </div>
- </div>
-</footer>
- </div>
- </div>
- </div>
-
-
- </div>
-
- <script src="../../../../js/jquery-1.10.2.min.js"></script>
- <script src="../../../../js/bootstrap-3.0.3.min.js"></script>
- <script src="../../../../js/highlight.pack.js"></script>
- <script src="../../../../js/base.js"></script>
- <script src="../../../../js/custom.js"></script>
-
- </body>
-</html>
\ No newline at end of file