Google Git
Sign in
apache / mynewt-site / 8528acea806ecedcedbaec90568a1524b3ae623d / . / v1_1_0 / os / tutorials / blinky_console / index.html
blob: fd7a1a9dc67708632f77b2c69c2e2aed32ee6542 [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>Add Console and Shell to Blinky - 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="Add Console and Shell to Blinky">
<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" >
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>
<ul>
<li >
<a href="../arduino_zero/">Blinky on Arduino Zero</a>
</li>
<li >
<a href="../blinky_primo/">Blinky on Arduino Primo</a>
</li>
<li >
<a href="../olimex/">Blinky on Olimex</a>
</li>
<li >
<a href="../nRF52/">Blinky on nRF52 DK</a>
</li>
<li >
<a href="../rbnano2/">Blinky on RedBear Nano 2</a>
</li>
<li >
<a href="../blinky_stm32f4disc/">Blinky on STM32F4-Discovery</a>
</li>
<li class="active">
<a href="./">Add Console and Shell to Blinky</a>
</li>
</ul>
</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>
</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>&raquo; <a href="os/tutorials/blinky/">Project Blinky</a></li>
<li>&raquo; <a href="os/tutorials/tutorials/">Tutorials</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; Add Console and Shell to Blinky</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/tutorials/blinky_console.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="enabling-the-console-and-shell-for-blinky">Enabling The Console and Shell for Blinky</h2>
<p>This tutorial shows you how to add the Console and Shell to the Blinky application and interact with it over a serial line connection.
<br></p>
<h3 id="prerequisites">Prerequisites</h3>
<ul>
<li>Work through one of the Blinky Tutorials to create and build a Blinky application for one of the boards.</li>
<li>Have a <a href="/os/get_started/serial_access.md">serial setup</a>.</li>
</ul>
<p><br></p>
<h3 id="use-an-existing-project">Use an Existing Project</h3>
<p>Since all we're doing is adding the shell and console capability to blinky, we assume
that you have worked through at least some of the other tutorials, and have an existing project.
For this example, we'll be modifying the <a href="../nRF52/">blinky on nrf52</a> project to enable
the shell and console connectivity. You can use blinky on a different board.</p>
<p><br></p>
<h3 id="modify-the-dependencies-and-configuration">Modify the Dependencies and Configuration</h3>
<p>Modify the package dependencies in your application target's <code>pkg.yml</code> file as follows:</p>
<ul>
<li>Add the shell package: <code>@apache-mynewt-core/sys/shell</code>.</li>
<li>
<p>Replace the <code>@apache-mynewt-core/sys/console/stub</code> package with the <code>@apache-mynewt-core/sys/console/full</code> package. </p>
<p><strong>Note</strong>: If you are using version 1.1 or lower of blinky, the <code>@apache-mynewt-core/sys/console/full</code> package may be already listed as a dependency.</p>
</li>
</ul>
<p>The updated <code>pkg.yml</code> file should have the following two lines:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>pkg.deps:
- &quot;@apache-mynewt-core/sys/console/full&quot;
- &quot;@apache-mynewt-core/sys/shell&quot;
</code></pre></div>
<p>This lets the newt system know that it needs to pull in the code for the console and the shell.</p>
<p>Modify the system configuration settings to enable Shell and Console ticks and prompt. Add the following to your application target's <code>syscfg.yml</code> file:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>syscfg.vals:
# Enable the shell task.
SHELL_TASK: 1
SHELL_PROMPT_MODULE: 1
</code></pre></div>
<p><br></p>
<h3 id="use-the-os-default-event-queue-to-process-blinky-timer-and-shell-events">Use the OS Default Event Queue to Process Blinky Timer and Shell Events</h3>
<p>Mynewt creates a main task that executes the application <code>main()</code> function. It also creates an OS default event queue that packages can use to queue their events. Shell uses the OS default event queue for Shell events, and <code>main()</code> can process the events in the context of the main task. </p>
<p>Blinky's main.c is very simple. It only has a <code>main()</code> function that executes an infinite loop to toggle the LED and sleep for one second. We will modify blinky:</p>
<ul>
<li>To use os_callout to generate a timer event every one second instead of sleeping. The timer events are added to the OS default event queue.</li>
<li>To process events from the OS default event queue inside the infinite loop in <code>main()</code>.</li>
</ul>
<p>This allows the main task to process both Shell events and the timer events to toggle the LED from the OS default event queue.</p>
<p><br></p>
<h3 id="modify-mainc">Modify main.c</h3>
<p>Initialize a os_callout timer and move the toggle code from the while loop in <code>main()</code> to the event callback function. Add the following code above the <code>main()</code> function:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #177500">/* The timer callout */</span>
<span style="color: #A90D91">static</span> <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_callout</span> <span style="color: #000000">blinky_callout</span>;
<span style="color: #177500">/*</span>
<span style="color: #177500"> * Event callback function for timer events. It toggles the led pin.</span>
<span style="color: #177500"> */</span>
<span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span>
<span style="color: #000000">timer_ev_cb</span>(<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_event</span> <span style="color: #000000">*ev</span>)
{
<span style="color: #000000">assert</span>(<span style="color: #000000">ev</span> <span style="color: #000000">!=</span> <span style="color: #A90D91">NULL</span>);
<span style="color: #000000">++g_task1_loops</span>;
<span style="color: #000000">hal_gpio_toggle</span>(<span style="color: #000000">g_led_pin</span>);
<span style="color: #000000">os_callout_reset</span>(<span style="color: #000000">&amp;blinky_callout</span>, <span style="color: #000000">OS_TICKS_PER_SEC</span>);
}
<span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span>
<span style="color: #000000">init_timer</span>(<span style="color: #A90D91">void</span>)
{
<span style="color: #177500">/*</span>
<span style="color: #177500"> * Initialize the callout for a timer event.</span>
<span style="color: #177500"> */</span>
<span style="color: #000000">os_callout_init</span>(<span style="color: #000000">&amp;blinky_callout</span>, <span style="color: #000000">os_eventq_dflt_get</span>(),
<span style="color: #000000">timer_ev_cb</span>, <span style="color: #A90D91">NULL</span>);
<span style="color: #000000">os_callout_reset</span>(<span style="color: #000000">&amp;blinky_callout</span>, <span style="color: #000000">OS_TICKS_PER_SEC</span>);
}
</code></pre></div>
<p>In <code>main()</code>, add the call to the <code>init_timer()</code> function before the while loop and modify the while loop to process events from the OS default event queue:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">int</span>
<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
{
<span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
<span style="color: #633820">#ifdef ARCH_sim</span>
<span style="color: #000000">mcu_sim_parse_args</span>(<span style="color: #000000">argc</span>, <span style="color: #000000">argv</span>);
<span style="color: #633820">#endif</span>
<span style="color: #000000">sysinit</span>();
<span style="color: #000000">g_led_pin</span> <span style="color: #000000">=</span> <span style="color: #000000">LED_BLINK_PIN</span>;
<span style="color: #000000">hal_gpio_init_out</span>(<span style="color: #000000">g_led_pin</span>, <span style="color: #1C01CE">1</span>);
<span style="background-color: #ffffcc"> <span style="color: #000000">init_timer</span>();
</span> <span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) {
<span style="background-color: #ffffcc"> <span style="color: #000000">os_eventq_run</span>(<span style="color: #000000">os_eventq_dflt_get</span>());
</span> }
<span style="color: #000000">assert</span>(<span style="color: #1C01CE">0</span>);
<span style="color: #A90D91">return</span> <span style="color: #000000">rc</span>;
}
</code></pre></div>
<p><br></p>
<h3 id="build-run-and-upload-the-blinky-application-target">Build, Run, and Upload the Blinky Application Target</h3>
<p>We're not going to build the bootloader here since we are assuming that you have already
built and loaded it during previous tutorials.</p>
<p>We will use the <code>newt run</code> command to build and deploy our improved blinky image. The run command performs the following tasks for us:</p>
<ol>
<li>Builds a binary Mynewt executable</li>
<li>Wraps the executable in an image header and footer, turning it into a Mynewt image.</li>
<li>Uploads the image to the target hardware.</li>
<li>Starts a gdb process to remotely debug the Mynewt device.</li>
</ol>
<p>Run the <code>newt run nrf52_blinky 0</code> command. The <code>0</code> is the version number that should be written to the image header. Any version will do, so we choose 0.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt run nrf52_blinky 0
...
Archiving util_mem.a
Linking /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
App image succesfully generated: /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
Loading app image into slot 1
[/home/me/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh /home/me/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky]
Debugging /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
</code></pre></div>
<p><br></p>
<h3 id="set-up-a-serial-connection">Set Up a Serial Connection</h3>
<p>You'll need a Serial connection to see the output of your program. You can reference the <a href="../../get_started/serial_access/">Serial Port Setup</a> Tutorial for more information on setting up your serial communication.</p>
<p><br></p>
<h3 id="communicate-with-the-application">Communicate with the Application</h3>
<p>Once you have a connection set up, you can connect to your device as follows:</p>
<ul>
<li>
<p>On Mac OS and Linux platforms, you can run <code>minicom -D /dev/tty.usbserial-&lt;port&gt; -b 115200</code> to connect to the console of your app. Note that on Linux, the format of the port name is <code>/dev/ttyUSB&lt;N&gt;</code>, where N is a number.</p>
</li>
<li>
<p>On Windows, you can use a terminal application such as PuTTY to connect to the device.</p>
</li>
</ul>
<p>If you located your port from a MinGW terminal, the port name format is <code>/dev/ttyS&lt;N&gt;</code>, where <code>N</code> is a number. You must map the port name to a Windows COM port: <code>/dev/ttyS&lt;N&gt;</code> maps to <code>COM&lt;N+1&gt;</code>. For example, <code>/dev/ttyS2</code> maps to <code>COM3</code>.</p>
<p>You can also use the Windows Device Manager to locate the COM port.</p>
<p><br>
To test and make sure that the Shell is running, first just hit <return>:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>004543 shell&gt;
</code></pre></div>
<p>You can try some commands:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>003005 shell&gt; help
003137 Available modules:
003137 os
003138 prompt
003138 To select a module, enter &#39;select &lt;module name&gt;&#39;.
003140 shell&gt; prompt
003827 help
003827 ticks shell ticks command
004811 shell&gt; prompt ticks off
005770 Console Ticks off
shell&gt; prompt ticks on
006404 Console Ticks on
006404 shell&gt;
</code></pre></div>
<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>