Google Git
Sign in
apache / mynewt-site / 8528acea806ecedcedbaec90568a1524b3ae623d / . / v1_3_0 / os / tutorials / add_newtmgr / index.html
blob: a7a66aa87c29260c0f3afd2708bc4ac586c129b9 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../img/favicon.ico">
<title>Enable Newt Manager in any app - 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="Enable Newt Manager in any app">
<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.11.0, Apache NimBLE 1.6.0 </a> released (September 7, 2023)
</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_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" selected="selected" >
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></li>
<li ><a href="../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../tutorials/">Tutorials</a>
<ul>
<li ><a href="../blinky/">Project Blinky</a>
</li>
<li ><a href="../repo/add_repos/">Work with repositories</a>
</li>
<li ><a href="../project-slinky/">Project Slinky for Remote Comms</a>
</li>
<li><a href="
../ble_bare_bones/
">Bluetooth Low Energy</a>
</li>
<li><a href="
../lora/lorawanapp/
">LoRa</a>
</li>
<li><a href="
../event_queue/
">OS Fundamentals</a>
</li>
<li><a href="
./
">Remote Device Management</a>
<ul>
<li class="active">
<a href="./">Enable Newt Manager in any app</a>
</li>
<li >
<a href="../ota_upgrade_nrf52/">Upgrade an Image Over-The-Air</a>
</li>
</ul>
</li>
<li><a href="
../sensors/sensors/
">Sensors</a>
</li>
<li><a href="
../segger_rtt/
">Tooling</a>
</li>
<li><a href="
../codesize/
">Other</a>
</li>
</ul>
</li>
<li ><a href="../../os_user_guide/">OS User Guide</a>
</li>
<li><a href="
../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../newt/install/prev_releases/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; Remote Device Management</li>
<li>&raquo; <a href="os/tutorials/tutorials/">Tutorials</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; Enable Newt Manager in any app</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/tutorials/add_newtmgr.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.3.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="enabling-newt-manager-in-your-application">Enabling Newt Manager in Your Application</h2>
<p><br>
In order for your application to communicate with the newtmgr tool and process Newt Manager commands, you must
enable Newt Manager device management and the support to process Newt Manager commands
in your application. This tutorial explains how to add the support to your application.</p>
<p>This tutorial assumes that you have read the <a href="/os/modules/devmgmt/newtmgr/">Device Management with Newt Manager</a>
guide and are familiar with the <code>newtmgr</code> and <code>oicmgr</code> frameworks and all the options that are available
to customize your application.</p>
<p>This tutorial shows you how to configure your application to:</p>
<ul>
<li>Use the newtmgr framework.</li>
<li>Use serial transport to communicate with the newtmgr tool.</li>
<li>Support all Newt Manager commands.</li>
</ul>
<p>See <a href="#other-configuration-options">Other Configuration Options</a> on how to customize your application.</p>
<p><br></p>
<h3 id="prerequisites">Prerequisites</h3>
<p>Ensure that you have met the following prerequisites before continuing with this tutorial:</p>
<ul>
<li>Have Internet connectivity to fetch remote Mynewt components.</li>
<li>Have a cable to establish a serial USB connection between the board and the laptop.</li>
<li>Install the newt tool and toolchains (See <a href="/os/get_started/get_started.md">Basic Setup</a>).</li>
<li>Install the <a href="../../../newtmgr/install_mac/">newtmgr tool</a>.</li>
</ul>
<p><br></p>
<h3 id="use-an-existing-project">Use an Existing Project</h3>
<p>We assume that you have worked through at least some of the other tutorials and have an existing project.
In this example, we modify the <code>btshell</code> app to enable Newt Manager support.
We call our target <code>myble</code>. You can create the target using any name you choose. </p>
<h3 id="modify-package-dependencies-and-configurations">Modify Package Dependencies and Configurations</h3>
<p>Add the following packages to the <code>pkg.deps</code> parameter in your target or application <code>pkg.yml</code> file:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.deps:
- mgmt/newtmgr
- mgmt/newtmgr/transport/nmgr_shell
- mgmt/imgmgr
- sys/log/full
- sys/stats/full
- sys/config
- test/crash_test
- test/runtest
</code></pre></div>
<p>Each package provides the following Newt Manager functionality:</p>
<ul>
<li><code>mgmt/newtmgr</code>: Supports the newtmgr framework and the
Newt Manager <code>echo</code>, <code>taskstat</code> <code>mpstat</code>, <code>datetime</code>, and <code>reset</code> commands.</li>
<li><code>mgmt/newtmgr/transport/nmgr_shell</code>: Supports serial transport.</li>
<li><code>mgmt/imgmgr</code>: Supports the <code>newtmgr image</code> command </li>
<li><code>sys/log/full</code> : Supports the <code>newtmgr log</code> command.</li>
<li><code>sys/stats/full</code>: Supports the <code>newtmgr stat</code> command. </li>
<li><code>sys/config</code>: Supports the <code>newtmgr config</code> command. </li>
<li><code>test/crash_test</code>: Supports the <code>newtmgr crash</code> command. </li>
<li><code>test/runtest</code>: Supports the <code>newt run</code> command.</li>
</ul>
<p>Add the following configuration setting values to the <code>syscfg.vals</code> parameter in the target or
application <code>syscfg.yml</code> file:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>syscfg.vals:
LOG_NEWTMGR: 1
STATS_NEWTMGR: 1
CONFIG_NEWTMGR: 1
CRASH_TEST_NEWTMGR: 1
RUNTEST_NEWTMGR: 1
SHELL_TASK: 1
SHELL_NEWTMGR: 1
</code></pre></div>
<p><br>
The first five configuration settings enable support for the Newt Manager <code>log</code>, <code>stat</code>, <code>config</code>, <code>crash</code>,
and <code>run</code> commands. The <code>SHELL_TASK</code> setting enables the shell for serial transport. The <code>SHELL_NEWTMGR</code> setting enables newtmgr support in the shell.</p>
<p>Note that you may need to override additional configuration settings that are specific to each package to customize the
package functionality.</p>
<p><br></p>
<h3 id="modify-the-source">Modify the Source</h3>
<p>By default, the <code>mgmt</code> package uses the Mynewt default event queue to receive request events from the newtmgr tool. These events are processed in the context of the application main task. </p>
<p>You can specify a different event queue for the package to use. If you choose to use a dedicated event queue, you must create a task to process events from this event queue. The <code>mgmt</code> package executes and handles newtmgr request events in the context of this task. The <code>mgmt</code> package exports the <code>mgmt_evq_set()</code> function that allows you to specify an event queue. </p>
<p>This example uses the Mynewt default event queue and you do not need to modify your application source. </p>
<p>If you choose to use a different event queue, see <a href="../event_queue/">Events and Event Queues</a> for details on how to initialize an event queue and create a task to process the events. You will also need to modify your <code>main.c</code> to add the call to the <code>mgmt_evq_set()</code> function as follows:</p>
<p>Add the <code>mgmt/mgmt.h</code> header file: </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>#include &lt;mgmt/mgmt.h&gt;
</code></pre></div>
<p><br>
Add the call to specify the event queue. In the <code>main()</code> function, scroll down to the <code>while (1)</code> loop and add the following statement above the loop: </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>mgmt_evq_set(&amp;my_eventq)
</code></pre></div>
<p>where <code>my_eventq</code> is an event queue that you have initialized.</p>
<h3 id="build-the-targets">Build the Targets</h3>
<p>Build the two targets as follows:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt build nrf52_boot
&lt;snip&gt;
App successfully built: ./bin/nrf52_boot/apps/boot/boot.elf
$ newt build myble
Compiling hci_common.c
Compiling util.c
Archiving nimble.a
Compiling os.c
&lt;snip&gt;
</code></pre></div>
<p><br></p>
<h3 id="create-the-application-image">Create the Application Image</h3>
<p>Generate an application image for the <code>myble</code> target. You can use any version number you choose.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt create-image myble 1.0.0
App image successfully generated: ./bin/makerbeacon/apps/btshell/btshell.img
Build manifest: ./bin/makerbeacon/apps/btshell/manifest.json
</code></pre></div>
<p><br></p>
<h3 id="load-the-image">Load the Image</h3>
<p>Ensure the USB connector is in place and the power LED on the board is lit. Turn the power switch on your board off,
then back on to reset the board after loading the image.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt load nrf52_boot
$ newt load myble
</code></pre></div>
<h3 id="set-up-a-connection-profile">Set Up a Connection Profile</h3>
<p>The newtmgr tool requires a connection profile in order to connect to your board. If you have not done so,
follow the <a href="../../../newtmgr/command_list/newtmgr_conn/">instructions</a> for setting up your connection profile.</p>
<p><br></p>
<h3 id="communicate-with-your-application">Communicate with Your Application</h3>
<p>Once you have a connection profile set up, you can connect to your device with <code>newtmgr -c myconn &lt;command&gt;</code> to run commands in your application. </p>
<p>Issue the <code>echo</code> command to ensure that your application is communicating with the newtmgr tool:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code># newtmgr -c myconn echo hello
hello
</code></pre></div>
<p><br>
Test your application to ensure that it can process a Newt Manager command that is supported by a different package.
Issue the <code>stat</code> command to see the BLE stats. </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>stat group: ble_att
0 error_rsp_rx
0 error_rsp_tx
0 exec_write_req_rx
0 exec_write_req_tx
0 exec_write_rsp_rx
0 exec_write_rsp_tx
0 find_info_req_rx
0 find_info_req_tx
0 find_info_rsp_rx
0 find_info_rsp_tx
0 find_type_value_req_rx
...
0 read_type_req_tx
0 read_type_rsp_rx
0 read_type_rsp_tx
0 write_cmd_rx
0 write_cmd_tx
0 write_req_rx
0 write_req_tx
0 write_rsp_rx
0 write_rsp_tx
</code></pre></div>
<p>Your application is now able to communicate with the newtmgr tool.</p>
<p><br></p>
<h3 id="other-configuration-options">Other Configuration Options</h3>
<p>This section explains how to customize your application to use other Newt Manager protocol options.</p>
<h4 id="newtmgr-framework-transport-protocol-options">Newtmgr Framework Transport Protocol Options</h4>
<p>The newtmgr framework currently supports BLE and serial transport protocols.
To configure the transport protocols that are supported, modify the <code>pkg.yml</code>
and <code>syscfg.yml</code> files as follows:</p>
<ul>
<li>Add the <code>mgmt/newtmgr/transport/ble</code> package to the <code>pkg.deps</code> parameter to enable BLE transport.</li>
<li>Add the <code>mgmt/newtmgr/transport/nmgr_shell</code> package to
the <code>pkg.deps</code> parameter, and add <code>SHELL_TASK: 1</code> and <code>SHELL_NEWTMGR</code> to the <code>syscfg.vals</code> parameter to enable serial transport when your application also uses the <a href="/os/modules/shell/shell.md">Shell</a>.</li>
<li>Add the <code>mgmt/newtmgr/transport/nmgr_uart</code> package to the <code>pkg.deps</code> parameter to enable serial transport over a UART port. You can use this package instead of the <code>nmgr_shell</code> package when your application does not use the <a href="/os/modules/shell/shell.md">Shell</a> or you want to use a dedicated UART port to communicate with newtmgr. You can change the <code>NMGR_UART</code> and <code>NMGR_URART_SPEED</code> sysconfig values to specify a different port.</li>
</ul>
<p><br></p>
<h4 id="oicmgr-framework-options">Oicmgr Framework Options</h4>
<p>To use the oicmgr framework instead of the newtmgr framework, modify the <code>pkg.yml</code> and <code>syscfg.yml</code> files
as follows:</p>
<ul>
<li>Add the <code>mgmt/oicmgr</code> package (instead of the <code>mgmt/newtmgr</code> and <code>mgmt/newtmgr/transport</code> packages
as described previously) to the <code>pkg.deps</code> parameter.</li>
<li>Add <code>OC_SERVER: 1</code> to the <code>syscfg.vals</code> parameter.</li>
</ul>
<p>Oicmgr supports the IP, serial, and BLE transport protocols. To configure the transport protocols that are supported,
set the configuration setting values in the <code>syscfg.vals</code> parameter as follows:</p>
<ul>
<li>Add <code>OC_TRANSPORT_IP: 1</code> to enable IP transport. </li>
<li>Add <code>OC_TRANSPORT_GATT: 1</code> to enable BLE transport.</li>
<li>Add <code>OC_TRANSPORT_SERIAL: 1</code>, <code>SHELL_TASK: 1</code>, <code>SHELL_NEWTMGR:1</code> to enable serial transport.</li>
</ul>
<p><br></p>
<h4 id="customize-the-newt-manager-commands-that-your-application-supports">Customize the Newt Manager Commands that Your Application Supports</h4>
<p>We recommend that you only enable support for the Newt Manager commands that your application uses
to reduce your application code size. To configure the commands that are supported, set the configuration
setting values in the <code>syscfg.vals</code> parameter as follows:</p>
<ul>
<li>Add <code>LOG_NEWTMGR: 1</code> to enable support for the <code>newtmgr log</code> command.</li>
<li>Add <code>STATS_NEWTMGR: 1</code> to enable support for the <code>newtmgr stat</code> command.</li>
<li>Add <code>CONFIG_NEWTMGR: 1</code> to enable support for the <code>newtmgr config</code> command.</li>
<li>Add <code>CRASH_TEST_NEWTMGR: 1</code> to enable support for the <code>newtmgr crash</code> command.</li>
<li>Add <code>RUNTEST_NEWTMGR: 1</code> to enable support for the <code>newtmgr crash</code> command.</li>
</ul>
<p>Notes: </p>
<ul>
<li>When you enable Newt Manager support, using either the newtmgr or oicmgr framework, your application automatically
supports the Newt Manager <code>echo</code>, <code>taskstat</code>, <code>mpstat</code>, <code>datetime</code>, and <code>reset</code> commands. These
commands cannot be configured individually.</li>
<li>The <code>mgmt/imgmgr</code> package does not provide a configuration setting to enable or disable support
for the <code>newtmgr image</code> command. Do not specify the package in the <code>pkg.deps</code> parameter if
your device has limited flash memory and cannot support Over-The-Air (OTA) firmware upgrades.</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 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>