blob: 4afe8b27f4af825cbcd7bc70e7882082658ae9f4 [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">
<title>Set up a bare bones NimBLE application &mdash; Apache Mynewt latest documentation</title>
<link rel="shortcut icon" href="../../_static/mynewt-logo-only-newt32x32.png"/>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/sphinx_theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/bootstrap-3.0.3.min.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/v2.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/restructuredtext.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/overrides.css" type="text/css" />
<link rel="index" title="Index"
href="../../genindex.html"/>
<link rel="search" title="Search" href="../../search.html"/>
<link rel="top" title="Apache Mynewt latest documentation" href="../../index.html"/>
<link rel="up" title="Bluetooth Low Energy" href="ble.html"/>
<link rel="next" title="BLE iBeacon" href="ibeacon.html"/>
<link rel="prev" title="Bluetooth Low Energy" href="ble.html"/>
<script src="../../_static/js/modernizr.min.js"></script>
<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="not-front page-documentation" role="document" >
<div id="wrapper">
<div class="container">
<div id="banner" class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="../../_static/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.11.0, Apache NimBLE 1.6.0 </a> released September 7, 2023)
</div>
</div>
</div>
</div>
<header>
<nav id="navbar" class="navbar navbar-inverse" 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>
<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>
<a href="/about/">About</a>
</li>
<li>
<a href="/talks/">Talks</a>
</li>
<li class="active">
<a href="/documentation/">Documentation</a>
</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>
</nav>
</header>
<!-- STARTS MAIN CONTENT -->
<div id="main-content">
<div id="breadcrumb">
<div class="container">
<a href="/documentation/">Docs</a> /
<a href="../tutorials.html">Tutorials</a> /
<a href="ble.html">Bluetooth Low Energy</a> /
Set up a bare bones NimBLE application
<div class="sourcelink">
<a href="https://github.com/apache/mynewt-documentation/edit/master/docs/tutorials/ble/ble_bare_bones.rst" class="icon icon-github"
rel="nofollow"> Edit on GitHub</a>
</div>
</div>
</div>
<!-- STARTS CONTAINER -->
<div class="container">
<!-- STARTS .content -->
<div id="content" class="row">
<!-- STARTS .container-sidebar -->
<div class="container-sidebar col-xs-12 col-sm-3">
<div id="docSidebar" class="sticky-container">
<div role="search" class="sphinx-search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search documentation" class="search-documentation" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<!-- Note: only works when deployed -->
<select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest" selected>
Version: latest
</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" >
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>
<div class="region region-sidebar">
<div class="docs-menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../get_started/index.html">Setup &amp; Get Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../concepts.html">Concepts</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../tutorials.html">Tutorials</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../blinky/blinky.html">Project Blinky</a></li>
<li class="toctree-l2"><a class="reference internal" href="../repo/add_repos.html">Working with repositories</a></li>
<li class="toctree-l2"><a class="reference internal" href="../slinky/project-slinky.html">Project Slinky for Remote Comms</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="ble.html">Bluetooth Low Energy</a><ul class="current">
<li class="toctree-l3 current"><a class="current reference internal" href="#">Set up a bare bones NimBLE application</a></li>
<li class="toctree-l3"><a class="reference internal" href="ibeacon.html">BLE iBeacon</a></li>
<li class="toctree-l3"><a class="reference internal" href="eddystone.html">BLE Eddystone</a></li>
<li class="toctree-l3"><a class="reference internal" href="bleprph/bleprph.html">BLE Peripheral Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="blehci_project.html">Use HCI access to NimBLE controller</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../lora/lorawanapp.html">LoRa</a></li>
<li class="toctree-l2"><a class="reference internal" href="../os_fundamentals/os_fundamentals.html">OS Fundamentals</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devmgmt/devmgmt.html">Remote Device Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sensors/sensors.html">Sensors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tooling/tooling.html">Tooling</a></li>
<li class="toctree-l2"><a class="reference internal" href="../other/other.html">Other</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../external_links.html">Third-party Resources</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../os/os_user_guide.html">OS User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../network/index.html">BLE User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../newt/index.html">Newt Tool Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../newtmgr/index.html">Newt Manager Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../mynewt_faq/index.html">Mynewt FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../misc/index.html">Appendix</a></li>
</ul>
</div>
</div>
</div>
<!-- ENDS STICKY CONTAINER -->
</div>
<!-- ENDS .container-sidebar -->
<div class="col-xs-12 col-sm-9">
<div class="">
<div class="rst-content">
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="set-up-a-bare-bones-nimble-application">
<h1>Set up a bare bones NimBLE application<a class="headerlink" href="#set-up-a-bare-bones-nimble-application" title="Permalink to this headline"></a></h1>
<p>This tutorial explains how to set up a minimal application using the
NimBLE stack. It assumes that you have already installed the
newt tool and are familiar with its concepts.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#create-a-mynewt-project" id="id1">Create a Mynewt project</a></p></li>
<li><p><a class="reference internal" href="#create-an-application-package" id="id2">Create an application package</a></p></li>
<li><p><a class="reference internal" href="#create-the-target" id="id3">Create the target</a></p></li>
<li><p><a class="reference internal" href="#enter-ble" id="id4">Enter BLE</a></p></li>
<li><p><a class="reference internal" href="#build-the-target" id="id5">Build the target</a></p></li>
<li><p><a class="reference internal" href="#conclusion" id="id6">Conclusion</a></p></li>
</ul>
</div>
<div class="section" id="create-a-mynewt-project">
<h2><a class="toc-backref" href="#id1">Create a Mynewt project</a><a class="headerlink" href="#create-a-mynewt-project" title="Permalink to this headline"></a></h2>
<p>We start by creating a project space for your own application work using
the Newt tool. We will call our project <code class="docutils literal notranslate"><span class="pre">my_proj</span></code>.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>~/dev$ newt new my_proj1
Downloading project skeleton from apache/mynewt-blinky...
Installing skeleton in my_proj1...
Project my_proj1 successfully created.
</pre></div>
</div>
<p>The above command created the following directory tree:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>~/dev$ tree my_proj1
my_proj1
├── DISCLAIMER
├── LICENSE
├── NOTICE
├── README.md
├── apps
│   └── blinky
│   ├── pkg.yml
│   └── src
│   └── main.c
├── project.yml
└── targets
├── my_blinky_sim
│   ├── pkg.yml
│   └── target.yml
└── unittest
├── pkg.yml
└── target.yml
6 directories, 11 files
</pre></div>
</div>
<p>Next, we need to retrieve the Mynewt repositories that our app will
depend on. When you retrieve a repository, your project gains access to
the libraries and applications that the repo contains.</p>
<p>A new project automatically depends on the Apache Mynewt core repo
(<code class="docutils literal notranslate"><span class="pre">apache-mynewt-core</span></code>). The core repo contains the Apache Mynewt
operating system, NimBLE stack, and other system libraries. Later, our
app may need packages from additional repos, but for now the core repo
suits our needs.</p>
<p>We download the dependent repos using the <code class="docutils literal notranslate"><span class="pre">newt</span> <span class="pre">upgrade</span></code> command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>~/dev$ cd my_proj1
~/dev/my_proj1$ newt upgrade
Downloading repository mynewt-core (commit: master) ...
apache-mynewt-core successfully upgraded to version 1.7.0
</pre></div>
</div>
<p>Now it’s time to create your own app.</p>
</div>
<div class="section" id="create-an-application-package">
<h2><a class="toc-backref" href="#id2">Create an application package</a><a class="headerlink" href="#create-an-application-package" title="Permalink to this headline"></a></h2>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">~/dev/my_proj1$ newt pkg new apps/ble_app -t app</span>
<span class="go">Download package template for package type app.</span>
<span class="go">Package successfully installed into /home/me/dev/my_proj1/apps/ble_app.</span>
</pre></div>
</div>
<p>You now have an application called <code class="docutils literal notranslate"><span class="pre">apps/ble_app</span></code>. It isn’t terribly
interesting as far as applications go, but it does all the configuration
and set up required of a Mynewt app. It will be a useful starting point
for our BLE application.</p>
</div>
<div class="section" id="create-the-target">
<h2><a class="toc-backref" href="#id3">Create the target</a><a class="headerlink" href="#create-the-target" title="Permalink to this headline"></a></h2>
<p>Now you have to create the target that ties your application to a BSP.
We will call this target “ble_tgt”.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">~/dev/my_proj1$ newt target create ble_tgt</span>
<span class="go">Target targets/ble_tgt successfully created</span>
</pre></div>
</div>
<p>We now have a new target:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>~/dev/my_proj1]$ tree targets/ble_tgt
targets/ble_tgt
├── pkg.yml
└── target.yml
</pre></div>
</div>
<p>We need to fill out a few details in our target before it is usable. At
a minimum, a target must specify three bits of information:</p>
<ul class="simple">
<li><p>Application pacakge</p></li>
<li><p>BSP package</p></li>
<li><p>Build profile</p></li>
</ul>
<p>The application package is straightforward; this is the ble_app package
that we created in the previous step.</p>
<p>For the BSP package, this tutorial chooses to target the nRF52dk BSP. If
you would like to use a different platform, substitute the name of the
appropriate BSP package in the command below.</p>
<p>Finally, the build profile specifies the set of compiler and linker
options to use during the build. Apache Mynewt supports two build
profiles: <code class="docutils literal notranslate"><span class="pre">debug</span></code> and <code class="docutils literal notranslate"><span class="pre">optimized</span></code>.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">~/dev/my_proj1$ newt target set ble_tgt \</span>
<span class="go"> app=apps/ble_app \</span>
<span class="go"> bsp=@apache-mynewt-core/hw/bsp/nordic_pca10040 \</span>
<span class="go"> build_profile=optimized</span>
<span class="go">Target targets/ble_tgt successfully set target.app to apps/ble_app</span>
<span class="go">Target targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nordic_pca10040</span>
<span class="go">Target targets/ble_tgt successfully set target.build_profile to optimized</span>
</pre></div>
</div>
</div>
<div class="section" id="enter-ble">
<h2><a class="toc-backref" href="#id4">Enter BLE</a><a class="headerlink" href="#enter-ble" title="Permalink to this headline"></a></h2>
<p>Since our application will support BLE functionality, we need to give it
access to a BLE stack. We do this by adding the necessary NimBLE
packages to the app’s dependency list in <code class="docutils literal notranslate"><span class="pre">apps/ble_app/pkg.yml</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">pkg.deps:</span>
<span class="go"> - &quot;@apache-mynewt-core/kernel/os&quot;</span>
<span class="go"> - &quot;@apache-mynewt-core/sys/console/full&quot;</span>
<span class="go"> - &quot;@apache-mynewt-core/sys/log/full&quot;</span>
<span class="go"> - &quot;@apache-mynewt-core/sys/stats/full&quot;</span>
<span class="hll"><span class="go"> - &quot;@apache-mynewt-nimble/nimble/host&quot;</span>
</span><span class="hll"><span class="go"> - &quot;@apache-mynewt-nimble/nimble/host/store/config&quot;</span>
</span><span class="hll"><span class="go"> - &quot;@apache-mynewt-nimble/nimble/transport&quot;</span>
</span></pre></div>
</div>
<p>To enable a combined host-controller in the app set correct transport which will include
NimBLE controller into build. For this update <code class="docutils literal notranslate"><span class="pre">apps/ble_app/syscfg.yml</span></code></p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">syscfg.vals:</span>
<span class="go"> BLE_HCI_TRANSPORT: builtin</span>
</pre></div>
</div>
<p>Your <cite>main.c</cite> will also need to include the nimble host header:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="gp">#</span>include<span class="w"> </span><span class="s2">&quot;host/ble_hs.h&quot;</span>
</span></pre></div>
</div>
<p><strong>Important note:</strong> The controller package affects system configuration,
see <a class="reference internal" href="../../network/ble_setup/ble_lp_clock.html"><span class="doc">this page</span></a> for
details.</p>
</div>
<div class="section" id="build-the-target">
<h2><a class="toc-backref" href="#id5">Build the target</a><a class="headerlink" href="#build-the-target" title="Permalink to this headline"></a></h2>
<p>Now would be a good time for a basic sanity check. Let’s make sure the
target builds.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>~/dev/my_proj1$ newt build ble_tgt
Building target targets/ble_tgt
Compiling repos/apache-mynewt-core/hw/hal/src/hal_common.c
Compiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c
&lt;...snip...&gt;
Linking /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.elf
Target successfully built: targets/ble_tgt
</pre></div>
</div>
<p>Now let’s try running our minimal application on actual hardware. Attach
the target device to your computer and run the application with
<code class="docutils literal notranslate"><span class="pre">newt</span> <span class="pre">run</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>~/dev/my_proj1$ newt run ble_tgt 0
App image succesfully generated: /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.img
&lt;...snip...&gt;
Resetting target
[Switching to Thread 57005]
0x000000dc in ?? ()
(gdb)
</pre></div>
</div>
<p>You can start the application by pressing <code class="docutils literal notranslate"><span class="pre">c</span> <span class="pre">&lt;enter&gt;</span></code> at the gdb
prompt. When the excitement of watching the idle loop run wears off,
quit gdb with <code class="docutils literal notranslate"><span class="pre">&lt;ctrl-c&gt;</span> <span class="pre">q</span> <span class="pre">&lt;enter&gt;</span></code>.</p>
<p>If your target fails to build or run, you might want to revisit the
<a class="reference internal" href="../blinky/blinky.html"><span class="doc">project blinky tutorial</span></a> to see if
there is a setup step you missed. You may also find help by posting a
question to the <a class="reference external" href="/community.html">mailing list</a> or searching the
archives.</p>
</div>
<div class="section" id="conclusion">
<h2><a class="toc-backref" href="#id6">Conclusion</a><a class="headerlink" href="#conclusion" title="Permalink to this headline"></a></h2>
<p>You now have a fully functional BLE app (never mind that it doesn’t
actually do anything yet!). With all the necessary infrastructure in
place, you can now start turning this into a real application. A good
next step would be to turn your app into a beaconing device. The <a class="reference internal" href="ibeacon.html"><span class="doc">BLE
iBeacon tutorial</span></a> builds on this one
and ends with a functioning iBeacon. For something a little more
ambitious, the <a class="reference internal" href="bleprph/bleprph.html"><span class="doc">BLE peripheral project
tutorial</span></a> describes a
NimBLE peripheral application in detail.</p>
</div>
</div>
</div>
</div>
<div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation">
<a href="ibeacon.html" class="btn btn-neutral float-right" title="BLE iBeacon" accesskey="n">Next: BLE iBeacon <span class="fa fa-arrow-circle-right"></span></a>
<a href="ble.html" class="btn btn-neutral" title="Bluetooth Low Energy" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: Bluetooth Low Energy</a>
</div>
</div>
</div>
</div>
<!-- ENDS CONTENT SECTION -->
</div>
<!-- ENDS .content -->
</div>
</div>
<footer>
<div class="container">
<div 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">
<img src="../../_static/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
<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>
<a href="">
<img src="../../_static/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
</div>
</div>
</footer>
</div>
<!-- ENDS #wrapper -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
LINK_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<script type="text/javascript" src="../../_static/js/bootstrap-3.0.3.min.js"></script>
<script type="text/javascript" src="../../_static/js/affix.js"></script>
<script type="text/javascript" src="../../_static/js/main.js"></script>
</body>
</html>