blob: 5238ec9e4afec523687fdbb3475a7bbb149dffd8 [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>newtmgr image &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="Command List" href="index.html"/>
<link rel="next" title="newtmgr log" href="newtmgr_logs.html"/>
<link rel="prev" title="newtmgr fs" href="newtmgr_fs.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="../index.html">Newt Manager Guide</a> /
<a href="index.html">Command List</a> /
newtmgr image
<div class="sourcelink">
<a href="https://github.com/apache/mynewt-newtmgr/edit/master/docs/command_list/newtmgr_image.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" selected="selected" >
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"><a class="reference internal" href="../../tutorials/tutorials.html">Tutorials</a></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 current"><a class="reference internal" href="../index.html">Newt Manager Guide</a><ul class="current">
<li class="toctree-l2 current"><a class="reference internal" href="index.html">Command List</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="newtmgr_config.html">newtmgr config</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_conn.html">newtmgr conn</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_crash.html">newtmgr crash</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_datetime.html">newtmgr datetime</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_echo.html">newtmgr echo</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_fs.html">newtmgr fs</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">newtmgr image</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_logs.html">newtmgr log</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_mpstats.html">newtmgr mpstat</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_reset.html">newtmgr reset</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_run.html">newtmgr run</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_stat.html">newtmgr stat</a></li>
<li class="toctree-l3"><a class="reference internal" href="newtmgr_taskstats.html">newtmgr taskstat</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../install/index.html">Install</a></li>
</ul>
</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="alert alert-warning">
<p>
Version 1.6.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>
<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="newtmgr-image">
<h1>newtmgr image<a class="headerlink" href="#newtmgr-image" title="Permalink to this headline">¶</a></h1>
<p>Manage images on a device.</p>
<div class="section" id="usage">
<h2>Usage:<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">newtmgr image [command] -c &lt;connection_profile&gt; [flags]</span>
</pre></div>
</div>
</div>
<div class="section" id="flags">
<h2>Flags:<a class="headerlink" href="#flags" title="Permalink to this headline">¶</a></h2>
<p>The coredownload subcommand uses the following local flags:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">-n, --bytes uint32 Number of bytes of the core to download</span>
<span class="go">-e, --elfify Create an ELF file</span>
<span class="go"> --offset unint32 Offset of the core file to start the download</span>
</pre></div>
</div>
</div>
<div class="section" id="global-flags">
<h2>Global Flags:<a class="headerlink" href="#global-flags" title="Permalink to this headline">¶</a></h2>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">-c, --conn string connection profile to use</span>
<span class="go">-h, --help help for newtmgr</span>
<span class="go">-l, --loglevel string log level to use (default &quot;info&quot;)</span>
<span class="go"> --name string name of target BLE device; overrides profile setting</span>
<span class="go">-t, --timeout float timeout in seconds (partial seconds allowed) (default 10)</span>
<span class="go">-r, --tries int total number of tries in case of timeout (default 1)</span>
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>The image command provides subcommands to manage core and image files on a device. Newtmgr uses the <code class="docutils literal notranslate"><span class="pre">conn_profile</span></code>
connection profile to connect to the device.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 95%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Sub-command</p></th>
<th class="head"><p>Explanation</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>confirm</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">confirm</span> <span class="pre">[hex-image-hash]</span></code> command makes an image setup permanent on a device. If a <code class="docutils literal notranslate"><span class="pre">hex-image-hash</span></code> hash value is specified, Mynewt permanently switches to the image identified by the hash value. If a hash value is not specified, the current image is made permanent.</p></td>
</tr>
<tr class="row-odd"><td><p>coreconvert</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coreconvert</span> <span class="pre">&lt;core-filename&gt;</span> <span class="pre">&lt;elf-file&gt;</span></code> command converts the <code class="docutils literal notranslate"><span class="pre">core-filename</span></code> core file to an ELF format and names it <code class="docutils literal notranslate"><span class="pre">elf-file</span></code>. <strong>Note</strong>: This command does not download the core file from a device. The core file must exist on your host.</p></td>
</tr>
<tr class="row-even"><td><p>coredownload</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coredownload</span> <span class="pre">&lt;core-filename&gt;</span></code> command downloads the core file from a device and names the file <code class="docutils literal notranslate"><span class="pre">core-filename</span></code> on your host. Use the local flags under Flags to customize the command.</p></td>
</tr>
<tr class="row-odd"><td><p>coreerase</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coreerase</span></code> command erases the core file on a device.</p></td>
</tr>
<tr class="row-even"><td><p>corelist</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">corelist</span></code> command lists the core(s) on a device.</p></td>
</tr>
<tr class="row-odd"><td><p>erase</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">erase</span></code> command erases an unused image from the secondary image slot on a device. The image cannot be erased if the image is a confirmed image, is marked for test on the next reboot, or is an active image for a split image setup.</p></td>
</tr>
<tr class="row-even"><td><p>list</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">list</span></code> command displays information for the images on a device.</p></td>
</tr>
<tr class="row-odd"><td><p>test</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">test</span> <span class="pre">&lt;hex-image-hash&gt;</span></code> command tests the image, identified by the <code class="docutils literal notranslate"><span class="pre">hex-image-hash</span></code> hash value, on next reboot.</p></td>
</tr>
<tr class="row-even"><td><p>upload</p></td>
<td><p>The <code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">upload</span> <span class="pre">&lt;image-file&gt;</span></code> command uploads the <code class="docutils literal notranslate"><span class="pre">image-file</span></code> image file to a device.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<table class="docutils align-default">
<colgroup>
<col style="width: 5%" />
<col style="width: 23%" />
<col style="width: 71%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Sub-command</p></th>
<th class="head"><p>Usage</p></th>
<th class="head"><p>Explanation</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>confirm</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">confirm-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Makes the current image setup on a device permanent. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-odd"><td><p>confirm</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">confirmbe9699809a049...73d77f-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Makes the image, identified by the <code class="docutils literal notranslate"><span class="pre">be9699809a049...73d77f</span></code> hash value, setup on a device permanent. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-even"><td><p>coreconvert</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coreconvert</span> <span class="pre">mycore</span> <span class="pre">mycore.elf</span></code></p></td>
<td><p>Converts the <code class="docutils literal notranslate"><span class="pre">mycore</span></code> file to the ELF format and saves it in the <code class="docutils literal notranslate"><span class="pre">mycore.elf</span></code> file.</p></td>
</tr>
<tr class="row-odd"><td><p>coredownload</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coredownload</span> <span class="pre">mycore</span> <span class="pre">-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Downloads the core from a device and saves it in the <code class="docutils literal notranslate"><span class="pre">mycore</span></code> file. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-even"><td><p>coredownload</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coredownload</span> <span class="pre">mycore</span> <span class="pre">-e</span> <span class="pre">-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Downloads the core from a device, converts the core file into the ELF format, and saves it in the <code class="docutils literal notranslate"><span class="pre">mycore</span></code> file. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-odd"><td><p>coredownload</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coredownload</span> <span class="pre">mycore</span> <span class="pre">--offset</span> <span class="pre">10</span> <span class="pre">-n</span> <span class="pre">30-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Downloads 30 bytes, starting at offset 10, of the core from a device and saves it in the <code class="docutils literal notranslate"><span class="pre">mycore</span></code> file. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-even"><td><p>coreerase</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">coreerase</span> <span class="pre">-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Erases the core file on a device. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-odd"><td><p>corelist</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">corelist-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Lists the core files on a device. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-even"><td><p>erase</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">erase-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Erases the image, if unused, from the secondary image slot on a device. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-odd"><td><p>list</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">list-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Lists the images on a device. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-even"><td><p>test</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">test</span> <span class="pre">be9699809a049...73d77f</span></code></p></td>
<td><p>Tests the image, identified by the <code class="docutils literal notranslate"><span class="pre">be9699809a049...73d77f</span></code> hash value, during the next reboot on a device. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
<tr class="row-odd"><td><p>upload</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">newtmgr</span> <span class="pre">image</span> <span class="pre">upload</span> <span class="pre">btshell.img-c</span> <span class="pre">profile01</span></code></p></td>
<td><p>Uploads the <code class="docutils literal notranslate"><span class="pre">btshell.img</span></code> image to a device. Newtmgr connects to the device over a connection specified in the <code class="docutils literal notranslate"><span class="pre">profile01</span></code> connection profile.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation">
<a href="newtmgr_logs.html" class="btn btn-neutral float-right" title="newtmgr log" accesskey="n">Next: newtmgr log <span class="fa fa-arrow-circle-right"></span></a>
<a href="newtmgr_fs.html" class="btn btn-neutral" title="newtmgr fs" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: newtmgr fs</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>