blob: 88406f2dc0d9aabbd1ac235bdecda4cce32c2b8e [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.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/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</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="../ibeacon/">BLE iBeacon</a>
</li>
<li >
<a href="../eddystone/">BLE Eddystone</a>
</li>
<li >
<a href="../add_newtmgr/">Enable Newt Manager in any app</a>
</li>
<li >
<a href="../add_shell/">Enable the OS Shell and Console</a>
</li>
<li >
<a href="../tasks_lesson/">Tasks and Priority Management</a>
</li>
<li >
<a href="../wi-fi_on_arduino/">Enable Wi-Fi on Arduino MKR1000</a>
</li>
<li >
<a href="../unit_test/">Write a Test Suite for a Package</a>
</li>
<li >
<a href="../event_queue/">Events and Event Queues</a>
</li>
<li >
<a href="../bletiny_project/">BLE app to check stats via console</a>
</li>
<li ><a href="../bleprph/bleprph-intro/">BLE peripheral project</a>
</li>
<li >
<a href="../blehci_project/">BLE HCI interface</a>
</li>
<li><a href="
../air_quality_sensor/
">Air-quality Sensor project</a>
</li>
<li >
<a href="../nrf52_adc/">Add an Analog Sensor</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>
</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="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>Add the following dependencies to your application target's <code>pkg.yml</code> file:</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;
- &quot;@apache-mynewt-core/sys/sysinit&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
# Enable Console OS Ticks
CONSOLE_TICKS: 1
# Enable Console Prompt
CONSOLE_PROMPT: 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: #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="color: #000000">init_timer</span>();
<span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) {
<span style="color: #000000">os_eventq_run</span>(<span style="color: #000000">os_eventq_dflt_get</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-the-blinky-application-target">Build 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>Run the <code>newt build nrf52_blinky</code> command to build the Blinky application:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt build nrf52_blinky
...
Archiving util_mem.a
Linking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
Target successfully built: targets/nrf52_blinky
</code></pre></div>
<p><br></p>
<h3 id="sign-and-create-the-blinky-application-image">Sign and Create the Blinky Application Image</h3>
<p>Run the <code>newt create-image nrf52_blinky 1.0.0</code> command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt create-image nrf52_blinky 1.0.0
App image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img
</code></pre></div>
<p><br></p>
<h3 id="load-the-image">Load the Image</h3>
<p>Make sure the USB connector is in place and the power LED on the board is lit. Use the Power ON/OFF switch to reset the board after loading the image.</p>
<p>Run the <code>newt load nrf52_blinky</code> command to load the Blinky application image onto the board.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>$ newt load nrf52_blinky
Loading app image into slot 1
</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>
<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>
</li>
</ul>
<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>3534: &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>3609: &gt; ?
Commands:
8841: echo ? prompt ticks tasks mempools
8843: date b
8844: &gt; ticks off
Console Ticks off
&gt; prompt off
Prompt now off.
ticks on
33383: Console Ticks on
33568:
prompt on
39108: Prompt now on.
39108: &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 (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>