| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| |
| <!-- This is broken by doc revisioning. |
| --> |
| <link rel="shortcut icon" href="../../../img/favicon.ico"> |
| |
| <title>Set up application - Apache Mynewt</title> |
| |
| <link href="../../../css/bootstrap-3.0.3.min.css" rel="stylesheet"> |
| <link rel="stylesheet" href="../../../css/highlight.css"> |
| <link href="../../../css/base.css" rel="stylesheet"> |
| <link href="../../../css/custom.css" rel="stylesheet"> |
| <link href="../../../css/v2.css" rel="stylesheet"> |
| <link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet"> |
| <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css"> |
| |
| <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> |
| <!--[if lt IE 9]> |
| <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> |
| <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script> |
| <![endif]--> |
| |
| |
| <script> |
| (function(i, s, o, g, r, a, m) { |
| i["GoogleAnalyticsObject"] = r; |
| (i[r] = |
| i[r] || |
| function() { |
| (i[r].q = i[r].q || []).push(arguments); |
| }), |
| (i[r].l = 1 * new Date()); |
| (a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]); |
| a.async = 1; |
| a.src = g; |
| m.parentNode.insertBefore(a, m); |
| })(window, document, "script", "//www.google-analytics.com/analytics.js", "ga"); |
| |
| ga("create", "UA-72162311-1", "auto"); |
| ga("send", "pageview"); |
| </script> |
| |
| </head> |
| |
| |
| <body class="Set up application"> |
| |
| |
| <div class="container"> |
| <div class="row v2-main-banner"> |
| <a class="logo-cell" href="/"> |
| <img class="logo" src="/img/logo.png"> |
| </a> |
| <div class="tagline-cell"> |
| <h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4> |
| </div> |
| <div class="news-cell"> |
| <div class="well"> |
| <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024) |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation"> |
| <div class="container"> |
| <!-- Collapsed navigation --> |
| <div class="navbar-header"> |
| <!-- Expander button --> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| |
| </div> |
| |
| <!-- Expanded navigation --> |
| <div class="navbar-collapse collapse"> |
| <!-- Main navigation --> |
| <ul class="nav navbar-nav navbar-right"> |
| <li |
| class="" |
| > |
| <a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a> |
| </li> |
| <li |
| class="important" |
| > |
| <a href="/quick-start/">Quick Start</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/about/">About</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/talks/">Talks</a> |
| </li> |
| <li |
| class="active" |
| > |
| <a href="/documentation/">Documentation</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/download/">Download</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/community/">Community</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/events/">Events</a> |
| </li> |
| </ul> |
| |
| </div> |
| </div> |
| </nav> |
| |
| |
| |
| <div class="container"> |
| |
| <div class="row"> |
| <div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary"> |
| <div class="top"> |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get"> |
| <div class="form-group"> |
| <input type="text" name="q" class="form-control" placeholder="Search documentation" /> |
| </div> |
| </form> |
| </div> |
| </div> |
| <ul class="toc-nav"> |
| <li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value"> |
| <option value="/latest"> |
| Version: master |
| </option> |
| <option value="/v1_12_0/" > |
| Version: 1.12.0 |
| </option> |
| <option value="/v1_11_0/" > |
| Version: 1.11.0 |
| </option> |
| <option value="/v1_10_0/" > |
| Version: 1.10.0 |
| </option> |
| <option value="/v1_9_0/" > |
| Version: 1.9.0 |
| </option> |
| <option value="/v1_8_0/" > |
| Version: 1.8.0 |
| </option> |
| <option value="/v1_7_0/" > |
| Version: 1.7.0 |
| </option> |
| <option value="/v1_6_0/" > |
| Version: 1.6.0 |
| </option> |
| <option value="/v1_5_0/" > |
| Version: 1.5.0 |
| </option> |
| <option value="/v1_4_0/" > |
| Version: 1.4.0 |
| </option> |
| <option value="/v1_3_0/os/introduction" > |
| Version: 1.3.0 |
| </option> |
| <option value="/v1_2_0/os/introduction" > |
| Version: 1.2.0 |
| </option> |
| <option value="/v1_1_0/os/introduction" > |
| Version: 1.1.0 |
| </option> |
| <option value="/v1_0_0/os/introduction" > |
| Version: 1.0.0 |
| </option> |
| <option value="/v0_9_0/os/introduction" selected="selected" > |
| Version: 0.9.0 |
| </option> |
| </select></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../os/introduction/">Mynewt Documentation</a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../os/get_started/get_started/">Basic Setup</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li > |
| <a href="../../../os/get_started/vocabulary/">Concepts</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../os/tutorials/tutorials/">Tutorials</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../os/os_user_guide/">OS User Guide</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../ble_intro/ |
| ">BLE User Guide</a> |
| |
| |
| <ul> |
| |
| |
| |
| <li > |
| <a href="../ble_intro/">NimBLE Introduction</a> |
| </li> |
| |
| |
| |
| |
| |
| <li > |
| <a href="../ble_sec/">NimBLE Security</a> |
| </li> |
| |
| |
| |
| |
| |
| <li class="active"> |
| <a href="./">Set up application</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../ini_stack/ble_ini_intro/">Initialize stack</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../bletiny_api/">API for bletiny app</a> |
| |
| |
| </li> |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../newt/newt_intro/">Newt Tool Guide</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../newtmgr/overview/">Newt Manager Guide</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li > |
| <a href="../../../known_issues/">Known Issues</a> |
| </li> |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../../../faq/how_to_edit_docs/ |
| ">Appendix</a> |
| |
| |
| </li> |
| |
| |
| |
| </ul> |
| </div></div> |
| |
| <div class="col-md-9" role="main"> |
| <div class="doc-header"> |
| <div role="navigation" aria-label="breadcrumbs navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="/documentation/">Docs</a></li> |
| |
| |
| |
| <li>» <a href="network/ble/ble_intro/">BLE User Guide</a></li> |
| |
| |
| |
| <li>» <a href="os/introduction/">Mynewt Documentation</a></li> |
| |
| |
| |
| <li>» Set up application</li> |
| |
| |
| |
| </ul> |
| </div> |
| </div> |
| |
| |
| |
| |
| <div class="alert alert-warning"> |
| <p> |
| Version 0.9.0 is not the most recent version of the Apache Mynewt |
| documentation. Click <a href="/latest">here</a> to read the latest |
| version. |
| </p> |
| </div> |
| |
| |
| |
| |
| |
| <h2 id="set-up-a-nimble-application">Set up a NimBLE application</h2> |
| <p>This tutorial explains how to set up an application using the NimBLE stack. The end result will be a framework that you can use to create your own BLE application using the nimble stack.</p> |
| <p>This tutorial assumes that you have already installed the newt tool and are familiar with its concepts.</p> |
| <h3 id="create-the-application-directory">Create the application directory</h3> |
| <p>You start by creating a project space for your own application work using the Newt tool (<code>my_proj1</code> in this example) and installing all the additional apps and libraries available by adding the repo <code>apache-mynewt-core</code>. See the tutorial on <a href="../../../os/tutorials/repo/add_repos/">adding a repo</a> for more on working with repos.</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev$ newt new my_proj1 |
| Downloading project skeleton from apache/incubator-mynewt-blinky... |
| Installing skeleton in my_proj1... |
| Project my_proj1 successfully created. |
| ~/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 |
| |
| ~/dev$ cd my_proj1 |
| ~/dev/my_proj1$ newt install |
| apache-mynewt-core |
| ~/dev/my_proj1$ tree |
| . |
| ├── DISCLAIMER |
| ├── LICENSE |
| ├── NOTICE |
| ├── README.md |
| ├── apps |
| │ └── blinky |
| │ ├── pkg.yml |
| │ └── src |
| │ └── main.c |
| ├── project.state |
| ├── project.yml |
| ├── repos |
| │ └── apache-mynewt-core |
| │ ├── DISCLAIMER |
| │ ├── LICENSE |
| │ ├── NOTICE |
| │ ├── README.md |
| │ ├── RELEASE_NOTES.md |
| │ ├── apps |
| │ │ ├── bleprph |
| │ │ │ └── src |
| │ │ │ ├── bleprph.h |
| │ │ │ ├── gatt_svr.c |
| │ │ │ └── main.c |
| │ │ ├── bletest |
| │ │ │ ├── pkg.yml |
| │ │ │ └── src |
| │ │ │ └── main.c |
| │ │ ├── bletiny |
| │ │ │ ├── pkg.yml |
| │ │ │ └── src |
| │ │ │ ├── bletiny_priv.h |
| │ │ │ ├── cmd.c |
| │ │ │ ├── main.c |
| │ │ │ ├── parse.c |
| │ │ │ └── periph.c |
| <snip> |
| |
| 232 directories, 846 files |
| </code></pre></div> |
| |
| <p><br></p> |
| <p>It's time to build your own app using one or more of the example apps available in the repo <code>apache-mynewt-core</code>. </p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev/my_proj1$ ls repos/apache-mynewt-core/apps |
| bleprph bletiny boot luatest test |
| bletest blinky ffs2native slinky |
| </code></pre></div> |
| |
| <p><br></p> |
| <p>At the very least your app must contain a <code>main()</code> function and a <code>pkg.yml</code> file. Use the following steps to create minimal ...</p> |
| <p><em>1. Create the app directory structure.</em></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev/my_proj1$ mkdir -p apps/ble_app/src |
| </code></pre></div> |
| |
| <p><br> |
| <em>2. Paste the following contents into <code>apps/ble_app/pkg.yml</code>.</em></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.name: apps/ble_app |
| pkg.type: app |
| |
| pkg.deps: |
| - "@apache-mynewt-core/libs/baselibc" |
| - "@apache-mynewt-core/libs/console/full" |
| - "@apache-mynewt-core/libs/os" |
| - "@apache-mynewt-core/net/nimble/controller" |
| - "@apache-mynewt-core/net/nimble/host" |
| </code></pre></div> |
| |
| <p><br> |
| <em>3. Paste the following contents into <code>apps/ble_app/src/main.c</code>.</em></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #633820">#include</span> <span style="color: #177500"><assert.h></span> |
| <span style="color: #633820">#include</span> <span style="color: #177500">"os/os.h"</span> |
| |
| <span style="color: #A90D91">int</span> |
| <span style="color: #000000">main</span>(<span style="color: #A90D91">void</span>) |
| { |
| <span style="color: #177500">/* Initialize OS */</span> |
| <span style="color: #000000">os_init</span>(); |
| |
| <span style="color: #177500">/* Start the OS */</span> |
| <span style="color: #000000">os_start</span>(); |
| |
| <span style="color: #177500">/* os_start should never return. If it does, this should be an error */</span> |
| <span style="color: #000000">assert</span>(<span style="color: #1C01CE">0</span>); |
| } |
| </code></pre></div> |
| |
| <p>In this <em>main()</em> all we are doing is initializing the Mynewt OS and starting it.</p> |
| <p><br></p> |
| <h3 id="create-the-target">Create the target</h3> |
| <p>Now you have to create the target that you will use to build your application. We will call this target "ble_tgt". Type the <code>newt target create ble_tgt</code> command. You should get this:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev/my_proj1$ newt target create ble_tgt |
| Target targets/ble_tgt successfully created |
| </code></pre></div> |
| |
| <p>What this command just did was to create a directory called <code>ble_tgt</code> in the targets directory of your project. Two files are created in that directory: pkg.yml and target.yml.</p> |
| <p>The target is not yet complete though! We need to set some target variables for this project. Currently, the nimble stack has been ported to the Nordic nrf5x chipsets; specifically the nrf51 and nrf52. This application will use the nrf52 but we will also show the setup for the nrf51 in case your project uses that chip.</p> |
| <p>Here is the command you will need to set up your target for the nrf52:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev/my_proj1$ newt target set ble_tgt \ |
| app=apps/ble_app \ |
| bsp=@apache-mynewt-core/hw/bsp/nrf52pdk \ |
| build_profile=optimized |
| Target targets/ble_tgt successfully set target.app to apps/ble_app |
| Target targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52pdk |
| Target targets/ble_tgt successfully set target.build_profile to optimized |
| </code></pre></div> |
| |
| <p>Here is the command you will need to set up your target for the nrf51:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev/my_proj1$ newt target set ble_tgt \ |
| app=apps/ble_app \ |
| bsp=@apache-mynewt-core/hw/bsp/nrf51dk \ |
| build_profile=optimized |
| Target targets/ble_tgt successfully set target.app to apps/ble_app |
| Target targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf51dk |
| Target targets/ble_tgt successfully set target.build_profile to optimized |
| </code></pre></div> |
| |
| <p><br></p> |
| <h3 id="nimble-stack-initialization">Nimble stack initialization</h3> |
| <p>There are certain stack initialization steps that are required for a BLE application to be up and running. If you are running a canned example (e.g. bletiny), these steps are already done for you. When you are writing your own app, you may want to assign different initial values or initialize additional packages that you may have added to your project or written yourself. </p> |
| <p>Details of the initialization step requirements are covered in <a href="../ini_stack/ble_ini_intro/">Initialize Stack</a> step.</p> |
| <p><br></p> |
| <h3 id="building-the-application">Building the application</h3> |
| <p>Now that we have created the application and the target we can build it and test it out. The command you need to run is the <code>newt build</code> command with the target we created (<em>ble_tgt</em>). The output will show the files being compiled and linked. You should see this when all is done (except for the <em>...</em> of course):</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>~/dev/my_proj1$ newt build ble_tgt |
| ... |
| Archiving os.a |
| Compiling cons_fmt.c |
| Compiling cons_tty.c |
| Archiving full.a |
| Linking ble_app.elf |
| App successfully built: /Users/wes/dev/my_proj1/bin/ble_tgt/apps/ble_app/ble_app.elf |
| </code></pre></div> |
| |
| <h3 id="conclusion">Conclusion</h3> |
| <p>You now have a fully functional BLE app (never mind the fact 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. Additional tutorials |
| with focus on adding application-layer functionality to your Nimble application |
| will be coming soon. In the meantime, you might get some inspiration from |
| apache-mynewt-core's example Nimble apps. These apps can be found at the below locations, relative to your project's base directory:</p> |
| <ul> |
| <li><em>repos/apache-mynewt-core/apps/bleprph</em></li> |
| <li><em>repos/apache-mynewt-core/apps/bletiny</em></li> |
| </ul> |
| |
| <div class="row"> |
| |
| |
| |
| |
| <ul class="nav nav-pills" style="margin-bottom: 10px"> |
| <li> |
| |
| </li> |
| <li class="pull-right"> |
| |
| </li> |
| </ul> |
| </div> |
| <footer class="row"> |
| <div class="col-xs-12"> |
| |
| <p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p> |
| |
| </div> |
| <div class="col-xs-12"> |
| <div class="logos"> |
| <a href="https://www.apache.org/"> |
| <img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache"> |
| </a> |
| <p> |
| Copyright © 2015-2021 The Apache Software Foundation.<br> |
| <small class="footnote"> |
| Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt |
| project logo are either registered trademarks or trademarks of the Apache |
| Software Foundation in the United States and other countries. |
| </small> |
| </p> |
| <a href=""> |
| <img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /> |
| </a> |
| </div> |
| </div> |
| <a href="https://www.apache.org/licenses/"> |
| <button class="button-footer-asf"> |
| License |
| </button> |
| </a> |
| <a href="https://www.apache.org/foundation/sponsorship.html"> |
| <button class="button-footer-asf"> |
| Sponsorship |
| </button> |
| </a> |
| <a href="https://www.apache.org/foundation/thanks.html"> |
| <button class="button-footer-asf"> |
| Thanks |
| </button> |
| </a> |
| <a href="https://www.apache.org/security/"> |
| <button class="button-footer-asf"> |
| Security |
| </button> |
| </a> |
| <a href="https://apache.org/events/current-event"> |
| <button class="button-footer-asf"> |
| ASF Events |
| </button> |
| </a> |
| </footer> |
| </div> |
| </div> |
| |
| |
| </div> |
| |
| <script src="../../../js/jquery-1.10.2.min.js"></script> |
| <script src="../../../js/bootstrap-3.0.3.min.js"></script> |
| <script src="../../../js/highlight.pack.js"></script> |
| <script src="../../../js/base.js"></script> |
| <script src="../../../js/custom.js"></script> |
| <script src="search/main.js"></script> |
| |
| </body> |
| </html> |
