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:18 UTC
[2/3] incubator-mynewt-site git commit: pull requests #75-77 and
minor changes to ble peripheral tutorials
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/bleprph/bleprph-adv/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/bleprph/bleprph-adv/index.html b/os/tutorials/bleprph/bleprph-adv/index.html
new file mode 100644
index 0000000..6e25c7a
--- /dev/null
+++ b/os/tutorials/bleprph/bleprph-adv/index.html
@@ -0,0 +1,760 @@
+<!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-adv/">
+ <link rel="shortcut icon" href="../../../../img/favicon.ico">
+
+ <title>Advertising - 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='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', 'mynewt.incubator.apache.org');
+ ga('send', 'pageview');
+ </script>
+
+ </head>
+
+
+ <body class="Advertising">
+
+
+ <div id="navbar" class="navbar navbar-default navbar-fixed-top" role="navigation">
+ <div class="logo-container">
+ <img src="/img/logo.svg">
+ </div>
+ <div class="container-fluid">
+ <!-- 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>
+ <a href="/">Home</a>
+ </li>
+ <li>
+ <a href="/about/">About</a>
+ </li>
+ <li class="dropdown">
+ <a href="/documentation/" class="dropdown-toggle" data-toggle="dropdown">Docs <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+
+
+
+
+
+ <li >
+ <a href="../../../../documentation/">
+ Overview
+ </a>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="active">
+ <a href="../../../get_started/introduction/">
+ Mynewt OS Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../../../newt/newt_intro/">
+ Newt Tool Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../../../newtmgr/overview/">
+ Newt Manager Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../how_to_edit_docs/">
+ Appendix
+ </a>
+ </li>
+
+
+ </ul>
+ </li>
+ <li>
+ <a href="/download/">Download</a>
+ </li>
+ <li>
+ <a href="/community/">Community</a>
+ </li>
+ <li>
+ <a href="/events/">Events</a>
+ </li>
+ </ul>
+
+ <!-- Search, Navigation and Repo links -->
+ <ul class="nav navbar-nav navbar-right">
+
+ </ul>
+ </div>
+ </div>
+</div>
+
+
+
+ <div class="container-fluid">
+
+ <div class="row sm-extra-padding">
+ <div id="docSidebar" class="col-md-3 bg-grey sidebar-container"><div class="bs-sidebar hidden-print" role="complementary">
+ <div class="sidebar-top">
+ <img class="hidden-xs hidden-sm logo-small" src="/img/logo.svg" alt="MyNewt" title="MyNewt">
+ <div class="small" role="search">
+ <form id ="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
+ <div class="form-group">
+ <input type="text" name="q" placeholder="Search documentation" />
+ <button class="search-button" type="submit"><i class="fa fa-search"></i></button>
+ </div>
+ </form>
+ </div>
+ </div>
+ <ul class="nav bs-sidenav">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../get_started/introduction/
+">Mynewt OS Manual</a>
+
+
+ <ul class="current-toc">
+
+
+
+
+ <li>
+ <a href="../../../get_started/introduction/">Introduction</a>
+ </li>
+
+
+
+
+
+
+
+
+ <li ><a href="../../../get_started/get_started/">Quick Start</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../../get_started/vocabulary/">Concepts</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../tutorials/">Tutorials</a></li>
+
+
+ <ul class="current-toc">
+
+
+
+
+
+
+ <li>
+ <a href="../../arduino_zero/">Blinky on Arduino Zero</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../olimex/">Blinky on Olimex</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../STM32F303/">Blinky on STM32F303</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../nRF52/">Blinky on nRF52</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../blinky_sram_olimex/">Run Blinky from SRAM, no bootloader</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../add_repos/">Add repo to project</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../create_repo/">Create a repo</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../upgrade_repo/">Upgrade a repo</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../bletiny_project/">Use BLE app to check stats via console</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../project-slinky/">Enable remote comms on sim device</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../project-target-slinky/">Enable remote comms on STM32 board</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="../bleprph-intro/">BLE peripheral project</a></li>
+
+
+ <ul class="current-toc">
+
+
+
+
+
+
+ <li>
+ <a href="../bleprph-svc-reg/">Service Registration</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../bleprph-chr-access/">Characteristic Access</a>
+ </li>
+
+
+
+
+
+
+
+ <li class="active">
+ Advertising
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../bleprph-conn/">Connection Callbacks</a>
+ </li>
+
+
+
+
+ </ul>
+
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../../os_user_guide/">OS User Guide</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../network/ble/ble_intro/
+">BLE User Guide</a>
+
+
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newt/newt_intro/
+">Newt Tool Manual</a>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newtmgr/overview/
+">Newt Manager Manual</a>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../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-offset-3 col-md-9 documentation-viewer" role="main">
+ <div class="row doc-header">
+ <div class="col-sm-6">
+
+<ul class="nav nav-pills">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="active" role="presentation"><a href="../../../get_started/introduction/">Mynewt OS</a></li>
+
+
+
+ <li role="presentation"><a href="../../../../newt/newt_intro/">Newt Tool</a></li>
+
+
+
+ <li role="presentation"><a href="../../../../newtmgr/overview/">Newt Mgr</a></li>
+
+
+
+
+</ul>
+ </div>
+ <div class="col-sm-6">
+ <div role="navigation" aria-label="breadcrumbs navigation">
+ <ul class="wy-breadcrumbs">
+ <li><a href="/documentation/">Docs</a></li>
+
+
+
+ <li>» <a href="../../tutorials/">Tutorials</a></li>
+
+
+
+ <li>» <a href="../bleprph-intro/">BLE peripheral project</a></li>
+
+
+
+ <li>» Advertising</li>
+
+
+
+ </ul>
+</div>
+ </div>
+ </div>
+
+ <h2 id="ble-peripheral-project">BLE Peripheral Project<a class="headerlink" href="#ble-peripheral-project" title="Permanent link">¶</a></h2>
+<h3 id="advertising">Advertising<a class="headerlink" href="#advertising" title="Permanent link">¶</a></h3>
+<p><br></p>
+<h4 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">¶</a></h4>
+<p>A peripheral announces its presence to the world by broadcasting
+advertisements. An advertisement typically contains additional information
+about the peripheral sending it, such as the device name and an abbreviated
+list of supported services. The presence of this information helps a listening
+central to determine whether it is interested in connecting to the peripheral.
+Advertisements are quite limited in the amount of information they can contain,
+so only the most important information should be included.</p>
+<p>When a listening device receives an advertisement, it can choose to connect to
+the peripheral, or query the sender for more information. This second action
+is known as an <em>active scan</em>. A peripheral responds to an active scan with
+some extra information that it couldn't fit in its advertisement. This
+additional information is known as <em>scan response data</em>. <em>bleprph</em> does not
+configure any scan response data, so this feature is not discussed in the
+remainder of this tutorial.</p>
+<p><em>bleprph</em> constantly broadcasts advertisements until a central connects to it.
+When a connection is terminated, <em>bleprph</em> resumes advertising.</p>
+<p>Let's take a look at <em>bleprph</em>'s advertisement code (<em>main.c</em>):</p>
+<p><br></p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/**</span>
+<span style="color: #177500"> * Enables advertising with the following parameters:</span>
+<span style="color: #177500"> * o General discoverable mode.</span>
+<span style="color: #177500"> * o Undirected connectable mode.</span>
+<span style="color: #177500"> */</span>
+<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_hs_adv_fields</span> <span style="color: #000000">fields</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: #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: #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">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>);
+ <span style="color: #A90D91">return</span>;
+ }
+
+ <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>Now let's examine this code in detail.</p>
+<p><br></p>
+<h4 id="setting-advertisement-data">Setting advertisement data<a class="headerlink" href="#setting-advertisement-data" title="Permanent link">¶</a></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
+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
+member variables of the <em>struct ble_hs_adv_fields</em> type correspond to these
+standard fields. Information that doesn't fit neatly into a standard field
+should be put in the <em>manufacturing specific data</em> field.</p>
+<p>As you can see in the above code listing, the <code>struct ble_hs_adv_fields</code>
+instance is allocated on the stack. It is OK to use the stack for this struct
+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><br></p>
+<h4 id="begin-advertising">Begin advertising<a class="headerlink" href="#begin-advertising" title="Permanent link">¶</a></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><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
+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>
+
+ <div class="row">
+
+
+
+
+<ul class="nav nav-pills" style="margin-bottom: 10px">
+ <li>
+
+ <a href=../bleprph-chr-access/>
+ <span class="fa fa-arrow-left"></span>
+ Previous: Characteristic Access
+ </a>
+
+ </li>
+ <li class="pull-right">
+
+ <a href=../bleprph-conn/>
+ Next: Connection Callbacks
+ <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
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/bleprph/bleprph-chr-access/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/bleprph/bleprph-chr-access/index.html b/os/tutorials/bleprph/bleprph-chr-access/index.html
new file mode 100644
index 0000000..676fbeb
--- /dev/null
+++ b/os/tutorials/bleprph/bleprph-chr-access/index.html
@@ -0,0 +1,874 @@
+<!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-chr-access/">
+ <link rel="shortcut icon" href="../../../../img/favicon.ico">
+
+ <title>Characteristic Access - 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='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', 'mynewt.incubator.apache.org');
+ ga('send', 'pageview');
+ </script>
+
+ </head>
+
+
+ <body class="Characteristic Access">
+
+
+ <div id="navbar" class="navbar navbar-default navbar-fixed-top" role="navigation">
+ <div class="logo-container">
+ <img src="/img/logo.svg">
+ </div>
+ <div class="container-fluid">
+ <!-- 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>
+ <a href="/">Home</a>
+ </li>
+ <li>
+ <a href="/about/">About</a>
+ </li>
+ <li class="dropdown">
+ <a href="/documentation/" class="dropdown-toggle" data-toggle="dropdown">Docs <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+
+
+
+
+
+ <li >
+ <a href="../../../../documentation/">
+ Overview
+ </a>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="active">
+ <a href="../../../get_started/introduction/">
+ Mynewt OS Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../../../newt/newt_intro/">
+ Newt Tool Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../../../newtmgr/overview/">
+ Newt Manager Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../how_to_edit_docs/">
+ Appendix
+ </a>
+ </li>
+
+
+ </ul>
+ </li>
+ <li>
+ <a href="/download/">Download</a>
+ </li>
+ <li>
+ <a href="/community/">Community</a>
+ </li>
+ <li>
+ <a href="/events/">Events</a>
+ </li>
+ </ul>
+
+ <!-- Search, Navigation and Repo links -->
+ <ul class="nav navbar-nav navbar-right">
+
+ </ul>
+ </div>
+ </div>
+</div>
+
+
+
+ <div class="container-fluid">
+
+ <div class="row sm-extra-padding">
+ <div id="docSidebar" class="col-md-3 bg-grey sidebar-container"><div class="bs-sidebar hidden-print" role="complementary">
+ <div class="sidebar-top">
+ <img class="hidden-xs hidden-sm logo-small" src="/img/logo.svg" alt="MyNewt" title="MyNewt">
+ <div class="small" role="search">
+ <form id ="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
+ <div class="form-group">
+ <input type="text" name="q" placeholder="Search documentation" />
+ <button class="search-button" type="submit"><i class="fa fa-search"></i></button>
+ </div>
+ </form>
+ </div>
+ </div>
+ <ul class="nav bs-sidenav">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../get_started/introduction/
+">Mynewt OS Manual</a>
+
+
+ <ul class="current-toc">
+
+
+
+
+ <li>
+ <a href="../../../get_started/introduction/">Introduction</a>
+ </li>
+
+
+
+
+
+
+
+
+ <li ><a href="../../../get_started/get_started/">Quick Start</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../../get_started/vocabulary/">Concepts</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../tutorials/">Tutorials</a></li>
+
+
+ <ul class="current-toc">
+
+
+
+
+
+
+ <li>
+ <a href="../../arduino_zero/">Blinky on Arduino Zero</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../olimex/">Blinky on Olimex</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../STM32F303/">Blinky on STM32F303</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../nRF52/">Blinky on nRF52</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../blinky_sram_olimex/">Run Blinky from SRAM, no bootloader</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../add_repos/">Add repo to project</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../create_repo/">Create a repo</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../upgrade_repo/">Upgrade a repo</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../bletiny_project/">Use BLE app to check stats via console</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../project-slinky/">Enable remote comms on sim device</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../project-target-slinky/">Enable remote comms on STM32 board</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="../bleprph-intro/">BLE peripheral project</a></li>
+
+
+ <ul class="current-toc">
+
+
+
+
+
+
+ <li>
+ <a href="../bleprph-svc-reg/">Service Registration</a>
+ </li>
+
+
+
+
+
+
+
+ <li class="active">
+ Characteristic Access
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../bleprph-adv/">Advertising</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../bleprph-conn/">Connection Callbacks</a>
+ </li>
+
+
+
+
+ </ul>
+
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../../os_user_guide/">OS User Guide</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../network/ble/ble_intro/
+">BLE User Guide</a>
+
+
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newt/newt_intro/
+">Newt Tool Manual</a>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newtmgr/overview/
+">Newt Manager Manual</a>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../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-offset-3 col-md-9 documentation-viewer" role="main">
+ <div class="row doc-header">
+ <div class="col-sm-6">
+
+<ul class="nav nav-pills">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="active" role="presentation"><a href="../../../get_started/introduction/">Mynewt OS</a></li>
+
+
+
+ <li role="presentation"><a href="../../../../newt/newt_intro/">Newt Tool</a></li>
+
+
+
+ <li role="presentation"><a href="../../../../newtmgr/overview/">Newt Mgr</a></li>
+
+
+
+
+</ul>
+ </div>
+ <div class="col-sm-6">
+ <div role="navigation" aria-label="breadcrumbs navigation">
+ <ul class="wy-breadcrumbs">
+ <li><a href="/documentation/">Docs</a></li>
+
+
+
+ <li>» <a href="../../tutorials/">Tutorials</a></li>
+
+
+
+ <li>» <a href="../bleprph-intro/">BLE peripheral project</a></li>
+
+
+
+ <li>» Characteristic Access</li>
+
+
+
+ </ul>
+</div>
+ </div>
+ </div>
+
+ <h2 id="ble-peripheral-project">BLE Peripheral Project<a class="headerlink" href="#ble-peripheral-project" title="Permanent link">¶</a></h2>
+<h3 id="characteristic-access">Characteristic Access<a class="headerlink" href="#characteristic-access" title="Permanent link">¶</a></h3>
+<p><br></p>
+<h4 id="review">Review<a class="headerlink" href="#review" title="Permanent link">¶</a></h4>
+<p>A characteristic's access callback implements its behavior. Recall that
+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
+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">/*** 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: #177500">// [...]</span>
+</pre></div>
+
+
+<p>As you can see, <em>bleprph</em> uses the same <em>access_cb</em> function for all the GAP
+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>
+<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: #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">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">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: #1C01CE">0</span>;
+}
+</pre></div>
+
+
+<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<a class="headerlink" href="#function-signature" title="Permanent link">¶</a></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>)
+</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>
+<th><strong>Parameter</strong></th>
+<th><strong>Purpose</strong></th>
+<th><strong>Notes</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>conn_handle</td>
+<td>Indicates which connection the characteristic access was sent over.</td>
+<td>Use this value to determine which peer is accessing the characteristic.</td>
+</tr>
+<tr>
+<td>attr_handle</td>
+<td>The low-level ATT handle of the characteristic value attribute.</td>
+<td>Can be used to determine which characteristic is being accessed if you don't want to perform a UUID lookup.</td>
+</tr>
+<tr>
+<td>op</td>
+<td>Indicates whether this is a read or write operation</td>
+<td>Valid values are:<br><em>BLE_GATT_ACCESS_OP_READ_CHR</em><br><em>BLE_GATT_ACCESS_OP_WRITE_CHR</em></td>
+</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>
+</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>
+<p><br></p>
+<h4 id="determine-characteristic-being-accessed">Determine characteristic being accessed<a class="headerlink" href="#determine-characteristic-being-accessed" title="Permanent link">¶</a></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">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: #177500">// [...]</span>
+</pre></div>
+
+
+<p>This function uses the UUID to determine which characteristic is being
+accessed. There are two alternative methods <em>bleprph</em> could have used to
+accomplish this task:</p>
+<ul>
+<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
+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>
+<p><br></p>
+<h4 id="read-access">Read access<a class="headerlink" href="#read-access" title="Permanent link">¶</a></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>;
+</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><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>;
+</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
+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<a class="headerlink" href="#write-access" title="Permanent link">¶</a></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>;
+</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>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>
+
+ <div class="row">
+
+
+
+
+<ul class="nav nav-pills" style="margin-bottom: 10px">
+ <li>
+
+ <a href=../bleprph-svc-reg/>
+ <span class="fa fa-arrow-left"></span>
+ Previous: Service Registration
+ </a>
+
+ </li>
+ <li class="pull-right">
+
+ <a href=../bleprph-adv/>
+ Next: Advertising
+ <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
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c23164b2/os/tutorials/bleprph/bleprph-conn/index.html
----------------------------------------------------------------------
diff --git a/os/tutorials/bleprph/bleprph-conn/index.html b/os/tutorials/bleprph/bleprph-conn/index.html
new file mode 100644
index 0000000..6dae5e0
--- /dev/null
+++ b/os/tutorials/bleprph/bleprph-conn/index.html
@@ -0,0 +1,790 @@
+<!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='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', 'mynewt.incubator.apache.org');
+ ga('send', 'pageview');
+ </script>
+
+ </head>
+
+
+ <body class="Connection Callbacks">
+
+
+ <div id="navbar" class="navbar navbar-default navbar-fixed-top" role="navigation">
+ <div class="logo-container">
+ <img src="/img/logo.svg">
+ </div>
+ <div class="container-fluid">
+ <!-- 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>
+ <a href="/">Home</a>
+ </li>
+ <li>
+ <a href="/about/">About</a>
+ </li>
+ <li class="dropdown">
+ <a href="/documentation/" class="dropdown-toggle" data-toggle="dropdown">Docs <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+
+
+
+
+
+ <li >
+ <a href="../../../../documentation/">
+ Overview
+ </a>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="active">
+ <a href="../../../get_started/introduction/">
+ Mynewt OS Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../../../newt/newt_intro/">
+ Newt Tool Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../../../newtmgr/overview/">
+ Newt Manager Manual
+ </a>
+ </li>
+
+
+
+ <li >
+ <a href="../../how_to_edit_docs/">
+ Appendix
+ </a>
+ </li>
+
+
+ </ul>
+ </li>
+ <li>
+ <a href="/download/">Download</a>
+ </li>
+ <li>
+ <a href="/community/">Community</a>
+ </li>
+ <li>
+ <a href="/events/">Events</a>
+ </li>
+ </ul>
+
+ <!-- Search, Navigation and Repo links -->
+ <ul class="nav navbar-nav navbar-right">
+
+ </ul>
+ </div>
+ </div>
+</div>
+
+
+
+ <div class="container-fluid">
+
+ <div class="row sm-extra-padding">
+ <div id="docSidebar" class="col-md-3 bg-grey sidebar-container"><div class="bs-sidebar hidden-print" role="complementary">
+ <div class="sidebar-top">
+ <img class="hidden-xs hidden-sm logo-small" src="/img/logo.svg" alt="MyNewt" title="MyNewt">
+ <div class="small" role="search">
+ <form id ="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
+ <div class="form-group">
+ <input type="text" name="q" placeholder="Search documentation" />
+ <button class="search-button" type="submit"><i class="fa fa-search"></i></button>
+ </div>
+ </form>
+ </div>
+ </div>
+ <ul class="nav bs-sidenav">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../get_started/introduction/
+">Mynewt OS Manual</a>
+
+
+ <ul class="current-toc">
+
+
+
+
+ <li>
+ <a href="../../../get_started/introduction/">Introduction</a>
+ </li>
+
+
+
+
+
+
+
+
+ <li ><a href="../../../get_started/get_started/">Quick Start</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../../get_started/vocabulary/">Concepts</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../tutorials/">Tutorials</a></li>
+
+
+ <ul class="current-toc">
+
+
+
+
+
+
+ <li>
+ <a href="../../arduino_zero/">Blinky on Arduino Zero</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../olimex/">Blinky on Olimex</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../STM32F303/">Blinky on STM32F303</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../nRF52/">Blinky on nRF52</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../blinky_sram_olimex/">Run Blinky from SRAM, no bootloader</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../add_repos/">Add repo to project</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../create_repo/">Create a repo</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../upgrade_repo/">Upgrade a repo</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../bletiny_project/">Use BLE app to check stats via console</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../project-slinky/">Enable remote comms on sim device</a>
+ </li>
+
+
+
+
+
+
+
+ <li>
+ <a href="../../project-target-slinky/">Enable remote comms on STM32 board</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="../bleprph-intro/">BLE peripheral project</a></li>
+
+
+ <ul class="current-toc">
+
+
+
+
+
+
+ <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">
+ Connection Callbacks
+ </li>
+
+
+
+
+ </ul>
+
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+
+ <li ><a href="../../../os_user_guide/">OS User Guide</a></li>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../network/ble/ble_intro/
+">BLE User Guide</a>
+
+
+ </li>
+
+
+
+ </ul>
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newt/newt_intro/
+">Newt Tool Manual</a>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../../../newtmgr/overview/
+">Newt Manager Manual</a>
+
+
+ </li>
+
+
+
+
+
+
+
+ <li><a href="
+ ../../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-offset-3 col-md-9 documentation-viewer" role="main">
+ <div class="row doc-header">
+ <div class="col-sm-6">
+
+<ul class="nav nav-pills">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="active" role="presentation"><a href="../../../get_started/introduction/">Mynewt OS</a></li>
+
+
+
+ <li role="presentation"><a href="../../../../newt/newt_intro/">Newt Tool</a></li>
+
+
+
+ <li role="presentation"><a href="../../../../newtmgr/overview/">Newt Mgr</a></li>
+
+
+
+
+</ul>
+ </div>
+ <div class="col-sm-6">
+ <div role="navigation" aria-label="breadcrumbs navigation">
+ <ul class="wy-breadcrumbs">
+ <li><a href="/documentation/">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<a class="headerlink" href="#ble-peripheral-project" title="Permanent link">¶</a></h2>
+<h3 id="connection-callbacks">Connection callbacks<a class="headerlink" href="#connection-callbacks" title="Permanent link">¶</a></h3>
+<p><br></p>
+<h4 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">¶</a></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()<a class="headerlink" href="#bleprph_on_connect" title="Permanent link">¶</a></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<a class="headerlink" href="#guarantees" title="Permanent link">¶</a></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=../../../os_user_guide/>
+ Next: OS User Guide
+ <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