Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_0_0 / os / get_started / docker / index.html
blob: 6725cce2bbb6e921a76de8ae6977249e169d3d19 [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>Docker Container Option - 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="Docker Container Option">
<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" selected="selected" >
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/">Basic Setup</a>
<ul>
<li ><a href="../native_install_intro/">Native Install Option</a>
</li>
<li class="active">
<a href="./">Docker Container Option</a>
</li>
<li >
<a href="../project_create/">Create Your First Project</a>
</li>
<li >
<a href="../serial_access/">Serial Port Setup</a>
</li>
</ul>
</li>
<li >
<a href="../vocabulary/">Concepts</a>
</li>
<li ><a href="../../tutorials/tutorials/">Tutorials</a>
</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>&raquo; <a href="os/get_started/get_started/">Basic Setup</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; Docker Container Option</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.0.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="everything-you-need-in-a-docker-container">Everything You Need in a Docker Container</h2>
<p>Docker provides a quick and easy way to get up and running with Mynewt. The
newt command line tool and the entire build toolchain is available in a single
docker container. The container is all that's needed to run your Mynewt based
application in the simulator. Enabling USB2 with your docker installation will
allow you to load your application on a supported device.</p>
<p>Docker is the only supported option if you are working on a Windows machine. If you are using Mac OS X or Linux, you have the choice of installing a Docker container of tools and toolchains or installing them natively. This chapter describes how to set up the Docker image for all three platforms.</p>
<p><br></p>
<h3 id="install-docker">Install Docker</h3>
<p>Install docker for your platform. <a href="https://www.docker.com/products/docker-toolbox">Mac OS X</a> / <a href="https://www.docker.com/products/docker-toolbox">Windows</a> / <a href="https://docs.docker.com/engine/installation/linux/">Linux</a></p>
<h4 id="mac-and-windows">Mac and Windows</h4>
<p>Mac and Windows require Docker Toolbox to interact with USB devices. Docker
for Mac and Docker for Windows do not support USB. Docker Toolbox uses
VirtualBox and allows you to map USB devices into docker containers as
described below.</p>
<p>Make sure to double click the Docker Quickstart Terminal application if you're
on Mac or Windows.</p>
<h4 id="linux">Linux</h4>
<p>The docker daemon listens on a Unix domain socket on Linux. That socket is
owned by root, which means by default you must be root to start a container.
Make sure to follow the optional step of adding yourself to the docker group so
you can start the newt container as yourself.</p>
<p><br></p>
<h3 id="use-the-newt-wrapper-script">Use the newt wrapper script</h3>
<p>Use the newt wrapper script to invoke newt. Create the following file, name it
<code>newt</code>, make it executable, and put it in your path. This will allow you to run newt as if it was natively installed. You can now follow the normal tutorials using the newt wrapper script.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #177500">#!/bin/bash</span>
<span style="color: #A90D91">if</span> <span style="color: #000000">[</span> <span style="color: #C41A16">&quot;</span><span style="color: #000000">$1</span><span style="color: #C41A16">&quot;</span> <span style="color: #000000">=</span> <span style="color: #C41A16">&quot;debug&quot;</span> <span style="color: #000000">]</span> <span style="color: #000000">||</span> <span style="color: #000000">[</span> <span style="color: #C41A16">&quot;</span><span style="color: #000000">$1</span><span style="color: #C41A16">&quot;</span> <span style="color: #000000">=</span> <span style="color: #C41A16">&quot;run&quot;</span> <span style="color: #000000">]</span>
<span style="color: #A90D91">then</span>
<span style="color: #000000">ti=</span><span style="color: #C41A16">&quot;-ti&quot;</span>
<span style="color: #A90D91">fi</span>
docker run -e <span style="color: #000000">NEWT_USER=</span><span style="color: #A90D91">$(</span>id -u<span style="color: #A90D91">)</span> -e <span style="color: #000000">NEWT_GROUP=</span><span style="color: #A90D91">$(</span>id -g<span style="color: #A90D91">)</span> -e <span style="color: #000000">NEWT_HOST=</span><span style="color: #A90D91">$(</span>uname<span style="color: #A90D91">)</span> <span style="color: #000000">$ti</span> --rm --device<span style="color: #000000">=</span>/dev/bus/usb --privileged -v <span style="color: #A90D91">$(pwd)</span>:/workspace -w /workspace mynewt/newt:latest /newt <span style="color: #C41A16">&quot;</span><span style="color: #000000">$@</span><span style="color: #C41A16">&quot;</span>
</code></pre></div>
<p><br></p>
<p><strong>Note 1:</strong> Remember to point to the correct subdirectory level when invoking <code>newt</code>. For example, invoke it using <code>../newt</code> in the example below.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>user@~/dockertest$ ls
myproj newt
user@~/dockertest$ cd myproj
<span style="background-color: #ffffcc">user@~/dockertest/myproj$ ../newt version
</span>Apache Newt (incubating) version: 0.8.0-b2
</code></pre></div>
<p><br></p>
<p><strong>Note 2:</strong> You can upgrade your container by running <code>docker pull mynewt/newt:latest</code> when updates are made available.</p>
<p><br></p>
<h3 id="enable-usb2-support-for-mac-or-windows">Enable USB2 Support for Mac or Windows</h3>
<p>If you plan on loading your application on an actual device, do the steps below.</p>
<p><br></p>
<h4 id="install-virtualbox-extension-pack">Install VirtualBox extension pack</h4>
<p>Docker uses a VirtualBox Linux VM to run containers. A free VirtualBox
extension pack is required to enable USB2 support. Download the <a href="http://download.virtualbox.org/virtualbox/5.0.16/Oracle_VM_VirtualBox_Extension_Pack-5.0.16-105871.vbox-extpack">VirtualBox
5.0.16 Oracle VM VirtualBox Extension
Pack</a>
and double click to install</p>
<p><br></p>
<h4 id="enable-usb2-and-select-your-device">Enable USB2 and select your device</h4>
<ul>
<li>
<p>The "default" VM created by docker-machine must first be stopped before you
can enable USB2. You have two options:</p>
<ul>
<li>Run the command <code>docker-machine stop default</code> in the terminal window or</li>
<li>Use the VirtualBox UI. Right click on <code>default</code> -&gt; Close -&gt; Power Off</li>
</ul>
</li>
<li>
<p>Enable USB2 using the VirtualBox UI. Select the "default"
VM-&gt;Settings-&gt;Ports-&gt;USB2 to enable USB2. Add your device to the USB Device
Filters to make the device visible in the docker container. See the image below.</p>
</li>
</ul>
<p><img src="../pics/virtualbox_usb.jpg" width="728px" /></p>
<ul>
<li>Restart the "default" VM. You have two options:<ul>
<li>Run <code>docker-machine start default</code> in the terminal window or </li>
<li>Use the VirtualBox UI. Make sure the "default" machine is highlighted. Click the green "Start" button. Select "Headless Start".</li>
</ul>
</li>
</ul>
<p><br></p>
<p><strong>Note 3</strong>: When working with actual hardware, remember that each board has an ID. If you swap boards and do not refresh the USB Device Filter on the VirtualBox UI, the ID might be stale and the Docker instance may not be able to see the board correctly. For example, you may see an error message like <code>Error: unable to find CMSIS-DAP device</code> when you try to load or run an image on the board. In that case, you need to click on the USB link in VirtualBox UI, remove the existing USB Device Filter (e.g. "Atmel Corp. EDBG CMSIS-DAP[0101]") by clicking on the "Removes selected USB filter" button, and add a new filter by clicking on the "Adds new USB filter" button.</p>
<p><br></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 (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>