Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_1_0 / os / tutorials / bleprph / bleprph-conn / index.html
blob: fa99b193ea287809dcfd478f0aff02355c322ed4 [file] [log] [blame]
<!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">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../img/favicon.ico">
<title>Bleprph conn - Apache Mynewt</title>
<link href="../../../../css/bootstrap-3.0.3.min.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=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- 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="Bleprph conn">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" 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="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">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>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<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="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" selected="selected" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../../introduction/">Mynewt Documentation</a>
</li>
<li><a href="
../../../../faq/go_env/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; Bleprph conn</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/tutorials/bleprph/bleprph-conn.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.1.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</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></span><code> <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">&quot;error enabling advertisement; rc=%d\n&quot;</span>, <span style="color: #000000">rc</span>);
<span style="color: #A90D91">return</span>;
}
</code></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></span><code><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: #3F6E75">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">&quot;connection %s; status=%d &quot;</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">&quot;up&quot;</span> <span style="color: #000000">:</span> <span style="color: #C41A16">&quot;down&quot;</span>, <span style="color: #000000">status</span>);
<span style="color: #000000">bleprph_print_conn_desc</span>(<span style="color: #000000">ctxt-&gt;desc</span>);
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;\n&quot;</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>;
}
</code></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></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">ble_gap_conn_ctxt</span> {
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">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: #3F6E75">ble_gap_upd_params</span> <span style="color: #000000">*self_params</span>;
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">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: #3F6E75">ble_gap_sec_params</span> <span style="color: #000000">*sec_params</span>;
};
};
</code></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></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">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>;
};
</code></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>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</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>
<script src="search/main.js"></script>
</body>
</html>