| <!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>Upgrade an Image Over-The-Air - 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="Upgrade an Image Over-The-Air"> |
| |
| |
| <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" selected="selected" > |
| 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=" |
| ../event_queue/ |
| ">OS Fundamentals</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../add_newtmgr/ |
| ">Remote Device Management</a> |
| |
| |
| <ul> |
| |
| |
| |
| <li > |
| <a href="../add_newtmgr/">Enable Newt Manager in any app</a> |
| </li> |
| |
| |
| |
| |
| |
| <li class="active"> |
| <a href="./">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=" |
| ../../../faq/go_env/ |
| ">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="os/tutorials/add_newtmgr/">Remote Device Management</a></li> |
| |
| |
| |
| <li>» <a href="os/tutorials/tutorials/">Tutorials</a></li> |
| |
| |
| |
| <li>» <a href="os/introduction/">Mynewt Documentation</a></li> |
| |
| |
| |
| <li>» Upgrade an Image Over-The-Air</li> |
| |
| |
| |
| <li class="wy-breadcrumbs-aside"> |
| |
| <a href="https://github.com/apache/mynewt-site/blob/master/docs/os/tutorials/ota_upgrade_nrf52.md" |
| class="icon icon-github"> Edit on GitHub</a> |
| |
| </li> |
| |
| </ul> |
| </div> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="alert alert-warning"> |
| <p> |
| Version 1.1.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="over-the-air-image-upgrade">Over-the-Air Image Upgrade</h2> |
| <p>Mynewt OS supports over-the-air image upgrades. This tutorial shows you how to use the newtmgr tool to upgrade an image on a device over BLE communication. </p> |
| <p>To support over-the-air image upgrade over BLE, a device must be running a Mynewt application that has newtmgr image management over BLE transport enabled. For this tutorial, we use the <a href="/os/tutorials/bleprph/bleprph-app/">bleprph</a> application, which includes image management over BLE functionality, on an nRF52-DK board. If you prefer to use a different BLE application, see <a href="/os/tutorials/add_newtmgr/">Enable Newt Manager in any app</a> to enable newtmgr image management over BLE transport support in your application. </p> |
| <p><strong>Note:</strong> Over-the-air upgrade via newtmgr BLE transport is supported on Mac OS and Linux. It is not supported on Windows platforms.</p> |
| <h3 id="prerequisites">Prerequisites</h3> |
| <p>Ensure that you meet the following prerequisites:</p> |
| <ul> |
| <li>Have Internet connectivity to fetch remote Mynewt components.</li> |
| <li>Have a computer that supports Bluetooth to communicate with the board and to build a Mynewt application. </li> |
| <li>Have a Micro-USB cable to connect the board and the computer.</li> |
| <li>Have a Nordic nRF52-DK Development Kit - PCA 10040</li> |
| <li>Install the <a href="https://www.segger.com/jlink-software.html">Segger JLINK software and documentation pack</a>.</li> |
| <li>Install the newt tool and toolchains (See <a href="/os/get_started/get_started.md">Basic Setup</a>).</li> |
| <li>Read the Mynewt OS <a href="/os/get_started/vocabulary.md">Concepts</a> section.</li> |
| <li>Read the <a href="/os/modules/bootloader/bootloader">Bootloader</a> section and understand the Mynewt bootloader concepts.</li> |
| <li>Build and load the <strong>bleprph</strong> application on to an nRF52-DK board via a serial connection. See <a href="/os/tutorials/bleprph/bleprph-app/">BLE Peripheral App</a>. </li> |
| </ul> |
| <p><br></p> |
| <h3 id="reducing-the-log-level">Reducing the Log Level</h3> |
| <p>You need to build your application with log level set to INFO or lower. The default log level for the <strong>bleprph</strong> app is set to DEBUG. The extra logging causes the communication to timeout. Perform the following to reduce the log level to INFO, build, and load the application. </p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt target amend myperiph syscfg="LOG_LEVEL=1" |
| $ newt build myperiph |
| $ newt create-image myperiph 1.0.0 |
| $ newt load myperiph |
| </code></pre></div> |
| |
| <p><br></p> |
| <h3 id="upgrading-an-image-on-a-device">Upgrading an Image on a Device</h3> |
| <p>Once you have an application with newtmgr image management with BLE transport support running on a device, you can use the newtmgr tool to upgrade an image over-the-air. </p> |
| <p>You must perform the following steps to upgrade an image:</p> |
| <p>Step 1: Create a newtmgr connection profile to communicate with the device over BLE. |
| <br> |
| Step 2: Upload the image to the secondary slot (slot 1) on the device. |
| <br> |
| Step 3: Test the image. |
| <br> |
| Step 4: Confirm and make the image permanent. </p> |
| <p>See the <a href="/os/modules/bootloader/bootloader">Bootloader</a> section for more information on the bootloader, image slots, and boot states.</p> |
| <p><br></p> |
| <h3 id="step-1-creating-a-newtmgr-connection-profile">Step 1: Creating a Newtmgr Connection Profile</h3> |
| <p>The <strong>bleprph</strong> application sets and advertises <code>nimble-bleprph</code> as its bluetooth device address. Run the <code>newtmgr conn add</code> command to create a newtmgr connection profile that uses this peer address to communicate with the device over BLE: |
| <br></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr conn add mybleprph type=ble connstring="peer_name=nimble-bleprph" |
| Connection profile mybleprph successfully added |
| </code></pre></div> |
| |
| <p><br> |
| Verify that the newtmgr tool can communicate with the device and check the image status on the device: |
| <br></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr image list -c mybleprph |
| Images: |
| slot=0 |
| version: 1.0.0 |
| bootable: true |
| flags: active confirmed |
| hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2 |
| Split status: N/A (0) |
| </code></pre></div> |
| |
| <p>The device only has an image loaded on the primary slot (slot 0). It does not have an image loaded on the secondary slot (slot 1). |
| <br></p> |
| <h3 id="step-2-uploading-an-image-to-the-device">Step 2: Uploading an Image to the Device</h3> |
| <p>We create an image with version 2.0.0 for the bleprph application from the <code>myperiph</code> target and upload the new image. You can upload a different image. |
| <br></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt create-image myperiph 2.0.0 |
| App image succesfully generated: ~/dev/myproj/bin/targets/myperiph/app/apps/bleprph/bleprph.img |
| </code></pre></div> |
| |
| <p><br> |
| Run the <code>newtmgr image upload</code> command to upload the image:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr image upload -c mybleprph ~/dev/myproj/bin/targets/myperiph/app/apps/bleprph/bleprph.img |
| 215 |
| 429 |
| 642 |
| 855 |
| 1068 |
| 1281 |
| |
| ... |
| |
| 125953 |
| 126164 |
| 126375 |
| 126586 |
| 126704 |
| Done |
| </code></pre></div> |
| |
| <p>The numbers indicate the number of bytes that the newtmgr tool has uploaded. </p> |
| <p><br> |
| Verify that the image uploaded to the secondary slot on the device successfully: |
| <br></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr image list -c mybleprph |
| Images: |
| slot=0 |
| version: 1.0.0 |
| bootable: true |
| flags: active confirmed |
| hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2 |
| slot=1 |
| version: 2.0.0 |
| bootable: true |
| flags: |
| hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682 |
| Split status: N/A (0) |
| </code></pre></div> |
| |
| <p>The device now has the uploaded image in the secondary slot (slot 1). |
| <br></p> |
| <h3 id="step-3-testing-the-image">Step 3: Testing the Image</h3> |
| <p>The image is uploaded to the secondary slot but is not yet active. You must run the <code>newtmgr image test</code> command to set the image status to <strong>pending</strong> and reboot the device. When the device reboots, the bootloader copies this image to the primary slot and runs the image. |
| <br></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr image test -c mybleprph 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682 |
| Images: |
| slot=0 |
| version: 1.0.0 |
| bootable: true |
| flags: active confirmed |
| hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2 |
| slot=1 |
| version: 2.0.0 |
| bootable: true |
| flags: pending |
| hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682 |
| Split status: N/A (0) |
| </code></pre></div> |
| |
| <p>The status of the image in the secondary slot is now set to <strong>pending</strong>. </p> |
| <p><br> |
| Power the device OFF and ON and run the <code>newtmgr image list</code> command to check the image status on the device after the reboot: |
| <br></p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr image list -c mybleprph |
| Images: |
| slot=0 |
| version: 2.0.0 |
| bootable: true |
| flags: active |
| hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682 |
| slot=1 |
| version: 1.0.0 |
| bootable: true |
| flags: confirmed |
| hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2 |
| Split status: N/A (0) |
| </code></pre></div> |
| |
| <p>The uploaded image is now active and running in the primary slot. The image, however, is not confirmed. The confirmed image is in the secondary slot. On the next reboot, the bootloader reverts to using the confirmed image. It copies the confirmed image to the primary slot and runs the image when the device reboots. You need to confirm and make the uploaded image in the primary slot permanent. |
| <br></p> |
| <h3 id="step-4-confirming-the-image">Step 4: Confirming the Image</h3> |
| <p>Run the <code>newtmgr image confirm</code> command to confirm and make the uploaded image permanent. Since the uploaded image is currently the active image, you can confirm the image setup without specifying the image hash value in the command:</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newtmgr image confirm -c mybleprph |
| Images: |
| slot=0 |
| version: 2.0.0 |
| bootable: true |
| flags: active confirmed |
| hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682 |
| slot=1 |
| version: 1.0.0 |
| bootable: true |
| flags: |
| hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2 |
| Split status: N/A (0) |
| </code></pre></div> |
| |
| <p>The uploaded image is now the active and confirmed image. You have successfully upgraded an image over-the-air.</p> |
| |
| <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> |
