You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by GitBox <gi...@apache.org> on 2019/01/03 23:51:45 UTC
[GitHub] aditihilbert closed pull request #498: automated asf-site build
aditihilbert closed pull request #498: automated asf-site build
URL: https://github.com/apache/mynewt-site/pull/498
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/about/index.html b/about/index.html
index 6a6a28af6c..7b5c22a87b 100644
--- a/about/index.html
+++ b/about/index.html
@@ -8,7 +8,8 @@
<!-- This is broken by doc revisioning.
<link rel="canonical" href="http://mynewt.apache.org/about/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
+ <link rel="shortcut icon" href="/img/mynewt-logo-only-newt32x32.png">
+
<title>About - Apache Mynewt</title>
@@ -29,14 +30,23 @@
<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>
+ (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>
@@ -54,7 +64,7 @@ <h4 class="tagline">An OS to build, deploy and securely manage billions of devic
</div>
<div class="news-cell">
<div class="well">
- <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.0.0</a> released (March 22, 2017)
+ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov 5, 2018)
</div>
</div>
</div>
@@ -108,7 +118,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.0.0</a> released (Marc
<li
class=""
>
- <a href="/latest/os/introduction">Documentation</a>
+ <a href="/documentation/">Documentation</a>
</li>
<li
class=""
@@ -144,7 +154,10 @@ <h3> Features </h3>
Real-time operating system kernel (Mynewt OS)
</li>
<li>
- Bluetooth Low Energy stack (BLE 4.2) - choose HOST only or CONTROLLER only or FULL stack.
+ Bluetooth Low Energy stack (BLE 5) - choose HOST only or CONTROLLER only or FULL stack.
+ </li>
+ <li>
+ Bluetooth Low Energy Mesh
</li>
<li>
Command line package management and build system (Newt Tool)
@@ -163,10 +176,10 @@ <h3> Features </h3>
Secure bootloader, signed images and remote firmware upgrade
</li>
<li>
- Flash circular buffers, Newtron Flash File System (nffs), or hook up any other file system
+ Flash circular buffers, Newtron Flash File System (nffs), or hook up any other file system
</li>
<li>
- Serial upgrade of bootloader, see <a href="https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22newtmgr%20over%20Serial%22"> discussion thread </a>
+ Serial upgrade of bootloader, see <a href="https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22newtmgr%20over%20Serial%22"> discussion thread </a>
</li>
<li>
WiFi support via socket interface, join <a href="https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22socket%20interface%22"> discussion here </a>
@@ -214,7 +227,7 @@ <h3 id="feature-request">Feature Request</h3>
<p>If you have suggestions for a new feature, use case, or implementation improvements, file a JIRA ticket with Issue Type set to "Wish". Introduce it in the <a href="../dev@mynewt.incubator.apache.org">dev@</a> mailing list with a link to the JIRA ticket. This assumes you have signed up for an account on JIRA and submitted a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project.</p>
<p><br></p>
<h3 id="faq">FAQ</h3>
-<p><font color="#F2853F"> Questions? </font> Click <a href="../latest/faq/answers">here</a></p>
+<p><font color="#F2853F"> Questions? </font> Click <a href="../latest/mynewt_faq.html">here</a></p>
</div>
</div>
@@ -233,7 +246,9 @@ <h3 id="faq">FAQ</h3>
<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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
+ <a href="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg">
+ <img src="/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
+ </a>
</div>
</div>
</footer>
diff --git a/community/index.html b/community/index.html
index 87dcc24382..832c3aead4 100644
--- a/community/index.html
+++ b/community/index.html
@@ -8,7 +8,8 @@
<!-- This is broken by doc revisioning.
<link rel="canonical" href="http://mynewt.apache.org/community/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
+ <link rel="shortcut icon" href="/img/mynewt-logo-only-newt32x32.png">
+
<title>Community - Apache Mynewt</title>
@@ -29,14 +30,23 @@
<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>
+ (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>
@@ -54,7 +64,7 @@ <h4 class="tagline">An OS to build, deploy and securely manage billions of devic
</div>
<div class="news-cell">
<div class="well">
- <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.0.0</a> released (March 22, 2017)
+ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov 5, 2018)
</div>
</div>
</div>
@@ -108,7 +118,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.0.0</a> released (Marc
<li
class=""
>
- <a href="/latest/os/introduction">Documentation</a>
+ <a href="/documentation/">Documentation</a>
</li>
<li
class=""
@@ -151,12 +161,12 @@ <h3 id="mailing-lists">Mailing Lists</h3>
<div class="bg-purple mailing-list-title text-center">
Dev Mailing List
</div>
- <p><a class="bold-link" href="mailto:dev@mynewt.incubator.apache.org">dev@mynewt.incubator.apache.org</a></p>
+ <p><a class="bold-link" href="mailto:dev@mynewt.apache.org">dev@mynewt.apache.org</a></p>
<p>For both contributors and users. Ask questions. Share ideas. Discuss issues, roadmap, process. Help coordinate. Influence.</p>
<div class="mailing-list-title text-center">
- <p><a href="mailto:dev-subscribe@mynewt.incubator.apache.org">Subscribe</a></p>
- <p text-center><a href="mailto:dev-unsubscribe@mynewt.incubator.apache.org">Unsubscribe</a></p>
- <p> <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/">Mail archives</a> </p>
+ <p><a href="mailto:dev-subscribe@mynewt.apache.org">Subscribe</a></p>
+ <p text-center><a href="mailto:dev-unsubscribe@mynewt.apache.org">Unsubscribe</a></p>
+ <p> <a href="http://mail-archives.apache.org/mod_mbox/mynewt-dev/">Mail archives</a> </p>
<p> Find us on Slack:</p>
<p> <a href="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a></p>
</div>
@@ -165,24 +175,24 @@ <h3 id="mailing-lists">Mailing Lists</h3>
<div class="bg-purple mailing-list-title text-center">
Commits Mailing List
</div>
- <p><a class="bold-link" href="mailto:commits@mynewt.incubator.apache.org">commits@mynewt.incubator.apache.org</a></p>
+ <p><a class="bold-link" href="mailto:commits@mynewt.apache.org">commits@mynewt.apache.org</a></p>
<p>For code or documentation contributors. Receive automated notifications of any changes to Mynewt code and documentation.</p>
<div class="mailing-list-title text-center">
- <p><a href="mailto:commits-subscribe@mynewt.incubator.apache.org">Subscribe</a></p>
- <p><a href="mailto:commits-unsubscribe@mynewt.incubator.apache.org">Unsubscribe</a></p>
- <p> <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-commits/">Mail archives</a> </p>
+ <p><a href="mailto:commits-subscribe@mynewt.apache.org">Subscribe</a></p>
+ <p><a href="mailto:commits-unsubscribe@mynewt.apache.org">Unsubscribe</a></p>
+ <p> <a href="http://mail-archives.apache.org/mod_mbox/mynewt-commits/">Mail archives</a> </p>
</div>
</div>
<div class="col-md-4 mailing-list">
<div class="bg-purple mailing-list-title text-center">
Notifications Mailing List
</div>
- <p><a class="bold-link" href="mailto:notifications@mynewt.incubator.apache.org">notifications@mynewt.incubator.apache.org</a></p>
+ <p><a class="bold-link" href="mailto:notifications@mynewt.apache.org">notifications@mynewt.apache.org</a></p>
<p>For all autogenerated mail other than commits e.g. JIRA issue-tracker notifications. Can also be used for announcements. </p>
<div class="mailing-list-title text-center">
- <p><a href="mailto:notifications-subscribe@mynewt.incubator.apache.org">Subscribe</a></p>
- <p><a href="mailto:notifications-unsubscribe@mynewt.incubator.apache.org">Unsubscribe</a></p>
- <p> <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-notifications/">Mail archives</a> </p>
+ <p><a href="mailto:notifications-subscribe@mynewt.apache.org">Subscribe</a></p>
+ <p><a href="mailto:notifications-unsubscribe@mynewt.apache.org">Unsubscribe</a></p>
+ <p> <a href="http://mail-archives.apache.org/mod_mbox/mynewt-notifications/">Mail archives</a> </p>
</div>
</div>
</div>
@@ -193,20 +203,14 @@ <h3>Getting involved</h3>
<p> It is easy! Simply send an email to the dev@ mailing list introducing yourself and the Apache Mynewt community will welcome you. If you have questions, sending an email to this list is the fastest way of getting an answer. </p>
- <p> If you want to browse the code, <a href="https://github.com/apache/incubator-mynewt-core/tree/develop">Mynewt Core Repo</a> is the best place to start.
+ <p> If you want to browse the code, <a href="https://github.com/apache/mynewt-core/tree/develop">Mynewt Core Repo</a> is the best place to start.
<p> If you wish to contribute code, a quick look at the <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Contributing+to+Apache+Mynewt"> recommended steps </a> should help.
<h3>Bug Submission and Issue Tracking</h3>
- <p>Issues, features, improvements, and wish-lists are tracked using <a href="https://issues.apache.org/jira/browse/Mynewt/">ASF JIRA</a>, the Atlassian JIRA software on Apache Software Foundation </p>
- <li>
- <p><a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20MYNEWT%20AND%20fixVersion%20%3D%20WISHLIST%20ORDER%20BY%20updated%20DESC%2C%20priority%20DESC%2C%20created%20ASC">Click here to see WISHLIST for Mynewt</a></p>
- </li>
- <li>
- Sign up for an account on JIRA and submit a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. Editing a ticket requires an account.
- </li>
- <li> Log in and report a bug by choosing the "MYNEWT" project, clicking on the "Create" button, and creating a ticket with an appropriate Issue Type (e.g. Bug, Wish). </p>
- <p> If you are a contributor and wish to work on a change, open a JIRA ticket first. It's always a good idea to introduce the change in the dev@ mailing list and refer to that ticket. When you generate a pull request into the github mirror for your change, always reference the JIRA ticket number in the title. JIRA is set up to resolve the ticket when your code is merged into the ASF git repository and the pull request closed. </p>
+ <p> Issues, features, improvements, and wish-lists are now tracked on the <a href="https://github.com/apache/mynewt-core/issues">Mynewt Core Github Repo</a>. New issues will be marked with the appropriate label by a committer who will review them. </p>
+
+ <p> If you are a contributor and wish to work on a change, it's always a good idea to introduce the change in the dev@ mailing list before submitting a pull request into the github mirror for your change. </p>
<br>
</div>
@@ -225,7 +229,9 @@ <h3>Bug Submission and Issue Tracking</h3>
<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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
+ <a href="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg">
+ <img src="/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
+ </a>
</div>
</div>
</footer>
diff --git a/develop/about/index.html b/develop/about/index.html
deleted file mode 100644
index 89d4ae3b85..0000000000
--- a/develop/about/index.html
+++ /dev/null
@@ -1,250 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/about/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
-
- <title>About - 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">
- <link href="../extra.css" rel="stylesheet">
-
- <!-- 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="About">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="active "
->
- <a href="/about/">About</a>
- </li>
- <li
- class=""
->
- <a href="/talks/">Talks</a>
- </li>
- <li
- class=""
->
- <a href="/latest/os/introduction">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="container small-no-padding">
- <div class="row">
- <div class="col-md-8 content">
- <h3> Features </h3>
- <li>
- Real-time operating system kernel (Mynewt OS)
- </li>
- <li>
- Bluetooth Low Energy stack (BLE 4.2) - choose HOST only or CONTROLLER only or FULL stack.
- </li>
- <li>
- Command line package management and build system (Newt Tool)
- </li>
- <li>
- Hardware Abstraction Layer unifying common MCU features, see <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/201606.mbox/%3C06CB0682-8F67-4C3F-93E4-6A20444487A1%40apache.org%3E"> discussion thread </a>
-
- </li>
- <li>
- Board Support Infrastructure
- </li>
- <li>
- System level logs and statistics
- </li>
- <li>
- Secure bootloader, signed images and remote firmware upgrade
- </li>
- <li>
- Flash circular buffers, Newtron Flash File System (nffs), or hook up any other file system
- </li>
- <li>
- Serial upgrade of bootloader, see <a href="https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22newtmgr%20over%20Serial%22"> discussion thread </a>
- </li>
- <li>
- WiFi support via socket interface, join <a href="https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22socket%20interface%22"> discussion here </a>
- <li>
- Basic IP support
- </li>
- <br>
- <p> For features in each release, see <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Apache+Mynewt+Project"> Release Notes </a>
- </p>
- </div>
- <div class="col-md-4">
- <div class="rhs">
- <h3> Source Code on github.com </h3>
- <li>
- <a href="https://github.com/apache/incubator-mynewt-core"> Git repo for Mynewt OS </a>
- </li>
- <li>
- <a href="https://github.com/apache/incubator-mynewt-newt"> Git repo for Newt Tool </a>
- </li>
- <li>
- <a href="https://github.com/apache/incubator-mynewt-site"> Git repo for Docs </a>
- </li>
- </div>
- </div>
- </div>
-</div>
-
-<div class="container small-no-padding">
- <div class="row">
- <div class="col-md-12 content">
-
- <h3 id="roadmap">Roadmap</h3>
-<p>Some upcoming features:</p>
-<ul>
-<li>Full IP support</li>
-<li>Low power support with ability for drivers to turn on/off low power settings automatically</li>
-<li>Sensor API, see <a href="https://lists.apache.org/list.html?dev@mynewt.apache.org:dfr=June%201|dto=2016-11-14:%22Sensor%20Drivers%22">discussion thread</a></li>
-<li>Support for MIPS architecture</li>
-<li>Support for additional boards</li>
-</ul>
-<p><font color="#F2853F"> The detailed roadmap is tracked on <a href="https://issues.apache.org/jira/browse/MYNEWT/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel">JIRA for Mynewt</a>. </font></p>
-<p><br></p>
-<h3 id="feature-request">Feature Request</h3>
-<p>The WISHLIST at the top of the roadmap on <a href="https://issues.apache.org/jira/browse/MYNEWT/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel">JIRA for Mynewt</a> features all the new ideas awaiting discussion and review. Once the community decides to go ahead with a request, it is scheduled into a release. Generally, effort is made to schedule a requested feature into a particular version no later than 6 weeks prior to the planned release date.</p>
-<p>If you have suggestions for a new feature, use case, or implementation improvements, file a JIRA ticket with Issue Type set to "Wish". Introduce it in the <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/">dev@</a> mailing list with a link to the JIRA ticket. This assumes you have signed up for an account on JIRA and submitted a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project.</p>
-<p><br></p>
-<h3 id="faq">FAQ</h3>
-<p><font color="#F2853F"> Questions? </font> Click <a href="../latest/faq/answers">here</a></p>
-
- </div>
- </div>
-</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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</footer>
-
- </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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/community/index.html b/develop/community/index.html
deleted file mode 100644
index 87dcc24382..0000000000
--- a/develop/community/index.html
+++ /dev/null
@@ -1,242 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/community/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
-
- <title>Community - 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">
- <link href="../extra.css" rel="stylesheet">
-
- <!-- 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="Community">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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=""
->
- <a href="/latest/os/introduction">Documentation</a>
- </li>
- <li
- class=""
->
- <a href="/download/">Download</a>
- </li>
- <li
- class="active "
->
- <a href="/community/">Community</a>
- </li>
- <li
- class=""
->
- <a href="/events/">Events</a>
- </li>
- </ul>
-
- </div>
- </div>
-</nav>
-
-
-
- <div class="container">
-
-
-<div class="container small-no-padding">
- <div class="row content">
- <div class="col-md-12">
-
- <h3 id="mailing-lists">Mailing Lists</h3>
-<p>We welcome you to join our mailing lists and get in touch with us!
-<font color="#F2853F"> <em>To complete your subscription you have to confirm it by replying to the response sent to you when you email your subscription request!</em> </font></p>
-
- </div>
- </div>
- <div class="row">
- <div class="col-md-4 mailing-list">
- <div class="bg-purple mailing-list-title text-center">
- Dev Mailing List
- </div>
- <p><a class="bold-link" href="mailto:dev@mynewt.incubator.apache.org">dev@mynewt.incubator.apache.org</a></p>
- <p>For both contributors and users. Ask questions. Share ideas. Discuss issues, roadmap, process. Help coordinate. Influence.</p>
- <div class="mailing-list-title text-center">
- <p><a href="mailto:dev-subscribe@mynewt.incubator.apache.org">Subscribe</a></p>
- <p text-center><a href="mailto:dev-unsubscribe@mynewt.incubator.apache.org">Unsubscribe</a></p>
- <p> <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-dev/">Mail archives</a> </p>
- <p> Find us on Slack:</p>
- <p> <a href="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a></p>
- </div>
- </div>
- <div class="col-md-4 mailing-list">
- <div class="bg-purple mailing-list-title text-center">
- Commits Mailing List
- </div>
- <p><a class="bold-link" href="mailto:commits@mynewt.incubator.apache.org">commits@mynewt.incubator.apache.org</a></p>
- <p>For code or documentation contributors. Receive automated notifications of any changes to Mynewt code and documentation.</p>
- <div class="mailing-list-title text-center">
- <p><a href="mailto:commits-subscribe@mynewt.incubator.apache.org">Subscribe</a></p>
- <p><a href="mailto:commits-unsubscribe@mynewt.incubator.apache.org">Unsubscribe</a></p>
- <p> <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-commits/">Mail archives</a> </p>
- </div>
- </div>
- <div class="col-md-4 mailing-list">
- <div class="bg-purple mailing-list-title text-center">
- Notifications Mailing List
- </div>
- <p><a class="bold-link" href="mailto:notifications@mynewt.incubator.apache.org">notifications@mynewt.incubator.apache.org</a></p>
- <p>For all autogenerated mail other than commits e.g. JIRA issue-tracker notifications. Can also be used for announcements. </p>
- <div class="mailing-list-title text-center">
- <p><a href="mailto:notifications-subscribe@mynewt.incubator.apache.org">Subscribe</a></p>
- <p><a href="mailto:notifications-unsubscribe@mynewt.incubator.apache.org">Unsubscribe</a></p>
- <p> <a href="http://mail-archives.apache.org/mod_mbox/incubator-mynewt-notifications/">Mail archives</a> </p>
- </div>
- </div>
-</div>
-
-<div class="row">
- <div class="col-md-12">
- <h3>Getting involved</h3>
-
- <p> It is easy! Simply send an email to the dev@ mailing list introducing yourself and the Apache Mynewt community will welcome you. If you have questions, sending an email to this list is the fastest way of getting an answer. </p>
-
- <p> If you want to browse the code, <a href="https://github.com/apache/incubator-mynewt-core/tree/develop">Mynewt Core Repo</a> is the best place to start.
-
- <p> If you wish to contribute code, a quick look at the <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Contributing+to+Apache+Mynewt"> recommended steps </a> should help.
-
- <h3>Bug Submission and Issue Tracking</h3>
- <p>Issues, features, improvements, and wish-lists are tracked using <a href="https://issues.apache.org/jira/browse/Mynewt/">ASF JIRA</a>, the Atlassian JIRA software on Apache Software Foundation </p>
- <li>
- <p><a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20MYNEWT%20AND%20fixVersion%20%3D%20WISHLIST%20ORDER%20BY%20updated%20DESC%2C%20priority%20DESC%2C%20created%20ASC">Click here to see WISHLIST for Mynewt</a></p>
- </li>
- <li>
- Sign up for an account on JIRA and submit a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. Editing a ticket requires an account.
- </li>
- <li> Log in and report a bug by choosing the "MYNEWT" project, clicking on the "Create" button, and creating a ticket with an appropriate Issue Type (e.g. Bug, Wish). </p>
- <p> If you are a contributor and wish to work on a change, open a JIRA ticket first. It's always a good idea to introduce the change in the dev@ mailing list and refer to that ticket. When you generate a pull request into the github mirror for your change, always reference the JIRA ticket number in the title. JIRA is set up to resolve the ticket when your code is merged into the ASF git repository and the pull request closed. </p>
-<br>
-
-</div>
-</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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</footer>
-
- </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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/download/index.html b/develop/download/index.html
deleted file mode 100644
index e6ddf0a72e..0000000000
--- a/develop/download/index.html
+++ /dev/null
@@ -1,221 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/download/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
-
- <title>Download - 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">
- <link href="../extra.css" rel="stylesheet">
-
- <!-- 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="Download">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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=""
->
- <a href="/latest/os/introduction">Documentation</a>
- </li>
- <li
- class="active "
->
- <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="container">
- <div class="row">
- <div class="col-md-12">
-
- <h3 id="latest-apache-mynewt-os-release">Latest Apache Mynewt OS Release</h3>
-<ul>
-<li>Release Version: Mynewt 0.9.0-incubating</li>
-<li>Release Date: June 6, 2016</li>
-<li><a href="https://cwiki.apache.org/confluence/display/MYNEWT/RN-0.9.0-incubating">Release Notes</a> </li>
-</ul>
-<h4 id="fresh-install">Fresh install</h4>
-<p>If you are brand new to Mynewt, go to <a href="../os/get_started/get_started/">Quick Start</a>. The Newt tool will automatically download the latest release.</p>
-<p>If you have already installed the Newt tool but not started any project yet, go to <a href="../latest/os/get_started/project_create/">Create Your First Project</a>. The Newt tool will automatically download the latest release.</p>
-<h4 id="upgrade">Upgrade</h4>
-<p>If you have already installed the Newt tool and started a project that installed a previous version of Apache Mynewt, upgrade using Newt tool:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ newt upgrade
-</pre></div>
-
-
-<h3 id="code-in-development">Code in development</h3>
-<p>While the use of one of the official releases listed above is generally recommended, you may be interested in seeing work in progress.</p>
-<p>The most recent code resides in the <code>develop</code> branch of the Mynewt git repository. You may view or fork the repositories for Mynewt OS and Newt Tool from the Apache mirror on github.com.</p>
-<ul>
-<li><a href="https://github.com/apache/incubator-mynewt-core/tree/develop">Apache Mynewt OS mirror on github.com</a></li>
-<li><a href="https://github.com/apache/incubator-mynewt-newt/tree/develop">Apache Newt Tool mirror on github.com</a></li>
-</ul>
-<p>Alternatively, you can clone the desired branch using git:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ git clone git://github.com/apache/incubator-mynewt-core.git -b develop
-$ git clone git://github.com/apache/incubator-mynewt-newt.git -b develop
-</pre></div>
-
-
-<p><br></p>
-<p>A relatively stable version of code in progress can be found in the <code>master</code> branch of the Mynewt git repository.
-You may access the code for Mynewt OS and Newt Tool from the 'master` branch of the Apache mirror on github.com or clone it using git:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ git clone git://github.com/apache/incubator-mynewt-core.git
-$ git clone git://github.com/apache/incubator-mynewt-newt.git
-</pre></div>
-
-
-<p><br></p>
-<p>For general information on using Git at Apache, go to https://git-wip-us.apache.org.</p>
-<p><br></p>
-<h3 id="release-archives">Release Archives</h3>
-<ul>
-<li>Mynewt 0.8.0-incubating, <a href="https://cwiki.apache.org/confluence/display/MYNEWT/RN-0.8.0-incubating">Release Notes</a></li>
-<li>Mynewt 0.8.0-b2-incubating, <a href="https://cwiki.apache.org/confluence/display/MYNEWT/RN-0.8.0-b2-incubating">Release Notes</a></li>
-</ul>
-<p><br>
-<br></p>
-
- </div>
- </div>
-
-</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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</footer>
-
- </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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/events/index.html b/develop/events/index.html
deleted file mode 100644
index e04570355a..0000000000
--- a/develop/events/index.html
+++ /dev/null
@@ -1,195 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/events/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
-
- <title>Events - 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">
- <link href="../extra.css" rel="stylesheet">
-
- <!-- 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="Events">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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=""
->
- <a href="/latest/os/introduction">Documentation</a>
- </li>
- <li
- class=""
->
- <a href="/download/">Download</a>
- </li>
- <li
- class=""
->
- <a href="/community/">Community</a>
- </li>
- <li
- class="active "
->
- <a href="/events/">Events</a>
- </li>
- </ul>
-
- </div>
- </div>
-</nav>
-
-
-
- <div class="container">
-
- <div class="row">
- <div class="column col-md-12">
- <div class="container">
- <div class="row">
- <div class="col-md-12 content">
-
- <h3 id="events">Events</h3>
-<p>Please take a look at our upcoming events! We hope to see you there.</p>
-
-
- <div class="event">
- <h2>CES</h2>
- <p>5-8 January, 2017</p>
- <p>Las Vegas, NV</p>
- <p>Contact runtime.io or email us at dev@mynewt.incubator.apache.org to check out and discuss Apache Mynewt and its many uses.</p>
- </div>
-
- <div class="event">
- <h2>Embedded Systems Conference</h2>
- <p>6-8 December, 2016</p>
- <p>San Jose Convention Center, San Jose, CA, USA</p>
- <p>Meet up to discuss Apache Mynewt.</p>
- </div>
-
- </div>
- </div>
- </div>
- </div>
-</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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</footer>
-
- </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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/faq/answers/index.html b/develop/faq/answers/index.html
deleted file mode 100644
index ae9ea6c9b7..0000000000
--- a/develop/faq/answers/index.html
+++ /dev/null
@@ -1,383 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/faq/answers/"> -->
- <link rel="shortcut icon" href="../../img/favicon.ico">
-
- <title>FAQ - 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">
- <link href="../../extra.css" rel="stylesheet">
-
- <!-- 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="FAQ">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../os/introduction/">Mynewt Documentation</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../go_env/
-">Appendix</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../go_env/">Setting Up Go to Contribute to Newt and Newtmgr Tools</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ide/">Using an IDE to Develop Mynewt Applications</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../how_to_edit_docs/">Edit Docs</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">FAQ</a>
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../go_env/">Appendix</a></li>
-
-
-
- <li>» FAQ</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/faq/answers.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="faq">FAQ</h2>
-<p>Here are some lists, grouped by categories, of frequently asked questions. </p>
-<p><strong>Mynewt software questions:</strong></p>
-<ul>
-<li><a href="../../os/tutorials/codesize/">How do I reduce the code size for my Mynewt image?</a></li>
-</ul>
-<p><strong>Administrative questions:</strong></p>
-<ul>
-<li><a href="#submit-a-bug">How do I submit a bug?</a></li>
-<li><a href="#request-feature">How do I request a feature?</a></li>
-<li><a href="#not-committer-patch">How do I submit a patch if I am not a committer?</a></li>
-<li><a href="#committer-merge">Can I merge my own Pull Request into the git repo if I am a committer?</a></li>
-<li><a href="#change-doc">How do I make changes to documentation?</a></li>
-<li><a href="#doc-editor">How do I make changes to documentation using an editor on my laptop?</a></li>
-</ul>
-<p><br></p>
-<h3 id="how-do-i-submit-a-bug"><a name="summit-a-bug"></a> How do I submit a bug?</h3>
-<p><br>
-If you do not have a JIRA account sign up for an account on <a href="https://issues.apache.org/jira/secure/Signup!default.jspa">JIRA</a>.</p>
-<p>Submit a request to the @dev mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. You can view the issues on JIRA for the MYNEWT project without an account but you need to log in for reporting a bug. </p>
-<p>Log in. Choose the "MYNEWT" project. Click on the "Create" button to create a ticket. Choose "Bug" as the Issue Type. Fill in the bug description, how it is triggered, and other details. </p>
-<h3 id="how-do-i-request-a-feature"><a name="request-feature"></a> How do I request a feature?</h3>
-<p><br>
-If you do not have a JIRA account sign up for an account on <a href="https://issues.apache.org/jira/secure/Signup!default.jspa">JIRA</a>.</p>
-<p>Submit a request to the @dev mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. You can view the issues on JIRA for the MYNEWT project without an account but you need to log in for reporting a bug. </p>
-<p>Log in. Choose the "MYNEWT" project. Click on the "Create" button to create a ticket. Choose "Wish" as the Issue Type. Fill in the feature description, benefits, and any other implementation details. Note in the description whether you want to work on it yourself. </p>
-<p>If you are not a committer and you wish to work on it, someone who is on the committer list will have to review your request and assign it to you. You will have to refer to this JIRA ticket in your pull request.</p>
-<h3 id="i-am-not-on-the-committer-list-how-do-i-submit-a-patch"><a name="not-committer-patch"></a>I am not on the committer list. How do I submit a patch?</h3>
-<p><br>
-<strong>You submit your proposed changes for your peers with committer status to review and merge.</strong></p>
-<p>The process to submit a Pull Request on github.com is described on the <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Submitting+Pull+Requests">Confluence page for the project</a>. </p>
-<h3 id="i-am-a-committer-in-the-project-can-i-merge-my-own-pull-request-into-the-git-repository"><a name="committer-merge"></a>I am a committer in the project. Can I merge my own Pull Request into the git repository?</h3>
-<p><br>
-Yes, but only if your Pull Request has been reviewed and approved by another committer in Apache Mynewt.
-The process to merge a Pull Request is described on the <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Merging+Pull+Requests">Confluence page for the project</a>.</p>
-<h3 id="i-would-like-to-make-some-edits-to-the-documentation-what-do-i-do"><a name="change-doc"></a>I would like to make some edits to the documentation. What do I do?</h3>
-<p><br>
-You submit your proposed changes for your peers with committer status to review and merge. </p>
-<p>Go to the <a href="https://github.com/apache/incubator-mynewt-site">documentation mirror</a> on github.com.</p>
-<p>Navigate to the file you wish to edit on github.com. All the technical documentation is in Markdown files under the <code>/docs</code> directory. Click on the pencil icon ("Edit the file in your fork of this project") and start making changes.</p>
-<p>Click the green "Propose file change" button. You will be directed to the page where you can start a pull request from the branch that was created for you. The branch is gets an automatic name <code>patch-#</code> where # is a number. Click on the green "Compare & pull request" to open the pull request.</p>
-<p>In the comment for the pull request, include a description of the changes you have made and why. Github will automatically notify everyone on the commits@mynewt.incubator.apache.org mailing list about the newly opened pull requests. You can open a pull request even if you don't think the code is ready for merging but want some discussion on the matter.</p>
-<p>Upon receiving notification, one or more committers will review your work, ask for edits or clarifications, and merge when your proposed changes are ready.</p>
-<p>If you want to withdraw the pull request simply go to your fork <code>https://github.com/<your github username>/incubator-mynewt-site</code> and click on "branches". You should see your branch under "Your branches". Click on the delete icon.</p>
-<h3 id="i-would-like-to-make-some-edits-to-the-documentation-but-want-to-use-an-editor-on-my-own-laptop-what-do-i-do"><a name="doc-editor"></a>I would like to make some edits to the documentation but want to use an editor on my own laptop. What do I do?</h3>
-<p><br>
-You submit your proposed changes for your peers with committer status to review and merge. </p>
-<p>Go to the <a href="https://github.com/apache/incubator-mynewt-site">documentation mirror</a> on github.com. You need to create your own fork of the repo in github.com by clicking on the "Fork" button on the top right. Clone the forked repository into your laptop (using <code>git clone</code> from a terminal or using the download buttons on the github page)and create a local branch for the edits and switching to it (using <code>git checkout -b <new-branchname></code> or GitHub Desktop). </p>
-<p>Make your changes using the editor of your choice. Push that branch to your fork on github. Then submit a pull request from that branch on your github fork.</p>
-<p>The review and merge process is the same as other pull requests described for earlier questions.</p>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../how_to_edit_docs/>
- <span class="fa fa-arrow-left"></span>
- Previous: Edit Docs
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/faq/go_env/index.html b/develop/faq/go_env/index.html
deleted file mode 100644
index 88ec4545b8..0000000000
--- a/develop/faq/go_env/index.html
+++ /dev/null
@@ -1,502 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/faq/go_env/"> -->
- <link rel="shortcut icon" href="../../img/favicon.ico">
-
- <title>Setting Up Go to Contribute to Newt and Newtmgr Tools - 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">
- <link href="../../extra.css" rel="stylesheet">
-
- <!-- 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="Setting Up Go to Contribute to Newt and Newtmgr Tools">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../os/introduction/">Mynewt Documentation</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ./
-">Appendix</a>
-
-
- <ul>
-
-
-
- <li class="active">
- <a href="./">Setting Up Go to Contribute to Newt and Newtmgr Tools</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ide/">Using an IDE to Develop Mynewt Applications</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../how_to_edit_docs/">Edit Docs</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../answers/">FAQ</a>
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» Appendix</li>
-
-
-
- <li>» Setting Up Go to Contribute to Newt and Newtmgr Tools</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/faq/go_env.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="contributing-to-newt-or-newtmgr-tools">Contributing to Newt or Newtmgr Tools</h2>
-<p>Newt and Newtmgr are written in Go (golang). This guide shows you how to install Go and setup your environment to update and build the tools if you want to: </p>
-<ul>
-<li>Contribute to newt or newtmgr features or fix bugs.</li>
-<li>Build the tools with latest updates from the master branch on a Linux platform.</li>
-</ul>
-<p>This guide shows you how to perform the following:</p>
-<ol>
-<li>Install Go on either Mac OS X or Linux. (Tasks that are specific to each platform are called out.)</li>
-<li>Setup the Go environment.</li>
-<li>Download the source, build, and install the newt or newtmgr tools.</li>
-<li>Update and rebuild the tools. </li>
-</ol>
-<p><strong>Note:</strong> You will also need to read and follow the instructions from the <a href="../../faq/answers/">FAQ</a> to set up your git repos to submit changes.</p>
-<h3 id="step-1-installing-go">Step 1: Installing Go</h3>
-<p>The latest master branch of newt and newtmgr requires GO version 1.7.6 or higher. You can skip this step and proceed to Step 2 if you already have Go version 1.7.6 or higher installed.</p>
-<p><br></p>
-<h4 id="installing-go-on-mac-os-x">Installing Go on Mac OS X</h4>
-<p>If you do not have Homebrew installed, run the following command. You will be prompted for your sudo password.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-</pre></div>
-
-
-<p>You can also extract (or <code>git clone</code>) Homebrew and install it to /usr/local.</p>
-<p><br>
-Use brew to install Go:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ brew install go
-==>
-...
-...
-==> *Summary*
-🍺 //usr/local/Cellar/go/1.8.1: 7,030 files, 281.8MB, built in 1 minute 12 seconds
-</pre></div>
-
-
-<p>You can also download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.</p>
-<p><br></p>
-<h4 id="installing-go-on-linux">Installing Go on Linux</h4>
-<p>You can download Go from <a href="https://golang.org/dl/">https://golang.org/dl/</a>.</p>
-<p><br></p>
-<h3 id="step-2-setting-up-your-go-environment">Step 2: Setting Up Your Go Environment</h3>
-<p>This section describes the Go environment and how to setup a Go workspace. If you already have a Go workspace for your other Go projects, you can skip this step and proceed to Step 3.</p>
-<p>Go provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the newt or newtmgr package repository into your local Go environment. The Go language environment dictates a specific directory structure, or workspace in Go parlance. It must contain three sibling directories with the names <strong>src</strong>, <strong>pkg</strong> and <strong>bin</strong>: </p>
-<ul>
-<li>src contains Go source files organized into packages (one package per directory)</li>
-<li>pkg contains package objects</li>
-<li>bin contains the Go application executables that Go builds and installs.</li>
-</ul>
-<p>The <strong>GOPATH</strong> environment variable specifies the location of your workspace. To setup this workspace environment, create a <strong>dev</strong> directory and then a <strong>go</strong> directory under it. Set the GOPATH environment variable to this directory where you will clone the newt and newtmgr repositories.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ cd $HOME
-$ mkdir -p dev/go
-$ cd dev/go
-$ export GOPATH=`pwd`
-</pre></div>
-
-
-<p><br>
-Add the following export statements to your ~/.bash_profile file and source the file:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>export GOPATH=$HOME/dev/go
-export PATH=$GOPATH/bin:$PATH
-</pre></div>
-
-
-<p><br></p>
-<h3 id="step-3-downloading-the-source-and-installing-the-tools">Step 3: Downloading the Source and Installing the Tools</h3>
-<p>Newt and newtmgr are individual Go packages and have their own git repositories. You can download the source and install one or both tools.</p>
-<p>We use the <code>go get</code> command to download the source, build, and install the binary in the <strong>$GOPATH/bin</strong> directory. </p>
-<p><br></p>
-<h4 id="downloading-and-installing-the-newt-tool">Downloading and Installing the Newt Tool</h4>
-<p>The newt Go package is <strong>mynewt.apache.org/newt/newt</strong> and is stored in the <a href="https://github.com/apache/incubator-mynewt-newt">Apache Mynewt newt tool repository mirrored on github</a>. </p>
-<p>Download the newt package source and install the tool:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$cd $GOPATH
-$go get mynewt.apache.org/newt/newt
-$cd $GOPATH/src/mynewt.apache.org/newt
-$ls
-DISCLAIMER RELEASE_NOTES.md util
-INSTALLING.md build.sh viper
-LICENSE newt yaml
-NOTICE newtmgr
-README.md newtvm
-$git status
-On branch master
-Your branch is up-to-date with 'origin/master'.
-
-nothing to commit, working directory clean
-</pre></div>
-
-
-<p><br>
-<strong>Note:</strong> The source code under the <strong>newtmgr</strong> directory is no longer used or updated. The current <strong>newtmgr</strong> source has its own Git repository.</p>
-<p><br>
-Check that the newt binary is installed and you are using the one from <strong> $GOPATH/bin</strong>:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ls $GOPATH/bin/newt
-~/dev/go/bin/newt
-$which newt
-~/dev/go/bin/newt
-$newt version
-Apache Newt (incubating) version: 1.0.0-dev
-</pre></div>
-
-
-<p><br></p>
-<h4 id="downloading-and-installing-the-newtmgr-tool">Downloading and Installing the Newtmgr Tool</h4>
-<p>The newtmgr Go package is <strong>mynewt.apache.org/newtmgr/newtmgr</strong>. It is stored in the <a href="https://github.com/apache/incubator-mynewt-newtmgr">Apache Mynewt newtmgr tool repository mirrored on github</a>.</p>
-<p>Download the newtmgr package and install the tool:</p>
-<p><strong>Note:</strong> <code>-ldflags -s</code> must be passed to the <code>go get</code> command.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$cd $GOPATH
-$go get -ldflags -s mynewt.apache.org/newtmgr/newtmgr
-$cd $GOPATH/src/mynewt.apache.org/newtmgr
-$ls
-DISCLAIMER NOTICE newtmgr
-LICENSE README.md nmxact
-$git status
-On branch master
-Your branch is up-to-date with 'origin/master'.
-
-nothing to commit, working directory clean
-</pre></div>
-
-
-<p><br>
-Check that the newtmgr binary is installed and you are using the one from <strong>$GOPATH/bin</strong>:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$ls $GOPATH/bin/newtmgr
-~/dev/go/bin/newtmgr
-$which newtmgr
-~/dev/go/bin/newtmgr
-</pre></div>
-
-
-<p><br></p>
-<h3 id="step-4-updating-and-rebuilding-the-tools">Step 4: Updating and Rebuilding the Tools:</h3>
-<p>This section shows you how to rebuild the newt and newtmgr tools with the latest updates from the master branch or after you have made changes in your branch. </p>
-<p>Here is the general procedure to rebuild either the newt or newtmgr tool. The only difference is the directory where you will be executing the commands from. You will need to repeat the procedure to rebuild both tools.</p>
-<ol>
-<li>Change to the directory where the local Git repository for the tool is installed.</li>
-<li>Pull the latest changes from the master branch. If you made changes you will need to rebase with <strong>origin master</strong> (See <a href="../../faq/answers/">FAQ</a>).</li>
-<li>Build and install the tool.</li>
-</ol>
-<p><br>
-Change to the directory where the source for the tool is installed.</p>
-<p>For the <strong>newt</strong> tool:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$cd $GOPATH/src/mynewt.apache.org/newt/newt
-</pre></div>
-
-
-<p>For the <strong>newtmgr</strong> tool:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$cd $GOPATH/src/mynewt.apache.org/newtmgr/newtmgr
-</pre></div>
-
-
-<p><br>
-After you change to the specific tool directory, get the latest updates from the master branch. If you made changes and need to rebase with the origin, add the <code>--rebase origin master</code> arguments to the <code>git pull</code> command:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$git pull
-</pre></div>
-
-
-<p><br>
-Build and install the tool. The updated binary will be installed in the <strong>$GOPATH/bin</strong> directory: </p>
-<p>(<strong>Note:</strong> <code>-ldflags -s</code> must be passed to the <code>go install</code> command if you are rebuilding newtmgr)</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>$go install
-</pre></div>
-
-
-<p>You can run the <code>ls -l</code> command to check the modification time for the binary to ensure the new version is installed. </p>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../../known_issues/>
- <span class="fa fa-arrow-left"></span>
- Previous: Known Issues
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../ide/>
- Next: Using an IDE to Develop Mynewt Applications
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/faq/how_to_edit_docs/index.html b/develop/faq/how_to_edit_docs/index.html
deleted file mode 100644
index 0fd36525f1..0000000000
--- a/develop/faq/how_to_edit_docs/index.html
+++ /dev/null
@@ -1,384 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/faq/how_to_edit_docs/"> -->
- <link rel="shortcut icon" href="../../img/favicon.ico">
-
- <title>Edit Docs - 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">
- <link href="../../extra.css" rel="stylesheet">
-
- <!-- 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="Edit Docs">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../os/introduction/">Mynewt Documentation</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../go_env/
-">Appendix</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../go_env/">Setting Up Go to Contribute to Newt and Newtmgr Tools</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ide/">Using an IDE to Develop Mynewt Applications</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">Edit Docs</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../answers/">FAQ</a>
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../go_env/">Appendix</a></li>
-
-
-
- <li>» Edit Docs</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/faq/how_to_edit_docs.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="how-to-edit-docs">How to Edit Docs</h2>
-<h3 id="objective">Objective</h3>
-<p>Learn the process of editing docs by adding some content to a test document.</p>
-<h3 id="markdown-mkdocs-mou">Markdown, MkDocs, Mou</h3>
-<p>The Mynewt documentation you see on the Apache incubator website is a bunch of HTML files generated using MkDocs which is a simple static site generation tool geared towards building project documentation. You can read about it at <a href="http://www.mkdocs.org">http://www.mkdocs.org</a>. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool (which in our case is MkDocs).</p>
-<p>The HTML pages are generated periodically after changes have been reviewed and accepted into the master branch.</p>
-<h3 id="access-to-the-apache-repo">Access to the Apache repo</h3>
-<p>Get an account on Apache. You do not need a committer account to view the website or clone the repository but you need it to push changes to it.</p>
-<p>If you are not a committer, you may follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is <a href="https://git-wip-us.apache.org/docs/workflow.html">https://git-wip-us.apache.org/docs/workflow.html</a>. You will find the steps described in more detail later in this tutorial.</p>
-<h3 id="editing-an-existing-page">Editing an existing page</h3>
-<ul>
-<li>Create a fork on the <a href="https://github.com/apache/incubator-mynewt-site">github mirror</a>.</li>
-<li>Create a new branch to work on your documentation and move to that branch.</li>
-</ul>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span> $ git checkout -b <your-branch-name>
-</pre></div>
-
-
-<ul>
-<li>Make changes directly on github.com. Generate a pull request. Alternatively, you can edit locally on your machine, push the branch (or the changes in the branch) to your fork on github.com, and then generate a pull request.</li>
-</ul>
-<h3 id="adding-a-new-page">Adding a new page</h3>
-<p>If you create a new file somewhere in the <code>docs</code> subdirectory to add a new page, you have to add a line in the <code>mkdocs.yml</code> file at the correct level. For example, if you add a new module named "Wi-Fi" by creating a new file named <code>wifi.md</code> in the <code>network</code> directory, you have to insert the following line under <code>Networking User Guide</code> in the <code>mkdocs.yml</code> file (at the same level as the <code>docs</code> directory). In this example, a link will show up in the navigation bar on the left under "Networking User Guide" titled "Wi-Fi" and take the user to the contents of the 'wifi.md' file when the link is clicked. <strong> Note: The change will show up on this <a href="http://mynewt.apache.org">Mynewt site</a> only after your pull request is merged in and the updated site is generated.</strong></p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span> - 'Wi-Fi': 'wifi.md'
-</pre></div>
-
-
-<h3 id="local-preview-of-html-files">Local preview of HTML files</h3>
-<p>You have the option to install MkDocs and do a local conversion yourself to preview the pages using the built-in webserver that comes with MkDocs. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will).</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span> $ python --version
- Python 2.7.2
- $ pip --version
- pip 1.5.2
- $ pip install mkdocs
-</pre></div>
-
-
-<p>You will then run the built-in webserver from the root of the documentation directory using the command <code>mkdocs serve</code>. The root directory for documentation is <code>incubator-mynewt-site</code> or the directory with the <code>mkdocs.yml</code> file.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span> $ ls
- docs images mkdocs.yml
- $ mkdocs serve
-</pre></div>
-
-
-<p>Then go to <a href="http://127.0.0.1:8000">http://127.0.0.1:8000</a> to preview your pages and see how they will look on the website. <strong>Remember that the <a href="https://mynewt.apache.org">MyNewt website</a> itself will not be updated.</strong></p>
-<p>For more information on MkDocs go to <a href="http://www.mkdocs.org">http://www.mkdocs.org</a>. </p>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../ide/>
- <span class="fa fa-arrow-left"></span>
- Previous: Using an IDE to Develop Mynewt Applications
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../answers/>
- Next: FAQ
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/faq/ide/index.html b/develop/faq/ide/index.html
deleted file mode 100644
index 0517472262..0000000000
--- a/develop/faq/ide/index.html
+++ /dev/null
@@ -1,564 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/faq/ide/"> -->
- <link rel="shortcut icon" href="../../img/favicon.ico">
-
- <title>Using an IDE to Develop Mynewt Applications - 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">
- <link href="../../extra.css" rel="stylesheet">
-
- <!-- 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="Using an IDE to Develop Mynewt Applications">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../os/introduction/">Mynewt Documentation</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../go_env/
-">Appendix</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../go_env/">Setting Up Go to Contribute to Newt and Newtmgr Tools</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">Using an IDE to Develop Mynewt Applications</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../how_to_edit_docs/">Edit Docs</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../answers/">FAQ</a>
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../go_env/">Appendix</a></li>
-
-
-
- <li>» Using an IDE to Develop Mynewt Applications</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/faq/ide.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="developing-mynewt-applications-with-visual-studio-code">Developing Mynewt Applications with Visual Studio Code</h2>
-<p>This guide shows you how to set up Visual Studio Code to develop and debug Mynewt applications. Visual Studio Code is supported on Mac OS, Linux, and Windows. This guide shows you how to:</p>
-<ol>
-<li>Install Visual Studio Code. </li>
-<li>Install the C/C++ and debugger extensions.</li>
-<li>Define task configurations to build Mynewt applications.</li>
-<li>Define debugger configurations to debug Mynewt applications. </li>
-<li>Launch the debugger. </li>
-</ol>
-<p>Prerequisites:</p>
-<ul>
-<li>Have Internet connectivity to fetch remote Mynewt components.</li>
-<li>Have a computer to build a Mynewt application.</li>
-<li>
-<p>Perform <a href="../../os/get_started/native_install_intro/">native installation</a> for the Mynewt tools and toolchains.</p>
-<p><strong>Note:</strong> For Windows platforms, ensure that the MinGW bash you install is added to your Windows Path. In addition, if you are using Windows 10 WSL, you must have the MinGW bash before the Windows 10 WSL bash in your Windows Path.</p>
-</li>
-<li>
-<p>Read the Mynewt OS Concepts section.</p>
-</li>
-<li>Create a project space (directory structure) and populate it with the core code repository (apache-mynewt-core) or know how to as explained in Creating Your First Project. </li>
-<li>Complete one of the <a href="../../os/tutorials/blinky/">Blinky Tutorials</a>.</li>
-</ul>
-<p><strong>Notes:</strong> </p>
-<ul>
-<li>This guide is not a tutorial for Visual Studio Code. It assumes you are familiar with Visual Studio Code. If this is your first time using Visual Studio Code, we recommend that you read the Visual Studio Code <a href="https://code.visualstudio.com/docs">documentation and tutorials</a> and evaluate whether you would like to use it to develop Mynewt applications. </li>
-<li>This guide uses Visual Studio Code on Windows. Visual Studio Code is supported on Linux and Mac OS but may have some variations in the keyboard shortcuts and command names for these platforms. </li>
-<li>You can also use the Eclipse IDE to develop Mynewt applications. See <a href="https://www.codecoup.pl/blog/hacking-mynewt-in-eclipse">https://www.codecoup.pl/blog/hacking-mynewt-in-eclipse</a> for more details. On Windows platforms, you must also ensure the MinGW bash is set in your Windows Path as described in the prerequisites.</li>
-</ul>
-<h3 id="installing-visual-studio-code">Installing Visual Studio Code</h3>
-<p>Download and install Visual Studio Code from <a href="https://code.visualstudio.com/">https://code.visualstudio.com/</a>.</p>
-<h3 id="installing-the-cc-and-debugger-extensions">Installing the C/C++ and Debugger Extensions</h3>
-<p>You need to install two extensions:</p>
-<ol>
-<li>
-<p>The C/C++ extension from Microsoft. This extension provides language support such as symbol searching, signatuare help, go to definition, and go to declaration.</p>
-</li>
-<li>
-<p>The Native Debug extension from webfreak. This extension provides GDB support. </p>
-</li>
-</ol>
-<p><br>
-To install the C/C++ extension:</p>
-<ol>
-<li>Press <code>Ctrl-P</code> to open the search box.</li>
-<li>Type <code>ext install cpptools</code> in the search box and press Enter. You should see the extension at the top of the list. </li>
-<li>Click <code>Install</code> to install the extension.
-<br></li>
-</ol>
-<p>To install the Native Debugger:</p>
-<ol>
-<li>Press <code>Ctrl-P</code> to open the search box.</li>
-<li>Type <code>ext install webfreak.debug</code> in the search box and press Enter. You should see the Native Debug extension at the top of the list.</li>
-<li>Click <code>Install</code> to install the extension.
-<br></li>
-</ol>
-<h3 id="defining-tasks-for-mynewt-projects">Defining Tasks for Mynewt Projects</h3>
-<p>Two main concepts in Visual Studio Code are workspaces and tasks. A workspace represents a folder that is open. You can open multiple workspaces and switch between workspaces. </p>
-<p>Tasks allow you to integrate the external tools and operations that are used to build or test your project into Visual Studio Code. Tasks are run from and the task results can be analyzed in Visual Studio Code. Tasks are defined within the scope of a workspace. This means that the tasks you define for a workspace only apply to the given workspace.</p>
-<p><br></p>
-<h4 id="associating-a-mynewt-project-to-a-workspace">Associating a Mynewt Project to a Workspace</h4>
-<p>For your Mynewt project, your Visual Studio Code workspace is the Mynewt project base directory. For example, if you create a project named <code>myproj</code> under the <code>~/dev</code> directory, then you open the <code>~/dev/myproj</code> folder for your workspace. </p>
-<p>Select <strong>File</strong> > <strong>Open Folder</strong>, and select the <code>myproj</code> folder from the <code>Select Folder</code> dialog box to open the folder.</p>
-<p><br></p>
-<h4 id="defining-visual-studio-code-tasks-to-build-and-debug-mynewt-applications">Defining Visual Studio Code Tasks to Build and Debug Mynewt Applications</h4>
-<p>You define Visual Studio Code tasks to build and debug your Mynewt targets in Visual Studio Code. We use the Blinky application for the Arduino Zero board from the <a href="../../os/tutorials/arduino_zero/">Blinky On Arduino Zero Tutorial</a> to illustrate how to define the tasks to build and debug the Arduino blinky bootloader and application targets.</p>
-<p>Perform the following steps to create the tasks to build and debug the Arduino blinky bootloader and appliction targets:</p>
-<p>Step 1: Press <code>Ctrl-Shift-P</code>, type <code>task</code>, and select <strong>Tasks:Configure Task Runner</strong> from the search results. </p>
-<p>Step 2: Select <strong>Others</strong> (scroll down to the bottom of the list) to create a task runner for external commands.
-<br>
-<p align="center"><img src="/faq/pics/task_runner_small.png"></p>
-<br>
-Tasks are defined in the <code>tasks.json</code> file. You should see the <code>.vscode</code> folder created in the <code>MYPROJ</code> folder and a <code>tasks.json</code> file created in the <code>.vscode</code> folder. The <code>tasks.json</code> file has the following default values. </p>
-<p><br>
-<p align="center"><img src="/faq/pics/task_json_small.png"></p>
-<br></p>
-<p>The sample <code>tasks.json</code> file defines a simple task that runs the echo command with "Hello World" as the argument. </p>
-<p>Step 3: Delete the content from the <code>tasks.json</code> file, add the following definitions, and press <code>Ctrl-S</code> to save the file.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>{
- "version": "0.1.0",
- "command": "newt",
- "echoCommand": true,
- "isShellCommand": true,
-
- "tasks":[
- {
- "taskName": "build_arduino_boot",
- "args": ["build", "arduino_boot"],
- "suppressTaskName": true
- },
- {
- "taskName": "build_arduino_blinky",
- "args": ["build", "arduino_blinky"],
- "isBuildCommand": true,
- "suppressTaskName": true
- },
- {
- "taskName": "create_arduino_blinky",
- "args": ["create-image", "arduino_blinky", "1.0.0"],
- "suppressTaskName":true
- },
- {
- "taskName": "debug_arduino_blinky",
- "args": ["debug", "arduino_blinky", "-n"],
- "suppressTaskName": true
- }
- ]
-}
-</pre></div>
-
-
-<p><br>
-The <code>tasks.json</code> file specifies the tasks that are run to build and debug the Arduino blinky targets. Each task runs a <code>newt</code> command. The <code>newt</code> command to run and the arguments for the <code>newt</code> command are passed in the <code>args</code> property for each task. </p>
-<p>The following tasks are defined in this example:</p>
-<ol>
-<li><strong>build_arduino_boot</strong>: Runs the <code>newt build arduino_boot</code> command to build the arduino_boot target.</li>
-<li>
-<p><strong>build_arduino_blinky</strong>: Runs the <code>newt build arduino_blinky</code> command to build the arduino_blinky target. </p>
-<p><strong>Note:</strong> This task sets the <code>isBuildCommand</code> property to <code>true</code>. This is an optional property that, when set to true, allows you to run the <strong>Tasks: Run Build Task</strong>(<code>Ctrl-Shift-B</code>) command to start the task.</p>
-</li>
-<li>
-<p><strong>create_arduino_blinky</strong>: Runs the <code>newt create-image arduino_blinky</code> command to create the image file.</p>
-</li>
-<li><strong>debug_arduino_blinky</strong>: Runs the <code>newt build arduino_blinky -n</code> command to debug the arduino_blinky target. The <code>-n</code> flag is specified to start only the GDB server and not the GDB client. We will launch the GDB client from Visual Studio Code.</li>
-</ol>
-<p>For more information on tasks and all supported properties, see the <a href="https://code.visualstudio.com/docs/editor/tasks">Visual Studio Code Task documentation</a>.</p>
-<p><br></p>
-<h4 id="running-a-task">Running a Task</h4>
-<p>To run a task, press <code>Ctrl-Shift-P</code>, type <code>task</code> on the search box, and select <strong>Tasks: Run Task</strong>. The tasks that you define in the <code>tasks.json</code> file are listed. Select the task to run. </p>
-<p>The following is an example of running the <code>build_arduino_boot</code> task:
-<br>
-<p align="center"><img src="/faq/pics/task_select_small.png"></p>
-<br>
-<br>
-<p align="center"><img src="/faq/pics/task_start_small.png"></p></p>
-<p><br></p>
-<p><strong>Note</strong>:To run the <code>build_arduino_linky</code> task, you can use the keyboard shortcut <code>Ctrl-Shift-B</code> because the task has the property <code>isBuildCommand</code> set to true. </p>
-<p><br></p>
-<h4 id="defining-tasks-for-other-newt-commands">Defining Tasks for Other Newt Commands</h4>
-<p>Other newt commands, such as the <code>newt load</code> command, do not need to run from within Visual Studio Code. You can define a task for each command as a convenience and run the command as a task, or you can run the newt command on the command line from the Visual Studio Code integrated terminal or an external terminal.</p>
-<p>To create the tasks for the <code>newt load arduino_boot</code> and <code>newt laod arduino_blinky</code> commands, add the following definitions to the <code>tasks.json</code> file:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span> {
- "taskName": "load_arduino_boot",
- "args": ["load", "arduino_boot"],
- "suppressTaskName":true
- },
- {
- "taskName": "load_arduino_blinky",
- "args": ["load", "arduino_blinky"],
- "suppressTaskName":true
- },
-</pre></div>
-
-
-<p><br>
-To run a command from the Visual Studio integrated terminal, instead of starting a task, press <code>Ctrl-`</code> to launch the integrated terminal and enter the command on the prompt:
-<br>
-<p align="center"><img src="/faq/pics/integrated_terminal_small.png"></p>
-<br></p>
-<h3 id="defining-debugger-configurations">Defining Debugger Configurations</h3>
-<p>You need to define a debugger configuration to launch the GDB debugger from within Visual Studio Code: </p>
-<p>Step 1: Select <strong>Debug</strong> > <strong>Open Configuration</strong>, and select the <strong>GDB</strong> environment.</p>
-<p><br>
-<p align="center"><img src="/faq/pics/debug_new_config_small.png"></p>
-<br></p>
-<p>You should see a default <code>launch.json</code> file created in the <code>.vscode</code> folder.
-<br>
-<p align="center"><img src="/faq/pics/launch_small.png"></p>
-<br></p>
-<p><br>
-Step 2: Delete the content from the <code>launch.json</code> file, add the following definitions, and press 'Ctrl-S' to save the file.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>{
- "version": "0.2.0",
- "configurations": [
- {
- "name": "gdb_arduino_blinky",
- "type": "gdb",
- "request": "attach",
- "executable": "${workspaceRoot}\\bin\\targets\\arduino_blinky\\app\\apps\\blinky\\blinky.elf",
- "target": ":3333",
- "cwd": "${workspaceRoot}",
- "gdbpath": "C:\\Program Files (x86)\\GNU Tools ARM Embedded\\4.9 2015q2\\bin\\arm-none-eabi-gdb.exe",
- "remote": true
-
- }
- ]
-}
-</pre></div>
-
-
-<p><br>
-This defines a <code>gdb_arduino_blinky</code> debugger configuration. It specifies: </p>
-<ul>
-<li>The debugger is type <strong>gdb</strong>.</li>
-<li>To use the <code>blinky.elf</code> file for the executable. </li>
-<li>To use port 3333 to connect with the remote target.</li>
-<li>To use arm-none-eabi-gdb for the GDB program.
-<br></li>
-</ul>
-<h3 id="debugging-your-application">Debugging Your Application</h3>
-<p>To debug your application, start the GDB server and launch the GDB session from Visual Studio Code. For the the arduino blinky example, perform the following:</p>
-<p>Step 1: Run the debug_arduino_blinky task to start the GDB server. Perform the following:</p>
-<ol>
-<li>Press <code>Ctrl-Shift-P</code> and type <code>task</code> in the search box. </li>
-<li>Select <strong>Tasks:Run Task</strong> > <strong>debug_arduino_blinky</strong>.</li>
-<li>Press <code>Ctrl-Shift-U</code> to open the Output Panel and see the OpenOCD GDB Server output.
-<br> <br />
-<p align="center"><img src="/faq/pics/gdb_server_small.png"></p>
-<br></li>
-</ol>
-<p>Step 2: Start the GDB session. Perform the following: </p>
-<ol>
-<li>Press <code>Ctrl-Shift-Y</code> to view the Debug Console. </li>
-<li>Press the Debugging icon on the activity bar (Ctrl-Shift-D) to bring up the Debug Side Bar.</li>
-<li>Select <code>gdb_arduino_blinky</code> from the DEBUG drop down menu. </li>
-<li>Press the green play button to start the gdb session.</li>
-</ol>
-<p align="center"><img src="/faq/pics/gdb_small.png"></p>
-
-<p><br>
-Step 3: Debug your application. You should see a debug session similar to the one shown below:
-<p align="center"><img src="/faq/pics/gdb_debug_small.png"></p>
-<br>
-For more information on how to use the Visual Studio Code Debugger, see the <a href="https://code.visualstudio.com/docs/editor/debugging">Visual Studio Code debugging documentation</a>.</p>
-<h3 id="working-with-multiple-mynewt-applications">Working with Multiple Mynewt Applications</h3>
-<p>As mentioned previously, each mynewt project corresponds to a Visual Studio Code workspace. If you have multiple Mynewt application targets defined in same project, you will need to define build and debug tasks for each target in the <code>tasks.json</code> file and debugger configurations for the targets in the <code>launch.json</code> file for the workspace. If you have a different Mynewt project for each mynewt application, you will need to define build and debug tasks in the <code>tasks.json</code> file and the debugger configuration in the <code>launch.json</code> file for each workspace. </p>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../go_env/>
- <span class="fa fa-arrow-left"></span>
- Previous: Setting Up Go to Contribute to Newt and Newtmgr Tools
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../how_to_edit_docs/>
- Next: Edit Docs
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/img/NimBLE_conn.png b/develop/img/NimBLE_conn.png
deleted file mode 100644
index ae9fa701cb..0000000000
Binary files a/develop/img/NimBLE_conn.png and /dev/null differ
diff --git a/develop/img/favicon.ico b/develop/img/favicon.ico
deleted file mode 100644
index e85006a3ce..0000000000
Binary files a/develop/img/favicon.ico and /dev/null differ
diff --git a/develop/index.html b/develop/index.html
deleted file mode 100644
index a8839ead59..0000000000
--- a/develop/index.html
+++ /dev/null
@@ -1,332 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/"> -->
- <link rel="shortcut icon" href="./img/favicon.ico">
-
- <title>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">
- <link href="./extra.css" rel="stylesheet">
-
- <!-- 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="home">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="active "
->
- <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=""
->
- <a href="/latest/os/introduction">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 v2-landing">
-
- <div class="col-xs-12 highlights">
-
- <div class="highlight">
- <img src="/img/concurrent_conn.png">
-
- <h2>Built for wireless</h2>
-
- <p> Meet your application’s demands with open source networking stacks e.g. Bluetooth Low Energy 4.2. </p>
-
- <ul>
- <li> Flexible, powerful BLE implementation (NimBLE)</li>
- <ul>
- <li> Full stack, host only, or controller only - your choice </li>
- <li> 10x throughput of Nordic Softdevice </li>
- <li> 2x as many concurrent connections as Nordic Softdevice </li>
- <li> 4x as many active connections in simulatenous central and peripheral roles as Nordic Softdevice </li>
- <li> <a href="pages/ble/">More on NimBLE...</a> </li>
- </ul>
- <li> Additional connectivity options include WiFi </li>
- <li> Native support for TCP/IP, UDP </li>
- <li> Supports protocols for constrained networks e.g. CoAP and 6LoWPAN </li>
- </ul>
-
- </div>
-
-<br>
-
- <div class="highlight">
- <img src="/img/secure_img.png">
-
- <h2>Security from the start</h2>
-
- <p> Ensure security is built into the code as well as lifecycle management for your product. </p>
- <ul>
- <li>Secure bootloader to verify firmware integrity and authenticity </li>
- <li>Device identity for secure provisioning </li>
- <li>Authenticated, authorized, and encrypted data transfers </li>
- <li>Abstracted interface to leverage hardware security </li>
- <li> <a href="pages/securitybullets/">More on Mynewt OS security...</a> </li>
- </ul>
-
-
- </div>
-
- <div class="highlight">
- <img src="/img/FWdist.png">
-
- <h2>Operations ready</h2>
-
- <p>Ready your IoT network of billions for remote monitoring, troubleshooting, management, and upgrade.</p>
-
- <ul>
- <li> Image management module to enable efficient, failure-aware, and reliable remote firmware updates </li>
- <li> Logging modules that can be invoked at various levels of granularity, including specialized reboot logs </li>
- <li> Richly instrumented statistics modules for OS components and network interfaces </li>
- <li> Modularity for selective, optimized composition to extract the best performance from the hardware platform </li>
- <li> <a href="latest/os/os_user_guide/"> More on managment utilities...</a></li>
- </ul>
-
- </p>
- </div>
-
-
-
- <div class="highlight">
- <img src="/img/cross-platforms.png" style="margin-top: 0px; margin-bottom: 0px;">
-
- <h2>Cross-platform</h2>
-
- <p> Pick one MCU now. Migrate to another later. </p>
-
- <ul>
- <li> Designed to be hardware agnostic - Cortex M0-M4 micro controllers, MIPS, RISC-V </li>
- <li> Hardware Abstraction Layer (HAL) to provide a uniform interface for peripherals across various micro controllers </li>
- <li> Board specific configurations are abstracted in Board Support Packages (BSP) </li>
- </ul>
-
- </div>
-
- <div class="highlight">
- <img src="/img/newt-img.png">
-
- <h2>Easy to use</h2>
- <p> Compose, fine-tune, and build your image within hours or even minutes. </p>
-
- <ul>
- <li> Hardware initialization in single configuration file for the chosen BSP </li>
- <li> Initialization of service parameters in a single configuration file for the chosen module e.g. BLE controller </li>
- <li> Smart package management and build using Newt Tool </li>
- <li> Automatic configuration audits using Newt Tool </li>
- <li> <a href="../newt/newt_intro/">More on Newt...</a> </li>
- </ul>
- </div>
-
- <div class="updates">
-
-<br>
-<br>
-
- <div class="row">
- <div class="col-xs-12">
-
- <h2>Supported Boards</h2>
-
- <ul>
- <li>
- <a href="https://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF52832/"> nRF52 DK </a> from Nordic Semiconductor (Cortex-M4)
- </li>
- <li>
- <a href="https://www.nordicsemi.com/eng/Products/nRF52840-Preview-DK"> nRF52840 Preview DK </a> from Nordic Semiconductor (Cortex-M4)
- </li>
- <li>
- <a href="https://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF51822"> nRF51 DK </a> from Nordic Semiconductor (Cortex-M0)
- </li>
- <li>
- <a href="http://ruuvitag.com"> RuuviTag </a> Sensor beacon platform (Nordic nRF52832 based)
- </li>
- <li>
- <a href="http://redbearlab.com/blenano/"> BLE Nano </a> from RedBear (Nordic nRF51822 SoC based)
- </li>
- <li>
- <a href="https://www.kickstarter.com/projects/1991736672/bluetooth-5-ready-ble-module-nano-2-and-blend-2"> BLE Nano2 and Blend2 </a> from RedBear (Nordic nRF52832 SoC based)
- </li>
- <li>
- <a href="https://www.rigado.com/products/bmd-300-eval-kit/"> BMD-300-EVAL-ES </a> from Rigado (Cortex-M4)
- </li>
- <li>
- <a href="http://www.st.com/en/evaluation-tools/stm32f4discovery.html"> STM32F4DISCOVERY </a> from ST Micro (Cortex-M4)
- </li>
- <li>
- <a href=" https://www.olimex.com/Products/ARM/ST/STM32-E407/open-source-hardware"> STM32-E407 </a> from Olimex (Cortex-M4)
- </li>
- <li>
- <a href="https://www.arduino.cc/en/Main/ArduinoBoardZero"> Arduino Zero </a> (Cortex-M0)
- </li>
- <li>
- <a href="http://www.arduino.org/products/previous-version-boards/11-previous-version-boards/arduino-zero-pro"> Arduino Zero Pro </a> (Cortex-M0)
- </li>
- <li>
- <a href="http://www.arduino.org/products/boards/4-arduino-boards/arduino-m0-pro"> Arduino M0 Pro </a> (Cortex-M0)
- </li>
- <li>
- <a href="http://www.st.com/en/evaluation-tools/nucleo-f401re.html"> NUCLEO-F401RE </a> (Cortex-M4)
- </li>
- <li>
- <a href="http://www.nxp.com/products/software-and-tools/hardware-development-tools/freedom-development-boards/freedom-development-platform-for-kinetis-k64-k63-and-k24-mcus:FRDM-K64F"> FRDM-K64F </a> from NXP (Cortex-M4)
- </li>
- <li>
- <a href="https://creatordev.io/ci40-iot-dev-kit.html"> Creator Ci40 IoT Kit </a> from Imagination Technologies (MIPS CPU)
- </li>
- <li>
- <a href="http://microbit.org/hardware"> BBB micro:bit </a> with Nordic nRF51822 (Cortex-M0)
- </li>
- <li>
- <a href="https://www.adafruit.com/feather"> Adafruit Feather </a> with Nordic nRF52 (Cortex-M4)
- </li>
- </ul>
- </div>
- </div>
- </div>
-
- </div>
-
-</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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</footer>
-
- </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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/known_issues/index.html b/develop/known_issues/index.html
deleted file mode 100644
index 8975a9efd7..0000000000
--- a/develop/known_issues/index.html
+++ /dev/null
@@ -1,414 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/known_issues/"> -->
- <link rel="shortcut icon" href="../img/favicon.ico">
-
- <title>Known Issues - 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">
- <link href="../extra.css" rel="stylesheet">
-
- <!-- 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="Known Issues">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../os/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 class="active">
- <a href="./">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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../os/introduction/">Mynewt Documentation</a></li>
-
-
-
- <li>» Known Issues</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/known_issues.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="known-issues">Known Issues</h2>
-<p>Here is a list of known issues and workarounds:</p>
-<ol>
-<li>
-<p><code>newt install</code> returns the following error:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span>ReadDesc: No matching branch for apache-mynewt-core repo
-No matching branch for apache-mynewt-core repo
-</pre></div>
-
-
-<p>The apache-mynewt-core Git repository location has changed due to Mynewt's graduation from an incubator project to an Apache top level project. The HTTP redirect to the new location may fail for some users. </p>
-<p><strong>Workaround:</strong> Edit the <code>project.yml</code> file and change the line <code>repo: incubator-mynewt-core</code> as shown in the following example to <code>repo: mynewt-core</code>:</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span> repository.apache-mynewt-core:
- type: github
- vers: 1-latest
- user: apache
- repo: incubator-mynewt-core
-</pre></div>
-
-
-</li>
-</ol>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../newtmgr/install_windows/>
- <span class="fa fa-arrow-left"></span>
- Previous: Install Newtmgr On Windows
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../faq/go_env/>
- Next: Setting Up Go to Contribute to Newt and Newtmgr Tools
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json
deleted file mode 100644
index 8958f5f9e2..0000000000
--- a/develop/mkdocs/search_index.json
+++ /dev/null
@@ -1,12219 +0,0 @@
-{
- "docs": [
- {
- "location": "/",
- "text": "",
- "title": "Home"
- },
- {
- "location": "/pages/ble/",
- "text": "",
- "title": "Bluetooth Low Energy 4.2"
- },
- {
- "location": "/quick-start/",
- "text": "Get set\n\n\nApache Mynewt currently offers two ways to quickly get set up, each appealing to different personal preferences and levels of familiarity with embedded systems.\n\n\n\n\n\n\n\n\nOption 1:\n All-in-one docker container that bundles Newt tool, developer toolchains and libraries. For this option, go to \nDocker instructions\n\n\n\n\n\n\nOption 2:\n Step-by-step instructions to install the Newt tool, developer toolchains and libraries natively on your computer. For this option, go to \nNative Setup\n\n\n\n\n\n\n\n\nGo!\n\n\nStart a new project as explained under \nCreate Your First Project\n. The core Mynewt OS is automatically downloaded as part of the project installation.\n\n\n\n\n\n\n\n\nWhen you \nCreate Your First Project\n you define a simulated target and run Project Blinky, the Hello World equivalent in the embedded world.\n\n\n\n\n\n\nIf you have one of the supported \nboards\n, you can make real LEDs blink in \nProject Blinky\n. Simply choose the appropriate tutorial for the board and proceed.\n\n\n\n\n\n\n\n\nAnd More...\n\n\nExplore the \nTutorials\n section for other interesting projects or simply to learn more about Mynewt's capabilities and get familiar with its use.",
- "title": "Quick Start"
- },
- {
- "location": "/quick-start/#get-set",
- "text": "Apache Mynewt currently offers two ways to quickly get set up, each appealing to different personal preferences and levels of familiarity with embedded systems. Option 1: All-in-one docker container that bundles Newt tool, developer toolchains and libraries. For this option, go to Docker instructions Option 2: Step-by-step instructions to install the Newt tool, developer toolchains and libraries natively on your computer. For this option, go to Native Setup",
- "title": "Get set"
- },
- {
- "location": "/quick-start/#go",
- "text": "Start a new project as explained under Create Your First Project . The core Mynewt OS is automatically downloaded as part of the project installation. When you Create Your First Project you define a simulated target and run Project Blinky, the Hello World equivalent in the embedded world. If you have one of the supported boards , you can make real LEDs blink in Project Blinky . Simply choose the appropriate tutorial for the board and proceed.",
- "title": "Go!"
- },
- {
- "location": "/quick-start/#and-more",
- "text": "Explore the Tutorials section for other interesting projects or simply to learn more about Mynewt's capabilities and get familiar with its use.",
- "title": "And More..."
- },
- {
- "location": "/about/",
- "text": "Roadmap\n\n\nSome upcoming features:\n\n\n\n\nFull IP support\n\n\nLow power support with ability for drivers to turn on/off low power settings automatically\n\n\nSensor API, see \ndiscussion thread\n\n\nSupport for MIPS architecture\n\n\nSupport for additional boards\n\n\n\n\n The detailed roadmap is tracked on \nJIRA for Mynewt\n. \n\n\n\n\nFeature Request\n\n\nThe WISHLIST at the top of the roadmap on \nJIRA for Mynewt\n features all the new ideas awaiting discussion and review. Once the community decides to go ahead with a request, it is scheduled into a release. Generally, effort is made to schedule a requested feature into a particular version no later than 6 weeks prior to the planned release date.\n\n\nIf you have suggestions for a new feature, use case, or implementation improvements, file a JIRA ticket with Issue Type set to \"Wish\". Introduce it in the \ndev@\n mailing list with a link to the JIRA ticket. This assumes you have signed up for an account on JIRA and submitted a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project.\n\n\n\n\nFAQ\n\n\n Questions? \n Click \nhere",
- "title": "About"
- },
- {
- "location": "/about/#roadmap",
- "text": "Some upcoming features: Full IP support Low power support with ability for drivers to turn on/off low power settings automatically Sensor API, see discussion thread Support for MIPS architecture Support for additional boards The detailed roadmap is tracked on JIRA for Mynewt .",
- "title": "Roadmap"
- },
- {
- "location": "/about/#feature-request",
- "text": "The WISHLIST at the top of the roadmap on JIRA for Mynewt features all the new ideas awaiting discussion and review. Once the community decides to go ahead with a request, it is scheduled into a release. Generally, effort is made to schedule a requested feature into a particular version no later than 6 weeks prior to the planned release date. If you have suggestions for a new feature, use case, or implementation improvements, file a JIRA ticket with Issue Type set to \"Wish\". Introduce it in the dev@ mailing list with a link to the JIRA ticket. This assumes you have signed up for an account on JIRA and submitted a request to the dev@ mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project.",
- "title": "Feature Request"
- },
- {
- "location": "/about/#faq",
- "text": "Questions? Click here",
- "title": "FAQ"
- },
- {
- "location": "/talks/",
- "text": "",
- "title": "Talks"
- },
- {
- "location": "/download/",
- "text": "Latest Apache Mynewt OS Release\n\n\n\n\nRelease Version: Mynewt 0.9.0-incubating\n\n\nRelease Date: June 6, 2016\n\n\nRelease Notes\n \n\n\n\n\nFresh install\n\n\nIf you are brand new to Mynewt, go to \nQuick Start\n. The Newt tool will automatically download the latest release.\n\n\nIf you have already installed the Newt tool but not started any project yet, go to \nCreate Your First Project\n. The Newt tool will automatically download the latest release.\n\n\nUpgrade\n\n\nIf you have already installed the Newt tool and started a project that installed a previous version of Apache Mynewt, upgrade using Newt tool:\n\n\n$ newt upgrade\n\n\n\n\n\nCode in development\n\n\nWhile the use of one of the official releases listed above is generally recommended, you may be interested in seeing work in progress.\n\n\nThe most recent code resides in the \ndevelop\n branch of the Mynewt git repository. You may view or fork the repositories for Mynewt OS and Newt Tool from the Apache mirror on github.com.\n\n\n\n\nApache Mynewt OS mirror on github.com\n\n\nApache Newt Tool mirror on github.com\n\n\n\n\nAlternatively, you can clone the desired branch using git:\n\n\n$ git clone git://github.com/apache/incubator-mynewt-core.git -b develop\n$ git clone git://github.com/apache/incubator-mynewt-newt.git -b develop\n\n\n\n\n\n\n\nA relatively stable version of code in progress can be found in the \nmaster\n branch of the Mynewt git repository.\nYou may access the code for Mynewt OS and Newt Tool from the 'master` branch of the Apache mirror on github.com or clone it using git:\n\n\n$ git clone git://github.com/apache/incubator-mynewt-core.git\n$ git clone git://github.com/apache/incubator-mynewt-newt.git\n\n\n\n\n\n\n\nFor general information on using Git at Apache, go to https://git-wip-us.apache.org.\n\n\n\n\nRelease Archives\n\n\n\n\nMynewt 0.8.0-incubating, \nRelease Notes\n\n\nMynewt 0.8.0-b2-incubating, \nRelease Notes",
- "title": "Download"
- },
- {
- "location": "/download/#latest-apache-mynewt-os-release",
- "text": "Release Version: Mynewt 0.9.0-incubating Release Date: June 6, 2016 Release Notes",
- "title": "Latest Apache Mynewt OS Release"
- },
- {
- "location": "/download/#fresh-install",
- "text": "If you are brand new to Mynewt, go to Quick Start . The Newt tool will automatically download the latest release. If you have already installed the Newt tool but not started any project yet, go to Create Your First Project . The Newt tool will automatically download the latest release.",
- "title": "Fresh install"
- },
- {
- "location": "/download/#upgrade",
- "text": "If you have already installed the Newt tool and started a project that installed a previous version of Apache Mynewt, upgrade using Newt tool: $ newt upgrade",
- "title": "Upgrade"
- },
- {
- "location": "/download/#code-in-development",
- "text": "While the use of one of the official releases listed above is generally recommended, you may be interested in seeing work in progress. The most recent code resides in the develop branch of the Mynewt git repository. You may view or fork the repositories for Mynewt OS and Newt Tool from the Apache mirror on github.com. Apache Mynewt OS mirror on github.com Apache Newt Tool mirror on github.com Alternatively, you can clone the desired branch using git: $ git clone git://github.com/apache/incubator-mynewt-core.git -b develop\n$ git clone git://github.com/apache/incubator-mynewt-newt.git -b develop A relatively stable version of code in progress can be found in the master branch of the Mynewt git repository.\nYou may access the code for Mynewt OS and Newt Tool from the 'master` branch of the Apache mirror on github.com or clone it using git: $ git clone git://github.com/apache/incubator-mynewt-core.git\n$ git clone git://github.com/apache/incubator-mynewt-newt.git For general information on using Git at Apache, go to https://git-wip-us.apache.org.",
- "title": "Code in development"
- },
- {
- "location": "/download/#release-archives",
- "text": "Mynewt 0.8.0-incubating, Release Notes Mynewt 0.8.0-b2-incubating, Release Notes",
- "title": "Release Archives"
- },
- {
- "location": "/community/",
- "text": "Mailing Lists\n\n\nWe welcome you to join our mailing lists and get in touch with us! \n\n \nTo complete your subscription you have to confirm it by replying to the response sent to you when you email your subscription request!",
- "title": "Community"
- },
- {
- "location": "/community/#mailing-lists",
- "text": "We welcome you to join our mailing lists and get in touch with us! To complete your subscription you have to confirm it by replying to the response sent to you when you email your subscription request!",
- "title": "Mailing Lists"
- },
- {
- "location": "/events/",
- "text": "Events\n\n\nPlease take a look at our upcoming events! We hope to see you there.",
- "title": "Events"
- },
- {
- "location": "/events/#events",
- "text": "Please take a look at our upcoming events! We hope to see you there.",
- "title": "Events"
- },
- {
- "location": "/os/introduction/",
- "text": "Introduction\n\n\nWelcome to Apache Mynewt\n\n\nApache Mynewt is an operating system that makes it easy to develop\napplications for microcontroller environments where power and cost\nare driving factors. Examples of these devices are connected locks,\nlights, and wearables.\n\n\nMicrocontroller environments have a number of characteristics that\nmakes the operating system requirements for them unique:\n\n\n\n\n\n\nLow memory footprint: memory on these systems range from\n8-16KB (on the low end) to 16MB (on the high end).\n\n\n\n\n\n\nReduced code size: code often runs out of flash, and total available code size ranges from 64-128KB to 16-32MB.\n\n\n\n\n\n\nLow processing speed: processor speeds vary from 10-12MHz to 160-200MHz. \n\n\n\n\n\n\nLow power operation: devices operate in mostly sleeping mode, in order to conserve\nbattery power and maximize power usage.\n\n\n\n\n\n\nAs more and more devices get connected, these interconnected devices perform complex tasks. To\nperform these tasks, you need low-level operational functionality built into the operating system.\nTypically, connected devices built with these microcontrollers perform a myriad of functions:\n\n\n\n\n\n\nNetworking Stacks: Bluetooth Low Energy and Thread\n\n\n\n\n\n\nPeripherals: PWM to drive motors, ADCs to measure sensor data, and RTCs\nto keep time.\n\n\n\n\n\n\nScheduled Processing: actions must happen on a calendared or periodic basis.\n\n\n\n\n\n\nApache Mynewt accomplishes all the above easily, by providing a complete\noperating system for constrained devices, including:\n\n\n\n\n\n\nA fully open-source Bluetooth Low Energy stack with both Host and\nController implementations.\n\n\n\n\n\n\nA pre-emptive, multi-tasking Real Time operating system kernel\n\n\n\n\n\n\nA Hardware Abstraction Layer (HAL) that abstracts the MCU's\nperipheral functions, allowing developers to easily write cross-platform\ncode.\n\n\n\n\n\n\n\n\nNewt\n\n\nIn order to provide all this functionality, and operate in an\nextremely low resource environment, Mynewt provides a very fine-grained source\npackage management and build system tool, called \nnewt\n.\n\n\nYou can install \nnewt\n for \nMac OS\n, \nLinux\n, or \nWindows\n.\n\n\n\n\nNewt Manager\n\n\nIn order to enable a user to communicate with remote instances of Mynewt OS and query, configure, and operate them, Mynewt provides an application tool called Newt Manager or \nnewtmgr\n.\n\n\nYou can install \nnewtmgr\n for \nMac OS\n, \nLinux\n, or \nWindows\n.\n\n\n\n\nBuild your first Mynewt App with Newt\n\n\nWith the introductions out of the way, now is a good time to \nget set up and\nstarted\n with your first Mynewt application.\n\n\nHappy Hacking!",
- "title": "toc"
- },
- {
- "location": "/os/introduction/#introduction",
- "text": "",
- "title": "Introduction"
- },
- {
- "location": "/os/introduction/#welcome-to-apache-mynewt",
- "text": "Apache Mynewt is an operating system that makes it easy to develop\napplications for microcontroller environments where power and cost\nare driving factors. Examples of these devices are connected locks,\nlights, and wearables. Microcontroller environments have a number of characteristics that\nmakes the operating system requirements for them unique: Low memory footprint: memory on these systems range from\n8-16KB (on the low end) to 16MB (on the high end). Reduced code size: code often runs out of flash, and total available code size ranges from 64-128KB to 16-32MB. Low processing speed: processor speeds vary from 10-12MHz to 160-200MHz. Low power operation: devices operate in mostly sleeping mode, in order to conserve\nbattery power and maximize power usage. As more and more devices get connected, these interconnected devices perform complex tasks. To\nperform these tasks, you need low-level operational functionality built into the operating system.\nTypically, connected devices built with these microcontrollers perform a myriad of functions: Networking Stacks: Bluetooth Low Energy and Thread Peripherals: PWM to drive motors, ADCs to measure sensor data, and RTCs\nto keep time. Scheduled Processing: actions must happen on a calendared or periodic basis. Apache Mynewt accomplishes all the above easily, by providing a complete\noperating system for constrained devices, including: A fully open-source Bluetooth Low Energy stack with both Host and\nController implementations. A pre-emptive, multi-tasking Real Time operating system kernel A Hardware Abstraction Layer (HAL) that abstracts the MCU's\nperipheral functions, allowing developers to easily write cross-platform\ncode.",
- "title": "Welcome to Apache Mynewt"
- },
- {
- "location": "/os/introduction/#newt",
- "text": "In order to provide all this functionality, and operate in an\nextremely low resource environment, Mynewt provides a very fine-grained source\npackage management and build system tool, called newt . You can install newt for Mac OS , Linux , or Windows .",
- "title": "Newt"
- },
- {
- "location": "/os/introduction/#newt-manager",
- "text": "In order to enable a user to communicate with remote instances of Mynewt OS and query, configure, and operate them, Mynewt provides an application tool called Newt Manager or newtmgr . You can install newtmgr for Mac OS , Linux , or Windows .",
- "title": "Newt Manager"
- },
- {
- "location": "/os/introduction/#build-your-first-mynewt-app-with-newt",
- "text": "With the introductions out of the way, now is a good time to get set up and\nstarted with your first Mynewt application. Happy Hacking!",
- "title": "Build your first Mynewt App with Newt"
- },
- {
- "location": "/os/get_started/get_started/",
- "text": "Quick Start\n\n\nIf you are curious about Mynewt and want to get a quick feel for the project, you've come to the right place. We have two options for you:\n\n\n\n\nOption 1 (Recommended)\n allows you to install the Newt tool, instances of the Mynewt OS (for simulated targets), and toolchains for developing embedded software (e.g. GNU toolchain) natively on your laptop or computer. We have tried to make the process easy. For example, for the Mac OS we created brew formulas. \n\n\nWe recommend this option if you are familiar with such environments or are concerned about performance on your machine. Follow the instructions in the \nNative Install Option\n if you prefer this option.\n\n\n\n\nOption 2\n is an easy, self-contained way to get up and running with Mynewt - but has limitations! The Newt tool and build toolchains are all available in a single \nAll-in-one Docker Container\n that you can install on your laptop or computer.\n\n\nHowever, this is not a long-term option since support is not likely for all features useful or critical to embedded systems development. For example, USB device mapping available in the Docker toolkit is no longer available in the new Docker releases. The Docker option is also typically slower than the native install option. \n\n\n\n\nYou can then proceed with the instructions on how to \n* \nCreate Your First Project\n - on simulated hardware.\n\n\nUpon successful start, several tutorials await your eager attention!\n\n\n\n\nSend us an email on the dev@ mailing list if you have comments or suggestions!\n If you haven't joined the mailing list, you will find the links \nhere\n.",
- "title": "toc"
- },
- {
- "location": "/os/get_started/get_started/#quick-start",
- "text": "If you are curious about Mynewt and want to get a quick feel for the project, you've come to the right place. We have two options for you: Option 1 (Recommended) allows you to install the Newt tool, instances of the Mynewt OS (for simulated targets), and toolchains for developing embedded software (e.g. GNU toolchain) natively on your laptop or computer. We have tried to make the process easy. For example, for the Mac OS we created brew formulas. We recommend this option if you are familiar with such environments or are concerned about performance on your machine. Follow the instructions in the Native Install Option if you prefer this option. Option 2 is an easy, self-contained way to get up and running with Mynewt - but has limitations! The Newt tool and build toolchains are all available in a single All-in-one Docker Container that you can install on your laptop or computer. However, this is not a long-term option since support is not likely for all features useful or critical to embedded systems development. For example, USB device mapping available in the Docker toolkit is no longer available in the new Docker releases. The Docker option is also typically slower than the native install option. You can then proceed with the instructions on how to \n* Create Your First Project - on simulated hardware. Upon successful start, several tutorials await your eager attention! Send us an email on the dev@ mailing list if you have comments or suggestions! If you haven't joined the mailing list, you will find the links here .",
- "title": "Quick Start"
- },
- {
- "location": "/os/get_started/native_install_intro/",
- "text": "Native Installation\n\n\nThis section shows you how to install the tools to develop and build Mynewt OS applications on Mac OS, Linux, and Windows, and run and debug the applications on target boards. For Mac OS and Linux, you can also build Mynewt OS applications that run on Mynewt's simulated hardware. These applications run natively on Mac OS and Linux. \n\n\nThe tools you need are:\n\n\n\n\n\n\nNewt tool: Tool to create, build, load, and debug Mynewt OS applications.\n\n\n\n\nSee \nInstalling the Newt Tool on Mac OS\n to install on Mac OS.\n\n\nSee \nInstalling the Newt Tool on Linux\n to install on Linux.\n\n\nSee \nInstalling the Newt Tool on Windows\n to install on Windows. \n\n\n\n\n\n\n\n\nNative toolchain: Native toolchain to compile and build Mynewt OS applications that run on Mynewt's simulated hardware on Mac OS and Linux. \n\n\n(See \nInstalling Native Toolchain\n). \n\n\n\n\n\n\nCross tools for ARM: \n\n\n\n\nCross toolchain for ARM to compile and build Mynewt OS applications for target boards.\n\n\nDebuggers to load and debug applications on target boards. \n\n\n\n\n(See \nInstalling Cross Tools for ARMs\n).\n\n\n\n\n\n\nIf you would like to use an IDE to develop and debug Mynewt applications, see \nusing an IDE to develop Mynewt Applications\n. You must still perform the native installation outlined on this page.",
- "title": "toc"
- },
- {
- "location": "/os/get_started/native_install_intro/#native-installation",
- "text": "This section shows you how to install the tools to develop and build Mynewt OS applications on Mac OS, Linux, and Windows, and run and debug the applications on target boards. For Mac OS and Linux, you can also build Mynewt OS applications that run on Mynewt's simulated hardware. These applications run natively on Mac OS and Linux. The tools you need are: Newt tool: Tool to create, build, load, and debug Mynewt OS applications. See Installing the Newt Tool on Mac OS to install on Mac OS. See Installing the Newt Tool on Linux to install on Linux. See Installing the Newt Tool on Windows to install on Windows. Native toolchain: Native toolchain to compile and build Mynewt OS applications that run on Mynewt's simulated hardware on Mac OS and Linux. (See Installing Native Toolchain ). Cross tools for ARM: Cross toolchain for ARM to compile and build Mynewt OS applications for target boards. Debuggers to load and debug applications on target boards. (See Installing Cross Tools for ARMs ). If you would like to use an IDE to develop and debug Mynewt applications, see using an IDE to develop Mynewt Applications . You must still perform the native installation outlined on this page.",
- "title": "Native Installation"
- },
- {
- "location": "/newt/install/newt_mac/",
- "text": "Installing Newt on Mac OS\n\n\nNewt is supported on Mac OS X 64 bit platforms and has been tested on Mac OS 10.9 and higher.\n\n\nThis page shows you how to install the following versions of newt:\n\n\n\n\nThe latest stable release version (1.0.0) \n\n\nThe latest from the master branch (unstable)\n\n\n\n\nNote:\n If you would like to contribute to the newt tool, see \nSetting Up Go Environment to Contribute to Newt and Newtmgr Tools\n.\n\n\nInstalling Homebrew\n\n\nIf you do not have Homebrew installed, run the following command. You will be prompted for your sudo password.\n\n\n$ ruby -e \n$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\n\n\n\n\n\n\nYou can also extract (or \ngit clone\n) Homebrew and install it to /usr/local.\n\n\n\n\nInstalling Newt\n\n\nAdd the \n runtimeco/homebrew-mynewt \n tap:\n\n\n$brew tap runtimeco/homebrew-mynewt\n$brew update\n\n\n\n\n\n\n\nInstalling the Latest Release Version of Newt\n\n\nInstall the latest stable release version (1.0.0) of newt:\n\n\n$brew install mynewt-newt\n==\n Installing mynewt-newt from runtimeco/mynewt\n==\n Downloading https://github.com/runtimeco/binary-releases/raw/master/mynewt-newt-tools_1.0.0/mynewt-newt-1.0.0.mavericks.bottle.tar.gz\n==\n Downloading from https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/mynewt-newt-1.0.0.mavericks.\n######################################################################## 100.0%\n==\n Pouring mynewt-newt-1.0.0.mavericks.bottle.tar.gz\n\ud83c\udf7a /usr/local/Cellar/mynewt-newt/1.0.0: 3 files, 10.4MB\n\n\n\n\n\n\n\nNote:\n This installs the newt 1.0.0 binary that has been tested on Mac OS 10.9 and higher. If you are running an earlier version of Mac OS, the installation will install the latest version of Go and compile newt locally.\n\n\n\nCheck that you are using the installed version of newt:\n\n\n$which newt\n/usr/local/bin/newt\n$ls -l /usr/local/bin/newt\nlrwxr-xr-x 1 user staff 36 Apr 15 08:18 /usr/local/bin/newt -\n ../Cellar/mynewt-newt/1.0.0/bin/newt\n$newt version\nApache Newt (incubating) version: 1.0.0\n\n\n\n\n\nNote:\n If you previously built newt from source and the output of \nwhich newt\n shows \"$GOPATH/bin/newt\", you will need to move \"$GOPATH/bin\" after \"/usr/local/bin\" in your $PATH.\n\n\n\nGet information about newt: \n\n\n$newt help\nNewt allows you to create your own embedded application based on the Mynewt \noperating system. Newt provides both build and package management in a single \ntool, which allows you to compose an embedded application, and set of \nprojects, and then build the necessary artifacts from those projects. For more \ninformation on the Mynewt operating system, please visit \nhttps://mynewt.apache.org/. \n\nPlease use the newt help command, and specify the name of the command you want \nhelp for, for help on how to use a specific command\n\nUsage:\n newt [flags]\n newt [command]\n\nExamples:\n newt\n newt help [\ncommand-name\n]\n For help on \ncommand-name\n. If not specified, print this message.\n\nAvailable Commands:\n build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug \ntarget\n\n size Size of target components\n sync Synchronize project dependencies\n target Commands to create, delete, configure, and query targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number\n\nFlags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse \nnewt [command] --help\n for more information about a command.\n\n\n\n\n\n\n\nInstalling Newt from the Master Branch\n\n\nWe recommend that you use the latest stable release version (1.0.0) of newt. If you would like to use the master branch with the latest updates, you can install newt from the HEAD of the master branch. \n\n\n Notes: \n\n\n\n\nThe master branch may be unstable.\n\n\nThis installation will install the latest version of Go on your computer, if it is not installed, and compile newt locally. \n\n\n\n\n\nIf you previously installed newt using brew, unlink the current version:\n\n\n$brew unlink mynewt-newt\n\n\n\n\n\n\nInstall the latest unstable version of newt from the master branch:\n\n\n$brew install --HEAD mynewt-newt\n==\n Installing mynewt-newt from runtimeco/mynewt\n==\n Cloning https://github.com/apache/incubator-mynewt-newt.git\nCloning into \nUsers/\nusername\n/Library/Caches/Homebrew/mynewt-newt--git\n...\nremote: Counting objects: 623, done.\nremote: Compressing objects: 100% (501/501), done.\nremote: Total 623 (delta 154), reused 323 (delta 84), pack-reused 0\nReceiving objects: 100% (623/623), 1.10 MiB | 0 bytes/s, done.\nResolving deltas: 100% (154/154), done.\n==\n Checking out branch master\n==\n go install\n\ud83c\udf7a /usr/local/Cellar/mynewt-newt/HEAD-409f7d3: 3 files, 10.4MB, built in 10 seconds\n$newt version\nApache Newt (incubating) version: 1.0.0-dev\n\n\n\n\n\n\nTo switch back to the stable release version (1.0.0) of newt, you can run:\n\n\n$brew switch mynewt-newt 1.0.0\nCleaning /usr/local/Cellar/mynewt-newt/1.0.0\nCleaning /usr/local/Cellar/mynewt-newt/HEAD-409f7d3\n1 links created for /usr/local/Cellar/mynewt-newt/1.0.0\n$newt version\nApache Newt (incubating) version: 1.0.0",
- "title": "Install Newt on Mac"
- },
- {
- "location": "/newt/install/newt_mac/#installing-newt-on-mac-os",
- "text": "Newt is supported on Mac OS X 64 bit platforms and has been tested on Mac OS 10.9 and higher. This page shows you how to install the following versions of newt: The latest stable release version (1.0.0) The latest from the master branch (unstable) Note: If you would like to contribute to the newt tool, see Setting Up Go Environment to Contribute to Newt and Newtmgr Tools .",
- "title": "Installing Newt on Mac OS"
- },
- {
- "location": "/newt/install/newt_mac/#installing-homebrew",
- "text": "If you do not have Homebrew installed, run the following command. You will be prompted for your sudo password. $ ruby -e $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install) You can also extract (or git clone ) Homebrew and install it to /usr/local.",
- "title": "Installing Homebrew"
- },
- {
- "location": "/newt/install/newt_mac/#installing-newt",
- "text": "Add the runtimeco/homebrew-mynewt tap: $brew tap runtimeco/homebrew-mynewt\n$brew update",
- "title": "Installing Newt"
- },
- {
- "location": "/newt/install/newt_mac/#installing-the-latest-release-version-of-newt",
- "text": "Install the latest stable release version (1.0.0) of newt: $brew install mynewt-newt\n== Installing mynewt-newt from runtimeco/mynewt\n== Downloading https://github.com/runtimeco/binary-releases/raw/master/mynewt-newt-tools_1.0.0/mynewt-newt-1.0.0.mavericks.bottle.tar.gz\n== Downloading from https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/mynewt-newt-1.0.0.mavericks.\n######################################################################## 100.0%\n== Pouring mynewt-newt-1.0.0.mavericks.bottle.tar.gz\n\ud83c\udf7a /usr/local/Cellar/mynewt-newt/1.0.0: 3 files, 10.4MB Note: This installs the newt 1.0.0 binary that has been tested on Mac OS 10.9 and higher. If you are running an earlier version of Mac OS, the installation will install the latest version of Go and compile newt locally. \nCheck that you are using the installed version of newt: $which newt\n/usr/local/bin/newt\n$ls -l /usr/local/bin/newt\nlrwxr-xr-x 1 user staff 36 Apr 15 08:18 /usr/local/bin/newt - ../Cellar/mynewt-newt/1.0.0/bin/newt\n$newt version\nApache Newt (incubating) version: 1.0.0 Note: If you previously built newt from source and the output of which newt shows \"$GOPATH/bin/newt\", you will need to move \"$GOPATH/bin\" after \"/usr/local/bin\" in your $PATH. \nGet information about newt: $newt help\nNewt allows you to create your own embedded application based on the Mynewt \noperating system. Newt provides both build and package management in a single \ntool, which allows you to compose an embedded application, and set of \nprojects, and then build the necessary artifacts from those projects. For more \ninformation on the Mynewt operating system, please visit \nhttps://mynewt.apache.org/. \n\nPlease use the newt help command, and specify the name of the command you want \nhelp for, for help on how to use a specific command\n\nUsage:\n newt [flags]\n newt [command]\n\nExamples:\n newt\n newt help [ command-name ]\n For help on command-name . If not specified, print this message.\n\nAvailable Commands:\n build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug target \n size Size of target components\n sync Synchronize project dependencies\n target Commands to create, delete, configure, and query targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number\n\nFlags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse newt [command] --help for more information about a command.",
- "title": "Installing the Latest Release Version of Newt"
- },
- {
- "location": "/newt/install/newt_mac/#installing-newt-from-the-master-branch",
- "text": "We recommend that you use the latest stable release version (1.0.0) of newt. If you would like to use the master branch with the latest updates, you can install newt from the HEAD of the master branch. Notes: The master branch may be unstable. This installation will install the latest version of Go on your computer, if it is not installed, and compile newt locally. \nIf you previously installed newt using brew, unlink the current version: $brew unlink mynewt-newt \nInstall the latest unstable version of newt from the master branch: $brew install --HEAD mynewt-newt\n== Installing mynewt-newt from runtimeco/mynewt\n== Cloning https://github.com/apache/incubator-mynewt-newt.git\nCloning into Users/ username /Library/Caches/Homebrew/mynewt-newt--git ...\nremote: Counting objects: 623, done.\nremote: Compressing objects: 100% (501/501), done.\nremote: Total 623 (delta 154), reused 323 (delta 84), pack-reused 0\nReceiving objects: 100% (623/623), 1.10 MiB | 0 bytes/s, done.\nResolving deltas: 100% (154/154), done.\n== Checking out branch master\n== go install\n\ud83c\udf7a /usr/local/Cellar/mynewt-newt/HEAD-409f7d3: 3 files, 10.4MB, built in 10 seconds\n$newt version\nApache Newt (incubating) version: 1.0.0-dev \nTo switch back to the stable release version (1.0.0) of newt, you can run: $brew switch mynewt-newt 1.0.0\nCleaning /usr/local/Cellar/mynewt-newt/1.0.0\nCleaning /usr/local/Cellar/mynewt-newt/HEAD-409f7d3\n1 links created for /usr/local/Cellar/mynewt-newt/1.0.0\n$newt version\nApache Newt (incubating) version: 1.0.0",
- "title": "Installing Newt from the Master Branch"
- },
- {
- "location": "/newt/install/newt_linux/",
- "text": "Installing Newt on Linux\n\n\nYou can install the latest stable release (1.0.0) of the newt tool from a Debian binary package (amd64) or from a Debian source package. This page shows you how to:\n\n\n\n\nSet up your computer to retrieve Debian packages from the runtimeco debian package repository.\n\n\nInstall the latest stable release version of newt from a Debian binary package. \n\n\nInstall the latest stable release version of newt from a Debian source package.\n\n\n\n\nIf you are installing on an amd64 platform, we recommend that you install from the binary package.\n\n\nNote:\n We have tested the newt tool binary and apt-get install from the runtimeco Debian package repository for Ubuntu version 16. Earlier Ubuntu versions (for example: Ubuntu 14) may have incompatibility with the repository. We recommend that you upgrade Ubuntu on your computer. \n\n\nNote:\n See \nSetting Up an Go Environment to Contribute to Newt and Newtmgr Tools\n if you want to: \n\n\n\n\nUse the newt tool with the latest updates from the master branch. The master branch may be unstable and we recommend that you use the latest stable release version.\n\n\nContribute to the newt tool. \n\n\n\n\n\n\nSetting Up Your Computer to Get Packages from runtimeco\n\n\nThe newt Debian packages are stored in a private repository on \nhttps://github/runtimeco/debian-mynewt\n. The following steps must be performed on your computer to retreive packages from the repository:\n\n\nNote:\n You only need to perform this setup once on your computer.\n\n\n\n\nInstall the \napt-transport-https\n package to use HTTPS to retrieve packages. \n\n\nDownload the public key for the runtimeco debian repository and import the key into the apt keychain.\n\n\nAdd the repository for the binary and source packages to the apt source list.\n\n\n\n\n\nInstall the apt-transport-https package:\n\n\n$sudo apt-get update\n$sudo apt-get install apt-transport-https\n\n\n\n\n\n\n\nDownload the public key for the runtimeco apt repo (\nNote:\n There is a \n-\n after \napt-key add\n):\n\n\nwget -qO - https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/mynewt.gpg.key | sudo apt-key add -\n\n\n\n\n\n\n\nAdd the repository for the binary and source packages to the \nmynewt.list\n apt source list file.\n\n\n$sudo -s\n[sudo] password for \nuser\n:\nroot$ cat \n /etc/apt/sources.list.d/mynewt.list \nEOF\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\nEOF\nroot$exit\n\n\n\n\n\nNote:\n Do not forget to exit the root shell.\n\n\n\nVerify the content of the source list file:\n\n\n$more /etc/apt/sources.list.d/mynewt.list\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\n\n\n\n\n\n\nUpdate the available packages: \n\n\n$sudo apt-get update\n\n\n\n\n\n\n\nNote:\n If you are not using Ubuntu version 16, you may see the following errors. We recommend that you upgrade Ubuntu. We have provided instructions on how to manually download and install the binary package if you choose not to upgrade, but you will want to upgrade Ubuntu if you are installing from source.\n\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/source/Sources HttpError404\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-amd64/Packages Bad header line\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-i386/Packages HttpError404\n\nE: Some index files failed to download. They have been ignored, or old ones used instead.\n\n\n\n\n\n\n\n \n\n\nInstalling the Latest Release of Newt from a Binary Package\n\n\nFor Linux amd64 platforms, you can install the latest stable version (1.0.0) of newt from the newt Debian binary package. \n\n\n$sudo apt-get install newt\nReading package lists... Done\nBuilding dependency tree \nReading state information... Done\n\n ...\n\nPreparing to unpack .../newt_1.0.0-1_amd64.deb ...\nUnpacking newt (1.0.0-1) ...\nSetting up newt (1.0.0-1) ...\n\n\n\n\n\n\n\nNote:\nIf you are not using Ubuntu version 16 and are not able to update the runtimeco Debian package repo on your computer successfully, you can manually download and install the newt_1.0.0-1_amd64.deb binary package as follows:\n\n\n$wget https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/pool/main/n/newt/newt_1.0.0-1_amd64.deb\n$sudo dpkg -i newt_1.0.0-1_amd64.deb\n\n\n\n\n\n\nSee \nChecking the Installed Version of Newt\n to verify that you are using the installed version of newt.\n\n\n\n\nInstalling the Latest Stable Release of Newt from a Source Package\n\n\nIf you are running Linux on a different architecture, you can install the Debian source package for the latest stable release (1.0.0) of newt. The installation of the source package builds the newt binary and creates a Debian binary package that you then install.\n\n\nNote\n: Newt version 1.0.0 has been tested on Linux amd64 platforms. Version 1.0.0 does not build on 32 bit platforms but have been fixed for the next release.\n\n\n\n\nInstalling Go\n\n\nYou need Go version 1.7.6 or higher to build Newt version 1.0.0. Currently, the latest Go version that Ubuntu installs is 1.6. Run \ngo version\n to check if you have Go 1.7.6 installed. You can download Go from \nhttps://golang.org/dl/\n.\n\n\n\n\nInstalling from the Source Package\n\n\nCreate a directory and change into the directory, download the source package, and build a binary package from the source package:\n\n\nmkdir newt_source\n$cd newt_source\n$sudo apt-get --build source newt\n[sudo] password for \nuser\n: \nReading package lists... Done\nNeed to get 1,866 kB of source archives.\nGet:1 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newt 1.0.0-1 (dsc) [795 B]\nGet:2 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newt 1.0.0-1 (tar) [1,864 kB]\nGet:3 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newt 1.0.0-1 (diff) [2,000 B]\nFetched 1,866 kB in 1s (1,222 kB/s)\ndpkg-source: warning: extracting unsigned source package (newt_1.0.0-1.dsc)\ndpkg-source: info: extracting newt in newt-1.0.0\ndpkg-source: info: unpacking newt_1.0.0.orig.tar.gz\ndpkg-source: info: unpacking newt_1.0.0-1.debian.tar.xz\n\n ...\n\ndpkg-deb: building package \nnewt\n in \n../newt_1.0.0-1_amd64.deb\n.\n dpkg-genchanges --build=any,all \n../newt_1.0.0-1_amd64.changes\ndpkg-genchanges: info: binary-only upload (no source code included)\n dpkg-source --after-build newt-1.0.0\ndpkg-buildpackage: info: binary-only upload (no source included)\nW: Can\nt drop privileges for downloading as file \nnewt_1.0.0-1.dsc\n couldn\nt be accessed by user \n_apt\n. - pkgAcquire::Run (13: Permission denied)\n\n\n\n\n\nNote:\n You can ignore the \"Permission denied\" warning message at the end of the command.\n\n\n\nInstall the newt binary package that is created from the source package:\n\n\nNote:\n The file name for the binary package has the format: newt_1.0.0-1_\narch\n.deb, where \narch\n is a value that identifies your host architecture. \n\n\n$sudo dpkg -i newt_1.0.0-1_amd64.deb \nSelecting previously unselected package newt.\n(Reading database ... 252969 files and directories currently installed.)\nPreparing to unpack newt_1.0.0-1_amd64.deb ...\nUnpacking newt (1.0.0-1) ...\nSetting up newt (1.0.0-1) ...\n\n\n\n\n\n\n\n Checking the Installed Version of Newt\n\n\nAfter you have installed newt from either a Debian binary or source package, check that you are using the installed version of newt from \n/usr/bin\n. \n\n\nCheck the modification time of the binary and the newt tool that you are using:\n\n\n$ls -l /usr/bin/newt\n-rwxr-xr-x 1 root root 6919280 Apr 22 10:09 /usr/bin/newt\n$which newt\n/usr/bin/newt\n$newt version\nApache Newt (incubating) version: 1.0.0\n\n\n\n\n\nNote:\n If you previously built newt from source and the output of \nwhich newt\n shows \"$GOPATH/bin/newt\", you will need to move \"$GOPATH/bin\" after \"/usr/bin\" for your PATH environment variable and export it. \n\n\n\nGet information about newt:\n\n\n$newt\nNewt allows you to create your own embedded application based on the Mynewt\noperating system. Newt provides both build and package management in a single\ntool, which allows you to compose an embedded application, and set of\nprojects, and then build the necessary artifacts from those projects. For more\ninformation on the Mynewt operating system, please visit\nhttps://mynewt.apache.org/.\n\nPlease use the newt help command, and specify the name of the command you want\nhelp for, for help on how to use a specific command\n\nUsage:\n newt [flags]\n newt [command]\n\nExamples:\n newt\n newt help [\ncommand-name\n]\n For help on \ncommand-name\n. If not specified, print this message.\n\nAvailable Commands:\n build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug \ntarget\n\n size Size of target components\n sync Synchronize project dependencies\n target Commands to create, delete, configure, and query targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number\n\nFlags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse \nnewt [command] --help\n for more information about a command.",
- "title": "Install Newt on Linux"
- },
- {
- "location": "/newt/install/newt_linux/#installing-newt-on-linux",
- "text": "You can install the latest stable release (1.0.0) of the newt tool from a Debian binary package (amd64) or from a Debian source package. This page shows you how to: Set up your computer to retrieve Debian packages from the runtimeco debian package repository. Install the latest stable release version of newt from a Debian binary package. Install the latest stable release version of newt from a Debian source package. If you are installing on an amd64 platform, we recommend that you install from the binary package. Note: We have tested the newt tool binary and apt-get install from the runtimeco Debian package repository for Ubuntu version 16. Earlier Ubuntu versions (for example: Ubuntu 14) may have incompatibility with the repository. We recommend that you upgrade Ubuntu on your computer. Note: See Setting Up an Go Environment to Contribute to Newt and Newtmgr Tools if you want to: Use the newt tool with the latest updates from the master branch. The master branch may be unstable and we recommend that you use the latest stable release version. Contribute to the newt tool.",
- "title": "Installing Newt on Linux"
- },
- {
- "location": "/newt/install/newt_linux/#setting-up-your-computer-to-get-packages-from-runtimeco",
- "text": "The newt Debian packages are stored in a private repository on https://github/runtimeco/debian-mynewt . The following steps must be performed on your computer to retreive packages from the repository: Note: You only need to perform this setup once on your computer. Install the apt-transport-https package to use HTTPS to retrieve packages. Download the public key for the runtimeco debian repository and import the key into the apt keychain. Add the repository for the binary and source packages to the apt source list. \nInstall the apt-transport-https package: $sudo apt-get update\n$sudo apt-get install apt-transport-https Download the public key for the runtimeco apt repo ( Note: There is a - after apt-key add ): wget -qO - https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/mynewt.gpg.key | sudo apt-key add - Add the repository for the binary and source packages to the mynewt.list apt source list file. $sudo -s\n[sudo] password for user :\nroot$ cat /etc/apt/sources.list.d/mynewt.list EOF\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\nEOF\nroot$exit Note: Do not forget to exit the root shell. \nVerify the content of the source list file: $more /etc/apt/sources.list.d/mynewt.list\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main \nUpdate the available packages: $sudo apt-get update Note: If you are not using Ubuntu version 16, you may see the following errors. We recommend that you upgrade Ubuntu. We have provided instructions on how to manually download and install the binary package if you choose not to upgrade, but you will want to upgrade Ubuntu if you are installing from source. W: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/source/Sources HttpError404\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-amd64/Packages Bad header line\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-i386/Packages HttpError404\n\nE: Some index files failed to download. They have been ignored, or old ones used instead.",
- "title": "Setting Up Your Computer to Get Packages from runtimeco"
- },
- {
- "location": "/newt/install/newt_linux/#installing-the-latest-release-of-newt-from-a-binary-package",
- "text": "For Linux amd64 platforms, you can install the latest stable version (1.0.0) of newt from the newt Debian binary package. $sudo apt-get install newt\nReading package lists... Done\nBuilding dependency tree \nReading state information... Done\n\n ...\n\nPreparing to unpack .../newt_1.0.0-1_amd64.deb ...\nUnpacking newt (1.0.0-1) ...\nSetting up newt (1.0.0-1) ... Note: If you are not using Ubuntu version 16 and are not able to update the runtimeco Debian package repo on your computer successfully, you can manually download and install the newt_1.0.0-1_amd64.deb binary package as follows: $wget https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/pool/main/n/newt/newt_1.0.0-1_amd64.deb\n$sudo dpkg -i newt_1.0.0-1_amd64.deb \nSee Checking the Installed Version of Newt to verify that you are using the installed version of newt.",
- "title": "Installing the Latest Release of Newt from a Binary Package"
- },
- {
- "location": "/newt/install/newt_linux/#installing-the-latest-stable-release-of-newt-from-a-source-package",
- "text": "If you are running Linux on a different architecture, you can install the Debian source package for the latest stable release (1.0.0) of newt. The installation of the source package builds the newt binary and creates a Debian binary package that you then install. Note : Newt version 1.0.0 has been tested on Linux amd64 platforms. Version 1.0.0 does not build on 32 bit platforms but have been fixed for the next release.",
- "title": "Installing the Latest Stable Release of Newt from a Source Package"
- },
- {
- "location": "/newt/install/newt_linux/#installing-go",
- "text": "You need Go version 1.7.6 or higher to build Newt version 1.0.0. Currently, the latest Go version that Ubuntu installs is 1.6. Run go version to check if you have Go 1.7.6 installed. You can download Go from https://golang.org/dl/ .",
- "title": "Installing Go"
- },
- {
- "location": "/newt/install/newt_linux/#installing-from-the-source-package",
- "text": "Create a directory and change into the directory, download the source package, and build a binary package from the source package: mkdir newt_source\n$cd newt_source\n$sudo apt-get --build source newt\n[sudo] password for user : \nReading package lists... Done\nNeed to get 1,866 kB of source archives.\nGet:1 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newt 1.0.0-1 (dsc) [795 B]\nGet:2 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newt 1.0.0-1 (tar) [1,864 kB]\nGet:3 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newt 1.0.0-1 (diff) [2,000 B]\nFetched 1,866 kB in 1s (1,222 kB/s)\ndpkg-source: warning: extracting unsigned source package (newt_1.0.0-1.dsc)\ndpkg-source: info: extracting newt in newt-1.0.0\ndpkg-source: info: unpacking newt_1.0.0.orig.tar.gz\ndpkg-source: info: unpacking newt_1.0.0-1.debian.tar.xz\n\n ...\n\ndpkg-deb: building package newt in ../newt_1.0.0-1_amd64.deb .\n dpkg-genchanges --build=any,all ../newt_1.0.0-1_amd64.changes\ndpkg-genchanges: info: binary-only upload (no source code included)\n dpkg-source --after-build newt-1.0.0\ndpkg-buildpackage: info: binary-only upload (no source included)\nW: Can t drop privileges for downloading as file newt_1.0.0-1.dsc couldn t be accessed by user _apt . - pkgAcquire::Run (13: Permission denied) Note: You can ignore the \"Permission denied\" warning message at the end of the command. \nInstall the newt binary package that is created from the source package: Note: The file name for the binary package has the format: newt_1.0.0-1_ arch .deb, where arch is a value that identifies your host architecture. $sudo dpkg -i newt_1.0.0-1_amd64.deb \nSelecting previously unselected package newt.\n(Reading database ... 252969 files and directories currently installed.)\nPreparing to unpack newt_1.0.0-1_amd64.deb ...\nUnpacking newt (1.0.0-1) ...\nSetting up newt (1.0.0-1) ...",
- "title": "Installing from the Source Package"
- },
- {
- "location": "/newt/install/newt_windows/",
- "text": "Installing Newt on Windows\n\n\nYou can develop and build Mynewt OS applications for your target boards on the Windows platform. This page shows you how to build the newt tool from the lastest source on the master branch of the \nMynewt newt git repository\n. The tool is written in Go (golang).\n\n\nIn Windows, we use MinGW as the development environment to build and run Mynewt OS applications for target boards. MinGW runs the bash shell and provides a Unix-like environment. This provides a uniform way to build Mynewt OS applications. The Mynewt documentation and tutorials use Unix commands and you can use the same Unix commands on MinGW to follow the tutorials. The documentation will note any commands or behaviors that are specific to Windows.\n\n\nThis guide shows you how to perform the following:\n\n\n\n\nInstall MSYS2/MinGW. \n\n\nInstall Git.\n\n\nInstall Go. \n\n\nSetup the Go environment.\n\n\nDownload the source, build, and install the newt tool.\n\n\n\n\n\n\nStep 1: Installing MSYS2/MinGW\n\n\nMSYS2/MinGW provides a bash shell and tools to build applications that run on Windows. It includes three subsystems:\n\n\n\n\nMSYS2 toolchain to build POSIX applications that run on Windows. \n\n\nMinGW32 toolchains to build 32 bit native Windows applications. \n\n\nMinGW64 toolchains to build 64 bit native Windows applications. \n\n\n\n\nThe subsystems run the bash shell and provide a Unix-like environment. You can also run Windows applications from the shell. We will use the MinGW subsystem.\n\n\nNote:\n You can skip this installation step if you already have MinGW installed (from an earlier MSYS2/MinGW or Git Bash installation), but you must list the \nbin\n path for your installation in your Windows Path. For example: if you installed MSYS2/MinGW in the \n C:\\msys64 \n directory, add \nC:\\msys64\\usr\\bin\n to your Windows Path. If you are using Windows 10 WSL, ensure that you use the \nC:\\msys64\\usr\\bin\\bash.exe\n and not the Windows 10 WSL bash.\n\n\nTo install and setup MSYS2 and MinGW:\n\n\n\n\nDownload and run the \nMSYS2 installer\n. Select the 64 bit version if you are running on a 64 bit platform. Follow the prompts and check the \nRun MSYS2 now\n checkbox on the \nInstallation Complete\n dialog. \n\n\n\n\nIn the MSYS2 terminal, run the \npacman -Syuu\n command. If you get a message to run the update again, close the terminal and run the \npacman -Syuu\n command in a new terminal. \n\n\nTo start a new MSYS2 terminal, select the \"MSYS2 MSYS\" application from the Windows start menu.\n\n\n\n\n\n\nAdd a new user variable named \nMSYS2_PATH_TYPE\n and set the value to \ninherit\n in your Windows environment. This enables the MSYS2 and MinGW bash to inherit your Windows user \nPath\n values. \n\n\nTo add the variable, select properties for your computer \n Advanced system settings \n Environment Variables \n New\n\n\n\n\n\n\nAdd the MinGW \nbin\n path to your Windows Path. For example: if you install MSYS2/MinGW in the \nC:\\msys64\n directory, add \nC:\\msys64\\usr\\bin\n to your Windows Path. \n\n\nNote:\n If you are using Windows 10 WSL, ensure that you use the \nC:\\msys64\\usr\\bin\\bash.exe\n and not the Windows 10 WSL bash.\n\n\n\n\n\n\nRun the \npacman -Su vim\n command to install the vim editor. \n\n\nNote:\nYou can also use a Windows editor. You can access your files from the \nC:\\\nmsys-install-folder\n\\home\\\nusername\n folder, where \nmsys-install-folder\n is the folder you installed MSYS2 in. For example, if you installed MSYS2 in the \nmsys64\n folder, your files are stored in \nC:\\msys64\\home\\\nusername\n\n\n\n\n\n\nYou will need to start a MinGW terminal to run the commands specified in the Mynewt documentation and tutorials. To start a MinGW terminal, select the \"MSYS2 Mingw\" application from the start Menu (you can use either MinGW32 or MinGW64). \nIn Windows, we use the MingGW subsystem to build Mynewt tools and applications. \n\n\nStep 2: Installing Git for Windows\n\n\nDownload and install \nGit for Windows\n if it is not already installed.\n\n\nStep 3: Installing Go\n\n\nDownload and install the latest version of \nGo\n. Newt requires Go version 1.7.6 or higher.\n\n\nStep 4: Setting Up Your Go Environment\n\n\nThis section describes the Go environment and how to setup a Go workspace. Go provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the newt package repository into your local Go environment. The Go language environment dictates a specific directory structure, or workspace in Go parlance. It must contain three sibling directories with the names \nsrc\n, \npkg\n and \nbin\n: \n\n\n\n\nsrc contains Go source files organized into packages (one package per directory)\n\n\npkg contains package objects\n\n\nbin contains the Go application executables that Go builds and installs.\n\n\n\n\nThe \nGOPATH\n environment variable specifies the location of your workspace. To setup this workspace environment, create a \ndev\n directory and then a \ngo\n directory under it. Set the GOPATH environment variable to this directory where you will clone the newt repository.\n\n\nStart up a MinGW terminal and run the following commands to set up your Go workspace:\n\n\n$ cd $HOME\n$ mkdir -p dev/go \n$ cd dev/go\n$ export GOPATH=`pwd`\n\n\n\n\n\n\nAdd the following export statements to your ~/.bash_profile file and source the file:\n\n\nexport GOPATH=$HOME/dev/go\nexport PATH=$GOPATH/bin:$PATH\n\n\n\n\n\n\n\nStep 5: Downloading the Source and Installing the Newt Tool\n\n\nThe newt Go package is \nmynewt.apache.org/newt/newt\n and is stored in the \nApache Mynewt newt tool repository mirrored on github\n. We use the \ngo get\n command to download the source, build, and install the newt tool binary in the \n$GOPATH/bin\n directory. \n\n\n\nDownload the newt package source and install the tool:\n\n\n$cd $GOPATH\n$go get mynewt.apache.org/newt/newt\n$cd $GOPATH/src/mynewt.apache.org/newt\n$ls \nDISCLAIMER RELEASE_NOTES.md util\nINSTALLING.md build.sh viper\nLICENSE newt yaml\nNOTICE newtmgr\nREADME.md newtvm\n\n\n\n\n\n\nCheck that the newt tool is installed and it is in your path:\n\n\n$ls $GOPATH/bin/newt\n~/dev/go/bin/newt\n$which newt\n~/dev/go/bin/newt\n$ newt version\nApache Newt (incubating) version: 1.0.0-dev\n\n\n\n\n\n\nGet information about the newt tool:\n\n\n$newt\nNewt allows you to create your own embedded application based on the Mynewt\noperating system. Newt provides both build and package management in a single\ntool, which allows you to compose an embedded application, and set of\nprojects, and then build the necessary artifacts from those projects. For more\ninformation on the Mynewt operating system, please visit\nhttps://mynewt.apache.org/.\n\nPlease use the newt help command, and specify the name of the command you want\nhelp for, for help on how to use a specific command\n\nUsage:\n newt [flags]\n newt [command]\n\nExamples:\n newt\n newt help [\ncommand-name\n]\n For help on \ncommand-name\n. If not specified, print this message.\n\nAvailable Commands:\n build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug \ntarget\n\n size Size of target components\n sync Synchronize project dependencies\n target Commands to create, delete, configure, and query targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number\n\nFlags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 4)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse \nnewt [command] --help\n for more information about a command.",
- "title": "Install Newt on Windows"
- },
- {
- "location": "/newt/install/newt_windows/#installing-newt-on-windows",
- "text": "You can develop and build Mynewt OS applications for your target boards on the Windows platform. This page shows you how to build the newt tool from the lastest source on the master branch of the Mynewt newt git repository . The tool is written in Go (golang). In Windows, we use MinGW as the development environment to build and run Mynewt OS applications for target boards. MinGW runs the bash shell and provides a Unix-like environment. This provides a uniform way to build Mynewt OS applications. The Mynewt documentation and tutorials use Unix commands and you can use the same Unix commands on MinGW to follow the tutorials. The documentation will note any commands or behaviors that are specific to Windows. This guide shows you how to perform the following: Install MSYS2/MinGW. Install Git. Install Go. Setup the Go environment. Download the source, build, and install the newt tool.",
- "title": "Installing Newt on Windows"
- },
- {
- "location": "/newt/install/newt_windows/#step-1-installing-msys2mingw",
- "text": "MSYS2/MinGW provides a bash shell and tools to build applications that run on Windows. It includes three subsystems: MSYS2 toolchain to build POSIX applications that run on Windows. MinGW32 toolchains to build 32 bit native Windows applications. MinGW64 toolchains to build 64 bit native Windows applications. The subsystems run the bash shell and provide a Unix-like environment. You can also run Windows applications from the shell. We will use the MinGW subsystem. Note: You can skip this installation step if you already have MinGW installed (from an earlier MSYS2/MinGW or Git Bash installation), but you must list the bin path for your installation in your Windows Path. For example: if you installed MSYS2/MinGW in the C:\\msys64 directory, add C:\\msys64\\usr\\bin to your Windows Path. If you are using Windows 10 WSL, ensure that you use the C:\\msys64\\usr\\bin\\bash.exe and not the Windows 10 WSL bash. To install and setup MSYS2 and MinGW: Download and run the MSYS2 installer . Select the 64 bit version if you are running on a 64 bit platform. Follow the prompts and check the Run MSYS2 now checkbox on the Installation Complete dialog. In the MSYS2 terminal, run the pacman -Syuu command. If you get a message to run the update again, close the terminal and run the pacman -Syuu command in a new terminal. To start a new MSYS2 terminal, select the \"MSYS2 MSYS\" application from the Windows start menu. Add a new user variable named MSYS2_PATH_TYPE and set the value to inherit in your Windows environment. This enables the MSYS2 and MinGW bash to inherit your Windows user Path values. To add the variable, select properties for your computer Advanced system settings Environment Variables New Add the MinGW bin path to your Windows Path. For example: if you install MSYS2/MinGW in the C:\\msys64 directory, add C:\\msys64\\usr\\bin to your Windows Path. Note: If you are using Windows 10 WSL, ensure that you use the C:\\msys64\\usr\\bin\\bash.exe and not the Windows 10 WSL bash. Run the pacman -Su vim command to install the vim editor. Note: You can also use a Windows editor. You can access your files from the C:\\ msys-install-folder \\home\\ username folder, where msys-install-folder is the folder you installed MSYS2 in. For example, if you installed MSYS2 in the msys64 folder, your files are stored in C:\\msys64\\home\\ username You will need to start a MinGW terminal to run the commands specified in the Mynewt documentation and tutorials. To start a MinGW terminal, select the \"MSYS2 Mingw\" application from the start Menu (you can use either MinGW32 or MinGW64). \nIn Windows, we use the MingGW subsystem to build Mynewt tools and applications.",
- "title": "Step 1: Installing MSYS2/MinGW"
- },
- {
- "location": "/newt/install/newt_windows/#step-2-installing-git-for-windows",
- "text": "Download and install Git for Windows if it is not already installed.",
- "title": "Step 2: Installing Git for Windows"
- },
- {
- "location": "/newt/install/newt_windows/#step-3-installing-go",
- "text": "Download and install the latest version of Go . Newt requires Go version 1.7.6 or higher.",
- "title": "Step 3: Installing Go"
- },
- {
- "location": "/newt/install/newt_windows/#step-4-setting-up-your-go-environment",
- "text": "This section describes the Go environment and how to setup a Go workspace. Go provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the newt package repository into your local Go environment. The Go language environment dictates a specific directory structure, or workspace in Go parlance. It must contain three sibling directories with the names src , pkg and bin : src contains Go source files organized into packages (one package per directory) pkg contains package objects bin contains the Go application executables that Go builds and installs. The GOPATH environment variable specifies the location of your workspace. To setup this workspace environment, create a dev directory and then a go directory under it. Set the GOPATH environment variable to this directory where you will clone the newt repository. Start up a MinGW terminal and run the following commands to set up your Go workspace: $ cd $HOME\n$ mkdir -p dev/go \n$ cd dev/go\n$ export GOPATH=`pwd` \nAdd the following export statements to your ~/.bash_profile file and source the file: export GOPATH=$HOME/dev/go\nexport PATH=$GOPATH/bin:$PATH",
- "title": "Step 4: Setting Up Your Go Environment"
- },
- {
- "location": "/newt/install/newt_windows/#step-5-downloading-the-source-and-installing-the-newt-tool",
- "text": "The newt Go package is mynewt.apache.org/newt/newt and is stored in the Apache Mynewt newt tool repository mirrored on github . We use the go get command to download the source, build, and install the newt tool binary in the $GOPATH/bin directory. \nDownload the newt package source and install the tool: $cd $GOPATH\n$go get mynewt.apache.org/newt/newt\n$cd $GOPATH/src/mynewt.apache.org/newt\n$ls \nDISCLAIMER RELEASE_NOTES.md util\nINSTALLING.md build.sh viper\nLICENSE newt yaml\nNOTICE newtmgr\nREADME.md newtvm \nCheck that the newt tool is installed and it is in your path: $ls $GOPATH/bin/newt\n~/dev/go/bin/newt\n$which newt\n~/dev/go/bin/newt\n$ newt version\nApache Newt (incubating) version: 1.0.0-dev \nGet information about the newt tool: $newt\nNewt allows you to create your own embedded application based on the Mynewt\noperating system. Newt provides both build and package management in a single\ntool, which allows you to compose an embedded application, and set of\nprojects, and then build the necessary artifacts from those projects. For more\ninformation on the Mynewt operating system, please visit\nhttps://mynewt.apache.org/.\n\nPlease use the newt help command, and specify the name of the command you want\nhelp for, for help on how to use a specific command\n\nUsage:\n newt [flags]\n newt [command]\n\nExamples:\n newt\n newt help [ command-name ]\n For help on command-name . If not specified, print this message.\n\nAvailable Commands:\n build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug target \n size Size of target components\n sync Synchronize project dependencies\n target Commands to create, delete, configure, and query targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number\n\nFlags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 4)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse newt [command] --help for more information about a command.",
- "title": "Step 5: Downloading the Source and Installing the Newt Tool"
- },
- {
- "location": "/os/get_started/native_tools/",
- "text": "Installing Native Toolchain\n\n\nThis page shows you how to install the toolchain to build Mynewt OS applications that run native on Mac OS and Linux. The applications run on Mynewt's simulated hardware. It also allows you to run the test suites for all packages that do not require HW support. \n\n\nNote:\n This is not supported on Windows.\n\n\n\n\nSetting Up the Toolchain for Mac\n\n\nInstalling Brew\n\n\nIf you have not already installed Homebrew from the \nnewt\n tutorials pages\n, install it. \n\n\n\n\nInstalling gcc/libc\n\n\nOS X ships with a C compiler called Clang. To build applications for the Mynewt simulator with, a different compiler is used as default: gcc.\n\n\n$ brew install gcc\n...\n...\n==\n Summary\n\ud83c\udf7a /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M\n\n\n\n\n\n\n\nCheck the gcc version you have installed (either using brew or previously installed). The brew-installed version can be checked using \nbrew list gcc\n. The default compiler.yml configuration file in Mynewt expects version 5.x for Mac users, so if the installed version is 6.x and you wish to continue with this newer version, modify the \nmynewt-src-directory\n/repos/apache-mynewt-core/compiler/sim/compiler.yml\n file to change the default \ngcc-5\n defined there to \ngcc-6\n. In other words, replace the lines shown highlighted below:\n\n\n# OS X.\n\ncompiler.path.cc.DARWIN.OVERWRITE: \ngcc-5\n\n\ncompiler.path.as.DARWIN.OVERWRITE: \ngcc-5\n\n\ncompiler.path.objdump.DARWIN.OVERWRITE: \ngobjdump\n\ncompiler.path.objsize.DARWIN.OVERWRITE: \nobjsize\n\ncompiler.path.objcopy.DARWIN.OVERWRITE: \ngobjcopy\n\n\n\n\n\n\nwith the following:\n\n\ncompiler.path.cc.DARWIN.OVERWRITE: \ngcc-6\n\ncompiler.path.as.DARWIN.OVERWRITE: \ngcc-6\u201d\n\n\n\n\n\n\n\nIn case you wish to use Clang, you can change your \nmynewt-src-directory\n/repos/apache-mynewt-core/compiler/sim/compiler.yml\n to use Clang. Delete the gcc-5 DARWIN.OVERWRITE lines highlighted below.\n\n\n# OS X.\n\ncompiler.path.cc.DARWIN.OVERWRITE: \ngcc-5\n\n\ncompiler.path.as.DARWIN.OVERWRITE: \ngcc-5\n\n\ncompiler.path.objdump.DARWIN.OVERWRITE: \ngobjdump\n\ncompiler.path.objsize.DARWIN.OVERWRITE: \nobjsize\n\ncompiler.path.objcopy.DARWIN.OVERWRITE: \ngobjcopy\n\n\n\n\n\n\n\n\nNOTE:\n Both the newer gcc 6.x and Clang report a few warnings but they can be ignored.\n\n\n\n\nFURTHER NOTE:\n Mynewt developers mostly use gcc 5.x for sim builds; so it may take a little while to fix issues reported by the newer compiler. One option is to \ndisable warnings\n. To do that, remove the \n-Werror\n flag as an option for the compiler in the \nmynewt-src-directory\n/repos/apache-mynewt-core/compiler/sim/compiler.yml\n file as shown below. \n\n\ncompiler.flags.base: \n\n\n -m32 -Wall -ggdb\n\n\n\n\n\nYou may alternatively choose to \nspecify the precise warnings to ignore\n depending on the error thrown by the compiler. For example, if you see a \n[-Werror=misleading-indentation]\n error while building the sim image, add \n-Wno-misleading-indentation]\n as a compiler flag in the same line from the \nmynewt-src-directory\n/repos/apache-mynewt-core/compiler/sim/compiler.yml\n file.\n\n\ncompiler.flags.base: \n\n\n -m32 -Wall -Werror -ggdb -Wno-misleading-indentation\n\n\n\n\n\nA third option is to simply \ndowngrade to gcc 5.x\n.\n\n\n\n\nInstalling gdb\n\n\n$ brew install gdb\n...\n...\n==\n Summary\n\ud83c\udf7a /usr/local/Cellar/gdb/7.10.1: XXX files,YYM\n\n\n\n\n\n\n\nNOTE:\n When running a program with gdb, you may need to sign your gdb\nexecutable. \nThis page\n\nshows a recipe for gdb signing. Alternately you can skip this step and\ncontinue without the ability to debug your mynewt application on your PC.*\n\n\n\n\nSetting Up the Toolchain for Linux\n\n\nThe below procedure can be used to set up a Debian-based Linux system (e.g.,\nUbuntu). If you are running a different Linux distribution, you will need to\nsubstitute invocations of \napt-get\n in the below steps with the package manager\nthat your distro uses.\n\n\n\n\nInstall gcc/libc that will produce 32-bit executables:\n\n\n$ sudo apt-get install gcc-multilib libc6-i386\n\n\n\n\n\n\n\nInstall gdb\n\n\n$ sudo apt-get install gdb\n\nReading package lists... Done\nBuilding dependency tree \nReading state information... Done\nSuggested packages:\n gdb-doc gdbserver\nThe following NEW packages will be installed:\n gdb\n...\nProcessing triggers for man-db (2.6.7.1-1ubuntu1) ...\nSetting up gdb (7.7.1-0ubuntu5~14.04.2) ...\n\n\n\n\n\n\n\nAt this point you have installed all the necessary software to build and run your first project on a simluator on your Mac OS or Linux computer. You may proceed to the \nCreate Your First Project\n section or continue to the next section and install the cross tools for ARM.",
- "title": "Install Native Toolchain"
- },
- {
- "location": "/os/get_started/native_tools/#installing-native-toolchain",
- "text": "This page shows you how to install the toolchain to build Mynewt OS applications that run native on Mac OS and Linux. The applications run on Mynewt's simulated hardware. It also allows you to run the test suites for all packages that do not require HW support. Note: This is not supported on Windows.",
- "title": "Installing Native Toolchain"
- },
- {
- "location": "/os/get_started/native_tools/#setting-up-the-toolchain-for-mac",
- "text": "",
- "title": "Setting Up the Toolchain for Mac"
- },
- {
- "location": "/os/get_started/native_tools/#installing-brew",
- "text": "If you have not already installed Homebrew from the newt tutorials pages , install it.",
- "title": "Installing Brew"
- },
- {
- "location": "/os/get_started/native_tools/#installing-gcclibc",
- "text": "OS X ships with a C compiler called Clang. To build applications for the Mynewt simulator with, a different compiler is used as default: gcc. $ brew install gcc\n...\n...\n== Summary\n\ud83c\udf7a /usr/local/Cellar/gcc/5.2.0: 1353 files, 248M Check the gcc version you have installed (either using brew or previously installed). The brew-installed version can be checked using brew list gcc . The default compiler.yml configuration file in Mynewt expects version 5.x for Mac users, so if the installed version is 6.x and you wish to continue with this newer version, modify the mynewt-src-directory /repos/apache-mynewt-core/compiler/sim/compiler.yml file to change the default gcc-5 defined there to gcc-6 . In other words, replace the lines shown highlighted below: # OS X. compiler.path.cc.DARWIN.OVERWRITE: gcc-5 compiler.path.as.DARWIN.OVERWRITE: gcc-5 compiler.path.objdump.DARWIN.OVERWRITE: gobjdump \ncompiler.path.objsize.DARWIN.OVERWRITE: objsize \ncompiler.path.objcopy.DARWIN.OVERWRITE: gobjcopy with the following: compiler.path.cc.DARWIN.OVERWRITE: gcc-6 \ncompiler.path.as.DARWIN.OVERWRITE: gcc-6\u201d In case you wish to use Clang, you can change your mynewt-src-directory /repos/apache-mynewt-core/compiler/sim/compiler.yml to use Clang. Delete the gcc-5 DARWIN.OVERWRITE lines highlighted below. # OS X. compiler.path.cc.DARWIN.OVERWRITE: gcc-5 compiler.path.as.DARWIN.OVERWRITE: gcc-5 compiler.path.objdump.DARWIN.OVERWRITE: gobjdump \ncompiler.path.objsize.DARWIN.OVERWRITE: objsize \ncompiler.path.objcopy.DARWIN.OVERWRITE: gobjcopy NOTE: Both the newer gcc 6.x and Clang report a few warnings but they can be ignored. FURTHER NOTE: Mynewt developers mostly use gcc 5.x for sim builds; so it may take a little while to fix issues reported by the newer compiler. One option is to disable warnings . To do that, remove the -Werror flag as an option for the compiler in the mynewt-src-directory /repos/apache-mynewt-core/compiler/sim/compiler.yml file as shown below. compiler.flags.base: -m32 -Wall -ggdb You may alternatively choose to specify the precise warnings to ignore depending on the error thrown by the compiler. For example, if you see a [-Werror=misleading-indentation] error while building the sim image, add -Wno-misleading-indentation] as a compiler flag in the same line from the mynewt-src-directory /repos/apache-mynewt-core/compiler/sim/compiler.yml file. compiler.flags.base: -m32 -Wall -Werror -ggdb -Wno-misleading-indentation A third option is to simply downgrade to gcc 5.x .",
- "title": "Installing gcc/libc"
- },
- {
- "location": "/os/get_started/native_tools/#installing-gdb",
- "text": "$ brew install gdb\n...\n...\n== Summary\n\ud83c\udf7a /usr/local/Cellar/gdb/7.10.1: XXX files,YYM NOTE: When running a program with gdb, you may need to sign your gdb\nexecutable. This page \nshows a recipe for gdb signing. Alternately you can skip this step and\ncontinue without the ability to debug your mynewt application on your PC.*",
- "title": "Installing gdb"
- },
- {
- "location": "/os/get_started/native_tools/#setting-up-the-toolchain-for-linux",
- "text": "The below procedure can be used to set up a Debian-based Linux system (e.g.,\nUbuntu). If you are running a different Linux distribution, you will need to\nsubstitute invocations of apt-get in the below steps with the package manager\nthat your distro uses.",
- "title": "Setting Up the Toolchain for Linux"
- },
- {
- "location": "/os/get_started/native_tools/#install-gcclibc-that-will-produce-32-bit-executables",
- "text": "$ sudo apt-get install gcc-multilib libc6-i386",
- "title": "Install gcc/libc that will produce 32-bit executables:"
- },
- {
- "location": "/os/get_started/native_tools/#install-gdb",
- "text": "$ sudo apt-get install gdb\n\nReading package lists... Done\nBuilding dependency tree \nReading state information... Done\nSuggested packages:\n gdb-doc gdbserver\nThe following NEW packages will be installed:\n gdb\n...\nProcessing triggers for man-db (2.6.7.1-1ubuntu1) ...\nSetting up gdb (7.7.1-0ubuntu5~14.04.2) ... At this point you have installed all the necessary software to build and run your first project on a simluator on your Mac OS or Linux computer. You may proceed to the Create Your First Project section or continue to the next section and install the cross tools for ARM.",
- "title": "Install gdb"
- },
- {
- "location": "/os/get_started/cross_tools/",
- "text": "Installing the Cross Tools for ARM\n\n\nThis page shows you how to install the tools to build, run, and debug Mynewt OS applications that run on supported ARM target boards. It shows you how to install the following tools on Mac OS, Linux and Windows:\n\n\n\n\nARM cross toolchain to compile and build Mynewt applications for the target boards.\n\n\nDebuggers to load and debug applications on the target boards.\n\n\n\n\n\n\nInstalling the ARM Cross Toolchain\n\n\nARM maintains a pre-built GNU toolchain with gcc and gdb targeted at Embedded ARM Processors, namely Cortex-R/Cortex-M processor families. Mynewt OS has been tested with version 4.9 of the toolchain and we recommend you install this version to get started. Mynewt OS will eventually work with multiple versions available, including the latest releases. \n\n\nInstalling the ARM Toolchain For Mac OS X\n\n\nAdd the \nPX4/homebrew-px4\n homebrew tap and install version 4.9 of the toolchain. After installing, check that the symbolic link that homebrew created points to the correct version of the debugger.\n\n\n$ brew tap PX4/homebrew-px4\n$ brew update\n$ brew install gcc-arm-none-eabi-49\n$ arm-none-eabi-gcc --version \narm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]\nCopyright (C) 2014 Free Software Foundation, Inc.\nThis is free software; see the source for copying conditions. There is NO\nwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n$ ls -al /usr/local/bin/arm-none-eabi-gdb\nlrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb -\n /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb\n\n\n\n\n\nNote:\n If no version is specified, brew will install the latest version available. \n\n\n\n\nInstalling the ARM Toolchain For Linux\n\n\nOn a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with\napt-get as documented below. The steps are explained in depth at\n\nhttps://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa\n.\n\n\n$ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi \n$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa\n$ sudo apt-get update \n$ sudo apt-get install gcc-arm-none-eabi\n$ sudo apt-get install gdb-arm-none-eabi\n\n\n\n\n\n\n\nInstalling the ARM Toolchain for Windows\n\n\nStep 1: Download and run the \ninstaller\n to install arm-none-eabi-gcc and arm-none-eabi-gdb. Select the default destination folder: \nC:\\Program Files (x86)\\GNU Tools ARM Embedded\\4.9 2015q2\n. \n\n\nNote:\n You may select a different folder but the installation instructions use the default values.\n\n\nStep 2: Add the path:\n C:\\Program Files (x86)\\GNU Tools ARM Embedded\\4.9 2015q2\\bin\n to your Windows \nPath\n environment variable. Note: You must add \nbin\n to the path.\n\n\nStep 3: Check that you are using the installed versions arm-none-eabi-gcc and arm-none-eabi-gdb. Open a MinGW terminal and run the \nwhich\n commands. \n\n\nNote:\n You must start a new MinGW terminal to inherit the new \nPath\n values.\n\n\n$ which arm-none-eabi-gcc\n/c/Program Files (x86)/GNU Tools ARM Embedded/4.9 2015q2/bin/arm-none-eabi-gcc\n$which arm-none-eabi-gdb\n/c/Program Files (x86)/GNU Tools ARM Embedded/4.9 2015q2/bin/arm-none-eabi-gdb\n\n\n\n\n\nInstalling the Debuggers\n\n\nMynewt uses, depending on the board, either the OpenOCD or SEGGER J-Link debuggers. \n\n\n\nInstalling the OpenOCD Debugger\n\n\nOpenOCD (Open On-Chip Debugger) is open-source software that allows your\ncomputer to interface with the JTAG debug connector on a variety of boards. A\nJTAG connection lets you debug and test embedded target devices. For more on\nOpenOCD go to \nhttp://openocd.org\n.\n\n\nOpenOCD version 0.10.0 with nrf52 support is required. A binary for this version is available to download for Mac OS, Linux, and Windows.\n\n\n\n\nInstalling OpenOCD on Mac OS\n\n\nStep 1: Download the \nbinary tarball for Mac OS\n.\n\n\nStep 2: Change to the root directory: \n\n\n$cd / \n\n\n\n\n\n\nStep 3: Untar the tarball and install into \n /usr/local/bin\n. You will need to replace \n ~/Downloads \n with the directory that the tarball is downloaded to. \n\n\nsudo tar -xf ~/Downloads/openocd-bin-0.10.0-MacOS.tgz ` \n\n\n\n\n\n\nStep 4: Check the OpenOCD version you are using. \n\n\n$which openocd\n/usr/local/bin/openocd\n$openocd -v\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\nhttp://openocd.org/doc/doxygen/bugs.html\n\n\n\n\n\nYou should see version: \n0.10.0\n. \n\n\n\n\nInstalling OpenOCD on Linux\n\n\nStep 1: Download the \nbinary tarball for Linux\n\n\nStep 2: Change to the root directory: \n\n\n$cd / \n\n\n\n\n\n\nStep 3: Untar the tarball and install into \n /usr/local/bin\n. You will need to replace \n ~/Downloads \n with the directory that the tarball is downloaded to. \n\n\n Note:\n You must specify the -p option for the tar command.\n\n\n$sudo tar -xpf ~/Downloads/openocd-bin-0.10.0-Linux.tgz\n\n\n\n\n\n\nStep 4: Check the OpenOCD version you are using: \n\n\n$which openocd\n/usr/local/bin/openocd\n$openocd -v\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\nhttp://openocd.org/doc/doxygen/bugs.html\n\n\n\n\n\nYou should see version: \n0.10.0\n. \n\n\nIf you see any of these error messages:\n\n\n\n\n\n\nopenocd: error while loading shared libraries: libhidapi-hidraw.so.0: cannot open shared object file: No such file or directory\n\n\n\n\n\n\nopenocd: error while loading shared libraries: libusb-1.0.so.0: cannot open shared object file: No such file or directory \n\n\n\n\n\n\nrun the following command to install the libraries: \n\n\n$sudo apt-get install libhidapi-dev:i386\n\n\n\n\n\n\n\nInstalling OpenOCD on Windows\n\n\nStep 1: Download the \nbinary zip file for Windows\n.\n\n\nStep 2: Extract into the \nC:\\openocd-0.10.0\n folder. \n\n\nStep 3: Add the path: \n C:\\openocd-0.10.0\\bin\n to your Windows User \nPath\n environment variable. Note: You must add \nbin\n to the path.\n\n\nStep 4: Check the OpenOCD version you are using. Open a new MinGW terminal and run the following commands: \n\n\nNote:\n You must start a new MinGW terminal to inherit the new \nPath\n values.\n\n\n$which openocd\n/c/openocd-0.10.0/bin/openocd\n$openocd -v\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\n http://openocd.org/doc/doxygen/bugs.html\n\n\n\n\n\nYou should see version: \n0.10.0\n. \n\n\n\n\nInstalling SEGGAR J-Link\n\n\nYou can download and install Segger J-LINK Software and documentation pack from \nSEGGER\n. \n\n\nNote:\n On Windows, perform the following after the installation:\n\n\n\n\nAdd the installation destination folder path to your Windows user \nPath\n environment variable. You do not need to add \nbin\n to the path.\n\n\nOpen a new MinGW terminal to inherit the new \nPath\n values.",
- "title": "Install Cross Tools for ARM"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-cross-tools-for-arm",
- "text": "This page shows you how to install the tools to build, run, and debug Mynewt OS applications that run on supported ARM target boards. It shows you how to install the following tools on Mac OS, Linux and Windows: ARM cross toolchain to compile and build Mynewt applications for the target boards. Debuggers to load and debug applications on the target boards.",
- "title": "Installing the Cross Tools for ARM"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-arm-cross-toolchain",
- "text": "ARM maintains a pre-built GNU toolchain with gcc and gdb targeted at Embedded ARM Processors, namely Cortex-R/Cortex-M processor families. Mynewt OS has been tested with version 4.9 of the toolchain and we recommend you install this version to get started. Mynewt OS will eventually work with multiple versions available, including the latest releases.",
- "title": "Installing the ARM Cross Toolchain"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-arm-toolchain-for-mac-os-x",
- "text": "Add the PX4/homebrew-px4 homebrew tap and install version 4.9 of the toolchain. After installing, check that the symbolic link that homebrew created points to the correct version of the debugger. $ brew tap PX4/homebrew-px4\n$ brew update\n$ brew install gcc-arm-none-eabi-49\n$ arm-none-eabi-gcc --version \narm-none-eabi-gcc (GNU Tools for ARM Embedded Processors) 4.9.3 20150529 (release) [ARM/embedded-4_9-branch revision 224288]\nCopyright (C) 2014 Free Software Foundation, Inc.\nThis is free software; see the source for copying conditions. There is NO\nwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n$ ls -al /usr/local/bin/arm-none-eabi-gdb\nlrwxr-xr-x 1 aditihilbert admin 69 Sep 22 17:16 /usr/local/bin/arm-none-eabi-gdb - /usr/local/Cellar/gcc-arm-none-eabi-49/20150609/bin/arm-none-eabi-gdb Note: If no version is specified, brew will install the latest version available.",
- "title": "Installing the ARM Toolchain For Mac OS X"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-arm-toolchain-for-linux",
- "text": "On a Debian-based Linux distribution, gcc 4.9.3 for ARM can be installed with\napt-get as documented below. The steps are explained in depth at https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa . $ sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi \n$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa\n$ sudo apt-get update \n$ sudo apt-get install gcc-arm-none-eabi\n$ sudo apt-get install gdb-arm-none-eabi",
- "title": "Installing the ARM Toolchain For Linux"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-arm-toolchain-for-windows",
- "text": "Step 1: Download and run the installer to install arm-none-eabi-gcc and arm-none-eabi-gdb. Select the default destination folder: C:\\Program Files (x86)\\GNU Tools ARM Embedded\\4.9 2015q2 . Note: You may select a different folder but the installation instructions use the default values. Step 2: Add the path: C:\\Program Files (x86)\\GNU Tools ARM Embedded\\4.9 2015q2\\bin to your Windows Path environment variable. Note: You must add bin to the path. Step 3: Check that you are using the installed versions arm-none-eabi-gcc and arm-none-eabi-gdb. Open a MinGW terminal and run the which commands. Note: You must start a new MinGW terminal to inherit the new Path values. $ which arm-none-eabi-gcc\n/c/Program Files (x86)/GNU Tools ARM Embedded/4.9 2015q2/bin/arm-none-eabi-gcc\n$which arm-none-eabi-gdb\n/c/Program Files (x86)/GNU Tools ARM Embedded/4.9 2015q2/bin/arm-none-eabi-gdb",
- "title": "Installing the ARM Toolchain for Windows"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-debuggers",
- "text": "Mynewt uses, depending on the board, either the OpenOCD or SEGGER J-Link debuggers.",
- "title": "Installing the Debuggers"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-the-openocd-debugger",
- "text": "OpenOCD (Open On-Chip Debugger) is open-source software that allows your\ncomputer to interface with the JTAG debug connector on a variety of boards. A\nJTAG connection lets you debug and test embedded target devices. For more on\nOpenOCD go to http://openocd.org . OpenOCD version 0.10.0 with nrf52 support is required. A binary for this version is available to download for Mac OS, Linux, and Windows.",
- "title": "Installing the OpenOCD Debugger"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-openocd-on-mac-os",
- "text": "Step 1: Download the binary tarball for Mac OS . Step 2: Change to the root directory: $cd / \nStep 3: Untar the tarball and install into /usr/local/bin . You will need to replace ~/Downloads with the directory that the tarball is downloaded to. sudo tar -xf ~/Downloads/openocd-bin-0.10.0-MacOS.tgz ` \nStep 4: Check the OpenOCD version you are using. $which openocd\n/usr/local/bin/openocd\n$openocd -v\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\nhttp://openocd.org/doc/doxygen/bugs.html You should see version: 0.10.0 .",
- "title": "Installing OpenOCD on Mac OS"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-openocd-on-linux",
- "text": "Step 1: Download the binary tarball for Linux Step 2: Change to the root directory: $cd / \nStep 3: Untar the tarball and install into /usr/local/bin . You will need to replace ~/Downloads with the directory that the tarball is downloaded to. Note: You must specify the -p option for the tar command. $sudo tar -xpf ~/Downloads/openocd-bin-0.10.0-Linux.tgz \nStep 4: Check the OpenOCD version you are using: $which openocd\n/usr/local/bin/openocd\n$openocd -v\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\nhttp://openocd.org/doc/doxygen/bugs.html You should see version: 0.10.0 . If you see any of these error messages: openocd: error while loading shared libraries: libhidapi-hidraw.so.0: cannot open shared object file: No such file or directory openocd: error while loading shared libraries: libusb-1.0.so.0: cannot open shared object file: No such file or directory run the following command to install the libraries: $sudo apt-get install libhidapi-dev:i386",
- "title": "Installing OpenOCD on Linux"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-openocd-on-windows",
- "text": "Step 1: Download the binary zip file for Windows . Step 2: Extract into the C:\\openocd-0.10.0 folder. Step 3: Add the path: C:\\openocd-0.10.0\\bin to your Windows User Path environment variable. Note: You must add bin to the path. Step 4: Check the OpenOCD version you are using. Open a new MinGW terminal and run the following commands: Note: You must start a new MinGW terminal to inherit the new Path values. $which openocd\n/c/openocd-0.10.0/bin/openocd\n$openocd -v\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\n http://openocd.org/doc/doxygen/bugs.html You should see version: 0.10.0 .",
- "title": "Installing OpenOCD on Windows"
- },
- {
- "location": "/os/get_started/cross_tools/#installing-seggar-j-link",
- "text": "You can download and install Segger J-LINK Software and documentation pack from SEGGER . Note: On Windows, perform the following after the installation: Add the installation destination folder path to your Windows user Path environment variable. You do not need to add bin to the path. Open a new MinGW terminal to inherit the new Path values.",
- "title": "Installing SEGGAR J-Link"
- },
- {
- "location": "/os/get_started/docker/",
- "text": "Everything You Need in a Docker Container\n\n\nDocker provides a quick and easy way to get up and running with Mynewt. The\nnewt command line tool and the entire build toolchain is available in a single\ndocker container. The container is all that's needed to run your Mynewt based\napplication in the simulator. Enabling USB2 with your docker installation will\nallow you to load your application on a supported device.\n\n\nDocker 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.\n\n\n\n\nInstall Docker\n\n\nInstall docker for your platform. \nMac OS X\n / \nWindows\n / \nLinux\n\n\nMac and Windows\n\n\nMac and Windows require Docker Toolbox to interact with USB devices. Docker\nfor Mac and Docker for Windows do not support USB. Docker Toolbox uses\nVirtualBox and allows you to map USB devices into docker containers as\ndescribed below.\n\n\nMake sure to double click the Docker Quickstart Terminal application if you're\non Mac or Windows.\n\n\nLinux\n\n\nThe docker daemon listens on a Unix domain socket on Linux. That socket is\nowned by root, which means by default you must be root to start a container.\nMake sure to follow the optional step of adding yourself to the docker group so\nyou can start the newt container as yourself.\n\n\n\n\nUse the newt wrapper script\n\n\nUse the newt wrapper script to invoke newt. Create the following file, name it\n\nnewt\n, 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.\n\n\n#!/bin/bash\n\n\n\nif\n \n[\n \n$1\n \n=\n \ndebug\n \n]\n \n||\n \n[\n \n$1\n \n=\n \nrun\n \n]\n\n\nthen\n\n \nti=\n-ti\n\n\nfi\n\n\ndocker run -e \nNEWT_USER=\n$(\nid -u\n)\n -e \nNEWT_GROUP=\n$(\nid -g\n)\n -e \nNEWT_HOST=\n$(\nuname\n)\n \n$ti\n --rm --device\n=\n/dev/bus/usb --privileged -v \n$(pwd)\n:/workspace -w /workspace mynewt/newt:latest /newt \n$@\n\n\n\n\n\n\n\n\nNote 1:\n Remember to point to the correct subdirectory level when invoking \nnewt\n. For example, invoke it using \n../newt\n in the example below.\n\n\nuser@~/dockertest$ ls\nmyproj newt\nuser@~/dockertest$ cd myproj\n\nuser@~/dockertest/myproj$ ../newt version\n\nApache Newt (incubating) version: 0.8.0-b2\n\n\n\n\n\n\n\nNote 2:\n You can upgrade your container by running \ndocker pull mynewt/newt:latest\n when updates are made available.\n\n\n\n\nEnable USB2 Support for Mac or Windows\n\n\nIf you plan on loading your application on an actual device, do the steps below.\n\n\n\n\nInstall VirtualBox extension pack\n\n\nDocker uses a VirtualBox Linux VM to run containers. A free VirtualBox\nextension pack is required to enable USB2 support. Download the \nVirtualBox\n5.0.16 Oracle VM VirtualBox Extension\nPack\n\nand double click to install\n\n\n\n\nEnable USB2 and select your device\n\n\n\n\n\n\nThe \"default\" VM created by docker-machine must first be stopped before you\n can enable USB2. You have two options:\n\n\n\n\nRun the command \ndocker-machine stop default\n in the terminal window or\n\n\nUse the VirtualBox UI. Right click on \ndefault\n -\n Close -\n Power Off\n\n\n\n\n\n\n\n\nEnable USB2 using the VirtualBox UI. Select the \"default\"\n VM-\nSettings-\nPorts-\nUSB2 to enable USB2. Add your device to the USB Device\n Filters to make the device visible in the docker container. See the image below.\n\n\n\n\n\n\n\n\n\n\nRestart the \"default\" VM. You have two options:\n\n\nRun \ndocker-machine start default\n in the terminal window or \n\n\nUse the VirtualBox UI. Make sure the \"default\" machine is highlighted. Click the green \"Start\" button. Select \"Headless Start\".\n\n\n\n\n\n\n\n\n\n\nNote 3\n: 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 \nError: unable to find CMSIS-DAP device\n 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.",
- "title": "Docker Container Option"
- },
- {
- "location": "/os/get_started/docker/#everything-you-need-in-a-docker-container",
- "text": "Docker provides a quick and easy way to get up and running with Mynewt. The\nnewt command line tool and the entire build toolchain is available in a single\ndocker container. The container is all that's needed to run your Mynewt based\napplication in the simulator. Enabling USB2 with your docker installation will\nallow you to load your application on a supported device. 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.",
- "title": "Everything You Need in a Docker Container"
- },
- {
- "location": "/os/get_started/docker/#install-docker",
- "text": "Install docker for your platform. Mac OS X / Windows / Linux",
- "title": "Install Docker"
- },
- {
- "location": "/os/get_started/docker/#mac-and-windows",
- "text": "Mac and Windows require Docker Toolbox to interact with USB devices. Docker\nfor Mac and Docker for Windows do not support USB. Docker Toolbox uses\nVirtualBox and allows you to map USB devices into docker containers as\ndescribed below. Make sure to double click the Docker Quickstart Terminal application if you're\non Mac or Windows.",
- "title": "Mac and Windows"
- },
- {
- "location": "/os/get_started/docker/#linux",
- "text": "The docker daemon listens on a Unix domain socket on Linux. That socket is\nowned by root, which means by default you must be root to start a container.\nMake sure to follow the optional step of adding yourself to the docker group so\nyou can start the newt container as yourself.",
- "title": "Linux"
- },
- {
- "location": "/os/get_started/docker/#use-the-newt-wrapper-script",
- "text": "Use the newt wrapper script to invoke newt. Create the following file, name it newt , 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. #!/bin/bash if [ $1 = debug ] || [ $1 = run ] then \n ti= -ti fi \n\ndocker run -e NEWT_USER= $( id -u ) -e NEWT_GROUP= $( id -g ) -e NEWT_HOST= $( uname ) $ti --rm --device = /dev/bus/usb --privileged -v $(pwd) :/workspace -w /workspace mynewt/newt:latest /newt $@ Note 1: Remember to point to the correct subdirectory level when invoking newt . For example, invoke it using ../newt in the example below. user@~/dockertest$ ls\nmyproj newt\nuser@~/dockertest$ cd myproj user@~/dockertest/myproj$ ../newt version Apache Newt (incubating) version: 0.8.0-b2 Note 2: You can upgrade your container by running docker pull mynewt/newt:latest when updates are made available.",
- "title": "Use the newt wrapper script"
- },
- {
- "location": "/os/get_started/docker/#enable-usb2-support-for-mac-or-windows",
- "text": "If you plan on loading your application on an actual device, do the steps below.",
- "title": "Enable USB2 Support for Mac or Windows"
- },
- {
- "location": "/os/get_started/docker/#install-virtualbox-extension-pack",
- "text": "Docker uses a VirtualBox Linux VM to run containers. A free VirtualBox\nextension pack is required to enable USB2 support. Download the VirtualBox\n5.0.16 Oracle VM VirtualBox Extension\nPack \nand double click to install",
- "title": "Install VirtualBox extension pack"
- },
- {
- "location": "/os/get_started/docker/#enable-usb2-and-select-your-device",
- "text": "The \"default\" VM created by docker-machine must first be stopped before you\n can enable USB2. You have two options: Run the command docker-machine stop default in the terminal window or Use the VirtualBox UI. Right click on default - Close - Power Off Enable USB2 using the VirtualBox UI. Select the \"default\"\n VM- Settings- Ports- USB2 to enable USB2. Add your device to the USB Device\n Filters to make the device visible in the docker container. See the image below. Restart the \"default\" VM. You have two options: Run docker-machine start default in the terminal window or Use the VirtualBox UI. Make sure the \"default\" machine is highlighted. Click the green \"Start\" button. Select \"Headless Start\". Note 3 : 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 Error: unable to find CMSIS-DAP device 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.",
- "title": "Enable USB2 and select your device"
- },
- {
- "location": "/os/get_started/project_create/",
- "text": "Creating Your First Mynewt Project\n\n\nThis page shows you how to create a Mynewt project using the \nnewt\n command-line tool. The project is a blinky application that toggles a pin. The application uses the Mynewt's simulated hardware and runs as a native application on Mac OS and Linux. \n\n\nNote:\n The Mynewt simulator is not yet supported on Windows. If you are using the native install option (not the Docker option), you will need to create the blinky application for a target board. We recommend that you read the section on creating a new project and fetching the source repository to understand the Mynewt repository structure, create a new project, and fetch the source dependencies before proceeding to one of the \nBlinky Tutorials\n. \n\n\nThis guide shows you how to:\n\n\n\n\nCreate a new project and fetch the source repository and dependecies.\n\n\nTest the project packages. (Not supported on Windows.)\n\n\nBuild and run the simulated blinky application. (Not supported on Windows.) \n\n\n\n\nNote:\n The apache-mynewt-core Git repository location has changed due to Mynewt's graduation from an incubator project to an Apache top level project. The HTTP redirect to the new location may fail and you may get the following error when you run the \nnewt install\n step in this tutorial:\n\n\nReadDesc: No matching branch for apache-mynewt-core repo\nError: No matching branch for apache-mynewt-core repo\n\n\n\n\n\nTo avoid this error, you must edit the \nproject.yml\n file and change the line \nrepo: incubator-mynewt-core\n as shown in the following example to \nrepo: mynewt-core\n:\n\n\n\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n\n repo: incubator-mynewt-core\n\n\n\n\n\n\n\nPrerequisites\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nInstall the newt tool: \n\n\nIf you have taken the native install option, see the installation instructions for \nMac OS\n, \nLinux\n, or \nWindows\n. \n\n\nIf you have taken the Docker option, you have already installed Newt.\n\n\n\n\n\n\nInstall the \nnative toolchain\n to compile and build a Mynewt native application. \n\n\n\n\n\n\nCreating a New Project and Fetching the Source Repository\n\n\nThis section describes how to use the newt tool to create a new project and fetch the core mynewt source repository.\n\n\n\n\nCreating a New Project\n\n\nChoose a name for your project. We name the project \nmyproj\n. \n\n\n\nRun the \nnewt new myproj\n command, from your \ndev\n directory, to create a new project:\n\n\nNote:\n This tutorial assumes you created a \ndev\n directory under your home directory. \n\n\n$cd ~/dev\n$ newt new myproj\nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in myproj...\nProject myproj successfully created.\n\n\n\n\n\n\n\nThe newt tool creates a project base directory name \nmyproj\n. All newt tool commands are run from the project base directory. The newt tool populates this new project with a base skeleton of a new Apache Mynewt project in the project base directory. It has the following structure: \n\n\nNote\n: If you do not have \ntree\n, run \nbrew install tree\n to install on Mac OS, \nsudo apt-get install tree\n to install on Linux, and \npacman -Su tree\n from a MinGW terminal to install on Windows.\n\n\n$ cd myproj\n$ tree \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.yml\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 11 files\n\n\n\n\n\n\n\nThe newt tool installs the following files for a project in the project base directory:\n\n\n\n\nThe file \nproject.yml\n contains the repository list that the project uses to fetch\nits packages. Your project is a collection of repositories. In this case, the project only \ncomprises the core mynewt repository. Later, you will add more repositories to include other mynewt components.\n\n\nThe file \napps/blinky/pkg.yml\n contains the description of your application and its package dependencies.\n\n\nA \ntarget\n directory that contains the \nmy_blinky_sim\n directory. The \nmy_blinky_sim\n directory \na target information to build a version of myproj. Use \nnewt target show\n to see available build \ntargets.\n\n\nA non-buildable target called \nunittest\n. This is used internally by \nnewt\n and is not a formal build target.\n\n\n\n\nNote:\n The actual code and package files are not installed (except the template for \nmain.c\n). See the next step to install the packages.\n\n\n\n\nFetching the Mynewt Source Repository and Dependencies\n\n\nBy default, Mynewt projects rely on a single repository: \napache-mynewt-core\n and uses the source in the master branch. If you need to use a different branch, you need to change the \nvers\n value in the project.yml file: \n\n\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: mynewt-core\n\n\n\n\n\nChanging vers to 0-dev will put you on the latest master branch. \nThis branch may not be stable and you may encounter bugs or other problems.\n\n\nNote:\n On Windows platforms, you will need to change vers to 0-dev and use the latest master branch. Release 1.0.0 is not supported on Windows.\n\n\n\nRun the \nnewt install\n command, from your project base directory (myproj), to fetch the source repository and dependencies: \n\n\n$ newt install\napache-mynewt-core\n\n\n\n\n\nNote:\n It may take a while to download the apache-mynewt-core reposistory. Use the \n-v\n (verbose) option to see the installation progress.\n\n\n\nNote:\n As mentioned in the beginning of this tutorial, if you get the following error: \n\n\nReadDesc: No matching branch for apache-mynewt-core repo\nError: No matching branch for apache-mynewt-core repo\n\n\n\n\n\nYou must edit the \nproject.yml\n file and change the line \nrepo: incubator-mynewt-core\n to \nrepo: mynewt-core\n.\n\n\n\n\nView the core of the Apache Mynewt OS that is downloaded into your local directory. \n\n\n(The actual output will depend on what is in the latest 'master' branch)\n\n\n$ tree -L 2 repos/apache-mynewt-core/\n\nrepos/apache-mynewt-core/\n\u251c\u2500\u2500 CODING_STANDARDS.md\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 RELEASE_NOTES.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blecent\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blehci\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph_oic\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blesplit\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bletest\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bletiny\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bleuart\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 boot\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fat2native\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ffs2native\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ocf_sample\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 slinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 slinky_oic\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 spitest\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 splitty\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 testbench\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 timtest\n\u251c\u2500\u2500 boot\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 boot_serial\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bootutil\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 split\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 split_app\n\u251c\u2500\u2500 compiler\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 arm-none-eabi-m0\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 arm-none-eabi-m4\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 gdbmacros\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mips\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 sim\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 sim-mips\n\u251c\u2500\u2500 crypto\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mbedtls\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 tinycrypt\n\u251c\u2500\u2500 docs\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 doxygen.xml\n\u251c\u2500\u2500 encoding\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 base64\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 cborattr\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 json\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 tinycbor\n\u251c\u2500\u2500 fs\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 disk\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fatfs\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fcb\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fs\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 nffs\n\u251c\u2500\u2500 hw\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 cmsis-core\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 drivers\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 hal\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mcu\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 scripts\n\u251c\u2500\u2500 kernel\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n\u251c\u2500\u2500 libc\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 baselibc\n\u251c\u2500\u2500 mgmt\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 imgmgr\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mgmt\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 newtmgr\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 oicmgr\n\u251c\u2500\u2500 net\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ip\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 nimble\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 oic\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 wifi\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repository.yml\n\u251c\u2500\u2500 sys\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 config\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 console\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 coredump\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 defs\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 flash_map\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 id\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 log\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mfg\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 reboot\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 shell\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 stats\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 sysinit\n\u251c\u2500\u2500 targets\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 unittest\n\u251c\u2500\u2500 test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 crash_test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 flash_test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 runtest\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 testutil\n\u251c\u2500\u2500 time\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime\n\u2514\u2500\u2500 util\n \u251c\u2500\u2500 cbmem\n \u251c\u2500\u2500 crc\n \u2514\u2500\u2500 mem\n\n94 directories, 9 files\n\n\n\n\n\n\n\nTesting the Project Packages\n\n\nNote\n: This is not yet supported on Windows.\n\n\nYou can use the newt tool to execute the unit tests in a package. For example, run the following command to test the \nsys/config\n package in the \napache-mynewt-core\n repo: \n\n\n$ newt test @apache-mynewt-core/sys/config\nTesting package @apache-mynewt-core/sys/config/test-fcb\nCompiling bootutil_misc.c\nCompiling image_ec.c\nCompiling image_rsa.c\nCompiling image_validate.c\n\n ...\n\nLinking ~/dev/myproj/bin/targets/unittest/sys_config_test-fcb/app/sys/config/test-fcb/sys_config_test-fcb.elf\nExecuting test: ~/dev/myproj/bin/targets/unittest/sys_config_test-fcb/app/sys/config/test-fcb/sys_config_test-fcb.elf\nTesting package @apache-mynewt-core/sys/config/test-nffs\nCompiling repos/apache-mynewt-core/encoding/base64/src/hex.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_cli.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_dirent.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_mkdir.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_mount.c\nCompiling repos/apache-mynewt-core/encoding/base64/src/base64.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_file.c\nCompiling repos/apache-mynewt-core/fs/disk/src/disk.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_nmgr.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fsutil.c\nCompiling repos/apache-mynewt-core/fs/nffs/src/nffs.c\n\n ...\n\nLinking ~/dev/myproj/bin/targets/unittest/sys_config_test-nffs/app/sys/config/test-nffs/sys_config_test-nffs.elf\nExecuting test: ~/dev/myproj/bin/targets/unittest/sys_config_test-nffs/app/sys/config/test-nffs/sys_config_test-nffs.elf\nPassed tests: [sys/config/test-fcb sys/config/test-nffs]\nAll tests passed\n\n\n\n\n\nNote:\n If you installed the latest gcc using homebrew on your Mac, you are probably running gcc-6. Make sure you change the compiler.yml configuration to specify that you are using gcc-6 (See \nNative Install Option\n). You can also downgrade your installation to gcc-5 and use the default gcc compiler configuration for MyNewt:\n\n\n$ brew uninstall gcc-6\n$ brew link gcc-5\n\n\n\n\n\nNote:\n If you are running the standard gcc for 64-bit machines, it does not support 32-bit. In that case you will see compilation errors. You need to install multilib gcc (e.g. gcc-multilib if you running on a 64-bit Ubuntu).\n\n\n\n\nTo test all the packages in a project, specify \nall\n instead of the package name.\n\n\n$ newt test all\nTesting package @apache-mynewt-core/boot/boot_serial/test\nCompiling repos/apache-mynewt-core/boot/boot_serial/test/src/boot_test.c\nCompiling repos/apache-mynewt-core/boot/boot_serial/test/src/testcases/boot_serial_setup.c\n\n ...\n\nLinking ~/dev/myproj/bin/targets/unittest/boot_boot_serial_test/app/boot/boot_serial/test/boot_boot_serial_test.elf\n\n...lots of compiling and testing...\n\nLinking ~/dev/myproj/bin/targets/unittest/util_cbmem_test/app/util/cbmem/test/util_cbmem_test.elf\nExecuting test: ~/dev/myproj/bin/targets/unittest/util_cbmem_test/app/util/cbmem/test/util_cbmem_test.elf\nPassed tests: [boot/boot_serial/test boot/bootutil/test crypto/mbedtls/test encoding/base64/test encoding/cborattr/test encoding/json/test fs/fcb/test fs/nffs/test kernel/os/test net/ip/mn_socket/test net/nimble/host/test net/oic/test sys/config/test-fcb sys/config/test-nffs sys/flash_map/test sys/log/full/test util/cbmem/test]\nAll tests passed\n\n\n\n\n\n\n\nBuilding and Running the Simulated Blinky Application\n\n\nThe section shows you how to build and run the blinky application to run on Mynewt's simulated hardware.\n\n\nNote\n: This is not yet supported on Windows. Refer to the \nBlinky Tutorials\n to create a blinky application for a target board.\n\n\n\n\nBuilding the Application\n\n\nTo build the simulated blinky application, run \nnewt build my_blinky_sim\n:\n\n\n$ newt build my_blinky_sim \nBuilding target targets/my_blinky_sim\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\nCompiling repos/apache-mynewt-core/hw/bsp/native/src/hal_bsp.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nCompiling apps/blinky/src/main.c\n\n ...\n\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf\nTarget successfully built: targets/my_blinky_sim\n\n\n\n\n\n\n\nRunning the Blinky Application\n\n\nYou can run the simulated version of your project and see the simulated LED blink. \n\n\nIf you natively install the toolchain execute the binary directly:\n\n\n$ ./bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf\nhal_gpio set pin 1 to 0\n\n\n\n\n\n\nIf you are using newt docker, use \nnewt run\n to run the simulated binary.\n\n\n$ newt run my_blinky_sim\nLoading app image into slot 1\n ...\nDebugging ~/dev/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf\n ...\nReading symbols from /bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf...done.\n(gdb)\n\n\n\n\n\nType \nr\n at the \n(gdb)\n prompt to run the project. You will see an output indicating that the hal_gpio pin is toggling between 1 and 0 in a simulated blink.\n\n\n\n\nExploring other Mynewt OS Features\n\n\nCongratulations, you have created your first project! The blinky application\nis not terribly exciting when it is run in the simulator, as there is no LED to\nblink. Apache Mynewt has a lot more functionality than just running simulated\napplications. It provides all the features you'll need to cross-compile your\napplication, run it on real hardware and develop a full featured application.\n\n\nIf you're interested in learning more, a good next step is to dig in to one of\nthe \ntutorials\n and get a Mynewt project running on real hardware.\n\n\nHappy Hacking!",
- "title": "Create Your First Project"
- },
- {
- "location": "/os/get_started/project_create/#creating-your-first-mynewt-project",
- "text": "This page shows you how to create a Mynewt project using the newt command-line tool. The project is a blinky application that toggles a pin. The application uses the Mynewt's simulated hardware and runs as a native application on Mac OS and Linux. Note: The Mynewt simulator is not yet supported on Windows. If you are using the native install option (not the Docker option), you will need to create the blinky application for a target board. We recommend that you read the section on creating a new project and fetching the source repository to understand the Mynewt repository structure, create a new project, and fetch the source dependencies before proceeding to one of the Blinky Tutorials . This guide shows you how to: Create a new project and fetch the source repository and dependecies. Test the project packages. (Not supported on Windows.) Build and run the simulated blinky application. (Not supported on Windows.) Note: The apache-mynewt-core Git repository location has changed due to Mynewt's graduation from an incubator project to an Apache top level project. The HTTP redirect to the new location may fail and you may get the following error when you run the newt install step in this tutorial: ReadDesc: No matching branch for apache-mynewt-core repo\nError: No matching branch for apache-mynewt-core repo To avoid this error, you must edit the project.yml file and change the line repo: incubator-mynewt-core as shown in the following example to repo: mynewt-core : repository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache repo: incubator-mynewt-core",
- "title": "Creating Your First Mynewt Project"
- },
- {
- "location": "/os/get_started/project_create/#prerequisites",
- "text": "Have Internet connectivity to fetch remote Mynewt components. Install the newt tool: If you have taken the native install option, see the installation instructions for Mac OS , Linux , or Windows . If you have taken the Docker option, you have already installed Newt. Install the native toolchain to compile and build a Mynewt native application.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/get_started/project_create/#creating-a-new-project-and-fetching-the-source-repository",
- "text": "This section describes how to use the newt tool to create a new project and fetch the core mynewt source repository.",
- "title": "Creating a New Project and Fetching the Source Repository"
- },
- {
- "location": "/os/get_started/project_create/#creating-a-new-project",
- "text": "Choose a name for your project. We name the project myproj . \nRun the newt new myproj command, from your dev directory, to create a new project: Note: This tutorial assumes you created a dev directory under your home directory. $cd ~/dev\n$ newt new myproj\nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in myproj...\nProject myproj successfully created. The newt tool creates a project base directory name myproj . All newt tool commands are run from the project base directory. The newt tool populates this new project with a base skeleton of a new Apache Mynewt project in the project base directory. It has the following structure: Note : If you do not have tree , run brew install tree to install on Mac OS, sudo apt-get install tree to install on Linux, and pacman -Su tree from a MinGW terminal to install on Windows. $ cd myproj\n$ tree \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.yml\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 11 files The newt tool installs the following files for a project in the project base directory: The file project.yml contains the repository list that the project uses to fetch\nits packages. Your project is a collection of repositories. In this case, the project only \ncomprises the core mynewt repository. Later, you will add more repositories to include other mynewt components. The file apps/blinky/pkg.yml contains the description of your application and its package dependencies. A target directory that contains the my_blinky_sim directory. The my_blinky_sim directory \na target information to build a version of myproj. Use newt target show to see available build \ntargets. A non-buildable target called unittest . This is used internally by newt and is not a formal build target. Note: The actual code and package files are not installed (except the template for main.c ). See the next step to install the packages.",
- "title": "Creating a New Project"
- },
- {
- "location": "/os/get_started/project_create/#fetching-the-mynewt-source-repository-and-dependencies",
- "text": "By default, Mynewt projects rely on a single repository: apache-mynewt-core and uses the source in the master branch. If you need to use a different branch, you need to change the vers value in the project.yml file: repository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: mynewt-core Changing vers to 0-dev will put you on the latest master branch. This branch may not be stable and you may encounter bugs or other problems. Note: On Windows platforms, you will need to change vers to 0-dev and use the latest master branch. Release 1.0.0 is not supported on Windows. \nRun the newt install command, from your project base directory (myproj), to fetch the source repository and dependencies: $ newt install\napache-mynewt-core Note: It may take a while to download the apache-mynewt-core reposistory. Use the -v (verbose) option to see the installation progress. Note: As mentioned in the beginning of this tutorial, if you get the following error: ReadDesc: No matching branch for apache-mynewt-core repo\nError: No matching branch for apache-mynewt-core repo You must edit the project.yml file and change the line repo: incubator-mynewt-core to repo: mynewt-core . View the core of the Apache Mynewt OS that is downloaded into your local directory. (The actual output will depend on what is in the latest 'master' branch) $ tree -L 2 repos/apache-mynewt-core/\n\nrepos/apache-mynewt-core/\n\u251c\u2500\u2500 CODING_STANDARDS.md\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 RELEASE_NOTES.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blecent\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blehci\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bleprph_oic\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blesplit\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bletest\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bletiny\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bleuart\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 boot\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fat2native\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ffs2native\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ocf_sample\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 slinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 slinky_oic\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 spitest\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 splitty\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 testbench\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 timtest\n\u251c\u2500\u2500 boot\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 boot_serial\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bootutil\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 split\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 split_app\n\u251c\u2500\u2500 compiler\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 arm-none-eabi-m0\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 arm-none-eabi-m4\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 gdbmacros\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mips\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 sim\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 sim-mips\n\u251c\u2500\u2500 crypto\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mbedtls\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 tinycrypt\n\u251c\u2500\u2500 docs\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 doxygen.xml\n\u251c\u2500\u2500 encoding\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 base64\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 cborattr\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 json\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 tinycbor\n\u251c\u2500\u2500 fs\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 disk\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fatfs\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fcb\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fs\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 nffs\n\u251c\u2500\u2500 hw\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 cmsis-core\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 drivers\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 hal\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mcu\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 scripts\n\u251c\u2500\u2500 kernel\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n\u251c\u2500\u2500 libc\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 baselibc\n\u251c\u2500\u2500 mgmt\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 imgmgr\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mgmt\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 newtmgr\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 oicmgr\n\u251c\u2500\u2500 net\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 ip\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 nimble\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 oic\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 wifi\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repository.yml\n\u251c\u2500\u2500 sys\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 config\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 console\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 coredump\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 defs\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 flash_map\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 id\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 log\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 mfg\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 reboot\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 shell\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 stats\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 sysinit\n\u251c\u2500\u2500 targets\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 unittest\n\u251c\u2500\u2500 test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 crash_test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 flash_test\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 runtest\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 testutil\n\u251c\u2500\u2500 time\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime\n\u2514\u2500\u2500 util\n \u251c\u2500\u2500 cbmem\n \u251c\u2500\u2500 crc\n \u2514\u2500\u2500 mem\n\n94 directories, 9 files",
- "title": "Fetching the Mynewt Source Repository and Dependencies"
- },
- {
- "location": "/os/get_started/project_create/#testing-the-project-packages",
- "text": "Note : This is not yet supported on Windows. You can use the newt tool to execute the unit tests in a package. For example, run the following command to test the sys/config package in the apache-mynewt-core repo: $ newt test @apache-mynewt-core/sys/config\nTesting package @apache-mynewt-core/sys/config/test-fcb\nCompiling bootutil_misc.c\nCompiling image_ec.c\nCompiling image_rsa.c\nCompiling image_validate.c\n\n ...\n\nLinking ~/dev/myproj/bin/targets/unittest/sys_config_test-fcb/app/sys/config/test-fcb/sys_config_test-fcb.elf\nExecuting test: ~/dev/myproj/bin/targets/unittest/sys_config_test-fcb/app/sys/config/test-fcb/sys_config_test-fcb.elf\nTesting package @apache-mynewt-core/sys/config/test-nffs\nCompiling repos/apache-mynewt-core/encoding/base64/src/hex.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_cli.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_dirent.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_mkdir.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_mount.c\nCompiling repos/apache-mynewt-core/encoding/base64/src/base64.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_file.c\nCompiling repos/apache-mynewt-core/fs/disk/src/disk.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fs_nmgr.c\nCompiling repos/apache-mynewt-core/fs/fs/src/fsutil.c\nCompiling repos/apache-mynewt-core/fs/nffs/src/nffs.c\n\n ...\n\nLinking ~/dev/myproj/bin/targets/unittest/sys_config_test-nffs/app/sys/config/test-nffs/sys_config_test-nffs.elf\nExecuting test: ~/dev/myproj/bin/targets/unittest/sys_config_test-nffs/app/sys/config/test-nffs/sys_config_test-nffs.elf\nPassed tests: [sys/config/test-fcb sys/config/test-nffs]\nAll tests passed Note: If you installed the latest gcc using homebrew on your Mac, you are probably running gcc-6. Make sure you change the compiler.yml configuration to specify that you are using gcc-6 (See Native Install Option ). You can also downgrade your installation to gcc-5 and use the default gcc compiler configuration for MyNewt: $ brew uninstall gcc-6\n$ brew link gcc-5 Note: If you are running the standard gcc for 64-bit machines, it does not support 32-bit. In that case you will see compilation errors. You need to install multilib gcc (e.g. gcc-multilib if you running on a 64-bit Ubuntu). To test all the packages in a project, specify all instead of the package name. $ newt test all\nTesting package @apache-mynewt-core/boot/boot_serial/test\nCompiling repos/apache-mynewt-core/boot/boot_serial/test/src/boot_test.c\nCompiling repos/apache-mynewt-core/boot/boot_serial/test/src/testcases/boot_serial_setup.c\n\n ...\n\nLinking ~/dev/myproj/bin/targets/unittest/boot_boot_serial_test/app/boot/boot_serial/test/boot_boot_serial_test.elf\n\n...lots of compiling and testing...\n\nLinking ~/dev/myproj/bin/targets/unittest/util_cbmem_test/app/util/cbmem/test/util_cbmem_test.elf\nExecuting test: ~/dev/myproj/bin/targets/unittest/util_cbmem_test/app/util/cbmem/test/util_cbmem_test.elf\nPassed tests: [boot/boot_serial/test boot/bootutil/test crypto/mbedtls/test encoding/base64/test encoding/cborattr/test encoding/json/test fs/fcb/test fs/nffs/test kernel/os/test net/ip/mn_socket/test net/nimble/host/test net/oic/test sys/config/test-fcb sys/config/test-nffs sys/flash_map/test sys/log/full/test util/cbmem/test]\nAll tests passed",
- "title": "Testing the Project Packages"
- },
- {
- "location": "/os/get_started/project_create/#building-and-running-the-simulated-blinky-application",
- "text": "The section shows you how to build and run the blinky application to run on Mynewt's simulated hardware. Note : This is not yet supported on Windows. Refer to the Blinky Tutorials to create a blinky application for a target board.",
- "title": "Building and Running the Simulated Blinky Application"
- },
- {
- "location": "/os/get_started/project_create/#building-the-application",
- "text": "To build the simulated blinky application, run newt build my_blinky_sim : $ newt build my_blinky_sim \nBuilding target targets/my_blinky_sim\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\nCompiling repos/apache-mynewt-core/hw/bsp/native/src/hal_bsp.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nCompiling apps/blinky/src/main.c\n\n ...\n\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf\nTarget successfully built: targets/my_blinky_sim",
- "title": "Building the Application"
- },
- {
- "location": "/os/get_started/project_create/#running-the-blinky-application",
- "text": "You can run the simulated version of your project and see the simulated LED blink. If you natively install the toolchain execute the binary directly: $ ./bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf\nhal_gpio set pin 1 to 0 \nIf you are using newt docker, use newt run to run the simulated binary. $ newt run my_blinky_sim\nLoading app image into slot 1\n ...\nDebugging ~/dev/myproj/bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf\n ...\nReading symbols from /bin/targets/my_blinky_sim/app/apps/blinky/blinky.elf...done.\n(gdb) Type r at the (gdb) prompt to run the project. You will see an output indicating that the hal_gpio pin is toggling between 1 and 0 in a simulated blink.",
- "title": "Running the Blinky Application"
- },
- {
- "location": "/os/get_started/project_create/#exploring-other-mynewt-os-features",
- "text": "Congratulations, you have created your first project! The blinky application\nis not terribly exciting when it is run in the simulator, as there is no LED to\nblink. Apache Mynewt has a lot more functionality than just running simulated\napplications. It provides all the features you'll need to cross-compile your\napplication, run it on real hardware and develop a full featured application. If you're interested in learning more, a good next step is to dig in to one of\nthe tutorials and get a Mynewt project running on real hardware. Happy Hacking!",
- "title": "Exploring other Mynewt OS Features"
- },
- {
- "location": "/os/get_started/serial_access/",
- "text": "Using the Serial Port with Mynewt OS\n\n\nSome of the projects and tutorials here will allow you to use a serial port\nto interact with your Mynewt project. While most modern PCs and laptops\nno longer have a true serial port, almost all can use their USB ports\nas serial ports. \n\n\nThis will show you how to connect to some of the development boards\nwe use via a serial port. \n\n\nThe development boards covered here are:\n\n\n\n\nNordic Semiconductor NRF52dk\n\n\nArduino M0 Pro\n\n\n\n\nIn order to communicate with these boards you will also need a USB\n--\nSerial\nconverted. We'll be using the \nAdaFruit FT232H Breakout Board\n for\nthis, but almost any similar board should work just as well. You will also\nneed Minicom or a similar Serial communications application. We'll show you how\nto use the \nscreen\n command built in to Mac OS X, but later tutorials will\nalso show Minicom setup.\n\n\nSo let's get started!\n\n\n\n\nSetup FT232H\n\n\nThis is a great board because it's so easy to set up, and it can do Serial UART,\nSPI, I2C and GPIO as well. There's full documentation on the board \nhere\n\n but we're only covering the wiring for the Serial UART. \n\n\nStart by connecting a jumper wire to Pin D0. This will be the UART Tx pin, \nwhich we'll then connect to the Rx pin on the Development Board.\n\n\nNext connect a jumper wire to pin D1. This will be the UART Rx pin,\nwhich we'll connect to the Tx pin on the development board.\n\n\nFinally connect a jumper wire to the GND pin.\n\n\nIt should look like this:\n\n\n\n\n\n\nSetup Nordic Semiconductor NRF52DK\n\n\nOn the NRF52DK developer kit board, the Rx pin is P0.08, so you'll attach your\njumper wire from the Tx pin (D0) of the FT232H board here.\n\n\nThe TX Pin is pin P0.06, so you'll attache the jumper wire from the Rx Pin (D1)\non the FT232H board here. \n\n\nFinally, the GND wire should go to the GND Pin on the NRF52DK. When you're\ndone, your wiring should look like this:\n\n\n \n\n\n\n\nSetup Arduino M0 Pro\n\n\nOn the Arduino M0 Pro, the Tx and Rx pins are clearly labeled as such, as is the GND\npin. Just make sure you wire Rx from the FT232H to TX on the M0 Pro, and vice-versa.\n\n\nYour Arduino M0 Pro should look like this:\n\n\n\n\n\n\nSetup Serial Communications\n\n\nYou will need to know the serial port to connect to and use a terminal program to connect to the board.\n\n\nExample for Mac OS and Linux Platforms\n\n\nFirst check what USB devices are already connected before connecting the FT232H board to your computer. The ports are listed in the \n/dev\n directory and the format of the port name is platform dependent:\n\n\n\n\nMac OS uses the format \ntty.usbserial-\nsome identifier\n. \n\n\nLinux uses the format \nTTYUSB\nN\n, where \nN\n is a number. For example, TTYUSB2.\n\n\n\n\n\nThis example is run on a Mac OS system. \n\n\nCheck what USB devices are already connected:\n\n\n\n$ ls -la /dev/*usb*\n0 crw-rw-rw- 1 root wheel 20, 63 Nov 23 11:13 /dev/cu.usbmodem401322\n0 crw-rw-rw- 1 root wheel 20, 62 Nov 23 11:13 /dev/tty.usbmodem401322\n$\n\n\n\n\n\n\nPlug in the FT232H board and check the ports again:\n\n\n\n$ ls -la /dev/*usb*\n0 crw-rw-rw- 1 root wheel 20, 63 Nov 23 11:13 /dev/cu.usbmodem401322\n0 crw-rw-rw- 1 root wheel 20, 65 Nov 23 11:26 /dev/cu.usbserial-0020124\n0 crw-rw-rw- 1 root wheel 20, 62 Nov 23 11:13 /dev/tty.usbmodem401322\n0 crw-rw-rw- 1 root wheel 20, 64 Nov 23 11:26 /dev/tty.usbserial-0020124\n$\n\n\n\n\n\n\nThe FT232H is connected to \n/dev/tty.usbserial-0020124\n (The number after tty.usbserial will be different on your machine.)\n\n\nUse the screen command to connect to the board: \n\n\n\n$ screen /dev/tty.usbserial-0020124 115200\n\n\n\n\n\n\nTo exit out of \nscreen\n you'll type \ncontrol-A\n followed by \ncontrol-\\\n and you'll\nbe back to a terminal prompt.\n\n\n\n\nYou can also use minicom:\n\n\n\n$ minicom -D /dev/tty.usbserial-0020124\n\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/tty.usbserial-0020124, 09:57:17\n\nPress Meta-Z for help on special keys\n\n\n\n\n\n\nIf there's no Mynewt app running, or the Mynewt app doesn't have the Shell and Console\nenabled, you won't see anything there, but you can always refer back to this page\nfrom later tutorials if you need to.\n\n\n\n\nExample for Windows Platforms\n\n\nFirst check what USB devices are already connected before connecting the FT232H board to your computer. You can locate the ports from a MinGW terminal or use the Windows Device Manager. \n\n\nOn a MinGW terminal, the ports are listed in the /dev directory and the format of the port name is \nttyS\nN\n where N is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n.\n\n\nCheck what USB devices are already connected:\n\n\n\n$ls -l /dev/ttyS* \ncrw-rw-rw- 1 \nuser\n None 117, 5 May 9 04:24 /dev/ttyS5\n$\n\n\n\n\n\n\n/dev/ttyS5 maps to the Windows COM6 port. You can run Windows Device Manager to confirm:\n\n\n\n\n\n\n\n\nPlug in the FT232H board and check the ports again:\n\n\n\n$ls -l /dev/ttyS* \nls -l /dev/ttyS*\ncrw-rw-rw- 1 \nuser\n None 117, 10 May 9 04:55 /dev/ttyS10\ncrw-rw-rw- 1 \nuser\n None 117, 5 May 9 04:55 /dev/ttyS5\n$\n\n\n\n\n\n\nThe FT232H board is connected to port /dev/ttyS10 (or COM11):\n\n\n\n\n\n\n\n\nWe use the PuTTY terminal application to connect to the board on the COM11 port:\n\n\n\n\n\n\n\nPress Open and you should get a terminal screen titled \"COM11 - PuTTY\"\n\n\nIf there's no Mynewt app running, or the Mynewt app doesn't have the Shell and Console\nenabled, you won't see anything there, but you can always refer back to this page\nfrom later tutorials if you need to.\n\n\n\n\nNow that you know how to communicate with your mynewt application, let's move on to\ncreating one!",
- "title": "Serial Port Setup"
- },
- {
- "location": "/os/get_started/serial_access/#using-the-serial-port-with-mynewt-os",
- "text": "Some of the projects and tutorials here will allow you to use a serial port\nto interact with your Mynewt project. While most modern PCs and laptops\nno longer have a true serial port, almost all can use their USB ports\nas serial ports. This will show you how to connect to some of the development boards\nwe use via a serial port. The development boards covered here are: Nordic Semiconductor NRF52dk Arduino M0 Pro In order to communicate with these boards you will also need a USB -- Serial\nconverted. We'll be using the AdaFruit FT232H Breakout Board for\nthis, but almost any similar board should work just as well. You will also\nneed Minicom or a similar Serial communications application. We'll show you how\nto use the screen command built in to Mac OS X, but later tutorials will\nalso show Minicom setup. So let's get started!",
- "title": "Using the Serial Port with Mynewt OS"
- },
- {
- "location": "/os/get_started/serial_access/#setup-ft232h",
- "text": "This is a great board because it's so easy to set up, and it can do Serial UART,\nSPI, I2C and GPIO as well. There's full documentation on the board here \n but we're only covering the wiring for the Serial UART. Start by connecting a jumper wire to Pin D0. This will be the UART Tx pin, \nwhich we'll then connect to the Rx pin on the Development Board. Next connect a jumper wire to pin D1. This will be the UART Rx pin,\nwhich we'll connect to the Tx pin on the development board. Finally connect a jumper wire to the GND pin. It should look like this:",
- "title": "Setup FT232H"
- },
- {
- "location": "/os/get_started/serial_access/#setup-nordic-semiconductor-nrf52dk",
- "text": "On the NRF52DK developer kit board, the Rx pin is P0.08, so you'll attach your\njumper wire from the Tx pin (D0) of the FT232H board here. The TX Pin is pin P0.06, so you'll attache the jumper wire from the Rx Pin (D1)\non the FT232H board here. Finally, the GND wire should go to the GND Pin on the NRF52DK. When you're\ndone, your wiring should look like this:",
- "title": "Setup Nordic Semiconductor NRF52DK"
- },
- {
- "location": "/os/get_started/serial_access/#setup-arduino-m0-pro",
- "text": "On the Arduino M0 Pro, the Tx and Rx pins are clearly labeled as such, as is the GND\npin. Just make sure you wire Rx from the FT232H to TX on the M0 Pro, and vice-versa. Your Arduino M0 Pro should look like this:",
- "title": "Setup Arduino M0 Pro"
- },
- {
- "location": "/os/get_started/serial_access/#setup-serial-communications",
- "text": "You will need to know the serial port to connect to and use a terminal program to connect to the board.",
- "title": "Setup Serial Communications"
- },
- {
- "location": "/os/get_started/serial_access/#example-for-mac-os-and-linux-platforms",
- "text": "First check what USB devices are already connected before connecting the FT232H board to your computer. The ports are listed in the /dev directory and the format of the port name is platform dependent: Mac OS uses the format tty.usbserial- some identifier . Linux uses the format TTYUSB N , where N is a number. For example, TTYUSB2. \nThis example is run on a Mac OS system. Check what USB devices are already connected: $ ls -la /dev/*usb*\n0 crw-rw-rw- 1 root wheel 20, 63 Nov 23 11:13 /dev/cu.usbmodem401322\n0 crw-rw-rw- 1 root wheel 20, 62 Nov 23 11:13 /dev/tty.usbmodem401322\n$ \nPlug in the FT232H board and check the ports again: $ ls -la /dev/*usb*\n0 crw-rw-rw- 1 root wheel 20, 63 Nov 23 11:13 /dev/cu.usbmodem401322\n0 crw-rw-rw- 1 root wheel 20, 65 Nov 23 11:26 /dev/cu.usbserial-0020124\n0 crw-rw-rw- 1 root wheel 20, 62 Nov 23 11:13 /dev/tty.usbmodem401322\n0 crw-rw-rw- 1 root wheel 20, 64 Nov 23 11:26 /dev/tty.usbserial-0020124\n$ \nThe FT232H is connected to /dev/tty.usbserial-0020124 (The number after tty.usbserial will be different on your machine.) \nUse the screen command to connect to the board: $ screen /dev/tty.usbserial-0020124 115200 \nTo exit out of screen you'll type control-A followed by control-\\ and you'll\nbe back to a terminal prompt. You can also use minicom: $ minicom -D /dev/tty.usbserial-0020124\n\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/tty.usbserial-0020124, 09:57:17\n\nPress Meta-Z for help on special keys \nIf there's no Mynewt app running, or the Mynewt app doesn't have the Shell and Console\nenabled, you won't see anything there, but you can always refer back to this page\nfrom later tutorials if you need to.",
- "title": "Example for Mac OS and Linux Platforms"
- },
- {
- "location": "/os/get_started/serial_access/#example-for-windows-platforms",
- "text": "First check what USB devices are already connected before connecting the FT232H board to your computer. You can locate the ports from a MinGW terminal or use the Windows Device Manager. On a MinGW terminal, the ports are listed in the /dev directory and the format of the port name is ttyS N where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . Check what USB devices are already connected: $ls -l /dev/ttyS* \ncrw-rw-rw- 1 user None 117, 5 May 9 04:24 /dev/ttyS5\n$ \n/dev/ttyS5 maps to the Windows COM6 port. You can run Windows Device Manager to confirm: Plug in the FT232H board and check the ports again: $ls -l /dev/ttyS* \nls -l /dev/ttyS*\ncrw-rw-rw- 1 user None 117, 10 May 9 04:55 /dev/ttyS10\ncrw-rw-rw- 1 user None 117, 5 May 9 04:55 /dev/ttyS5\n$ \nThe FT232H board is connected to port /dev/ttyS10 (or COM11): We use the PuTTY terminal application to connect to the board on the COM11 port: Press Open and you should get a terminal screen titled \"COM11 - PuTTY\" If there's no Mynewt app running, or the Mynewt app doesn't have the Shell and Console\nenabled, you won't see anything there, but you can always refer back to this page\nfrom later tutorials if you need to. Now that you know how to communicate with your mynewt application, let's move on to\ncreating one!",
- "title": "Example for Windows Platforms"
- },
- {
- "location": "/os/get_started/vocabulary/",
- "text": "Concepts\n\n\nThis page is meant to introduce you to some of the concepts inherent to \nthe Apache Mynewt Operating System, and \nNewt\n the tool that stitches a \nproject built on Apache Mynewt together.\n\n\nProject\n\n\nThe project is the base directory of your embedded software tree. It is a \nworkspace that contains a logical collection of source code, for one or \nmore of your applications. A project consists of the following items:\n\n\n\n\nProject Definition: defines project level dependencies, and parameters\n (located in \nproject.yml\n)\n\n\nPackages\n\n\n\n\nPackages\n are described in detail in the section below. \n\n\nHere is an example project definition file from the default Apache Mynewt \nproject: \n\n\n$ more project.yml \n\nsnip\n\nproject.name: \nmy_project\n\n\nproject.repositories:\n - apache-mynewt-core\n\n# Use github\ns distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n$ \n\n\n\n\n\nA couple of things to note in the project definition:\n\n\n\n\n\n\nproject.repositories\n: Defines the remote repositories that this project\nrelies upon.\n\n\n\n\n\n\nrepository.apache-mynewt-core\n: Defines the repository information for \nthe \napache-mynewt-core\n repository.\n\n\n\n\n\n\nvers=1-latest\n: Defines the repository version. This string will use the \nlatest stable version in the 'Master' github branch. To use the latest version in the \nmaster branch, just change it to \nvers=0-dev\n. Note that this branch might not be stable. \n\n\n\n\n\n\nRepositories are versioned collections of packages. \n\n\nProjects can rely on remote repositories for functionality, and the newt tool \nwill resolve those remote repositories, and download the correct version into \nyour local source tree. Newly fetched repositories are put in the \nrepos\n\ndirectory of your project, and can be referenced throughout the system by using\nthe \n@\n specifier. \n\n\nBy default, the \n@apache-mynewt-core\n repository is included in every \nproject. Apache Mynewt Core contains all the base functionality of the Apache \nMynewt Operating System, including the Real Time Kernel, Bluetooth Networking \nStack, Flash File System, Console, Shell and Bootloader.\n\n\nNOTE:\n Any project can be converted into a repository by providing it with a \n\nrepository.yml\n file and putting it up onto Github. More information\nabout repositories can be found in the Newt documentation.\n\n\nPackage\n\n\nA package is a collection items that form a fundamental unit in the Mynewt \nOperating System. Packages can be:\n\n\n\n\nApplications\n\n\nLibraries\n\n\nCompiler definitions\n\n\nTargets\n\n\n\n\nA package is identified by having a \npkg.yml\n file in it's base \ndirectory. Here is a sample \npkg.yml\n file for the blinky applicaton:\n\n\n$ more pkg.yml \n\nsnip\n\npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps:\n - \n@apache-mynewt-core/libs/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/libs/console/full\n\n\n\n\n\n\nPackages have a few features worth noting:\n\n\n\n\nDependencies: Packages can rely upon other packages, and when they do\n they will inherit their functionality (header files, library definitions, etc.)\n\n\nAPIs: Packages can export named APIs, and they can require that certain \n APIs be present, in order to compile.\n\n\n\n\nEverything that newt knows about within a project's directory is a package. This \nmakes it very clean and easy to write re-usable components, which can describe their \nDependencies and APIs to the rest of the system.\n\n\nTarget\n\n\nA target in Apache Mynewt is very similar to a target in \nmake\n. It is the collection\nof parameters that must be passed to Newt in order to generate a reproducible build. A \ntarget represents the top of the build tree, and any packages or parameters specified at \nthe target level, cascade down to all dependencies.\n\n\nTargets are also packages, and are stored in the \ntargets/\n directory at the base \nof your project. Most targets consist of: \n\n\n\n\napp\n: The application to build.\n\n\nbsp\n: The board support package to combine with that application\n\n\nbuild_profile\n: Either \ndebug\n or \noptimized\n. \n\n\n\n\nTargets can also have additional items specified, including: \n\n\n\n\naflags\n: Any additional assembler flags you might want to specify to the build.\n\n\ncflags\n: Any additional compiler flags you might want to specify to the build.\n\n\nlflags\n: Any additional linker flags you might want to specify to the build.\n\n\n\n\nIn order to create and manipulate targets, the \nnewt\n tool offers a set of helper commands,\nyou can find more information about these by issuing:\n\n\n$ newt target\n\n\nnewt target\nUsage:\n newt target [flags]\n newt target [command]\n\nAvailable Commands:\n config View or populate a target\ns system configuration\n copy Copy target\n create Create a target\n delete Delete target\n dep View target\ns dependency graph\n revdep View target\ns reverse-dependency graph\n set Set target configuration variable\n show View target configuration variables\n\nGlobal Flags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse \nnewt target [command] --help\n for more information about a command.\n\n$ \n\n\n\n\n\nConfiguration\n\n\nThere are a lot of configuration options available when building your application in MyNewt. System Configuration options are set in \na file called \nsyscfg.yml\n and you will find these configuration files throughout the MyNewt packages. While you can edit these\nfiles directly to change some default settings, it is best to override the default settings in a \nsyscfg.yml\n file in your project\ndirectory rather than editing the package configurations directly.\n\n\nTo see all \nall\n the system configuration settings, simply type\n\n\n$ newt target config show \ntarget-name\n\n...\n* PACKAGE: sys/stats\n * Setting: STATS_CLI\n * Description: Expose the \nstat\n shell command.\n * Value: 0\n * Setting: STATS_NAMES\n * Description: Include and report the textual name of each statistic.\n * Value: 0\n * Setting: STATS_NEWTMGR\n * Description: Expose the \nstat\n newtmgr command.\n * Value: 0\n...\n$\n\n\n\n\n\nKeep in mind that this will only show the configuration options for any packages that are included in your applicaiton. \n\n\nIf you really want to see \nall\n the available configuration options, you can go rough each package and look at the\n\nsyscfg.yml\n file in each.",
- "title": "Concepts"
- },
- {
- "location": "/os/get_started/vocabulary/#concepts",
- "text": "This page is meant to introduce you to some of the concepts inherent to \nthe Apache Mynewt Operating System, and Newt the tool that stitches a \nproject built on Apache Mynewt together.",
- "title": "Concepts"
- },
- {
- "location": "/os/get_started/vocabulary/#project",
- "text": "The project is the base directory of your embedded software tree. It is a \nworkspace that contains a logical collection of source code, for one or \nmore of your applications. A project consists of the following items: Project Definition: defines project level dependencies, and parameters\n (located in project.yml ) Packages Packages are described in detail in the section below. Here is an example project definition file from the default Apache Mynewt \nproject: $ more project.yml snip \nproject.name: my_project \n\nproject.repositories:\n - apache-mynewt-core\n\n# Use github s distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n$ A couple of things to note in the project definition: project.repositories : Defines the remote repositories that this project\nrelies upon. repository.apache-mynewt-core : Defines the repository information for \nthe apache-mynewt-core repository. vers=1-latest : Defines the repository version. This string will use the \nlatest stable version in the 'Master' github branch. To use the latest version in the \nmaster branch, just change it to vers=0-dev . Note that this branch might not be stable. Repositories are versioned collections of packages. Projects can rely on remote repositories for functionality, and the newt tool \nwill resolve those remote repositories, and download the correct version into \nyour local source tree. Newly fetched repositories are put in the repos \ndirectory of your project, and can be referenced throughout the system by using\nthe @ specifier. By default, the @apache-mynewt-core repository is included in every \nproject. Apache Mynewt Core contains all the base functionality of the Apache \nMynewt Operating System, including the Real Time Kernel, Bluetooth Networking \nStack, Flash File System, Console, Shell and Bootloader. NOTE: Any project can be converted into a repository by providing it with a repository.yml file and putting it up onto Github. More information\nabout repositories can be found in the Newt documentation.",
- "title": "Project"
- },
- {
- "location": "/os/get_started/vocabulary/#package",
- "text": "A package is a collection items that form a fundamental unit in the Mynewt \nOperating System. Packages can be: Applications Libraries Compiler definitions Targets A package is identified by having a pkg.yml file in it's base \ndirectory. Here is a sample pkg.yml file for the blinky applicaton: $ more pkg.yml snip \npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: Apache Mynewt dev@mynewt.incubator.apache.org \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n\npkg.deps:\n - @apache-mynewt-core/libs/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/libs/console/full Packages have a few features worth noting: Dependencies: Packages can rely upon other packages, and when they do\n they will inherit their functionality (header files, library definitions, etc.) APIs: Packages can export named APIs, and they can require that certain \n APIs be present, in order to compile. Everything that newt knows about within a project's directory is a package. This \nmakes it very clean and easy to write re-usable components, which can describe their \nDependencies and APIs to the rest of the system.",
- "title": "Package"
- },
- {
- "location": "/os/get_started/vocabulary/#target",
- "text": "A target in Apache Mynewt is very similar to a target in make . It is the collection\nof parameters that must be passed to Newt in order to generate a reproducible build. A \ntarget represents the top of the build tree, and any packages or parameters specified at \nthe target level, cascade down to all dependencies. Targets are also packages, and are stored in the targets/ directory at the base \nof your project. Most targets consist of: app : The application to build. bsp : The board support package to combine with that application build_profile : Either debug or optimized . Targets can also have additional items specified, including: aflags : Any additional assembler flags you might want to specify to the build. cflags : Any additional compiler flags you might want to specify to the build. lflags : Any additional linker flags you might want to specify to the build. In order to create and manipulate targets, the newt tool offers a set of helper commands,\nyou can find more information about these by issuing: $ newt target newt target\nUsage:\n newt target [flags]\n newt target [command]\n\nAvailable Commands:\n config View or populate a target s system configuration\n copy Copy target\n create Create a target\n delete Delete target\n dep View target s dependency graph\n revdep View target s reverse-dependency graph\n set Set target configuration variable\n show View target configuration variables\n\nGlobal Flags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands\n\nUse newt target [command] --help for more information about a command.\n\n$",
- "title": "Target"
- },
- {
- "location": "/os/get_started/vocabulary/#configuration",
- "text": "There are a lot of configuration options available when building your application in MyNewt. System Configuration options are set in \na file called syscfg.yml and you will find these configuration files throughout the MyNewt packages. While you can edit these\nfiles directly to change some default settings, it is best to override the default settings in a syscfg.yml file in your project\ndirectory rather than editing the package configurations directly. To see all all the system configuration settings, simply type $ newt target config show target-name \n...\n* PACKAGE: sys/stats\n * Setting: STATS_CLI\n * Description: Expose the stat shell command.\n * Value: 0\n * Setting: STATS_NAMES\n * Description: Include and report the textual name of each statistic.\n * Value: 0\n * Setting: STATS_NEWTMGR\n * Description: Expose the stat newtmgr command.\n * Value: 0\n...\n$ Keep in mind that this will only show the configuration options for any packages that are included in your applicaiton. If you really want to see all the available configuration options, you can go rough each package and look at the syscfg.yml file in each.",
- "title": "Configuration"
- },
- {
- "location": "/os/tutorials/tutorials/",
- "text": "Tutorials\n\n\nIf the introduction to Mynewt has piqued your interest and you want to familiarize yourself with some of its functionality, this series of tutorials is for you. The lessons are aimed at the beginner.\n\n\nThe full list of tutorials can be seen in the navigation bar on the left. New ones are being constantly added and will show up there automatically.\n\n\n\n\nPrerequisites:\n\n\n\n\nYou have installed Docker container of Newt tool and toolchains or you have installed them natively on your machine\n\n\nYou have created a new project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in \nCreating Your First Project\n.\n\n\nYou have at least one of the supported development boards:\n\n\nArduino Zero hardware\n\n\nOlimex/STM32F407ZGT6 Cortex-M4 hardware\n\n\nnRF52 Development Kit from Nordic Semiconductor\n\n\n\n\n\n\n\n\nThe Nordic nrf52 developer kit supports Bluetooth Low Energy. We are always looking to add new hardware to the list, so if you want to develop the required Board Support Package (bsp) and/or Hardware Abstraction Layer (HAL) for a new board, you can look \nhere\n to get started.\n\n\n\n\nTutorial categories:\n\n\nThe tutorials fall into a few broad categories. Some examples in each category are listed below.\n\n\n\n\n\n\nMaking an LED blink (the \"Hello World\" equivalent in the electronics world)\n\n\n\n\nBlinky on Arduino Zero hardware\n\n\nBlinky on Olimex/STM32F407ZGT6 Cortex-M4 hardware\n\n\nBlinky on nRF52 Development Kit from Nordic Semiconductor\n \nNote:\n This supports BLE.\n\n\nBlinky on Redbear Nano2\n\n\n\n\n\n\n\n\n\n\nNavigating the code and adding functionality \n\n\n\n\nAdding more repositories to your project\n\n\nAdding a unit test for a package\n\n\nAdding task to manage multiple events\n\n\n\n\n\n\n\n\n\n\n\n\nBluetooth Low Energy\n\n\nRunning the example BLE app included in the repo\n\n\nWorking with another example BLE app for a peripheral device\n\n\n\n\n\n\n\n\n\n\n\n\nUsing NewtMgr\n\n\nEnabling remote communication with a device running Mynewt OS\n\n\n\n\n\n\n\n\n\n\n\n\nAdditional network connectivity\n\n\nConnect Arduino to a Wi-Fi network\n\n\n\n\n\n\n\n\nSend us an email on the dev@ mailing list if you have comments or suggestions!\n If you haven't joined the mailing list, you will find the links \nhere\n.",
- "title": "toc"
- },
- {
- "location": "/os/tutorials/tutorials/#tutorials",
- "text": "If the introduction to Mynewt has piqued your interest and you want to familiarize yourself with some of its functionality, this series of tutorials is for you. The lessons are aimed at the beginner. The full list of tutorials can be seen in the navigation bar on the left. New ones are being constantly added and will show up there automatically.",
- "title": "Tutorials"
- },
- {
- "location": "/os/tutorials/tutorials/#prerequisites",
- "text": "You have installed Docker container of Newt tool and toolchains or you have installed them natively on your machine You have created a new project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in Creating Your First Project . You have at least one of the supported development boards: Arduino Zero hardware Olimex/STM32F407ZGT6 Cortex-M4 hardware nRF52 Development Kit from Nordic Semiconductor The Nordic nrf52 developer kit supports Bluetooth Low Energy. We are always looking to add new hardware to the list, so if you want to develop the required Board Support Package (bsp) and/or Hardware Abstraction Layer (HAL) for a new board, you can look here to get started.",
- "title": "Prerequisites:"
- },
- {
- "location": "/os/tutorials/tutorials/#tutorial-categories",
- "text": "The tutorials fall into a few broad categories. Some examples in each category are listed below. Making an LED blink (the \"Hello World\" equivalent in the electronics world) Blinky on Arduino Zero hardware Blinky on Olimex/STM32F407ZGT6 Cortex-M4 hardware Blinky on nRF52 Development Kit from Nordic Semiconductor Note: This supports BLE. Blinky on Redbear Nano2 Navigating the code and adding functionality Adding more repositories to your project Adding a unit test for a package Adding task to manage multiple events Bluetooth Low Energy Running the example BLE app included in the repo Working with another example BLE app for a peripheral device Using NewtMgr Enabling remote communication with a device running Mynewt OS Additional network connectivity Connect Arduino to a Wi-Fi network Send us an email on the dev@ mailing list if you have comments or suggestions! If you haven't joined the mailing list, you will find the links here .",
- "title": "Tutorial categories:"
- },
- {
- "location": "/os/tutorials/blinky/",
- "text": "Blinky, your \"Hello World!\" on a Target Board\n\n\nThe set of Blinky tutorials show you how to create, build, and run a \"Hello World\" application that blinks a LED on the various target boards that Mynewt supports. The tutorials use the same Blinky application from the \nCreating Your First Project\n tutorial. \n\n\nObjective\n\n\nLearn how to use packages from a default application repository of Mynewt to build your first \nHello World\n application (Blinky) on a target board. Once built using the \nnewt\n tool, this application will blink a LED light on the target board.\n\n\nAvailable Tutorials\n\n\nTutorials are available for the following boards:\n\n\n\n\nBlinky on an Arduino Zero\n\n\nBlinky on an Arduino Primo\n\n\nBlinky on an Olimex\n\n\nBlinky on a nRF52 Development Kit\n\n\nBlinky on a RedBear Nano 2\n\n\nBlinky on a STM32F4-Discovery\n\n\n\n\nWe also have a tutorial that shows you how to add \nConsole and Shell to the Blinky Application\n.\n\n\n\nPrerequisites\n\n\nEnsure that you meet the following prerequisites before continuing with one of the tutorials. \n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a computer to build a Mynewt application and connect to the board over USB.\n\n\nHave a Micro-USB cable to connect the board and the computer.\n\n\nInstall the newt tool and toolchains (See \nBasic Setup\n).\n\n\nRead the Mynewt OS \nConcepts\n section. \n\n\nCreate a project space (directory structure) and populate it with the core code repository (apache-mynewt-core) or know how to as explained in \nCreating Your First Project\n.\n\n\n\n\n\nOverview of Steps\n\n\nThese are the general steps to create, load and run the Blinky application on your board:\n\n\n\n\nCreate a project.\n\n\nDefine the bootloader and Blinky application targets for the board.\n\n\nBuild the bootloader target.\n\n\nBuild the Blinky application target and create an application image.\n\n\nConnect to the board.\n\n\nLoad the bootloader onto the board.\n\n\nLoad the Blinky application image onto the board.\n\n\nSee the LED on your board blink.\n\n\n\n\n\n\nAfter you try the Blinky application on your boards, checkout out other tutorials to enable additional functionality such as \nremote comms\n on the current board. If you have BLE (Bluetooth Low Energy) chip (e.g. nRF52) on your board, you can try turning it into an \niBeacon\n or \nEddystone Beacon\n! \n\n\nIf you see anything missing or want to send us feedback, please sign up for \nappropriate mailing lists on our \nCommunity Page\n.",
- "title": "toc"
- },
- {
- "location": "/os/tutorials/blinky/#blinky-your-hello-world-on-a-target-board",
- "text": "The set of Blinky tutorials show you how to create, build, and run a \"Hello World\" application that blinks a LED on the various target boards that Mynewt supports. The tutorials use the same Blinky application from the Creating Your First Project tutorial.",
- "title": "Blinky, your \"Hello World!\" on a Target Board"
- },
- {
- "location": "/os/tutorials/blinky/#objective",
- "text": "Learn how to use packages from a default application repository of Mynewt to build your first Hello World application (Blinky) on a target board. Once built using the newt tool, this application will blink a LED light on the target board.",
- "title": "Objective"
- },
- {
- "location": "/os/tutorials/blinky/#available-tutorials",
- "text": "Tutorials are available for the following boards: Blinky on an Arduino Zero Blinky on an Arduino Primo Blinky on an Olimex Blinky on a nRF52 Development Kit Blinky on a RedBear Nano 2 Blinky on a STM32F4-Discovery We also have a tutorial that shows you how to add Console and Shell to the Blinky Application .",
- "title": "Available Tutorials"
- },
- {
- "location": "/os/tutorials/blinky/#prerequisites",
- "text": "Ensure that you meet the following prerequisites before continuing with one of the tutorials. Have Internet connectivity to fetch remote Mynewt components. Have a computer to build a Mynewt application and connect to the board over USB. Have a Micro-USB cable to connect the board and the computer. Install the newt tool and toolchains (See Basic Setup ). Read the Mynewt OS Concepts section. Create a project space (directory structure) and populate it with the core code repository (apache-mynewt-core) or know how to as explained in Creating Your First Project .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/blinky/#overview-of-steps",
- "text": "These are the general steps to create, load and run the Blinky application on your board: Create a project. Define the bootloader and Blinky application targets for the board. Build the bootloader target. Build the Blinky application target and create an application image. Connect to the board. Load the bootloader onto the board. Load the Blinky application image onto the board. See the LED on your board blink. After you try the Blinky application on your boards, checkout out other tutorials to enable additional functionality such as remote comms on the current board. If you have BLE (Bluetooth Low Energy) chip (e.g. nRF52) on your board, you can try turning it into an iBeacon or Eddystone Beacon ! If you see anything missing or want to send us feedback, please sign up for \nappropriate mailing lists on our Community Page .",
- "title": "Overview of Steps"
- },
- {
- "location": "/os/tutorials/arduino_zero/",
- "text": "Blinky, your \"Hello World!\", on Arduino Zero\n\n\nThis tutorial shows you how to create, build and run the Blinky application on an Arduino Zero board.\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Blinky\n.\n\n\nHave an Arduino Zero board.\n\nNote: There are many flavors of Arduino. Make sure you are using an Arduino Zero. See below for the versions of Arduino Zero that are compatible with this tutorial.\n\n\nInstall the \nOpenOCD debugger\n.\n\n\n\n\nThis tutorial uses the Arduino Zero Pro board. The tutorial has been tested on the following three Arduino Zero boards - Zero, M0 Pro, and Zero-Pro.\n\n\n\n\n\n\n\n\nMynewt has not been tested on Arduino M0 which has no internal debugger support.\n\n\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \nfetch external packages\n if you already created a project. \n\n\nRun the following commands to create a new project: \n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\n Fetch External Packages\n\n\nMynewt uses source code provided directly from the chip manufacturer for\nlow level operations. Sometimes this code is licensed only for the specific manufacturer of the chipset and cannot live in the Apache Mynewt repository. That happens to be the case for the Arduino Zero board which uses Atmel SAMD21. Runtime's github repository hosts such external third-party packages and the newt tool can fetch them.\n\n\nTo fetch the package with MCU support for Atmel SAMD21 for Arduino Zero from the Runtime git repository, you need to add\nthe repository to the \nproject.yml\n file in your base project directory.\n\n\nHere is an example \nproject.yml\n file with the Arduino Zero repository\nadded. The sections with \nmynewt_arduino_zero\n that need to be added to\nyour project file are highlighted.\n\n\nNote:\n On Windows platforms: You need to set \nvers\n to \n0-dev\n and use the latest master branch for both repositories.\n\n\n$ more project.yml\nproject.name: \nmy_project\n\n\nproject.repositories:\n - apache-mynewt-core\n\n - mynewt_arduino_zero\n\n\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\n\nrepository.mynewt_arduino_zero:\n\n type: github\n\n vers: 1-latest\n\n user: runtimeco\n\n repo: mynewt_arduino_zero\n\n$\n\n\n\n\n\n\nInstall the project dependencies using the \nnewt install\n command (you can specify \n-v\n for verbose output):\n\n\n$ newt install\napache-mynewt-core\nmynewt_arduino_zero\n$\n\n\n\n\n\n\n\nNOTE:\n If there has been a new release of a repo used in your project since you last installed it, the \n1-latest\n version for the repo in the \nproject.yml\n file will refer to the new release and will not match the installed files. In that case you will get an error message saying so and you will need to run \nnewt upgrade\n to overwrite the existing files with the latest codebase.\n\n\n\nYou need to create two targets for the Arduino Zero Pro board, one for the bootloader and one for the Blinky application.\n\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \narduino_boot\n.\n\n\n$ newt target create arduino_boot\n$ newt target set arduino_boot bsp=@mynewt_arduino_zero/hw/bsp/arduino_zero\nTarget targets/arduino_boot successfully created\n$ newt target set arduino_boot app=@apache-mynewt-core/apps/boot\nTarget targets/arduino_boot successfully set target.app to @apache-mynewt-core/apps/boot\n$ newt target set arduino_boot build_profile=optimized\nTarget targets/arduino_boot successfully set target.build_profile to optimized\n$ newt target set arduino_boot syscfg=BSP_ARDUINO_ZERO_PRO=1\nTarget targets/arduino_boot successfully set target.syscfg to BSP_ARDUINO_ZERO_PRO=1\n$\n\n\n\n\n\nNote:\n If you have an Arduino Zero instead of an Arduino Zero Pro or Arduino M0 Pro board, replace \nBSP_ARDUINO_ZERO_PRO\n with \nBSP_ARDUINO_ZERO\n in the last \nnewt target set\n command.\n\n\nThese commands perform the following:\n\n\n\n\nCreate a target named \narduino_boot\n for the Arduino Zero Bootloader. \n\n\nSet the application for the \narduino_boot\n target to the default Apache Mynewt\n bootloader (\n@apache-mynewt-core/apps/boot\n)\n\n\nSet the board support package for the target to\n \n@mynewt_arduino_zero/hw/bsp/arduino_zero\n. This is a reference to the downloaded\n Arduino Zero support from Github.\n\n\nUse the \"optimized\" build profile for the \narduino_boot\n target. This\n instructs Newt to generate smaller and more efficient code for this target.\n This setting is necessary due to the bootloader's strict size constraints.\n\n\nSets the system configuration setting for Board Support Package to support the Arduino Zero Pro. \n\n\n\n\nSee the \nConcepts\n section for more information on setting options.\n\n\n\nCreate a Target for the Blinky Application\n\n\nRun the following \nnewt target\n commands to create the Blinky application target. We name the application target \narduino_blinky\n.\n\n\n$ newt target create arduino_blinky\nTarget targets/arduino_blinky successfully created\n$ newt target set arduino_blinky app=apps/blinky\nTarget targets/arduino_blinky successfully set target.app to apps/blinky\n$ newt target set arduino_blinky bsp=@mynewt_arduino_zero/hw/bsp/arduino_zero\nTarget targets/arduino_blinky successfully set target.bsp to @mynewt_arduino_zero/hw/bsp/arduino_zero\n$ newt target set arduino_blinky build_profile=debug\nTarget targets/arduino_blinky successfully set target.build_profile to debug\n$ newt target set arduino_blinky syscfg=BSP_ARDUINO_ZERO_PRO=1\nTarget targets/arduino_boot successfully set target.syscfg to BSP_ARDUINO_ZERO_PRO=1\n$\n\n\n\n\n\nNote:\n If you have an Arduino Zero instead of a Arduino Zero Pro board, replace \nBSP_ARDUINO_ZERO_PRO\n with \nBSP_ARDUINO_ZERO\n in the last \nnewt target set\n command.\n\n\n\n\nBuild the Bootloader\n\n\nRun the \nnewt build arduino_boot\n command to build the bootloader:\n\n\n$ newt build arduino_boot\nBuilding target targets/arduino_boot\nCompiling bin/targets/arduino_boot/generated/src/arduino_boot-sysinit-app.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling bin/targets/arduino_boot/generated/src/arduino_boot-sysflash.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/arc4.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\n\n ....\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/arduino_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/arduino_boot\n\n\n\n\n\n\n\nBuild the Blinky Application\n\n\nRun the \nnewt build arduino_blinky\n command to build the Blinky application image:\n\n\n$ newt build arduino_blinky\nBuilding target targets/arduino_blinky\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\nCompiling apps/blinky/src/main.c\nCompiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/i2s/i2s.c\nCompiling repos/mynewt_arduino_zero/hw/bsp/arduino_zero/src/hal_bsp.c\nCompiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/i2s/i2s_callback.c\nCompiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/nvm/nvm.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/arduino_blinky\n\n\n\n\n\n\n\nConnect to the Board\n\n\nConnect your computer to the Arduino Zero (from now on we'll call this the\ntarget) with a Micro-USB cable through the Programming Port as shown below.\nMynewt will load the image onto the board and debug the target through this port. You should see a\ngreen LED come on that indicates the board has power.\n\n\nNo external debugger is required. The Arduino Zero comes with an internal\ndebugger that can be accessed by Mynewt.\n\n\nThe images below show the Arduino Zero Programming Port.\n\n\n\n\n\n\n\n\nLoad the Bootloader onto the Board\n\n\nRun the \nnewt load arduino_boot\n command to load the bootloader onto the board:\n\n\n$ newt load arduino_boot\nLoading bootloader\n$\n\n\n\n\n\nThe bootloader is loaded onto your board succesfully when the \nnewt load\n command returns to the command prompt after the \nLoading bootloader\n status message. You can proceed to load and run your Blinky application image (See \nRun the Blinky Application\n).\n\n\nIf the \nnewt load\n command outputs the following error messages, you will need to erase the board.\n\n\n$ newt load arduino_boot -v\nLoading bootloader\nError: Downloading ~/dev/myproj/bin/targets/arduino_boot/app/apps/boot/boot.elf.bin to 0x0\nOpen On-Chip Debugger 0.9.0 (2015-11-15-05:39)\nLicensed under GNU GPL v2\nFor bug reports, read\n http://openocd.org/doc/doxygen/bugs.html\nInfo : only one transport option; autoselect \nswd\n\nadapter speed: 500 kHz\nadapter_nsrst_delay: 100\ncortex_m reset_config sysresetreq\nInfo : CMSIS-DAP: SWD Supported\nInfo : CMSIS-DAP: JTAG Supported\nInfo : CMSIS-DAP: Interface Initialised (SWD)\nInfo : CMSIS-DAP: FW Version = 01.1F.0118\nInfo : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 1 nTRST = 0 nRESET = 1\nInfo : CMSIS-DAP: Interface ready\nInfo : clock speed 500 kHz\nInfo : SWD IDCODE 0x0bc11477\nInfo : at91samd21g18.cpu: hardware has 4 breakpoints, 2 watchpoints\nError: Target not halted\n\n\n\n\n\n\nTo erase your board, start a debug session and enter the highlighted commands at the \n(gdb)\n prompts:\n\n\nNote:\n On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal.\n\n\n$ newt debug arduino_blinky\n(gdb) mon at91samd chip-erase\nchip erased\nchip erased\n(gdb) x/32wx 0\n0x0: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x10: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x20: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x30: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x40: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x50: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x60: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x70: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n(gdb) q\n\n\n\n\n\n\nRun the \nnewt load arduino_boot\n command again after erasing the board. \n\n\n Reminder if you are using Docker: \n 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 \nError: unable to find CMSIS-DAP device\n 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.\n\n\n\n\nRun the Blinky Application\n\n\nAfter you load the bootloader successfully onto your board, you can load and run the Blinky application. \n\n\nRun the \nnewt run arduino_blinky 1.0.0\n command to build the arduino_blinky target (if necessary), create an image with version 1.0.0, load the image onto the board, and start a debugger session. \n\n\nNote\n The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals. The output of openocd is logged to the openocd.log file in your project's base directory and not to the terminal. The openocd and gdb terminals will close automatically when you quit gdb. \n\n\n\n$ newt run arduino_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.img\nLoading app image into slot 1\n[~/dev/myproj/repos/mynewt_arduino_zero/hw/bsp/arduino_zero/arduino_zero_debug.sh ~/dev/myproj/repos/mynewt_arduino_zero/hw/bsp/arduino_zero ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.9.0 (2015-11-15-13:10)\nLicensed under GNU GPL v2\nFor bug reports, read\nhttp://openocd.org/doc/doxygen/bugs.html\nInfo : only one transport option; autoselect \nswd\n\nadapter speed: 500 kHz\nadapter_nsrst_delay: 100\ncortex_m reset_config sysresetreq\nInfo : CMSIS-DAP: SWD Supported\nInfo : CMSIS-DAP: JTAG Supported\nInfo : CMSIS-DAP: Interface Initialised (SWD)\nInfo : CMSIS-DAP: FW Version = 01.1F.0118\nInfo : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 1 nTRST = 0 nRESET = 1\nInfo : CMSIS-DAP: Interface ready\nInfo : clock speed 500 kHz\nInfo : SWD IDCODE 0x0bc11477\nInfo : at91samd21g18.cpu: hardware has 4 breakpoints, 2 watchpoints\ntarget state: halted\ntarget halted due to debug-request, current mode: Thread \nxPSR: 0x21000000 pc: 0x0000fca6 psp: 0x20002408\nGNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs\nCopyright (C) 2014 Free Software Foundation, Inc.\nLicense GPLv3+: GNU GPL version 3 or later \nhttp://gnu.org/licenses/gpl.html\n\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law. Type \nshow copying\n\nand \nshow warranty\n for details.\nThis GDB was configured as \n--host=x86_64-apple-darwin10 --target=arm-none-eabi\n.\nType \nshow configuration\n for configuration details.\nFor bug reporting instructions, please see:\n\nhttp://www.gnu.org/software/gdb/bugs/\n.\nFind the GDB manual and other documentation resources online at:\n\nhttp://www.gnu.org/software/gdb/documentation/\n.\nFor help, type \nhelp\n.\nType \napropos word\n to search for commands related to \nword\n...\nReading symbols from ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.elf...(no debugging symbols found)...done.\nInfo : accepting \ngdb\n connection on tcp/3333\nInfo : SAMD MCU: SAMD21G18A (256KB Flash, 32KB RAM)\n0x0000fca6 in os_tick_idle ()\ntarget state: halted\ntarget halted due to debug-request, current mode: Thread \nxPSR: 0x21000000 pc: 0x000000b8 msp: 0x20008000\ntarget state: halted\ntarget halted due to debug-request, current mode: Thread \nxPSR: 0x21000000 pc: 0x000000b8 msp: 0x20008000\n(gdb) r\nThe \nremote\n target does not support \nrun\n. Try \nhelp target\n or \ncontinue\n.\n(gdb) c\nContinuing.\n\n\n\n\n\n\n\nNOTE:\n The 1.0.0 is the version number to assign to the image. You may assign an arbitrary version number. If you are not providing remote upgrade, and are just developing locally, you can provide 1.0.0 for every image version.\n\n\nIf you want the image to run without the debugger connected, simply quit the\ndebugger and restart the board. The image you programmed will come up and run on \nthe Arduino on the next boot! \n\n\n\nYou should see the LED blink!",
- "title": "Blinky on Arduino Zero"
- },
- {
- "location": "/os/tutorials/arduino_zero/#blinky-your-hello-world-on-arduino-zero",
- "text": "This tutorial shows you how to create, build and run the Blinky application on an Arduino Zero board.",
- "title": "Blinky, your \"Hello World!\", on Arduino Zero"
- },
- {
- "location": "/os/tutorials/arduino_zero/#prerequisites",
- "text": "Meet the prerequisites listed in Project Blinky . Have an Arduino Zero board. \nNote: There are many flavors of Arduino. Make sure you are using an Arduino Zero. See below for the versions of Arduino Zero that are compatible with this tutorial. Install the OpenOCD debugger . This tutorial uses the Arduino Zero Pro board. The tutorial has been tested on the following three Arduino Zero boards - Zero, M0 Pro, and Zero-Pro. Mynewt has not been tested on Arduino M0 which has no internal debugger support.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/arduino_zero/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to fetch external packages if you already created a project. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/arduino_zero/#create-a-target-for-the-blinky-application",
- "text": "Run the following newt target commands to create the Blinky application target. We name the application target arduino_blinky . $ newt target create arduino_blinky\nTarget targets/arduino_blinky successfully created\n$ newt target set arduino_blinky app=apps/blinky\nTarget targets/arduino_blinky successfully set target.app to apps/blinky\n$ newt target set arduino_blinky bsp=@mynewt_arduino_zero/hw/bsp/arduino_zero\nTarget targets/arduino_blinky successfully set target.bsp to @mynewt_arduino_zero/hw/bsp/arduino_zero\n$ newt target set arduino_blinky build_profile=debug\nTarget targets/arduino_blinky successfully set target.build_profile to debug\n$ newt target set arduino_blinky syscfg=BSP_ARDUINO_ZERO_PRO=1\nTarget targets/arduino_boot successfully set target.syscfg to BSP_ARDUINO_ZERO_PRO=1\n$ Note: If you have an Arduino Zero instead of a Arduino Zero Pro board, replace BSP_ARDUINO_ZERO_PRO with BSP_ARDUINO_ZERO in the last newt target set command.",
- "title": "Create a Target for the Blinky Application"
- },
- {
- "location": "/os/tutorials/arduino_zero/#build-the-bootloader",
- "text": "Run the newt build arduino_boot command to build the bootloader: $ newt build arduino_boot\nBuilding target targets/arduino_boot\nCompiling bin/targets/arduino_boot/generated/src/arduino_boot-sysinit-app.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling bin/targets/arduino_boot/generated/src/arduino_boot-sysflash.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/arc4.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\n\n ....\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/arduino_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/arduino_boot",
- "title": "Build the Bootloader"
- },
- {
- "location": "/os/tutorials/arduino_zero/#build-the-blinky-application",
- "text": "Run the newt build arduino_blinky command to build the Blinky application image: $ newt build arduino_blinky\nBuilding target targets/arduino_blinky\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\nCompiling apps/blinky/src/main.c\nCompiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/i2s/i2s.c\nCompiling repos/mynewt_arduino_zero/hw/bsp/arduino_zero/src/hal_bsp.c\nCompiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/i2s/i2s_callback.c\nCompiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/nvm/nvm.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/arduino_blinky",
- "title": "Build the Blinky Application"
- },
- {
- "location": "/os/tutorials/arduino_zero/#connect-to-the-board",
- "text": "Connect your computer to the Arduino Zero (from now on we'll call this the\ntarget) with a Micro-USB cable through the Programming Port as shown below.\nMynewt will load the image onto the board and debug the target through this port. You should see a\ngreen LED come on that indicates the board has power. No external debugger is required. The Arduino Zero comes with an internal\ndebugger that can be accessed by Mynewt. The images below show the Arduino Zero Programming Port.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/arduino_zero/#load-the-bootloader-onto-the-board",
- "text": "Run the newt load arduino_boot command to load the bootloader onto the board: $ newt load arduino_boot\nLoading bootloader\n$ The bootloader is loaded onto your board succesfully when the newt load command returns to the command prompt after the Loading bootloader status message. You can proceed to load and run your Blinky application image (See Run the Blinky Application ). If the newt load command outputs the following error messages, you will need to erase the board. $ newt load arduino_boot -v\nLoading bootloader\nError: Downloading ~/dev/myproj/bin/targets/arduino_boot/app/apps/boot/boot.elf.bin to 0x0\nOpen On-Chip Debugger 0.9.0 (2015-11-15-05:39)\nLicensed under GNU GPL v2\nFor bug reports, read\n http://openocd.org/doc/doxygen/bugs.html\nInfo : only one transport option; autoselect swd \nadapter speed: 500 kHz\nadapter_nsrst_delay: 100\ncortex_m reset_config sysresetreq\nInfo : CMSIS-DAP: SWD Supported\nInfo : CMSIS-DAP: JTAG Supported\nInfo : CMSIS-DAP: Interface Initialised (SWD)\nInfo : CMSIS-DAP: FW Version = 01.1F.0118\nInfo : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 1 nTRST = 0 nRESET = 1\nInfo : CMSIS-DAP: Interface ready\nInfo : clock speed 500 kHz\nInfo : SWD IDCODE 0x0bc11477\nInfo : at91samd21g18.cpu: hardware has 4 breakpoints, 2 watchpoints\nError: Target not halted \nTo erase your board, start a debug session and enter the highlighted commands at the (gdb) prompts: Note: On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal. $ newt debug arduino_blinky\n(gdb) mon at91samd chip-erase\nchip erased\nchip erased\n(gdb) x/32wx 0\n0x0: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x10: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x20: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x30: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x40: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x50: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x60: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n0x70: 0xffffffff 0xffffffff 0xffffffff 0xffffffff\n(gdb) q \nRun the newt load arduino_boot command again after erasing the board. Reminder if you are using Docker: 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 Error: unable to find CMSIS-DAP device 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.",
- "title": "Load the Bootloader onto the Board"
- },
- {
- "location": "/os/tutorials/blinky_primo/",
- "text": "Blinky, your \"Hello World!\", on Arduino Primo\n\n\nThis tutorial shows you how to create, build, and run the Blinky application on an Arduino Primo board.\n\n\nNote that the Mynewt OS will run on the nRF52 chip in the Arduino Primo board. However, the board support package for the Arduino Primo is different from the nRF52 dev kit board support package.\n\n\n\nPrerequisites\n\n\n\n\nMeet the the prerequisites listed in \nProject Blinky\n.\n\n\nHave an Arduino Primo board.\n\n\nInstall a debugger. Choose one of the two options below: Option 1 requires additional hardware but very easy to set up. \n\n\n\n\n\n\nOption 1\n\n\n\n\nSegger J-Link Debug Probe\n - any model (this tutorial has been tested with J-Link EDU and J-Link Pro)\n\n\nJ-Link 9 pin Cortex-M Adapter\n that allows JTAG, SWD and SWO connections between J-Link and Cortex M based target hardware systems\n\n\nInstall the \nSegger JLINK Software and documentation pack\n. \n\n\n\n\nOption 2\n\n\nThis board requires a patch version of OpenOCD 0.10.0 that is in development. See \nInstall OpenOCD\n instructions to install it if you do not have this version installed.\n\n\nYou can now use openocd to upload to Arduino Primo board via the USB port itself.\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already created a project.\n\n\nRun the following commands to create a new project:\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\nCreate the Targets\n\n\nCreate two targets for the Arduino Primo board - one for the bootloader and one for the Blinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nprimo_boot\n.\n\n\n$ newt target create primo_boot\n$ newt target set primo_boot app=@apache-mynewt-core/apps/boot bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52 build_profile=optimized\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Blinky application. We name the target \nprimoblinky\n.\n\n\n$ newt target create primoblinky\n$ newt target set primoblinky app=apps/blinky bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52 build_profile=debug\n\n\n\n\n\n\nIf you are using openocd, run the following \nnewt target set\n commands:\n\n\n$ newt target set primoblinky syscfg=OPENOCD_DEBUG=1\n$ newt target set primo_boot syscfg=OPENOCD_DEBUG=1\n\n\n\n\n\n\nYou can run the \nnewt target show\n command to verify the target settings:\n\n\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/primo_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n build_profile=optimized\ntargets/primoblinky\n app=@apache-mynewt-core/apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n build_profile=optimized\n\n\n\n\n\n\n\nBuild the Target Executables\n\n\nRun the \nnewt build primo_boot\n command to build the bootloader:\n\n\n$ newt build primo_boot\nBuilding target targets/primo_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/primo_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/primo_boot\n\n\n\n\n\n\nRun the \nnewt build primoblinky\n command to build the Blinky application:\n\n\n$ newt build primoblinky\nBuilding target targets/primoblinky\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nAssembling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/arch/cortex_m4/gcc_startup_nrf52.s\nCompiling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/sbrk.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nAssembling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/arch/cortex_m4/gcc_startup_nrf52_split.s\nCompiling apps/blinky/src/main.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_bitbang/src/uart_bitbang.c\nCompiling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/hal_bsp.c\n\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/primoblinky\n\n\n\n\n\n\n\nSign and Create the Blinky Application Image\n\n\nRun the \nnewt create-image primoblinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\n$ newt create-image primoblinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky.img\n\n\n\n\n\n\n\nConnect to the Board\n\n\n\n\nConnect a micro USB cable to the Arduino Primo board and to your computer's USB port.\n\n\nIf you are using the Segger J-Link debug probe, connect the debug probe to the JTAG port on the Primo board using the Jlink 9-pin adapter and cable. Note that there are two JTAG ports on the board. Use the one nearest to the reset button as shown in the picture. \n\n\n\n\n\n\nNote:\n If you are using the OpenOCD debugger, you do not need to attach this connector. \n\n\nLoad the Bootloader\n\n\nRun the \nnewt load primo_boot\n command to load the bootloader onto the board:\n\n\n$ newt load primo_boot\nLoading bootloader\n$\n\n\n\n\n\nNote:\n If you are using OpenOCD on a Windows platform and you get an \nunable to find CMSIS-DAP device\n error, you will need to download and install the mbed Windows serial port driver from \nhttps://developer.mbed.org/handbook/Windows-serial-configuration\n. Follow the instructions from the site to install the driver. Here are some additional notes about the installation:\n\n\n\n\nThe instructions indicate that the mbed Windows serial port driver is not required for Windows 10. If you are using Windows 10 and get the \nunable to find CMSIS-DAP device\n error, we recommend that you install the driver.\n\n\n\n\nIf the driver installation fails, we recommend that you download and install the Arduino Primo CMSIS-DAP driver. Perform the following steps: \n\n\n\n\nDownload the \nArduino Primo CMSIS-DAP driver\n and extract the zip file.\n\n\nStart Device Manager.\n\n\nSelect \nOther Devices\n \n \nCMSIS-DAP CDC\n \n \nProperties\n \n \nDrivers\n \n \nUpdate Driver...\n.\n\n\nSelect \nBrowse my computer for driver software\n.\n\n\nSelect the Arduino Driver folder where extracted the drivers to (check the include subfolders). Click \nNext\n to install the driver.\n\n\n\n\n\n\n\n\nRun the \nnewt load primo_boot\n command again.\n\n\n\n\nLoad the Blinky Application Image\n\n\nRun the \nnewt load primoblinky\n command to load the Blinky application image onto the board.\n\n\n$ newt load primoblinky \nLoading app image into slot 1\n$\n\n\n\n\n\nYou should see the orange LED (L13), below the ON LED, on the board blink!\n\n\nNote: If the LED does not blink, try resetting the board.\n\n\n\n\nErase Flash\n\n\nIf you want to erase the flash and load the image again, use JLinkExe and issue the \nerase\n command when you are using the Jlink debug probe: \n\n\nNote:\n On Windows: Run the \njlink\n command with the same arguments from a Windows Command Prompt terminal.\n\n\n\n$ JLinkExe -device nRF52 -speed 4000 -if SWD\nSEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)\nDLL version V5.12c, compiled Apr 21 2016 16:05:45\n\nConnecting to J-Link via USB...O.K.\nFirmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17\nHardware version: V1.00\nS/N: 682863966\nVTref = 3.300V\n\n\nType \nconnect\n to establish a target connection, \n?\n for help\nJ-Link\nerase\nCortex-M4 identified.\nErasing device (0;?i?)...\nComparing flash [100%] Done.\nErasing flash [100%] Done.\nVerifying flash [100%] Done.\nJ-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)\nErasing done.\nJ-Link\nexit\n$\n\n\n\n\n\n\n\nIf you are using the OpenOCD debugger, run the \nnewt debug primoblinky\n command and issue the highlighted command at the (gdb) prompt:\n\n\nNote:\n The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal.\n\n\n$newt debug primoblinky\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/primo_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52 ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.10.0-dev-snapshot (2017-03-28-11:24)\n\n ...\n\nos_tick_idle (ticks=128)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\nwarning: Source file is more recent than executable.\n200 if (ticks \n 0) {\n\n(gdb) mon nrf52 mass_erase",
- "title": "Blinky on Arduino Primo"
- },
- {
- "location": "/os/tutorials/blinky_primo/#blinky-your-hello-world-on-arduino-primo",
- "text": "This tutorial shows you how to create, build, and run the Blinky application on an Arduino Primo board. Note that the Mynewt OS will run on the nRF52 chip in the Arduino Primo board. However, the board support package for the Arduino Primo is different from the nRF52 dev kit board support package.",
- "title": "Blinky, your \"Hello World!\", on Arduino Primo"
- },
- {
- "location": "/os/tutorials/blinky_primo/#prerequisites",
- "text": "Meet the the prerequisites listed in Project Blinky . Have an Arduino Primo board. Install a debugger. Choose one of the two options below: Option 1 requires additional hardware but very easy to set up.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/blinky_primo/#option-1",
- "text": "Segger J-Link Debug Probe - any model (this tutorial has been tested with J-Link EDU and J-Link Pro) J-Link 9 pin Cortex-M Adapter that allows JTAG, SWD and SWO connections between J-Link and Cortex M based target hardware systems Install the Segger JLINK Software and documentation pack .",
- "title": "Option 1"
- },
- {
- "location": "/os/tutorials/blinky_primo/#option-2",
- "text": "This board requires a patch version of OpenOCD 0.10.0 that is in development. See Install OpenOCD instructions to install it if you do not have this version installed. You can now use openocd to upload to Arduino Primo board via the USB port itself.",
- "title": "Option 2"
- },
- {
- "location": "/os/tutorials/blinky_primo/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already created a project. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/blinky_primo/#build-the-target-executables",
- "text": "Run the newt build primo_boot command to build the bootloader: $ newt build primo_boot\nBuilding target targets/primo_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/primo_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/primo_boot \nRun the newt build primoblinky command to build the Blinky application: $ newt build primoblinky\nBuilding target targets/primoblinky\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nAssembling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/arch/cortex_m4/gcc_startup_nrf52.s\nCompiling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/sbrk.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nAssembling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/arch/cortex_m4/gcc_startup_nrf52_split.s\nCompiling apps/blinky/src/main.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_bitbang/src/uart_bitbang.c\nCompiling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/hal_bsp.c\n\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/primoblinky",
- "title": "Build the Target Executables"
- },
- {
- "location": "/os/tutorials/blinky_primo/#sign-and-create-the-blinky-application-image",
- "text": "Run the newt create-image primoblinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. $ newt create-image primoblinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky.img",
- "title": "Sign and Create the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/blinky_primo/#connect-to-the-board",
- "text": "Connect a micro USB cable to the Arduino Primo board and to your computer's USB port. If you are using the Segger J-Link debug probe, connect the debug probe to the JTAG port on the Primo board using the Jlink 9-pin adapter and cable. Note that there are two JTAG ports on the board. Use the one nearest to the reset button as shown in the picture. Note: If you are using the OpenOCD debugger, you do not need to attach this connector.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/blinky_primo/#load-the-bootloader",
- "text": "Run the newt load primo_boot command to load the bootloader onto the board: $ newt load primo_boot\nLoading bootloader\n$ Note: If you are using OpenOCD on a Windows platform and you get an unable to find CMSIS-DAP device error, you will need to download and install the mbed Windows serial port driver from https://developer.mbed.org/handbook/Windows-serial-configuration . Follow the instructions from the site to install the driver. Here are some additional notes about the installation: The instructions indicate that the mbed Windows serial port driver is not required for Windows 10. If you are using Windows 10 and get the unable to find CMSIS-DAP device error, we recommend that you install the driver. If the driver installation fails, we recommend that you download and install the Arduino Primo CMSIS-DAP driver. Perform the following steps: Download the Arduino Primo CMSIS-DAP driver and extract the zip file. Start Device Manager. Select Other Devices CMSIS-DAP CDC Properties Drivers Update Driver... . Select Browse my computer for driver software . Select the Arduino Driver folder where extracted the drivers to (check the include subfolders). Click Next to install the driver. Run the newt load primo_boot command again.",
- "title": "Load the Bootloader"
- },
- {
- "location": "/os/tutorials/blinky_primo/#load-the-blinky-application-image",
- "text": "Run the newt load primoblinky command to load the Blinky application image onto the board. $ newt load primoblinky \nLoading app image into slot 1\n$ You should see the orange LED (L13), below the ON LED, on the board blink! Note: If the LED does not blink, try resetting the board.",
- "title": "Load the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/blinky_primo/#erase-flash",
- "text": "If you want to erase the flash and load the image again, use JLinkExe and issue the erase command when you are using the Jlink debug probe: Note: On Windows: Run the jlink command with the same arguments from a Windows Command Prompt terminal. $ JLinkExe -device nRF52 -speed 4000 -if SWD\nSEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)\nDLL version V5.12c, compiled Apr 21 2016 16:05:45\n\nConnecting to J-Link via USB...O.K.\nFirmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17\nHardware version: V1.00\nS/N: 682863966\nVTref = 3.300V\n\n\nType connect to establish a target connection, ? for help\nJ-Link erase\nCortex-M4 identified.\nErasing device (0;?i?)...\nComparing flash [100%] Done.\nErasing flash [100%] Done.\nVerifying flash [100%] Done.\nJ-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)\nErasing done.\nJ-Link exit\n$ If you are using the OpenOCD debugger, run the newt debug primoblinky command and issue the highlighted command at the (gdb) prompt: Note: The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal. $newt debug primoblinky\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/primo_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52 ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.10.0-dev-snapshot (2017-03-28-11:24)\n\n ...\n\nos_tick_idle (ticks=128)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\nwarning: Source file is more recent than executable.\n200 if (ticks 0) { (gdb) mon nrf52 mass_erase",
- "title": "Erase Flash"
- },
- {
- "location": "/os/tutorials/olimex/",
- "text": "Blinky, your \"Hello World!\", on Olimex\n\n\nThis tutorial shows you how to create, build, and run the Blinky application on an Olimex STM32-E407 board.\n\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Blinky\n.\n\n\nHave a STM32-E407 development board from Olimex. \n\n\nHave a ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board)\n\n\nHave a USB A-B type cable to connect the debugger to your computer.\n\n\nInstall the \nOpenOCD debugger\n.\n\n\n\n\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already created a project.\n\n\nRun the following commands to create a new project:\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n\n $cd myproj\n\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\nCreate the Targets\n\n\nCreate two targets for the Olimex board - one for the bootloader and one for the Blinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nboot_olimex\n.\n\n\n$ newt target create boot_olimex\n$ newt target set boot_olimex build_profile=optimized\n$ newt target set boot_olimex app=@apache-mynewt-core/apps/boot\n$ newt target set boot_olimex bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Blinky application. We name the target \nolimex_blinky\n.\n\n\n$ newt target create olimex_blinky\n$ newt target set olimex_blinky build_profile=debug\n$ newt target set olimex_blinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard\n$ newt target set olimex_blinky app=apps/blinky\n\n\n\n\n\n\n\nBuild the Bootloader\n\n\nRun the \nnewt build boot_olimex\n command to build the bootloader:\n\n\n$ newt build boot_olimex\nBuilding target targets/boot_olimex\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling bin/targets/boot_olimex/generated/src/boot_olimex-sysflash.c\n\n ...\n\nArchiving libc_baselibc.a\nArchiving sys_flash_map.a\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/boot_olimex/app/apps/boot/boot.elf\nTarget successfully built: targets/boot_olimex\n\n\n\n\n\n\n\nBuild the Blinky Application\n\n\nRun the \nnewt build olimex_blinky\n command to build the blinky application:\n\n\n$ newt build olimex_blinky\nBuilding target targets/olimex_blinky\nAssembling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/arch/cortex_m4/startup_STM32F40x.s\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/sbrk.c\nCompiling apps/blinky/src/main.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nCompiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/hal_bsp.c\nCompiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/system_stm32f4xx.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/olimex_blinky\n\n\n\n\n\n\n\nSign and Create the Blinky Application Image\n\n\nRun the \nnewt create-image olimex_blinky 1.0.0\n command to sign and create an image file for the blinky application. You may assign an arbitrary version (e.g. 1.0.0) number.\n\n\n$ newt create-image olimex_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky.img\n\n\n\n\n\n\n\nConnect to the Board\n\n\nConfigure the board to bootload from flash memory and to use USB-OTG2 for the power source. Refer to the following diagrams to locate the boot jumpers and power input select jumpers on the board. \n\n\nNote:\n The labels for the \nUSB-OTG1\n and \nUSB-OTG2\n ports on the diagram are reversed. The port labeled USB-OTG1 on the diagram is the USB-OTG2 port and the port labeled USB-OTG2 on the diagram is the USB-OTG1 port.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nLocate the boot jumpers on the lower right corner of the board. \nB1_1/B1_0\n and \nB0_1/B0_0\n are PTH jumpers to control the boot mode when a bootloader is present. These two jumpers must be moved together. The board searches for the bootloader in three places: User Flash Memory, System Memory or the Embedded SRAM. For this Blinky project, we configure the board to boot from flash by jumpering \nB0_0\n and \nB1_0\n.\n\nNote:\n The markings on the board may not always be accurate, and you should always refer to the manual for the correct positioning. \n\n\n\n\n\n\nLocate the \nPower Input Select\n jumpers on the lower left corner of the board. Set the Power Select jumpers to position 5 and 6 to use the USB-OTG2 port for the power source. If you would like to use a different power source, refer to the \nOLIMEX STM32-E407 user manual\n for pin specifications.\n\n\n\n\n\n\nConnect the USB Micro-A cable to the USB-OTG2 port on the board. \n\n\n\n\n\n\nConnect the JTAG connector to the JTAG/SWD interface on the board. \n\n\n\n\n\n\nConnect the USB A-B cable to the ARM-USB-TINY-H connector and your computer.\n\n\n\n\n\n\nCheck that the red PWR LED lights up.\n\n\n\n\n\n\n\nLoad the Bootloader and Blinky Application\n\n\nRun the \nnewt load boot_olimex\n command to load the bootloader image onto the board:\n\n\n$newt load -v boot_olimex\nLoading bootloader\nLoad command: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ~/dev/myproj/bin/targets/boot_olimex/app/apps/boot/boot\nSuccessfully loaded image.\n\n\n\n\n\nNote: If you are using Windows and get a \nno device found\n error, you will need to install the usb driver. Download \nZadig\n and run it:\n\n\n\n\nSelect Options \n List All Devices.\n\n\nSelect \nOlimex OpenOCD JTAG ARM-USB-TINY-H\n from the drop down menu.\n\n\nSelect the \nWinUSB\n driver.\n\n\nClick Install Driver.\n\n\nRun the \nnewt load boot_olimex\n command again. \n\n\n\n\n\nRun the \nnewt load olimex_blinky\n command to load the blinky application image onto the board:\n\n\nnewt load -v olimex_blinky\nLoading app image into slot 1\nLoad command: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky\nSuccessfully loaded image.\n\n\n\n\n\n\nThe LED should be blinking!\n\n\n\nLet's double check that it is indeed booting from flash and making the LED blink from the image in flash. Pull the USB cable off the Olimex JTAG adaptor, severing the debug connection to the JTAG port. Next power off the Olimex board by pulling out the USB cable from the board. Wait for a couple of seconds and plug the USB cable back to the board.\n\n\nThe LED light will start blinking again. Success!\n\n\nIf you want to download the image to flash and open a gdb session, use \nnewt debug blinky\n. \n\n\nNote:\n The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal.\n\n\n\nType \nc\n to continue inside the gdb session.\n\n\n $ newt debug blinky\n Debugging with ~/dev/myproj/hw/bsp/olimex_stm32-e407_...\n Debugging ~/dev/myproj/project/blinky/bin/blinky/blinky.elf\n GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs\n Copyright (C) 2014 Free Software Foundation, Inc.\n License GPLv3+: GNU GPL version 3 \nhttp://gnu.org/licenses/gpl.html\n\n ...\n (info)\n ...\n target state: halted\n target halted due to debug-request, current mode: Thread\n xPSR: 0x01000000 pc: 0x08000250 msp: 0x10010000\n Info : accepting \ngdb\n connection from 3333\n Info : device id = 0x10036413\n Info : flash size = 1024kbytes\n Reset_Handler () at startup_STM32F40x.s:199\n 199 ldr r1, =__etext\n (gdb)\n\n\n\n\n\n\n\nIf you want to erase the flash and load the image again you may use the following commands from within gdb. \nflash erase_sector 0 0 x\n tells it to erase sectors 0 through x. When you ask it to display (in hex notation) the contents of the sector starting at location 'lma,' you should see all f's. The memory location 0x8000000 is the start or origin of the flash memory contents and is specified in the olimex_stm32-e407_devboard.ld linker script. The flash memory locations is specific to the processor.\n\n\n (gdb) monitor flash erase_sector 0 0 4\n erased sectors 0 through 4 on flash bank 0 in 2.296712s\n (gdb) monitor mdw 0x08000000 16\n 0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff\n (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff\n (0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff\n (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff \n (gdb) monitor flash info 0",
- "title": "Blinky on Olimex"
- },
- {
- "location": "/os/tutorials/olimex/#blinky-your-hello-world-on-olimex",
- "text": "This tutorial shows you how to create, build, and run the Blinky application on an Olimex STM32-E407 board.",
- "title": "Blinky, your \"Hello World!\", on Olimex"
- },
- {
- "location": "/os/tutorials/olimex/#prerequisites",
- "text": "Meet the prerequisites listed in Project Blinky . Have a STM32-E407 development board from Olimex. Have a ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board) Have a USB A-B type cable to connect the debugger to your computer. Install the OpenOCD debugger .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/olimex/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already created a project. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n\n $cd myproj\n\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/olimex/#build-the-bootloader",
- "text": "Run the newt build boot_olimex command to build the bootloader: $ newt build boot_olimex\nBuilding target targets/boot_olimex\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling bin/targets/boot_olimex/generated/src/boot_olimex-sysflash.c\n\n ...\n\nArchiving libc_baselibc.a\nArchiving sys_flash_map.a\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/boot_olimex/app/apps/boot/boot.elf\nTarget successfully built: targets/boot_olimex",
- "title": "Build the Bootloader"
- },
- {
- "location": "/os/tutorials/olimex/#build-the-blinky-application",
- "text": "Run the newt build olimex_blinky command to build the blinky application: $ newt build olimex_blinky\nBuilding target targets/olimex_blinky\nAssembling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/arch/cortex_m4/startup_STM32F40x.s\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/sbrk.c\nCompiling apps/blinky/src/main.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nCompiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/hal_bsp.c\nCompiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/system_stm32f4xx.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/olimex_blinky",
- "title": "Build the Blinky Application"
- },
- {
- "location": "/os/tutorials/olimex/#sign-and-create-the-blinky-application-image",
- "text": "Run the newt create-image olimex_blinky 1.0.0 command to sign and create an image file for the blinky application. You may assign an arbitrary version (e.g. 1.0.0) number. $ newt create-image olimex_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky.img",
- "title": "Sign and Create the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/olimex/#connect-to-the-board",
- "text": "Configure the board to bootload from flash memory and to use USB-OTG2 for the power source. Refer to the following diagrams to locate the boot jumpers and power input select jumpers on the board. Note: The labels for the USB-OTG1 and USB-OTG2 ports on the diagram are reversed. The port labeled USB-OTG1 on the diagram is the USB-OTG2 port and the port labeled USB-OTG2 on the diagram is the USB-OTG1 port. Locate the boot jumpers on the lower right corner of the board. B1_1/B1_0 and B0_1/B0_0 are PTH jumpers to control the boot mode when a bootloader is present. These two jumpers must be moved together. The board searches for the bootloader in three places: User Flash Memory, System Memory or the Embedded SRAM. For this Blinky project, we configure the board to boot from flash by jumpering B0_0 and B1_0 . Note: The markings on the board may not always be accurate, and you should always refer to the manual for the correct positioning. Locate the Power Input Select jumpers on the lower left corner of the board. Set the Power Select jumpers to position 5 and 6 to use the USB-OTG2 port for the power source. If you would like to use a different power source, refer to the OLIMEX STM32-E407 user manual for pin specifications. Connect the USB Micro-A cable to the USB-OTG2 port on the board. Connect the JTAG connector to the JTAG/SWD interface on the board. Connect the USB A-B cable to the ARM-USB-TINY-H connector and your computer. Check that the red PWR LED lights up.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/olimex/#load-the-bootloader-and-blinky-application",
- "text": "Run the newt load boot_olimex command to load the bootloader image onto the board: $newt load -v boot_olimex\nLoading bootloader\nLoad command: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ~/dev/myproj/bin/targets/boot_olimex/app/apps/boot/boot\nSuccessfully loaded image. Note: If you are using Windows and get a no device found error, you will need to install the usb driver. Download Zadig and run it: Select Options List All Devices. Select Olimex OpenOCD JTAG ARM-USB-TINY-H from the drop down menu. Select the WinUSB driver. Click Install Driver. Run the newt load boot_olimex command again. \nRun the newt load olimex_blinky command to load the blinky application image onto the board: newt load -v olimex_blinky\nLoading app image into slot 1\nLoad command: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky\nSuccessfully loaded image. \nThe LED should be blinking! \nLet's double check that it is indeed booting from flash and making the LED blink from the image in flash. Pull the USB cable off the Olimex JTAG adaptor, severing the debug connection to the JTAG port. Next power off the Olimex board by pulling out the USB cable from the board. Wait for a couple of seconds and plug the USB cable back to the board. The LED light will start blinking again. Success! If you want to download the image to flash and open a gdb session, use newt debug blinky . Note: The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal. \nType c to continue inside the gdb session. $ newt debug blinky\n Debugging with ~/dev/myproj/hw/bsp/olimex_stm32-e407_...\n Debugging ~/dev/myproj/project/blinky/bin/blinky/blinky.elf\n GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs\n Copyright (C) 2014 Free Software Foundation, Inc.\n License GPLv3+: GNU GPL version 3 http://gnu.org/licenses/gpl.html \n ...\n (info)\n ...\n target state: halted\n target halted due to debug-request, current mode: Thread\n xPSR: 0x01000000 pc: 0x08000250 msp: 0x10010000\n Info : accepting gdb connection from 3333\n Info : device id = 0x10036413\n Info : flash size = 1024kbytes\n Reset_Handler () at startup_STM32F40x.s:199\n 199 ldr r1, =__etext\n (gdb) If you want to erase the flash and load the image again you may use the following commands from within gdb. flash erase_sector 0 0 x tells it to erase sectors 0 through x. When you ask it to display (in hex notation) the contents of the sector starting at location 'lma,' you should see all f's. The memory location 0x8000000 is the start or origin of the flash memory contents and is specified in the olimex_stm32-e407_devboard.ld linker script. The flash memory locations is specific to the processor. (gdb) monitor flash erase_sector 0 0 4\n erased sectors 0 through 4 on flash bank 0 in 2.296712s\n (gdb) monitor mdw 0x08000000 16\n 0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff\n (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff\n (0x08000000: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff\n (0x08000020: ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff \n (gdb) monitor flash info 0",
- "title": "Load the Bootloader and Blinky Application"
- },
- {
- "location": "/os/tutorials/nRF52/",
- "text": "Blinky, your \"Hello World!\", on a nRF52 Development Kit\n\n\nThis tutorial shows you how to create, build, and run the Blinky application on a nRF52 Development Kit.\n\n\n\nNote that there are several versions of the nRF52 Development Kit in the market. The boards tested with this tutorial are listed under \"Prerequisites\".\n\n\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Blinky\n.\n\n\nHave a nRF52 Development Kit (one of the following)\n\n\nNordic nRF52-DK Development Kit - PCA 10040\n\n\nRigado BMD-300 Evaluation Kit - BMD-300-EVAL-ES\n\n\n\n\n\n\nInstall the \nSegger JLINK Software and documentation pack\n.\n\n\n\n\nThis tutorial uses the Nordic nRF52-DK board.\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already have a project created. \n\n\nRun the following commands to create a new project:\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\nCreate the Targets\n\n\nCreate two targets for the nRF52-DK board - one for the bootloader and one for the Blinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nnrf52_boot\n:\n\n\n\nNote: This tutorial uses the Nordic nRF52-DK board. You must specify the correct bsp for the board you are using. \n \n\n\n\n\nFor the Nordic Dev Kit choose @apache-mynewt-core/hw/bsp/nrf52dk instead (in the highlighted lines)\n\n\nFor the Rigado Eval Kit choose @apache-mynewt-core/hw/bsp/bmd300eval instead (in the highlighted lines)\n\n\n\n\n$ newt target create nrf52_boot\n$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot\n\n$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n\n$ newt target set nrf52_boot build_profile=optimized\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Blinky application. We name the target \nnrf52_blinky\n.\n\n\n$ newt target create nrf52_blinky\n$ newt target set nrf52_blinky app=apps/blinky\n\n$ newt target set nrf52_blinky bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n\n$ newt target set nrf52_blinky build_profile=debug\n\n\n\n\n\n\nYou can run the \nnewt target show\n command to verify the target settings:\n\n\n$ newt target show \ntargets/nrf52_blinky\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=debug\ntargets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\n\n\nBuild the Target Executables\n\n\nRun the \nnewt build nrf52_boot\n command to build the bootloader:\n\n\n$ newt build nrf52_boot\nBuilding target targets/nrf52_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot\n\n\n\n\n\n\nRun the \nnewt build nrf52_blinky\n command to build the Blinky application:\n\n\n$ newt build nrf52_blinky\nBuilding target targets/nrf52_blinky\nAssembling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s\nCompiling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/sbrk.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nAssembling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52.s\nCompiling apps/blinky/src/main.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/nrf52_blinky\n\n\n\n\n\n\n\nSign and Create the Blinky Application Image\n\n\nRun the \nnewt create-image nrf52_blinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\n$ newt create-image nrf52_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img\n\n\n\n\n\n\n\nConnect to the Board\n\n\n\n\nConnect a micro-USB cable from your computer to the micro-USB port on the nRF52-DK board.\n\n\nTurn the power on the board to ON. You should see the green LED light up on the board.\n\n\n\n\nLoad the Bootloader and the Blinky Application Image\n\n\nRun the \nnewt load nrf52_boot\n command to load the bootloader onto the board: \n\n\n$ newt load nrf52_boot\nLoading bootloader\n$\n\n\n\n\n\n\nRun the \nnewt load nrf52_blinky\n command to load the Blinky application image onto the board.\n\n\n$ newt load nrf52_blinky\nLoading app image into slot 1\n\n\n\n\n\nYou should see the LED1 on the board blink!\n\n\nNote: If the LED does not blink, try resetting your board.\n\n\n\n\nIf you want to erase the flash and load the image again, you can run \nJLinkExe\n to issue an \nerase\n command.\n\n\nNote:\n On Windows: Run the \njlink\n command with the same arguments from a Windows Command Prompt terminal.\n\n\n\n\n$ JLinkExe -device nRF52 -speed 4000 -if SWD\nSEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)\nDLL version V5.12c, compiled Apr 21 2016 16:05:45\n\nConnecting to J-Link via USB...O.K.\nFirmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17\nHardware version: V1.00\nS/N: 682863966\nVTref = 3.300V\n\n\nType \nconnect\n to establish a target connection, \n?\n for help\nJ-Link\nerase\nCortex-M4 identified.\nErasing device (0;?i?)...\nComparing flash [100%] Done.\nErasing flash [100%] Done.\nVerifying flash [100%] Done.\nJ-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)\nErasing done.\nJ-Link\nexit\n$",
- "title": "Blinky on nRF52 DK"
- },
- {
- "location": "/os/tutorials/nRF52/#blinky-your-hello-world-on-a-nrf52-development-kit",
- "text": "This tutorial shows you how to create, build, and run the Blinky application on a nRF52 Development Kit. Note that there are several versions of the nRF52 Development Kit in the market. The boards tested with this tutorial are listed under \"Prerequisites\".",
- "title": "Blinky, your \"Hello World!\", on a nRF52 Development Kit"
- },
- {
- "location": "/os/tutorials/nRF52/#prerequisites",
- "text": "Meet the prerequisites listed in Project Blinky . Have a nRF52 Development Kit (one of the following) Nordic nRF52-DK Development Kit - PCA 10040 Rigado BMD-300 Evaluation Kit - BMD-300-EVAL-ES Install the Segger JLINK Software and documentation pack . This tutorial uses the Nordic nRF52-DK board.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/nRF52/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already have a project created. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/nRF52/#build-the-target-executables",
- "text": "Run the newt build nrf52_boot command to build the bootloader: $ newt build nrf52_boot\nBuilding target targets/nrf52_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot \nRun the newt build nrf52_blinky command to build the Blinky application: $ newt build nrf52_blinky\nBuilding target targets/nrf52_blinky\nAssembling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s\nCompiling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/sbrk.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nAssembling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52.s\nCompiling apps/blinky/src/main.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/nrf52_blinky",
- "title": "Build the Target Executables"
- },
- {
- "location": "/os/tutorials/nRF52/#sign-and-create-the-blinky-application-image",
- "text": "Run the newt create-image nrf52_blinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. $ newt create-image nrf52_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img",
- "title": "Sign and Create the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/nRF52/#connect-to-the-board",
- "text": "Connect a micro-USB cable from your computer to the micro-USB port on the nRF52-DK board. Turn the power on the board to ON. You should see the green LED light up on the board.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/nRF52/#load-the-bootloader-and-the-blinky-application-image",
- "text": "Run the newt load nrf52_boot command to load the bootloader onto the board: $ newt load nrf52_boot\nLoading bootloader\n$ \nRun the newt load nrf52_blinky command to load the Blinky application image onto the board. $ newt load nrf52_blinky\nLoading app image into slot 1 You should see the LED1 on the board blink! Note: If the LED does not blink, try resetting your board. If you want to erase the flash and load the image again, you can run JLinkExe to issue an erase command. Note: On Windows: Run the jlink command with the same arguments from a Windows Command Prompt terminal. $ JLinkExe -device nRF52 -speed 4000 -if SWD\nSEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)\nDLL version V5.12c, compiled Apr 21 2016 16:05:45\n\nConnecting to J-Link via USB...O.K.\nFirmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17\nHardware version: V1.00\nS/N: 682863966\nVTref = 3.300V\n\n\nType connect to establish a target connection, ? for help\nJ-Link erase\nCortex-M4 identified.\nErasing device (0;?i?)...\nComparing flash [100%] Done.\nErasing flash [100%] Done.\nVerifying flash [100%] Done.\nJ-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)\nErasing done.\nJ-Link exit\n$",
- "title": "Load the Bootloader and the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/rbnano2/",
- "text": "Blinky, your \"Hello World!\", on RedBear Nano 2\n\n\nThis tutorial shows you how to create, build and run the Blinky application on a RedBear Nano 2 board.\n\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Blinky\n.\n\n\nHave a RedBear Nano 2 board. \n\n\nInstall a patched version of OpenOCD 0.10.0 described in \nInstall OpenOCD\n.\n\n\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already have a project created. \n\n\nRun the following commands to create a new project:\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\nCreate the Targets\n\n\nCreate two targets for the RedBear Nano 2 board - one for the bootloader and one for the Blinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nrbnano2_boot\n:\n\n\n$ newt target create rbnano2_boot\n$ newt target set rbnano2_boot app=@apache-mynewt-core/apps/boot\n$ newt target set rbnano2_boot bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n$ newt target set rbnano2_boot build_profile=optimized\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Blinky application. We name the target \nnrf52_blinky\n.\n\n\n$ newt target create rbnano2_blinky\n$ newt target set rbnano2_blinky app=apps/blinky\n$ newt target set rbnano2_blinky bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n$ newt target set rbnano2_blinky build_profile=debug\n\n\n\n\n\n\nYou can run the \nnewt target show\n command to verify the target settings:\n\n\n$ newt target show \ntargets/rbnano2_blinky\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n build_profile=debug\ntargets/rbnano2_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n build_profile=optimized\n\n\n\n\n\n\n\nBuild the Target Executables\n\n\nRun the \nnewt build rbnano2_boot\n command to build the bootloader:\n\n\n$newt build rbnano2_boot\nBuilding target targets/rbnano2_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\n ...\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/rbnano2_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/rbnano2_boot\n\n\n\n\n\n\nRun the \nnewt build rbnano2_blinky\n command to build the Blinky application:\n\n\n$newt build rbnano2_blinky\nBuilding target targets/rbnano2_blinky\nAssembling repos/apache-mynewt-core/hw/bsp/rb-nano2/src/arch/cortex_m4/gcc_startup_nrf52_split.s\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/bsp/rb-nano2/src/sbrk.c\nCompiling apps/blinky/src/main.c\n\n ...\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/rbnano2_blinky\n\n\n\n\n\n\n\nSign and Create the Blinky Application Image\n\n\nRun the \nnewt create-image rbnano2_blinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\n$newt create-image rbnano2_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky.img\n\n\n\n\n\n\n\nConnect to the Board\n\n\nConnect the RedBear Nano 2 USB to a USB port on your computer. You should see an orange LED light up on the board.\n\n\nLoad the Bootloader\n\n\nRun the \nnewt load rbnano2_boot\n command to load the bootloader onto the board: \n\n\n$ newt load rbnano2_boot\nLoading bootloader\n$\n\n\n\n\n\n\n\nNote:\n On Windows platforms, if you get an \nunable to find CMSIS-DAP device\n error, you will need to download and install the mbed Windows serial port driver from \nhttps://developer.mbed.org/handbook/Windows-serial-configuration\n. Follow the instructions from the site to install the driver. Here are some additional notes about the installation:\n\n\n\n\nThe instructions indicate that the mbed Windows serial port driver is not required for Windows 10. If you are using Windows 10 and get the \nunable to find CMSIS-DAP device\n error, we recommend that you install the driver.\n\n\nIf the driver installation fails, we recommend that you unplug the board, plug it back in, and retry the installation.\n\n\n\n\nRun the \nnewt load rbnano2_boot\n command again.\n\n\n\n\nClear the Write Protection on the Flash Memory\n\n\nThe flash memory on the RedBear Nano 2 comes write protected from the factory. If you get an error loading the bootloader and you are using a brand new chip, you need to clear the write protection from the debugger and then load the bootloader again. Run the \nnewt debug rbnano2_blinky\n command and issue the following commands at the highlighted (gdb) prompts. \n\n\nNote:\n The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal.\n\n\n\n\n$newt debug rbnano2_blinky\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/rb-nano2/rb-nano2_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/rb-nano2 ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.10.0-dev-snapshot (2017-03-28-11:24)\nLicensed under GNU GPL v2\n\n ...\n\n\n(gdb) set {unsigned long}0x4001e504=2\n\n(gdb) x/1wx 0x4001e504\n\n0x4001e504:0x00000002\n\n(gdb) set {unsigned long}0x4001e50c=1\n\nInfo : SWD DPIDR 0x2ba01477\nError: Failed to read memory at 0x00009ef4\n\n(gdb) x/32wx 0x00\n\n0x0:0xffffffff0xffffffff0xffffffff0xffffffff\n0x10:0xffffffff0xffffffff0xffffffff0xffffffff\n0x20:0xffffffff0xffffffff0xffffffff0xffffffff\n0x30:0xffffffff0xffffffff0xffffffff0xffffffff\n0x40:0xffffffff0xffffffff0xffffffff0xffffffff\n0x50:0xffffffff0xffffffff0xffffffff0xffffffff\n0x60:0xffffffff0xffffffff0xffffffff0xffffffff\n0x70:0xffffffff0xffffffff0xffffffff0xffffffff\n(gdb)\n\n\n\n\n\n\n\nLoad the Blinky Application Image\n\n\n\nRun the \nnewt load rbnano2_blinky\n command to load the Blinky application image onto the board:\n\n\n$ newt load rbnano2_blinky\nLoading app image into slot 1\n\n\n\n\n\nYou should see a blue LED on the board blink!\n\n\nNote: If the LED does not blink, try resetting your board.",
- "title": "Blinky on RedBear Nano 2"
- },
- {
- "location": "/os/tutorials/rbnano2/#blinky-your-hello-world-on-redbear-nano-2",
- "text": "This tutorial shows you how to create, build and run the Blinky application on a RedBear Nano 2 board.",
- "title": "Blinky, your \"Hello World!\", on RedBear Nano 2"
- },
- {
- "location": "/os/tutorials/rbnano2/#prerequisites",
- "text": "Meet the prerequisites listed in Project Blinky . Have a RedBear Nano 2 board. Install a patched version of OpenOCD 0.10.0 described in Install OpenOCD .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/rbnano2/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already have a project created. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/rbnano2/#build-the-target-executables",
- "text": "Run the newt build rbnano2_boot command to build the bootloader: $newt build rbnano2_boot\nBuilding target targets/rbnano2_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\n ...\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/rbnano2_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/rbnano2_boot \nRun the newt build rbnano2_blinky command to build the Blinky application: $newt build rbnano2_blinky\nBuilding target targets/rbnano2_blinky\nAssembling repos/apache-mynewt-core/hw/bsp/rb-nano2/src/arch/cortex_m4/gcc_startup_nrf52_split.s\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/bsp/rb-nano2/src/sbrk.c\nCompiling apps/blinky/src/main.c\n\n ...\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/rbnano2_blinky",
- "title": "Build the Target Executables"
- },
- {
- "location": "/os/tutorials/rbnano2/#sign-and-create-the-blinky-application-image",
- "text": "Run the newt create-image rbnano2_blinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. $newt create-image rbnano2_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky.img",
- "title": "Sign and Create the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/rbnano2/#connect-to-the-board",
- "text": "Connect the RedBear Nano 2 USB to a USB port on your computer. You should see an orange LED light up on the board.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/rbnano2/#load-the-bootloader",
- "text": "Run the newt load rbnano2_boot command to load the bootloader onto the board: $ newt load rbnano2_boot\nLoading bootloader\n$ Note: On Windows platforms, if you get an unable to find CMSIS-DAP device error, you will need to download and install the mbed Windows serial port driver from https://developer.mbed.org/handbook/Windows-serial-configuration . Follow the instructions from the site to install the driver. Here are some additional notes about the installation: The instructions indicate that the mbed Windows serial port driver is not required for Windows 10. If you are using Windows 10 and get the unable to find CMSIS-DAP device error, we recommend that you install the driver. If the driver installation fails, we recommend that you unplug the board, plug it back in, and retry the installation. Run the newt load rbnano2_boot command again.",
- "title": "Load the Bootloader"
- },
- {
- "location": "/os/tutorials/rbnano2/#clear-the-write-protection-on-the-flash-memory",
- "text": "The flash memory on the RedBear Nano 2 comes write protected from the factory. If you get an error loading the bootloader and you are using a brand new chip, you need to clear the write protection from the debugger and then load the bootloader again. Run the newt debug rbnano2_blinky command and issue the following commands at the highlighted (gdb) prompts. Note: The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal. $newt debug rbnano2_blinky\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/rb-nano2/rb-nano2_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/rb-nano2 ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.10.0-dev-snapshot (2017-03-28-11:24)\nLicensed under GNU GPL v2\n\n ... (gdb) set {unsigned long}0x4001e504=2 (gdb) x/1wx 0x4001e504 0x4001e504:0x00000002 (gdb) set {unsigned long}0x4001e50c=1 Info : SWD DPIDR 0x2ba01477\nError: Failed to read memory at 0x00009ef4 (gdb) x/32wx 0x00 0x0:0xffffffff0xffffffff0xffffffff0xffffffff\n0x10:0xffffffff0xffffffff0xffffffff0xffffffff\n0x20:0xffffffff0xffffffff0xffffffff0xffffffff\n0x30:0xffffffff0xffffffff0xffffffff0xffffffff\n0x40:0xffffffff0xffffffff0xffffffff0xffffffff\n0x50:0xffffffff0xffffffff0xffffffff0xffffffff\n0x60:0xffffffff0xffffffff0xffffffff0xffffffff\n0x70:0xffffffff0xffffffff0xffffffff0xffffffff\n(gdb)",
- "title": "Clear the Write Protection on the Flash Memory"
- },
- {
- "location": "/os/tutorials/rbnano2/#load-the-blinky-application-image",
- "text": "Run the newt load rbnano2_blinky command to load the Blinky application image onto the board: $ newt load rbnano2_blinky\nLoading app image into slot 1 You should see a blue LED on the board blink! Note: If the LED does not blink, try resetting your board.",
- "title": "Load the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/",
- "text": "Blinky, your \"Hello World!\", on STM32F4-Discovery\n\n\nThis tutorial shows you how to create, build, and run the Blinky application on the STM32F4-Discovery board.\n\n\n\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Blinky\n.\n\n\nHave a STM32F4-Discovery board.\n\n\nHave a USB type A to Mini-B cable. \n\n\nInstall a patched version of OpenOCD 0.10.0 described in \nInstall OpenOCD\n. \n\n\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already have a project created. \n\n\nRun the following commands to create a new project:\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\nCreate the Targets\n\n\nCreate two targets for the STM32F4-Discovery board - one for the bootloader and one for the Blinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nstm32f4disc_boot\n:\n\n\n$ newt target create stm32f4disc_boot\n$ newt target set stm32f4disc_boot app=@apache-mynewt-core/apps/boot\n$ newt target set stm32f4disc_boot bsp=@apache-mynewt-core/hw/bsp/stm32f4discovery\n$ newt target set stm32f4disc_boot build_profile=optimized\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Blinky application. We name the target \nstm32f4disc_blinky\n:\n\n\n$ newt target create stm32f4disc_blinky\n$ newt target set stm32f4disc_blinky app=apps/blinky\n$ newt target set stm32f4disc_blinky bsp=@apache-mynewt-core/hw/bsp/stm32f4discovery\n$ newt target set stm32f4disc_blinky build_profile=debug\n\n\n\n\n\n\nYou can run the \nnewt target show\n command to verify the target settings:\n\n\n$ newt target show \ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/stm32f4disc_blinky\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/stm32f4discovery\n build_profile=debug\ntargets/stm32f4disc_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/stm32f4discovery\n build_profile=optimized\n\n\n\n\n\n\n\nBuild the Target Executables\n\n\nRun the \nnewt build stm32f4disc_boot\n command to build the bootloader:\n\n\n$ newt build stm32f4disc_boot\nBuilding target targets/stm32f4disc_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\n ...\n\nArchiving sys_flash_map.a\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/stm32f4disc_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/stm32f4disc_boot\n\n\n\n\n\n\nRun the \nnewt build stm32f4disc_blinky\n command to build the Blinky application:\n\n\n$newt build stm32f4disc_blinky\nBuilding target targets/stm32f4disc_blinky\nCompiling apps/blinky/src/main.c\nCompiling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/sbrk.c\nCompiling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/system_stm32f4xx.c\nCompiling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/hal_bsp.c\nAssembling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/arch/cortex_m4/startup_STM32F40x.s\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\n\n ...\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/stm32f4disc_blinky\n\n\n\n\n\n\n\nSign and Create the Blinky Application Image\n\n\nRun the \nnewt create-image stm32f4disc_blinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\n$newt create-image stm32f4disc_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky.img\n\n\n\n\n\n\n\nConnect to the Board\n\n\nConnect a USB type A to Mini-B cable from your computer to the port the board indicated on the diagram: \n\n\n\n\n\n\n\n\n\n\nYou should see the small PWR red LED light up.\n\n\nLoad the Bootloader and the Blinky Application Image\n\n\nRun the \nnewt load stm32f4disc_boot\n command to load the bootloader onto the board: \n\n\n$newt load stm32f4disc_boot\nLoading bootloader\n\n\n\n\n\nNote: If you are using Windows and get an \nopen failed\n or \nno device found\n error, you will need to install the usb driver. Download \nZadig\n and run it:\n\n\n\n\nSelect Options \n List All Devices.\n\n\nSelect \nSTM32 STLink\n from the drop down menu.\n\n\nSelect the \nWinUSB\n driver.\n\n\nClick Install Driver.\n\n\nRun the \nnewt load stm32f4disc_boot\n command again.\n\n\n\n\nNote: If you are running Linux and get an \nopen failed\n message, there are two common issues with this board. If you have a board produced before mid-2016, it is likely that you have an older version of the ST-LINK programmer. To correct this, open the \nrepos/apache-mynewt-core/hw/bsp/stm32f4discovery/f4discovery.cfg\n file in a text editor, and change the line:\n\n\nsource [find interface/stlink-v2-1.cfg]\n\n\n\n\n\nto:\n\n\nsource [find interface/stlink-v2.cfg]\n\n\n\n\n\nIf you receive an error like \nlibusb_open() failed with LIBUSB_ERROR_ACCESS\n, it means that your \nudev\n rules are not correctly set up for this device. You can find some example \nudev\n rules for ST-LINK programmers \nhere\n.\n\n\n\nRun the \nnewt load stm32f4disc_blinky\n command to load the Blinky application image onto the board.\n\n\n$newt load stm32f4disc_blinky\nLoading app image into slot 1\n\n\n\n\n\nYou should see the small green LD4 LED on the board blink!\n\n\nNote: If the LED does not blink, try resetting your board.\n\n\n\n\nIf you want to erase the flash and load the image again, start a debug session, and enter \nmon stm32f2x mass_erase 0\n at the gdb prompt:\n\n\nNote:\n The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal.\n\n\n\n\n$newt debug stm32f4disc_blinky\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/stm32f4discovery/stm32f4discovery_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/stm32f4discovery ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\n http://openocd.org/doc/doxygen/bugs.html\nInfo : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD\nadapter speed: 2000 kHz\nadapter_nsrst_delay: 100\nnone separate\nInfo : Unable to match requested speed 2000 kHz, using 1800 kHz\nInfo : Unable to match requested speed 2000 kHz, using 1800 kHz\nInfo : clock speed 1800 kHz\nInfo : STLINK v2 JTAG v25 API v2 SWIM v14 VID 0x0483 PID 0x374B\nInfo : using stlink api v2\nInfo : Target voltage: 2.881129\nInfo : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints\ntarget halted due to debug-request, current mode: Thread\n\n ...\n\nReading symbols from ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky.elf...done.\ntarget halted due to debug-request, current mode: Thread\nxPSR: 0x41000000 pc: 0x08021e90 psp: 0x20002290\nInfo : accepting \ngdb\n connection on tcp/3333\nInfo : device id = 0x10076413\nInfo : flash size = 1024kbytes\n0x08021e90 in __WFI () at repos/apache-mynewt-core/hw/cmsis-core/src/ext/core_cmInstr.h:342\n342 __ASM volatile (\nwfi\n);\n(gdb) mon stm32f2x mass_erase 0\nstm32x mass erase complete\nstm32x mass erase complete\n(gdb)",
- "title": "Blinky on STM32F4-Discovery"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#blinky-your-hello-world-on-stm32f4-discovery",
- "text": "This tutorial shows you how to create, build, and run the Blinky application on the STM32F4-Discovery board.",
- "title": "Blinky, your \"Hello World!\", on STM32F4-Discovery"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#prerequisites",
- "text": "Meet the prerequisites listed in Project Blinky . Have a STM32F4-Discovery board. Have a USB type A to Mini-B cable. Install a patched version of OpenOCD 0.10.0 described in Install OpenOCD .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already have a project created. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myproj\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myproj...\n Project myproj successfully created.\n $ cd myproj\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#build-the-target-executables",
- "text": "Run the newt build stm32f4disc_boot command to build the bootloader: $ newt build stm32f4disc_boot\nBuilding target targets/stm32f4disc_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\n ...\n\nArchiving sys_flash_map.a\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/stm32f4disc_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/stm32f4disc_boot \nRun the newt build stm32f4disc_blinky command to build the Blinky application: $newt build stm32f4disc_blinky\nBuilding target targets/stm32f4disc_blinky\nCompiling apps/blinky/src/main.c\nCompiling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/sbrk.c\nCompiling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/system_stm32f4xx.c\nCompiling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/hal_bsp.c\nAssembling repos/apache-mynewt-core/hw/bsp/stm32f4discovery/src/arch/cortex_m4/startup_STM32F40x.s\nCompiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c\n\n ...\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/stm32f4disc_blinky",
- "title": "Build the Target Executables"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#sign-and-create-the-blinky-application-image",
- "text": "Run the newt create-image stm32f4disc_blinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. $newt create-image stm32f4disc_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky.img",
- "title": "Sign and Create the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#connect-to-the-board",
- "text": "Connect a USB type A to Mini-B cable from your computer to the port the board indicated on the diagram: You should see the small PWR red LED light up.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/blinky_stm32f4disc/#load-the-bootloader-and-the-blinky-application-image",
- "text": "Run the newt load stm32f4disc_boot command to load the bootloader onto the board: $newt load stm32f4disc_boot\nLoading bootloader Note: If you are using Windows and get an open failed or no device found error, you will need to install the usb driver. Download Zadig and run it: Select Options List All Devices. Select STM32 STLink from the drop down menu. Select the WinUSB driver. Click Install Driver. Run the newt load stm32f4disc_boot command again. Note: If you are running Linux and get an open failed message, there are two common issues with this board. If you have a board produced before mid-2016, it is likely that you have an older version of the ST-LINK programmer. To correct this, open the repos/apache-mynewt-core/hw/bsp/stm32f4discovery/f4discovery.cfg file in a text editor, and change the line: source [find interface/stlink-v2-1.cfg] to: source [find interface/stlink-v2.cfg] If you receive an error like libusb_open() failed with LIBUSB_ERROR_ACCESS , it means that your udev rules are not correctly set up for this device. You can find some example udev rules for ST-LINK programmers here . \nRun the newt load stm32f4disc_blinky command to load the Blinky application image onto the board. $newt load stm32f4disc_blinky\nLoading app image into slot 1 You should see the small green LD4 LED on the board blink! Note: If the LED does not blink, try resetting your board. If you want to erase the flash and load the image again, start a debug session, and enter mon stm32f2x mass_erase 0 at the gdb prompt: Note: The output of the debug session below is for Mac OS and Linux platforms. On Windows, openocd and gdb are started in separate Windows Command Prompt terminals, and the terminals are automatically closed when you quit gdb. In addition, the output of openocd is logged to the openocd.log file in your project's base directory instead of the terminal. $newt debug stm32f4disc_blinky\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/stm32f4discovery/stm32f4discovery_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/stm32f4discovery ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky]\nOpen On-Chip Debugger 0.10.0\nLicensed under GNU GPL v2\nFor bug reports, read\n http://openocd.org/doc/doxygen/bugs.html\nInfo : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD\nadapter speed: 2000 kHz\nadapter_nsrst_delay: 100\nnone separate\nInfo : Unable to match requested speed 2000 kHz, using 1800 kHz\nInfo : Unable to match requested speed 2000 kHz, using 1800 kHz\nInfo : clock speed 1800 kHz\nInfo : STLINK v2 JTAG v25 API v2 SWIM v14 VID 0x0483 PID 0x374B\nInfo : using stlink api v2\nInfo : Target voltage: 2.881129\nInfo : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints\ntarget halted due to debug-request, current mode: Thread\n\n ...\n\nReading symbols from ~/dev/myproj/bin/targets/stm32f4disc_blinky/app/apps/blinky/blinky.elf...done.\ntarget halted due to debug-request, current mode: Thread\nxPSR: 0x41000000 pc: 0x08021e90 psp: 0x20002290\nInfo : accepting gdb connection on tcp/3333\nInfo : device id = 0x10076413\nInfo : flash size = 1024kbytes\n0x08021e90 in __WFI () at repos/apache-mynewt-core/hw/cmsis-core/src/ext/core_cmInstr.h:342\n342 __ASM volatile ( wfi );\n(gdb) mon stm32f2x mass_erase 0\nstm32x mass erase complete\nstm32x mass erase complete\n(gdb)",
- "title": "Load the Bootloader and the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/blinky_console/",
- "text": "Enabling The Console and Shell for Blinky\n\n\nThis tutorial shows you how to add the Console and Shell to the Blinky application and interact with it over a serial line connection.\n\n\n\nPrerequisites\n\n\n\n\nWork through one of the Blinky Tutorials to create and build a Blinky application for one of the boards.\n\n\nHave a \nserial setup\n.\n\n\n\n\n\n\nUse an Existing Project\n\n\nSince all we're doing is adding the shell and console capability to blinky, we assume \nthat you have worked through at least some of the other tutorials, and have an existing project.\nFor this example, we'll be modifying the \nblinky on nrf52\n project to enable \nthe shell and console connectivity. You can use blinky on a different board.\n\n\n\n\nModify the Dependencies and Configuration\n\n\nAdd the following dependencies to your application target's \npkg.yml\n file:\n\n\npkg.deps:\n - \n@apache-mynewt-core/sys/console/full\n\n - \n@apache-mynewt-core/sys/shell\n\n - \n@apache-mynewt-core/sys/sysinit\n\n\n\n\n\n\nThis lets the newt system know that it needs to pull in the code for the console and the shell.\n\n\nModify the system configuration settings to enable Shell and Console ticks and prompt. Add the following to your application target's \nsyscfg.yml\n file:\n\n\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n # Enable Console OS Ticks\n CONSOLE_TICKS: 1\n # Enable Console Prompt\n CONSOLE_PROMPT: 1 \n\n\n\n\n\n\n\nUse the OS Default Event Queue to Process Blinky Timer and Shell Events\n\n\nMynewt creates a main task that executes the application \nmain()\n 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 \nmain()\n can process the events in the context of the main task. \n\n\nBlinky's main.c is very simple. It only has a \nmain()\n function that executes an infinite loop to toggle the LED and sleep for one second. We will modify blinky:\n\n\n\n\nTo 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.\n\n\nTo process events from the OS default event queue inside the infinite loop in \nmain()\n.\n\n\n\n\nThis allows the main task to process both Shell events and the timer events to toggle the LED from the OS default event queue.\n\n\n\n\nModify main.c\n\n\nInitialize a os_callout timer and move the toggle code from the while loop in \nmain()\n to the event callback function. Add the following code above the \nmain()\n function:\n\n\n/* The timer callout */\n\n\nstatic\n \nstruct\n \nos_callout\n \nblinky_callout\n;\n\n\n/*\n\n\n * Event callback function for timer events. It toggles the led pin.\n\n\n */\n\n\nstatic\n \nvoid\n \ntimer_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n \n!=\n \nNULL\n);\n\n \n++g_task1_loops\n;\n \nhal_gpio_toggle\n(\ng_led_pin\n);\n\n \nos_callout_reset\n(\nblinky_callout\n, \nOS_TICKS_PER_SEC\n);\n}\n\n\nstatic\n \nvoid\n \ninit_timer\n(\nvoid\n)\n{\n \n/*\n\n\n * Initialize the callout for a timer event.\n\n\n */\n\n \nos_callout_init\n(\nblinky_callout\n, \nos_eventq_dflt_get\n(),\n \ntimer_ev_cb\n, \nNULL\n);\n\n \nos_callout_reset\n(\nblinky_callout\n, \nOS_TICKS_PER_SEC\n);\n\n}\n\n\n\n\n\nIn \nmain()\n, add the call to the \ninit_timer()\n function before the while loop and modify the while loop to process events from the OS default event queue:\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n\n \nint\n \nrc\n;\n\n\n#ifdef ARCH_sim\n\n \nmcu_sim_parse_args\n(\nargc\n, \nargv\n);\n\n#endif\n\n\n \nsysinit\n();\n\n \ng_led_pin\n \n=\n \nLED_BLINK_PIN\n;\n \nhal_gpio_init_out\n(\ng_led_pin\n, \n1\n);\n \ninit_timer\n();\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n \nassert\n(\n0\n)\n \nreturn\n \nrc\n;\n}\n\n\n\n\n\n\n\nBuild the Blinky Application Target\n\n\nWe're not going to build the bootloader here since we are assuming that you have already\nbuilt and loaded it during previous tutorials.\n\n\nRun the \nnewt build nrf52_blinky\n command to build the Blinky application:\n\n\n$ newt build nrf52_blinky\n\n ...\n\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/nrf52_blinky\n\n\n\n\n\n\n\nSign and Create the Blinky Application Image\n\n\nRun the \nnewt create-image nrf52_blinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\n$ newt create-image nrf52_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img\n\n\n\n\n\n\n\nLoad the Image\n\n\nMake 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.\n\n\nRun the \nnewt load nrf52_blinky\n command to load the Blinky application image onto the board.\n\n\n$ newt load nrf52_blinky\nLoading app image into slot 1\n\n\n\n\n\n\n\nSet Up a Serial Connection\n\n\nYou'll need a Serial connection to see the output of your program. You can reference the \nSerial Port Setup\n Tutorial for more information on setting up your serial communication.\n\n\n\n\nCommunicate with the Application\n\n\nOnce you have a connection set up, you can connect to your device as follows:\n\n\n\n\n\n\nOn Mac OS and Linux platforms, you can run \nminicom -D /dev/tty.usbserial-\nport\n -b 115200\n to connect to the console of your app. Note that on Linux, the format of the port name is \n/dev/ttyUSB\nN\n, where N is a number.\n\n\n\n\n\n\nOn Windows, you can use a terminal application such as PuTTY to connect to the device.\n\n\nIf you located your port from a MinGW terminal, the port name format is \n/dev/ttyS\nN\n, where \nN\n is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n.\n\n\nYou can also use the Windows Device Manager to locate the COM port.\n\n\n\n\n\n\n\nTo test and make sure that the Shell is running, first just hit \n:\n\n\n3534: \n\n\n\n\n\n\nYou can try some commands:\n\n\n3609: \n ?\nCommands:\n8841: echo ? prompt ticks tasks mempools\n8843: date b\n8844: \n ticks off\n Console Ticks off\n \n prompt off\n Prompt now off.\nticks on\n33383: Console Ticks on\n\n33568:\nprompt on\n39108: Prompt now on.\n39108:",
- "title": "Add Console and Shell to Blinky"
- },
- {
- "location": "/os/tutorials/blinky_console/#enabling-the-console-and-shell-for-blinky",
- "text": "This tutorial shows you how to add the Console and Shell to the Blinky application and interact with it over a serial line connection.",
- "title": "Enabling The Console and Shell for Blinky"
- },
- {
- "location": "/os/tutorials/blinky_console/#prerequisites",
- "text": "Work through one of the Blinky Tutorials to create and build a Blinky application for one of the boards. Have a serial setup .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/blinky_console/#use-an-existing-project",
- "text": "Since all we're doing is adding the shell and console capability to blinky, we assume \nthat you have worked through at least some of the other tutorials, and have an existing project.\nFor this example, we'll be modifying the blinky on nrf52 project to enable \nthe shell and console connectivity. You can use blinky on a different board.",
- "title": "Use an Existing Project"
- },
- {
- "location": "/os/tutorials/blinky_console/#modify-the-dependencies-and-configuration",
- "text": "Add the following dependencies to your application target's pkg.yml file: pkg.deps:\n - @apache-mynewt-core/sys/console/full \n - @apache-mynewt-core/sys/shell \n - @apache-mynewt-core/sys/sysinit This lets the newt system know that it needs to pull in the code for the console and the shell. Modify the system configuration settings to enable Shell and Console ticks and prompt. Add the following to your application target's syscfg.yml file: syscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n # Enable Console OS Ticks\n CONSOLE_TICKS: 1\n # Enable Console Prompt\n CONSOLE_PROMPT: 1",
- "title": "Modify the Dependencies and Configuration"
- },
- {
- "location": "/os/tutorials/blinky_console/#use-the-os-default-event-queue-to-process-blinky-timer-and-shell-events",
- "text": "Mynewt creates a main task that executes the application main() 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 main() can process the events in the context of the main task. Blinky's main.c is very simple. It only has a main() function that executes an infinite loop to toggle the LED and sleep for one second. We will modify blinky: 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. To process events from the OS default event queue inside the infinite loop in main() . This allows the main task to process both Shell events and the timer events to toggle the LED from the OS default event queue.",
- "title": "Use the OS Default Event Queue to Process Blinky Timer and Shell Events"
- },
- {
- "location": "/os/tutorials/blinky_console/#modify-mainc",
- "text": "Initialize a os_callout timer and move the toggle code from the while loop in main() to the event callback function. Add the following code above the main() function: /* The timer callout */ static struct os_callout blinky_callout ; /* * Event callback function for timer events. It toggles the led pin. */ static void timer_ev_cb ( struct os_event *ev )\n{\n assert ( ev != NULL );\n\n ++g_task1_loops ;\n hal_gpio_toggle ( g_led_pin );\n\n os_callout_reset ( blinky_callout , OS_TICKS_PER_SEC );\n} static void init_timer ( void )\n{\n /* * Initialize the callout for a timer event. */ \n os_callout_init ( blinky_callout , os_eventq_dflt_get (),\n timer_ev_cb , NULL );\n\n os_callout_reset ( blinky_callout , OS_TICKS_PER_SEC );\n\n} In main() , add the call to the init_timer() function before the while loop and modify the while loop to process events from the OS default event queue: main ( int argc , char **argv )\n{\n\n int rc ; #ifdef ARCH_sim \n mcu_sim_parse_args ( argc , argv ); #endif \n\n sysinit ();\n\n g_led_pin = LED_BLINK_PIN ;\n hal_gpio_init_out ( g_led_pin , 1 );\n init_timer ();\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n assert ( 0 )\n return rc ;\n}",
- "title": "Modify main.c"
- },
- {
- "location": "/os/tutorials/blinky_console/#build-the-blinky-application-target",
- "text": "We're not going to build the bootloader here since we are assuming that you have already\nbuilt and loaded it during previous tutorials. Run the newt build nrf52_blinky command to build the Blinky application: $ newt build nrf52_blinky\n\n ...\n\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf\nTarget successfully built: targets/nrf52_blinky",
- "title": "Build the Blinky Application Target"
- },
- {
- "location": "/os/tutorials/blinky_console/#sign-and-create-the-blinky-application-image",
- "text": "Run the newt create-image nrf52_blinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. $ newt create-image nrf52_blinky 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img",
- "title": "Sign and Create the Blinky Application Image"
- },
- {
- "location": "/os/tutorials/blinky_console/#load-the-image",
- "text": "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. Run the newt load nrf52_blinky command to load the Blinky application image onto the board. $ newt load nrf52_blinky\nLoading app image into slot 1",
- "title": "Load the Image"
- },
- {
- "location": "/os/tutorials/blinky_console/#set-up-a-serial-connection",
- "text": "You'll need a Serial connection to see the output of your program. You can reference the Serial Port Setup Tutorial for more information on setting up your serial communication.",
- "title": "Set Up a Serial Connection"
- },
- {
- "location": "/os/tutorials/blinky_console/#communicate-with-the-application",
- "text": "Once you have a connection set up, you can connect to your device as follows: On Mac OS and Linux platforms, you can run minicom -D /dev/tty.usbserial- port -b 115200 to connect to the console of your app. Note that on Linux, the format of the port name is /dev/ttyUSB N , where N is a number. On Windows, you can use a terminal application such as PuTTY to connect to the device. If you located your port from a MinGW terminal, the port name format is /dev/ttyS N , where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . You can also use the Windows Device Manager to locate the COM port. \nTo test and make sure that the Shell is running, first just hit : 3534: You can try some commands: 3609: ?\nCommands:\n8841: echo ? prompt ticks tasks mempools\n8843: date b\n8844: ticks off\n Console Ticks off\n prompt off\n Prompt now off.\nticks on\n33383: Console Ticks on\n\n33568:\nprompt on\n39108: Prompt now on.\n39108:",
- "title": "Communicate with the Application"
- },
- {
- "location": "/os/tutorials/repo/add_repos/",
- "text": "Adding Repositories to your Project\n\n\nWhat is a Repository\n\n\nA repository is a version-ed Mynewt project, which is a collection of Mynewt packages organized in a specific way for redistribution. \n\n\nWhat differentiates a repository from a Mynewt project is the presence of a\n\nrepository.yml\n file describing the repository. This will be described \nbelow. For a basic understanding of repositories you may read the \nNewt Tool Manual\n and \nHow to create repos\n.\n\n\nNote:\n For the remainder of this document we'll use the term repo as shorthand for a Mynewt repository.\n\n\nRepos are useful because they are an organized way for the community to share Mynewt packages and projects. In fact, the Mynewt-core is distributed as a repo.\n\n\n\n\nWhy does Mynewt need additional repos?\n\n\nRepos add functionality not included in the Mynewt core. New repos might be created for several reasons.\n\n\n\n\nExpertise\n. Individuals or organizations may have expertise that they want\nto share in the form of repos. For example a chip vendor may\ncreate a repo to hold the Mynewt support for their chips.\n\n\nNon-Core component\n. Some components, although very useful to Mynewt users\nare not core to all Mynewt users. These are likely candidates to be held in \ndifferent repos.\n\n\nSoftware licensing\n. Some software have licenses that make them incompatible\nwith the ASF (Apache Software Foundation) license policies. These may be \nvaluable components to some Mynewt users, but cannot be contained in the \napache-Mynewt-core\n.\n\n\n\n\n\n\nWhat Repos are in my Project\n\n\nThe list of repos used by your project are contained within the \n\nproject.yml\n file. An example can be seen by creating a new project:\n\n\n$ mkdir ~/dev\n$ cd ~/dev\n$ newt new myproj\n$ cd myproj\n\n\n\n\n\n\n\nView the \nproject.yml\n section and you will see a line describing the repos:\n\n\nproject.repositories:\n - apache-Mynewt-core\n\n\n\n\n\n \n\n\nBy default, this newly created project uses a single repo called \n\napache-Mynewt-core\n. \n\n\nIf you wish to add additional repos, you would add \nadditional lines to the \nproject.repositories\n variable like this.\n\n\nproject.repositories:\n - apache-Mynewt-core\n\n - another_repo_named_x\n\n\n\n\n\n\n\nRepo Descriptors\n\n\nIn addition to the repo name, the \nproject.yml\n file must also contain\na repo descriptor for each repository you include that gives \nnewt\n \ninformation on obtaining the repo.\n\n\nIn the same \nmyproj\n above you will see the following repo descriptor.\n\n\nrepository.apache-Mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\n\n\n\n\nA repo descriptor starts with \nrepository.\nname\n.\n. In this example, the \ndescriptor specifies the information for the \napache-Mynewt-core\n.\n\n\n\n\nThe fields within the descriptor have the following definitions:\n\n\n\n\n\n\ntype\n -- The type of code storage the repo uses. The current version\nof \nnewt\n only supports github. Future versions may support generic git or other\ncode storage mechanisms.\n\n\n\n\n\n\nvers\n -- The version of the repo to use for your project. A source\ncode repository contains many versions of the source. This field is used to \nspecify the one to use for this project. See the section on versions below \nfor a detailed description of the format of this field.\n\n\n\n\n\n\nuser\n -- The username for the repo. On github, this is the name\nafter \ngithub.com\n in the repo path. Consider the repository \n\nhttps://github.com/apache/incubator-mynewt-core\n. It has username \napache\n. \n\n\n\n\n\n\nrepo\n -- The name of the repo. On github, this is the name after\nthe username described above. Consider the repository \n\nhttps://github.com/apache/incubator-mynewt-core\n. It has path \n\nincubator-mynewt-core\n. This is a path to the source control\nand should not be confused with the name of the repo that you used in the \n\nrepository.\nname\n declaration above. That name is contained elsewhere\nwithin the repo. See Below.\n\n\n\n\n\n\n\n\nAdding Existing Repos to my Project\n\n\nTo add a new repo to your project, you have to complete two steps.\n\n\n\n\n\n\nEdit the \nproject.yml\n file and add a new repo descriptor. The previous\nsection includes information on the field required in your repo descriptor.\n\n\n\n\n\n\nEdit the \nproject/yml\n file and add a new line to the \nproject.repositories\n\nvariable with the name of the repo you are adding. \n\n\n\n\n\n\nAn example of a \nproject.yml\n file with two repositories is shown below:\n\n\nproject.name: \nmy_project\n\n\nproject.repositories:\n - apache-Mynewt-core\n - Mynewt_arduino_zero\n\n# Use github\ns distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-Mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\n# a special repo to hold hardware specific stuff for arduino zero\nrepository.Mynewt_arduino_zero:\n type: github\n vers: 1-latest\n user: runtimeco\n repo: Mynewt_arduino_zero\n\n\n\n\n\n\n\nWhat Version of the Repo to use\n\n\nMynewt repos are version-ed artifacts. They are stored in source control \nsystems like github. The repo descriptor in your \nproject.yml\n file must\nspecify the version of the repo you will accept into your project.\n\n\nFor now, we are at the beginnings of Mynewt. For testing and evaluation\nplease use \n1-latest\n in the \nvers\n field in your repo descriptor.\n\n\n vers:1-latest\n\n\n\n\n\nSee \nCreate a Repo\n for a description of the versioning system and all the possible ways to specify a version to use.\n\n\n\n\nIdentifying a Repo\n\n\nA repo contains Mynewt packages organized in a specific way and stored in one of the supported code storage methods described above. In other words, it is a Mynewt project with an additional file \nrepository.yml\n which describes the repo for use by \nnewt\n (and humans browsing them). It contains a mapping of version numbers to the actual github branches containing the source code.\n\n\nNote that the \nrepository.yml\n file lives only in the master branch of the git\nrepository. \nNewt\n will always fetch this file from the master branch and then\nuse that to determine the actual branch required depending on the version\nspecified in your \nproject.yml\n file. Special care should be taken to ensure that this file exists only in the master branch.\n\n\nHere is the \nrepository.yml\n file from the apache-Mynewt-core:\n\n\nrepo.name: apache-mynewt-core\nrepo.versions:\n \n0.0.0\n: \nmaster\n\n \n0.0.1\n: \nmaster\n\n \n0.7.9\n: \nmynewt_0_8_0_b2_tag\n\n \n0.8.0\n: \nmynewt_0_8_0_tag\n\n \n0.9.0\n: \nmynewt_0_9_0_tag\n\n \n0.9.9\n: \nmynewt_1_0_0_b1_tag\n\n \n0.9.99\n: \nmynewt_1_0_0_b2_tag\n\n \n0.9.999\n: \nmynewt_1_0_0_rc1_tag\n\n \n1.0.0\n: \nmynewt_1_0_0_tag\n\n\n \n0-latest\n: \n1.0.0\n # 1.0.0\n \n0-dev\n: \n0.0.0\n # master\n\n \n0.8-latest\n: \n0.8.0\n\n \n0.9-latest\n: \n0.9.0\n\n \n1.0-latest\n: \n1.0.0\n # 1.0.0\n\n\n\n\n\n\n\nIt contains the following:\n\n\n\n\nrepo.name\n The external name that is used to include the library in \nyour \nproject.yml\n file. This is the name you in include in the \nproject.repositories\n variable when adding this repository to your project.\n\n\nrepo.versions\n A description of what versions to give the user depending \non the settings in their \nproject.yml\n file. \n\n\n\n\n\n\nRepo Version\n\n\nThe repo version number resolves to an actual git branch depending on the mapping specified in \nrepository.yml\n for that repo. The version field argument in your \nproject.yml\n file supports multiple formats for flexibility:\n\n\nmajor_num\n.\nminor_num\n.\nrevision_num\n\n\n\n\n\n\nor\n\n\nmajor_num\n.\nminor_num\n-\nstability string\n\n\n\n\n\n\nor \n\n\nmajor_num\n-\nstability string\n\n\n\n\n\n\n\n\nThe stability string can be one of 3 pre-defined stability values.\n\n\n\n\nstable -- A stable release version of the repository\n\n\ndev -- A development version from the repository\n\n\nlatest -- The latest from the repository\n\n\n\n\nIn your \nproject.yml\n file you can specify different combinations of \nthe version number and stability value. For example:\n\n\n\n\n1-latest\n -- The latest version with major number 1\n\n\n1.2-stable\n -- The latest stable version with major and minor number 1.2\n\n\n1.2-dev\n -- The development version from 1.2\n\n\n1.1.1\n -- a specific version 1.1.1\n\n\n\n\nYou cannot specify a stability string with a fully numbered version, e.g.\n\n\n1.2.8-stable\n\n\n\n\n\n\n\nRepo Versions Available\n\n\nA \nrepository.yml\n file contains information to match a version request\ninto a git branch to fetch for your project.\n\n\nIt's up to the repository maintainer to map these to branches of the \nrepository. For example, let's say in a fictitious repository the following are \ndefined.\n\n\nrepo.versions:\n \n0.8.0\n: \nxxx_branch_0_8_0\n\n \n1.0.0\n: \nxxx_branch_1_0_0\n\n \n1.0.2\n: \nxxx_branch_1_0_2\n\n \n1.1.1\n: \nxxx_branch_1_1_0\n\n \n1.1.2\n: \nxxx_branch_1_1_2\n\n \n1.2.0\n: \nxxx_branch_1_2_0\n\n \n1.2.1\n: \nxxx_branch_1_2_1\n\n \n1.2-dev\n: \n1.2.1\n\n \n1-dev\n: \n1.2-dev\n\n \n1.2-stable\n: \n1.2.0\n\n \n0-latest\n: \n0.8.0\n\n \n1-latest\n: \n1-dev\n\n ....\n\n\n\n\n\nWhen the \nproject.yml\n file asks for \n1.2-stable\n it is resolved to version\n\n1.2.0\n (perhaps \n1.2.1\n is not stable yet), which in turn resolves to a specific\nbranch \nxxx_branch_1_2_0\n. This is the branch that \nnewt\n fetches into \nyour project. \n\n\nNote:\n Make sure a repo version exists in the \nrepository.yml\n file of a repo you wish to add. Otherwise Newt will not be able to resolve the version and will fail to fetch the repo into your project.\n\n\n\n\nHow to find out what Repos are available for Mynewt components\n\n\nCurrently, there is no \nnewt\n command to locate/search Mynewt package \nrepositories. However, since the \nnewt\n tool supports only github, \nsearching github by keyword is a satisfactory option until a search \ntool is created.\n\n\nWhen searching github, recall that a Mynewt repository must \nhave a \nrepository.yml\n file in its root directory. If you don't see \nthat file, it's not a Mynewt repository and can't be included in your \nproject via the newt tool. \n\n\nOnce you find a repository, the github URL and \nrepository.yml\n file\nshould give you all the information to add it to your \nproject.yml\n file.",
- "title": "toc"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#adding-repositories-to-your-project",
- "text": "",
- "title": "Adding Repositories to your Project"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#what-is-a-repository",
- "text": "A repository is a version-ed Mynewt project, which is a collection of Mynewt packages organized in a specific way for redistribution. What differentiates a repository from a Mynewt project is the presence of a repository.yml file describing the repository. This will be described \nbelow. For a basic understanding of repositories you may read the Newt Tool Manual and How to create repos . Note: For the remainder of this document we'll use the term repo as shorthand for a Mynewt repository. Repos are useful because they are an organized way for the community to share Mynewt packages and projects. In fact, the Mynewt-core is distributed as a repo.",
- "title": "What is a Repository"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#why-does-mynewt-need-additional-repos",
- "text": "Repos add functionality not included in the Mynewt core. New repos might be created for several reasons. Expertise . Individuals or organizations may have expertise that they want\nto share in the form of repos. For example a chip vendor may\ncreate a repo to hold the Mynewt support for their chips. Non-Core component . Some components, although very useful to Mynewt users\nare not core to all Mynewt users. These are likely candidates to be held in \ndifferent repos. Software licensing . Some software have licenses that make them incompatible\nwith the ASF (Apache Software Foundation) license policies. These may be \nvaluable components to some Mynewt users, but cannot be contained in the apache-Mynewt-core .",
- "title": "Why does Mynewt need additional repos?"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#what-repos-are-in-my-project",
- "text": "The list of repos used by your project are contained within the project.yml file. An example can be seen by creating a new project: $ mkdir ~/dev\n$ cd ~/dev\n$ newt new myproj\n$ cd myproj View the project.yml section and you will see a line describing the repos: project.repositories:\n - apache-Mynewt-core By default, this newly created project uses a single repo called apache-Mynewt-core . If you wish to add additional repos, you would add \nadditional lines to the project.repositories variable like this. project.repositories:\n - apache-Mynewt-core - another_repo_named_x",
- "title": "What Repos are in my Project"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#repo-descriptors",
- "text": "In addition to the repo name, the project.yml file must also contain\na repo descriptor for each repository you include that gives newt \ninformation on obtaining the repo. In the same myproj above you will see the following repo descriptor. repository.apache-Mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core A repo descriptor starts with repository. name . . In this example, the \ndescriptor specifies the information for the apache-Mynewt-core . The fields within the descriptor have the following definitions: type -- The type of code storage the repo uses. The current version\nof newt only supports github. Future versions may support generic git or other\ncode storage mechanisms. vers -- The version of the repo to use for your project. A source\ncode repository contains many versions of the source. This field is used to \nspecify the one to use for this project. See the section on versions below \nfor a detailed description of the format of this field. user -- The username for the repo. On github, this is the name\nafter github.com in the repo path. Consider the repository https://github.com/apache/incubator-mynewt-core . It has username apache . repo -- The name of the repo. On github, this is the name after\nthe username described above. Consider the repository https://github.com/apache/incubator-mynewt-core . It has path incubator-mynewt-core . This is a path to the source control\nand should not be confused with the name of the repo that you used in the repository. name declaration above. That name is contained elsewhere\nwithin the repo. See Below.",
- "title": "Repo Descriptors"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#adding-existing-repos-to-my-project",
- "text": "To add a new repo to your project, you have to complete two steps. Edit the project.yml file and add a new repo descriptor. The previous\nsection includes information on the field required in your repo descriptor. Edit the project/yml file and add a new line to the project.repositories \nvariable with the name of the repo you are adding. An example of a project.yml file with two repositories is shown below: project.name: my_project \n\nproject.repositories:\n - apache-Mynewt-core\n - Mynewt_arduino_zero\n\n# Use github s distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-Mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\n# a special repo to hold hardware specific stuff for arduino zero\nrepository.Mynewt_arduino_zero:\n type: github\n vers: 1-latest\n user: runtimeco\n repo: Mynewt_arduino_zero",
- "title": "Adding Existing Repos to my Project"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#what-version-of-the-repo-to-use",
- "text": "Mynewt repos are version-ed artifacts. They are stored in source control \nsystems like github. The repo descriptor in your project.yml file must\nspecify the version of the repo you will accept into your project. For now, we are at the beginnings of Mynewt. For testing and evaluation\nplease use 1-latest in the vers field in your repo descriptor. vers:1-latest See Create a Repo for a description of the versioning system and all the possible ways to specify a version to use.",
- "title": "What Version of the Repo to use"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#identifying-a-repo",
- "text": "A repo contains Mynewt packages organized in a specific way and stored in one of the supported code storage methods described above. In other words, it is a Mynewt project with an additional file repository.yml which describes the repo for use by newt (and humans browsing them). It contains a mapping of version numbers to the actual github branches containing the source code. Note that the repository.yml file lives only in the master branch of the git\nrepository. Newt will always fetch this file from the master branch and then\nuse that to determine the actual branch required depending on the version\nspecified in your project.yml file. Special care should be taken to ensure that this file exists only in the master branch. Here is the repository.yml file from the apache-Mynewt-core: repo.name: apache-mynewt-core\nrepo.versions:\n 0.0.0 : master \n 0.0.1 : master \n 0.7.9 : mynewt_0_8_0_b2_tag \n 0.8.0 : mynewt_0_8_0_tag \n 0.9.0 : mynewt_0_9_0_tag \n 0.9.9 : mynewt_1_0_0_b1_tag \n 0.9.99 : mynewt_1_0_0_b2_tag \n 0.9.999 : mynewt_1_0_0_rc1_tag \n 1.0.0 : mynewt_1_0_0_tag \n\n 0-latest : 1.0.0 # 1.0.0\n 0-dev : 0.0.0 # master\n\n 0.8-latest : 0.8.0 \n 0.9-latest : 0.9.0 \n 1.0-latest : 1.0.0 # 1.0.0 It contains the following: repo.name The external name that is used to include the library in \nyour project.yml file. This is the name you in include in the project.repositories variable when adding this repository to your project. repo.versions A description of what versions to give the user depending \non the settings in their project.yml file.",
- "title": "Identifying a Repo"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#repo-version",
- "text": "The repo version number resolves to an actual git branch depending on the mapping specified in repository.yml for that repo. The version field argument in your project.yml file supports multiple formats for flexibility: major_num . minor_num . revision_num or major_num . minor_num - stability string or major_num - stability string The stability string can be one of 3 pre-defined stability values. stable -- A stable release version of the repository dev -- A development version from the repository latest -- The latest from the repository In your project.yml file you can specify different combinations of \nthe version number and stability value. For example: 1-latest -- The latest version with major number 1 1.2-stable -- The latest stable version with major and minor number 1.2 1.2-dev -- The development version from 1.2 1.1.1 -- a specific version 1.1.1 You cannot specify a stability string with a fully numbered version, e.g. 1.2.8-stable",
- "title": "Repo Version"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#repo-versions-available",
- "text": "A repository.yml file contains information to match a version request\ninto a git branch to fetch for your project. It's up to the repository maintainer to map these to branches of the \nrepository. For example, let's say in a fictitious repository the following are \ndefined. repo.versions:\n 0.8.0 : xxx_branch_0_8_0 \n 1.0.0 : xxx_branch_1_0_0 \n 1.0.2 : xxx_branch_1_0_2 \n 1.1.1 : xxx_branch_1_1_0 \n 1.1.2 : xxx_branch_1_1_2 \n 1.2.0 : xxx_branch_1_2_0 \n 1.2.1 : xxx_branch_1_2_1 \n 1.2-dev : 1.2.1 \n 1-dev : 1.2-dev \n 1.2-stable : 1.2.0 \n 0-latest : 0.8.0 \n 1-latest : 1-dev \n .... When the project.yml file asks for 1.2-stable it is resolved to version 1.2.0 (perhaps 1.2.1 is not stable yet), which in turn resolves to a specific\nbranch xxx_branch_1_2_0 . This is the branch that newt fetches into \nyour project. Note: Make sure a repo version exists in the repository.yml file of a repo you wish to add. Otherwise Newt will not be able to resolve the version and will fail to fetch the repo into your project.",
- "title": "Repo Versions Available"
- },
- {
- "location": "/os/tutorials/repo/add_repos/#how-to-find-out-what-repos-are-available-for-mynewt-components",
- "text": "Currently, there is no newt command to locate/search Mynewt package \nrepositories. However, since the newt tool supports only github, \nsearching github by keyword is a satisfactory option until a search \ntool is created. When searching github, recall that a Mynewt repository must \nhave a repository.yml file in its root directory. If you don't see \nthat file, it's not a Mynewt repository and can't be included in your \nproject via the newt tool. Once you find a repository, the github URL and repository.yml file\nshould give you all the information to add it to your project.yml file.",
- "title": "How to find out what Repos are available for Mynewt components"
- },
- {
- "location": "/os/tutorials/repo/upgrade_repo/",
- "text": "Upgrade a repo\n\n\nIn order to upgrade a previously installed repository, the \"newt upgrade\" command should be issued:\n\n\n$ newt upgrade\n\n\n\n\n\n\n\nNewt upgrade will look at the current desired version in \nproject.yml\n, \nand compare it to the version in \nproject.state\n. If these two differ, it \nwill upgrade the dependency. Upgrade works not just for the dependency \nin \nproject.yml\n, but for all the sub-dependencies that they might have.\n\n\nIf you have changed any settings in the \nproject.yml\n file, you should run \n\nnewt upgrade\n to ensure that your repos are all up to date with the versions \nspecified in your \nproject.yml\n file.",
- "title": "Upgrade a Repo"
- },
- {
- "location": "/os/tutorials/repo/upgrade_repo/#upgrade-a-repo",
- "text": "In order to upgrade a previously installed repository, the \"newt upgrade\" command should be issued: $ newt upgrade Newt upgrade will look at the current desired version in project.yml , \nand compare it to the version in project.state . If these two differ, it \nwill upgrade the dependency. Upgrade works not just for the dependency \nin project.yml , but for all the sub-dependencies that they might have. If you have changed any settings in the project.yml file, you should run newt upgrade to ensure that your repos are all up to date with the versions \nspecified in your project.yml file.",
- "title": "Upgrade a repo"
- },
- {
- "location": "/os/tutorials/repo/create_repo/",
- "text": "Create a Repo out of a Project\n\n\nIn order to create a repository out of a project, all you need to do is create a \n\nrepository.yml\n file, and check it into the master branch of your project.\n\n\nNOTE:\n Currently only github source control service is supported by our \npackage management system, but support for plain git is planned for a future\nversion.\n\n\nThe \nrepository.yml\n defines all versions of the repository and the corresponding \nsource control tags that these versions correspond to. As an example, if the \n\nrepository.yml\n file has the following content, it means there is one version \nof the apache-mynewt-core operating system available, which is \n0.0.0\n (implying we \nhaven't released yet!). Such a version number corresponds to the \"develop\" branch \nin this repository. \n0-latest\n would also resolved to this same \n0.0.0\n version. \nThe next section explains the versioning system a bit more.\n\n\n$ more repository.yml\nrepo.name: apache-mynewt-core\nrepo.versions:\n \n0.0.0\n: \ndevelop\n\n \n0-latest\n: \n0.0.0\n\n\n\n\n\n\n\n\nWhere should the repository.yml file be?\n\n\nThe \nrepository.yml\n file lives only in the master branch of the git\nrepository. \nNewt\n will always fetch this file from the master branch and then\nuse that to resolve the actual branch required depending on the version\nspecified in the project. \nSpecial care should be taken to ensure that this\nfile exists only in the master branch.\n\n\nHere is the \nrepository.yml\n file from a certain snapshot of apache-Mynewt-core:\n\n\nrepo.name: apache-mynewt-core\nrepo.versions:\n \n0.7.9\n: \nMynewt_0_8_0_b2_tag\n\n \n0-latest\n: \n0.7.9\n\n \n0.8-latest\n: \n0.7.9\n\n\n\n\n\n\n\n\nIt contains the following:\n\n\n\n\nrepo.name\n The external name that is used to include the library in \nyour \nproject.yml\n file. This is the name you include in the \nproject.repositories\n \nvariable when adding this repository to your project.\n\n\nrepo.versions\n A description of what versions to give the user depending \non the settings in their \nproject.yml\n file. See below for a thorough description\non versioning. Its a flexible mapping between version numbers and git branches.\n\n\n\n\n\n\nRepo Version Specification\n\n\nThe version field argument for a repo has the following format:\n\n\nmajor_num\n.\nminor_num\n.\nrevision_num\n\n\n\n\n\n\nor\n\n\nmajor_num\n.\nminor_num\n-\nstability string\n\n\n\n\n\n\nor \n\n\nmajor_num\n-\nstability string\n\n\n\n\n\n\n\n\nThe stability string can be one of 3 pre-defined stability values.\n\n\n\n\nstable\n -- A stable release version of the repository\n\n\ndev\n -- A development version from the repository\n\n\nlatest\n -- The latest from the repository\n\n\n\n\nIn your \nproject.yml\n file you can specify different combinations of \nthe version number and stability value. For example:\n\n\n\n\n1-latest\n -- The latest version with major number 1\n\n\n1.2-stable\n -- The latest stable version with major and minor number 1.2\n\n\n1.2-dev\n -- The development version from 1.2\n\n\n1.1.1\n -- a specific version 1.1.1\n\n\n\n\nYou \ncannot\n specify a stability string with a fully numbered version, e.g.\n\n\n1.2.8-stable\n\n\n\n\n\n\n\nRepo Version Resolution\n\n\nA \nrepository.yml\n file contains information to match this version request\ninto a git branch to fetch for your project.\n\n\nIt's up to you as the repository maintainer to map these to actual github branches \nof the repository. For example, let's say in a fictitious repository the \nfollowing are defined.\n\n\nrepo.versions:\n \n0.8.0\n: \nxxx_branch_0_8_0\n\n \n1.0.0\n: \nxxx_branch_1_0_0\n\n \n1.0.2\n: \nxxx_branch_1_0_2\n\n \n1.1.1\n: \nxxx_branch_1_1_0\n\n \n1.1.2\n: \nxxx_branch_1_1_2\n\n \n1.2.0\n: \nxxx_branch_1_2_0\n\n \n1.2.1\n: \nxxx_branch_1_2_1\n\n \n1.2-dev\n: \n1.2.1\n\n \n1-dev\n: \n1.2-dev\n\n \n1.2-stable\n: \n1.2.0\n\n \n0-latest\n: \n0.8.0\n\n \n1-latest\n: \n1-dev\n\n ....\n\n\n\n\n\nWhen the \nproject.yml\n file asks for \n1.2-stable\n it will be resolved to version\n\n1.2.0\n which in turn will resolve to a specific branch \nxxx_branch_1_2_0\n.\n\nThis is the branch that \nnewt\n will then fetch into the project with that \nproject.yml\n file.\n\n\n\n\nDependencies on other repos\n\n\nRepositories can also have dependencies on other repositories. These \ndependencies should be listed out on a per-tag basis. So, for example, \nif apache-mynewt-core were to depend on sterlys-little-repo, you might \nhave the following directives in the repository.yml:\n\n\ndevelop.repositories:\n sterlys-little-repo:\n type: github\n vers: 0.8-latest\n user: sterlinghughes\n repo: sterlys-little-repo\n\n\n\n\n\n\n\nThis would tell Newt that for anything that resolves to the develop \nbranch, this repository requires the sterlys-little-repo repository. \n\n\nDependencies are resolved circularly by the newt tool, and every \ndependent repository is placed as a sibling in the repos directory. \nCurrently, if two repositories have the same name, they will conflict \nand bad things will happen.\n\n\nWhen a repository is installed to the repos/ directory, the current \nversion of that repository is written to the \nproject.state\n file. The \nproject state file contains the currently installed version of any given \nrepository. This way, the current set of repositories can be recreated \nfrom the \nproject.state\n file reliably, whereas the \nproject.yml\n file can \nhave higher level directives (i.e. include 0.8-stable.)\n\n\nResolving dependencies\n\n\nAt the moment, all dependencies must match, otherwise newt will provide \nan error. As an example, if you have a set of dependencies such that:\n\n\napache-mynewt-core depends on sterlys-little-repo 0.6-stable\napache-mynewt-core depends on sterlys-big-repo 0.5.1\nsterlys-big-repo-0.5.1 depends on sterlys-little-repo 0.6.2\n\n\n\n\n\n\n\nwhere 0.6-stable is 0.6.3, the newt tool will try and resolve the dependency to \nsterlys-little-repo. It will notice that there are two conflicting \nversions of the same repository, and not perform installation.\n\n\nIn the future Newt will be smarter about loading in all dependencies, \nand then looking to satisfy those dependencies to the best match of all \npotential options.",
- "title": "Turn project into a Repo"
- },
- {
- "location": "/os/tutorials/repo/create_repo/#create-a-repo-out-of-a-project",
- "text": "In order to create a repository out of a project, all you need to do is create a repository.yml file, and check it into the master branch of your project. NOTE: Currently only github source control service is supported by our \npackage management system, but support for plain git is planned for a future\nversion. The repository.yml defines all versions of the repository and the corresponding \nsource control tags that these versions correspond to. As an example, if the repository.yml file has the following content, it means there is one version \nof the apache-mynewt-core operating system available, which is 0.0.0 (implying we \nhaven't released yet!). Such a version number corresponds to the \"develop\" branch \nin this repository. 0-latest would also resolved to this same 0.0.0 version. \nThe next section explains the versioning system a bit more. $ more repository.yml\nrepo.name: apache-mynewt-core\nrepo.versions:\n 0.0.0 : develop \n 0-latest : 0.0.0",
- "title": "Create a Repo out of a Project"
- },
- {
- "location": "/os/tutorials/repo/create_repo/#where-should-the-repositoryyml-file-be",
- "text": "The repository.yml file lives only in the master branch of the git\nrepository. Newt will always fetch this file from the master branch and then\nuse that to resolve the actual branch required depending on the version\nspecified in the project. Special care should be taken to ensure that this\nfile exists only in the master branch. Here is the repository.yml file from a certain snapshot of apache-Mynewt-core: repo.name: apache-mynewt-core\nrepo.versions:\n 0.7.9 : Mynewt_0_8_0_b2_tag \n 0-latest : 0.7.9 \n 0.8-latest : 0.7.9 It contains the following: repo.name The external name that is used to include the library in \nyour project.yml file. This is the name you include in the project.repositories \nvariable when adding this repository to your project. repo.versions A description of what versions to give the user depending \non the settings in their project.yml file. See below for a thorough description\non versioning. Its a flexible mapping between version numbers and git branches.",
- "title": "Where should the repository.yml file be?"
- },
- {
- "location": "/os/tutorials/repo/create_repo/#repo-version-specification",
- "text": "The version field argument for a repo has the following format: major_num . minor_num . revision_num or major_num . minor_num - stability string or major_num - stability string The stability string can be one of 3 pre-defined stability values. stable -- A stable release version of the repository dev -- A development version from the repository latest -- The latest from the repository In your project.yml file you can specify different combinations of \nthe version number and stability value. For example: 1-latest -- The latest version with major number 1 1.2-stable -- The latest stable version with major and minor number 1.2 1.2-dev -- The development version from 1.2 1.1.1 -- a specific version 1.1.1 You cannot specify a stability string with a fully numbered version, e.g. 1.2.8-stable",
- "title": "Repo Version Specification"
- },
- {
- "location": "/os/tutorials/repo/create_repo/#repo-version-resolution",
- "text": "A repository.yml file contains information to match this version request\ninto a git branch to fetch for your project. It's up to you as the repository maintainer to map these to actual github branches \nof the repository. For example, let's say in a fictitious repository the \nfollowing are defined. repo.versions:\n 0.8.0 : xxx_branch_0_8_0 \n 1.0.0 : xxx_branch_1_0_0 \n 1.0.2 : xxx_branch_1_0_2 \n 1.1.1 : xxx_branch_1_1_0 \n 1.1.2 : xxx_branch_1_1_2 \n 1.2.0 : xxx_branch_1_2_0 \n 1.2.1 : xxx_branch_1_2_1 \n 1.2-dev : 1.2.1 \n 1-dev : 1.2-dev \n 1.2-stable : 1.2.0 \n 0-latest : 0.8.0 \n 1-latest : 1-dev \n .... When the project.yml file asks for 1.2-stable it will be resolved to version 1.2.0 which in turn will resolve to a specific branch xxx_branch_1_2_0 . \nThis is the branch that newt will then fetch into the project with that project.yml file.",
- "title": "Repo Version Resolution"
- },
- {
- "location": "/os/tutorials/repo/create_repo/#dependencies-on-other-repos",
- "text": "Repositories can also have dependencies on other repositories. These \ndependencies should be listed out on a per-tag basis. So, for example, \nif apache-mynewt-core were to depend on sterlys-little-repo, you might \nhave the following directives in the repository.yml: develop.repositories:\n sterlys-little-repo:\n type: github\n vers: 0.8-latest\n user: sterlinghughes\n repo: sterlys-little-repo This would tell Newt that for anything that resolves to the develop \nbranch, this repository requires the sterlys-little-repo repository. Dependencies are resolved circularly by the newt tool, and every \ndependent repository is placed as a sibling in the repos directory. \nCurrently, if two repositories have the same name, they will conflict \nand bad things will happen. When a repository is installed to the repos/ directory, the current \nversion of that repository is written to the project.state file. The \nproject state file contains the currently installed version of any given \nrepository. This way, the current set of repositories can be recreated \nfrom the project.state file reliably, whereas the project.yml file can \nhave higher level directives (i.e. include 0.8-stable.)",
- "title": "Dependencies on other repos"
- },
- {
- "location": "/os/tutorials/repo/create_repo/#resolving-dependencies",
- "text": "At the moment, all dependencies must match, otherwise newt will provide \nan error. As an example, if you have a set of dependencies such that: apache-mynewt-core depends on sterlys-little-repo 0.6-stable\napache-mynewt-core depends on sterlys-big-repo 0.5.1\nsterlys-big-repo-0.5.1 depends on sterlys-little-repo 0.6.2 where 0.6-stable is 0.6.3, the newt tool will try and resolve the dependency to \nsterlys-little-repo. It will notice that there are two conflicting \nversions of the same repository, and not perform installation. In the future Newt will be smarter about loading in all dependencies, \nand then looking to satisfy those dependencies to the best match of all \npotential options.",
- "title": "Resolving dependencies"
- },
- {
- "location": "/os/tutorials/repo/private_repo/",
- "text": "Accessing a private repository\n\n\nTo access a private repository, newt needs to be configured with one of the following:\n\n\n\n\nAccess token for the repository\n\n\nBasic auth login and password for the user\n\n\n\n\nNOTE:\n To create a github access token, see \n\nhttps://help.github.com/articles/creating-an-access-token-for-command-line-use/\n\n\nThere are two ways to specify this information, as shown below. In\nthese examples, both a token and a login/password are specified, but you\nonly need to specify one of these.\n\n\n1. project.yml (probably world-readable and therefore not secure):\n\n\n repository.my-private-repo:\n type: github\n vers: 0-dev\n user: owner-of-repo\n repo: repo-name\n\n token: \n8ab6433f8971b05c2a9c3341533e8ddb754e404e\n\n\n login: githublogin\n\n password: githubpassword\n\n\n\n\n\n2. $HOME/.newt/repos.yml\n\n\n repository.my-private-repo:\n\n token: \n8ab6433f8971b05c2a9c3341533e8ddb754e404e\n\n\n login: githublogin\n\n password: githubpassword\n\n\n\n\n\nIf both a token and a login+password are specified, newt uses the token.\nIf both the project.yml file and the private repos.yml file specify\nsecurity credentials, newt uses the project.yml settings.\n\n\nNOTE:\n When newt downloads the actual repo content, as\nopposed to just the repository.yml file, it does not use the same\nmechanism. Instead, it invokes the git command line tool. This is an\nannoyance because the user cannot use the same access token for all git\noperations. This is something that will be fixed in the future.",
- "title": "Access a private Repo"
- },
- {
- "location": "/os/tutorials/repo/private_repo/#accessing-a-private-repository",
- "text": "To access a private repository, newt needs to be configured with one of the following: Access token for the repository Basic auth login and password for the user NOTE: To create a github access token, see \nhttps://help.github.com/articles/creating-an-access-token-for-command-line-use/ There are two ways to specify this information, as shown below. In\nthese examples, both a token and a login/password are specified, but you\nonly need to specify one of these. 1. project.yml (probably world-readable and therefore not secure): repository.my-private-repo:\n type: github\n vers: 0-dev\n user: owner-of-repo\n repo: repo-name token: 8ab6433f8971b05c2a9c3341533e8ddb754e404e login: githublogin password: githubpassword 2. $HOME/.newt/repos.yml repository.my-private-repo: token: 8ab6433f8971b05c2a9c3341533e8ddb754e404e login: githublogin password: githubpassword If both a token and a login+password are specified, newt uses the token.\nIf both the project.yml file and the private repos.yml file specify\nsecurity credentials, newt uses the project.yml settings. NOTE: When newt downloads the actual repo content, as\nopposed to just the repository.yml file, it does not use the same\nmechanism. Instead, it invokes the git command line tool. This is an\nannoyance because the user cannot use the same access token for all git\noperations. This is something that will be fixed in the future.",
- "title": "Accessing a private repository"
- },
- {
- "location": "/os/tutorials/project-slinky/",
- "text": "Project Slinky\n\n\nThe goal of the project is to use a sample application called \"Slinky\" included in the Mynewt repository to enable remote communications with a device running the Mynewt OS. The protocol for remote communications is called newt manager (newtmgr). \n\n\nIf you have an existing project using a target that does not use the Slinky application and you wish to add newtmgr functionality to it, check out the tutorial titled \nEnable newtmgr in any app\n. \n\n\nAvailable Tutorials\n\n\nTutorials are available for the following boards:\n\n\n\n\nSlinky on a simulated device\n. This is supported on Mac OS and Linux platforms.\n\n\nSlinky on a nRF52\n.\n\n\nSlinky on an Olimex\n.\n\n\n\n\n\nPrerequisites\n\n\nEnsure that you meet the following prerequisites before continuing with this tutorial:\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a computer to build a Mynewt application and connect to the board over USB.\n\n\nHave a Micro-USB cable to connect the board and the computer.\n\n\nHave a \nserial port setup\n.\n\n\nInstall the newt tool and the toolchains (See \nBasic Setup\n).\n\n\nInstall the \nnewtmgr tool\n.\n\n\nRead the Mynewt OS \nConcepts\n section.\n\n\nCreate a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or kn\now how to as explained in \nCreating Your First Project\n.\n\n\n\n\nOverview of Steps\n\n\n\n\nInstall dependencies.\n\n\nDefine the bootloader and Slinky application target for the target board.\n\n\nBuild the bootloader target.\n\n\nBuild the Slinky application target and create an application image.\n\n\nSet a up serial connection with the targets.\n\n\nCreate a connection profile using the newtmgr tool.\n\n\nUse the newtmgr tool to communicate with the targets.",
- "title": "toc"
- },
- {
- "location": "/os/tutorials/project-slinky/#project-slinky",
- "text": "The goal of the project is to use a sample application called \"Slinky\" included in the Mynewt repository to enable remote communications with a device running the Mynewt OS. The protocol for remote communications is called newt manager (newtmgr). If you have an existing project using a target that does not use the Slinky application and you wish to add newtmgr functionality to it, check out the tutorial titled Enable newtmgr in any app .",
- "title": "Project Slinky"
- },
- {
- "location": "/os/tutorials/project-slinky/#available-tutorials",
- "text": "Tutorials are available for the following boards: Slinky on a simulated device . This is supported on Mac OS and Linux platforms. Slinky on a nRF52 . Slinky on an Olimex .",
- "title": "Available Tutorials"
- },
- {
- "location": "/os/tutorials/project-slinky/#prerequisites",
- "text": "Ensure that you meet the following prerequisites before continuing with this tutorial: Have Internet connectivity to fetch remote Mynewt components. Have a computer to build a Mynewt application and connect to the board over USB. Have a Micro-USB cable to connect the board and the computer. Have a serial port setup . Install the newt tool and the toolchains (See Basic Setup ). Install the newtmgr tool . Read the Mynewt OS Concepts section. Create a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or kn\now how to as explained in Creating Your First Project .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/project-slinky/#overview-of-steps",
- "text": "Install dependencies. Define the bootloader and Slinky application target for the target board. Build the bootloader target. Build the Slinky application target and create an application image. Set a up serial connection with the targets. Create a connection profile using the newtmgr tool. Use the newtmgr tool to communicate with the targets.",
- "title": "Overview of Steps"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/",
- "text": "Project Sim Slinky\n\n\nThis tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for a simulated device. This is supported on Mac OS and Linux platforms.\n\n\n\n\nPrerequisites\n\n\nMeet the prerequisites listed in \nProject Slinky\n.\n\n\nCreating a new project\n\n\nInstructions for creating a project are located in the \nBasic Setup\n section of the \nMynewt Documentation\n\n\nWe will list only the steps here for brevity. We will name the project \nslinky\n.\n\n\n$ newt new slinky\nDownloading project skeleton from apache/incubator-mynewt-blinky...\n...\nInstalling skeleton in slink...\nProject slinky successfully created\n$ cd slinky\n$newt install\napache-mynewt-core\n\n\n\n\n\nSetting up your target build\n\n\nCreate a target for \nslinky\n using the native bsp. We will list only the steps and suppress the tool output here for brevity.\n\n\n $ newt target create sim_slinky\n $ newt target set sim_slinky bsp=@apache-mynewt-core/hw/bsp/native\n $ newt target set sim_slinky build_profile=debug\n $ newt target set sim_slinky app=@apache-mynewt-core/apps/slinky\n\n\n\n\n\nBuilding Your target\n\n\nTo build your target, use \nnewt build\n. When complete, an executable file\nis created.\n\n\n $ newt build sim_slinky \n Building target targets/sim_slinky\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\n Compiling repos/apache-mynewt-core/boot/split/src/split.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\n Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aesni.c\n Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\n Compiling repos/apache-mynewt-core/boot/split/src/split_config.c\n Compiling repos/apache-mynewt-core/apps/slinky/src/main.c\n\n ...\n\n Archiving util_crc.a\n Archiving util_mem.a\n Linking ~/dev/slinky/bin/targets/sim_slinky/app/apps/slinky/slinky.elf\n Target successfully built: targets/sim_slinky\n\n\n\n\n\nRun the target\n\n\nRun the executable you have build for the simulated environment. The serial port name on which the simulated target is connected is shown in the output when mynewt slinky starts.\n\n\n $ ~/dev/slinky/bin/targets/sim_slinky/app/apps/slinky/slinky.elf\n uart0 at /dev/ttys005\n\n\n\n\n\n\n\nIn this example, the slinky app opened up a com port \n/dev/ttys005\n for communications with newtmgr. \n\n\nNOTE:\n This application will block. You will need to open a new console (or execute this in another console) to continue the tutorial.*\n\n\n\n\nSetting up a connection profile\n\n\nYou will now set up a connection profile using \nnewtmgr\n for the serial port connection and start communicating with the simulated remote device.\n\n\n $ newtmgr conn add sim1 type=serial connstring=/dev/ttys005\n Connection profile sim1 successfully added\n $ newtmgr conn show\n Connection profiles: \n sim1: type=serial, connstring=\n/dev/ttys005\n\n\n\n\n\n\nExecuting newtmgr commands with the target\n\n\nYou can now use connection profile \nsim1\n to talk to the running sim_slinky.\nAs an example, we will query the running mynewt OS for the usage of its \nmemory pools. \n\n\n $ newtmgr -c sim1 mpstat\n Return Code = 0\n name blksz cnt free min\n msys_1 292 12 10 10\n\n\n\n\n\nAs a test command, you can send an arbitrary string to the target and it\nwill echo that string back in a response to newtmgr.\n\n\n $ newtmgr -c sim1 echo \nHello Mynewt\n\n Hello Mynewt\n\n\n\n\n\nIn addition to these, you can also examine running tasks, statistics, \nlogs, image status (not on sim), and configuration.",
- "title": "Slinky on sim device"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#project-sim-slinky",
- "text": "This tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for a simulated device. This is supported on Mac OS and Linux platforms.",
- "title": "Project Sim Slinky"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#prerequisites",
- "text": "Meet the prerequisites listed in Project Slinky .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#creating-a-new-project",
- "text": "Instructions for creating a project are located in the Basic Setup section of the Mynewt Documentation We will list only the steps here for brevity. We will name the project slinky . $ newt new slinky\nDownloading project skeleton from apache/incubator-mynewt-blinky...\n...\nInstalling skeleton in slink...\nProject slinky successfully created\n$ cd slinky\n$newt install\napache-mynewt-core",
- "title": "Creating a new project"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#setting-up-your-target-build",
- "text": "Create a target for slinky using the native bsp. We will list only the steps and suppress the tool output here for brevity. $ newt target create sim_slinky\n $ newt target set sim_slinky bsp=@apache-mynewt-core/hw/bsp/native\n $ newt target set sim_slinky build_profile=debug\n $ newt target set sim_slinky app=@apache-mynewt-core/apps/slinky",
- "title": "Setting up your target build"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#building-your-target",
- "text": "To build your target, use newt build . When complete, an executable file\nis created. $ newt build sim_slinky \n Building target targets/sim_slinky\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\n Compiling repos/apache-mynewt-core/boot/split/src/split.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\n Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\n Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aesni.c\n Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\n Compiling repos/apache-mynewt-core/boot/split/src/split_config.c\n Compiling repos/apache-mynewt-core/apps/slinky/src/main.c\n\n ...\n\n Archiving util_crc.a\n Archiving util_mem.a\n Linking ~/dev/slinky/bin/targets/sim_slinky/app/apps/slinky/slinky.elf\n Target successfully built: targets/sim_slinky",
- "title": "Building Your target"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#run-the-target",
- "text": "Run the executable you have build for the simulated environment. The serial port name on which the simulated target is connected is shown in the output when mynewt slinky starts. $ ~/dev/slinky/bin/targets/sim_slinky/app/apps/slinky/slinky.elf\n uart0 at /dev/ttys005 In this example, the slinky app opened up a com port /dev/ttys005 for communications with newtmgr. NOTE: This application will block. You will need to open a new console (or execute this in another console) to continue the tutorial.*",
- "title": "Run the target"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#setting-up-a-connection-profile",
- "text": "You will now set up a connection profile using newtmgr for the serial port connection and start communicating with the simulated remote device. $ newtmgr conn add sim1 type=serial connstring=/dev/ttys005\n Connection profile sim1 successfully added\n $ newtmgr conn show\n Connection profiles: \n sim1: type=serial, connstring= /dev/ttys005",
- "title": "Setting up a connection profile"
- },
- {
- "location": "/os/tutorials/project-sim-slinky/#executing-newtmgr-commands-with-the-target",
- "text": "You can now use connection profile sim1 to talk to the running sim_slinky.\nAs an example, we will query the running mynewt OS for the usage of its \nmemory pools. $ newtmgr -c sim1 mpstat\n Return Code = 0\n name blksz cnt free min\n msys_1 292 12 10 10 As a test command, you can send an arbitrary string to the target and it\nwill echo that string back in a response to newtmgr. $ newtmgr -c sim1 echo Hello Mynewt \n Hello Mynewt In addition to these, you can also examine running tasks, statistics, \nlogs, image status (not on sim), and configuration.",
- "title": "Executing newtmgr commands with the target"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/",
- "text": "Project Slinky using the Nordic nRF52 Board\n\n\nThis tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for a Nordic nRF52 board.\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Slinky\n. \n\n\nHave a Nordic nRF52-DK board. \n\n\nInstall the \nSegger JLINK Software and documentation pack\n.\n\n\n\n\nCreate a New Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already have a project created or completed the \nSim Slinky\n tutorial. \n\n\nRun the following commands to create a new project. We name the project \nslinky\n. \n\n\n$ newt new slinky\nDownloading project skeleton from apache/incubator-mynewt-blinky...\n...\nInstalling skeleton in slink...\nProject slinky successfully created\n$ cd slinky\n$newt install \napache-mynewt-core\n\n\n\n\n\n\n\n Create the Targets\n\n\nCreate two targets for the nRF52-DK board - one for the bootloader and one for the Slinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nnrf52_boot\n.\n\n\n$ newt target create nrf52_boot\n$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_boot build_profile=optimized\n$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Slinky application. We name the target \nnrf52_slinky\n.\n\n\n$ newt target create nrf52_slinky\n$ newt target set nrf52_slinky bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_slinky build_profile=debug\n$ newt target set nrf52_slinky app=@apache-mynewt-core/apps/slinky\n\n\n\n\n\n\n\nBuild the Targets\n\n\nRun the \nnewt build nrf52_boot\n command to build the bootloader:\n\n\n$ newt build nrf52-boot\nBuilding target targets/nrf52_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot\n\n\n\n\n\n\n\nRun the \nnewt build nrf52_slinky\n command to build the Slinky application:\n\n\n$newt build nrf52_slinky\nBuilding target targets/nrf52_slinky\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/split/src/split.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/boot/split/src/split_config.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aesni.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/apps/slinky/src/main.c\n\n ...\n\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/nrf52_slinky/app/apps/slinky/slinky.elf\nTarget successfully built: targets/nrf52_slinky\n\n\n\n\n\n\n\nSign and Create the Slinky Application Image\n\n\nRun the \nnewt create-image nrf52_slinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\n$ newt create-image nrf52_slinky 1.0.0\nApp image succesfully generated: ~/dev/slinky/bin/targets/nrf52_slinky/app/apps/slinky/slinky.img\n$\n\n\n\n\n\n\n\nConnect to the Board\n\n\n\n\nConnect a micro-USB cable from your computer to the micro-USB port on the nRF52-DK board.\n\n\nTurn the power on the board to ON. You should see the green LED light up on the board.\n\n\n\n\n\n\nLoad the Bootloader and the Slinky Application Image\n\n\nRun the \nnewt load nrf52_boot\n command to load the bootloader onto the board:\n\n\n$ newt load nrf52_boot\nLoading bootloader\n$\n\n\n\n\n\n\nRun the \nnewt load nrf52_slinky\n command to load the Slinky application image onto the board:\n\n\n$ newt load nrf52_slinky\nLoading app image into slot 1\n$\n\n\n\n\n\n\n\nConnect Newtmgr with the Board using a Serial Connection\n\n\nSet up a serial connection from your computer to the nRF52-DK board (See \nSerial Port Setup\n). \n\n\nLocate the port, in the /dev directory on your computer, that the serial connection uses. The format of the port name is platform dependent:\n\n\n\n\nMac OS uses the format \ntty.usbserial-\nsome identifier\n.\n\n\nLinux uses the format \nTTYUSB\nN\n, where \nN\n is a number. For example, TTYUSB2.\n\n\n\n\nMinGW on Windows uses the format \nttyS\nN\n, where \nN\n is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n. \n\n\nYou can also use the Windows Device Manager to find the COM port number.\n\n\n\n\n\n\n\n\n$ ls /dev/tty*usbserial*\n/dev/tty.usbserial-1d11\n$\n\n\n\n\n\n\n\nSetup a newtmgr connection profile for the serial port. For our example, the port is \n/dev/tty.usbserial-1d11\n. \n\n\nRun the \nnewtmgr conn add\n command to define a newtmgr connection profile for the serial port. We name the connection profile \nnrf52serial\n. \n\n\nNote\n: \n\n\n\n\nYou will need to replace the \nconnstring\n with the specific port for your serial connection. \n\n\nOn Windows, you must specify \nCOM\nN+1\n for the connstring if \n/dev/ttyS\nN\n is the serial port.\n\n\n\n\n\n\n$ newtmgr conn add nrf52serial type=serial connstring=/dev/tty.usbserial-1d11\nConnection profile nrf52serial successfully added\n$\n\n\n\n\n\n\nYou can run the \nnewt conn show\n command to see all the newtmgr connection profiles:\n\n\n$ newtmgr conn show\nConnection profiles:\n nrf52serial: type=serial, connstring=\n/dev/tty.usbserial-1d11\n\n sim1: type=serial, connstring=\n/dev/ttys012\n\n$\n\n\n\n\n\n\n\nUse Newtmgr to Query the Board\n\n\nRun some newtmgr commands to query and receive responses back from the board (See the \nNewt Manager Guide\n for more information on the newtmgr commands). \n\n\nRun the \nnewtmgr echo hello -c nrf52serial\n command. This is the simplest command that requests the board to echo back the text. \n\n\n$ newtmgr echo hello -c nrf52serial \nhello\n$\n\n\n\n\n\n\nRun the \nnewtmgr image list -c nrf52serial\n command to list the images on the board:\n\n\n$ newtmgr image list -c nrf52serial \nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: f411a55d7a5f54eb8880d380bf47521d8c41ed77fd0a7bd5373b0ae87ddabd42\nSplit status: N/A\n$\n\n\n\n\n\n\nRun the \nnewtmgr taskstat -c nrf52serial\n command to display the task statistics on the board:\n\n\n$ newtmgr taskstat -c nrf52serial\nReturn Code = 0\n task pri tid runtime csw stksz stkuse last_checkin next_checkin\n task1 8 2 0 1751 192 110 0 0\n task2 9 3 0 1751 64 31 0 0\n idle 255 0 224081 2068 64 32 0 0\n main 127 1 3 29 1024 365 0 0\n$",
- "title": "Slinky on Nordic nRF52"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#project-slinky-using-the-nordic-nrf52-board",
- "text": "This tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for a Nordic nRF52 board.",
- "title": "Project Slinky using the Nordic nRF52 Board"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#prerequisites",
- "text": "Meet the prerequisites listed in Project Slinky . Have a Nordic nRF52-DK board. Install the Segger JLINK Software and documentation pack .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#create-a-new-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already have a project created or completed the Sim Slinky tutorial. Run the following commands to create a new project. We name the project slinky . $ newt new slinky\nDownloading project skeleton from apache/incubator-mynewt-blinky...\n...\nInstalling skeleton in slink...\nProject slinky successfully created\n$ cd slinky\n$newt install \napache-mynewt-core",
- "title": "Create a New Project"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#build-the-targets",
- "text": "Run the newt build nrf52_boot command to build the bootloader: $ newt build nrf52-boot\nBuilding target targets/nrf52_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot Run the newt build nrf52_slinky command to build the Slinky application: $newt build nrf52_slinky\nBuilding target targets/nrf52_slinky\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/split/src/split.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/boot/split/src/split_config.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aesni.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/apps/slinky/src/main.c\n\n ...\n\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/nrf52_slinky/app/apps/slinky/slinky.elf\nTarget successfully built: targets/nrf52_slinky",
- "title": "Build the Targets"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#sign-and-create-the-slinky-application-image",
- "text": "Run the newt create-image nrf52_slinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. $ newt create-image nrf52_slinky 1.0.0\nApp image succesfully generated: ~/dev/slinky/bin/targets/nrf52_slinky/app/apps/slinky/slinky.img\n$",
- "title": "Sign and Create the Slinky Application Image"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#connect-to-the-board",
- "text": "Connect a micro-USB cable from your computer to the micro-USB port on the nRF52-DK board. Turn the power on the board to ON. You should see the green LED light up on the board.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#load-the-bootloader-and-the-slinky-application-image",
- "text": "Run the newt load nrf52_boot command to load the bootloader onto the board: $ newt load nrf52_boot\nLoading bootloader\n$ \nRun the newt load nrf52_slinky command to load the Slinky application image onto the board: $ newt load nrf52_slinky\nLoading app image into slot 1\n$",
- "title": "Load the Bootloader and the Slinky Application Image"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#connect-newtmgr-with-the-board-using-a-serial-connection",
- "text": "Set up a serial connection from your computer to the nRF52-DK board (See Serial Port Setup ). Locate the port, in the /dev directory on your computer, that the serial connection uses. The format of the port name is platform dependent: Mac OS uses the format tty.usbserial- some identifier . Linux uses the format TTYUSB N , where N is a number. For example, TTYUSB2. MinGW on Windows uses the format ttyS N , where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . You can also use the Windows Device Manager to find the COM port number. $ ls /dev/tty*usbserial*\n/dev/tty.usbserial-1d11\n$ Setup a newtmgr connection profile for the serial port. For our example, the port is /dev/tty.usbserial-1d11 . Run the newtmgr conn add command to define a newtmgr connection profile for the serial port. We name the connection profile nrf52serial . Note : You will need to replace the connstring with the specific port for your serial connection. On Windows, you must specify COM N+1 for the connstring if /dev/ttyS N is the serial port. $ newtmgr conn add nrf52serial type=serial connstring=/dev/tty.usbserial-1d11\nConnection profile nrf52serial successfully added\n$ \nYou can run the newt conn show command to see all the newtmgr connection profiles: $ newtmgr conn show\nConnection profiles:\n nrf52serial: type=serial, connstring= /dev/tty.usbserial-1d11 \n sim1: type=serial, connstring= /dev/ttys012 \n$",
- "title": "Connect Newtmgr with the Board using a Serial Connection"
- },
- {
- "location": "/os/tutorials/project-nrf52-slinky/#use-newtmgr-to-query-the-board",
- "text": "Run some newtmgr commands to query and receive responses back from the board (See the Newt Manager Guide for more information on the newtmgr commands). Run the newtmgr echo hello -c nrf52serial command. This is the simplest command that requests the board to echo back the text. $ newtmgr echo hello -c nrf52serial \nhello\n$ \nRun the newtmgr image list -c nrf52serial command to list the images on the board: $ newtmgr image list -c nrf52serial \nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: f411a55d7a5f54eb8880d380bf47521d8c41ed77fd0a7bd5373b0ae87ddabd42\nSplit status: N/A\n$ \nRun the newtmgr taskstat -c nrf52serial command to display the task statistics on the board: $ newtmgr taskstat -c nrf52serial\nReturn Code = 0\n task pri tid runtime csw stksz stkuse last_checkin next_checkin\n task1 8 2 0 1751 192 110 0 0\n task2 9 3 0 1751 64 31 0 0\n idle 255 0 224081 2068 64 32 0 0\n main 127 1 3 29 1024 365 0 0\n$",
- "title": "Use Newtmgr to Query the Board"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/",
- "text": "Project Slinky Using Olimex Board\n\n\nThis tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for an Olimex STM-E407 board.\n\n\n\nPrerequisites\n\n\n\n\nMeet the prerequisites listed in \nProject Slinky\n.\n\n\nHave a STM32-E407 development board from Olimex. \n\n\nHave a ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board)\n\n\nHave a USB A-B type cable to connect the debugger to your computer. \n\n\nHave a USB to TTL Serial Cable with female wiring harness.\n\n\nInstall the \nOpenOCD debugger\n.\n\n\n\n\nCreate a New Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \ncreate the targets\n if you already have a project created or completed the \nSim Slinky\n tutorial.\n\n\n$ newt new slinky\nDownloading project skeleton from apache/incubator-mynewt-blinky...\n...\nInstalling skeleton in slink...\nProject slink successfully created\n$ cd slinky\n$newt install\napache-mynewt-core\n\n\n\n\n\n\n\n Create the Targets\n\n\nCreate two targets for the STM32-E407 board - one for the bootloader and one for the Slinky application.\n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nstm32_boot\n.\n\n\n$ newt target create stm32_boot\n$ newt target set stm32_bootr bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard\n$ newt target set stm32_boot build_profile=optimized\n$ newt target set stm32_boot target.app=@apache-mynewt-core/apps/boot\n\n\n\n\n\n\nRun the following \nnewt target\n commands to create a target for the Slinky application. We name the target \nstm32_slinky\n.\n\n\n$ newt target create stm32_slinky\n$ newt target set stm32_slinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard\n$ newt target set stm32_slinky build_profile=debug\n$ newt target set stm32_slinky app=@apache-mynewt-core/apps/slinky\n\n\n\n\n\n\n\nBuild the Targets\n\n\nRun the \nnewt build stm32_boot\n command to build the bootloader:\n\n\n$ newt build stm32_boot\nBuilding target targets/stm32_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/stm32_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/stm32_boot\n$\n\n\n\n\n\n\nRun the \nnewt build stm32_slinky\n command to build the Slinky application:\n\n\n$newt build stm32_slinky\nBuilding target targets/stm32_slinky\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/split/src/split.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/slinky/src/main.c\n\n ...\n\nArchiving util_crc.a\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/stm32_slinky/app/apps/slinky/slinky.elf\nTarget successfully built: targets/stm32_slinky\n$\n\n\n\n\n\n\n\nSign and Create the Slinky Application Image\n\n\nRun the \nnewt create-image stm32_slinky 1.0.0\n command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image.\n\n\ncreate-image stm32_slinky 1.0.0\nApp image succesfully generated: ~/dev/slinky/bin/targets/stm32_slinky/app/apps/slinky/slinky.img\n$\n\n\n\n\n\n\n\nConnect to the Board\n\n\n\n\nConnect the USB A-B type cable to the ARM-USB-TINY-H debugger connector. \n\n\nConnect the ARM-USB-Tiny-H debugger connector to your computer and the board.\n\n\nConnect the USB Micro-A cable to the USB-OTG2 port on the board.\n\n\nSet the Power Sel jumper on the board to pins 5 and 6 to select USB-OTG2 as the power source. If you would like to use a different power source, refer to the \nOLIMEX STM32-E407 user manual\n for pin specifications.\n\n\n\n\nYou should see a red LED light up on the board. \n\n\n\n\nLoad the Bootloader and the Slinky Application Image\n\n\nRun the \nnewt load stm32_boot\n command to load the bootloader onto the board:\n\n\n$ newt load stm32_boot\nLoading bootloader\n$\n\n\n\n\n\n\nNote: If you are using Windows and get a \nno device found\n error, you will need to install the usb driver. Download \nZadig\n and run it:\n\n\n\n\nSelect Options \n List All Devices.\n\n\nSelect \nOlimex OpenOCD JTAG ARM-USB-TINY-H\n from the drop down menu.\n\n\nSelect the \nWinUSB\n driver.\n\n\nClick Install Driver.\n\n\nRun the \nnewt load stm32_boot\n command again.\n\n\n\n\n\nRun the \nnewt load stm32_slinky\n command to load the Slinky application image onto the board:\n\n\n$ newt load stm32_slinky\nLoading app image into slot 1\n$\n\n\n\n\n\n\n\nConnect Newtmgr with the Board using a Serial Connection\n\n\nLocate the PC6/USART6_TX (pin 3), PC7/USART6_RX (pin 4), and GND (pin 2) of the UEXT connector on the Olimex board. More information on the UEXT connector can be found at \nhttps://www.olimex.com/Products/Modules/UEXT/\n. The schematic of the board can be found at \nhttps://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407_sch.pdf\n for reference.\n\n\n\n\n\n\nConnect the female RX pin of the USB-TTL serial cable to the TX (Pin 3) of the UEXT connector on the board.\n\n\nConnect the female TX pin of the USB-TTL serial cable to the RX (Pin 4) of the UEXT connector on the board.\n\n\nConnect the GND pin of the USB-TTL serial cable to the GND (Pin 2) of the UEXT connector on the board.\n\n\n\n\n\nLocate the port, in the /dev directory on your computer, that the serial connection uses. The format of the port name is platform dependent:\n\n\n\n\nMac OS uses the format \ntty.usbserial-\nsome identifier\n.\n\n\nLinux uses the format \nTTYUSB\nN\n, where \nN\n is a number. For example, TTYUSB2.\n\n\n\n\nMinGW on Windows uses the format \nttyS\nN\n, where \nN\n is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n.\n\n\nYou can also use the Windows Device Manager to find the COM port number.\n\n\n\n\n\n\n\n\n$ ls /dev/tty*usbserial*\n/dev/tty.usbserial-1d13\n$\n\n\n\n\n\n\nSetup a newtmgr connection profile for the serial port. For our example, the port is \n/dev/tty.usbserial-1d13\n.\n\n\nRun the \nnewtmgr conn add\n command to define a newtmgr connection profile for the serial port. We name the connection profile \nstm32serial\n. \n\n\nNote\n:\n\n\n\n\nYou will need to replace the \nconnstring\n with the specific port for your serial connection.\n\n\nOn Windows, you must specify \nCOM\nN+1\n for the connstring if \n/dev/ttyS\nN\n is the serial port.\n\n\n\n\n\n\n$ newtmgr conn add stm32serial type=serial connstring=/dev/tty.usbserial-1d13\nConnection profile stm32serial successfully added\n$\n\n\n\n\n\n\nYou can run the \nnewt conn show\n command to see all the newtmgr connection profiles:\n\n\n$ newtmgr conn show\nConnection profiles:\n stm32serial: type=serial, connstring=\n/dev/tty.usbserial-1d13\n\n sim1: type=serial, connstring=\n/dev/ttys012\n\n$\n\n\n\n\n\n\n\nUse Newtmgr to Query the Board\n\n\nRun some newtmgr commands to query and receive responses back from the board (See the \nNewt Manager Guide\n for more information on the newtmgr commands).\n\n\nRun the \nnewtmgr echo hello -c stm32serial\n command. This is the simplest command that requests the board to echo back the\n text.\n\n\n$ newtmgr echo hello -c stm32serial\nhello\n$\n\n\n\n\n\n\nRun the \nnewtmgr image list -c stm32serial\n command to list the images on the board:\n\n\n$ newtmgr image list -c stm32serial\nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: 9cf8af22b1b573909a8290a90c066d4e190407e97680b7a32243960ec2bf3a7f\nSplit status: N/A\n$\n\n\n\n\n\n\nRun the \nnewtmgr taskstat -c stm32serial\n command to display the task statistics on the board:\n\n\n$ newtmgr taskstat -c stm32serial\nReturn Code = 0\n task pri tid runtime csw stksz stkuse last_checkin next_checkin\n task1 8 2 0 90 192 110 0 0\n task2 9 3 0 90 64 31 0 0\n idle 255 0 89460 89463 64 26 0 0\n main 127 1 4 26 1024 368 0 0\n$",
- "title": "Slinky on Olimex"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#project-slinky-using-olimex-board",
- "text": "This tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for an Olimex STM-E407 board.",
- "title": "Project Slinky Using Olimex Board"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#prerequisites",
- "text": "Meet the prerequisites listed in Project Slinky . Have a STM32-E407 development board from Olimex. Have a ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board) Have a USB A-B type cable to connect the debugger to your computer. Have a USB to TTL Serial Cable with female wiring harness. Install the OpenOCD debugger .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#create-a-new-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to create the targets if you already have a project created or completed the Sim Slinky tutorial. $ newt new slinky\nDownloading project skeleton from apache/incubator-mynewt-blinky...\n...\nInstalling skeleton in slink...\nProject slink successfully created\n$ cd slinky\n$newt install\napache-mynewt-core",
- "title": "Create a New Project"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#build-the-targets",
- "text": "Run the newt build stm32_boot command to build the bootloader: $ newt build stm32_boot\nBuilding target targets/stm32_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\n ...\n\nArchiving sys_mfg.a\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/stm32_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/stm32_boot\n$ \nRun the newt build stm32_slinky command to build the Slinky application: $newt build stm32_slinky\nBuilding target targets/stm32_slinky\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/split/src/split.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/apps/slinky/src/main.c\n\n ...\n\nArchiving util_crc.a\nArchiving util_mem.a\nLinking ~/dev/slinky/bin/targets/stm32_slinky/app/apps/slinky/slinky.elf\nTarget successfully built: targets/stm32_slinky\n$",
- "title": "Build the Targets"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#sign-and-create-the-slinky-application-image",
- "text": "Run the newt create-image stm32_slinky 1.0.0 command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. create-image stm32_slinky 1.0.0\nApp image succesfully generated: ~/dev/slinky/bin/targets/stm32_slinky/app/apps/slinky/slinky.img\n$",
- "title": "Sign and Create the Slinky Application Image"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#connect-to-the-board",
- "text": "Connect the USB A-B type cable to the ARM-USB-TINY-H debugger connector. Connect the ARM-USB-Tiny-H debugger connector to your computer and the board. Connect the USB Micro-A cable to the USB-OTG2 port on the board. Set the Power Sel jumper on the board to pins 5 and 6 to select USB-OTG2 as the power source. If you would like to use a different power source, refer to the OLIMEX STM32-E407 user manual for pin specifications. You should see a red LED light up on the board.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#load-the-bootloader-and-the-slinky-application-image",
- "text": "Run the newt load stm32_boot command to load the bootloader onto the board: $ newt load stm32_boot\nLoading bootloader\n$ \nNote: If you are using Windows and get a no device found error, you will need to install the usb driver. Download Zadig and run it: Select Options List All Devices. Select Olimex OpenOCD JTAG ARM-USB-TINY-H from the drop down menu. Select the WinUSB driver. Click Install Driver. Run the newt load stm32_boot command again. \nRun the newt load stm32_slinky command to load the Slinky application image onto the board: $ newt load stm32_slinky\nLoading app image into slot 1\n$",
- "title": "Load the Bootloader and the Slinky Application Image"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#connect-newtmgr-with-the-board-using-a-serial-connection",
- "text": "Locate the PC6/USART6_TX (pin 3), PC7/USART6_RX (pin 4), and GND (pin 2) of the UEXT connector on the Olimex board. More information on the UEXT connector can be found at https://www.olimex.com/Products/Modules/UEXT/ . The schematic of the board can be found at https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407_sch.pdf for reference. Connect the female RX pin of the USB-TTL serial cable to the TX (Pin 3) of the UEXT connector on the board. Connect the female TX pin of the USB-TTL serial cable to the RX (Pin 4) of the UEXT connector on the board. Connect the GND pin of the USB-TTL serial cable to the GND (Pin 2) of the UEXT connector on the board. \nLocate the port, in the /dev directory on your computer, that the serial connection uses. The format of the port name is platform dependent: Mac OS uses the format tty.usbserial- some identifier . Linux uses the format TTYUSB N , where N is a number. For example, TTYUSB2. MinGW on Windows uses the format ttyS N , where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . You can also use the Windows Device Manager to find the COM port number. $ ls /dev/tty*usbserial*\n/dev/tty.usbserial-1d13\n$ \nSetup a newtmgr connection profile for the serial port. For our example, the port is /dev/tty.usbserial-1d13 . Run the newtmgr conn add command to define a newtmgr connection profile for the serial port. We name the connection profile stm32serial . Note : You will need to replace the connstring with the specific port for your serial connection. On Windows, you must specify COM N+1 for the connstring if /dev/ttyS N is the serial port. $ newtmgr conn add stm32serial type=serial connstring=/dev/tty.usbserial-1d13\nConnection profile stm32serial successfully added\n$ \nYou can run the newt conn show command to see all the newtmgr connection profiles: $ newtmgr conn show\nConnection profiles:\n stm32serial: type=serial, connstring= /dev/tty.usbserial-1d13 \n sim1: type=serial, connstring= /dev/ttys012 \n$",
- "title": "Connect Newtmgr with the Board using a Serial Connection"
- },
- {
- "location": "/os/tutorials/project-stm32-slinky/#use-newtmgr-to-query-the-board",
- "text": "Run some newtmgr commands to query and receive responses back from the board (See the Newt Manager Guide for more information on the newtmgr commands). Run the newtmgr echo hello -c stm32serial command. This is the simplest command that requests the board to echo back the\n text. $ newtmgr echo hello -c stm32serial\nhello\n$ \nRun the newtmgr image list -c stm32serial command to list the images on the board: $ newtmgr image list -c stm32serial\nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: 9cf8af22b1b573909a8290a90c066d4e190407e97680b7a32243960ec2bf3a7f\nSplit status: N/A\n$ \nRun the newtmgr taskstat -c stm32serial command to display the task statistics on the board: $ newtmgr taskstat -c stm32serial\nReturn Code = 0\n task pri tid runtime csw stksz stkuse last_checkin next_checkin\n task1 8 2 0 90 192 110 0 0\n task2 9 3 0 90 64 31 0 0\n idle 255 0 89460 89463 64 26 0 0\n main 127 1 4 26 1024 368 0 0\n$",
- "title": "Use Newtmgr to Query the Board"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/",
- "text": "Over-the-Air Image Upgrade\n\n\nMynewt 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. \n\n\nTo 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 \nbleprph\n application, which includes image management over BLE functionality, on an nRF52-DK board. If you prefer to use a different BLE application, see \nEnable Newt Manager in any app\n to enable newtmgr image management over BLE transport support in your application. \n\n\nNote:\n Over-the-air upgrade via newtmgr BLE transport is supported on Mac OS and Linux. It is not supported on Windows platforms.\n\n\nPrerequisites\n\n\nEnsure that you meet the following prerequisites:\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a computer that supports Bluetooth to communicate with the board and to build a Mynewt application. \n\n\nHave a Micro-USB cable to connect the board and the computer.\n\n\nHave a Nordic nRF52-DK Development Kit - PCA 10040\n\n\nInstall the \nSegger JLINK software and documentation pack\n.\n\n\nInstall the newt tool and toolchains (See \nBasic Setup\n).\n\n\nRead the Mynewt OS \nConcepts\n section.\n\n\nRead the \nBootloader\n section and understand the Mynewt bootloader concepts.\n\n\nBuild and load the \nbleprph\n application on to an nRF52-DK board via a serial connection. See \nBLE Peripheral App\n. \n\n\n\n\nUpgrading an Image on a Device\n\n\nOnce 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. \n\n\nYou must perform the following steps to upgrade an image:\n\n\nStep 1: Create a newtmgr connection profile to communicate with the device over BLE.\n\n\nStep 2: Upload the image to the secondary slot (slot 1) on the device.\n\n\nStep 3: Test the image.\n\n\nStep 4: Confirm and make the image permanent. \n\n\nSee the \nBootloader\n section for more information on the bootloader, image slots, and boot states.\n\n\n\n\nStep 1: Creating a Newtmgr Connection Profile\n\n\nThe \nbleprph\n application sets and advertises \nnimble-bleprph\n as its bluetooth device address. Run the \nnewtmgr conn add\n command to create a newtmgr connection profile that uses this peer address to communicate with the device over BLE:\n\n\n\n$ newtmgr conn add mybleprph type=ble connstring=\npeer_name=nimble-bleprph\n\nConnection profile mybleprph successfully added\n\n\n\n\n\n\nVerify that the newtmgr tool can communicate with the device and check the image status on the device:\n\n\n\n$ newtmgr image list -c mybleprph \nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\nSplit status: N/A (0)\n\n\n\n\n\nThe 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).\n\n\n\nStep 2: Uploading an Image to the Device\n\n\nWe create an image with version 2.0.0 for the bleprph application from the \nmyperiph\n target and upload the new image. You can upload a different image.\n\n\n\n$ newt create-image myperiph 2.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/myperiph/app/apps/bleprph/bleprph.img\n\n\n\n\n\n\nRun the \nnewtmgr image upload\n command to upload the image:\n\n\n$ newtmgr image upload -c mybleprph ~/dev/myproj/bin/targets/myperiph/app/apps/bleprph/bleprph.img\n215\n429\n642\n855\n1068\n1281\n\n...\n\n125953\n126164\n126375\n126586\n126704\nDone\n\n\n\n\n\nThe numbers indicate the number of bytes that the newtmgr tool has uploaded. \n\n\n\nVerify that the image uploaded to the secondary slot on the device successfully:\n\n\n\n$ newtmgr image list -c mybleprph\nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\n slot=1\n version: 2.0.0\n bootable: true\n flags: \n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\nSplit status: N/A (0)\n\n\n\n\n\nThe device now has the uploaded image in the secondary slot (slot 1).\n\n\n\nStep 3: Testing the Image\n\n\nThe image is uploaded to the secondary slot but is not yet active. You must run the \nnewtmgr image test\n command to set the image status to \npending\n and reboot the device. When the device reboots, the bootloader copies this image to the primary slot and runs the image.\n\n\n\n$ newtmgr image test -c mybleprph 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\n slot=1\n version: 2.0.0\n bootable: true\n flags: pending\n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\nSplit status: N/A (0)\n\n\n\n\n\nThe status of the image in the secondary slot is now set to \npending\n. \n\n\n\nPower the device OFF and ON and run the \nnewtmgr image list\n command to check the image status on the device after the reboot:\n\n\n\n$ newtmgr image list -c mybleprph\nImages:\n slot=0\n version: 2.0.0\n bootable: true\n flags: active\n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\n slot=1\n version: 1.0.0\n bootable: true\n flags: confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\nSplit status: N/A (0)\n\n\n\n\n\nThe 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.\n\n\n\nStep 4: Confirming the Image\n\n\nRun the \nnewtmgr image confirm\n 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:\n\n\n$ newtmgr image confirm -c mybleprph \nImages:\n slot=0\n version: 2.0.0\n bootable: true\n flags: active confirmed\n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\n slot=1\n version: 1.0.0\n bootable: true\n flags: \n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\nSplit status: N/A (0)\n\n\n\n\n\nThe uploaded image is now the active and confirmed image. You have successfully upgraded an image over-the-air.",
- "title": "Upgrade an Image Over-The-Air"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#over-the-air-image-upgrade",
- "text": "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. 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 bleprph application, which includes image management over BLE functionality, on an nRF52-DK board. If you prefer to use a different BLE application, see Enable Newt Manager in any app to enable newtmgr image management over BLE transport support in your application. Note: Over-the-air upgrade via newtmgr BLE transport is supported on Mac OS and Linux. It is not supported on Windows platforms.",
- "title": "Over-the-Air Image Upgrade"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#prerequisites",
- "text": "Ensure that you meet the following prerequisites: Have Internet connectivity to fetch remote Mynewt components. Have a computer that supports Bluetooth to communicate with the board and to build a Mynewt application. Have a Micro-USB cable to connect the board and the computer. Have a Nordic nRF52-DK Development Kit - PCA 10040 Install the Segger JLINK software and documentation pack . Install the newt tool and toolchains (See Basic Setup ). Read the Mynewt OS Concepts section. Read the Bootloader section and understand the Mynewt bootloader concepts. Build and load the bleprph application on to an nRF52-DK board via a serial connection. See BLE Peripheral App .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#upgrading-an-image-on-a-device",
- "text": "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. You must perform the following steps to upgrade an image: Step 1: Create a newtmgr connection profile to communicate with the device over BLE. \nStep 2: Upload the image to the secondary slot (slot 1) on the device. \nStep 3: Test the image. \nStep 4: Confirm and make the image permanent. See the Bootloader section for more information on the bootloader, image slots, and boot states.",
- "title": "Upgrading an Image on a Device"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#step-1-creating-a-newtmgr-connection-profile",
- "text": "The bleprph application sets and advertises nimble-bleprph as its bluetooth device address. Run the newtmgr conn add command to create a newtmgr connection profile that uses this peer address to communicate with the device over BLE: $ newtmgr conn add mybleprph type=ble connstring= peer_name=nimble-bleprph \nConnection profile mybleprph successfully added \nVerify that the newtmgr tool can communicate with the device and check the image status on the device: $ newtmgr image list -c mybleprph \nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\nSplit status: N/A (0) 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).",
- "title": "Step 1: Creating a Newtmgr Connection Profile"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#step-2-uploading-an-image-to-the-device",
- "text": "We create an image with version 2.0.0 for the bleprph application from the myperiph target and upload the new image. You can upload a different image. $ newt create-image myperiph 2.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/myperiph/app/apps/bleprph/bleprph.img \nRun the newtmgr image upload command to upload the image: $ newtmgr image upload -c mybleprph ~/dev/myproj/bin/targets/myperiph/app/apps/bleprph/bleprph.img\n215\n429\n642\n855\n1068\n1281\n\n...\n\n125953\n126164\n126375\n126586\n126704\nDone The numbers indicate the number of bytes that the newtmgr tool has uploaded. \nVerify that the image uploaded to the secondary slot on the device successfully: $ newtmgr image list -c mybleprph\nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\n slot=1\n version: 2.0.0\n bootable: true\n flags: \n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\nSplit status: N/A (0) The device now has the uploaded image in the secondary slot (slot 1).",
- "title": "Step 2: Uploading an Image to the Device"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#step-3-testing-the-image",
- "text": "The image is uploaded to the secondary slot but is not yet active. You must run the newtmgr image test command to set the image status to pending and reboot the device. When the device reboots, the bootloader copies this image to the primary slot and runs the image. $ newtmgr image test -c mybleprph 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\nImages:\n slot=0\n version: 1.0.0\n bootable: true\n flags: active confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\n slot=1\n version: 2.0.0\n bootable: true\n flags: pending\n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\nSplit status: N/A (0) The status of the image in the secondary slot is now set to pending . \nPower the device OFF and ON and run the newtmgr image list command to check the image status on the device after the reboot: $ newtmgr image list -c mybleprph\nImages:\n slot=0\n version: 2.0.0\n bootable: true\n flags: active\n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\n slot=1\n version: 1.0.0\n bootable: true\n flags: confirmed\n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\nSplit status: N/A (0) 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.",
- "title": "Step 3: Testing the Image"
- },
- {
- "location": "/os/tutorials/ota_upgrade_nrf52/#step-4-confirming-the-image",
- "text": "Run the newtmgr image confirm 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: $ newtmgr image confirm -c mybleprph \nImages:\n slot=0\n version: 2.0.0\n bootable: true\n flags: active confirmed\n hash: 291ebc02a8c345911c96fdf4e7b9015a843697658fd6b5faa0eb257a23e93682\n slot=1\n version: 1.0.0\n bootable: true\n flags: \n hash: b8d17c77a03b37603cd9f89fdcfe0ba726f8ddff6eac63011dee2e959cc316c2\nSplit status: N/A (0) The uploaded image is now the active and confirmed image. You have successfully upgraded an image over-the-air.",
- "title": "Step 4: Confirming the Image"
- },
- {
- "location": "/os/tutorials/ibeacon/",
- "text": "BLE iBeacon\n\n\nThis tutorial guides you through the process of creating an iBeacon application using NimBLE and Mynewt. At the conclusion of this tutorial, you will have a fully functional iBeacon app.\n\n\niBeacon Protocol\n\n\nA beaconing device announces its presence to the world by broadcasting\nadvertisements. The iBeacon protocol is built on top of the standard BLE\nadvertisement specification.\n\nThis page\n provides a\ngood summary of the iBeacon sub-fields.\n\n\nCreate an Empty BLE Application\n\n\nThis tutorial picks up where the\n\nSet up a NimBLE application\n document\nconcludes. The first step in creating a beaconing device is to create an empty\nBLE app, as explained in that tutorial. Before proceeding, you should have:\n\n\n\n\nAn app called \"ble_app\".\n\n\nA target called \"ble_tgt\".\n\n\nSuccessfully executed the app on your target device.\n\n\n\n\nAdd beaconing\n\n\nHere is a brief specification of how we want our beaconing app to behave:\n\n\n\n\nWait until the host and controller are in sync.\n\n\nConfigure the NimBLE stack with an address to put in its advertisements.\n\n\nAdvertise indefinitely.\n\n\n\n\nLet's take these one at a time.\n\n\n\n\n1. Wait for host-controller sync\n\n\nThe first step, waiting for host-controller-sync, is mandatory in all BLE\napplications. The NimBLE stack is inoperable while the two components are out\nof sync. In a combined host-controller app, the sync happens immediately at\nstartup. When the host and controller are separate, sync typically occurs\nin less than a second.\n\n\nWe achieve this by configuring the NimBLE host with a callback function that\ngets called when sync takes place:\n\n\nstatic\n \nvoid\n\n\nble_app_set_addr\n()\n\n{ }\n\n\n\nstatic\n \nvoid\n\n\nble_app_advertise\n();\n\n{ }\n\n\n\nstatic\n \nvoid\n\n\nble_app_on_sync\n(\nvoid\n)\n\n{\n\n \n/* Generate a non-resolvable private address. */\n\n\n \nble_app_set_addr\n();\n\n\n\n \n/* Advertise indefinitely. */\n\n\n \nble_app_advertise\n();\n\n}\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nsysinit\n();\n\n\n \nble_hs_cfg\n.\nsync_cb\n \n=\n \nble_app_on_sync\n;\n\n\n \n/* As the last thing, process events from default event queue. */\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n}\n\n\n\n\n\nble_hs_cfg.sync_cb\n points to the function that should be called when sync\noccurs. Our callback function, \nble_app_on_sync()\n, kicks off the control flow\nthat we specified above. Now we need to fill in the two stub functions.\n\n\n\n\n2. Configure the NimBLE stack with an address\n\n\nA BLE device needs an address to do just about anything. Some devices have a\npublic Bluetooth address burned into them, but this is not always the case.\nFurthermore, the NimBLE controller might not know how to read an address out of\nyour particular hardware. For a beaconing device, we generally don't care what\naddress gets used since nothing will be connecting to us.\n\n\nA reliable solution is to generate a \nnon-resolvable private address\n (nRPA)\neach time the application runs. Such an address contains no identifying\ninformation, and they are expected to change frequently.\n\n\nstatic\n \nvoid\n\n\nble_app_set_addr\n(\nvoid\n)\n{\n\n \nble_addr_t\n \naddr\n;\n\n \nint\n \nrc\n;\n\n\n\n \nrc\n \n=\n \nble_hs_id_gen_rnd\n(\n1\n, \naddr\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n \nrc\n \n=\n \nble_hs_id_set_rnd\n(\naddr\n.\nval\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n}\n\n\nstatic\n \nvoid\n\n\nble_app_advertise\n();\n{ }\n\n\nstatic\n \nvoid\n\n\nble_app_on_sync\n(\nvoid\n)\n{\n \n/* Generate a non-resolvable private address. */\n\n \nble_app_set_addr\n();\n\n \n/* Advertise indefinitely. */\n\n \nble_app_advertise\n();\n}\n\n\n\n\n\nOur new function, \nble_app_set_addr()\n, makes two calls into the stack:\n\n\n\n\nble_hs_id_gen_rnd\n: Generate an nRPA.\n\n\nble_hs_id_set_rnd\n: Configure NimBLE to use the newly-generated address.\n\n\n\n\nYou can click either of the function names for more detailed documentation.\n\n\n\n\n3. Advertise indefinitely\n\n\nThe first step in advertising is to configure the host with advertising data.\nThis operation tells the host what data to use for the contents of its\nadvertisements. The NimBLE host provides a special helper function for\nconfiguration iBeacon advertisement data:\n\nble_ibeacon_set_adv_data\n.\n\n\nIf you follow the API link, you'll see that this function takes three parameters: a 128-bit UUID, a major version, and a minor version. This corresponds with the iBeacon specification, as these three items are the primary components in an iBeacon advertisement.\n\n\nFor now, we'll advertise the following:\n\n \nUUID\n: \n11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11\n\n\n \nMajor\n: 2\n* \nMinor\n: 10\n\n\nstatic\n \nvoid\n\n\nble_app_advertise\n(\nvoid\n)\n{\n \nuint8_t\n \nuuid128\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Fill the UUID buffer with a string of 0x11 bytes. */\n\n \nmemset\n(\nuuid128\n, \n0x11\n, \nsizeof\n \nuuid128\n);\n\n \n/* Major version=2; minor version=10. */\n\n \nrc\n \n=\n \nble_ibeacon_set_adv_data\n(\nuuid128\n, \n2\n, \n10\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* TODO: Begin advertising. */\n\n}\n\n\n\n\n\nNow that the host knows what to advertise, the next step is to actually begin\nadvertising. The function to initiate advertising is:\n\nble_gap_adv_start\n.\nThis function takes several parameters. For simplicity, we reproduce the\nfunction prototype here:\n\n\nint\n\n\nble_gap_adv_start\n(\n \nuint8_t\n \nown_addr_type\n,\n \nconst\n \nble_addr_t\n \n*direct_addr\n,\n \nint32_t\n \nduration_ms\n,\n \nconst\n \nstruct\n \nble_gap_adv_params\n \n*adv_params\n,\n \nble_gap_event_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nThis function gives an application quite a bit of freedom in how advertising is to be done. The default values are mostly fine for our simple beaconing application. We will pass the following values to this function:\n\n\n\n\n\n\n\n\nParameter\n\n\nValue\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nown_addr_type\n\n\nBLE_OWN_ADDR_RANDOM\n\n\nUse the nRPA we generated earlier.\n\n\n\n\n\n\ndirect_addr\n\n\nNULL\n\n\nWe are broadcasting, not targeting a peer.\n\n\n\n\n\n\nduration_ms\n\n\nBLE_HS_FOREVER\n\n\nAdvertise indefinitely.\n\n\n\n\n\n\nadv_params\n\n\ndefaults\n\n\nCan be used to specify low level advertising parameters.\n\n\n\n\n\n\ncb\n\n\nNULL\n\n\nWe are non-connectable, so no need for an event callback.\n\n\n\n\n\n\ncb_arg\n\n\nNULL\n\n\nNo callback implies no callback argument.\n\n\n\n\n\n\n\n\nThese arguments are mostly self-explanatory. The exception is \nadv_params\n, which can be used to specify a number of low-level parameters. For a beaconing application, the default settings are appropriate. We specify default settings by providing a zero-filled instance of the \nble_gap_adv_params\n struct as our argument.\n\n\nstatic\n \nvoid\n\n\nbleprph_advertise\n(\nvoid\n)\n{\n \nstruct\n \nble_gap_adv_params\n \nadv_params\n;\n \nuint8_t\n \nuuid128\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Arbitrarily set the UUID to a string of 0x11 bytes. */\n\n \nmemset\n(\nuuid128\n, \n0x11\n, \nsizeof\n \nuuid128\n);\n\n \n/* Major version=2; minor version=10. */\n\n \nrc\n \n=\n \nble_ibeacon_set_adv_data\n(\nuuid128\n, \n2\n, \n10\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror setting iBeacon advertisement data; rc=%d\\n\n,\n \nrc\n);\n \nreturn\n;\n }\n\n \n/* Begin advertising. */\n\n\n \nadv_params\n \n=\n (\nstruct\n \nble_gap_adv_params\n){ \n0\n };\n\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_OWN_ADDR_RANDOM\n, \nNULL\n, \nBLE_HS_FOREVER\n,\n\n \nadv_params\n, \nNULL\n, \nNULL\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n}\n\n\n\n\n\nConclusion\n\n\nThat's it! Now when you run this app on your board, you should be able to see\nit with all your iBeacon-aware devices. You can test it out with the\n\nnewt run\n command.\n\n\nSource Listing\n\n\nFor reference, here is the complete application source:\n\n\n#include\n \nsysinit/sysinit.h\n\n\n#include\n \nos/os.h\n\n\n#include\n \nconsole/console.h\n\n\n#include\n \nhost/ble_hs.h\n\n\n\nstatic\n \nvoid\n\n\nble_app_set_addr\n(\nvoid\n)\n{\n \nble_addr_t\n \naddr\n;\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nble_hs_id_gen_rnd\n(\n1\n, \naddr\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nble_hs_id_set_rnd\n(\naddr\n.\nval\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n}\n\n\nstatic\n \nvoid\n\n\nbleprph_advertise\n(\nvoid\n)\n{\n \nstruct\n \nble_gap_adv_params\n \nadv_params\n;\n \nuint8_t\n \nuuid128\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Arbitrarily set the UUID to a string of 0x11 bytes. */\n\n \nmemset\n(\nuuid128\n, \n0x11\n, \nsizeof\n \nuuid128\n);\n\n \n/* Major version=2; minor version=10. */\n\n \nrc\n \n=\n \nble_ibeacon_set_adv_data\n(\nuuid128\n, \n2\n, \n10\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror setting iBeacon advertisement data; rc=%d\\n\n,\n \nrc\n);\n \nreturn\n;\n }\n\n \n/* Begin advertising. */\n\n \nadv_params\n \n=\n (\nstruct\n \nble_gap_adv_params\n){ \n0\n };\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_OWN_ADDR_RANDOM\n, \nNULL\n, \nBLE_HS_FOREVER\n,\n \nadv_params\n, \nNULL\n, \nNULL\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n}\n\n\nstatic\n \nvoid\n\n\nble_app_on_sync\n(\nvoid\n)\n{\n \n/* Generate a non-resolvable private address. */\n\n \nble_app_set_addr\n();\n\n \n/* Advertise indefinitely. */\n\n \nble_app_advertise\n();\n}\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nsysinit\n();\n\n \nble_hs_cfg\n.\nsync_cb\n \n=\n \nble_app_on_sync\n;\n\n \n/* As the last thing, process events from default event queue. */\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n}",
- "title": "BLE iBeacon"
- },
- {
- "location": "/os/tutorials/ibeacon/#ble-ibeacon",
- "text": "This tutorial guides you through the process of creating an iBeacon application using NimBLE and Mynewt. At the conclusion of this tutorial, you will have a fully functional iBeacon app.",
- "title": "BLE iBeacon"
- },
- {
- "location": "/os/tutorials/ibeacon/#ibeacon-protocol",
- "text": "A beaconing device announces its presence to the world by broadcasting\nadvertisements. The iBeacon protocol is built on top of the standard BLE\nadvertisement specification. This page provides a\ngood summary of the iBeacon sub-fields.",
- "title": "iBeacon Protocol"
- },
- {
- "location": "/os/tutorials/ibeacon/#create-an-empty-ble-application",
- "text": "This tutorial picks up where the Set up a NimBLE application document\nconcludes. The first step in creating a beaconing device is to create an empty\nBLE app, as explained in that tutorial. Before proceeding, you should have: An app called \"ble_app\". A target called \"ble_tgt\". Successfully executed the app on your target device.",
- "title": "Create an Empty BLE Application"
- },
- {
- "location": "/os/tutorials/ibeacon/#add-beaconing",
- "text": "Here is a brief specification of how we want our beaconing app to behave: Wait until the host and controller are in sync. Configure the NimBLE stack with an address to put in its advertisements. Advertise indefinitely. Let's take these one at a time.",
- "title": "Add beaconing"
- },
- {
- "location": "/os/tutorials/ibeacon/#1-wait-for-host-controller-sync",
- "text": "The first step, waiting for host-controller-sync, is mandatory in all BLE\napplications. The NimBLE stack is inoperable while the two components are out\nof sync. In a combined host-controller app, the sync happens immediately at\nstartup. When the host and controller are separate, sync typically occurs\nin less than a second. We achieve this by configuring the NimBLE host with a callback function that\ngets called when sync takes place: static void ble_app_set_addr () { } static void ble_app_advertise (); { } static void ble_app_on_sync ( void ) { /* Generate a non-resolvable private address. */ ble_app_set_addr (); /* Advertise indefinitely. */ ble_app_advertise (); } int main ( int argc , char **argv )\n{\n sysinit (); ble_hs_cfg . sync_cb = ble_app_on_sync ; \n /* As the last thing, process events from default event queue. */ \n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n} ble_hs_cfg.sync_cb points to the function that should be called when sync\noccurs. Our callback function, ble_app_on_sync() , kicks off the control flow\nthat we specified above. Now we need to fill in the two stub functions.",
- "title": "1. Wait for host-controller sync"
- },
- {
- "location": "/os/tutorials/ibeacon/#2-configure-the-nimble-stack-with-an-address",
- "text": "A BLE device needs an address to do just about anything. Some devices have a\npublic Bluetooth address burned into them, but this is not always the case.\nFurthermore, the NimBLE controller might not know how to read an address out of\nyour particular hardware. For a beaconing device, we generally don't care what\naddress gets used since nothing will be connecting to us. A reliable solution is to generate a non-resolvable private address (nRPA)\neach time the application runs. Such an address contains no identifying\ninformation, and they are expected to change frequently. static void ble_app_set_addr ( void )\n{ ble_addr_t addr ; int rc ; rc = ble_hs_id_gen_rnd ( 1 , addr ); assert ( rc == 0 ); rc = ble_hs_id_set_rnd ( addr . val ); assert ( rc == 0 ); } static void ble_app_advertise ();\n{ } static void ble_app_on_sync ( void )\n{\n /* Generate a non-resolvable private address. */ \n ble_app_set_addr ();\n\n /* Advertise indefinitely. */ \n ble_app_advertise ();\n} Our new function, ble_app_set_addr() , makes two calls into the stack: ble_hs_id_gen_rnd : Generate an nRPA. ble_hs_id_set_rnd : Configure NimBLE to use the newly-generated address. You can click either of the function names for more detailed documentation.",
- "title": "2. Configure the NimBLE stack with an address"
- },
- {
- "location": "/os/tutorials/ibeacon/#3-advertise-indefinitely",
- "text": "The first step in advertising is to configure the host with advertising data.\nThis operation tells the host what data to use for the contents of its\nadvertisements. The NimBLE host provides a special helper function for\nconfiguration iBeacon advertisement data: ble_ibeacon_set_adv_data . If you follow the API link, you'll see that this function takes three parameters: a 128-bit UUID, a major version, and a minor version. This corresponds with the iBeacon specification, as these three items are the primary components in an iBeacon advertisement. For now, we'll advertise the following: UUID : 11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11 Major : 2\n* Minor : 10 static void ble_app_advertise ( void )\n{\n uint8_t uuid128 [ 16 ];\n int rc ;\n\n /* Fill the UUID buffer with a string of 0x11 bytes. */ \n memset ( uuid128 , 0x11 , sizeof uuid128 );\n\n /* Major version=2; minor version=10. */ \n rc = ble_ibeacon_set_adv_data ( uuid128 , 2 , 10 );\n assert ( rc == 0 );\n\n /* TODO: Begin advertising. */ \n} Now that the host knows what to advertise, the next step is to actually begin\nadvertising. The function to initiate advertising is: ble_gap_adv_start .\nThis function takes several parameters. For simplicity, we reproduce the\nfunction prototype here: int ble_gap_adv_start (\n uint8_t own_addr_type ,\n const ble_addr_t *direct_addr ,\n int32_t duration_ms ,\n const struct ble_gap_adv_params *adv_params ,\n ble_gap_event_fn *cb ,\n void *cb_arg \n) This function gives an application quite a bit of freedom in how advertising is to be done. The default values are mostly fine for our simple beaconing application. We will pass the following values to this function: Parameter Value Notes own_addr_type BLE_OWN_ADDR_RANDOM Use the nRPA we generated earlier. direct_addr NULL We are broadcasting, not targeting a peer. duration_ms BLE_HS_FOREVER Advertise indefinitely. adv_params defaults Can be used to specify low level advertising parameters. cb NULL We are non-connectable, so no need for an event callback. cb_arg NULL No callback implies no callback argument. These arguments are mostly self-explanatory. The exception is adv_params , which can be used to specify a number of low-level parameters. For a beaconing application, the default settings are appropriate. We specify default settings by providing a zero-filled instance of the ble_gap_adv_params struct as our argument. static void bleprph_advertise ( void )\n{\n struct ble_gap_adv_params adv_params ;\n uint8_t uuid128 [ 16 ];\n int rc ;\n\n /* Arbitrarily set the UUID to a string of 0x11 bytes. */ \n memset ( uuid128 , 0x11 , sizeof uuid128 );\n\n /* Major version=2; minor version=10. */ \n rc = ble_ibeacon_set_adv_data ( uuid128 , 2 , 10 );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error setting iBeacon advertisement data; rc=%d\\n ,\n rc );\n return ;\n }\n\n /* Begin advertising. */ adv_params = ( struct ble_gap_adv_params ){ 0 }; rc = ble_gap_adv_start ( BLE_OWN_ADDR_RANDOM , NULL , BLE_HS_FOREVER , adv_params , NULL , NULL ); assert ( rc == 0 ); }",
- "title": "3. Advertise indefinitely"
- },
- {
- "location": "/os/tutorials/ibeacon/#conclusion",
- "text": "That's it! Now when you run this app on your board, you should be able to see\nit with all your iBeacon-aware devices. You can test it out with the newt run command.",
- "title": "Conclusion"
- },
- {
- "location": "/os/tutorials/ibeacon/#source-listing",
- "text": "For reference, here is the complete application source: #include sysinit/sysinit.h #include os/os.h #include console/console.h #include host/ble_hs.h static void ble_app_set_addr ( void )\n{\n ble_addr_t addr ;\n int rc ;\n\n rc = ble_hs_id_gen_rnd ( 1 , addr );\n assert ( rc == 0 );\n\n rc = ble_hs_id_set_rnd ( addr . val );\n assert ( rc == 0 );\n} static void bleprph_advertise ( void )\n{\n struct ble_gap_adv_params adv_params ;\n uint8_t uuid128 [ 16 ];\n int rc ;\n\n /* Arbitrarily set the UUID to a string of 0x11 bytes. */ \n memset ( uuid128 , 0x11 , sizeof uuid128 );\n\n /* Major version=2; minor version=10. */ \n rc = ble_ibeacon_set_adv_data ( uuid128 , 2 , 10 );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error setting iBeacon advertisement data; rc=%d\\n ,\n rc );\n return ;\n }\n\n /* Begin advertising. */ \n adv_params = ( struct ble_gap_adv_params ){ 0 };\n rc = ble_gap_adv_start ( BLE_OWN_ADDR_RANDOM , NULL , BLE_HS_FOREVER ,\n adv_params , NULL , NULL );\n assert ( rc == 0 );\n} static void ble_app_on_sync ( void )\n{\n /* Generate a non-resolvable private address. */ \n ble_app_set_addr ();\n\n /* Advertise indefinitely. */ \n ble_app_advertise ();\n} int main ( int argc , char **argv )\n{\n sysinit ();\n\n ble_hs_cfg . sync_cb = ble_app_on_sync ;\n\n /* As the last thing, process events from default event queue. */ \n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n}",
- "title": "Source Listing"
- },
- {
- "location": "/os/tutorials/eddystone/",
- "text": "BLE Eddystone\n\n\n\n\nEddystone Beacon Protocol\n\n\nA beaconing device announces its presence to the world by broadcasting\nadvertisements. The Eddystone protocol is built on top of the standard BLE\nadvertisement specification. Eddystone supports multiple data packet types\n\n\n\n\nEddystone-UID: a unique, static ID with a 10-byte Namespace component and a 6-byte Instance component.\n\n\nEddystone-URL: a compressed URL that, once parsed and decompressed, is directly usable by the client.\n\n\nEddystone-TLM: \"telemetry\" packets that are broadcast alongside the Eddystone-UID or Eddystone-URL packets and contains beacon\u2019s \u201chealth status\u201d (e.g., battery life).\n\n\nEddystone-EID to broadcast an ephemeral identifier that changes every few minutes and allow only parties that can resolve the identifier to use the beacon. \n\n\n\n\nThis page\n describes the Eddystone open beacon format developed by Google.\n\n\nApache Mynewt currently supports Eddystone-UID and Eddystone-URL formats only. This tutorial will explain how to get an Eddystone-URL beacon going on a peripheral device.\n\n\n\n\nConfiguration\n\n\nUse the following function to configure your NimBLE device to send Eddystone-URL beacons:\n\n\nint\n\n\nble_eddystone_set_adv_data_url\n(\nstruct\n \nble_hs_adv_fields\n \n*adv_fields\n,\n \nuint8_t\n \nurl_scheme\n, \nchar\n \n*url_body\n,\n \nuint8_t\n \nurl_body_len\n, \nuint8_t\n \nurl_suffix\n)\n\n\n\n\n\nThis function's parameters are documented below.\n\n\n\n\n\n\n\n\nParameter\n\n\nPurpose\n\n\n\n\n\n\n\n\n\n\nadv_fields\n\n\nThe base advertisement fields to transform into an eddystone beacon.\n\n\n\n\n\n\nurl_scheme\n\n\nThe prefix of the URL; one of the BLE_EDDYSTONE_URL_SCHEME values from ble_eddystone.h\n\n\n\n\n\n\nurl_body\n\n\nThe middle of the url specified within \"\".\n\n\n\n\n\n\nurl_body_len\n\n\nThe string length of the url_body argument.\n\n\n\n\n\n\nurl_suffix\n\n\nThe suffix of the URL; one of the BLE_EDDYSTONE_URL_SUFFIX values from ble_eddystone.h\n\n\n\n\n\n\n\n\n\n\nModify bleprph\n\n\nTo demonstrate how the above function is used, we will now modify the \nbleprph\n\nexample application to send Eddystone beacons. For some background behind the \nbleprph\n\napp, we recommend you take a look at the \nbleprph project\ntutorial\n. If you plan on making these modifications\nyourself, it might be a good idea to copy \nbleprph\n to your local repository\nand work with the copy. In general, you should avoid changing a package that\nnewt downloads, as you will lose your changes the next time you upgrade the\npackage.\n\n\nbleprph\n sets its advertisement data and begins advertising as follows (\nmain.c\n):\n\n\nstatic\n \nvoid\n\n\nbleprph_advertise\n(\nvoid\n)\n{\n \nstruct\n \nble_gap_adv_params\n \nadv_params\n;\n \nstruct\n \nble_hs_adv_fields\n \nfields\n;\n \nconst\n \nchar\n \n*name\n;\n \nint\n \nrc\n;\n\n \n/**\n\n\n * Set the advertisement data included in our advertisements:\n\n\n * o Flags (indicates advertisement type and other general info).\n\n\n * o Advertising tx power.\n\n\n * o Device name.\n\n\n * o 16-bit service UUIDs (alert notifications).\n\n\n */\n\n\n \nmemset\n(\nfields\n, \n0\n, \nsizeof\n \nfields\n);\n\n \n/* Advertise two flags:\n\n\n * o Discoverability in forthcoming advertisement (general)\n\n\n * o BLE-only (BR/EDR unsupported).\n\n\n */\n\n \nfields\n.\nflags\n \n=\n \nBLE_HS_ADV_F_DISC_GEN\n \n|\n\n \nBLE_HS_ADV_F_BREDR_UNSUP\n;\n\n \n/* Indicate that the TX power level field should be included; have the\n\n\n * stack fill this value automatically. This is done by assiging the\n\n\n * special value BLE_HS_ADV_TX_PWR_LVL_AUTO.\n\n\n */\n\n \nfields\n.\ntx_pwr_lvl_is_present\n \n=\n \n1\n;\n \nfields\n.\ntx_pwr_lvl\n \n=\n \nBLE_HS_ADV_TX_PWR_LVL_AUTO\n;\n\n \nname\n \n=\n \nble_svc_gap_device_name\n();\n \nfields\n.\nname\n \n=\n (\nuint8_t\n \n*\n)\nname\n;\n \nfields\n.\nname_len\n \n=\n \nstrlen\n(\nname\n);\n \nfields\n.\nname_is_complete\n \n=\n \n1\n;\n\n \nfields\n.\nuuids16\n \n=\n (\nble_uuid16_t\n[]){\n \nBLE_UUID16_INIT\n(\nGATT_SVR_SVC_ALERT_UUID\n)\n };\n \nfields\n.\nnum_uuids16\n \n=\n \n1\n;\n \nfields\n.\nuuids16_is_complete\n \n=\n \n1\n;\n\n \nrc\n \n=\n \nble_gap_adv_set_fields\n(\nfields\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror setting advertisement data; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n\n \n/* Begin advertising. */\n\n \nmemset\n(\nadv_params\n, \n0\n, \nsizeof\n \nadv_params\n);\n \nadv_params\n.\nconn_mode\n \n=\n \nBLE_GAP_CONN_MODE_UND\n;\n \nadv_params\n.\ndisc_mode\n \n=\n \nBLE_GAP_DISC_MODE_GEN\n;\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_OWN_ADDR_PUBLIC\n, \nNULL\n, \nBLE_HS_FOREVER\n,\n \nadv_params\n, \nbleprph_gap_event\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror enabling advertisement; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n}\n\n\n\n\n\nThe call to \nble_gap_adv_set_fields()\n configures the device with normal\n(non-Eddystone) advertisements; the call to \nble_gap_adv_start()\n tells the\nNimBLE stack to start broadcasting. We are now going to create an Eddystone app\nby making the following changes:\n\n\n\n\nCall \nble_eddystone_set_adv_data()\n instead of \nble_gap_adv_set_fields()\n. The tutorial shows how to emit \"`https://mynewt.apache.org\".\n\n\nRemove advertisement data such as device name, flags, tx levels etc. that are not required. \n\n\nRemove unnecessary local variables e.g. \nname\n pointer. \n\n\nModify the call to \nble_gap_adv_start()\n such that the device is non-discoverable and non-connectable.\n\n\n\n\n\n\nstatic\n \nvoid\n\n\nbleprph_advertise\n(\nvoid\n)\n{ \n \nstruct\n \nble_gap_adv_params\n \nadv_params\n;\n \nstruct\n \nble_hs_adv_fields\n \nfields\n;\n \nint\n \nrc\n;\n\n \n/** \n\n\n * Remove the advertisement data typically included in our advertisements: \n\n\n * o Flags (indicates advertisement type and other general info).\n\n\n * o Advertising tx power.\n\n\n * o Device name.\n\n\n * o 16-bit service UUIDs (alert notifications).\n\n\n */\n\n\n \nmemset\n(\nfields\n, \n0\n, \nsizeof\n \nfields\n);\n\n\n \n/* No flags are needed for Eddystone URL. Remove all from default app.*/\n\n\n\n\n \nrc\n \n=\n \nble_eddystone_set_adv_data_url\n(\nfields\n, \nBLE_EDDYSTONE_URL_SCHEME_HTTPS\n, \nmynewt.apache\n, \n\n \n13\n, \nBLE_EDDYSTONE_URL_SUFFIX_ORG\n); \n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror setting eddystone advertisement data; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n\n \n/* Begin advertising. */\n\n \nmemset\n(\nadv_params\n, \n0\n, \nsizeof\n \nadv_params\n);\n\n \nadv_params\n.\nconn_mode\n \n=\n \nBLE_GAP_CONN_MODE_NON\n;\n\n \nadv_params\n.\ndisc_mode\n \n=\n \nBLE_GAP_DISC_MODE_NON\n;\n\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_OWN_ADDR_PUBLIC\n, \nNULL\n, \nBLE_HS_FOREVER\n,\n \nadv_params\n, \nbleprph_gap_event\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror enabling advertisement; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n}\n\n\n\n\n\nAlso include the header file for the eddystone beacon \nble_eddystone.h\n in the app's main.c file. \n\n\n#include\n \nhost/ble_eddystone.h\n\n\n\n\n\n\nIf you have copied the bleprph app into your local repository then make sure that the pkg.yml for the app has the \n@apache-mynewt-core/\n prefix; otherwise the package dependencies will not be resolved correctly.\n\n\npkg.deps: \n - \n@apache-mynewt-core/boot/split\n\n - \n@apache-mynewt-core/kernel/os\n\n\nsnip\n\n\n\n\n\n\nFinally, enable the \nBLE_EDDYSTONE\n sysconfig in the syscfg.yml of either your target or your app.\n\n\nsyscfg.vals:\n \nsnip\n\n BLE_EDDYSTONE: 1 \n\n\n\n\n\nNow when you run this app on your board, you should be able to see it with all\nyour Eddystone-aware devices.",
- "title": "BLE Eddystone"
- },
- {
- "location": "/os/tutorials/eddystone/#ble-eddystone",
- "text": "",
- "title": "BLE Eddystone"
- },
- {
- "location": "/os/tutorials/eddystone/#eddystone-beacon-protocol",
- "text": "A beaconing device announces its presence to the world by broadcasting\nadvertisements. The Eddystone protocol is built on top of the standard BLE\nadvertisement specification. Eddystone supports multiple data packet types Eddystone-UID: a unique, static ID with a 10-byte Namespace component and a 6-byte Instance component. Eddystone-URL: a compressed URL that, once parsed and decompressed, is directly usable by the client. Eddystone-TLM: \"telemetry\" packets that are broadcast alongside the Eddystone-UID or Eddystone-URL packets and contains beacon\u2019s \u201chealth status\u201d (e.g., battery life). Eddystone-EID to broadcast an ephemeral identifier that changes every few minutes and allow only parties that can resolve the identifier to use the beacon. This page describes the Eddystone open beacon format developed by Google. Apache Mynewt currently supports Eddystone-UID and Eddystone-URL formats only. This tutorial will explain how to get an Eddystone-URL beacon going on a peripheral device.",
- "title": "Eddystone Beacon Protocol"
- },
- {
- "location": "/os/tutorials/eddystone/#configuration",
- "text": "Use the following function to configure your NimBLE device to send Eddystone-URL beacons: int ble_eddystone_set_adv_data_url ( struct ble_hs_adv_fields *adv_fields ,\n uint8_t url_scheme , char *url_body ,\n uint8_t url_body_len , uint8_t url_suffix ) This function's parameters are documented below. Parameter Purpose adv_fields The base advertisement fields to transform into an eddystone beacon. url_scheme The prefix of the URL; one of the BLE_EDDYSTONE_URL_SCHEME values from ble_eddystone.h url_body The middle of the url specified within \"\". url_body_len The string length of the url_body argument. url_suffix The suffix of the URL; one of the BLE_EDDYSTONE_URL_SUFFIX values from ble_eddystone.h",
- "title": "Configuration"
- },
- {
- "location": "/os/tutorials/eddystone/#modify-bleprph",
- "text": "To demonstrate how the above function is used, we will now modify the bleprph \nexample application to send Eddystone beacons. For some background behind the bleprph \napp, we recommend you take a look at the bleprph project\ntutorial . If you plan on making these modifications\nyourself, it might be a good idea to copy bleprph to your local repository\nand work with the copy. In general, you should avoid changing a package that\nnewt downloads, as you will lose your changes the next time you upgrade the\npackage. bleprph sets its advertisement data and begins advertising as follows ( main.c ): static void bleprph_advertise ( void )\n{\n struct ble_gap_adv_params adv_params ;\n struct ble_hs_adv_fields fields ;\n const char *name ;\n int rc ;\n\n /** * Set the advertisement data included in our advertisements: * o Flags (indicates advertisement type and other general info). * o Advertising tx power. * o Device name. * o 16-bit service UUIDs (alert notifications). */ \n\n memset ( fields , 0 , sizeof fields );\n\n /* Advertise two flags: * o Discoverability in forthcoming advertisement (general) * o BLE-only (BR/EDR unsupported). */ \n fields . flags = BLE_HS_ADV_F_DISC_GEN | \n BLE_HS_ADV_F_BREDR_UNSUP ;\n\n /* Indicate that the TX power level field should be included; have the * stack fill this value automatically. This is done by assiging the * special value BLE_HS_ADV_TX_PWR_LVL_AUTO. */ \n fields . tx_pwr_lvl_is_present = 1 ;\n fields . tx_pwr_lvl = BLE_HS_ADV_TX_PWR_LVL_AUTO ;\n\n name = ble_svc_gap_device_name ();\n fields . name = ( uint8_t * ) name ;\n fields . name_len = strlen ( name );\n fields . name_is_complete = 1 ;\n\n fields . uuids16 = ( ble_uuid16_t []){\n BLE_UUID16_INIT ( GATT_SVR_SVC_ALERT_UUID )\n };\n fields . num_uuids16 = 1 ;\n fields . uuids16_is_complete = 1 ;\n\n rc = ble_gap_adv_set_fields ( fields );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error setting advertisement data; rc=%d\\n , rc );\n return ;\n }\n\n /* Begin advertising. */ \n memset ( adv_params , 0 , sizeof adv_params );\n adv_params . conn_mode = BLE_GAP_CONN_MODE_UND ;\n adv_params . disc_mode = BLE_GAP_DISC_MODE_GEN ;\n rc = ble_gap_adv_start ( BLE_OWN_ADDR_PUBLIC , NULL , BLE_HS_FOREVER ,\n adv_params , bleprph_gap_event , NULL );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error enabling advertisement; rc=%d\\n , rc );\n return ;\n }\n} The call to ble_gap_adv_set_fields() configures the device with normal\n(non-Eddystone) advertisements; the call to ble_gap_adv_start() tells the\nNimBLE stack to start broadcasting. We are now going to create an Eddystone app\nby making the following changes: Call ble_eddystone_set_adv_data() instead of ble_gap_adv_set_fields() . The tutorial shows how to emit \"`https://mynewt.apache.org\". Remove advertisement data such as device name, flags, tx levels etc. that are not required. Remove unnecessary local variables e.g. name pointer. Modify the call to ble_gap_adv_start() such that the device is non-discoverable and non-connectable. static void bleprph_advertise ( void )\n{ \n struct ble_gap_adv_params adv_params ;\n struct ble_hs_adv_fields fields ;\n int rc ;\n\n /** * Remove the advertisement data typically included in our advertisements: * o Flags (indicates advertisement type and other general info). * o Advertising tx power. * o Device name. * o 16-bit service UUIDs (alert notifications). */ \n\n memset ( fields , 0 , sizeof fields ); /* No flags are needed for Eddystone URL. Remove all from default app.*/ rc = ble_eddystone_set_adv_data_url ( fields , BLE_EDDYSTONE_URL_SCHEME_HTTPS , mynewt.apache , 13 , BLE_EDDYSTONE_URL_SUFFIX_ORG ); \n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error setting eddystone advertisement data; rc=%d\\n , rc );\n return ;\n }\n\n /* Begin advertising. */ \n memset ( adv_params , 0 , sizeof adv_params ); adv_params . conn_mode = BLE_GAP_CONN_MODE_NON ; adv_params . disc_mode = BLE_GAP_DISC_MODE_NON ; rc = ble_gap_adv_start ( BLE_OWN_ADDR_PUBLIC , NULL , BLE_HS_FOREVER ,\n adv_params , bleprph_gap_event , NULL );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error enabling advertisement; rc=%d\\n , rc );\n return ;\n }\n} Also include the header file for the eddystone beacon ble_eddystone.h in the app's main.c file. #include host/ble_eddystone.h If you have copied the bleprph app into your local repository then make sure that the pkg.yml for the app has the @apache-mynewt-core/ prefix; otherwise the package dependencies will not be resolved correctly. pkg.deps: \n - @apache-mynewt-core/boot/split \n - @apache-mynewt-core/kernel/os snip Finally, enable the BLE_EDDYSTONE sysconfig in the syscfg.yml of either your target or your app. syscfg.vals:\n snip \n BLE_EDDYSTONE: 1 Now when you run this app on your board, you should be able to see it with all\nyour Eddystone-aware devices.",
- "title": "Modify bleprph"
- },
- {
- "location": "/os/tutorials/add_newtmgr/",
- "text": "Enabling Newt Manager in Your Application\n\n\n\nIn order for your application to communicate with the newtmgr tool and process Newt Manager commands, you must \nenable Newt Manager device management and the support to process Newt Manager commands \nin your application. This tutorial explains how to add the support to your application.\n\n\nThis tutorial assumes that you have read the \nDevice Management with Newt Manager\n\nguide and are familiar with the \nnewtmgr\n and \noicmgr\n frameworks and all the options that are available \nto customize your application.\n\n\nThis tutorial shows you how to configure your application to:\n\n\n\n\nUse the newtmgr framework.\n\n\nUse serial transport to communicate with the newtmgr tool.\n\n\nSupport all Newt Manager commands.\n\n\n\n\nSee \nOther Configuration Options\n on how to customize your application.\n\n\n\n\nPrerequisites\n\n\nEnsure that you have met the following prerequisites before continuing with this tutorial:\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a cable to establish a serial USB connection between the board and the laptop.\n\n\nInstall the newt tool and toolchains (See \nBasic Setup\n).\n\n\nInstall the \nnewtmgr tool\n.\n\n\n\n\n\n\nUse an Existing Project\n\n\nWe assume that you have worked through at least some of the other tutorials and have an existing project.\nIn this example, we modify the \nble_tiny\n project to enable Newt Manager support. \nWe call our application \nmyble\n. You can create the application using any name you choose. \n\n\nModify Package Dependencies and Configurations\n\n\nAdd the following packages to the \npkg.deps\n parameter in your target or application \npkg.yml\n file:\n\n\npkg.deps:\n - mgmt/newtmgr\n - mgmt/newtmgr/transport/nmgr_shell\n - mgmt/imgmgr\n - sys/log/full\n - sys/stats/full\n - sys/config\n - test/crash_test\n - test/runtest\n\n\n\n\n\nEach package provides the following Newt Manager functionality:\n\n\n\n\nmgmt/newtmgr\n: Supports the newtmgr framework and the \nNewt Manager \necho\n, \ntaskstat\n \nmpstat\n, \ndatetime\n, and \nreset\n commands.\n\n\nmgmt/newtmgr/transport/nmgr_shell\n: Supports serial transport.\n\n\nmgmt/imgmgr\n: Supports the \nnewtmgr image\n command \n\n\nsys/log/full\n : Supports the \nnewtmgr log\n command.\n\n\nsys/stats/full\n: Supports the \nnewtmgr stat\n command. \n\n\nsys/config\n: Supports the \nnewtmgr config\n command. \n\n\ntest/crash_test\n: Supports the \nnewtmgr crash\n command. \n\n\ntest/runtest\n: Supports the \nnewt run\n command.\n\n\n\n\nAdd the following configuration setting values to the \nsyscfg.vals\n parameter in the target or \napplication \nsyscfg.yml\n file:\n\n\nsyscfg.vals:\n LOG_NEWTMGR: 1\n STATS_NEWTMGR: 1\n CONFIG_NEWTMGR: 1\n CRASH_TEST_NEWTMGR: 1\n RUNTEST_NEWTMGR: 1\n SHELL_TASK: 1\n\n\n\n\n\nThe first five configuration settings enable support for the Newt Manager \nlog\n, \nstat\n, \nconfig\n, \ncrash\n, \nand \nrun\n commands. The \nSHELL_TASK\n setting enables the shell for serial transport.\n\n\nNote that you may need to override additional configuration settings that are specific to each package to customize the \npackage functionality.\n\n\n\n\nModify the Source\n\n\nBy default, the \nmgmt\n package uses the Mynewt default event queue to receive request events from the newtmgr tool. These events are processed in the context of the application main task. \n\n\nYou can specify a different event queue for the package to use. If you choose to use a dedicated event queue, you must create a task to process events from this event queue. The \nmgmt\n package executes and handles newtmgr request events in the context of this task. The \nmgmt\n package exports the \nmgmt_evq_set()\n function that allows you to specify an event queue. \n\n\nThis example uses the Mynewt default event queue and you do not need to modify your application source. \n\n\nIf you choose to use a different event queue, see \nEvents and Event Queues\n for details on how to initialize an event queue and create a task to process the events. You will also need to modify your \nmain.c\n to add the call to the \nmgmt_evq_set()\n function as follows:\n\n\nAdd the \nmgmt/mgmt.h\n header file: \n\n\n#include \nmgmt/mgmt.h\n\n\n\n\n\n\n\nAdd the call to specify the event queue. In the \nmain()\n function, scroll down to the \nwhile (1)\n loop and add the following statement above the loop: \n\n\nmgmt_evq_set(\nmy_eventq)\n\n\n\n\n\nwhere \nmy_eventq\n is an event queue that you have initialized.\n\n\nBuild the Targets\n\n\nBuild the two targets as follows:\n\n\n$ newt build nrf52_boot\n\nsnip\n\nApp successfully built: ./bin/nrf52_boot/apps/boot/boot.elf\n$ newt build myble\nCompiling hci_common.c\nCompiling util.c\nArchiving nimble.a\nCompiling os.c\n\nsnip\n\n\n\n\n\n\n\n\nCreate the Application Image\n\n\nGenerate a signed application image for the \nmyble\n target. You can use any version number you choose.\n\n\n$ newt create-image myble 1.0.0\nApp image successfully generated: ./bin/makerbeacon/apps/bletiny/bletiny.img\nBuild manifest: ./bin/makerbeacon/apps/bletiny/manifest.json\n\n\n\n\n\n\n\nLoad the Image\n\n\nEnsure the USB connector is in place and the power LED on the board is lit. Turn the power switch on your board off, \nthen back on to reset the board after loading the image.\n\n\n$ newt load nrf52_boot\n$ newt load myble\n\n\n\n\n\nSet Up a Connection Profile\n\n\nThe newtmgr tool requires a connection profile in order to connect to your board. If you have not done so, \nfollow the \ninstructions\n for setting up your connection profile.\n\n\n\n\nCommunicate with Your Application\n\n\nOnce you have a connection profile set up, you can connect to your device with \nnewtmgr -c myconn \ncommand\n to run commands in your application. \n\n\nIssue the \necho\n command to ensure that your application is communicating with the newtmgr tool:\n\n\n# newtmgr -c myconn echo hello\nhello\n\n\n\n\n\nTest your application to ensure that it can process a Newt Manager command that is supported by a different package.\nIssue the \nstat\n command to see the BLE stats. \n\n\nnewtmgr -c myconn stat ble_att\nReturn Code = 0\nStats Name: ble_att\n prep_write_req_tx: 0\n indicate_req_tx: 0\n write_rsp_tx: 0\n find_info_req_tx: 0\n read_rsp_rx: 0\n read_group_type_rsp_tx: 0\n indicate_req_rx: 0\n find_type_value_rsp_tx: 0\n\n ...\n\n read_req_rx: 0\n read_type_req_rx: 0\n notify_req_tx: 0\n mtu_rsp_tx: 0\n find_type_value_req_rx: 0\n read_blob_rsp_rx: 0\n read_group_type_req_tx: 0\n exec_write_req_tx: 0\n\n\n\n\n\nYour application is now able to communicate with the newtmgr tool.\n\n\nOther Configuration Options\n\n\nThis section explains how to customize your application to use other Newt Manager protocol options.\n\n\nNewtmgr Framework Transport Protocol Options\n\n\nThe newtmgr framework currently supports BLE and serial transport protocols. \nTo configure the transport protocols that are supported, modify the \npkg.yml\n \nand \nsyscfg.yml\n files as follows:\n\n\n\n\nAdd the \nmgmt/newtmgr/transport/ble\n package to the \npkg.deps\n parameter to enable BLE transport.\n\n\nAdd the \nmgmt/newtmgr/transport/nmgr_shell\n package to \nthe \npkg.deps\n parameter, and add \nSHELL_TASK: 1\n to the \nsyscfg.vals\n parameter to enable serial transport when your application also uses the \nShell\n.\n\n\nAdd the \nmgmt/newtmgr/transport/nmgr_uart\n package to the \npkg.deps\n parameter to enable serial transport over a UART port. You can use this package instead of the \nnmgr_shell\n package when your application does not use the \nShell\n or you want to use a dedicated UART port to communicate with newtmgr. You can change the \nNMGR_UART\n and \nNMGR_URART_SPEED\n sysconfig values to specify a different port.\n\n\n\n\n\n\nOicmgr Framework Options\n\n\nTo use the oicmgr framework instead of the newtmgr framework, modify the \npkg.yml\n and \nsyscfg.yml\n files \nas follows:\n\n\n\n\nAdd the \nmgmt/oicmgr\n package (instead of the \nmgmt/newtmgr\n and \nmgmt/newtmgr/transport\n packages \nas described previously) to the \npkg.deps\n parameter.\n\n\nAdd \nOC_SERVER: 1\n to the \nsyscfg.vals\n parameter.\n\n\n\n\nOicmgr supports the IP, serial, and BLE transport protocols. To configure the transport protocols that are supported, \nset the configuration setting values in the \nsyscfg.vals\n parameter as follows:\n\n\n\n\nAdd \nOC_TRANSPORT_IP: 1\n to enable IP transport. \n\n\nAdd \nOC_TRANSPORT_GATT: 1\n to enable BLE transport.\n\n\nAdd \nOC_TRANSPORT_SERIAL: 1\n and \nSHELL_TASK: 1\n to enable serial transport.\n\n\n\n\n\n\nCustomize the Newt Manager Commands that Your Application Supports\n\n\nWe recommend that you only enable support for the Newt Manager commands that your application uses \nto reduce your application code size. To configure the commands that are supported, set the configuration \nsetting values in the \nsyscfg.vals\n parameter as follows:\n\n\n\n\nAdd \nLOG_NEWTMGR: 1\n to enable support for the \nnewtmgr log\n command.\n\n\nAdd \nSTATS_NEWTMGR: 1\n to enable support for the \nnewtmgr stat\n command.\n\n\nAdd \nCONFIG_NEWTMGR: 1\n to enable support for the \nnewtmgr config\n command.\n\n\nAdd \nCRASH_TEST_NEWTMGR: 1\n to enable support for the \nnewtmgr crash\n command.\n\n\nAdd \nRUNTEST_NEWTMGR: 1\n to enable support for the \nnewtmgr crash\n command.\n\n\n\n\nNotes: \n\n\n\n\nWhen you enable Newt Manager support, using either the newtmgr or oicmgr framework, your application automatically \nsupports the Newt Manager \necho\n, \ntaskstat\n, \nmpstat\n, \ndatetime\n, and \nreset\n commands. These \ncommands cannot be configured individually.\n\n\nThe \nmgmt/imgmgr\n package does not provide a configuration setting to enable or disable support \nfor the \nnewtmgr image\n command. Do not specify the package in the \npkg.deps\n parameter if \nyour device has limited flash memory and cannot support Over-The-Air (OTA) firmware upgrades.",
- "title": "Enable Newt Manager in any app"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#enabling-newt-manager-in-your-application",
- "text": "In order for your application to communicate with the newtmgr tool and process Newt Manager commands, you must \nenable Newt Manager device management and the support to process Newt Manager commands \nin your application. This tutorial explains how to add the support to your application. This tutorial assumes that you have read the Device Management with Newt Manager \nguide and are familiar with the newtmgr and oicmgr frameworks and all the options that are available \nto customize your application. This tutorial shows you how to configure your application to: Use the newtmgr framework. Use serial transport to communicate with the newtmgr tool. Support all Newt Manager commands. See Other Configuration Options on how to customize your application.",
- "title": "Enabling Newt Manager in Your Application"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#prerequisites",
- "text": "Ensure that you have met the following prerequisites before continuing with this tutorial: Have Internet connectivity to fetch remote Mynewt components. Have a cable to establish a serial USB connection between the board and the laptop. Install the newt tool and toolchains (See Basic Setup ). Install the newtmgr tool .",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#use-an-existing-project",
- "text": "We assume that you have worked through at least some of the other tutorials and have an existing project.\nIn this example, we modify the ble_tiny project to enable Newt Manager support. \nWe call our application myble . You can create the application using any name you choose.",
- "title": "Use an Existing Project"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#modify-package-dependencies-and-configurations",
- "text": "Add the following packages to the pkg.deps parameter in your target or application pkg.yml file: pkg.deps:\n - mgmt/newtmgr\n - mgmt/newtmgr/transport/nmgr_shell\n - mgmt/imgmgr\n - sys/log/full\n - sys/stats/full\n - sys/config\n - test/crash_test\n - test/runtest Each package provides the following Newt Manager functionality: mgmt/newtmgr : Supports the newtmgr framework and the \nNewt Manager echo , taskstat mpstat , datetime , and reset commands. mgmt/newtmgr/transport/nmgr_shell : Supports serial transport. mgmt/imgmgr : Supports the newtmgr image command sys/log/full : Supports the newtmgr log command. sys/stats/full : Supports the newtmgr stat command. sys/config : Supports the newtmgr config command. test/crash_test : Supports the newtmgr crash command. test/runtest : Supports the newt run command. Add the following configuration setting values to the syscfg.vals parameter in the target or \napplication syscfg.yml file: syscfg.vals:\n LOG_NEWTMGR: 1\n STATS_NEWTMGR: 1\n CONFIG_NEWTMGR: 1\n CRASH_TEST_NEWTMGR: 1\n RUNTEST_NEWTMGR: 1\n SHELL_TASK: 1 The first five configuration settings enable support for the Newt Manager log , stat , config , crash , \nand run commands. The SHELL_TASK setting enables the shell for serial transport. Note that you may need to override additional configuration settings that are specific to each package to customize the \npackage functionality.",
- "title": "Modify Package Dependencies and Configurations"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#modify-the-source",
- "text": "By default, the mgmt package uses the Mynewt default event queue to receive request events from the newtmgr tool. These events are processed in the context of the application main task. You can specify a different event queue for the package to use. If you choose to use a dedicated event queue, you must create a task to process events from this event queue. The mgmt package executes and handles newtmgr request events in the context of this task. The mgmt package exports the mgmt_evq_set() function that allows you to specify an event queue. This example uses the Mynewt default event queue and you do not need to modify your application source. If you choose to use a different event queue, see Events and Event Queues for details on how to initialize an event queue and create a task to process the events. You will also need to modify your main.c to add the call to the mgmt_evq_set() function as follows: Add the mgmt/mgmt.h header file: #include mgmt/mgmt.h \nAdd the call to specify the event queue. In the main() function, scroll down to the while (1) loop and add the following statement above the loop: mgmt_evq_set( my_eventq) where my_eventq is an event queue that you have initialized.",
- "title": "Modify the Source"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#build-the-targets",
- "text": "Build the two targets as follows: $ newt build nrf52_boot snip \nApp successfully built: ./bin/nrf52_boot/apps/boot/boot.elf\n$ newt build myble\nCompiling hci_common.c\nCompiling util.c\nArchiving nimble.a\nCompiling os.c snip",
- "title": "Build the Targets"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#create-the-application-image",
- "text": "Generate a signed application image for the myble target. You can use any version number you choose. $ newt create-image myble 1.0.0\nApp image successfully generated: ./bin/makerbeacon/apps/bletiny/bletiny.img\nBuild manifest: ./bin/makerbeacon/apps/bletiny/manifest.json",
- "title": "Create the Application Image"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#load-the-image",
- "text": "Ensure the USB connector is in place and the power LED on the board is lit. Turn the power switch on your board off, \nthen back on to reset the board after loading the image. $ newt load nrf52_boot\n$ newt load myble",
- "title": "Load the Image"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#set-up-a-connection-profile",
- "text": "The newtmgr tool requires a connection profile in order to connect to your board. If you have not done so, \nfollow the instructions for setting up your connection profile.",
- "title": "Set Up a Connection Profile"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#communicate-with-your-application",
- "text": "Once you have a connection profile set up, you can connect to your device with newtmgr -c myconn command to run commands in your application. Issue the echo command to ensure that your application is communicating with the newtmgr tool: # newtmgr -c myconn echo hello\nhello Test your application to ensure that it can process a Newt Manager command that is supported by a different package.\nIssue the stat command to see the BLE stats. newtmgr -c myconn stat ble_att\nReturn Code = 0\nStats Name: ble_att\n prep_write_req_tx: 0\n indicate_req_tx: 0\n write_rsp_tx: 0\n find_info_req_tx: 0\n read_rsp_rx: 0\n read_group_type_rsp_tx: 0\n indicate_req_rx: 0\n find_type_value_rsp_tx: 0\n\n ...\n\n read_req_rx: 0\n read_type_req_rx: 0\n notify_req_tx: 0\n mtu_rsp_tx: 0\n find_type_value_req_rx: 0\n read_blob_rsp_rx: 0\n read_group_type_req_tx: 0\n exec_write_req_tx: 0 Your application is now able to communicate with the newtmgr tool.",
- "title": "Communicate with Your Application"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#other-configuration-options",
- "text": "This section explains how to customize your application to use other Newt Manager protocol options.",
- "title": "Other Configuration Options"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#newtmgr-framework-transport-protocol-options",
- "text": "The newtmgr framework currently supports BLE and serial transport protocols. \nTo configure the transport protocols that are supported, modify the pkg.yml \nand syscfg.yml files as follows: Add the mgmt/newtmgr/transport/ble package to the pkg.deps parameter to enable BLE transport. Add the mgmt/newtmgr/transport/nmgr_shell package to \nthe pkg.deps parameter, and add SHELL_TASK: 1 to the syscfg.vals parameter to enable serial transport when your application also uses the Shell . Add the mgmt/newtmgr/transport/nmgr_uart package to the pkg.deps parameter to enable serial transport over a UART port. You can use this package instead of the nmgr_shell package when your application does not use the Shell or you want to use a dedicated UART port to communicate with newtmgr. You can change the NMGR_UART and NMGR_URART_SPEED sysconfig values to specify a different port.",
- "title": "Newtmgr Framework Transport Protocol Options"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#oicmgr-framework-options",
- "text": "To use the oicmgr framework instead of the newtmgr framework, modify the pkg.yml and syscfg.yml files \nas follows: Add the mgmt/oicmgr package (instead of the mgmt/newtmgr and mgmt/newtmgr/transport packages \nas described previously) to the pkg.deps parameter. Add OC_SERVER: 1 to the syscfg.vals parameter. Oicmgr supports the IP, serial, and BLE transport protocols. To configure the transport protocols that are supported, \nset the configuration setting values in the syscfg.vals parameter as follows: Add OC_TRANSPORT_IP: 1 to enable IP transport. Add OC_TRANSPORT_GATT: 1 to enable BLE transport. Add OC_TRANSPORT_SERIAL: 1 and SHELL_TASK: 1 to enable serial transport.",
- "title": "Oicmgr Framework Options"
- },
- {
- "location": "/os/tutorials/add_newtmgr/#customize-the-newt-manager-commands-that-your-application-supports",
- "text": "We recommend that you only enable support for the Newt Manager commands that your application uses \nto reduce your application code size. To configure the commands that are supported, set the configuration \nsetting values in the syscfg.vals parameter as follows: Add LOG_NEWTMGR: 1 to enable support for the newtmgr log command. Add STATS_NEWTMGR: 1 to enable support for the newtmgr stat command. Add CONFIG_NEWTMGR: 1 to enable support for the newtmgr config command. Add CRASH_TEST_NEWTMGR: 1 to enable support for the newtmgr crash command. Add RUNTEST_NEWTMGR: 1 to enable support for the newtmgr crash command. Notes: When you enable Newt Manager support, using either the newtmgr or oicmgr framework, your application automatically \nsupports the Newt Manager echo , taskstat , mpstat , datetime , and reset commands. These \ncommands cannot be configured individually. The mgmt/imgmgr package does not provide a configuration setting to enable or disable support \nfor the newtmgr image command. Do not specify the package in the pkg.deps parameter if \nyour device has limited flash memory and cannot support Over-The-Air (OTA) firmware upgrades.",
- "title": "Customize the Newt Manager Commands that Your Application Supports"
- },
- {
- "location": "/os/tutorials/add_shell/",
- "text": "Enabling The Console and Shell in a project\n\n\n\n\nThis tutorial explains how to add the Console and Shell task to a project so that you \ncan interact with your project over a serial line connection.\n\n\n\n\nPrerequisites\n\n\nEnsure that you have met the following prerequisites before continuing with this tutorial:\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components. \n\n\nHave a cable to establish a serial USB connection between the board and the laptop\n\n\nInstall the newt tool and toolchains (See \nBasic Setup\n).\n\n\nInstall the \nSegger JLINK package\n to load your project on the board.\n\n\n\n\n\n\nUse an existing project\n\n\nSince all we're doing is adding the shell and console capability to a project, we assume \nthat you have worked through at least some of the other tutorials, and have an existing project.\nFor this example, we'll be modifying the \nble_tiny\n project to enable \nthe shell and console connectivity. We'll be calling our app myble as in that project as well. \nFeel free to use whatever project you'd like though.\n\n\n\n\nModify the Dependencies and Configuration\n\n\nThe first thing you'll need to add is a few new dependencies for your app. To add shell support to \nyour app make sure the following \npkg.deps\n are defined in your target's pkg.yml file:\n\n\npkg.deps:\n - \n@apache-mynewt-core/sys/console/full\n\n - \n@apache-mynewt-core/sys/shell\n\n - \n@apache-mynewt-core/sys/sysinit\n\n\n\n\n\n\nThis lets the newt system know that it needs to pull in the code for the console and the shell.\n\n\nNow we'll need to modify the settings for the app to turn on the shell, etc. by modifying the\n\nsyscfg.yml\n file for your target. (Remember, these files are in the targets/\n directory.)\nIf there isn't a \nsyscfg.yml\n file in your target's directory, you will need to create one.\n\n\n# Package: apps/bletiny\n\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n # Enable Console OS Ticks\n CONSOLE_TICKS: 1\n # Enable Console Prompt\n CONSOLE_PROMPT: 1 \n\n\n\n\n\nBuild targets\n\n\nWe're not going to build the bootloader here since we are assuming that you have already\nbuilt and loaded it during previous tutorials.\n\n\n$ newt build myble\nArchiving cbmem.a\nCompiling crc16.c\nCompiling crc8.c\nArchiving crc.a\nCompiling mem.c\nArchiving mem.a\nLinking ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nTarget successfully built: targets/myble\n\n\n\n\n\n\n\nCreate the app image\n\n\nGenerate a signed application image for the \nmyble\n target. The version number is arbitrary.\n\n\n$ newt create-image myble 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.img\n\n\n\n\n\n\n\nLoad the image\n\n\nMake 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.\n\n\n$ newt load myble\n\n\n\n\n\n\n\nSet up Serial connection\n\n\nYou'll need a Serial connection to see the output of your program. You can reference the \nSerial Port Setup\n \nTutorial for more information on setting up your serial communications.\n\n\n\n\nConnecting with your app\n\n\nOnce you have a connection set up, you can connect to your device as follows: \n\n\n\n\n\n\nOn Mac OS and Linux platforms, you can run \nminicom -D /dev/tty.usbserial-\nport\n -b 115200\n to connect to the console of your app. Note that on Linux, the format of the port name is \n/dev/ttyUSB\nN\n, where N is a number. \n\n\n\n\n\n\nOn Windows, you can use a terminal application such as PuTTY to connect to the device. \n\n\nIf you located your port from a MinGW terminal, the port name format is \n/dev/ttyS\nN\n, where \nN\n is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n. \n\n\nYou can also use the Windows Device Manager to locate the COM port.\n\n\n\n\n\n\n\nTo test and make sure that the Shell is running, first just hit \n:\n\n\n3534: \n\n\n\n\n\n\nRemember, we turned the CONSOLE_PROMPT and the CONSOLE_TICKS on earlier. You can try some commands now:\n\n\n3609: \n ?\nCommands:\n8841: echo ? prompt ticks tasks mempools\n8843: date b\n8844: \n ticks off\n Console Ticks off\n \n prompt off\n Prompt now off.\nticks on\n33383: Console Ticks on\n\n33568:\nprompt on\n39108: Prompt now on.\n39108:",
- "title": "Enable the OS Shell and Console"
- },
- {
- "location": "/os/tutorials/add_shell/#enabling-the-console-and-shell-in-a-project",
- "text": "This tutorial explains how to add the Console and Shell task to a project so that you \ncan interact with your project over a serial line connection.",
- "title": "Enabling The Console and Shell in a project"
- },
- {
- "location": "/os/tutorials/add_shell/#prerequisites",
- "text": "Ensure that you have met the following prerequisites before continuing with this tutorial: Have Internet connectivity to fetch remote Mynewt components. Have a cable to establish a serial USB connection between the board and the laptop Install the newt tool and toolchains (See Basic Setup ). Install the Segger JLINK package to load your project on the board.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/add_shell/#use-an-existing-project",
- "text": "Since all we're doing is adding the shell and console capability to a project, we assume \nthat you have worked through at least some of the other tutorials, and have an existing project.\nFor this example, we'll be modifying the ble_tiny project to enable \nthe shell and console connectivity. We'll be calling our app myble as in that project as well. \nFeel free to use whatever project you'd like though.",
- "title": "Use an existing project"
- },
- {
- "location": "/os/tutorials/add_shell/#modify-the-dependencies-and-configuration",
- "text": "The first thing you'll need to add is a few new dependencies for your app. To add shell support to \nyour app make sure the following pkg.deps are defined in your target's pkg.yml file: pkg.deps:\n - @apache-mynewt-core/sys/console/full \n - @apache-mynewt-core/sys/shell \n - @apache-mynewt-core/sys/sysinit This lets the newt system know that it needs to pull in the code for the console and the shell. Now we'll need to modify the settings for the app to turn on the shell, etc. by modifying the syscfg.yml file for your target. (Remember, these files are in the targets/ directory.)\nIf there isn't a syscfg.yml file in your target's directory, you will need to create one. # Package: apps/bletiny\n\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n # Enable Console OS Ticks\n CONSOLE_TICKS: 1\n # Enable Console Prompt\n CONSOLE_PROMPT: 1",
- "title": "Modify the Dependencies and Configuration"
- },
- {
- "location": "/os/tutorials/add_shell/#build-targets",
- "text": "We're not going to build the bootloader here since we are assuming that you have already\nbuilt and loaded it during previous tutorials. $ newt build myble\nArchiving cbmem.a\nCompiling crc16.c\nCompiling crc8.c\nArchiving crc.a\nCompiling mem.c\nArchiving mem.a\nLinking ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nTarget successfully built: targets/myble",
- "title": "Build targets"
- },
- {
- "location": "/os/tutorials/add_shell/#create-the-app-image",
- "text": "Generate a signed application image for the myble target. The version number is arbitrary. $ newt create-image myble 1.0.0\nApp image succesfully generated: ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.img",
- "title": "Create the app image"
- },
- {
- "location": "/os/tutorials/add_shell/#load-the-image",
- "text": "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. $ newt load myble",
- "title": "Load the image"
- },
- {
- "location": "/os/tutorials/add_shell/#set-up-serial-connection",
- "text": "You'll need a Serial connection to see the output of your program. You can reference the Serial Port Setup \nTutorial for more information on setting up your serial communications.",
- "title": "Set up Serial connection"
- },
- {
- "location": "/os/tutorials/add_shell/#connecting-with-your-app",
- "text": "Once you have a connection set up, you can connect to your device as follows: On Mac OS and Linux platforms, you can run minicom -D /dev/tty.usbserial- port -b 115200 to connect to the console of your app. Note that on Linux, the format of the port name is /dev/ttyUSB N , where N is a number. On Windows, you can use a terminal application such as PuTTY to connect to the device. If you located your port from a MinGW terminal, the port name format is /dev/ttyS N , where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . You can also use the Windows Device Manager to locate the COM port. \nTo test and make sure that the Shell is running, first just hit : 3534: Remember, we turned the CONSOLE_PROMPT and the CONSOLE_TICKS on earlier. You can try some commands now: 3609: ?\nCommands:\n8841: echo ? prompt ticks tasks mempools\n8843: date b\n8844: ticks off\n Console Ticks off\n prompt off\n Prompt now off.\nticks on\n33383: Console Ticks on\n\n33568:\nprompt on\n39108: Prompt now on.\n39108:",
- "title": "Connecting with your app"
- },
- {
- "location": "/os/tutorials/codesize/",
- "text": "How to Reduce Application Code Size\n\n\nGettng your application to fit in an image slot can be challenging,\nparticularly on flash constrained hardware such as the nRF51. Below are\nsome suggested system configuration settings that reduce the code size of your Mynewt image.\n\n\n\n\n\n\n\n\nSetting\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nLOG_LEVEL: 255\n\n\nDisable all logging.\n\n\n\n\n\n\nLOG_CLI: 0\n\n\nDisable log shell commands.\n\n\n\n\n\n\nSTATS_CLI: 0\n\n\nDisable stats shell commands.\n\n\n\n\n\n\nSHELL_TASK: 0\n\n\nDisable the interactive shell.\n\n\n\n\n\n\nSHELL_OS_MODULE: 0\n\n\nDisable memory management shell commands.\n\n\n\n\n\n\nSHELL_CMD_HELP: 0\n\n\nDisable help for shell commands.\n\n\n\n\n\n\n\n\nYou can use the \nnewt target set\n command to set the syscfg settings in the \nsyscfg.yml\n file for the target. See the \nNewt Tool Command Guide\n for the command syntax\n\n\nNote:\n The \nnewt target set\n command deletes all the current syscfg settings in the target \nsyscfg.yml\n file and only sets the syscfg settings specified in the command. If you are experimenting with different settings to see how they affect the code size and do not want to reenter all the setting values in the \nnewt target set\n command, you can use the \nnewt target append\n command. This command adds or updates only the settings specified in the command and does not overwrite other setting values. While you can also edit the target \nsyscfg.yml\n file directly, we recommend that you use the \nnewt target\n commands.",
- "title": "How to Reduce Application Code Size"
- },
- {
- "location": "/os/tutorials/codesize/#how-to-reduce-application-code-size",
- "text": "Gettng your application to fit in an image slot can be challenging,\nparticularly on flash constrained hardware such as the nRF51. Below are\nsome suggested system configuration settings that reduce the code size of your Mynewt image. Setting Description LOG_LEVEL: 255 Disable all logging. LOG_CLI: 0 Disable log shell commands. STATS_CLI: 0 Disable stats shell commands. SHELL_TASK: 0 Disable the interactive shell. SHELL_OS_MODULE: 0 Disable memory management shell commands. SHELL_CMD_HELP: 0 Disable help for shell commands. You can use the newt target set command to set the syscfg settings in the syscfg.yml file for the target. See the Newt Tool Command Guide for the command syntax Note: The newt target set command deletes all the current syscfg settings in the target syscfg.yml file and only sets the syscfg settings specified in the command. If you are experimenting with different settings to see how they affect the code size and do not want to reenter all the setting values in the newt target set command, you can use the newt target append command. This command adds or updates only the settings specified in the command and does not overwrite other setting values. While you can also edit the target syscfg.yml file directly, we recommend that you use the newt target commands.",
- "title": "How to Reduce Application Code Size"
- },
- {
- "location": "/os/tutorials/tasks_lesson/",
- "text": "Tasks and Priority Management\n\n\nTarget Platform: Arduino M0 Pro\n (or legacy Arduino Zero or Zero Pro, but not Arduino M0)\n\n\nThis lesson is designed to teach core OS concepts and strategies encountered when \nbuilding applications using Mynewt. Specifically, this lesson will cover tasks, \nsimple multitasking, and priority management running on an Arduino M0 Pro.\n\n\nPrerequisites\n\n\nBefore starting, you should read about Mynewt in the \nIntroduction\n \nsection and complete the \nQuickStart\n \nguide and the \nBlinky\n tutorial. \nFurthermore, it may be helpful to take a peek at the \ntask documentation\n \nfor additional insights.\n\n\nEquipment\n\n\nYou will need the following equipment:\n\n\n\n\nArduino M0 Pro (or legacy Arduino Zero or Zero Pro, but not Arduino M0)\n\n\nComputer with Mynewt installed\n\n\nUSB to Micro USB Cable\n\n\n\n\nBuild Your Application\n\n\nTo save time, we will simply modify the Blinky application. We'll add the Task Management code to\nthe Blinky application. Follow the \nArduino Zero Blinky tutorial\n \nto create a new project and build your bootloader and application. Finally, build and \nload the application to your Arduino to verify that everything is in order. Now let\u2019s get started!\n\n\nDefault Main Task\n\n\nDuring Mynewt system startup, Mynewt creates a default main task and executes the application \nmain()\n function in the context of this task. The main task priority defaults to 127 and can be configured with the \nOS_MAIN_TASK_PRIO\n system configuration setting.\n\n\nThe blinky application only has the \nmain\n task. The \nmain()\n function executes an infinite loop that toggles the led and sleeps for one second. \n\n\n\nCreate a New Task\n\n\nThe purpose of this section is to give an introduction to the important aspects of tasks \nand how to properly initialize them. First, let\u2019s define a second task called \nwork_task\n \nin main.c (located in apps/blinky/src):\n\n\nstruct\n \nos_task\n \nwork_task\n;\n\n\n\n\n\nA task is represented by the \nos_task\n \nstruct which will hold the task\u2019s information (name, state, priority, etc.). A task is made up of two \nmain elements, a task function (also known as a task handler) and a task stack.\n\n\nNext, let\u2019s take a look at what is required to initialize our new task.\n\n\nTask Stack\n\n\nThe task stack is an array of type \nos_stack_t\n which holds the program stack frames. Mynewt gives \nus the ability to set the stack size for a task giving the application developer room to optimize \nmemory usage. Since we\u2019re not short on memory, our \nwork_stack\n is plenty large \nfor the purpose of this lesson. Notice that the elements in our task stack are of type \nos_stack_t\n \nwhich are generally 32 bits, making our entire stack 1024 Bytes.\n\n\n \n#define WORK_STACK_SIZE OS_STACK_ALIGN(256)\n\n\n\n\n\n\nNote: The \nOS_STACK_ALIGN\n macro is used to align the stack based on the hardware architecture.\n\n\nTask Function\n\n\nA task function is essentially an infinite loop that waits for some \u201cevent\u201d to wake it up. In general, the task function is where the majority of work is done by a task. Let\u2019s write a task function for \nwork_task\n called \nwork_task_handler()\n:\n\n\nvoid\n\n\nwork_task_handler\n(\nvoid\n \n*arg\n)\n{\n \nstruct\n \nos_task\n \n*t\n;\n\n \ng_led_pin\n \n=\n \nLED_BLINK_PIN\n;\n \nhal_gpio_init_out\n(\ng_led_pin\n, \n1\n);\n\n \nwhile\n (\n1\n) {\n \nt\n \n=\n \nos_sched_get_current_task\n();\n \nassert\n(\nt-\nt_func\n \n==\n \nwork_task_handler\n);\n \n/* Do work... */\n\n }\n}\n\n\n\n\n\nThe task function is called when the task is initially put into the \nrunning\n state by the scheduler. \nWe use an infinite loop to ensure that the task function never returns. Our assertion that the current \ntask's handler is the same as our task handler is for illustration purposes only and does not need to \nbe in most task functions.\n\n\nTask Priority\n\n\nAs a preemptive, multitasking RTOS, Mynewt decides which tasks to run based on which has a higher \npriority; the highest priority being 0 and the lowest 255. Thus, before initializing our task, we \nmust choose a priority defined as a macro variable.\n\n\nLet\u2019s set the priority of \nwork_task\n to 0, because everyone knows that work is more important than blinking.\n\n\n \n#define WORK_TASK_PRIO (0)\n\n\n\n\n\n\nInitialization\n\n\nTo initialize a new task we use \nos_task_init()\n \nwhich takes a number of arguments including our new task function, stack, and priority. \n\n\nAdd the \ninit_tasks()\n function to initialize \nwork_task\n to keep our main function clean. \n\n\nint\n\n\ninit_tasks\n(\nvoid\n)\n{\n \n/* \u2026 */\n\n \nos_stack_t\n \n*work_stack\n;\n \nwork_stack\n \n=\n \nmalloc\n(\nsizeof\n(\nos_stack_t\n)\n*WORK_STACK_SIZE\n);\n\n \nassert\n(\nwork_stack\n);\n \nos_task_init\n(\nwork_task\n, \nwork\n, \nwork_task_handler\n, \nNULL\n,\n \nWORK_TASK_PRIO\n, \nOS_WAIT_FOREVER\n, \nwork_stack\n,\n \nWORK_STACK_SIZE\n);\n\n \nreturn\n \n0\n;\n}\n\n\n\n\n\n\n\nAdd the call to \ninit_tasks()\n in \nmain()\n before the \nwhile\n loop:\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n\n ...\n\n \n/* Initialize the work task */\n\n \ninit_tasks\n();\n\n \nwhile\n (\n1\n) {\n ...\n }\n}\n\n\n\n\n\n\nAnd that\u2019s it! Now run your application using the newt run command.\n\n\n$ newt run arduino_blinky 0.0.0\n\n\n\n\n\n\nWhen GDB appears press C then Enter to continue and \u2026 \nwait, why doesn't our LED blink anymore?\n\n\n\n\nReview\n\n\nBefore we run our new app, let\u2019s review what we need in order to create a task. This is a general case for a new task called mytask:\n\n\n1)\n Define a new task, task stack, and priority:\n\n\n/* My Task */\n\n\nstruct\n \nos_task\n \nmytask\n\n\n/* My Task Stack */\n\n\n#define MYTASK_STACK_SIZE OS_STACK_ALIGN(256)\n\n\nos_stack_t\n \nmytask_stack\n[\nMYTASK_STACK_SIZE\n];\n\n/* My Task Priority */\n\n\n#define MYTASK_PRIO (0)\n\n\n\n\n\n\n2)\n Define task function:\n\n\nvoid\n \n\nmytask_handler\n(\nvoid\n \n*arg\n)\n{\n \nwhile\n (\n1\n) {\n \n/* ... */\n\n }\n}\n\n\n\n\n\n3)\n Initialize the task:\n\n\nos_task_init\n(\nmytask\n, \nmytask\n, \nmytask_handler\n, \nNULL\n, \n \nMYTASK_PRIO\n, \nOS_WAIT_FOREVER\n, \nmytask_stack\n,\n \nMYTASK_STACK_SIZE\n);\n\n\n\n\n\nTask Priority, Preempting, and Context Switching\n\n\nA preemptive RTOS is one in which a higher priority task that is \nready to run\n will preempt (i.e. take the \nplace of) the lower priority task which is \nrunning\n. When a lower priority task is preempted by a higher \npriority task, the lower priority task\u2019s context data (stack pointer, registers, etc.) is saved and the new \ntask is switched in.\n\n\nIn our example, \nwork_task\n (priority 0) has a higher priority than the \nmain\n task (priority 127). Since \nwork_task\n is never put into a \nsleep\n state, it holds the processor focus on its context. \n\n\nLet\u2019s give \nwork_task\n a delay and some simulated work to keep it busy. The delay is measured in os ticks and the actual number of ticks per second is dependent on the board. We multiply \nOS_TICKS_PER_SEC\n, which is defined in the MCU, by the number of seconds we wish to delay.\n\n\nvoid\n\n\nwork_task_handler\n(\nvoid\n \n*arg\n)\n{\n \nstruct\n \nos_task\n \n*t\n;\n\n \ng_led_pin\n \n=\n \nLED_BLINK_PIN\n;\n \nhal_gpio_init_out\n(\ng_led_pin\n, \n1\n);\n\n \nwhile\n (\n1\n) {\n \nt\n \n=\n \nos_sched_get_current_t\n:\nask\n();\n \nassert\n(\nt-\nt_func\n \n==\n \nwork_task_handler\n);\n \n/* Do work... */\n\n \nint\n \ni\n;\n \nfor\n(\ni\n \n=\n \n0\n; \ni\n \n \n1000000\n; \n++i\n) {\n \n/* Simulate doing a noticeable amount of work */\n\n \nhal_gpio_write\n(\ng_led_pin\n, \n1\n);\n }\n \nos_time_delay\n(\n3\n \n*\n \nOS_TICKS_PER_SEC\n);\n }\n}\n\n\n\n\n\n\nIn order to notice the LED changing, modify the time delay in \nmain()\n to blink at a higher frequency.\n\n\nos_time_delay\n(\nOS_TICKS_PER_SEC/\n10\n);\n\n\n\n\n\n\nBefore we run the app, let\u2019s predict the behavior. With the newest additions to \nwork_task_handler()\n, \nour first action will be to sleep for three seconds. This allows the \nmain\n task, running \nmain()\n, to take over the CPU and blink to its heart\u2019s content. After three seconds, \nwork_task\n will wake up and be made \nready to run\n. \nThis causes it to preempt the \nmain\n task. The LED will then remain lit for a short period while \nwork_task\n \nloops, then blink again for another three seconds while \nwork_task\n sleeps. \n\n\nYou should see that our prediction was correct! \n\n\nPriority Management Considerations\n\n\nWhen projects grow in scope, from blinking LEDs into more sophisticated applications, the number of \ntasks needed increases alongside complexity. It remains important, then, that each of our tasks is \ncapable of doing its work within a reasonable amount of time.\n\n\nSome tasks, such as the Shell task, execute quickly and require almost instantaneous response. Therefore, \nthe Shell task should be given a high priority. On the other hand, tasks which may be communicating over \na network, or processing data, should be given a low priority in order to not hog the CPU.\n\n\nThe diagram below shows the different scheduling patterns we would expect when we set the \nwork_task\n priority higher and lower than the \nmain\n task priority. \n\n\n\n\nIn the second case where the \nmain\n task has a higher priority, \nwork_task\n runs and executes \u201cwork\u201d when\nthe \nmain\n task sleeps, saving us idle time compared to the first case.\n\n\nNote:\n Defining the same priority for two tasks fires an assert in os_task_init() and must be avoided. Priority 127 is reserved for main task, 255 for idle task.",
- "title": "Tasks and Priority Management"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#tasks-and-priority-management",
- "text": "Target Platform: Arduino M0 Pro (or legacy Arduino Zero or Zero Pro, but not Arduino M0) This lesson is designed to teach core OS concepts and strategies encountered when \nbuilding applications using Mynewt. Specifically, this lesson will cover tasks, \nsimple multitasking, and priority management running on an Arduino M0 Pro.",
- "title": "Tasks and Priority Management"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#prerequisites",
- "text": "Before starting, you should read about Mynewt in the Introduction \nsection and complete the QuickStart \nguide and the Blinky tutorial. \nFurthermore, it may be helpful to take a peek at the task documentation \nfor additional insights.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#equipment",
- "text": "You will need the following equipment: Arduino M0 Pro (or legacy Arduino Zero or Zero Pro, but not Arduino M0) Computer with Mynewt installed USB to Micro USB Cable",
- "title": "Equipment"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#build-your-application",
- "text": "To save time, we will simply modify the Blinky application. We'll add the Task Management code to\nthe Blinky application. Follow the Arduino Zero Blinky tutorial \nto create a new project and build your bootloader and application. Finally, build and \nload the application to your Arduino to verify that everything is in order. Now let\u2019s get started!",
- "title": "Build Your Application"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#default-main-task",
- "text": "During Mynewt system startup, Mynewt creates a default main task and executes the application main() function in the context of this task. The main task priority defaults to 127 and can be configured with the OS_MAIN_TASK_PRIO system configuration setting. The blinky application only has the main task. The main() function executes an infinite loop that toggles the led and sleeps for one second.",
- "title": "Default Main Task"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#create-a-new-task",
- "text": "The purpose of this section is to give an introduction to the important aspects of tasks \nand how to properly initialize them. First, let\u2019s define a second task called work_task \nin main.c (located in apps/blinky/src): struct os_task work_task ; A task is represented by the os_task \nstruct which will hold the task\u2019s information (name, state, priority, etc.). A task is made up of two \nmain elements, a task function (also known as a task handler) and a task stack. Next, let\u2019s take a look at what is required to initialize our new task.",
- "title": "Create a New Task"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#task-stack",
- "text": "The task stack is an array of type os_stack_t which holds the program stack frames. Mynewt gives \nus the ability to set the stack size for a task giving the application developer room to optimize \nmemory usage. Since we\u2019re not short on memory, our work_stack is plenty large \nfor the purpose of this lesson. Notice that the elements in our task stack are of type os_stack_t \nwhich are generally 32 bits, making our entire stack 1024 Bytes. #define WORK_STACK_SIZE OS_STACK_ALIGN(256) Note: The OS_STACK_ALIGN macro is used to align the stack based on the hardware architecture.",
- "title": "Task Stack"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#task-function",
- "text": "A task function is essentially an infinite loop that waits for some \u201cevent\u201d to wake it up. In general, the task function is where the majority of work is done by a task. Let\u2019s write a task function for work_task called work_task_handler() : void work_task_handler ( void *arg )\n{\n struct os_task *t ;\n\n g_led_pin = LED_BLINK_PIN ;\n hal_gpio_init_out ( g_led_pin , 1 );\n\n while ( 1 ) {\n t = os_sched_get_current_task ();\n assert ( t- t_func == work_task_handler );\n /* Do work... */ \n }\n} The task function is called when the task is initially put into the running state by the scheduler. \nWe use an infinite loop to ensure that the task function never returns. Our assertion that the current \ntask's handler is the same as our task handler is for illustration purposes only and does not need to \nbe in most task functions.",
- "title": "Task Function"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#task-priority",
- "text": "As a preemptive, multitasking RTOS, Mynewt decides which tasks to run based on which has a higher \npriority; the highest priority being 0 and the lowest 255. Thus, before initializing our task, we \nmust choose a priority defined as a macro variable. Let\u2019s set the priority of work_task to 0, because everyone knows that work is more important than blinking. #define WORK_TASK_PRIO (0)",
- "title": "Task Priority"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#initialization",
- "text": "To initialize a new task we use os_task_init() \nwhich takes a number of arguments including our new task function, stack, and priority. Add the init_tasks() function to initialize work_task to keep our main function clean. int init_tasks ( void )\n{\n /* \u2026 */ \n os_stack_t *work_stack ;\n work_stack = malloc ( sizeof ( os_stack_t ) *WORK_STACK_SIZE );\n\n assert ( work_stack );\n os_task_init ( work_task , work , work_task_handler , NULL ,\n WORK_TASK_PRIO , OS_WAIT_FOREVER , work_stack ,\n WORK_STACK_SIZE );\n\n return 0 ;\n} Add the call to init_tasks() in main() before the while loop: int main ( int argc , char **argv )\n{\n\n ...\n\n /* Initialize the work task */ \n init_tasks ();\n\n while ( 1 ) {\n ...\n }\n} \nAnd that\u2019s it! Now run your application using the newt run command. $ newt run arduino_blinky 0.0.0 \nWhen GDB appears press C then Enter to continue and \u2026 wait, why doesn't our LED blink anymore?",
- "title": "Initialization"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#review",
- "text": "Before we run our new app, let\u2019s review what we need in order to create a task. This is a general case for a new task called mytask: 1) Define a new task, task stack, and priority: /* My Task */ struct os_task mytask /* My Task Stack */ #define MYTASK_STACK_SIZE OS_STACK_ALIGN(256) os_stack_t mytask_stack [ MYTASK_STACK_SIZE ]; /* My Task Priority */ #define MYTASK_PRIO (0) 2) Define task function: void mytask_handler ( void *arg )\n{\n while ( 1 ) {\n /* ... */ \n }\n} 3) Initialize the task: os_task_init ( mytask , mytask , mytask_handler , NULL , \n MYTASK_PRIO , OS_WAIT_FOREVER , mytask_stack ,\n MYTASK_STACK_SIZE );",
- "title": "Review"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#task-priority-preempting-and-context-switching",
- "text": "A preemptive RTOS is one in which a higher priority task that is ready to run will preempt (i.e. take the \nplace of) the lower priority task which is running . When a lower priority task is preempted by a higher \npriority task, the lower priority task\u2019s context data (stack pointer, registers, etc.) is saved and the new \ntask is switched in. In our example, work_task (priority 0) has a higher priority than the main task (priority 127). Since work_task is never put into a sleep state, it holds the processor focus on its context. Let\u2019s give work_task a delay and some simulated work to keep it busy. The delay is measured in os ticks and the actual number of ticks per second is dependent on the board. We multiply OS_TICKS_PER_SEC , which is defined in the MCU, by the number of seconds we wish to delay. void work_task_handler ( void *arg )\n{\n struct os_task *t ;\n\n g_led_pin = LED_BLINK_PIN ;\n hal_gpio_init_out ( g_led_pin , 1 );\n\n while ( 1 ) {\n t = os_sched_get_current_t : ask ();\n assert ( t- t_func == work_task_handler );\n /* Do work... */ \n int i ;\n for ( i = 0 ; i 1000000 ; ++i ) {\n /* Simulate doing a noticeable amount of work */ \n hal_gpio_write ( g_led_pin , 1 );\n }\n os_time_delay ( 3 * OS_TICKS_PER_SEC );\n }\n} \nIn order to notice the LED changing, modify the time delay in main() to blink at a higher frequency. os_time_delay ( OS_TICKS_PER_SEC/ 10 ); \nBefore we run the app, let\u2019s predict the behavior. With the newest additions to work_task_handler() , \nour first action will be to sleep for three seconds. This allows the main task, running main() , to take over the CPU and blink to its heart\u2019s content. After three seconds, work_task will wake up and be made ready to run . \nThis causes it to preempt the main task. The LED will then remain lit for a short period while work_task \nloops, then blink again for another three seconds while work_task sleeps. You should see that our prediction was correct!",
- "title": "Task Priority, Preempting, and Context Switching"
- },
- {
- "location": "/os/tutorials/tasks_lesson/#priority-management-considerations",
- "text": "When projects grow in scope, from blinking LEDs into more sophisticated applications, the number of \ntasks needed increases alongside complexity. It remains important, then, that each of our tasks is \ncapable of doing its work within a reasonable amount of time. Some tasks, such as the Shell task, execute quickly and require almost instantaneous response. Therefore, \nthe Shell task should be given a high priority. On the other hand, tasks which may be communicating over \na network, or processing data, should be given a low priority in order to not hog the CPU. The diagram below shows the different scheduling patterns we would expect when we set the work_task priority higher and lower than the main task priority. In the second case where the main task has a higher priority, work_task runs and executes \u201cwork\u201d when\nthe main task sleeps, saving us idle time compared to the first case. Note: Defining the same priority for two tasks fires an assert in os_task_init() and must be avoided. Priority 127 is reserved for main task, 255 for idle task.",
- "title": "Priority Management Considerations"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/",
- "text": "Enable Wi-Fi on Arduino MKR1000\n\n\nThis tutorial shows you how to enable Wi-Fi on an Arduino MKR1000 board and connect to a Wi-Fi network.\n\n\nPrerequisites\n\n\nEnsure that you have met the following prerequisites before continuing with this tutorial:\n\n\n\n\nHave an Arduino MKR1000 board.\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a computer to build a Mynewt application and connect to the board over USB.\n\n\nHave a Micro-USB cable to connect the board and the computer.\n\n\nHave local Wi-Fi network that the computer is connected to and that the MKR1000 board can join.\n\n\nHave a \nSerial Port Setup\n.\n\n\nHave a \nSegger J-Link Debug Probe\n.\n\n\nHave a \nJ-Link 9 pin Cortex-M Adapter\n that allows JTAG, SWD and SWO connections between J-Link and Cortex M based target hardware systems\n\n\nInstall the \nSegger JLINK Software and documentation pack\n.\n\n\nInstall the Newt tool and toolchains (See \nBasic Setup\n).\n\n\nCreate a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in \nCreating Your First Project\n.\n\n\nRead the Mynewt OS \nConcepts\n section.\n\n\n\n\nCreate a Project\n\n\nCreate a new project if you do not have an existing one. You can skip this step and proceed to \nfetch external packages\n if you already created a project.\n\n\nRun the following commands to create a new project:\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new arduinowifi\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in arduinowifi...\n Project arduinowifi successfully created.\n $ cd arduinowifi\n $ newt install\n apache-mynewt-core\n $\n\n\n\n\n\n\n\n Fetch External Packages\n\n\nMynewt uses source code provided directly from the chip manufacturer for\nlow level operations. Sometimes this code is licensed only for the specific manufacturer of the chipset and cannot live in\nthe Apache Mynewt repository. That happens to be the case for the Arduino Zero board which uses Atmel SAMD21. Runtime's git\nhub repository hosts such external third-party packages and the Newt tool can fetch them.\n\n\nTo fetch the package with MCU support for Atmel SAMD21 for Arduino Zero from the Runtime git repository, you need to add\nthe repository to the \nproject.yml\n file in your base project directory.\n\n\nMynewt uses source code provided directly from the chip manufacturer for\nlow level operations. Sometimes this code is licensed only for the specific manufacturer of the chipset and cannot live in the Apache Mynewt repository. That happens to be the case for the Arduino Zero board which uses Atmel SAMD21. Runtime's github repository hosts such external third-party packages and the Newt tool can fetch them.\n\n\nTo fetch the package with MCU support for Atmel SAMD21 for Arduino Zero from the Runtime git repository, you need to add\nthe repository to the \nproject.yml\n file in your base project directory (\narduinowifi\n).\n\n\nHere is an example \nproject.yml\n file with the Arduino Zero repository\nadded. The sections with \nmynewt_arduino_zero\n that need to be added to\nyour project file are highlighted.\n\n\nNote:\n On Windows platforms: You need to set \nvers\n to \n0-dev\n and use the latest master branch for both repositories.\n\n\n$ more project.yml\nproject.name: \nmy_project\n\n\nproject.repositories:\n - apache-mynewt-core\n\n - mynewt_arduino_zero\n\n\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\n\nrepository.mynewt_arduino_zero:\n\n type: github\n\n vers: 1-latest\n\n user: runtimeco\n\n repo: mynewt_arduino_zero\n\n$\n\n\n\n\n\n\n\n\nInstall the project dependencies using the \nnewt install\n command (you can specify \n-v\n for verbose output):\n\n\n$ newt install\napache-mynewt-core\nmynewt_arduino_zero\n$\n\n\n\n\n\nNOTE:\n If there has been a new release of a repo used in your project since you last installed it, the \n1-latest\n version for the repo in the \nproject.yml\n file will refer to the new release and will not match the installed files. In that case you will get an error message saying so and you will need to run \nnewt upgrade\n to overwrite the existing files with the latest codebase.\n\n\n\n\nCreate a Target for the Bootloader\n\n\nYou need to create two targets for the MKR1000 board, one for the bootloader and one for the \nwinc1500_wifi\n application. \n\n\nRun the following \nnewt target\n commands, from your project directory, to create a bootloader target. We name the target \nmkr1000_boot\n.\n\n\n$ newt target create mkr1000_boot\n$ newt target set mkr1000_boot bsp=@mynewt_arduino_zero/hw/bsp/arduino_mkr1000\n$ newt target set mkr1000_boot app=@apache-mynewt-core/apps/boot\n$ newt target set mkr1000_boot build_profile=optimized\n$ newt target set mkr1000_boot syscfg=BSP_ARDUINO_ZERO_PRO=1\n\n\n\n\n\n\n\nCreate a Target for the Wi-Fi Application\n\n\nRun the following \nnewt target\n commands to create a target for the \nwinc1500_wifi\n application in the arduino repository. We name the application target \nmkr1000_wifi\n.\n\n\n$ newt target create mkr1000_wifi\n$ newt target set mkr1000_wifi app=@mynewt_arduino_zero/apps/winc1500_wifi\n$ newt target set mkr1000_wifi bsp=@mynewt_arduino_zero/hw/bsp/arduino_mkr1000\n$ newt target set mkr1000_wifi build_profile=debug\n$ newt target set mkr1000_boot syscfg=BSP_ARDUINO_ZERO_PRO=1\n\n\n\n\n\n\n\nBuild the Bootloader\n\n\nRun the \nnewt build mkr1000_boot\n command to build the bootloader:\n\n\n$ newt build mkr1000_boot\nBuilding target targets/mkr1000_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\n ...\n\nArchiving util_mem.a\nLinking ~/dev/arduinowifi/bin/targets/mkr1000_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/mkr1000_boot\n$\n\n\n\n\n\n\n\nBuild the Wi-Fi Application\n\n\nRun the \nnewt build mkr1000_wifi\n command to build the wi-fi application image:\n\n\n$newt build mkr1000_wifi\nBuilding target targets/mkr1000_wifi\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\n ...\n\nArchiving util_mem.a\nLinking ~/dev/arduinowifi/bin/targets/mkr1000_wifi/app/apps/winc1500_wifi/winc1500_wifi.elf\nTarget successfully built: targets/mkr1000_wifi\n$\n\n\n\n\n\n\n\nSign and Create the Wi-Fi Application Image\n\n\nRun the \nnewt create-image mkr1000_wifi 1.0.0\n command to sign and create an image file for the Wi-Fi application. You may assign an arbitrary version (e.g. 1.0.0) number.\n\n\n$newt create-image mkr1000_wifi 1.0.0\nCompiling bin/targets/mkr1000_wifi/generated/src/mkr1000_wifi-sysinit-app.c\nArchiving mkr1000_wifi-sysinit-app.a\nLinking ~/dev/arduinowifi/bin/targets/mkr1000_wifi/app/apps/winc1500_wifi/winc1500_wifi.elf\nApp image succesfully generated: ~/dev/arduinowifi/bin/targets/mkr1000_wifi/app/apps/winc1500_wifi/winc1500_wifi.img\n$\n\n\n\n\n\n\n\nConnect to the Board\n\n\n\n\nConnect your computer to the MKR1000 board with the Micro-USB cable. \n\n\nConnect the debug probe to the JTAG port on the board using the Jlink 9-pin adapter and cable. \n\n\n\n\n\n\n\n\n\n\n\n\n\nMynewt will download and debug the target through this port. You should see a green LED come on and indicates the board has power. \n\n\n\n\nLoad the Bootloader onto the Board\n\n\nRun the \nnewt load mkr1000_boot\n command to load the bootloader onto the board:\n\n\n$ newt load mkr1000_boot\nLoading bootloader\n$\n\n\n\n\n\n\n\nLoad the Wi-Fi Application Image onto the Board\n\n\nRun the \nnewt load mkr1000_wifi\n command to load the wifi application onto the board:\n\n\n$ newt load mkr1000_wifi\nLoading app image into slot 1\n$\n\n\n\n\n\n\n\nSetup a Serial Connection Between Your Computer and the Board\n\n\nSet up a serial connection from your computer to the MKR1000 board (See \nSerial Port Setup\n). On the MKR1000 board, the TX pin is PIN 14 and the RX pin in PIN 13.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nLocate the port, in the /dev directory on your computer, that the serial connection uses. The format of the port name is\n platform dependent:\n\n\n\n\nMac OS uses the format \ntty.usbserial-\nsome identifier\n.\n\n\nLinux uses the format \nTTYUSB\nN\n, where \nN\n is a number. For example, TTYUSB2.\n\n\n\n\nMinGW on Windows uses the format \nttyS\nN\n, where \nN\n is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n.\n\n\nYou can also use the Windows Device Manager to find the COM port number.\n\n\n\n\n\n\n\n\n$ ls /dev/tty*usbserial*\n/dev/tty.usbserial-1d13\n$\n\n\n\n\n\nStart Wi-Fi via console\n\n\nUse a terminal emulation program to communicate with the board over the serial port. This tutorial shows a Minicom set up. Run the minicom command with the serial port you located on your computer:\n\n\nNote:\n On Windows, you can use the PuTTY application. \n\n\n$ minicom -D /dev/tty.usbserial-1d13 -b 115200\n\n\n\n\n\n\nType \nwifi start\n to start Wi-Fi.\n\n\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Mar 18 2016, 04:59:47.\nPort /dev/tty.usbserial-1d13, 17:06:09\n\nPress Meta-Z for help on special keys\n\n\nwifi start\n\n3293703:(APP)(INFO)Chip ID 1503a0\n(APP)(INFO)Firmware ver : 19.4.4\n(APP)(INFO)Min driver ver : 19.3.0\n(APP)(INFO)Curr driver ver: 19.3.0\nwifi_init : 0\n\n\n\n\n\n\nConnect to the local Wi-Fi network. Note that the MKR1000 board only supports 2.4 GHz Wi-Fi networks.\n\n\nRun the \nwifi connect\n command and specify your network \n and \n. After you are connected to your wi-fi network, run the \nnet service\n command to start network services.\n\n\nwifi connect \nssid\n \npassword\n\n\n3362937:wifi_request_scan : 0\n3363843:scan_results 9: 0\n3363855:wifi_connect : 0\n3364852:connect_done : 0\n3364861:dhcp done 10.0.0.4\n3365470:get sys time response 2017.3.31-0.9.57 \n\nnet service \n\n\n\n\n\nThe board is connected to the network succesfully and has IP address: 10.0.0.4\n\n\nEstablish TCP Connection and Talk!\n\n\nFrom a terminal on your computer, telnet to ports 7, 9, or 19 using the IP address your board has been assigned. Type something on this terminal and see the console output (on minicom). Can you see the difference in the behaviors?\n\n\n$telnet 10.0.0.4 7\nTrying 10.0.0.4...\nConnected to 10.0.0.4.\nEscape character is \n^]\n.\nhello\nhello\n^]\ntelnet\n q\n$\n\n\n\n\n\nOne port echoes whatever is typed, one discards everything it gets, and the third spews out bits constantly. Type \nwifi stop\n to disable WiFi on the Arduino board.",
- "title": "Enable Wi-Fi on Arduino MKR1000"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#enable-wi-fi-on-arduino-mkr1000",
- "text": "This tutorial shows you how to enable Wi-Fi on an Arduino MKR1000 board and connect to a Wi-Fi network.",
- "title": "Enable Wi-Fi on Arduino MKR1000"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#prerequisites",
- "text": "Ensure that you have met the following prerequisites before continuing with this tutorial: Have an Arduino MKR1000 board. Have Internet connectivity to fetch remote Mynewt components. Have a computer to build a Mynewt application and connect to the board over USB. Have a Micro-USB cable to connect the board and the computer. Have local Wi-Fi network that the computer is connected to and that the MKR1000 board can join. Have a Serial Port Setup . Have a Segger J-Link Debug Probe . Have a J-Link 9 pin Cortex-M Adapter that allows JTAG, SWD and SWO connections between J-Link and Cortex M based target hardware systems Install the Segger JLINK Software and documentation pack . Install the Newt tool and toolchains (See Basic Setup ). Create a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in Creating Your First Project . Read the Mynewt OS Concepts section.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#create-a-project",
- "text": "Create a new project if you do not have an existing one. You can skip this step and proceed to fetch external packages if you already created a project. Run the following commands to create a new project: $ mkdir ~/dev\n $ cd ~/dev\n $ newt new arduinowifi\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in arduinowifi...\n Project arduinowifi successfully created.\n $ cd arduinowifi\n $ newt install\n apache-mynewt-core\n $",
- "title": "Create a Project"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#create-a-target-for-the-bootloader",
- "text": "You need to create two targets for the MKR1000 board, one for the bootloader and one for the winc1500_wifi application. \nRun the following newt target commands, from your project directory, to create a bootloader target. We name the target mkr1000_boot . $ newt target create mkr1000_boot\n$ newt target set mkr1000_boot bsp=@mynewt_arduino_zero/hw/bsp/arduino_mkr1000\n$ newt target set mkr1000_boot app=@apache-mynewt-core/apps/boot\n$ newt target set mkr1000_boot build_profile=optimized\n$ newt target set mkr1000_boot syscfg=BSP_ARDUINO_ZERO_PRO=1",
- "title": "Create a Target for the Bootloader"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#create-a-target-for-the-wi-fi-application",
- "text": "Run the following newt target commands to create a target for the winc1500_wifi application in the arduino repository. We name the application target mkr1000_wifi . $ newt target create mkr1000_wifi\n$ newt target set mkr1000_wifi app=@mynewt_arduino_zero/apps/winc1500_wifi\n$ newt target set mkr1000_wifi bsp=@mynewt_arduino_zero/hw/bsp/arduino_mkr1000\n$ newt target set mkr1000_wifi build_profile=debug\n$ newt target set mkr1000_boot syscfg=BSP_ARDUINO_ZERO_PRO=1",
- "title": "Create a Target for the Wi-Fi Application"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#build-the-bootloader",
- "text": "Run the newt build mkr1000_boot command to build the bootloader: $ newt build mkr1000_boot\nBuilding target targets/mkr1000_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\n ...\n\nArchiving util_mem.a\nLinking ~/dev/arduinowifi/bin/targets/mkr1000_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/mkr1000_boot\n$",
- "title": "Build the Bootloader"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#build-the-wi-fi-application",
- "text": "Run the newt build mkr1000_wifi command to build the wi-fi application image: $newt build mkr1000_wifi\nBuilding target targets/mkr1000_wifi\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\n ...\n\nArchiving util_mem.a\nLinking ~/dev/arduinowifi/bin/targets/mkr1000_wifi/app/apps/winc1500_wifi/winc1500_wifi.elf\nTarget successfully built: targets/mkr1000_wifi\n$",
- "title": "Build the Wi-Fi Application"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#sign-and-create-the-wi-fi-application-image",
- "text": "Run the newt create-image mkr1000_wifi 1.0.0 command to sign and create an image file for the Wi-Fi application. You may assign an arbitrary version (e.g. 1.0.0) number. $newt create-image mkr1000_wifi 1.0.0\nCompiling bin/targets/mkr1000_wifi/generated/src/mkr1000_wifi-sysinit-app.c\nArchiving mkr1000_wifi-sysinit-app.a\nLinking ~/dev/arduinowifi/bin/targets/mkr1000_wifi/app/apps/winc1500_wifi/winc1500_wifi.elf\nApp image succesfully generated: ~/dev/arduinowifi/bin/targets/mkr1000_wifi/app/apps/winc1500_wifi/winc1500_wifi.img\n$",
- "title": "Sign and Create the Wi-Fi Application Image"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#connect-to-the-board",
- "text": "Connect your computer to the MKR1000 board with the Micro-USB cable. Connect the debug probe to the JTAG port on the board using the Jlink 9-pin adapter and cable. \nMynewt will download and debug the target through this port. You should see a green LED come on and indicates the board has power.",
- "title": "Connect to the Board"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#load-the-bootloader-onto-the-board",
- "text": "Run the newt load mkr1000_boot command to load the bootloader onto the board: $ newt load mkr1000_boot\nLoading bootloader\n$",
- "title": "Load the Bootloader onto the Board"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#load-the-wi-fi-application-image-onto-the-board",
- "text": "Run the newt load mkr1000_wifi command to load the wifi application onto the board: $ newt load mkr1000_wifi\nLoading app image into slot 1\n$",
- "title": "Load the Wi-Fi Application Image onto the Board"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#setup-a-serial-connection-between-your-computer-and-the-board",
- "text": "Set up a serial connection from your computer to the MKR1000 board (See Serial Port Setup ). On the MKR1000 board, the TX pin is PIN 14 and the RX pin in PIN 13. \nLocate the port, in the /dev directory on your computer, that the serial connection uses. The format of the port name is\n platform dependent: Mac OS uses the format tty.usbserial- some identifier . Linux uses the format TTYUSB N , where N is a number. For example, TTYUSB2. MinGW on Windows uses the format ttyS N , where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . You can also use the Windows Device Manager to find the COM port number. $ ls /dev/tty*usbserial*\n/dev/tty.usbserial-1d13\n$",
- "title": "Setup a Serial Connection Between Your Computer and the Board"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#start-wi-fi-via-console",
- "text": "Use a terminal emulation program to communicate with the board over the serial port. This tutorial shows a Minicom set up. Run the minicom command with the serial port you located on your computer: Note: On Windows, you can use the PuTTY application. $ minicom -D /dev/tty.usbserial-1d13 -b 115200 \nType wifi start to start Wi-Fi. Welcome to minicom 2.7\n\nOPTIONS: \nCompiled on Mar 18 2016, 04:59:47.\nPort /dev/tty.usbserial-1d13, 17:06:09\n\nPress Meta-Z for help on special keys wifi start 3293703:(APP)(INFO)Chip ID 1503a0\n(APP)(INFO)Firmware ver : 19.4.4\n(APP)(INFO)Min driver ver : 19.3.0\n(APP)(INFO)Curr driver ver: 19.3.0\nwifi_init : 0 \nConnect to the local Wi-Fi network. Note that the MKR1000 board only supports 2.4 GHz Wi-Fi networks. Run the wifi connect command and specify your network and . After you are connected to your wi-fi network, run the net service command to start network services. wifi connect ssid password 3362937:wifi_request_scan : 0\n3363843:scan_results 9: 0\n3363855:wifi_connect : 0\n3364852:connect_done : 0\n3364861:dhcp done 10.0.0.4\n3365470:get sys time response 2017.3.31-0.9.57 net service The board is connected to the network succesfully and has IP address: 10.0.0.4",
- "title": "Start Wi-Fi via console"
- },
- {
- "location": "/os/tutorials/wi-fi_on_arduino/#establish-tcp-connection-and-talk",
- "text": "From a terminal on your computer, telnet to ports 7, 9, or 19 using the IP address your board has been assigned. Type something on this terminal and see the console output (on minicom). Can you see the difference in the behaviors? $telnet 10.0.0.4 7\nTrying 10.0.0.4...\nConnected to 10.0.0.4.\nEscape character is ^] .\nhello\nhello\n^]\ntelnet q\n$ One port echoes whatever is typed, one discards everything it gets, and the third spews out bits constantly. Type wifi stop to disable WiFi on the Arduino board.",
- "title": "Establish TCP Connection and Talk!"
- },
- {
- "location": "/os/tutorials/unit_test/",
- "text": "Write a Test Suite for a Package\n\n\nThis document guides the reader through creating a test suite for a Mynewt package.\n\n\nIntroduction\n\n\nWriting a test suite involves using the\n\ntest/testutil\n package. The testutil\nlibrary provides the functionality needed to define test suites and test cases.\n\n\nChoose Your Package Under Test\n\n\nChoose the package you want to write a test suite for. In this tutorial, we\nwill use the \ntime/datetime\n in the apache-mynewt-core repo. Throughout this\ntutorial, we will be inside the apache-mynewt-core repo directory, unlike most\ntutorials which operate from the top-level project directory.\n\n\nCreate A Test Package\n\n\nTypically, a library has only one test package. The convention is name the\ntest package by appending \n/test\n to the host library name. For example, the\ntest package for \nencoding/json\n is \nencoding/json/test\n. The directory\nstructure of the json package is shown below:\n\n\nencoding/json\n\n\n\u251c\u2500\u2500\n \ninclude\n\n\n\u2502\u00a0\u00a0\n \n\u2514\u2500\u2500\n \njson\n\n\n\u2502\u00a0\u00a0\n \n\u2514\u2500\u2500\n \njson\n.\nh\n\n\n\u251c\u2500\u2500\n \npkg\n.\nyml\n\n\n\u251c\u2500\u2500\n \nsrc\n\n\n\u2502\u00a0\u00a0\n \n\u251c\u2500\u2500\n \njson_decode\n.\nc\n\n\n\u2502\u00a0\u00a0\n \n\u2514\u2500\u2500\n \njson_encode\n.\nc\n\n\n\u2514\u2500\u2500\n \ntest\n\n \n\u251c\u2500\u2500\n \npkg\n.\nyml\n\n \n\u2514\u2500\u2500\n \nsrc\n\n \n\u251c\u2500\u2500\n \ntest_json\n.\nc\n\n \n\u251c\u2500\u2500\n \ntest_json\n.\nh\n\n \n\u251c\u2500\u2500\n \ntest_json_utils\n.\nc\n\n \n\u2514\u2500\u2500\n \ntestcases\n\n \n\u251c\u2500\u2500\n \njson_simple_decode\n.\nc\n\n \n\u2514\u2500\u2500\n \njson_simple_encode\n.\nc\n\n\n\n\n\n\nThe top-level \ntest\n directory contains the json test package. To create a\ntest package for the datetime package, we need to create a similar package\ncalled \ntime/datetime/test\n.\n\n\n$ newt pkg new time/datetime/test -t unittest\nDownload package template for package type pkg.\nPackage successfuly installed into /home/me/mynewt-core/time/datetime/test.\n\n\n\n\n\nWe now have a test package inside \ntime/datetime\n:\n\n\ntime/datetime\n\u251c\u2500\u2500 include\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime.h\n\u251c\u2500\u2500 pkg.yml\n\u251c\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime.c\n\u2514\u2500\u2500 test\n \u251c\u2500\u2500 README.md\n \u251c\u2500\u2500 pkg.yml\n \u251c\u2500\u2500 src\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n \u2514\u2500\u2500 syscfg.yml\n\n\n\n\n\nThere is one modification we need to make to the new package before we can\nstart writing unit test code. A test package needs access to the code it will\nbe testing, so we need to add a dependency on\n\n@apache-mynewt-core/time/datetime\n to our \npkg.yml\n file:\n\n\npkg.name: \ntime/datetime/test\n\npkg.type: unittest\npkg.description: \nDescription of your package\n\npkg.author: \nYou \nyou@you.org\n\npkg.homepage: \nhttp://your-url.org/\n\npkg.keywords:\n\npkg.deps:\n - \n@apache-mynewt-core/test/testutil\n\n\n - \n@apache-mynewt-core/time/datetime\n\n\n\npkg.deps.SELFTEST:\n - \n@apache-mynewt-core/sys/console/stub\n\n\n\n\n\n\nWhile we have the \npkg.yml\n file open, let's take a look at what newt filled in automatically:\n\n\n\n\npkg.type: unittest\n designates this as a test package. A \ntest package\n is\n special in that it can be built and executed using the \nnewt test\n command.\n\n\nA test package always depends on \n@apache-mynewt-core/test/testutil\n. The\n testutil library provides the tools necessary for verifying package behavior, \n\n\nThe \nSELFTEST\n suffix indicates that a setting should only be applied when the \nnewt test\n command is used.\n\n\n\n\nRegarding the conditional dependency on \nsys/console/stub\n, the datetime\npackage requires some form of console to function. In a regular application,\nthe console dependency would be supplied by a higher order package. Because\n\nnewt test\n runs the test package without an application present, the test\npackage needs to supply all unresolved dependencies itself when run in\nself-test mode.\n\n\nCreate Your Test Suite Code\n\n\nWe will be adding a \ntest suite\n to the \nmain.c\n file. The test suite will be empty for now. We also need to invoke the test suite from \nmain()\n.\n\n\nOur \nmain.c\n file now looks like this:\n\n\n#include\n \nsysinit/sysinit.h\n\n\n#include\n \ntestutil/testutil.h\n\n\n\nTEST_SUITE\n(\ntest_datetime_suite\n) {\n \n/* Empty for now; add test cases later. */\n\n}\n\n\n#if MYNEWT_VAL(SELFTEST)\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \n/* Initialize all packages. */\n\n \nsysinit\n();\n\n \ntest_datetime_suite\n();\n\n \n/* Indicate whether all test cases passed. */\n\n \nreturn\n \ntu_any_failed\n;\n}\n\n#endif\n\n\n\n\n\n\nTry It Out\n\n\nWe now have a working test suite with no tests. Let's make sure we get a passing result when we run \nnewt test\n:\n\n\n$ newt test time/datetime\n\nbuild output\n\nExecuting test: /home/me/mynewt-core/bin/targets/unittest/time_datetime_test/app/time/datetime/test/time_datetime_test.elf\nPassed tests: [time/datetime/test]\nAll tests passed\n\n\n\n\n\nCreate a Test\n\n\nTo create a test within your test suite, there are two things to do.\n\n\n\n\nImplement the test case function using the \ntestutil\n macros.\n\n\nCall the test case function from within the test suite.\n\n\n\n\nFor this tutorial we will create a test case to verify the \ndatetime_parse()\n\nfunction. The \ndatetime_parse()\n function is declared as follows:\n\n\n/**\n\n\n * Parses an RFC 3339 datetime string. Some examples of valid datetime strings\n\n\n * are:\n\n\n * 2016-03-02T22:44:00 UTC time (implicit)\n\n\n * 2016-03-02T22:44:00Z UTC time (explicit)\n\n\n * 2016-03-02T22:44:00-08:00 PST timezone\n\n\n * 2016-03-02T22:44:00.1 fractional seconds\n\n\n * 2016-03-02T22:44:00.101+05:30 fractional seconds with timezone\n\n\n *\n\n\n * On success, the two output parameters are filled in (tv and tz).\n\n\n *\n\n\n * @return 0 on success;\n\n\n * nonzero on parse error.\n\n\n */\n\n\nint\n\n\ndatetime_parse\n(\nconst\n \nchar\n \n*input\n, \nstruct\n \nos_timeval\n \n*tv\n, \nstruct\n \nos_timezone\n \n*tz\n)\n\n\n\n\n\nOur test case should make sure this function rejects invalid input, and that it\nparses valid input correctly. The updated \nmain.c\n file looks like this:\n\n\n#include\n \nsysinit/sysinit.h\n\n\n#include\n \ntestutil/testutil.h\n\n\n#include\n \nos/os_time.h\n\n\n#include\n \ndatetime/datetime.h\n\n\n\nTEST_SUITE\n(\ntest_datetime_suite\n)\n{\n \ntest_datetime_parse_simple\n();\n}\n\n\nTEST_CASE\n(\ntest_datetime_parse_simple\n)\n{\n \nstruct\n \nos_timezone\n \ntz\n;\n \nstruct\n \nos_timeval\n \ntv\n;\n \nint\n \nrc\n;\n\n \n/*** Valid input. */\n\n\n \n/* No timezone; UTC implied. */\n\n \nrc\n \n=\n \ndatetime_parse\n(\n2017-06-28T22:37:59\n, \ntv\n, \ntz\n);\n \nTEST_ASSERT_FATAL\n(\nrc\n \n==\n \n0\n);\n \nTEST_ASSERT\n(\ntv\n.\ntv_sec\n \n==\n \n1498689479\n);\n \nTEST_ASSERT\n(\ntv\n.\ntv_usec\n \n==\n \n0\n);\n \nTEST_ASSERT\n(\ntz\n.\ntz_minuteswest\n \n==\n \n0\n);\n \nTEST_ASSERT\n(\ntz\n.\ntz_dsttime\n \n==\n \n0\n);\n\n \n/* PDT timezone. */\n\n \nrc\n \n=\n \ndatetime_parse\n(\n2013-12-05T02:43:07-07:00\n, \ntv\n, \ntz\n);\n \nTEST_ASSERT_FATAL\n(\nrc\n \n==\n \n0\n);\n \nTEST_ASSERT\n(\ntv\n.\ntv_sec\n \n==\n \n1386236587\n);\n \nTEST_ASSERT\n(\ntv\n.\ntv_usec\n \n==\n \n0\n);\n \nTEST_ASSERT\n(\ntz\n.\ntz_minuteswest\n \n==\n \n420\n);\n \nTEST_ASSERT\n(\ntz\n.\ntz_dsttime\n \n==\n \n0\n);\n\n \n/*** Invalid input. */\n\n\n \n/* Nonsense. */\n\n \nrc\n \n=\n \ndatetime_parse\n(\nabc\n, \ntv\n, \ntz\n);\n \nTEST_ASSERT\n(\nrc\n \n!=\n \n0\n);\n\n \n/* Date-only. */\n\n \nrc\n \n=\n \ndatetime_parse\n(\n2017-01-02\n, \ntv\n, \ntz\n);\n \nTEST_ASSERT\n(\nrc\n \n!=\n \n0\n);\n\n \n/* Zero month. */\n\n \nrc\n \n=\n \ndatetime_parse\n(\n2017-00-28T22:37:59\n, \ntv\n, \ntz\n);\n \nTEST_ASSERT\n(\nrc\n \n!=\n \n0\n);\n\n \n/* 13 month. */\n\n \nrc\n \n=\n \ndatetime_parse\n(\n2017-13-28T22:37:59\n, \ntv\n, \ntz\n);\n \nTEST_ASSERT\n(\nrc\n \n!=\n \n0\n);\n}\n\n\n#if MYNEWT_VAL(SELFTEST)\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \n/* Initialize all packages. */\n\n \nsysinit\n();\n\n \ntest_datetime_suite\n();\n\n \n/* Indicate whether all test cases passed. */\n\n \nreturn\n \ntu_any_failed\n;\n}\n\n#endif\n\n\n\n\n\n\nTake a few minutes to review the above code. Then keep reading for some\nspecifics.\n\n\nAsserting\n\n\nThe \ntest/testutil\n package provides two tools for verifying the correctness of a package:\n\n\n\n\nTEST_ASSERT\n\n\nTEST_ASSERT_FATAL\n\n\n\n\nBoth of these macros check if the supplied condition is true. They differ in\nhow they behave when the condition is not true. On failure, \nTEST_ASSERT\n\nreports the error and proceeds with the remainder of the test case.\n\nTEST_ASSERT_FATAL\n, on the other hand, aborts the test case on failure.\n\n\nThe general rule is to only use \nTEST_ASSERT_FATAL\n when subsequent assertions\ndepend on the condition being checked. For example, when \ndatetime_parse()\n is\nexpected to succeed, the return code is checked with \nTEST_ASSERT_FATAL\n. If\n\ndatetime_parse()\n unexpectedly failed, the contents of the \ntv\n and \ntz\n\nobjects would be indeterminate, so it is desirable to abort the test instead of\nchecking them and reporting spurious failures.\n\n\nScaling Up\n\n\nThe above example is small and self contained, so it is reasonable to put\neverything in a single C file. A typical package will need a lot more test\ncode, and it helps to follow some conventions to maintain organization. Let's\ntake a look at a more realistic example. Here is the directory structure of\nthe \nfs/nffs/test\n package:\n\n\nfs/nffs/test\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 nffs_test.c\n \u251c\u2500\u2500 nffs_test.h\n \u251c\u2500\u2500 nffs_test_debug.c\n \u251c\u2500\u2500 nffs_test_priv.h\n \u251c\u2500\u2500 nffs_test_system_01.c\n \u251c\u2500\u2500 nffs_test_utils.c\n \u251c\u2500\u2500 nffs_test_utils.h\n \u2514\u2500\u2500 testcases\n \u251c\u2500\u2500 append_test.c\n \u251c\u2500\u2500 cache_large_file_test.c\n \u251c\u2500\u2500 corrupt_block_test.c\n \u251c\u2500\u2500 corrupt_scratch_test.c\n \u251c\u2500\u2500 gc_on_oom_test.c\n \u251c\u2500\u2500 gc_test.c\n \u251c\u2500\u2500 incomplete_block_test.c\n \u251c\u2500\u2500 large_system_test.c\n \u251c\u2500\u2500 large_unlink_test.c\n \u251c\u2500\u2500 large_write_test.c\n \u251c\u2500\u2500 long_filename_test.c\n \u251c\u2500\u2500 lost_found_test.c\n \u251c\u2500\u2500 many_children_test.c\n \u251c\u2500\u2500 mkdir_test.c\n \u251c\u2500\u2500 open_test.c\n \u251c\u2500\u2500 overwrite_many_test.c\n \u251c\u2500\u2500 overwrite_one_test.c\n \u251c\u2500\u2500 overwrite_three_test.c\n \u251c\u2500\u2500 overwrite_two_test.c\n \u251c\u2500\u2500 read_test.c\n \u251c\u2500\u2500 readdir_test.c\n \u251c\u2500\u2500 rename_test.c\n \u251c\u2500\u2500 split_file_test.c\n \u251c\u2500\u2500 truncate_test.c\n \u251c\u2500\u2500 unlink_test.c\n \u2514\u2500\u2500 wear_level_test.c\n\n\n\n\n\nThe \nfs/nffs/test\n package follows these conventions:\n\n\n\n\nA maximum of one test case per C file.\n\n\nEach test case file goes in the \ntestcases\n subdirectory.\n\n\nTest suites and utility functions go directly in the \nsrc\n directory.\n\n\n\n\nTest packages contributed to the Mynewt project should follow these conventions.\n\n\nCongratulations\n\n\nNow you can begin the work of validating your packages.",
- "title": "Write a Test Suite for a Package"
- },
- {
- "location": "/os/tutorials/unit_test/#write-a-test-suite-for-a-package",
- "text": "This document guides the reader through creating a test suite for a Mynewt package.",
- "title": "Write a Test Suite for a Package"
- },
- {
- "location": "/os/tutorials/unit_test/#introduction",
- "text": "Writing a test suite involves using the test/testutil package. The testutil\nlibrary provides the functionality needed to define test suites and test cases.",
- "title": "Introduction"
- },
- {
- "location": "/os/tutorials/unit_test/#choose-your-package-under-test",
- "text": "Choose the package you want to write a test suite for. In this tutorial, we\nwill use the time/datetime in the apache-mynewt-core repo. Throughout this\ntutorial, we will be inside the apache-mynewt-core repo directory, unlike most\ntutorials which operate from the top-level project directory.",
- "title": "Choose Your Package Under Test"
- },
- {
- "location": "/os/tutorials/unit_test/#create-a-test-package",
- "text": "Typically, a library has only one test package. The convention is name the\ntest package by appending /test to the host library name. For example, the\ntest package for encoding/json is encoding/json/test . The directory\nstructure of the json package is shown below: encoding/json \u251c\u2500\u2500 include \u2502\u00a0\u00a0 \u2514\u2500\u2500 json \u2502\u00a0\u00a0 \u2514\u2500\u2500 json . h \u251c\u2500\u2500 pkg . yml \u251c\u2500\u2500 src \u2502\u00a0\u00a0 \u251c\u2500\u2500 json_decode . c \u2502\u00a0\u00a0 \u2514\u2500\u2500 json_encode . c \u2514\u2500\u2500 test \n \u251c\u2500\u2500 pkg . yml \n \u2514\u2500\u2500 src \n \u251c\u2500\u2500 test_json . c \n \u251c\u2500\u2500 test_json . h \n \u251c\u2500\u2500 test_json_utils . c \n \u2514\u2500\u2500 testcases \n \u251c\u2500\u2500 json_simple_decode . c \n \u2514\u2500\u2500 json_simple_encode . c The top-level test directory contains the json test package. To create a\ntest package for the datetime package, we need to create a similar package\ncalled time/datetime/test . $ newt pkg new time/datetime/test -t unittest\nDownload package template for package type pkg.\nPackage successfuly installed into /home/me/mynewt-core/time/datetime/test. We now have a test package inside time/datetime : time/datetime\n\u251c\u2500\u2500 include\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime.h\n\u251c\u2500\u2500 pkg.yml\n\u251c\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 datetime.c\n\u2514\u2500\u2500 test\n \u251c\u2500\u2500 README.md\n \u251c\u2500\u2500 pkg.yml\n \u251c\u2500\u2500 src\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n \u2514\u2500\u2500 syscfg.yml There is one modification we need to make to the new package before we can\nstart writing unit test code. A test package needs access to the code it will\nbe testing, so we need to add a dependency on @apache-mynewt-core/time/datetime to our pkg.yml file: pkg.name: time/datetime/test \npkg.type: unittest\npkg.description: Description of your package \npkg.author: You you@you.org \npkg.homepage: http://your-url.org/ \npkg.keywords:\n\npkg.deps:\n - @apache-mynewt-core/test/testutil - @apache-mynewt-core/time/datetime \npkg.deps.SELFTEST:\n - @apache-mynewt-core/sys/console/stub While we have the pkg.yml file open, let's take a look at what newt filled in automatically: pkg.type: unittest designates this as a test package. A test package is\n special in that it can be built and executed using the newt test command. A test package always depends on @apache-mynewt-core/test/testutil . The\n testutil library provides the tools necessary for verifying package behavior, The SELFTEST suffix indicates that a setting should only be applied when the newt test command is used. Regarding the conditional dependency on sys/console/stub , the datetime\npackage requires some form of console to function. In a regular application,\nthe console dependency would be supplied by a higher order package. Because newt test runs the test package without an application present, the test\npackage needs to supply all unresolved dependencies itself when run in\nself-test mode.",
- "title": "Create A Test Package"
- },
- {
- "location": "/os/tutorials/unit_test/#create-your-test-suite-code",
- "text": "We will be adding a test suite to the main.c file. The test suite will be empty for now. We also need to invoke the test suite from main() . Our main.c file now looks like this: #include sysinit/sysinit.h #include testutil/testutil.h TEST_SUITE ( test_datetime_suite ) {\n /* Empty for now; add test cases later. */ \n} #if MYNEWT_VAL(SELFTEST) int main ( int argc , char **argv )\n{\n /* Initialize all packages. */ \n sysinit ();\n\n test_datetime_suite ();\n\n /* Indicate whether all test cases passed. */ \n return tu_any_failed ;\n} #endif",
- "title": "Create Your Test Suite Code"
- },
- {
- "location": "/os/tutorials/unit_test/#try-it-out",
- "text": "We now have a working test suite with no tests. Let's make sure we get a passing result when we run newt test : $ newt test time/datetime build output \nExecuting test: /home/me/mynewt-core/bin/targets/unittest/time_datetime_test/app/time/datetime/test/time_datetime_test.elf\nPassed tests: [time/datetime/test]\nAll tests passed",
- "title": "Try It Out"
- },
- {
- "location": "/os/tutorials/unit_test/#create-a-test",
- "text": "To create a test within your test suite, there are two things to do. Implement the test case function using the testutil macros. Call the test case function from within the test suite. For this tutorial we will create a test case to verify the datetime_parse() \nfunction. The datetime_parse() function is declared as follows: /** * Parses an RFC 3339 datetime string. Some examples of valid datetime strings * are: * 2016-03-02T22:44:00 UTC time (implicit) * 2016-03-02T22:44:00Z UTC time (explicit) * 2016-03-02T22:44:00-08:00 PST timezone * 2016-03-02T22:44:00.1 fractional seconds * 2016-03-02T22:44:00.101+05:30 fractional seconds with timezone * * On success, the two output parameters are filled in (tv and tz). * * @return 0 on success; * nonzero on parse error. */ int datetime_parse ( const char *input , struct os_timeval *tv , struct os_timezone *tz ) Our test case should make sure this function rejects invalid input, and that it\nparses valid input correctly. The updated main.c file looks like this: #include sysinit/sysinit.h #include testutil/testutil.h #include os/os_time.h #include datetime/datetime.h TEST_SUITE ( test_datetime_suite )\n{\n test_datetime_parse_simple ();\n} TEST_CASE ( test_datetime_parse_simple )\n{\n struct os_timezone tz ;\n struct os_timeval tv ;\n int rc ;\n\n /*** Valid input. */ \n\n /* No timezone; UTC implied. */ \n rc = datetime_parse ( 2017-06-28T22:37:59 , tv , tz );\n TEST_ASSERT_FATAL ( rc == 0 );\n TEST_ASSERT ( tv . tv_sec == 1498689479 );\n TEST_ASSERT ( tv . tv_usec == 0 );\n TEST_ASSERT ( tz . tz_minuteswest == 0 );\n TEST_ASSERT ( tz . tz_dsttime == 0 );\n\n /* PDT timezone. */ \n rc = datetime_parse ( 2013-12-05T02:43:07-07:00 , tv , tz );\n TEST_ASSERT_FATAL ( rc == 0 );\n TEST_ASSERT ( tv . tv_sec == 1386236587 );\n TEST_ASSERT ( tv . tv_usec == 0 );\n TEST_ASSERT ( tz . tz_minuteswest == 420 );\n TEST_ASSERT ( tz . tz_dsttime == 0 );\n\n /*** Invalid input. */ \n\n /* Nonsense. */ \n rc = datetime_parse ( abc , tv , tz );\n TEST_ASSERT ( rc != 0 );\n\n /* Date-only. */ \n rc = datetime_parse ( 2017-01-02 , tv , tz );\n TEST_ASSERT ( rc != 0 );\n\n /* Zero month. */ \n rc = datetime_parse ( 2017-00-28T22:37:59 , tv , tz );\n TEST_ASSERT ( rc != 0 );\n\n /* 13 month. */ \n rc = datetime_parse ( 2017-13-28T22:37:59 , tv , tz );\n TEST_ASSERT ( rc != 0 );\n} #if MYNEWT_VAL(SELFTEST) int main ( int argc , char **argv )\n{\n /* Initialize all packages. */ \n sysinit ();\n\n test_datetime_suite ();\n\n /* Indicate whether all test cases passed. */ \n return tu_any_failed ;\n} #endif Take a few minutes to review the above code. Then keep reading for some\nspecifics.",
- "title": "Create a Test"
- },
- {
- "location": "/os/tutorials/unit_test/#asserting",
- "text": "The test/testutil package provides two tools for verifying the correctness of a package: TEST_ASSERT TEST_ASSERT_FATAL Both of these macros check if the supplied condition is true. They differ in\nhow they behave when the condition is not true. On failure, TEST_ASSERT \nreports the error and proceeds with the remainder of the test case. TEST_ASSERT_FATAL , on the other hand, aborts the test case on failure. The general rule is to only use TEST_ASSERT_FATAL when subsequent assertions\ndepend on the condition being checked. For example, when datetime_parse() is\nexpected to succeed, the return code is checked with TEST_ASSERT_FATAL . If datetime_parse() unexpectedly failed, the contents of the tv and tz \nobjects would be indeterminate, so it is desirable to abort the test instead of\nchecking them and reporting spurious failures.",
- "title": "Asserting"
- },
- {
- "location": "/os/tutorials/unit_test/#scaling-up",
- "text": "The above example is small and self contained, so it is reasonable to put\neverything in a single C file. A typical package will need a lot more test\ncode, and it helps to follow some conventions to maintain organization. Let's\ntake a look at a more realistic example. Here is the directory structure of\nthe fs/nffs/test package: fs/nffs/test\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 nffs_test.c\n \u251c\u2500\u2500 nffs_test.h\n \u251c\u2500\u2500 nffs_test_debug.c\n \u251c\u2500\u2500 nffs_test_priv.h\n \u251c\u2500\u2500 nffs_test_system_01.c\n \u251c\u2500\u2500 nffs_test_utils.c\n \u251c\u2500\u2500 nffs_test_utils.h\n \u2514\u2500\u2500 testcases\n \u251c\u2500\u2500 append_test.c\n \u251c\u2500\u2500 cache_large_file_test.c\n \u251c\u2500\u2500 corrupt_block_test.c\n \u251c\u2500\u2500 corrupt_scratch_test.c\n \u251c\u2500\u2500 gc_on_oom_test.c\n \u251c\u2500\u2500 gc_test.c\n \u251c\u2500\u2500 incomplete_block_test.c\n \u251c\u2500\u2500 large_system_test.c\n \u251c\u2500\u2500 large_unlink_test.c\n \u251c\u2500\u2500 large_write_test.c\n \u251c\u2500\u2500 long_filename_test.c\n \u251c\u2500\u2500 lost_found_test.c\n \u251c\u2500\u2500 many_children_test.c\n \u251c\u2500\u2500 mkdir_test.c\n \u251c\u2500\u2500 open_test.c\n \u251c\u2500\u2500 overwrite_many_test.c\n \u251c\u2500\u2500 overwrite_one_test.c\n \u251c\u2500\u2500 overwrite_three_test.c\n \u251c\u2500\u2500 overwrite_two_test.c\n \u251c\u2500\u2500 read_test.c\n \u251c\u2500\u2500 readdir_test.c\n \u251c\u2500\u2500 rename_test.c\n \u251c\u2500\u2500 split_file_test.c\n \u251c\u2500\u2500 truncate_test.c\n \u251c\u2500\u2500 unlink_test.c\n \u2514\u2500\u2500 wear_level_test.c The fs/nffs/test package follows these conventions: A maximum of one test case per C file. Each test case file goes in the testcases subdirectory. Test suites and utility functions go directly in the src directory. Test packages contributed to the Mynewt project should follow these conventions.",
- "title": "Scaling Up"
- },
- {
- "location": "/os/tutorials/unit_test/#congratulations",
- "text": "Now you can begin the work of validating your packages.",
- "title": "Congratulations"
- },
- {
- "location": "/os/tutorials/event_queue/",
- "text": "How to Use Event Queues to Manage Multiple Events\n\n\nIntroduction\n\n\nThe event queue mechanism allows you to serialize incoming events for your task. You can use it to get information about hardware interrupts, callout expirations, and messages from other tasks.\n\n\nThe benefit of using events for inter-task communication is that it can reduce the number of resources that need to be shared and locked. \n\n\nThe benefit of processing interrupts in a task context instead of the interrupt context is that other interrupts and high priority tasks are not blocked waiting for the interrupt handler to complete processing. A task can also access other OS facilities and sleep.\n\n\nThis tutorial assumes that you have read about \nEvent Queues\n, the \nHardware Abstraction Layer\n, and \nOS Callouts\n in the OS User's Guide. \n\n\nThis tutorial shows you how to create an application that uses events for: \n\n\n\n\nInter-task communication \n\n\nOS callouts for timer expiration \n\n\nGPIO interrupts \n\n\n\n\nIt also shows you how to:\n\n\n\n\nUse the Mynewt default event queue and application main task to process your events. \n\n\nCreate a dedicated event queue and task for your events. \n\n\n\n\nTo reduce an application's memory requirement, we recommend that you use the Mynewt default event queue if your application or package does not have real-time timing requirements. \n\n\nPrerequisites\n\n\nEnsure that you have met the following prerequisites before continuing with this tutorial:\n\n\n\n\nInstall the newt tool.\n\n\nInstall the newtmgr tool.\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nInstall the compiler tools to support native compiling to build the project this tutorial creates.\n\n\nHave a cable to establish a serial USB connection between the board and the laptop.\n\n\n\n\nExample Application\n\n\nIn this example, you will write an application, for the Nordic nRF52 board, that uses events from three input sources to toggle three GPIO outputs and light up the LEDs. If you are using a different board, you will need to adjust the GPIO pin numbers in the code example.\n\n\nThe application handles events from three sources on two event queues:\n\n\n\n\nEvents generated by an application task at periodic intervals are added to the Mynewt default event queue. \n\n\nOS callouts for timer events are added to the \nmy_timer_interrupt_eventq\n event queue. \n\n\nGPIO interrupt events are added to the \nmy_timer_interrupt_eventq\n event queue.\n\n\n\n\n\nCreate the Project\n\n\nFollow the instructions in the \nnRF52 tutorial\n to create a project.\n\n\n\nCreate the Application\n\n\nCreate the \npkg.yml\n file for the application:\n\n\npkg.name: apps/eventq_example\npkg.type: app\n\npkg.deps:\n - kernel/os\n - hw/hal\n - sys/console/stub\n\n\n\n\n\n\n\nApplication Task Generated Events\n\n\nThe application creates a task that generates events, at periodic intervals, to toggle the LED at pin \nTASK_LED\n. The event is queued on the Mynewt default event queue and is processed in the context of the application main task. \n\n\nDeclare and initialize the \ngen_task_ev\n event with the \nmy_ev_cb()\n callback function to process the event:\n\n\n/* Callback function for application task event */\n\n\nstatic\n \nvoid\n \nmy_ev_cb\n(\nstruct\n \nos_event\n \n*\n);\n\n\n/* Initialize the event with the callback function */\n\n\nstatic\n \nstruct\n \nos_event\n \ngen_task_ev\n \n=\n {\n .\nev_cb\n \n=\n \nmy_ev_cb\n,\n};\n\n\n\n\n\n\nImplement the \nmy_ev_cb()\n callback function to process a task generated event and toggle the LED at pin \nTASK_LED\n:\n\n\n/* LED 1 (P0.17 on the board) */\n\n\n#define TASK_LED 17\n\n\n\n/*\n\n\n * Event callback function for events generated by gen_task. It toggles \n\n\n * the LED at pin TASK_LED.\n\n\n */\n\n\nstatic\n \nvoid\n \nmy_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n);\n \nhal_gpio_toggle\n(\nTASK_LED\n);\n \nreturn\n;\n}\n\n\n\n\n\n\nCreate a task that generates an event at periodic intervals and adds, using the \nos_eventq_put()\n function, the event to the Mynewt default event queue:\n\n\n#define GEN_TASK_PRIO 3 \n\n\n#define GEN_TASK_STACK_SZ 512\n\n\n\nstatic\n \nos_stack_t\n \ngen_task_stack\n[\nGEN_TASK_STACK_SZ\n];\n\nstatic\n \nstruct\n \nos_task\n \ngen_task_str\n;\n\n\n/* \n\n\n * Task handler to generate an event to toggle the LED at pin TASK_LED. \n\n\n * The event is added to the Mynewt default event queue. \n\n\n */\n\n\nstatic\n \nvoid\n\n\ngen_task\n(\nvoid\n \n*arg\n)\n{\n \nwhile\n (\n1\n) {\n \nos_time_delay\n(\nOS_TICKS_PER_SEC\n \n/\n \n4\n);\n \nos_eventq_put\n(\nos_eventq_dflt_get\n(), \ngen_task_ev\n);\n }\n}\n\n\nstatic\n \nvoid\n\n\ninit_tasks\n(\nvoid\n)\n{\n\n \n/* Create a task to generate events to toggle the LED at pin TASK_LED */\n\n\n \nos_task_init\n(\ngen_task_str\n, \ngen_task\n, \ngen_task\n, \nNULL\n, \nGEN_TASK_PRIO\n,\n \nOS_WAIT_FOREVER\n, \ngen_task_stack\n, \nGEN_TASK_STACK_SZ\n);\n\n ...\n\n}\n\n\n\n\n\n\nImplement the application \nmain()\n function to call the \nos_eventq_run()\n function to dequeue an event from the Mynewt default event queue and call the callback function to process the event. \n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nsysinit\n();\n\n \ninit_tasks\n();\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n()); \n }\n \nassert\n(\n0\n);\n}\n\n\n\n\n\n\n\nOS Callout Timer Events\n\n\nSet up OS callout timer events. For this example, we use a dedicated event queue for timer events to show you how to create a dedicated event queue and a task to process the events.\n\n\nImplement the \nmy_timer_ev_cb()\n callback function to process a timer event and toggle the LED at pin \nCALLOUT_LED\n:\n\n\n/* LED 2 (P0.18 on the board) */\n\n\n#define CALLOUT_LED 18\n\n\n\n/* The timer callout */\n\n\nstatic\n \nstruct\n \nos_callout\n \nmy_callout\n;\n\n\n/*\n\n\n * Event callback function for timer events. It toggles the LED at pin CALLOUT_LED.\n\n\n */\n\n\nstatic\n \nvoid\n \nmy_timer_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n \n!=\n \nNULL\n);\n\n \nhal_gpio_toggle\n(\nCALLOUT_LED\n);\n\n \nos_callout_reset\n(\nmy_callout\n, \nOS_TICKS_PER_SEC\n \n/\n \n2\n);\n}\n\n\n\n\n\n\nIn the \ninit_tasks()\n function, initialize the \nmy_timer_interrupt_eventq\n event queue, create a task to process events from the queue, and initialize the OS callout for the timer: \n\n\n#define MY_TIMER_INTERRUPT_TASK_PRIO 4\n\n\n#define MY_TIMER_INTERRUPT_TASK_STACK_SZ 512\n\n\n\nstatic\n \nos_stack_t\n \nmy_timer_interrupt_task_stack\n[\nMY_TIMER_INTERRUPT_TASK_STACK_SZ\n];\n\nstatic\n \nstruct\n \nos_task\n \nmy_timer_interrupt_task_str\n;\n\n\nstatic\n \nvoid\n\n\ninit_tasks\n(\nvoid\n)\n{\n \n/* Use a dedicate event queue for timer and interrupt events */\n\n\n \nos_eventq_init\n(\nmy_timer_interrupt_eventq\n); \n\n \n/* \n\n\n * Create the task to process timer and interrupt events from the\n\n\n * my_timer_interrupt_eventq event queue.\n\n\n */\n\n \nos_task_init\n(\nmy_timer_interrupt_task_str\n, \ntimer_interrupt_task\n, \n \nmy_timer_interrupt_task\n, \nNULL\n, \n \nMY_TIMER_INTERRUPT_TASK_PRIO\n, \nOS_WAIT_FOREVER\n, \n \nmy_timer_interrupt_task_stack\n, \n \nMY_TIMER_INTERRUPT_TASK_STACK_SZ\n);\n \n/* \n\n\n * Initialize the callout for a timer event. \n\n\n * The my_timer_ev_cb callback function processes the timer events.\n\n\n */\n\n \nos_callout_init\n(\nmy_callout\n, \nmy_timer_interrupt_eventq\n, \n \nmy_timer_ev_cb\n, \nNULL\n);\n\n \nos_callout_reset\n(\nmy_callout\n, \nOS_TICKS_PER_SEC\n);\n\n}\n\n\n\n\n\n\nImplement the \nmy_timer_interrupt_task()\n task handler to dispatch events from the \nmy_timer_interrupt_eventq\n event queue:\n\n\nstatic\n \nvoid\n\n\nmy_timer_interrupt_task\n(\nvoid\n \n*arg\n)\n{\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nmy_timer_interrupt_eventq\n);\n }\n}\n\n\n\n\n\n\n\nInterrupt Events\n\n\nThe application toggles the LED each time button 1 on the board is pressed. The interrupt handler generates an event when the GPIO for button 1 (P0.13) changes state. The events are added to the \nmy_timer_interrupt_eventq\n event queue, the same queue as the timer events.\n\n\nDeclare and initialize the \ngpio_ev\n event with the \nmy_interrupt_ev_cb()\n callback function to process the event:\n\n\nstatic\n \nstruct\n \nos_event\n \ngpio_ev\n {\n .\nev_cb\n \n=\n \nmy_interrupt_ev_cb\n,\n};\n\n\n\n\n\n\nImplement the \nmy_interrupt_ev_cb()\n callback function to process an interrupt event and toggle the LED at pin \nGPIO_LED\n:\n\n\n/* LED 3 (P0.19 on the board) */\n\n\n#define GPIO_LED 19\n\n\n\n/*\n\n\n * Event callback function for interrupt events. It toggles the LED at pin GPIO_LED.\n\n\n */\n\n\nstatic\n \nvoid\n \nmy_interrupt_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n \n!=\n \nNULL\n);\n\n \nhal_gpio_toggle\n(\nGPIO_LED\n);\n}\n\n\n\n\n\n\n\nImplement the \nmy_gpio_irq()\n handler to post an interrupt event to the \nmy_timer_interrupt_eventq\n event queue:\n\n\nstatic\n \nvoid\n\n\nmy_gpio_irq\n(\nvoid\n \n*arg\n)\n{\n \nos_eventq_put\n(\nmy_timer_interrupt_eventq\n, \ngpio_ev\n);\n}\n\n\n\n\n\n\n\nIn the \ninit_tasks()\n function, add the code to set up and enable the GPIO input pin for the button and initialize the GPIO output pins for the LEDs:\n\n\n/* LED 1 (P0.17 on the board) */\n\n\n#define TASK_LED 17 \n\n\n\n/* 2 (P0.18 on the board) */\n\n\n#define CALLOUT_LED 18 \n\n\n\n/* LED 3 (P0.19 on the board) */\n\n\n#define GPIO_LED 19\n\n\n\n/* Button 1 (P0.13 on the board) */\n\n\n#define BUTTON1_PIN 13\n\n\n\nvoid\n \n\ninit_tasks\n()\n\n \n/* Initialize OS callout for timer events. */\n\n\n ....\n\n \n/* \n\n\n * Initialize and enable interrupts for the pin for button 1 and \n\n\n * configure the button with pull up resistor on the nrf52dk.\n\n\n */\n \n \nhal_gpio_irq_init\n(\nBUTTON1_PIN\n, \nmy_gpio_irq\n, \nNULL\n, \nHAL_GPIO_TRIG_RISING\n, \nHAL_GPIO_PULL_UP\n);\n\n \nhal_gpio_irq_enable\n(\nBUTTON1_PIN\n);\n\n \n/* Initialize the GPIO output pins. Value 1 is off for these LEDs. */\n\n\n \nhal_gpio_init_out\n(\nTASK_LED\n, \n1\n);\n \nhal_gpio_init_out\n(\nCALLOUT_LED\n, \n1\n);\n \nhal_gpio_init_out\n(\nGPIO_LED\n, \n1\n);\n}\n\n\n\n\n\n\n\nPutting It All Together\n\n\nHere is the complete \nmain.c\n source for your application. Build the application and load it on your board. The task LED (LED1) blinks at an interval of 250ms, the callout LED (LED2) blinks at an interval of 500ms, and the GPIO LED (LED3) toggles on or off each time you press Button 1.\n\n\n#include\n \nos/os.h\n\n\n#include\n \nbsp/bsp.h\n\n\n#include\n \nhal/hal_gpio.h\n\n\n#include\n \nassert.h\n\n\n#include\n \nsysinit/sysinit.h\n\n\n\n\n#define MY_TIMER_INTERRUPT_TASK_PRIO 4\n\n\n#define MY_TIMER_INTERRUPT_TASK_STACK_SZ 512\n\n\n\n#define GEN_TASK_PRIO 3\n\n\n#define GEN_TASK_STACK_SZ 512\n\n\n\n/* LED 1 (P0.17 on the board) */\n\n\n#define TASK_LED 17\n\n\n\n/* LED 2 (P0.18 on the board) */\n\n\n#define CALLOUT_LED 18\n\n\n\n/* LED 3 (P0.19 on the board) */\n\n\n#define GPIO_LED 19\n\n\n\n/* Button 1 (P0.13 on the board) */\n\n\n#define BUTTON1_PIN 13\n\n\n\n\nstatic\n \nvoid\n \nmy_ev_cb\n(\nstruct\n \nos_event\n \n*\n);\n\nstatic\n \nvoid\n \nmy_timer_ev_cb\n(\nstruct\n \nos_event\n \n*\n);\n\nstatic\n \nvoid\n \nmy_interrupt_ev_cb\n(\nstruct\n \nos_event\n \n*\n);\n\n\nstatic\n \nstruct\n \nos_eventq\n \nmy_timer_interrupt_eventq\n;\n\n\nstatic\n \nos_stack_t\n \nmy_timer_interrupt_task_stack\n[\nMY_TIMER_INTERRUPT_TASK_STACK_SZ\n];\n\nstatic\n \nstruct\n \nos_task\n \nmy_timer_interrupt_task_str\n;\n\n\nstatic\n \nos_stack_t\n \ngen_task_stack\n[\nGEN_TASK_STACK_SZ\n];\n\nstatic\n \nstruct\n \nos_task\n \ngen_task_str\n;\n\n\nstatic\n \nstruct\n \nos_event\n \ngen_task_ev\n \n=\n {\n .\nev_cb\n \n=\n \nmy_ev_cb\n,\n};\n\n\nstatic\n \nstruct\n \nos_event\n \ngpio_ev\n \n=\n {\n .\nev_cb\n \n=\n \nmy_interrupt_ev_cb\n,\n};\n\n\n\nstatic\n \nstruct\n \nos_callout\n \nmy_callout\n;\n\n\n/*\n\n\n * Task handler to generate an event to toggle the LED at pin TASK_LED.\n\n\n * The event is added to the Mynewt default event queue.\n\n\n */\n\n\n\nstatic\n \nvoid\n\n\ngen_task\n(\nvoid\n \n*arg\n)\n{\n \nwhile\n (\n1\n) {\n \nos_time_delay\n(\nOS_TICKS_PER_SEC\n \n/\n \n4\n);\n \nos_eventq_put\n(\nos_eventq_dflt_get\n(), \ngen_task_ev\n);\n }\n}\n\n\n/*\n\n\n * Event callback function for events generated by gen_task. It toggles the LED at pin TASK_LED. \n\n\n */\n\n\nstatic\n \nvoid\n \nmy_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n);\n \nhal_gpio_toggle\n(\nTASK_LED\n);\n \nreturn\n;\n}\n\n\n/*\n\n\n * Event callback function for timer events. It toggles the LED at pin CALLOUT_LED.\n\n\n */\n\n\nstatic\n \nvoid\n \nmy_timer_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n \n!=\n \nNULL\n);\n\n \nhal_gpio_toggle\n(\nCALLOUT_LED\n);\n \nos_callout_reset\n(\nmy_callout\n, \nOS_TICKS_PER_SEC\n \n/\n \n2\n);\n}\n\n\n/*\n\n\n * Event callback function for interrupt events. It toggles the LED at pin GPIO_LED.\n\n\n */\n\n\nstatic\n \nvoid\n \nmy_interrupt_ev_cb\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nassert\n(\nev\n \n!=\n \nNULL\n);\n\n \nhal_gpio_toggle\n(\nGPIO_LED\n);\n}\n\n\nstatic\n \nvoid\n\n\nmy_gpio_irq\n(\nvoid\n \n*arg\n)\n{\n \nos_eventq_put\n(\nmy_timer_interrupt_eventq\n, \ngpio_ev\n);\n}\n\n\n\n\nstatic\n \nvoid\n\n\nmy_timer_interrupt_task\n(\nvoid\n \n*arg\n)\n{\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nmy_timer_interrupt_eventq\n);\n }\n}\n\n\nvoid\n\n\ninit_tasks\n(\nvoid\n)\n{\n\n \n/* Create a task to generate events to toggle the LED at pin TASK_LED */\n\n\n \nos_task_init\n(\ngen_task_str\n, \ngen_task\n, \ngen_task\n, \nNULL\n, \nGEN_TASK_PRIO\n,\n \nOS_WAIT_FOREVER\n, \ngen_task_stack\n, \nGEN_TASK_STACK_SZ\n);\n\n\n \n/* Use a dedicate event queue for timer and interrupt events */\n\n \nos_eventq_init\n(\nmy_timer_interrupt_eventq\n); \n\n \n/* \n\n\n * Create the task to process timer and interrupt events from the\n\n\n * my_timer_interrupt_eventq event queue.\n\n\n */\n\n \nos_task_init\n(\nmy_timer_interrupt_task_str\n, \ntimer_interrupt_task\n, \n \nmy_timer_interrupt_task\n, \nNULL\n, \n \nMY_TIMER_INTERRUPT_TASK_PRIO\n, \nOS_WAIT_FOREVER\n, \n \nmy_timer_interrupt_task_stack\n, \n \nMY_TIMER_INTERRUPT_TASK_STACK_SZ\n);\n\n \n/* \n\n\n * Initialize the callout for a timer event. \n\n\n * The my_timer_ev_cb callback function processes the timer event.\n\n\n */\n\n \nos_callout_init\n(\nmy_callout\n, \nmy_timer_interrupt_eventq\n, \n \nmy_timer_ev_cb\n, \nNULL\n);\n\n \nos_callout_reset\n(\nmy_callout\n, \nOS_TICKS_PER_SEC\n);\n\n \n/* \n\n\n * Initialize and enable interrupt for the pin for button 1 and \n\n\n * configure the button with pull up resistor on the nrf52dk.\n\n\n */\n \n \nhal_gpio_irq_init\n(\nBUTTON1_PIN\n, \nmy_gpio_irq\n, \nNULL\n, \nHAL_GPIO_TRIG_RISING\n, \nHAL_GPIO_PULL_UP\n);\n\n \nhal_gpio_irq_enable\n(\nBUTTON1_PIN\n);\n\n \nhal_gpio_init_out\n(\nTASK_LED\n, \n1\n);\n \nhal_gpio_init_out\n(\nCALLOUT_LED\n, \n1\n);\n \nhal_gpio_init_out\n(\nGPIO_LED\n, \n1\n);\n}\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nsysinit\n();\n\n \ninit_tasks\n();\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n()); \n }\n \nassert\n(\n0\n);\n}",
- "title": "Events and Event Queues"
- },
- {
- "location": "/os/tutorials/event_queue/#how-to-use-event-queues-to-manage-multiple-events",
- "text": "",
- "title": "How to Use Event Queues to Manage Multiple Events"
- },
- {
- "location": "/os/tutorials/event_queue/#introduction",
- "text": "The event queue mechanism allows you to serialize incoming events for your task. You can use it to get information about hardware interrupts, callout expirations, and messages from other tasks. The benefit of using events for inter-task communication is that it can reduce the number of resources that need to be shared and locked. The benefit of processing interrupts in a task context instead of the interrupt context is that other interrupts and high priority tasks are not blocked waiting for the interrupt handler to complete processing. A task can also access other OS facilities and sleep. This tutorial assumes that you have read about Event Queues , the Hardware Abstraction Layer , and OS Callouts in the OS User's Guide. This tutorial shows you how to create an application that uses events for: Inter-task communication OS callouts for timer expiration GPIO interrupts It also shows you how to: Use the Mynewt default event queue and application main task to process your events. Create a dedicated event queue and task for your events. To reduce an application's memory requirement, we recommend that you use the Mynewt default event queue if your application or package does not have real-time timing requirements.",
- "title": "Introduction"
- },
- {
- "location": "/os/tutorials/event_queue/#prerequisites",
- "text": "Ensure that you have met the following prerequisites before continuing with this tutorial: Install the newt tool. Install the newtmgr tool. Have Internet connectivity to fetch remote Mynewt components. Install the compiler tools to support native compiling to build the project this tutorial creates. Have a cable to establish a serial USB connection between the board and the laptop.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/event_queue/#example-application",
- "text": "In this example, you will write an application, for the Nordic nRF52 board, that uses events from three input sources to toggle three GPIO outputs and light up the LEDs. If you are using a different board, you will need to adjust the GPIO pin numbers in the code example. The application handles events from three sources on two event queues: Events generated by an application task at periodic intervals are added to the Mynewt default event queue. OS callouts for timer events are added to the my_timer_interrupt_eventq event queue. GPIO interrupt events are added to the my_timer_interrupt_eventq event queue.",
- "title": "Example Application"
- },
- {
- "location": "/os/tutorials/event_queue/#create-the-project",
- "text": "Follow the instructions in the nRF52 tutorial to create a project.",
- "title": "Create the Project"
- },
- {
- "location": "/os/tutorials/event_queue/#create-the-application",
- "text": "Create the pkg.yml file for the application: pkg.name: apps/eventq_example\npkg.type: app\n\npkg.deps:\n - kernel/os\n - hw/hal\n - sys/console/stub",
- "title": "Create the Application"
- },
- {
- "location": "/os/tutorials/event_queue/#application-task-generated-events",
- "text": "The application creates a task that generates events, at periodic intervals, to toggle the LED at pin TASK_LED . The event is queued on the Mynewt default event queue and is processed in the context of the application main task. Declare and initialize the gen_task_ev event with the my_ev_cb() callback function to process the event: /* Callback function for application task event */ static void my_ev_cb ( struct os_event * ); /* Initialize the event with the callback function */ static struct os_event gen_task_ev = {\n . ev_cb = my_ev_cb ,\n}; \nImplement the my_ev_cb() callback function to process a task generated event and toggle the LED at pin TASK_LED : /* LED 1 (P0.17 on the board) */ #define TASK_LED 17 /* * Event callback function for events generated by gen_task. It toggles * the LED at pin TASK_LED. */ static void my_ev_cb ( struct os_event *ev )\n{\n assert ( ev );\n hal_gpio_toggle ( TASK_LED );\n return ;\n} \nCreate a task that generates an event at periodic intervals and adds, using the os_eventq_put() function, the event to the Mynewt default event queue: #define GEN_TASK_PRIO 3 #define GEN_TASK_STACK_SZ 512 static os_stack_t gen_task_stack [ GEN_TASK_STACK_SZ ]; static struct os_task gen_task_str ; /* * Task handler to generate an event to toggle the LED at pin TASK_LED. * The event is added to the Mynewt default event queue. */ static void gen_task ( void *arg )\n{\n while ( 1 ) {\n os_time_delay ( OS_TICKS_PER_SEC / 4 );\n os_eventq_put ( os_eventq_dflt_get (), gen_task_ev );\n }\n} static void init_tasks ( void )\n{\n\n /* Create a task to generate events to toggle the LED at pin TASK_LED */ \n\n os_task_init ( gen_task_str , gen_task , gen_task , NULL , GEN_TASK_PRIO ,\n OS_WAIT_FOREVER , gen_task_stack , GEN_TASK_STACK_SZ );\n\n ...\n\n} \nImplement the application main() function to call the os_eventq_run() function to dequeue an event from the Mynewt default event queue and call the callback function to process the event. int main ( int argc , char **argv )\n{\n sysinit ();\n\n init_tasks ();\n\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ()); \n }\n assert ( 0 );\n}",
- "title": "Application Task Generated Events"
- },
- {
- "location": "/os/tutorials/event_queue/#os-callout-timer-events",
- "text": "Set up OS callout timer events. For this example, we use a dedicated event queue for timer events to show you how to create a dedicated event queue and a task to process the events. Implement the my_timer_ev_cb() callback function to process a timer event and toggle the LED at pin CALLOUT_LED : /* LED 2 (P0.18 on the board) */ #define CALLOUT_LED 18 /* The timer callout */ static struct os_callout my_callout ; /* * Event callback function for timer events. It toggles the LED at pin CALLOUT_LED. */ static void my_timer_ev_cb ( struct os_event *ev )\n{\n assert ( ev != NULL );\n\n hal_gpio_toggle ( CALLOUT_LED );\n\n os_callout_reset ( my_callout , OS_TICKS_PER_SEC / 2 );\n} \nIn the init_tasks() function, initialize the my_timer_interrupt_eventq event queue, create a task to process events from the queue, and initialize the OS callout for the timer: #define MY_TIMER_INTERRUPT_TASK_PRIO 4 #define MY_TIMER_INTERRUPT_TASK_STACK_SZ 512 static os_stack_t my_timer_interrupt_task_stack [ MY_TIMER_INTERRUPT_TASK_STACK_SZ ]; static struct os_task my_timer_interrupt_task_str ; static void init_tasks ( void )\n{\n /* Use a dedicate event queue for timer and interrupt events */ \n\n os_eventq_init ( my_timer_interrupt_eventq ); \n\n /* * Create the task to process timer and interrupt events from the * my_timer_interrupt_eventq event queue. */ \n os_task_init ( my_timer_interrupt_task_str , timer_interrupt_task , \n my_timer_interrupt_task , NULL , \n MY_TIMER_INTERRUPT_TASK_PRIO , OS_WAIT_FOREVER , \n my_timer_interrupt_task_stack , \n MY_TIMER_INTERRUPT_TASK_STACK_SZ );\n /* * Initialize the callout for a timer event. * The my_timer_ev_cb callback function processes the timer events. */ \n os_callout_init ( my_callout , my_timer_interrupt_eventq , \n my_timer_ev_cb , NULL );\n\n os_callout_reset ( my_callout , OS_TICKS_PER_SEC );\n\n} \nImplement the my_timer_interrupt_task() task handler to dispatch events from the my_timer_interrupt_eventq event queue: static void my_timer_interrupt_task ( void *arg )\n{\n while ( 1 ) {\n os_eventq_run ( my_timer_interrupt_eventq );\n }\n}",
- "title": "OS Callout Timer Events"
- },
- {
- "location": "/os/tutorials/event_queue/#interrupt-events",
- "text": "The application toggles the LED each time button 1 on the board is pressed. The interrupt handler generates an event when the GPIO for button 1 (P0.13) changes state. The events are added to the my_timer_interrupt_eventq event queue, the same queue as the timer events. Declare and initialize the gpio_ev event with the my_interrupt_ev_cb() callback function to process the event: static struct os_event gpio_ev {\n . ev_cb = my_interrupt_ev_cb ,\n}; \nImplement the my_interrupt_ev_cb() callback function to process an interrupt event and toggle the LED at pin GPIO_LED : /* LED 3 (P0.19 on the board) */ #define GPIO_LED 19 /* * Event callback function for interrupt events. It toggles the LED at pin GPIO_LED. */ static void my_interrupt_ev_cb ( struct os_event *ev )\n{\n assert ( ev != NULL );\n\n hal_gpio_toggle ( GPIO_LED );\n} Implement the my_gpio_irq() handler to post an interrupt event to the my_timer_interrupt_eventq event queue: static void my_gpio_irq ( void *arg )\n{\n os_eventq_put ( my_timer_interrupt_eventq , gpio_ev );\n} In the init_tasks() function, add the code to set up and enable the GPIO input pin for the button and initialize the GPIO output pins for the LEDs: /* LED 1 (P0.17 on the board) */ #define TASK_LED 17 /* 2 (P0.18 on the board) */ #define CALLOUT_LED 18 /* LED 3 (P0.19 on the board) */ #define GPIO_LED 19 /* Button 1 (P0.13 on the board) */ #define BUTTON1_PIN 13 void init_tasks ()\n\n /* Initialize OS callout for timer events. */ \n\n ....\n\n /* * Initialize and enable interrupts for the pin for button 1 and * configure the button with pull up resistor on the nrf52dk. */ \n hal_gpio_irq_init ( BUTTON1_PIN , my_gpio_irq , NULL , HAL_GPIO_TRIG_RISING , HAL_GPIO_PULL_UP );\n\n hal_gpio_irq_enable ( BUTTON1_PIN );\n\n /* Initialize the GPIO output pins. Value 1 is off for these LEDs. */ \n\n hal_gpio_init_out ( TASK_LED , 1 );\n hal_gpio_init_out ( CALLOUT_LED , 1 );\n hal_gpio_init_out ( GPIO_LED , 1 );\n}",
- "title": "Interrupt Events"
- },
- {
- "location": "/os/tutorials/event_queue/#putting-it-all-together",
- "text": "Here is the complete main.c source for your application. Build the application and load it on your board. The task LED (LED1) blinks at an interval of 250ms, the callout LED (LED2) blinks at an interval of 500ms, and the GPIO LED (LED3) toggles on or off each time you press Button 1. #include os/os.h #include bsp/bsp.h #include hal/hal_gpio.h #include assert.h #include sysinit/sysinit.h #define MY_TIMER_INTERRUPT_TASK_PRIO 4 #define MY_TIMER_INTERRUPT_TASK_STACK_SZ 512 #define GEN_TASK_PRIO 3 #define GEN_TASK_STACK_SZ 512 /* LED 1 (P0.17 on the board) */ #define TASK_LED 17 /* LED 2 (P0.18 on the board) */ #define CALLOUT_LED 18 /* LED 3 (P0.19 on the board) */ #define GPIO_LED 19 /* Button 1 (P0.13 on the board) */ #define BUTTON1_PIN 13 static void my_ev_cb ( struct os_event * ); static void my_timer_ev_cb ( struct os_event * ); static void my_interrupt_ev_cb ( struct os_event * ); static struct os_eventq my_timer_interrupt_eventq ; static os_stack_t my_timer_interrupt_task_stack [ MY_TIMER_INTERRUPT_TASK_STACK_SZ ]; static struct os_task my_timer_interrupt_task_str ; static os_stack_t gen_task_stack [ GEN_TASK_STACK_SZ ]; static struct os_task gen_task_str ; static struct os_event gen_task_ev = {\n . ev_cb = my_ev_cb ,\n}; static struct os_event gpio_ev = {\n . ev_cb = my_interrupt_ev_cb ,\n}; static struct os_callout my_callout ; /* * Task handler to generate an event to toggle the LED at pin TASK_LED. * The event is added to the Mynewt default event queue. */ static void gen_task ( void *arg )\n{\n while ( 1 ) {\n os_time_delay ( OS_TICKS_PER_SEC / 4 );\n os_eventq_put ( os_eventq_dflt_get (), gen_task_ev );\n }\n} /* * Event callback function for events generated by gen_task. It toggles the LED at pin TASK_LED. */ static void my_ev_cb ( struct os_event *ev )\n{\n assert ( ev );\n hal_gpio_toggle ( TASK_LED );\n return ;\n} /* * Event callback function for timer events. It toggles the LED at pin CALLOUT_LED. */ static void my_timer_ev_cb ( struct os_event *ev )\n{\n assert ( ev != NULL );\n\n hal_gpio_toggle ( CALLOUT_LED );\n os_callout_reset ( my_callout , OS_TICKS_PER_SEC / 2 );\n} /* * Event callback function for interrupt events. It toggles the LED at pin GPIO_LED. */ static void my_interrupt_ev_cb ( struct os_event *ev )\n{\n assert ( ev != NULL );\n\n hal_gpio_toggle ( GPIO_LED );\n} static void my_gpio_irq ( void *arg )\n{\n os_eventq_put ( my_timer_interrupt_eventq , gpio_ev );\n} static void my_timer_interrupt_task ( void *arg )\n{\n while ( 1 ) {\n os_eventq_run ( my_timer_interrupt_eventq );\n }\n} void init_tasks ( void )\n{\n\n /* Create a task to generate events to toggle the LED at pin TASK_LED */ \n\n os_task_init ( gen_task_str , gen_task , gen_task , NULL , GEN_TASK_PRIO ,\n OS_WAIT_FOREVER , gen_task_stack , GEN_TASK_STACK_SZ );\n\n\n /* Use a dedicate event queue for timer and interrupt events */ \n os_eventq_init ( my_timer_interrupt_eventq ); \n\n /* * Create the task to process timer and interrupt events from the * my_timer_interrupt_eventq event queue. */ \n os_task_init ( my_timer_interrupt_task_str , timer_interrupt_task , \n my_timer_interrupt_task , NULL , \n MY_TIMER_INTERRUPT_TASK_PRIO , OS_WAIT_FOREVER , \n my_timer_interrupt_task_stack , \n MY_TIMER_INTERRUPT_TASK_STACK_SZ );\n\n /* * Initialize the callout for a timer event. * The my_timer_ev_cb callback function processes the timer event. */ \n os_callout_init ( my_callout , my_timer_interrupt_eventq , \n my_timer_ev_cb , NULL );\n\n os_callout_reset ( my_callout , OS_TICKS_PER_SEC );\n\n /* * Initialize and enable interrupt for the pin for button 1 and * configure the button with pull up resistor on the nrf52dk. */ \n hal_gpio_irq_init ( BUTTON1_PIN , my_gpio_irq , NULL , HAL_GPIO_TRIG_RISING , HAL_GPIO_PULL_UP );\n\n hal_gpio_irq_enable ( BUTTON1_PIN );\n\n hal_gpio_init_out ( TASK_LED , 1 );\n hal_gpio_init_out ( CALLOUT_LED , 1 );\n hal_gpio_init_out ( GPIO_LED , 1 );\n} int main ( int argc , char **argv )\n{\n sysinit ();\n\n init_tasks ();\n\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ()); \n }\n assert ( 0 );\n}",
- "title": "Putting It All Together"
- },
- {
- "location": "/os/tutorials/bletiny_project/",
- "text": "Check stats for a BLE Application the NRF52 Board\n\n\n\n\nThis tutorial explains how to run an example BLE app on a board and command it to scan and spew some stats. The stats will be seen over a serial port, not a BLE wireless connection.\n\n\n\n\nPrerequisites\n\n\nEnsure that you have met the following prerequisites before continuing with this tutorial:\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a board with BLE radio that is supported by Mynewt. We will use an nRF52 Dev board in this tutorial.\n\n\nHave a cable to establish a serial USB connection between the board and the laptop\n\n\nInstall the newt tool and toolchains (See \nBasic Setup\n).\n\n\nInstall the \nSegger JLINK package\n to load your project on the board.\n\n\n\n\n\n\nCreate a project\n\n\nUse the newt tool to create a new project directory containing a skeletal Mynewt framework. Change into the newly created directory.\n\n\n$ newt new myproj \nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in myproj...\nProject myproj successfully created.\n$ cd myproj\n\n$ newt install \n\n\n\n\n\n\n\nCreate targets\n\n\nYou will create two targets - one for the bootloader, the other for the application.\n\n\n$ newt target create myble\nTarget targets/myble successfully created\n$ newt target create nrf52_boot\nTarget targets/myble successfully created\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/myble\ntargets/nrf52_boot\n\n\n\n\n\n\n\nDefine the targets further. Note that you are using the example app \nbletiny\n for the application target. Set the bsp \n\n\nNOTE:\n The preview version, nrf52pdk, is no longer supported. If you do not see PCA100040 on the top of your board, you have a preview version of the board and will need to upgrade your developer board before continuing.\n\n\n\n\n$ newt target set myble bsp=@apache-mynewt-core/hw/bsp/nrf52dk\nTarget targets/myble successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set myble app=@apache-mynewt-core/apps/bletiny\nTarget targets/myble successfully set target.app to @apache-mynewt-core/apps/bletiny\n$ newt target set myble build_profile=optimized\nTarget targets/myble successfully set target.build_profile to optimized\n\n\n\n\n\nUse the same \nnewt target set\n command to set the following definition for the bootloader target -- again, make sure you use the correct value for the bsp based on which version of the board you have..\n\n\ntargets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\nYou should have the following targets by the end of this step.\n\n\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/myble\n app=@apache-mynewt-core/apps/bletiny\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\ntargets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\nSince we're interested in seeing the stats, we'll need to enable the stats module for the target. By default, the stats module is not enabled, so we will have to override the default behavior.\nTo do this, you'll need to create a configuration file \nsyscfg.yml\n in the app directory. from the target definition above, you can see that the app is in \napache-mynewt-core/apps/bletiny\n\nso that is where you'll put your configuration file. \n\n\n# Package: apps/bletiny\n\nsyscfg.vals:\n SHELL_TASK: 1\n STATS_NAMES: 1\n STATS_CLI: 1\n\n\n\n\n\nThe first configuration value turns on the Shell Task, and we'll need this to get to the shell. The next 2 enable the names for the various stats, and then turns on the stats CLI option.\n\n\nBuild targets\n\n\nThen build the two targets.\n\n\nRun the \nnewt build nrf52_boot\n command to build the bootloader:\n\n\nBuilding target targets/nrf52_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/myproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot\n\n\n\n\n\n\nRun the \nnewt build myble\n command to build the bletiny application:\n\n\n newt build myble\nBuilding target targets/myble\nCompiling repos/apache-mynewt-core/encoding/base64/src/base64.c\nCompiling repos/apache-mynewt-core/encoding/base64/src/hex.c\nCompiling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/hal_bsp.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/parse.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/misc.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/gatt_svr.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/cmd.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/main.c\n\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nTarget successfully built: targets/myble\n\n\n\n\n\n\n\nCreate the app image\n\n\nRun the \nnewt create-image myble 1.0.0\n command to generate a signed application image for the \nmyble\n target. The version number is arbitrary.\n\n\n$newt create-image myble 1.0.0\nCompiling bin/targets/myble/generated/src/myble-sysinit-app.c\nArchiving myble-sysinit-app.a\nLinking ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nApp image succesfully generated: ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.img\n\n\n\n\n\n\n\nLoad the image\n\n\nMake 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.\n\n\n$ newt load nrf52_boot\n$ newt load myble\n\n\n\n\n\n\n\nEstablish serial connection\n\n\nYou will now look for some BLE related stats over a serial connection and see the radio is actually working. \nIf you haven't done so already, make sure you're familiar with the \nSerial Port Setup and Configuration\n\nsection. \n\n\n\n\nOnce you have a connection set up, you can connect to your device as follows:\n\n\n\n\n\n\nOn Mac OS and Linux platforms, you can run \nminicom -D /dev/tty.usbserial-\nport\n -b 115200\n to connect to the console of your app. Note that on Linux, the format of the port name is \n/dev/ttyUSB\nN\n, where N is a number.\n\n\n\n\n\n\nOn Windows, you can run \nPuTTY\n to connect to the device.\n\n\nIf you located your port from a MinGW terminal, the port name format is \n/dev/ttyS\nN\n, where \nN\n is a number. You must map the port name to a Windows COM port: \n/dev/ttyS\nN\n maps to \nCOM\nN+1\n. For example, \n/dev/ttyS2\n maps to \nCOM3\n.\n\n\nYou can also use the Windows Device Manager to locate the COM port number.\n\n\n\n\n\n\n\nThis tutorial uses minicom. When the Minicom screen comes up, type in \n?\n\n\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Mar 18 2016, 04:59:47.\nPort /dev/tty.usbserial-1a12, 21:24:09\n\nPress Meta-Z for help on special keys\n\n\n?\n\n7471:Commands:\n7471: stat echo ? prompt ticks tasks \n7474: mempools date b \n\n\n\n\n\n\n\nIf you'd like a shell prompt, try the \nprompt\n command.\n\n\nprompt\n\n14025:Usage: prompt [set|show] [prompt_char]\nprompt set \n\n15086:Prompt set to: \n\n15086:Usage: prompt [set|show] [prompt_char]\n15087: \n\n\n\n\n\n\nYou'll notice that there is an ever-increasing counter before the prompt (and before any output to the terminal).\nThis is just a counter kept by the MCU.\n\n\nNote\n: If you want to have a shell prompt by default, simply add the line: \nCONSOLE_PROMPT: 1\n to your \nsyscfg.yml\n file and it will be turned on by default.\n\n\n\n\nTry the \ntasks\n command. \n\n\n tasks\n\nTasks: \n46682: task pri tid runtime csw stksz stkuse lcheck ncheck fg\n46684: idle 255 0 46683 99 64 31 0 0 0\n46686: main 127 1 1 29 512 156 0 0 0\n46688: ble_ll 0 2 0 12 80 58 0 0 0\n46691: \n \n\n\n\n\n\n\n\nTry specifying a BLE related stat, for example \nble_ll\n. You should see some HCI (Host Controller Interface) command counts. \n\n\n113136: \n stat ble_ll\n\nhci_cmds: 11\n155545:hci_cmd_errs: 0\n155545:hci_events_sent: 11\n155547:bad_ll_state: 0\n155547:bad_acl_hdr: 0\n155548:no_bufs: 0\n155548:rx_adv_pdu_crc_ok: 0\n155549:rx_adv_pdu_crc_err: 0\n155550:rx_adv_bytes_crc_ok: 0\n155551:rx_adv_bytes_crc_err: 0\n155552:rx_data_pdu_crc_ok: 0\n\n ...\n\n155564:scan_req_txf: 0\n155565:scan_req_txg: 0\n155565:scan_rsp_txg: 0\n155566: \n \n\n\n\n\n\n\n\nFor a more exciting output, try scanning your surroundings for BLE advertisements. The HCI command shown below specifies a scan duration in ms, scan to passive, and no duplicates. You should see some scan data flying by!\n\n\nb scan dur=10000 passive=1 nodups=1\n\n37266:[ts=291140616ssb, mod=4 level=1] GAP procedure initiated: discovery; own_as\n\n37641:\n38256:received advertisement; event_type=0 rssi=-48 addr_type=1 addr=59:cc:3d:a3:\n38261: flags=0x1a:\n38261: General discoverable mode\n38262: uuids16(complete)=0x1802 \n38263: name(complete)=Find Me\n38264:\n38551:scanning finished\n\n\n\n\n\n\n\nIf you're still not seeing any output from the device, try running the debugger and see if you are seeing the program execute properly. \n\n\n\n\n$newt debug myble\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk ~/dev/wanda/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny]\n~/dev/myproj/repos/apache-mynewt-core/hw/scripts/common.sh: line 38: [: =: unary operator expected\nDebugging ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nGNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs\nCopyright (C) 2014 Free Software Foundation, Inc.\nLicense GPLv3+: GNU GPL version 3 or later \nhttp://gnu.org/licenses/gpl.html\n\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law. Type \nshow copying\n\nand \nshow warranty\n for details.\nThis GDB was configured as \n--host=x86_64-apple-darwin10 --target=arm-none-eabi\n.\nType \nshow configuration\n for configuration details.\nFor bug reporting instructions, please see:\n\nhttp://www.gnu.org/software/gdb/bugs/\n.\nFind the GDB manual and other documentation resources online at:\n\nhttp://www.gnu.org/software/gdb/documentation/\n.\nFor help, type \nhelp\n.\nType \napropos word\n to search for commands related to \nword\n...\nReading symbols from ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf...done.\nos_tick_idle (ticks=1920)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\n200 if (ticks \n 0) {\n(gdb) monitor reset\nResetting target\n(gdb) c\nContinuing.\n^C\nProgram received signal SIGTRAP, Trace/breakpoint trap.\nos_tick_idle (ticks=1907)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\n200 if (ticks \n 0) {\n(gdb) p g_os_time\n$1 = 13\n(gdb) c\nContinuing.\n^C\nProgram received signal SIGTRAP, Trace/breakpoint trap.\nos_tick_idle (ticks=1920)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\n200 if (ticks \n 0) {\n(gdb) p g_os_time\n$2 = 6611\n(gdb) \n\n\n\n\n\n\n\nYou should see the g_os_time advancing as above, as each os time tick is 1ms. If the system ticks aren't advancing, then nothing's actually running.",
- "title": "BLE app to check stats via console"
- },
- {
- "location": "/os/tutorials/bletiny_project/#check-stats-for-a-ble-application-the-nrf52-board",
- "text": "This tutorial explains how to run an example BLE app on a board and command it to scan and spew some stats. The stats will be seen over a serial port, not a BLE wireless connection.",
- "title": "Check stats for a BLE Application the NRF52 Board"
- },
- {
- "location": "/os/tutorials/bletiny_project/#prerequisites",
- "text": "Ensure that you have met the following prerequisites before continuing with this tutorial: Have Internet connectivity to fetch remote Mynewt components. Have a board with BLE radio that is supported by Mynewt. We will use an nRF52 Dev board in this tutorial. Have a cable to establish a serial USB connection between the board and the laptop Install the newt tool and toolchains (See Basic Setup ). Install the Segger JLINK package to load your project on the board.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/bletiny_project/#create-a-project",
- "text": "Use the newt tool to create a new project directory containing a skeletal Mynewt framework. Change into the newly created directory. $ newt new myproj \nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in myproj...\nProject myproj successfully created.\n$ cd myproj\n\n$ newt install",
- "title": "Create a project"
- },
- {
- "location": "/os/tutorials/bletiny_project/#create-targets",
- "text": "You will create two targets - one for the bootloader, the other for the application. $ newt target create myble\nTarget targets/myble successfully created\n$ newt target create nrf52_boot\nTarget targets/myble successfully created\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/myble\ntargets/nrf52_boot Define the targets further. Note that you are using the example app bletiny for the application target. Set the bsp NOTE: The preview version, nrf52pdk, is no longer supported. If you do not see PCA100040 on the top of your board, you have a preview version of the board and will need to upgrade your developer board before continuing. $ newt target set myble bsp=@apache-mynewt-core/hw/bsp/nrf52dk\nTarget targets/myble successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set myble app=@apache-mynewt-core/apps/bletiny\nTarget targets/myble successfully set target.app to @apache-mynewt-core/apps/bletiny\n$ newt target set myble build_profile=optimized\nTarget targets/myble successfully set target.build_profile to optimized Use the same newt target set command to set the following definition for the bootloader target -- again, make sure you use the correct value for the bsp based on which version of the board you have.. targets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized You should have the following targets by the end of this step. $ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/myble\n app=@apache-mynewt-core/apps/bletiny\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\ntargets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized Since we're interested in seeing the stats, we'll need to enable the stats module for the target. By default, the stats module is not enabled, so we will have to override the default behavior.\nTo do this, you'll need to create a configuration file syscfg.yml in the app directory. from the target definition above, you can see that the app is in apache-mynewt-core/apps/bletiny \nso that is where you'll put your configuration file. # Package: apps/bletiny\n\nsyscfg.vals:\n SHELL_TASK: 1\n STATS_NAMES: 1\n STATS_CLI: 1 The first configuration value turns on the Shell Task, and we'll need this to get to the shell. The next 2 enable the names for the various stats, and then turns on the stats CLI option.",
- "title": "Create targets"
- },
- {
- "location": "/os/tutorials/bletiny_project/#build-targets",
- "text": "Then build the two targets. Run the newt build nrf52_boot command to build the bootloader: Building target targets/nrf52_boot\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c\nCompiling repos/apache-mynewt-core/boot/bootutil/src/loader.c\nCompiling repos/apache-mynewt-core/apps/boot/src/boot.c\n\nArchiving sys_sysinit.a\nArchiving util_mem.a\nLinking ~/myproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot \nRun the newt build myble command to build the bletiny application: newt build myble\nBuilding target targets/myble\nCompiling repos/apache-mynewt-core/encoding/base64/src/base64.c\nCompiling repos/apache-mynewt-core/encoding/base64/src/hex.c\nCompiling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/hal_bsp.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/parse.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/misc.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/gatt_svr.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/cmd.c\nCompiling repos/apache-mynewt-core/apps/bletiny/src/main.c\n\nArchiving util_mem.a\nLinking ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nTarget successfully built: targets/myble",
- "title": "Build targets"
- },
- {
- "location": "/os/tutorials/bletiny_project/#create-the-app-image",
- "text": "Run the newt create-image myble 1.0.0 command to generate a signed application image for the myble target. The version number is arbitrary. $newt create-image myble 1.0.0\nCompiling bin/targets/myble/generated/src/myble-sysinit-app.c\nArchiving myble-sysinit-app.a\nLinking ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nApp image succesfully generated: ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.img",
- "title": "Create the app image"
- },
- {
- "location": "/os/tutorials/bletiny_project/#load-the-image",
- "text": "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. $ newt load nrf52_boot\n$ newt load myble",
- "title": "Load the image"
- },
- {
- "location": "/os/tutorials/bletiny_project/#establish-serial-connection",
- "text": "You will now look for some BLE related stats over a serial connection and see the radio is actually working. \nIf you haven't done so already, make sure you're familiar with the Serial Port Setup and Configuration \nsection. Once you have a connection set up, you can connect to your device as follows: On Mac OS and Linux platforms, you can run minicom -D /dev/tty.usbserial- port -b 115200 to connect to the console of your app. Note that on Linux, the format of the port name is /dev/ttyUSB N , where N is a number. On Windows, you can run PuTTY to connect to the device. If you located your port from a MinGW terminal, the port name format is /dev/ttyS N , where N is a number. You must map the port name to a Windows COM port: /dev/ttyS N maps to COM N+1 . For example, /dev/ttyS2 maps to COM3 . You can also use the Windows Device Manager to locate the COM port number. \nThis tutorial uses minicom. When the Minicom screen comes up, type in ? Welcome to minicom 2.7\n\nOPTIONS: \nCompiled on Mar 18 2016, 04:59:47.\nPort /dev/tty.usbserial-1a12, 21:24:09\n\nPress Meta-Z for help on special keys ? 7471:Commands:\n7471: stat echo ? prompt ticks tasks \n7474: mempools date b If you'd like a shell prompt, try the prompt command. prompt 14025:Usage: prompt [set|show] [prompt_char]\nprompt set \n15086:Prompt set to: \n15086:Usage: prompt [set|show] [prompt_char]\n15087: You'll notice that there is an ever-increasing counter before the prompt (and before any output to the terminal).\nThis is just a counter kept by the MCU. Note : If you want to have a shell prompt by default, simply add the line: CONSOLE_PROMPT: 1 to your syscfg.yml file and it will be turned on by default. Try the tasks command. tasks Tasks: \n46682: task pri tid runtime csw stksz stkuse lcheck ncheck fg\n46684: idle 255 0 46683 99 64 31 0 0 0\n46686: main 127 1 1 29 512 156 0 0 0\n46688: ble_ll 0 2 0 12 80 58 0 0 0\n46691: Try specifying a BLE related stat, for example ble_ll . You should see some HCI (Host Controller Interface) command counts. 113136: stat ble_ll hci_cmds: 11\n155545:hci_cmd_errs: 0\n155545:hci_events_sent: 11\n155547:bad_ll_state: 0\n155547:bad_acl_hdr: 0\n155548:no_bufs: 0\n155548:rx_adv_pdu_crc_ok: 0\n155549:rx_adv_pdu_crc_err: 0\n155550:rx_adv_bytes_crc_ok: 0\n155551:rx_adv_bytes_crc_err: 0\n155552:rx_data_pdu_crc_ok: 0\n\n ...\n\n155564:scan_req_txf: 0\n155565:scan_req_txg: 0\n155565:scan_rsp_txg: 0\n155566: For a more exciting output, try scanning your surroundings for BLE advertisements. The HCI command shown below specifies a scan duration in ms, scan to passive, and no duplicates. You should see some scan data flying by! b scan dur=10000 passive=1 nodups=1 37266:[ts=291140616ssb, mod=4 level=1] GAP procedure initiated: discovery; own_as\n\n37641:\n38256:received advertisement; event_type=0 rssi=-48 addr_type=1 addr=59:cc:3d:a3:\n38261: flags=0x1a:\n38261: General discoverable mode\n38262: uuids16(complete)=0x1802 \n38263: name(complete)=Find Me\n38264:\n38551:scanning finished If you're still not seeing any output from the device, try running the debugger and see if you are seeing the program execute properly. $newt debug myble\n[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk ~/dev/wanda/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny]\n~/dev/myproj/repos/apache-mynewt-core/hw/scripts/common.sh: line 38: [: =: unary operator expected\nDebugging ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf\nGNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs\nCopyright (C) 2014 Free Software Foundation, Inc.\nLicense GPLv3+: GNU GPL version 3 or later http://gnu.org/licenses/gpl.html \nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law. Type show copying \nand show warranty for details.\nThis GDB was configured as --host=x86_64-apple-darwin10 --target=arm-none-eabi .\nType show configuration for configuration details.\nFor bug reporting instructions, please see: http://www.gnu.org/software/gdb/bugs/ .\nFind the GDB manual and other documentation resources online at: http://www.gnu.org/software/gdb/documentation/ .\nFor help, type help .\nType apropos word to search for commands related to word ...\nReading symbols from ~/dev/myproj/bin/targets/myble/app/apps/bletiny/bletiny.elf...done.\nos_tick_idle (ticks=1920)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\n200 if (ticks 0) {\n(gdb) monitor reset\nResetting target\n(gdb) c\nContinuing.\n^C\nProgram received signal SIGTRAP, Trace/breakpoint trap.\nos_tick_idle (ticks=1907)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\n200 if (ticks 0) {\n(gdb) p g_os_time\n$1 = 13\n(gdb) c\nContinuing.\n^C\nProgram received signal SIGTRAP, Trace/breakpoint trap.\nos_tick_idle (ticks=1920)\n at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200\n200 if (ticks 0) {\n(gdb) p g_os_time\n$2 = 6611\n(gdb) You should see the g_os_time advancing as above, as each os time tick is 1ms. If the system ticks aren't advancing, then nothing's actually running.",
- "title": "Establish serial connection"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-intro/",
- "text": "BLE Peripheral Project\n\n\nIntroduction\n\n\n\n\nOverview\n\n\nbleprph\n is an example app included in the apache-mynewt-core repository. This app implements a simple BLE peripheral with the following properties:\n\n\n\n\nSupports a single concurrent connection.\n\n\nAutomatically advertises connectability when not connected to a central device.\n\n\nSupports pairing and bonding.\n\n\nSupports five services.\n\n\n\n\nThis tutorial aims to provide a guided tour through the \nbleprph\n app source\ncode. This document builds on some concepts described elsewhere in the Apache\nMynewt documentation. Before proceeding with this tutorial, you might want to\nfamiliarize yourself with the following pages:\n\n\n\n\nCreate Your First Mynewt Project\n\n\nNimBLE Stack Initialization\n\n\n\n\n\n\nServices, Characteristics, Descriptors\n\n\nA BLE peripheral interfaces with other BLE devices by exposing \nservices\n,\n\ncharacteristics\n, and \ndescriptors\n. All three of these entities are\nimplemented at a lower layer via \nattributes\n. If you are not familiar with\nthese concepts, you will probably want to check out this\n\noverview\n\nfrom the Bluetooth Developer's site before proceeding.\n\n\nNow let's dig in to some C code.",
- "title": "toc"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-intro/#ble-peripheral-project",
- "text": "",
- "title": "BLE Peripheral Project"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-intro/#introduction",
- "text": "",
- "title": "Introduction"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-intro/#overview",
- "text": "bleprph is an example app included in the apache-mynewt-core repository. This app implements a simple BLE peripheral with the following properties: Supports a single concurrent connection. Automatically advertises connectability when not connected to a central device. Supports pairing and bonding. Supports five services. This tutorial aims to provide a guided tour through the bleprph app source\ncode. This document builds on some concepts described elsewhere in the Apache\nMynewt documentation. Before proceeding with this tutorial, you might want to\nfamiliarize yourself with the following pages: Create Your First Mynewt Project NimBLE Stack Initialization",
- "title": "Overview"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-intro/#services-characteristics-descriptors",
- "text": "A BLE peripheral interfaces with other BLE devices by exposing services , characteristics , and descriptors . All three of these entities are\nimplemented at a lower layer via attributes . If you are not familiar with\nthese concepts, you will probably want to check out this overview \nfrom the Bluetooth Developer's site before proceeding. Now let's dig in to some C code.",
- "title": "Services, Characteristics, Descriptors"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-svc-reg/",
- "text": "BLE Peripheral Project\n\n\nService Registration\n\n\n\n\nAttribute Set\n\n\nThe NimBLE host uses a table-based design for GATT server configuration. The\nset of supported attributes are expressed as a series of tables that resides in\nyour C code.\n\n\nbleprph\n supports the following services:\n\n\n\n\nGAP\n\n\nGATT\n\n\nnewtmgr\n\n\nAlert Notification\n\n\nSecurity Test\n\n\n\n\nThe first two services (GAP and GATT) are mandatory services that all BLE peripherals must support. These are implemented in a separate package which the \nbleprph\n app depends on. Later, we will see how the \nmain()\n function initializes and registers this package. Your app will follow the same procedure when using GATT service libraries.\n\n\nThe third service, newtmgr, is vendor-specific service supported by most Mynewt devices. This service is used for remote configuration, status queries, and firmware updates. As with GAP and GATT, this service is implemented in a package separate from the \nbleprph\n app.\n\n\nThe final two services, \nAlert Notification\n and \nSecurity Test\n, are not implemented in separate libraries. Rather, these services are specific to the app, so they are implemented the \nbleprph\n app itself. The attribute table used to express these services is located in the \ngatt_svr.c\n file, so let's take a look at that now. The attribute table is called \ngatt_svr_svcs\n; here are the first several lines from this table:\n\n\n\n\nstatic\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \ngatt_svr_svcs\n[] \n=\n {\n {\n \n/*** Alert Notification Service. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_SVC_ALERT_UUID\n),\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_NEW_ALERT\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_NOTIFY\n,\n }, {\n \n// [...]\n\n\n\n\n\n\n\n\nAs you can see, the table is an array of service definitions (\n\nstruct ble_gatt_svc_def\n). This code excerpt contains a small part of the\nAlert Notification service. Let's now consider the contents of this table in\nmore detail.\n\n\nA service definition consists of the following fields:\n\n\n\n\n\n\n\n\nField\n\n\nMeaning\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\ntype\n\n\nSpecifies whether this is a primary or secondary service.\n\n\nSecondary services are not very common. When in doubt, specify \nBLE_GATT_SVC_TYPE_PRIMARY\n for new services.\n\n\n\n\n\n\nuuid128\n\n\nThe 128-bit UUID of this service.\n\n\nIf the service has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the \nBLE_UUID16()\n macro.\n\n\n\n\n\n\ncharacteristics\n\n\nThe array of characteristics that belong to this service.\n\n\n\n\n\n\n\n\n\n\n\n\nA service is little more than a container of characteristics; the\ncharacteristics themselves are where the real action happens. A characteristic\ndefinition consists of the following fields:\n\n\n\n\n\n\n\n\nField\n\n\nMeaning\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nuuid128\n\n\nThe 128-bit UUID of this characteristic.\n\n\nIf the characteristic has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the \nBLE_UUID16()\n macro.\n\n\n\n\n\n\naccess_cb\n\n\nA callback function that gets executed whenever a peer device accesses this characteristic.\n\n\nFor reads:\n this function generates the value that gets sent back to the peer.\nFor writes:\n this function receives the written value as an argument.\n\n\n\n\n\n\nflags\n\n\nIndicates which operations are permitted for this characteristic. The NimBLE stack responds negatively when a peer attempts an unsupported operation.\n\n\nThe full list of flags can be found under \nble_gatt_chr_flags\n in \nnet/nimble/host/include/host/ble_gatt.h\n.\n\n\n\n\n\n\n\n\nA characteristic's access callback implements its behavior. Access\ncallbacks are described in detail in the next section:\n\nBLE Peripheral - Characteristic Access\n.\n\n\nThe service definition array and each characteristic definition array is\nterminated with an empty entry, represented with a 0. The below code listing\nshows the last service in the array, including terminating zeros for the\ncharacteristic array and service array.\n\n\n\n\n {\n \n/*** Service: Security test. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid128\n \n=\n \ngatt_svr_svc_sec_test_uuid\n,\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n \n/*** Characteristic: Random number generator. */\n\n .\nuuid128\n \n=\n \ngatt_svr_chr_sec_test_rand_uuid\n,\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_sec_test\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n \n|\n \nBLE_GATT_CHR_F_READ_ENC\n,\n }, {\n \n/*** Characteristic: Static value. */\n\n .\nuuid128\n \n=\n \ngatt_svr_chr_sec_test_static_uuid\n,\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_sec_test\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n \n|\n\n \nBLE_GATT_CHR_F_WRITE\n \n|\n \nBLE_GATT_CHR_F_WRITE_ENC\n,\n }, {\n \n0\n, \n/* No more characteristics in this service. */\n\n } },\n },\n\n {\n \n0\n, \n/* No more services. */\n\n },\n\n\n\n\n\n\n\nRegistration function\n\n\nAfter you have created your service table, your app needs to register it with the NimBLE stack. This is done by calling the \nble_gatts_add_svcs()\n function. There is a small complication, though. The NimBLE host needs to allocate sufficient resources upfront to accommodate all of your peripheral's services. You can ensure your GATT services are accounted for in the host configuration object by calling the \nble_gatts_count_cfg()\n function.\n\n\nThe \nbleprph\n app registers its services in \ngatt_svr.c\n as follows:\n\n\nint\n\n\ngatt_svr_init\n(\nstruct\n \nble_hs_cfg\n \n*cfg\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nble_gatts_count_cfg\n(\ngatt_svr_svcs\n, \ncfg\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \nrc\n;\n }\n\n \nrc\n \n=\n \nble_gatts_add_svcs\n(\ngatt_svr_svcs\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \nrc\n;\n }\n\n \nreturn\n \n0\n;\n}\n\n\n\n\n\nYou application will perform the above two-step process for each service definition array that you wish to register. Libraries that implement GATT services will generally expose an initialization function which does this for you.\n\n\n\n\nDescriptors and Included Services\n\n\nYour peripheral can also expose descriptors and included services. These are\nless common, so they are not covered in this tutorial. For more information,\nsee the \nBLE User Guide\n.",
- "title": "Service Registration"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-svc-reg/#ble-peripheral-project",
- "text": "",
- "title": "BLE Peripheral Project"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-svc-reg/#service-registration",
- "text": "",
- "title": "Service Registration"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-svc-reg/#attribute-set",
- "text": "The NimBLE host uses a table-based design for GATT server configuration. The\nset of supported attributes are expressed as a series of tables that resides in\nyour C code. bleprph supports the following services: GAP GATT newtmgr Alert Notification Security Test The first two services (GAP and GATT) are mandatory services that all BLE peripherals must support. These are implemented in a separate package which the bleprph app depends on. Later, we will see how the main() function initializes and registers this package. Your app will follow the same procedure when using GATT service libraries. The third service, newtmgr, is vendor-specific service supported by most Mynewt devices. This service is used for remote configuration, status queries, and firmware updates. As with GAP and GATT, this service is implemented in a package separate from the bleprph app. The final two services, Alert Notification and Security Test , are not implemented in separate libraries. Rather, these services are specific to the app, so they are implemented the bleprph app itself. The attribute table used to express these services is located in the gatt_svr.c file, so let's take a look at that now. The attribute table is called gatt_svr_svcs ; here are the first several lines from this table: static const struct ble_gatt_svc_def gatt_svr_svcs [] = {\n {\n /*** Alert Notification Service. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid128 = BLE_UUID16 ( GATT_SVR_SVC_ALERT_UUID ),\n . characteristics = ( struct ble_gatt_chr_def []) { {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_NEW_ALERT ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_NOTIFY ,\n }, {\n // [...] As you can see, the table is an array of service definitions ( struct ble_gatt_svc_def ). This code excerpt contains a small part of the\nAlert Notification service. Let's now consider the contents of this table in\nmore detail. A service definition consists of the following fields: Field Meaning Notes type Specifies whether this is a primary or secondary service. Secondary services are not very common. When in doubt, specify BLE_GATT_SVC_TYPE_PRIMARY for new services. uuid128 The 128-bit UUID of this service. If the service has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the BLE_UUID16() macro. characteristics The array of characteristics that belong to this service. A service is little more than a container of characteristics; the\ncharacteristics themselves are where the real action happens. A characteristic\ndefinition consists of the following fields: Field Meaning Notes uuid128 The 128-bit UUID of this characteristic. If the characteristic has a 16-bit UUID, you can convert it to its corresponding 128-bit UUID with the BLE_UUID16() macro. access_cb A callback function that gets executed whenever a peer device accesses this characteristic. For reads: this function generates the value that gets sent back to the peer. For writes: this function receives the written value as an argument. flags Indicates which operations are permitted for this characteristic. The NimBLE stack responds negatively when a peer attempts an unsupported operation. The full list of flags can be found under ble_gatt_chr_flags in net/nimble/host/include/host/ble_gatt.h . A characteristic's access callback implements its behavior. Access\ncallbacks are described in detail in the next section: BLE Peripheral - Characteristic Access . The service definition array and each characteristic definition array is\nterminated with an empty entry, represented with a 0. The below code listing\nshows the last service in the array, including terminating zeros for the\ncharacteristic array and service array. {\n /*** Service: Security test. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid128 = gatt_svr_svc_sec_test_uuid ,\n . characteristics = ( struct ble_gatt_chr_def []) { {\n /*** Characteristic: Random number generator. */ \n . uuid128 = gatt_svr_chr_sec_test_rand_uuid ,\n . access_cb = gatt_svr_chr_access_sec_test ,\n . flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_READ_ENC ,\n }, {\n /*** Characteristic: Static value. */ \n . uuid128 = gatt_svr_chr_sec_test_static_uuid ,\n . access_cb = gatt_svr_chr_access_sec_test ,\n . flags = BLE_GATT_CHR_F_READ | \n BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_WRITE_ENC ,\n }, {\n 0 , /* No more characteristics in this service. */ \n } },\n },\n\n {\n 0 , /* No more services. */ \n },",
- "title": "Attribute Set"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-svc-reg/#registration-function",
- "text": "After you have created your service table, your app needs to register it with the NimBLE stack. This is done by calling the ble_gatts_add_svcs() function. There is a small complication, though. The NimBLE host needs to allocate sufficient resources upfront to accommodate all of your peripheral's services. You can ensure your GATT services are accounted for in the host configuration object by calling the ble_gatts_count_cfg() function. The bleprph app registers its services in gatt_svr.c as follows: int gatt_svr_init ( struct ble_hs_cfg *cfg )\n{\n int rc ;\n\n rc = ble_gatts_count_cfg ( gatt_svr_svcs , cfg );\n if ( rc != 0 ) {\n return rc ;\n }\n\n rc = ble_gatts_add_svcs ( gatt_svr_svcs );\n if ( rc != 0 ) {\n return rc ;\n }\n\n return 0 ;\n} You application will perform the above two-step process for each service definition array that you wish to register. Libraries that implement GATT services will generally expose an initialization function which does this for you.",
- "title": "Registration function"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-svc-reg/#descriptors-and-included-services",
- "text": "Your peripheral can also expose descriptors and included services. These are\nless common, so they are not covered in this tutorial. For more information,\nsee the BLE User Guide .",
- "title": "Descriptors and Included Services"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/",
- "text": "BLE Peripheral Project\n\n\nCharacteristic Access\n\n\n\n\nReview\n\n\nA characteristic's access callback implements its behavior. Recall that\nservices and characteristics are registered with NimBLE via attribute tables.\nEach characteristic definition in an attribute table contains an \naccess_cb\n\nfield. The \naccess_cb\n field is an application callback that gets executed\nwhenever a peer device attempts to read or write the characteristic.\n\n\nEarlier in this tutorial, we looked at how \nbleprph\n implements the ANS\nservice. Let's take another look at how \nbleprph\n specifies the first few\ncharacteristics in this service.\n\n\n\n\nstatic\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \ngatt_svr_svcs\n[] \n=\n {\n {\n \n/*** Alert Notification Service. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_SVC_ALERT_UUID\n),\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n .\nuuid128\n \n=\n \nBLE_UUID16\n(\nGATT_SVR_CHR_NEW_ALERT\n),\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_alert\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_NOTIFY\n,\n }, {\n \n// [...]\n\n\n\n\n\n\nAs you can see, \nbleprph\n uses the same \naccess_cb\n function for all the ANS\nservice characteristics, but the developer could have implemented separate\nfunctions for each characteristic if they preferred. Here is part of the\n\naccess_cb\n function that the ANS service characteristics use:\n\n\n\n\nstatic\n \nint\n\n\ngatt_svr_chr_access_alert\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nble_gatt_access_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n)\n{\n \nuint16_t\n \nuuid16\n;\n \nint\n \nrc\n;\n\n \nuuid16\n \n=\n \nble_uuid_128_to_16\n(\nctxt-\nchr-\nuuid128\n);\n \nassert\n(\nuuid16\n \n!=\n \n0\n);\n\n \nswitch\n (\nuuid16\n) {\n \ncase\n \nGATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID\n:\n \nassert\n(\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nrc\n \n=\n \nos_mbuf_append\n(\nctxt-\nom\n, \ngatt_svr_new_alert_cat\n,\n \nsizeof\n \ngatt_svr_new_alert_cat\n);\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \nBLE_ATT_ERR_INSUFFICIENT_RES\n;\n\n \ncase\n \nGATT_SVR_CHR_UNR_ALERT_STAT_UUID\n:\n \nif\n (\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_WRITE_CHR\n) {\n \nif\n (\nOS_MBUF_PKTLEN\n(\nctxt-\nom\n) \n!=\n \nsizeof\n \ngatt_svr_unr_alert_stat\n) {\n \nreturn\n \nBLE_ATT_ERR_INVALID_ATTR_VALUE_LEN\n;\n }\n\n \nrc\n \n=\n \nble_hs_mbuf_to_flat\n(\nctxt-\nom\n, \ngatt_svr_unr_alert_stat\n,\n \nsizeof\n \ngatt_svr_unr_alert_stat\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \nBLE_ATT_ERR_UNLIKELY\n;\n }\n\n \nreturn\n \n0\n;\n\n \n/* [...] */\n\n\n \ndefault\n:\n\n \nassert\n(\n0\n);\n \nreturn\n \nBLE_ATT_ERR_UNLIKELY\n;\n }\n}\n\n\n\n\n\nAfter you've taken a moment to examine the structure of this function, let's explore some details.\n\n\n\n\nFunction signature\n\n\nstatic\n \nint\n\n\ngatt_svr_chr_access_alert\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nble_gatt_access_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n)\n\n\n\n\n\nA characteristic access function always takes this same set of parameters and\nalways returns an int. The parameters to this function type are documented\nbelow.\n\n\n\n\n\n\n\n\nParameter\n\n\nPurpose\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nIndicates which connection the characteristic access was sent over.\n\n\nUse this value to determine which peer is accessing the characteristic.\n\n\n\n\n\n\nattr_handle\n\n\nThe low-level ATT handle of the characteristic value attribute.\n\n\nCan be used to determine which characteristic is being accessed if you don't want to perform a UUID lookup.\n\n\n\n\n\n\nop\n\n\nIndicates whether this is a read or write operation\n\n\nValid values are:\nBLE_GATT_ACCESS_OP_READ_CHR\nBLE_GATT_ACCESS_OP_WRITE_CHR\n\n\n\n\n\n\nctxt\n\n\nContains the characteristic value mbuf that the application needs to access.\n\n\nFor characteristic accesses, use the \nctxt-\nchr\n member; for descriptor accesses, use the \nctxt-\ndsc\n member.\n\n\n\n\n\n\n\n\nThe return value of the access function tells the NimBLE stack how to respond\nto the peer performing the operation. A value of 0 indicates success. For\nfailures, the function returns the specific \nATT error code\n that the NimBLE\nstack should respond with. \nNote:\n The return code is a formal code, \nnot\n a NimBLE value!\n\n\n\n\nDetermine characteristic being accessed\n\n\n{\n \nuint16_t\n \nuuid16\n;\n\n \nuuid16\n \n=\n \nble_uuid_128_to_16\n(\nctxt-\nchr-\nuuid128\n);\n \nassert\n(\nuuid16\n \n!=\n \n0\n);\n\n \nswitch\n (\nuuid16\n) {\n \n// [...]\n\n\n\n\n\n\nThis function uses the UUID to determine which characteristic is being\naccessed. There are two alternative methods \nbleprph\n could have used to\naccomplish this task:\n\n\n\n\nMap characteristics to ATT handles during service registration; use the \nattr_handle\n parameter as a key into this table during characteristic access.\n\n\nImplement a dedicated function for each characteristic; each function inherently knows which characteristic it corresponds to.\n\n\n\n\nAll the ANS service characteristics have 16-bit UUIDs, so this function uses\nthe \nble_uuid_128_to_16()\n function to convert the 128-bit UUID to its\ncorresponding 16-bit UUID. This conversion function returns the corresponding\n16-bit UUID on success, or 0 on failure. Success is asserted here to ensure\nthe NimBLE stack is doing its job properly; the stack should only call this\nfunction for accesses to characteristics that it is registered with, and all\nANS service characteristics have valid 16-bit UUIDs.\n\n\n\n\nRead access\n\n\n \ncase\n \nGATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID\n:\n \nassert\n(\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nrc\n \n=\n \nos_mbuf_append\n(\nctxt-\nom\n, \ngatt_svr_new_alert_cat\n,\n \nsizeof\n \ngatt_svr_new_alert_cat\n);\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \nBLE_ATT_ERR_INSUFFICIENT_RES\n;\n\n\n\n\n\nThis code excerpt handles read accesses to the Supported New Alert Category\ncharacteristic. The \nassert()\n here is another case of making sure the NimBLE\nstack is doing its job; this characteristic was registered as read-only, so the\nstack should have prevented write accesses.\n\n\nTo fulfill a characteristic read request, the application needs fill a buffer (\nom\n) with the characteristic value. The NimBLE host will then include the contents of this buffer in its read response. NimBLE uses \nmbufs\n to exchange data between itself and the application. To fill an mbuf with data that is available in a contiguous chunk of memory, the \nos_mbuf_append()\n function suffices. The source of the data, \ngatt_svr_new_alert_cat\n, is is stored in read-only memory as follows:\n\n\n\n\nstatic\n \nconst\n \nuint8_t\n \ngatt_svr_new_alert_cat\n \n=\n \n0x01\n; \n/* Simple alert. */\n\n\n\n\n\n\nIt is not shown in the above snippet, but this function ultimately returns 0.\nBy returning 0, \nbleprph\n indicates that the characteristic data in\n\nctxt-\nom\n is valid and that NimBLE should include it in its response\nto the peer.\n\n\n\n\nWrite access\n\n\nstatic\n \nuint16_t\n \ngatt_svr_unr_alert_stat\n;\n\n\n\n\n\n \ncase\n \nGATT_SVR_CHR_UNR_ALERT_STAT_UUID\n:\n \nif\n (\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_WRITE_CHR\n) {\n \nif\n (\nOS_MBUF_PKTLEN\n(\nctxt-\nom\n) \n!=\n \nsizeof\n \ngatt_svr_unr_alert_stat\n) {\n \nreturn\n \nBLE_ATT_ERR_INVALID_ATTR_VALUE_LEN\n;\n }\n\n \nrc\n \n=\n \nble_hs_mbuf_to_flat\n(\nctxt-\nom\n, \ngatt_svr_unr_alert_stat\n,\n \nsizeof\n \ngatt_svr_unr_alert_stat\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \nBLE_ATT_ERR_UNLIKELY\n;\n }\n\n \nreturn\n \n0\n;\n } \nelse\n \n/* [...] */\n\n\n\n\n\n\nThis code excerpt handles writes to the New Alert characteristic. For writes,\nthe role of the \nctxt-\nom\n field is the reverse of the read case. The NimBLE\nstack uses these fields to indicate the data written by the peer.\n\n\nMany characteristics have strict length requirements for write operations.\nThis characteristic has such a restriction; if the written data is not a 2-byte\nvalue, the application tells NimBLE to respond with an invalid attribute value\nlength error.\n\n\nbleprph\n copies the data out of the supplied mbuf and writes it to a contiguous chunk of storage (the \ngatt_svr_unr_alert_stat\n variable). This is accomplished with the \nble_hs_mbuf_to_flat()\n function. If the application did not have a suitable destination for the data handy, it could have inherited the mbuf from the context object. This is done by saving a copy of the mbuf pointer, and assigning \nNULL\n to \nctxt-\nom\n. By assigning \nNULL\n to the mbuf pointer, your application prevents the stack from freeing the mbuf while it is still being used. Be aware, however, that it is the application's responsibility to free inherited mbufs.",
- "title": "Characteristic Access"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#ble-peripheral-project",
- "text": "",
- "title": "BLE Peripheral Project"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#characteristic-access",
- "text": "",
- "title": "Characteristic Access"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#review",
- "text": "A characteristic's access callback implements its behavior. Recall that\nservices and characteristics are registered with NimBLE via attribute tables.\nEach characteristic definition in an attribute table contains an access_cb \nfield. The access_cb field is an application callback that gets executed\nwhenever a peer device attempts to read or write the characteristic. Earlier in this tutorial, we looked at how bleprph implements the ANS\nservice. Let's take another look at how bleprph specifies the first few\ncharacteristics in this service. static const struct ble_gatt_svc_def gatt_svr_svcs [] = {\n {\n /*** Alert Notification Service. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid128 = BLE_UUID16 ( GATT_SVR_SVC_ALERT_UUID ),\n . characteristics = ( struct ble_gatt_chr_def []) { {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n . uuid128 = BLE_UUID16 ( GATT_SVR_CHR_NEW_ALERT ),\n . access_cb = gatt_svr_chr_access_alert ,\n . flags = BLE_GATT_CHR_F_NOTIFY ,\n }, {\n // [...] As you can see, bleprph uses the same access_cb function for all the ANS\nservice characteristics, but the developer could have implemented separate\nfunctions for each characteristic if they preferred. Here is part of the access_cb function that the ANS service characteristics use: static int gatt_svr_chr_access_alert ( uint16_t conn_handle , uint16_t attr_handle ,\n struct ble_gatt_access_ctxt *ctxt ,\n void *arg )\n{\n uint16_t uuid16 ;\n int rc ;\n\n uuid16 = ble_uuid_128_to_16 ( ctxt- chr- uuid128 );\n assert ( uuid16 != 0 );\n\n switch ( uuid16 ) {\n case GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID :\n assert ( ctxt- op == BLE_GATT_ACCESS_OP_READ_CHR );\n rc = os_mbuf_append ( ctxt- om , gatt_svr_new_alert_cat ,\n sizeof gatt_svr_new_alert_cat );\n return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES ;\n\n case GATT_SVR_CHR_UNR_ALERT_STAT_UUID :\n if ( ctxt- op == BLE_GATT_ACCESS_OP_WRITE_CHR ) {\n if ( OS_MBUF_PKTLEN ( ctxt- om ) != sizeof gatt_svr_unr_alert_stat ) {\n return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN ;\n }\n\n rc = ble_hs_mbuf_to_flat ( ctxt- om , gatt_svr_unr_alert_stat ,\n sizeof gatt_svr_unr_alert_stat , NULL );\n if ( rc != 0 ) {\n return BLE_ATT_ERR_UNLIKELY ;\n }\n\n return 0 ;\n\n /* [...] */ \n\n default : \n assert ( 0 );\n return BLE_ATT_ERR_UNLIKELY ;\n }\n} After you've taken a moment to examine the structure of this function, let's explore some details.",
- "title": "Review"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#function-signature",
- "text": "static int gatt_svr_chr_access_alert ( uint16_t conn_handle , uint16_t attr_handle ,\n struct ble_gatt_access_ctxt *ctxt ,\n void *arg ) A characteristic access function always takes this same set of parameters and\nalways returns an int. The parameters to this function type are documented\nbelow. Parameter Purpose Notes conn_handle Indicates which connection the characteristic access was sent over. Use this value to determine which peer is accessing the characteristic. attr_handle The low-level ATT handle of the characteristic value attribute. Can be used to determine which characteristic is being accessed if you don't want to perform a UUID lookup. op Indicates whether this is a read or write operation Valid values are: BLE_GATT_ACCESS_OP_READ_CHR BLE_GATT_ACCESS_OP_WRITE_CHR ctxt Contains the characteristic value mbuf that the application needs to access. For characteristic accesses, use the ctxt- chr member; for descriptor accesses, use the ctxt- dsc member. The return value of the access function tells the NimBLE stack how to respond\nto the peer performing the operation. A value of 0 indicates success. For\nfailures, the function returns the specific ATT error code that the NimBLE\nstack should respond with. Note: The return code is a formal code, not a NimBLE value!",
- "title": "Function signature"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#determine-characteristic-being-accessed",
- "text": "{\n uint16_t uuid16 ;\n\n uuid16 = ble_uuid_128_to_16 ( ctxt- chr- uuid128 );\n assert ( uuid16 != 0 );\n\n switch ( uuid16 ) {\n // [...] This function uses the UUID to determine which characteristic is being\naccessed. There are two alternative methods bleprph could have used to\naccomplish this task: Map characteristics to ATT handles during service registration; use the attr_handle parameter as a key into this table during characteristic access. Implement a dedicated function for each characteristic; each function inherently knows which characteristic it corresponds to. All the ANS service characteristics have 16-bit UUIDs, so this function uses\nthe ble_uuid_128_to_16() function to convert the 128-bit UUID to its\ncorresponding 16-bit UUID. This conversion function returns the corresponding\n16-bit UUID on success, or 0 on failure. Success is asserted here to ensure\nthe NimBLE stack is doing its job properly; the stack should only call this\nfunction for accesses to characteristics that it is registered with, and all\nANS service characteristics have valid 16-bit UUIDs.",
- "title": "Determine characteristic being accessed"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#read-access",
- "text": "case GATT_SVR_CHR_SUP_NEW_ALERT_CAT_UUID :\n assert ( ctxt- op == BLE_GATT_ACCESS_OP_READ_CHR );\n rc = os_mbuf_append ( ctxt- om , gatt_svr_new_alert_cat ,\n sizeof gatt_svr_new_alert_cat );\n return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES ; This code excerpt handles read accesses to the Supported New Alert Category\ncharacteristic. The assert() here is another case of making sure the NimBLE\nstack is doing its job; this characteristic was registered as read-only, so the\nstack should have prevented write accesses. To fulfill a characteristic read request, the application needs fill a buffer ( om ) with the characteristic value. The NimBLE host will then include the contents of this buffer in its read response. NimBLE uses mbufs to exchange data between itself and the application. To fill an mbuf with data that is available in a contiguous chunk of memory, the os_mbuf_append() function suffices. The source of the data, gatt_svr_new_alert_cat , is is stored in read-only memory as follows: static const uint8_t gatt_svr_new_alert_cat = 0x01 ; /* Simple alert. */ It is not shown in the above snippet, but this function ultimately returns 0.\nBy returning 0, bleprph indicates that the characteristic data in ctxt- om is valid and that NimBLE should include it in its response\nto the peer.",
- "title": "Read access"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-chr-access/#write-access",
- "text": "static uint16_t gatt_svr_unr_alert_stat ; case GATT_SVR_CHR_UNR_ALERT_STAT_UUID :\n if ( ctxt- op == BLE_GATT_ACCESS_OP_WRITE_CHR ) {\n if ( OS_MBUF_PKTLEN ( ctxt- om ) != sizeof gatt_svr_unr_alert_stat ) {\n return BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN ;\n }\n\n rc = ble_hs_mbuf_to_flat ( ctxt- om , gatt_svr_unr_alert_stat ,\n sizeof gatt_svr_unr_alert_stat , NULL );\n if ( rc != 0 ) {\n return BLE_ATT_ERR_UNLIKELY ;\n }\n\n return 0 ;\n } else /* [...] */ This code excerpt handles writes to the New Alert characteristic. For writes,\nthe role of the ctxt- om field is the reverse of the read case. The NimBLE\nstack uses these fields to indicate the data written by the peer. Many characteristics have strict length requirements for write operations.\nThis characteristic has such a restriction; if the written data is not a 2-byte\nvalue, the application tells NimBLE to respond with an invalid attribute value\nlength error. bleprph copies the data out of the supplied mbuf and writes it to a contiguous chunk of storage (the gatt_svr_unr_alert_stat variable). This is accomplished with the ble_hs_mbuf_to_flat() function. If the application did not have a suitable destination for the data handy, it could have inherited the mbuf from the context object. This is done by saving a copy of the mbuf pointer, and assigning NULL to ctxt- om . By assigning NULL to the mbuf pointer, your application prevents the stack from freeing the mbuf while it is still being used. Be aware, however, that it is the application's responsibility to free inherited mbufs.",
- "title": "Write access"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-adv/",
- "text": "BLE Peripheral Project\n\n\nAdvertising\n\n\n\n\nOverview\n\n\nA peripheral announces its presence to the world by broadcasting\nadvertisements. An advertisement typically contains additional information\nabout the peripheral sending it, such as the device name and an abbreviated\nlist of supported services. The presence of this information helps a listening\ncentral to determine whether it is interested in connecting to the peripheral.\nAdvertisements are quite limited in the amount of information they can contain,\nso only the most important information should be included.\n\n\nWhen a listening device receives an advertisement, it can choose to connect to\nthe peripheral, or query the sender for more information. This second action\nis known as an \nactive scan\n. A peripheral responds to an active scan with\nsome extra information that it couldn't fit in its advertisement. This\nadditional information is known as \nscan response data\n. \nbleprph\n does not\nconfigure any scan response data, so this feature is not discussed in the\nremainder of this tutorial.\n\n\nbleprph\n constantly broadcasts advertisements until a central connects to it.\nWhen a connection is terminated, \nbleprph\n resumes advertising.\n\n\nLet's take a look at \nbleprph\n's advertisement code (\nmain.c\n):\n\n\n\n\n/**\n\n\n * Enables advertising with the following parameters:\n\n\n * o General discoverable mode.\n\n\n * o Undirected connectable mode.\n\n\n */\n\n\nstatic\n \nvoid\n\n\nbleprph_advertise\n(\nvoid\n)\n{\n \nstruct\n \nble_gap_adv_params\n \nadv_params\n;\n \nstruct\n \nble_hs_adv_fields\n \nfields\n;\n \nconst\n \nchar\n \n*name\n;\n \nint\n \nrc\n;\n\n \n/**\n\n\n * Set the advertisement data included in our advertisements:\n\n\n * o Flags (indicates advertisement type and other general info).\n\n\n * o Advertising tx power.\n\n\n * o Device name.\n\n\n * o 16-bit service UUIDs (alert notifications).\n\n\n */\n\n\n \nmemset\n(\nfields\n, \n0\n, \nsizeof\n \nfields\n);\n\n \n/* Indicate that the flags field should be included; specify a value of 0\n\n\n * to instruct the stack to fill the value in for us.\n\n\n */\n\n \nfields\n.\nflags_is_present\n \n=\n \n1\n;\n \nfields\n.\nflags\n \n=\n \n0\n;\n\n \n/* Indicate that the TX power level field should be included; have the\n\n\n * stack fill this one automatically as well. This is done by assiging the\n\n\n * special value BLE_HS_ADV_TX_PWR_LVL_AUTO.\n\n\n */\n\n \nfields\n.\ntx_pwr_lvl_is_present\n \n=\n \n1\n;\n \nfields\n.\ntx_pwr_lvl\n \n=\n \nBLE_HS_ADV_TX_PWR_LVL_AUTO\n;\n\n \nname\n \n=\n \nble_svc_gap_device_name\n();\n \nfields\n.\nname\n \n=\n (\nuint8_t\n \n*\n)\nname\n;\n \nfields\n.\nname_len\n \n=\n \nstrlen\n(\nname\n);\n \nfields\n.\nname_is_complete\n \n=\n \n1\n;\n\n \nfields\n.\nuuids16\n \n=\n (\nuint16_t\n[]){ \nGATT_SVR_SVC_ALERT_UUID\n };\n \nfields\n.\nnum_uuids16\n \n=\n \n1\n;\n \nfields\n.\nuuids16_is_complete\n \n=\n \n1\n;\n\n \nrc\n \n=\n \nble_gap_adv_set_fields\n(\nfields\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror setting advertisement data; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n\n \n/* Begin advertising. */\n\n \nmemset\n(\nadv_params\n, \n0\n, \nsizeof\n \nadv_params\n);\n \nadv_params\n.\nconn_mode\n \n=\n \nBLE_GAP_CONN_MODE_UND\n;\n \nadv_params\n.\ndisc_mode\n \n=\n \nBLE_GAP_DISC_MODE_GEN\n;\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_ADDR_TYPE_PUBLIC\n, \n0\n, \nNULL\n, \nBLE_HS_FOREVER\n,\n \nadv_params\n, \nbleprph_gap_event\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror enabling advertisement; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n}\n\n\n\n\n\nNow let's examine this code in detail.\n\n\n\n\nSetting advertisement data\n\n\nA NimBLE peripheral specifies what information to include in its advertisements with the \nble_gap_adv_set_fields()\n function.\n\n\nThe \nfields\n argument specifies the fields and their contents to include in\nsubsequent advertisements. The Bluetooth \nCore Specification\nSupplement\n\ndefines a set of standard fields that can be included in an advertisement; the\nmember variables of the \nstruct ble_hs_adv_fields\n type correspond to these\nstandard fields. Information that doesn't fit neatly into a standard field\nshould be put in the \nmanufacturing specific data\n field.\n\n\nAs you can see in the above code listing, the \nstruct ble_hs_adv_fields\n\ninstance is allocated on the stack. It is OK to use the stack for this struct\nand the data it references, as the \nble_gap_adv_set_fields()\n\nfunction makes a copy of all the advertisement data before it returns.\n\nbleprph\n doesn't take full advantange of this; it stores its device name in a\nstatic array.\n\n\nThe code sets several members of the \nstruct ble_hs_adv_fields\n instance. Most\nof them are quite straight-forward. However, the \nname_is_complete\n field\nrequires some explanation. Bluetooth specifies two name-related advertisement\nfields: \nShortened Local Name\n and \nComplete Local Name\n. Setting the\n\nname_is_complete\n variable to 1 or 0 tells NimBLE which of these two fields to\ninclude in advertisements. Some other advertisement fields also correspond to\nmultiple variables in the field struct, so it is a good idea to review the\n\nble_hs_adv_fields\n reference to make sure you get the details right in your\napp.\n\n\n\n\nBegin advertising\n\n\nAn app starts advertising with\n\nble_gap_adv_start()\n\nfunction. This function allows a lot of flexibility, and it might seem\ndaunting at first glance. \nbleprph\n specifies a simple set of arguments that\nis appropriate for most peripherals. When getting started on a typical\nperipheral, we recommend you use the same arguments as \nbleprph\n, with the\nexception of the last two (\ncb\n and \ncb_arg\n; \nbleprph_gap_event\n and \nNULL\n in\nthis case). These last two arguments will be specific to your app, so let's\ntalk about them.\n\n\ncb\n is a callback function. It gets executed when a central connects to your\nperipheral after receiving an advertisement. The \ncb_arg\n argument gets passed\nto the \ncb\n callback. If your callback doesn't need the \ncb_arg\n parameter,\nyou can do what \nbleprph\n does and pass \nNULL\n. Once a connection is\nestablished, the \ncb\n callback becomes permanently associated with the\nconnection. All subsequent events related to the connection are communicated\nto your app via calls to this callback function. GAP event callbacks are an\nimportant part of building a BLE app, and we examine \nbleprph\n's connection\ncallback in detail in the next section of this tutorial.\n\n\n\n\nOne final note:\n Your peripheral automatically stops advertising when a\ncentral connects to it. You can immediately resume advertising if you want to\nallow another central to connect, but you will need to do so explicitly by\ncalling \nble_gap_adv_start()\n again. Also, be aware NimBLE's default\nconfiguration only allows a single connection at a time. NimBLE supports\nmultiple concurrent connections, but you must configure it to do so first.",
- "title": "Advertising"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-adv/#ble-peripheral-project",
- "text": "",
- "title": "BLE Peripheral Project"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-adv/#advertising",
- "text": "",
- "title": "Advertising"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-adv/#overview",
- "text": "A peripheral announces its presence to the world by broadcasting\nadvertisements. An advertisement typically contains additional information\nabout the peripheral sending it, such as the device name and an abbreviated\nlist of supported services. The presence of this information helps a listening\ncentral to determine whether it is interested in connecting to the peripheral.\nAdvertisements are quite limited in the amount of information they can contain,\nso only the most important information should be included. When a listening device receives an advertisement, it can choose to connect to\nthe peripheral, or query the sender for more information. This second action\nis known as an active scan . A peripheral responds to an active scan with\nsome extra information that it couldn't fit in its advertisement. This\nadditional information is known as scan response data . bleprph does not\nconfigure any scan response data, so this feature is not discussed in the\nremainder of this tutorial. bleprph constantly broadcasts advertisements until a central connects to it.\nWhen a connection is terminated, bleprph resumes advertising. Let's take a look at bleprph 's advertisement code ( main.c ): /** * Enables advertising with the following parameters: * o General discoverable mode. * o Undirected connectable mode. */ static void bleprph_advertise ( void )\n{\n struct ble_gap_adv_params adv_params ;\n struct ble_hs_adv_fields fields ;\n const char *name ;\n int rc ;\n\n /** * Set the advertisement data included in our advertisements: * o Flags (indicates advertisement type and other general info). * o Advertising tx power. * o Device name. * o 16-bit service UUIDs (alert notifications). */ \n\n memset ( fields , 0 , sizeof fields );\n\n /* Indicate that the flags field should be included; specify a value of 0 * to instruct the stack to fill the value in for us. */ \n fields . flags_is_present = 1 ;\n fields . flags = 0 ;\n\n /* Indicate that the TX power level field should be included; have the * stack fill this one automatically as well. This is done by assiging the * special value BLE_HS_ADV_TX_PWR_LVL_AUTO. */ \n fields . tx_pwr_lvl_is_present = 1 ;\n fields . tx_pwr_lvl = BLE_HS_ADV_TX_PWR_LVL_AUTO ;\n\n name = ble_svc_gap_device_name ();\n fields . name = ( uint8_t * ) name ;\n fields . name_len = strlen ( name );\n fields . name_is_complete = 1 ;\n\n fields . uuids16 = ( uint16_t []){ GATT_SVR_SVC_ALERT_UUID };\n fields . num_uuids16 = 1 ;\n fields . uuids16_is_complete = 1 ;\n\n rc = ble_gap_adv_set_fields ( fields );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error setting advertisement data; rc=%d\\n , rc );\n return ;\n }\n\n /* Begin advertising. */ \n memset ( adv_params , 0 , sizeof adv_params );\n adv_params . conn_mode = BLE_GAP_CONN_MODE_UND ;\n adv_params . disc_mode = BLE_GAP_DISC_MODE_GEN ;\n rc = ble_gap_adv_start ( BLE_ADDR_TYPE_PUBLIC , 0 , NULL , BLE_HS_FOREVER ,\n adv_params , bleprph_gap_event , NULL );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error enabling advertisement; rc=%d\\n , rc );\n return ;\n }\n} Now let's examine this code in detail.",
- "title": "Overview"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-adv/#setting-advertisement-data",
- "text": "A NimBLE peripheral specifies what information to include in its advertisements with the ble_gap_adv_set_fields() function. The fields argument specifies the fields and their contents to include in\nsubsequent advertisements. The Bluetooth Core Specification\nSupplement \ndefines a set of standard fields that can be included in an advertisement; the\nmember variables of the struct ble_hs_adv_fields type correspond to these\nstandard fields. Information that doesn't fit neatly into a standard field\nshould be put in the manufacturing specific data field. As you can see in the above code listing, the struct ble_hs_adv_fields \ninstance is allocated on the stack. It is OK to use the stack for this struct\nand the data it references, as the ble_gap_adv_set_fields() \nfunction makes a copy of all the advertisement data before it returns. bleprph doesn't take full advantange of this; it stores its device name in a\nstatic array. The code sets several members of the struct ble_hs_adv_fields instance. Most\nof them are quite straight-forward. However, the name_is_complete field\nrequires some explanation. Bluetooth specifies two name-related advertisement\nfields: Shortened Local Name and Complete Local Name . Setting the name_is_complete variable to 1 or 0 tells NimBLE which of these two fields to\ninclude in advertisements. Some other advertisement fields also correspond to\nmultiple variables in the field struct, so it is a good idea to review the ble_hs_adv_fields reference to make sure you get the details right in your\napp.",
- "title": "Setting advertisement data"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-adv/#begin-advertising",
- "text": "An app starts advertising with ble_gap_adv_start() \nfunction. This function allows a lot of flexibility, and it might seem\ndaunting at first glance. bleprph specifies a simple set of arguments that\nis appropriate for most peripherals. When getting started on a typical\nperipheral, we recommend you use the same arguments as bleprph , with the\nexception of the last two ( cb and cb_arg ; bleprph_gap_event and NULL in\nthis case). These last two arguments will be specific to your app, so let's\ntalk about them. cb is a callback function. It gets executed when a central connects to your\nperipheral after receiving an advertisement. The cb_arg argument gets passed\nto the cb callback. If your callback doesn't need the cb_arg parameter,\nyou can do what bleprph does and pass NULL . Once a connection is\nestablished, the cb callback becomes permanently associated with the\nconnection. All subsequent events related to the connection are communicated\nto your app via calls to this callback function. GAP event callbacks are an\nimportant part of building a BLE app, and we examine bleprph 's connection\ncallback in detail in the next section of this tutorial. One final note: Your peripheral automatically stops advertising when a\ncentral connects to it. You can immediately resume advertising if you want to\nallow another central to connect, but you will need to do so explicitly by\ncalling ble_gap_adv_start() again. Also, be aware NimBLE's default\nconfiguration only allows a single connection at a time. NimBLE supports\nmultiple concurrent connections, but you must configure it to do so first.",
- "title": "Begin advertising"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-gap-event/",
- "text": "BLE Peripheral Project\n\n\nGAP Event callbacks\n\n\n\n\nOverview\n\n\nEvery BLE connection has a \nGAP event callback\n associated with it. A\nGAP event callback is a bit of application code which NimBLE uses to inform\nyou of connection-related events. For example, if a connection is terminated,\nNimBLE lets you know about it with a call to that connection's callback.\n\n\nIn the \nadvertising section\n of this tutorial, we saw how the\napplication specifies a GAP event callback when it begins advertising. NimBLE\nuses this callback to notify the application that a central has connected to\nyour peripheral after receiving an advertisement. Let's revisit how \nbleprph\n specifies its connection callback when advertising:\n\n\n\n\n \n/* Begin advertising. */\n\n \nmemset\n(\nadv_params\n, \n0\n, \nsizeof\n \nadv_params\n);\n \nadv_params\n.\nconn_mode\n \n=\n \nBLE_GAP_CONN_MODE_UND\n;\n \nadv_params\n.\ndisc_mode\n \n=\n \nBLE_GAP_DISC_MODE_GEN\n;\n \nrc\n \n=\n \nble_gap_adv_start\n(\nBLE_ADDR_TYPE_PUBLIC\n, \n0\n, \nNULL\n, \nBLE_HS_FOREVER\n,\n \nadv_params\n, \nbleprph_gap_event\n, \nNULL\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nBLEPRPH_LOG\n(\nERROR\n, \nerror enabling advertisement; rc=%d\\n\n, \nrc\n);\n \nreturn\n;\n }\n\n\n\n\n\n\n\nbleprph_gap_event()\n\n\nThe \nbleprph_gap_event()\n function is \nbleprph\n's GAP event callback; NimBLE\ncalls this function when the advertising operation leads to connection\nestablishment. Upon connection establishment, this callback becomes\npermanently associated with the connection; all subsequent events related to\nthis connection are communicated through this callback.\n\n\nNow let's look at the function that \nbleprph\n uses for all its connection\ncallbacks: \nbleprph_gap_event()\n.\n\n\n/**\n\n\n * The nimble host executes this callback when a GAP event occurs. The\n\n\n * application associates a GAP event callback with each connection that forms.\n\n\n * bleprph uses the same callback for all connections.\n\n\n *\n\n\n * @param event The type of event being signalled.\n\n\n * @param ctxt Various information pertaining to the event.\n\n\n * @param arg Application-specified argument; unuesd by\n\n\n * bleprph.\n\n\n *\n\n\n * @return 0 if the application successfully handled the\n\n\n * event; nonzero on failure. The semantics\n\n\n * of the return code is specific to the\n\n\n * particular GAP event being signalled.\n\n\n */\n\n\nstatic\n \nint\n\n\nbleprph_gap_event\n(\nstruct\n \nble_gap_event\n \n*event\n, \nvoid\n \n*arg\n)\n{\n \nstruct\n \nble_gap_conn_desc\n \ndesc\n;\n \nint\n \nrc\n;\n\n \nswitch\n (\nevent-\ntype\n) {\n \ncase\n \nBLE_GAP_EVENT_CONNECT\n:\n \n/* A new connection was established or a connection attempt failed. */\n\n \nBLEPRPH_LOG\n(\nINFO\n, \nconnection %s; status=%d \n,\n \nevent-\nconnect\n.\nstatus\n \n==\n \n0\n \n?\n \nestablished\n \n:\n \nfailed\n,\n \nevent-\nconnect\n.\nstatus\n);\n \nif\n (\nevent-\nconnect\n.\nstatus\n \n==\n \n0\n) {\n \nrc\n \n=\n \nble_gap_conn_find\n(\nevent-\nconnect\n.\nconn_handle\n, \ndesc\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nbleprph_print_conn_desc\n(\ndesc\n);\n }\n \nBLEPRPH_LOG\n(\nINFO\n, \n\\n\n);\n\n \nif\n (\nevent-\nconnect\n.\nstatus\n \n!=\n \n0\n) {\n \n/* Connection failed; resume advertising. */\n\n \nbleprph_advertise\n();\n }\n \nreturn\n \n0\n;\n\n \ncase\n \nBLE_GAP_EVENT_DISCONNECT\n:\n \nBLEPRPH_LOG\n(\nINFO\n, \ndisconnect; reason=%d \n, \nevent-\ndisconnect\n.\nreason\n);\n \nbleprph_print_conn_desc\n(\nevent-\ndisconnect\n.\nconn\n);\n \nBLEPRPH_LOG\n(\nINFO\n, \n\\n\n);\n\n \n/* Connection terminated; resume advertising. */\n\n \nbleprph_advertise\n();\n \nreturn\n \n0\n;\n\n \ncase\n \nBLE_GAP_EVENT_CONN_UPDATE\n:\n \n/* The central has updated the connection parameters. */\n\n \nBLEPRPH_LOG\n(\nINFO\n, \nconnection updated; status=%d \n,\n \nevent-\nconn_update\n.\nstatus\n);\n \nrc\n \n=\n \nble_gap_conn_find\n(\nevent-\nconnect\n.\nconn_handle\n, \ndesc\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nbleprph_print_conn_desc\n(\ndesc\n);\n \nBLEPRPH_LOG\n(\nINFO\n, \n\\n\n);\n \nreturn\n \n0\n;\n\n \ncase\n \nBLE_GAP_EVENT_ENC_CHANGE\n:\n \n/* Encryption has been enabled or disabled for this connection. */\n\n \nBLEPRPH_LOG\n(\nINFO\n, \nencryption change event; status=%d \n,\n \nevent-\nenc_change\n.\nstatus\n);\n \nrc\n \n=\n \nble_gap_conn_find\n(\nevent-\nconnect\n.\nconn_handle\n, \ndesc\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nbleprph_print_conn_desc\n(\ndesc\n);\n \nBLEPRPH_LOG\n(\nINFO\n, \n\\n\n);\n \nreturn\n \n0\n;\n\n \ncase\n \nBLE_GAP_EVENT_SUBSCRIBE\n:\n \nBLEPRPH_LOG\n(\nINFO\n, \nsubscribe event; conn_handle=%d attr_handle=%d \n\n \nreason=%d prevn=%d curn=%d previ=%d curi=%d\\n\n,\n \nevent-\nsubscribe\n.\nconn_handle\n,\n \nevent-\nsubscribe\n.\nattr_handle\n,\n \nevent-\nsubscribe\n.\nreason\n,\n \nevent-\nsubscribe\n.\nprev_notify\n,\n \nevent-\nsubscribe\n.\ncur_notify\n,\n \nevent-\nsubscribe\n.\nprev_indicate\n,\n \nevent-\nsubscribe\n.\ncur_indicate\n);\n \nreturn\n \n0\n;\n }\n\n \nreturn\n \n0\n;\n}\n\n\n\n\n\n\n\nConnection callbacks are used to communicate a variety of events related to a\nconnection. An application determines the type of event that occurred by\ninspecting the value of the \nevent-\ntype\n parameter. The full list of event\ncodes can be found on the \nGAP events\n page.\n\n\nGuarantees\n\n\nIt is important to know what your application code is allowed to do from within\na connection callback.\n\n\nNo restrictions on NimBLE operations\n\n\nYour app is free to make calls into the NimBLE stack from within a connection\ncallback. \nbleprph\n takes advantage of this freedom when it resumes\nadvertising upon connection termination. All other NimBLE operations are also\nallowed (service discovery, pairing initiation, etc).\n\n\nAll context data is transient\n\n\nPointers in the context object point to data living on the stack. Your\ncallback is free to read (or write, if appropriate) through these pointers, but\nyou should not store these pointers for later use. If your application needs\nto retain some data from a context object, it needs to make a copy.",
- "title": "GAP Event Callbacks"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-gap-event/#ble-peripheral-project",
- "text": "",
- "title": "BLE Peripheral Project"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-gap-event/#gap-event-callbacks",
- "text": "",
- "title": "GAP Event callbacks"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-gap-event/#overview",
- "text": "Every BLE connection has a GAP event callback associated with it. A\nGAP event callback is a bit of application code which NimBLE uses to inform\nyou of connection-related events. For example, if a connection is terminated,\nNimBLE lets you know about it with a call to that connection's callback. In the advertising section of this tutorial, we saw how the\napplication specifies a GAP event callback when it begins advertising. NimBLE\nuses this callback to notify the application that a central has connected to\nyour peripheral after receiving an advertisement. Let's revisit how bleprph specifies its connection callback when advertising: /* Begin advertising. */ \n memset ( adv_params , 0 , sizeof adv_params );\n adv_params . conn_mode = BLE_GAP_CONN_MODE_UND ;\n adv_params . disc_mode = BLE_GAP_DISC_MODE_GEN ;\n rc = ble_gap_adv_start ( BLE_ADDR_TYPE_PUBLIC , 0 , NULL , BLE_HS_FOREVER ,\n adv_params , bleprph_gap_event , NULL );\n if ( rc != 0 ) {\n BLEPRPH_LOG ( ERROR , error enabling advertisement; rc=%d\\n , rc );\n return ;\n }",
- "title": "Overview"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-gap-event/#bleprph_gap_event",
- "text": "The bleprph_gap_event() function is bleprph 's GAP event callback; NimBLE\ncalls this function when the advertising operation leads to connection\nestablishment. Upon connection establishment, this callback becomes\npermanently associated with the connection; all subsequent events related to\nthis connection are communicated through this callback. Now let's look at the function that bleprph uses for all its connection\ncallbacks: bleprph_gap_event() . /** * The nimble host executes this callback when a GAP event occurs. The * application associates a GAP event callback with each connection that forms. * bleprph uses the same callback for all connections. * * @param event The type of event being signalled. * @param ctxt Various information pertaining to the event. * @param arg Application-specified argument; unuesd by * bleprph. * * @return 0 if the application successfully handled the * event; nonzero on failure. The semantics * of the return code is specific to the * particular GAP event being signalled. */ static int bleprph_gap_event ( struct ble_gap_event *event , void *arg )\n{\n struct ble_gap_conn_desc desc ;\n int rc ;\n\n switch ( event- type ) {\n case BLE_GAP_EVENT_CONNECT :\n /* A new connection was established or a connection attempt failed. */ \n BLEPRPH_LOG ( INFO , connection %s; status=%d ,\n event- connect . status == 0 ? established : failed ,\n event- connect . status );\n if ( event- connect . status == 0 ) {\n rc = ble_gap_conn_find ( event- connect . conn_handle , desc );\n assert ( rc == 0 );\n bleprph_print_conn_desc ( desc );\n }\n BLEPRPH_LOG ( INFO , \\n );\n\n if ( event- connect . status != 0 ) {\n /* Connection failed; resume advertising. */ \n bleprph_advertise ();\n }\n return 0 ;\n\n case BLE_GAP_EVENT_DISCONNECT :\n BLEPRPH_LOG ( INFO , disconnect; reason=%d , event- disconnect . reason );\n bleprph_print_conn_desc ( event- disconnect . conn );\n BLEPRPH_LOG ( INFO , \\n );\n\n /* Connection terminated; resume advertising. */ \n bleprph_advertise ();\n return 0 ;\n\n case BLE_GAP_EVENT_CONN_UPDATE :\n /* The central has updated the connection parameters. */ \n BLEPRPH_LOG ( INFO , connection updated; status=%d ,\n event- conn_update . status );\n rc = ble_gap_conn_find ( event- connect . conn_handle , desc );\n assert ( rc == 0 );\n bleprph_print_conn_desc ( desc );\n BLEPRPH_LOG ( INFO , \\n );\n return 0 ;\n\n case BLE_GAP_EVENT_ENC_CHANGE :\n /* Encryption has been enabled or disabled for this connection. */ \n BLEPRPH_LOG ( INFO , encryption change event; status=%d ,\n event- enc_change . status );\n rc = ble_gap_conn_find ( event- connect . conn_handle , desc );\n assert ( rc == 0 );\n bleprph_print_conn_desc ( desc );\n BLEPRPH_LOG ( INFO , \\n );\n return 0 ;\n\n case BLE_GAP_EVENT_SUBSCRIBE :\n BLEPRPH_LOG ( INFO , subscribe event; conn_handle=%d attr_handle=%d \n reason=%d prevn=%d curn=%d previ=%d curi=%d\\n ,\n event- subscribe . conn_handle ,\n event- subscribe . attr_handle ,\n event- subscribe . reason ,\n event- subscribe . prev_notify ,\n event- subscribe . cur_notify ,\n event- subscribe . prev_indicate ,\n event- subscribe . cur_indicate );\n return 0 ;\n }\n\n return 0 ;\n} Connection callbacks are used to communicate a variety of events related to a\nconnection. An application determines the type of event that occurred by\ninspecting the value of the event- type parameter. The full list of event\ncodes can be found on the GAP events page.",
- "title": "bleprph_gap_event()"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-gap-event/#guarantees",
- "text": "It is important to know what your application code is allowed to do from within\na connection callback. No restrictions on NimBLE operations Your app is free to make calls into the NimBLE stack from within a connection\ncallback. bleprph takes advantage of this freedom when it resumes\nadvertising upon connection termination. All other NimBLE operations are also\nallowed (service discovery, pairing initiation, etc). All context data is transient Pointers in the context object point to data living on the stack. Your\ncallback is free to read (or write, if appropriate) through these pointers, but\nyou should not store these pointers for later use. If your application needs\nto retain some data from a context object, it needs to make a copy.",
- "title": "Guarantees"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-app/",
- "text": "BLE Peripheral Project\n\n\nOverview\n\n\n\n\nNow that we've gone through how BLE Apps are contructed, how they function, and how all the parts fit together\nlet's try out a BLE Peripheral App to see how it all works.\n\n\n\n\nPrerequisites\n\n\n\n\n\n\nYou should already have completed the previous \nBLE Tiny Project\n, though it's not required.\n\n\nYou should have a BLE Central App of some sort to connect with. On Mac OS or iOS, you can use \nLightBlue\n\nwhich is a free app to browse and connect to BLE Peripheral devices. \n\n\n\n\n\n\nCreate a New Target\n\n\nYou can create a new project instead, but this tutorial will simply use the previously created bletiny project and add a new target for the BLE Peripheral\n\n\n$ newt target create myperiph\nTarget targets/myperiph successfully created\n$ newt target set myperiph bsp=@apache-mynewt-core/hw/bsp/nrf52dk\nTarget targets/myperiph successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set myperiph app=@apache-mynewt-core/apps/bleprph\nTarget targets/myperiph successfully set target.app to @apache-mynewt-core/apps/bleprph\n$ newt target set myperiph build_profile=optimized\nTarget targets/myperiph successfully set target.build_profile to optimized\n$ newt build myperiph\nBuilding target targets/myperiph\n...\nLinking ~/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.elf\nTarget successfully built: targets/myperiph\n$ newt create-image myperiph 1.0.0\nApp image succesfully generated: ~/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.img\n$ newt load myperiph\nLoading app image into slot 1\n\n\n\n\n\nNow if you reset the board, and fire up your BLE Central App, you should see a new peripheral device called 'nimble-bleprph'.\n\n\n\n\n\n\n\n\nNow that you can see the device, you can begin to interact with the advertised service. \n\n\nClick on the device and you'll establish a connection.\n\n\n\n\n\n\n\n\nNow that you're connected, you can see the Services that are being advertised.\n\n\nScroll to the bottom and you will see a Read Characteristic, and a Read/Write Characteristic.\n\n\n\n\n\n\nJust click on the Read Write Characteristic and you will see the existing value.\n\n\n\n\n\n\nType in a new value.\n\n\n\n\n\n\nAnd you will see the new value reflected.\n\n\n\n\n\n\nIf you still have your console connected, you will be able to see the connection requests, and pairing,\nhappen on the device as well.\n\n\n\n\n258894:[ts=2022609336ssb, mod=64 level=1] connection established; status=0 handle=1 our_ota_addr_type=0 our_ota_addr=0a:0a:0a:0a:0a:0a our_id_addr_type=0 our_id_addr=0a:0a:0a:0a:0a:0a peer_ota_addr_type=1 peer_ota_addr=7f:be:d4:44:c0:d4 peer_id_addr_type=1 peer_id_addr=7f:be:d4:44:c0:d4 conn_itvl=24 conn_latency=0 supervision_timeout=72 encrypted=0 authenticated=0 bonded=0\n\n258904:[ts=2022687456ssb, mod=64 level=1]\n258917:[ts=2022789012ssb, mod=64 level=1] mtu update event; conn_handle=1 cid=4 mtu=185\n258925:[ts=2022851508ssb, mod=64 level=1] subscribe event; conn_handle=1 attr_handle=14 reason=1 prevn=0 curn=0 previ=0 curi=1\n261486:[ts=2042859320ssb, mod=64 level=1] encryption change event; status=0 handle=1 our_ota_addr_type=0 our_ota_addr=0a:0a:0a:0a:0a:0a our_id_addr_type=0 our_id_addr=0a:0a:0a:0a:0a:0a peer_ota_addr_type=1 peer_ota_addr=7f:be:d4:44:c0:d4 peer_id_addr_type=1 peer_id_addr=7f:be:d4:44:c0:d4 conn_itvl=24 conn_latency=0 supervision_timeout=72 encrypted=1 authenticated=0 bonded=1\n261496:[ts=2042937440ssb, mod=64 level=1]\n\n\n\n\n\n\n\nCongratulations! You've just built and connected your first BLE Peripheral device!",
- "title": "BLE Peripheral App"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-app/#ble-peripheral-project",
- "text": "",
- "title": "BLE Peripheral Project"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-app/#overview",
- "text": "Now that we've gone through how BLE Apps are contructed, how they function, and how all the parts fit together\nlet's try out a BLE Peripheral App to see how it all works.",
- "title": "Overview"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-app/#prerequisites",
- "text": "You should already have completed the previous BLE Tiny Project , though it's not required. You should have a BLE Central App of some sort to connect with. On Mac OS or iOS, you can use LightBlue \nwhich is a free app to browse and connect to BLE Peripheral devices.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/bleprph/bleprph-app/#create-a-new-target",
- "text": "You can create a new project instead, but this tutorial will simply use the previously created bletiny project and add a new target for the BLE Peripheral $ newt target create myperiph\nTarget targets/myperiph successfully created\n$ newt target set myperiph bsp=@apache-mynewt-core/hw/bsp/nrf52dk\nTarget targets/myperiph successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set myperiph app=@apache-mynewt-core/apps/bleprph\nTarget targets/myperiph successfully set target.app to @apache-mynewt-core/apps/bleprph\n$ newt target set myperiph build_profile=optimized\nTarget targets/myperiph successfully set target.build_profile to optimized\n$ newt build myperiph\nBuilding target targets/myperiph\n...\nLinking ~/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.elf\nTarget successfully built: targets/myperiph\n$ newt create-image myperiph 1.0.0\nApp image succesfully generated: ~/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.img\n$ newt load myperiph\nLoading app image into slot 1 Now if you reset the board, and fire up your BLE Central App, you should see a new peripheral device called 'nimble-bleprph'. Now that you can see the device, you can begin to interact with the advertised service. Click on the device and you'll establish a connection. Now that you're connected, you can see the Services that are being advertised. Scroll to the bottom and you will see a Read Characteristic, and a Read/Write Characteristic. Just click on the Read Write Characteristic and you will see the existing value. Type in a new value. And you will see the new value reflected. If you still have your console connected, you will be able to see the connection requests, and pairing,\nhappen on the device as well. 258894:[ts=2022609336ssb, mod=64 level=1] connection established; status=0 handle=1 our_ota_addr_type=0 our_ota_addr=0a:0a:0a:0a:0a:0a our_id_addr_type=0 our_id_addr=0a:0a:0a:0a:0a:0a peer_ota_addr_type=1 peer_ota_addr=7f:be:d4:44:c0:d4 peer_id_addr_type=1 peer_id_addr=7f:be:d4:44:c0:d4 conn_itvl=24 conn_latency=0 supervision_timeout=72 encrypted=0 authenticated=0 bonded=0 258904:[ts=2022687456ssb, mod=64 level=1]\n258917:[ts=2022789012ssb, mod=64 level=1] mtu update event; conn_handle=1 cid=4 mtu=185\n258925:[ts=2022851508ssb, mod=64 level=1] subscribe event; conn_handle=1 attr_handle=14 reason=1 prevn=0 curn=0 previ=0 curi=1\n261486:[ts=2042859320ssb, mod=64 level=1] encryption change event; status=0 handle=1 our_ota_addr_type=0 our_ota_addr=0a:0a:0a:0a:0a:0a our_id_addr_type=0 our_id_addr=0a:0a:0a:0a:0a:0a peer_ota_addr_type=1 peer_ota_addr=7f:be:d4:44:c0:d4 peer_id_addr_type=1 peer_id_addr=7f:be:d4:44:c0:d4 conn_itvl=24 conn_latency=0 supervision_timeout=72 encrypted=1 authenticated=0 bonded=1\n261496:[ts=2042937440ssb, mod=64 level=1] Congratulations! You've just built and connected your first BLE Peripheral device!",
- "title": "Create a New Target"
- },
- {
- "location": "/os/tutorials/blehci_project/",
- "text": "Use HCI access to NimBLE controller\n\n\n\n\nThis tutorial explains how to use the example application \nblehci\n included in the NimBLE stack to talk to the Mynewt NimBLE controller via the Host Controller Interface. You may build the Mynewt image using a laptop running any OS of your choice - Mac, Linux, or Windows.\n\n\nThe host used in this specific example is the BlueZ Bluetooth stack. Since BlueZ is a Bluetooth stack for Linux kernel-based family of operating system, the tutorial expects a computer running Linux OS and with BlueZ installed to talk to the board with the Mynewt image.\n\n\n\n\nPrerequisites\n\n\nEnsure that you meet the following prerequisites before continuing with one of the tutorials.\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a board with BLE radio that is supported by Mynewt. We will use an nRF52 Dev board in this tutorial.\n\n\nHave a USB TTL Serial Cable that supports hardware flow control such as ones found at \nhttp://www.ftdichip.com/Products/Cables/USBTTLSerial.htm\n to establish a serial USB connection between the board and the laptop.\n\n\nInstall the newt tool and toolchains (See \nBasic Setup\n).\n\n\nInstall a BLE host such as BlueZ on a Linux machine to talk to the nrf52 board running Mynewt. Use \nsudo apt-get install bluez\n to install it on your Linux machine. \n\n\n\n\n\n\nCreate a project\n\n\nUse the newt tool to create a new project directory containing a skeletal Mynewt framework. Change into the newly created directory. \n\n\n$ newt new blehciproj \nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in blehciproj ...\nProject blehciproj successfully created.\n$ cd mblehciproj \n\n$ newt install\napache-mynewt-core\n\n\n\n\n\n\n\nCreate targets\n\n\nYou will create two targets - one for the bootloader, the other for the application. Then you will add the definitions for them. Note that you are using the example app \nblehci\n for the application target. Set the bsp correctly (nrf52pdk or nrf52dk depending on whether the board is the preview kit or the dev kit, respectively).\n\n\n$ newt target create nrf52_boot\n$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot\n$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_boot build_profile=optimized\n\n\n\n\n\n$ newt target create myble2\n$ newt target set myble2 bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set myble2 app=@apache-mynewt-core/apps/blehci\n$ newt target set myble2 build_profile=optimized\n\n\n\n\n\n\n\nCheck that the targets are defined correctly.\n\n\n$ newt target show\n targets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n targets/myble2\n app=@apache-mynewt-core/apps/blehci\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n targets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\n\n\nBuild targets\n\n\nThen build the two targets.\n\n\n$ newt build nrf52_boot\n\nsnip\n\nLinking ~/dev/blehciproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot\n\n$ newt build myble2\n\nsnip\n\nLinking ~/dev/blehciproj/bin/targets/myble2/app/apps/blehci/blehci.elf\nTarget successfully built: targets/myble2\n$\n\n\n\n\n\n\n\nCreate the app image\n\n\nGenerate a signed application image for the \nmyble2\n target. The version number is arbitrary.\n\n\n$ newt create-image myble2 1.0.0\nApp image succesfully generated: ~/dev/blehciproj/bin/targets/myble2/app/apps/bletiny/bletiny.img\n\n\n\n\n\n\n\nLoad the bootloader and the application image\n\n\nMake 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.\n\n\nLoad the bootloader:\n\n\n$ newt load nrf52_boot\nLoading bootloader\n$\n\n\n\n\n\n\nLoad the application image:\n\n\n$ newt load myble2\nLoading app image into slot 1\n$\n\n\n\n\n\n\n\nEstablish serial connection\n\n\nAttach a serial port to your board by connecting the USB TTL Serial Cable. This should create /dev/ttyUSB0 (or similar) on your machine. \n\n\nNote\n Certain Linux OS versions have been observed to detect the nrf52 board as a mass storage device and the console access doesn\u2019t work properly. In that case try powering the nrf52 board from your monitor or something other than your Linux computer/laptop when you set up the serial port for HCI communication.\n\n\n\n\nOpen Bluetooth monitor btmon\n\n\nbtmon\n is a BlueZ test tool to display all HCI commands and events in a human readable format. Start the btmon tool in a terminal window. \n\n\n$ sudo btmon\n[sudo] password for admin: \nBluetooth monitor ver 5.37\n\n\n\n\n\n\n\nAttach the blehci device to BlueZ\n\n\nIn a different terminal, attach the blehci device to the BlueZ daemon (substitute the correct /dev filename for ttyUSB0).\n\n\n$ sudo btattach -B /dev/ttyUSB0 -S 1000000\nAttaching BR/EDR controller to /dev/ttyUSB0\nSwitched line discipline from 0 to 15\nDevice index 1 attached\n\n\n\n\n\nThe baud rate used to connect to the controller may be changed by overriding the default value of 1000000 in the \nnet/nimble/transport/uart/syscfg.yml\n. Settings in the serial transport \nsyscfg.yml\n file can be overridden by a higher priority package such as the application. So, for example, you may set the \nBLE_HCI_UART_BAUD\n to a different value in \napps/blehci/syscfg.yml\n.\n\n\nIf there is no CTS/RTS lines present in the test environment, flow control should be turned off. This can be done with\n-N option for btattach. \nNote:\n -N option came with BlueZ ver 5.44.\n\n\n\n\nStart btmgmt to send commands\n\n\nIn a third terminal, start btmgmt. This tool allows you to send commands to the blehci controller. Use the index number that shows up when you \nbtattach\n in the previous step.\n\n\n$ sudo btmgmt --index 1\n[sudo] password for admin: \n\n\n\n\n\nSet your device address (you can substitute any static random address here).\n\n\n[hci1]# static-addr cc:11:11:11:11:11\nStatic address successfully set\n\n\n\n\n\nInitialize the controller.\n\n\n[hci1]# power on\nhci1 Set Powered complete, settings: powered le static-addr \n\n\n\n\n\nBegin scanning.\n\n\n[hci1]# find -l\nDiscovery started\nhci1 type 6 discovering on\nhci1 dev_found: 58:EF:77:C8:8D:17 type LE Random rssi -78 flags 0x0000 \nAD flags 0x06 \neir_len 23\n\nsnip",
- "title": "BLE HCI interface"
- },
- {
- "location": "/os/tutorials/blehci_project/#use-hci-access-to-nimble-controller",
- "text": "This tutorial explains how to use the example application blehci included in the NimBLE stack to talk to the Mynewt NimBLE controller via the Host Controller Interface. You may build the Mynewt image using a laptop running any OS of your choice - Mac, Linux, or Windows. The host used in this specific example is the BlueZ Bluetooth stack. Since BlueZ is a Bluetooth stack for Linux kernel-based family of operating system, the tutorial expects a computer running Linux OS and with BlueZ installed to talk to the board with the Mynewt image.",
- "title": "Use HCI access to NimBLE controller"
- },
- {
- "location": "/os/tutorials/blehci_project/#prerequisites",
- "text": "Ensure that you meet the following prerequisites before continuing with one of the tutorials. Have Internet connectivity to fetch remote Mynewt components. Have a board with BLE radio that is supported by Mynewt. We will use an nRF52 Dev board in this tutorial. Have a USB TTL Serial Cable that supports hardware flow control such as ones found at http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm to establish a serial USB connection between the board and the laptop. Install the newt tool and toolchains (See Basic Setup ). Install a BLE host such as BlueZ on a Linux machine to talk to the nrf52 board running Mynewt. Use sudo apt-get install bluez to install it on your Linux machine.",
- "title": "Prerequisites"
- },
- {
- "location": "/os/tutorials/blehci_project/#create-a-project",
- "text": "Use the newt tool to create a new project directory containing a skeletal Mynewt framework. Change into the newly created directory. $ newt new blehciproj \nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in blehciproj ...\nProject blehciproj successfully created.\n$ cd mblehciproj \n\n$ newt install\napache-mynewt-core",
- "title": "Create a project"
- },
- {
- "location": "/os/tutorials/blehci_project/#create-targets",
- "text": "You will create two targets - one for the bootloader, the other for the application. Then you will add the definitions for them. Note that you are using the example app blehci for the application target. Set the bsp correctly (nrf52pdk or nrf52dk depending on whether the board is the preview kit or the dev kit, respectively). $ newt target create nrf52_boot\n$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot\n$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_boot build_profile=optimized $ newt target create myble2\n$ newt target set myble2 bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set myble2 app=@apache-mynewt-core/apps/blehci\n$ newt target set myble2 build_profile=optimized Check that the targets are defined correctly. $ newt target show\n targets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n targets/myble2\n app=@apache-mynewt-core/apps/blehci\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n targets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized",
- "title": "Create targets"
- },
- {
- "location": "/os/tutorials/blehci_project/#build-targets",
- "text": "Then build the two targets. $ newt build nrf52_boot snip \nLinking ~/dev/blehciproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf\nTarget successfully built: targets/nrf52_boot\n\n$ newt build myble2 snip \nLinking ~/dev/blehciproj/bin/targets/myble2/app/apps/blehci/blehci.elf\nTarget successfully built: targets/myble2\n$",
- "title": "Build targets"
- },
- {
- "location": "/os/tutorials/blehci_project/#create-the-app-image",
- "text": "Generate a signed application image for the myble2 target. The version number is arbitrary. $ newt create-image myble2 1.0.0\nApp image succesfully generated: ~/dev/blehciproj/bin/targets/myble2/app/apps/bletiny/bletiny.img",
- "title": "Create the app image"
- },
- {
- "location": "/os/tutorials/blehci_project/#load-the-bootloader-and-the-application-image",
- "text": "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. Load the bootloader: $ newt load nrf52_boot\nLoading bootloader\n$ \nLoad the application image: $ newt load myble2\nLoading app image into slot 1\n$",
- "title": "Load the bootloader and the application image"
- },
- {
- "location": "/os/tutorials/blehci_project/#establish-serial-connection",
- "text": "Attach a serial port to your board by connecting the USB TTL Serial Cable. This should create /dev/ttyUSB0 (or similar) on your machine. Note Certain Linux OS versions have been observed to detect the nrf52 board as a mass storage device and the console access doesn\u2019t work properly. In that case try powering the nrf52 board from your monitor or something other than your Linux computer/laptop when you set up the serial port for HCI communication.",
- "title": "Establish serial connection"
- },
- {
- "location": "/os/tutorials/blehci_project/#open-bluetooth-monitor-btmon",
- "text": "btmon is a BlueZ test tool to display all HCI commands and events in a human readable format. Start the btmon tool in a terminal window. $ sudo btmon\n[sudo] password for admin: \nBluetooth monitor ver 5.37",
- "title": "Open Bluetooth monitor btmon"
- },
- {
- "location": "/os/tutorials/blehci_project/#attach-the-blehci-device-to-bluez",
- "text": "In a different terminal, attach the blehci device to the BlueZ daemon (substitute the correct /dev filename for ttyUSB0). $ sudo btattach -B /dev/ttyUSB0 -S 1000000\nAttaching BR/EDR controller to /dev/ttyUSB0\nSwitched line discipline from 0 to 15\nDevice index 1 attached The baud rate used to connect to the controller may be changed by overriding the default value of 1000000 in the net/nimble/transport/uart/syscfg.yml . Settings in the serial transport syscfg.yml file can be overridden by a higher priority package such as the application. So, for example, you may set the BLE_HCI_UART_BAUD to a different value in apps/blehci/syscfg.yml . If there is no CTS/RTS lines present in the test environment, flow control should be turned off. This can be done with\n-N option for btattach. Note: -N option came with BlueZ ver 5.44.",
- "title": "Attach the blehci device to BlueZ"
- },
- {
- "location": "/os/tutorials/blehci_project/#start-btmgmt-to-send-commands",
- "text": "In a third terminal, start btmgmt. This tool allows you to send commands to the blehci controller. Use the index number that shows up when you btattach in the previous step. $ sudo btmgmt --index 1\n[sudo] password for admin: Set your device address (you can substitute any static random address here). [hci1]# static-addr cc:11:11:11:11:11\nStatic address successfully set Initialize the controller. [hci1]# power on\nhci1 Set Powered complete, settings: powered le static-addr Begin scanning. [hci1]# find -l\nDiscovery started\nhci1 type 6 discovering on\nhci1 dev_found: 58:EF:77:C8:8D:17 type LE Random rssi -78 flags 0x0000 \nAD flags 0x06 \neir_len 23 snip",
- "title": "Start btmgmt to send commands"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/",
- "text": "Air quality sensor project\n\n\nSetting up source tree for stuff you need\n\n\nTo start with, you need to create a new project under which you will do this development. So you type in:\n\n\n $ mkdir $HOME/src\n $ cd $HOME/src\n $ newt new air_quality\n\n\n\n\n\nLet's say you are using Arduino Primo -- which is based on the Nordic Semi NRF52 chip -- as the platform. \nYou know you need the board support package for that hardware. You can look up its location, add it your \nproject, and fetch that along with the core OS components. Luckily, the Arduino Primo is supported in the \nMynewt Core, so there's nothing much to do here. \n\n\nYour project.yml file should look like this:\n\n\n [user@IsMyLaptop:~/src/air_quality]$ emacs project.yml \n\n [user@IsMyLaptop:~/src/air_quality]$ cat project.yml\n project.name: \nair_quality\n\n\n project.repositories:\n - apache-mynewt-core\n\n # Use github\ns distribution mechanism for core ASF libraries.\n # This provides mirroring automatically for us.\n #\n repository.apache-mynewt-core:\n type: github\n vers: 0-latest\n user: apache\n repo: incubator-mynewt-core\n\n [user@IsMyLaptop:~/src/air_quality]$ newt install\n apache-mynewt-core\n [user@IsMyLaptop:~/src/air_quality]$ ls repos/\n apache-mynewt-core\n\n\n\n\n\nGood. You want to make sure you have all the needed bits for supporting your board; \nso you decide to build the blinky project for the platform first.\n\n\nNow create a target for it and build it. Easiest way to proceed is to copy the existing target for blinky, and modify it to build for Arduino Primo board.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ newt target copy my_blinky_sim blink_primo\nTarget successfully copied; targets/my_blinky_sim --\n targets/blink_primo\n[user@IsMyLaptop:~/src/air_quality]$ newt target set blink_primo bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\nTarget targets/blink_nrf successfully set target.bsp to @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n[user@IsMyLaptop:~/src/air_quality]$ newt build blink_primo\nCompiling hal_bsp.c\n...\nLinking blinky.elf\nApp successfully built: /Users/user/src/air_quality/bin/blink_primo/apps/blinky/blinky.elf\n\n\n\n\n\nGood.\n\n\nYou know that this platform uses bootloader, which means you have to create a target for that too.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ newt target create boot_primo\nTarget targets/boot_nrf successfully created\n[user@IsMyLaptop:~/src/air_quality]$ newt target show\n@apache-mynewt-core/targets/unittest\n bsp=hw/bsp/native\n build_profile=debug\n compiler=compiler/sim\ntargets/blink_primo\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n build_profile=debug\ntargets/boot_primo\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n[user@IsMyLaptop:~/src/air_quality]$ newt target set boot_nrf bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\nTarget targets/boot_nrf successfully set target.bsp to @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n[user@IsMyLaptop:~/src/air_quality]$ newt target set boot_nrf app=@apache-mynewt-core/apps/boot\nTarget targets/boot_nrf successfully set target.app to @apache-mynewt-core/apps/boot\n[user@IsMyLaptop:~/src/air_quality]$ newt target set boot_nrf build_profile=optimized\nTarget targets/boot_nrf successfully set target.build_profile to optimized\n\n\n\n\n\nAnd then build it, and load it onto the board.\n\n\nnewt build boot_primo\n....\nLinking boot.elf\nApp successfully built: /Users/user/src/air_quality/bin/boot_primo/apps/boot/boot.elf\n[user@IsMyLaptop:~/src/air_quality]\n$ newt load boot_primo\n\n\n\n\n\nAt this point, you may (or may not) see a bunch of error messages about not being able to connect to\nyour board, not being able to load the image, etc. If that's the case, and you haven't already, you\nshould most definitely go worth through the \nblinky_primo\n tutorial so that you\ncan properly communicate with your board.\n\n\nNext you must download the targets to board, and see that the LED actually blinks. You plug in the \nArduino Primo board to your laptop, and say:\n\n\n[user@IsMyLaptop:~/src/air_quality]$ newt load blink_primo\nLoading app image into slot 1\nError: couldn\nt open /Users/user/src/air_quality/bin/blink_primo/apps/blinky/blinky.img\n\nError: exit status 1\n\nload - Load app image to target for \ntarget-name\n.\n\nUsage:\n newt load [flags]\n\nExamples:\n newt load \ntarget-name\n\n\n\nGlobal Flags:\n -l, --loglevel string Log level, defaults to WARN. (default \nWARN\n)\n -o, --outfile string Filename to tee log output to\n -q, --quiet Be quiet; only display error output.\n -s, --silent Be silent; don\nt output anything.\n -v, --verbose Enable verbose output when executing commands.\nexit status 1\n\n\n\n\n\nAh. Forgot to create an image out of the blinky binary. Note that every time you want to build and \nload a new firmware image to a target board, you need to run 'create-image' on it.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ newt create-image blink_primo 0.0.1\nApp image successfully generated: /Users/user/src/air_quality/bin/blink_primo/apps/blinky/blinky.img\nBuild manifest: /Users/user/src/air_quality/bin/blink_nrf/apps/blinky/manifest.json\n[user@IsMyLaptop:~/src/air_quality]$ newt load blink_primo\n\n\n\n\n\nAnd it's blinking.\n\n\nShortcut for doing build/create-image/load/debug steps all in one is 'newt run' command. Check \nout the usage from command line help.\n\n\nCreate test project\n\n\nNow that you have your system setup, you can start creating your own stuff.\nFirst you want to create a project for yourself - you could start by using blinky as a project \ntemplate, but since we're going to want to be able to access the data via Bluetooth, let's \nuse the \nbleprph\n Bluetooth Peripheral project instead.\n\n\n [user@IsMyLaptop:~/src/air_quality]$ mkdir apps/air_quality\n [user@IsMyLaptop:~/src/air_quality]$ cp repos/apache-mynewt-core/apps/bleprph/pkg.yml apps/air_quality/\n [user@IsMyLaptop:~/src/air_quality]$ cp -Rp repos/apache-mynewt-core/apps/bleprph/src apps/air_quality/\n\n\n\n\n\nThen you modify the apps/air_quality/pkg.yml for air_quality in order to change the \npkg.name\n to be \napps/air_quality\n.\nYou'll need to add the \n@apache-mynewt-core/\n path to all the package dependencies, since the app no longer\nresides within the apache-mynewt-core repository.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ cat apps/air_quality/pkg.yml\npkg.name: apps/air_quality\npkg.type: app\npkg.description: BLE Air Quality application.\npkg.author: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps: \n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/sys/shell\n\n - \n@apache-mynewt-core/sys/stats/full\n\n - \n@apache-mynewt-core/sys/log/full\n\n - \n@apache-mynewt-core/mgmt/newtmgr\n\n - \n@apache-mynewt-core/mgmt/newtmgr/transport/ble\n\n - \n@apache-mynewt-core/net/nimble/controller\n\n - \n@apache-mynewt-core/net/nimble/host\n\n - \n@apache-mynewt-core/net/nimble/host/services/ans\n\n - \n@apache-mynewt-core/net/nimble/host/services/gap\n\n - \n@apache-mynewt-core/net/nimble/host/services/gatt\n\n - \n@apache-mynewt-core/net/nimble/host/store/ram\n\n - \n@apache-mynewt-core/net/nimble/transport/ram\n\n - \n@apache-mynewt-core/sys/console/full\n\n - \n@apache-mynewt-core/sys/sysinit\n\n - \n@apache-mynewt-core/sys/id\n\n\n\n\n\n\nAnd create a target for it:\n\n\n[user@IsMyLaptop:~/src/air_quality]$ newt target create air_q\nTarget targets/air_q successfully created\n[user@IsMyLaptop:~/src/air_quality]$ newt target set air_q bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\nTarget targets/air_q successfully set target.bsp to @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n[user@IsMyLaptop:~/src/air_quality]$ newt target set air_q app=apps/air_quality \nTarget targets/air_q successfully set target.app to apps/air_quality\n[user@IsMyLaptop:~/src/air_quality]$ newt target set air_q build_profile=debug\nTarget targets/air_q successfully set target.build_profile to debug\n[user@IsMyLaptop:~/src/air_quality]$ newt build air_q\n ....\nLinking /Users/dsimmons/dev/myproj/bin/targets/air_q/app/apps/air_quality/air_quality.elf\nTarget successfully built: targets/air_q\n\n\n\n\n\nCreate packages for drivers\n\n\nOne of the sensors you want to enable is SenseAir K30, which will connect to the board over a serial port.\nTo start development of the driver, you first need to create a package description for it, and add stubs for sources.\n\n\nThe first thing to do is to create the directory structure for your driver:\n\n\n[user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/senseair/include/senseair\n[user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/senseair/src\n\n\n\n\n\nNow you can add the files you need. You'll need a pkg.yml to describe the driver, and then header stub followed by source stub.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/senseair/pkg.yml\n\n\n\n\n\n#\n\n\n# Licensed to the Apache Software Foundation (ASF) under one\n\n\n# or more contributor license agreements. See the NOTICE file\n\n\n# distributed with this work for additional information\n\n\n# regarding copyright ownership. The ASF licenses this file\n\n\n# to you under the Apache License, Version 2.0 (the\n\n\n# \nLicense\n); you may not use this file except in compliance\n\n\n# with the License. You may obtain a copy of the License at\n\n\n# \n\n\n# http:\n//www.apache.org/licenses/LICENSE-2.0\n\n\n#\n\n\n# Unless required by applicable law or agreed to in writing,\n\n\n# software distributed under the License is distributed on an\n\n\n# \nAS IS\n BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n\n\n# KIND, either express or implied. See the License for the\n\n\n# specific language governing permissions and limitations\n\n\n# under the License.\n\n\n#\n\n\npkg\n.\nname\n: \nlibs/my_drivers/senseair\n\n\npkg\n.\ndescription\n: \nHost\n \nside\n \nof\n \nthe\n \nnimble\n \nBluetooth\n \nSmart\n \nstack\n.\n\npkg\n.\nauthor\n: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\n\npkg\n.\nhomepage\n: \nhttp://mynewt.apache.org/\n\n\npkg\n.\nkeywords\n:\n \n-\n \nble\n\n \n-\n \nbluetooth\n\n\n\npkg\n.\ndeps\n:\n \n-\n \n@apache-mynewt-core/kernel/os\n\n\n\n\n\n\n[user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/senseair/include/senseair/senseair.h\n\n\n\n\n\n/*\n\n\n * Licensed to the Apache Software Foundation (ASF) under one\n\n\n * or more contributor license agreements. See the NOTICE file\n\n\n * distributed with this work for additional information\n\n\n * regarding copyright ownership. The ASF licenses this file\n\n\n * to you under the Apache License, Version 2.0 (the\n\n\n * \nLicense\n); you may not use this file except in compliance\n\n\n * with the License. You may obtain a copy of the License at\n\n\n * \n\n\n * http://www.apache.org/licenses/LICENSE-2.0\n\n\n *\n\n\n * Unless required by applicable law or agreed to in writing,\n\n\n * software distributed under the License is distributed on an\n\n\n * \nAS IS\n BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n\n\n * KIND, either express or implied. See the License for the\n\n\n * specific language governing permissions and limitations\n\n\n * under the License.\n\n\n*/\n\n\n#ifndef _SENSEAIR_H_\n\n\n#define _SENSEAIR_H_\n\n\n\nvoid\n \nsenseair_init\n(\nvoid\n);\n\n\n#endif \n/* _SENSEAIR_H_ */\n\n\n\n\n\n\n[user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/senseair/src/senseair.c\n\n\n\n\n\n/**\n\n\n * Licensed to the Apache Software Foundation (ASF) under one\n\n\n * or more contributor license agreements. See the NOTICE file\n\n\n * distributed with this work for additional information\n\n\n * regarding copyright ownership. The ASF licenses this file\n\n\n * to you under the Apache License, Version 2.0 (the\n\n\n * \nLicense\n); you may not use this file except in compliance\n\n\n * with the License. You may obtain a copy of the License at\n\n\n * \n\n\n * http://www.apache.org/licenses/LICENSE-2.0\n\n\n *\n\n\n * Unless required by applicable law or agreed to in writing,\n\n\n * software distributed under the License is distributed on an\n\n\n * \nAS IS\n BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n\n\n * KIND, either express or implied. See the License for the\n\n\n * specific language governing permissions and limitations\n\n\n * under the License.\n\n\n */\n\n\n\nvoid\n\n\nsenseair_init\n(\nvoid\n)\n{\n}\n\n\n\n\n\nAnd add dependency to this package in your project yml file.\n\n\nHere's the listing from apps/air_quality/pkg.yml\n\n\npkg.name: apps/air_quality\npkg.type: app\npkg.description: Air quality sensor test\npkg.keywords:\n\npkg.deps:\n - \n@apache-mynewt-core/libs/console/full\n\n - \n@apache-mynewt-core/libs/newtmgr\n\n - \n@apache-mynewt-core/libs/os\n\n - \n@apache-mynewt-core/libs/shell\n\n - \n@apache-mynewt-core/sys/config\n\n - \n@apache-mynewt-core/sys/log/full\n\n - \n@apache-mynewt-core/sys/stats/full\n\n - libs/my_drivers/senseair\n\n\n\n\n\nAnd add a call to your main() to initialize this driver.\n\n\n [user@IsMyLaptop:~/src/air_quality]$ diff project/blinky/src/main.c project/air_quality/src/main.c\n 28a29\n \n #include \nsenseair/senseair.h\n\n 190a192\n \n senseair_init();\n [user@IsMyLaptop:~/src/air_quality\n\n\n\n\n\nThe ble_prph app runs everything in one task handler. For this project, we're going to add a second\ntask handler to respond to the shell, and then handle communicating with the senseair sensor for us.\n\n\n/** shell task settings. */\n\n\n#define SHELL_TASK_PRIO 2\n\n\n#define SHELL_STACK_SIZE (OS_STACK_ALIGN(336))\n\n\n\nstruct\n \nos_eventq\n \nshell_evq\n;\n\nstruct\n \nos_task\n \nshell_task\n;\n\nbssnz_t\n \nos_stack_t\n \nshell_stack\n[\nSHELL_STACK_SIZE\n];\n\n\n\n\n\nThat defines the task, now we need to initialize it, add a task handler, and we're going to \nuse this task as our default task handler.\n\n\n/**\n\n\n * Event loop for the main shell task.\n\n\n */\n\n\nstatic\n \nvoid\n\n\nshell_task_handler\n(\nvoid\n \n*unused\n)\n{\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nshell_evq\n);\n }\n}\n\n\n\n\n\nAnd in your \nmain()\n add:\n\n\n \n/* Initialize shell eventq */\n\n \nos_eventq_init\n(\nshell_evq\n);\n\n \n/* Create the shell task. \n\n\n * All shell operations are performed in this task.\n\n\n */\n\n \nos_task_init\n(\nshell_task\n, \nshell\n, \nshell_task_handler\n,\n \nNULL\n, \nSHELL_TASK_PRIO\n, \nOS_WAIT_FOREVER\n,\n \nshell_stack\n, \nSHELL_STACK_SIZE\n);\n\n\n\n\n\nDon't forget to change your default task handler!\n\n\n \nos_eventq_dflt_set\n(\nshell_evq\n);\n\n\n\n\n\nAnd then build it to make sure all goes well.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ newt build air_q\nCompiling senseair.c\nArchiving senseair.a\nLinking air_quality.elf\nApp successfully built: /Users/user/src/air_quality/bin/air_q/apps/air_quality/air_quality.elf\n\n\n\n\n\nAll looks good.\n\n\nAdd CLI commands for testing drivers\n\n\nWhile developing the driver, you want to issue operations from console asking it to do stuff. We'll assume that you've already worked through the tutorial \non how to \nenable the CLI\n, so all we'll need to do is add the propper values to the project's \nsyscfg.yml\n file:\n\n\n[user@IsMyLaptop:~/src/air_quality]$ cat targets/air_q/syscfg.yml\nsyscfg.vals:\n # Set as per blinky_primo\n OPENOCD_DEBUG: 1\n # Enable the shell task.\n SHELL_TASK: 1\n STATS_CLI: 1\n CONSOLE_TICKS: 1\n CONSOLE_PROMPT: 1\n\n\n\n\n\nThen register your senseair command with the shell by adding the following to \nlibs/my_drivers/senseair/src/senseair.c\n\n\n#include\n \nshell/shell.h\n\n\n#include\n \nconsole/console.h\n\n\n#include\n \nassert.h\n\n\n\n\nstatic\n \nint\n \nsenseair_shell_func\n(\nint\n \nargc\n, \nchar\n \n**argv\n);\n\nstatic\n \nstruct\n \nshell_cmd\n \nsenseair_cmd\n \n=\n {\n .\nsc_cmd\n \n=\n \nsenseair\n,\n .\nsc_cmd_func\n \n=\n \nsenseair_shell_func\n,\n};\n\n\nvoid\n\n\nsenseair_init\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nshell_cmd_register\n(\nsenseair_cmd\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n}\n\n\nstatic\n \nint\n\n\nsenseair_shell_func\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nconsole_printf\n(\nYay! Somebody called!\\n\n);\n \nreturn\n \n0\n;\n\n}\n\n\n\n\n\nNow you can you build this, download to target, and start minicom on your console port. If you haven't already, familiarize yourself with\nthe tutorial on how to connect a serial port to your board \nhere\n.\n\n\nYou'll need to wire up your Board to a Serial converter first. On the Arduino Primo Board pin 1 is TX and pin 0 is RX so wire 1 to RX on your serial board, and 0 to TX on your serial board.\n\n\n [user@IsMyLaptop:~]$ minicom -D /dev/tty.usbserial-AH02MIE2\n\n\n Welcome to minicom 2.7\n\n OPTIONS: \n Compiled on Oct 12 2015, 07:48:30.\n Port /dev/tty.usbserial-AH02MIE2, 13:44:40\n\n Press CTRL-X Z for help on special keys\n\n ?\n 419: \n ?\n Commands:\n 641: stat echo ? prompt ticks tasks\n 643: mempools date senseair\n 644: \n senseair\n Yay! Somebody called!\n 1125: \n\n 53611: \n tasks\n Tasks:\n 54047: task pri tid runtime csw stksz stkuse lcheck ncheck flg\n 54057: idle 255 0 54048 66890 64 30 0 0 0\n 54068: ble_ll 0 1 9 64986 80 58 0 0 0\n 54079: bleprph 1 2 0 1 336 32 0 0 0\n 54090: shell 2 3 0 2077 336 262 0 0 0\n 54101: \n\n\n\n\n\n\nThat's great. Your shell task is running, and is responding appropriately!\nYou can connect the hardware to your board and start developing code for the driver itself.\n\n\nUse of HAL for drivers\n\n\nThe sensor has a serial port connection, and that's how you are going to connect to it. Your original BSP, hw/bsp/arduino_primo_nrf52, has two UARTs set up.\nWe're using one for our shell/console. It also has a second UART set up as a 'bit-bang' UART but since the SenseAir only needs to\ncommunicate at 9600 baud, this bit-banged uart is plenty fast enough.\n\n\nYou'll have to make a small change to the \nsyscfg.yml\n file in your project's target directory to change the pin definitions \nfor this second UART. Those changes are as follows:\n\n\n UART_0_PIN_TX: 23\n UART_0_PIN_RX: 24\n\n\n\n\n\nWith this in place, you can refer to serial port where your SenseAir sensor by a logical number. This makes the code more platform independent - you could connect this sensor to another board, like Olimex. You will also use the HAL UART abstraction to do the UART port setup and data transfer. That way you don't need to have any platform dependent pieces within your little driver.\n\n\nYou will now see what the driver code ends up looking like. Here's the header file, filled in from the stub you created earlier.\n\n\n/*\n\n\n * Licensed to the Apache Software Foundation (ASF) under one\n\n\n * or more contributor license agreements. See the NOTICE file\n\n\n * distributed with this work for additional information\n\n\n * regarding copyright ownership. The ASF licenses this file\n\n\n * to you under the Apache License, Version 2.0 (the\n\n\n * \nLicense\n); you may not use this file except in compliance\n\n\n * with the License. You may obtain a copy of the License at\n\n\n * \n\n\n * http://www.apache.org/licenses/LICENSE-2.0\n\n\n *\n\n\n * Unless required by applicable law or agreed to in writing,\n\n\n * software distributed under the License is distributed on an\n\n\n * \nAS IS\n BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n\n\n * KIND, either express or implied. See the License for the\n\n\n * specific language governing permissions and limitations\n\n\n * under the License.\n\n\n*/\n\n\n#ifndef _SENSEAIR_H_\n\n\n#define _SENSEAIR_H_\n\n\n\nenum\n \nsenseair_read_type\n {\n \nSENSEAIR_CO2\n,\n};\n\n\nint\n \nsenseair_init\n(\nint\n \nuartno\n);\n\n\nint\n \nsenseair_read\n(\nenum\n \nsenseair_read_type\n);\n\n\n#endif \n/* _SENSEAIR_H_ */\n\n\n\n\n\n\nAs you can see, logical UART number has been added to the init routine. A 'read' function has been added, \nwhich is a blocking read. If you were making a commercial product, you would probably have a callback for reporting the results.\n\n\nAnd here is the source for the driver.\n\n\n/**\n\n\n * Licensed to the Apache Software Foundation (ASF) under one\n\n\n * or more contributor license agreements. See the NOTICE file\n\n\n * distributed with this work for additional information\n\n\n * regarding copyright ownership. The ASF licenses this file\n\n\n * to you under the Apache License, Version 2.0 (the\n\n\n * \nLicense\n); you may not use this file except in compliance\n\n\n * with the License. You may obtain a copy of the License at\n\n\n *\n\n\n * http://www.apache.org/licenses/LICENSE-2.0\n\n\n *\n\n\n * Unless required by applicable law or agreed to in writing,\n\n\n * software distributed under the License is distributed on an\n\n\n * \nAS IS\n BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n\n\n * KIND, either express or implied. See the License for the\n\n\n * specific language governing permissions and limitations\n\n\n * under the License.\n\n\n */\n\n\n#include\n \nstring.h\n\n\n\n#include\n \nshell/shell.h\n\n\n#include\n \nconsole/console.h\n\n\n#include\n \nos/os.h\n\n\n\n#include\n \nhal/hal_uart.h\n\n\n\n#include\n \nsenseair/senseair.h\n\n\n\nstatic\n \nconst\n \nuint8_t\n \ncmd_read_co2\n[] \n=\n {\n \n0xFE\n, \n0\nX44\n, \n0\nX00\n, \n0\nX08\n, \n0\nX02\n, \n0\nX9F\n, \n0\nX25\n\n};\n\n\nstatic\n \nint\n \nsenseair_shell_func\n(\nint\n \nargc\n, \nchar\n \n**argv\n);\n\nstatic\n \nstruct\n \nshell_cmd\n \nsenseair_cmd\n \n=\n {\n .\nsc_cmd\n \n=\n \nsenseair\n,\n .\nsc_cmd_func\n \n=\n \nsenseair_shell_func\n,\n};\n\n\nstruct\n \nsenseair\n { \n \nint\n \nuart\n;\n \nstruct\n \nos_sem\n \nsema\n;\n \nconst\n \nuint8_t\n \n*tx_data\n;\n \nint\n \ntx_off\n;\n \nint\n \ntx_len\n;\n \nuint8_t\n \nrx_data\n[\n32\n]; \n \nint\n \nrx_off\n;\n \nint\n \nvalue\n;\n} \nsenseair\n;\n\n\nstatic\n \nint\n\n\nsenseair_tx_char\n(\nvoid\n \n*arg\n)\n{\n \nstruct\n \nsenseair\n \n*s\n \n=\n \nsenseair\n;\n \nint\n \nrc\n;\n\n \nif\n (\ns-\ntx_off\n \n=\n \ns-\ntx_len\n) {\n \n/*\n\n\n * Command tx finished.\n\n\n */\n\n \ns-\ntx_data\n \n=\n \nNULL\n;\n \nreturn\n \n-\n1\n;\n }\n\n \nrc\n \n=\n \ns-\ntx_data\n[\ns-\ntx_off\n];\n \ns-\ntx_off++\n;\n \nreturn\n \nrc\n;\n}\n\n\n/*\n\n\n * CRC for modbus over serial port.\n\n\n */\n\n\nstatic\n \nconst\n \nuint16_t\n \nmb_crc_tbl\n[] \n=\n {\n \n0x0000\n, \n0xcc01\n, \n0xd801\n, \n0x1400\n, \n0xf001\n, \n0x3c00\n, \n0x2800\n, \n0xe401\n,\n \n0xa001\n, \n0x6c00\n, \n0x7800\n, \n0xb401\n, \n0x5000\n, \n0x9c01\n, \n0x8801\n, \n0x4400\n\n};\n\n\nstatic\n \nuint16_t\n\n\nmb_crc\n(\nconst\n \nuint8_t\n \n*data\n, \nint\n \nlen\n, \nuint16_t\n \ncrc\n)\n{\n \nwhile\n (\nlen--\n \n \n0\n) {\n \ncrc\n \n^=\n \n*data++\n;\n \ncrc\n \n=\n (\ncrc\n \n \n4\n) \n^\n \nmb_crc_tbl\n[\ncrc\n \n \n0xf\n];\n \ncrc\n \n=\n (\ncrc\n \n \n4\n) \n^\n \nmb_crc_tbl\n[\ncrc\n \n \n0xf\n];\n }\n \nreturn\n \ncrc\n;\n}\n\n\nstatic\n \nint\n\n\nmb_crc_check\n(\nconst\n \nvoid\n \n*pkt\n, \nint\n \nlen\n)\n{\n \nuint16_t\n \ncrc\n, \ncmp\n;\n \nuint8_t\n \n*bp\n \n=\n (\nuint8_t\n \n*\n)\npkt\n;\n\n \nif\n (\nlen\n \n \nsizeof\n(\ncrc\n) \n+\n \n1\n) {\n \nreturn\n \n-\n1\n;\n }\n \ncrc\n \n=\n \nmb_crc\n(\npkt\n, \nlen\n \n-\n \n2\n, \n0xffff\n);\n \ncmp\n \n=\n \nbp\n[\nlen\n \n-\n \n2\n] \n|\n (\nbp\n[\nlen\n \n-\n \n1\n] \n \n8\n);\n \nif\n (\ncrc\n \n!=\n \ncmp\n) {\n \nreturn\n \n-\n1\n;\n } \nelse\n {\n \nreturn\n \n0\n;\n }\n}\n\n\nstatic\n \nint\n\n\nsenseair_rx_char\n(\nvoid\n \n*arg\n, \nuint8_t\n \ndata\n)\n{\n \nstruct\n \nsenseair\n \n*s\n \n=\n (\nstruct\n \nsenseair\n \n*\n)\narg\n;\n \nint\n \nrc\n;\n\n \nif\n (\ns-\nrx_off\n \n=\n \nsizeof\n(\ns-\nrx_data\n)) {\n \ns-\nrx_off\n \n=\n \n0\n;\n }\n \ns-\nrx_data\n[\ns-\nrx_off\n] \n=\n \ndata\n;\n \ns-\nrx_off++\n;\n\n \nif\n (\ns-\nrx_off\n \n==\n \n7\n) {\n \nrc\n \n=\n \nmb_crc_check\n(\ns-\nrx_data\n, \ns-\nrx_off\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \ns-\nvalue\n \n=\n \ns-\nrx_data\n[\n3\n] \n*\n \n256\n \n+\n \ns-\nrx_data\n[\n4\n];\n \nos_sem_release\n(\ns-\nsema\n);\n }\n }\n \nreturn\n \n0\n;\n}\n\n\nvoid\n\n\nsenseair_tx\n(\nstruct\n \nsenseair\n \n*s\n, \nconst\n \nuint8_t\n \n*tx_data\n, \nint\n \ndata_len\n)\n{\n \ns-\ntx_data\n \n=\n \ntx_data\n;\n \ns-\ntx_len\n \n=\n \ndata_len\n;\n \ns-\ntx_off\n \n=\n \n0\n;\n \ns-\nrx_off\n \n=\n \n0\n;\n\n \nhal_uart_start_tx\n(\ns-\nuart\n);\n}\n\n\nint\n\n\nsenseair_read\n(\nenum\n \nsenseair_read_type\n \ntype\n)\n{\n \nstruct\n \nsenseair\n \n*s\n \n=\n \nsenseair\n;\n \nconst\n \nuint8_t\n \n*cmd\n;\n \nint\n \ncmd_len\n;\n \nint\n \nrc\n;\n\n \nif\n (\ns-\ntx_data\n) {\n \n/*\n\n\n * busy\n\n\n */\n\n \nreturn\n \n-\n1\n;\n }\n \nswitch\n (\ntype\n) {\n \ncase\n \nSENSEAIR_CO2\n:\n \ncmd\n \n=\n \ncmd_read_co2\n;\n \ncmd_len\n \n=\n \nsizeof\n(\ncmd_read_co2\n);\n \nbreak\n;\n \ndefault\n:\n\n \nreturn\n \n-\n1\n;\n }\n \nsenseair_tx\n(\ns\n, \ncmd\n, \ncmd_len\n);\n \nrc\n \n=\n \nos_sem_pend\n(\ns-\nsema\n, \nOS_TICKS_PER_SEC\n \n/\n \n2\n);\n \nif\n (\nrc\n \n==\n \nOS_TIMEOUT\n) {\n \n/*\n\n\n * timeout\n\n\n */\n\n \nreturn\n \n-\n2\n;\n }\n \nreturn\n \ns-\nvalue\n;\n}\n\n\nstatic\n \nint\n\n\nsenseair_shell_func\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nvalue\n;\n \nenum\n \nsenseair_read_type\n \ntype\n;\n\n \nif\n (\nargc\n \n \n2\n) {\n\nusage\n:\n \nconsole_printf\n(\n%s co2\\n\n, \nargv\n[\n0\n]);\n \nreturn\n \n0\n;\n }\n \nif\n (\n!strcmp\n(\nargv\n[\n1\n], \nco2\n)) {\n \ntype\n \n=\n \nSENSEAIR_CO2\n;\n } \nelse\n {\n \ngoto\n \nusage\n;\n }\n \nvalue\n \n=\n \nsenseair_read\n(\ntype\n);\n \nif\n (\nvalue\n \n=\n \n0\n) {\n \nconsole_printf\n(\nGot %d\\n\n, \nvalue\n);\n } \nelse\n {\n \nconsole_printf\n(\nError while reading: %d\\n\n, \nvalue\n);\n }\n \nreturn\n \n0\n;\n}\n\n\nint\n\n\nsenseair_init\n(\nint\n \nuartno\n)\n{\n \nint\n \nrc\n;\n \nstruct\n \nsenseair\n \n*s\n \n=\n \nsenseair\n;\n\n \nrc\n \n=\n \nshell_cmd_register\n(\nsenseair_cmd\n);\n \nif\n (\nrc\n) {\n \nreturn\n \nrc\n;\n }\n\n \nrc\n \n=\n \nos_sem_init\n(\ns-\nsema\n, \n1\n);\n \nif\n (\nrc\n) {\n \nreturn\n \nrc\n;\n }\n \nrc\n \n=\n \nhal_uart_init_cbs\n(\nuartno\n, \nsenseair_tx_char\n, \nNULL\n,\n \nsenseair_rx_char\n, \nsenseair\n);\n \nif\n (\nrc\n) {\n \nreturn\n \nrc\n;\n }\n \nrc\n \n=\n \nhal_uart_config\n(\nuartno\n, \n9600\n, \n8\n, \n1\n, \nHAL_UART_PARITY_NONE\n,\n \nHAL_UART_FLOW_CTL_NONE\n);\n \nif\n (\nrc\n) {\n \nreturn\n \nrc\n;\n }\n \ns-\nuart\n \n=\n \nuartno\n;\n\n \nreturn\n \n0\n;\n}\n\n\n\n\n\nAnd your modified main() for senseair driver init.\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n ....\n \nsenseair_init\n(\n0\n);\n ....\n }\n\n\n\n\n\nYou can see from the code that you are using the HAL interface to open a UART port, and using OS \nsemaphore as a way of blocking the task when waiting for read response to come back from the sensor.\n\n\nNow comes the fun part: Hooking up the sensor! It's fun because a) hooking up a sensor is always \nfun and b) the SenseAir sensor's PCB is entirely unlabeled, so you'll have to trust us on how to hook it up. \n\n\nSo here we go. \n\n\nYou'll have to do a little soldering. I soldered some header pins to the SenseAir K30 board to\nmake connecting wires easier using standard jumper wires, but you can also just solder wires\nstraight to the board if you prefer.\n\n\nHere's what your SenseAir board should look like once it's wired up:\n\n\n\n\nNow that you have that wired up, let's get the Arduino Primo wired up. A couple of things to note:\n\n\n\n\nThe Arduino Primo's 'console' UART is actually UART1. \n\n\nThe secondary (bit-banged) UART is UART0, so that's where we'll have to hook up the SenseAir.\n\n\n\n\nHere's what your Arduino Primo should now look like with everything wired in:\n\n\n\n\nEverything is wired and you're ready to go! Build and load your new app:\n\n\n$ newt build air_q\nBuilding target targets/air_q\nCompiling apps/air_quality/src/main.c\nArchiving apps_air_quality.a\nLinking myproj/bin/targets/air_q/app/apps/air_quality/air_quality.elf\nTarget successfully built: targets/air_q\n$ newt create-image air_q 1.0.0\nApp image succesfully generated: myproj/bin/targets/air_q/app/apps/air_quality/air_quality.img\n$ newt load air_q\nLoading app image into slot 1\n\n\n\n\n\nNow, you should be able to connect to your serial port and read values:\n\n\nuser@IsMyLaptop:~]$ minicom -D /dev/tty.usbserial-AH02MIE2\n\n\n Welcome to minicom 2.7\n\n OPTIONS: \n Compiled on Oct 12 2015, 07:48:30.\n Port /dev/tty.usbserial-AH02MIE2, 13:44:40\n\n Press CTRL-X Z for help on special keys\n\n 1185: \n ?\n Commands:\n 1382: stat echo ? prompt ticks tasks\n 1390: mempools date senseair\n 1395: \n senseair\n senseair co2\n 2143: \n senseair co2\n Got 973\n\n\n\n\n\nAnd you're getting valid readings! Congratulations!\n\n\nNext we'll hook this all up via Bluetooth so that you can read those values remotely.",
- "title": "Basic Air Quality Sensor"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/#air-quality-sensor-project",
- "text": "",
- "title": "Air quality sensor project"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/#setting-up-source-tree-for-stuff-you-need",
- "text": "To start with, you need to create a new project under which you will do this development. So you type in: $ mkdir $HOME/src\n $ cd $HOME/src\n $ newt new air_quality Let's say you are using Arduino Primo -- which is based on the Nordic Semi NRF52 chip -- as the platform. \nYou know you need the board support package for that hardware. You can look up its location, add it your \nproject, and fetch that along with the core OS components. Luckily, the Arduino Primo is supported in the \nMynewt Core, so there's nothing much to do here. Your project.yml file should look like this: [user@IsMyLaptop:~/src/air_quality]$ emacs project.yml \n [user@IsMyLaptop:~/src/air_quality]$ cat project.yml\n project.name: air_quality \n\n project.repositories:\n - apache-mynewt-core\n\n # Use github s distribution mechanism for core ASF libraries.\n # This provides mirroring automatically for us.\n #\n repository.apache-mynewt-core:\n type: github\n vers: 0-latest\n user: apache\n repo: incubator-mynewt-core\n\n [user@IsMyLaptop:~/src/air_quality]$ newt install\n apache-mynewt-core\n [user@IsMyLaptop:~/src/air_quality]$ ls repos/\n apache-mynewt-core Good. You want to make sure you have all the needed bits for supporting your board; \nso you decide to build the blinky project for the platform first. Now create a target for it and build it. Easiest way to proceed is to copy the existing target for blinky, and modify it to build for Arduino Primo board. [user@IsMyLaptop:~/src/air_quality]$ newt target copy my_blinky_sim blink_primo\nTarget successfully copied; targets/my_blinky_sim -- targets/blink_primo\n[user@IsMyLaptop:~/src/air_quality]$ newt target set blink_primo bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\nTarget targets/blink_nrf successfully set target.bsp to @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n[user@IsMyLaptop:~/src/air_quality]$ newt build blink_primo\nCompiling hal_bsp.c\n...\nLinking blinky.elf\nApp successfully built: /Users/user/src/air_quality/bin/blink_primo/apps/blinky/blinky.elf Good. You know that this platform uses bootloader, which means you have to create a target for that too. [user@IsMyLaptop:~/src/air_quality]$ newt target create boot_primo\nTarget targets/boot_nrf successfully created\n[user@IsMyLaptop:~/src/air_quality]$ newt target show\n@apache-mynewt-core/targets/unittest\n bsp=hw/bsp/native\n build_profile=debug\n compiler=compiler/sim\ntargets/blink_primo\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n build_profile=debug\ntargets/boot_primo\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n[user@IsMyLaptop:~/src/air_quality]$ newt target set boot_nrf bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\nTarget targets/boot_nrf successfully set target.bsp to @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n[user@IsMyLaptop:~/src/air_quality]$ newt target set boot_nrf app=@apache-mynewt-core/apps/boot\nTarget targets/boot_nrf successfully set target.app to @apache-mynewt-core/apps/boot\n[user@IsMyLaptop:~/src/air_quality]$ newt target set boot_nrf build_profile=optimized\nTarget targets/boot_nrf successfully set target.build_profile to optimized And then build it, and load it onto the board. newt build boot_primo\n....\nLinking boot.elf\nApp successfully built: /Users/user/src/air_quality/bin/boot_primo/apps/boot/boot.elf\n[user@IsMyLaptop:~/src/air_quality]\n$ newt load boot_primo At this point, you may (or may not) see a bunch of error messages about not being able to connect to\nyour board, not being able to load the image, etc. If that's the case, and you haven't already, you\nshould most definitely go worth through the blinky_primo tutorial so that you\ncan properly communicate with your board. Next you must download the targets to board, and see that the LED actually blinks. You plug in the \nArduino Primo board to your laptop, and say: [user@IsMyLaptop:~/src/air_quality]$ newt load blink_primo\nLoading app image into slot 1\nError: couldn t open /Users/user/src/air_quality/bin/blink_primo/apps/blinky/blinky.img\n\nError: exit status 1\n\nload - Load app image to target for target-name .\n\nUsage:\n newt load [flags]\n\nExamples:\n newt load target-name \n\n\nGlobal Flags:\n -l, --loglevel string Log level, defaults to WARN. (default WARN )\n -o, --outfile string Filename to tee log output to\n -q, --quiet Be quiet; only display error output.\n -s, --silent Be silent; don t output anything.\n -v, --verbose Enable verbose output when executing commands.\nexit status 1 Ah. Forgot to create an image out of the blinky binary. Note that every time you want to build and \nload a new firmware image to a target board, you need to run 'create-image' on it. [user@IsMyLaptop:~/src/air_quality]$ newt create-image blink_primo 0.0.1\nApp image successfully generated: /Users/user/src/air_quality/bin/blink_primo/apps/blinky/blinky.img\nBuild manifest: /Users/user/src/air_quality/bin/blink_nrf/apps/blinky/manifest.json\n[user@IsMyLaptop:~/src/air_quality]$ newt load blink_primo And it's blinking. Shortcut for doing build/create-image/load/debug steps all in one is 'newt run' command. Check \nout the usage from command line help.",
- "title": "Setting up source tree for stuff you need"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/#create-test-project",
- "text": "Now that you have your system setup, you can start creating your own stuff.\nFirst you want to create a project for yourself - you could start by using blinky as a project \ntemplate, but since we're going to want to be able to access the data via Bluetooth, let's \nuse the bleprph Bluetooth Peripheral project instead. [user@IsMyLaptop:~/src/air_quality]$ mkdir apps/air_quality\n [user@IsMyLaptop:~/src/air_quality]$ cp repos/apache-mynewt-core/apps/bleprph/pkg.yml apps/air_quality/\n [user@IsMyLaptop:~/src/air_quality]$ cp -Rp repos/apache-mynewt-core/apps/bleprph/src apps/air_quality/ Then you modify the apps/air_quality/pkg.yml for air_quality in order to change the pkg.name to be apps/air_quality .\nYou'll need to add the @apache-mynewt-core/ path to all the package dependencies, since the app no longer\nresides within the apache-mynewt-core repository. [user@IsMyLaptop:~/src/air_quality]$ cat apps/air_quality/pkg.yml\npkg.name: apps/air_quality\npkg.type: app\npkg.description: BLE Air Quality application.\npkg.author: Apache Mynewt dev@mynewt.incubator.apache.org \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n\npkg.deps: \n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/sys/shell \n - @apache-mynewt-core/sys/stats/full \n - @apache-mynewt-core/sys/log/full \n - @apache-mynewt-core/mgmt/newtmgr \n - @apache-mynewt-core/mgmt/newtmgr/transport/ble \n - @apache-mynewt-core/net/nimble/controller \n - @apache-mynewt-core/net/nimble/host \n - @apache-mynewt-core/net/nimble/host/services/ans \n - @apache-mynewt-core/net/nimble/host/services/gap \n - @apache-mynewt-core/net/nimble/host/services/gatt \n - @apache-mynewt-core/net/nimble/host/store/ram \n - @apache-mynewt-core/net/nimble/transport/ram \n - @apache-mynewt-core/sys/console/full \n - @apache-mynewt-core/sys/sysinit \n - @apache-mynewt-core/sys/id And create a target for it: [user@IsMyLaptop:~/src/air_quality]$ newt target create air_q\nTarget targets/air_q successfully created\n[user@IsMyLaptop:~/src/air_quality]$ newt target set air_q bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52\nTarget targets/air_q successfully set target.bsp to @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n[user@IsMyLaptop:~/src/air_quality]$ newt target set air_q app=apps/air_quality \nTarget targets/air_q successfully set target.app to apps/air_quality\n[user@IsMyLaptop:~/src/air_quality]$ newt target set air_q build_profile=debug\nTarget targets/air_q successfully set target.build_profile to debug\n[user@IsMyLaptop:~/src/air_quality]$ newt build air_q\n ....\nLinking /Users/dsimmons/dev/myproj/bin/targets/air_q/app/apps/air_quality/air_quality.elf\nTarget successfully built: targets/air_q",
- "title": "Create test project"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/#create-packages-for-drivers",
- "text": "One of the sensors you want to enable is SenseAir K30, which will connect to the board over a serial port.\nTo start development of the driver, you first need to create a package description for it, and add stubs for sources. The first thing to do is to create the directory structure for your driver: [user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/senseair/include/senseair\n[user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/senseair/src Now you can add the files you need. You'll need a pkg.yml to describe the driver, and then header stub followed by source stub. [user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/senseair/pkg.yml # # Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file # distributed with this work for additional information # regarding copyright ownership. The ASF licenses this file # to you under the Apache License, Version 2.0 (the # License ); you may not use this file except in compliance # with the License. You may obtain a copy of the License at # # http: //www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, # software distributed under the License is distributed on an # AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY # KIND, either express or implied. See the License for the # specific language governing permissions and limitations # under the License. # pkg . name : libs/my_drivers/senseair pkg . description : Host side of the nimble Bluetooth Smart stack . pkg . author : Apache Mynewt dev@mynewt.incubator.apache.org pkg . homepage : http://mynewt.apache.org/ pkg . keywords :\n - ble \n - bluetooth pkg . deps :\n - @apache-mynewt-core/kernel/os [user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/senseair/include/senseair/senseair.h /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * License ); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ #ifndef _SENSEAIR_H_ #define _SENSEAIR_H_ void senseair_init ( void ); #endif /* _SENSEAIR_H_ */ [user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/senseair/src/senseair.c /** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * License ); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ void senseair_init ( void )\n{\n} And add dependency to this package in your project yml file. Here's the listing from apps/air_quality/pkg.yml pkg.name: apps/air_quality\npkg.type: app\npkg.description: Air quality sensor test\npkg.keywords:\n\npkg.deps:\n - @apache-mynewt-core/libs/console/full \n - @apache-mynewt-core/libs/newtmgr \n - @apache-mynewt-core/libs/os \n - @apache-mynewt-core/libs/shell \n - @apache-mynewt-core/sys/config \n - @apache-mynewt-core/sys/log/full \n - @apache-mynewt-core/sys/stats/full \n - libs/my_drivers/senseair And add a call to your main() to initialize this driver. [user@IsMyLaptop:~/src/air_quality]$ diff project/blinky/src/main.c project/air_quality/src/main.c\n 28a29\n #include senseair/senseair.h \n 190a192\n senseair_init();\n [user@IsMyLaptop:~/src/air_quality The ble_prph app runs everything in one task handler. For this project, we're going to add a second\ntask handler to respond to the shell, and then handle communicating with the senseair sensor for us. /** shell task settings. */ #define SHELL_TASK_PRIO 2 #define SHELL_STACK_SIZE (OS_STACK_ALIGN(336)) struct os_eventq shell_evq ; struct os_task shell_task ; bssnz_t os_stack_t shell_stack [ SHELL_STACK_SIZE ]; That defines the task, now we need to initialize it, add a task handler, and we're going to \nuse this task as our default task handler. /** * Event loop for the main shell task. */ static void shell_task_handler ( void *unused )\n{\n while ( 1 ) {\n os_eventq_run ( shell_evq );\n }\n} And in your main() add: /* Initialize shell eventq */ \n os_eventq_init ( shell_evq );\n\n /* Create the shell task. * All shell operations are performed in this task. */ \n os_task_init ( shell_task , shell , shell_task_handler ,\n NULL , SHELL_TASK_PRIO , OS_WAIT_FOREVER ,\n shell_stack , SHELL_STACK_SIZE ); Don't forget to change your default task handler! os_eventq_dflt_set ( shell_evq ); And then build it to make sure all goes well. [user@IsMyLaptop:~/src/air_quality]$ newt build air_q\nCompiling senseair.c\nArchiving senseair.a\nLinking air_quality.elf\nApp successfully built: /Users/user/src/air_quality/bin/air_q/apps/air_quality/air_quality.elf All looks good.",
- "title": "Create packages for drivers"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/#add-cli-commands-for-testing-drivers",
- "text": "While developing the driver, you want to issue operations from console asking it to do stuff. We'll assume that you've already worked through the tutorial \non how to enable the CLI , so all we'll need to do is add the propper values to the project's syscfg.yml file: [user@IsMyLaptop:~/src/air_quality]$ cat targets/air_q/syscfg.yml\nsyscfg.vals:\n # Set as per blinky_primo\n OPENOCD_DEBUG: 1\n # Enable the shell task.\n SHELL_TASK: 1\n STATS_CLI: 1\n CONSOLE_TICKS: 1\n CONSOLE_PROMPT: 1 Then register your senseair command with the shell by adding the following to libs/my_drivers/senseair/src/senseair.c #include shell/shell.h #include console/console.h #include assert.h static int senseair_shell_func ( int argc , char **argv ); static struct shell_cmd senseair_cmd = {\n . sc_cmd = senseair ,\n . sc_cmd_func = senseair_shell_func ,\n}; void senseair_init ( void )\n{\n int rc ;\n\n rc = shell_cmd_register ( senseair_cmd );\n assert ( rc == 0 );\n} static int senseair_shell_func ( int argc , char **argv )\n{\n console_printf ( Yay! Somebody called!\\n );\n return 0 ;\n\n} Now you can you build this, download to target, and start minicom on your console port. If you haven't already, familiarize yourself with\nthe tutorial on how to connect a serial port to your board here . You'll need to wire up your Board to a Serial converter first. On the Arduino Primo Board pin 1 is TX and pin 0 is RX so wire 1 to RX on your serial board, and 0 to TX on your serial board. [user@IsMyLaptop:~]$ minicom -D /dev/tty.usbserial-AH02MIE2\n\n\n Welcome to minicom 2.7\n\n OPTIONS: \n Compiled on Oct 12 2015, 07:48:30.\n Port /dev/tty.usbserial-AH02MIE2, 13:44:40\n\n Press CTRL-X Z for help on special keys\n\n ?\n 419: ?\n Commands:\n 641: stat echo ? prompt ticks tasks\n 643: mempools date senseair\n 644: senseair\n Yay! Somebody called!\n 1125: \n 53611: tasks\n Tasks:\n 54047: task pri tid runtime csw stksz stkuse lcheck ncheck flg\n 54057: idle 255 0 54048 66890 64 30 0 0 0\n 54068: ble_ll 0 1 9 64986 80 58 0 0 0\n 54079: bleprph 1 2 0 1 336 32 0 0 0\n 54090: shell 2 3 0 2077 336 262 0 0 0\n 54101: That's great. Your shell task is running, and is responding appropriately!\nYou can connect the hardware to your board and start developing code for the driver itself.",
- "title": "Add CLI commands for testing drivers"
- },
- {
- "location": "/os/tutorials/air_quality_sensor/#use-of-hal-for-drivers",
- "text": "The sensor has a serial port connection, and that's how you are going to connect to it. Your original BSP, hw/bsp/arduino_primo_nrf52, has two UARTs set up.\nWe're using one for our shell/console. It also has a second UART set up as a 'bit-bang' UART but since the SenseAir only needs to\ncommunicate at 9600 baud, this bit-banged uart is plenty fast enough. You'll have to make a small change to the syscfg.yml file in your project's target directory to change the pin definitions \nfor this second UART. Those changes are as follows: UART_0_PIN_TX: 23\n UART_0_PIN_RX: 24 With this in place, you can refer to serial port where your SenseAir sensor by a logical number. This makes the code more platform independent - you could connect this sensor to another board, like Olimex. You will also use the HAL UART abstraction to do the UART port setup and data transfer. That way you don't need to have any platform dependent pieces within your little driver. You will now see what the driver code ends up looking like. Here's the header file, filled in from the stub you created earlier. /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * License ); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ #ifndef _SENSEAIR_H_ #define _SENSEAIR_H_ enum senseair_read_type {\n SENSEAIR_CO2 ,\n}; int senseair_init ( int uartno ); int senseair_read ( enum senseair_read_type ); #endif /* _SENSEAIR_H_ */ As you can see, logical UART number has been added to the init routine. A 'read' function has been added, \nwhich is a blocking read. If you were making a commercial product, you would probably have a callback for reporting the results. And here is the source for the driver. /** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * License ); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ #include string.h #include shell/shell.h #include console/console.h #include os/os.h #include hal/hal_uart.h #include senseair/senseair.h static const uint8_t cmd_read_co2 [] = {\n 0xFE , 0 X44 , 0 X00 , 0 X08 , 0 X02 , 0 X9F , 0 X25 \n}; static int senseair_shell_func ( int argc , char **argv ); static struct shell_cmd senseair_cmd = {\n . sc_cmd = senseair ,\n . sc_cmd_func = senseair_shell_func ,\n}; struct senseair { \n int uart ;\n struct os_sem sema ;\n const uint8_t *tx_data ;\n int tx_off ;\n int tx_len ;\n uint8_t rx_data [ 32 ]; \n int rx_off ;\n int value ;\n} senseair ; static int senseair_tx_char ( void *arg )\n{\n struct senseair *s = senseair ;\n int rc ;\n\n if ( s- tx_off = s- tx_len ) {\n /* * Command tx finished. */ \n s- tx_data = NULL ;\n return - 1 ;\n }\n\n rc = s- tx_data [ s- tx_off ];\n s- tx_off++ ;\n return rc ;\n} /* * CRC for modbus over serial port. */ static const uint16_t mb_crc_tbl [] = {\n 0x0000 , 0xcc01 , 0xd801 , 0x1400 , 0xf001 , 0x3c00 , 0x2800 , 0xe401 ,\n 0xa001 , 0x6c00 , 0x7800 , 0xb401 , 0x5000 , 0x9c01 , 0x8801 , 0x4400 \n}; static uint16_t mb_crc ( const uint8_t *data , int len , uint16_t crc )\n{\n while ( len-- 0 ) {\n crc ^= *data++ ;\n crc = ( crc 4 ) ^ mb_crc_tbl [ crc 0xf ];\n crc = ( crc 4 ) ^ mb_crc_tbl [ crc 0xf ];\n }\n return crc ;\n} static int mb_crc_check ( const void *pkt , int len )\n{\n uint16_t crc , cmp ;\n uint8_t *bp = ( uint8_t * ) pkt ;\n\n if ( len sizeof ( crc ) + 1 ) {\n return - 1 ;\n }\n crc = mb_crc ( pkt , len - 2 , 0xffff );\n cmp = bp [ len - 2 ] | ( bp [ len - 1 ] 8 );\n if ( crc != cmp ) {\n return - 1 ;\n } else {\n return 0 ;\n }\n} static int senseair_rx_char ( void *arg , uint8_t data )\n{\n struct senseair *s = ( struct senseair * ) arg ;\n int rc ;\n\n if ( s- rx_off = sizeof ( s- rx_data )) {\n s- rx_off = 0 ;\n }\n s- rx_data [ s- rx_off ] = data ;\n s- rx_off++ ;\n\n if ( s- rx_off == 7 ) {\n rc = mb_crc_check ( s- rx_data , s- rx_off );\n if ( rc == 0 ) {\n s- value = s- rx_data [ 3 ] * 256 + s- rx_data [ 4 ];\n os_sem_release ( s- sema );\n }\n }\n return 0 ;\n} void senseair_tx ( struct senseair *s , const uint8_t *tx_data , int data_len )\n{\n s- tx_data = tx_data ;\n s- tx_len = data_len ;\n s- tx_off = 0 ;\n s- rx_off = 0 ;\n\n hal_uart_start_tx ( s- uart );\n} int senseair_read ( enum senseair_read_type type )\n{\n struct senseair *s = senseair ;\n const uint8_t *cmd ;\n int cmd_len ;\n int rc ;\n\n if ( s- tx_data ) {\n /* * busy */ \n return - 1 ;\n }\n switch ( type ) {\n case SENSEAIR_CO2 :\n cmd = cmd_read_co2 ;\n cmd_len = sizeof ( cmd_read_co2 );\n break ;\n default : \n return - 1 ;\n }\n senseair_tx ( s , cmd , cmd_len );\n rc = os_sem_pend ( s- sema , OS_TICKS_PER_SEC / 2 );\n if ( rc == OS_TIMEOUT ) {\n /* * timeout */ \n return - 2 ;\n }\n return s- value ;\n} static int senseair_shell_func ( int argc , char **argv )\n{\n int value ;\n enum senseair_read_type type ;\n\n if ( argc 2 ) { usage :\n console_printf ( %s co2\\n , argv [ 0 ]);\n return 0 ;\n }\n if ( !strcmp ( argv [ 1 ], co2 )) {\n type = SENSEAIR_CO2 ;\n } else {\n goto usage ;\n }\n value = senseair_read ( type );\n if ( value = 0 ) {\n console_printf ( Got %d\\n , value );\n } else {\n console_printf ( Error while reading: %d\\n , value );\n }\n return 0 ;\n} int senseair_init ( int uartno )\n{\n int rc ;\n struct senseair *s = senseair ;\n\n rc = shell_cmd_register ( senseair_cmd );\n if ( rc ) {\n return rc ;\n }\n\n rc = os_sem_init ( s- sema , 1 );\n if ( rc ) {\n return rc ;\n }\n rc = hal_uart_init_cbs ( uartno , senseair_tx_char , NULL ,\n senseair_rx_char , senseair );\n if ( rc ) {\n return rc ;\n }\n rc = hal_uart_config ( uartno , 9600 , 8 , 1 , HAL_UART_PARITY_NONE ,\n HAL_UART_FLOW_CTL_NONE );\n if ( rc ) {\n return rc ;\n }\n s- uart = uartno ;\n\n return 0 ;\n} And your modified main() for senseair driver init. int main ( int argc , char **argv )\n{\n ....\n senseair_init ( 0 );\n ....\n } You can see from the code that you are using the HAL interface to open a UART port, and using OS \nsemaphore as a way of blocking the task when waiting for read response to come back from the sensor. Now comes the fun part: Hooking up the sensor! It's fun because a) hooking up a sensor is always \nfun and b) the SenseAir sensor's PCB is entirely unlabeled, so you'll have to trust us on how to hook it up. So here we go. You'll have to do a little soldering. I soldered some header pins to the SenseAir K30 board to\nmake connecting wires easier using standard jumper wires, but you can also just solder wires\nstraight to the board if you prefer. Here's what your SenseAir board should look like once it's wired up: Now that you have that wired up, let's get the Arduino Primo wired up. A couple of things to note: The Arduino Primo's 'console' UART is actually UART1. The secondary (bit-banged) UART is UART0, so that's where we'll have to hook up the SenseAir. Here's what your Arduino Primo should now look like with everything wired in: Everything is wired and you're ready to go! Build and load your new app: $ newt build air_q\nBuilding target targets/air_q\nCompiling apps/air_quality/src/main.c\nArchiving apps_air_quality.a\nLinking myproj/bin/targets/air_q/app/apps/air_quality/air_quality.elf\nTarget successfully built: targets/air_q\n$ newt create-image air_q 1.0.0\nApp image succesfully generated: myproj/bin/targets/air_q/app/apps/air_quality/air_quality.img\n$ newt load air_q\nLoading app image into slot 1 Now, you should be able to connect to your serial port and read values: user@IsMyLaptop:~]$ minicom -D /dev/tty.usbserial-AH02MIE2\n\n\n Welcome to minicom 2.7\n\n OPTIONS: \n Compiled on Oct 12 2015, 07:48:30.\n Port /dev/tty.usbserial-AH02MIE2, 13:44:40\n\n Press CTRL-X Z for help on special keys\n\n 1185: ?\n Commands:\n 1382: stat echo ? prompt ticks tasks\n 1390: mempools date senseair\n 1395: senseair\n senseair co2\n 2143: senseair co2\n Got 973 And you're getting valid readings! Congratulations! Next we'll hook this all up via Bluetooth so that you can read those values remotely.",
- "title": "Use of HAL for drivers"
- },
- {
- "location": "/os/tutorials/air_quality_ble/",
- "text": "Air quality sensor project via Bluetooth\n\n\nThis is a follow-on project to the \nBasic Air Quality Sensor\n project; so it is\nassumed that you have worked through that project and have your CO\n2\n sensor working properly with\nyour Arduino Primo board. \n\n\nSo let's get started making this thing Bluetooth enabled!\n\n\nAdd Bluetooth GATT Services\n\n\nSince we already built the previous demo on the \nbluetooth peripheral\n basic\napp most of the bluetooth plumbing has already been taken care of for us. What's left is for us\nto add the required GATT services for advertising the Carbon Dioxide sensor so that\nother devices can get those values.\n\n\nFirst, we'll define the GATT Services in \napps/air_quality/src/bleprph.h\n.\n\n\n/* Sensor Data */\n\n\n/* e761d2af-1c15-4fa7-af80-b5729002b340 */\n\n\nstatic\n \nconst\n \nble_uuid128_t\n \ngatt_svr_svc_co2_uuid\n \n=\n\n \nBLE_UUID128_INIT\n(\n0x40\n, \n0xb3\n, \n0x20\n, \n0x90\n, \n0x72\n, \n0xb5\n, \n0x80\n, \n0xaf\n,\n \n0xa7\n, \n0x4f\n, \n0x15\n, \n0x1c\n, \n0xaf\n, \n0xd2\n, \n0x61\n, \n0xe7\n);\n\n#define CO2_SNS_TYPE 0xDEAD\n\n\n#define CO2_SNS_STRING \nSenseAir K30 CO2 Sensor\n\n\n#define CO2_SNS_VAL 0xBEAD\n\n\n\nuint16_t\n \ngatt_co2_val\n; \n\n\n\n\n\nYou can use any hex values you choose for the sensor type and sensor values, and you can \neven forget the sensor type and sensor string definitions altogether but they make\nthe results look nice in our Bluetooth App for Mac OS X and iOS.\n\n\nNext we'll add those services to \napps/air_quality/src/gatt_svr.c\n.\n\n\nstatic\n \nint\n\n\ngatt_svr_sns_access\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nble_gatt_access_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n);\n\n\nstatic\n \nuint16_t\n \ngatt_co2_val_len\n;\n\n\n\n\n\nMake sure it is added as \nprimary\n service.\n\n\nstatic\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \ngatt_svr_svcs\n[] \n=\n {\n {\n \n/*** Service: Security test. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid\n \n=\n \ngatt_svr_svc_sec_test_uuid\n.\nu\n,\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n \n/*** Characteristic: Random number generator. */\n\n .\nuuid\n \n=\n \ngatt_svr_chr_sec_test_rand_uuid\n.\nu\n,\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_sec_test\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n \n|\n \nBLE_GATT_CHR_F_READ_ENC\n,\n }, {\n \n/*** Characteristic: Static value. */\n\n .\nuuid\n \n=\n \ngatt_svr_chr_sec_test_static_uuid\n,.\nu\n\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_sec_test\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n \n|\n\n \nBLE_GATT_CHR_F_WRITE\n \n|\n \nBLE_GATT_CHR_F_WRITE_ENC\n,\n }, {\n \n0\n, \n/* No more characteristics in this service. */\n\n } },\n },\n {\n \n/*** CO2 Level Notification Service. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid\n \n=\n \ngatt_svr_svc_co2_uuid\n.\nu\n,\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n .\nuuid\n \n=\n \nBLE_UUID16_DECLARE\n(\nCO2_SNS_TYPE\n),\n .\naccess_cb\n \n=\n \ngatt_svr_sns_access\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n }, {\n .\nuuid\n \n=\n \nBLE_UUID16_DECLARE\n(\nCO2_SNS_VAL\n),\n .\naccess_cb\n \n=\n \ngatt_svr_sns_access\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_NOTIFY\n,\n }, {\n \n0\n, \n/* No more characteristics in this service. */\n\n } },\n },\n\n {\n \n0\n, \n/* No more services. */\n\n },\n };\n\n\n\n\n\nNext we need to tell the GATT Server how to handle requests for CO\n2\n readings :\n\n\nsstatic\n \nint\n\n\ngatt_svr_sns_access\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nble_gatt_access_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n)\n{\n \nuint16_t\n \nuuid16\n;\n \nint\n \nrc\n;\n\n \nuuid16\n \n=\n \nble_uuid_u16\n(\nctxt-\nchr-\nuuid\n);\n\n \nswitch\n (\nuuid16\n) {\n \ncase\n \nCO2_SNS_TYPE\n:\n \nassert\n(\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nrc\n \n=\n \nos_mbuf_append\n(\nctxt-\nom\n, \nCO2_SNS_STRING\n, \nsizeof\n \nCO2_SNS_STRING\n);\n \nBLEPRPH_LOG\n(\nINFO\n, \nCO2 SENSOR TYPE READ: %s\\n\n, \nCO2_SNS_STRING\n);\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \nBLE_ATT_ERR_INSUFFICIENT_RES\n;\n\n \ncase\n \nCO2_SNS_VAL\n:\n \nif\n (\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_WRITE_CHR\n) {\n \nrc\n \n=\n \ngatt_svr_chr_write\n(\nctxt-\nom\n, \n0\n,\n \nsizeof\n \ngatt_co2_val\n,\n \ngatt_co2_val\n,\n \ngatt_co2_val_len\n);\n \nreturn\n \nrc\n;\n } \nelse\n \nif\n (\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n) {\n \nrc\n \n=\n \nos_mbuf_append\n(\nctxt-\nom\n, \ngatt_co2_val\n,\n \nsizeof\n \ngatt_co2_val\n);\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \nBLE_ATT_ERR_INSUFFICIENT_RES\n;\n }\n\n \ndefault\n:\n\n \nassert\n(\n0\n);\n \nreturn\n \nBLE_ATT_ERR_UNLIKELY\n;\n }\n}\n\n\n\n\n\nNow it's time to go into our \napps/air_quality/src/main.c\n and change how we read CO\n2\n readings and \nrespond to requests. \n\n\nWe'll need a task handler with an event queue for the CO\n2\n readings -- they were handled by the shell task in the previous tutorial but now it needs to be replaced by a different handler as shown below.\n\n\n/* CO2 Task settings */\n\n\n#define CO2_TASK_PRIO 5\n\n\n#define CO2_STACK_SIZE (OS_STACK_ALIGN(336))\n\n\nstruct\n \nos_eventq\n \nco2_evq\n;\n\nstruct\n \nos_task\n \nco2_task\n;\n\nbssnz_t\n \nos_stack_t\n \nco2_stack\n[\nCO2_STACK_SIZE\n];\n\n\n\n\n\nAnd of course we'll need to go to our \nmain()\n and do all the standard task and event setup we\nnormally do by adding the following. Again, remember to delete all the shell event queues and tasks.\n\n\n/* Initialize sensor eventq */\n\n\nos_eventq_init\n(\nco2_evq\n);\n\n\n/* Create the CO2 reader task. \n\n\n * All sensor reading operations are performed in this task.\n\n\n */\n\n\nos_task_init\n(\nco2_task\n, \nsensor\n, \nco2_task_handler\n,\n \nNULL\n, \nCO2_TASK_PRIO\n, \nOS_WAIT_FOREVER\n,\n \nco2_stack\n, \nCO2_STACK_SIZE\n);\n\n\n\n\n\nWe'll also need to add a task handler -- since we initialized it above:\n\n\n/**\n\n\n * Event loop for the sensor task.\n\n\n */\n\n\nstatic\n \nvoid\n\n\nco2_task_handler\n(\nvoid\n \n*unused\n)\n{ \n \nwhile\n (\n1\n) {\n \nco2_read_event\n();\n \n/* Wait 2 second */\n\n \nos_time_delay\n(\nOS_TICKS_PER_SEC\n \n*\n \n2\n);\n\n }\n}\n\n\n\n\n\nAnd finally, we'll take care of that \nco2_read_event()\n function:\n\n\nint\n\n\nco2_read_event\n(\nvoid\n)\n{\n \nint\n \nvalue\n;\n \nenum\n \nsenseair_read_type\n \ntype\n \n=\n \nSENSEAIR_CO2\n;\n \nuint16_t\n \nchr_val_handle\n;\n \nint\n \nrc\n;\n\n \nvalue\n \n=\n \nsenseair_read\n(\ntype\n);\n \nif\n (\nvalue\n \n=\n \n0\n) {\n \nconsole_printf\n(\nGot %d\\n\n, \nvalue\n);\n } \nelse\n {\n \nconsole_printf\n(\nError while reading: %d\\n\n, \nvalue\n);\n \ngoto\n \nerr\n;\n }\n \ngatt_co2_val\n \n=\n \nvalue\n;\n \nrc\n \n=\n \nble_gatts_find_chr\n(\ngatt_svr_svc_co2_uuid\n.\nu\n, \nBLE_UUID16_DECLARE\n(\nCO2_SNS_VAL\n), \nNULL\n, \nchr_val_handle\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nble_gatts_chr_updated\n(\nchr_val_handle\n);\n \nreturn\n (\n0\n);\n\nerr\n:\n \nreturn\n (\nrc\n);\n}\n\n\n\n\n\nYou'll notice that it looks eeirily similar to a portion of the shell event we created \nearlier. This one simply reads and updates the CO\n2\n value and sends that over BLE to any\nconnected clients instead. \n\n\nWe can now build, create-image and load the app onto our Arduino Primo board, and then \nconnect and see the updated values! The image below shows the results using MyNewt Sensor Reader,\na Mac OS X app developed for connecting to MyNewt devices over Bluetooth but you can also use LightBlue\nor any other application that can connect to, and read, Bluetooth data.\n\n\n\n\nCongratulations!!",
- "title": "BLE-enabled Air Quality Sensor"
- },
- {
- "location": "/os/tutorials/air_quality_ble/#air-quality-sensor-project-via-bluetooth",
- "text": "This is a follow-on project to the Basic Air Quality Sensor project; so it is\nassumed that you have worked through that project and have your CO 2 sensor working properly with\nyour Arduino Primo board. So let's get started making this thing Bluetooth enabled!",
- "title": "Air quality sensor project via Bluetooth"
- },
- {
- "location": "/os/tutorials/air_quality_ble/#add-bluetooth-gatt-services",
- "text": "Since we already built the previous demo on the bluetooth peripheral basic\napp most of the bluetooth plumbing has already been taken care of for us. What's left is for us\nto add the required GATT services for advertising the Carbon Dioxide sensor so that\nother devices can get those values. First, we'll define the GATT Services in apps/air_quality/src/bleprph.h . /* Sensor Data */ /* e761d2af-1c15-4fa7-af80-b5729002b340 */ static const ble_uuid128_t gatt_svr_svc_co2_uuid = \n BLE_UUID128_INIT ( 0x40 , 0xb3 , 0x20 , 0x90 , 0x72 , 0xb5 , 0x80 , 0xaf ,\n 0xa7 , 0x4f , 0x15 , 0x1c , 0xaf , 0xd2 , 0x61 , 0xe7 ); #define CO2_SNS_TYPE 0xDEAD #define CO2_SNS_STRING SenseAir K30 CO2 Sensor #define CO2_SNS_VAL 0xBEAD uint16_t gatt_co2_val ; You can use any hex values you choose for the sensor type and sensor values, and you can \neven forget the sensor type and sensor string definitions altogether but they make\nthe results look nice in our Bluetooth App for Mac OS X and iOS. Next we'll add those services to apps/air_quality/src/gatt_svr.c . static int gatt_svr_sns_access ( uint16_t conn_handle , uint16_t attr_handle ,\n struct ble_gatt_access_ctxt *ctxt ,\n void *arg ); static uint16_t gatt_co2_val_len ; Make sure it is added as primary service. static const struct ble_gatt_svc_def gatt_svr_svcs [] = {\n {\n /*** Service: Security test. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid = gatt_svr_svc_sec_test_uuid . u ,\n . characteristics = ( struct ble_gatt_chr_def []) { {\n /*** Characteristic: Random number generator. */ \n . uuid = gatt_svr_chr_sec_test_rand_uuid . u ,\n . access_cb = gatt_svr_chr_access_sec_test ,\n . flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_READ_ENC ,\n }, {\n /*** Characteristic: Static value. */ \n . uuid = gatt_svr_chr_sec_test_static_uuid ,. u \n . access_cb = gatt_svr_chr_access_sec_test ,\n . flags = BLE_GATT_CHR_F_READ | \n BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_WRITE_ENC ,\n }, {\n 0 , /* No more characteristics in this service. */ \n } },\n },\n {\n /*** CO2 Level Notification Service. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid = gatt_svr_svc_co2_uuid . u ,\n . characteristics = ( struct ble_gatt_chr_def []) { {\n . uuid = BLE_UUID16_DECLARE ( CO2_SNS_TYPE ),\n . access_cb = gatt_svr_sns_access ,\n . flags = BLE_GATT_CHR_F_READ ,\n }, {\n . uuid = BLE_UUID16_DECLARE ( CO2_SNS_VAL ),\n . access_cb = gatt_svr_sns_access ,\n . flags = BLE_GATT_CHR_F_NOTIFY ,\n }, {\n 0 , /* No more characteristics in this service. */ \n } },\n },\n\n {\n 0 , /* No more services. */ \n },\n }; Next we need to tell the GATT Server how to handle requests for CO 2 readings : sstatic int gatt_svr_sns_access ( uint16_t conn_handle , uint16_t attr_handle ,\n struct ble_gatt_access_ctxt *ctxt ,\n void *arg )\n{\n uint16_t uuid16 ;\n int rc ;\n\n uuid16 = ble_uuid_u16 ( ctxt- chr- uuid );\n\n switch ( uuid16 ) {\n case CO2_SNS_TYPE :\n assert ( ctxt- op == BLE_GATT_ACCESS_OP_READ_CHR );\n rc = os_mbuf_append ( ctxt- om , CO2_SNS_STRING , sizeof CO2_SNS_STRING );\n BLEPRPH_LOG ( INFO , CO2 SENSOR TYPE READ: %s\\n , CO2_SNS_STRING );\n return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES ;\n\n case CO2_SNS_VAL :\n if ( ctxt- op == BLE_GATT_ACCESS_OP_WRITE_CHR ) {\n rc = gatt_svr_chr_write ( ctxt- om , 0 ,\n sizeof gatt_co2_val ,\n gatt_co2_val ,\n gatt_co2_val_len );\n return rc ;\n } else if ( ctxt- op == BLE_GATT_ACCESS_OP_READ_CHR ) {\n rc = os_mbuf_append ( ctxt- om , gatt_co2_val ,\n sizeof gatt_co2_val );\n return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES ;\n }\n\n default : \n assert ( 0 );\n return BLE_ATT_ERR_UNLIKELY ;\n }\n} Now it's time to go into our apps/air_quality/src/main.c and change how we read CO 2 readings and \nrespond to requests. We'll need a task handler with an event queue for the CO 2 readings -- they were handled by the shell task in the previous tutorial but now it needs to be replaced by a different handler as shown below. /* CO2 Task settings */ #define CO2_TASK_PRIO 5 #define CO2_STACK_SIZE (OS_STACK_ALIGN(336)) struct os_eventq co2_evq ; struct os_task co2_task ; bssnz_t os_stack_t co2_stack [ CO2_STACK_SIZE ]; And of course we'll need to go to our main() and do all the standard task and event setup we\nnormally do by adding the following. Again, remember to delete all the shell event queues and tasks. /* Initialize sensor eventq */ os_eventq_init ( co2_evq ); /* Create the CO2 reader task. * All sensor reading operations are performed in this task. */ os_task_init ( co2_task , sensor , co2_task_handler ,\n NULL , CO2_TASK_PRIO , OS_WAIT_FOREVER ,\n co2_stack , CO2_STACK_SIZE ); We'll also need to add a task handler -- since we initialized it above: /** * Event loop for the sensor task. */ static void co2_task_handler ( void *unused )\n{ \n while ( 1 ) {\n co2_read_event ();\n /* Wait 2 second */ \n os_time_delay ( OS_TICKS_PER_SEC * 2 );\n\n }\n} And finally, we'll take care of that co2_read_event() function: int co2_read_event ( void )\n{\n int value ;\n enum senseair_read_type type = SENSEAIR_CO2 ;\n uint16_t chr_val_handle ;\n int rc ;\n\n value = senseair_read ( type );\n if ( value = 0 ) {\n console_printf ( Got %d\\n , value );\n } else {\n console_printf ( Error while reading: %d\\n , value );\n goto err ;\n }\n gatt_co2_val = value ;\n rc = ble_gatts_find_chr ( gatt_svr_svc_co2_uuid . u , BLE_UUID16_DECLARE ( CO2_SNS_VAL ), NULL , chr_val_handle );\n assert ( rc == 0 );\n ble_gatts_chr_updated ( chr_val_handle );\n return ( 0 ); err :\n return ( rc );\n} You'll notice that it looks eeirily similar to a portion of the shell event we created \nearlier. This one simply reads and updates the CO 2 value and sends that over BLE to any\nconnected clients instead. We can now build, create-image and load the app onto our Arduino Primo board, and then \nconnect and see the updated values! The image below shows the results using MyNewt Sensor Reader,\na Mac OS X app developed for connecting to MyNewt devices over Bluetooth but you can also use LightBlue\nor any other application that can connect to, and read, Bluetooth data. Congratulations!!",
- "title": "Add Bluetooth GATT Services"
- },
- {
- "location": "/os/tutorials/nrf52_adc/",
- "text": "Adding an Analog Sensor on nRF52\n\n\n\n\nObjective\n\n\nWe will be adding an analog sensor to the NRF52DK development board and using the Analog to Digital Converter\n(ADC) to read the values from the sensor. It's also using Bluetooth to allow you to connect to the app and\nread the value of the sensor. Please see the following section for the required hardware\nin order to complete this tutorial.\n\n\n\n\nHardware needed\n\n\n\n\nnRF52 Development Kit (one of the following)\n\n\nDev Kit from Nordic - PCA 10040\n\n\nEval Kit from Rigado - BMD-300-EVAL-ES\n\n\n\n\n\n\neTape Liquid Sensor -- buy from \nAdafruit\n\n\nLaptop running Mac OS\n\n\nIt is assumed you have already installed newt tool. \n\n\nIt is assumed you already installed native tools as described \nhere\n\n\n\n\n\n\nCreate a project.\n\n\nCreate a new project to hold your work. For a deeper understanding, you can read about project creation in \n\nGet Started -- Creating Your First Project\n\nor just follow the commands below.\n\n\n $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myadc\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myadc...\n Project myadc successfully created.\n $ cd myadc\n\n\n\n\n\n\n\nAdd Additional Repositories\n\n\nThe board-specific libraries for the NRF52dk board are in an external repository at present, so\nyou'll need to include that remote repository and install it as well. If you're not familiar\nwith using repositories, see the section on \nrepositories\n before\ncontinuing. Or just copy and paste the following.\n\n\nIn your \nproject.yml\n file, add \nmynewt_nordic\n to the \nproject.repositories\n section, and \nthen add the proper repository definition. When you're done, your \nproject.yml\n file\nshould look like this:\n\n\nproject.name: \nmy_project\n\n\nproject.repositories:\n - apache-mynewt-core\n\n - mynewt_nordic\n\n\n# Use github\ns distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\nrepository.mynewt_nordic:\n\n type: github\n\n vers: 1-latest\n\n user: runtimeco\n\n repo: mynewt_nordic\n\n\n\n\n\n\n\nInstall Everything\n\n\nNow that you have defined the needed repositories, it's time to install everything so\nthat you can get started.\n\n\n $ newt install -v \n apache-mynewt-core\n Downloading repository description for apache-mynewt-core... success!\n ...\n apache-mynewt-core successfully installed version 0.9.0-none\n ...\n mynewt_nordic\n Downloading repository description for mynewt_nordic... success!\n ...\n mynewt_nordic successfully installed version 0.9.9-none\n\n\n\n\n\n\n\nCreate the targets\n\n\nCreate two targets - one for the bootloader and one for the nrf52 board. \n\n\n\nNote: The correct bsp must be chosen for the board you are using. \n\n\n\n\nFor the Nordic Dev Kit choose @apache-mynewt-core/hw/bsp/nrf52dk instead (in the highlighted lines)\n\n\nFor the Rigado Eval Kit choose @apache-mynewt-core/hw/bsp/bmd300eval instead (in the highlighted lines)\n\n\n\n\nFor the app itself we're going to extend the \nbleprph\n app so that we\nget the Bluetooth communications built in, so the first thing we'll need to do is copy that app\ninto our own app directory:\n\n\n$ mkdir -p apps/nrf52_adc\n$ cp -Rp repos/apache-mynewt-core/apps/bleprph/* apps/nrf52_adc\n\n\n\n\n\nNext, you'll modify the \npkg.yml\n file for your app. Note the change in \npkg.name\n and \npkg.description\n. Also make sure that you specify the full path of all the packages with the prefix \n@apache-mynewt-core/\n as shown in the third highlighted line.\n\n\n$ cat apps/nrf52_adc/pkg.yml\n...\n\npkg.name: apps/nrf52_adc\n\npkg.type: app\n\npkg.description: Simple BLE peripheral application for ADC Sensors.\n\npkg.author: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps: \n\n - \n@apache-mynewt-core/boot/split\n\n\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/mgmt/imgmgr\n\n - \n@apache-mynewt-core/mgmt/newtmgr\n\n - \n@apache-mynewt-core/mgmt/newtmgr/transport/ble\n\n - \n@apache-mynewt-core/net/nimble/controller\n\n - \n@apache-mynewt-core/net/nimble/host\n\n - \n@apache-mynewt-core/net/nimble/host/services/ans\n\n - \n@apache-mynewt-core/net/nimble/host/services/gap\n\n - \n@apache-mynewt-core/net/nimble/host/services/gatt\n\n - \n@apache-mynewt-core/net/nimble/host/store/ram\n\n - \n@apache-mynewt-core/net/nimble/transport/ram\n\n - \n@apache-mynewt-core/sys/console/full\n\n - \n@apache-mynewt-core/sys/log/full\n\n - \n@apache-mynewt-core/sys/stats/full\n\n - \n@apache-mynewt-core/sys/sysinit\n\n - \n@apache-mynewt-core/sys/id\n\n\n\n\n\n\nGreat! We have our very own app so let's make sure we have all of our targets set\ncorrectly:\n\n\n$ newt target create nrf52_adc\n$ newt target set nrf52_adc app=apps/nrf52_adc\n\nTarget targets/nrf52_adc successfully set target.app to apps/nrf52_adc\n\n$ newt target set nrf52_adc bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_adc build_profile=debug\n\n$ newt target create nrf52_boot\n\n$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot\n\n$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_boot build_profile=optimized\n\n$ newt target show \ntargets/nrf52_adc\n app=apps/nrf52_adc\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=debug\ntargets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized\n\n\n\n\n\n\nNote: If you've already built and installed a bootloader for your NRF52dk then you do\nnot need to create a target for it here, or build and load it as below. \n\n\n\n\nBuild the target executables\n\n\n$ newt build nrf52_boot\n...\nCompiling boot.c\nArchiving boot.a\nLinking boot.elf\nApp successfully built: ~/dev/myadc/bin/nrf52_boot/apps/boot/boot.elf\n\n\n\n\n\n$ newt build nrf52_adc\n...\nCompiling main.c\nArchiving nrf52_adc.a\nLinking nrf52_adc.elf\nApp successfully built: ~/dev/myadc/bin/nrf52_adc/apps/nrf52_adc/nrf52_adc.elf\n\n\n\n\n\n\n\nSign and create the nrf52_adc application image\n\n\nYou must sign and version your application image to download it using newt to the board. \nUse the newt create-image command to perform this action. You may assign an arbitrary \nversion (e.g. 1.0.0) to the image.\n\n\n$ newt create-image nrf52_adc 1.0.0\nApp image successfully generated: ~/dev/myadc/bin/nrf52_adc/apps/nrf52_adc/nrf52_adc.img\nBuild manifest: ~/dev/myadc/bin/nrf52_adc/apps/nrf52_adc/manifest.json\n\n\n\n\n\n\n\nConnect the board\n\n\nConnect the evaluation board via micro-USB to your PC via USB cable.\n\n\n\n\nDownload to the target\n\n\nDownload the bootloader first and then the nrf52_adc executable to the target platform. \nDon't forget to reset the board if you don't see the LED blinking right away!\n\n\n$ newt load nrf52_boot\n$ newt load nrf52_adc\n\n\n\n\n\n\n\nNote:\n If you want to erase the flash and load the image again, you can use JLinkExe to issue an \nerase\n command.\n\n\n$ JLinkExe -device nRF52 -speed 4000 -if SWD\nSEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)\nDLL version V5.12c, compiled Apr 21 2016 16:05:45\n\nConnecting to J-Link via USB...O.K.\nFirmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17\nHardware version: V1.00\nS/N: 682863966\nVTref = 3.300V\n\n\nType \nconnect\n to establish a target connection, \n?\n for help\nJ-Link\nerase\nCortex-M4 identified.\nErasing device (0;?i?)...\nComparing flash [100%] Done.\nErasing flash [100%] Done.\nVerifying flash [100%] Done.\nJ-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)\nErasing done.\nJ-Link\nexit\n$\n\n\n\n\n\n\n\nSo you have a BLE app, but really all you've done is change the name of the \nbleprph\n app to \nnrf52_adc\n and load that.\nNot all that impressive, and it certainly won't read an Analog Sensor right now. So let's do that next. In order to \nread an ADC sensor, and since the ADC package is in an external, licensed, repository, we'll create a driver for it\nhere in our app that will leverage the existing driver in the external repository. It adds another layer of \nindirection, but it will also give us a look at building our own driver, so we'll do it this way. \n\n\n\n\nBuilding a Driver\n\n\nThe first thing to do is to create the directory structure for your driver:\n\n\n[user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/myadc/include/myadc\n[user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/myadc/src\n\n\n\n\n\nNow you can add the files you need. You'll need a pkg.yml to describe the driver, and then header stub followed by source stub.\n\n\n[user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/myadc/pkg.yml\n\n\n\n\n\n#\n\n\n# Licensed to the Apache Software Foundation (ASF) under one\n\n\n# or more contributor license agreements. See the NOTICE file\n\n\n# distributed with this work for additional information\n\n\n# regarding copyright ownership. The ASF licenses this file\n\n\n# to you under the Apache License, Version 2.0 (the\n\n\n# \nLicense\n); you may not use this file except in compliance\n\n\n# with the License. You may obtain a copy of the License at\n\n\n# \n\n\n# http:\n//www.apache.org/licenses/LICENSE-2.0\n\n\n#\n\n\n# Unless required by applicable law or agreed to in writing,\n\n\n# software distributed under the License is distributed on an\n\n\n# \nAS IS\n BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n\n\n# KIND, either express or implied. See the License for the\n\n\n# specific language governing permissions and limitations\n\n\n# under the License.\n\n\n#\n\n\npkg\n.\nname\n: \nlibs/my_drivers/myadc\n\n\npkg\n.\ndeps\n:\n \n-\n \n@apache-mynewt-core/hw/hal\n\n \n-\n \n@mynewt_nordic/hw/drivers/adc/adc_nrf52\n\n\n\n\n\n\nFirst, let's create the required header file \nmyadc.h\n in the includes directory i.e. \nlibs/my_drivers/myadc/include/myadc/myadc.h\n.\nIt's a pretty straightforward header file, since we only need to do 2 things:\n\n\n\n\nInitialize the ADC device\n\n\nRead ADC Values\n\n\n\n\n#ifndef _NRF52_ADC_H_\n\n\n#define _NRF52_ADC_H_\n\n\n\nvoid\n \n*\n \nadc_init\n(\nvoid\n);\n\nint\n \nadc_read\n(\nvoid\n \n*buffer\n, \nint\n \nbuffer_len\n);\n\n\n#endif \n/* _NRF52_ADC_H_ */\n\n\n\n\n\n\nNext we'll need a corresponding source file \nmyadc.c\n in the src directory. This is where\nwe'll implement the specifics of the driver:\n\n\n#include\n \nassert.h\n\n\n#include\n \nos/os.h\n\n\n/* ADC */\n\n\n#include\n \nmyadc/myadc.h\n\n\n#include\n \nnrf.h\n\n\n#include\n \napp_util_platform.h\n\n\n#include\n \napp_error.h\n\n\n#include\n \nadc/adc.h\n\n\n#include\n \nadc_nrf52/adc_nrf52.h\n\n\n#include\n \nnrf_drv_saadc.h\n\n\n\n\n#define ADC_NUMBER_SAMPLES (2)\n\n\n#define ADC_NUMBER_CHANNELS (1)\n\n\n\nnrf_drv_saadc_config_t\n \nadc_config\n \n=\n \nNRF_DRV_SAADC_DEFAULT_CONFIG\n;\n\n\nstruct\n \nadc_dev\n \n*adc\n;\n\nuint8_t\n \n*sample_buffer1\n;\n\nuint8_t\n \n*sample_buffer2\n;\n\n\nstatic\n \nstruct\n \nadc_dev\n \nos_bsp_adc0\n;\n\nstatic\n \nnrf_drv_saadc_config_t\n \nos_bsp_adc0_config\n \n=\n {\n .\nresolution\n \n=\n \nMYNEWT_VAL\n(\nADC_0_RESOLUTION\n),\n .\noversample\n \n=\n \nMYNEWT_VAL\n(\nADC_0_OVERSAMPLE\n),\n .\ninterrupt_priority\n \n=\n \nMYNEWT_VAL\n(\nADC_0_INTERRUPT_PRIORITY\n),\n};\n\nvoid\n \n*\n\n\nadc_init\n(\nvoid\n)\n{\n \nint\n \nrc\n \n=\n \n0\n;\n\n \nrc\n \n=\n \nos_dev_create\n((\nstruct\n \nos_dev\n \n*\n) \nos_bsp_adc0\n, \nadc0\n,\n \nOS_DEV_INIT_KERNEL\n, \nOS_DEV_INIT_PRIO_DEFAULT\n,\n \nnrf52_adc_dev_init\n, \nos_bsp_adc0_config\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nnrf_saadc_channel_config_t\n \ncc\n \n=\n \nNRF_DRV_SAADC_DEFAULT_CHANNEL_CONFIG_SE\n(\nNRF_SAADC_INPUT_AIN1\n);\n \ncc\n.\ngain\n \n=\n \nNRF_SAADC_GAIN1_6\n;\n \ncc\n.\nreference\n \n=\n \nNRF_SAADC_REFERENCE_INTERNAL\n;\n \nadc\n \n=\n (\nstruct\n \nadc_dev\n \n*\n) \nos_dev_open\n(\nadc0\n, \n0\n, \nadc_config\n);\n \nassert\n(\nadc\n \n!=\n \nNULL\n);\n \nadc_chan_config\n(\nadc\n, \n0\n, \ncc\n);\n \nsample_buffer1\n \n=\n \nmalloc\n(\nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nsample_buffer2\n \n=\n \nmalloc\n(\nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nmemset\n(\nsample_buffer1\n, \n0\n, \nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nmemset\n(\nsample_buffer2\n, \n0\n, \nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nadc_buf_set\n(\nadc\n, \nsample_buffer1\n, \nsample_buffer2\n,\n \nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nreturn\n \nadc\n;\n}\n\n\n\nint\n\n\nadc_read\n(\nvoid\n \n*buffer\n, \nint\n \nbuffer_len\n)\n{\n \nint\n \ni\n;\n \nint\n \nadc_result\n;\n \nint\n \nmy_result_mv\n \n=\n \n0\n;\n \nint\n \nrc\n;\n \nfor\n (\ni\n \n=\n \n0\n; \ni\n \n \nADC_NUMBER_SAMPLES\n; \ni++\n) {\n \nrc\n \n=\n \nadc_buf_read\n(\nadc\n, \nbuffer\n, \nbuffer_len\n, \ni\n, \nadc_result\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \ngoto\n \nerr\n;\n }\n \nmy_result_mv\n \n=\n \nadc_result_mv\n(\nadc\n, \n0\n, \nadc_result\n);\n } \n \nadc_buf_release\n(\nadc\n, \nbuffer\n, \nbuffer_len\n);\n \nreturn\n \nmy_result_mv\n;\n\nerr\n:\n \nreturn\n (\nrc\n);\n}\n\n\n\n\n\nThere's a lot going on in here, so let's walk through it step by step. \n\n\nFirst, we define a default configuration, with the resolution, oversample and interrupt priority. You'll see\nthat these are \nMYNEWT_VAL\n values, which means that we'll define them shortly in\na \nsyscfg.yml\n file to be passed to the compiler at build time. \n\n\nstatic\n \nstruct\n \nadc_dev\n \nos_bsp_adc0\n;\n\nstatic\n \nnrf_drv_saadc_config_t\n \nos_bsp_adc0_config\n \n=\n {\n .\nresolution\n \n=\n \nMYNEWT_VAL\n(\nADC_0_RESOLUTION\n),\n .\noversample\n \n=\n \nMYNEWT_VAL\n(\nADC_0_OVERSAMPLE\n),\n .\ninterrupt_priority\n \n=\n \nMYNEWT_VAL\n(\nADC_0_INTERRUPT_PRIORITY\n),\n};\n\n\n\n\n\nNext, in \nadc_init()\n , we need to tell the OS to create the device.\n\n\nvoid\n \n*\n\n\nadc_init\n(\nvoid\n)\n{\n \nint\n \nrc\n \n=\n \n0\n;\n\n \nrc\n \n=\n \nos_dev_create\n((\nstruct\n \nos_dev\n \n*\n) \nos_bsp_adc0\n, \nadc0\n,\n \nOS_DEV_INIT_KERNEL\n, \nOS_DEV_INIT_PRIO_DEFAULT\n,\n \nnrf52_adc_dev_init\n, \nos_bsp_adc0_config\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nnrf_saadc_channel_config_t\n \ncc\n \n=\n \nNRF_DRV_SAADC_DEFAULT_CHANNEL_CONFIG_SE\n(\nNRF_SAADC_INPUT_AIN1\n);\n \ncc\n.\ngain\n \n=\n \nNRF_SAADC_GAIN1_6\n;\n \ncc\n.\nreference\n \n=\n \nNRF_SAADC_REFERENCE_INTERNAL\n;\n \nadc\n \n=\n (\nstruct\n \nadc_dev\n \n*\n) \nos_dev_open\n(\nadc0\n, \n0\n, \nadc_config\n);\n \nassert\n(\nadc\n \n!=\n \nNULL\n);\n \nadc_chan_config\n(\nadc\n, \n0\n, \ncc\n);\n \nsample_buffer1\n \n=\n \nmalloc\n(\nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nsample_buffer2\n \n=\n \nmalloc\n(\nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nmemset\n(\nsample_buffer1\n, \n0\n, \nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nmemset\n(\nsample_buffer2\n, \n0\n, \nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nadc_buf_set\n(\nadc\n, \nsample_buffer1\n, \nsample_buffer2\n,\n \nadc_buf_size\n(\nadc\n, \nADC_NUMBER_CHANNELS\n, \nADC_NUMBER_SAMPLES\n));\n \nreturn\n \nadc\n;\n}\n\n\n\n\n\nA few things need to be said about this part, as it is the most confusing. First, \nwe're using a \ndefault\n configuration for the ADC Channel via the \nNRF_DRV_SAADC_DEFAULT_CHANNEL_CONFIG_SE\n\nmacro. The important part here is that we're actually using \nAIN1\n. I know what you're thinking, \"But \nwe want ADC-0!\" and that's true. The board is actually labelled 'A0, A1, A2' etc., and the actual pin \nnumbers are also listed on the board, which seems handy. At first. But it gets messy very quickly.\n\n\nIf you try to use AIN0, and then go poke around in the registers while this is running, \n\n\n(gdb) p/x {NRF_SAADC_Type}0x40007000\n...\n CH = {{\n PSELP = 0x1,\n PSELN = 0x0,\n CONFIG = 0x20000,\n LIMIT = 0x7fff8000\n }, \n\n\n\n\n\nYou'll see that the pin for channel 0 is set to 1, which corresponds to AIN0, but that's \nNOT\n\nthe same as A0 -- pin P0.03, the one we're using. For that, you use AIN1, which would set the\npin value to 2. Messy. Someone, somewhere, thought this made sense. \n\n\nThe only other thing to note here is that we're using the internal reference voltage, rather than\nsetting our own. There's nothing wrong with that, but since we are, we'll have to crank up\nthe gain a bit by using \nNRF_SAADC_GAIN1_6\n.\n\n\nThen, in \nadc_read()\n we will take readings, convert the raw readings to \na millivolt equivalent, and return the result. \n\n\nint\n\n\nadc_read\n(\nvoid\n \n*buffer\n, \nint\n \nbuffer_len\n)\n{\n \nint\n \ni\n;\n \nint\n \nadc_result\n;\n \nint\n \nmy_result_mv\n \n=\n \n0\n;\n \nint\n \nrc\n;\n \nfor\n (\ni\n \n=\n \n0\n; \ni\n \n \nADC_NUMBER_SAMPLES\n; \ni++\n) {\n \nrc\n \n=\n \nadc_buf_read\n(\nadc\n, \nbuffer\n, \nbuffer_len\n, \ni\n, \nadc_result\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \ngoto\n \nerr\n;\n }\n \nmy_result_mv\n \n=\n \nadc_result_mv\n(\nadc\n, \n0\n, \nadc_result\n);\n } \n \nadc_buf_release\n(\nadc\n, \nbuffer\n, \nbuffer_len\n);\n \nreturn\n \nmy_result_mv\n;\n\nerr\n:\n \nreturn\n (\nrc\n);\n}\n\n\n\n\n\nFinally, we'll need some settings for our driver, as mentioned earlier. In the \nmyadc\n directory\nyou'll need to add a \nsyscfg.yml\n file:\n\n\n# Package: libs/my_driver/myadc\n\nsyscfg.defs:\n ADC_0:\n description: \nTBD\n\n value: 1\n ADC_0_RESOLUTION:\n description: \nTBD\n\n value: \nSAADC_CONFIG_RESOLUTION\n\n ADC_0_OVERSAMPLE:\n description: \nTBD\n\n value: \nSAADC_CONFIG_OVERSAMPLE\n\n ADC_0_INTERRUPT_PRIORITY:\n description: \nTBD\n\n value: \nSAADC_CONFIG_IRQ_PRIORITY\n\n\n\n\n\n\nOnce that's all done, you should have a working ADC Driver for your NRF52DK board. The last step in getting the driver set up is to include it in the package dependency defined by \npkg.deps\n in the \npkg.yml\n file of your app. Add it in \napps/nrf52_adc/pkg.yml\n as shown by the highlighted line below.\n\n\n# Licensed to the Apache Software Foundation (ASF) under one\n# \nsnip\n\n\npkg.name: apps/nrf52_adc\npkg.type: app\npkg.description: Simple BLE peripheral application for ADC sensor.\npkg.author: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps: \n - \n@apache-mynewt-core/boot/split\n\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/mgmt/imgmgr\n\n - \n@apache-mynewt-core/mgmt/newtmgr\n\n - \n@apache-mynewt-core/mgmt/newtmgr/transport/ble\n\n - \n@apache-mynewt-core/net/nimble/controller\n\n - \n@apache-mynewt-core/net/nimble/host\n\n - \n@apache-mynewt-core/net/nimble/host/services/ans\n\n - \n@apache-mynewt-core/net/nimble/host/services/gap\n\n - \n@apache-mynewt-core/net/nimble/host/services/gatt\n\n - \n@apache-mynewt-core/net/nimble/host/store/ram\n\n - \n@apache-mynewt-core/net/nimble/transport/ram\n\n - \n@apache-mynewt-core/sys/console/full\n\n - \n@apache-mynewt-core/sys/log/full\n\n - \n@apache-mynewt-core/sys/stats/full\n\n - \n@apache-mynewt-core/sys/sysinit\n\n - \n@apache-mynewt-core/sys/id\n\n\n - libs/my_drivers/myadc\n\n\n\n\n\n\n\nCreating the ADC Task\n\n\nNow that the driver is done, we'll need to add calls to the main app's \nmain.c\n file, as well\nas a few other things. First, we'll need to update the includes, and add a task for our ADC\nsampling.\n\n\n#include\n \nmyadc/myadc.h\n\n...\n\n/* ADC Task settings */\n\n\n#define ADC_TASK_PRIO 5\n\n\n#define ADC_STACK_SIZE (OS_STACK_ALIGN(336))\n\n\nstruct\n \nos_eventq\n \nadc_evq\n;\n\nstruct\n \nos_task\n \nadc_task\n;\n\nbssnz_t\n \nos_stack_t\n \nadc_stack\n[\nADC_STACK_SIZE\n];\n\n\n\n\n\nNext we'll need o initialize the task \nevent_q\n so we'll add the highlighted code to \nmain()\n as shown below:\n\n\n \n/* Set the default device name. */\n\n \nrc\n \n=\n \nble_svc_gap_device_name_set\n(\nnimble-adc\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nconf_load\n();\n\n\n \n/* Initialize adc sensor task eventq */\n\n\n \nos_eventq_init\n(\nadc_evq\n);\n\n\n\n \n/* Create the ADC reader task. \n\n\n * All sensor operations are performed in this task.\n\n\n */\n\n\n \nos_task_init\n(\nadc_task\n, \nsensor\n, \nadc_task_handler\n,\n\n \nNULL\n, \nADC_TASK_PRIO\n, \nOS_WAIT_FOREVER\n,\n\n \nadc_stack\n, \nADC_STACK_SIZE\n);\n\n\n\n\n\nWe'll need that \nadc_task_handler()\n function to exist, and that's where we'll initialize the ADC Device\nand set the event handler. In the task's while() loop, we'll just make a call to \nadc_sample()\n to cause\nthe ADC driver to sample the adc device.\n\n\n/**\n\n\n * Event loop for the sensor task.\n\n\n */\n\n\nstatic\n \nvoid\n\n\nadc_task_handler\n(\nvoid\n \n*unused\n)\n{\n \nstruct\n \nadc_dev\n \n*adc\n;\n \nint\n \nrc\n;\n \n/* ADC init */\n\n \nadc\n \n=\n \nadc_init\n();\n \nrc\n \n=\n \nadc_event_handler_set\n(\nadc\n, \nadc_read_event\n, (\nvoid\n \n*\n) \nNULL\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nwhile\n (\n1\n) {\n \nadc_sample\n(\nadc\n);\n \n/* Wait 2 second */\n\n \nos_time_delay\n(\nOS_TICKS_PER_SEC\n \n*\n \n2\n);\n }\n}\n\n\n\n\n\nAbove the \nadc_task_handler\n, add code to handle the \nadc_read_event()\n calls:\n\n\nint\n\n\nadc_read_event\n(\nstruct\n \nadc_dev\n \n*dev\n, \nvoid\n \n*arg\n, \nuint8_t\n \netype\n,\n \nvoid\n \n*buffer\n, \nint\n \nbuffer_len\n)\n{\n \nint\n \nvalue\n;\n \nuint16_t\n \nchr_val_handle\n;\n \nint\n \nrc\n;\n\n \nvalue\n \n=\n \nadc_read\n(\nbuffer\n, \nbuffer_len\n);\n \nif\n (\nvalue\n \n=\n \n0\n) {\n \nconsole_printf\n(\nGot %d\\n\n, \nvalue\n);\n } \nelse\n {\n \nconsole_printf\n(\nError while reading: %d\\n\n, \nvalue\n);\n \ngoto\n \nerr\n;\n }\n \ngatt_adc_val\n \n=\n \nvalue\n;\n \nrc\n \n=\n \nble_gatts_find_chr\n(\ngatt_svr_svc_adc_uuid\n.\nu\n, \nBLE_UUID16_DECLARE\n(\nADC_SNS_VAL\n), \nNULL\n, \nchr_val_handle\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n \nble_gatts_chr_updated\n(\nchr_val_handle\n);\n \nreturn\n (\n0\n);\n\nerr\n:\n \nreturn\n (\nrc\n);\n} \n\n\n\n\n\nThis is where we actually read the ADC value and then update the BLE Characteristic for that value. \n\n\nBut wait, we haven't defined those BLE services and characteristics yet! Right, so don't try to build and run this\napp just yet or it will surely fail. Instead, move on to the next section and get all of those services \ndefined.\n\n\n\n\nBuilding the BLE Services\n\n\nIf the nrf52_adc app is going to be a Bluetooth-enabled sensor app that will allow you to read the value of the eTape Water Level Sensor\nvia Bluetooth we'll need to actually define those Services and Characteristics.\n\n\nAs with the \nble peripheral\n app, we will advertise a couple of values from our app. The first is\nnot strictly necessary, but it will help us build an iOS app later. We've defined a service and the characteristics in\nthat service in \nbleadc.h\n in the \napps/nrf52_adc/src/\n directory as follows:\n\n\n/* Sensor Data */\n\n\n/* e761d2af-1c15-4fa7-af80-b5729002b340 */\n\n\nstatic\n \nconst\n \nble_uuid128_t\n \ngatt_svr_svc_adc_uuid\n \n=\n\n \nBLE_UUID128_INIT\n(\n0x40\n, \n0xb3\n, \n0x20\n, \n0x90\n, \n0x72\n, \n0xb5\n, \n0x80\n, \n0xaf\n,\n \n0xa7\n, \n0x4f\n, \n0x15\n, \n0x1c\n, \n0xaf\n, \n0xd2\n, \n0x61\n, \n0xe7\n);\n\n#define ADC_SNS_TYPE 0xDEAD\n\n\n#define ADC_SNS_STRING \neTape Liquid Level Sensor\n\n\n#define ADC_SNS_VAL 0xBEAD\n\n\nextern\n \nuint16_t\n \ngatt_adc_val\n; \n\n\n\n\n\nThe first is the UUID of the service, followed by the 2 characteristics we are going to offer.\nThe first characteristic is going to advertise the \ntype\n of sensor we are advertising, and\nit will be a read-only characteristic. The second characteristic will be the sensor value\nitself, and we will allow connected devices to 'subscribe' to it in order to get \nconstantly-updated values.\n\n\nNote:\n You can choose any valid Characteristic UUIDs to go here. We're using these values\nfor illustrative purposes only.\n\n\nThe value that we'll be updating is also defined here as \ngatt_adc_val\n.\n\n\nIf we then go look at \ngatt_srv.c\n we can see the structure of the service and\ncharacteristic offering that we set up:\n\n\nstatic\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \ngatt_svr_svcs\n[] \n=\n {\n {\n \n/*** Service: Security test. */\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n .\nuuid\n \n=\n \ngatt_svr_svc_sec_test_uuid\n.\nu\n,\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n \n/*** Characteristic: Random number generator. */\n\n .\nuuid\n \n=\n \ngatt_svr_chr_sec_test_rand_uuid\n.\nu\n,\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_sec_test\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n \n|\n \nBLE_GATT_CHR_F_READ_ENC\n,\n }, {\n \n/*** Characteristic: Static value. */\n\n .\nuuid\n \n=\n \ngatt_svr_chr_sec_test_static_uuid\n.\nu\n,\n .\naccess_cb\n \n=\n \ngatt_svr_chr_access_sec_test\n,\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n \n|\n\n \nBLE_GATT_CHR_F_WRITE\n \n|\n \nBLE_GATT_CHR_F_WRITE_ENC\n,\n }, {\n \n0\n, \n/* No more characteristics in this service. */\n\n } },\n },\n\n {\n\n \n/*** ADC Level Notification Service. */\n\n\n .\ntype\n \n=\n \nBLE_GATT_SVC_TYPE_PRIMARY\n,\n\n .\nuuid\n \n=\n \ngatt_svr_svc_adc_uuid\n.\nu\n,\n\n .\ncharacteristics\n \n=\n (\nstruct\n \nble_gatt_chr_def\n[]) { {\n\n .\nuuid\n \n=\n \nBLE_UUID16_DECLARE\n(\nADC_SNS_TYPE\n),\n\n .\naccess_cb\n \n=\n \ngatt_svr_sns_access\n,\n\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_READ\n,\n\n }, {\n\n .\nuuid\n \n=\n \nBLE_UUID16_DECLARE\n(\nADC_SNS_VAL\n),\n\n .\naccess_cb\n \n=\n \ngatt_svr_sns_access\n,\n\n .\nflags\n \n=\n \nBLE_GATT_CHR_F_NOTIFY\n,\n\n }, {\n\n \n0\n, \n/* No more characteristics in this service. */\n\n\n } },\n\n },\n\n\n\n {\n \n0\n, \n/* No more services. */\n\n },\n};\n\n\n\n\n\nYou should recognize the first services from the \nBLE Peripheral\n\ntutorial earlier. We're just adding another Service, with 2 new Characteristics, to \nthat application.\n\n\nWe'll need to fill in the function that will be called for this service, \ngatt_srv_sns_access\n\nnext so that the service knows what to do.\n\n\nstatic\n \nint\n\n\ngatt_svr_sns_access\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nble_gatt_access_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n)\n{\n \nuint16_t\n \nuuid16\n;\n \nint\n \nrc\n;\n\n \nuuid16\n \n=\n \nble_uuid_u16\n(\nctxt-\nchr-\nuuid\n);\n\n \nswitch\n (\nuuid16\n) {\n \ncase\n \nADC_SNS_TYPE\n:\n \nassert\n(\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n);\n \nrc\n \n=\n \nos_mbuf_append\n(\nctxt-\nom\n, \nADC_SNS_STRING\n, \nsizeof\n \nADC_SNS_STRING\n);\n \nBLEPRPH_LOG\n(\nINFO\n, \nADC SENSOR TYPE READ: %s\\n\n, \nADC_SNS_STRING\n);\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \nBLE_ATT_ERR_INSUFFICIENT_RES\n;\n\n \ncase\n \nADC_SNS_VAL\n:\n \nif\n (\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_WRITE_CHR\n) {\n \nrc\n \n=\n \ngatt_svr_chr_write\n(\nctxt-\nom\n, \n0\n,\n \nsizeof\n \ngatt_adc_val\n,\n \ngatt_adc_val\n,\n \nNULL\n);\n \nreturn\n \nrc\n;\n } \nelse\n \nif\n (\nctxt-\nop\n \n==\n \nBLE_GATT_ACCESS_OP_READ_CHR\n) {\n \nrc\n \n=\n \nos_mbuf_append\n(\nctxt-\nom\n, \ngatt_adc_val\n,\n \nsizeof\n \ngatt_adc_val\n);\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \nBLE_ATT_ERR_INSUFFICIENT_RES\n;\n }\n\n \ndefault\n:\n\n \nassert\n(\n0\n);\n \nreturn\n \nBLE_ATT_ERR_UNLIKELY\n;\n }\n}\n\n\n\n\n\nYou can see that when request is for the \nADC_SNS_TYPE\n, we return the\nSensor Type we defined earlier. If the request if for \nADC_SNS_VAL\n we'll return the\n\ngatt_adc_val\n value. \n\n\nDon't forget to include the \nbleadc.h\n include file at the top of the \ngatt_svr.c\n file!\n\n\n#include \nassert.h\n\n#include \nstdio.h\n\n#include \nstring.h\n\n#include \nbsp/bsp.h\n\n#include \nhost/ble_hs.h\n\n#include \nhost/ble_uuid.h\n\n#include \nbleprph.h\n\n\n#include \nbleadc.h\n\n\n\n\n\n\nIf you build, load and run this application now, you will see all those Services and Characteristics\nadvertised, and you will even be able to read the \"Sensor Type\" String via the ADC_SNS_TYPE\nCharacteristic.\n\n\n\n\nAdding the eTape Water Sensor\n\n\nNow that we have a fully functioning BLE App that we can subscribe to sensor\nvalues from, it's time to actually wire up the sensor!\n\n\nAs previously mentioned, we're going to be using an eTape Water Level Sensor. You can \nget one from \nAdafruit\n. \n\n\nWe're going to use the sensor as a resistive sensor, and the setup is very simple. \nI'll be using a 'breadboard` to put this all together for illustrative purposes. \nFirst, attach a jumper-wire from Vdd on the board to the breadboard.\nNext, attach a jumper wire from pin P0.03 on the board to the breadboard. This will be\nour ADC-in. The sensor should have come with a 560 ohm resistor, so plug that\ninto the board between Vdd and ADC-in holes. Finally, attach a jumper from\nGND on the board to your breadboard. At this point, your breadboard should look\nlike this:\n\n\n\n\nNow attach one of the middle 2 leads from the sensor to ground on the breadboard and \nthe other middle lead to the ADC-in on the breadboard. Your breadboard should now look\nlike this:\n\n\n\n\nAnd your eTape Sensor should look like this (at least if you have it mounted in a\ngraduated cylinder as I do).\n\n\n\n\nThat concludes the hardware portion. Easy!\n\n\nAt this point you should be able to build, create-image and load your application and see it properly \nsending readings. \n\n\n\n\nConclusion\n\n\nCongratulations, you've now completed both a hardware project and a software project by connecting a\nsensor to your device and using Mynewt to read data from that sensor and send it via Bluetooth\nto a connected device. That's no small feat!\n\n\nIf you see anything missing or want to send us feedback, please do so by signing up for \nappropriate mailing lists on our \nCommunity Page\n.\n\n\nKeep on hacking and sensing!\n\n\n\n\nNote\n\n\nIf you're wondering how to actually view these sensor readings via Bluetooth, you have a couple of\noptions. On Mac OS or iOS you can download the \nLightBlue app\n.\nThis app lets you connect to, and interrogate, BLE devices like the one you just built. \n\n\nIf you used the BLE Service and Characteristic UUIDs used in this tutorial, you can also download\nand use a Mac OS \nMyNewt Sensor Reader App\n (Zip Archive) that allows \nyou to graph your data, etc. An iOS version is in Beta testing and should be available soon.\n\n\n\n\nEnjoy!",
- "title": "Add an Analog Sensor"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#adding-an-analog-sensor-on-nrf52",
- "text": "",
- "title": "Adding an Analog Sensor on nRF52"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#objective",
- "text": "We will be adding an analog sensor to the NRF52DK development board and using the Analog to Digital Converter\n(ADC) to read the values from the sensor. It's also using Bluetooth to allow you to connect to the app and\nread the value of the sensor. Please see the following section for the required hardware\nin order to complete this tutorial.",
- "title": "Objective"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#hardware-needed",
- "text": "nRF52 Development Kit (one of the following) Dev Kit from Nordic - PCA 10040 Eval Kit from Rigado - BMD-300-EVAL-ES eTape Liquid Sensor -- buy from Adafruit Laptop running Mac OS It is assumed you have already installed newt tool. It is assumed you already installed native tools as described here",
- "title": "Hardware needed"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#create-a-project",
- "text": "Create a new project to hold your work. For a deeper understanding, you can read about project creation in Get Started -- Creating Your First Project \nor just follow the commands below. $ mkdir ~/dev\n $ cd ~/dev\n $ newt new myadc\n Downloading project skeleton from apache/incubator-mynewt-blinky...\n Installing skeleton in myadc...\n Project myadc successfully created.\n $ cd myadc",
- "title": "Create a project."
- },
- {
- "location": "/os/tutorials/nrf52_adc/#add-additional-repositories",
- "text": "The board-specific libraries for the NRF52dk board are in an external repository at present, so\nyou'll need to include that remote repository and install it as well. If you're not familiar\nwith using repositories, see the section on repositories before\ncontinuing. Or just copy and paste the following. In your project.yml file, add mynewt_nordic to the project.repositories section, and \nthen add the proper repository definition. When you're done, your project.yml file\nshould look like this: project.name: my_project \n\nproject.repositories:\n - apache-mynewt-core - mynewt_nordic \n# Use github s distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core repository.mynewt_nordic: type: github vers: 1-latest user: runtimeco repo: mynewt_nordic",
- "title": "Add Additional Repositories"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#install-everything",
- "text": "Now that you have defined the needed repositories, it's time to install everything so\nthat you can get started. $ newt install -v \n apache-mynewt-core\n Downloading repository description for apache-mynewt-core... success!\n ...\n apache-mynewt-core successfully installed version 0.9.0-none\n ...\n mynewt_nordic\n Downloading repository description for mynewt_nordic... success!\n ...\n mynewt_nordic successfully installed version 0.9.9-none",
- "title": "Install Everything"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#create-the-targets",
- "text": "Create two targets - one for the bootloader and one for the nrf52 board. \nNote: The correct bsp must be chosen for the board you are using. For the Nordic Dev Kit choose @apache-mynewt-core/hw/bsp/nrf52dk instead (in the highlighted lines) For the Rigado Eval Kit choose @apache-mynewt-core/hw/bsp/bmd300eval instead (in the highlighted lines) For the app itself we're going to extend the bleprph app so that we\nget the Bluetooth communications built in, so the first thing we'll need to do is copy that app\ninto our own app directory: $ mkdir -p apps/nrf52_adc\n$ cp -Rp repos/apache-mynewt-core/apps/bleprph/* apps/nrf52_adc Next, you'll modify the pkg.yml file for your app. Note the change in pkg.name and pkg.description . Also make sure that you specify the full path of all the packages with the prefix @apache-mynewt-core/ as shown in the third highlighted line. $ cat apps/nrf52_adc/pkg.yml\n... pkg.name: apps/nrf52_adc pkg.type: app pkg.description: Simple BLE peripheral application for ADC Sensors. pkg.author: Apache Mynewt dev@mynewt.incubator.apache.org \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n\npkg.deps: - @apache-mynewt-core/boot/split - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/mgmt/imgmgr \n - @apache-mynewt-core/mgmt/newtmgr \n - @apache-mynewt-core/mgmt/newtmgr/transport/ble \n - @apache-mynewt-core/net/nimble/controller \n - @apache-mynewt-core/net/nimble/host \n - @apache-mynewt-core/net/nimble/host/services/ans \n - @apache-mynewt-core/net/nimble/host/services/gap \n - @apache-mynewt-core/net/nimble/host/services/gatt \n - @apache-mynewt-core/net/nimble/host/store/ram \n - @apache-mynewt-core/net/nimble/transport/ram \n - @apache-mynewt-core/sys/console/full \n - @apache-mynewt-core/sys/log/full \n - @apache-mynewt-core/sys/stats/full \n - @apache-mynewt-core/sys/sysinit \n - @apache-mynewt-core/sys/id Great! We have our very own app so let's make sure we have all of our targets set\ncorrectly: $ newt target create nrf52_adc\n$ newt target set nrf52_adc app=apps/nrf52_adc Target targets/nrf52_adc successfully set target.app to apps/nrf52_adc $ newt target set nrf52_adc bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_adc build_profile=debug\n\n$ newt target create nrf52_boot $ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot $ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n$ newt target set nrf52_boot build_profile=optimized\n\n$ newt target show \ntargets/nrf52_adc\n app=apps/nrf52_adc\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=debug\ntargets/nrf52_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk\n build_profile=optimized \nNote: If you've already built and installed a bootloader for your NRF52dk then you do\nnot need to create a target for it here, or build and load it as below.",
- "title": "Create the targets"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#build-the-target-executables",
- "text": "$ newt build nrf52_boot\n...\nCompiling boot.c\nArchiving boot.a\nLinking boot.elf\nApp successfully built: ~/dev/myadc/bin/nrf52_boot/apps/boot/boot.elf $ newt build nrf52_adc\n...\nCompiling main.c\nArchiving nrf52_adc.a\nLinking nrf52_adc.elf\nApp successfully built: ~/dev/myadc/bin/nrf52_adc/apps/nrf52_adc/nrf52_adc.elf",
- "title": "Build the target executables"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#sign-and-create-the-nrf52_adc-application-image",
- "text": "You must sign and version your application image to download it using newt to the board. \nUse the newt create-image command to perform this action. You may assign an arbitrary \nversion (e.g. 1.0.0) to the image. $ newt create-image nrf52_adc 1.0.0\nApp image successfully generated: ~/dev/myadc/bin/nrf52_adc/apps/nrf52_adc/nrf52_adc.img\nBuild manifest: ~/dev/myadc/bin/nrf52_adc/apps/nrf52_adc/manifest.json",
- "title": "Sign and create the nrf52_adc application image"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#connect-the-board",
- "text": "Connect the evaluation board via micro-USB to your PC via USB cable.",
- "title": "Connect the board"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#download-to-the-target",
- "text": "Download the bootloader first and then the nrf52_adc executable to the target platform. \nDon't forget to reset the board if you don't see the LED blinking right away! $ newt load nrf52_boot\n$ newt load nrf52_adc Note: If you want to erase the flash and load the image again, you can use JLinkExe to issue an erase command. $ JLinkExe -device nRF52 -speed 4000 -if SWD\nSEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)\nDLL version V5.12c, compiled Apr 21 2016 16:05:45\n\nConnecting to J-Link via USB...O.K.\nFirmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17\nHardware version: V1.00\nS/N: 682863966\nVTref = 3.300V\n\n\nType connect to establish a target connection, ? for help\nJ-Link erase\nCortex-M4 identified.\nErasing device (0;?i?)...\nComparing flash [100%] Done.\nErasing flash [100%] Done.\nVerifying flash [100%] Done.\nJ-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)\nErasing done.\nJ-Link exit\n$ So you have a BLE app, but really all you've done is change the name of the bleprph app to nrf52_adc and load that.\nNot all that impressive, and it certainly won't read an Analog Sensor right now. So let's do that next. In order to \nread an ADC sensor, and since the ADC package is in an external, licensed, repository, we'll create a driver for it\nhere in our app that will leverage the existing driver in the external repository. It adds another layer of \nindirection, but it will also give us a look at building our own driver, so we'll do it this way.",
- "title": "Download to the target"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#building-a-driver",
- "text": "The first thing to do is to create the directory structure for your driver: [user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/myadc/include/myadc\n[user@IsMyLaptop:~/src/air_quality]$ mkdir -p libs/my_drivers/myadc/src Now you can add the files you need. You'll need a pkg.yml to describe the driver, and then header stub followed by source stub. [user@IsMyLaptop:~/src/air_quality]$ cat libs/my_drivers/myadc/pkg.yml # # Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file # distributed with this work for additional information # regarding copyright ownership. The ASF licenses this file # to you under the Apache License, Version 2.0 (the # License ); you may not use this file except in compliance # with the License. You may obtain a copy of the License at # # http: //www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, # software distributed under the License is distributed on an # AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY # KIND, either express or implied. See the License for the # specific language governing permissions and limitations # under the License. # pkg . name : libs/my_drivers/myadc pkg . deps :\n - @apache-mynewt-core/hw/hal \n - @mynewt_nordic/hw/drivers/adc/adc_nrf52 First, let's create the required header file myadc.h in the includes directory i.e. libs/my_drivers/myadc/include/myadc/myadc.h .\nIt's a pretty straightforward header file, since we only need to do 2 things: Initialize the ADC device Read ADC Values #ifndef _NRF52_ADC_H_ #define _NRF52_ADC_H_ void * adc_init ( void ); int adc_read ( void *buffer , int buffer_len ); #endif /* _NRF52_ADC_H_ */ Next we'll need a corresponding source file myadc.c in the src directory. This is where\nwe'll implement the specifics of the driver: #include assert.h #include os/os.h /* ADC */ #include myadc/myadc.h #include nrf.h #include app_util_platform.h #include app_error.h #include adc/adc.h #include adc_nrf52/adc_nrf52.h #include nrf_drv_saadc.h #define ADC_NUMBER_SAMPLES (2) #define ADC_NUMBER_CHANNELS (1) nrf_drv_saadc_config_t adc_config = NRF_DRV_SAADC_DEFAULT_CONFIG ; struct adc_dev *adc ; uint8_t *sample_buffer1 ; uint8_t *sample_buffer2 ; static struct adc_dev os_bsp_adc0 ; static nrf_drv_saadc_config_t os_bsp_adc0_config = {\n . resolution = MYNEWT_VAL ( ADC_0_RESOLUTION ),\n . oversample = MYNEWT_VAL ( ADC_0_OVERSAMPLE ),\n . interrupt_priority = MYNEWT_VAL ( ADC_0_INTERRUPT_PRIORITY ),\n}; void * adc_init ( void )\n{\n int rc = 0 ;\n\n rc = os_dev_create (( struct os_dev * ) os_bsp_adc0 , adc0 ,\n OS_DEV_INIT_KERNEL , OS_DEV_INIT_PRIO_DEFAULT ,\n nrf52_adc_dev_init , os_bsp_adc0_config );\n assert ( rc == 0 );\n nrf_saadc_channel_config_t cc = NRF_DRV_SAADC_DEFAULT_CHANNEL_CONFIG_SE ( NRF_SAADC_INPUT_AIN1 );\n cc . gain = NRF_SAADC_GAIN1_6 ;\n cc . reference = NRF_SAADC_REFERENCE_INTERNAL ;\n adc = ( struct adc_dev * ) os_dev_open ( adc0 , 0 , adc_config );\n assert ( adc != NULL );\n adc_chan_config ( adc , 0 , cc );\n sample_buffer1 = malloc ( adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n sample_buffer2 = malloc ( adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n memset ( sample_buffer1 , 0 , adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n memset ( sample_buffer2 , 0 , adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n adc_buf_set ( adc , sample_buffer1 , sample_buffer2 ,\n adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n return adc ;\n} int adc_read ( void *buffer , int buffer_len )\n{\n int i ;\n int adc_result ;\n int my_result_mv = 0 ;\n int rc ;\n for ( i = 0 ; i ADC_NUMBER_SAMPLES ; i++ ) {\n rc = adc_buf_read ( adc , buffer , buffer_len , i , adc_result );\n if ( rc != 0 ) {\n goto err ;\n }\n my_result_mv = adc_result_mv ( adc , 0 , adc_result );\n } \n adc_buf_release ( adc , buffer , buffer_len );\n return my_result_mv ; err :\n return ( rc );\n} There's a lot going on in here, so let's walk through it step by step. First, we define a default configuration, with the resolution, oversample and interrupt priority. You'll see\nthat these are MYNEWT_VAL values, which means that we'll define them shortly in\na syscfg.yml file to be passed to the compiler at build time. static struct adc_dev os_bsp_adc0 ; static nrf_drv_saadc_config_t os_bsp_adc0_config = {\n . resolution = MYNEWT_VAL ( ADC_0_RESOLUTION ),\n . oversample = MYNEWT_VAL ( ADC_0_OVERSAMPLE ),\n . interrupt_priority = MYNEWT_VAL ( ADC_0_INTERRUPT_PRIORITY ),\n}; Next, in adc_init() , we need to tell the OS to create the device. void * adc_init ( void )\n{\n int rc = 0 ;\n\n rc = os_dev_create (( struct os_dev * ) os_bsp_adc0 , adc0 ,\n OS_DEV_INIT_KERNEL , OS_DEV_INIT_PRIO_DEFAULT ,\n nrf52_adc_dev_init , os_bsp_adc0_config );\n assert ( rc == 0 );\n nrf_saadc_channel_config_t cc = NRF_DRV_SAADC_DEFAULT_CHANNEL_CONFIG_SE ( NRF_SAADC_INPUT_AIN1 );\n cc . gain = NRF_SAADC_GAIN1_6 ;\n cc . reference = NRF_SAADC_REFERENCE_INTERNAL ;\n adc = ( struct adc_dev * ) os_dev_open ( adc0 , 0 , adc_config );\n assert ( adc != NULL );\n adc_chan_config ( adc , 0 , cc );\n sample_buffer1 = malloc ( adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n sample_buffer2 = malloc ( adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n memset ( sample_buffer1 , 0 , adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n memset ( sample_buffer2 , 0 , adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n adc_buf_set ( adc , sample_buffer1 , sample_buffer2 ,\n adc_buf_size ( adc , ADC_NUMBER_CHANNELS , ADC_NUMBER_SAMPLES ));\n return adc ;\n} A few things need to be said about this part, as it is the most confusing. First, \nwe're using a default configuration for the ADC Channel via the NRF_DRV_SAADC_DEFAULT_CHANNEL_CONFIG_SE \nmacro. The important part here is that we're actually using AIN1 . I know what you're thinking, \"But \nwe want ADC-0!\" and that's true. The board is actually labelled 'A0, A1, A2' etc., and the actual pin \nnumbers are also listed on the board, which seems handy. At first. But it gets messy very quickly. If you try to use AIN0, and then go poke around in the registers while this is running, (gdb) p/x {NRF_SAADC_Type}0x40007000\n...\n CH = {{\n PSELP = 0x1,\n PSELN = 0x0,\n CONFIG = 0x20000,\n LIMIT = 0x7fff8000\n }, You'll see that the pin for channel 0 is set to 1, which corresponds to AIN0, but that's NOT \nthe same as A0 -- pin P0.03, the one we're using. For that, you use AIN1, which would set the\npin value to 2. Messy. Someone, somewhere, thought this made sense. The only other thing to note here is that we're using the internal reference voltage, rather than\nsetting our own. There's nothing wrong with that, but since we are, we'll have to crank up\nthe gain a bit by using NRF_SAADC_GAIN1_6 . Then, in adc_read() we will take readings, convert the raw readings to \na millivolt equivalent, and return the result. int adc_read ( void *buffer , int buffer_len )\n{\n int i ;\n int adc_result ;\n int my_result_mv = 0 ;\n int rc ;\n for ( i = 0 ; i ADC_NUMBER_SAMPLES ; i++ ) {\n rc = adc_buf_read ( adc , buffer , buffer_len , i , adc_result );\n if ( rc != 0 ) {\n goto err ;\n }\n my_result_mv = adc_result_mv ( adc , 0 , adc_result );\n } \n adc_buf_release ( adc , buffer , buffer_len );\n return my_result_mv ; err :\n return ( rc );\n} Finally, we'll need some settings for our driver, as mentioned earlier. In the myadc directory\nyou'll need to add a syscfg.yml file: # Package: libs/my_driver/myadc\n\nsyscfg.defs:\n ADC_0:\n description: TBD \n value: 1\n ADC_0_RESOLUTION:\n description: TBD \n value: SAADC_CONFIG_RESOLUTION \n ADC_0_OVERSAMPLE:\n description: TBD \n value: SAADC_CONFIG_OVERSAMPLE \n ADC_0_INTERRUPT_PRIORITY:\n description: TBD \n value: SAADC_CONFIG_IRQ_PRIORITY Once that's all done, you should have a working ADC Driver for your NRF52DK board. The last step in getting the driver set up is to include it in the package dependency defined by pkg.deps in the pkg.yml file of your app. Add it in apps/nrf52_adc/pkg.yml as shown by the highlighted line below. # Licensed to the Apache Software Foundation (ASF) under one\n# snip \n\npkg.name: apps/nrf52_adc\npkg.type: app\npkg.description: Simple BLE peripheral application for ADC sensor.\npkg.author: Apache Mynewt dev@mynewt.incubator.apache.org \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n\npkg.deps: \n - @apache-mynewt-core/boot/split \n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/mgmt/imgmgr \n - @apache-mynewt-core/mgmt/newtmgr \n - @apache-mynewt-core/mgmt/newtmgr/transport/ble \n - @apache-mynewt-core/net/nimble/controller \n - @apache-mynewt-core/net/nimble/host \n - @apache-mynewt-core/net/nimble/host/services/ans \n - @apache-mynewt-core/net/nimble/host/services/gap \n - @apache-mynewt-core/net/nimble/host/services/gatt \n - @apache-mynewt-core/net/nimble/host/store/ram \n - @apache-mynewt-core/net/nimble/transport/ram \n - @apache-mynewt-core/sys/console/full \n - @apache-mynewt-core/sys/log/full \n - @apache-mynewt-core/sys/stats/full \n - @apache-mynewt-core/sys/sysinit \n - @apache-mynewt-core/sys/id - libs/my_drivers/myadc",
- "title": "Building a Driver"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#creating-the-adc-task",
- "text": "Now that the driver is done, we'll need to add calls to the main app's main.c file, as well\nas a few other things. First, we'll need to update the includes, and add a task for our ADC\nsampling. #include myadc/myadc.h \n... /* ADC Task settings */ #define ADC_TASK_PRIO 5 #define ADC_STACK_SIZE (OS_STACK_ALIGN(336)) struct os_eventq adc_evq ; struct os_task adc_task ; bssnz_t os_stack_t adc_stack [ ADC_STACK_SIZE ]; Next we'll need o initialize the task event_q so we'll add the highlighted code to main() as shown below: /* Set the default device name. */ \n rc = ble_svc_gap_device_name_set ( nimble-adc );\n assert ( rc == 0 );\n\n conf_load (); /* Initialize adc sensor task eventq */ os_eventq_init ( adc_evq ); /* Create the ADC reader task. * All sensor operations are performed in this task. */ os_task_init ( adc_task , sensor , adc_task_handler , NULL , ADC_TASK_PRIO , OS_WAIT_FOREVER , adc_stack , ADC_STACK_SIZE ); We'll need that adc_task_handler() function to exist, and that's where we'll initialize the ADC Device\nand set the event handler. In the task's while() loop, we'll just make a call to adc_sample() to cause\nthe ADC driver to sample the adc device. /** * Event loop for the sensor task. */ static void adc_task_handler ( void *unused )\n{\n struct adc_dev *adc ;\n int rc ;\n /* ADC init */ \n adc = adc_init ();\n rc = adc_event_handler_set ( adc , adc_read_event , ( void * ) NULL );\n assert ( rc == 0 );\n\n while ( 1 ) {\n adc_sample ( adc );\n /* Wait 2 second */ \n os_time_delay ( OS_TICKS_PER_SEC * 2 );\n }\n} Above the adc_task_handler , add code to handle the adc_read_event() calls: int adc_read_event ( struct adc_dev *dev , void *arg , uint8_t etype ,\n void *buffer , int buffer_len )\n{\n int value ;\n uint16_t chr_val_handle ;\n int rc ;\n\n value = adc_read ( buffer , buffer_len );\n if ( value = 0 ) {\n console_printf ( Got %d\\n , value );\n } else {\n console_printf ( Error while reading: %d\\n , value );\n goto err ;\n }\n gatt_adc_val = value ;\n rc = ble_gatts_find_chr ( gatt_svr_svc_adc_uuid . u , BLE_UUID16_DECLARE ( ADC_SNS_VAL ), NULL , chr_val_handle );\n assert ( rc == 0 );\n ble_gatts_chr_updated ( chr_val_handle );\n return ( 0 ); err :\n return ( rc );\n} This is where we actually read the ADC value and then update the BLE Characteristic for that value. But wait, we haven't defined those BLE services and characteristics yet! Right, so don't try to build and run this\napp just yet or it will surely fail. Instead, move on to the next section and get all of those services \ndefined.",
- "title": "Creating the ADC Task"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#building-the-ble-services",
- "text": "If the nrf52_adc app is going to be a Bluetooth-enabled sensor app that will allow you to read the value of the eTape Water Level Sensor\nvia Bluetooth we'll need to actually define those Services and Characteristics. As with the ble peripheral app, we will advertise a couple of values from our app. The first is\nnot strictly necessary, but it will help us build an iOS app later. We've defined a service and the characteristics in\nthat service in bleadc.h in the apps/nrf52_adc/src/ directory as follows: /* Sensor Data */ /* e761d2af-1c15-4fa7-af80-b5729002b340 */ static const ble_uuid128_t gatt_svr_svc_adc_uuid = \n BLE_UUID128_INIT ( 0x40 , 0xb3 , 0x20 , 0x90 , 0x72 , 0xb5 , 0x80 , 0xaf ,\n 0xa7 , 0x4f , 0x15 , 0x1c , 0xaf , 0xd2 , 0x61 , 0xe7 ); #define ADC_SNS_TYPE 0xDEAD #define ADC_SNS_STRING eTape Liquid Level Sensor #define ADC_SNS_VAL 0xBEAD extern uint16_t gatt_adc_val ; The first is the UUID of the service, followed by the 2 characteristics we are going to offer.\nThe first characteristic is going to advertise the type of sensor we are advertising, and\nit will be a read-only characteristic. The second characteristic will be the sensor value\nitself, and we will allow connected devices to 'subscribe' to it in order to get \nconstantly-updated values. Note: You can choose any valid Characteristic UUIDs to go here. We're using these values\nfor illustrative purposes only. The value that we'll be updating is also defined here as gatt_adc_val . If we then go look at gatt_srv.c we can see the structure of the service and\ncharacteristic offering that we set up: static const struct ble_gatt_svc_def gatt_svr_svcs [] = {\n {\n /*** Service: Security test. */ \n . type = BLE_GATT_SVC_TYPE_PRIMARY ,\n . uuid = gatt_svr_svc_sec_test_uuid . u ,\n . characteristics = ( struct ble_gatt_chr_def []) { {\n /*** Characteristic: Random number generator. */ \n . uuid = gatt_svr_chr_sec_test_rand_uuid . u ,\n . access_cb = gatt_svr_chr_access_sec_test ,\n . flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_READ_ENC ,\n }, {\n /*** Characteristic: Static value. */ \n . uuid = gatt_svr_chr_sec_test_static_uuid . u ,\n . access_cb = gatt_svr_chr_access_sec_test ,\n . flags = BLE_GATT_CHR_F_READ | \n BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_WRITE_ENC ,\n }, {\n 0 , /* No more characteristics in this service. */ \n } },\n }, { /*** ADC Level Notification Service. */ . type = BLE_GATT_SVC_TYPE_PRIMARY , . uuid = gatt_svr_svc_adc_uuid . u , . characteristics = ( struct ble_gatt_chr_def []) { { . uuid = BLE_UUID16_DECLARE ( ADC_SNS_TYPE ), . access_cb = gatt_svr_sns_access , . flags = BLE_GATT_CHR_F_READ , }, { . uuid = BLE_UUID16_DECLARE ( ADC_SNS_VAL ), . access_cb = gatt_svr_sns_access , . flags = BLE_GATT_CHR_F_NOTIFY , }, { 0 , /* No more characteristics in this service. */ } }, }, {\n 0 , /* No more services. */ \n },\n}; You should recognize the first services from the BLE Peripheral \ntutorial earlier. We're just adding another Service, with 2 new Characteristics, to \nthat application. We'll need to fill in the function that will be called for this service, gatt_srv_sns_access \nnext so that the service knows what to do. static int gatt_svr_sns_access ( uint16_t conn_handle , uint16_t attr_handle ,\n struct ble_gatt_access_ctxt *ctxt ,\n void *arg )\n{\n uint16_t uuid16 ;\n int rc ;\n\n uuid16 = ble_uuid_u16 ( ctxt- chr- uuid );\n\n switch ( uuid16 ) {\n case ADC_SNS_TYPE :\n assert ( ctxt- op == BLE_GATT_ACCESS_OP_READ_CHR );\n rc = os_mbuf_append ( ctxt- om , ADC_SNS_STRING , sizeof ADC_SNS_STRING );\n BLEPRPH_LOG ( INFO , ADC SENSOR TYPE READ: %s\\n , ADC_SNS_STRING );\n return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES ;\n\n case ADC_SNS_VAL :\n if ( ctxt- op == BLE_GATT_ACCESS_OP_WRITE_CHR ) {\n rc = gatt_svr_chr_write ( ctxt- om , 0 ,\n sizeof gatt_adc_val ,\n gatt_adc_val ,\n NULL );\n return rc ;\n } else if ( ctxt- op == BLE_GATT_ACCESS_OP_READ_CHR ) {\n rc = os_mbuf_append ( ctxt- om , gatt_adc_val ,\n sizeof gatt_adc_val );\n return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES ;\n }\n\n default : \n assert ( 0 );\n return BLE_ATT_ERR_UNLIKELY ;\n }\n} You can see that when request is for the ADC_SNS_TYPE , we return the\nSensor Type we defined earlier. If the request if for ADC_SNS_VAL we'll return the gatt_adc_val value. Don't forget to include the bleadc.h include file at the top of the gatt_svr.c file! #include assert.h \n#include stdio.h \n#include string.h \n#include bsp/bsp.h \n#include host/ble_hs.h \n#include host/ble_uuid.h \n#include bleprph.h #include bleadc.h If you build, load and run this application now, you will see all those Services and Characteristics\nadvertised, and you will even be able to read the \"Sensor Type\" String via the ADC_SNS_TYPE\nCharacteristic.",
- "title": "Building the BLE Services"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#adding-the-etape-water-sensor",
- "text": "Now that we have a fully functioning BLE App that we can subscribe to sensor\nvalues from, it's time to actually wire up the sensor! As previously mentioned, we're going to be using an eTape Water Level Sensor. You can \nget one from Adafruit . We're going to use the sensor as a resistive sensor, and the setup is very simple. \nI'll be using a 'breadboard` to put this all together for illustrative purposes. \nFirst, attach a jumper-wire from Vdd on the board to the breadboard.\nNext, attach a jumper wire from pin P0.03 on the board to the breadboard. This will be\nour ADC-in. The sensor should have come with a 560 ohm resistor, so plug that\ninto the board between Vdd and ADC-in holes. Finally, attach a jumper from\nGND on the board to your breadboard. At this point, your breadboard should look\nlike this: Now attach one of the middle 2 leads from the sensor to ground on the breadboard and \nthe other middle lead to the ADC-in on the breadboard. Your breadboard should now look\nlike this: And your eTape Sensor should look like this (at least if you have it mounted in a\ngraduated cylinder as I do). That concludes the hardware portion. Easy! At this point you should be able to build, create-image and load your application and see it properly \nsending readings.",
- "title": "Adding the eTape Water Sensor"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#conclusion",
- "text": "Congratulations, you've now completed both a hardware project and a software project by connecting a\nsensor to your device and using Mynewt to read data from that sensor and send it via Bluetooth\nto a connected device. That's no small feat! If you see anything missing or want to send us feedback, please do so by signing up for \nappropriate mailing lists on our Community Page . Keep on hacking and sensing!",
- "title": "Conclusion"
- },
- {
- "location": "/os/tutorials/nrf52_adc/#note",
- "text": "If you're wondering how to actually view these sensor readings via Bluetooth, you have a couple of\noptions. On Mac OS or iOS you can download the LightBlue app .\nThis app lets you connect to, and interrogate, BLE devices like the one you just built. If you used the BLE Service and Characteristic UUIDs used in this tutorial, you can also download\nand use a Mac OS MyNewt Sensor Reader App (Zip Archive) that allows \nyou to graph your data, etc. An iOS version is in Beta testing and should be available soon. Enjoy!",
- "title": "Note"
- },
- {
- "location": "/os/os_user_guide/",
- "text": "OS User Guide\n\n\nThis guide provides comprehensive information about Mynewt OS, the real-time operating system for embedded systems.\n\n\nIt is intended both for an embedded real-time software developer as well as higher-level applications developer wanting to understand the features and benefits of the system. \n\n\nMynewt OS is highly composable and flexible. Only those features actually used by the application are compiled into the run-time image. Hence, the actual size of Mynewt is completely determined by the application. The guide covers all the features and services available in the OS and contains several examples showing how they can be used.\n\n\nSend us an email on the dev@ mailing list if you have comments or suggestions!\n If you haven't joined the mailing list, you will find the links \nhere\n.",
- "title": "toc"
- },
- {
- "location": "/os/os_user_guide/#os-user-guide",
- "text": "This guide provides comprehensive information about Mynewt OS, the real-time operating system for embedded systems. It is intended both for an embedded real-time software developer as well as higher-level applications developer wanting to understand the features and benefits of the system. Mynewt OS is highly composable and flexible. Only those features actually used by the application are compiled into the run-time image. Hence, the actual size of Mynewt is completely determined by the application. The guide covers all the features and services available in the OS and contains several examples showing how they can be used. Send us an email on the dev@ mailing list if you have comments or suggestions! If you haven't joined the mailing list, you will find the links here .",
- "title": "OS User Guide"
- },
- {
- "location": "/os/core_os/mynewt_os/",
- "text": "Mynewt Core OS\n\n\nThe Mynewt Core OS is a multitasking, preemptive real-time operating system combining a scheduler with typical RTOS features such as mutexes, semaphores, memory pools, etc. The Mynewt Core OS also provides a number of useful utilities such as a task watchdog, networking stack, memory buffers and time management API. Each of these features is described in detail in its own section of the manual.\n\n\nA multitasking, preemptive operating system is one in which a number of different tasks can be instantiated and assigned a priority, with higher priority tasks running before lower priority tasks. Furthermore, if a lower priority task is running and a higher priority task wants to run, the lower priority task is halted and the higher priority task is allowed to run. In other words, the lower priority task is preempted by the higher priority task.\n\n\nWhy use an OS?\n\n\nYou may ask yourself \"why do I need a multitasking preemptive OS\"? The answer may indeed be that you do not. Some applications are simple and only require a polling loop. Others are more complex and may require that certain jobs are executed in a timely manner or before other jobs are executed. If you have a simple polling loop, you cannot move on to service a job until the current job is done being serviced. With the Mynewt OS, the application developer need not worry about certain jobs taking too long or not executing in a timely fashion; the OS provides mechanisms to deal with these situations. Another benefit of using an OS is that it helps shield application developers from other application code being written; the developer does not have to worry (or has to worry less) about other application code behaving badly and causing undesirable behavior or preventing their code from executing properly. Other benefits of using an OS (and the Mynewt OS in particular) is that it also provides features that the developer would otherwise need to create on his/her own. \n\n\nCore OS Features\n\n\n\n\n\n\nScheduler/context switching\n\n\nTime\n\n\nTasks\n\n\nEvent queues/callouts\n\n\nSemaphores\n\n\nMutexes\n\n\nMemory pools\n\n\nHeap\n\n\nMbufs\n\n\nSanity\n\n\nCallouts\n\n\nPorting OS to other platforms\n\n\n\n\nBasic OS Application Creation\n\n\nCreating an application using the Mynewt Core OS is a relatively simple task. The main steps are:\n\n\n\n\nInstall the basic Newt Tool structure (build structure) for your application.\n\n\nCreate your BSP (Board Support Package).\n\n\nIn your application \nmain()\n function, call the \nsysinit()\n function to initialize \nthe system and packages, perform application specific initialization, then\nwait and dispatch events from the OS default event \nqueue in an infinite loop. (See \nSystem Configuration and Initialization\n for more details.) \n\n\n\n\nInitializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initialized prior to being called by another (higher priority) task. \n\n\nFor example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API.\n\n\nConsider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.\n\n\nExample\n\n\nOne way to avoid initialization issues like the one described above is for the application to \ninitialize the objects that are accessed by multiple tasks before it initializes the tasks with the OS.\n\n\nThe code example shown below illustrates this concept. The application initializes system and packages, calls an application specific \"task initialization\" function, and dispatches events from the default event queue. The application task initialization function is responsible for initializing all the data objects that each task exposes to the other tasks. The tasks themselves are also initialized at this time (by calling \nos_task_init()\n). \n\n\nIn the example, each task works in a ping-pong like fashion: task 1 wakes up, adds a token to semaphore 1 and then waits for a token from semaphore 2. Task 2 waits for a token on semaphore 1 and once it gets it, adds a token to semaphore 2. Notice that the semaphores are initialized by the application specific task initialization functions and not inside the task handler functions. If task 2 (being lower in priority than task 1) had called \nos_sem_init()\n for task2_sem inside \ntask2_handler()\n, task 1 would have called \nos_sem_pend()\n using task2_sem before task2_sem was initialized.\n\n\n \nstruct\n \nos_sem\n \ntask1_sem\n;\n \nstruct\n \nos_sem\n \ntask2_sem\n;\n\n \n/* Task 1 handler function */\n\n \nvoid\n\n \ntask1_handler\n(\nvoid\n \n*arg\n)\n {\n \nwhile\n (\n1\n) {\n \n/* Release semaphore to task 2 */\n\n \nos_sem_release\n(\ntask1_sem\n);\n\n \n/* Wait for semaphore from task 2 */\n\n \nos_sem_pend\n(\ntask2_sem\n, \nOS_TIMEOUT_NEVER\n);\n }\n }\n\n \n/* Task 2 handler function */\n\n \nvoid\n\n \ntask2_handler\n(\nvoid\n \n*arg\n)\n {\n \nstruct\n \nos_task\n \n*t\n;\n\n \nwhile\n (\n1\n) {\n \n/* Wait for semaphore from task1 */\n\n \nos_sem_pend\n(\ntask1_sem\n, \nOS_TIMEOUT_NEVER\n);\n\n \n/* Release task2 semaphore */\n\n \nos_sem_release\n(\ntask2_sem\n);\n }\n }\n\n\n \n/* Initialize task 1 exposed data objects */\n\n \nvoid\n\n \ntask1_init\n(\nvoid\n)\n {\n \n/* Initialize task1 semaphore */\n\n \nos_sem_init\n(\ntask1_sem\n, \n0\n);\n }\n\n \n/* Initialize task 2 exposed data objects */\n\n \nvoid\n\n \ntask2_init\n(\nvoid\n)\n {\n \n/* Initialize task1 semaphore */\n\n \nos_sem_init\n(\ntask2_sem\n, \n0\n);\n }\n\n \n/**\n\n\n * init_app_tasks\n\n\n * \n\n\n * This function performs initializations that are required before tasks run. \n\n\n * \n\n\n * @return int 0 success; error otherwise.\n\n\n */\n\n \nstatic\n \nint\n\n \ninit_app_tasks\n(\nvoid\n)\n {\n \n/* \n\n\n * Call task specific initialization functions to initialize any shared objects \n\n\n * before initializing the tasks with the OS.\n\n\n */\n\n \ntask1_init\n();\n \ntask2_init\n();\n\n \n/*\n\n\n * Initialize tasks 1 and 2 with the OS. \n\n\n */\n\n \nos_task_init\n(\ntask1\n, \ntask1\n, \ntask1_handler\n, \nNULL\n, \nTASK1_PRIO\n, \n \nOS_WAIT_FOREVER\n, \ntask1_stack\n, \nTASK1_STACK_SIZE\n);\n\n \nos_task_init\n(\ntask2\n, \ntask2\n, \ntask2_handler\n, \nNULL\n, \nTASK2_PRIO\n, \n \nOS_WAIT_FOREVER\n, \ntask2_stack\n, \nTASK2_STACK_SIZE\n);\n\n \nreturn\n \n0\n;\n }\n\n \n/**\n\n\n * main\n\n\n * \n\n\n * The main function for the application. This function initializes the system and packages, \n\n\n * calls the application specific task initialization function, then waits and dispatches \n\n\n * events from the OS default event queue in an infinite loop. \n\n\n */\n\n \nint\n\n \nmain\n(\nint\n \nargc\n, \nchar\n \n**arg\n)\n {\n\n \n/* Perform system and package initialization */\n\n \nsysinit\n();\n\n \n/* Initialize application specific tasks */\n\n \ninit_app_tasks\n();\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n \n/* main never returns */\n \n}\n\n\n\n\n\nOS Functions\n\n\nThe functions available at the OS level are:\n\n\n\n\nos_started",
- "title": "toc"
- },
- {
- "location": "/os/core_os/mynewt_os/#mynewt-core-os",
- "text": "The Mynewt Core OS is a multitasking, preemptive real-time operating system combining a scheduler with typical RTOS features such as mutexes, semaphores, memory pools, etc. The Mynewt Core OS also provides a number of useful utilities such as a task watchdog, networking stack, memory buffers and time management API. Each of these features is described in detail in its own section of the manual. A multitasking, preemptive operating system is one in which a number of different tasks can be instantiated and assigned a priority, with higher priority tasks running before lower priority tasks. Furthermore, if a lower priority task is running and a higher priority task wants to run, the lower priority task is halted and the higher priority task is allowed to run. In other words, the lower priority task is preempted by the higher priority task.",
- "title": "Mynewt Core OS"
- },
- {
- "location": "/os/core_os/mynewt_os/#why-use-an-os",
- "text": "You may ask yourself \"why do I need a multitasking preemptive OS\"? The answer may indeed be that you do not. Some applications are simple and only require a polling loop. Others are more complex and may require that certain jobs are executed in a timely manner or before other jobs are executed. If you have a simple polling loop, you cannot move on to service a job until the current job is done being serviced. With the Mynewt OS, the application developer need not worry about certain jobs taking too long or not executing in a timely fashion; the OS provides mechanisms to deal with these situations. Another benefit of using an OS is that it helps shield application developers from other application code being written; the developer does not have to worry (or has to worry less) about other application code behaving badly and causing undesirable behavior or preventing their code from executing properly. Other benefits of using an OS (and the Mynewt OS in particular) is that it also provides features that the developer would otherwise need to create on his/her own.",
- "title": "Why use an OS?"
- },
- {
- "location": "/os/core_os/mynewt_os/#core-os-features",
- "text": "Scheduler/context switching Time Tasks Event queues/callouts Semaphores Mutexes Memory pools Heap Mbufs Sanity Callouts Porting OS to other platforms",
- "title": "Core OS Features"
- },
- {
- "location": "/os/core_os/mynewt_os/#basic-os-application-creation",
- "text": "Creating an application using the Mynewt Core OS is a relatively simple task. The main steps are: Install the basic Newt Tool structure (build structure) for your application. Create your BSP (Board Support Package). In your application main() function, call the sysinit() function to initialize \nthe system and packages, perform application specific initialization, then\nwait and dispatch events from the OS default event \nqueue in an infinite loop. (See System Configuration and Initialization for more details.) Initializing application modules and tasks can get somewhat complicated with RTOS's similar to Mynewt. Care must be taken that the API provided by a task are initialized prior to being called by another (higher priority) task. For example, take a simple application with two tasks (tasks 1 and 2, with task 1 higher priority than task 2). Task 2 provides an API which has a semaphore lock and this semaphore is initialized by task 2 when the task handler for task 2 is called. Task 1 is expected to call this API. Consider the sequence of events when the OS is started. The scheduler starts running and picks the highest priority task (task 1 in this case). The task handler function for task 1 is called and will keep running until it yields execution. Before yielding, code in the task 1 handler function calls the API provided by task 2. The semaphore being accessed in the task 2 API has yet to be initialized since the task 2 handler function has not had a chance to run! This will lead to undesirable behavior and will need to be addressed by the application developer. Note that the Mynewt OS does guard against internal API being called before the OS has started (they will return error) but it does not safeguard application defined objects from access prior to initialization.",
- "title": "Basic OS Application Creation"
- },
- {
- "location": "/os/core_os/mynewt_os/#example",
- "text": "One way to avoid initialization issues like the one described above is for the application to \ninitialize the objects that are accessed by multiple tasks before it initializes the tasks with the OS. The code example shown below illustrates this concept. The application initializes system and packages, calls an application specific \"task initialization\" function, and dispatches events from the default event queue. The application task initialization function is responsible for initializing all the data objects that each task exposes to the other tasks. The tasks themselves are also initialized at this time (by calling os_task_init() ). In the example, each task works in a ping-pong like fashion: task 1 wakes up, adds a token to semaphore 1 and then waits for a token from semaphore 2. Task 2 waits for a token on semaphore 1 and once it gets it, adds a token to semaphore 2. Notice that the semaphores are initialized by the application specific task initialization functions and not inside the task handler functions. If task 2 (being lower in priority than task 1) had called os_sem_init() for task2_sem inside task2_handler() , task 1 would have called os_sem_pend() using task2_sem before task2_sem was initialized. struct os_sem task1_sem ;\n struct os_sem task2_sem ;\n\n /* Task 1 handler function */ \n void \n task1_handler ( void *arg )\n {\n while ( 1 ) {\n /* Release semaphore to task 2 */ \n os_sem_release ( task1_sem );\n\n /* Wait for semaphore from task 2 */ \n os_sem_pend ( task2_sem , OS_TIMEOUT_NEVER );\n }\n }\n\n /* Task 2 handler function */ \n void \n task2_handler ( void *arg )\n {\n struct os_task *t ;\n\n while ( 1 ) {\n /* Wait for semaphore from task1 */ \n os_sem_pend ( task1_sem , OS_TIMEOUT_NEVER );\n\n /* Release task2 semaphore */ \n os_sem_release ( task2_sem );\n }\n }\n\n\n /* Initialize task 1 exposed data objects */ \n void \n task1_init ( void )\n {\n /* Initialize task1 semaphore */ \n os_sem_init ( task1_sem , 0 );\n }\n\n /* Initialize task 2 exposed data objects */ \n void \n task2_init ( void )\n {\n /* Initialize task1 semaphore */ \n os_sem_init ( task2_sem , 0 );\n }\n\n /** * init_app_tasks * * This function performs initializations that are required before tasks run. * * @return int 0 success; error otherwise. */ \n static int \n init_app_tasks ( void )\n {\n /* * Call task specific initialization functions to initialize any shared objects * before initializing the tasks with the OS. */ \n task1_init ();\n task2_init ();\n\n /* * Initialize tasks 1 and 2 with the OS. */ \n os_task_init ( task1 , task1 , task1_handler , NULL , TASK1_PRIO , \n OS_WAIT_FOREVER , task1_stack , TASK1_STACK_SIZE );\n\n os_task_init ( task2 , task2 , task2_handler , NULL , TASK2_PRIO , \n OS_WAIT_FOREVER , task2_stack , TASK2_STACK_SIZE );\n\n return 0 ;\n }\n\n /** * main * * The main function for the application. This function initializes the system and packages, * calls the application specific task initialization function, then waits and dispatches * events from the OS default event queue in an infinite loop. */ \n int \n main ( int argc , char **arg )\n {\n\n /* Perform system and package initialization */ \n sysinit ();\n\n /* Initialize application specific tasks */ \n init_app_tasks ();\n\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n /* main never returns */ \n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mynewt_os/#os-functions",
- "text": "The functions available at the OS level are: os_started",
- "title": "OS Functions"
- },
- {
- "location": "/os/core_os/os_started/",
- "text": "os_started\n\n\nint\n \nos_started\n(\nvoid\n)\n\n\n\n\n\nReturns 'true' (1) if the os has been started; 0 otherwise.\n\n\n\n\nArguments\n\n\nNone\n\n\n\n\nReturned values\n\n\nInteger value with 0 meaning the OS has not been started and 1 indicating the OS has been started (i.e. \nos_start()\n has been called).",
- "title": "os_started"
- },
- {
- "location": "/os/core_os/os_started/#os_started",
- "text": "int os_started ( void ) Returns 'true' (1) if the os has been started; 0 otherwise.",
- "title": "os_started"
- },
- {
- "location": "/os/core_os/os_started/#arguments",
- "text": "None",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/os_started/#returned-values",
- "text": "Integer value with 0 meaning the OS has not been started and 1 indicating the OS has been started (i.e. os_start() has been called).",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/context_switch/",
- "text": "Scheduler/Context Switching\n\n\nScheduler's job is to maintain the list of tasks and decide which one should be running next.\n\n\nDescription\n\n\nTask states can be \nrunning\n, \nready to run\n or \nsleeping\n.\n\n\nWhen a task is \nrunning\n, the CPU is executing in that task's context. The program counter (PC) is pointing to instructions that task wants to execute and the stack pointer (SP) is pointing to that task's stack.\n\n\nA task which is \nready to run\n wants to get on the CPU to do its work.\n\n\nA task which is \nsleeping\n has no more work to do. It's waiting for someone or something else to wake it up.\n\n\nThe Scheduler algorithm is simple: from among the tasks which are ready to run, pick the the one with highest priority (lowest numeric value in task's \nt_prio\n field), and make its state \nrunning\n.\n\n\nTasks which are either \nrunning\n or \nready to run\n are kept in a linked list \ng_os_run_list\n. This list is ordered by priority.\n\n\nTasks which are \nsleeping\n are kept in a linked list \ng_os_sleep_list\n.\n\n\nThe scheduler has a CPU architecture specific component; this code is responsible for swapping in the task which should be \nrunning\n. This process is called context switch. During context switching the state of the CPU (e.g. registers) for the currently \nrunning\n task is stored and the new task is swapped in.\n\n\nList of Functions\n\n\nThe functions available in context_switch are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_sched\n\n\nPerforms context switch if needed.\n\n\n\n\n\n\nos_arch_ctx_sw\n\n\nChange the state of a given task to \nrunning\n.\n\n\n\n\n\n\nos_sched_ctx_sw_hook\n\n\nPerforms task accounting when context switching.\n\n\n\n\n\n\nos_sched_get_current_task\n\n\nReturns the pointer to the task which is currently \nrunning\n.\n\n\n\n\n\n\nos_sched_insert\n\n\nInsert a task into scheduler's \nready to run\n list.\n\n\n\n\n\n\nos_sched_next_task\n\n\nReturns the pointer to highest priority task from the list which are \nready to run\n.\n\n\n\n\n\n\nos_sched_os_timer_exp\n\n\nInform scheduler that OS time has moved forward.\n\n\n\n\n\n\nos_sched_remove\n\n\nStops a task and removes it from all the OS task lists.\n\n\n\n\n\n\nos_sched_resort\n\n\nInform scheduler that the priority of the given task has changed and the \nready to run\n list should be re-sorted.\n\n\n\n\n\n\nos_sched_set_current_task\n\n\nSets the given task to \nrunning\n.\n\n\n\n\n\n\nos_sched_sleep\n\n\nThe given task's state is changed from \nready to run\n to \nsleeping\n.\n\n\n\n\n\n\nos_sched_wakeup\n\n\nCalled to make task \nready to run\n. If task is \nsleeping\n, it is woken up.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/context_switch/context_switch/#schedulercontext-switching",
- "text": "Scheduler's job is to maintain the list of tasks and decide which one should be running next.",
- "title": "Scheduler/Context Switching"
- },
- {
- "location": "/os/core_os/context_switch/context_switch/#description",
- "text": "Task states can be running , ready to run or sleeping . When a task is running , the CPU is executing in that task's context. The program counter (PC) is pointing to instructions that task wants to execute and the stack pointer (SP) is pointing to that task's stack. A task which is ready to run wants to get on the CPU to do its work. A task which is sleeping has no more work to do. It's waiting for someone or something else to wake it up. The Scheduler algorithm is simple: from among the tasks which are ready to run, pick the the one with highest priority (lowest numeric value in task's t_prio field), and make its state running . Tasks which are either running or ready to run are kept in a linked list g_os_run_list . This list is ordered by priority. Tasks which are sleeping are kept in a linked list g_os_sleep_list . The scheduler has a CPU architecture specific component; this code is responsible for swapping in the task which should be running . This process is called context switch. During context switching the state of the CPU (e.g. registers) for the currently running task is stored and the new task is swapped in.",
- "title": "Description"
- },
- {
- "location": "/os/core_os/context_switch/context_switch/#list-of-functions",
- "text": "The functions available in context_switch are: Function Description os_sched Performs context switch if needed. os_arch_ctx_sw Change the state of a given task to running . os_sched_ctx_sw_hook Performs task accounting when context switching. os_sched_get_current_task Returns the pointer to the task which is currently running . os_sched_insert Insert a task into scheduler's ready to run list. os_sched_next_task Returns the pointer to highest priority task from the list which are ready to run . os_sched_os_timer_exp Inform scheduler that OS time has moved forward. os_sched_remove Stops a task and removes it from all the OS task lists. os_sched_resort Inform scheduler that the priority of the given task has changed and the ready to run list should be re-sorted. os_sched_set_current_task Sets the given task to running . os_sched_sleep The given task's state is changed from ready to run to sleeping . os_sched_wakeup Called to make task ready to run . If task is sleeping , it is woken up.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/context_switch/os_sched/",
- "text": "os_sched \n\n\nvoid\n \nos_sched\n(\nstruct\n \nos_task\n \n*next_t\n)\n\n\n\n\n\nPerforms context switch if needed. If \nnext_t\n is set, that task will be made \nrunning\n. If \nnext_t\n is \nNULL\n, highest priority \nready to run\n is swapped in. This function can be called when new tasks were made \nready to run\n or if the current task is moved to \nsleeping\n state.\n\n\nThis function will call the architecture specific routine to swap in the new task.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next (optional)\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nInterrupts must be disabled when calling this.\n\n\nExample\n\n\n\n\nos_error_t\n\n\nos_mutex_release\n(\nstruct\n \nos_mutex\n \n*mu\n)\n{\n ...\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n\n \n/* Re-schedule if needed */\n\n \nif\n (\nresched\n) {\n \nos_sched\n(\nrdy\n);\n }\n\n \nreturn\n \nOS_OK\n;\n\n}",
- "title": "os_sched"
- },
- {
- "location": "/os/core_os/context_switch/os_sched/#os_sched",
- "text": "void os_sched ( struct os_task *next_t ) Performs context switch if needed. If next_t is set, that task will be made running . If next_t is NULL , highest priority ready to run is swapped in. This function can be called when new tasks were made ready to run or if the current task is moved to sleeping state. This function will call the architecture specific routine to swap in the new task.",
- "title": " os_sched "
- },
- {
- "location": "/os/core_os/context_switch/os_sched/#arguments",
- "text": "Arguments Description next_t Pointer to task which must run next (optional)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched/#notes",
- "text": "Interrupts must be disabled when calling this.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched/#example",
- "text": "os_error_t os_mutex_release ( struct os_mutex *mu )\n{\n ...\n OS_EXIT_CRITICAL ( sr );\n\n /* Re-schedule if needed */ \n if ( resched ) {\n os_sched ( rdy );\n }\n\n return OS_OK ;\n\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw/",
- "text": "os_arch_ctx_sw \n\n\nvoid\n \nos_arch_ctx_sw\n(\nstruct\n \nos_task\n \n*next_t\n)\n\n\n\n\n\nChange the state of task pointed by \nnext_t\n to be \nrunning\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnext_t\n\n\nPointer to task which must run next\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nThis would get called from another task's context.\n\n\nExample\n\n\n\n\nvoid\n\n \nos_sched\n(\nstruct\n \nos_task\n \n*next_t\n)\n {\n \nos_sr_t\n \nsr\n;\n\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n\n \nif\n (\n!next_t\n) {\n \nnext_t\n \n=\n \nos_sched_next_task\n();\n }\n\n \nif\n (\nnext_t\n \n!=\n \ng_current_task\n) {\n \nos_arch_ctx_sw\n(\nnext_t\n);\n }\n\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n }",
- "title": "os_arch_ctx_sw"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw/#os_arch_ctx_sw",
- "text": "void os_arch_ctx_sw ( struct os_task *next_t ) Change the state of task pointed by next_t to be running .",
- "title": " os_arch_ctx_sw "
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw/#arguments",
- "text": "Arguments Description next_t Pointer to task which must run next",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw/#notes",
- "text": "This would get called from another task's context.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_arch_ctx_sw/#example",
- "text": "void \n os_sched ( struct os_task *next_t )\n {\n os_sr_t sr ;\n\n OS_ENTER_CRITICAL ( sr );\n\n if ( !next_t ) {\n next_t = os_sched_next_task ();\n }\n\n if ( next_t != g_current_task ) {\n os_arch_ctx_sw ( next_t );\n }\n\n OS_EXIT_CRITICAL ( sr );\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/",
- "text": "os_sched_ctx_sw_hook \n\n\nvoid\n \nos_sched_ctx_sw_hook\n(\nstruct\n \nos_task\n \n*next_t\n)\n\n\n\n\n\nPerforms task accounting when context switching.\n\n\nThis function must be called from the architecture specific context switching routine \nos_arch_ctx_sw()\n before resuming execution of the \nrunning\n task.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\n\n\nos_arch_ctx_sw\n(\nstruct\n \nos_task\n \n*t\n)\n{\n \nos_sched_ctx_sw_hook\n(\nt\n);\n\n \n/* Set PendSV interrupt pending bit to force context switch */\n\n \nSCB-\nICSR\n \n=\n \nSCB_ICSR_PENDSVSET_Msk\n;\n}",
- "title": "os_sched_ctx_sw_hook"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/#os_sched_ctx_sw_hook",
- "text": "void os_sched_ctx_sw_hook ( struct os_task *next_t ) Performs task accounting when context switching. This function must be called from the architecture specific context switching routine os_arch_ctx_sw() before resuming execution of the running task.",
- "title": " os_sched_ctx_sw_hook "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_ctx_sw_hook/#example",
- "text": "void os_arch_ctx_sw ( struct os_task *t )\n{\n os_sched_ctx_sw_hook ( t );\n\n /* Set PendSV interrupt pending bit to force context switch */ \n SCB- ICSR = SCB_ICSR_PENDSVSET_Msk ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_get_current_task/",
- "text": "os_sched_get_current_task \n\n\nstruct\n \nos_task\n \n*os_sched_get_current_task\n(\nvoid\n)\n\n\n\n\n\nReturns the pointer to task which is currently \nrunning\n.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nSee description.\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\n\n\nos_time_delay\n(\nint32_t\n \nosticks\n)\n{\n \nos_sr_t\n \nsr\n;\n\n \nif\n (\nosticks\n \n \n0\n) {\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n \nos_sched_sleep\n(\nos_sched_get_current_task\n(), (\nos_time_t\n)\nosticks\n);\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n \nos_sched\n(\nNULL\n);\n }\n}",
- "title": "os_sched_get_current_task"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_get_current_task/#os_sched_get_current_task",
- "text": "struct os_task *os_sched_get_current_task ( void ) Returns the pointer to task which is currently running .",
- "title": " os_sched_get_current_task "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_get_current_task/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_get_current_task/#returned-values",
- "text": "See description.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_get_current_task/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_get_current_task/#example",
- "text": "void os_time_delay ( int32_t osticks )\n{\n os_sr_t sr ;\n\n if ( osticks 0 ) {\n OS_ENTER_CRITICAL ( sr );\n os_sched_sleep ( os_sched_get_current_task (), ( os_time_t ) osticks );\n OS_EXIT_CRITICAL ( sr );\n os_sched ( NULL );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_insert/",
- "text": "os_sched_insert \n\n\nos_error_t\n \nos_sched_insert\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nInsert task into scheduler's \nready to run\n list.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns \nOS_EINVAL\n if task state is not \nREADY\n.\nReturns 0 on success.\n\n\nNotes\n\n\nYou probably don't need to call this.",
- "title": "os_sched_insert"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_insert/#os_sched_insert",
- "text": "os_error_t os_sched_insert ( struct os_task *t ) Insert task into scheduler's ready to run list.",
- "title": " os_sched_insert "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_insert/#arguments",
- "text": "Arguments Description t Pointer to task",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_insert/#returned-values",
- "text": "Returns OS_EINVAL if task state is not READY .\nReturns 0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_insert/#notes",
- "text": "You probably don't need to call this.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_next_task/",
- "text": "os_sched_next_task \n\n\nstruct\n \nos_task\n \n*os_sched_next_task\n(\nvoid\n)\n\n\n\n\n\nReturns the pointer to highest priority task from the list which are \nready to run\n.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nSee description.\n\n\nNotes\n\n\nShould be called with interrupts disabled.",
- "title": "os_sched_next_task"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_next_task/#os_sched_next_task",
- "text": "struct os_task *os_sched_next_task ( void ) Returns the pointer to highest priority task from the list which are ready to run .",
- "title": " os_sched_next_task "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_next_task/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_next_task/#returned-values",
- "text": "See description.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_next_task/#notes",
- "text": "Should be called with interrupts disabled.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_os_timer_exp/",
- "text": "os_sched_os_timer_exp \n\n\nvoid\n \nos_sched_os_timer_exp\n(\nvoid\n)\n\n\n\n\n\nInform scheduler that OS time has moved forward, and it should inspect tasks which are \nsleeping\n to check whether they should be moved to \ng_run_list\n or not.\n\n\nThis function should be called from code which handles moving OS time forward. After calling it, the highest priority task which is \nready to run\n might've changed, so call to \nos_sched()\n should be done.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\n\n\ntimer_handler\n(\nvoid\n)\n{\n \nos_time_tick\n();\n \nos_callout_tick\n();\n \nos_sched_os_timer_exp\n();\n \nos_sched\n(\nNULL\n);\n}",
- "title": "os_sched_os_timer_exp"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_os_timer_exp/#os_sched_os_timer_exp",
- "text": "void os_sched_os_timer_exp ( void ) Inform scheduler that OS time has moved forward, and it should inspect tasks which are sleeping to check whether they should be moved to g_run_list or not. This function should be called from code which handles moving OS time forward. After calling it, the highest priority task which is ready to run might've changed, so call to os_sched() should be done.",
- "title": " os_sched_os_timer_exp "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_os_timer_exp/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_os_timer_exp/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_os_timer_exp/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_os_timer_exp/#example",
- "text": "void timer_handler ( void )\n{\n os_time_tick ();\n os_callout_tick ();\n os_sched_os_timer_exp ();\n os_sched ( NULL );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_remove/",
- "text": "os_sched_remove \n\n\nint\n \nos_sched_remove\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nStops and removes task \nt\n.\n\n\nThe function removes the task from the \ng_os_task_list\n task list. It also removes the task from one of the following task list:\n\n\n\n\ng_os_run_list\n if the task is in the Ready state.\n\n\ng_os_sleep_list\n if the task is in the Sleep state.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to the \nos_task\n structure for the task to be removed.\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK - The task is removed successfully.\n\n\nNotes\n\n\nThis function must be called with all interrupts disabled.\n\n\nExample\n\n\nThe \nos_task_remove\n function calls the \nos_sched_remove\n function to remove a task:\n\n\nint\n\n\nos_task_remove\n(\nstruct\n \nos_task\n \n*t\n)\n{\n \nint\n \nrc\n;\n \nos_sr_t\n \nsr\n;\n\n \n/* Add error checking code to ensure task can removed. */\n\n\n\n \n/* Call os_sched_remove to remove the task. */\n\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n \nrc\n \n=\n \nos_sched_remove\n(\nt\n);\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n \nreturn\n \nrc\n;\n}",
- "title": "os_sched_remove"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_remove/#os_sched_remove",
- "text": "int os_sched_remove ( struct os_task *t ) Stops and removes task t . The function removes the task from the g_os_task_list task list. It also removes the task from one of the following task list: g_os_run_list if the task is in the Ready state. g_os_sleep_list if the task is in the Sleep state.",
- "title": " os_sched_remove "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_remove/#arguments",
- "text": "Arguments Description t Pointer to the os_task structure for the task to be removed.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_remove/#returned-values",
- "text": "OS_OK - The task is removed successfully.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_remove/#notes",
- "text": "This function must be called with all interrupts disabled.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_remove/#example",
- "text": "The os_task_remove function calls the os_sched_remove function to remove a task: int os_task_remove ( struct os_task *t )\n{\n int rc ;\n os_sr_t sr ;\n\n /* Add error checking code to ensure task can removed. */ \n\n\n /* Call os_sched_remove to remove the task. */ \n OS_ENTER_CRITICAL ( sr );\n rc = os_sched_remove ( t );\n OS_EXIT_CRITICAL ( sr );\n return rc ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_resort/",
- "text": "os_sched_resort \n\n\nvoid\n \nos_sched_resort\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nInform scheduler that the priority of the task \nt\n has changed (e.g. in order to avoid priority inversion), and the \nready to run\n list should be re-sorted.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to a task whose priority has changed\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nt\n must be \nready to run\n before calling this.\n\n\nExample\n\n\n\n\nos_error_t\n\n\nos_mutex_pend\n(\nstruct\n \nos_mutex\n \n*mu\n, \nuint32_t\n \ntimeout\n)\n{\n ....\n \n/* Change priority of owner if needed */\n\n \nif\n (\nmu-\nmu_owner-\nt_prio\n \n \ncurrent-\nt_prio\n) {\n \nmu-\nmu_owner-\nt_prio\n \n=\n \ncurrent-\nt_prio\n;\n \nos_sched_resort\n(\nmu-\nmu_owner\n);\n }\n ....\n}",
- "title": "os_sched_resort"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_resort/#os_sched_resort",
- "text": "void os_sched_resort ( struct os_task *t ) Inform scheduler that the priority of the task t has changed (e.g. in order to avoid priority inversion), and the ready to run list should be re-sorted.",
- "title": " os_sched_resort "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_resort/#arguments",
- "text": "Arguments Description t Pointer to a task whose priority has changed",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_resort/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_resort/#notes",
- "text": "t must be ready to run before calling this.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_resort/#example",
- "text": "os_error_t os_mutex_pend ( struct os_mutex *mu , uint32_t timeout )\n{\n ....\n /* Change priority of owner if needed */ \n if ( mu- mu_owner- t_prio current- t_prio ) {\n mu- mu_owner- t_prio = current- t_prio ;\n os_sched_resort ( mu- mu_owner );\n }\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_set_current_task/",
- "text": "os_sched_set_current_task \n\n\nvoid\n \n\nos_sched_set_current_task\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nSets the currently running task to \nt\n.\n\n\nThis is called from architecture specific context switching code to update scheduler state. Call is made when state of the task \nt\n is made \nrunning\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to a task\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nThis function simply sets the global variable holding the currently running task. It does not perform a context switch or change the os run or sleep list.",
- "title": "os_sched_set_current_task"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_set_current_task/#os_sched_set_current_task",
- "text": "void os_sched_set_current_task ( struct os_task *t ) Sets the currently running task to t . This is called from architecture specific context switching code to update scheduler state. Call is made when state of the task t is made running .",
- "title": " os_sched_set_current_task "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_set_current_task/#arguments",
- "text": "Arguments Description t Pointer to a task",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_set_current_task/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_set_current_task/#notes",
- "text": "This function simply sets the global variable holding the currently running task. It does not perform a context switch or change the os run or sleep list.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_sleep/",
- "text": "os_sched_sleep \n\n\nint\n\n\nos_sched_sleep\n(\nstruct\n \nos_task\n \n*t\n, \nos_time_t\n \nnticks\n)\n\n\n\n\n\nTask \nt\n state is changed from \nready to run\n to \nsleeping\n. Sleep time will be specified in \nnticks\n.\n\n\nTask will be woken up after sleep timer expires, unless there are other signals causing it to wake up.\n\n\nIf \nnticks\n is set to \nOS_TIMEOUT_NEVER\n, task never wakes up with a sleep timer.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\nnticks\n\n\nNumber of ticks to sleep in OS ticks\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nNotes\n\n\nMust be called with interrupts disabled.\n\n\nExample\n\n\n\n\nstruct\n \nos_event\n \n*\n\n\nos_eventq_get\n(\nstruct\n \nos_eventq\n \n*evq\n)\n{\n \nstruct\n \nos_event\n \n*ev\n;\n \nos_sr_t\n \nsr\n;\n\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n\npull_one\n:\n \nev\n \n=\n \nSTAILQ_FIRST\n(\nevq-\nevq_list\n);\n \nif\n (\nev\n) {\n \nSTAILQ_REMOVE\n(\nevq-\nevq_list\n, \nev\n, \nos_event\n, \nev_next\n);\n \nev-\nev_queued\n \n=\n \n0\n;\n } \nelse\n {\n \nevq-\nevq_task\n \n=\n \nos_sched_get_current_task\n();\n \nos_sched_sleep\n(\nevq-\nevq_task\n, \nOS_TIMEOUT_NEVER\n);\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n\n \nos_sched\n(\nNULL\n);\n\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n \nevq-\nevq_task\n \n=\n \nNULL\n;\n \ngoto\n \npull_one\n;\n }\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n\n \nreturn\n (\nev\n);\n}",
- "title": "os_sched_sleep"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_sleep/#os_sched_sleep",
- "text": "int os_sched_sleep ( struct os_task *t , os_time_t nticks ) Task t state is changed from ready to run to sleeping . Sleep time will be specified in nticks . Task will be woken up after sleep timer expires, unless there are other signals causing it to wake up. If nticks is set to OS_TIMEOUT_NEVER , task never wakes up with a sleep timer.",
- "title": " os_sched_sleep "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_sleep/#arguments",
- "text": "Arguments Description t Pointer to task nticks Number of ticks to sleep in OS ticks",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_sleep/#returned-values",
- "text": "Returns 0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_sleep/#notes",
- "text": "Must be called with interrupts disabled.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_sleep/#example",
- "text": "struct os_event * os_eventq_get ( struct os_eventq *evq )\n{\n struct os_event *ev ;\n os_sr_t sr ;\n\n OS_ENTER_CRITICAL ( sr ); pull_one :\n ev = STAILQ_FIRST ( evq- evq_list );\n if ( ev ) {\n STAILQ_REMOVE ( evq- evq_list , ev , os_event , ev_next );\n ev- ev_queued = 0 ;\n } else {\n evq- evq_task = os_sched_get_current_task ();\n os_sched_sleep ( evq- evq_task , OS_TIMEOUT_NEVER );\n OS_EXIT_CRITICAL ( sr );\n\n os_sched ( NULL );\n\n OS_ENTER_CRITICAL ( sr );\n evq- evq_task = NULL ;\n goto pull_one ;\n }\n OS_EXIT_CRITICAL ( sr );\n\n return ( ev );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_wakeup/",
- "text": "os_sched_wakeup \n\n\nint\n\n\nos_sched_wakeup\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nCalled to make task \nready to run\n. If task is \nsleeping\n, it is woken up.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nNotes\n\n\nExample\n\n\n\n\nvoid\n\n\nos_eventq_put\n(\nstruct\n \nos_eventq\n \n*evq\n, \nstruct\n \nos_event\n \n*ev\n)\n{\n ....\n \n/* If task waiting on event, wake it up. */\n\n \nresched\n \n=\n \n0\n;\n \nif\n (\nevq-\nevq_task\n) {\n \nos_sched_wakeup\n(\nevq-\nevq_task\n);\n \nevq-\nevq_task\n \n=\n \nNULL\n;\n \nresched\n \n=\n \n1\n;\n }\n ....\n}",
- "title": "os_sched_wakeup"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_wakeup/#os_sched_wakeup",
- "text": "int os_sched_wakeup ( struct os_task *t ) Called to make task ready to run . If task is sleeping , it is woken up.",
- "title": " os_sched_wakeup "
- },
- {
- "location": "/os/core_os/context_switch/os_sched_wakeup/#arguments",
- "text": "Arguments Description t Pointer to task",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_wakeup/#returned-values",
- "text": "Returns 0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_wakeup/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/context_switch/os_sched_wakeup/#example",
- "text": "void os_eventq_put ( struct os_eventq *evq , struct os_event *ev )\n{\n ....\n /* If task waiting on event, wake it up. */ \n resched = 0 ;\n if ( evq- evq_task ) {\n os_sched_wakeup ( evq- evq_task );\n evq- evq_task = NULL ;\n resched = 1 ;\n }\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime/",
- "text": "CPU Time\n\n\nThe MyNewt \ncputime\n module provides high resolution time and timer support. \n\n\nDescription\n\n\nThe \ncputime\n API provides high resolution time and timer support. The module must be initialized, using the \nos_cputime_init()\n function, with the clock frequency to use. The module uses the \nhal_timer\n API, defined in hal/hal_timer.h, to access the hardware timers. It uses the hardware timer number specified by the \nOS_CPUTIME_TIMER_NUM\n system configuration setting.\n\n\nData Structures\n\n\nThe module uses the following data structures:\n\n\n\n\nuint32_t\n to represent \ncputime\n. Only the lower 32 bits of a 64 timer are used. \n\n\nstruct hal_timer\n to represent a cputime timer.\n\n\n\n\nList of Functions\n\n\nThe functions available in cputime are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_cputime_delay_nsecs\n\n\nDelays for a specified number of nanoseconds.\n\n\n\n\n\n\nos_cputime_delay_ticks\n\n\nDelays for a specified number of ticks.\n\n\n\n\n\n\nos_cputime_delay_usecs\n\n\nDelays for a specified number of microseconds.\n\n\n\n\n\n\nos_cputime_get32\n\n\nGets the current value of the cpu time.\n\n\n\n\n\n\nos_cputime_init\n\n\nInitializes the cputime module.\n\n\n\n\n\n\nos_cputime_nsecs_to_ticks\n\n\nConverts the specified number of nanoseconds to number of ticks.\n\n\n\n\n\n\nos_cputime_ticks_to_nsecs\n\n\nConverts the specified number of ticks to number of nanoseconds.\n\n\n\n\n\n\nos_cputime_ticks_to_usecs\n\n\nConverts the specified number of ticks to number of microseconds.\n\n\n\n\n\n\nos_cputime_timer_init\n\n\nInitializes a timer.\n\n\n\n\n\n\nos_cputime_timer_relative\n\n\nSets a timer to expire in the specified number of microseconds from the current time.\n\n\n\n\n\n\nos_cputime_timer_start\n\n\nSets a timer to expire at the specified cputime.\n\n\n\n\n\n\nos_cputime_timer_stop\n\n\nStops a timer from running.\n\n\n\n\n\n\nos_cputime_usecs_to_ticks\n\n\nConverts the specified number of microseconds to number of ticks.\n\n\n\n\n\n\n\n\nList of Macros\n\n\nThese macros should be used to evaluate the time with respect to each other.\n\n\n\n\nCPUIME_LT(t1,t2)\n -- evaluates to true if t1 is before t2 in time.\n\n\nCPUTIME_GT(t1,t2)\n -- evaluates to true if t1 is after t2 in time \n\n\nCPUTIME_LEQ(t1,t2)\n -- evaluates to true if t1 is on or before t2 in time.\n\n\nCPUTIME_GEQ(t1,t2)\n -- evaluates to true if t1 is on or after t2 in time.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/cputime/os_cputime/#cpu-time",
- "text": "The MyNewt cputime module provides high resolution time and timer support.",
- "title": "CPU Time"
- },
- {
- "location": "/os/core_os/cputime/os_cputime/#description",
- "text": "The cputime API provides high resolution time and timer support. The module must be initialized, using the os_cputime_init() function, with the clock frequency to use. The module uses the hal_timer API, defined in hal/hal_timer.h, to access the hardware timers. It uses the hardware timer number specified by the OS_CPUTIME_TIMER_NUM system configuration setting.",
- "title": "Description"
- },
- {
- "location": "/os/core_os/cputime/os_cputime/#data-structures",
- "text": "The module uses the following data structures: uint32_t to represent cputime . Only the lower 32 bits of a 64 timer are used. struct hal_timer to represent a cputime timer.",
- "title": "Data Structures"
- },
- {
- "location": "/os/core_os/cputime/os_cputime/#list-of-functions",
- "text": "The functions available in cputime are: Function Description os_cputime_delay_nsecs Delays for a specified number of nanoseconds. os_cputime_delay_ticks Delays for a specified number of ticks. os_cputime_delay_usecs Delays for a specified number of microseconds. os_cputime_get32 Gets the current value of the cpu time. os_cputime_init Initializes the cputime module. os_cputime_nsecs_to_ticks Converts the specified number of nanoseconds to number of ticks. os_cputime_ticks_to_nsecs Converts the specified number of ticks to number of nanoseconds. os_cputime_ticks_to_usecs Converts the specified number of ticks to number of microseconds. os_cputime_timer_init Initializes a timer. os_cputime_timer_relative Sets a timer to expire in the specified number of microseconds from the current time. os_cputime_timer_start Sets a timer to expire at the specified cputime. os_cputime_timer_stop Stops a timer from running. os_cputime_usecs_to_ticks Converts the specified number of microseconds to number of ticks.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/cputime/os_cputime/#list-of-macros",
- "text": "These macros should be used to evaluate the time with respect to each other. CPUIME_LT(t1,t2) -- evaluates to true if t1 is before t2 in time. CPUTIME_GT(t1,t2) -- evaluates to true if t1 is after t2 in time CPUTIME_LEQ(t1,t2) -- evaluates to true if t1 is on or before t2 in time. CPUTIME_GEQ(t1,t2) -- evaluates to true if t1 is on or after t2 in time.",
- "title": "List of Macros"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_nsecs/",
- "text": "os_cputime_delay_nsecs\n\n\nvoid\n \nos_cputime_delay_nsecs\n(\nuint32_t\n \nnsecs\n)\n\n\n\n\n\nWaits for a specified number of nanoseconds to elapse before returning.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnsecs\n\n\nNumber of nanoseconds to delay for.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\nDelays for 250000 nsecs:\n\n\nos_cputime_delay_nsecs\n(\n250000\n)",
- "title": "os_cputime_delay_nsecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_nsecs/#os_cputime_delay_nsecs",
- "text": "void os_cputime_delay_nsecs ( uint32_t nsecs ) Waits for a specified number of nanoseconds to elapse before returning.",
- "title": "os_cputime_delay_nsecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_nsecs/#arguments",
- "text": "Arguments Description nsecs Number of nanoseconds to delay for.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_nsecs/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_nsecs/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_nsecs/#example",
- "text": "Delays for 250000 nsecs: os_cputime_delay_nsecs ( 250000 )",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_ticks/",
- "text": "os_cputime_delay_ticks\n\n\nvoid\n \nos_cputime_delay_ticks\n(\nuint32_t\n \nticks\n)\n\n\n\n\n\nWaits for a specified number of ticks to elapse before returning.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nticks\n\n\nNumber of ticks to delay for.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\nDelays for 100000 ticks:\n\n\nos_cputime_delay_ticks\n(\n100000\n)",
- "title": "os_cputime_delay_ticks"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_ticks/#os_cputime_delay_ticks",
- "text": "void os_cputime_delay_ticks ( uint32_t ticks ) Waits for a specified number of ticks to elapse before returning.",
- "title": "os_cputime_delay_ticks"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_ticks/#arguments",
- "text": "Arguments Description ticks Number of ticks to delay for.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_ticks/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_ticks/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_ticks/#example",
- "text": "Delays for 100000 ticks: os_cputime_delay_ticks ( 100000 )",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_usecs/",
- "text": "os_cputime_delay_usecs\n\n\nvoid\n \nos_cputime_delay_usecs\n(\nuint32_t\n \nusecs\n)\n\n\n\n\n\nWaits for a specified number of microseconds to elapse before returning.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nusecs\n\n\nNumber of microseconds to delay for.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\nDelays for 250000 usecs:\n\n\nos_cputime_delay_usecs\n(\n250000\n)",
- "title": "os_cputime_delay_usecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_usecs/#os_cputime_delay_usecs",
- "text": "void os_cputime_delay_usecs ( uint32_t usecs ) Waits for a specified number of microseconds to elapse before returning.",
- "title": "os_cputime_delay_usecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_usecs/#arguments",
- "text": "Arguments Description usecs Number of microseconds to delay for.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_usecs/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_usecs/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_delay_usecs/#example",
- "text": "Delays for 250000 usecs: os_cputime_delay_usecs ( 250000 )",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_get32/",
- "text": "os_cputime_get32\n\n\nuint32_t\n \nos_cputime_get32\n(\nvoid\n)\n\n\n\n\n\nGets the current cputime. If a timer is 64 bits, only the lower 32 bit is returned.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nThe current cputime.\n\n\nNotes\n\n\nExample\n\n\nuint32\n \ncur_cputime\n;\n\ncur_cputime\n \n=\n \nos_cputime_get32\n();",
- "title": "os_cputime_get32"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_get32/#os_cputime_get32",
- "text": "uint32_t os_cputime_get32 ( void ) Gets the current cputime. If a timer is 64 bits, only the lower 32 bit is returned.",
- "title": "os_cputime_get32"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_get32/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_get32/#returned-values",
- "text": "The current cputime.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_get32/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_get32/#example",
- "text": "uint32 cur_cputime ; cur_cputime = os_cputime_get32 ();",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_init/",
- "text": "os_cputime_init\n\n\nint\n \nos_cputime_init\n(\nuint32_t\n \nclock_freq\n)\n\n\n\n\n\nInitializes the cputime module with the clock frequency (in HZ) to use for the timer resolution. It configures the hardware timer specified by the \nOS_CPUTIME_TIMER_NUM\n sysconfig value to run at the specified clock frequency.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nclock_freq\n\n\nClock frequency, in HZ, for the timer resolution.\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success and -1 on error.\n\n\nNotes\n\n\nThis function must be called after os_init is called. It should only be called once and before any other timer API and hardware timers are used.\n\n\nExample\n\n\nA BSP package usually calls this function and uses the \nOS_CPUTIME_FREQUENCY\n sysconfig value for the clock frequency argument:\n\n\nint\n \nrc\n\n\nrc\n \n=\n \nos_cputime_init\n(\nMYNEWT_VAL\n(\nOS_CPUTIME_FREQUENCY\n));",
- "title": "os_cputime_init"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_init/#os_cputime_init",
- "text": "int os_cputime_init ( uint32_t clock_freq ) Initializes the cputime module with the clock frequency (in HZ) to use for the timer resolution. It configures the hardware timer specified by the OS_CPUTIME_TIMER_NUM sysconfig value to run at the specified clock frequency.",
- "title": "os_cputime_init"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_init/#arguments",
- "text": "Arguments Description clock_freq Clock frequency, in HZ, for the timer resolution.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_init/#returned-values",
- "text": "0 on success and -1 on error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_init/#notes",
- "text": "This function must be called after os_init is called. It should only be called once and before any other timer API and hardware timers are used.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_init/#example",
- "text": "A BSP package usually calls this function and uses the OS_CPUTIME_FREQUENCY sysconfig value for the clock frequency argument: int rc rc = os_cputime_init ( MYNEWT_VAL ( OS_CPUTIME_FREQUENCY ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_nsecs_to_ticks/",
- "text": "os_cputime_nsecs_to_ticks\n\n\nuint32_t\n \nos_cputime_nsecs_to_ticks\n(\nuint32_t\n \nnsecs\n)\n\n\n\n\n\nConverts a specified number of nanoseconds to cputime ticks.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnsecs\n\n\nNumber of nanoseconds to convert to ticks.\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of ticks in \nnsecs\n nanoseconds.\n\n\nNotes\n\n\nExample\n\n\nuint32_t\n \nnum_ticks\n;\n\nnum_ticks\n \n=\n \nos_cputime_nsecs_to_ticks\n(\n1000000\n);",
- "title": "os_cputime_nsecs_to_ticks"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_nsecs_to_ticks/#os_cputime_nsecs_to_ticks",
- "text": "uint32_t os_cputime_nsecs_to_ticks ( uint32_t nsecs ) Converts a specified number of nanoseconds to cputime ticks.",
- "title": "os_cputime_nsecs_to_ticks"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_nsecs_to_ticks/#arguments",
- "text": "Arguments Description nsecs Number of nanoseconds to convert to ticks.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_nsecs_to_ticks/#returned-values",
- "text": "The number of ticks in nsecs nanoseconds.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_nsecs_to_ticks/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_nsecs_to_ticks/#example",
- "text": "uint32_t num_ticks ; num_ticks = os_cputime_nsecs_to_ticks ( 1000000 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_nsecs/",
- "text": "os_cputime_ticks_to_nsecs\n\n\nuint32_t\n \nos_cputime_ticks_to_nsecs\n(\nuint32_t\n \nticks\n)\n\n\n\n\n\nConverts cputime ticks to nanoseconds.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nticks\n\n\nNumber of cputime ticks to convert to nanoseconds.\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of nanoseconds in \nticks\n number of ticks.\n\n\nNotes\n\n\nExample\n\n\nuint32_t\n \nnum_nsecs\n;\n\nnum_nsecs\n \n=\n \nos_cputime_ticks_to_nsecs\n(\n1000000\n);",
- "title": "os_cputime_ticks_to_nsecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_nsecs/#os_cputime_ticks_to_nsecs",
- "text": "uint32_t os_cputime_ticks_to_nsecs ( uint32_t ticks ) Converts cputime ticks to nanoseconds.",
- "title": "os_cputime_ticks_to_nsecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_nsecs/#arguments",
- "text": "Arguments Description ticks Number of cputime ticks to convert to nanoseconds.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_nsecs/#returned-values",
- "text": "The number of nanoseconds in ticks number of ticks.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_nsecs/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_nsecs/#example",
- "text": "uint32_t num_nsecs ; num_nsecs = os_cputime_ticks_to_nsecs ( 1000000 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_usecs/",
- "text": "os_cputime_ticks_to_usecs\n\n\nuint32_t\n \nos_cputime_ticks_to_usecs\n(\nuint32_t\n \nticks\n)\n\n\n\n\n\nConverts a specified number of cputime ticks to microseconds.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nticks\n\n\nNumber of cputime ticks to convert to microseconds.\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of microseconds in \nticks\n number of ticks.\n\n\nNotes\n\n\nExample\n\n\nuint32_t\n \nnum_usecs\n;\n\nnum_usecs\n \n=\n \nos_cputime_ticks_to_usecs\n(\n1000000\n);",
- "title": "os_cputime_ticks_to_usecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_usecs/#os_cputime_ticks_to_usecs",
- "text": "uint32_t os_cputime_ticks_to_usecs ( uint32_t ticks ) Converts a specified number of cputime ticks to microseconds.",
- "title": "os_cputime_ticks_to_usecs"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_usecs/#arguments",
- "text": "Arguments Description ticks Number of cputime ticks to convert to microseconds.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_usecs/#returned-values",
- "text": "The number of microseconds in ticks number of ticks.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_usecs/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_ticks_to_usecs/#example",
- "text": "uint32_t num_usecs ; num_usecs = os_cputime_ticks_to_usecs ( 1000000 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_init/",
- "text": "os_cputime_timer_init\n\n\nvoid\n \nos_cputime_timer_init\n(\nstruct\n \nhal_timer\n \n*timer\n, \nhal_timer_cb\n \nfp\n, \nvoid\n \n*arg\n)\n\n\n\n\n\nInitializes a cputime timer, indicated by \ntimer\n, with a pointer to a callback function to call when the timer expires. When an optional opaque argument is specified, it is passed to the timer callback function. \n\n\nThe callback function has the following prototype:\n\n\nvoid\n \nhal_timer_cb\n(\nvoid\n \n*arg\n)\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntimer\n\n\nPointer to the hal_timer to initialize. This value cannot be NULL.\n\n\n\n\n\n\nfp\n\n\nPointer to the callback function to call when the timer expires. This value cannot be NULL.\n\n\n\n\n\n\narg\n\n\nOptional opaque argument to pass to the hal timer callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\nExample of ble_ll setting up a response timer:\n\n\nble_ll_wfr_timer_exp\n(\nvoid\n \n*arg\n)\n{\n \nint\n \nrx_start\n;\n \nuint8_t\n \nlls\n;\n\n ...\n\n \n/* If we have started a reception, there is nothing to do here */\n\n \nif\n (\n!rx_start\n) {\n \nswitch\n (\nlls\n) {\n \ncase\n \nBLE_LL_STATE_ADV\n:\n \nble_ll_adv_wfr_timer_exp\n();\n \nbreak\n;\n\n ...\n\n \n/* Do nothing here. Fall through intentional */\n\n \ncase\n \nBLE_LL_STATE_INITIATING\n:\n \ndefault\n:\n\n \nbreak\n;\n }\n }\n}\n\n\nvoid\n \nble_ll_init\n(\nvoid\n)\n{\n ...\n\n \nos_cputime_timer_init\n(\ng_ble_ll_data\n.\nll_wfr_timer\n, \nble_ll_wfr_timer_exp\n, \nNULL\n);\n\n ...\n}",
- "title": "os_cputime_timer_init"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_init/#os_cputime_timer_init",
- "text": "void os_cputime_timer_init ( struct hal_timer *timer , hal_timer_cb fp , void *arg ) Initializes a cputime timer, indicated by timer , with a pointer to a callback function to call when the timer expires. When an optional opaque argument is specified, it is passed to the timer callback function. The callback function has the following prototype: void hal_timer_cb ( void *arg )",
- "title": "os_cputime_timer_init"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_init/#arguments",
- "text": "Arguments Description timer Pointer to the hal_timer to initialize. This value cannot be NULL. fp Pointer to the callback function to call when the timer expires. This value cannot be NULL. arg Optional opaque argument to pass to the hal timer callback function.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_init/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_init/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_init/#example",
- "text": "Example of ble_ll setting up a response timer: ble_ll_wfr_timer_exp ( void *arg )\n{\n int rx_start ;\n uint8_t lls ;\n\n ...\n\n /* If we have started a reception, there is nothing to do here */ \n if ( !rx_start ) {\n switch ( lls ) {\n case BLE_LL_STATE_ADV :\n ble_ll_adv_wfr_timer_exp ();\n break ;\n\n ...\n\n /* Do nothing here. Fall through intentional */ \n case BLE_LL_STATE_INITIATING :\n default : \n break ;\n }\n }\n} void ble_ll_init ( void )\n{\n ...\n\n os_cputime_timer_init ( g_ble_ll_data . ll_wfr_timer , ble_ll_wfr_timer_exp , NULL );\n\n ...\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_relative/",
- "text": "os_cputime_timer_relative\n\n\nvoid\n \nos_cputime_timer_relative\n(\nstruct\n \nhal_timer\n \n*timer\n, \nuint32_t\n \nusecs\n)\n\n\n\n\n\nSets a timer to expire in the specified number of microseconds from the current time. The callback function for the timer is called when the timer expires. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntimer\n\n\nPointer to an initialized hal_timer.\n\n\n\n\n\n\nusecs\n\n\nThe number of microseconds to set the timer to expire from now.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\ntimer\n must be initialized using the \nos_cputime_timer_init()\n function before setting up a timer. \n\n\nExample\n\n\n`\n\n\nstruct\n \nhal_timer\n \nmytimer\n;\n ...\n\n\nos_cputime_timer_relative\n(\nmytimer\n, \n100\n);",
- "title": "os_cputime_timer_relative"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_relative/#os_cputime_timer_relative",
- "text": "void os_cputime_timer_relative ( struct hal_timer *timer , uint32_t usecs ) Sets a timer to expire in the specified number of microseconds from the current time. The callback function for the timer is called when the timer expires.",
- "title": "os_cputime_timer_relative"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_relative/#arguments",
- "text": "Arguments Description timer Pointer to an initialized hal_timer. usecs The number of microseconds to set the timer to expire from now.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_relative/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_relative/#notes",
- "text": "timer must be initialized using the os_cputime_timer_init() function before setting up a timer.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_relative/#example",
- "text": "` struct hal_timer mytimer ;\n ... os_cputime_timer_relative ( mytimer , 100 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_start/",
- "text": "os_cputime_timer_start\n\n\nvoid\n \nos_cputime_timer_start\n(\nstruct\n \nhal_timer\n \n*timer\n, \nuint32_t\n \ncputime\n)\n\n\n\n\n\nSets a timer to expire at the specified cputime. The callback function for the timer is called when the timer expires. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntimer\n\n\nPointer to an initialized hal_timer.\n\n\n\n\n\n\ncputime\n\n\nThe cputime when the timer expires.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\ntimer\n must be initialized using the \nos_cputime_timer_init()\n function before setting up a timer.\n\n\nExample\n\n\nvoid\n\n\nble_ll_wfr_enable\n(\nuint32_t\n \ncputime\n)\n{\n \nos_cputime_timer_start\n(\ng_ble_ll_data\n.\nll_wfr_timer\n, \ncputime\n);\n}",
- "title": "os_cputime_timer_start"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_start/#os_cputime_timer_start",
- "text": "void os_cputime_timer_start ( struct hal_timer *timer , uint32_t cputime ) Sets a timer to expire at the specified cputime. The callback function for the timer is called when the timer expires.",
- "title": "os_cputime_timer_start"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_start/#arguments",
- "text": "Arguments Description timer Pointer to an initialized hal_timer. cputime The cputime when the timer expires.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_start/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_start/#notes",
- "text": "timer must be initialized using the os_cputime_timer_init() function before setting up a timer.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_start/#example",
- "text": "void ble_ll_wfr_enable ( uint32_t cputime )\n{\n os_cputime_timer_start ( g_ble_ll_data . ll_wfr_timer , cputime );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_stop/",
- "text": "os_cputime_timer_stop\n\n\nvoid\n \nos_cputime_timer_stop\n(\nstruct\n \nhal_timer\n \n*timer\n)\n\n\n\n\n\nStops a timer from running. The timer is removed from the timer queue and interrupts are disabled if there are no more timers on the timer queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntimer\n\n\nPointer to the timer to stop.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\nvoid\n\n\nble_ll_wfr_disable\n(\nvoid\n)\n{\n \nos_cputime_timer_stop\n(\ng_ble_ll_data\n.\nll_wfr_timer\n);\n}",
- "title": "os_cputime_timer_stop"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_stop/#os_cputime_timer_stop",
- "text": "void os_cputime_timer_stop ( struct hal_timer *timer ) Stops a timer from running. The timer is removed from the timer queue and interrupts are disabled if there are no more timers on the timer queue.",
- "title": "os_cputime_timer_stop"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_stop/#arguments",
- "text": "Arguments Description timer Pointer to the timer to stop.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_stop/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_stop/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_timer_stop/#example",
- "text": "void ble_ll_wfr_disable ( void )\n{\n os_cputime_timer_stop ( g_ble_ll_data . ll_wfr_timer );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_usecs_to_ticks/",
- "text": "os_cputime_usecs_to_ticks\n\n\nuint32_t\n \nos_cputime_usecs_to_ticks\n(\nuint32_t\n \nusecs\n)\n\n\n\n\n\nConverts a specified number of microseconds to cputime ticks.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nusecs\n\n\nNumber of microseconds to convert to ticks.\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of ticks in \nusecs\n nanoseconds.\n\n\nNotes\n\n\nExample\n\n\nuint32_t\n \nnum_ticks\n;\n\nnum_ticks\n \n=\n \nos_cputime_usecs_to_ticks\n(\n100\n);",
- "title": "os_cputime_usecs_to_ticks"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_usecs_to_ticks/#os_cputime_usecs_to_ticks",
- "text": "uint32_t os_cputime_usecs_to_ticks ( uint32_t usecs ) Converts a specified number of microseconds to cputime ticks.",
- "title": "os_cputime_usecs_to_ticks"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_usecs_to_ticks/#arguments",
- "text": "Arguments Description usecs Number of microseconds to convert to ticks.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_usecs_to_ticks/#returned-values",
- "text": "The number of ticks in usecs nanoseconds.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_usecs_to_ticks/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/cputime/os_cputime_usecs_to_ticks/#example",
- "text": "uint32_t num_ticks ; num_ticks = os_cputime_usecs_to_ticks ( 100 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_time/",
- "text": "OS_Time\n\n\nThe system time for the Mynewt OS.\n\n\nDescription\n\n\nThe Mynewt OS contains an incrementing time that drives the OS scheduler and time delays. The time is a fixed size (e.g. 32 bits) and will eventually wrap back to zero. The time to wrap from zero back to zero is called the \nOS time epoch\n. \n\n\nThe frequency of the OS time tick is specified in the architecture-specific OS code \nos_arch.h\n and is named \nOS_TICKS_PER_SEC\n.\n\n\nThe Mynewt OS also provides APIs for setting and retrieving the wallclock time (also known as local time or time-of-day in other operating systems).\n\n\nData Structures\n\n\nTime is stored in Mynewt as an \nos_time_t\n value. \n\n\nWallclock time is represented using the \nstruct os_timeval\n and \nstruct os_timezone\n tuple.\n\n\nstruct os_timeval\n represents the number of seconds elapsed since the epoch (00:00:00 Jan 1, 1970 UTC).\n\n\nstruct\n \nos_timeval\n {\n \nint64_t\n \ntv_sec\n; \n/* seconds since Jan 1 1970 UTC */\n\n \nint32_t\n \ntv_usec\n; \n/* fractional seconds */\n\n};\n\n\nstruct\n \nos_timeval\n \ntv\n \n=\n { \n1457400000\n, \n0\n }; \n/* 01:20:00 Mar 8 2016 UTC */\n\n\n\n\n\n\nstruct os_timezone\n is used to specify the offset of local time from UTC and whether daylight savings is in effect. Note that \ntz_minuteswest\n is a positive number if the local time is \nbehind\n UTC and a negative number if the local time is \nahead\n of UTC.\n\n\nstruct\n \nos_timezone\n {\n \nint16_t\n \ntz_minuteswest\n;\n \nint16_t\n \ntz_dsttime\n;\n};\n\n\n/* Pacific Standard Time is 08:00 hours west of UTC */\n\n\nstruct\n \nos_timezone\n \nPST\n \n=\n { \n480\n, \n0\n };\n\nstruct\n \nos_timezone\n \nPDT\n \n=\n { \n480\n, \n1\n };\n\n\n/* Indian Standard Time is 05:30 hours east of UTC */\n\n\nstruct\n \nos_timezone\n \nIST\n \n=\n { \n-\n330\n, \n0\n };\n\n\n\n\n\nList of Functions\n\n\nThe functions available in time are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_time_advance\n\n\nIncrements the OS time tick for the system.\n\n\n\n\n\n\nos_time_delay\n\n\nPut the current task to sleep for the given number of ticks.\n\n\n\n\n\n\nos_time_get\n\n\nGet the current value of OS time.\n\n\n\n\n\n\nos_time_ms_to_ticks\n\n\nConverts milliseconds to os ticks.\n\n\n\n\n\n\nos_get_uptime_usec\n\n\nGets the time duration since boot.\n\n\n\n\n\n\nos_gettimeofday\n\n\nPopulate the given timeval and timezone structs with current time data.\n\n\n\n\n\n\nos_settimeofday\n\n\nSet the current time of day to the given time structs.\n\n\n\n\n\n\n\n\nList of Macros\n\n\nSeveral macros help with the evalution of times with respect to each other.\n\n\n\n\nOS_TIME_TICK_LT(t1,t2)\n -- evaluates to true if t1 is before t2 in time.\n\n\nOS_TIME_TICK_GT(t1,t2)\n -- evaluates to true if t1 is after t2 in time \n\n\nOS_TIME_TICK_GEQ(t1,t2)\n -- evaluates to true if t1 is on or after t2 in time.\n\n\n\n\nNOTE: For all of these macros the calculations are done modulo 'os_time_t'. \n\n\nEnsure that comparison of OS time always uses the macros above (to compensate for the possible wrap of OS time).\n\n\nThe following macros help adding or subtracting time when represented as \nstruct os_timeval\n. All parameters to the following macros are pointers to \nstruct os_timeval\n.\n\n\n\n\nos_timeradd(tvp, uvp, vvp)\n -- Add \nuvp\n to \ntvp\n and store result in \nvvp\n.\n\n\nos_timersub(tvp, uvp, vvp)\n -- Subtract \nuvp\n from \ntvp\n and store result in \nvvp\n.\n\n\n\n\nSpecial Notes\n\n\nIts important to understand how quickly the time wraps especially when doing time comparison using the macros above (or by any other means). \n\n\nFor example, if a tick is 1 millisecond and \nos_time_t\n is 32-bits the OS time will wrap back to zero in about 49.7 days or stated another way, the OS time epoch is 49.7 days.\n\n\nIf two times are more than 1/2 the OS time epoch apart, any time comparison will be incorrect. Ensure at design time that comparisons will not occur between times that are more than half the OS time epoch.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/time/os_time/#os_time",
- "text": "The system time for the Mynewt OS.",
- "title": "OS_Time"
- },
- {
- "location": "/os/core_os/time/os_time/#description",
- "text": "The Mynewt OS contains an incrementing time that drives the OS scheduler and time delays. The time is a fixed size (e.g. 32 bits) and will eventually wrap back to zero. The time to wrap from zero back to zero is called the OS time epoch . The frequency of the OS time tick is specified in the architecture-specific OS code os_arch.h and is named OS_TICKS_PER_SEC . The Mynewt OS also provides APIs for setting and retrieving the wallclock time (also known as local time or time-of-day in other operating systems).",
- "title": "Description"
- },
- {
- "location": "/os/core_os/time/os_time/#data-structures",
- "text": "Time is stored in Mynewt as an os_time_t value. Wallclock time is represented using the struct os_timeval and struct os_timezone tuple. struct os_timeval represents the number of seconds elapsed since the epoch (00:00:00 Jan 1, 1970 UTC). struct os_timeval {\n int64_t tv_sec ; /* seconds since Jan 1 1970 UTC */ \n int32_t tv_usec ; /* fractional seconds */ \n}; struct os_timeval tv = { 1457400000 , 0 }; /* 01:20:00 Mar 8 2016 UTC */ struct os_timezone is used to specify the offset of local time from UTC and whether daylight savings is in effect. Note that tz_minuteswest is a positive number if the local time is behind UTC and a negative number if the local time is ahead of UTC. struct os_timezone {\n int16_t tz_minuteswest ;\n int16_t tz_dsttime ;\n}; /* Pacific Standard Time is 08:00 hours west of UTC */ struct os_timezone PST = { 480 , 0 }; struct os_timezone PDT = { 480 , 1 }; /* Indian Standard Time is 05:30 hours east of UTC */ struct os_timezone IST = { - 330 , 0 };",
- "title": "Data Structures"
- },
- {
- "location": "/os/core_os/time/os_time/#list-of-functions",
- "text": "The functions available in time are: Function Description os_time_advance Increments the OS time tick for the system. os_time_delay Put the current task to sleep for the given number of ticks. os_time_get Get the current value of OS time. os_time_ms_to_ticks Converts milliseconds to os ticks. os_get_uptime_usec Gets the time duration since boot. os_gettimeofday Populate the given timeval and timezone structs with current time data. os_settimeofday Set the current time of day to the given time structs.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/time/os_time/#list-of-macros",
- "text": "Several macros help with the evalution of times with respect to each other. OS_TIME_TICK_LT(t1,t2) -- evaluates to true if t1 is before t2 in time. OS_TIME_TICK_GT(t1,t2) -- evaluates to true if t1 is after t2 in time OS_TIME_TICK_GEQ(t1,t2) -- evaluates to true if t1 is on or after t2 in time. NOTE: For all of these macros the calculations are done modulo 'os_time_t'. Ensure that comparison of OS time always uses the macros above (to compensate for the possible wrap of OS time). The following macros help adding or subtracting time when represented as struct os_timeval . All parameters to the following macros are pointers to struct os_timeval . os_timeradd(tvp, uvp, vvp) -- Add uvp to tvp and store result in vvp . os_timersub(tvp, uvp, vvp) -- Subtract uvp from tvp and store result in vvp .",
- "title": "List of Macros"
- },
- {
- "location": "/os/core_os/time/os_time/#special-notes",
- "text": "Its important to understand how quickly the time wraps especially when doing time comparison using the macros above (or by any other means). For example, if a tick is 1 millisecond and os_time_t is 32-bits the OS time will wrap back to zero in about 49.7 days or stated another way, the OS time epoch is 49.7 days. If two times are more than 1/2 the OS time epoch apart, any time comparison will be incorrect. Ensure at design time that comparisons will not occur between times that are more than half the OS time epoch.",
- "title": "Special Notes"
- },
- {
- "location": "/os/core_os/time/os_time_advance/",
- "text": "os_time_advance\n\n\nvoid\n \nos_time_advance\n(\nint\n \nticks\n)\n\n\n\n\n\nMoves the OS time forward by the value specified in \nticks\n. Typically, this is called in one place by the architecture specific OS code (kernel/os/src/arch) timer_handler which is in turn called by the BSP specific code assigned to drive the OS timer tick. See Porting Mynewt OS for details.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nticks\n\n\nNumber of ticks to move the OS time forward.\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample",
- "title": "os_time_advance"
- },
- {
- "location": "/os/core_os/time/os_time_advance/#os_time_advance",
- "text": "void os_time_advance ( int ticks ) Moves the OS time forward by the value specified in ticks . Typically, this is called in one place by the architecture specific OS code (kernel/os/src/arch) timer_handler which is in turn called by the BSP specific code assigned to drive the OS timer tick. See Porting Mynewt OS for details.",
- "title": "os_time_advance"
- },
- {
- "location": "/os/core_os/time/os_time_advance/#arguments",
- "text": "Arguments Description ticks Number of ticks to move the OS time forward.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_time_advance/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_time_advance/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_time_advance/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_time_delay/",
- "text": "os_time_delay\n\n\nvoid\n \nos_time_delay\n(\nint32_t\n \nticks\n) \n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nticks\n\n\nNumber of ticks to delay. Less than or equal to zero means no delay\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nPassing \nOS_TIMEOUT_NEVER\n to this function will not block indefinitely but will return immediately. Passing delays larger than 1/2 the OS time epoch should be avoided; behavior is unpredictable.\n\n\nExample\n\n\n\n\n \n/* delay 3 seconds */\n\n \nint32_t\n \ndelay\n \n=\n \nOS_TICKS_PER_SEC\n \n*\n \n3\n;\n \nos_time_delay\n(\ndelay\n);",
- "title": "os_time_delay"
- },
- {
- "location": "/os/core_os/time/os_time_delay/#os_time_delay",
- "text": "void os_time_delay ( int32_t ticks )",
- "title": "os_time_delay"
- },
- {
- "location": "/os/core_os/time/os_time_delay/#arguments",
- "text": "Arguments Description ticks Number of ticks to delay. Less than or equal to zero means no delay",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_time_delay/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_time_delay/#notes",
- "text": "Passing OS_TIMEOUT_NEVER to this function will not block indefinitely but will return immediately. Passing delays larger than 1/2 the OS time epoch should be avoided; behavior is unpredictable.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_time_delay/#example",
- "text": "/* delay 3 seconds */ \n int32_t delay = OS_TICKS_PER_SEC * 3 ;\n os_time_delay ( delay );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_time_get/",
- "text": "os_time_get\n\n\nos_time_t\n \nos_time_get\n(\nvoid\n) \n\n\n\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nThe current value of the OS time\n\n\nNotes\n\n\nSee the \nSpecial Notes\n on OS time epoch and comparison\n\n\nExample\n\n\n\n\n \nos_time_t\n \nnow\n \n=\n \nos_time_get\n();",
- "title": "os_time_get"
- },
- {
- "location": "/os/core_os/time/os_time_get/#os_time_get",
- "text": "os_time_t os_time_get ( void )",
- "title": "os_time_get"
- },
- {
- "location": "/os/core_os/time/os_time_get/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_time_get/#returned-values",
- "text": "The current value of the OS time",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_time_get/#notes",
- "text": "See the Special Notes on OS time epoch and comparison",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_time_get/#example",
- "text": "os_time_t now = os_time_get ();",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_time_ms_to_ticks/",
- "text": "os_time_ms_to_ticks\n\n\nint\n \nos_time_ms_to_ticks\n(\nuint32_t\n \nms\n, \nuint32_t\n \n*out_ticks\n)\n\n\n\n\n\nConverts milliseconds to OS ticks.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nms\n\n\nNumber of milliseconds to convert to OS ticks.\n\n\n\n\n\n\nout_ticks\n\n\nPointer to an uint32_t to return the number of OS ticks for \nms\n milliseconds.\n\n\n\n\n\n\n\n\nN/A\n\n\nReturned values\n\n\n0\n: Success\n\nOS_EINVAL\n: Number of ticks is too large to fit in an uint32_t.\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\nunint32_t\n \nnum_ticks\n;\n\nos_time_ms_to_ticks\n(\n50\n, \nnum_ticks\n);",
- "title": "os_time_ms_to_ticks"
- },
- {
- "location": "/os/core_os/time/os_time_ms_to_ticks/#os_time_ms_to_ticks",
- "text": "int os_time_ms_to_ticks ( uint32_t ms , uint32_t *out_ticks ) Converts milliseconds to OS ticks.",
- "title": "os_time_ms_to_ticks"
- },
- {
- "location": "/os/core_os/time/os_time_ms_to_ticks/#arguments",
- "text": "Arguments Description ms Number of milliseconds to convert to OS ticks. out_ticks Pointer to an uint32_t to return the number of OS ticks for ms milliseconds. N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_time_ms_to_ticks/#returned-values",
- "text": "0 : Success OS_EINVAL : Number of ticks is too large to fit in an uint32_t. N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_time_ms_to_ticks/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_time_ms_to_ticks/#example",
- "text": "unint32_t num_ticks ; os_time_ms_to_ticks ( 50 , num_ticks );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_get_uptime_usec/",
- "text": "os_get_uptime_usec\n\n\nint64_t\n \nos_get_uptime_usec\n(\nvoid\n)\n\n\n\n\n\nGets the time duration, in microseconds, since boot.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nTime since boot in microseconds. \n\n\nNotes\n\n\nExample\n\n\n\n\n \nint64_t\n \ntime_since_boot\n;\n \ntime_since_boot\n \n=\n \nos_get_uptime_usec\n();",
- "title": "os_get_uptime_usec"
- },
- {
- "location": "/os/core_os/time/os_get_uptime_usec/#os_get_uptime_usec",
- "text": "int64_t os_get_uptime_usec ( void ) Gets the time duration, in microseconds, since boot.",
- "title": "os_get_uptime_usec"
- },
- {
- "location": "/os/core_os/time/os_get_uptime_usec/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_get_uptime_usec/#returned-values",
- "text": "Time since boot in microseconds.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_get_uptime_usec/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_get_uptime_usec/#example",
- "text": "int64_t time_since_boot ;\n time_since_boot = os_get_uptime_usec ();",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_gettimeofday/",
- "text": "os_gettimeofday\n\n\nint\n \nos_gettimeofday\n(\nstruct\n \nos_timeval\n \n*utctime\n, \nstruct\n \nos_timezone\n \n*timezone\n); \n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nutctime\n\n\nUTC time corresponding to wallclock time\n\n\n\n\n\n\ntimezone\n\n\nTimezone to convert UTC time to wallclock time\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success and non-zero on failure.\n\n\nNotes\n\n\nutctime\n or \ntimezone\n may be NULL.\n\n\nThe function is a no-op if both \nutctime\n and \ntimezone\n are NULL.\n\n\nExample\n\n\n\n\n \n/*\n\n\n * Display wallclock time on the console.\n\n\n */\n\n \nint\n \nrc\n;\n \nstruct\n \nos_timeval\n \nutc\n;\n \nstruct\n \nos_timezone\n \ntz\n;\n \nchar\n \nbuf\n[\nDATETIME_BUFSIZE\n];\n\n \nrc\n \n=\n \nos_gettimeofday\n(\nutc\n, \ntz\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \nformat_datetime\n(\nutc\n, \ntz\n, \nbuf\n, \nsizeof\n(\nbuf\n));\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n }",
- "title": "os_gettimeofday"
- },
- {
- "location": "/os/core_os/time/os_gettimeofday/#os_gettimeofday",
- "text": "int os_gettimeofday ( struct os_timeval *utctime , struct os_timezone *timezone );",
- "title": "os_gettimeofday"
- },
- {
- "location": "/os/core_os/time/os_gettimeofday/#arguments",
- "text": "Arguments Description utctime UTC time corresponding to wallclock time timezone Timezone to convert UTC time to wallclock time",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_gettimeofday/#returned-values",
- "text": "Returns 0 on success and non-zero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_gettimeofday/#notes",
- "text": "utctime or timezone may be NULL. The function is a no-op if both utctime and timezone are NULL.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_gettimeofday/#example",
- "text": "/* * Display wallclock time on the console. */ \n int rc ;\n struct os_timeval utc ;\n struct os_timezone tz ;\n char buf [ DATETIME_BUFSIZE ];\n\n rc = os_gettimeofday ( utc , tz );\n if ( rc == 0 ) {\n format_datetime ( utc , tz , buf , sizeof ( buf ));\n console_printf ( %s\\n , buf );\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/time/os_settimeofday/",
- "text": "os_settimeofday\n\n\nint\n \nos_settimeofday\n(\nstruct\n \nos_timeval\n \n*utctime\n, \nstruct\n \nos_timezone\n \n*timezone\n);\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nutctime\n\n\nUTC time corresponding to the wallclock time\n\n\n\n\n\n\ntimezone\n\n\nTimezone associated with the wallclock time\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success and non-zero on failure.\n\n\nNotes\n\n\nutctime\n may be NULL if only the timezone needs to be changed. This is useful when adjusting the \ntimezone\n to account for daylight savings.\n\n\ntimezone\n may be NULL if only the UTC time needs to be changed. This is useful when synchronizing Mynewt's time with an external time source like NTP.\n\n\nThe function is a no-op if both \nutctime\n and \ntimezone\n are NULL.\n\n\nExample\n\n\n\n\n \nint\n \nrc\n;\n \nparse_datetime\n(\ndatestr\n, \nutctime\n, \ntz\n);\n \nrc\n \n=\n \nos_settimeofday\n(\nutctime\n, \ntz\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* success */\n\n }",
- "title": "os_settimeofday"
- },
- {
- "location": "/os/core_os/time/os_settimeofday/#os_settimeofday",
- "text": "int os_settimeofday ( struct os_timeval *utctime , struct os_timezone *timezone );",
- "title": "os_settimeofday"
- },
- {
- "location": "/os/core_os/time/os_settimeofday/#arguments",
- "text": "Arguments Description utctime UTC time corresponding to the wallclock time timezone Timezone associated with the wallclock time",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/time/os_settimeofday/#returned-values",
- "text": "Returns 0 on success and non-zero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/time/os_settimeofday/#notes",
- "text": "utctime may be NULL if only the timezone needs to be changed. This is useful when adjusting the timezone to account for daylight savings. timezone may be NULL if only the UTC time needs to be changed. This is useful when synchronizing Mynewt's time with an external time source like NTP. The function is a no-op if both utctime and timezone are NULL.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/time/os_settimeofday/#example",
- "text": "int rc ;\n parse_datetime ( datestr , utctime , tz );\n rc = os_settimeofday ( utctime , tz );\n if ( rc == 0 ) {\n /* success */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/task/task/",
- "text": "Task\n\n\nA task, along with the scheduler, forms the basis of the Mynewt OS. A task \nconsists of two basic elements: a task stack and a task function. The task \nfunction is basically a forever loop, waiting for some \"event\" to wake it up. \nThere are two methods used to signal a task that it has work to do: \nevent queues\n \nand \nsemaphores\n .\n\n\nThe Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task \npriority (from 0 to 255), with 0 being the highest priority task. If a higher \npriority task than the current task wants to run, the scheduler preempts the \ncurrently running task and switches context to the higher priority task. This is \njust a fancy way of saying that the processor stack pointer now points to the \nstack of the higher priority task and the task resumes execution where it left \noff.\n\n\nTasks run to completion unless they are preempted by a higher priority task. The \ndeveloper must ensure that tasks eventually \"sleep\"; otherwise lower priority \ntasks will never get a chance to run (actually, any task lower in priority than \nthe task that never sleeps). A task will be put to sleep in the following cases: \nit puts itself to sleep using \nos_time_delay()\n, it waits on an \nevent queue\n\nwhich is empty or attempts to obtain a mutex or a \nsemaphore\n that is currently \nowned by another task.\n\n\nNote that other sections of the manual describe these OS features in more \ndetail.\n\n\nDescription\n\n\nIn order to create a task two data structures need to be defined: the task \nobject (\nstruct os_task\n) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declaring your stack! The stack is in units \nof \nos_stack_t\n sized elements (generally 32-bits). Looking at the example given \nbelow and assuming \nos_stack_t\n is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. \n\n\nA task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn!\n\n\nIn order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the \nos_task_init()\n function is called. Once \nos_task_init()\n is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before \nos_start()\n is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init()' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is started. Once the os has started, the highest priority task will be \nthe first task set to run.\n\n\nInformation about a task can be obtained using the \nos_task_info_get_next()\n \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type \nos_task_info\n and is described below.\n\n\nThe following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval.\n\n\n/* Create a simple \nproject\n with a task that blinks a LED every second */\n\n\n\n/* Define task stack and task object */\n\n\n#define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) \n\n\n#define MY_STACK_SIZE (64) \n\n\nstruct\n \nos_task\n \nmy_task\n; \n\nos_stack_t\n \nmy_task_stack\n[\nMY_STACK_SIZE\n]; \n\n\n/* This is the task function */\n\n\nvoid\n \nmy_task_func\n(\nvoid\n \n*arg\n) {\n \n/* Set the led pin as an output */\n\n \nhal_gpio_init_out\n(\nLED_BLINK_PIN\n, \n1\n);\n\n \n/* The task is a forever loop that does not return */\n\n \nwhile\n (\n1\n) {\n \n/* Wait one second */\n \n \nos_time_delay\n(\n1000\n);\n\n \n/* Toggle the LED */\n \n \nhal_gpio_toggle\n(\nLED_BLINK_PIN\n);\n }\n}\n\n\n/* This is the main function for the project */\n\n\nint\n \nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n) \n{\n\n \n/* Perform system and package initialization */\n\n \nsysinit\n();\n\n \n/* Initialize the task */\n\n \nos_task_init\n(\nmy_task\n, \nmy_task\n, \nmy_task_func\n, \nNULL\n, \nMY_TASK_PRIO\n, \n \nOS_WAIT_FOREVER\n, \nmy_task_stack\n, \nMY_STACK_SIZE\n);\n\n \n/* Process events from the default event queue. */\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n \n/* main never returns */\n \n}\n\n\n\n\n\nData structures\n\n\n/* The highest and lowest task priorities */\n\n\n#define OS_TASK_PRI_HIGHEST (0)\n\n\n#define OS_TASK_PRI_LOWEST (0xff)\n\n\n\n/* Task states */\n\n\ntypedef\n \nenum\n \nos_task_state\n {\n \nOS_TASK_READY\n \n=\n \n1\n, \n \nOS_TASK_SLEEP\n \n=\n \n2\n\n} \nos_task_state_t\n;\n\n\n/* Task flags */\n\n\n#define OS_TASK_FLAG_NO_TIMEOUT (0x0001U)\n\n\n#define OS_TASK_FLAG_SEM_WAIT (0x0002U)\n\n\n#define OS_TASK_FLAG_MUTEX_WAIT (0x0004U)\n\n\n\ntypedef\n \nvoid\n (\n*os_task_func_t\n)(\nvoid\n \n*\n);\n\n\n#define OS_TASK_MAX_NAME_LEN (32)\n\n\n\n\n\n\n\n\nstruct\n \nos_task\n {\n \nos_stack_t\n \n*t_stackptr\n;\n \nos_stack_t\n \n*t_stacktop\n;\n\n \nuint16_t\n \nt_stacksize\n;\n \nuint16_t\n \nt_flags\n;\n\n \nuint8_t\n \nt_taskid\n;\n \nuint8_t\n \nt_prio\n;\n \nuint8_t\n \nt_state\n;\n \nuint8_t\n \nt_pad\n;\n\n \nchar\n \n*t_name\n;\n \nos_task_func_t\n \nt_func\n;\n \nvoid\n \n*t_arg\n;\n\n \nvoid\n \n*t_obj\n;\n\n \nstruct\n \nos_sanity_check\n \nt_sanity_check\n; \n\n \nos_time_t\n \nt_next_wakeup\n;\n \nos_time_t\n \nt_run_time\n;\n \nuint32_t\n \nt_ctx_sw_cnt\n;\n\n \n/* Global list of all tasks, irrespective of run or sleep lists */\n\n \nSTAILQ_ENTRY\n(\nos_task\n) \nt_os_task_list\n;\n\n \n/* Used to chain task to either the run or sleep list */\n \n \nTAILQ_ENTRY\n(\nos_task\n) \nt_os_list\n;\n\n \n/* Used to chain task to an object such as a semaphore or mutex */\n\n \nSLIST_ENTRY\n(\nos_task\n) \nt_obj_list\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt_stackptr\n\n\nCurrent stack pointer\n\n\n\n\n\n\nt_stacktop\n\n\nThe address of the top of the task stack. The stack grows downward\n\n\n\n\n\n\nt_stacksize\n\n\nThe size of the stack, in units of os_stack_t (not bytes!)\n\n\n\n\n\n\nt_flags\n\n\nTask flags (see flag definitions)\n\n\n\n\n\n\nt_taskid\n\n\nA numeric id assigned to each task\n\n\n\n\n\n\nt_prio\n\n\nThe priority of the task. The lower the number, the higher the priority\n\n\n\n\n\n\nt_state\n\n\nThe task state (see state definitions)\n\n\n\n\n\n\nt_pad\n\n\npadding (for alignment)\n\n\n\n\n\n\nt_name\n\n\nName of task\n\n\n\n\n\n\nt_func\n\n\nPointer to task function\n\n\n\n\n\n\nt_obj\n\n\nGeneric object used by mutexes and semaphores when the task is waiting on a mutex or semaphore\n\n\n\n\n\n\nt_sanity_check\n\n\nSanity task data structure\n\n\n\n\n\n\nt_next_wakeup\n\n\nOS time when task is next scheduled to wake up\n\n\n\n\n\n\nt_run_time\n\n\nThe amount of os time ticks this task has been running\n\n\n\n\n\n\nt_ctx_sw_cnt\n\n\nThe number of times that this task has been run\n\n\n\n\n\n\nt_os_task_list\n\n\nList pointer for global task list. All tasks are placed on this list\n\n\n\n\n\n\nt_os_list\n\n\nList pointer used by either the active task list or the sleeping task list\n\n\n\n\n\n\nt_obj_list\n\n\nList pointer for tasks waiting on a semaphore or mutex\n\n\n\n\n\n\n\n\n\n\nstruct\n \nos_task_info\n {\n \nuint8_t\n \noti_prio\n;\n \nuint8_t\n \noti_taskid\n;\n \nuint8_t\n \noti_state\n;\n \nuint8_t\n \noti_flags\n;\n \nuint16_t\n \noti_stkusage\n;\n \nuint16_t\n \noti_stksize\n;\n \nuint32_t\n \noti_cswcnt\n;\n \nuint32_t\n \noti_runtime\n;\n \nos_time_t\n \noti_last_checkin\n;\n \nos_time_t\n \noti_next_checkin\n;\n\n \nchar\n \noti_name\n[\nOS_TASK_MAX_NAME_LEN\n];\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\noti_prio\n\n\nTask priority\n\n\n\n\n\n\noti_taskid\n\n\nTask id\n\n\n\n\n\n\noti_state\n\n\nTask state\n\n\n\n\n\n\noti_flags\n\n\nTask flags\n\n\n\n\n\n\noti_stkusage\n\n\nAmount of stack used by the task (in os_stack_t units)\n\n\n\n\n\n\noti_stksize\n\n\nThe size of the stack (in os_stack_t units)\n\n\n\n\n\n\noti_cswcnt\n\n\nThe context switch count\n\n\n\n\n\n\noti_runtime\n\n\nThe amount of time that the task has run (in os time ticks)\n\n\n\n\n\n\noti_last_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_next_checkin\n\n\nThe time (os time) at which this task last checked in to the sanity task\n\n\n\n\n\n\noti_name\n\n\nName of the task\n\n\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in task are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_task_init\n\n\nCalled to create a task. This adds the task object to the list of ready to run tasks.\n\n\n\n\n\n\nos_task_count\n\n\nReturns the number of tasks that have been created.\n\n\n\n\n\n\nos_task_info_get_next\n\n\nPopulates the os task info structure given with task information.\n\n\n\n\n\n\nos_task_remove\n\n\nRemoves a task from the task list.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/task/task/#task",
- "text": "A task, along with the scheduler, forms the basis of the Mynewt OS. A task \nconsists of two basic elements: a task stack and a task function. The task \nfunction is basically a forever loop, waiting for some \"event\" to wake it up. \nThere are two methods used to signal a task that it has work to do: event queues \nand semaphores . The Mynewt OS is a multi-tasking, preemptive OS. Every task is assigned a task \npriority (from 0 to 255), with 0 being the highest priority task. If a higher \npriority task than the current task wants to run, the scheduler preempts the \ncurrently running task and switches context to the higher priority task. This is \njust a fancy way of saying that the processor stack pointer now points to the \nstack of the higher priority task and the task resumes execution where it left \noff. Tasks run to completion unless they are preempted by a higher priority task. The \ndeveloper must ensure that tasks eventually \"sleep\"; otherwise lower priority \ntasks will never get a chance to run (actually, any task lower in priority than \nthe task that never sleeps). A task will be put to sleep in the following cases: \nit puts itself to sleep using os_time_delay() , it waits on an event queue \nwhich is empty or attempts to obtain a mutex or a semaphore that is currently \nowned by another task. Note that other sections of the manual describe these OS features in more \ndetail.",
- "title": "Task"
- },
- {
- "location": "/os/core_os/task/task/#description",
- "text": "In order to create a task two data structures need to be defined: the task \nobject ( struct os_task ) and its associated stack. Determining the stack size can \nbe a bit tricky; generally developers should not declare large local variables \non the stack so that task stacks can be of limited size. However, all \napplications are different and the developer must choose the stack size \naccordingly. NOTE: be careful when declaring your stack! The stack is in units \nof os_stack_t sized elements (generally 32-bits). Looking at the example given \nbelow and assuming os_stack_t is defined to be a 32-bit unsigned value, \n\"my_task_stack\" will use 256 bytes. A task must also have an associated \"task function\". This is the function that \nwill be called when the task is first run. This task function should never \nreturn! In order to inform the Mynewt OS of the new task and to have it added to the \nscheduler, the os_task_init() function is called. Once os_task_init() is \ncalled, the task is made ready to run and is added to the active task list. Note \nthat a task can be initialized (started) before or after the os has started \n(i.e. before os_start() is called) but must be initialized after the os has \nbeen initialized (i.e. 'os_init()' has been called). In most of the examples and \ncurrent Mynewt projects, the os is initialized, tasks are initialized, and the \nthe os is started. Once the os has started, the highest priority task will be \nthe first task set to run. Information about a task can be obtained using the os_task_info_get_next() \nAPI. Developers can walk the list of tasks to obtain information on all created \ntasks. This information is of type os_task_info and is described below. The following is a very simple example showing a single application task. This \ntask simply toggles an LED at a one second interval. /* Create a simple project with a task that blinks a LED every second */ /* Define task stack and task object */ #define MY_TASK_PRI (OS_TASK_PRI_HIGHEST) #define MY_STACK_SIZE (64) struct os_task my_task ; os_stack_t my_task_stack [ MY_STACK_SIZE ]; /* This is the task function */ void my_task_func ( void *arg ) {\n /* Set the led pin as an output */ \n hal_gpio_init_out ( LED_BLINK_PIN , 1 );\n\n /* The task is a forever loop that does not return */ \n while ( 1 ) {\n /* Wait one second */ \n os_time_delay ( 1000 );\n\n /* Toggle the LED */ \n hal_gpio_toggle ( LED_BLINK_PIN );\n }\n} /* This is the main function for the project */ int main ( int argc , char **argv ) \n{\n\n /* Perform system and package initialization */ \n sysinit ();\n\n /* Initialize the task */ \n os_task_init ( my_task , my_task , my_task_func , NULL , MY_TASK_PRIO , \n OS_WAIT_FOREVER , my_task_stack , MY_STACK_SIZE );\n\n /* Process events from the default event queue. */ \n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n /* main never returns */ \n}",
- "title": "Description"
- },
- {
- "location": "/os/core_os/task/task/#data-structures",
- "text": "/* The highest and lowest task priorities */ #define OS_TASK_PRI_HIGHEST (0) #define OS_TASK_PRI_LOWEST (0xff) /* Task states */ typedef enum os_task_state {\n OS_TASK_READY = 1 , \n OS_TASK_SLEEP = 2 \n} os_task_state_t ; /* Task flags */ #define OS_TASK_FLAG_NO_TIMEOUT (0x0001U) #define OS_TASK_FLAG_SEM_WAIT (0x0002U) #define OS_TASK_FLAG_MUTEX_WAIT (0x0004U) typedef void ( *os_task_func_t )( void * ); #define OS_TASK_MAX_NAME_LEN (32) struct os_task {\n os_stack_t *t_stackptr ;\n os_stack_t *t_stacktop ;\n\n uint16_t t_stacksize ;\n uint16_t t_flags ;\n\n uint8_t t_taskid ;\n uint8_t t_prio ;\n uint8_t t_state ;\n uint8_t t_pad ;\n\n char *t_name ;\n os_task_func_t t_func ;\n void *t_arg ;\n\n void *t_obj ;\n\n struct os_sanity_check t_sanity_check ; \n\n os_time_t t_next_wakeup ;\n os_time_t t_run_time ;\n uint32_t t_ctx_sw_cnt ;\n\n /* Global list of all tasks, irrespective of run or sleep lists */ \n STAILQ_ENTRY ( os_task ) t_os_task_list ;\n\n /* Used to chain task to either the run or sleep list */ \n TAILQ_ENTRY ( os_task ) t_os_list ;\n\n /* Used to chain task to an object such as a semaphore or mutex */ \n SLIST_ENTRY ( os_task ) t_obj_list ;\n}; Element Description t_stackptr Current stack pointer t_stacktop The address of the top of the task stack. The stack grows downward t_stacksize The size of the stack, in units of os_stack_t (not bytes!) t_flags Task flags (see flag definitions) t_taskid A numeric id assigned to each task t_prio The priority of the task. The lower the number, the higher the priority t_state The task state (see state definitions) t_pad padding (for alignment) t_name Name of task t_func Pointer to task function t_obj Generic object used by mutexes and semaphores when the task is waiting on a mutex or semaphore t_sanity_check Sanity task data structure t_next_wakeup OS time when task is next scheduled to wake up t_run_time The amount of os time ticks this task has been running t_ctx_sw_cnt The number of times that this task has been run t_os_task_list List pointer for global task list. All tasks are placed on this list t_os_list List pointer used by either the active task list or the sleeping task list t_obj_list List pointer for tasks waiting on a semaphore or mutex struct os_task_info {\n uint8_t oti_prio ;\n uint8_t oti_taskid ;\n uint8_t oti_state ;\n uint8_t oti_flags ;\n uint16_t oti_stkusage ;\n uint16_t oti_stksize ;\n uint32_t oti_cswcnt ;\n uint32_t oti_runtime ;\n os_time_t oti_last_checkin ;\n os_time_t oti_next_checkin ;\n\n char oti_name [ OS_TASK_MAX_NAME_LEN ];\n}; Element Description oti_prio Task priority oti_taskid Task id oti_state Task state oti_flags Task flags oti_stkusage Amount of stack used by the task (in os_stack_t units) oti_stksize The size of the stack (in os_stack_t units) oti_cswcnt The context switch count oti_runtime The amount of time that the task has run (in os time ticks) oti_last_checkin The time (os time) at which this task last checked in to the sanity task oti_next_checkin The time (os time) at which this task last checked in to the sanity task oti_name Name of the task",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/task/task/#list-of-functions",
- "text": "The functions available in task are: Function Description os_task_init Called to create a task. This adds the task object to the list of ready to run tasks. os_task_count Returns the number of tasks that have been created. os_task_info_get_next Populates the os task info structure given with task information. os_task_remove Removes a task from the task list.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/task/os_task_count/",
- "text": "os_task_count\n\n\nuint8_t\n \nos_task_count\n(\nvoid\n);\n\n\n\n\n\nReturns the number of tasks that have been created. \n\n\n\n\nArguments\n\n\nNone\n\n\n\n\nReturned values\n\n\nunsigned 8-bit integer representing number of tasks created\n\n\n\n\nExample\n\n\n \nuint8_t\n \nnum_tasks\n;\n\n \nnum_tasks\n \n=\n \nos_task_count\n();",
- "title": "os_task_count"
- },
- {
- "location": "/os/core_os/task/os_task_count/#os_task_count",
- "text": "uint8_t os_task_count ( void ); Returns the number of tasks that have been created.",
- "title": " os_task_count"
- },
- {
- "location": "/os/core_os/task/os_task_count/#arguments",
- "text": "None",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/task/os_task_count/#returned-values",
- "text": "unsigned 8-bit integer representing number of tasks created",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/task/os_task_count/#example",
- "text": "uint8_t num_tasks ;\n\n num_tasks = os_task_count ();",
- "title": "Example"
- },
- {
- "location": "/os/core_os/task/os_task_info_get_next/",
- "text": "os_task_info_get_next\n\n\nstruct\n \nos_task\n \n*os_task_info_get_next\n(\nconst\n \nstruct\n \nos_task\n \n*prev\n, \nstruct\n \nos_task_info\n \n*oti\n);\n\n\n\n\n\nPopulates the os task info structure pointed to by \noti\n with task information. \nThe task populating the \noti\n structure is either the first task on the task \nlist if \nprev\n is \nNULL\n, or the next task in the task list (the next pointer of \n\nprev\n).\n\n\nIf there are no tasks initialized, \nNULL\n is returned. Otherwise, the task \nstructure used to populate \noti\n is returned.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nprev\n\n\nPointer to previous task in task list. If NULL, use first task on list\n\n\n\n\n\n\noti\n\n\nPointer to \nos_task_info\n structure where task information will be stored\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns a pointer to the os task structure that was used to populate the task \ninformation structure. \nNULL\n means that no tasks were created.\n\n\n\n\nExample\n\n\nvoid\n \n\nget_task_info\n(\nvoid\n)\n{\n \nstruct\n \nos_task\n \n*prev_task\n; \n \nstruct\n \nos_task_info\n \noti\n; \n\n \nconsole_printf\n(\nTasks: \\n\n);\n \nprev_task\n \n=\n \nNULL\n;\n \nwhile\n (\n1\n) {\n \nprev_task\n \n=\n \nos_task_info_get_next\n(\nprev_task\n, \noti\n);\n \nif\n (\nprev_task\n \n==\n \nNULL\n) {\n \nbreak\n;\n }\n\n \nconsole_printf\n(\n %s (prio: %u, tid: %u, lcheck: %lu, ncheck: %lu, \n\n \nflags: 0x%x, ssize: %u, susage: %u, cswcnt: %lu, \n\n \ntot_run_time: %lums)\\n\n,\n \noti\n.\noti_name\n, \noti\n.\noti_prio\n, \noti\n.\noti_taskid\n, \n (\nunsigned\n \nlong\n)\noti\n.\noti_last_checkin\n,\n (\nunsigned\n \nlong\n)\noti\n.\noti_next_checkin\n, \noti\n.\noti_flags\n,\n \noti\n.\noti_stksize\n, \noti\n.\noti_stkusage\n, (\nunsigned\n \nlong\n)\noti\n.\noti_cswcnt\n,\n (\nunsigned\n \nlong\n)\noti\n.\noti_runtime\n);\n\n }\n}",
- "title": "os_task_info_get_next"
- },
- {
- "location": "/os/core_os/task/os_task_info_get_next/#os_task_info_get_next",
- "text": "struct os_task *os_task_info_get_next ( const struct os_task *prev , struct os_task_info *oti ); Populates the os task info structure pointed to by oti with task information. \nThe task populating the oti structure is either the first task on the task \nlist if prev is NULL , or the next task in the task list (the next pointer of prev ). If there are no tasks initialized, NULL is returned. Otherwise, the task \nstructure used to populate oti is returned.",
- "title": " os_task_info_get_next"
- },
- {
- "location": "/os/core_os/task/os_task_info_get_next/#arguments",
- "text": "Arguments Description prev Pointer to previous task in task list. If NULL, use first task on list oti Pointer to os_task_info structure where task information will be stored",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/task/os_task_info_get_next/#returned-values",
- "text": "Returns a pointer to the os task structure that was used to populate the task \ninformation structure. NULL means that no tasks were created.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/task/os_task_info_get_next/#example",
- "text": "void get_task_info ( void )\n{\n struct os_task *prev_task ; \n struct os_task_info oti ; \n\n console_printf ( Tasks: \\n );\n prev_task = NULL ;\n while ( 1 ) {\n prev_task = os_task_info_get_next ( prev_task , oti );\n if ( prev_task == NULL ) {\n break ;\n }\n\n console_printf ( %s (prio: %u, tid: %u, lcheck: %lu, ncheck: %lu, \n flags: 0x%x, ssize: %u, susage: %u, cswcnt: %lu, \n tot_run_time: %lums)\\n ,\n oti . oti_name , oti . oti_prio , oti . oti_taskid , \n ( unsigned long ) oti . oti_last_checkin ,\n ( unsigned long ) oti . oti_next_checkin , oti . oti_flags ,\n oti . oti_stksize , oti . oti_stkusage , ( unsigned long ) oti . oti_cswcnt ,\n ( unsigned long ) oti . oti_runtime );\n\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/task/os_task_init/",
- "text": "os_task_init\n\n\nint\n \nos_task_init\n(\nstruct\n \nos_task\n \n*t\n, \nchar\n \n*name\n, \nos_task_func_t\n \nfunc\n, \nvoid\n \n*arg\n, \n \nuint8_t\n \nprio\n, \nos_time_t\n \nsanity_itvl\n, \nos_stack_t\n \n*stack_bottom\n, \n \nuint16_t\n \nstack_size\n)\n\n\n\n\n\nCalled to create a task. This adds the task object to the list of \nready to run\n\ntasks.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\nname\n\n\nTask name\n\n\n\n\n\n\nfunc\n\n\nTask function\n\n\n\n\n\n\narg\n\n\nGeneric argument to pass to task\n\n\n\n\n\n\nprio\n\n\nPriority of task\n\n\n\n\n\n\nsanity_itvl\n\n\nThe interval at which the sanity task will check to see if this task is sill alive\n\n\n\n\n\n\nstack_bottom\n\n\nPointer to bottom of stack.\n\n\n\n\n\n\nstack_size\n\n\nThe size of the stack. NOTE: this is not in bytes! It is the number of \nos_stack_t\n elements allocated (generally 32-bits each)\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: task initialization successful.\n\n\nAll other error codes indicate an internal error.\n\n\n\n\nExample\n\n\n \n/* Create the task */\n \n \nint\n \nrc\n;\n\n \nos_stack_t\n \nmy_task_stack\n[\nMY_STACK_SIZE\n];\n\n \nrc\n \n=\n \nos_task_init\n(\nmy_task\n, \nmy_task\n, \nmy_task_func\n, \nNULL\n, \nMY_TASK_PRIO\n, \n \nOS_WAIT_FOREVER\n, \nmy_task_stack\n, \nMY_STACK_SIZE\n);\n \nassert\n(\nrc\n \n==\n \nOS_OK\n);",
- "title": "os_task_init"
- },
- {
- "location": "/os/core_os/task/os_task_init/#os_task_init",
- "text": "int os_task_init ( struct os_task *t , char *name , os_task_func_t func , void *arg , \n uint8_t prio , os_time_t sanity_itvl , os_stack_t *stack_bottom , \n uint16_t stack_size ) Called to create a task. This adds the task object to the list of ready to run \ntasks.",
- "title": " os_task_init"
- },
- {
- "location": "/os/core_os/task/os_task_init/#arguments",
- "text": "Arguments Description t Pointer to task name Task name func Task function arg Generic argument to pass to task prio Priority of task sanity_itvl The interval at which the sanity task will check to see if this task is sill alive stack_bottom Pointer to bottom of stack. stack_size The size of the stack. NOTE: this is not in bytes! It is the number of os_stack_t elements allocated (generally 32-bits each)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/task/os_task_init/#returned-values",
- "text": "OS_OK : task initialization successful. All other error codes indicate an internal error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/task/os_task_init/#example",
- "text": "/* Create the task */ \n int rc ;\n\n os_stack_t my_task_stack [ MY_STACK_SIZE ];\n\n rc = os_task_init ( my_task , my_task , my_task_func , NULL , MY_TASK_PRIO , \n OS_WAIT_FOREVER , my_task_stack , MY_STACK_SIZE );\n assert ( rc == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/task/os_task_remove/",
- "text": "os_task_remove\n\n\nint\n \nos_task_remove\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nRemoves a task, \nt\n, from the task list. A task cannot be removed when it is in one of the following states:\n\n\n\n\nIt is running - a task cannot remove itself.\n\n\nIt has not been initialized.\n\n\nIt is holding a lock on a semphore or mutex.\n\n\nIt is suspended waiting on a lock (semaphore or mutex) or for an event on an event queue.\n\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to the \nos_task\n structure for the task to be removed\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: Task \nt\n is removed sucessfully.\n\nOS_INVALID_PARM\n: Task \nt\n is the calling task. A task cannot remove itself.\n\nOS_NOT_STARTED\n: Task \nt\n is not initialized.\n\nOS_EBUSY\n: Task \nt\n is either holding a lock or suspended waiting for a lock or an event.\n\n\n\nExample\n\n\nstruct\n \nos_task\n \nworker_task\n;\n\n\nint\n\n\nremove_my_worker_task\n(\nvoid\n)\n{\n \n/* Add error checking code to ensure task can removed. */\n\n\n \n/* Call os_task_remove to remove the worker task */\n\n \nrc\n \n=\n \nos_task_remove\n(\nworker_task\n);\n \nreturn\n \nrc\n;\n}",
- "title": "os_task_remove"
- },
- {
- "location": "/os/core_os/task/os_task_remove/#os_task_remove",
- "text": "int os_task_remove ( struct os_task *t ) Removes a task, t , from the task list. A task cannot be removed when it is in one of the following states: It is running - a task cannot remove itself. It has not been initialized. It is holding a lock on a semphore or mutex. It is suspended waiting on a lock (semaphore or mutex) or for an event on an event queue.",
- "title": " os_task_remove"
- },
- {
- "location": "/os/core_os/task/os_task_remove/#arguments",
- "text": "Arguments Description t Pointer to the os_task structure for the task to be removed",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/task/os_task_remove/#returned-values",
- "text": "OS_OK : Task t is removed sucessfully. OS_INVALID_PARM : Task t is the calling task. A task cannot remove itself. OS_NOT_STARTED : Task t is not initialized. OS_EBUSY : Task t is either holding a lock or suspended waiting for a lock or an event.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/task/os_task_remove/#example",
- "text": "struct os_task worker_task ; int remove_my_worker_task ( void )\n{\n /* Add error checking code to ensure task can removed. */ \n\n /* Call os_task_remove to remove the worker task */ \n rc = os_task_remove ( worker_task );\n return rc ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/event_queue/",
- "text": "Event Queues\n\n\nAn event queue allows a task to serialize incoming events and simplify event processing. Events are stored in a queue and a task removes and processes an event from the queue. An event is processed in the context of this task. Events may be generated by \nOS callouts\n, interrupt handlers, and other tasks. \n\n\nDescription\n\n\nMynewt's event queue model uses callback functions to process events. Each event is associated with a callback function that is called to process the event. This model enables a library package, that uses events in its implementation but does not have real-time timing requirements, to use an application event queue instead of creating a dedicated event queue and task to process its events. The callback function executes in the context of the task that the application creates to manage the event queue. This model reduces an application's memory requirement because memory must be allocated for the task's stack when a task is created. A package that has real-time timing requirements and must run at a specific task priority should create a dedicated event queue and task to process its events.\n\n\nIn the Mynewt model, a package defines its events and implements the callback functions for the events. A package that does not have real-time timing requirements should use Mynewt's default event queue for its events. The callback function for an event from the Mynewt default event queue is executed in the context of the application main task. A package can, optionally, export a function that allows an application to specify the event queue for the package to use. (See the example in the \nos_eventq_designate()\n function description on how to write such a function.) The application task handler that manages the event queue simply pulls events from the event queue and executes the event's callback function in its context. \n\n\nA common way that Mynewt applications or packages process events from an event queue is to have a task that executes in an infinite loop and calls the \nos_eventq_get()\n function to dequeue and return the event from the head of the event queue. The task then calls the event callback function to process the event. The \nos_eventq_get()\n function puts the task in to the \nsleeping\n state when there are no events on the queue. (See \nScheduler\n for more information on task execution states.) Other tasks (or interrupts) call the \nos_eventq_put()\n function to add an event to the queue. The \nos_eventq_put()\n function determines whether a task is blocked waiting for an event on the queue and puts the task into the \nready-to-run\n state. \n\n\nA task can use the \nos_eventq_run()\n wrapper function that calls the \nos_eventq_get()\n function to dequeue an event from the queue and then calls the event callback function to process the event.\n\n\nNote:\n\n\n\n\nOnly one task should consume or block waiting for events from an event queue.\n\n\nThe \nos_callout\n subsystem uses events for timer expiration notification.\n\n\n\n\nData structures\n\n\nThe \nos_event\n structure defines an event and has the following fields:\n\n\nstruct\n \nos_event\n {\n \nuint8_t\n \nev_queued\n;\n \nos_event_fn\n \n*ev_cb\n;\n \nvoid\n \n*ev_arg\n;\n \nSTAILQ_ENTRY\n(\nos_event\n) \nev_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nev_queued\n\n\nInternal field that indicates whether this event is currently linked to an event queue\n\n\n\n\n\n\nev_cb\n\n\nPointer to the callback function to call to process this event\n\n\n\n\n\n\nev_arg\n\n\nPointer to an optional opaque data that the callback function uses to process this event\n\n\n\n\n\n\nev_next\n\n\nLinkage attaching this event to an event queue\n\n\n\n\n\n\n\n\nAn event callback function has the following function prototype:\n\n\ntypedef\n \nvoid\n \nos_event_fn\n(\nstruct\n \nos_event\n \n*ev\n);\n\n\n\n\n\nA pointer to the \nos_event\n structure for the event is passed as an argument to the callback function. \n\n\nNotes: If the memory for the \nos_event\n structure is dynamically allocated: \n\n\n\n\nYou must not free the memory for an event that is currently on an event queue.\n\n\nYou must free the memory in the callback function after it completes processing the event.\n\n\n\n\nYou must set the callback function for an event when you initialize the event. For example, here is an example of a statically-initialized event in the NimBLE host:\n\n\nstatic\n \nvoid\n \nble_hs_event_tx_notify\n(\nstruct\n \nos_event\n \n*ev\n);\n\n\n/** OS event - triggers tx of pending notifications and indications. */\n\n\nstatic\n \nstruct\n \nos_event\n \nble_hs_ev_tx_notifications\n \n=\n {\n .\nev_cb\n \n=\n \nble_hs_event_tx_notify\n,\n};\n\n\n\n\n\n \n\nThe \nos_eventq\n structure defines an event queue and has the following fields: \n\n\nstruct\n \nos_eventq\n {\n \nstruct\n \nos_task\n \n*evq_task\n;\n \nSTAILQ_HEAD\n(, \nos_event\n) \nevq_list\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq_task\n\n\nPointer to the task, if any, that is waiting (in the \nsleeping\n state) for the \nos_eventq_get()\n function to return an event\n\n\n\n\n\n\nevq_list\n\n\nHead of the list of events in this queue\n\n\n\n\n\n\n\n\nYou must call the \nos_eventq_init()\n function to initialize an event queue before you can add events to the queue.\n\n\nList of Functions\n\n\nThe functions available in the Event Queue feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_eventq_init\n\n\nInitializes an event queue.\n\n\n\n\n\n\nos_eventq_inited\n\n\nIndicates whether an event queue has been initialized.\n\n\n\n\n\n\nos_eventq_get\n\n\nDequeues an event from the head of an event queue. The calling task blocks (in the \nsleeping\n state) when the event queue is empty.\n\n\n\n\n\n\nos_eventq_put\n\n\nEnqueues an event at the tail of an event queue and puts a task waiting for an event on the queue into the \nready-to-run\n state.\n\n\n\n\n\n\nos_eventq_remove\n\n\nRemoves an event from an event queue.\n\n\n\n\n\n\nos_eventq_dflt_get\n\n\nGets the default event queue.\n\n\n\n\n\n\nos_eventq_designate\n\n\nReassigns a package's current event queue to a new event queue.\n\n\n\n\n\n\nos_eventq_run\n\n\nWrapper function that dequeues an event from an event queue and calls the callbck function for the event.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/event_queue/event_queue/#event-queues",
- "text": "An event queue allows a task to serialize incoming events and simplify event processing. Events are stored in a queue and a task removes and processes an event from the queue. An event is processed in the context of this task. Events may be generated by OS callouts , interrupt handlers, and other tasks.",
- "title": "Event Queues"
- },
- {
- "location": "/os/core_os/event_queue/event_queue/#description",
- "text": "Mynewt's event queue model uses callback functions to process events. Each event is associated with a callback function that is called to process the event. This model enables a library package, that uses events in its implementation but does not have real-time timing requirements, to use an application event queue instead of creating a dedicated event queue and task to process its events. The callback function executes in the context of the task that the application creates to manage the event queue. This model reduces an application's memory requirement because memory must be allocated for the task's stack when a task is created. A package that has real-time timing requirements and must run at a specific task priority should create a dedicated event queue and task to process its events. In the Mynewt model, a package defines its events and implements the callback functions for the events. A package that does not have real-time timing requirements should use Mynewt's default event queue for its events. The callback function for an event from the Mynewt default event queue is executed in the context of the application main task. A package can, optionally, export a function that allows an application to specify the event queue for the package to use. (See the example in the os_eventq_designate() function description on how to write such a function.) The application task handler that manages the event queue simply pulls events from the event queue and executes the event's callback function in its context. A common way that Mynewt applications or packages process events from an event queue is to have a task that executes in an infinite loop and calls the os_eventq_get() function to dequeue and return the event from the head of the event queue. The task then calls the event callback function to process the event. The os_eventq_get() function puts the task in to the sleeping state when there are no events on the queue. (See Scheduler for more information on task execution states.) Other tasks (or interrupts) call the os_eventq_put() function to add an event to the queue. The os_eventq_put() function determines whether a task is blocked waiting for an event on the queue and puts the task into the ready-to-run state. A task can use the os_eventq_run() wrapper function that calls the os_eventq_get() function to dequeue an event from the queue and then calls the event callback function to process the event. Note: Only one task should consume or block waiting for events from an event queue. The os_callout subsystem uses events for timer expiration notification.",
- "title": "Description"
- },
- {
- "location": "/os/core_os/event_queue/event_queue/#data-structures",
- "text": "The os_event structure defines an event and has the following fields: struct os_event {\n uint8_t ev_queued ;\n os_event_fn *ev_cb ;\n void *ev_arg ;\n STAILQ_ENTRY ( os_event ) ev_next ;\n}; Element Description ev_queued Internal field that indicates whether this event is currently linked to an event queue ev_cb Pointer to the callback function to call to process this event ev_arg Pointer to an optional opaque data that the callback function uses to process this event ev_next Linkage attaching this event to an event queue An event callback function has the following function prototype: typedef void os_event_fn ( struct os_event *ev ); A pointer to the os_event structure for the event is passed as an argument to the callback function. Notes: If the memory for the os_event structure is dynamically allocated: You must not free the memory for an event that is currently on an event queue. You must free the memory in the callback function after it completes processing the event. You must set the callback function for an event when you initialize the event. For example, here is an example of a statically-initialized event in the NimBLE host: static void ble_hs_event_tx_notify ( struct os_event *ev ); /** OS event - triggers tx of pending notifications and indications. */ static struct os_event ble_hs_ev_tx_notifications = {\n . ev_cb = ble_hs_event_tx_notify ,\n}; \nThe os_eventq structure defines an event queue and has the following fields: struct os_eventq {\n struct os_task *evq_task ;\n STAILQ_HEAD (, os_event ) evq_list ;\n}; Element Description evq_task Pointer to the task, if any, that is waiting (in the sleeping state) for the os_eventq_get() function to return an event evq_list Head of the list of events in this queue You must call the os_eventq_init() function to initialize an event queue before you can add events to the queue.",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/event_queue/event_queue/#list-of-functions",
- "text": "The functions available in the Event Queue feature are: Function Description os_eventq_init Initializes an event queue. os_eventq_inited Indicates whether an event queue has been initialized. os_eventq_get Dequeues an event from the head of an event queue. The calling task blocks (in the sleeping state) when the event queue is empty. os_eventq_put Enqueues an event at the tail of an event queue and puts a task waiting for an event on the queue into the ready-to-run state. os_eventq_remove Removes an event from an event queue. os_eventq_dflt_get Gets the default event queue. os_eventq_designate Reassigns a package's current event queue to a new event queue. os_eventq_run Wrapper function that dequeues an event from an event queue and calls the callbck function for the event.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_init/",
- "text": "os_eventq_init\n\n\n \nvoid\n\n \nos_eventq_init\n(\nstruct\n \nos_eventq\n \n*evq\n)\n\n\n\n\n\nInitializes an event queue. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nPointer to the event queue to initialize\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nCalled during OS, package, and application initialization and before interrupts generating events have been enabled.\n\n\nExample\n\n\n\nThis example shows the \napp/bletest\n application initializing the \ng_bletest_evq\n event queue.\n\n\nstruct\n \nos_eventq\n \ng_bletest_evq\n;\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \n/* variable declarations here */\n\n\n \nos_eventq_init\n(\ng_bletest_evq\n);\n\n \n/* initialization continues here */\n\n\n}",
- "title": "os_eventq_init"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_init/#os_eventq_init",
- "text": "void \n os_eventq_init ( struct os_eventq *evq ) Initializes an event queue.",
- "title": " os_eventq_init"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_init/#arguments",
- "text": "Arguments Description evq Pointer to the event queue to initialize",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_init/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_init/#notes",
- "text": "Called during OS, package, and application initialization and before interrupts generating events have been enabled.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_init/#example",
- "text": "This example shows the app/bletest application initializing the g_bletest_evq event queue. struct os_eventq g_bletest_evq ; int main ( void )\n{\n /* variable declarations here */ \n\n os_eventq_init ( g_bletest_evq );\n\n /* initialization continues here */ \n\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_inited/",
- "text": "os_eventq_inited\n\n\n \nint\n\n \nos_eventq_inited\n(\nconst\n \nstruct\n \nos_eventq\n \n*evq\n)\n\n\n\n\n\nIndicates whether an event queue has been initialized.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nPointer to the event queue to check\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n1 if the event queue has been initialized and ready for use.\n\n\n0 if the event queue has not been initialized.\n\n\n\n\nNotes\n\n\nYou do not need to call this function prior to using an event queue if you have called the \nos_eventq_init()\n function \nto initialize the queue.\n\n\nExample\n\n\n\nThis example checks whether an event queue has been initialized.\n\n\nstruct\n \nos_eventq\n \ng_my_evq\n;\n\n\nint\n\n\nmy_task_init\n(\nuint8_t\n \nprio\n, \nos_stack_t\n \n*stack_ptr\n, \nuint16_t\n \nstack_len\n)\n{\n \n/* variable declarations here */\n\n\n \nif\n(\nos_eventq_inited\n(\ng_my_evq\n))\n {\n \n/* deal with the event queue */\n\n };\n\n}",
- "title": "os_eventq_inited"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_inited/#os_eventq_inited",
- "text": "int \n os_eventq_inited ( const struct os_eventq *evq ) Indicates whether an event queue has been initialized.",
- "title": " os_eventq_inited"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_inited/#arguments",
- "text": "Arguments Description evq Pointer to the event queue to check",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_inited/#returned-values",
- "text": "1 if the event queue has been initialized and ready for use. 0 if the event queue has not been initialized.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_inited/#notes",
- "text": "You do not need to call this function prior to using an event queue if you have called the os_eventq_init() function \nto initialize the queue.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_inited/#example",
- "text": "This example checks whether an event queue has been initialized. struct os_eventq g_my_evq ; int my_task_init ( uint8_t prio , os_stack_t *stack_ptr , uint16_t stack_len )\n{\n /* variable declarations here */ \n\n if ( os_eventq_inited ( g_my_evq ))\n {\n /* deal with the event queue */ \n };\n\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_get/",
- "text": "os_eventq_get\n\n\nstruct\n \nos_event\n \n*\n\n\nos_eventq_get\n(\nstruct\n \nos_eventq\n \n*evq\n)\n\n\n\n\n\nDequeues and returns an event from the head of an event queue. When the event queue is empty, \nthe function puts the task into the \nsleeping\n state.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nEvent queue to retrieve the event from\n\n\n\n\n\n\n\n\nReturned values\n\n\nA pointer to the \nos_event\n structure for the event dequeued from the queue. \n\n\nNotes\n\n\nIn most cases, you do not need to call this function directly. You should call the \nos_eventq_run()\n wrapper\nfunction that calls this function to retrieve an event and then calls the callback function to process the event. \n\n\nExample\n\n\nExample of the \nos_eventq_run()\n wrapper function that calls this function:\n\n\nvoid\n\n\nos_eventq_run\n(\nstruct\n \nos_eventq\n \n*evq\n)\n{\n \nstruct\n \nos_event\n \n*ev\n;\n\n \nev\n \n=\n \nos_eventq_get\n(\nevq\n);\n \nassert\n(\nev-\nev_cb\n \n!=\n \nNULL\n);\n\n \nev-\nev_cb\n(\nev\n);\n}",
- "title": "os_eventq_get"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_get/#os_eventq_get",
- "text": "struct os_event * os_eventq_get ( struct os_eventq *evq ) Dequeues and returns an event from the head of an event queue. When the event queue is empty, \nthe function puts the task into the sleeping state.",
- "title": " os_eventq_get"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_get/#arguments",
- "text": "Arguments Description evq Event queue to retrieve the event from",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_get/#returned-values",
- "text": "A pointer to the os_event structure for the event dequeued from the queue.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_get/#notes",
- "text": "In most cases, you do not need to call this function directly. You should call the os_eventq_run() wrapper\nfunction that calls this function to retrieve an event and then calls the callback function to process the event.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_get/#example",
- "text": "Example of the os_eventq_run() wrapper function that calls this function: void os_eventq_run ( struct os_eventq *evq )\n{\n struct os_event *ev ;\n\n ev = os_eventq_get ( evq );\n assert ( ev- ev_cb != NULL );\n\n ev- ev_cb ( ev );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put/",
- "text": "os_eventq_put\n\n\nvoid\n\n\nos_eventq_put\n(\nstruct\n \nos_eventq\n \n*evq\n, \nstruct\n \nos_event\n \n*ev\n)\n\n\n\n\n\nEnqueues an event onto the tail of an event queue. It puts a task, if any, that is in the \nsleeping\n state waiting for an event into the \nready-to-run\n state.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nEvent queue to add the event to\n\n\n\n\n\n\nev\n\n\nEvent to enqueue\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nExample\n\n\n\nThis example shows the ble host adding a host controller interface event to the \nble_hs_eventq\n event queue.\n\n\n/* Returns the ble_hs_eventq */\n\n\nstatic\n \nstruct\n \nos_eventq\n \n*\n\n\nble_hs_evq_get\n(\nvoid\n)\n{\n \nreturn\n \nble_hs_evq\n;\n}\n\n\n/* Event callback function */\n\n\nstatic\n \nvoid\n\n\nble_hs_event_rx_hci_ev\n(\nstruct\n \nos_event\n \n*ev\n)\n{\n \nuint8_t\n \n*hci_evt\n;\n \nint\n \nrc\n;\n\n \nhci_evt\n \n=\n \nev-\nev_arg\n;\n \nrc\n \n=\n \nos_memblock_put\n(\nble_hs_hci_ev_pool\n, \nev\n);\n \nBLE_HS_DBG_ASSERT_EVAL\n(\nrc\n \n==\n \n0\n);\n\n \nble_hs_hci_evt_process\n(\nhci_evt\n);\n}\n\n\nvoid\n\n\nble_hs_enqueue_hci_event\n(\nuint8_t\n \n*hci_evt\n)\n{\n \nstruct\n \nos_event\n \n*ev\n;\n\n \n/* Allocates memory for the event */\n\n \nev\n \n=\n \nos_memblock_get\n(\nble_hs_hci_ev_pool\n);\n\n \nif\n (\nev\n \n==\n \nNULL\n) {\n \nble_hci_trans_buf_free\n(\nhci_evt\n);\n } \nelse\n {\n \n/* \n\n\n * Initializes the event with the ble_hs_event_rx_hci_ev callback function \n\n\n * and the hci_evt data for the callback function to use. \n\n\n */\n \n \nev-\nev_queued\n \n=\n \n0\n;\n \nev-\nev_cb\n \n=\n \nble_hs_event_rx_hci_ev\n;\n \nev-\nev_arg\n \n=\n \nhci_evt\n;\n\n \n/* Enqueues the event on the ble_hs_evq */\n\n \nos_eventq_put\n(\nble_hs_evq_get\n(), \nev\n);\n }\n}",
- "title": "os_eventq_put"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put/#os_eventq_put",
- "text": "void os_eventq_put ( struct os_eventq *evq , struct os_event *ev ) Enqueues an event onto the tail of an event queue. It puts a task, if any, that is in the sleeping state waiting for an event into the ready-to-run state.",
- "title": " os_eventq_put"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put/#arguments",
- "text": "Arguments Description evq Event queue to add the event to ev Event to enqueue",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_put/#example",
- "text": "This example shows the ble host adding a host controller interface event to the ble_hs_eventq event queue. /* Returns the ble_hs_eventq */ static struct os_eventq * ble_hs_evq_get ( void )\n{\n return ble_hs_evq ;\n} /* Event callback function */ static void ble_hs_event_rx_hci_ev ( struct os_event *ev )\n{\n uint8_t *hci_evt ;\n int rc ;\n\n hci_evt = ev- ev_arg ;\n rc = os_memblock_put ( ble_hs_hci_ev_pool , ev );\n BLE_HS_DBG_ASSERT_EVAL ( rc == 0 );\n\n ble_hs_hci_evt_process ( hci_evt );\n} void ble_hs_enqueue_hci_event ( uint8_t *hci_evt )\n{\n struct os_event *ev ;\n\n /* Allocates memory for the event */ \n ev = os_memblock_get ( ble_hs_hci_ev_pool );\n\n if ( ev == NULL ) {\n ble_hci_trans_buf_free ( hci_evt );\n } else {\n /* * Initializes the event with the ble_hs_event_rx_hci_ev callback function * and the hci_evt data for the callback function to use. */ \n ev- ev_queued = 0 ;\n ev- ev_cb = ble_hs_event_rx_hci_ev ;\n ev- ev_arg = hci_evt ;\n\n /* Enqueues the event on the ble_hs_evq */ \n os_eventq_put ( ble_hs_evq_get (), ev );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_remove/",
- "text": "os_eventq_remove\n\n\nvoid\n\n\nos_eventq_remove\n(\nstruct\n \nos_eventq\n \n*evq\n, \nstruct\n \nos_event\n \n*ev\n)\n\n\n\n\n\nRemoves an event from an event queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nEvent queue to remove the event from\n\n\n\n\n\n\nev\n\n\nEvent to remove\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\nThis example from the \nos_callout_stop()\n function shows how to remove a callout event from an event queue. It removes\nthe event from the queue if the event is queued.\n\n\nvoid\n\n\nos_callout_stop\n(\nstruct\n \nos_callout\n \n*c\n)\n{\n \nos_sr_t\n \nsr\n;\n\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n\n \nif\n (\nos_callout_queued\n(\nc\n)) {\n \nTAILQ_REMOVE\n(\ng_callout_list\n, \nc\n, \nc_next\n);\n \nc-\nc_next\n.\ntqe_prev\n \n=\n \nNULL\n;\n }\n\n \nif\n (\nc-\nc_evq\n) {\n \nos_eventq_remove\n(\nc-\nc_evq\n, \nc-\nc_ev\n);\n }\n\n \nOS_EXIT_CRITICAL\n(\nsr\n);\n}",
- "title": "os_eventq_remove"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_remove/#os_eventq_remove",
- "text": "void os_eventq_remove ( struct os_eventq *evq , struct os_event *ev ) Removes an event from an event queue.",
- "title": " os_eventq_remove"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_remove/#arguments",
- "text": "Arguments Description evq Event queue to remove the event from ev Event to remove",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_remove/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_remove/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_remove/#example",
- "text": "This example from the os_callout_stop() function shows how to remove a callout event from an event queue. It removes\nthe event from the queue if the event is queued. void os_callout_stop ( struct os_callout *c )\n{\n os_sr_t sr ;\n\n OS_ENTER_CRITICAL ( sr );\n\n if ( os_callout_queued ( c )) {\n TAILQ_REMOVE ( g_callout_list , c , c_next );\n c- c_next . tqe_prev = NULL ;\n }\n\n if ( c- c_evq ) {\n os_eventq_remove ( c- c_evq , c- c_ev );\n }\n\n OS_EXIT_CRITICAL ( sr );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_dflt_get/",
- "text": "os_eventq_dflt_get\n\n\n \nstruct\n \nos_eventq\n \n \n*os_eventq_dflt_get\n(\nvoid\n)\n\n\n\n\n\nGets the OS default event queue that Mynewt creates at startup.\n\n\nArguments\n\n\nNone\n\n\nReturned values\n\n\nstruct os_eventq *\n: Pointer to OS the default event queue. \n\n\nNotes\n\n\nNone\n\n\nExample\n\n\n\n\nThis example shows an application's \nmain()\n function processing events from the OS default event queue.\n\n\nvoid\n \nmain\n(\nint\n \nargc\n, \nchar\n**argv\n)\n{\n \nsysinit\n();\n\n ...\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n\n}",
- "title": "os_eventq_dflt_get"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_dflt_get/#os_eventq_dflt_get",
- "text": "struct os_eventq \n *os_eventq_dflt_get ( void ) Gets the OS default event queue that Mynewt creates at startup.",
- "title": " os_eventq_dflt_get"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_dflt_get/#arguments",
- "text": "None",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_dflt_get/#returned-values",
- "text": "struct os_eventq * : Pointer to OS the default event queue.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_dflt_get/#notes",
- "text": "None",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_dflt_get/#example",
- "text": "This example shows an application's main() function processing events from the OS default event queue. void main ( int argc , char **argv )\n{\n sysinit ();\n\n ...\n\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_designate/",
- "text": "os_eventq_designate\n\n\n \nvoid\n\n \nos_eventq_designate\n(\nstruct\n \nos_eventq\n \n**cur_evq\n, \nstruct\n \nos_eventq\n \n*new_evq\n, \nstruct\n \nos_event\n \n*start_ev\n)\n\n\n\n\n\nReassigns a package's current event queue pointer to point to a new event queue. If a startup event \nis specified, the event is added to the new event queue and removed from the current event queue.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ncur_evq\n\n\nCurrent event queue pointer to reassign\n\n\n\n\n\n\nnew_evq\n\n\nNew event queue to use for the package\n\n\n\n\n\n\nstart_ev\n\n\nStart event to add to the new event queue\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nExample\n\n\n\n\nThis example shows the \nmgmt_evq_set()\n function that the \nmgmt/newtmgr\n package implements. The function\nallows an application to specify an event queue for \nnewtmgr\n to use. The \nmgmt_evq_set()\n function calls the \nos_eventq_designate()\n function to reassign the \nnmgr_evq\n to the event queue that the application specifies. \n\n\nvoid\n\n\nmgmt_evq_set\n(\nstruct\n \nos_eventq\n \n*evq\n)\n{\n \nos_eventq_designate\n(\nnmgr_evq\n, \nevq\n, \nNULL\n);\n}",
- "title": "os_eventq_designate"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_designate/#os_eventq_designate",
- "text": "void \n os_eventq_designate ( struct os_eventq **cur_evq , struct os_eventq *new_evq , struct os_event *start_ev ) Reassigns a package's current event queue pointer to point to a new event queue. If a startup event \nis specified, the event is added to the new event queue and removed from the current event queue.",
- "title": " os_eventq_designate"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_designate/#arguments",
- "text": "Arguments Description cur_evq Current event queue pointer to reassign new_evq New event queue to use for the package start_ev Start event to add to the new event queue",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_designate/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_designate/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_designate/#example",
- "text": "This example shows the mgmt_evq_set() function that the mgmt/newtmgr package implements. The function\nallows an application to specify an event queue for newtmgr to use. The mgmt_evq_set() function calls the os_eventq_designate() function to reassign the nmgr_evq to the event queue that the application specifies. void mgmt_evq_set ( struct os_eventq *evq )\n{\n os_eventq_designate ( nmgr_evq , evq , NULL );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_run/",
- "text": "os_eventq_run\n\n\n \nvoid\n\n \nos_eventq_run\n(\nstruct\n \nos_eventq\n \n*evq\n)\n\n\n\n\n\nWrapper function that calls the \nos_eventq_get()\n function to dequeue the event from the head of the event queue and then calls the callback function for the event.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nEvent queue to dequeue the event from\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nExample\n\n\n\nThis example shows an application \nmain()\n that calls the \nos_eventq_run()\n function to process events from the OS default event queue in an infinite loop.\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n\n \nsysinit\n();\n ...\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nos_eventq_dflt_get\n());\n }\n}",
- "title": "os_eventq_run"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_run/#os_eventq_run",
- "text": "void \n os_eventq_run ( struct os_eventq *evq ) Wrapper function that calls the os_eventq_get() function to dequeue the event from the head of the event queue and then calls the callback function for the event.",
- "title": " os_eventq_run"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_run/#arguments",
- "text": "Arguments Description evq Event queue to dequeue the event from",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_run/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_run/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/event_queue/os_eventq_run/#example",
- "text": "This example shows an application main() that calls the os_eventq_run() function to process events from the OS default event queue in an infinite loop. int main ( int argc , char **argv )\n{\n\n sysinit ();\n ...\n\n while ( 1 ) {\n os_eventq_run ( os_eventq_dflt_get ());\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/semaphore/semaphore/",
- "text": "Semaphore\n\n\nA semaphore is a structure used for gaining exclusive access (much like a mutex), synchronizing task operations and/or use in a \"producer/consumer\" roles. Semaphores like the ones used by the Mynewt OS are called \"counting\" semaphores as they are allowed to have more than one token (explained below).\n\n\nDescription\n\n\nA semaphore is a fairly simple construct consisting of a queue for waiting tasks and the number of tokens currently owned by the semaphore. A semaphore can be obtained as long as there are tokens in the semaphore. Any task can add tokens to the semaphore and any task can request the semaphore, thereby removing tokens. When creating the semaphore, the initial number of tokens can be set as well.\n\n\nWhen used for exclusive access to a shared resource the semaphore only needs a single token. In this case, a single task \"creates\" the semaphore by calling \nos_sem_init\n with a value of one (1) for the token. When a task desires exclusive access to the shared resource it requests the semaphore by calling \nos_sem_pend\n. If there is a token the requesting task will acquire the semaphore and continue operation. If no tokens are available the task will be put to sleep until there is a token. A common problem with using a semaphore for exclusive access is called \npriority inversion\n. Consider the following scenario: a high and low priority task both share a resource which is locked using a semaphore. If the low priority task obtains the semaphore and then the high priority task requests the semaphore, the high priority task is now blocked until the low priority task releases the semaphore. Now suppose that there are tasks between the low priority task and the high priority task that want to run. These tasks will preempt the low priority task which owns the semaphore. Thus, the high priority task is blocked waiting for the low priority task to finish using the semaphore but the low priority task cannot run since other tasks are running. Thus, the high priority tasks is \"inverted\" in priority; in effect running at a much lower priority as normally it would preempt the other (lower priority) tasks. If this is an issue a mutex should be used instead of a semaphore.\n\n\nSemaphores can also be used for task synchronization. A simple example of this would be the following. A task creates a semaphore and initializes it with no tokens. The task then waits on the semaphore, and since there are no tokens, the task is put to sleep. When other tasks want to wake up the sleeping task they simply add a token by calling \nos_sem_release\n. This will cause the sleeping task to wake up (instantly if no other higher priority tasks want to run).\n\n\nThe other common use of a counting semaphore is in what is commonly called a \"producer/consumer\" relationship. The producer adds tokens (by calling \nos_sem_release\n) and the consumer consumes them by calling \nos_sem_pend\n. In this relationship, the producer has work for the consumer to do. Each token added to the semaphore will cause the consumer to do whatever work is required. A simple example could be the following: every time a button is pressed there is some work to do (ring a bell). Each button press causes the producer to add a token. Each token consumed rings the bell. There will be exactly the same number of bell rings as there are button presses. In other words, each call to \nos_sem_pend\n subtracts exactly one token and each call to \nos_sem_release\n adds exactly one token.\n\n\nData structures\n\n\nstruct\n \nos_sem\n\n{\n \nSLIST_HEAD\n(, \nos_task\n) \nsem_head\n; \n/* chain of waiting tasks */\n\n \nuint16_t\n \n_pad\n;\n \nuint16_t\n \nsem_tokens\n; \n/* # of tokens */\n\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsem_head\n\n\nQueue head for list of tasks waiting on semaphore\n\n\n\n\n\n\n_pad\n\n\nPadding for alignment\n\n\n\n\n\n\nsem_tokens\n\n\nCurrent number of tokens\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in semaphore are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_sem_init\n\n\nInitialize a semaphore with a given number of tokens.\n\n\n\n\n\n\nos_sem_pend\n\n\nWait for a semaphore for a given amount of time.\n\n\n\n\n\n\nos_sem_release\n\n\nRelease a semaphore that you are holding. This adds a token to the semaphore.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/semaphore/semaphore/#semaphore",
- "text": "A semaphore is a structure used for gaining exclusive access (much like a mutex), synchronizing task operations and/or use in a \"producer/consumer\" roles. Semaphores like the ones used by the Mynewt OS are called \"counting\" semaphores as they are allowed to have more than one token (explained below).",
- "title": "Semaphore"
- },
- {
- "location": "/os/core_os/semaphore/semaphore/#description",
- "text": "A semaphore is a fairly simple construct consisting of a queue for waiting tasks and the number of tokens currently owned by the semaphore. A semaphore can be obtained as long as there are tokens in the semaphore. Any task can add tokens to the semaphore and any task can request the semaphore, thereby removing tokens. When creating the semaphore, the initial number of tokens can be set as well. When used for exclusive access to a shared resource the semaphore only needs a single token. In this case, a single task \"creates\" the semaphore by calling os_sem_init with a value of one (1) for the token. When a task desires exclusive access to the shared resource it requests the semaphore by calling os_sem_pend . If there is a token the requesting task will acquire the semaphore and continue operation. If no tokens are available the task will be put to sleep until there is a token. A common problem with using a semaphore for exclusive access is called priority inversion . Consider the following scenario: a high and low priority task both share a resource which is locked using a semaphore. If the low priority task obtains the semaphore and then the high priority task requests the semaphore, the high priority task is now blocked until the low priority task releases the semaphore. Now suppose that there are tasks between the low priority task and the high priority task that want to run. These tasks will preempt the low priority task which owns the semaphore. Thus, the high priority task is blocked waiting for the low priority task to finish using the semaphore but the low priority task cannot run since other tasks are running. Thus, the high priority tasks is \"inverted\" in priority; in effect running at a much lower priority as normally it would preempt the other (lower priority) tasks. If this is an issue a mutex should be used instead of a semaphore. Semaphores can also be used for task synchronization. A simple example of this would be the following. A task creates a semaphore and initializes it with no tokens. The task then waits on the semaphore, and since there are no tokens, the task is put to sleep. When other tasks want to wake up the sleeping task they simply add a token by calling os_sem_release . This will cause the sleeping task to wake up (instantly if no other higher priority tasks want to run). The other common use of a counting semaphore is in what is commonly called a \"producer/consumer\" relationship. The producer adds tokens (by calling os_sem_release ) and the consumer consumes them by calling os_sem_pend . In this relationship, the producer has work for the consumer to do. Each token added to the semaphore will cause the consumer to do whatever work is required. A simple example could be the following: every time a button is pressed there is some work to do (ring a bell). Each button press causes the producer to add a token. Each token consumed rings the bell. There will be exactly the same number of bell rings as there are button presses. In other words, each call to os_sem_pend subtracts exactly one token and each call to os_sem_release adds exactly one token.",
- "title": "Description"
- },
- {
- "location": "/os/core_os/semaphore/semaphore/#data-structures",
- "text": "struct os_sem \n{\n SLIST_HEAD (, os_task ) sem_head ; /* chain of waiting tasks */ \n uint16_t _pad ;\n uint16_t sem_tokens ; /* # of tokens */ \n}; Element Description sem_head Queue head for list of tasks waiting on semaphore _pad Padding for alignment sem_tokens Current number of tokens",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/semaphore/semaphore/#list-of-functions",
- "text": "The functions available in semaphore are: Function Description os_sem_init Initialize a semaphore with a given number of tokens. os_sem_pend Wait for a semaphore for a given amount of time. os_sem_release Release a semaphore that you are holding. This adds a token to the semaphore.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_init/",
- "text": "os_sem_init\n\n\nos_error_t\n \nos_sem_init\n(\nstruct\n \nos_sem\n \n*sem\n, \nuint16_t\n \ntokens\n) \n\n\n\n\n\nInitialize a semaphore with a given number of tokens. Should be called before the semaphore is used.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*sem\n\n\nPointer to semaphore\n\n\n\n\n\n\ntokens\n\n\nInitial number of tokens allocated to semaphore\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_INVALID_PARM\n: returned when \n*sem\n is \nNULL\n on entry.\n\n\nOS_OK\n: semaphore initialized successfully.\n\n\nNotes\n\n\n\n\nExample\n\n\nThe following example shows how to initialize a semaphore used for exclusive access.\n\n\nstruct\n \nos_mutex\n \ng_os_sem\n;\n\nos_error_t\n \nerr\n;\n\n\nerr\n \n=\n \nos_sem_init\n(\ng_os_sem\n, \n1\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);",
- "title": "os_sem_init"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_init/#os_sem_init",
- "text": "os_error_t os_sem_init ( struct os_sem *sem , uint16_t tokens ) Initialize a semaphore with a given number of tokens. Should be called before the semaphore is used.",
- "title": " os_sem_init"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_init/#arguments",
- "text": "Arguments Description *sem Pointer to semaphore tokens Initial number of tokens allocated to semaphore",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_init/#returned-values",
- "text": "OS_INVALID_PARM : returned when *sem is NULL on entry. OS_OK : semaphore initialized successfully.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_init/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_init/#example",
- "text": "The following example shows how to initialize a semaphore used for exclusive access. struct os_mutex g_os_sem ; os_error_t err ; err = os_sem_init ( g_os_sem , 1 ); assert ( err == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_pend/",
- "text": "os_sem_pend \n\n\nos_error_t\n \nos_sem_pend\n(\nstruct\n \nos_sem\n \n*sem\n, \nuint32_t\n \ntimeout\n)\n\n\n\n\n\nWait for a semaphore for a given amount of time.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*sem\n\n\nPointer to semaphore\n\n\n\n\n\n\ntimeout\n\n\nAmount of time, in os ticks, to wait for semaphore. A value of 0 means no wait. A value of 0xFFFFFFFF means wait forever.\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_INVALID_PARM\n: returned when \n*sem\n is \nNULL\n on entry.\n\n\nOS_OK\n: semaphore acquired successfully.\n\n\nOS_TIMEOUT\n: the semaphore was not available within the timeout specified.\n\n\nOS_NOT_STARTED:\n Attempt to release a semaphore before os started.\n\n\nNotes\n\n\nIf a timeout of 0 is used and the function returns \nOS_TIMEOUT\n, the semaphore was not available and was not acquired. No release of the semaphore should occur and the calling task does not own the semaphore.\n\n\nExample\n\n\nstruct\n \nos_sem\n \ng_os_sem\n;\n\nos_error_t\n \nerr\n;\n\n\nerr\n \n=\n \nos_sem_pend\n(\ng_os_sem\n, \nOS_TIMEOUT_NEVER\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);\n\n\n/* Perform operations requiring semaphore lock */\n\n\n\nerr\n \n=\n \nos_sem_release\n(\ng_os_sem\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);",
- "title": "os_sem_pend"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_pend/#os_sem_pend",
- "text": "os_error_t os_sem_pend ( struct os_sem *sem , uint32_t timeout ) Wait for a semaphore for a given amount of time.",
- "title": " os_sem_pend "
- },
- {
- "location": "/os/core_os/semaphore/os_sem_pend/#arguments",
- "text": "Arguments Description *sem Pointer to semaphore timeout Amount of time, in os ticks, to wait for semaphore. A value of 0 means no wait. A value of 0xFFFFFFFF means wait forever.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_pend/#returned-values",
- "text": "OS_INVALID_PARM : returned when *sem is NULL on entry. OS_OK : semaphore acquired successfully. OS_TIMEOUT : the semaphore was not available within the timeout specified. OS_NOT_STARTED: Attempt to release a semaphore before os started.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_pend/#notes",
- "text": "If a timeout of 0 is used and the function returns OS_TIMEOUT , the semaphore was not available and was not acquired. No release of the semaphore should occur and the calling task does not own the semaphore.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_pend/#example",
- "text": "struct os_sem g_os_sem ; os_error_t err ; err = os_sem_pend ( g_os_sem , OS_TIMEOUT_NEVER ); assert ( err == OS_OK ); /* Perform operations requiring semaphore lock */ err = os_sem_release ( g_os_sem ); assert ( err == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_release/",
- "text": "os_sem_release \n\n\nos_error_t\n \nos_sem_release\n(\nstruct\n \nos_sem\n \n*sem\n)\n\n\n\n\n\nRelease a semaphore that you are holding. This adds a token to the semaphore.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*sem\n\n\nPointer to semaphore\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_NOT_STARTED\n: Called before os has been started.\n\n\nOS_INVALID_PARM\n: returned when \n*sem\n is \nNULL\n on entry.\n\n\nOS_OK\n: semaphore released successfully.\n\n\nNotes\n\n\nExample\n\n\nstruct\n \nos_sem\n \ng_os_sem\n;\n\nos_error_t\n \nerr\n;\n\n\nerr\n \n=\n \nos_sem_pend\n(\ng_os_sem\n, \nOS_TIMEOUT_NEVER\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);\n\n\n/* Perform operations requiring semaphore lock */\n\n\n\nerr\n \n=\n \nos_sem_release\n(\ng_os_sem\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);",
- "title": "os_sem_release"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_release/#os_sem_release",
- "text": "os_error_t os_sem_release ( struct os_sem *sem ) Release a semaphore that you are holding. This adds a token to the semaphore.",
- "title": " os_sem_release "
- },
- {
- "location": "/os/core_os/semaphore/os_sem_release/#arguments",
- "text": "Arguments Description *sem Pointer to semaphore",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_release/#returned-values",
- "text": "OS_NOT_STARTED : Called before os has been started. OS_INVALID_PARM : returned when *sem is NULL on entry. OS_OK : semaphore released successfully.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_release/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/semaphore/os_sem_release/#example",
- "text": "struct os_sem g_os_sem ; os_error_t err ; err = os_sem_pend ( g_os_sem , OS_TIMEOUT_NEVER ); assert ( err == OS_OK ); /* Perform operations requiring semaphore lock */ err = os_sem_release ( g_os_sem ); assert ( err == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mutex/mutex/",
- "text": "Mutex\n\n\nMutex is short for \"mutual exclusion\"; a mutex provides mutually exclusive access to a shared resource. A mutex provides \npriority inheritance\n in order to prevent \npriority inversion\n. Priority inversion occurs when a higher priority task is waiting on a resource owned by a lower priority task. Using a mutex, the lower priority task will inherit the highest priority of any task waiting on the mutex. \n\n\nDescription\n\n\nThe first order of business when using a mutex is to declare the mutex globally. The mutex needs to be initialized before it is used (see the examples). It is generally a good idea to initialize the mutex before tasks start running in order to avoid a task possibly using the mutex before it is initialized.\n\n\nWhen a task wants exclusive access to a shared resource it needs to obtain the mutex by calling \nos_mutex_pend\n. If the mutex is currently owned by a different task (a lower priority task), the requesting task will be put to sleep and the owners priority will be elevated to the priority of the requesting task. Note that multiple tasks can request ownership and the current owner is elevated to the highest priority of any task waitin on the mutex. When the task is done using the shared resource, it needs to release the mutex by called \nos_mutex_release\n. There needs to be one release per call to pend. Note that nested calls to \nos_mutex_pend\n are allowed but there needs to be one release per pend.\n\n\nThe following example will illustrate how priority inheritance works. In this example, the task number is the same as its priority. Remember that the lower the number, the higher the priority (i.e. priority 0 is higher priority than priority 1). Suppose that task 5 gets ownership of a mutex but is preempted by task 4. Task 4 attempts to gain ownership of the mutex but cannot as it is owned by task 5. Task 4 is put to sleep and task 5 is temporarily raised to priority 4. Before task 5 can release the mutex, task 3 runs and attempts to acquire the mutex. At this point, both task 3 and task 4 are waiting on the mutex (sleeping). Task 5 now runs at priority 3 (the highest priority of all the tasks waiting on the mutex). When task 5 finally releases the mutex it will be preempted as two higher priority tasks are waiting for it. \n\n\nNote that when multiple tasks are waiting on a mutex owned by another task, once the mutex is released the highest priority task waiting on the mutex is run. \n\n\nData structures\n\n\nstruct\n \nos_mutex\n\n{\n \nSLIST_HEAD\n(, \nos_task\n) \nmu_head\n;\n \nuint8_t\n \n_pad\n;\n \nuint8_t\n \nmu_prio\n;\n \nuint16_t\n \nmu_level\n;\n \nstruct\n \nos_task\n \n*mu_owner\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmu_head\n\n\nQueue head for list of tasks waiting on mutex\n\n\n\n\n\n\n_pad\n\n\nPadding\n\n\n\n\n\n\nmu_prio\n\n\nDefault priority of owner of mutex. Used to reset priority of task when mutex released\n\n\n\n\n\n\nmu_level\n\n\nCall nesting level (for nested calls)\n\n\n\n\n\n\nmu_owner\n\n\nPointer to task structure which owns mutex\n\n\n\n\n\n\n\n\nList of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_mutex_init\n\n\nInitialize the mutex. Must be called before the mutex can be used.\n\n\n\n\n\n\nos_mutex_pend\n\n\nAcquire ownership of a mutex.\n\n\n\n\n\n\nos_mutex_release\n\n\nRelease ownership of a mutex.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/mutex/mutex/#mutex",
- "text": "Mutex is short for \"mutual exclusion\"; a mutex provides mutually exclusive access to a shared resource. A mutex provides priority inheritance in order to prevent priority inversion . Priority inversion occurs when a higher priority task is waiting on a resource owned by a lower priority task. Using a mutex, the lower priority task will inherit the highest priority of any task waiting on the mutex.",
- "title": "Mutex"
- },
- {
- "location": "/os/core_os/mutex/mutex/#description",
- "text": "The first order of business when using a mutex is to declare the mutex globally. The mutex needs to be initialized before it is used (see the examples). It is generally a good idea to initialize the mutex before tasks start running in order to avoid a task possibly using the mutex before it is initialized. When a task wants exclusive access to a shared resource it needs to obtain the mutex by calling os_mutex_pend . If the mutex is currently owned by a different task (a lower priority task), the requesting task will be put to sleep and the owners priority will be elevated to the priority of the requesting task. Note that multiple tasks can request ownership and the current owner is elevated to the highest priority of any task waitin on the mutex. When the task is done using the shared resource, it needs to release the mutex by called os_mutex_release . There needs to be one release per call to pend. Note that nested calls to os_mutex_pend are allowed but there needs to be one release per pend. The following example will illustrate how priority inheritance works. In this example, the task number is the same as its priority. Remember that the lower the number, the higher the priority (i.e. priority 0 is higher priority than priority 1). Suppose that task 5 gets ownership of a mutex but is preempted by task 4. Task 4 attempts to gain ownership of the mutex but cannot as it is owned by task 5. Task 4 is put to sleep and task 5 is temporarily raised to priority 4. Before task 5 can release the mutex, task 3 runs and attempts to acquire the mutex. At this point, both task 3 and task 4 are waiting on the mutex (sleeping). Task 5 now runs at priority 3 (the highest priority of all the tasks waiting on the mutex). When task 5 finally releases the mutex it will be preempted as two higher priority tasks are waiting for it. Note that when multiple tasks are waiting on a mutex owned by another task, once the mutex is released the highest priority task waiting on the mutex is run.",
- "title": "Description"
- },
- {
- "location": "/os/core_os/mutex/mutex/#data-structures",
- "text": "struct os_mutex \n{\n SLIST_HEAD (, os_task ) mu_head ;\n uint8_t _pad ;\n uint8_t mu_prio ;\n uint16_t mu_level ;\n struct os_task *mu_owner ;\n}; Element Description mu_head Queue head for list of tasks waiting on mutex _pad Padding mu_prio Default priority of owner of mutex. Used to reset priority of task when mutex released mu_level Call nesting level (for nested calls) mu_owner Pointer to task structure which owns mutex",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/mutex/mutex/#list-of-functions",
- "text": "The functions available in this OS feature are: Function Description os_mutex_init Initialize the mutex. Must be called before the mutex can be used. os_mutex_pend Acquire ownership of a mutex. os_mutex_release Release ownership of a mutex.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_init/",
- "text": "os_mutex_init\n\n\nos_error_t\n \nos_mutex_init\n(\nstruct\n \nos_mutex\n \n*mu\n)\n\n\n\n\n\nInitialize the mutex. Must be called before the mutex can be used.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*mu\n\n\nPointer to mutex\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_INVALID_PARM\n: returned when \n*mu\n is \nNULL\n on entry.\n\n\nOS_OK\n: mutex initialized successfully.\n\n\nNotes\n\n\n\n\nExample\n\n\nstruct\n \nos_mutex\n \ng_mutex1\n;\n\nos_error_t\n \nerr\n;\n\n\nerr\n \n=\n \nos_mutex_init\n(\ng_mutex1\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);",
- "title": "os_mutex_init"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_init/#os_mutex_init",
- "text": "os_error_t os_mutex_init ( struct os_mutex *mu ) Initialize the mutex. Must be called before the mutex can be used.",
- "title": "os_mutex_init"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_init/#arguments",
- "text": "Arguments Description *mu Pointer to mutex",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_init/#returned-values",
- "text": "OS_INVALID_PARM : returned when *mu is NULL on entry. OS_OK : mutex initialized successfully.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_init/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_init/#example",
- "text": "struct os_mutex g_mutex1 ; os_error_t err ; err = os_mutex_init ( g_mutex1 ); assert ( err == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_pend/",
- "text": "os_mutex_pend \n\n\nos_error_t\n \nos_mutex_pend\n(\nstruct\n \nos_mutex\n \n*mu\n, \nuint32_t\n \ntimeout\n) \n\n\n\n\n\nAcquire ownership of a mutex.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*mu\n\n\nPointer to mutex\n\n\n\n\n\n\ntimeout\n\n\nTimeout, in os ticks. A value of 0 means no timeout. A value of 0xFFFFFFFF means to wait forever.\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_INVALID_PARM\n: returned when \n*mu\n is \nNULL\n on entry.\n\n\nOS_OK\n: mutex was successfully acquired.\n\n\nOS_TIMEOUT\n: the mutex was not available within the timeout specified.\n\n\nOS_NOT_STARTED\n: Attempt to release a mutex before the os has been started.\n\n\nNotes\n\n\nIf the mutex is owned by another task and the timeout is 0 the function returns immediately with the error code \nOS_TIMEOUT\n. The calling task \ndoes not\n own the mutex when this occurs.\n\n\nExample\n\n\nstruct\n \nos_mutex\n \ng_mutex1\n;\n\nos_error_t\n \nerr\n;\n\n\nerr\n \n=\n \nos_mutex_pend\n(\ng_mutex1\n, \n0\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);\n\n\n/* Perform operations requiring exclusive access */\n\n\n\nerr\n \n=\n \nos_mutex_release\n(\ng_mutex1\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);",
- "title": "os_mutex_pend"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_pend/#os_mutex_pend",
- "text": "os_error_t os_mutex_pend ( struct os_mutex *mu , uint32_t timeout ) Acquire ownership of a mutex.",
- "title": "os_mutex_pend "
- },
- {
- "location": "/os/core_os/mutex/os_mutex_pend/#arguments",
- "text": "Arguments Description *mu Pointer to mutex timeout Timeout, in os ticks. A value of 0 means no timeout. A value of 0xFFFFFFFF means to wait forever.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_pend/#returned-values",
- "text": "OS_INVALID_PARM : returned when *mu is NULL on entry. OS_OK : mutex was successfully acquired. OS_TIMEOUT : the mutex was not available within the timeout specified. OS_NOT_STARTED : Attempt to release a mutex before the os has been started.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_pend/#notes",
- "text": "If the mutex is owned by another task and the timeout is 0 the function returns immediately with the error code OS_TIMEOUT . The calling task does not own the mutex when this occurs.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_pend/#example",
- "text": "struct os_mutex g_mutex1 ; os_error_t err ; err = os_mutex_pend ( g_mutex1 , 0 ); assert ( err == OS_OK ); /* Perform operations requiring exclusive access */ err = os_mutex_release ( g_mutex1 ); assert ( err == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_release/",
- "text": "os_mutex_release\n\n\nos_error_t\n \nos_mutex_release\n(\nstruct\n \nos_mutex\n \n*mu\n)\n\n\n\n\n\nRelease ownership of a mutex\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*mu\n\n\nPointer to mutex\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_INVALID_PARM\n: returned when \n*mu\n is \nNULL\n on entry.\n\n\nOS_OK\n: mutex initialized successfully.\n\n\nOS_BAD_MUTEX\n: The mutex was not owned by the task attempting to release it.\n\n\nOS_NOT_STARTED\n: Attempt to release a mutex before the os has been started.\n\n\nExample\n\n\nstruct\n \nos_mutex\n \ng_mutex1\n;\n\nos_error_t\n \nerr\n;\n\n\nerr\n \n=\n \nos_mutex_pend\n(\ng_mutex1\n, \n0\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);\n\n\n/* Perform operations requiring exclusive access */\n\n\n\nerr\n \n=\n \nos_mutex_release\n(\ng_mutex1\n);\n\nassert\n(\nerr\n \n==\n \nOS_OK\n);",
- "title": "os_mutex_release"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_release/#os_mutex_release",
- "text": "os_error_t os_mutex_release ( struct os_mutex *mu ) Release ownership of a mutex",
- "title": "os_mutex_release"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_release/#arguments",
- "text": "Arguments Description *mu Pointer to mutex",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_release/#returned-values",
- "text": "OS_INVALID_PARM : returned when *mu is NULL on entry. OS_OK : mutex initialized successfully. OS_BAD_MUTEX : The mutex was not owned by the task attempting to release it. OS_NOT_STARTED : Attempt to release a mutex before the os has been started.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mutex/os_mutex_release/#example",
- "text": "struct os_mutex g_mutex1 ; os_error_t err ; err = os_mutex_pend ( g_mutex1 , 0 ); assert ( err == OS_OK ); /* Perform operations requiring exclusive access */ err = os_mutex_release ( g_mutex1 ); assert ( err == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/memory_pool/memory_pool/",
- "text": "Memory Pools\n\n\nA memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.\n\n\nDescription\n\n\nIn order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc).\n\n\nstruct\n \nos_mempool\n \nmy_pool\n;\n\n\n\n\n\n\nThe next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named \nOS_ALIGNMENT\n and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient size to hold a list pointer as this is needed to chain memory blocks on the free list.\n\n\nIn order to simplify this for the user two macros have been provided: \nOS_MEMPOOL_BYTES(n, blksize)\n and \nOS_MEMPOOL_SIZE(n, blksize)\n. The first macro returns the number of bytes needed for the memory pool while the second returns the number of \nos_membuf_t\n elements required by the memory pool. The \nos_membuf_t\n type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. \n\n\nHere are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. \nOS_ALIGNMENT\n).\n\n\nvoid\n \n*my_memory_buffer\n;\n\nmy_memory_buffer\n \n=\n \nmalloc\n(\nOS_MEMPOOL_BYTES\n(\nNUM_BLOCKS\n, \nBLOCK_SIZE\n));\n\n\n\n\n\nos_membuf_t\n \nmy_memory_buffer\n[\nOS_MEMPOOL_SIZE\n(\nNUM_BLOCKS\n, \nBLOCK_SIZE\n)];\n\n\n\n\n\n\nNow that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool the user needs to initialize the memory pool by calling \nos_mempool_init\n.\n\n\nos_mempool_init\n(\nmy_pool\n, \nNUM_BLOCKS\n, \nBLOCK_SIZE\n, \nmy_memory_buffer\n,\n \nMyPool\n);\n\n\n\n\n\n\nOnce the memory pool has been initialized the developer can allocate memory blocks from the pool by calling \nos_memblock_get\n. When the memory block is no longer needed the memory can be freed by calling \nos_memblock_put\n. \n\n\nData structures\n\n\nstruct\n \nos_mempool\n {\n \nint\n \nmp_block_size\n;\n \nint\n \nmp_num_blocks\n;\n \nint\n \nmp_num_free\n;\n \nint\n \nmp_min_free\n;\n \nuint32_t\n \nmp_membuf_addr\n;\n \nSTAILQ_ENTRY\n(\nos_mempool\n) \nmp_list\n; \n \nSLIST_HEAD\n(,\nos_memblock\n);\n \nchar\n \n*name\n;\n};\n\n\nstruct\n \nos_mempool_info\n {\n \nint\n \nomi_block_size\n;\n \nint\n \nomi_num_blocks\n;\n \nint\n \nomi_num_free\n;\n \nint\n \nomi_min_free\n;\n \nchar\n \nomi_name\n[\nOS_MEMPOOL_INFO_NAME_LEN\n];\n};\n\n\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp_block_size\n\n\nSize of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes\n\n\n\n\n\n\nmp_num_blocks\n\n\nNumber of memory blocks in the pool\n\n\n\n\n\n\nmp_num_free\n\n\nNumber of free blocks left\n\n\n\n\n\n\nmp_min_free\n\n\nLowest number of free blocks seen\n\n\n\n\n\n\nmp_membuf_addr\n\n\nThe address of the memory block. This is used to check that a valid memory block is being freed.\n\n\n\n\n\n\nmp_list\n\n\nList pointer to chain memory pools so they can be displayed by newt tools\n\n\n\n\n\n\nSLIST_HEAD(,os_memblock)\n\n\nList pointer to chain free memory blocks\n\n\n\n\n\n\nname\n\n\nName for the memory block\n\n\n\n\n\n\n\n\nList of Functions/Macros\n\n\nThe functions/macros available in mem_pool are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_memblock_get\n\n\nAllocate an element from the memory pool.\n\n\n\n\n\n\nos_mempool_init\n\n\nInitializes the memory pool.\n\n\n\n\n\n\nos_memblock_put\n\n\nReleases previously allocated element back to the pool.\n\n\n\n\n\n\nos_mempool_info_get_next\n\n\nRetrieves memory pool information for the next memory pool.\n\n\n\n\n\n\nOS_MEMPOOL_BYTES\n\n\nCalculates how many bytes of memory is used by n number of elements, when individual element size is blksize bytes.\n\n\n\n\n\n\nOS_MEMPOOL_SIZE\n\n\nCalculates the number of os_membuf_t elements used by n blocks of size blksize bytes.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/memory_pool/memory_pool/#memory-pools",
- "text": "A memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.",
- "title": "Memory Pools"
- },
- {
- "location": "/os/core_os/memory_pool/memory_pool/#description",
- "text": "In order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc). struct os_mempool my_pool ; \nThe next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named OS_ALIGNMENT and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient size to hold a list pointer as this is needed to chain memory blocks on the free list. In order to simplify this for the user two macros have been provided: OS_MEMPOOL_BYTES(n, blksize) and OS_MEMPOOL_SIZE(n, blksize) . The first macro returns the number of bytes needed for the memory pool while the second returns the number of os_membuf_t elements required by the memory pool. The os_membuf_t type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. Here are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT ). void *my_memory_buffer ; my_memory_buffer = malloc ( OS_MEMPOOL_BYTES ( NUM_BLOCKS , BLOCK_SIZE )); os_membuf_t my_memory_buffer [ OS_MEMPOOL_SIZE ( NUM_BLOCKS , BLOCK_SIZE )]; \nNow that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool the user needs to initialize the memory pool by calling os_mempool_init . os_mempool_init ( my_pool , NUM_BLOCKS , BLOCK_SIZE , my_memory_buffer ,\n MyPool ); \nOnce the memory pool has been initialized the developer can allocate memory blocks from the pool by calling os_memblock_get . When the memory block is no longer needed the memory can be freed by calling os_memblock_put .",
- "title": "Description"
- },
- {
- "location": "/os/core_os/memory_pool/memory_pool/#data-structures",
- "text": "struct os_mempool {\n int mp_block_size ;\n int mp_num_blocks ;\n int mp_num_free ;\n int mp_min_free ;\n uint32_t mp_membuf_addr ;\n STAILQ_ENTRY ( os_mempool ) mp_list ; \n SLIST_HEAD (, os_memblock );\n char *name ;\n}; struct os_mempool_info {\n int omi_block_size ;\n int omi_num_blocks ;\n int omi_num_free ;\n int omi_min_free ;\n char omi_name [ OS_MEMPOOL_INFO_NAME_LEN ];\n}; Element Description mp_block_size Size of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes mp_num_blocks Number of memory blocks in the pool mp_num_free Number of free blocks left mp_min_free Lowest number of free blocks seen mp_membuf_addr The address of the memory block. This is used to check that a valid memory block is being freed. mp_list List pointer to chain memory pools so they can be displayed by newt tools SLIST_HEAD(,os_memblock) List pointer to chain free memory blocks name Name for the memory block",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/memory_pool/memory_pool/#list-of-functionsmacros",
- "text": "The functions/macros available in mem_pool are: Function Description os_memblock_get Allocate an element from the memory pool. os_mempool_init Initializes the memory pool. os_memblock_put Releases previously allocated element back to the pool. os_mempool_info_get_next Retrieves memory pool information for the next memory pool. OS_MEMPOOL_BYTES Calculates how many bytes of memory is used by n number of elements, when individual element size is blksize bytes. OS_MEMPOOL_SIZE Calculates the number of os_membuf_t elements used by n blocks of size blksize bytes.",
- "title": "List of Functions/Macros"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_get/",
- "text": "os_memblock_get\n\n\nvoid\n \n*os_memblock_get\n(\nstruct\n \nos_mempool\n \n*mp\n)\n\n\n\n\n\nAllocate an element from the memory pool. If successful, you'll get a pointer to allocated element. If there are no elements available, you'll get \nNULL\n as response.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nPool where element is getting allocated from\n\n\n\n\n\n\n\n\nReturned values\n\n\nNULL\n: no elements available.\n\n: pointer to allocated element.\n\n\nNotes\n\n\nExample\n\n\n\n\n \nstruct\n \nnffs_file\n \n*file\n;\n\n \nfile\n \n=\n \nos_memblock_get\n(\nnffs_file_pool\n);\n \nif\n (\nfile\n \n!=\n \nNULL\n) {\n \nmemset\n(\nfile\n, \n0\n, \nsizeof\n \n*file\n);\n }",
- "title": "os_memblock_get"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_get/#os_memblock_get",
- "text": "void *os_memblock_get ( struct os_mempool *mp ) Allocate an element from the memory pool. If successful, you'll get a pointer to allocated element. If there are no elements available, you'll get NULL as response.",
- "title": " os_memblock_get"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_get/#arguments",
- "text": "Arguments Description mp Pool where element is getting allocated from",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_get/#returned-values",
- "text": "NULL : no elements available. : pointer to allocated element.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_get/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_get/#example",
- "text": "struct nffs_file *file ;\n\n file = os_memblock_get ( nffs_file_pool );\n if ( file != NULL ) {\n memset ( file , 0 , sizeof *file );\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_info_get_next/",
- "text": "os_mempool_info_get_next\n\n\nstruct\n \nos_mempool\n \n*\n \nos_mempool_info_get_next\n(\nstruct\n \nos_mempool\n \n*mp\n, \nstruct\n \nos_mempool_info\n \n*omi\n)\n\n\n\n\n\nPopulates the os_mempool_info structure pointed to by \nomi\n with memory pool information. \nThe value of \nmp\n specifies the memory pool information to populate. If \nmp\n is \nNULL\n, it populates the information for the first memory pool on the memory pool list. If \nmp\n is not NULL, it populates the information for the next memory pool after \nmp\n. \n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nPointer to the memory pool in the memory pool list from the previous \nos_mempool_info_get_next\n function call. The next memory pool after \nmp\n is populated. If \nmp\n is NULL, the first memory pool on the memory pool list is populated.\n\n\n\n\n\n\nomi\n\n\nPointer to \nos_mempool_info\n structure where memory information will be stored.\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\nA pointer to the memory pool structure that was used to populate the memory pool information structure. \n\n\n\n\n\n\nNULL indicates \nmp\n is the last memory pool on the list and \nomi\n is not populated with memory pool information.\n\n\n\n\n\n\n\n\nExample\n\n\nshell_os_mpool_display_cmd\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nstruct\n \nos_mempool\n \n*mp\n;\n \nstruct\n \nos_mempool_info\n \nomi\n;\n \nchar\n \n*name\n;\n\n \nname\n \n=\n \nNULL\n;\n \nfound\n \n=\n \n0\n;\n\n \nif\n (\nargc\n \n \n1\n \n \nstrcmp\n(\nargv\n[\n1\n], \n)) {\n \nname\n \n=\n \nargv\n[\n1\n]; \n }\n \nconsole_printf\n(\nMempools: \\n\n);\n \nmp\n \n=\n \nNULL\n;\n \nconsole_printf\n(\n%32s %5s %4s %4s %4s\\n\n, \nname\n, \nblksz\n, \ncnt\n, \nfree\n,\n \nmin\n);\n \nwhile\n (\n1\n) {\n \nmp\n \n=\n \no\n{\n_mempool_info_get_next\n(\nmp\n, \nomi\n);\n \nif\n (\nmp\n \n==\n \nNULL\n) {\n \nbreak\n; \n }\n \nif\n (\nname\n) {\n \nif\n (\nstrcmp\n(\nname\n, \nomi\n.\nomi_name\n)) {\n \ncontinue\n;\n } \nelse\n {\n \nfound\n \n=\n \n1\n;\n }\n }\n\n \nconsole_printf\n(\n%32s %5d %4d %4d %4d\\n\n, \nomi\n.\nomi_name\n,\n \nomi\n.\nomi_block_size\n, \nomi\n.\nomi_num_blocks\n,\n \nomi\n.\nomi_num_free\n, \nomi\n.\nomi_min_free\n);\n }\n\n \nif\n (\nname\n \n \n!found\n) {\n \nconsole_printf\n(\nCouldn\nt find a memory pool with name %s\\n\n,\n \nname\n);\n }\n \nreturn\n (\n0\n);\n}",
- "title": "os_mempool_info_get_next"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_info_get_next/#os_mempool_info_get_next",
- "text": "struct os_mempool * os_mempool_info_get_next ( struct os_mempool *mp , struct os_mempool_info *omi ) Populates the os_mempool_info structure pointed to by omi with memory pool information. \nThe value of mp specifies the memory pool information to populate. If mp is NULL , it populates the information for the first memory pool on the memory pool list. If mp is not NULL, it populates the information for the next memory pool after mp .",
- "title": " os_mempool_info_get_next"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_info_get_next/#arguments",
- "text": "Arguments Description mp Pointer to the memory pool in the memory pool list from the previous os_mempool_info_get_next function call. The next memory pool after mp is populated. If mp is NULL, the first memory pool on the memory pool list is populated. omi Pointer to os_mempool_info structure where memory information will be stored.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_info_get_next/#returned-values",
- "text": "A pointer to the memory pool structure that was used to populate the memory pool information structure. NULL indicates mp is the last memory pool on the list and omi is not populated with memory pool information.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_info_get_next/#example",
- "text": "shell_os_mpool_display_cmd ( int argc , char **argv )\n{\n struct os_mempool *mp ;\n struct os_mempool_info omi ;\n char *name ;\n\n name = NULL ;\n found = 0 ;\n\n if ( argc 1 strcmp ( argv [ 1 ], )) {\n name = argv [ 1 ]; \n }\n console_printf ( Mempools: \\n );\n mp = NULL ;\n console_printf ( %32s %5s %4s %4s %4s\\n , name , blksz , cnt , free ,\n min );\n while ( 1 ) {\n mp = o { _mempool_info_get_next ( mp , omi );\n if ( mp == NULL ) {\n break ; \n }\n if ( name ) {\n if ( strcmp ( name , omi . omi_name )) {\n continue ;\n } else {\n found = 1 ;\n }\n }\n\n console_printf ( %32s %5d %4d %4d %4d\\n , omi . omi_name ,\n omi . omi_block_size , omi . omi_num_blocks ,\n omi . omi_num_free , omi . omi_min_free );\n }\n\n if ( name !found ) {\n console_printf ( Couldn t find a memory pool with name %s\\n ,\n name );\n }\n return ( 0 );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_init/",
- "text": "os_mempool_init\n\n\nos_error_t\n \nos_mempool_init\n(\nstruct\n \nos_mempool\n \n*mp\n, \nint\n \nblocks\n, \nint\n \nblock_size\n, \nvoid\n \n*membuf\n, \nchar\n \n*name\n)\n\n\n\n\n\nInitializes the memory pool. Memory pointed to by \nmembuf\n is divided into \nblocks\n number of elements of size \nOS_ALIGN(*block_size*)\n. The \nname\n is optional, and names the memory pool.\n\n\nIt is assumed that the amount of memory pointed by \nmembuf\n has at least \nOS_MEMPOOL_BYTES(blocks, block_size)\n number of bytes.\n\n\nname\n is not copied, so caller should make sure that the memory does not get reused.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nMemory pool being initialized\n\n\n\n\n\n\nblocks\n\n\nNumber of elements in the pool\n\n\n\n\n\n\nblock_size\n\n\nMinimum size of an individual element in pool\n\n\n\n\n\n\nmembuf\n\n\nBacking store for the memory pool elements\n\n\n\n\n\n\nname\n\n\nName of the memory pool\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: operation was successful.\n\n\nOS_INVALID_PARAM\n: invalid parameters. Block count or block size was negative, or \nmembuf\n or \nmp\n was \nNULL\n.\n\n\nOS_MEM_NOT_ALIGNED\n: \nmembuf\n was not aligned on correct byte boundary.\n\n\nNotes\n\n\nNote that \nos_mempool_init()\n does not allocate backing storage; \nmembuf\n has to be allocated by the caller.\n\n\nIt's recommended that you use \nOS_MEMPOOL_BYTES()\n or \nOS_MEMPOOL_SIZE()\n to figure out how much memory to allocate for the pool.\n\n\nExample\n\n\n\n\n \nvoid\n \n*nffs_file_mem\n;\n\n \nnffs_file_mem\n \n=\n \nmalloc\n(\nOS_MEMPOOL_BYTES\n(\nnffs_config\n.\nnc_num_files\n, \nsizeof\n (\nstruct\n \nnffs_file\n)));\n\n \nrc\n \n=\n \nos_mempool_init\n(\nnffs_file_pool\n, \nnffs_config\n.\nnc_num_files\n,\n \nsizeof\n (\nstruct\n \nnffs_file\n), \nnffs_file_mem\n,\n \nnffs_file_pool\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Memory pool initialization failure */\n\n }",
- "title": "os_mempool_init"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_init/#os_mempool_init",
- "text": "os_error_t os_mempool_init ( struct os_mempool *mp , int blocks , int block_size , void *membuf , char *name ) Initializes the memory pool. Memory pointed to by membuf is divided into blocks number of elements of size OS_ALIGN(*block_size*) . The name is optional, and names the memory pool. It is assumed that the amount of memory pointed by membuf has at least OS_MEMPOOL_BYTES(blocks, block_size) number of bytes. name is not copied, so caller should make sure that the memory does not get reused.",
- "title": " os_mempool_init"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_init/#arguments",
- "text": "Arguments Description mp Memory pool being initialized blocks Number of elements in the pool block_size Minimum size of an individual element in pool membuf Backing store for the memory pool elements name Name of the memory pool",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_init/#returned-values",
- "text": "OS_OK : operation was successful. OS_INVALID_PARAM : invalid parameters. Block count or block size was negative, or membuf or mp was NULL . OS_MEM_NOT_ALIGNED : membuf was not aligned on correct byte boundary.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_init/#notes",
- "text": "Note that os_mempool_init() does not allocate backing storage; membuf has to be allocated by the caller. It's recommended that you use OS_MEMPOOL_BYTES() or OS_MEMPOOL_SIZE() to figure out how much memory to allocate for the pool.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/memory_pool/os_mempool_init/#example",
- "text": "void *nffs_file_mem ;\n\n nffs_file_mem = malloc ( OS_MEMPOOL_BYTES ( nffs_config . nc_num_files , sizeof ( struct nffs_file )));\n\n rc = os_mempool_init ( nffs_file_pool , nffs_config . nc_num_files ,\n sizeof ( struct nffs_file ), nffs_file_mem ,\n nffs_file_pool );\n if ( rc != 0 ) {\n /* Memory pool initialization failure */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_put/",
- "text": "os_memblock_put\n\n\nos_error_t\n \nos_memblock_put\n(\nstruct\n \nos_mempool\n \n*mp\n, \nvoid\n \n*block_addr\n)\n\n\n\n\n\nReleases previously allocated element back to the pool. \n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nPointer to memory pool from which block was allocated\n\n\n\n\n\n\nblock_addr\n\n\nPointer to element getting freed\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: operation was a success:\n\n\nOS_INVALID_PARAM\n: If either \nmp\n or \nblock_addr\n were \nNULL\n, or the block being freed was outside the range of the memory buffer or not on a true block size boundary.\n\n\n\n\nExample\n\n\n\n\n \nif\n (\nfile\n \n!=\n \nNULL\n) {\n \nrc\n \n=\n \nos_memblock_put\n(\nnffs_file_pool\n, \nfile\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Error freeing memory block */\n\n }\n }",
- "title": "os_memblock_put"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_put/#os_memblock_put",
- "text": "os_error_t os_memblock_put ( struct os_mempool *mp , void *block_addr ) Releases previously allocated element back to the pool.",
- "title": "os_memblock_put"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_put/#arguments",
- "text": "Arguments Description mp Pointer to memory pool from which block was allocated block_addr Pointer to element getting freed",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_put/#returned-values",
- "text": "OS_OK : operation was a success: OS_INVALID_PARAM : If either mp or block_addr were NULL , or the block being freed was outside the range of the memory buffer or not on a true block size boundary.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/memory_pool/os_memblock_put/#example",
- "text": "if ( file != NULL ) {\n rc = os_memblock_put ( nffs_file_pool , file );\n if ( rc != 0 ) {\n /* Error freeing memory block */ \n }\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/",
- "text": "OS_MEMPOOL_BYTES\n\n\nOS_MEMPOOL_BYTES\n(\nn\n,\nblksize\n)\n\n\n\n\n\nCalculates how many bytes of memory is used by \nn\n number of elements, when individual element size is \nblksize\n bytes.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nn\n\n\nNumber of elements\n\n\n\n\n\n\nblksize\n\n\nSize of an element is number of bytes\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of bytes used by the memory pool.\n\n\n\n\nNotes\n\n\nOS_MEMPOOL_BYTES\n is a macro and not a function.\n\n\n\n\nExample\n\n\nHere we allocate memory to be used as a pool.\n\n\n \nvoid\n \n*nffs_file_mem\n;\n\n \nnffs_file_mem\n \n=\n \nmalloc\n(\nOS_MEMPOOL_BYTES\n(\nnffs_config\n.\nnc_num_files\n, \nsizeof\n (\nstruct\n \nnffs_file\n)));\n \nif\n (\nnffs_file_mem\n \n==\n \nNULL\n) {\n \nreturn\n \nFS_ENOMEM\n;\n }",
- "title": "OS_MEMPOOL_BYTES"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#os_mempool_bytes",
- "text": "OS_MEMPOOL_BYTES ( n , blksize ) Calculates how many bytes of memory is used by n number of elements, when individual element size is blksize bytes.",
- "title": "OS_MEMPOOL_BYTES"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#arguments",
- "text": "Arguments Description n Number of elements blksize Size of an element is number of bytes",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#returned-values",
- "text": "The number of bytes used by the memory pool.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#notes",
- "text": "OS_MEMPOOL_BYTES is a macro and not a function.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_BYTES/#example",
- "text": "Here we allocate memory to be used as a pool. void *nffs_file_mem ;\n\n nffs_file_mem = malloc ( OS_MEMPOOL_BYTES ( nffs_config . nc_num_files , sizeof ( struct nffs_file )));\n if ( nffs_file_mem == NULL ) {\n return FS_ENOMEM ;\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/",
- "text": "OS_MEMPOOL_SIZE\n\n\nOS_MEMPOOL_SIZE\n(\nn\n,\nblksize\n)\n\n\n\n\n\nCalculates the number of \nos_membuf_t\n elements used by \nn\n blocks of size \nblksize\n bytes.\n\n\nNote that \nos_membuf_t\n is used so that memory blocks are aligned on \nOS_ALIGNMENT\n boundaries.\n\n\nThe \nblksize\n variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on \nOS_ALIGNMENT\n boundaries. \n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nn\n\n\nNumber of elements\n\n\n\n\n\n\nblksize\n\n\nSize of an element is number of bytes\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe number of \nos_membuf_t\n elements used by the memory pool. Note that \nos_membuf_t\n is defined to be a unsigned, 32-bit integer when \nOS_ALIGNMENT\n is 4 and an unsigned, 64-bit integer when \nOS_ALIGNMENT\n is 8.\n\n\n\n\nNotes\n\n\nOS_MEMPOOL_SIZE\n is a macro and not a function.\n\n\n\n\nExample\n\n\nHere we define a memory buffer to be used by a memory pool using \nOS_MEMPOOL_SIZE\n\n\n#define NUM_BLOCKS (16)\n\n\n#define BLOCK_SIZE (32)\n\n\n\nos_membuf_t\n \nmy_pool_memory\n[\nOS_MEMPOOL_SIZE\n(\nNUM_BLOCKS\n, \nBLOCK_SIZE\n)]",
- "title": "OS_MEMPOOL_SIZE"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#os_mempool_size",
- "text": "OS_MEMPOOL_SIZE ( n , blksize ) Calculates the number of os_membuf_t elements used by n blocks of size blksize bytes. Note that os_membuf_t is used so that memory blocks are aligned on OS_ALIGNMENT boundaries. The blksize variable is the minimum number of bytes required for each block; the actual block size is padded so that each block is aligned on OS_ALIGNMENT boundaries.",
- "title": "OS_MEMPOOL_SIZE"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#arguments",
- "text": "Arguments Description n Number of elements blksize Size of an element is number of bytes",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#returned-values",
- "text": "The number of os_membuf_t elements used by the memory pool. Note that os_membuf_t is defined to be a unsigned, 32-bit integer when OS_ALIGNMENT is 4 and an unsigned, 64-bit integer when OS_ALIGNMENT is 8.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#notes",
- "text": "OS_MEMPOOL_SIZE is a macro and not a function.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/memory_pool/OS_MEMPOOL_SIZE/#example",
- "text": "Here we define a memory buffer to be used by a memory pool using OS_MEMPOOL_SIZE #define NUM_BLOCKS (16) #define BLOCK_SIZE (32) os_membuf_t my_pool_memory [ OS_MEMPOOL_SIZE ( NUM_BLOCKS , BLOCK_SIZE )]",
- "title": "Example"
- },
- {
- "location": "/os/core_os/heap/heap/",
- "text": "Heap\n\n\nAPI for doing dynamic memory allocation.\n\n\nDescription\n\n\nThis provides \nmalloc()\n \n \nfree()\n functionality with locking. The shared resource heap needs to be protected from concurrent access when OS has been started. \nos_malloc()\n function grabs a mutex before calling \nmalloc()\n.\n\n\nData structures\n\n\nN/A\n\n\nList of Functions\n\n\nThe functions available in heap are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_free\n\n\nFrees previously allocated memory back to the heap.\n\n\n\n\n\n\nos_malloc\n\n\nAllocates the given number of bytes from heap and returns a pointer to it.\n\n\n\n\n\n\nos_realloc\n\n\nTries to resize previously allocated memory block, and returns pointer to resized memory.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/heap/heap/#heap",
- "text": "API for doing dynamic memory allocation.",
- "title": "Heap"
- },
- {
- "location": "/os/core_os/heap/heap/#description",
- "text": "This provides malloc() free() functionality with locking. The shared resource heap needs to be protected from concurrent access when OS has been started. os_malloc() function grabs a mutex before calling malloc() .",
- "title": "Description"
- },
- {
- "location": "/os/core_os/heap/heap/#data-structures",
- "text": "N/A",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/heap/heap/#list-of-functions",
- "text": "The functions available in heap are: Function Description os_free Frees previously allocated memory back to the heap. os_malloc Allocates the given number of bytes from heap and returns a pointer to it. os_realloc Tries to resize previously allocated memory block, and returns pointer to resized memory.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/heap/os_free/",
- "text": "os_free\n\n\nvoid\n \nos_free\n(\nvoid\n \n*mem\n)\n\n\n\n\n\nFrees previously allocated memory back to the heap.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmem\n\n\nPointer to memory being released\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nCalls C-library \nfree()\n under the covers.\n\n\nExample\n\n\n\n\n \nos_free\n(\ninfo\n);",
- "title": "os_free"
- },
- {
- "location": "/os/core_os/heap/os_free/#os_free",
- "text": "void os_free ( void *mem ) Frees previously allocated memory back to the heap.",
- "title": "os_free"
- },
- {
- "location": "/os/core_os/heap/os_free/#arguments",
- "text": "Arguments Description mem Pointer to memory being released",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/heap/os_free/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/heap/os_free/#notes",
- "text": "Calls C-library free() under the covers.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/heap/os_free/#example",
- "text": "os_free ( info );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/heap/os_malloc/",
- "text": "os_malloc\n\n\nvoid\n \n*os_malloc\n(\nsize_t\n \nsize\n)\n\n\n\n\n\nAllocates \nsize\n number of bytes from heap and returns a pointer to it.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsize\n\n\nNumber of bytes to allocate\n\n\n\n\n\n\n\n\nReturned values\n\n\nptr\n: pointer to memory allocated from heap.\n\nNULL\n: not enough memory available.\n\n\nNotes\n\n\nos_malloc()\n calls \nmalloc()\n, which is provided by the C-library. The heap must be set up during platform initialization.\nDepending on which C-library you use, you might have to do the heap setup differently. Most often \nmalloc()\n implementation will maintain a list of allocated and then freed memory blocks. If user asks for memory which cannot be satisfied from free list, they'll call platform's \nsbrk()\n, which then tries to grow the heap.\n\n\nExample\n\n\n\n\n \ninfo\n \n=\n (\nstruct\n \nos_task_info\n \n*\n) \nos_malloc\n(\n \nsizeof\n(\nstruct\n \nos_task_info\n) \n*\n \ntcount\n);\n \nif\n (\n!info\n) {\n \nrc\n \n=\n \n-\n1\n;\n \ngoto\n \nerr\n;\n }",
- "title": "os_malloc"
- },
- {
- "location": "/os/core_os/heap/os_malloc/#os_malloc",
- "text": "void *os_malloc ( size_t size ) Allocates size number of bytes from heap and returns a pointer to it.",
- "title": " os_malloc"
- },
- {
- "location": "/os/core_os/heap/os_malloc/#arguments",
- "text": "Arguments Description size Number of bytes to allocate",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/heap/os_malloc/#returned-values",
- "text": "ptr : pointer to memory allocated from heap. NULL : not enough memory available.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/heap/os_malloc/#notes",
- "text": "os_malloc() calls malloc() , which is provided by the C-library. The heap must be set up during platform initialization.\nDepending on which C-library you use, you might have to do the heap setup differently. Most often malloc() implementation will maintain a list of allocated and then freed memory blocks. If user asks for memory which cannot be satisfied from free list, they'll call platform's sbrk() , which then tries to grow the heap.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/heap/os_malloc/#example",
- "text": "info = ( struct os_task_info * ) os_malloc (\n sizeof ( struct os_task_info ) * tcount );\n if ( !info ) {\n rc = - 1 ;\n goto err ;\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/heap/os_realloc/",
- "text": "os_realloc\n\n\nvoid\n \n*os_realloc\n(\nvoid\n \n*ptr\n, \nsize_t\n \nsize\n)\n\n\n\n\n\nTries to resize previously allocated memory block, and returns pointer to resized memory.\n\nptr\n can be \nNULL\n, in which case the call is similar to calling \nos_malloc()\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nptr\n\n\nPointer to previously allocated memory\n\n\n\n\n\n\nsize\n\n\nNew size to adjust the memory block to\n\n\n\n\n\n\n\n\nReturned values\n\n\nNULL\n: size adjustment was not successful. \n\n\nptr\n: pointer to new start of memory block\n\n\nNotes\n\n\nExample\n\n\n\n\nInsert\n \nthe\n \ncode\n \nsnippet\n \nhere",
- "title": "os_realloc"
- },
- {
- "location": "/os/core_os/heap/os_realloc/#os_realloc",
- "text": "void *os_realloc ( void *ptr , size_t size ) Tries to resize previously allocated memory block, and returns pointer to resized memory. ptr can be NULL , in which case the call is similar to calling os_malloc() .",
- "title": "os_realloc"
- },
- {
- "location": "/os/core_os/heap/os_realloc/#arguments",
- "text": "Arguments Description ptr Pointer to previously allocated memory size New size to adjust the memory block to",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/heap/os_realloc/#returned-values",
- "text": "NULL : size adjustment was not successful. ptr : pointer to new start of memory block",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/heap/os_realloc/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/heap/os_realloc/#example",
- "text": "Insert the code snippet here",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/",
- "text": "Mbufs\n\n\nThe mbuf (short for memory buffer) is a common concept in networking stacks. The mbuf is used to hold packet data as it traverses the stack. The mbuf also generally stores header information or other networking stack information that is carried around with the packet. The mbuf and its associated library of functions were developed to make common networking stack operations (like stripping and adding protocol headers) efficient and as copy-free as possible.\n\n\nIn its simplest form, an mbuf is a memory block with some space reserved for internal information and a pointer which is used to \"chain\" memory blocks together in order to create a \"packet\". This is a very important aspect of the mbuf: the ability to chain mbufs together to create larger \"packets\" (chains of mbufs).\n\n\nWhy use mbufs?\n\n\nThe main reason is to conserve memory. Consider a networking protocol that generally sends small packets but occasionally sends large ones. The Bluetooth Low Energy (BLE) protocol is one such example. A flat buffer would need to be sized so that the maximum packet size could be contained by the buffer. With the mbuf, a number of mbufs can be chained together so that the occasional large packet can be handled while leaving more packet buffers available to the networking stack for smaller packets.\n\n\nPacket Header mbuf\n\n\nNot all mbufs are created equal. The first mbuf in a chain of mbufs is a special mbuf called a \"packet header mbuf\". The reason that this mbuf is special is that it contains the length of all the data contained by the chain of mbufs (the packet length, in other words). The packet header mbuf may also contain a user defined structure (called a \"user header\") so that networking protocol specific information can be conveyed to various layers of the networking stack. Any mbufs that are part of the packet (i.e. in the mbuf chain but not the first one) are \"normal\" (i.e. non-packet header) mbufs. A normal mbuf does not have any packet header or user packet header structures in them; they only contain the basic mbuf header (\nstruct os_mbuf\n). Figure 1 illustrates these two types of mbufs. Note that the numbers/text in parentheses denote the size of the structures/elements (in bytes) and that \nMBLEN\n is the memory block length of the memory pool used by the mbuf pool.\n\n\n\n\nNormal mbuf\n\n\nNow let's take a deeper dive into the mbuf structure. Figure 2 illustrates a normal mbuf and breaks out the various fields in the \nos_mbuf\n structure. \n\n\n\n\nThe \nom_data\n field is a pointer to where the data starts inside the data buffer. Typically, mbufs that are allocated from the mbuf pool (discussed later) have their \nom_data\n pointer set to the start of the data buffer but there are cases where this may not be desirable (added a protocol header to a packet, for example). \n\n\nThe \nom_flags\n field is a set of flags used internally by the mbuf library. Currently, no flags have been defined. \n\n\nThe \nom_pkthdr_len\n field is the total length of all packet headers in the mbuf. For normal mbufs this is set to 0 as there is no packet or user packet headers. For packet header mbufs, this would be set to the length of the packet header structure (16) plus the size of the user packet header (if any). Note that it is this field which differentiates packet header mbufs from normal mbufs (i.e. if \nom_pkthdr_len\n is zero, this is a normal mbuf; otherwise it is a packet header mbuf). \n\n\nThe \nom_len\n field contains the amount of user data in the data buffer. When initially allocated, this field is 0 as there is no user data in the mbuf. \n\n\nThe \nomp_pool\n field is a pointer to the pool from which this mbuf has been allocated. This is used internally by the mbuf library. \n\n\nThe \nomp_next\n field is a linked list element which is used to chain mbufs.\n\n\n\n\nFigure 2 also shows a normal mbuf with actual values in the \nos_mbuf\n structure. This mbuf starts at address 0x1000 and is 256 bytes in total length. In this example, the user has copied 33 bytes into the data buffer starting at address 0x1010 (this is where \nom_data\n points). Note that the packet header length in this mbuf is 0 as it is not a packet header mbuf.\n\n\n\n\nFigure 3 illustrates the packet header mbuf along with some chained mbufs (i.e a \"packet\"). In this example, the user header structure is defined to be 8 bytes. Note that in figure 3 we show a number of different mbufs with varying \nom_data\n pointers and lengths since we want to show various examples of valid mbufs. For all the mbufs (both packet header and normal ones) the total length of the memory block is 128 bytes.\n\n\n\n\nMbuf pools\n\n\nMbufs are collected into \"mbuf pools\" much like memory blocks. The mbuf pool itself contains a pointer to a memory pool. The memory blocks in this memory pool are the actual mbufs; both normal and packet header mbufs. Thus, the memory block (and corresponding memory pool) must be sized correctly. In other words, the memory blocks which make up the memory pool used by the mbuf pool must be at least: \nsizeof(struct os_mbuf)\n + \nsizeof(struct os_mbuf_pkthdr)\n + \nsizeof(struct user_defined_header)\n + \ndesired minimum data buffer length\n. For example, if the developer wants mbufs to contain at least 64 bytes of user data and they have a user header of 12 bytes, the size of the memory block would be (at least): 64 + 12 + 16 + 8, or 100 bytes. Yes, this is a fair amount of overhead. However, the flexibility provided by the mbuf library usually outweighs overhead concerns.\n\n\nCreate mbuf pool\n\n\nCreating an mbuf pool is fairly simple: create a memory pool and then create the mbuf pool using that memory pool. Once the developer has determined the size of the user data needed per mbuf (this is based on the application/networking stack and is outside the scope of this discussion) and the size of the user header (if any), the memory blocks can be sized. In the example shown below, the application requires 64 bytes of user data per mbuf and also allocates a user header (called \nstruct user_hdr\n). Note that we do not show the user header data structure as there really is no need; all we need to do is to account for it when creating the memory pool. In the example, we use the macro \nMBUF_PKTHDR_OVERHEAD\n to denote the amount of packet header overhead per mbuf and \nMBUF_MEMBLOCK_OVERHEAD\n to denote the total amount of overhead required per memory block. The macro \nMBUF_BUF_SIZE\n is used to denote the amount of payload that the application requires (aligned on a 32-bit boundary in this case). All this leads to the total memory block size required, denoted by the macro \nMBUF_MEMBLOCK_OVERHEAD\n.\n\n\n#define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr)\n\n\n#define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD\n\n\n\n#define MBUF_NUM_MBUFS (32)\n\n\n#define MBUF_PAYLOAD_SIZE (64)\n\n\n#define MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4)\n\n\n#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD)\n\n\n#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE)\n\n\n\nstruct\n \nos_mbuf_pool\n \ng_mbuf_pool\n; \n\nstruct\n \nos_mempool\n \ng_mbuf_mempool\n;\n\nos_membuf_t\n \ng_mbuf_buffer\n[\nMBUF_MEMPOOL_SIZE\n];\n\n\nvoid\n\n\ncreate_mbuf_pool\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n, \n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n, \n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n}\n\n\n\n\n\nUsing mbufs\n\n\nThe following examples illustrate typical mbuf usage. There are two basic mbuf allocation API: \nos_mbuf_get()\n and \nos_mbuf_get_pkthdr()\n. The first API obtains a normal mbuf whereas the latter obtains a packet header mbuf. Typically, application developers use \nos_mbuf_get_pkthdr()\n and rarely, if ever, need to call \nos_mbuf_get()\n as the rest of the mbuf API (e.g. \nos_mbuf_append()\n, \nos_mbuf_copyinto()\n, etc.) typically deal with allocating and chaining mbufs. It is recommended to use the provided API to copy data into/out of mbuf chains and/or manipulate mbufs.\n\n\nIn \nexample1\n, the developer creates a packet and then sends the packet to a networking interface. The code sample also provides an example of copying data out of an mbuf as well as use of the \"pullup\" api (another very common mbuf api).\n\n\nvoid\n\n\nmbuf_usage_example1\n(\nuint8_t\n \n*mydata\n, \nint\n \nmydata_length\n)\n{\n \nint\n \nrc\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/* get a packet header mbuf */\n\n \nom\n \n=\n \nos_mbuf_get_pkthdr\n(\ng_mbuf_pool\n, \nsizeof\n(\nstruct\n \nuser_hdr\n));\n \nif\n (\nom\n) {\n \n/* \n\n\n * Copy user data into mbuf. NOTE: if mydata_length is greater than the\n\n\n * mbuf payload size (64 bytes using above example), mbufs are allocated\n\n\n * and chained together to accommodate the total packet length.\n\n\n */\n\n \nrc\n \n=\n \nos_mbuf_copyinto\n(\nom\n, \n0\n, \nmydata\n, \nlen\n);\n \nif\n (\nrc\n) {\n \n/* Error! Could not allocate enough mbufs for total packet length */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Send packet to networking interface */\n\n \nsend_pkt\n(\nom\n);\n }\n}\n\n\n\n\n\nIn \nexample2\n we show use of the pullup api as this illustrates some of the typical pitfalls developers encounter when using mbufs. The first pitfall is one of alignment/padding. Depending on the processor and/or compiler, the \nsizeof()\n a structure may vary. Thus, the size of \nmy_protocol_header\n may be different inside the packet data of the mbuf than the size of the structure on the stack or as a global variable, for instance. While some networking protcols may align protocol information on convenient processor boundaries many others try to conserve bytes \"on the air\" (i.e inside the packet data). Typical methods used to deal with this are \"packing\" the structure (i.e. force compiler to not pad) or creating protocol headers that do not require padding. \nexample2\n assumes that one of these methods was used when defining the \nmy_protocol_header\n structure.\n\n\nAnother common pitfall occurs around endianness. A network protocol may be little endian or big endian; it all depends on the protocol specification. Processors also have an endianness; this means that the developer has to be careful that the processor endianness and the protocol endianness are handled correctly. In \nexample2\n, some common networking functions are used: \nntohs()\n and \nntohl()\n. These are shorthand for \"network order to host order, short\" and \"network order to host order, long\". Basically, these functions convert data of a certain size (i.e. 16 bits, 32 bits, etc) to the endianness of the host. Network byte order is big-endian (most significant byte first), so these functions convert big-endian byte order to host order (thus, the implementation of these functions is host dependent). Note that the BLE networking stack \"on the air\" format is least signigicant byte first (i.e. little-endian), so a \nbletoh\n function would have to take little-endian format and convert to host format.\n\n\nA long story short: the developer must take care when copying structure data to/from mbufs and flat buffers!\n\n\nA final note: these examples assume the same mbuf struture and definitions used in the first example. \n\n\nvoid\n\n\nmbuf_usage_example2\n(\nstruct\n \nmbuf\n \n*rxpkt\n)\n{\n \nint\n \nrc\n;\n \nuint8_t\n \npacket_data\n[\n16\n];\n \nstruct\n \nmbuf\n \n*om\n;\n \nstruct\n \nmy_protocol_header\n \n*phdr\n;\n\n \n/* Make sure that \nmy_protocol_header\n bytes are contiguous in mbuf */\n\n \nom\n \n=\n \nos_mbuf_pullup\n(\ng_mbuf_pool\n, \nsizeof\n(\nstruct\n \nmy_protocol_header\n));\n \nif\n (\n!om\n) {\n \n/* Not able to pull up data into contiguous area */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* \n\n\n * Get the protocol information from the packet. In this example we presume that we\n\n\n * are interested in protocol types that are equal to MY_PROTOCOL_TYPE, are not zero\n\n\n * length, and have had some time in flight.\n\n\n */\n\n \nphdr\n \n=\n \nOS_MBUF_DATA\n(\nom\n, \nstruct\n \nmy_protocol_header\n \n*\n);\n \ntype\n \n=\n \nntohs\n(\nphdr-\nprot_type\n);\n \nlength\n \n=\n \nntohs\n(\nphdr-\nprot_length\n);\n \ntime_in_flight\n \n=\n \nntohl\n(\nphdr-\nprot_tif\n);\n\n \nif\n ((\ntype\n \n==\n \nMY_PROTOCOL_TYPE\n) \n (\nlength\n \n \n0\n) \n (\ntime_in_flight\n \n \n0\n)) {\n \nrc\n \n=\n \nos_mbuf_copydata\n(\nrxpkt\n, \nsizeof\n(\nstruct\n \nmy_protocol_header\n), \n16\n, \npacket_data\n);\n \nif\n (\n!rc\n) {\n \n/* Success! Perform operations on packet data */\n\n \n... \nuser\n \ncode\n \nhere\n ...\n\n }\n }\n\n \n/* Free passed in packet (mbuf chain) since we don\nt need it anymore */\n\n \nos_mbuf_free_chain\n(\nom\n);\n}\n\n\n\n\n\n\n\nData Structures\n\n\nstruct\n \nos_mbuf_pool\n {\n \nuint16_t\n \nomp_databuf_len\n;\n \nuint16_t\n \nomp_mbuf_count\n;\n \nstruct\n \nos_mempool\n \n*omp_pool\n;\n \nSTAILQ_ENTRY\n(\nos_mbuf_pool\n) \nomp_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nomp_databuf_len\n\n\nThe length, in bytes, of the \"data buffer\" of the mbuf. The data buffer of the mbuf is everything except the os_mbuf structure (which is present in all types of mbufs)\n\n\n\n\n\n\nomp_mbuf_count\n\n\nTotal number of mbufs in the pool when allocated. This is NOT the number of free mbufs in the pool!\n\n\n\n\n\n\nomp_pool\n\n\nThe memory pool from which the mbufs are allocated\n\n\n\n\n\n\nomp_next\n\n\nThis is a linked list pointer which chains memory pools. It is used by the system memory pool library\n\n\n\n\n\n\n\n\n\n\nstruct\n \nos_mbuf_pkthdr\n {\n \nuint16_t\n \nomp_len\n;\n \nuint16_t\n \nomp_flags\n;\n \nSTAILQ_ENTRY\n(\nos_mbuf_pkthdr\n) \nomp_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nomp_len\n\n\nLength, in bytes, of the \"packet\". This is the sum of the user data in all the mbufs chained to the packet header mbuf (including the packet header mbuf)\n\n\n\n\n\n\nomp_flags\n\n\nPacket header flags.\n\n\n\n\n\n\nomp_next\n\n\nLinked list pointer to chain \"packets\". This can be used to add mbuf chains to a queue or linked list and is there for convenience.\n\n\n\n\n\n\n\n\n\n\nstruct\n \nos_mbuf\n {\n \nuint8_t\n \n*om_data\n;\n \nuint8_t\n \nom_flags\n;\n \nuint8_t\n \nom_pkthdr_len\n;\n \nuint16_t\n \nom_len\n;\n \nstruct\n \nos_mbuf_pool\n \n*om_omp\n;\n \nSLIST_ENTRY\n(\nos_mbuf\n) \nom_next\n;\n \nuint8_t\n \nom_databuf\n[\n0\n];\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom_data\n\n\nPointer to start of user data in mbuf data buffer\n\n\n\n\n\n\nom_flags\n\n\nmbuf flags field. Currently all flags unused.\n\n\n\n\n\n\nom_pkthdr_len\n\n\nThe total length of all packet headers in the mbuf (mbuf packet header plus user packet header), in bytes\n\n\n\n\n\n\nom_len\n\n\nThe length of the user data contained in this mbuf, in bytes\n\n\n\n\n\n\nom_omp\n\n\nMemory pool pointer. This is the mbuf pool from which this mbuf was allocated.\n\n\n\n\n\n\nom_next\n\n\nPointer to next mbuf in packet chain\n\n\n\n\n\n\nom_databuf\n\n\nmbuf data buffer (accessor to start of mbuf data buffer). Note that the mbuf data buffer refers to the start of either the user data in normal mbufs or the start of the os mbuf packet header for packet header mbufs\n\n\n\n\n\n\n\n\nList of Functions/Macros\n\n\nThe functions/macros available in mbuf are:\n\n\n\n\n\n\n\n\nFunction/Macro\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nOS_MBUF_PKTHDR\n\n\nGet a pointer to the os mbuf packet header of an mbuf.\n\n\n\n\n\n\nOS_MBUF_PKTHDR_TO_MBUF\n\n\nGet a pointer to the mbuf given a pointer to the os mbuf packet header.\n\n\n\n\n\n\nOS_MBUF_PKTLEN\n\n\nGet the length of an entire mbuf chain.\n\n\n\n\n\n\nOS_MBUF_DATA\n\n\nCast the data pointer of an mbuf to a given type.\n\n\n\n\n\n\nOS_MBUF_USRHDR\n\n\nGet a pointer to the user packet header of an mbuf.\n\n\n\n\n\n\nOS_MBUF_USRHDR_LEN\n\n\nRetrieve the length of the user packet header in an mbuf.\n\n\n\n\n\n\nOS_MBUF_LEADINGSPACE\n\n\nGet the amount of leading space in an mbuf (in bytes).\n\n\n\n\n\n\nOS_MBUF_TRAILINGSPACE\n\n\nGet the amount of trailing space in an mbuf (in bytes).\n\n\n\n\n\n\nos_mbuf_adj\n\n\nTrims the given number of bytes from either the head (if positive) or tail (if negative) of an mbuf chain.\n\n\n\n\n\n\nos_mbuf_append\n\n\nAppends a data buffer of the given length to the end of an mbuf chain.\n\n\n\n\n\n\nos_mbuf_concat\n\n\nAttaches a second mbuf chain onto the end of the first.\n\n\n\n\n\n\nos_mbuf_copydata\n\n\nCopy data from an mbuf chain.\n\n\n\n\n\n\nos_mbuf_copyinto\n\n\nCopies the contents of a flat buffer into an mbuf chain.\n\n\n\n\n\n\nos_mbuf_dup\n\n\nDuplicate a chain of mbufs.\n\n\n\n\n\n\nos_mbuf_extend\n\n\nIncreases the length of an mbuf chain by the specified amount.\n\n\n\n\n\n\nos_mbuf_free_chain\n\n\nFrees a chain of mbufs.\n\n\n\n\n\n\nos_mbuf_get\n\n\nGet an mbuf from the mbuf pool.\n\n\n\n\n\n\nos_mbuf_get_pkthdr\n\n\nAllocates a packet header mbuf from the given mbuf pool. Adds a user header to the packet header mbuf.\n\n\n\n\n\n\nos_mbuf_memcmp\n\n\nPerforms a memory compare of the specified region of an mbuf chain against a flat buffer.\n\n\n\n\n\n\nos_mbuf_off\n\n\nGiven an offset in the packet, return the mbuf and the offset in that mbuf where byte 'off' is located.\n\n\n\n\n\n\nos_mbuf_pool_init\n\n\nnitialize an mbuf pool.\n\n\n\n\n\n\nos_mbuf_prepend\n\n\nIncreases the length of an mbuf chain by adding data to the front.\n\n\n\n\n\n\nos_mbuf_pullup\n\n\nRearrange an mbuf chain so that the given length of bytes are contiguous and in the data area of an mbuf.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#mbufs",
- "text": "The mbuf (short for memory buffer) is a common concept in networking stacks. The mbuf is used to hold packet data as it traverses the stack. The mbuf also generally stores header information or other networking stack information that is carried around with the packet. The mbuf and its associated library of functions were developed to make common networking stack operations (like stripping and adding protocol headers) efficient and as copy-free as possible. In its simplest form, an mbuf is a memory block with some space reserved for internal information and a pointer which is used to \"chain\" memory blocks together in order to create a \"packet\". This is a very important aspect of the mbuf: the ability to chain mbufs together to create larger \"packets\" (chains of mbufs).",
- "title": "Mbufs"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#why-use-mbufs",
- "text": "The main reason is to conserve memory. Consider a networking protocol that generally sends small packets but occasionally sends large ones. The Bluetooth Low Energy (BLE) protocol is one such example. A flat buffer would need to be sized so that the maximum packet size could be contained by the buffer. With the mbuf, a number of mbufs can be chained together so that the occasional large packet can be handled while leaving more packet buffers available to the networking stack for smaller packets.",
- "title": "Why use mbufs?"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#packet-header-mbuf",
- "text": "Not all mbufs are created equal. The first mbuf in a chain of mbufs is a special mbuf called a \"packet header mbuf\". The reason that this mbuf is special is that it contains the length of all the data contained by the chain of mbufs (the packet length, in other words). The packet header mbuf may also contain a user defined structure (called a \"user header\") so that networking protocol specific information can be conveyed to various layers of the networking stack. Any mbufs that are part of the packet (i.e. in the mbuf chain but not the first one) are \"normal\" (i.e. non-packet header) mbufs. A normal mbuf does not have any packet header or user packet header structures in them; they only contain the basic mbuf header ( struct os_mbuf ). Figure 1 illustrates these two types of mbufs. Note that the numbers/text in parentheses denote the size of the structures/elements (in bytes) and that MBLEN is the memory block length of the memory pool used by the mbuf pool.",
- "title": "Packet Header mbuf"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#normal-mbuf",
- "text": "Now let's take a deeper dive into the mbuf structure. Figure 2 illustrates a normal mbuf and breaks out the various fields in the os_mbuf structure. The om_data field is a pointer to where the data starts inside the data buffer. Typically, mbufs that are allocated from the mbuf pool (discussed later) have their om_data pointer set to the start of the data buffer but there are cases where this may not be desirable (added a protocol header to a packet, for example). The om_flags field is a set of flags used internally by the mbuf library. Currently, no flags have been defined. The om_pkthdr_len field is the total length of all packet headers in the mbuf. For normal mbufs this is set to 0 as there is no packet or user packet headers. For packet header mbufs, this would be set to the length of the packet header structure (16) plus the size of the user packet header (if any). Note that it is this field which differentiates packet header mbufs from normal mbufs (i.e. if om_pkthdr_len is zero, this is a normal mbuf; otherwise it is a packet header mbuf). The om_len field contains the amount of user data in the data buffer. When initially allocated, this field is 0 as there is no user data in the mbuf. The omp_pool field is a pointer to the pool from which this mbuf has been allocated. This is used internally by the mbuf library. The omp_next field is a linked list element which is used to chain mbufs. Figure 2 also shows a normal mbuf with actual values in the os_mbuf structure. This mbuf starts at address 0x1000 and is 256 bytes in total length. In this example, the user has copied 33 bytes into the data buffer starting at address 0x1010 (this is where om_data points). Note that the packet header length in this mbuf is 0 as it is not a packet header mbuf. Figure 3 illustrates the packet header mbuf along with some chained mbufs (i.e a \"packet\"). In this example, the user header structure is defined to be 8 bytes. Note that in figure 3 we show a number of different mbufs with varying om_data pointers and lengths since we want to show various examples of valid mbufs. For all the mbufs (both packet header and normal ones) the total length of the memory block is 128 bytes.",
- "title": "Normal mbuf"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#mbuf-pools",
- "text": "Mbufs are collected into \"mbuf pools\" much like memory blocks. The mbuf pool itself contains a pointer to a memory pool. The memory blocks in this memory pool are the actual mbufs; both normal and packet header mbufs. Thus, the memory block (and corresponding memory pool) must be sized correctly. In other words, the memory blocks which make up the memory pool used by the mbuf pool must be at least: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_defined_header) + desired minimum data buffer length . For example, if the developer wants mbufs to contain at least 64 bytes of user data and they have a user header of 12 bytes, the size of the memory block would be (at least): 64 + 12 + 16 + 8, or 100 bytes. Yes, this is a fair amount of overhead. However, the flexibility provided by the mbuf library usually outweighs overhead concerns.",
- "title": "Mbuf pools"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#create-mbuf-pool",
- "text": "Creating an mbuf pool is fairly simple: create a memory pool and then create the mbuf pool using that memory pool. Once the developer has determined the size of the user data needed per mbuf (this is based on the application/networking stack and is outside the scope of this discussion) and the size of the user header (if any), the memory blocks can be sized. In the example shown below, the application requires 64 bytes of user data per mbuf and also allocates a user header (called struct user_hdr ). Note that we do not show the user header data structure as there really is no need; all we need to do is to account for it when creating the memory pool. In the example, we use the macro MBUF_PKTHDR_OVERHEAD to denote the amount of packet header overhead per mbuf and MBUF_MEMBLOCK_OVERHEAD to denote the total amount of overhead required per memory block. The macro MBUF_BUF_SIZE is used to denote the amount of payload that the application requires (aligned on a 32-bit boundary in this case). All this leads to the total memory block size required, denoted by the macro MBUF_MEMBLOCK_OVERHEAD . #define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr) #define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD #define MBUF_NUM_MBUFS (32) #define MBUF_PAYLOAD_SIZE (64) #define MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4) #define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD) #define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE) struct os_mbuf_pool g_mbuf_pool ; struct os_mempool g_mbuf_mempool ; os_membuf_t g_mbuf_buffer [ MBUF_MEMPOOL_SIZE ]; void create_mbuf_pool ( void )\n{\n int rc ;\n\n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS , \n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE , \n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n}",
- "title": "Create mbuf pool"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#using-mbufs",
- "text": "The following examples illustrate typical mbuf usage. There are two basic mbuf allocation API: os_mbuf_get() and os_mbuf_get_pkthdr() . The first API obtains a normal mbuf whereas the latter obtains a packet header mbuf. Typically, application developers use os_mbuf_get_pkthdr() and rarely, if ever, need to call os_mbuf_get() as the rest of the mbuf API (e.g. os_mbuf_append() , os_mbuf_copyinto() , etc.) typically deal with allocating and chaining mbufs. It is recommended to use the provided API to copy data into/out of mbuf chains and/or manipulate mbufs. In example1 , the developer creates a packet and then sends the packet to a networking interface. The code sample also provides an example of copying data out of an mbuf as well as use of the \"pullup\" api (another very common mbuf api). void mbuf_usage_example1 ( uint8_t *mydata , int mydata_length )\n{\n int rc ;\n struct os_mbuf *om ;\n\n /* get a packet header mbuf */ \n om = os_mbuf_get_pkthdr ( g_mbuf_pool , sizeof ( struct user_hdr ));\n if ( om ) {\n /* * Copy user data into mbuf. NOTE: if mydata_length is greater than the * mbuf payload size (64 bytes using above example), mbufs are allocated * and chained together to accommodate the total packet length. */ \n rc = os_mbuf_copyinto ( om , 0 , mydata , len );\n if ( rc ) {\n /* Error! Could not allocate enough mbufs for total packet length */ \n return - 1 ;\n }\n\n /* Send packet to networking interface */ \n send_pkt ( om );\n }\n} In example2 we show use of the pullup api as this illustrates some of the typical pitfalls developers encounter when using mbufs. The first pitfall is one of alignment/padding. Depending on the processor and/or compiler, the sizeof() a structure may vary. Thus, the size of my_protocol_header may be different inside the packet data of the mbuf than the size of the structure on the stack or as a global variable, for instance. While some networking protcols may align protocol information on convenient processor boundaries many others try to conserve bytes \"on the air\" (i.e inside the packet data). Typical methods used to deal with this are \"packing\" the structure (i.e. force compiler to not pad) or creating protocol headers that do not require padding. example2 assumes that one of these methods was used when defining the my_protocol_header structure. Another common pitfall occurs around endianness. A network protocol may be little endian or big endian; it all depends on the protocol specification. Processors also have an endianness; this means that the developer has to be careful that the processor endianness and the protocol endianness are handled correctly. In example2 , some common networking functions are used: ntohs() and ntohl() . These are shorthand for \"network order to host order, short\" and \"network order to host order, long\". Basically, these functions convert data of a certain size (i.e. 16 bits, 32 bits, etc) to the endianness of the host. Network byte order is big-endian (most significant byte first), so these functions convert big-endian byte order to host order (thus, the implementation of these functions is host dependent). Note that the BLE networking stack \"on the air\" format is least signigicant byte first (i.e. little-endian), so a bletoh function would have to take little-endian format and convert to host format. A long story short: the developer must take care when copying structure data to/from mbufs and flat buffers! A final note: these examples assume the same mbuf struture and definitions used in the first example. void mbuf_usage_example2 ( struct mbuf *rxpkt )\n{\n int rc ;\n uint8_t packet_data [ 16 ];\n struct mbuf *om ;\n struct my_protocol_header *phdr ;\n\n /* Make sure that my_protocol_header bytes are contiguous in mbuf */ \n om = os_mbuf_pullup ( g_mbuf_pool , sizeof ( struct my_protocol_header ));\n if ( !om ) {\n /* Not able to pull up data into contiguous area */ \n return - 1 ;\n }\n\n /* * Get the protocol information from the packet. In this example we presume that we * are interested in protocol types that are equal to MY_PROTOCOL_TYPE, are not zero * length, and have had some time in flight. */ \n phdr = OS_MBUF_DATA ( om , struct my_protocol_header * );\n type = ntohs ( phdr- prot_type );\n length = ntohs ( phdr- prot_length );\n time_in_flight = ntohl ( phdr- prot_tif );\n\n if (( type == MY_PROTOCOL_TYPE ) ( length 0 ) ( time_in_flight 0 )) {\n rc = os_mbuf_copydata ( rxpkt , sizeof ( struct my_protocol_header ), 16 , packet_data );\n if ( !rc ) {\n /* Success! Perform operations on packet data */ \n ... user code here ... \n }\n }\n\n /* Free passed in packet (mbuf chain) since we don t need it anymore */ \n os_mbuf_free_chain ( om );\n}",
- "title": "Using mbufs"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#data-structures",
- "text": "struct os_mbuf_pool {\n uint16_t omp_databuf_len ;\n uint16_t omp_mbuf_count ;\n struct os_mempool *omp_pool ;\n STAILQ_ENTRY ( os_mbuf_pool ) omp_next ;\n}; Element Description omp_databuf_len The length, in bytes, of the \"data buffer\" of the mbuf. The data buffer of the mbuf is everything except the os_mbuf structure (which is present in all types of mbufs) omp_mbuf_count Total number of mbufs in the pool when allocated. This is NOT the number of free mbufs in the pool! omp_pool The memory pool from which the mbufs are allocated omp_next This is a linked list pointer which chains memory pools. It is used by the system memory pool library struct os_mbuf_pkthdr {\n uint16_t omp_len ;\n uint16_t omp_flags ;\n STAILQ_ENTRY ( os_mbuf_pkthdr ) omp_next ;\n}; Element Description omp_len Length, in bytes, of the \"packet\". This is the sum of the user data in all the mbufs chained to the packet header mbuf (including the packet header mbuf) omp_flags Packet header flags. omp_next Linked list pointer to chain \"packets\". This can be used to add mbuf chains to a queue or linked list and is there for convenience. struct os_mbuf {\n uint8_t *om_data ;\n uint8_t om_flags ;\n uint8_t om_pkthdr_len ;\n uint16_t om_len ;\n struct os_mbuf_pool *om_omp ;\n SLIST_ENTRY ( os_mbuf ) om_next ;\n uint8_t om_databuf [ 0 ];\n}; Element Description om_data Pointer to start of user data in mbuf data buffer om_flags mbuf flags field. Currently all flags unused. om_pkthdr_len The total length of all packet headers in the mbuf (mbuf packet header plus user packet header), in bytes om_len The length of the user data contained in this mbuf, in bytes om_omp Memory pool pointer. This is the mbuf pool from which this mbuf was allocated. om_next Pointer to next mbuf in packet chain om_databuf mbuf data buffer (accessor to start of mbuf data buffer). Note that the mbuf data buffer refers to the start of either the user data in normal mbufs or the start of the os mbuf packet header for packet header mbufs",
- "title": "Data Structures"
- },
- {
- "location": "/os/core_os/mbuf/mbuf/#list-of-functionsmacros",
- "text": "The functions/macros available in mbuf are: Function/Macro Description OS_MBUF_PKTHDR Get a pointer to the os mbuf packet header of an mbuf. OS_MBUF_PKTHDR_TO_MBUF Get a pointer to the mbuf given a pointer to the os mbuf packet header. OS_MBUF_PKTLEN Get the length of an entire mbuf chain. OS_MBUF_DATA Cast the data pointer of an mbuf to a given type. OS_MBUF_USRHDR Get a pointer to the user packet header of an mbuf. OS_MBUF_USRHDR_LEN Retrieve the length of the user packet header in an mbuf. OS_MBUF_LEADINGSPACE Get the amount of leading space in an mbuf (in bytes). OS_MBUF_TRAILINGSPACE Get the amount of trailing space in an mbuf (in bytes). os_mbuf_adj Trims the given number of bytes from either the head (if positive) or tail (if negative) of an mbuf chain. os_mbuf_append Appends a data buffer of the given length to the end of an mbuf chain. os_mbuf_concat Attaches a second mbuf chain onto the end of the first. os_mbuf_copydata Copy data from an mbuf chain. os_mbuf_copyinto Copies the contents of a flat buffer into an mbuf chain. os_mbuf_dup Duplicate a chain of mbufs. os_mbuf_extend Increases the length of an mbuf chain by the specified amount. os_mbuf_free_chain Frees a chain of mbufs. os_mbuf_get Get an mbuf from the mbuf pool. os_mbuf_get_pkthdr Allocates a packet header mbuf from the given mbuf pool. Adds a user header to the packet header mbuf. os_mbuf_memcmp Performs a memory compare of the specified region of an mbuf chain against a flat buffer. os_mbuf_off Given an offset in the packet, return the mbuf and the offset in that mbuf where byte 'off' is located. os_mbuf_pool_init nitialize an mbuf pool. os_mbuf_prepend Increases the length of an mbuf chain by adding data to the front. os_mbuf_pullup Rearrange an mbuf chain so that the given length of bytes are contiguous and in the data area of an mbuf.",
- "title": "List of Functions/Macros"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR/",
- "text": "OS_MBUF_PKTHDR\n\n\nOS_MBUF_PKTHDR\n(\n__om\n)\n\n\n\n\n\nMacro used to get a pointer to the os mbuf packet header of an mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *)\n\n\n\n\n\n\n\n\n\n\nExample\n\n\nint\n\n\ndoes_packet_have_data\n(\nstruct\n \nos_mbuf\n \n*om\n)\n{\n \nstruct\n \nos_mbuf_pkthdr\n \n*hdr\n;\n\n \nhdr\n \n=\n \nOS_MBUF_PKTHDR\n(\nom\n);\n \nif\n (\nhdr-\nomp_len\n \n!=\n \n0\n) {\n \n/* Packet has data in it */\n\n \nreturn\n \nTRUE\n\n } \nelse\n {\n \n/* Packet has no data */\n\n \nreturn\n \nFALSE\n;\n }\n}",
- "title": "OS_MBUF_PKTHDR"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR/#os_mbuf_pkthdr",
- "text": "OS_MBUF_PKTHDR ( __om ) Macro used to get a pointer to the os mbuf packet header of an mbuf.",
- "title": "OS_MBUF_PKTHDR"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR/#example",
- "text": "int does_packet_have_data ( struct os_mbuf *om )\n{\n struct os_mbuf_pkthdr *hdr ;\n\n hdr = OS_MBUF_PKTHDR ( om );\n if ( hdr- omp_len != 0 ) {\n /* Packet has data in it */ \n return TRUE \n } else {\n /* Packet has no data */ \n return FALSE ;\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF/",
- "text": "OS_MBUF_PKTHDR_TO_MBUF\n\n\nOS_MBUF_PKTHDR_TO_MBUF\n(\n__hdr\n)\n\n\n\n\n\nMacro used to get a pointer to the mbuf given a pointer to the os mbuf packet header\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__hdr\n\n\nPointer to os mbuf packet header (struct os_mbuf_pkthdr *)\n\n\n\n\n\n\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nos_mbuf_pkthdr\n \n*hdr\n;\n\n \nom\n \n=\n \nOS_MBUF_PKTHDR_TO_MBUF\n(\nhdr\n);\n \nos_mbuf_free_chain\n(\nom\n);",
- "title": "OS_MBUF_PKTHDR_TO_MBUF"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF/#os_mbuf_pkthdr_to_mbuf",
- "text": "OS_MBUF_PKTHDR_TO_MBUF ( __hdr ) Macro used to get a pointer to the mbuf given a pointer to the os mbuf packet header",
- "title": "OS_MBUF_PKTHDR_TO_MBUF"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF/#arguments",
- "text": "Arguments Description __hdr Pointer to os mbuf packet header (struct os_mbuf_pkthdr *)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF/#example",
- "text": "struct os_mbuf *om ;\n struct os_mbuf_pkthdr *hdr ;\n\n om = OS_MBUF_PKTHDR_TO_MBUF ( hdr );\n os_mbuf_free_chain ( om );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTLEN/",
- "text": "OS_MBUF_PKTLEN\n\n\nOS_MBUF_PKTLEN\n(\n__om\n)\n\n\n\n\n\nMacro used to get the length of an entire mbuf chain.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *)\n\n\n\n\n\n\n\n\n\n\nExample\n\n\n \nuint16_t\n \npktlen\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/* Check if there is any data in the mbuf chain */\n\n \npktlen\n \n=\n \nOS_MBUF_PKTLEN\n(\nom\n);\n \nif\n (\npktlen\n \n!=\n \n0\n) {\n \n/* mbuf chain has data */\n\n }",
- "title": "OS_MBUF_PKTLEN"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTLEN/#os_mbuf_pktlen",
- "text": "OS_MBUF_PKTLEN ( __om ) Macro used to get the length of an entire mbuf chain.",
- "title": "OS_MBUF_PKTLEN"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTLEN/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_PKTLEN/#example",
- "text": "uint16_t pktlen ;\n struct os_mbuf *om ;\n\n /* Check if there is any data in the mbuf chain */ \n pktlen = OS_MBUF_PKTLEN ( om );\n if ( pktlen != 0 ) {\n /* mbuf chain has data */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_DATA/",
- "text": "OS_MBUF_DATA\n\n\nOS_MBUF_DATA\n(\n__om\n, \n__type\n)\n\n\n\n\n\nMacro used to cast the data pointer of an mbuf to a given type.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *)\n\n\n\n\n\n\n__type\n\n\nType to cast\n\n\n\n\n\n\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n\n \nuint8_t\n \n*rxbuf\n;\n\n \nrxbuf\n \n=\n \nOS_MBUF_DATA\n(\nom\n, \nuint8_t\n \n*\n);",
- "title": "OS_MBUF_DATA"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_DATA/#os_mbuf_data",
- "text": "OS_MBUF_DATA ( __om , __type ) Macro used to cast the data pointer of an mbuf to a given type.",
- "title": "OS_MBUF_DATA"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_DATA/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *) __type Type to cast",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_DATA/#example",
- "text": "struct os_mbuf *om \n uint8_t *rxbuf ;\n\n rxbuf = OS_MBUF_DATA ( om , uint8_t * );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR/",
- "text": "OS_MBUF_USRHDR\n\n\nOS_MBUF_USRHDR\n(\n__om\n)\n\n\n\n\n\nMacro used to get a pointer to the user packet header of an mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf)\n\n\n\n\n\n\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n\n \nstruct\n \nuser_header\n \n*hdr\n;\n\n \nhdr\n \n=\n \nOS_MBUF_USRHDR\n(\nom\n);",
- "title": "OS_MBUF_USRHDR"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR/#os_mbuf_usrhdr",
- "text": "OS_MBUF_USRHDR ( __om ) Macro used to get a pointer to the user packet header of an mbuf.",
- "title": "OS_MBUF_USRHDR"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR/#example",
- "text": "struct os_mbuf *om \n struct user_header *hdr ;\n\n hdr = OS_MBUF_USRHDR ( om );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR_LEN/",
- "text": "OS_MBUF_USRHDR_LEN\n\n\nOS_MBUF_USRHDR_LEN\n(\n__om\n)\n\n\n\n\n\nMacro used to retrieve the length of the user packet header in an mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf)\n\n\n\n\n\n\n\n\n\n\nExample\n\n\n \nuint16_t\n \nuser_length\n;\n \nstruct\n \nos_mbuf\n \n*om\n\n \nstruct\n \nuser_header\n \n*hdr\n;\n\n \nuser_length\n \n=\n \nOS_MBUF_USRHDR_LEN\n(\nom\n);",
- "title": "OS_MBUF_USRHDR_LEN"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR_LEN/#os_mbuf_usrhdr_len",
- "text": "OS_MBUF_USRHDR_LEN ( __om ) Macro used to retrieve the length of the user packet header in an mbuf.",
- "title": "OS_MBUF_USRHDR_LEN"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR_LEN/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_USRHDR_LEN/#example",
- "text": "uint16_t user_length ;\n struct os_mbuf *om \n struct user_header *hdr ;\n\n user_length = OS_MBUF_USRHDR_LEN ( om );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_LEADINGSPACE/",
- "text": "OS_MBUF_LEADINGSPACE\n\n\nOS_MBUF_LEADINGSPACE\n(\n__om\n)\n\n\n\n\n\nMacro used to get the amount of leading space in an mbuf (in bytes).\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *)\n\n\n\n\n\n\n\n\n\n\nNotes\n\n\nThis macro works on both normal mbufs and packet header mbufs. The amount of leading space is the number of bytes between the current \nom_data\n pointer of the mbuf and the start of the mbuf user data buffer.\n\n\n\n\nExample\n\n\n \nuint8_t\n \n*dptr\n;\n \nuint16_t\n \nspace\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_data_struct\n \nmy_data\n;\n\n \n/* Copy data from \nmy_data\n into the start of an mbuf but only if there is enough room */\n\n \nspace\n \n=\n \nOS_MBUF_LEADINGSPACE\n(\nom\n);\n \nif\n (\nspace\n \n=\n \nsizeof\n(\nstruct\n \nmy_data_struct\n)) {\n \ndptr\n \n=\n \nom-\nom_data\n \n-\n \nsizeof\n(\nstruct\n \nmy_data_struct\n);\n \nmemcpy\n(\ndptr\n, \nmy_data\n, \nsizeof\n(\nstruct\n \nmy_data_struct\n));\n }",
- "title": "OS_MBUF_LEADINGSPACE"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_LEADINGSPACE/#os_mbuf_leadingspace",
- "text": "OS_MBUF_LEADINGSPACE ( __om ) Macro used to get the amount of leading space in an mbuf (in bytes).",
- "title": "OS_MBUF_LEADINGSPACE"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_LEADINGSPACE/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_LEADINGSPACE/#notes",
- "text": "This macro works on both normal mbufs and packet header mbufs. The amount of leading space is the number of bytes between the current om_data pointer of the mbuf and the start of the mbuf user data buffer.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_LEADINGSPACE/#example",
- "text": "uint8_t *dptr ;\n uint16_t space ;\n struct os_mbuf *om ;\n struct my_data_struct my_data ;\n\n /* Copy data from my_data into the start of an mbuf but only if there is enough room */ \n space = OS_MBUF_LEADINGSPACE ( om );\n if ( space = sizeof ( struct my_data_struct )) {\n dptr = om- om_data - sizeof ( struct my_data_struct );\n memcpy ( dptr , my_data , sizeof ( struct my_data_struct ));\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE/",
- "text": "OS_MBUF_TRAILINGSPACE\n\n\nOS_MBUF_TRAILINGSPACE\n(\n__om\n)\n\n\n\n\n\nMacro used to get the amount of trailing space in an mbuf (in bytes).\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__om\n\n\nPointer to mbuf (struct os_mbuf *)\n\n\n\n\n\n\n\n\n\n\nNotes\n\n\nThis macro works on both normal mbufs and packet header mbufs. The amount of trailing space is the number of bytes between the current \nom_data\n pointer of the mbuf and the end of the mbuf.\n\n\n\n\nExample\n\n\n \nuint16_t\n \nspace\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_data_struct\n \nmy_data\n;\n\n \n/* Copy data from \nmy_data\n to the end of an mbuf but only if there is enough room */\n\n \nspace\n \n=\n \nOS_MBUF_TRAILINGSPACE\n(\nom\n);\n \nif\n (\nspace\n \n=\n \nsizeof\n(\nstruct\n \nmy_data_struct\n)) {\n \nmemcpy\n(\nom-\nom_data\n, \nmy_data\n, \nsizeof\n(\nstruct\n \nmy_data_struct\n));\n }",
- "title": "OS_MBUF_TRAILINGSPACE"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE/#os_mbuf_trailingspace",
- "text": "OS_MBUF_TRAILINGSPACE ( __om ) Macro used to get the amount of trailing space in an mbuf (in bytes).",
- "title": "OS_MBUF_TRAILINGSPACE"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE/#arguments",
- "text": "Arguments Description __om Pointer to mbuf (struct os_mbuf *)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE/#notes",
- "text": "This macro works on both normal mbufs and packet header mbufs. The amount of trailing space is the number of bytes between the current om_data pointer of the mbuf and the end of the mbuf.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE/#example",
- "text": "uint16_t space ;\n struct os_mbuf *om ;\n struct my_data_struct my_data ;\n\n /* Copy data from my_data to the end of an mbuf but only if there is enough room */ \n space = OS_MBUF_TRAILINGSPACE ( om );\n if ( space = sizeof ( struct my_data_struct )) {\n memcpy ( om- om_data , my_data , sizeof ( struct my_data_struct ));\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_adj/",
- "text": "os_mbuf_adj\n\n\nvoid\n \nos_mbuf_adj\n(\nstruct\n \nos_mbuf\n \n*mp\n, \nint\n \nreq_len\n);\n\n\n\n\n\nTrims \nreq_len\n bytes from either the head (if positive) or tail (if negative) of an mbuf chain. Adjusts the packet length of the mbuf chain if \nmp\n points to a packet header mbuf. When trimming from the head, no mbufs are freed. When trimming from the tail, any mbufs of zero length left at the end of the chain are freed.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmp\n\n\nPointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf\n\n\n\n\n\n\nreq_len\n\n\nNumber of bytes to trim from head or tail of mbuf\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nExample\n\n\n \nuint16_t\n \npktlen\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_pkt_header\n \nhdr\n;\n\n \n/* Get mbuf chain length */\n\n \npktlen\n \n=\n \nOS_MBUF_PKTLEN\n(\nom\n);\n\n \n/* Strip header from mbuf chain */\n\n \nos_mbuf_adj\n(\nom\n, \nsizeof\n(\nstruct\n \nmy_pkt_header\n));\n \npktlen\n \n-=\n \nsizeof\n(\nstruct\n \nmy_pkt_header\n);\n\n \n/* New packet length should be old packet length minus stripped header */\n\n \nassert\n(\npktlen\n \n==\n \nOS_MBUF_PKTLEN\n(\nom\n));",
- "title": "os_mbuf_adj"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_adj/#os_mbuf_adj",
- "text": "void os_mbuf_adj ( struct os_mbuf *mp , int req_len ); Trims req_len bytes from either the head (if positive) or tail (if negative) of an mbuf chain. Adjusts the packet length of the mbuf chain if mp points to a packet header mbuf. When trimming from the head, no mbufs are freed. When trimming from the tail, any mbufs of zero length left at the end of the chain are freed.",
- "title": " os_mbuf_adj"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_adj/#arguments",
- "text": "Arguments Description mp Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf req_len Number of bytes to trim from head or tail of mbuf",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_adj/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_adj/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_adj/#example",
- "text": "uint16_t pktlen ;\n struct os_mbuf *om ;\n struct my_pkt_header hdr ;\n\n /* Get mbuf chain length */ \n pktlen = OS_MBUF_PKTLEN ( om );\n\n /* Strip header from mbuf chain */ \n os_mbuf_adj ( om , sizeof ( struct my_pkt_header ));\n pktlen -= sizeof ( struct my_pkt_header );\n\n /* New packet length should be old packet length minus stripped header */ \n assert ( pktlen == OS_MBUF_PKTLEN ( om ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_append/",
- "text": "os_mbuf_append\n\n\nint\n \nos_mbuf_append\n(\nstruct\n \nos_mbuf\n \n*om\n, \nconst\n \nvoid\n \n*data\n, \nuint16_t\n \nlen\n)\n\n\n\n\n\nAppends a data buffer of length \nlen\n to the end of an mbuf chain, adjusting packet length if \nom\n is a packet header mbuf. If not enough trailing space exists at the end of the mbuf chain, mbufs are allocated to hold the data.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf\n\n\n\n\n\n\ndata\n\n\nPointer to data buffer to copy from\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to copy from data buffer to the end of the mbuf\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: success\n\n\nOS_ENOMEM\n: Could not allocate enough mbufs to hold data.\n\n\nOS_EINVAL\n: \nom\n was \nNULL\n on entry.\n\n\n\n\nNotes\n\n\nIf not enough mbufs were available the packet header length of the mbuf may get adjusted even though the entire data buffer was not appended to the end of the mbuf.\n\n\n\n\nIf any mbufs are allocated, they are allocated from the same pool as \nom\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n \nuint16_t\n \npktlen\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_data_struct\n \nmy_data\n;\n\n \n/* Get initial packet length */\n\n \npktlen\n \n=\n \nOS_MBUF_PKTLEN\n(\nom\n);\n\n \n/* Append \nmy_data\n to end of mbuf, freeing mbuf if unable to append all the data */\n\n \nrc\n \n=\n \nos_mbuf_append\n(\nom\n, \nmy_data\n, \nsizeof\n(\nstruct\n \nmy_pkt_header\n));\n \nif\n (\nrc\n) {\n \nos_mbuf_free_chain\n(\nom\n);\n }\n \npktlen\n \n+=\n \nsizeof\n(\nstruct\n \nmy_pkt_header\n);\n\n \n/* New packet length should be initial packet length plus length of \nmy_data\n */\n\n \nassert\n(\npktlen\n \n==\n \nOS_MBUF_PKTLEN\n(\nom\n));",
- "title": "os_mbuf_append"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_append/#os_mbuf_append",
- "text": "int os_mbuf_append ( struct os_mbuf *om , const void *data , uint16_t len ) Appends a data buffer of length len to the end of an mbuf chain, adjusting packet length if om is a packet header mbuf. If not enough trailing space exists at the end of the mbuf chain, mbufs are allocated to hold the data.",
- "title": " os_mbuf_append"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_append/#arguments",
- "text": "Arguments Description om Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf data Pointer to data buffer to copy from len Number of bytes to copy from data buffer to the end of the mbuf",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_append/#returned-values",
- "text": "0: success OS_ENOMEM : Could not allocate enough mbufs to hold data. OS_EINVAL : om was NULL on entry.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_append/#notes",
- "text": "If not enough mbufs were available the packet header length of the mbuf may get adjusted even though the entire data buffer was not appended to the end of the mbuf. If any mbufs are allocated, they are allocated from the same pool as om",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_append/#example",
- "text": "int rc ;\n uint16_t pktlen ;\n struct os_mbuf *om ;\n struct my_data_struct my_data ;\n\n /* Get initial packet length */ \n pktlen = OS_MBUF_PKTLEN ( om );\n\n /* Append my_data to end of mbuf, freeing mbuf if unable to append all the data */ \n rc = os_mbuf_append ( om , my_data , sizeof ( struct my_pkt_header ));\n if ( rc ) {\n os_mbuf_free_chain ( om );\n }\n pktlen += sizeof ( struct my_pkt_header );\n\n /* New packet length should be initial packet length plus length of my_data */ \n assert ( pktlen == OS_MBUF_PKTLEN ( om ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_concat/",
- "text": "os_mbuf_concat\n\n\nvoid\n \nos_mbuf_concat\n(\nstruct\n \nos_mbuf\n \n*first\n, \nstruct\n \nos_mbuf\n \n*second\n)\n\n\n\n\n\nAttaches a second mbuf chain onto the end of the first. If the first chain contains a packet header, the header's length is updated. If the second chain has a packet header, its header is cleared.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfirst\n\n\nPointer to first mbuf chain\n\n\n\n\n\n\nsecond\n\n\nPointer to second mbuf chain\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\n\n\nNotes\n\n\nNo data is copied or moved nor are any mbufs freed.\n\n\n\n\nExample\n\n\n \nuint16_t\n \npktlen1\n;\n \nuint16_t\n \npktlen2\n;\n \nstruct\n \nos_mbuf\n \n*pkt1\n;\n \nstruct\n \nos_mbuf\n \n*pkt2\n;\n\n \n/* Get initial packet lengths */\n\n \npktlen1\n \n=\n \nOS_MBUF_PKTLEN\n(\npkt1\n);\n \npktlen2\n \n=\n \nOS_MBUF_PKTLEN\n(\npkt2\n);\n\n \n/* Add pkt2 to end of pkt1 */\n\n \nos_mbuf_concat\n(\npkt1\n, \npkt2\n);\n\n \n/* New packet length should be sum of pkt1 and pkt2 */\n\n \nassert\n((\npktlen1\n \n+\n \npktlen2\n) \n==\n \nOS_MBUF_PKTLEN\n(\npkt1\n));",
- "title": "os_mbuf_concat"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_concat/#os_mbuf_concat",
- "text": "void os_mbuf_concat ( struct os_mbuf *first , struct os_mbuf *second ) Attaches a second mbuf chain onto the end of the first. If the first chain contains a packet header, the header's length is updated. If the second chain has a packet header, its header is cleared.",
- "title": " os_mbuf_concat"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_concat/#arguments",
- "text": "Arguments Description first Pointer to first mbuf chain second Pointer to second mbuf chain",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_concat/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_concat/#notes",
- "text": "No data is copied or moved nor are any mbufs freed.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_concat/#example",
- "text": "uint16_t pktlen1 ;\n uint16_t pktlen2 ;\n struct os_mbuf *pkt1 ;\n struct os_mbuf *pkt2 ;\n\n /* Get initial packet lengths */ \n pktlen1 = OS_MBUF_PKTLEN ( pkt1 );\n pktlen2 = OS_MBUF_PKTLEN ( pkt2 );\n\n /* Add pkt2 to end of pkt1 */ \n os_mbuf_concat ( pkt1 , pkt2 );\n\n /* New packet length should be sum of pkt1 and pkt2 */ \n assert (( pktlen1 + pktlen2 ) == OS_MBUF_PKTLEN ( pkt1 ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copydata/",
- "text": "os_mbuf_copydata\n\n\nint\n \nos_mbuf_copydata\n(\nconst\n \nstruct\n \nos_mbuf\n \n*m\n, \nint\n \noff\n, \nint\n \nlen\n, \nvoid\n \n*dst\n)\n\n\n\n\n\nCopy data from an mbuf chain starting \noff\n bytes from the beginning, continuing for \nlen\n bytes, into the indicated buffer.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nm\n\n\nPointer to mbuf chain\n\n\n\n\n\n\noff\n\n\nStart copy offset, in bytes, from beginning of mbuf chain\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to copy\n\n\n\n\n\n\ndst\n\n\nData buffer to copy into\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: success.\n\n-1: The mbuf does not contain enough data\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_hdr_1\n \nmy_hdr1\n; \n \nstruct\n \nmy_hdr_2\n \nmy_hdr2\n; \n\n \n/* Header 1 and Header 2 are contiguous in packet at start. Retrieve them from the mbuf chain */\n \n \nrc\n \n=\n \nos_mbuf_copydata\n(\nom\n, \n0\n, \nsizeof\n(\nstruct\n \nmy_hdr_1\n), \nmy_hdr1\n);\n \nif\n (\nrc\n) {\n \n/* error! */\n\n \nreturn\n \n-\n1\n;\n }\n\n \nrc\n \n=\n \nos_mbuf_copydata\n(\nom\n, \nsizeof\n(\nstruct\n \nmy_hdr_1\n), \nsizeof\n(\nstruct\n \nmy_hdr_2\n), \nmy_hdr2\n);\n \nif\n (\nrc\n) {\n \n/* error! */\n\n \nreturn\n \n-\n1\n;\n }",
- "title": "os_mbuf_copydata"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copydata/#os_mbuf_copydata",
- "text": "int os_mbuf_copydata ( const struct os_mbuf *m , int off , int len , void *dst ) Copy data from an mbuf chain starting off bytes from the beginning, continuing for len bytes, into the indicated buffer.",
- "title": " os_mbuf_copydata"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copydata/#arguments",
- "text": "Arguments Description m Pointer to mbuf chain off Start copy offset, in bytes, from beginning of mbuf chain len Number of bytes to copy dst Data buffer to copy into",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copydata/#returned-values",
- "text": "0: success. \n-1: The mbuf does not contain enough data",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copydata/#example",
- "text": "int rc ;\n struct os_mbuf *om ;\n struct my_hdr_1 my_hdr1 ; \n struct my_hdr_2 my_hdr2 ; \n\n /* Header 1 and Header 2 are contiguous in packet at start. Retrieve them from the mbuf chain */ \n rc = os_mbuf_copydata ( om , 0 , sizeof ( struct my_hdr_1 ), my_hdr1 );\n if ( rc ) {\n /* error! */ \n return - 1 ;\n }\n\n rc = os_mbuf_copydata ( om , sizeof ( struct my_hdr_1 ), sizeof ( struct my_hdr_2 ), my_hdr2 );\n if ( rc ) {\n /* error! */ \n return - 1 ;\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copyinto/",
- "text": "os_mbuf_copyinto\n\n\nint\n \nos_mbuf_copyinto\n(\nstruct\n \nos_mbuf\n \n*om\n, \nint\n \noff\n, \nconst\n \nvoid\n \n*src\n, \nint\n \nlen\n);\n\n\n\n\n\nCopies the contents of a flat buffer into an mbuf chain, starting at the specified destination offset. If the mbuf is too small for the source data, it is extended as necessary. If the destination mbuf contains a packet header, the header length is updated.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf chain\n\n\n\n\n\n\noff\n\n\nStart copy offset, in bytes, from beginning of mbuf chain\n\n\n\n\n\n\nsrc\n\n\nAddress from which bytes are copied\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to copy from src\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: success.\n\nAll other values indicate an error.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n \nuint16_t\n \npktlen\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_data_struct\n \nmy_data\n; \n\n \n/* Get initial packet length */\n\n \npktlen\n \n=\n \nOS_MBUF_PKTLEN\n(\nom\n);\n\n \n/* Copy \nmy_data\n into mbuf */\n\n \nrc\n \n=\n \nos_mbuf_copyinto\n(\nom\n, \n0\n, \nmy_data\n, \nsizeof\n(\nstruct\n \nmy_data_struct\n));\n \nif\n (\nrc\n) {\n \nos_mbuf_free_chain\n(\nom\n);\n \nreturn\n;\n }\n\n \n/* Packet length should have increased by size of \nmy_data\n */\n\n \npktlen\n \n+=\n \nsizeof\n(\nstruct\n \nmy_data_struct\n);\n \nassert\n(\npktlen\n \n==\n \nOS_MBUF_PKTLEN\n(\nom\n));",
- "title": "os_mbuf_copyinto"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copyinto/#os_mbuf_copyinto",
- "text": "int os_mbuf_copyinto ( struct os_mbuf *om , int off , const void *src , int len ); Copies the contents of a flat buffer into an mbuf chain, starting at the specified destination offset. If the mbuf is too small for the source data, it is extended as necessary. If the destination mbuf contains a packet header, the header length is updated.",
- "title": " os_mbuf_copyinto"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copyinto/#arguments",
- "text": "Arguments Description om Pointer to mbuf chain off Start copy offset, in bytes, from beginning of mbuf chain src Address from which bytes are copied len Number of bytes to copy from src",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copyinto/#returned-values",
- "text": "0: success. \nAll other values indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_copyinto/#example",
- "text": "int rc ;\n uint16_t pktlen ;\n struct os_mbuf *om ;\n struct my_data_struct my_data ; \n\n /* Get initial packet length */ \n pktlen = OS_MBUF_PKTLEN ( om );\n\n /* Copy my_data into mbuf */ \n rc = os_mbuf_copyinto ( om , 0 , my_data , sizeof ( struct my_data_struct ));\n if ( rc ) {\n os_mbuf_free_chain ( om );\n return ;\n }\n\n /* Packet length should have increased by size of my_data */ \n pktlen += sizeof ( struct my_data_struct );\n assert ( pktlen == OS_MBUF_PKTLEN ( om ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_dup/",
- "text": "os_mbuf_dup\n\n\nstruct\n \nos_mbuf\n \n*os_mbuf_dup\n(\nstruct\n \nos_mbuf\n \n*om\n)\n\n\n\n\n\nDuplicate a chain of mbufs. Return the start of the duplicated chain.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf chain to duplicate\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nPointer to the duplicated chain or \nNULL\n if not enough mbufs were available to duplicate the chain.\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nos_mbuf\n \n*new_om\n;\n\n \n/* Make a copy of om, returning -1 if not able to duplicate om */\n\n \nnew_om\n \n=\n \nos_mbuf_dup\n(\nom\n);\n \nif\n (\n!new_om\n) {\n \nreturn\n \n-\n1\n;\n }",
- "title": "os_mbuf_dup"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_dup/#os_mbuf_dup",
- "text": "struct os_mbuf *os_mbuf_dup ( struct os_mbuf *om ) Duplicate a chain of mbufs. Return the start of the duplicated chain.",
- "title": " os_mbuf_dup"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_dup/#arguments",
- "text": "Arguments Description om Pointer to mbuf chain to duplicate",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_dup/#returned-values",
- "text": "Pointer to the duplicated chain or NULL if not enough mbufs were available to duplicate the chain.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_dup/#example",
- "text": "struct os_mbuf *om ;\n struct os_mbuf *new_om ;\n\n /* Make a copy of om, returning -1 if not able to duplicate om */ \n new_om = os_mbuf_dup ( om );\n if ( !new_om ) {\n return - 1 ;\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_extend/",
- "text": "os_mbuf_extend\n\n\nvoid\n \n*os_mbuf_extend\n(\nstruct\n \nos_mbuf\n \n*om\n, \nuint16_t\n \nlen\n);\n\n\n\n\n\nIncreases the length of an mbuf chain by the specified amount. If there is not sufficient room in the last buffer, a new buffer is allocated and appended to the chain. It is an error to request more data than can fit in a single buffer.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf chain\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to increase packet header\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nPointer to start of extended data. Caller is guaranteed that there are at least \nlen\n bytes from this pointer to the end of the mbuf.\n\n\nReturns \nNULL\n if extension fails due to insufficient mbufs or \nlen\n too large.\n\n\n\nExample\n\n\n \nuint8_t\n \n*dptr\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_data_struct\n \nmy_data\n; \n\n \n/* Obtain enough room to add \nmy_data\n to an mbuf chain */\n\n \ndptr\n \n=\n \nos_mbuf_extend\n(\nom\n, \nsizeof\n(\nstruct\n \nmy_data_struct\n));\n \nif\n (\ndptr\n) {\n \nmemcpy\n(\ndptr\n, \nmy_data\n, \nsizeof\n(\nstruct\n \nmy_data_struct\n));\n }",
- "title": "os_mbuf_extend"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_extend/#os_mbuf_extend",
- "text": "void *os_mbuf_extend ( struct os_mbuf *om , uint16_t len ); Increases the length of an mbuf chain by the specified amount. If there is not sufficient room in the last buffer, a new buffer is allocated and appended to the chain. It is an error to request more data than can fit in a single buffer.",
- "title": " os_mbuf_extend"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_extend/#arguments",
- "text": "Arguments Description om Pointer to mbuf chain len Number of bytes to increase packet header",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_extend/#returned-values",
- "text": "Pointer to start of extended data. Caller is guaranteed that there are at least len bytes from this pointer to the end of the mbuf. Returns NULL if extension fails due to insufficient mbufs or len too large.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_extend/#example",
- "text": "uint8_t *dptr ;\n struct os_mbuf *om ;\n struct my_data_struct my_data ; \n\n /* Obtain enough room to add my_data to an mbuf chain */ \n dptr = os_mbuf_extend ( om , sizeof ( struct my_data_struct ));\n if ( dptr ) {\n memcpy ( dptr , my_data , sizeof ( struct my_data_struct ));\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_free_chain/",
- "text": "os_mbuf_free_chain\n\n\nint\n \nos_mbuf_free_chain\n(\nstruct\n \nos_mbuf\n \n*om\n);\n\n\n\n\n\nFrees a chain of mbufs\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf chain\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: success\n\nAny other value indicates error\n\n\n\n\nNotes\n\n\nNote that for each mbuf in the chain, \nos_mbuf_free()\n is called.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/* Free mbuf chain */\n\n \nrc\n \n=\n \nos_mbuf_free_chain\n(\nom\n);\n \nassert\n(\nrc\n \n==\n \n0\n);",
- "title": "os_mbuf_free_chain"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_free_chain/#os_mbuf_free_chain",
- "text": "int os_mbuf_free_chain ( struct os_mbuf *om ); Frees a chain of mbufs",
- "title": " os_mbuf_free_chain"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_free_chain/#arguments",
- "text": "Arguments Description om Pointer to mbuf chain",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_free_chain/#returned-values",
- "text": "0: success \nAny other value indicates error",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_free_chain/#notes",
- "text": "Note that for each mbuf in the chain, os_mbuf_free() is called.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_free_chain/#example",
- "text": "int rc ;\n struct os_mbuf *om ;\n\n /* Free mbuf chain */ \n rc = os_mbuf_free_chain ( om );\n assert ( rc == 0 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get/",
- "text": "os_mbuf_get\n\n\nstruct\n \nos_mbuf\n \n*os_mbuf_get\n(\nstruct\n \nos_mbuf_pool\n \n*omp\n, \nuint16_t\n \nleadingspace\n)\n\n\n\n\n\nGet an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to being returned. The \neadingspace\n parameter allows the user to specify the amount of leading space in the allocated mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf pool from which to allocate mbuf\n\n\n\n\n\n\nleadingspace\n\n\nAmount of leading space in allocated mbuf. Request cannot exceed the mbuf data buffer size.\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns a pointer to the allocated mbuf or \nNULL\n if there are no mbufs available or \nleadingspace\n was too large.\n\n\n\nNotes\n\n\nIn most typical applications, the application developer does not need to call \nos_mbuf_get()\n; the other API will do this automatically. However, this API is provided for convenience as mbufs can also be a simple way to allocate temporary chunks of memory.\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/* Get an mbuf */\n\n \nom\n \n=\n \nos_mbuf_get\n(\ng_mbuf_pool\n, \n0\n);\n \nif\n (\nom\n) {\n \n/* we have allocated an mbuf from the pool */\n\n }",
- "title": "os_mbuf_get"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get/#os_mbuf_get",
- "text": "struct os_mbuf *os_mbuf_get ( struct os_mbuf_pool *omp , uint16_t leadingspace ) Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to being returned. The eadingspace parameter allows the user to specify the amount of leading space in the allocated mbuf.",
- "title": "os_mbuf_get"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get/#arguments",
- "text": "Arguments Description om Pointer to mbuf pool from which to allocate mbuf leadingspace Amount of leading space in allocated mbuf. Request cannot exceed the mbuf data buffer size.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get/#returned-values",
- "text": "Returns a pointer to the allocated mbuf or NULL if there are no mbufs available or leadingspace was too large.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get/#notes",
- "text": "In most typical applications, the application developer does not need to call os_mbuf_get() ; the other API will do this automatically. However, this API is provided for convenience as mbufs can also be a simple way to allocate temporary chunks of memory.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get/#example",
- "text": "struct os_mbuf *om ;\n\n /* Get an mbuf */ \n om = os_mbuf_get ( g_mbuf_pool , 0 );\n if ( om ) {\n /* we have allocated an mbuf from the pool */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get_pkthdr/",
- "text": "os_mbuf_get_pkthdr\n\n\nstruct\n \nos_mbuf\n \n*os_mbuf_get_pkthdr\n(\nstruct\n \nos_mbuf_pool\n \n*omp\n, \nuint8_t\n \npkthdr_len\n);\n\n\n\n\n\nAllocates a packet header mbuf from the mbuf pool pointed to by \nomp\n. Adds a user header of length \npkthdr_len\n to packet header mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf pool from which to allocate mbuf\n\n\n\n\n\n\npkthdr_len\n\n\nThe user header packet length to allocate for the packet header mbuf\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns a pointer to the allocated mbuf or \nNULL\n if there are no mbufs available or the user packet header was too large.\n\n\n\n\nNotes\n\n\nThe packet header mbuf returned will have its data pointer incremented by the \nsizeof(struct os_mbuf_pkthdr)\n as well as the amount of user header data (i.e. \npkthdr_len\n). In other words, the data pointer is offset from the start of the mbuf by: \nsizeof(struct os_mbuf)\n + \nsizeof(struct os_mbuf_pkthdr)\n + \npkthdr_len\n. The \nom_pkthdr_len\n element in the allocated mbuf is set to: \nsizeof(struct os_mbuf_pkthdr)\n + \npkthdr_len\n.\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_user_header\n \nmy_hdr\n;\n\n \n/* Get a packet header mbuf with a user header in it */\n\n \nom\n \n=\n \nos_mbuf_get_pkthdr\n(\ng_mbuf_pool\n, \nsizeof\n(\nstruct\n \nmy_user_header\n));\n \nif\n (\nom\n) {\n \n/* Packet header mbuf was allocated */\n\n }",
- "title": "os_mbuf_get_pkthdr"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get_pkthdr/#os_mbuf_get_pkthdr",
- "text": "struct os_mbuf *os_mbuf_get_pkthdr ( struct os_mbuf_pool *omp , uint8_t pkthdr_len ); Allocates a packet header mbuf from the mbuf pool pointed to by omp . Adds a user header of length pkthdr_len to packet header mbuf.",
- "title": "os_mbuf_get_pkthdr"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get_pkthdr/#arguments",
- "text": "Arguments Description om Pointer to mbuf pool from which to allocate mbuf pkthdr_len The user header packet length to allocate for the packet header mbuf",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get_pkthdr/#returned-values",
- "text": "Returns a pointer to the allocated mbuf or NULL if there are no mbufs available or the user packet header was too large.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get_pkthdr/#notes",
- "text": "The packet header mbuf returned will have its data pointer incremented by the sizeof(struct os_mbuf_pkthdr) as well as the amount of user header data (i.e. pkthdr_len ). In other words, the data pointer is offset from the start of the mbuf by: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + pkthdr_len . The om_pkthdr_len element in the allocated mbuf is set to: sizeof(struct os_mbuf_pkthdr) + pkthdr_len .",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_get_pkthdr/#example",
- "text": "struct os_mbuf *om ;\n struct my_user_header my_hdr ;\n\n /* Get a packet header mbuf with a user header in it */ \n om = os_mbuf_get_pkthdr ( g_mbuf_pool , sizeof ( struct my_user_header ));\n if ( om ) {\n /* Packet header mbuf was allocated */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_memcmp/",
- "text": "os_mbuf_memcmp\n\n\nint\n \nos_mbuf_memcmp\n(\nconst\n \nstruct\n \nos_mbuf\n \n*om\n, \nint\n \noff\n, \nconst\n \nvoid\n \n*data\n, \nint\n \nlen\n)\n\n\n\n\n\nPerforms a memory compare of the specified region of an mbuf chain against a flat buffer.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf\n\n\n\n\n\n\noff\n\n\nOffset, in bytes, from start of mbuf to start of comparison\n\n\n\n\n\n\ndata\n\n\nPointer to flat data buffer to compare\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to compare\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nA value of zero means the memory regions are identical; all other values represent either an error or a value returned from memcmp. \n\n\n\n\nNotes\n\n\nThis function will compare bytes starting from \noff\n bytes from the start of the mbuf chain with a data buffer.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nuint8_t\n \nmy_data_buffer\n[\n32\n];\n\n \n/* Get a packet header mbuf with a user header in it */\n\n \nrc\n \n=\n \nos_mbuf_memcmp\n(\nom\n, \n0\n, \nmy_data_buffer\n, \n32\n);\n \nif\n (\n!rc\n) {\n \n/* \nmy_data_buffer\n and the data from offset 0 in the mbuf chain are identical! */\n\n }",
- "title": "os_mbuf_memcmp"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_memcmp/#os_mbuf_memcmp",
- "text": "int os_mbuf_memcmp ( const struct os_mbuf *om , int off , const void *data , int len ) Performs a memory compare of the specified region of an mbuf chain against a flat buffer.",
- "title": "os_mbuf_memcmp"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_memcmp/#arguments",
- "text": "Arguments Description om Pointer to mbuf off Offset, in bytes, from start of mbuf to start of comparison data Pointer to flat data buffer to compare len Number of bytes to compare",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_memcmp/#returned-values",
- "text": "A value of zero means the memory regions are identical; all other values represent either an error or a value returned from memcmp.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_memcmp/#notes",
- "text": "This function will compare bytes starting from off bytes from the start of the mbuf chain with a data buffer.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_memcmp/#example",
- "text": "int rc ;\n struct os_mbuf *om ;\n uint8_t my_data_buffer [ 32 ];\n\n /* Get a packet header mbuf with a user header in it */ \n rc = os_mbuf_memcmp ( om , 0 , my_data_buffer , 32 );\n if ( !rc ) {\n /* my_data_buffer and the data from offset 0 in the mbuf chain are identical! */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_off/",
- "text": "os_mbuf_off\n\n\nstruct\n \nos_mbuf\n \n*os_mbuf_off\n(\nstruct\n \nos_mbuf\n \n*om\n, \nint\n \noff\n, \nint\n \n*out_off\n)\n\n\n\n\n\nGiven an offset in the packet (i.e. user data byte offset in the mbuf chain), return the mbuf and the offset in that mbuf where byte 'off' is located. Note that the offset is \nreturned\n in \nout_off\n.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf\n\n\n\n\n\n\noff\n\n\nLocation in mbuf chain of desired byte offset\n\n\n\n\n\n\nout_off\n\n\nPointer to storage for the relative offset of the absolute location in the returned mbuf\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nNULL\n if the offset is not within the mbuf chain or \nom\n points to \nNULL\n.\n\n\n\n\nNotes\n\n\nThe user is allowed to call this function with the length of the mbuf chain but no greater. This allows the user to get the mbuf and offset (in that mbuf) where the next user data byte should be written.\n\n\nWhile this api is provided to the user, other APIs are expected to be used by the applciation developer (i.e. \nos_mbuf_append()\n or \nos_mbuf_copyinto()\n).\n\n\n\nExample\n\n\n \nint\n \nrelative_offset\n;\n \nuint16_t\n \npktlen\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nos_mbuf\n \n*tmp\n;\n\n \n/* Append a new line character to end of mbuf data */\n\n \npktlen\n \n=\n \nOS_MBUF_PKTLEN\n(\nom\n);\n\n \nrelative_offset\n \n=\n \n0\n;\n \ntmp\n \n=\n \nos_mbuf_off\n(\nom\n, \npktlen\n, \nrelative_offset\n);\n \nif\n (\ntmp\n) {\n \n/* Offset found. */\n\n \ntmp-\nom_data\n[\nrelative_offset\n] \n=\n \n\\n\n;\n } \nelse\n {\n \n/*\n\n\n * This mbuf does not contain enough bytes so this is an invalid offset.\n\n\n * In other words, the mbuf is less than 62 bytes in length.\n\n\n */\n\n }",
- "title": "os_mbuf_off"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_off/#os_mbuf_off",
- "text": "struct os_mbuf *os_mbuf_off ( struct os_mbuf *om , int off , int *out_off ) Given an offset in the packet (i.e. user data byte offset in the mbuf chain), return the mbuf and the offset in that mbuf where byte 'off' is located. Note that the offset is returned in out_off .",
- "title": "os_mbuf_off"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_off/#arguments",
- "text": "Arguments Description om Pointer to mbuf off Location in mbuf chain of desired byte offset out_off Pointer to storage for the relative offset of the absolute location in the returned mbuf",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_off/#returned-values",
- "text": "NULL if the offset is not within the mbuf chain or om points to NULL .",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_off/#notes",
- "text": "The user is allowed to call this function with the length of the mbuf chain but no greater. This allows the user to get the mbuf and offset (in that mbuf) where the next user data byte should be written. While this api is provided to the user, other APIs are expected to be used by the applciation developer (i.e. os_mbuf_append() or os_mbuf_copyinto() ).",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_off/#example",
- "text": "int relative_offset ;\n uint16_t pktlen ;\n struct os_mbuf *om ;\n struct os_mbuf *tmp ;\n\n /* Append a new line character to end of mbuf data */ \n pktlen = OS_MBUF_PKTLEN ( om );\n\n relative_offset = 0 ;\n tmp = os_mbuf_off ( om , pktlen , relative_offset );\n if ( tmp ) {\n /* Offset found. */ \n tmp- om_data [ relative_offset ] = \\n ;\n } else {\n /* * This mbuf does not contain enough bytes so this is an invalid offset. * In other words, the mbuf is less than 62 bytes in length. */ \n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pool_init/",
- "text": "os_mbuf_pool_init\n\n\nint\n \nos_mbuf_pool_init\n(\nstruct\n \nos_mbuf_pool\n \n*omp\n, \nstruct\n \nos_mempool\n \n*mp\n, \nuint16_t\n \nbuf_len\n, \n \nuint16_t\n \nnbufs\n)\n\n\n\n\n\nInitialize an mbuf pool\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nomp\n\n\nPointer to mbuf pool to initialize\n\n\n\n\n\n\nmp\n\n\nPointer to memory pool used by mbuf pool\n\n\n\n\n\n\nbuf_len\n\n\nThe size of the memory blocks in the memory pool used by the mbuf pool\n\n\n\n\n\n\nnbufs\n\n\nThe number of mbufs in the pool\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success; all other values indicate an error.\n\n\n\n\nNotes\n\n\nThe parameter \nbuf_len\n is the total size of the memory block. This must accommodate the \nos_mbuf\n structure, the \nos_mbuf_pkthdr\n structure, any user headers plus the desired amount of user data.\n\n\n\n\nExample\n\n\n#define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr)\n\n\n#define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD\n\n\n\n#define MBUF_NUM_MBUFS (32)\n\n\n#define MBUF_PAYLOAD_SIZE (64)\n\n\n#define MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4)\n\n\n#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD)\n\n\n#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE)\n\n\n\nstruct\n \nos_mbuf_pool\n \ng_mbuf_pool\n; \n\nstruct\n \nos_mempool\n \ng_mbuf_mempool\n;\n\nos_membuf_t\n \ng_mbuf_buffer\n[\nMBUF_MEMPOOL_SIZE\n];\n\n\nvoid\n\n\ncreate_mbuf_pool\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n, \n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n, \n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n}",
- "title": "os_mbuf_pool_init"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pool_init/#os_mbuf_pool_init",
- "text": "int os_mbuf_pool_init ( struct os_mbuf_pool *omp , struct os_mempool *mp , uint16_t buf_len , \n uint16_t nbufs ) Initialize an mbuf pool",
- "title": "os_mbuf_pool_init"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pool_init/#arguments",
- "text": "Arguments Description omp Pointer to mbuf pool to initialize mp Pointer to memory pool used by mbuf pool buf_len The size of the memory blocks in the memory pool used by the mbuf pool nbufs The number of mbufs in the pool",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pool_init/#returned-values",
- "text": "0 on success; all other values indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pool_init/#notes",
- "text": "The parameter buf_len is the total size of the memory block. This must accommodate the os_mbuf structure, the os_mbuf_pkthdr structure, any user headers plus the desired amount of user data.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pool_init/#example",
- "text": "#define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr) #define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD #define MBUF_NUM_MBUFS (32) #define MBUF_PAYLOAD_SIZE (64) #define MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4) #define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD) #define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE) struct os_mbuf_pool g_mbuf_pool ; struct os_mempool g_mbuf_mempool ; os_membuf_t g_mbuf_buffer [ MBUF_MEMPOOL_SIZE ]; void create_mbuf_pool ( void )\n{\n int rc ;\n\n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS , \n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE , \n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_prepend/",
- "text": "os_mbuf_prepend\n\n\nstruct\n \nos_mbuf\n \n*os_mbuf_prepend\n(\nstruct\n \nos_mbuf\n \n*om\n, \nint\n \nlen\n)\n\n\n\n\n\nIncreases the length of an mbuf chain by adding data to the front. If there is insufficient room in the leading mbuf, additional mbufs are allocated and prepended as necessary. If this function fails to allocate an mbuf, the entire chain is freed.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf\n\n\n\n\n\n\nlen\n\n\nLength, in bytes, to prepend\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nPointer to mbuf at head of chain; \nNULL\n if not enough mbufs were available to accommodate \nlen\n.\n\n\n\n\nNotes\n\n\nIf \nom\n is a packet header mbuf, the total length of the packet is adjusted by \nlen\n. Note that the returned mbuf may not point to \nom\n if insufficient leading space was available in \nom\n.\n\n\n\n\nExample\n\n\n \nuint16_t\n \npktlen\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nos_mbuf\n \n*tmp\n;\n\n \n/* Get initial packet length before prepend */\n\n \npktlen\n \n=\n \nOS_MBUF_PKTLEN\n(\nom\n);\n\n \ntmp\n \n=\n \nos_mbuf_prepend\n(\nom\n, \n32\n);\n \nif\n (\n!tmp\n) {\n \n/* Not able to prepend. The chain pointed to by *om has been freed */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* The packet length should equal the original length plus what we prepended */\n\n \nassert\n((\npktlen\n \n+\n \n32\n) \n==\n \nOS_MBUF_PKTLEN\n(\ntmp\n));",
- "title": "os_mbuf_prepend"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_prepend/#os_mbuf_prepend",
- "text": "struct os_mbuf *os_mbuf_prepend ( struct os_mbuf *om , int len ) Increases the length of an mbuf chain by adding data to the front. If there is insufficient room in the leading mbuf, additional mbufs are allocated and prepended as necessary. If this function fails to allocate an mbuf, the entire chain is freed.",
- "title": "os_mbuf_prepend"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_prepend/#arguments",
- "text": "Arguments Description om Pointer to mbuf len Length, in bytes, to prepend",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_prepend/#returned-values",
- "text": "Pointer to mbuf at head of chain; NULL if not enough mbufs were available to accommodate len .",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_prepend/#notes",
- "text": "If om is a packet header mbuf, the total length of the packet is adjusted by len . Note that the returned mbuf may not point to om if insufficient leading space was available in om .",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_prepend/#example",
- "text": "uint16_t pktlen ;\n struct os_mbuf *om ;\n struct os_mbuf *tmp ;\n\n /* Get initial packet length before prepend */ \n pktlen = OS_MBUF_PKTLEN ( om );\n\n tmp = os_mbuf_prepend ( om , 32 );\n if ( !tmp ) {\n /* Not able to prepend. The chain pointed to by *om has been freed */ \n return - 1 ;\n }\n\n /* The packet length should equal the original length plus what we prepended */ \n assert (( pktlen + 32 ) == OS_MBUF_PKTLEN ( tmp ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pullup/",
- "text": "os_mbuf_pullup\n\n\nstruct\n \nos_mbuf\n \n*os_mbuf_pullup\n(\nstruct\n \nos_mbuf\n \n*om\n, \nuint16_t\n \nlen\n)\n\n\n\n\n\nRearrange an mbuf chain so that len bytes are contiguous, and in the data area of an mbuf (so that \nOS_MBUF_DATA()\n will work on a structure of size \nlen\n.) Returns the resulting mbuf chain on success, free's it and returns \nNULL\n on failure.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nPointer to mbuf\n\n\n\n\n\n\nlen\n\n\nLength, in bytes, to pullup (make contiguous in mbuf)\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nPointer to mbuf at head of chain; \nNULL\n if not enough mbufs were available to accommodate \nlen\n or if the requested pullup size was too large.\n\n\n\n\nNotes\n\n\nHopefully it is apparent to the user that you cannot pullup more bytes than the mbuf can accommodate. Pullup does not allocate more than one mbuf; the entire pullup length must be contained within a single mbuf.\n\n\nThe mbuf that is being pulled up into does not need to be a packet header mbuf; it can be a normal mbuf. The user should note that the maximum pullup length does depend on the type of mbuf being pulled up into (a packet header or normal mbuf).\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nos_mbuf\n \n*tmp\n;\n \nstruct\n \nmy_header_struct\n \nmy_header\n;\n\n \n/* Make sure \nmy_header\n is contiguous in the mbuf */\n\n \ntmp\n \n=\n \nos_mbuf_pullup\n(\nom\n, \nsizeof\n(\nmy_header_struct\n));\n \nif\n (\n!tmp\n) {\n \n/* Pullup failed. The chain pointed to by *om has been freed */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* copy data from mbuf into header structure */\n\n \nmemcpy\n(\nmy_header\n, \ntmp-\nom_data\n, \nsizeof\n(\nstruct\n \nmy_header_struct\n));",
- "title": "os_mbuf_pullup"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pullup/#os_mbuf_pullup",
- "text": "struct os_mbuf *os_mbuf_pullup ( struct os_mbuf *om , uint16_t len ) Rearrange an mbuf chain so that len bytes are contiguous, and in the data area of an mbuf (so that OS_MBUF_DATA() will work on a structure of size len .) Returns the resulting mbuf chain on success, free's it and returns NULL on failure.",
- "title": "os_mbuf_pullup"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pullup/#arguments",
- "text": "Arguments Description om Pointer to mbuf len Length, in bytes, to pullup (make contiguous in mbuf)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pullup/#returned-values",
- "text": "Pointer to mbuf at head of chain; NULL if not enough mbufs were available to accommodate len or if the requested pullup size was too large.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pullup/#notes",
- "text": "Hopefully it is apparent to the user that you cannot pullup more bytes than the mbuf can accommodate. Pullup does not allocate more than one mbuf; the entire pullup length must be contained within a single mbuf. The mbuf that is being pulled up into does not need to be a packet header mbuf; it can be a normal mbuf. The user should note that the maximum pullup length does depend on the type of mbuf being pulled up into (a packet header or normal mbuf).",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/mbuf/os_mbuf_pullup/#example",
- "text": "struct os_mbuf *om ;\n struct os_mbuf *tmp ;\n struct my_header_struct my_header ;\n\n /* Make sure my_header is contiguous in the mbuf */ \n tmp = os_mbuf_pullup ( om , sizeof ( my_header_struct ));\n if ( !tmp ) {\n /* Pullup failed. The chain pointed to by *om has been freed */ \n return - 1 ;\n }\n\n /* copy data from mbuf into header structure */ \n memcpy ( my_header , tmp- om_data , sizeof ( struct my_header_struct ));",
- "title": "Example"
- },
- {
- "location": "/os/core_os/msys/msys/",
- "text": "Msys\n\n\nMsys stands for \"system mbufs\" and is a set of APIs built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size. \n\n\nLet us walk through an example where the user registers three mbuf pools with msys: one with 32 byte mbufs, one with 256 and one with 2048. If the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used. If the request is for 33 bytes the 256 byte mbuf pool is used. If an mbuf data size is requested that is larger than any of the pools (say, 4000 bytes) the largest pool is used. While this behaviour may not be optimal in all cases that is the currently implemented behaviour. All this means is that the user is not guaranteed that a single mbuf can hold the requested data.\n\n\nThe msys code will not allocate an mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementations the current code will simply return \nNULL\n. Using the above example, say the user requests 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate an mbuf from that pool. If that pool is empty, \nNULL\n is returned even though the 32 and 2048 byte pools are not empty.\n\n\nNote that no added descriptions on how to use the msys API are presented here (other than in the API descriptions themselves) as the msys API is used in exactly the same manner as the mbuf API. The only difference is that mbuf pools are added to msys by calling \nos_msys_register().\n\n\n \n\n\nList of Functions\n\n\nThe functions available in msys are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_msys_get\n\n\nRetrieve an mbuf from the system mbuf pools with the given number of bytes available in the mbuf.\n\n\n\n\n\n\nos_msys_get_pkthdr\n\n\nRetrieve a packet header mbuf from the system mbuf pools with the given number of bytes available for the user header in the mbuf.\n\n\n\n\n\n\nos_msys_register\n\n\nRegister an mbuf pool for use as a system mbuf pool.\n\n\n\n\n\n\nos_msys_reset\n\n\nResets msys module.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/msys/msys/#msys",
- "text": "Msys stands for \"system mbufs\" and is a set of APIs built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size. Let us walk through an example where the user registers three mbuf pools with msys: one with 32 byte mbufs, one with 256 and one with 2048. If the user requests an mbuf with 10 bytes, the 32-byte mbuf pool is used. If the request is for 33 bytes the 256 byte mbuf pool is used. If an mbuf data size is requested that is larger than any of the pools (say, 4000 bytes) the largest pool is used. While this behaviour may not be optimal in all cases that is the currently implemented behaviour. All this means is that the user is not guaranteed that a single mbuf can hold the requested data. The msys code will not allocate an mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementations the current code will simply return NULL . Using the above example, say the user requests 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate an mbuf from that pool. If that pool is empty, NULL is returned even though the 32 and 2048 byte pools are not empty. Note that no added descriptions on how to use the msys API are presented here (other than in the API descriptions themselves) as the msys API is used in exactly the same manner as the mbuf API. The only difference is that mbuf pools are added to msys by calling os_msys_register().",
- "title": "Msys"
- },
- {
- "location": "/os/core_os/msys/msys/#list-of-functions",
- "text": "The functions available in msys are: Function Description os_msys_get Retrieve an mbuf from the system mbuf pools with the given number of bytes available in the mbuf. os_msys_get_pkthdr Retrieve a packet header mbuf from the system mbuf pools with the given number of bytes available for the user header in the mbuf. os_msys_register Register an mbuf pool for use as a system mbuf pool. os_msys_reset Resets msys module.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/msys/os_msys_get/",
- "text": "os_msys_get\n\n\nstruct\n \nos_mbuf\n \n*os_msys_get\n(\nuint16_t\n \ndsize\n, \nuint16_t\n \nleadingspace\n)\n\n\n\n\n\nRetrieve an mbuf from the system mbuf pools with \nleadingspace\n bytes available in the mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndsize\n\n\nMinimum requested size of mbuf. Actual mbuf allocated may not accommodate \ndsize\n\n\n\n\n\n\nleadingspace\n\n\nNumber of bytes for leading space in mbuf (space at start of mbuf)\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nPointer to mbuf or \nNULL\n if no mbufs were available.\n\n\n\n\nNotes\n\n\nAs described in the overview section, \nos_msys_get()\n may return an mbuf that is smaller than \ndsize\n, meaning that the mbuf user data buffer does not have enough contiguous space to hold \ndsize\n bytes.\n\n\nThis API will not return an mbuf from a larger mbuf pool if the appropriate msys mbuf pool is empty. See the overview for more information.\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/* Allocate an mbuf with hopefully at least 100 bytes in its user data buffer */\n\n \nom\n \n=\n \nos_msys_get\n(\n100\n, \n0\n);\n \nif\n (\n!om\n) {\n \n/* No mbufs available. */\n\n \nreturn\n \n-\n1\n;\n }\n}",
- "title": "os_msys_get"
- },
- {
- "location": "/os/core_os/msys/os_msys_get/#os_msys_get",
- "text": "struct os_mbuf *os_msys_get ( uint16_t dsize , uint16_t leadingspace ) Retrieve an mbuf from the system mbuf pools with leadingspace bytes available in the mbuf.",
- "title": "os_msys_get"
- },
- {
- "location": "/os/core_os/msys/os_msys_get/#arguments",
- "text": "Arguments Description dsize Minimum requested size of mbuf. Actual mbuf allocated may not accommodate dsize leadingspace Number of bytes for leading space in mbuf (space at start of mbuf)",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/msys/os_msys_get/#returned-values",
- "text": "Pointer to mbuf or NULL if no mbufs were available.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/msys/os_msys_get/#notes",
- "text": "As described in the overview section, os_msys_get() may return an mbuf that is smaller than dsize , meaning that the mbuf user data buffer does not have enough contiguous space to hold dsize bytes. This API will not return an mbuf from a larger mbuf pool if the appropriate msys mbuf pool is empty. See the overview for more information.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/msys/os_msys_get/#example",
- "text": "struct os_mbuf *om ;\n\n /* Allocate an mbuf with hopefully at least 100 bytes in its user data buffer */ \n om = os_msys_get ( 100 , 0 );\n if ( !om ) {\n /* No mbufs available. */ \n return - 1 ;\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/msys/os_msys_get_pkthdr/",
- "text": "os_msys_get_pkthdr\n\n\nstruct\n \nos_mbuf\n \n*os_msys_get_pkthdr\n(\nuint16_t\n \ndsize\n, \nuint16_t\n \nuser_hdr_len\n)\n\n\n\n\n\nRetrieve a packet header mbuf from the system mbuf pools with \nuser_hdr_len\n bytes available for the user header in the mbuf.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndsize\n\n\nMinimum requested size of mbuf. Actual mbuf allocated may not accommodate \ndsize\n\n\n\n\n\n\nuser_hdr_len\n\n\nSize, in of bytes, of user header in the mbuf\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nPointer to mbuf or \nNULL\n if no mbufs were available.\n\n\n\n\nNotes\n\n\nThe same notes apply to this API as to \nos_msys_get()\n.\n\n\n\n\nExample\n\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n \nstruct\n \nmy_user_hdr_struct\n \nmy_usr_hdr\n;\n\n \n/*\n\n\n * Allocate an mbuf with hopefully at least 100 bytes in its user data buffer\n\n\n * and that has a user header of size sizeof(struct my_user_hdr_struct)\n\n\n */\n\n \nom\n \n=\n \nos_msys_get_pkthdr\n(\n100\n, \nsizeof\n(\nstruct\n \nmy_user_hdr_struct\n));\n \nif\n (\n!om\n) {\n \n/* No mbufs available. */\n\n \nreturn\n \n-\n1\n;\n }\n}",
- "title": "os_msys_get_pkthdr"
- },
- {
- "location": "/os/core_os/msys/os_msys_get_pkthdr/#os_msys_get_pkthdr",
- "text": "struct os_mbuf *os_msys_get_pkthdr ( uint16_t dsize , uint16_t user_hdr_len ) Retrieve a packet header mbuf from the system mbuf pools with user_hdr_len bytes available for the user header in the mbuf.",
- "title": "os_msys_get_pkthdr"
- },
- {
- "location": "/os/core_os/msys/os_msys_get_pkthdr/#arguments",
- "text": "Arguments Description dsize Minimum requested size of mbuf. Actual mbuf allocated may not accommodate dsize user_hdr_len Size, in of bytes, of user header in the mbuf",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/msys/os_msys_get_pkthdr/#returned-values",
- "text": "Pointer to mbuf or NULL if no mbufs were available.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/msys/os_msys_get_pkthdr/#notes",
- "text": "The same notes apply to this API as to os_msys_get() .",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/msys/os_msys_get_pkthdr/#example",
- "text": "struct os_mbuf *om ;\n struct my_user_hdr_struct my_usr_hdr ;\n\n /* * Allocate an mbuf with hopefully at least 100 bytes in its user data buffer * and that has a user header of size sizeof(struct my_user_hdr_struct) */ \n om = os_msys_get_pkthdr ( 100 , sizeof ( struct my_user_hdr_struct ));\n if ( !om ) {\n /* No mbufs available. */ \n return - 1 ;\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/msys/os_msys_register/",
- "text": "os_msys_register\n\n\nint\n \nos_msys_register\n(\nstruct\n \nos_mbuf_pool\n \n*new_pool\n) \n\n\n\n\n\nRegister an mbuf pool for use as a system mbuf pool. The pool should be initialized prior to registration.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnew_pool\n\n\nPointer to mbuf pool to add to system mbuf pools\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success; all other values indicate an error.\n\n\n\n\nExample\n\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);",
- "title": "os_msys_register"
- },
- {
- "location": "/os/core_os/msys/os_msys_register/#os_msys_register",
- "text": "int os_msys_register ( struct os_mbuf_pool *new_pool ) Register an mbuf pool for use as a system mbuf pool. The pool should be initialized prior to registration.",
- "title": "os_msys_register"
- },
- {
- "location": "/os/core_os/msys/os_msys_register/#arguments",
- "text": "Arguments Description new_pool Pointer to mbuf pool to add to system mbuf pools",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/msys/os_msys_register/#returned-values",
- "text": "0 on success; all other values indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/msys/os_msys_register/#example",
- "text": "rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/msys/os_msys_reset/",
- "text": "os_msys_reset\n\n\nvoid\n \nos_msys_reset\n(\nvoid\n) \n\n\n\n\n\nResets msys module. This de-registers all pools from msys but does nothing to the pools themselves (they still exist as mbuf pools).\n\n\n\n\nArguments\n\n\nNone\n\n\n\n\nReturned values\n\n\nNone\n\n\n\n\nExample\n\n\n \nos_msys_reset\n();",
- "title": "os_msys_reset"
- },
- {
- "location": "/os/core_os/msys/os_msys_reset/#os_msys_reset",
- "text": "void os_msys_reset ( void ) Resets msys module. This de-registers all pools from msys but does nothing to the pools themselves (they still exist as mbuf pools).",
- "title": "os_msys_reset"
- },
- {
- "location": "/os/core_os/msys/os_msys_reset/#arguments",
- "text": "None",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/msys/os_msys_reset/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/msys/os_msys_reset/#example",
- "text": "os_msys_reset ();",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mqueue/mqueue/",
- "text": "Mqueue\n\n\nThe mqueue construct allows a task to wake up when it receives data. Typically, this data is in the form of packets received over a network. A common networking stack operation is to put a packet on a queue and post an event to the task monitoring that queue. When the task handles the event, it processes each packet on the packet queue.\n\n\n\n\nUsing Mqueue\n\n\nThe following code sample demonstrates how to use an mqueue. In this example:\n\n\n\n\npackets are put on a receive queue\n\n\na task processes each packet on the queue (increments a receive counter)\n\n\n\n\nNot shown in the code example is a call \nmy_task_rx_data_func\n. Presumably, some other code will call this API. \n\n\n\n\nuint32_t\n \npkts_rxd\n;\n\nstruct\n \nos_mqueue\n \nrxpkt_q\n;\n\nstruct\n \nos_eventq\n \nmy_task_evq\n;\n\n\n/**\n\n\n * Removes each packet from the receive queue and processes it.\n\n\n */\n\n\nvoid\n\n\nprocess_rx_data_queue\n(\nvoid\n)\n{\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \nwhile\n ((\nom\n \n=\n \nos_mqueue_get\n(\nrxpkt_q\n)) \n!=\n \nNULL\n) {\n \n++pkts_rxd\n;\n \nos_mbuf_free_chain\n(\nom\n);\n }\n}\n\n\n/**\n\n\n * Called when a packet is received.\n\n\n */\n\n\nint\n\n\nmy_task_rx_data_func\n(\nstruct\n \nos_mbuf\n \n*om\n)\n{\n \nint\n \nrc\n;\n\n \n/* Enqueue the received packet and wake up the listening task. */\n\n \nrc\n \n=\n \nos_mqueue_put\n(\nrxpkt_q\n, \nmy_task_evq\n, \nom\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \nreturn\n \n0\n;\n}\n\n\nvoid\n\n\nmy_task_handler\n(\nvoid\n \n*arg\n)\n{\n \nstruct\n \nos_event\n \n*ev\n;\n \nstruct\n \nos_callout_func\n \n*cf\n;\n \nint\n \nrc\n;\n\n \n/* Initialize eventq */\n\n \nos_eventq_init\n(\nmy_task_evq\n);\n\n \n/* Initialize mqueue */\n\n \nos_mqueue_init\n(\nrxpkt_q\n, \nNULL\n);\n\n \n/* Process each event posted to our eventq. When there are no events to\n\n\n * process, sleep until one arrives.\n\n\n */\n\n \nwhile\n (\n1\n) {\n \nos_eventq_run\n(\nmy_task_evq\n);\n }\n}\n\n\n\n\n\nData Structures\n\n\nstruct\n \nos_mqueue\n {\n \nSTAILQ_HEAD\n(, \nos_mbuf_pkthdr\n) \nmq_head\n;\n \nstruct\n \nos_event\n \nmq_ev\n;\n};\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in Mqueue are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_mqueue_init\n\n\nInitializes an mqueue.\n\n\n\n\n\n\nos_mqueue_get\n\n\nRetrieves a packet off an Mqueue.\n\n\n\n\n\n\nos_mqueue_put\n\n\nAdds a packet (i.e. packet header mbuf) to an mqueue.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/mqueue/mqueue/#mqueue",
- "text": "The mqueue construct allows a task to wake up when it receives data. Typically, this data is in the form of packets received over a network. A common networking stack operation is to put a packet on a queue and post an event to the task monitoring that queue. When the task handles the event, it processes each packet on the packet queue.",
- "title": "Mqueue"
- },
- {
- "location": "/os/core_os/mqueue/mqueue/#using-mqueue",
- "text": "The following code sample demonstrates how to use an mqueue. In this example: packets are put on a receive queue a task processes each packet on the queue (increments a receive counter) Not shown in the code example is a call my_task_rx_data_func . Presumably, some other code will call this API. uint32_t pkts_rxd ; struct os_mqueue rxpkt_q ; struct os_eventq my_task_evq ; /** * Removes each packet from the receive queue and processes it. */ void process_rx_data_queue ( void )\n{\n struct os_mbuf *om ;\n\n while (( om = os_mqueue_get ( rxpkt_q )) != NULL ) {\n ++pkts_rxd ;\n os_mbuf_free_chain ( om );\n }\n} /** * Called when a packet is received. */ int my_task_rx_data_func ( struct os_mbuf *om )\n{\n int rc ;\n\n /* Enqueue the received packet and wake up the listening task. */ \n rc = os_mqueue_put ( rxpkt_q , my_task_evq , om );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n return 0 ;\n} void my_task_handler ( void *arg )\n{\n struct os_event *ev ;\n struct os_callout_func *cf ;\n int rc ;\n\n /* Initialize eventq */ \n os_eventq_init ( my_task_evq );\n\n /* Initialize mqueue */ \n os_mqueue_init ( rxpkt_q , NULL );\n\n /* Process each event posted to our eventq. When there are no events to * process, sleep until one arrives. */ \n while ( 1 ) {\n os_eventq_run ( my_task_evq );\n }\n}",
- "title": "Using Mqueue"
- },
- {
- "location": "/os/core_os/mqueue/mqueue/#data-structures",
- "text": "struct os_mqueue {\n STAILQ_HEAD (, os_mbuf_pkthdr ) mq_head ;\n struct os_event mq_ev ;\n};",
- "title": "Data Structures"
- },
- {
- "location": "/os/core_os/mqueue/mqueue/#list-of-functions",
- "text": "The functions available in Mqueue are: Function Description os_mqueue_init Initializes an mqueue. os_mqueue_get Retrieves a packet off an Mqueue. os_mqueue_put Adds a packet (i.e. packet header mbuf) to an mqueue.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_init/",
- "text": "os_mqueue_init\n\n\nint\n\n\nos_mqueue_init\n(\nstruct\n \nos_mqueue\n \n*mq\n, \nos_event_fn\n \n*ev_cb\n, \nvoid\n \n*arg\n)\n\n\n\n\n\nInitializes an mqueue. An mqueue is a queue of mbufs that ties to a particular task's event queue. Mqueues form a helper API around a common paradigm: wait on an event queue until at least one packet is available, then process a queue of packets.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmq\n\n\nThe mqueue to initialize\n\n\n\n\n\n\nev_cb\n\n\nThe callback to associate with the mqeueue event. Typically, this callback pulls each packet off the mqueue and processes them.\n\n\n\n\n\n\narg\n\n\nThe argument to associate with the mqueue event.\n\n\n\n\n\n\n\n\n@return 0 on success, non-zero on failure.\n\n\nInitializes an mqueue. Sets the event argument in the os event of the mqueue to \narg\n.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmq\n\n\nPointer to a mqueue structure\n\n\n\n\n\n\narg\n\n\nEvent argument\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: success. All other values indicate an error\n\n\n\n\nExample\n\n\n/* Event callback to execute when a packet is received. */\n\n\nextern\n \nvoid\n \nprocess_rx_data_queue\n(\nvoid\n);\n\n\n/* Declare mqueue */\n\n\nstruct\n \nos_mqueue\n \nrxpkt_q\n;\n\n\n/* Initialize mqueue */\n\n\nos_mqueue_init\n(\nrxpkt_q\n, \nprocess_rx_data_queue\n, \nNULL\n);",
- "title": "os_mqueue_init"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_init/#os_mqueue_init",
- "text": "int os_mqueue_init ( struct os_mqueue *mq , os_event_fn *ev_cb , void *arg ) Initializes an mqueue. An mqueue is a queue of mbufs that ties to a particular task's event queue. Mqueues form a helper API around a common paradigm: wait on an event queue until at least one packet is available, then process a queue of packets.",
- "title": "os_mqueue_init"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_init/#arguments",
- "text": "Arguments Description mq The mqueue to initialize ev_cb The callback to associate with the mqeueue event. Typically, this callback pulls each packet off the mqueue and processes them. arg The argument to associate with the mqueue event. @return 0 on success, non-zero on failure. Initializes an mqueue. Sets the event argument in the os event of the mqueue to arg .",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_init/#arguments_1",
- "text": "Arguments Description mq Pointer to a mqueue structure arg Event argument",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_init/#returned-values",
- "text": "0: success. All other values indicate an error",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_init/#example",
- "text": "/* Event callback to execute when a packet is received. */ extern void process_rx_data_queue ( void ); /* Declare mqueue */ struct os_mqueue rxpkt_q ; /* Initialize mqueue */ os_mqueue_init ( rxpkt_q , process_rx_data_queue , NULL );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_get/",
- "text": "os_mqueue_get\n\n\nstruct\n \nos_mbuf\n \n*os_mqueue_get\n(\nstruct\n \nos_mqueue\n \n*mq\n)\n\n\n\n\n\nRetrieves a packet off an mqueue. Returns a pointer to the mbuf at the head of the mbuf chain or \nNULL\n if no packets are on the queue.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmq\n\n\nThe mqueue to retrieve an mbuf from.\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe packet at the head of the queue or \nNULL\n if no packets are on the queue.\n\n\n\n\nExample\n\n\nuint32_t\n \npkts_rxd\n;\n\nstruct\n \nos_mqueue\n \nrxpkt_q\n;\n\n\nvoid\n\n\nprocess_rx_data_queue\n(\nvoid\n)\n{\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/* Drain all packets off queue and process them */\n\n \nwhile\n ((\nom\n \n=\n \nos_mqueue_get\n(\nrxpkt_q\n)) \n!=\n \nNULL\n) {\n \n++pkts_rxd\n;\n \nos_mbuf_free_chain\n(\nom\n);\n }\n}",
- "title": "os_mqueue_get"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_get/#os_mqueue_get",
- "text": "struct os_mbuf *os_mqueue_get ( struct os_mqueue *mq ) Retrieves a packet off an mqueue. Returns a pointer to the mbuf at the head of the mbuf chain or NULL if no packets are on the queue.",
- "title": "os_mqueue_get"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_get/#arguments",
- "text": "Arguments Description mq The mqueue to retrieve an mbuf from.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_get/#returned-values",
- "text": "The packet at the head of the queue or NULL if no packets are on the queue.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_get/#example",
- "text": "uint32_t pkts_rxd ; struct os_mqueue rxpkt_q ; void process_rx_data_queue ( void )\n{\n struct os_mbuf *om ;\n\n /* Drain all packets off queue and process them */ \n while (( om = os_mqueue_get ( rxpkt_q )) != NULL ) {\n ++pkts_rxd ;\n os_mbuf_free_chain ( om );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_put/",
- "text": "os_mqueue_put\n\n\nint\n \nos_mqueue_put\n(\nstruct\n \nos_mqueue\n \n*mq\n, \nstruct\n \nos_eventq\n \n*evq\n, \nstruct\n \nos_mbuf\n \n*m\n)\n\n\n\n\n\nAdds a packet (i.e. packet header mbuf) to an mqueue. The event associated with the mqueue gets posted to the specified eventq.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmq\n\n\nThe mbuf queue to append the mbuf to.\n\n\n\n\n\n\nevq\n\n\nThe event queue to post an event to.\n\n\n\n\n\n\nm\n\n\nThe mbuf to append to the mbuf queue.\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: success\n\n\nOS_EINVAL\n: the mbuf is not a packet header mbuf.\n\n\n\n\nExample\n\n\nint\n\n\nmy_task_rx_data_func\n(\nstruct\n \nos_mbuf\n \n*om\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_mqueue_put\n(\nrxpkt_q\n, \nmy_task_evq\n, \nom\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \nreturn\n \n0\n;\n}",
- "title": "os_mqueue_put"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_put/#os_mqueue_put",
- "text": "int os_mqueue_put ( struct os_mqueue *mq , struct os_eventq *evq , struct os_mbuf *m ) Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated with the mqueue gets posted to the specified eventq.",
- "title": "os_mqueue_put"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_put/#arguments",
- "text": "Arguments Description mq The mbuf queue to append the mbuf to. evq The event queue to post an event to. m The mbuf to append to the mbuf queue.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_put/#returned-values",
- "text": "0: success OS_EINVAL : the mbuf is not a packet header mbuf.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/mqueue/os_mqueue_put/#example",
- "text": "int my_task_rx_data_func ( struct os_mbuf *om )\n{\n int rc ;\n\n rc = os_mqueue_put ( rxpkt_q , my_task_evq , om );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n return 0 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/core_os/sanity/sanity/",
- "text": "Sanity\n\n\nThe Sanity task is a software watchdog task, which runs periodically to check\nsystem state, and ensure that everything is still operating properly.\n\n\nIn a typical system design, there are multiple stages of watchdog: \n\n\n\n\n\n\nInternal Watchdog\n\n\n\n\n\n\nExternal Watchdog \n\n\n\n\n\n\nSanity Watchdog \n\n\n\n\n\n\nThe \nInternal Watchdog\n is typically an MCU watchdog, which is tickled in \nthe core of the OS. The internal watchdog is tickled frequently, and is \nmeant to be an indicator the OS is running.\n\n\nThe \nExternal Watchdog\n is a watchdog that's typically run slower. The \npurpose of an external watchdog is to provide the system with a hard reset\nwhen it has lost its mind. \n\n\nThe \nSanity Watchdog\n is the least frequently run watchdog, and is meant as \nan application watchdog. \n\n\nThis document is about the operation of the Mynewt Sanity Watchdog.\n\n\nDescription\n\n\nInitializing the Sanity Task\n\n\nThe Sanity Watchdog is a task in the Mynewt OS, which when enabled, runs \nevery \nsanity_seconds\n. In order to enable the Sanity Watchdog task, \ncall the \nos_sanity_task_init()\n function.\n\n\nint\n \nos_sanity_task_init\n(\nint\n \nsanity_seconds\n);\n\n\n\n\n\nBy default, every operating system task provides the frequency it will \ncheck in with the sanity task, with the \nsanity_itvl\n parameter in the \n\nos_task_init()\n function:\n\n\nint\n \nos_task_init\n(\nstruct\n \nos_task\n \n*t\n, \nchar\n \n*name\n, \nos_task_func_t\n \nfunc\n, \n \nvoid\n \n*arg\n, \nuint8_t\n \nprio\n, \nos_time_t\n \nsanity_itvl\n, \nos_stack_t\n \n*bottom\n,\n \nuint16_t\n \nstack_size\n);\n\n\n\n\n\nsanity_itvl\n is the time in OS time ticks that the task being created \nmust register in with the sanity task. \n\n\nChecking in with Sanity Task\n\n\nThe task must then register in with the sanity task every \nsanity_itvl\n \nseconds. In order to do that, the task should call the \nos_sanity_task_checkin\n\nfunction, which will reset the sanity check associated with this task.\nHere is an example of a task that uses a callout to checkin with the \nsanity task every 50 seconds:\n\n\n#define TASK1_SANITY_CHECKIN_ITVL (50 * OS_TICKS_PER_SEC) \n\n\nstruct\n \nos_eventq\n \ntask1_evq\n;\n\n\nstatic\n \nvoid\n\n\ntask1\n(\nvoid\n \n*arg\n)\n{\n \nstruct\n \nos_task\n \n*t\n;\n \nstruct\n \nos_event\n \n*ev\n;\n \nstruct\n \nos_callout\n \nc\n;\n\n \n/* Get current OS task */\n\n \nt\n \n=\n \nos_sched_get_current_task\n();\n\n \n/* Initialize the event queue. */\n\n \nos_eventq_init\n(\ntask1_evq\n);\n\n \n/* Initialize the callout */\n\n \nos_callout_init\n(\nc\n, \ntask1_evq\n, \nNULL\n);\n\n \n/* reset the callout to checkin with the sanity task \n\n\n * in 50 seconds to kick off timing.\n\n\n */\n\n \nos_callout_reset\n(\nc\n, \nTASK1_SANITY_CHECKIN_ITVL\n);\n\n \nwhile\n (\n1\n) {\n \nev\n \n=\n \nos_eventq_get\n(\ntask1_evq\n);\n\n \n/* The sanity timer has reset */\n\n \nif\n (\nev-\nev_arg\n \n==\n \nc\n) {\n \nos_sanity_task_checkin\n(\nt\n);\n } \nelse\n {\n \n/* not expecting any other events */\n\n \nassert\n(\n0\n);\n }\n }\n\n \n/* Should never reach */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\nRegistering a Custom Sanity Check\n\n\nIf a particular task wants to further hook into the sanity framework to \nperform other checks during the sanity task's operation, it can do so by\nregistering a \nstruct os_sanity_check\n using the \nos_sanity_check_register\n\nfunction.\n\n\nstatic\n \nint\n \n\nmymodule_perform_sanity_check\n(\nstruct\n \nos_sanity_check\n \n*sc\n, \nvoid\n \n*arg\n)\n{\n \n/* Perform your checking here. In this case, we check if there \n\n\n * are available buffers in mymodule, and return 0 (all good)\n\n\n * if true, and -1 (error) if not.\n\n\n */\n\n \nif\n (\nmymodule_has_buffers\n()) {\n \nreturn\n (\n0\n);\n } \nelse\n {\n \nreturn\n (\n-\n1\n);\n }\n}\n\n\nstatic\n \nint\n \n\nmymodule_register_sanity_check\n(\nvoid\n)\n{\n \nstruct\n \nos_sanity_check\n \nsc\n;\n\n \nos_sanity_check_init\n(\nsc\n);\n \n/* Only assert() if mymodule_perform_sanity_check() fails 50 \n\n\n * times. SANITY_TASK_INTERVAL is defined by the user, and \n\n\n * is the frequency at which the sanity_task runs in seconds.\n\n\n */\n\n \nOS_SANITY_CHECK_SETFUNC\n(\nsc\n, \nmymodule_perform_sanity_check\n, \nNULL\n, \n \n50\n \n*\n \nSANITY_TASK_INTERVAL\n);\n\n \nrc\n \n=\n \nos_sanity_check_register\n(\nsc\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \ngoto\n \nerr\n;\n } \n\n \nreturn\n (\n0\n);\n\nerr\n:\n \nreturn\n (\nrc\n);\n}\n\n\n\n\n\nIn the above example, every time the custom sanity check \n\nmymodule_perform_sanity_check\n returns successfully (0), \nthe sanity check is reset. In the \nOS_SANITY_CHECK_SETFUNC\n macro,\nthe sanity checkin interval is specified as 50 * \nSANITY_TASK_INTERVAL\n \n(which is the interval at which the sanity task runs.) This means \nthat the \nmymodule_perform_sanity_check()\n function needs to fail\n50 times consecutively before the sanity task will crash the system.\n\n\nTIP:\n When checking things like memory buffers, which can be temporarily \nbe exhausted, it's a good idea to have the sanity check fail multiple \nconsecutive times before crashing the system. This will avoid crashing\nfor temporary failures.\n\n\nData structures\n\n\nOS Sanity Check\n\n\nstruct\n \nos_sanity_check\n {\n \nos_time_t\n \nsc_checkin_last\n;\n \nos_time_t\n \nsc_checkin_itvl\n;\n \nos_sanity_check_func_t\n \nsc_func\n;\n \nvoid\n \n*sc_arg\n; \n\n \nSLIST_ENTRY\n(\nos_sanity_check\n) \nsc_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc_checkin_last\n\n\nThe last time this sanity check checked in with the sanity task, in OS time ticks.\n\n\n\n\n\n\nsc_checkin_itvl\n\n\nHow frequently the sanity check is supposed to check in with the sanity task, in OS time ticks.\n\n\n\n\n\n\nsc_func\n\n\nIf not \nNULL\n, call this function when running the sanity task. If the function returns 0, reset the sanity check.\n\n\n\n\n\n\nsc_arg\n\n\nArgument to pass to \nsc_func\n when calling it.\n\n\n\n\n\n\nsc_next\n\n\nSanity checks are chained in the sanity task when \nos_sanity_check_register()\n is called.\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in sanity are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_sanity_check_init\n\n\nInitialize the given sanity check.\n\n\n\n\n\n\nos_sanity_check_register\n\n\nRegister the given sanity check with the sanity task.\n\n\n\n\n\n\nos_sanity_check_reset\n\n\nReset the given sanity check.\n\n\n\n\n\n\nos_sanity_task_checkin\n\n\nInforms the sanity task that the given task is still alive and working normally.\n\n\n\n\n\n\nos_sanity_task_init\n\n\nInitialize the os sanity task.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/sanity/sanity/#sanity",
- "text": "The Sanity task is a software watchdog task, which runs periodically to check\nsystem state, and ensure that everything is still operating properly. In a typical system design, there are multiple stages of watchdog: Internal Watchdog External Watchdog Sanity Watchdog The Internal Watchdog is typically an MCU watchdog, which is tickled in \nthe core of the OS. The internal watchdog is tickled frequently, and is \nmeant to be an indicator the OS is running. The External Watchdog is a watchdog that's typically run slower. The \npurpose of an external watchdog is to provide the system with a hard reset\nwhen it has lost its mind. The Sanity Watchdog is the least frequently run watchdog, and is meant as \nan application watchdog. This document is about the operation of the Mynewt Sanity Watchdog.",
- "title": "Sanity"
- },
- {
- "location": "/os/core_os/sanity/sanity/#description",
- "text": "",
- "title": "Description"
- },
- {
- "location": "/os/core_os/sanity/sanity/#initializing-the-sanity-task",
- "text": "The Sanity Watchdog is a task in the Mynewt OS, which when enabled, runs \nevery sanity_seconds . In order to enable the Sanity Watchdog task, \ncall the os_sanity_task_init() function. int os_sanity_task_init ( int sanity_seconds ); By default, every operating system task provides the frequency it will \ncheck in with the sanity task, with the sanity_itvl parameter in the os_task_init() function: int os_task_init ( struct os_task *t , char *name , os_task_func_t func , \n void *arg , uint8_t prio , os_time_t sanity_itvl , os_stack_t *bottom ,\n uint16_t stack_size ); sanity_itvl is the time in OS time ticks that the task being created \nmust register in with the sanity task.",
- "title": "Initializing the Sanity Task"
- },
- {
- "location": "/os/core_os/sanity/sanity/#checking-in-with-sanity-task",
- "text": "The task must then register in with the sanity task every sanity_itvl \nseconds. In order to do that, the task should call the os_sanity_task_checkin \nfunction, which will reset the sanity check associated with this task.\nHere is an example of a task that uses a callout to checkin with the \nsanity task every 50 seconds: #define TASK1_SANITY_CHECKIN_ITVL (50 * OS_TICKS_PER_SEC) struct os_eventq task1_evq ; static void task1 ( void *arg )\n{\n struct os_task *t ;\n struct os_event *ev ;\n struct os_callout c ;\n\n /* Get current OS task */ \n t = os_sched_get_current_task ();\n\n /* Initialize the event queue. */ \n os_eventq_init ( task1_evq );\n\n /* Initialize the callout */ \n os_callout_init ( c , task1_evq , NULL );\n\n /* reset the callout to checkin with the sanity task * in 50 seconds to kick off timing. */ \n os_callout_reset ( c , TASK1_SANITY_CHECKIN_ITVL );\n\n while ( 1 ) {\n ev = os_eventq_get ( task1_evq );\n\n /* The sanity timer has reset */ \n if ( ev- ev_arg == c ) {\n os_sanity_task_checkin ( t );\n } else {\n /* not expecting any other events */ \n assert ( 0 );\n }\n }\n\n /* Should never reach */ \n assert ( 0 );\n}",
- "title": "Checking in with Sanity Task"
- },
- {
- "location": "/os/core_os/sanity/sanity/#registering-a-custom-sanity-check",
- "text": "If a particular task wants to further hook into the sanity framework to \nperform other checks during the sanity task's operation, it can do so by\nregistering a struct os_sanity_check using the os_sanity_check_register \nfunction. static int mymodule_perform_sanity_check ( struct os_sanity_check *sc , void *arg )\n{\n /* Perform your checking here. In this case, we check if there * are available buffers in mymodule, and return 0 (all good) * if true, and -1 (error) if not. */ \n if ( mymodule_has_buffers ()) {\n return ( 0 );\n } else {\n return ( - 1 );\n }\n} static int mymodule_register_sanity_check ( void )\n{\n struct os_sanity_check sc ;\n\n os_sanity_check_init ( sc );\n /* Only assert() if mymodule_perform_sanity_check() fails 50 * times. SANITY_TASK_INTERVAL is defined by the user, and * is the frequency at which the sanity_task runs in seconds. */ \n OS_SANITY_CHECK_SETFUNC ( sc , mymodule_perform_sanity_check , NULL , \n 50 * SANITY_TASK_INTERVAL );\n\n rc = os_sanity_check_register ( sc );\n if ( rc != 0 ) {\n goto err ;\n } \n\n return ( 0 ); err :\n return ( rc );\n} In the above example, every time the custom sanity check mymodule_perform_sanity_check returns successfully (0), \nthe sanity check is reset. In the OS_SANITY_CHECK_SETFUNC macro,\nthe sanity checkin interval is specified as 50 * SANITY_TASK_INTERVAL \n(which is the interval at which the sanity task runs.) This means \nthat the mymodule_perform_sanity_check() function needs to fail\n50 times consecutively before the sanity task will crash the system. TIP: When checking things like memory buffers, which can be temporarily \nbe exhausted, it's a good idea to have the sanity check fail multiple \nconsecutive times before crashing the system. This will avoid crashing\nfor temporary failures.",
- "title": "Registering a Custom Sanity Check"
- },
- {
- "location": "/os/core_os/sanity/sanity/#data-structures",
- "text": "",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/sanity/sanity/#os-sanity-check",
- "text": "struct os_sanity_check {\n os_time_t sc_checkin_last ;\n os_time_t sc_checkin_itvl ;\n os_sanity_check_func_t sc_func ;\n void *sc_arg ; \n\n SLIST_ENTRY ( os_sanity_check ) sc_next ;\n}; Element Description sc_checkin_last The last time this sanity check checked in with the sanity task, in OS time ticks. sc_checkin_itvl How frequently the sanity check is supposed to check in with the sanity task, in OS time ticks. sc_func If not NULL , call this function when running the sanity task. If the function returns 0, reset the sanity check. sc_arg Argument to pass to sc_func when calling it. sc_next Sanity checks are chained in the sanity task when os_sanity_check_register() is called.",
- "title": "OS Sanity Check"
- },
- {
- "location": "/os/core_os/sanity/sanity/#list-of-functions",
- "text": "The functions available in sanity are: Function Description os_sanity_check_init Initialize the given sanity check. os_sanity_check_register Register the given sanity check with the sanity task. os_sanity_check_reset Reset the given sanity check. os_sanity_task_checkin Informs the sanity task that the given task is still alive and working normally. os_sanity_task_init Initialize the os sanity task.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_init/",
- "text": "os_sanity_check_init\n\n\nint\n \nos_sanity_check_init\n(\nstruct\n \nos_sanity_check\n \n*sc\n)\n\n\n\n\n\nInitialize the sanity check pointed to by \nsc\n. Sets default values, and ensures\nmemory is cleared out.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc\n\n\nPointer to sanity check\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: sanity check initialization is successful \n\n\nAll other error codes indicate an error.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_sanity_task_check_init\n(\nmy_sanity_check\n); \n \nassert\n(\nrc\n \n==\n \nOS_OK\n);",
- "title": "os_sanity_check_init"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_init/#os_sanity_check_init",
- "text": "int os_sanity_check_init ( struct os_sanity_check *sc ) Initialize the sanity check pointed to by sc . Sets default values, and ensures\nmemory is cleared out.",
- "title": " os_sanity_check_init"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_init/#arguments",
- "text": "Arguments Description sc Pointer to sanity check",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_init/#returned-values",
- "text": "OS_OK : sanity check initialization is successful All other error codes indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_init/#example",
- "text": "int rc ;\n\n rc = os_sanity_task_check_init ( my_sanity_check ); \n assert ( rc == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_register/",
- "text": "os_sanity_check_register\n\n\nint\n \nos_sanity_check_register\n(\nstruct\n \nos_sanity_check\n \n*sc\n)\n\n\n\n\n\nRegister the sanity check pointed to by \nsc\n with the sanity task. After registration\nthe sanity task will check this sanity check with every run of the sanity task.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc\n\n\nPointer to sanity check\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: sanity check successfully registered\n\n\nAll other error codes indicate an error.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_sanity_check_register\n(\nmy_sc\n); \n \nassert\n(\nrc\n \n==\n \nOS_OK\n);",
- "title": "os_sanity_check_register"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_register/#os_sanity_check_register",
- "text": "int os_sanity_check_register ( struct os_sanity_check *sc ) Register the sanity check pointed to by sc with the sanity task. After registration\nthe sanity task will check this sanity check with every run of the sanity task.",
- "title": " os_sanity_check_register"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_register/#arguments",
- "text": "Arguments Description sc Pointer to sanity check",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_register/#returned-values",
- "text": "OS_OK : sanity check successfully registered All other error codes indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_register/#example",
- "text": "int rc ;\n\n rc = os_sanity_check_register ( my_sc ); \n assert ( rc == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_reset/",
- "text": "os_sanity_check_reset\n\n\nint\n \nos_sanity_check_reset\n(\nstruct\n \nos_sanity_check\n \n*sc\n)\n\n\n\n\n\nReset the sanity check pointed to by sc. This tells the sanity task that \nthis sanity check is considered valid for another \nsc_checkin_itvl\n time \nticks.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc\n\n\nPointer to sanity check\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: sanity check reset successful\n\n\nAll other error codes indicate an error.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_sanity_check_reset\n(\nmy_sc\n); \n \nassert\n(\nrc\n \n==\n \nOS_OK\n);",
- "title": "os_sanity_check_reset"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_reset/#os_sanity_check_reset",
- "text": "int os_sanity_check_reset ( struct os_sanity_check *sc ) Reset the sanity check pointed to by sc. This tells the sanity task that \nthis sanity check is considered valid for another sc_checkin_itvl time \nticks.",
- "title": " os_sanity_check_reset"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_reset/#arguments",
- "text": "Arguments Description sc Pointer to sanity check",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_reset/#returned-values",
- "text": "OS_OK : sanity check reset successful All other error codes indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_check_reset/#example",
- "text": "int rc ;\n\n rc = os_sanity_check_reset ( my_sc ); \n assert ( rc == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_checkin/",
- "text": "os_sanity_task_checkin\n\n\nint\n \nos_sanity_task_checkin\n(\nstruct\n \nos_task\n \n*t\n)\n\n\n\n\n\nUsed by a task to check in to the sanity task. This informs the sanity task that \n\ntask\n is still alive and working normally.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nt\n\n\nPointer to task\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: sanity check-in successful\n\n\nAll other error codes indicate an error.\n\n\n\n\nExample\n\n\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_sanity_task_checkin\n(\nmy_task\n); \n \nassert\n(\nrc\n \n==\n \nOS_OK\n);",
- "title": "os_sanity_task_checkin"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_checkin/#os_sanity_task_checkin",
- "text": "int os_sanity_task_checkin ( struct os_task *t ) Used by a task to check in to the sanity task. This informs the sanity task that task is still alive and working normally.",
- "title": " os_sanity_task_checkin"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_checkin/#arguments",
- "text": "Arguments Description t Pointer to task",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_checkin/#returned-values",
- "text": "OS_OK : sanity check-in successful All other error codes indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_checkin/#example",
- "text": "int rc ;\n\n rc = os_sanity_task_checkin ( my_task ); \n assert ( rc == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_init/",
- "text": "os_sanity_task_init\n\n\nint\n \nos_sanity_task_init\n(\nint\n \nnum_secs\n);\n\n\n\n\n\nInitialize the os sanity task. \nnum_secs\n is the number of seconds to wait\nin between runs of the sanity task.\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnum_secs\n\n\nNumber of seconds to wait in between running sanity checks.\n\n\n\n\n\n\n\n\n\n\nReturned values\n\n\nOS_OK\n: Sanity task was successfully created.\n\n\nAll other error codes indicate an error.\n\n\n\n\nExample\n\n\n/* Run sanity checks every 50 seconds */\n\n\n\n#define SANITY_TASK_INTERVAL (50)\n\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nos_sanity_task_init\n(\nSANITY_TASK_INTERVAL\n); \n \nassert\n(\nrc\n \n==\n \nOS_OK\n);",
- "title": "os_sanity_task_init"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_init/#os_sanity_task_init",
- "text": "int os_sanity_task_init ( int num_secs ); Initialize the os sanity task. num_secs is the number of seconds to wait\nin between runs of the sanity task.",
- "title": " os_sanity_task_init"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_init/#arguments",
- "text": "Arguments Description num_secs Number of seconds to wait in between running sanity checks.",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_init/#returned-values",
- "text": "OS_OK : Sanity task was successfully created. All other error codes indicate an error.",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/sanity/os_sanity_task_init/#example",
- "text": "/* Run sanity checks every 50 seconds */ #define SANITY_TASK_INTERVAL (50) \n int rc ;\n\n rc = os_sanity_task_init ( SANITY_TASK_INTERVAL ); \n assert ( rc == OS_OK );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/callout/callout/",
- "text": "Callout\n\n\nCallouts are MyNewt OS timers.\n\n\nDescription\n\n\nCallout is a way of setting up an OS timer. When the timer fires, it is delivered as an event to task's event queue.\n\n\nUser would initialize their callout structure using \nos_callout_init()\n, or \nos_callout_func_init()\n and then arm it with \nos_callout_reset()\n.\n\n\nIf user wants to cancel the timer before it expires, they can either use \nos_callout_reset()\n to arm it for later expiry, or stop it altogether by calling \nos_callout_stop()\n.\n\n\nThere are 2 different options for data structure to use. First is \nstruct os_callout\n, which is a bare-bones version. You would initialize this with \nos_callout_init()\n.\n\n\nSecond option is \nstruct os_callout_func\n. This you can use if you expect to have multiple different types of timers in your task, running concurrently. The structure contains a function pointer, and you would call that function from your task's event processing loop.\n\n\nTime unit when arming the timer is OS ticks. This rate of this ticker depends on the platform this is running on. You should use OS define \nOS_TICKS_PER_SEC\n to convert wallclock time to OS ticks.\n\n\nCallout timer fires out just once. For periodic timer type of operation you need to rearm it once it fires.\n\n\nData structures\n\n\n \nstruct\n \nos_callout\n {\n \nstruct\n \nos_event\n \nc_ev\n;\n \nstruct\n \nos_eventq\n \n*c_evq\n;\n \nuint32_t\n \nc_ticks\n;\n \nTAILQ_ENTRY\n(\nos_callout\n) \nc_next\n;\n };\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nc_ev\n\n\nEvent structure of this callout\n\n\n\n\n\n\nc_evq\n\n\nEvent queue where this callout is placed on timer expiry\n\n\n\n\n\n\nc_ticks\n\n\nOS tick amount when timer fires\n\n\n\n\n\n\nc_next\n\n\nLinkage to other unexpired callouts\n\n\n\n\n\n\n\n\n \nstruct\n \nos_callout_func\n {\n \nstruct\n \nos_callout\n \ncf_c\n;\n \nos_callout_func_t\n \ncf_func\n;\n \nvoid\n \n*cf_arg\n;\n };\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ncf_c\n\n\nstruct os_callout. See above\n\n\n\n\n\n\ncf_func\n\n\nFunction pointer which should be called by event queue processing\n\n\n\n\n\n\ncf_arg\n\n\nGeneric void * argument to that function\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in callout are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_callout_func_init\n\n\nInitializes the given callout function struct.\n\n\n\n\n\n\nos_callout_init\n\n\nInitializes the given callout struct.\n\n\n\n\n\n\nos_callout_queued\n\n\nChecks whether the given callout has been armed.\n\n\n\n\n\n\nos_callout_reset\n\n\nResets the callout to happen in the given number of OS ticks.\n\n\n\n\n\n\nos_callout_stop\n\n\nDisarms a timer.",
- "title": "toc"
- },
- {
- "location": "/os/core_os/callout/callout/#callout",
- "text": "Callouts are MyNewt OS timers.",
- "title": "Callout"
- },
- {
- "location": "/os/core_os/callout/callout/#description",
- "text": "Callout is a way of setting up an OS timer. When the timer fires, it is delivered as an event to task's event queue. User would initialize their callout structure using os_callout_init() , or os_callout_func_init() and then arm it with os_callout_reset() . If user wants to cancel the timer before it expires, they can either use os_callout_reset() to arm it for later expiry, or stop it altogether by calling os_callout_stop() . There are 2 different options for data structure to use. First is struct os_callout , which is a bare-bones version. You would initialize this with os_callout_init() . Second option is struct os_callout_func . This you can use if you expect to have multiple different types of timers in your task, running concurrently. The structure contains a function pointer, and you would call that function from your task's event processing loop. Time unit when arming the timer is OS ticks. This rate of this ticker depends on the platform this is running on. You should use OS define OS_TICKS_PER_SEC to convert wallclock time to OS ticks. Callout timer fires out just once. For periodic timer type of operation you need to rearm it once it fires.",
- "title": "Description"
- },
- {
- "location": "/os/core_os/callout/callout/#data-structures",
- "text": "struct os_callout {\n struct os_event c_ev ;\n struct os_eventq *c_evq ;\n uint32_t c_ticks ;\n TAILQ_ENTRY ( os_callout ) c_next ;\n }; Element Description c_ev Event structure of this callout c_evq Event queue where this callout is placed on timer expiry c_ticks OS tick amount when timer fires c_next Linkage to other unexpired callouts struct os_callout_func {\n struct os_callout cf_c ;\n os_callout_func_t cf_func ;\n void *cf_arg ;\n }; Element Description cf_c struct os_callout. See above cf_func Function pointer which should be called by event queue processing cf_arg Generic void * argument to that function",
- "title": "Data structures"
- },
- {
- "location": "/os/core_os/callout/callout/#list-of-functions",
- "text": "The functions available in callout are: Function Description os_callout_func_init Initializes the given callout function struct. os_callout_init Initializes the given callout struct. os_callout_queued Checks whether the given callout has been armed. os_callout_reset Resets the callout to happen in the given number of OS ticks. os_callout_stop Disarms a timer.",
- "title": "List of Functions"
- },
- {
- "location": "/os/core_os/callout/os_callout_func_init/",
- "text": "os_callout_func_init \n\n\n \nvoid\n \nos_callout_func_init\n(\nstruct\n \nos_callout_func\n \n*cf\n, \nstruct\n \nos_eventq\n \n*evq\n, \nos_callout_func_t\n \ntimo_func\n, \nvoid\n \n*ev_arg\n)\n\n\n\n\n\nInitializes the given \nstruct os_callout_func\n. Data structure is filled in with elements given as argument.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ncf\n\n\nPointer to os_callout_func being initialized\n\n\n\n\n\n\nevq\n\n\nEvent queue where this gets delivered to\n\n\n\n\n\n\ntimo_func\n\n\nTimeout function. Event processing should call this\n\n\n\n\n\n\nev_arg\n\n\nGeneric argument for the event\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nThe same notes as with \nos_callout_init()\n.\n\n\nExample\n\n\n\n\n \nstruct\n \nos_callout_func\n \ng_native_cputimer\n;\n \nstruct\n \nos_eventq\n \ng_native_cputime_evq\n;\n \nvoid\n \nnative_cputimer_cb\n(\nvoid\n \n*arg\n);\n\n \n/* Initialize the callout function */\n\n \nos_callout_func_init\n(\ng_native_cputimer\n,\n \ng_native_cputime_evq\n,\n \nnative_cputimer_cb\n,\n \nNULL\n);",
- "title": "os_callout_func_init"
- },
- {
- "location": "/os/core_os/callout/os_callout_func_init/#os_callout_func_init",
- "text": "void os_callout_func_init ( struct os_callout_func *cf , struct os_eventq *evq , os_callout_func_t timo_func , void *ev_arg ) Initializes the given struct os_callout_func . Data structure is filled in with elements given as argument.",
- "title": " os_callout_func_init "
- },
- {
- "location": "/os/core_os/callout/os_callout_func_init/#arguments",
- "text": "Arguments Description cf Pointer to os_callout_func being initialized evq Event queue where this gets delivered to timo_func Timeout function. Event processing should call this ev_arg Generic argument for the event",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/callout/os_callout_func_init/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/callout/os_callout_func_init/#notes",
- "text": "The same notes as with os_callout_init() .",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/callout/os_callout_func_init/#example",
- "text": "struct os_callout_func g_native_cputimer ;\n struct os_eventq g_native_cputime_evq ;\n void native_cputimer_cb ( void *arg );\n\n /* Initialize the callout function */ \n os_callout_func_init ( g_native_cputimer ,\n g_native_cputime_evq ,\n native_cputimer_cb ,\n NULL );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/callout/os_callout_init/",
- "text": "os_callout_init \n\n\n \nvoid\n \nos_callout_init\n(\nstruct\n \nos_callout\n \n*c\n, \nstruct\n \nos_eventq\n \n*evq\n, \nvoid\n \n*ev_arg\n)\n\n\n\n\n\nInitializes \nstruct os_callout\n. Event type will be set to \nOS_EVENT_T_TIMER\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nc\n\n\nPointer to os_callout to initialize\n\n\n\n\n\n\nevq\n\n\nEvent queue where this gets delivered to\n\n\n\n\n\n\nev_arg\n\n\nGeneric argument which is filled in for the event\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nBe careful not to call this if the callout is armed, because that will mess up the list of pending callouts.\nOr if the timer has already fired, it will mess up the event queue where the callout was delivered to.\n\n\nExample\n\n\n\n\n \nstruct\n \nos_eventq\n \nmy_evq\n;\n \nstruct\n \nos_callout\n \nmy_callouts\n[\n8\n];\n\n \nfor\n (\ni\n \n=\n \n0\n; \ni\n \n \n8\n; \ni++\n) {\n \nos_callout_init\n(\nmy_callouts\n[\ni\n], \nmy_evq\n, (\nvoid\n \n*\n)\ni\n);\n }",
- "title": "os_callout_init"
- },
- {
- "location": "/os/core_os/callout/os_callout_init/#os_callout_init",
- "text": "void os_callout_init ( struct os_callout *c , struct os_eventq *evq , void *ev_arg ) Initializes struct os_callout . Event type will be set to OS_EVENT_T_TIMER .",
- "title": "os_callout_init "
- },
- {
- "location": "/os/core_os/callout/os_callout_init/#arguments",
- "text": "Arguments Description c Pointer to os_callout to initialize evq Event queue where this gets delivered to ev_arg Generic argument which is filled in for the event",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/callout/os_callout_init/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/callout/os_callout_init/#notes",
- "text": "Be careful not to call this if the callout is armed, because that will mess up the list of pending callouts.\nOr if the timer has already fired, it will mess up the event queue where the callout was delivered to.",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/callout/os_callout_init/#example",
- "text": "struct os_eventq my_evq ;\n struct os_callout my_callouts [ 8 ];\n\n for ( i = 0 ; i 8 ; i++ ) {\n os_callout_init ( my_callouts [ i ], my_evq , ( void * ) i );\n }",
- "title": "Example"
- },
- {
- "location": "/os/core_os/callout/os_callout_queued/",
- "text": "os_callout_queued\n\n\n \nint\n \nos_callout_queued\n(\nstruct\n \nos_callout\n \n*c\n)\n\n\n\n\n\nTells whether the callout has been armed or not.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nc\n\n\nPointer to callout being checked\n\n\n\n\n\n\n\n\nReturned values\n\n\n0: timer is not armed\n\n\nnon-zero: timer is armed",
- "title": "os_callout_queued"
- },
- {
- "location": "/os/core_os/callout/os_callout_queued/#os_callout_queued",
- "text": "int os_callout_queued ( struct os_callout *c ) Tells whether the callout has been armed or not.",
- "title": "os_callout_queued"
- },
- {
- "location": "/os/core_os/callout/os_callout_queued/#arguments",
- "text": "Arguments Description c Pointer to callout being checked",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/callout/os_callout_queued/#returned-values",
- "text": "0: timer is not armed non-zero: timer is armed",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/callout/os_callout_reset/",
- "text": "os_callout_reset \n\n\n \nvoid\n \nos_callout_reset\n(\nstruct\n \nos_callout\n \n*c\n, \nint32_t\n \ntimo\n)\n\n\n\n\n\nResets the callout to happen \ntimo\n in OS ticks.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nc\n\n\nPointer to os_callout being reset\n\n\n\n\n\n\ntimo\n\n\nOS ticks the timer is being set to\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nNotes\n\n\nExample\n\n\n\n\n \n/* Re-start the timer (run every 50 msecs) */\n\n \nos_callout_reset\n(\ng_bletest_timer\n.\ncf_c\n, \nOS_TICKS_PER_SEC\n \n/\n \n20\n);",
- "title": "os_callout_reset"
- },
- {
- "location": "/os/core_os/callout/os_callout_reset/#os_callout_reset",
- "text": "void os_callout_reset ( struct os_callout *c , int32_t timo ) Resets the callout to happen timo in OS ticks.",
- "title": " os_callout_reset "
- },
- {
- "location": "/os/core_os/callout/os_callout_reset/#arguments",
- "text": "Arguments Description c Pointer to os_callout being reset timo OS ticks the timer is being set to",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/callout/os_callout_reset/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/callout/os_callout_reset/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/core_os/callout/os_callout_reset/#example",
- "text": "/* Re-start the timer (run every 50 msecs) */ \n os_callout_reset ( g_bletest_timer . cf_c , OS_TICKS_PER_SEC / 20 );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/callout/os_callout_stop/",
- "text": "os_callout_stop \n\n\n \nvoid\n \nos_callout_stop\n(\nstruct\n \nos_callout\n \n*c\n)\n\n\n\n\n\nDisarms a timer.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nc\n\n\nPointer to os_callout being stopped\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nExample\n\n\n \nstruct\n \nos_callout_func\n \ng_native_cputimer\n;\n\n \nos_callout_stop\n(\ng_native_cputimer\n.\ncf_c\n);",
- "title": "os_callout_stop"
- },
- {
- "location": "/os/core_os/callout/os_callout_stop/#os_callout_stop",
- "text": "void os_callout_stop ( struct os_callout *c ) Disarms a timer.",
- "title": " os_callout_stop "
- },
- {
- "location": "/os/core_os/callout/os_callout_stop/#arguments",
- "text": "Arguments Description c Pointer to os_callout being stopped",
- "title": "Arguments"
- },
- {
- "location": "/os/core_os/callout/os_callout_stop/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/core_os/callout/os_callout_stop/#example",
- "text": "struct os_callout_func g_native_cputimer ;\n\n os_callout_stop ( g_native_cputimer . cf_c );",
- "title": "Example"
- },
- {
- "location": "/os/core_os/porting/port_os/",
- "text": "Porting Mynewt OS\n\n\nThis chapter describes how to adapt the Mynewt OS to different platforms.\n\n\nDescription\n\n\nThe Mynewt OS is a complete multi-tasking environment with scheduler, time\ncontrol, buffer management, and synchronization objects. it also includes\nlibraries and services like console, command shell, image manager,\nbootloader, and file systems etc.\n\n\nThee majority of this software is platform independent and requires no\nintervention to run on your platform, but some of the components require\nsupport from the underlying platform.\n\n\nThe platform dependency of these components can fall into several categories:\n\n\n\n\nCPU Core Dependencies\n -- Specific code or\nconfiguration to operate the CPU core within your target platform\n\n\nMCU Dependencies\n -- Specific code or configuration to operate the MCU or\nSoC within your target platform\n\n\nBSP Dependencies\n -- Specific code or configuration to accommodate the\nspecific layout and functionality of your target platform\n\n\n\n\nBoard Support Package (BSP) Dependency\n\n\nWith all of the functionality provided by the core, MCU, and MCU HAL (Hardware Abstraction Layer), \nthere are still some things that must be specified for your particular system. This\nis provided in Mynewt to allow you the flexibility to design for the exact\nfunctionality, peripherals and features that you require in your product. \n\n\nIn Mynewt, these settings/components are included in a Board Support Package\n(BSP). The BSP contains the information specific to running Mynewt on a target\nplatform or hardware board. Mynewt supports some common open source hardware as well\nas the development boards for some common MCUs. These development systems\nmight be enough for you to get your prototype up and running, but when building\na product you are likely going to have your own board which is slightly different\nfrom those already supported by Mynewt.\n\n\nFor example, you might decide on your system that 16 Kilobytes of flash space\nin one flash device is reserved for a flash file system. Or on your system\nyou may decide that GPIO pin 5 of the MCU is connected to the system LED. Or\nyou may decide that the OS Tick (the underlying time source for the OS) should\nrun slower than the defaults to conserve battery power. These types of\nbehaviors are specified in the BSP. \n\n\nThe information provided in the BSP (what you need to specify to get a\ncomplete executable) can vary depending on the MCU and its underlying core\narchitecture. For example, some MCUs have dedicated pins for UART, SPI etc,\nso there is no configuration required in the BSP when using these peripherals.\nHowever some MCUs have a pin multiplexor that allows the UART to be mapped to\nseveral different pins. For these MCUs, the BSP must specify if and where\nthe UART pins should appear to match the hardware layout of your system.\n\n\n\n\nIf your BSP is already supported my Mynewt, there is no additional BSP work involved in porting to your platform.\n\nYou need only set the \nbsp\n attribute in your Mynewt target using the \nnewt command tool\n.\n\n\nIf your BSP is not yet supported by Mynewt, you can add support by following the instructions on \nhow to add BSP support to Mynewt\n\n\n\n\nMCU Dependency\n\n\nSome OS code depends on the MCU or SoC that the system contains. For example, the MCU may specify \nthe potential memory map of the system - where code and data can reside.\n\n\n\n\nIf your MCU is already supported by Mynewt, there is no additional MCU work involved in \nporting to your platform. You need only set the \narch\n attribute in your Mynewt target \nusing the \nnewt command tool\n.\n\n\nIf your MCU is not yet supported by Mynewt, you can add support by following the \ninstructions on \nhow to add MCU support to Mynewt\n\n\n\n\nMCU Hardware Abstraction Layer (HAL)\n\n\nMynewt's architecture supports a hardware abstraction layer (HAL) for common on or off-chip MCU peripherals \nsuch as GPIO, UARTs, flash memory etc. Even if your MCU is supported for the core OS, \nyou may find that you need to implement the HAL functionality for a new peripheral. \nFor a description of the HAL abstraction and implementation information,\nsee the \nHAL API\n\n\nCPU Core Dependency\n\n\nSome OS code depends on the CPU core that your system is using. For example, a given CPU core \nhas a specific assembly language instruction set, and may require special cross compiler or \ncompiler settings to use the appropriate instruction set. \n\n\n\n\nIf your CPU architecture is already supported by Mynewt, there is no CPU core work involved \nin porting to your platform. You need only set the \narch\n and \ncompiler\n attributes in your \nMynewt target using the \nnewt command tool\n.\n\n\nIf your CPU architecture is not supported by Mynewt, you can add support by following the \ninstructions on \nhow to add CPU architecture support to Mynewt",
- "title": "toc"
- },
- {
- "location": "/os/core_os/porting/port_os/#porting-mynewt-os",
- "text": "This chapter describes how to adapt the Mynewt OS to different platforms.",
- "title": "Porting Mynewt OS"
- },
- {
- "location": "/os/core_os/porting/port_os/#description",
- "text": "The Mynewt OS is a complete multi-tasking environment with scheduler, time\ncontrol, buffer management, and synchronization objects. it also includes\nlibraries and services like console, command shell, image manager,\nbootloader, and file systems etc. Thee majority of this software is platform independent and requires no\nintervention to run on your platform, but some of the components require\nsupport from the underlying platform. The platform dependency of these components can fall into several categories: CPU Core Dependencies -- Specific code or\nconfiguration to operate the CPU core within your target platform MCU Dependencies -- Specific code or configuration to operate the MCU or\nSoC within your target platform BSP Dependencies -- Specific code or configuration to accommodate the\nspecific layout and functionality of your target platform",
- "title": "Description"
- },
- {
- "location": "/os/core_os/porting/port_os/#board-support-package-bsp-dependency",
- "text": "With all of the functionality provided by the core, MCU, and MCU HAL (Hardware Abstraction Layer), \nthere are still some things that must be specified for your particular system. This\nis provided in Mynewt to allow you the flexibility to design for the exact\nfunctionality, peripherals and features that you require in your product. In Mynewt, these settings/components are included in a Board Support Package\n(BSP). The BSP contains the information specific to running Mynewt on a target\nplatform or hardware board. Mynewt supports some common open source hardware as well\nas the development boards for some common MCUs. These development systems\nmight be enough for you to get your prototype up and running, but when building\na product you are likely going to have your own board which is slightly different\nfrom those already supported by Mynewt. For example, you might decide on your system that 16 Kilobytes of flash space\nin one flash device is reserved for a flash file system. Or on your system\nyou may decide that GPIO pin 5 of the MCU is connected to the system LED. Or\nyou may decide that the OS Tick (the underlying time source for the OS) should\nrun slower than the defaults to conserve battery power. These types of\nbehaviors are specified in the BSP. The information provided in the BSP (what you need to specify to get a\ncomplete executable) can vary depending on the MCU and its underlying core\narchitecture. For example, some MCUs have dedicated pins for UART, SPI etc,\nso there is no configuration required in the BSP when using these peripherals.\nHowever some MCUs have a pin multiplexor that allows the UART to be mapped to\nseveral different pins. For these MCUs, the BSP must specify if and where\nthe UART pins should appear to match the hardware layout of your system. If your BSP is already supported my Mynewt, there is no additional BSP work involved in porting to your platform. \nYou need only set the bsp attribute in your Mynewt target using the newt command tool . If your BSP is not yet supported by Mynewt, you can add support by following the instructions on how to add BSP support to Mynewt",
- "title": "Board Support Package (BSP) Dependency"
- },
- {
- "location": "/os/core_os/porting/port_os/#mcu-dependency",
- "text": "Some OS code depends on the MCU or SoC that the system contains. For example, the MCU may specify \nthe potential memory map of the system - where code and data can reside. If your MCU is already supported by Mynewt, there is no additional MCU work involved in \nporting to your platform. You need only set the arch attribute in your Mynewt target \nusing the newt command tool . If your MCU is not yet supported by Mynewt, you can add support by following the \ninstructions on how to add MCU support to Mynewt",
- "title": "MCU Dependency"
- },
- {
- "location": "/os/core_os/porting/port_os/#mcu-hardware-abstraction-layer-hal",
- "text": "Mynewt's architecture supports a hardware abstraction layer (HAL) for common on or off-chip MCU peripherals \nsuch as GPIO, UARTs, flash memory etc. Even if your MCU is supported for the core OS, \nyou may find that you need to implement the HAL functionality for a new peripheral. \nFor a description of the HAL abstraction and implementation information,\nsee the HAL API",
- "title": "MCU Hardware Abstraction Layer (HAL)"
- },
- {
- "location": "/os/core_os/porting/port_os/#cpu-core-dependency",
- "text": "Some OS code depends on the CPU core that your system is using. For example, a given CPU core \nhas a specific assembly language instruction set, and may require special cross compiler or \ncompiler settings to use the appropriate instruction set. If your CPU architecture is already supported by Mynewt, there is no CPU core work involved \nin porting to your platform. You need only set the arch and compiler attributes in your \nMynewt target using the newt command tool . If your CPU architecture is not supported by Mynewt, you can add support by following the \ninstructions on how to add CPU architecture support to Mynewt",
- "title": "CPU Core Dependency"
- },
- {
- "location": "/os/core_os/porting/port_bsp/",
- "text": "Create a BSP for your Target\n\n\nIntroduction\n\n\nIf you are using a board or system not currently supported by Mynewt, you will need to \ncreate a BSP for the new target. If another similar BSP exists it is recommended to \ncopy that BSP as a starting point. For example, if another BSP exists using the same MCU, \nstart with a copy of that BSP.\n\n\nEither way, this document describes the steps necessary to create a new BSP from scratch. \n\n\nKeep your Reference Documents handy\n\n\nTo build a proper BSP, you will typically need the following:\n\n\n\n\nThe datasheet for the MCU you have chosen\n\n\nThe schematic of your board\n\n\nThe information on the CPU core within your MCU if it is not included in your MCU documentation\n\n\nThis Mynewt documentation\n\n\n\n\nName your BSP\n\n\nSelect a name for your BSP. For the remainder of this document, we'll assume the bsp is named \nmyboard\n. \nIn general its best to select a name that describes the board/system you are creating.\n\n\nCreate a BSP directory\n\n\nCreate a directory \nhw/bsp/myboard\n using the name chosen above. Within this BSP directory, create the following subdirectories:\n\n\n\n\ninclude\n\n\ninclude/bsp\n\n\nsrc\n\n\n\n\nCreate a Target using Mynewt\n\n\nCreate a newt target for your test project for the BSP. To learn how to create a target, \nsee this \nhowto\n \nTutorial\n. Once you are familiar \nwith creating targets, move on below to create a target to use to test your BSP.\n\n\nIt is recommended that you use a simple project like \nblinky\n to minimize the time \nto get a working Mynewt system. For this document, we will assume the \ntarget\n is called \nmyboard_blinky\n \nand uses project \nblinky\n. \n\n\nSet the \nbsp\n of the project to \n/hw/bsp/myboard\n. While creating your target, you will need to \nspecify your \narch\nand \ncompiler\n. If your platform requires an architecture or compiler \nthat are not defined in Mynewt, you will need to add them first. To add a CPU architecture see \nCPU Porting\n.\n\n\nWhen this is complete, your \ntarget\n may look similar to this.\n\n\n \n$\n \nnewt\n \ntarget\n \nshow\n\n \nmyboard_blinky\n\n \narch=cortex_m0\n\n \nbsp=hw/bsp/myboard\n\n \ncompiler=arm-none-eabi-m0\n\n \ncompiler_def=debug\n\n \nname=myboard_blinky\n\n \nproject=blinky\n\n\n\n\n\n\nCreate Required Files For Compilation\n\n\nCreate the following files within the BSP directory tree. For now, they can be empty files. We will fill them out one at a time.\n\n\n\n\n\n\n\n\nFile Path Name\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nLICENSE\n\n\nA File to present the source license for your BSP\n\n\n\n\n\n\nREADME.md\n\n\nA markdown file to write documentation for your BSP\n\n\n\n\n\n\npkg.yml\n\n\nA package file to describe your BSP contents\n\n\n\n\n\n\ninclude/bsp/bsp.h\n\n\nA header file to include definitions required by system from the BSP\n\n\n\n\n\n\ninclude/bsp/bsp_sysid.h\n\n\nA header file to enumerate the devices in your BSP\n\n\n\n\n\n\nsrc/os_bsp.c\n\n\nA C source file to provide functions required by the OS from your BSP\n\n\n\n\n\n\nsrc/sbrk.c\n\n\nA C source file to memory from your heap to the OS\n\n\n\n\n\n\nsrc/libc_stubs.c\n\n\nA C source file to provide stubs/methods required by libc\n\n\n\n\n\n\nmyboard.ld\n\n\nA linker script to provide the memory map for your linked code\n\n\n\n\n\n\n\n\nOptionally, create these files as necessary to provide all functionality from Mynewt.\n\n\n\n\n\n\n\n\nFile Path Name\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmyboard_boot.ld\n\n\nA linker script to provide the memory map for your bootloader\n\n\n\n\n\n\nmyboard_download.sh\n\n\nA bash script to download code into your platform\n\n\n\n\n\n\nmyboard_debug.sh\n\n\nA bash script to intiate a gdb session with your platform\n\n\n\n\n\n\nsrc/hal_bsp.c\n\n\nA C source file to provide functions required by the HAL from your BSP\n\n\n\n\n\n\n\n\nFill Out your Package File\n\n\nEdit the package file to describe your BSP.\n\n\nThe package file must contain:\n\n\n pkg.name: \nhw/bsp/myboard\n\n pkg.linkerscript: \nmyboard.ld\n\n\n\n\n\n\n\n\n\n\n\n\nAttribute\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npkg.name\n\n\nThe name of your bsp package\n\n\n\n\n\n\npkg.linkerscript\n\n\nThe linker script that controls the memory placement of the compiled code sections from the Mynewt OS and your applications.\n\n\n\n\n\n\n\n\nThe linker script is a key component of the BSP and specifies where each section of code and data are \nstored within your CPU which can vary with the BSP depending on your chosen memory layout.\n\nFor a tutorial on writing linker scripts, see \nCreate or Copy Linker Script(s)\n.\n\n\nThe package file typically contains:\n\n\n pkg.linkerscript.bootloader.OVERWRITE: \nmyboard_boot.ld\n\n pkg.downloadscript: \nmyboard_download.sh\n\n pkg.debugscript: \nmyboard_debug.sh\n\n pkg.deps:\n - hw/mcu/mymcu/variant\n\n\n\n\n\nwhere \nmymcu/variant\n should be replaced with the specific MCU and variant used in your design.\n\n\nThe following table describes additional attributes relevant to the BSP \npkg.yml\n file.\n\n\n\n\n\n\n\n\nAttribute\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npkg.linkerscript.bootloader.OVERWRITE\n\n\nA special linker for creating a bootloader for Mynewt\n\n\n\n\n\n\npkg.downloadscript\n\n\nA script that can download a flash image into your target platform\n\n\n\n\n\n\npkg.debugscript\n\n\nA script that can run the GDB debugger on your board\n\n\n\n\n\n\npkg.deps\n\n\nAny dependencies on your BSP\n\n\n\n\n\n\n\n\nThe BSP will invariably depend upon an MCU (in this sample it's \nhw/mcu/mymcu/variant\n) since the \nMynewt OS runs on an MCU within your target. If your MCU is not supported by Mynewt, \nsee \nMCU Porting\n for details on how to create a new MCU in Mynewt.\n\n\nThe package file may also contain:\n\n\n pkg.cflags: -D__MY_SPECIAL_BSP_OPTIONS_\n pkg.deps:\n - libs/cmsis-core\n\n\n\n\n\n\n\n\n\n\n\nAttribute\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npkg.cflags\n\n\nAny specific compiler flags for your bsp\n\n\n\n\n\n\npkg.deps\n\n\nAny other libraries that may be required. Some architectures (like ARM) have special libraries to make BSP creation easier.\n\n\n\n\n\n\n\n\nCreate or Copy Linker Script\n\n\nIt's probably best to start with a linker script from another BSP using the same MCU. If this is not available, \nconsult your MCU documentation and library samples to find a linker script to start with.\n\n\nTypically, a linker script has to specify the following sections for code:\n\n\n\n\n.text -- the location and alignment of the memory section to store your code\n\n\n.data -- the location and alignment of the memory section to store initialized data\n\n\n.bss -- the location and alignment of the memory section to store uninitialized data\n\n\n.heap -- the location and alignment of the memory section to provide system memory\n\n\n\n\nThe linker script should specify the location and size of the different memory regions \nin your BSP and map the code sections described above into these regions. \n\n\nThe linker script should also include an ENTRY point. This is used by the debugger \nto know where to start the program counter when the target is debugged.\n\n\nThere may be additional requirements from the MCU or OS that you may find easiest to \nplace in the linker script. Some specific variables that the OS and MCU depends on are :\n\n\n\n\n\n\n\n\nVariable\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n__bss_start__\n\n\na variable located at the start of the BSS section\n\n\n\n\n\n\n__bss_end__\n\n\na variable located at the end of the BSS section\n\n\n\n\n\n\n__isr_vector\n\n\nSome CPUs map their interrupt vectors. They may need to be specified in the linker\n\n\n\n\n\n\n_user_heap_start\n\n\nthe start of the heap for unallocated memory\n\n\n\n\n\n\n_user_heap_end\n\n\nthe end of the heap for unallocated memory\n\n\n\n\n\n\n\n\nCreate an alternate linker script for the bootloader since it is typically linked to use different addresses to boot the main image. \n\n\nAdd Functions and Defines\n\n\nAt this point, it will be possible to run the \nnewt\n tool to build your target.\n\n\nYou may run into complaints from the linker script that a few Mynewt specific functions are missing. We will describe these below.\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nos_bsp_init()\n\n\ncode to initialize the bsp\n\n\n\n\n\n\nos_bsp_systick_init()\n\n\ncode to setup the system tick for the OS\n\n\n\n\n\n\n\n\nThere are also several libc definitions that can be stubbed in your first BSP. Examples are \n_write\n, \n_read\n, \netc. that can be found in \nlibc_stubs.c\n. But you \nmust\n implement the following function to provide memory to the OS and system.\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n_sbrk\n\n\nReturns memory from heap (used by malloc)\n\n\n\n\n\n\n\n\n\n\nImplement \n_sbrk()\n\n\n\n\nsbrk()\n is required by libc to get memory from the heap for things like malloc. Although not strongly BSP dependent, \nthis is currently in the BSP to allow flexibility in providing system memory. See other BSPs for providing \nsbrk\n functionality.\n\n\n\n\nImplement \nos_bsp_init()\n\n\n\n\nos_bsp_init\n should initialize anything required in the OS by the BSP. Typically this is a very small set. \n\n\nNOTE\n: Currently we are making calls to \n_sbrk()\n and \nclose(0)\n from \nos_bsp_init\n to get around a \nlinker issue where some of libc is not getting included. Please include this in your \nos_bsp_init\n.\n\n\n \n/*\n\n\n * XXX these references are here to keep the functions in for libc to find.\n\n\n */\n\n \n_sbrk\n(\n0\n);\n \n_close\n(\n0\n);\n\n\n\n\n\n\n\nOther Unresolved Defines or Functions\n\n\n\n\nThere may be other unresolved defines or functions that are required by the specific MCU within your BSP. Below lists some sample defines.\n\n\n\n\n\n\n\n\nUndefined Variable\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nCONSOLE_UART_PORT\n\n\nWhich communications port on your target runs the console\n\n\n\n\n\n\nLED_BLINK_PIN\n\n\nwhich pin on your target runs the blinky LED\n\n\n\n\n\n\n\n\nThe set of missing functionality depends upon the libraries and dependencies you have included in the project. \nThat's why its best to keep your first project pretty simple then add incrementally. \nFor example, if you include the Newtron file system, you will need to define a file system map for your BSP.\n\n\nMissing functionality may take the form of \n#define\n items required to compile, or they may take the form of missing functions. \n\n\n\n\ncmsis_nvic.h\n\n\n\n\nIf you are using an ARM cortex architecture, you need to define the number of interrupts supported by your system. \nIf you are not using ARM Cortex architecture this may not be required (but something else might be).\n\n\nAdd Debug Script\n\n\nThe debug script in the bsp directory allows the newt tool to automatically connect to the debugger \nand create a debug session with the target. This requires knowledge of your target debug interface. \nMost of the Mynewt BSP targets use \nopenocd\n to perform debugging. \nThis script typically creates an openocd connection to the target and then connects a gdb instance \nto this openocd connection. There are several examples in existing BSPs to follow.\n\n\nThe script must take a single argument which is the name of the image file minus the '.elf' suffix.\n\n\nThe BSP is complete without this file, but newt will be unable to establish a debug session without it.\n\n\nAdd Download Script\n\n\nSimilar to the debug script, the download script is a hook for newt to download the image to the target system. \nThe download script also typically uses the openocd interface to erase flash and progam the code into the device.\n\n\nNOTE:\n The download script needs to command openocd to program the image into the appropriate location \nwhich is typically called \nFLASH_OFFSET\n in these scripts. This location has to match the linker script \nlocation of the image link address. For example, if your linker links the code to be run at \n0xC000\n your \ndownload script should download the image to the same address in the correct flash. \n\n\nAdd License and Documentation\n\n\nThe \nLICENSE\n file is an ASCII text file that describes the source license for this\npackage.\n\n\nThe \nREADME.md\n is a \nmarkdown\n\n file that contains any documentation you\nwant to provide for the BSP.",
- "title": "BSP Porting"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#create-a-bsp-for-your-target",
- "text": "",
- "title": "Create a BSP for your Target"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#introduction",
- "text": "If you are using a board or system not currently supported by Mynewt, you will need to \ncreate a BSP for the new target. If another similar BSP exists it is recommended to \ncopy that BSP as a starting point. For example, if another BSP exists using the same MCU, \nstart with a copy of that BSP. Either way, this document describes the steps necessary to create a new BSP from scratch.",
- "title": "Introduction"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#keep-your-reference-documents-handy",
- "text": "To build a proper BSP, you will typically need the following: The datasheet for the MCU you have chosen The schematic of your board The information on the CPU core within your MCU if it is not included in your MCU documentation This Mynewt documentation",
- "title": "Keep your Reference Documents handy"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#name-your-bsp",
- "text": "Select a name for your BSP. For the remainder of this document, we'll assume the bsp is named myboard . \nIn general its best to select a name that describes the board/system you are creating.",
- "title": "Name your BSP"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#create-a-bsp-directory",
- "text": "Create a directory hw/bsp/myboard using the name chosen above. Within this BSP directory, create the following subdirectories: include include/bsp src",
- "title": "Create a BSP directory"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#create-a-target-using-mynewt",
- "text": "Create a newt target for your test project for the BSP. To learn how to create a target, \nsee this howto Tutorial . Once you are familiar \nwith creating targets, move on below to create a target to use to test your BSP. It is recommended that you use a simple project like blinky to minimize the time \nto get a working Mynewt system. For this document, we will assume the target is called myboard_blinky \nand uses project blinky . Set the bsp of the project to /hw/bsp/myboard . While creating your target, you will need to \nspecify your arch and compiler . If your platform requires an architecture or compiler \nthat are not defined in Mynewt, you will need to add them first. To add a CPU architecture see CPU Porting . When this is complete, your target may look similar to this. $ newt target show \n myboard_blinky \n arch=cortex_m0 \n bsp=hw/bsp/myboard \n compiler=arm-none-eabi-m0 \n compiler_def=debug \n name=myboard_blinky \n project=blinky",
- "title": "Create a Target using Mynewt"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#create-required-files-for-compilation",
- "text": "Create the following files within the BSP directory tree. For now, they can be empty files. We will fill them out one at a time. File Path Name Description LICENSE A File to present the source license for your BSP README.md A markdown file to write documentation for your BSP pkg.yml A package file to describe your BSP contents include/bsp/bsp.h A header file to include definitions required by system from the BSP include/bsp/bsp_sysid.h A header file to enumerate the devices in your BSP src/os_bsp.c A C source file to provide functions required by the OS from your BSP src/sbrk.c A C source file to memory from your heap to the OS src/libc_stubs.c A C source file to provide stubs/methods required by libc myboard.ld A linker script to provide the memory map for your linked code Optionally, create these files as necessary to provide all functionality from Mynewt. File Path Name Description myboard_boot.ld A linker script to provide the memory map for your bootloader myboard_download.sh A bash script to download code into your platform myboard_debug.sh A bash script to intiate a gdb session with your platform src/hal_bsp.c A C source file to provide functions required by the HAL from your BSP",
- "title": "Create Required Files For Compilation"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#fill-out-your-package-file",
- "text": "Edit the package file to describe your BSP. The package file must contain: pkg.name: hw/bsp/myboard \n pkg.linkerscript: myboard.ld Attribute Description pkg.name The name of your bsp package pkg.linkerscript The linker script that controls the memory placement of the compiled code sections from the Mynewt OS and your applications. The linker script is a key component of the BSP and specifies where each section of code and data are \nstored within your CPU which can vary with the BSP depending on your chosen memory layout. \nFor a tutorial on writing linker scripts, see Create or Copy Linker Script(s) . The package file typically contains: pkg.linkerscript.bootloader.OVERWRITE: myboard_boot.ld \n pkg.downloadscript: myboard_download.sh \n pkg.debugscript: myboard_debug.sh \n pkg.deps:\n - hw/mcu/mymcu/variant where mymcu/variant should be replaced with the specific MCU and variant used in your design. The following table describes additional attributes relevant to the BSP pkg.yml file. Attribute Description pkg.linkerscript.bootloader.OVERWRITE A special linker for creating a bootloader for Mynewt pkg.downloadscript A script that can download a flash image into your target platform pkg.debugscript A script that can run the GDB debugger on your board pkg.deps Any dependencies on your BSP The BSP will invariably depend upon an MCU (in this sample it's hw/mcu/mymcu/variant ) since the \nMynewt OS runs on an MCU within your target. If your MCU is not supported by Mynewt, \nsee MCU Porting for details on how to create a new MCU in Mynewt. The package file may also contain: pkg.cflags: -D__MY_SPECIAL_BSP_OPTIONS_\n pkg.deps:\n - libs/cmsis-core Attribute Description pkg.cflags Any specific compiler flags for your bsp pkg.deps Any other libraries that may be required. Some architectures (like ARM) have special libraries to make BSP creation easier.",
- "title": "Fill Out your Package File"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#create-or-copy-linker-script",
- "text": "It's probably best to start with a linker script from another BSP using the same MCU. If this is not available, \nconsult your MCU documentation and library samples to find a linker script to start with. Typically, a linker script has to specify the following sections for code: .text -- the location and alignment of the memory section to store your code .data -- the location and alignment of the memory section to store initialized data .bss -- the location and alignment of the memory section to store uninitialized data .heap -- the location and alignment of the memory section to provide system memory The linker script should specify the location and size of the different memory regions \nin your BSP and map the code sections described above into these regions. The linker script should also include an ENTRY point. This is used by the debugger \nto know where to start the program counter when the target is debugged. There may be additional requirements from the MCU or OS that you may find easiest to \nplace in the linker script. Some specific variables that the OS and MCU depends on are : Variable Description __bss_start__ a variable located at the start of the BSS section __bss_end__ a variable located at the end of the BSS section __isr_vector Some CPUs map their interrupt vectors. They may need to be specified in the linker _user_heap_start the start of the heap for unallocated memory _user_heap_end the end of the heap for unallocated memory Create an alternate linker script for the bootloader since it is typically linked to use different addresses to boot the main image.",
- "title": "Create or Copy Linker Script"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#add-functions-and-defines",
- "text": "At this point, it will be possible to run the newt tool to build your target. You may run into complaints from the linker script that a few Mynewt specific functions are missing. We will describe these below. Function Description os_bsp_init() code to initialize the bsp os_bsp_systick_init() code to setup the system tick for the OS There are also several libc definitions that can be stubbed in your first BSP. Examples are _write , _read , \netc. that can be found in libc_stubs.c . But you must implement the following function to provide memory to the OS and system. Function Description _sbrk Returns memory from heap (used by malloc) Implement _sbrk() sbrk() is required by libc to get memory from the heap for things like malloc. Although not strongly BSP dependent, \nthis is currently in the BSP to allow flexibility in providing system memory. See other BSPs for providing sbrk functionality. Implement os_bsp_init() os_bsp_init should initialize anything required in the OS by the BSP. Typically this is a very small set. NOTE : Currently we are making calls to _sbrk() and close(0) from os_bsp_init to get around a \nlinker issue where some of libc is not getting included. Please include this in your os_bsp_init . /* * XXX these references are here to keep the functions in for libc to find. */ \n _sbrk ( 0 );\n _close ( 0 ); Other Unresolved Defines or Functions There may be other unresolved defines or functions that are required by the specific MCU within your BSP. Below lists some sample defines. Undefined Variable Description CONSOLE_UART_PORT Which communications port on your target runs the console LED_BLINK_PIN which pin on your target runs the blinky LED The set of missing functionality depends upon the libraries and dependencies you have included in the project. \nThat's why its best to keep your first project pretty simple then add incrementally. \nFor example, if you include the Newtron file system, you will need to define a file system map for your BSP. Missing functionality may take the form of #define items required to compile, or they may take the form of missing functions. cmsis_nvic.h If you are using an ARM cortex architecture, you need to define the number of interrupts supported by your system. \nIf you are not using ARM Cortex architecture this may not be required (but something else might be).",
- "title": "Add Functions and Defines"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#add-debug-script",
- "text": "The debug script in the bsp directory allows the newt tool to automatically connect to the debugger \nand create a debug session with the target. This requires knowledge of your target debug interface. \nMost of the Mynewt BSP targets use openocd to perform debugging. \nThis script typically creates an openocd connection to the target and then connects a gdb instance \nto this openocd connection. There are several examples in existing BSPs to follow. The script must take a single argument which is the name of the image file minus the '.elf' suffix. The BSP is complete without this file, but newt will be unable to establish a debug session without it.",
- "title": "Add Debug Script"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#add-download-script",
- "text": "Similar to the debug script, the download script is a hook for newt to download the image to the target system. \nThe download script also typically uses the openocd interface to erase flash and progam the code into the device. NOTE: The download script needs to command openocd to program the image into the appropriate location \nwhich is typically called FLASH_OFFSET in these scripts. This location has to match the linker script \nlocation of the image link address. For example, if your linker links the code to be run at 0xC000 your \ndownload script should download the image to the same address in the correct flash.",
- "title": "Add Download Script"
- },
- {
- "location": "/os/core_os/porting/port_bsp/#add-license-and-documentation",
- "text": "The LICENSE file is an ASCII text file that describes the source license for this\npackage. The README.md is a markdown \n file that contains any documentation you\nwant to provide for the BSP.",
- "title": "Add License and Documentation"
- },
- {
- "location": "/os/core_os/porting/port_mcu/",
- "text": "Porting Mynewt to a new MCU\n\n\nPorting Mynewt to a new MCU is not a difficult task if the core CPU architectures is already supported.\n\n\nThe depth of work depends on the amount of HAL (Hardware Abstraction Layer) support you need and provide in your port.\n\n\nTo get started:\n\n\n\n\nCreate a \nhw/mcu/mymcu\n directory where \nmymcu\n is the MCU you are porting to. \nReplace the name \nmymcu\n with a description of the MCU you are using.\n\n\nCreate a \nhw/mcu/mymcu/variant\n directory where the variant is the specific \nvariant of the part you are usuing. Many MCU parts have variants with different capabilities \n(RAM, FLASH etc) or different pinouts. Replace \nvariant\n with a description of the variant of the part you are using.\n\n\nCreate a \nhw/mcu/mymcu/variant/pkg.yml\n file. Copy from another mcu and fill out the relevant information\n\n\nCreate \nhw/mcu/mymcu/variant/include\n,\nhw/mcu/mymcu/variant/include/mcu\n, and \n\nhw/mcu/mymcu/variant/src\n directories to contain the code for your mcu.\n\n\n\n\nAt this point there are two main tasks to complete.\n\n\n\n\nImplement any OS-specific code required by the OS\n\n\nImplement the HAL functionality that you are looking for\n\n\n\n\nPlease contact the Mynewt development list for help and advice porting to new MCU.",
- "title": "MCU Porting"
- },
- {
- "location": "/os/core_os/porting/port_mcu/#porting-mynewt-to-a-new-mcu",
- "text": "Porting Mynewt to a new MCU is not a difficult task if the core CPU architectures is already supported. The depth of work depends on the amount of HAL (Hardware Abstraction Layer) support you need and provide in your port. To get started: Create a hw/mcu/mymcu directory where mymcu is the MCU you are porting to. \nReplace the name mymcu with a description of the MCU you are using. Create a hw/mcu/mymcu/variant directory where the variant is the specific \nvariant of the part you are usuing. Many MCU parts have variants with different capabilities \n(RAM, FLASH etc) or different pinouts. Replace variant with a description of the variant of the part you are using. Create a hw/mcu/mymcu/variant/pkg.yml file. Copy from another mcu and fill out the relevant information Create hw/mcu/mymcu/variant/include , hw/mcu/mymcu/variant/include/mcu , and hw/mcu/mymcu/variant/src directories to contain the code for your mcu. At this point there are two main tasks to complete. Implement any OS-specific code required by the OS Implement the HAL functionality that you are looking for Please contact the Mynewt development list for help and advice porting to new MCU.",
- "title": "Porting Mynewt to a new MCU"
- },
- {
- "location": "/os/core_os/porting/port_cpu/",
- "text": "Porting Mynewt to a new CPU Architecture\n\n\nA new CPU architecture typically requires the following:\n\n\n\n\nA new compiler\n\n\nNew architecture-specific code for the OS\n\n\nHelper libraries to help others porting to the same architecture\n\n\n\n\nThese are discussed below:\n\n\nCreate A New Compiler\n\n\nNOTE: Newt does not automatically install the compilers require to build all platforms. \nIt's up to the user using their local machines package manager to install the compilers. \nThe steps described here just registers the compiler with newt. \n\n\nCreate a new directory (named after the compiler you are adding). Copy the \npkg.yml\n file from another compiler. \n\n\nEdit the \npkg.yml\n file and change the configuration attributes to match your compiler. \nMost are self-explanatory paths to different compiler and linker tools. There are a few configuration attributes worth noting.\n\n\n\n\n\n\n\n\nConfiguration Attributes\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npkg.keywords\n\n\nSpecific keywords to help others search for this using newt\n\n\n\n\n\n\ncompiler.flags.default\n\n\ndefault compiler flags for this architecture\n\n\n\n\n\n\ncompiler.flags.optimized\n\n\nadditional flags when the newt tool builds an optimized image\n\n\n\n\n\n\ncompiler.flags.debug\n\n\nadditional flags when the newt tool builds a debug image\n\n\n\n\n\n\n\n\nImplement Architecture-specific OS code\n\n\nThere are several architecture-specific code functions that are required when implementing a \nnew architecture. You can find examples in the \nsim\n architecture within Mynewt.\n\n\nWhen porting to a new CPU architecture, use the existing architectures as samples when writing your implementation.\n\n\nPlease contact the Mynewt development list for help and advice portingto new MCU.",
- "title": "CPU Porting"
- },
- {
- "location": "/os/core_os/porting/port_cpu/#porting-mynewt-to-a-new-cpu-architecture",
- "text": "A new CPU architecture typically requires the following: A new compiler New architecture-specific code for the OS Helper libraries to help others porting to the same architecture These are discussed below:",
- "title": "Porting Mynewt to a new CPU Architecture"
- },
- {
- "location": "/os/core_os/porting/port_cpu/#create-a-new-compiler",
- "text": "NOTE: Newt does not automatically install the compilers require to build all platforms. \nIt's up to the user using their local machines package manager to install the compilers. \nThe steps described here just registers the compiler with newt. Create a new directory (named after the compiler you are adding). Copy the pkg.yml file from another compiler. Edit the pkg.yml file and change the configuration attributes to match your compiler. \nMost are self-explanatory paths to different compiler and linker tools. There are a few configuration attributes worth noting. Configuration Attributes Description pkg.keywords Specific keywords to help others search for this using newt compiler.flags.default default compiler flags for this architecture compiler.flags.optimized additional flags when the newt tool builds an optimized image compiler.flags.debug additional flags when the newt tool builds a debug image",
- "title": "Create A New Compiler"
- },
- {
- "location": "/os/core_os/porting/port_cpu/#implement-architecture-specific-os-code",
- "text": "There are several architecture-specific code functions that are required when implementing a \nnew architecture. You can find examples in the sim architecture within Mynewt. When porting to a new CPU architecture, use the existing architectures as samples when writing your implementation. Please contact the Mynewt development list for help and advice portingto new MCU.",
- "title": "Implement Architecture-specific OS code"
- },
- {
- "location": "/os/modules/console/console/",
- "text": "Console\n\n\nThe console is an operating system window where users interact with the OS subsystems or a console \napplication. A user typically inputs text from a keyboard and reads the OS output text on a computer\nmonitor. The text are sent as a sequence of characters between the user and the OS. \n\n\nSupport is currently available for console access via the serial port on the hardware board.\n\n\nDescription\n\n\nIn the Mynewt OS, the console library comes in three versions:\n\n\n\n\nThe \nsys/console/full\n package implements the complete console functionality and API.\n\n\nThe \nsys/console/stub\n package implements stubs for the API.\n\n\nThe \nsys/console/minimal\n package implements minimal console functionality of reading from and writing to console. It implements the \nconsole_read()\n and \nconsole_write()\n functions and stubs for all the other console functions.\n\n\n\n\nAll the packages export the \nconsole\n API, and any package that uses the console API must list \nconsole\n as a requirement its \npkg.yml\n file: \n\n\npkg.name: sys/shell\npkg.deps:\n - kernel/os\n - encoding/base64\n - time/datetime\n - util/crc\npkg.req_apis:\n - console\n\n\n\n\n\n\nThe project \npkg.yml\n file also specifies the version of the console package to use.\n\n\n\n\nUsing the Full Console Package\n\n\nA project that requires the full console capability must list the \nsys/console/full\n package as a dependency in its \npkg.yml\n file.\n\n\nAn example is the \nslinky\n application. It requires the full console capability and has the following\n\npkg.yml\n file: \n\n\npkg.name: apps/slinky\npkg.deps:\n - test/flash_test\n - mgmt/imgmgr\n - mgmt/newtmgr\n - mgmt/newtmgr/transport/nmgr_shell\n - kernel/os\n - boot/bootutil\n - sys/shell\n - sys/console/full\n ...\n - sys/id\n\n\n\n\n\n\n\nUsing the Stub Console Package\n\n\nA project that uses console stub API must list the \nsys/console/stub\n package as a dependency in its \npkg.yml\n file.\n\n\nExamples of when a project would use the console stubs might be:\n\n\n\n\nA project may not have a physical console (e.g. a UART port to connect a terminal to) \nbut may have a dependency on a package that has console capability. \n\n\nA bootloader project where we want to keep the size of the image small. It includes \nthe \nkernel/os\n package that can print out messages on a console (e.g. if there is a hard fault).\nHowever, we do not want to use any console I/O capability in this particular bootloader project to \nkeep the size small. \n\n\n\n\nThe project would use the console stub API and has the following \npkg.yml\n file: \n\n\npkg.name: apps/boot\npkg.deps:\n - boot/bootutil\n - kernel/os\n - sys/console/stub\n\n\n\n\n\n\n\nUsing the Minimal Console Package\n\n\nThere might be projects that need to read and write data on a serial connection but do not need the full console capability. An example might be a project that supports serial image upgrade but does not need full newtmgr capability. The project would use the console minimal API and has the following \npkg.yml\n file: \n\n\npkg.name: apps/boot\npkg.type: app\npkg.description: Boot loader application.\npkg.author: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n - loader\n\npkg.deps:\n - boot/bootutil\n - kernel/os\n - sys/console/stub\n\npkg.deps.BOOT_SERIAL.OVERWRITE:\n - sys/console/minimal\n - boot/boot_serial\n\n\n\n\n\n\nConsole has 2 modes for transmit; \nblocking mode\n and \nnon-blocking mode\n. Usually the \nnon-blocking mode\n is the \nactive one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added \nbased on these interrupts.\n\n\nBlocking mode\n is used when we don't want TX completion interrupts. It is used when system crashes, and we still \nwant to output info related to that crash.\n\n\nConsole, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to \nknow that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically.\n\n\nThe Console also has a prompt that is configurable. It is off by default but can be turned on programmatically. The\nprompt character can also be changed by the user.\n\n\nData structures\n\n\nN/A\n\n\nList of Functions\n\n\nThe functions available in console are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconsole_blocking_mode\n\n\nCalls the \nconsole_blocking_tx\n function to flush the buffered console output (transmit) queue.\n\n\n\n\n\n\nconsole_echo\n\n\nControls whether echoing is on or off for the console.\n\n\n\n\n\n\nconsole_init\n\n\nInitialize the console.\n\n\n\n\n\n\nconsole_is_init\n\n\nReturns whether console has been initialized or not.\n\n\n\n\n\n\nconsole_printf\n\n\nWrites a formatted message instead of raw output to the console.\n\n\n\n\n\n\nconsole_read\n\n\nCopies up the to given number of bytes to the input string.\n\n\n\n\n\n\nconsole_write\n\n\nQueues characters to console display over serial port.",
- "title": "toc"
- },
- {
- "location": "/os/modules/console/console/#console",
- "text": "The console is an operating system window where users interact with the OS subsystems or a console \napplication. A user typically inputs text from a keyboard and reads the OS output text on a computer\nmonitor. The text are sent as a sequence of characters between the user and the OS. Support is currently available for console access via the serial port on the hardware board.",
- "title": "Console"
- },
- {
- "location": "/os/modules/console/console/#description",
- "text": "In the Mynewt OS, the console library comes in three versions: The sys/console/full package implements the complete console functionality and API. The sys/console/stub package implements stubs for the API. The sys/console/minimal package implements minimal console functionality of reading from and writing to console. It implements the console_read() and console_write() functions and stubs for all the other console functions. All the packages export the console API, and any package that uses the console API must list console as a requirement its pkg.yml file: pkg.name: sys/shell\npkg.deps:\n - kernel/os\n - encoding/base64\n - time/datetime\n - util/crc\npkg.req_apis:\n - console \nThe project pkg.yml file also specifies the version of the console package to use.",
- "title": "Description"
- },
- {
- "location": "/os/modules/console/console/#using-the-full-console-package",
- "text": "A project that requires the full console capability must list the sys/console/full package as a dependency in its pkg.yml file. An example is the slinky application. It requires the full console capability and has the following pkg.yml file: pkg.name: apps/slinky\npkg.deps:\n - test/flash_test\n - mgmt/imgmgr\n - mgmt/newtmgr\n - mgmt/newtmgr/transport/nmgr_shell\n - kernel/os\n - boot/bootutil\n - sys/shell\n - sys/console/full\n ...\n - sys/id",
- "title": "Using the Full Console Package"
- },
- {
- "location": "/os/modules/console/console/#using-the-stub-console-package",
- "text": "A project that uses console stub API must list the sys/console/stub package as a dependency in its pkg.yml file. Examples of when a project would use the console stubs might be: A project may not have a physical console (e.g. a UART port to connect a terminal to) \nbut may have a dependency on a package that has console capability. A bootloader project where we want to keep the size of the image small. It includes \nthe kernel/os package that can print out messages on a console (e.g. if there is a hard fault).\nHowever, we do not want to use any console I/O capability in this particular bootloader project to \nkeep the size small. The project would use the console stub API and has the following pkg.yml file: pkg.name: apps/boot\npkg.deps:\n - boot/bootutil\n - kernel/os\n - sys/console/stub",
- "title": "Using the Stub Console Package"
- },
- {
- "location": "/os/modules/console/console/#using-the-minimal-console-package",
- "text": "There might be projects that need to read and write data on a serial connection but do not need the full console capability. An example might be a project that supports serial image upgrade but does not need full newtmgr capability. The project would use the console minimal API and has the following pkg.yml file: pkg.name: apps/boot\npkg.type: app\npkg.description: Boot loader application.\npkg.author: Apache Mynewt dev@mynewt.incubator.apache.org \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n - loader\n\npkg.deps:\n - boot/bootutil\n - kernel/os\n - sys/console/stub\n\npkg.deps.BOOT_SERIAL.OVERWRITE:\n - sys/console/minimal\n - boot/boot_serial \nConsole has 2 modes for transmit; blocking mode and non-blocking mode . Usually the non-blocking mode is the \nactive one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added \nbased on these interrupts. Blocking mode is used when we don't want TX completion interrupts. It is used when system crashes, and we still \nwant to output info related to that crash. Console, by default, echoes everything it receives back. Terminal programs expect this, and is a way for the user to \nknow that the console is connected and responsive. Whether echoing happens or not can be controlled programmatically. The Console also has a prompt that is configurable. It is off by default but can be turned on programmatically. The\nprompt character can also be changed by the user.",
- "title": "Using the Minimal Console Package"
- },
- {
- "location": "/os/modules/console/console/#data-structures",
- "text": "N/A",
- "title": "Data structures"
- },
- {
- "location": "/os/modules/console/console/#list-of-functions",
- "text": "The functions available in console are: Function Description console_blocking_mode Calls the console_blocking_tx function to flush the buffered console output (transmit) queue. console_echo Controls whether echoing is on or off for the console. console_init Initialize the console. console_is_init Returns whether console has been initialized or not. console_printf Writes a formatted message instead of raw output to the console. console_read Copies up the to given number of bytes to the input string. console_write Queues characters to console display over serial port.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/console/console_blocking_mode/",
- "text": "console_blocking_mode \n\n\nvoid\n \nconsole_blocking_mode\n(\nvoid\n)\n\n\n\n\n\nCalls the \nconsole_blocking_tx\n function to flush the buffered console output (transmit) queue. \nThe function \nOS_ENTER_CRITICAL()\n is called to disable interrupts and \nOS_EXIT_CRITICAL()\n \nis called to enable interrupts back again once the buffer is flushed.\n\n\nArguments\n\n\nNone\n\n\nReturned values\n\n\nN/A\n\n\nExample\n\n\nHere is an example of calling \nconsole_blocking_mode\n and printing crash information from an assert to help debug.\n\n\nvoid\n\n\n_assert_func\n(\nconst\n \nchar\n \n*file\n, \nint\n \nline\n, \nconst\n \nchar\n \n*func\n, \nconst\n \nchar\n \n*e\n)\n{\n \nint\n \nsr\n;\n\n \nOS_ENTER_CRITICAL\n(\nsr\n);\n (\nvoid\n)\nsr\n;\n \nos_die_line\n \n=\n \nline\n;\n \nos_die_module\n \n=\n \nfile\n;\n \nconsole_blocking_mode\n();\n \nconsole_printf\n(\nAssert %s; failed in %s:%d\\n\n, \ne\n \n?\n \ne\n : \n, \nfile\n, \nline\n);\n \nsystem_reset\n();\n}",
- "title": "console_blocking_mode"
- },
- {
- "location": "/os/modules/console/console_blocking_mode/#console_blocking_mode",
- "text": "void console_blocking_mode ( void ) Calls the console_blocking_tx function to flush the buffered console output (transmit) queue. \nThe function OS_ENTER_CRITICAL() is called to disable interrupts and OS_EXIT_CRITICAL() \nis called to enable interrupts back again once the buffer is flushed.",
- "title": " console_blocking_mode "
- },
- {
- "location": "/os/modules/console/console_blocking_mode/#arguments",
- "text": "None",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_blocking_mode/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_blocking_mode/#example",
- "text": "Here is an example of calling console_blocking_mode and printing crash information from an assert to help debug. void _assert_func ( const char *file , int line , const char *func , const char *e )\n{\n int sr ;\n\n OS_ENTER_CRITICAL ( sr );\n ( void ) sr ;\n os_die_line = line ;\n os_die_module = file ;\n console_blocking_mode ();\n console_printf ( Assert %s; failed in %s:%d\\n , e ? e : , file , line );\n system_reset ();\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/console/console_echo/",
- "text": "console_echo \n\n\nvoid\n \nconsole_echo\n(\nint\n \non\n)\n\n\n\n\n\nControls whether echoing is on or off for the console. When echoing is on, all characters received are transmitted back.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\non\n\n\n1 turns on echoing, 0 turns it off\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nNone\n\n\nExample\n\n\nHere is an example where newtmgr protocol handler is controlling whether echoing is on or off. \nNewtmgr\n\nturns echoing off when it is transmitting large chunks of data to a target board.\n\n\nstatic\n \nint\n\n\nnmgr_def_console_echo\n(\nstruct\n \nnmgr_jbuf\n \n*njb\n)\n{\n \nint\n \necho_on\n \n=\n \n1\n;\n \nint\n \nrc\n;\n \nstruct\n \njson_attr_t\n \nattrs\n[\n3\n] \n=\n {\n [\n0\n] \n=\n {\n .\nattribute\n \n=\n \necho\n,\n .\ntype\n \n=\n \nt_integer\n,\n .\naddr\n.\ninteger\n \n=\n \necho_on\n,\n .\nnodefault\n \n=\n \n1\n\n },\n [\n1\n] \n=\n {\n .\nattribute\n \n=\n \nNULL\n\n }\n };\n\n \nrc\n \n=\n \njson_read_object\n(\nnjb-\nnjb_buf\n, \nattrs\n);\n \nif\n (\nrc\n) {\n \nreturn\n \nOS_EINVAL\n;\n }\n\n \nif\n (\necho_on\n) {\n \nconsole_echo\n(\n1\n);\n } \nelse\n {\n \nconsole_echo\n(\n0\n);\n }\n \nreturn\n (\n0\n);\n}",
- "title": "console_echo"
- },
- {
- "location": "/os/modules/console/console_echo/#console_echo",
- "text": "void console_echo ( int on ) Controls whether echoing is on or off for the console. When echoing is on, all characters received are transmitted back.",
- "title": " console_echo "
- },
- {
- "location": "/os/modules/console/console_echo/#arguments",
- "text": "Arguments Description on 1 turns on echoing, 0 turns it off",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_echo/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_echo/#notes",
- "text": "None",
- "title": "Notes"
- },
- {
- "location": "/os/modules/console/console_echo/#example",
- "text": "Here is an example where newtmgr protocol handler is controlling whether echoing is on or off. Newtmgr \nturns echoing off when it is transmitting large chunks of data to a target board. static int nmgr_def_console_echo ( struct nmgr_jbuf *njb )\n{\n int echo_on = 1 ;\n int rc ;\n struct json_attr_t attrs [ 3 ] = {\n [ 0 ] = {\n . attribute = echo ,\n . type = t_integer ,\n . addr . integer = echo_on ,\n . nodefault = 1 \n },\n [ 1 ] = {\n . attribute = NULL \n }\n };\n\n rc = json_read_object ( njb- njb_buf , attrs );\n if ( rc ) {\n return OS_EINVAL ;\n }\n\n if ( echo_on ) {\n console_echo ( 1 );\n } else {\n console_echo ( 0 );\n }\n return ( 0 );\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/console/console_init/",
- "text": "console_init \n\n\nint\n \nconsole_init\n(\nconsole_rx_cb\n \nrx_cb\n)\n\n\n\n\n\nInitializes the console receive buffer and calls hal funtions \nhal_uart_init_cbs\n and \nhal_uart_config\n to \ninitialize the serial port connection and configure it (e.g. baud rate, flow control etc.)\n\n\nCaller registers a function pointer of \ntype void (*console_rx_cb)(int full_line)\n. This function will be \ncalled when the console receives either a) full line of data or b) when RX buffer in console is full. \nNote that this function is most likely getting called from an interrupt context.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nrx_cb\n\n\nFunction pointer, which gets called when input is received.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\nNon-zero if HAL UART function calls fail.\n\n\nExample\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n ....\n\n \n/* Init tasks */\n\n \nshell_task_init\n(\nSHELL_TASK_PRIO\n, \nshell_stack\n, \nSHELL_TASK_STACK_SIZE\n,\n \nSHELL_MAX_INPUT_LEN\n);\n \nconsole_init\n(\nshell_console_rx_cb\n);\n\n ....\n}",
- "title": "console_init"
- },
- {
- "location": "/os/modules/console/console_init/#console_init",
- "text": "int console_init ( console_rx_cb rx_cb ) Initializes the console receive buffer and calls hal funtions hal_uart_init_cbs and hal_uart_config to \ninitialize the serial port connection and configure it (e.g. baud rate, flow control etc.) Caller registers a function pointer of type void (*console_rx_cb)(int full_line) . This function will be \ncalled when the console receives either a) full line of data or b) when RX buffer in console is full. \nNote that this function is most likely getting called from an interrupt context.",
- "title": " console_init "
- },
- {
- "location": "/os/modules/console/console_init/#arguments",
- "text": "Arguments Description rx_cb Function pointer, which gets called when input is received.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_init/#returned-values",
- "text": "Returns 0 on success.\nNon-zero if HAL UART function calls fail.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_init/#example",
- "text": "int main ( int argc , char **argv )\n{\n ....\n\n /* Init tasks */ \n shell_task_init ( SHELL_TASK_PRIO , shell_stack , SHELL_TASK_STACK_SIZE ,\n SHELL_MAX_INPUT_LEN );\n console_init ( shell_console_rx_cb );\n\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/console/console_is_init/",
- "text": "console_is_init \n\n\nint\n \nconsole_is_init\n(\nvoid\n)\n\n\n\n\n\nReturns whether console has been initialized or not. I.e. whether \nconsole_init()\n has been called yet.\n\n\nArguments\n\n\nNone\n\n\nReturned values\n\n\nReturns 1 if console has been initialized. 0 if not.\n\n\nExample\n\n\nstatic\n \nint\n\n\nlog_console_append\n(\nstruct\n \nlog\n \n*log\n, \nvoid\n \n*buf\n, \nint\n \nlen\n)\n{\n ....\n\n \nif\n (\n!console_is_init\n()) {\n \nreturn\n (\n0\n);\n }\n\n \n/* print log entry to console */\n\n ....\n}",
- "title": "console_is_init"
- },
- {
- "location": "/os/modules/console/console_is_init/#console_is_init",
- "text": "int console_is_init ( void ) Returns whether console has been initialized or not. I.e. whether console_init() has been called yet.",
- "title": " console_is_init "
- },
- {
- "location": "/os/modules/console/console_is_init/#arguments",
- "text": "None",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_is_init/#returned-values",
- "text": "Returns 1 if console has been initialized. 0 if not.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_is_init/#example",
- "text": "static int log_console_append ( struct log *log , void *buf , int len )\n{\n ....\n\n if ( !console_is_init ()) {\n return ( 0 );\n }\n\n /* print log entry to console */ \n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/console/console_printf/",
- "text": "console_printf\n\n\nvoid\n \nconsole_printf\n(\nconst\n \nchar\n \n*fmt\n, ...)\n\n\n\n\n\nWrites a formatted message instead of raw output to the console. It first composes a C string containing \nthe text specified as arguments to the function or containing the elements in the variable argument list \npassed to it using \nsnprintf\n or \nvsnprintf\n, respectively. It then uses the function \nconsole_write\n to \noutput the formatted data (messages) on the console.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfmt\n\n\nPointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console.\n\n\n\n\n\n\n...\n\n\nDepending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. \nva_list\n is a special type defined in \n in \nstdarg.h\n.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nWhile \nconsole_printf\n, with its well understood formatting options in C, is more convenient and easy on the \neyes than the raw output of \nconsole_write\n, the associated code size is considerably larger.\n\n\nExample\n\n\nExample #1:\n\n\nchar\n \nadv_data_buf\n[\n32\n];\n\n\nvoid\n\n\ntask\n()\n{\n \nchar\n \nadv_data_buf\n[\n32\n];\n\n \nconsole_printf\n(\n%s\n, \nadv_data_buf\n);\n}\n\n\n\n\n\nExample #2:\n\n\nstruct\n \nexception_frame\n {\n \nuint32_t\n \nr0\n;\n \nuint32_t\n \nr1\n;\n\n\nstruct\n \ntrap_frame\n {\n \nstruct\n \nexception_frame\n \n*ef\n;\n \nuint32_t\n \nr2\n;\n \nuint32_t\n \nr3\n;\n};\n\n\nvoid\n\n\ntask\n(\nstruct\n \ntrap_frame\n \n*tf\n)\n{\n \nconsole_printf\n(\n r0:%8.8x r1:%8.8x\n, \ntf-\nef-\nr0\n, \ntf-\nef-\nr1\n);\n \nconsole_printf\n(\n r8:%8.8x r9:%8.8x\n, \ntf-\nr2\n, \ntf-\nr3\n);\n}",
- "title": "console_printf"
- },
- {
- "location": "/os/modules/console/console_printf/#console_printf",
- "text": "void console_printf ( const char *fmt , ...) Writes a formatted message instead of raw output to the console. It first composes a C string containing \nthe text specified as arguments to the function or containing the elements in the variable argument list \npassed to it using snprintf or vsnprintf , respectively. It then uses the function console_write to \noutput the formatted data (messages) on the console.",
- "title": " console_printf"
- },
- {
- "location": "/os/modules/console/console_printf/#arguments",
- "text": "Arguments Description fmt Pointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console. ... Depending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in in stdarg.h .",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_printf/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_printf/#notes",
- "text": "While console_printf , with its well understood formatting options in C, is more convenient and easy on the \neyes than the raw output of console_write , the associated code size is considerably larger.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/console/console_printf/#example",
- "text": "Example #1: char adv_data_buf [ 32 ]; void task ()\n{\n char adv_data_buf [ 32 ];\n\n console_printf ( %s , adv_data_buf );\n} Example #2: struct exception_frame {\n uint32_t r0 ;\n uint32_t r1 ; struct trap_frame {\n struct exception_frame *ef ;\n uint32_t r2 ;\n uint32_t r3 ;\n}; void task ( struct trap_frame *tf )\n{\n console_printf ( r0:%8.8x r1:%8.8x , tf- ef- r0 , tf- ef- r1 );\n console_printf ( r8:%8.8x r9:%8.8x , tf- r2 , tf- r3 );\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/console/console_read/",
- "text": "console_read \n\n\nint\n \nconsole_read\n(\nchar\n \n*str\n, \nint\n \ncnt\n, \nint\n \n*newline\n)\n\n\n\n\n\nCopies up to \ncnt\n bytes of received data to buffer pointed by \nstr\n. Function tries to break the input into \nseparate lines; once it encounters a newline character, it replaces that with end-of-string and returns.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nstr\n\n\nBuffer where data is copied to.\n\n\n\n\n\n\ncnt\n\n\nMaximum number of characters to copy.\n\n\n\n\n\n\nnewline\n\n\nPointer to an integer variable that is set to 1 when an newline character is received and set to 0 otherwise.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns the number of characters copied. 0 if there was no data\navailable, or if the first received character was '\\n'.\n\n\nExample\n\n\nvoid\n\n\ntask1_loop\n(\nvoid\n \n*arg\n)\n{\n \nstruct\n \nos_event\n \n*ev\n;\n \nchar\n \nrx_msg\n[\n128\n];\n \nint\n \nrx_len\n;\n \nint\n \nnewline\n;\n\n \nwhile\n (\n1\n) {\n \nev\n \n=\n \nos_eventq_get\n(\ntask1_evq\n);\n \nassert\n(\nev\n);\n \nif\n (\nev-\nev_type\n \n==\n \nCONS_EV_TYPE\n) {\n \nrx_len\n \n=\n \nconsole_read\n(\nrx_msg\n, \nsizeof\n(\nrx_msg\n), \nnewline\n);\n \nif\n (\nrx_len\n) {\n \nif\n (\n!strncmp\n(\nrx_msg\n, \nreset\n, \nrx_len\n)) {\n \nassert\n(\n0\n);\n }\n }\n }\n }\n}",
- "title": "console_read"
- },
- {
- "location": "/os/modules/console/console_read/#console_read",
- "text": "int console_read ( char *str , int cnt , int *newline ) Copies up to cnt bytes of received data to buffer pointed by str . Function tries to break the input into \nseparate lines; once it encounters a newline character, it replaces that with end-of-string and returns.",
- "title": " console_read "
- },
- {
- "location": "/os/modules/console/console_read/#arguments",
- "text": "Arguments Description str Buffer where data is copied to. cnt Maximum number of characters to copy. newline Pointer to an integer variable that is set to 1 when an newline character is received and set to 0 otherwise.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_read/#returned-values",
- "text": "Returns the number of characters copied. 0 if there was no data\navailable, or if the first received character was '\\n'.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_read/#example",
- "text": "void task1_loop ( void *arg )\n{\n struct os_event *ev ;\n char rx_msg [ 128 ];\n int rx_len ;\n int newline ;\n\n while ( 1 ) {\n ev = os_eventq_get ( task1_evq );\n assert ( ev );\n if ( ev- ev_type == CONS_EV_TYPE ) {\n rx_len = console_read ( rx_msg , sizeof ( rx_msg ), newline );\n if ( rx_len ) {\n if ( !strncmp ( rx_msg , reset , rx_len )) {\n assert ( 0 );\n }\n }\n }\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/console/console_write/",
- "text": "console_write \n\n\nvoid\n \nconsole_write\n(\nchar\n \n*str\n, \nint\n \ncnt\n)\n\n\n\n\n\nQueues characters to console display over serial port.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*str\n\n\npointer to the character or packet to be transmitted\n\n\n\n\n\n\ncnt\n\n\nnumber of characters in \nstr\n\n\n\n\n\n\n\n\nReturned values\n\n\nN/A\n\n\nExample\n\n\nHere is an example of the function being used in an echo command with a newline at the end.\n\n\nstatic\n \nint\n\n\nshell_echo_cmd\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \ni\n;\n\n \nfor\n (\ni\n \n=\n \n1\n; \ni\n \n \nargc\n; \ni++\n) {\n \nconsole_write\n(\nargv\n[\ni\n], \nstrlen\n(\nargv\n[\ni\n]));\n \nconsole_write\n(\n \n, \nsizeof\n(\n \n)\n-\n1\n);\n }\n \nconsole_write\n(\n\\n\n, \nsizeof\n(\n\\n\n)\n-\n1\n);\n\n \nreturn\n (\n0\n);\n}",
- "title": "console_write"
- },
- {
- "location": "/os/modules/console/console_write/#console_write",
- "text": "void console_write ( char *str , int cnt ) Queues characters to console display over serial port.",
- "title": " console_write "
- },
- {
- "location": "/os/modules/console/console_write/#arguments",
- "text": "Arguments Description *str pointer to the character or packet to be transmitted cnt number of characters in str",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/console/console_write/#returned-values",
- "text": "N/A",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/console/console_write/#example",
- "text": "Here is an example of the function being used in an echo command with a newline at the end. static int shell_echo_cmd ( int argc , char **argv )\n{\n int i ;\n\n for ( i = 1 ; i argc ; i++ ) {\n console_write ( argv [ i ], strlen ( argv [ i ]));\n console_write ( , sizeof ( ) - 1 );\n }\n console_write ( \\n , sizeof ( \\n ) - 1 );\n\n return ( 0 );\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/shell/shell/",
- "text": "Shell\n\n\nThe shell runs above the console and provides two functionalities:\n\n\n\n\nProcesses console input. See the \nEnabling the Console and Shell Tutorial\n for an example of the shell.\n\n\nImplements the \nnewtmgr\n line protocol over serial transport. \n\n\n\n\nThe \nsys/shell\n package implements the shell. The shell uses the OS default event queue \nfor shell events and runs in the context of the main task. An application can, optionally, \nspecify a dedicated event queue for the shell to use.\n\n\nDescription\n\n\n\n\n\n\nThe shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string \ninto tokens and uses the first token to determine the subsystem command handler to call to process the command.\n\n\n\n\n\n\nSubsystems register their command handlers using the \nshell_cmd_register()\n \n function. When shell calls the command handler, it passes the other tokens as arguments.\n\n\n\n\n\n\nA few commands are currently available in the shell - \ntasks\n, \nlog\n, \necho\n, \ndate\n and \nprompt\n.\n\n\n\n\n\n\n\n\n\n\nThe shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are\nsent over the console. The Newtmgr serial transport package (\nmgmt/newtmgr/transport/newtmgr_shell\n) \ncalls the \nshell_nlip_input_register()\n function to register a handler that the shell calls when it \nreceives newtmgr request messages.\n\n\n\n\n\n\n\n\nData structures\n\n\nThis data structure is used in holding information about registered command handlers.\n\n\nstruct\n \nshell_cmd\n {\n \nchar\n \n*sc_cmd\n;\n \nshell_cmd_func_t\n \nsc_cmd_func\n;\n \nSTAILQ_ENTRY\n(\nshell_cmd\n) \nsc_next\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc_cmd\n\n\nCharacter string of the command\n\n\n\n\n\n\nsc_cmd_func\n\n\nPointer to the command handler\n\n\n\n\n\n\nsc_next\n\n\nBookkeeping linkage internal for shell\n\n\n\n\n\n\n\n\nList of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nshell_cmd_register\n\n\nRegisters a handler for incoming console commands.\n\n\n\n\n\n\nshell_nlip_input_register\n\n\nRegisters a handler for incoming newtmgr messages.\n\n\n\n\n\n\nshell_nlip_output\n\n\nQueue outgoing newtmgr message for transmission.\n\n\n\n\n\n\nshell_evq_set\n\n\nSpecifies a dedicated event queue for shell events.",
- "title": "toc"
- },
- {
- "location": "/os/modules/shell/shell/#shell",
- "text": "The shell runs above the console and provides two functionalities: Processes console input. See the Enabling the Console and Shell Tutorial for an example of the shell. Implements the newtmgr line protocol over serial transport. The sys/shell package implements the shell. The shell uses the OS default event queue \nfor shell events and runs in the context of the main task. An application can, optionally, \nspecify a dedicated event queue for the shell to use.",
- "title": "Shell"
- },
- {
- "location": "/os/modules/shell/shell/#description",
- "text": "The shell's first job is to direct incoming commands to other subsystems. It parses the incoming character string \ninto tokens and uses the first token to determine the subsystem command handler to call to process the command. Subsystems register their command handlers using the shell_cmd_register() \n function. When shell calls the command handler, it passes the other tokens as arguments. A few commands are currently available in the shell - tasks , log , echo , date and prompt . The shell's second job is to handle packet framing, encoding, and decoding of newtmgr protocol messages that are\nsent over the console. The Newtmgr serial transport package ( mgmt/newtmgr/transport/newtmgr_shell ) \ncalls the shell_nlip_input_register() function to register a handler that the shell calls when it \nreceives newtmgr request messages.",
- "title": "Description"
- },
- {
- "location": "/os/modules/shell/shell/#data-structures",
- "text": "This data structure is used in holding information about registered command handlers. struct shell_cmd {\n char *sc_cmd ;\n shell_cmd_func_t sc_cmd_func ;\n STAILQ_ENTRY ( shell_cmd ) sc_next ;\n}; Element Description sc_cmd Character string of the command sc_cmd_func Pointer to the command handler sc_next Bookkeeping linkage internal for shell",
- "title": "Data structures"
- },
- {
- "location": "/os/modules/shell/shell/#list-of-functions",
- "text": "The functions available in this OS feature are: Function Description shell_cmd_register Registers a handler for incoming console commands. shell_nlip_input_register Registers a handler for incoming newtmgr messages. shell_nlip_output Queue outgoing newtmgr message for transmission. shell_evq_set Specifies a dedicated event queue for shell events.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/shell/shell_cmd_register/",
- "text": "shell_cmd_register \n\n\nint\n \nshell_cmd_register\n(\nstruct\n \nshell_cmd\n \n*sc\n)\n\n\n\n\n\nRegisters a handler for incoming console commands. Within the structure there is the command string \nand the handler for those commands. Caller must allocate the memory for this structure and keep it around \nas shell links this to its own internal data structures.\n\n\nCommand handler is of type \nint(*shell_cmd_func_t)(int argc, char **argv)\n. Command line arguments \nare passed to it as an array of character pointers.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc\n\n\nStructure containing info about the command.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\nNon-zero on failure.\n\n\nExample\n\n\nstatic\n \nint\n \nfs_ls_cmd\n(\nint\n \nargc\n, \nchar\n \n**argv\n);\n\n\nstatic\n \nstruct\n \nshell_cmd\n \nfs_ls_struct\n \n=\n {\n .\nsc_cmd\n \n=\n \nls\n,\n .\nsc_cmd_func\n \n=\n \nfs_ls_cmd\n\n};\n\n\nvoid\n\n\nfs_cli_init\n(\nvoid\n)\n{\n \nshell_cmd_register\n(\nfs_ls_struct\n);\n ....\n}",
- "title": "shell_cmd_register"
- },
- {
- "location": "/os/modules/shell/shell_cmd_register/#shell_cmd_register",
- "text": "int shell_cmd_register ( struct shell_cmd *sc ) Registers a handler for incoming console commands. Within the structure there is the command string \nand the handler for those commands. Caller must allocate the memory for this structure and keep it around \nas shell links this to its own internal data structures. Command handler is of type int(*shell_cmd_func_t)(int argc, char **argv) . Command line arguments \nare passed to it as an array of character pointers.",
- "title": " shell_cmd_register "
- },
- {
- "location": "/os/modules/shell/shell_cmd_register/#arguments",
- "text": "Arguments Description sc Structure containing info about the command.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/shell/shell_cmd_register/#returned-values",
- "text": "Returns 0 on success.\nNon-zero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/shell/shell_cmd_register/#example",
- "text": "static int fs_ls_cmd ( int argc , char **argv ); static struct shell_cmd fs_ls_struct = {\n . sc_cmd = ls ,\n . sc_cmd_func = fs_ls_cmd \n}; void fs_cli_init ( void )\n{\n shell_cmd_register ( fs_ls_struct );\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/shell/shell_nlip_input_register/",
- "text": "shell_nlip_input_register \n\n\nint\n \nshell_nlip_input_register\n(\nshell_nlip_input_func_t\n \nnf\n, \nvoid\n \n*arg\n)\n\n\n\n\n\nRegisters a handler for incoming newtmgr messages. Shell receives incoming data stream from \nUART and when it detects NLIP frame, it decodes it and passes it on by calling the function \nnf\n.\n\n\nHandler function is of type \nint (*shell_nlip_input_func_t)(struct os_mbuf *m, void *arg)\n. \nShell passes the incoming newtmgr message inside \nos_mbuf\n \nm\n, and \narg\n is the argument that \nwas passed in during handler registration.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnf\n\n\nHandler for incoming newtmgr datagrams.\n\n\n\n\n\n\narg\n\n\nArgument that gets passed to this handler, along with the datagram\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nExample\n\n\nstatic\n \nint\n\n\nnmgr_shell_in\n(\nstruct\n \nos_mbuf\n \n*m\n, \nvoid\n \n*arg\n)\n{\n ....\n}\n\n\nint\n \n\nnmgr_task_init\n(\nuint8_t\n \nprio\n, \nos_stack_t\n \n*stack_ptr\n, \nuint16_t\n \nstack_len\n)\n{\n \nint\n \nrc\n;\n ....\n \nrc\n \n=\n \nshell_nlip_input_register\n(\nnmgr_shell_in\n, \n (\nvoid\n \n*\n) \ng_nmgr_shell_transport\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \ngoto\n \nerr\n;\n }\n ....\n}",
- "title": "shell_nlip_input_register"
- },
- {
- "location": "/os/modules/shell/shell_nlip_input_register/#shell_nlip_input_register",
- "text": "int shell_nlip_input_register ( shell_nlip_input_func_t nf , void *arg ) Registers a handler for incoming newtmgr messages. Shell receives incoming data stream from \nUART and when it detects NLIP frame, it decodes it and passes it on by calling the function nf . Handler function is of type int (*shell_nlip_input_func_t)(struct os_mbuf *m, void *arg) . \nShell passes the incoming newtmgr message inside os_mbuf m , and arg is the argument that \nwas passed in during handler registration.",
- "title": " shell_nlip_input_register "
- },
- {
- "location": "/os/modules/shell/shell_nlip_input_register/#arguments",
- "text": "Arguments Description nf Handler for incoming newtmgr datagrams. arg Argument that gets passed to this handler, along with the datagram",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/shell/shell_nlip_input_register/#returned-values",
- "text": "Returns 0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/shell/shell_nlip_input_register/#example",
- "text": "static int nmgr_shell_in ( struct os_mbuf *m , void *arg )\n{\n ....\n} int nmgr_task_init ( uint8_t prio , os_stack_t *stack_ptr , uint16_t stack_len )\n{\n int rc ;\n ....\n rc = shell_nlip_input_register ( nmgr_shell_in , \n ( void * ) g_nmgr_shell_transport );\n if ( rc != 0 ) {\n goto err ;\n }\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/shell/shell_nlip_output/",
- "text": "shell_nlip_output \n\n\nint\n \nshell_nlip_output\n(\nstruct\n \nos_mbuf\n \n*m\n)\n\n\n\n\n\nQueue outgoing newtmgr message for transmission. Shell package will encode this and frame it while sending it out via console.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nm\n\n\nos_mbuf containing the message\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success.\n\n\nExample\n\n\nstatic\n \nint\n \n\nnmgr_shell_out\n(\nstruct\n \nnmgr_transport\n \n*nt\n, \nstruct\n \nos_mbuf\n \n*m\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nshell_nlip_output\n(\nm\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \ngoto\n \nerr\n;\n }\n\n \nreturn\n (\n0\n);\n\nerr\n:\n \nreturn\n (\nrc\n);\n}",
- "title": "shell_nlip_output"
- },
- {
- "location": "/os/modules/shell/shell_nlip_output/#shell_nlip_output",
- "text": "int shell_nlip_output ( struct os_mbuf *m ) Queue outgoing newtmgr message for transmission. Shell package will encode this and frame it while sending it out via console.",
- "title": " shell_nlip_output "
- },
- {
- "location": "/os/modules/shell/shell_nlip_output/#arguments",
- "text": "Arguments Description m os_mbuf containing the message",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/shell/shell_nlip_output/#returned-values",
- "text": "Returns 0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/shell/shell_nlip_output/#example",
- "text": "static int nmgr_shell_out ( struct nmgr_transport *nt , struct os_mbuf *m )\n{\n int rc ;\n\n rc = shell_nlip_output ( m );\n if ( rc != 0 ) {\n goto err ;\n }\n\n return ( 0 ); err :\n return ( rc );\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/shell/shell_evq_set/",
- "text": "shell_evq_set\n\n\nvoid\n \nshell_evq_set\n(\nstruct\n \nos_eventq\n \n*evq\n)\n\n\n\n\n\nSpecifies an event queue to use for shell events. You must create the event queue \nand the task to process events from the queue before calling this function. \n\n\nBy default, shell uses the OS default event queue and executes in the context\nof the main task that Mynewt creates.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nevq\n\n\nPointer to the event queue to use for shell events.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes",
- "title": "shell_evq_set"
- },
- {
- "location": "/os/modules/shell/shell_evq_set/#shell_evq_set",
- "text": "void shell_evq_set ( struct os_eventq *evq ) Specifies an event queue to use for shell events. You must create the event queue \nand the task to process events from the queue before calling this function. By default, shell uses the OS default event queue and executes in the context\nof the main task that Mynewt creates.",
- "title": " shell_evq_set"
- },
- {
- "location": "/os/modules/shell/shell_evq_set/#arguments",
- "text": "Arguments Description evq Pointer to the event queue to use for shell events.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/shell/shell_evq_set/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/shell/shell_evq_set/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/split/split/",
- "text": "Split Images\n\n\nDescription\n\n\nThe split image mechanism divides a target into two separate images: one\ncapable of image upgrade; the other containing application code. By isolating\nupgrade functionality to a separate image, the application can support\nover-the-air upgrade without dedicating flash space to network stack and\nmanagement code. \n\n\nConcept\n\n\nMynewt supports three image setups:\n\n\n\n\n\n\n\n\nSetup\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nSingle\n\n\nOne large image; upgrade not supported.\n\n\n\n\n\n\nUnified\n\n\nTwo standalone images.\n\n\n\n\n\n\nSplit\n\n\nKernel in slot 0; application in slot 1.\n\n\n\n\n\n\n\n\nEach setup has its tradeoffs. The Single setup gives you the most flash space,\nbut doesn't allow you to upgrade after manufacturing. The Unified setup allows\nfor a complete failover in case a bad image gets uploaded, but requires a lot\nof redundancy in each image, limiting the amount of flash available to the\napplication. The Split setup sits somewhere between these two options.\n\n\nBefore exploring the split setup in more detail, it might be helpful to get a\nbasic understanding of the Mynewt boot sequence. The boot process is\nsummarized below.\n\n\nBoot Sequence - Single\n\n\nIn the Single setup, there is no boot loader. Instead, the image is placed at\naddress 0. The hardware boots directly into the image code. Upgrade is not\npossible because there is no boot loader to move an alternate image into place.\n\n\nBoot Sequence - Unified\n\n\nIn the Unified setup, the boot loader is placed at address 0. At startup, the\nboot loader arranges for the correct image to be in image slot 0, which may\nentail swapping the contents of the two image slots. Finally, the boot loader\njumps to the image in slot 0.\n\n\nBoot Sequence - Split\n\n\nThe Split setup differs from the other setups mainly in that a target is not\nfully contained in a single image. Rather, the target is partitioned among two\nseparate images: the \nloader\n, and the \napplication\n. Functionality is divided\namong these two images as follows:\n\n\n\n\n\n\nLoader: \n\n\n\n\nMynewt OS.\n\n\nNetwork stack for connectivity during upgrade e.g. BLE stack.\n\n\nAnything else required for image upgrade.\n\n\n\n\n\n\n\n\nApplication:\n\n\n\n\nParts of Mynewt not required for image upgrade.\n\n\nApplication-specific code.\n\n\n\n\n\n\n\n\nThe loader image serves three purposes:\n\n\n\n\nSecond-stage boot loader:\n it jumps into the application image at\n start up.\n\n\nImage upgrade server:\n the user can upgrade to a new loader + application\n combo, even if an application image is not currently running.\n\n\nFunctionality container:\n the application image can directly access all the\n code present in the loader image\n\n\n\n\nFrom the perspective of the boot loader, a loader image is identical to a plain\nunified image. What makes a loader image different is a change to its start up\nsequence: rather than starting the Mynewt OS, it jumps to the application image\nin slot 1 if one is present.\n\n\nTutorial\n\n\nBuilding a Split Image\n\n\nWe will be referring to the nRF51dk for examples in this document. Let's take\na look at this board's flash map (defined in \nhw/bsp/nrf51dk/bsp.yml\n):\n\n\n\n\n\n\n\n\nName\n\n\nOffset\n\n\nSize (kB)\n\n\n\n\n\n\n\n\n\n\nBoot loader\n\n\n0x00000000\n\n\n16\n\n\n\n\n\n\nReboot log\n\n\n0x00004000\n\n\n16\n\n\n\n\n\n\nImage slot 0\n\n\n0x00008000\n\n\n110\n\n\n\n\n\n\nImage slot 1\n\n\n0x00023800\n\n\n110\n\n\n\n\n\n\nImage scratch\n\n\n0x0003f000\n\n\n2\n\n\n\n\n\n\nFlash file system\n\n\n0x0003f800\n\n\n2\n\n\n\n\n\n\n\n\nThe application we will be building is \nbleprph\n.\nFirst, we create a target to tie our BSP and application together.\n\n\nnewt target create bleprph-nrf51dk\nnewt target set bleprph-nrf51dk \\\n app=@apache-mynewt-core/apps/bleprph \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nThe two syscfg settings disable bluetooth security and keep the code size down.\n\n\nWe can verify the target using the \ntarget show\n command:\n\n\n[~/tmp/myproj2]$ newt target show bleprph-nrf51dk\ntargets/bleprph-nrf51dk\n app=@apache-mynewt-core/apps/bleprph\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nNext, build the target:\n\n\n[~/tmp/myproj2]$ newt build bleprph-nrf51dk\nBuilding target targets/bleprph-nrf51dk\n# [...]\nTarget successfully built: targets/bleprph-nrf51dk\n\n\n\n\n\nWith our target built, we can view a code size breakdown using the \nnewt size \ntarget\n command. In the interest of brevity, the smaller entries are excluded from the below output:\n\n\n[~/tmp/myproj2]$ newt size bleprph-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 2959 697 hw_drivers_nimble_nrf51.a\n 4126 108 hw_mcu_nordic_nrf51xxx.a\n 8161 4049 kernel_os.a\n 2254 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1499 44 mgmt_newtmgr_nmgr_os.a\n 23918 1930 net_nimble_controller.a\n 28537 2779 net_nimble_host.a\n 2207 205 sys_config.a\n 1074 197 sys_console_full.a\n 3268 97 sys_log.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf\n\n\n\n\n\nThe full image text size is about 103kB (where 1kB = 1024 bytes). With an image slot size of 110kB,\nthis leaves only about 7kB of flash for additional application code and data.\nNot good. This is the situation we would be facing if we were using the\nUnified setup.\n\n\nThe Split setup can go a long way in solving our problem. Our unified bleprph\nimage consists mostly of components that get used during an image upgrade. By\nusing the Split setup, we turn the unified image into two separate images: the\nloader and the application. The functionality related to image upgrade can be\ndelegated to the loader image, freeing up a significant amount of flash in the\napplication image slot.\n\n\nLet's create a new target to use with the Split setup. We designate a target\nas a split target by setting the \nloader\n variable. In our example, we are\ngoing to use \nbleprph\n as the loader, and \nsplitty\n as the application.\n\nbleprph\n makes sense as a loader because it contains the BLE stack and\neverything else required for an image upgrade.\n\n\nnewt target create split-nrf51dk\nnewt target set split-nrf51dk \\\n loader=@apache-mynewt-core/apps/bleprph \\\n app=@apache-mynewt-core/apps/splitty \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nVerify that the target looks correct:\n\n\n[~/tmp/myproj2]$ newt target show split-nrf51dk\ntargets/split-nrf51dk\n app=@apache-mynewt-core/apps/splitty\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n loader=@apache-mynewt-core/apps/bleprph\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0\n\n\n\n\n\nNow, let's build the new target:\n\n\n[~/tmp/myproj2]$ newt build split-nrf51dk\nBuilding target targets/split-nrf51dk\n# [...]\nTarget successfully built: targets/split-nrf51dk\n\n\n\n\n\nAnd look at the size breakdown (again, smaller entries are removed):\n\n\n[~/tmp/myproj2]$ newt size split-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 3064 251 sys_shell.a\n\nobjsize\n text data bss dec hex filename\n 4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf\n\nSize of Loader Image: loader\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 3168 705 hw_drivers_nimble_nrf51.a\n 4318 109 hw_mcu_nordic_nrf51xxx.a\n 8285 4049 kernel_os.a\n 2274 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1491 44 mgmt_newtmgr_nmgr_os.a\n 25169 1946 net_nimble_controller.a\n 31397 2827 net_nimble_host.a\n 2259 205 sys_config.a\n 1318 202 sys_console_full.a\n 3424 97 sys_log.a\n 1053 60 sys_stats.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf\n\n\n\n\n\nThe size command shows two sets of output: one for the application, and another\nfor the loader. The addition of the split functionality did make bleprph\nslightly bigger, but notice how small the application is: 4.5 kB! Where before\nwe only had 7 kB left, now we have 105.5 kB. Furthermore, all the\nfunctionality in the loader is available to the application at any time. For\nexample, if your application needs bluetooth functionality, it can use the BLE\nstack present in the loader instead of containing its own copy.\n\n\nFinally, let's deploy the split image to our nRF51dk board. The procedure here\nis the same as if we were using the Unified setup, i.e., via either the \nnewt load\n or \nnewt run\n command.\n\n\n[~/repos/mynewt/core]$ newt load split-nrf51dk 0\nLoading app image into slot 2\nLoading loader image into slot 1\n\n\n\n\n\nImage Management\n\n\nRetrieve Current State (image list)\n\n\nImage management in the split setup is a bit more complicated than in the\nunified setup. You can determine a device's image management state with the\n\nnewtmgr image list\n command. Here is how a device responds to this command\nafter our loader + application combo has been deployed:\n\n\n[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags:\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching\n\n\n\n\n\nThere are several interesting things about this response:\n\n\n\n\nTwo images:\n This is expected; we deployed both a loader image and an\napplication image.\n\n\nbootable flag:\n Notice slot 0's bootable flag is set, while slot 1's is\nnot. This tells us that slot 0 contains a loader and slot 1 contains an\napplication. If an image is bootable, it can be booted directly from the boot\nloader. Non-bootable images can only be started from a loader image.\n\n\nflags:\n Slot 0 is \nactive\n and \nconfirmed\n; none of slot 1's flags are set.\nThe \nactive\n flag indicates that the image is currently running; the\n\nconfirmed\n flag indicates that the image will continue to be used on\nsubsequent reboots. Slot 1's lack of enabled flags indicates that the image is\nnot being used at all.\n\n\nSplit status:\n The split status field tells you if the loader and\napplication are compatible. A loader + application combo is compatible only if\nboth images were built at the same time with \nnewt\n. If the loader and\napplication are not compatible, the loader will not boot into the application.\n\n\n\n\nEnabling a Split Application\n\n\nBy default, the application image in slot 1 is disabled. This is indicated in\nthe \nimage list\n response above. When you deploy a loader / application combo\nto your device, the application image won't actually run. Instead, the loader\nwill act as though an application image is not present and remain in \"loader\nmode\". Typically, a device in loader mode simply acts as an image management\nserver, listening for an image upgrade or a request to activate the application\nimage.\n\n\nUse the following command sequence to enable the split application image:\n\n\n\n\nTell device to \"test out\" the application image on next boot (\nnewtmgr image test \napplication-image-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change permanent (\nnewtmgr image confirm\n).\n\n\n\n\nAfter the above sequence, a \nnewtmgr image list\n command elicits the following response:\n\n\n[~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags: active confirmed\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching\n\n\n\n\n\nThe \nactive confirmed\n flags value on both slots indicates that both images are\npermanently running.\n\n\nImage Upgrade\n\n\nFirst, let's review of the image upgrade process for the Unified setup. The\nuser upgrades to a new image in this setup with the following steps:\n\n\nImage Upgrade - Unified\n\n\n\n\nUpload new image to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new image on next boot (\nnewtmgr image test \nimage-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake new image permanent (\nnewtmgr image confirm\n).\n\n\n\n\nImage Upgrade - Split\n\n\nThe image upgrade process is a bit more complicated in the Split setup. It is\nmore complicated because two images need to be upgraded (loader and\napplication) rather than just one. The split upgrade process is described\nbelow:\n\n\n\n\nDisable split functionality; we need to deactivate the application image in\n slot 1 (\nnewtmgr image test \ncurrent-loader-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change permanent (\nnewtmgr image confirm\n).\n\n\nUpload new loader to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new loader on next boot (\nnewtmgr image test \nnew-loader-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change of loader permanent (\nnewtmgr image confirm\n).\n\n\nUpload new application to slot 1 (\nnewtmgr image upload \nfilename\n).\n\n\nTell device to \"test out\" the new application on next boot (\nnewtmgr image test \nnew-application-hash\n).\n\n\nReboot device (\nnewtmgr reset\n).\n\n\nMake above change of application permanent (\nnewtmgr image confirm\n).\n\n\n\n\nWhen performing this process manually, it may be helpful to use \nimage list\n to\ncheck the image management state as you go.\n\n\nSyscfg\n\n\nSyscfg is Mynewt's system-wide configuration mechanism. In a split setup,\nthere is a single umbrella syscfg configuration that applies to both the loader\nand the application. Consequently, overriding a value in an application-only\npackage potentially affects the loader (and vice-versa).\n\n\nLoaders\n\n\nThe following applications have been enabled as loaders. You may choose to\nbuild your own loader application, and these can serve as samples.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/bleprph\n\n\n\n\nSplit Apps\n\n\nThe following applications have been enabled as split applications. If you\nchoose to build your own split application these can serve as samples. Note\nthat slinky can be either a loader image or an application image.\n\n\n\n\n@apache-mynewt-core/apps/slinky\n\n\n@apache-mynewt-core/apps/splitty\n\n\n\n\nTheory of Operation\n\n\nA split image is built as follows:\n\n\nFirst newt builds the application and loader images separately to ensure they\nare consistent (no errors) and to generate elf files which can inform newt of\nthe symbols used by each part.\n\n\nThen newt collects the symbols used by both application and loader in two ways.\nIt collects the set of symbols from the \n.elf\n files. It also collects all the\npossible symbols from the \n.a\n files for each application.\n\n\nNewt builds the set of packages that the two applications share. It ensures\nthat all the symbols used in those packages are matching. NOTE: because of\nfeatures and #ifdefs, its possible for the two package to have symbols that are\nnot the same. In this case newt generates an error and will not build a split\nimage.\n\n\nThen newt creates the list of symbols that the two applications share from\nthose packages (using the .elf files).\n\n\nNewt re-links the loader to ensure all of these symbols are present in the\nloader application (by forcing the linker to include them in the \n.elf\n).\n\n\nNewt builds a special copy of the loader.elf with only these symbols (and the\nhandful of symbols discussed in the linking section above).\n\n\nFinally, newt links the application, replacing the common .a libraries with the\nspecial loader.elf image during the link.",
- "title": "toc"
- },
- {
- "location": "/os/modules/split/split/#split-images",
- "text": "",
- "title": "Split Images"
- },
- {
- "location": "/os/modules/split/split/#description",
- "text": "The split image mechanism divides a target into two separate images: one\ncapable of image upgrade; the other containing application code. By isolating\nupgrade functionality to a separate image, the application can support\nover-the-air upgrade without dedicating flash space to network stack and\nmanagement code.",
- "title": "Description"
- },
- {
- "location": "/os/modules/split/split/#concept",
- "text": "Mynewt supports three image setups: Setup Description Single One large image; upgrade not supported. Unified Two standalone images. Split Kernel in slot 0; application in slot 1. Each setup has its tradeoffs. The Single setup gives you the most flash space,\nbut doesn't allow you to upgrade after manufacturing. The Unified setup allows\nfor a complete failover in case a bad image gets uploaded, but requires a lot\nof redundancy in each image, limiting the amount of flash available to the\napplication. The Split setup sits somewhere between these two options. Before exploring the split setup in more detail, it might be helpful to get a\nbasic understanding of the Mynewt boot sequence. The boot process is\nsummarized below.",
- "title": "Concept"
- },
- {
- "location": "/os/modules/split/split/#boot-sequence-single",
- "text": "In the Single setup, there is no boot loader. Instead, the image is placed at\naddress 0. The hardware boots directly into the image code. Upgrade is not\npossible because there is no boot loader to move an alternate image into place.",
- "title": "Boot Sequence - Single"
- },
- {
- "location": "/os/modules/split/split/#boot-sequence-unified",
- "text": "In the Unified setup, the boot loader is placed at address 0. At startup, the\nboot loader arranges for the correct image to be in image slot 0, which may\nentail swapping the contents of the two image slots. Finally, the boot loader\njumps to the image in slot 0.",
- "title": "Boot Sequence - Unified"
- },
- {
- "location": "/os/modules/split/split/#boot-sequence-split",
- "text": "The Split setup differs from the other setups mainly in that a target is not\nfully contained in a single image. Rather, the target is partitioned among two\nseparate images: the loader , and the application . Functionality is divided\namong these two images as follows: Loader: Mynewt OS. Network stack for connectivity during upgrade e.g. BLE stack. Anything else required for image upgrade. Application: Parts of Mynewt not required for image upgrade. Application-specific code. The loader image serves three purposes: Second-stage boot loader: it jumps into the application image at\n start up. Image upgrade server: the user can upgrade to a new loader + application\n combo, even if an application image is not currently running. Functionality container: the application image can directly access all the\n code present in the loader image From the perspective of the boot loader, a loader image is identical to a plain\nunified image. What makes a loader image different is a change to its start up\nsequence: rather than starting the Mynewt OS, it jumps to the application image\nin slot 1 if one is present.",
- "title": "Boot Sequence - Split"
- },
- {
- "location": "/os/modules/split/split/#tutorial",
- "text": "",
- "title": "Tutorial"
- },
- {
- "location": "/os/modules/split/split/#building-a-split-image",
- "text": "We will be referring to the nRF51dk for examples in this document. Let's take\na look at this board's flash map (defined in hw/bsp/nrf51dk/bsp.yml ): Name Offset Size (kB) Boot loader 0x00000000 16 Reboot log 0x00004000 16 Image slot 0 0x00008000 110 Image slot 1 0x00023800 110 Image scratch 0x0003f000 2 Flash file system 0x0003f800 2 The application we will be building is bleprph .\nFirst, we create a target to tie our BSP and application together. newt target create bleprph-nrf51dk\nnewt target set bleprph-nrf51dk \\\n app=@apache-mynewt-core/apps/bleprph \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 The two syscfg settings disable bluetooth security and keep the code size down. We can verify the target using the target show command: [~/tmp/myproj2]$ newt target show bleprph-nrf51dk\ntargets/bleprph-nrf51dk\n app=@apache-mynewt-core/apps/bleprph\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Next, build the target: [~/tmp/myproj2]$ newt build bleprph-nrf51dk\nBuilding target targets/bleprph-nrf51dk\n# [...]\nTarget successfully built: targets/bleprph-nrf51dk With our target built, we can view a code size breakdown using the newt size target command. In the interest of brevity, the smaller entries are excluded from the below output: [~/tmp/myproj2]$ newt size bleprph-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 2959 697 hw_drivers_nimble_nrf51.a\n 4126 108 hw_mcu_nordic_nrf51xxx.a\n 8161 4049 kernel_os.a\n 2254 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1499 44 mgmt_newtmgr_nmgr_os.a\n 23918 1930 net_nimble_controller.a\n 28537 2779 net_nimble_host.a\n 2207 205 sys_config.a\n 1074 197 sys_console_full.a\n 3268 97 sys_log.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 105592 1176 13392 120160 1d560 /home/me/tmp/myproj2/bin/targets/bleprph-nrf51dk/app/apps/bleprph/bleprph.elf The full image text size is about 103kB (where 1kB = 1024 bytes). With an image slot size of 110kB,\nthis leaves only about 7kB of flash for additional application code and data.\nNot good. This is the situation we would be facing if we were using the\nUnified setup. The Split setup can go a long way in solving our problem. Our unified bleprph\nimage consists mostly of components that get used during an image upgrade. By\nusing the Split setup, we turn the unified image into two separate images: the\nloader and the application. The functionality related to image upgrade can be\ndelegated to the loader image, freeing up a significant amount of flash in the\napplication image slot. Let's create a new target to use with the Split setup. We designate a target\nas a split target by setting the loader variable. In our example, we are\ngoing to use bleprph as the loader, and splitty as the application. bleprph makes sense as a loader because it contains the BLE stack and\neverything else required for an image upgrade. newt target create split-nrf51dk\nnewt target set split-nrf51dk \\\n loader=@apache-mynewt-core/apps/bleprph \\\n app=@apache-mynewt-core/apps/splitty \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized \\\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Verify that the target looks correct: [~/tmp/myproj2]$ newt target show split-nrf51dk\ntargets/split-nrf51dk\n app=@apache-mynewt-core/apps/splitty\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk\n build_profile=optimized\n loader=@apache-mynewt-core/apps/bleprph\n syscfg=BLE_LL_CFG_FEAT_LE_ENCRYPTION=0:BLE_SM_LEGACY=0 Now, let's build the new target: [~/tmp/myproj2]$ newt build split-nrf51dk\nBuilding target targets/split-nrf51dk\n# [...]\nTarget successfully built: targets/split-nrf51dk And look at the size breakdown (again, smaller entries are removed): [~/tmp/myproj2]$ newt size split-nrf51dk\nSize of Application Image: app\n FLASH RAM\n 3064 251 sys_shell.a\n\nobjsize\n text data bss dec hex filename\n 4680 112 17572 22364 575c /home/me/tmp/myproj2/bin/targets/split-nrf51dk/app/apps/splitty/splitty.elf\n\nSize of Loader Image: loader\n FLASH RAM\n 2446 1533 apps_bleprph.a\n 1430 104 boot_bootutil.a\n 1232 0 crypto_mbedtls.a\n 1107 0 encoding_cborattr.a\n 2390 0 encoding_tinycbor.a\n 1764 0 fs_fcb.a\n 3168 705 hw_drivers_nimble_nrf51.a\n 4318 109 hw_mcu_nordic_nrf51xxx.a\n 8285 4049 kernel_os.a\n 2274 38 libc_baselibc.a\n 2612 0 libgcc.a\n 2232 24 mgmt_imgmgr.a\n 1491 44 mgmt_newtmgr_nmgr_os.a\n 25169 1946 net_nimble_controller.a\n 31397 2827 net_nimble_host.a\n 2259 205 sys_config.a\n 1318 202 sys_console_full.a\n 3424 97 sys_log.a\n 1053 60 sys_stats.a\n 1296 0 time_datetime.a\n\nobjsize\n text data bss dec hex filename\n 112020 1180 13460 126660 1eec4 /home/me/tmp/myproj2/bin/targets/split-nrf51dk/loader/apps/bleprph/bleprph.elf The size command shows two sets of output: one for the application, and another\nfor the loader. The addition of the split functionality did make bleprph\nslightly bigger, but notice how small the application is: 4.5 kB! Where before\nwe only had 7 kB left, now we have 105.5 kB. Furthermore, all the\nfunctionality in the loader is available to the application at any time. For\nexample, if your application needs bluetooth functionality, it can use the BLE\nstack present in the loader instead of containing its own copy. Finally, let's deploy the split image to our nRF51dk board. The procedure here\nis the same as if we were using the Unified setup, i.e., via either the newt load or newt run command. [~/repos/mynewt/core]$ newt load split-nrf51dk 0\nLoading app image into slot 2\nLoading loader image into slot 1",
- "title": "Building a Split Image"
- },
- {
- "location": "/os/modules/split/split/#image-management",
- "text": "",
- "title": "Image Management"
- },
- {
- "location": "/os/modules/split/split/#retrieve-current-state-image-list",
- "text": "Image management in the split setup is a bit more complicated than in the\nunified setup. You can determine a device's image management state with the newtmgr image list command. Here is how a device responds to this command\nafter our loader + application combo has been deployed: [~/tmp/myproj2]$ newtmgr -c A600ANJ1 image list\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags:\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching There are several interesting things about this response: Two images: This is expected; we deployed both a loader image and an\napplication image. bootable flag: Notice slot 0's bootable flag is set, while slot 1's is\nnot. This tells us that slot 0 contains a loader and slot 1 contains an\napplication. If an image is bootable, it can be booted directly from the boot\nloader. Non-bootable images can only be started from a loader image. flags: Slot 0 is active and confirmed ; none of slot 1's flags are set.\nThe active flag indicates that the image is currently running; the confirmed flag indicates that the image will continue to be used on\nsubsequent reboots. Slot 1's lack of enabled flags indicates that the image is\nnot being used at all. Split status: The split status field tells you if the loader and\napplication are compatible. A loader + application combo is compatible only if\nboth images were built at the same time with newt . If the loader and\napplication are not compatible, the loader will not boot into the application.",
- "title": "Retrieve Current State (image list)"
- },
- {
- "location": "/os/modules/split/split/#enabling-a-split-application",
- "text": "By default, the application image in slot 1 is disabled. This is indicated in\nthe image list response above. When you deploy a loader / application combo\nto your device, the application image won't actually run. Instead, the loader\nwill act as though an application image is not present and remain in \"loader\nmode\". Typically, a device in loader mode simply acts as an image management\nserver, listening for an image upgrade or a request to activate the application\nimage. Use the following command sequence to enable the split application image: Tell device to \"test out\" the application image on next boot ( newtmgr image test application-image-hash ). Reboot device ( newtmgr reset ). Make above change permanent ( newtmgr image confirm ). After the above sequence, a newtmgr image list command elicits the following response: [~/tmp/myproj2]$ newtmgr -c A600ANJ1 image confirm\nImages:\n slot=0\n version: 0.0.0\n bootable: true\n flags: active confirmed\n hash: 948f118966f7989628f8f3be28840fd23a200fc219bb72acdfe9096f06c4b39b\n slot=1\n version: 0.0.0\n bootable: false\n flags: active confirmed\n hash: 78e4d263eeb5af5635705b7cae026cc184f14aa6c6c59c6e80616035cd2efc8f\nSplit status: matching The active confirmed flags value on both slots indicates that both images are\npermanently running.",
- "title": "Enabling a Split Application"
- },
- {
- "location": "/os/modules/split/split/#image-upgrade",
- "text": "First, let's review of the image upgrade process for the Unified setup. The\nuser upgrades to a new image in this setup with the following steps:",
- "title": "Image Upgrade"
- },
- {
- "location": "/os/modules/split/split/#image-upgrade-unified",
- "text": "Upload new image to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new image on next boot ( newtmgr image test image-hash ). Reboot device ( newtmgr reset ). Make new image permanent ( newtmgr image confirm ).",
- "title": "Image Upgrade - Unified"
- },
- {
- "location": "/os/modules/split/split/#image-upgrade-split",
- "text": "The image upgrade process is a bit more complicated in the Split setup. It is\nmore complicated because two images need to be upgraded (loader and\napplication) rather than just one. The split upgrade process is described\nbelow: Disable split functionality; we need to deactivate the application image in\n slot 1 ( newtmgr image test current-loader-hash ). Reboot device ( newtmgr reset ). Make above change permanent ( newtmgr image confirm ). Upload new loader to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new loader on next boot ( newtmgr image test new-loader-hash ). Reboot device ( newtmgr reset ). Make above change of loader permanent ( newtmgr image confirm ). Upload new application to slot 1 ( newtmgr image upload filename ). Tell device to \"test out\" the new application on next boot ( newtmgr image test new-application-hash ). Reboot device ( newtmgr reset ). Make above change of application permanent ( newtmgr image confirm ). When performing this process manually, it may be helpful to use image list to\ncheck the image management state as you go.",
- "title": "Image Upgrade - Split"
- },
- {
- "location": "/os/modules/split/split/#syscfg",
- "text": "Syscfg is Mynewt's system-wide configuration mechanism. In a split setup,\nthere is a single umbrella syscfg configuration that applies to both the loader\nand the application. Consequently, overriding a value in an application-only\npackage potentially affects the loader (and vice-versa).",
- "title": "Syscfg"
- },
- {
- "location": "/os/modules/split/split/#loaders",
- "text": "The following applications have been enabled as loaders. You may choose to\nbuild your own loader application, and these can serve as samples. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/bleprph",
- "title": "Loaders"
- },
- {
- "location": "/os/modules/split/split/#split-apps",
- "text": "The following applications have been enabled as split applications. If you\nchoose to build your own split application these can serve as samples. Note\nthat slinky can be either a loader image or an application image. @apache-mynewt-core/apps/slinky @apache-mynewt-core/apps/splitty",
- "title": "Split Apps"
- },
- {
- "location": "/os/modules/split/split/#theory-of-operation",
- "text": "A split image is built as follows: First newt builds the application and loader images separately to ensure they\nare consistent (no errors) and to generate elf files which can inform newt of\nthe symbols used by each part. Then newt collects the symbols used by both application and loader in two ways.\nIt collects the set of symbols from the .elf files. It also collects all the\npossible symbols from the .a files for each application. Newt builds the set of packages that the two applications share. It ensures\nthat all the symbols used in those packages are matching. NOTE: because of\nfeatures and #ifdefs, its possible for the two package to have symbols that are\nnot the same. In this case newt generates an error and will not build a split\nimage. Then newt creates the list of symbols that the two applications share from\nthose packages (using the .elf files). Newt re-links the loader to ensure all of these symbols are present in the\nloader application (by forcing the linker to include them in the .elf ). Newt builds a special copy of the loader.elf with only these symbols (and the\nhandful of symbols discussed in the linking section above). Finally, newt links the application, replacing the common .a libraries with the\nspecial loader.elf image during the link.",
- "title": "Theory of Operation"
- },
- {
- "location": "/os/modules/bootloader/bootloader/",
- "text": "Bootloader\n\n\nThe \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE, etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process.\n\n\nThe bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:\n\n\n\n\nCalculates hash of the image.\n\n\nUses public key to uncover hash value from included signature. \n\n\nCompares the calculated and uncovered hashes for a match.\n\n\n\n\nThe \"secure bootloader\" should be placed in protected memory on a given microcontroller.\n\n\nThe Mynewt bootloader comprises two packages:\n\n\n\n\nThe bootutil library (boot/bootutil)\n\n\nThe boot application (apps/boot)\n\n\n\n\nThe Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nmanner for the following two reasons:\n\n\n\n\nBy keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders.\n\n\nBy excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.\n\n\n\n\nLimitations\n\n\nThe boot loader currently only supports images with the following\ncharacteristics:\n\n\n\n\nBuilt to run from flash.\n\n\nBuild to run from a fixed location (i.e., position-independent).\n\n\n\n\nImage Format\n\n\nThe following definitions describe the image header format.\n\n\n#define IMAGE_MAGIC 0x96f3b83c\n\n\n#define IMAGE_MAGIC_NONE 0xffffffff\n\n\n\nstruct\n \nimage_version\n {\n \nuint8_t\n \niv_major\n;\n \nuint8_t\n \niv_minor\n;\n \nuint16_t\n \niv_revision\n;\n \nuint32_t\n \niv_build_num\n;\n};\n\n\n/** Image header. All fields are in little endian byte order. */\n\n\nstruct\n \nimage_header\n {\n \nuint32_t\n \nih_magic\n;\n \nuint16_t\n \nih_tlv_size\n; \n/* Trailing TLVs */\n\n \nuint8_t\n \nih_key_id\n;\n \nuint8_t\n \n_pad1\n;\n \nuint16_t\n \nih_hdr_size\n;\n \nuint16_t\n \n_pad2\n;\n \nuint32_t\n \nih_img_size\n; \n/* Does not include header. */\n\n \nuint32_t\n \nih_flags\n;\n \nstruct\n \nimage_version\n \nih_ver\n;\n \nuint32_t\n \n_pad3\n;\n};\n\n\n\n\n\nThe \nih_hdr_size\n field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header.\n\n\nThe following are the image header flags available.\n\n\n#define IMAGE_F_PIC 0x00000001\n\n\n#define IMAGE_F_SHA256 0x00000002 \n/* Image contains hash TLV */\n\n\n#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 \n/* PKCS15 w/RSA and SHA */\n\n\n#define IMAGE_F_ECDSA224_SHA256 0x00000008 \n/* ECDSA256 over SHA256 */\n\n\n#define IMAGE_F_NON_BOOTABLE 0x00000010\n\n\n#define IMAGE_HEADER_SIZE 32\n\n\n\n\n\n\nOptional type-length-value records (TLVs) containing image metadata are placed\nafter the end of the image. For example, security data gets added as a footer at the end of the image.\n\n\n/** Image trailer TLV format. All fields in little endian. */\n\n\nstruct\n \nimage_tlv\n {\n \nuint8_t\n \nit_type\n; \n/* IMAGE_TLV_[...]. */\n\n \nuint8_t\n \n_pad\n;\n \nuint16_t\n \nit_len\n \n/* Data length (not including TLV header). */\n\n};\n\n\n/*\n\n\n * Image trailer TLV types.\n\n\n */\n\n\n#define IMAGE_TLV_SHA256 1 \n/* SHA256 of image hdr and body */\n\n\n#define IMAGE_TLV_RSA2048 2 \n/* RSA2048 of hash output */\n\n\n#define IMAGE_TLV_ECDSA224 3 \n/* ECDSA of hash output */\n\n\n\n\n\n\nFlash Map\n\n\nA Mynewt device's flash is partitioned according to its \nflash map\n. At a high\nlevel, the flash map maps numeric IDs to \nflash areas\n. A flash area is a\nregion of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nA write to one area does not restrict writes to other areas.\n\n\n\n\nThe boot loader uses the following flash areas:\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n\n\n\n\nImage Slots\n\n\nA portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary slot, it must swap the two images in flash prior to booting.\n\n\nIn addition to the two image slots, the boot loader requires a scratch area to\nallow for reliable image swapping.\n\n\nBoot States\n\n\nLogically, you can think of a pair of flags associated with each image slot:\npending and confirmed. On startup, the boot loader determines the state of the\ndevice by inspecting each pair of flags. These flags have the following\nmeanings:\n\n\n\n\npending: image gets tested on next reboot; absent subsequent confirm command,\n revert to original image on second reboot.\n\n\nconfirmed: always use image unless excluded by a test image.\n\n\n\n\nIn English, when the user wants to run the secondary image, they set the\npending flag for the second slot and reboot the device. On startup, the boot\nloader will swap the two images in flash, clear the secondary slot's pending\nflag, and run the newly-copied image in slot 0. This is a temporary state; if\nthe device reboots again, the boot loader swaps the images back to their\noriginal slots and boots into the original image. If the user doesn't want to\nrevert to the original state, they can make the current state permanent by\nsetting the confirmed flag in slot 0.\n\n\nSwitching to an alternate image is a two-step process (set + confirm) to\nprevent a device from becoming \"bricked\" by bad firmware. If the device\ncrashes immediately upon booting the second image, the boot loader reverts to\nthe working image, rather than repeatedly rebooting into the bad image.\n\n\nThe following set of tables illustrate the three possible states that the\ndevice can be in:\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | X | |\n---------------+--------+--------\n\nImage 0 confirmed; |\nNo change on reboot |\n---------------------------------\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | X |\n confirmed | X | |\n---------------+--------+--------\n\nImage 0 confirmed; |\nTest image 1 on next reboot |\n---------------------------------\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | | X |\n---------------+--------+--------\n\nTesting image 0; |\nRevert to image 1 on next reboot |\n---------------------------------\n\n\n\n\n\n\nBoot Vector\n\n\nAt startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two\nrecords (called \"image trailers\"), one written at the end of each image slot.\nAn image trailer has the following structure:\n\n\n 0 1 2 3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ MAGIC (16 octets) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ ~\n~ Swap status (128 * min-write-size * 3) ~\n~ ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Copy done | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Image OK | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n\n\n\n\n\nThese records are at the end of each image slot. The offset immediately\nfollowing such a record represents the start of the next flash area.\n\n\nNote: \nmin-write-size\n is a property of the flash hardware. If the hardware\nallows individual bytes to be written at arbitrary addresses, then\n\nmin-write-size\n is 1. If the hardware only allows writes at even addresses,\nthen \nmin-write-size\n is 2, and so on.\n\n\nThe fields are defined as follows:\n\n\n\n\n\n\nMAGIC: The following 16 bytes, written in host-byte-order:\n\n\nconst uint32_t boot_img_magic[4] = {\n 0xf395c277,\n 0x7fefd260,\n 0x0f505235,\n 0x8079b62c,\n};\n\n\n\n\n\n\n\n\n\nSwap status: A series of single-byte records. Each record corresponds to a\nflash sector in an image slot. A swap status byte indicate the location of\nthe corresponding sector data. During an image swap, image data is moved one\nsector at a time. The swap status is necessary for resuming a swap operation\nif the device rebooted before a swap operation completed.\n\n\n\n\n\n\nCopy done: A single byte indicating whether the image in this slot is\ncomplete (\n0x01=done, 0xff=not done\n).\n\n\n\n\n\n\nImage OK: A single byte indicating whether the image in this slot has been\nconfirmed as good by the user (\n0x01=confirmed; 0xff=not confirmed\n).\n\n\n\n\n\n\nThe boot vector records are structured around the limitations imposed by flash\nhardware. As a consequence, they do not have a very intuitive design, and it\nis difficult to get a sense of the state of the device just by looking at the\nboot vector. It is better to map all the possible vector states to the swap types\n(None, Test, Revert) via a set of tables. These tables are reproduced below.\nIn these tables, the \"pending\" and \"confirmed\" flags are shown for illustrative\npurposes; they are not actually present in the boot vector.\n\n\nState I\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Unset | Unset |\n image-ok | Any | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: none |\n-----------------------------------\n\n\n\nState II\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Any | Good |\n image-ok | Any | N/A |\n-----------------+--------+--------\n\n pending | | X |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: test |\n-----------------------------------\n\n\n\nState III\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0xff | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | | X |\n-----------------+--------+--------\n\n swap: revert (test image running) |\n-----------------------------------\n\n\n\nState IV\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0x01 | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: none (confirmed test image) |\n-----------------------------------\n\n\n\n\n\n\nHigh-level Operation\n\n\nWith the terms defined, we can now explore the boot loader's operation. First,\na high-level overview of the boot process is presented. Then, the following\nsections describe each step of the process in more detail.\n\n\nProcedure:\n\n\nA. Inspect swap status region; is an interrupted swap is being resumed?\n Yes: Complete the partial swap operation; skip to step C.\n No: Proceed to step B.\n\nB. Inspect boot vector; is a swap requested?\n Yes.\n 1. Is the requested image valid (integrity and security check)?\n Yes.\n a. Perform swap operation.\n b. Persist completion of swap procedure to boot vector.\n c. Proceed to step C.\n No.\n a. Erase invalid image.\n b. Persist failure of swap procedure to boot vector.\n c. Proceed to step C.\n No: Proceed to step C.\n\nC. Boot into image in slot 0.\n\n\n\n\n\nImage Swapping\n\n\nThe boot loader swaps the contents of the two image slots for two reasons:\n\n\n\n\nUser has issued an \"image test\" operation; the image in slot-1 should be\n run once (state II).\n\n\nTest image rebooted without being confirmed; the boot loader should\n revert to the original image currently in slot-1 (state III).\n\n\n\n\nIf the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the swap operation. The two images are swapped\naccording to the following procedure:\n\n\n1. Determine how many flash sectors each image slot consists of. This\n number must be the same for both slots.\n2. Iterate the list of sector indices in descending order (i.e., starting\n with the greatest index); current element = \nindex\n.\n b. Erase scratch area.\n c. Copy slot0[index] to scratch area.\n d. Write updated swap status (i).\n\n e. Erase slot1[index]\n f. Copy slot0[index] to slot1[index]\n - If these are the last sectors (i.e., first swap being perfomed),\n copy the full sector *except* the image trailer.\n - Else, copy entire sector contents.\n g. Write updated swap status (ii).\n\n h. Erase slot0[index].\n i. Copy scratch area slot0[index].\n j. Write updated swap status (iii).\n\n3. Persist completion of swap procedure to slot 0 image trailer.\n\n\n\n\n\nThe additional caveats in step 2f are necessary so that the slot 1 image trailer\ncan be written by the user at a later time. With the image trailer unwritten,\nthe user can test the image in slot 1 (i.e., transition to state II).\n\n\nThe particulars of step 3 vary depending on whether an image is being tested or\nreverted:\n\n\n* test:\n o Write slot0.copy_done = 1\n (should now be in state III)\n\n* revert:\n o Write slot0.magic = BOOT_MAGIC\n o Write slot0.copy_done = 1\n o Write slot0.image_ok = 1\n (should now be in state IV)\n\n\n\n\n\nSwap Status\n\n\nThe swap status region allows the boot loader to recover in case it restarts in\nthe middle of an image swap operation. The swap status region consists of a\nseries of single-byte records. These records are written independently, and\ntherefore must be padded according to the minimum write size imposed by the\nflash hardware. In the below figure, a \nmin-write-size\n of 1 is assumed for\nsimplicity. The structure of the swap status region is illustrated below. In\nthis figure, a \nmin-write-size\n of 1 is assumed for simplicity.\n\n\n 0 1 2 3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec125,state 2 | |\n+-+-+-+-+-+-+-+-+ +\n~ ~\n~ [Records for indices 124 through 1 ~\n~ ~\n~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n\n\n\n\n\nAnd now, in English...\n\n\nEach image slot is partitioned into a sequence of flash sectors. If we were to\nenumerate the sectors in a single slot, starting at 0, we would have a list of\nsector indices. Since there are two image slots, each sector index would\ncorrespond to a pair of sectors. For example, sector index 0 corresponds to\nthe first sector in slot 0 and the first sector in slot 1. Furthermore, we\nimpose a limit of 128 indices. If an image slot consists of more than 128\nsectors, the flash layout is not compatible with this boot loader. Finally,\nreverse the list of indices such that the list starts with index 127 and ends\nwith 0. The swap status region is a representation of this reversed list.\n\n\nDuring a swap operation, each sector index transitions through four separate\nstates:\n\n\n0. slot 0: image 0, slot 1: image 1, scratch: N/A\n1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1-\ns, erase 1)\n2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0-\n1, erase 0)\n3. slot 0: image 1, slot 1: image 0, scratch: N/A (s-\n0)\n\n\n\n\n\nEach time a sector index transitions to a new state, the boot loader writes a\nrecord to the swap status region. Logically, the boot loader only needs one\nrecord per sector index to keep track of the current swap state. However, due\nto limitations imposed by flash hardware, a record cannot be overwritten when\nan index's state changes. To solve this problem, the boot loader uses three\nrecords per sector index rather than just one.\n\n\nEach sector-state pair is represented as a set of three records. The record\nvalues map to the above four states as follows\n\n\n | rec0 | rec1 | rec2\n--------+------+------+------\nstate 0 | 0xff | 0xff | 0xff\nstate 1 | 0x01 | 0xff | 0xff\nstate 2 | 0x01 | 0x02 | 0xff\nstate 3 | 0x01 | 0x02 | 0x03\n\n\n\n\n\nThe swap status region can accommodate 128 sector indices. Hence, the size of\nthe region, in bytes, is \n128 * min-write-size * 3\n. The number 128 is chosen\nsomewhat arbitrarily and will likely be made configurable. The only\nrequirement for the index count is that is is great enough to account for a\nmaximum-sized image (i.e., at least as great as the total sector count in an\nimage slot). If a device's image slots use less than 128 sectors, the first\nrecord that gets written will be somewhere in the middle of the region. For\nexample, if a slot uses 64 sectors, the first sector index that gets swapped is\n63, which corresponds to the exact halfway point within the region.\n\n\nReset Recovery\n\n\nIf the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot vector to determine how the image parts are distributed in flash.\n\n\nThe first step is determine where the relevant swap status region is located.\nBecause this region is embedded within the image slots, its location in flash\nchanges during a swap operation. The below set of tables map boot vector\ncontents to swap status location. In these tables, the \"source\" field\nindicates where the swap status region is located.\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0x01 | N/A |\n----------+------------+------------\n\nsource: none |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------\n\nsource: slot 0 |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Any | Good |\ncopy-done | Any | N/A |\n----------+------------+------------\n\nsource: scratch |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Unset | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------|\nsource: varies |\n------------------------------------+------------------------------+\nThis represents one of two cases: |\no No swaps ever (no status to read, so no harm in checking). |\no Mid-revert; status in slot 0. |\n-------------------------------------------------------------------\n\n\n\n\n\n\nIf the swap status region indicates that the images are not contiguous,\nbootutil completes the swap operation that was in progress when the system was\nreset. In other words, it applies the procedure defined in the previous\nsection, moving image 1 into slot 0 and image 0 into slot 1. If the boot\nstatus file indicates that an image part is present in the scratch area, this\npart is copied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1.\n\n\nAfter the swap operation has been completed, the boot loader proceeds as though\nit had just been started.\n\n\nIntegrity Check\n\n\nAn image is checked for integrity immediately before it gets copied into the\nprimary slot. If the boot loader doesn't perform an image swap, then it\ndoesn't perform an integrity check.\n\n\nDuring the integrity check, the boot loader verifies the following aspects of\nan image:\n\n\n\n\n32-bit magic number must be correct (0x96f3b83c).\n\n\nImage must contain a SHA256 TLV.\n\n\nCalculated SHA256 must matche SHA256 TLV contents.\n\n\nImage \nmay\n contain a signature TLV. If it does, its contents must be\n verifiable using a key embedded in the boot loader.\n\n\n\n\nImage Signing and Verification\n\n\nAs indicated above, the final step of the integrity check is signature\nverification. The boot loader can have one or more public keys embedded in it\nat build time. During signature verification, the boot loader verifies that an\nimage was signed with a private key that corresponds to one of its public keys.\nThe image signature TLV indicates the index of the key that is has been signed\nwith. The boot loader uses this index to identify the corresponding public\nkey.\n\n\nFor information on embedding public keys in the boot loader, as well as\nproducing signed images, see: boot/bootutil/signed_images.md",
- "title": "toc"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#bootloader",
- "text": "The \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE, etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it: Calculates hash of the image. Uses public key to uncover hash value from included signature. Compares the calculated and uncovered hashes for a match. The \"secure bootloader\" should be placed in protected memory on a given microcontroller. The Mynewt bootloader comprises two packages: The bootutil library (boot/bootutil) The boot application (apps/boot) The Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nmanner for the following two reasons: By keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders. By excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.",
- "title": "Bootloader"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#limitations",
- "text": "The boot loader currently only supports images with the following\ncharacteristics: Built to run from flash. Build to run from a fixed location (i.e., position-independent).",
- "title": "Limitations"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#image-format",
- "text": "The following definitions describe the image header format. #define IMAGE_MAGIC 0x96f3b83c #define IMAGE_MAGIC_NONE 0xffffffff struct image_version {\n uint8_t iv_major ;\n uint8_t iv_minor ;\n uint16_t iv_revision ;\n uint32_t iv_build_num ;\n}; /** Image header. All fields are in little endian byte order. */ struct image_header {\n uint32_t ih_magic ;\n uint16_t ih_tlv_size ; /* Trailing TLVs */ \n uint8_t ih_key_id ;\n uint8_t _pad1 ;\n uint16_t ih_hdr_size ;\n uint16_t _pad2 ;\n uint32_t ih_img_size ; /* Does not include header. */ \n uint32_t ih_flags ;\n struct image_version ih_ver ;\n uint32_t _pad3 ;\n}; The ih_hdr_size field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header. The following are the image header flags available. #define IMAGE_F_PIC 0x00000001 #define IMAGE_F_SHA256 0x00000002 /* Image contains hash TLV */ #define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 /* PKCS15 w/RSA and SHA */ #define IMAGE_F_ECDSA224_SHA256 0x00000008 /* ECDSA256 over SHA256 */ #define IMAGE_F_NON_BOOTABLE 0x00000010 #define IMAGE_HEADER_SIZE 32 Optional type-length-value records (TLVs) containing image metadata are placed\nafter the end of the image. For example, security data gets added as a footer at the end of the image. /** Image trailer TLV format. All fields in little endian. */ struct image_tlv {\n uint8_t it_type ; /* IMAGE_TLV_[...]. */ \n uint8_t _pad ;\n uint16_t it_len /* Data length (not including TLV header). */ \n}; /* * Image trailer TLV types. */ #define IMAGE_TLV_SHA256 1 /* SHA256 of image hdr and body */ #define IMAGE_TLV_RSA2048 2 /* RSA2048 of hash output */ #define IMAGE_TLV_ECDSA224 3 /* ECDSA of hash output */",
- "title": "Image Format"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#flash-map",
- "text": "A Mynewt device's flash is partitioned according to its flash map . At a high\nlevel, the flash map maps numeric IDs to flash areas . A flash area is a\nregion of disk with the following properties: An area can be fully erased without affecting any other areas. A write to one area does not restrict writes to other areas. The boot loader uses the following flash areas: #define FLASH_AREA_BOOTLOADER 0 #define FLASH_AREA_IMAGE_0 1 #define FLASH_AREA_IMAGE_1 2 #define FLASH_AREA_IMAGE_SCRATCH 3",
- "title": "Flash Map"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#image-slots",
- "text": "A portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary slot, it must swap the two images in flash prior to booting. In addition to the two image slots, the boot loader requires a scratch area to\nallow for reliable image swapping.",
- "title": "Image Slots"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#boot-states",
- "text": "Logically, you can think of a pair of flags associated with each image slot:\npending and confirmed. On startup, the boot loader determines the state of the\ndevice by inspecting each pair of flags. These flags have the following\nmeanings: pending: image gets tested on next reboot; absent subsequent confirm command,\n revert to original image on second reboot. confirmed: always use image unless excluded by a test image. In English, when the user wants to run the secondary image, they set the\npending flag for the second slot and reboot the device. On startup, the boot\nloader will swap the two images in flash, clear the secondary slot's pending\nflag, and run the newly-copied image in slot 0. This is a temporary state; if\nthe device reboots again, the boot loader swaps the images back to their\noriginal slots and boots into the original image. If the user doesn't want to\nrevert to the original state, they can make the current state permanent by\nsetting the confirmed flag in slot 0. Switching to an alternate image is a two-step process (set + confirm) to\nprevent a device from becoming \"bricked\" by bad firmware. If the device\ncrashes immediately upon booting the second image, the boot loader reverts to\nthe working image, rather than repeatedly rebooting into the bad image. The following set of tables illustrate the three possible states that the\ndevice can be in: | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | X | |\n---------------+--------+-------- \nImage 0 confirmed; |\nNo change on reboot |\n--------------------------------- \n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | X |\n confirmed | X | |\n---------------+--------+-------- \nImage 0 confirmed; |\nTest image 1 on next reboot |\n--------------------------------- \n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | | X |\n---------------+--------+-------- \nTesting image 0; |\nRevert to image 1 on next reboot |\n---------------------------------",
- "title": "Boot States"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#boot-vector",
- "text": "At startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two\nrecords (called \"image trailers\"), one written at the end of each image slot.\nAn image trailer has the following structure: 0 1 2 3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ MAGIC (16 octets) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ ~\n~ Swap status (128 * min-write-size * 3) ~\n~ ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Copy done | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Image OK | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ These records are at the end of each image slot. The offset immediately\nfollowing such a record represents the start of the next flash area. Note: min-write-size is a property of the flash hardware. If the hardware\nallows individual bytes to be written at arbitrary addresses, then min-write-size is 1. If the hardware only allows writes at even addresses,\nthen min-write-size is 2, and so on. The fields are defined as follows: MAGIC: The following 16 bytes, written in host-byte-order: const uint32_t boot_img_magic[4] = {\n 0xf395c277,\n 0x7fefd260,\n 0x0f505235,\n 0x8079b62c,\n}; Swap status: A series of single-byte records. Each record corresponds to a\nflash sector in an image slot. A swap status byte indicate the location of\nthe corresponding sector data. During an image swap, image data is moved one\nsector at a time. The swap status is necessary for resuming a swap operation\nif the device rebooted before a swap operation completed. Copy done: A single byte indicating whether the image in this slot is\ncomplete ( 0x01=done, 0xff=not done ). Image OK: A single byte indicating whether the image in this slot has been\nconfirmed as good by the user ( 0x01=confirmed; 0xff=not confirmed ). The boot vector records are structured around the limitations imposed by flash\nhardware. As a consequence, they do not have a very intuitive design, and it\nis difficult to get a sense of the state of the device just by looking at the\nboot vector. It is better to map all the possible vector states to the swap types\n(None, Test, Revert) via a set of tables. These tables are reproduced below.\nIn these tables, the \"pending\" and \"confirmed\" flags are shown for illustrative\npurposes; they are not actually present in the boot vector. State I\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Unset | Unset |\n image-ok | Any | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | X | |\n-----------------+--------+-------- \n swap: none |\n----------------------------------- \n\n\nState II\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Any | Good |\n image-ok | Any | N/A |\n-----------------+--------+-------- \n pending | | X |\n confirmed | X | |\n-----------------+--------+-------- \n swap: test |\n----------------------------------- \n\n\nState III\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0xff | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | | X |\n-----------------+--------+-------- \n swap: revert (test image running) |\n----------------------------------- \n\n\nState IV\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0x01 | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | X | |\n-----------------+--------+-------- \n swap: none (confirmed test image) |\n-----------------------------------",
- "title": "Boot Vector"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#high-level-operation",
- "text": "With the terms defined, we can now explore the boot loader's operation. First,\na high-level overview of the boot process is presented. Then, the following\nsections describe each step of the process in more detail. Procedure: A. Inspect swap status region; is an interrupted swap is being resumed?\n Yes: Complete the partial swap operation; skip to step C.\n No: Proceed to step B.\n\nB. Inspect boot vector; is a swap requested?\n Yes.\n 1. Is the requested image valid (integrity and security check)?\n Yes.\n a. Perform swap operation.\n b. Persist completion of swap procedure to boot vector.\n c. Proceed to step C.\n No.\n a. Erase invalid image.\n b. Persist failure of swap procedure to boot vector.\n c. Proceed to step C.\n No: Proceed to step C.\n\nC. Boot into image in slot 0.",
- "title": "High-level Operation"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#image-swapping",
- "text": "The boot loader swaps the contents of the two image slots for two reasons: User has issued an \"image test\" operation; the image in slot-1 should be\n run once (state II). Test image rebooted without being confirmed; the boot loader should\n revert to the original image currently in slot-1 (state III). If the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the swap operation. The two images are swapped\naccording to the following procedure: 1. Determine how many flash sectors each image slot consists of. This\n number must be the same for both slots.\n2. Iterate the list of sector indices in descending order (i.e., starting\n with the greatest index); current element = index .\n b. Erase scratch area.\n c. Copy slot0[index] to scratch area.\n d. Write updated swap status (i).\n\n e. Erase slot1[index]\n f. Copy slot0[index] to slot1[index]\n - If these are the last sectors (i.e., first swap being perfomed),\n copy the full sector *except* the image trailer.\n - Else, copy entire sector contents.\n g. Write updated swap status (ii).\n\n h. Erase slot0[index].\n i. Copy scratch area slot0[index].\n j. Write updated swap status (iii).\n\n3. Persist completion of swap procedure to slot 0 image trailer. The additional caveats in step 2f are necessary so that the slot 1 image trailer\ncan be written by the user at a later time. With the image trailer unwritten,\nthe user can test the image in slot 1 (i.e., transition to state II). The particulars of step 3 vary depending on whether an image is being tested or\nreverted: * test:\n o Write slot0.copy_done = 1\n (should now be in state III)\n\n* revert:\n o Write slot0.magic = BOOT_MAGIC\n o Write slot0.copy_done = 1\n o Write slot0.image_ok = 1\n (should now be in state IV)",
- "title": "Image Swapping"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#swap-status",
- "text": "The swap status region allows the boot loader to recover in case it restarts in\nthe middle of an image swap operation. The swap status region consists of a\nseries of single-byte records. These records are written independently, and\ntherefore must be padded according to the minimum write size imposed by the\nflash hardware. In the below figure, a min-write-size of 1 is assumed for\nsimplicity. The structure of the swap status region is illustrated below. In\nthis figure, a min-write-size of 1 is assumed for simplicity. 0 1 2 3\n 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec125,state 2 | |\n+-+-+-+-+-+-+-+-+ +\n~ ~\n~ [Records for indices 124 through 1 ~\n~ ~\n~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ And now, in English... Each image slot is partitioned into a sequence of flash sectors. If we were to\nenumerate the sectors in a single slot, starting at 0, we would have a list of\nsector indices. Since there are two image slots, each sector index would\ncorrespond to a pair of sectors. For example, sector index 0 corresponds to\nthe first sector in slot 0 and the first sector in slot 1. Furthermore, we\nimpose a limit of 128 indices. If an image slot consists of more than 128\nsectors, the flash layout is not compatible with this boot loader. Finally,\nreverse the list of indices such that the list starts with index 127 and ends\nwith 0. The swap status region is a representation of this reversed list. During a swap operation, each sector index transitions through four separate\nstates: 0. slot 0: image 0, slot 1: image 1, scratch: N/A\n1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1- s, erase 1)\n2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0- 1, erase 0)\n3. slot 0: image 1, slot 1: image 0, scratch: N/A (s- 0) Each time a sector index transitions to a new state, the boot loader writes a\nrecord to the swap status region. Logically, the boot loader only needs one\nrecord per sector index to keep track of the current swap state. However, due\nto limitations imposed by flash hardware, a record cannot be overwritten when\nan index's state changes. To solve this problem, the boot loader uses three\nrecords per sector index rather than just one. Each sector-state pair is represented as a set of three records. The record\nvalues map to the above four states as follows | rec0 | rec1 | rec2\n--------+------+------+------\nstate 0 | 0xff | 0xff | 0xff\nstate 1 | 0x01 | 0xff | 0xff\nstate 2 | 0x01 | 0x02 | 0xff\nstate 3 | 0x01 | 0x02 | 0x03 The swap status region can accommodate 128 sector indices. Hence, the size of\nthe region, in bytes, is 128 * min-write-size * 3 . The number 128 is chosen\nsomewhat arbitrarily and will likely be made configurable. The only\nrequirement for the index count is that is is great enough to account for a\nmaximum-sized image (i.e., at least as great as the total sector count in an\nimage slot). If a device's image slots use less than 128 sectors, the first\nrecord that gets written will be somewhere in the middle of the region. For\nexample, if a slot uses 64 sectors, the first sector index that gets swapped is\n63, which corresponds to the exact halfway point within the region.",
- "title": "Swap Status"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#reset-recovery",
- "text": "If the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot vector to determine how the image parts are distributed in flash. The first step is determine where the relevant swap status region is located.\nBecause this region is embedded within the image slots, its location in flash\nchanges during a swap operation. The below set of tables map boot vector\ncontents to swap status location. In these tables, the \"source\" field\nindicates where the swap status region is located. | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0x01 | N/A |\n----------+------------+------------ \nsource: none |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------ \nsource: slot 0 |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Any | Good |\ncopy-done | Any | N/A |\n----------+------------+------------ \nsource: scratch |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Unset | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------|\nsource: varies |\n------------------------------------+------------------------------+\nThis represents one of two cases: |\no No swaps ever (no status to read, so no harm in checking). |\no Mid-revert; status in slot 0. |\n------------------------------------------------------------------- If the swap status region indicates that the images are not contiguous,\nbootutil completes the swap operation that was in progress when the system was\nreset. In other words, it applies the procedure defined in the previous\nsection, moving image 1 into slot 0 and image 0 into slot 1. If the boot\nstatus file indicates that an image part is present in the scratch area, this\npart is copied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1. After the swap operation has been completed, the boot loader proceeds as though\nit had just been started.",
- "title": "Reset Recovery"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#integrity-check",
- "text": "An image is checked for integrity immediately before it gets copied into the\nprimary slot. If the boot loader doesn't perform an image swap, then it\ndoesn't perform an integrity check. During the integrity check, the boot loader verifies the following aspects of\nan image: 32-bit magic number must be correct (0x96f3b83c). Image must contain a SHA256 TLV. Calculated SHA256 must matche SHA256 TLV contents. Image may contain a signature TLV. If it does, its contents must be\n verifiable using a key embedded in the boot loader.",
- "title": "Integrity Check"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#image-signing-and-verification",
- "text": "As indicated above, the final step of the integrity check is signature\nverification. The boot loader can have one or more public keys embedded in it\nat build time. During signature verification, the boot loader verifies that an\nimage was signed with a private key that corresponds to one of its public keys.\nThe image signature TLV indicates the index of the key that is has been signed\nwith. The boot loader uses this index to identify the corresponding public\nkey. For information on embedding public keys in the boot loader, as well as\nproducing signed images, see: boot/bootutil/signed_images.md",
- "title": "Image Signing and Verification"
- },
- {
- "location": "/os/modules/bootloader/boot_build_status/",
- "text": "",
- "title": "boot_build_status"
- },
- {
- "location": "/os/modules/bootloader/boot_build_status_one/",
- "text": "",
- "title": "boot_build_status_one"
- },
- {
- "location": "/os/modules/bootloader/boot_clear_status/",
- "text": "",
- "title": "boot_clear_status"
- },
- {
- "location": "/os/modules/bootloader/boot_copy_area/",
- "text": "",
- "title": "boot_copy_area"
- },
- {
- "location": "/os/modules/bootloader/boot_copy_image/",
- "text": "",
- "title": "boot_copy_image"
- },
- {
- "location": "/os/modules/bootloader/boot_erase_area/",
- "text": "",
- "title": "boot_erase_area"
- },
- {
- "location": "/os/modules/bootloader/boot_fill_slot/",
- "text": "",
- "title": "boot_fill_slot"
- },
- {
- "location": "/os/modules/bootloader/boot_find_image_area_idx/",
- "text": "",
- "title": "boot_find_image_area_idx"
- },
- {
- "location": "/os/modules/bootloader/boot_find_image_part/",
- "text": "",
- "title": "boot_find_image_part"
- },
- {
- "location": "/os/modules/bootloader/boot_find_image_slot/",
- "text": "",
- "title": "boot_find_image_slot"
- },
- {
- "location": "/os/modules/bootloader/boot_go/",
- "text": "",
- "title": "boot_go"
- },
- {
- "location": "/os/modules/bootloader/boot_init_flash/",
- "text": "",
- "title": "boot_init_flash"
- },
- {
- "location": "/os/modules/bootloader/boot_move_area/",
- "text": "",
- "title": "boot_move_area"
- },
- {
- "location": "/os/modules/bootloader/boot_read_image_header/",
- "text": "",
- "title": "boot_read_image_header"
- },
- {
- "location": "/os/modules/bootloader/boot_read_image_headers/",
- "text": "",
- "title": "boot_read_image_headers"
- },
- {
- "location": "/os/modules/bootloader/boot_read_status/",
- "text": "",
- "title": "boot_read_status"
- },
- {
- "location": "/os/modules/bootloader/boot_select_image_slot/",
- "text": "",
- "title": "boot_select_image_slot"
- },
- {
- "location": "/os/modules/bootloader/boot_slot_addr/",
- "text": "",
- "title": "boot_slot_addr"
- },
- {
- "location": "/os/modules/bootloader/boot_slot_to_area_idx/",
- "text": "",
- "title": "boot_slot_to_area_idx"
- },
- {
- "location": "/os/modules/bootloader/boot_swap_areas/",
- "text": "",
- "title": "boot_swap_areas"
- },
- {
- "location": "/os/modules/bootloader/boot_vect_delete_main/",
- "text": "",
- "title": "boot_vect_delete_main"
- },
- {
- "location": "/os/modules/bootloader/boot_vect_delete_test/",
- "text": "",
- "title": "boot_vect_delete_test"
- },
- {
- "location": "/os/modules/bootloader/boot_vect_read_main/",
- "text": "",
- "title": "boot_vect_read_main"
- },
- {
- "location": "/os/modules/bootloader/boot_vect_read_one/",
- "text": "",
- "title": "boot_vect_read_one"
- },
- {
- "location": "/os/modules/bootloader/boot_vect_read_test/",
- "text": "",
- "title": "boot_vect_read_test"
- },
- {
- "location": "/os/modules/bootloader/boot_write_status/",
- "text": "",
- "title": "boot_write_status"
- },
- {
- "location": "/os/modules/fs/fs/fs/",
- "text": "File System Abstraction\n\n\nMynewt provides a file system abstraction layer (\nfs/fs\n) to allow client code to be file system agnostic. By accessing the file system via the \nfs/fs\n API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the \nfs/fs\n API rather than accessing the underlying file system directly.\n\n\nDescription\n\n\nApplications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the\n\nfs/fs\n package.\nIn terms of the Mynewt hierarchy, an \napp\n package must depend on a specific file system package, while \nlibrary\n packages should only depend on \nfs/fs\n.\n\n\nApplications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.\nIn the following example, the \nNewtron Flash File System\n\nis used.\n\n\n# repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/fs # include the file operations interfaces\n - fs/nffs # include the NFFS filesystem implementation\n\n\n\n\n\n# repos/apache-mynewt-core/apps/slinky/syscfg.yml\n# [...]\n # Package: apps/\nexample app\n\n# [...]\n CONFIG_NFFS: 1 # initialize and configure NFFS into the system\n# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues \n# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect\n\n# [...]\n\n\n\n\n\nConsult the documentation for \nnffs\n for a more detailed explanation of NFFS_DETECT_FAIL\n\n\nCode which uses the file system after the system has been initialized need only depend on \nfs/fs\n. For example, the \nlibs/imgmgr\n package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the \nfs/fs\n package.\n\n\n# repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...]\n\n\n\n\n\nThe \nlibs/imgmgr\n package uses the \nfs/fs\n API for all file system operations.\n\n\nSupport for multiple filesystems\n\n\nWhen using a single filesystem/disk, it is valid to provide paths in the standard\nunix way, eg, \n/\ndir-name\n/\nfile-name\n. When trying to run more than one filesystem\nor a single filesystem in multiple devices simultaneosly, an extra name has to be\ngiven to the disk that is being used. The abstraction for that was added as the\n\nfs/disk\n package which is a dependency of \nfs/fs\n. It adds the following extra\nuser function:\n\n\nint\n \ndisk_register\n(\nconst\n \nchar\n \n*disk_name\n, \nconst\n \nchar\n \n*fs_name\n, \nstruct\n \ndisk_ops\n \n*dops\n)\n\n\n\n\n\nAs an example os usage:\n\n\ndisk_register\n(\nmmc0\n, \nfatfs\n, \nmmc_ops\n);\n\ndisk_register\n(\nflash0\n, \nnffs\n, \nNULL\n);\n\n\n\n\n\nThis registers the name \nmmc0\n to use \nfatfs\n as the filesystem and \nmmc_ops\n for\nthe low-level disk driver and also registers \nflash0\n to use \nnffs\n. \nnffs\n is\ncurrently strongly bound to the \nhal_flash\n interface, ignoring any other possible\n\ndisk_ops\n given.\n\n\nstruct disk_ops\n\n\nTo support a new low-level disk interface, the \nstruct disk_ops\n interface must\nbe implemented by the low-level driver. Currently only \nread\n and \nwrite\n are\neffectively used (by \nfatfs\n).\n\n\nstruct\n \ndisk_ops\n {\n \nint\n (\n*read\n)(\nuint8_t\n, \nuint32_t\n, \nvoid\n \n*\n, \nuint32_t\n);\n \nint\n (\n*write\n)(\nuint8_t\n, \nuint32_t\n, \nconst\n \nvoid\n \n*\n, \nuint32_t\n);\n \nint\n (\n*ioctl\n)(\nuint8_t\n, \nuint32_t\n, \nvoid\n \n*\n);\n \nSLIST_ENTRY\n(\ndisk_ops\n) \nsc_next\n;\n}\n\n\n\n\n\nThread Safety\n\n\nAll \nfs/fs\n functions are thread safe.\n\n\nHeader Files\n\n\nAll code which uses the \nfs/fs\n package needs to include the following header:\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nData Structures\n\n\nAll \nfs/fs\n data structures are opaque to client code.\n\n\nstruct\n \nfs_file\n;\n\nstruct\n \nfs_dir\n;\n\nstruct\n \nfs_dirent\n;\n\n\n\n\n\nAPI\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\nReturn Codes\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfs_close\n\n\nCloses the specified file and invalidates the file handle.\n\n\n\n\n\n\nfs_closedir\n\n\nCloses the specified directory handle.\n\n\n\n\n\n\nfs_dirent_is_dir\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file.\n\n\n\n\n\n\nfs_dirent_name\n\n\nRetrieves the filename of the specified directory entry.\n\n\n\n\n\n\nfs_filelen\n\n\nRetrieves the current length of the specified open file.\n\n\n\n\n\n\nfs_getpos\n\n\nRetrieves the current read and write position of the specified open file.\n\n\n\n\n\n\nfs_mkdir\n\n\nCreates the directory represented by the specified path.\n\n\n\n\n\n\nfs_open\n\n\nOpens a file at the specified path.\n\n\n\n\n\n\nfs_opendir\n\n\nOpens the directory at the specified path.\n\n\n\n\n\n\nfs_read\n\n\nReads data from the specified file.\n\n\n\n\n\n\nfs_readdir\n\n\nReads the next entry in an open directory.\n\n\n\n\n\n\nfs_register\n\n\nRegisters a file system with the abstraction layer.\n\n\n\n\n\n\nfs_rename\n\n\nPerforms a rename and/or move of the specified source path to the specified destination.\n\n\n\n\n\n\nfs_seek\n\n\nPositions a file's read and write pointer at the specified offset.\n\n\n\n\n\n\nfs_unlink\n\n\nUnlinks the file or directory at the specified path.\n\n\n\n\n\n\nfs_write\n\n\nWrites the supplied data to the current offset of the specified file handle.\n\n\n\n\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfsutil_read_file\n\n\nOpens a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\n\n\n\n\nfsutil_write_file\n\n\nOpen a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.",
- "title": "toc"
- },
- {
- "location": "/os/modules/fs/fs/fs/#file-system-abstraction",
- "text": "Mynewt provides a file system abstraction layer ( fs/fs ) to allow client code to be file system agnostic. By accessing the file system via the fs/fs API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the fs/fs API rather than accessing the underlying file system directly.",
- "title": "File System Abstraction"
- },
- {
- "location": "/os/modules/fs/fs/fs/#description",
- "text": "Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the fs/fs package.\nIn terms of the Mynewt hierarchy, an app package must depend on a specific file system package, while library packages should only depend on fs/fs . Applications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.\nIn the following example, the Newtron Flash File System \nis used. # repos/apache-mynewt-core/apps/slinky/pkg.yml\n\npkg.name: repos/apache-mynewt-core/apps/slinky\npkg.deps:\n - fs/fs # include the file operations interfaces\n - fs/nffs # include the NFFS filesystem implementation # repos/apache-mynewt-core/apps/slinky/syscfg.yml\n# [...]\n # Package: apps/ example app \n# [...]\n CONFIG_NFFS: 1 # initialize and configure NFFS into the system\n# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues \n# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect\n\n# [...] Consult the documentation for nffs for a more detailed explanation of NFFS_DETECT_FAIL Code which uses the file system after the system has been initialized need only depend on fs/fs . For example, the libs/imgmgr package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the fs/fs package. # repos/apache-mynewt-core/libs/imgmgr/pkg.yml\npkg.name: libs/imgmgr\npkg.deps:\n - fs/fs\n\n# [...] The libs/imgmgr package uses the fs/fs API for all file system operations.",
- "title": "Description"
- },
- {
- "location": "/os/modules/fs/fs/fs/#support-for-multiple-filesystems",
- "text": "When using a single filesystem/disk, it is valid to provide paths in the standard\nunix way, eg, / dir-name / file-name . When trying to run more than one filesystem\nor a single filesystem in multiple devices simultaneosly, an extra name has to be\ngiven to the disk that is being used. The abstraction for that was added as the fs/disk package which is a dependency of fs/fs . It adds the following extra\nuser function: int disk_register ( const char *disk_name , const char *fs_name , struct disk_ops *dops ) As an example os usage: disk_register ( mmc0 , fatfs , mmc_ops ); disk_register ( flash0 , nffs , NULL ); This registers the name mmc0 to use fatfs as the filesystem and mmc_ops for\nthe low-level disk driver and also registers flash0 to use nffs . nffs is\ncurrently strongly bound to the hal_flash interface, ignoring any other possible disk_ops given.",
- "title": "Support for multiple filesystems"
- },
- {
- "location": "/os/modules/fs/fs/fs/#struct-disk_ops",
- "text": "To support a new low-level disk interface, the struct disk_ops interface must\nbe implemented by the low-level driver. Currently only read and write are\neffectively used (by fatfs ). struct disk_ops {\n int ( *read )( uint8_t , uint32_t , void * , uint32_t );\n int ( *write )( uint8_t , uint32_t , const void * , uint32_t );\n int ( *ioctl )( uint8_t , uint32_t , void * );\n SLIST_ENTRY ( disk_ops ) sc_next ;\n}",
- "title": "struct disk_ops"
- },
- {
- "location": "/os/modules/fs/fs/fs/#thread-safety",
- "text": "All fs/fs functions are thread safe.",
- "title": "Thread Safety"
- },
- {
- "location": "/os/modules/fs/fs/fs/#header-files",
- "text": "All code which uses the fs/fs package needs to include the following header: #include fs/fs.h",
- "title": "Header Files"
- },
- {
- "location": "/os/modules/fs/fs/fs/#data-structures",
- "text": "All fs/fs data structures are opaque to client code. struct fs_file ; struct fs_dir ; struct fs_dirent ;",
- "title": "Data Structures"
- },
- {
- "location": "/os/modules/fs/fs/fs_return_codes/",
- "text": "fs/fs Return Codes\n\n\nFunctions in \nfs/fs\n that indicate success or failure do so with the following set of return codes:\n\n\n\n\n\n\n\n\nReturn code\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nFS_EOK\n\n\nSuccess\n\n\n\n\n\n\nFS_ECORRUPT\n\n\nFile system corrupt\n\n\n\n\n\n\nFS_EHW\n\n\nError accessing storage medium\n\n\n\n\n\n\nFS_EOFFSET\n\n\nInvalid offset\n\n\n\n\n\n\nFS_EINVAL\n\n\nInvalid argument\n\n\n\n\n\n\nFS_ENOMEM\n\n\nInsufficient memory\n\n\n\n\n\n\nFS_ENOENT\n\n\nNo such file or directory\n\n\n\n\n\n\nFS_EEMPTY\n\n\nSpecified region is empty (internal only)\n\n\n\n\n\n\nFS_EFULL\n\n\nDisk full\n\n\n\n\n\n\nFS_EUNEXP\n\n\nDisk contains unexpected metadata\n\n\n\n\n\n\nFS_EOS\n\n\nOS error\n\n\n\n\n\n\nFS_EEXIST\n\n\nFile or directory already exists\n\n\n\n\n\n\nFS_EACCESS\n\n\nOperation prohibited by file open mode\n\n\n\n\n\n\nFS_EUNINIT\n\n\nFile system not initialized\n\n\n\n\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h",
- "title": "Return Codes"
- },
- {
- "location": "/os/modules/fs/fs/fs_return_codes/#fsfs-return-codes",
- "text": "Functions in fs/fs that indicate success or failure do so with the following set of return codes: Return code Description FS_EOK Success FS_ECORRUPT File system corrupt FS_EHW Error accessing storage medium FS_EOFFSET Invalid offset FS_EINVAL Invalid argument FS_ENOMEM Insufficient memory FS_ENOENT No such file or directory FS_EEMPTY Specified region is empty (internal only) FS_EFULL Disk full FS_EUNEXP Disk contains unexpected metadata FS_EOS OS error FS_EEXIST File or directory already exists FS_EACCESS Operation prohibited by file open mode FS_EUNINIT File system not initialized",
- "title": "fs/fs Return Codes"
- },
- {
- "location": "/os/modules/fs/fs/fs_return_codes/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_ops/",
- "text": "struct fs_ops\n\n\nstruct\n \nfs_ops\n {\n \nint\n (\n*f_open\n)(\nconst\n \nchar\n \n*filename\n, \nuint8_t\n \naccess_flags\n,\n \nstruct\n \nfs_file\n \n**out_file\n);\n \nint\n (\n*f_close\n)(\nstruct\n \nfs_file\n \n*file\n);\n \nint\n (\n*f_read\n)(\nstruct\n \nfs_file\n \n*file\n, \nuint32_t\n \nlen\n, \nvoid\n \n*out_data\n,\n \nuint32_t\n \n*out_len\n);\n \nint\n (\n*f_write\n)(\nstruct\n \nfs_file\n \n*file\n, \nconst\n \nvoid\n \n*data\n, \nint\n \nlen\n);\n\n \nint\n (\n*f_seek\n)(\nstruct\n \nfs_file\n \n*file\n, \nuint32_t\n \noffset\n);\n \nuint32_t\n (\n*f_getpos\n)(\nconst\n \nstruct\n \nfs_file\n \n*file\n);\n \nint\n (\n*f_filelen\n)(\nconst\n \nstruct\n \nfs_file\n \n*file\n, \nuint32_t\n \n*out_len\n);\n\n \nint\n (\n*f_unlink\n)(\nconst\n \nchar\n \n*filename\n);\n \nint\n (\n*f_rename\n)(\nconst\n \nchar\n \n*from\n, \nconst\n \nchar\n \n*to\n);\n \nint\n (\n*f_mkdir\n)(\nconst\n \nchar\n \n*path\n);\n\n \nint\n (\n*f_opendir\n)(\nconst\n \nchar\n \n*path\n, \nstruct\n \nfs_dir\n \n**out_dir\n);\n \nint\n (\n*f_readdir\n)(\nstruct\n \nfs_dir\n \n*dir\n, \nstruct\n \nfs_dirent\n \n**out_dirent\n);\n \nint\n (\n*f_closedir\n)(\nstruct\n \nfs_dir\n \n*dir\n);\n\n \nint\n (\n*f_dirent_name\n)(\nconst\n \nstruct\n \nfs_dirent\n \n*dirent\n, \nsize_t\n \nmax_len\n,\n \nchar\n \n*out_name\n, \nuint8_t\n \n*out_name_len\n);\n \nint\n (\n*f_dirent_is_dir\n)(\nconst\n \nstruct\n \nfs_dirent\n \n*dirent\n);\n\n \nconst\n \nchar\n \n*f_name\n;\n};\n\n\n\n\n\nThis data structure consists of a set of function pointers. Each function pointer corresponds to a file system operation. When registering a file system with the abstraction layer, each function pointer must be pointed at the corresponding routine in the custom file system package.\n\n\nThe required behavior of each corresponding function is documented in the \nfile system abstraction layer API\n.\n\n\nHeader file\n\n\n#include\n \nfs/fs_if.h",
- "title": "struct fs_ops"
- },
- {
- "location": "/os/modules/fs/fs/fs_ops/#struct-fs95ops",
- "text": "struct fs_ops {\n int ( *f_open )( const char *filename , uint8_t access_flags ,\n struct fs_file **out_file );\n int ( *f_close )( struct fs_file *file );\n int ( *f_read )( struct fs_file *file , uint32_t len , void *out_data ,\n uint32_t *out_len );\n int ( *f_write )( struct fs_file *file , const void *data , int len );\n\n int ( *f_seek )( struct fs_file *file , uint32_t offset );\n uint32_t ( *f_getpos )( const struct fs_file *file );\n int ( *f_filelen )( const struct fs_file *file , uint32_t *out_len );\n\n int ( *f_unlink )( const char *filename );\n int ( *f_rename )( const char *from , const char *to );\n int ( *f_mkdir )( const char *path );\n\n int ( *f_opendir )( const char *path , struct fs_dir **out_dir );\n int ( *f_readdir )( struct fs_dir *dir , struct fs_dirent **out_dirent );\n int ( *f_closedir )( struct fs_dir *dir );\n\n int ( *f_dirent_name )( const struct fs_dirent *dirent , size_t max_len ,\n char *out_name , uint8_t *out_name_len );\n int ( *f_dirent_is_dir )( const struct fs_dirent *dirent );\n\n const char *f_name ;\n}; This data structure consists of a set of function pointers. Each function pointer corresponds to a file system operation. When registering a file system with the abstraction layer, each function pointer must be pointed at the corresponding routine in the custom file system package. The required behavior of each corresponding function is documented in the file system abstraction layer API .",
- "title": "struct fs_ops"
- },
- {
- "location": "/os/modules/fs/fs/fs_ops/#header-file",
- "text": "#include fs/fs_if.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/",
- "text": "fs_close\n\n\nint\n \nfs_close\n(\nstruct\n \nfs_file\n \n*file\n)\n\n\n\n\n\nCloses the specified file and invalidates the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nIf the file has already been unlinked, and the file has no other open handles, the \nfs_close()\n function causes the file to be deleted from the disk.\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThe below code opens the file \n/settings/config.txt\n for reading, reads some data, and then closes the file.\n\n\nint\n\n\nread_config\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nuint32_t\n \nbytes_read\n;\n \nuint8_t\n \nbuf\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Open the file for reading. */\n\n \nrc\n \n=\n \nfs_open\n(\n/settings/config.txt\n, \nFS_ACCESS_READ\n, \nfile\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read up to 16 bytes from the file. */\n\n \nrc\n \n=\n \nfs_read\n(\nfile\n, \nsizeof\n \nbuf\n, \nbuf\n, \nbytes_read\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* buf now contains up to 16 bytes of file data. */\n\n \nconsole_printf\n(\nread %u bytes\\n\n, \nbytes_read\n)\n }\n\n \n/* Close the file. */\n\n \nfs_close\n(\nfile\n);\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_close"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/#fs95close",
- "text": "int fs_close ( struct fs_file *file ) Closes the specified file and invalidates the file handle.",
- "title": "fs_close"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/#arguments",
- "text": "Argument Description file Pointer to the file to close",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/#notes",
- "text": "If the file has already been unlinked, and the file has no other open handles, the fs_close() function causes the file to be deleted from the disk.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_close/#example",
- "text": "The below code opens the file /settings/config.txt for reading, reads some data, and then closes the file. int read_config ( void )\n{\n struct fs_file *file ;\n uint32_t bytes_read ;\n uint8_t buf [ 16 ];\n int rc ;\n\n /* Open the file for reading. */ \n rc = fs_open ( /settings/config.txt , FS_ACCESS_READ , file );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Read up to 16 bytes from the file. */ \n rc = fs_read ( file , sizeof buf , buf , bytes_read );\n if ( rc == 0 ) {\n /* buf now contains up to 16 bytes of file data. */ \n console_printf ( read %u bytes\\n , bytes_read )\n }\n\n /* Close the file. */ \n fs_close ( file );\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_closedir/",
- "text": "fs_closedir\n\n\nint\n \nfs_closedir\n(\nstruct\n \nfs_dir\n \n*dir\n)\n\n\n\n\n\nCloses the specified directory handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nThe name of the directory to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle.\n\n\nint\n\n\ntraverse_dir\n(\nconst\n \nchar\n \n*dirname\n)\n{\n \nstruct\n \nfs_dirent\n \n*dirent\n;\n \nstruct\n \nfs_dir\n \n*dir\n;\n \nchar\n \nbuf\n[\n64\n];\n \nuint8_t\n \nname_len\n;\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_opendir\n(\ndirname\n, \ndir\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Iterate through the parent directory, printing the name of each child\n\n\n * entry. The loop only terminates via a function return.\n\n\n */\n\n \nwhile\n (\n1\n) {\n \n/* Retrieve the next child node. */\n\n \nrc\n \n=\n \nfs_readdir\n(\ndir\n, \ndirent\n); \n \nif\n (\nrc\n \n==\n \nFS_ENOENT\n) {\n \n/* Traversal complete. */\n\n \nreturn\n \n0\n;\n } \nelse\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Unexpected error. */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read the child node\ns name from the file system. */\n\n \nrc\n \n=\n \nfs_dirent_name\n(\ndirent\n, \nsizeof\n \nbuf\n, \nbuf\n, \nname_len\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Print the child node\ns name to the console. */\n\n \nif\n (\nfs_dirent_is_dir\n(\ndirent\n)) {\n \nconsole_printf\n(\n dir: \n);\n } \nelse\n {\n \nconsole_printf\n(\nfile: \n);\n }\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n }\n}",
- "title": "fs_closedir"
- },
- {
- "location": "/os/modules/fs/fs/fs_closedir/#fs95closedir",
- "text": "int fs_closedir ( struct fs_dir *dir ) Closes the specified directory handle.",
- "title": "fs_closedir"
- },
- {
- "location": "/os/modules/fs/fs/fs_closedir/#arguments",
- "text": "Argument Description dir The name of the directory to close",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_closedir/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_closedir/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_closedir/#example",
- "text": "This example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle. int traverse_dir ( const char *dirname )\n{\n struct fs_dirent *dirent ;\n struct fs_dir *dir ;\n char buf [ 64 ];\n uint8_t name_len ;\n int rc ;\n\n rc = fs_opendir ( dirname , dir );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Iterate through the parent directory, printing the name of each child * entry. The loop only terminates via a function return. */ \n while ( 1 ) {\n /* Retrieve the next child node. */ \n rc = fs_readdir ( dir , dirent ); \n if ( rc == FS_ENOENT ) {\n /* Traversal complete. */ \n return 0 ;\n } else if ( rc != 0 ) {\n /* Unexpected error. */ \n return - 1 ;\n }\n\n /* Read the child node s name from the file system. */ \n rc = fs_dirent_name ( dirent , sizeof buf , buf , name_len );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Print the child node s name to the console. */ \n if ( fs_dirent_is_dir ( dirent )) {\n console_printf ( dir: );\n } else {\n console_printf ( file: );\n }\n console_printf ( %s\\n , buf );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_is_dir/",
- "text": "fs_dirent_is_dir\n\n\nint\n \nfs_dirent_is_dir\n(\nconst\n \nstruct\n \nfs_dirent\n \n*dirent\n)\n\n\n\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n1: The entry is a directory\n\n\n0: The entry is a regular file.\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle.\n\n\nint\n\n\ntraverse_dir\n(\nconst\n \nchar\n \n*dirname\n)\n{\n \nstruct\n \nfs_dirent\n \n*dirent\n;\n \nstruct\n \nfs_dir\n \n*dir\n;\n \nchar\n \nbuf\n[\n64\n];\n \nuint8_t\n \nname_len\n;\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_opendir\n(\ndirname\n, \ndir\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Iterate through the parent directory, printing the name of each child\n\n\n * entry. The loop only terminates via a function return.\n\n\n */\n\n \nwhile\n (\n1\n) {\n \n/* Retrieve the next child node. */\n\n \nrc\n \n=\n \nfs_readdir\n(\ndir\n, \ndirent\n); \n \nif\n (\nrc\n \n==\n \nFS_ENOENT\n) {\n \n/* Traversal complete. */\n\n \nreturn\n \n0\n;\n } \nelse\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Unexpected error. */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read the child node\ns name from the file system. */\n\n \nrc\n \n=\n \nfs_dirent_name\n(\ndirent\n, \nsizeof\n \nbuf\n, \nbuf\n, \nname_len\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Print the child node\ns name to the console. */\n\n \nif\n (\nfs_dirent_is_dir\n(\ndirent\n)) {\n \nconsole_printf\n(\n dir: \n);\n } \nelse\n {\n \nconsole_printf\n(\nfile: \n);\n }\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n }\n}",
- "title": "fs_dirent_is_dir"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_is_dir/#fs95dirent95is95dir",
- "text": "int fs_dirent_is_dir ( const struct fs_dirent *dirent ) Tells you whether the specified directory entry is a sub-directory or a regular file.",
- "title": "fs_dirent_is_dir"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_is_dir/#arguments",
- "text": "Argument Description dirent Pointer to the directory entry to query",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_is_dir/#returned-values",
- "text": "1: The entry is a directory 0: The entry is a regular file.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_is_dir/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_is_dir/#example",
- "text": "This example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle. int traverse_dir ( const char *dirname )\n{\n struct fs_dirent *dirent ;\n struct fs_dir *dir ;\n char buf [ 64 ];\n uint8_t name_len ;\n int rc ;\n\n rc = fs_opendir ( dirname , dir );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Iterate through the parent directory, printing the name of each child * entry. The loop only terminates via a function return. */ \n while ( 1 ) {\n /* Retrieve the next child node. */ \n rc = fs_readdir ( dir , dirent ); \n if ( rc == FS_ENOENT ) {\n /* Traversal complete. */ \n return 0 ;\n } else if ( rc != 0 ) {\n /* Unexpected error. */ \n return - 1 ;\n }\n\n /* Read the child node s name from the file system. */ \n rc = fs_dirent_name ( dirent , sizeof buf , buf , name_len );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Print the child node s name to the console. */ \n if ( fs_dirent_is_dir ( dirent )) {\n console_printf ( dir: );\n } else {\n console_printf ( file: );\n }\n console_printf ( %s\\n , buf );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/",
- "text": "fs_dirent_name\n\n\nint\n \nfs_dirent_name\n(\nconst\n \nstruct\n \nfs_dirent\n \n*dirent\n, \nsize_t\n \nmax_len\n,\n \nchar\n \n*out_name\n, \nuint8_t\n \n*out_name_len\n)\n\n\n\n\n\nRetrieves the filename of the specified directory entry. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\nmax_len\n\n\nSize of the \"out_name\" character buffer\n\n\n\n\n\n\nout_name\n\n\nOn success, the entry's filename is written here; always null-terminated\n\n\n\n\n\n\nout_name_len\n\n\nOn success, contains the actual length of the filename, NOT including the null-terminator\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nThe retrieved filename is always null-terminated. To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size \nfilename-max-length + 1\n should be used.\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle.\n\n\nint\n\n\ntraverse_dir\n(\nconst\n \nchar\n \n*dirname\n)\n{\n \nstruct\n \nfs_dirent\n \n*dirent\n;\n \nstruct\n \nfs_dir\n \n*dir\n;\n \nchar\n \nbuf\n[\n64\n];\n \nuint8_t\n \nname_len\n;\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_opendir\n(\ndirname\n, \ndir\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Iterate through the parent directory, printing the name of each child\n\n\n * entry. The loop only terminates via a function return.\n\n\n */\n\n \nwhile\n (\n1\n) {\n \n/* Retrieve the next child node. */\n\n \nrc\n \n=\n \nfs_readdir\n(\ndir\n, \ndirent\n); \n \nif\n (\nrc\n \n==\n \nFS_ENOENT\n) {\n \n/* Traversal complete. */\n\n \nreturn\n \n0\n;\n } \nelse\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Unexpected error. */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read the child node\ns name from the file system. */\n\n \nrc\n \n=\n \nfs_dirent_name\n(\ndirent\n, \nsizeof\n \nbuf\n, \nbuf\n, \nname_len\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Print the child node\ns name to the console. */\n\n \nif\n (\nfs_dirent_is_dir\n(\ndirent\n)) {\n \nconsole_printf\n(\n dir: \n);\n } \nelse\n {\n \nconsole_printf\n(\nfile: \n);\n }\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n }\n}",
- "title": "fs_dirent_name"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/#fs95dirent95name",
- "text": "int fs_dirent_name ( const struct fs_dirent *dirent , size_t max_len ,\n char *out_name , uint8_t *out_name_len ) Retrieves the filename of the specified directory entry.",
- "title": "fs_dirent_name"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/#arguments",
- "text": "Argument Description dirent Pointer to the directory entry to query max_len Size of the \"out_name\" character buffer out_name On success, the entry's filename is written here; always null-terminated out_name_len On success, contains the actual length of the filename, NOT including the null-terminator",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/#notes",
- "text": "The retrieved filename is always null-terminated. To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size filename-max-length + 1 should be used.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_dirent_name/#example",
- "text": "This example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle. int traverse_dir ( const char *dirname )\n{\n struct fs_dirent *dirent ;\n struct fs_dir *dir ;\n char buf [ 64 ];\n uint8_t name_len ;\n int rc ;\n\n rc = fs_opendir ( dirname , dir );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Iterate through the parent directory, printing the name of each child * entry. The loop only terminates via a function return. */ \n while ( 1 ) {\n /* Retrieve the next child node. */ \n rc = fs_readdir ( dir , dirent ); \n if ( rc == FS_ENOENT ) {\n /* Traversal complete. */ \n return 0 ;\n } else if ( rc != 0 ) {\n /* Unexpected error. */ \n return - 1 ;\n }\n\n /* Read the child node s name from the file system. */ \n rc = fs_dirent_name ( dirent , sizeof buf , buf , name_len );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Print the child node s name to the console. */ \n if ( fs_dirent_is_dir ( dirent )) {\n console_printf ( dir: );\n } else {\n console_printf ( file: );\n }\n console_printf ( %s\\n , buf );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_filelen/",
- "text": "fs_filelen\n\n\nint\n \nfs_filelen\n(\nconst\n \nstruct\n \nfs_file\n \n*file\n, \nuint32_t\n \n*out_len\n)\n\n\n\n\n\nRetrieves the current length of the specified open file.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes in the file gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nint\n\n\nwrite_config\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nint\n \nrc\n;\n\n \n/* If the file doesn\nt exist, create it. If it does exist, truncate it to\n\n\n * zero bytes.\n\n\n */\n\n \nrc\n \n=\n \nfs_open\n(\n/settings/config.txt\n, \nFS_ACCESS_WRITE\n \n|\n \nFS_ACCESS_TRUNCATE\n,\n \nfile\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* Write 5 bytes of data to the file. */\n\n \nrc\n \n=\n \nfs_write\n(\nfile\n, \nhello\n, \n5\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* The file should now contain exactly five bytes. */\n\n \nassert\n(\nfs_filelen\n(\nfile\n) \n==\n \n5\n);\n }\n\n \n/* Close the file. */\n\n \nfs_close\n(\nfile\n);\n }\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_filelen"
- },
- {
- "location": "/os/modules/fs/fs/fs_filelen/#fs95filelen",
- "text": "int fs_filelen ( const struct fs_file *file , uint32_t *out_len ) Retrieves the current length of the specified open file.",
- "title": "fs_filelen"
- },
- {
- "location": "/os/modules/fs/fs/fs_filelen/#arguments",
- "text": "Argument Description file Pointer to the file to query out_len On success, the number of bytes in the file gets written here",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_filelen/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_filelen/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_filelen/#example",
- "text": "int write_config ( void )\n{\n struct fs_file *file ;\n int rc ;\n\n /* If the file doesn t exist, create it. If it does exist, truncate it to * zero bytes. */ \n rc = fs_open ( /settings/config.txt , FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE ,\n file );\n if ( rc == 0 ) {\n /* Write 5 bytes of data to the file. */ \n rc = fs_write ( file , hello , 5 );\n if ( rc == 0 ) {\n /* The file should now contain exactly five bytes. */ \n assert ( fs_filelen ( file ) == 5 );\n }\n\n /* Close the file. */ \n fs_close ( file );\n }\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_getpos/",
- "text": "fs_getpos\n\n\nuint32_t\n \nfs_getpos\n(\nconst\n \nstruct\n \nfs_file\n \n*file\n)\n\n\n\n\n\nRetrieves the current read and write position of the specified open file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\nThe file offset, in bytes\n\n\n\n\nNotes\n\n\nIf a file is opened in append mode, its write pointer is always positioned at the end of the file. Calling this function on such a file only indicates the read position.\n\n\nHeader file\n\n\n#include\n \nfs/fs.h",
- "title": "fs_getpos"
- },
- {
- "location": "/os/modules/fs/fs/fs_getpos/#fs95getpos",
- "text": "uint32_t fs_getpos ( const struct fs_file *file ) Retrieves the current read and write position of the specified open file.",
- "title": "fs_getpos"
- },
- {
- "location": "/os/modules/fs/fs/fs_getpos/#arguments",
- "text": "Argument Description file Pointer to the file to query",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_getpos/#returned-values",
- "text": "The file offset, in bytes",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_getpos/#notes",
- "text": "If a file is opened in append mode, its write pointer is always positioned at the end of the file. Calling this function on such a file only indicates the read position.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_getpos/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/",
- "text": "fs_mkdir\n\n\nint\n \nfs_mkdir\n(\nconst\n \nchar\n \n*path\n)\n\n\n\n\n\nCreates the directory represented by the specified path. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nThe name of the directory to create\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure.\n\n\n\n\nNotes\n\n\nAll intermediate directories must already exist. The specified path must start with a '/' character.\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example demonstrates creating a series of nested directories.\n\n\nint\n\n\ncreate_path\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_mkdir\n(\n/data\n);\n \nif\n (\nrc\n \n!=\n \n0\n) \ngoto\n \nerr\n;\n\n \nrc\n \n=\n \nfs_mkdir\n(\n/data/logs\n);\n \nif\n (\nrc\n \n!=\n \n0\n) \ngoto\n \nerr\n;\n\n \nrc\n \n=\n \nfs_mkdir\n(\n/data/logs/temperature\n);\n \nif\n (\nrc\n \n!=\n \n0\n) \ngoto\n \nerr\n;\n\n \nrc\n \n=\n \nfs_mkdir\n(\n/data/logs/temperature/current\n);\n \nif\n (\nrc\n \n!=\n \n0\n) \ngoto\n \nerr\n;\n\n \nreturn\n \n0\n;\n\n\nerr\n:\n \n/* Clean up the incomplete directory tree, if any. */\n\n \nfs_unlink\n(\n/data\n);\n \nreturn\n \n-\n1\n;\n}",
- "title": "fs_mkdir"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/#fs95mkdir",
- "text": "int fs_mkdir ( const char *path ) Creates the directory represented by the specified path.",
- "title": "fs_mkdir"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/#arguments",
- "text": "Argument Description path The name of the directory to create",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/#returned-values",
- "text": "0 on success FS error code on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/#notes",
- "text": "All intermediate directories must already exist. The specified path must start with a '/' character.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_mkdir/#example",
- "text": "This example demonstrates creating a series of nested directories. int create_path ( void )\n{\n int rc ;\n\n rc = fs_mkdir ( /data );\n if ( rc != 0 ) goto err ;\n\n rc = fs_mkdir ( /data/logs );\n if ( rc != 0 ) goto err ;\n\n rc = fs_mkdir ( /data/logs/temperature );\n if ( rc != 0 ) goto err ;\n\n rc = fs_mkdir ( /data/logs/temperature/current );\n if ( rc != 0 ) goto err ;\n\n return 0 ; err :\n /* Clean up the incomplete directory tree, if any. */ \n fs_unlink ( /data );\n return - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/",
- "text": "fs_open\n\n\nint\n \nfs_open\n(\nconst\n \nchar\n \n*filename\n, \nuint8_t\n \naccess_flags\n,\n \nstruct\n \nfs_file\n \n**out_file\n)\n\n\n\n\n\nOpens a file at the specified path. The result of opening a nonexistent file depends on the access flags specified. All intermediate directories must already exist.\n\n\nThe access flags are best understood by comparing them to their equivalent mode strings accepted by the C standard library function \nfopen()\n.\nThe mode strings passed to \nfopen()\n map to \nfs_open()\n's access flags as follows:\n\n\nr\n - FS_ACCESS_READ\n\nr+\n - FS_ACCESS_READ | FS_ACCESS_WRITE\n\nw\n - FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n\nw+\n - FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n\na\n - FS_ACCESS_WRITE | FS_ACCESS_APPEND\n\na+\n - FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_APPEND\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nNull-terminated string indicating the full path of the file to open\n\n\n\n\n\n\naccess_flags\n\n\nFlags controlling file access; see above table\n\n\n\n\n\n\nout_file\n\n\nOn success, a pointer to the newly-created file handle gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\n\n\n\n\nThere is no concept of current working directory. Therefore all file names should start with '/'.\n\n\n\n\n\n\nAlways close files when you are done using them. If you forget to close a file, the file stays open forever. Do this too many times, and the underlying file system will run out of file handles, causing subsequent open operations to fail. This type of bug is known as a file handle leak or a file descriptor leak.\n\n\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThe below code opens the file \n/settings/config.txt\n for reading, reads some data, and then closes the file.\n\n\nint\n\n\nread_config\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nuint32_t\n \nbytes_read\n;\n \nuint8_t\n \nbuf\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Open the file for reading. */\n\n \nrc\n \n=\n \nfs_open\n(\n/settings/config.txt\n, \nFS_ACCESS_READ\n, \nfile\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read up to 16 bytes from the file. */\n\n \nrc\n \n=\n \nfs_read\n(\nfile\n, \nsizeof\n \nbuf\n, \nbuf\n, \nbytes_read\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* buf now contains up to 16 bytes of file data. */\n\n \nconsole_printf\n(\nread %u bytes\\n\n, \nbytes_read\n)\n }\n\n \n/* Close the file. */\n\n \nfs_close\n(\nfile\n);\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_open"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/#fs95open",
- "text": "int fs_open ( const char *filename , uint8_t access_flags ,\n struct fs_file **out_file ) Opens a file at the specified path. The result of opening a nonexistent file depends on the access flags specified. All intermediate directories must already exist. The access flags are best understood by comparing them to their equivalent mode strings accepted by the C standard library function fopen() .\nThe mode strings passed to fopen() map to fs_open() 's access flags as follows: r - FS_ACCESS_READ r+ - FS_ACCESS_READ | FS_ACCESS_WRITE w - FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE w+ - FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE a - FS_ACCESS_WRITE | FS_ACCESS_APPEND a+ - FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_APPEND",
- "title": "fs_open"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/#arguments",
- "text": "Argument Description filename Null-terminated string indicating the full path of the file to open access_flags Flags controlling file access; see above table out_file On success, a pointer to the newly-created file handle gets written here",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/#notes",
- "text": "There is no concept of current working directory. Therefore all file names should start with '/'. Always close files when you are done using them. If you forget to close a file, the file stays open forever. Do this too many times, and the underlying file system will run out of file handles, causing subsequent open operations to fail. This type of bug is known as a file handle leak or a file descriptor leak.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_open/#example",
- "text": "The below code opens the file /settings/config.txt for reading, reads some data, and then closes the file. int read_config ( void )\n{\n struct fs_file *file ;\n uint32_t bytes_read ;\n uint8_t buf [ 16 ];\n int rc ;\n\n /* Open the file for reading. */ \n rc = fs_open ( /settings/config.txt , FS_ACCESS_READ , file );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Read up to 16 bytes from the file. */ \n rc = fs_read ( file , sizeof buf , buf , bytes_read );\n if ( rc == 0 ) {\n /* buf now contains up to 16 bytes of file data. */ \n console_printf ( read %u bytes\\n , bytes_read )\n }\n\n /* Close the file. */ \n fs_close ( file );\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/",
- "text": "fs_opendir\n\n\nint\n \nfs_opendir\n(\nconst\n \nchar\n \n*path\n, \nstruct\n \nfs_dir\n \n**out_dir\n)\n\n\n\n\n\nOpens the directory at the specified path. The directory's contents can be read with subsequent calls to fs_readdir(). When you are done with the directory handle, close it with fs_closedir(). \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nThe name of the directory to open\n\n\n\n\n\n\nout_dir\n\n\nOn success, points to the directory handle\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if the specified directory does not exist\n\n\nOther \nFS error code\n on error.\n\n\n\n\nNotes\n\n\n\n\n\n\nUnlinking files from the directory while it is open may result in unpredictable behavior during subsequent calls to \nfs_readdir()\n. New files can be created inside the directory without causing problems.\n\n\n\n\n\n\nAlways close a directory when you are done reading from it. If you forget to close a directory, the directory stays open forever. Do this too many times, and the underlying file system will run out of directory handles, causing subsequent open operations to fail. This type of bug is known as a file handle leak or a file descriptor leak.\n\n\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle.\n\n\nint\n\n\ntraverse_dir\n(\nconst\n \nchar\n \n*dirname\n)\n{\n \nstruct\n \nfs_dirent\n \n*dirent\n;\n \nstruct\n \nfs_dir\n \n*dir\n;\n \nchar\n \nbuf\n[\n64\n];\n \nuint8_t\n \nname_len\n;\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_opendir\n(\ndirname\n, \ndir\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Iterate through the parent directory, printing the name of each child\n\n\n * entry. The loop only terminates via a function return.\n\n\n */\n\n \nwhile\n (\n1\n) {\n \n/* Retrieve the next child node. */\n\n \nrc\n \n=\n \nfs_readdir\n(\ndir\n, \ndirent\n); \n \nif\n (\nrc\n \n==\n \nFS_ENOENT\n) {\n \n/* Traversal complete. */\n\n \nreturn\n \n0\n;\n } \nelse\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Unexpected error. */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read the child node\ns name from the file system. */\n\n \nrc\n \n=\n \nfs_dirent_name\n(\ndirent\n, \nsizeof\n \nbuf\n, \nbuf\n, \nname_len\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Print the child node\ns name to the console. */\n\n \nif\n (\nfs_dirent_is_dir\n(\ndirent\n)) {\n \nconsole_printf\n(\n dir: \n);\n } \nelse\n {\n \nconsole_printf\n(\nfile: \n);\n }\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n }\n}",
- "title": "fs_opendir"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/#fs95opendir",
- "text": "int fs_opendir ( const char *path , struct fs_dir **out_dir ) Opens the directory at the specified path. The directory's contents can be read with subsequent calls to fs_readdir(). When you are done with the directory handle, close it with fs_closedir().",
- "title": "fs_opendir"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/#arguments",
- "text": "Argument Description path The name of the directory to open out_dir On success, points to the directory handle",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/#returned-values",
- "text": "0 on success FS_ENOENT if the specified directory does not exist Other FS error code on error.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/#notes",
- "text": "Unlinking files from the directory while it is open may result in unpredictable behavior during subsequent calls to fs_readdir() . New files can be created inside the directory without causing problems. Always close a directory when you are done reading from it. If you forget to close a directory, the directory stays open forever. Do this too many times, and the underlying file system will run out of directory handles, causing subsequent open operations to fail. This type of bug is known as a file handle leak or a file descriptor leak.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_opendir/#example",
- "text": "This example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle. int traverse_dir ( const char *dirname )\n{\n struct fs_dirent *dirent ;\n struct fs_dir *dir ;\n char buf [ 64 ];\n uint8_t name_len ;\n int rc ;\n\n rc = fs_opendir ( dirname , dir );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Iterate through the parent directory, printing the name of each child * entry. The loop only terminates via a function return. */ \n while ( 1 ) {\n /* Retrieve the next child node. */ \n rc = fs_readdir ( dir , dirent ); \n if ( rc == FS_ENOENT ) {\n /* Traversal complete. */ \n return 0 ;\n } else if ( rc != 0 ) {\n /* Unexpected error. */ \n return - 1 ;\n }\n\n /* Read the child node s name from the file system. */ \n rc = fs_dirent_name ( dirent , sizeof buf , buf , name_len );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Print the child node s name to the console. */ \n if ( fs_dirent_is_dir ( dirent )) {\n console_printf ( dir: );\n } else {\n console_printf ( file: );\n }\n console_printf ( %s\\n , buf );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_read/",
- "text": "fs_read\n\n\nint\n \nfs_read\n(\nstruct\n \nfs_file\n \n*file\n, \nuint32_t\n \nlen\n, \nvoid\n \n*out_data\n, \nuint32_t\n \n*out_len\n)\n\n\n\n\n\nReads data from the specified file. If more data is requested than remains in the file, all available data is retrieved and a success code is returned.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the the file to read from\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to attempt to read\n\n\n\n\n\n\nout_data\n\n\nThe destination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here. Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThe below code opens the file \n/settings/config.txt\n for reading, reads some data, and then closes the file.\n\n\nint\n\n\nread_config\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nuint32_t\n \nbytes_read\n;\n \nuint8_t\n \nbuf\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Open the file for reading. */\n\n \nrc\n \n=\n \nfs_open\n(\n/settings/config.txt\n, \nFS_ACCESS_READ\n, \nfile\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read up to 16 bytes from the file. */\n\n \nrc\n \n=\n \nfs_read\n(\nfile\n, \nsizeof\n \nbuf\n, \nbuf\n, \nbytes_read\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* buf now contains up to 16 bytes of file data. */\n\n \nconsole_printf\n(\nread %u bytes\\n\n, \nbytes_read\n)\n }\n\n \n/* Close the file. */\n\n \nfs_close\n(\nfile\n);\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_read"
- },
- {
- "location": "/os/modules/fs/fs/fs_read/#fs95read",
- "text": "int fs_read ( struct fs_file *file , uint32_t len , void *out_data , uint32_t *out_len ) Reads data from the specified file. If more data is requested than remains in the file, all available data is retrieved and a success code is returned.",
- "title": "fs_read"
- },
- {
- "location": "/os/modules/fs/fs/fs_read/#arguments",
- "text": "Argument Description file Pointer to the the file to read from len The number of bytes to attempt to read out_data The destination buffer to read into out_len On success, the number of bytes actually read gets written here. Pass null if you don't care.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_read/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_read/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_read/#example",
- "text": "The below code opens the file /settings/config.txt for reading, reads some data, and then closes the file. int read_config ( void )\n{\n struct fs_file *file ;\n uint32_t bytes_read ;\n uint8_t buf [ 16 ];\n int rc ;\n\n /* Open the file for reading. */ \n rc = fs_open ( /settings/config.txt , FS_ACCESS_READ , file );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Read up to 16 bytes from the file. */ \n rc = fs_read ( file , sizeof buf , buf , bytes_read );\n if ( rc == 0 ) {\n /* buf now contains up to 16 bytes of file data. */ \n console_printf ( read %u bytes\\n , bytes_read )\n }\n\n /* Close the file. */ \n fs_close ( file );\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_readdir/",
- "text": "fs_readdir\n\n\nint\n \nfs_readdir\n(\nstruct\n \nfs_dir\n \n*dir\n, \nstruct\n \nfs_dirent\n \n**out_dirent\n);\n\n\n\n\n\nReads the next entry in an open directory. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nThe directory handle to read from\n\n\n\n\n\n\nout_dirent\n\n\nOn success, points to the next child entry in the specified directory\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if there are no more entries in the parent directory\n\n\nOther \nFS error code\n on error.\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle.\n\n\nint\n\n\ntraverse_dir\n(\nconst\n \nchar\n \n*dirname\n)\n{\n \nstruct\n \nfs_dirent\n \n*dirent\n;\n \nstruct\n \nfs_dir\n \n*dir\n;\n \nchar\n \nbuf\n[\n64\n];\n \nuint8_t\n \nname_len\n;\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_opendir\n(\ndirname\n, \ndir\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Iterate through the parent directory, printing the name of each child\n\n\n * entry. The loop only terminates via a function return.\n\n\n */\n\n \nwhile\n (\n1\n) {\n \n/* Retrieve the next child node. */\n\n \nrc\n \n=\n \nfs_readdir\n(\ndir\n, \ndirent\n); \n \nif\n (\nrc\n \n==\n \nFS_ENOENT\n) {\n \n/* Traversal complete. */\n\n \nreturn\n \n0\n;\n } \nelse\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \n/* Unexpected error. */\n\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Read the child node\ns name from the file system. */\n\n \nrc\n \n=\n \nfs_dirent_name\n(\ndirent\n, \nsizeof\n \nbuf\n, \nbuf\n, \nname_len\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Print the child node\ns name to the console. */\n\n \nif\n (\nfs_dirent_is_dir\n(\ndirent\n)) {\n \nconsole_printf\n(\n dir: \n);\n } \nelse\n {\n \nconsole_printf\n(\nfile: \n);\n }\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n }\n}",
- "title": "fs_readdir"
- },
- {
- "location": "/os/modules/fs/fs/fs_readdir/#fs_readdir",
- "text": "int fs_readdir ( struct fs_dir *dir , struct fs_dirent **out_dirent ); Reads the next entry in an open directory.",
- "title": "fs_readdir"
- },
- {
- "location": "/os/modules/fs/fs/fs_readdir/#arguments",
- "text": "Argument Description dir The directory handle to read from out_dirent On success, points to the next child entry in the specified directory",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_readdir/#returned-values",
- "text": "0 on success FS_ENOENT if there are no more entries in the parent directory Other FS error code on error.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_readdir/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_readdir/#example",
- "text": "This example iterates through the contents of a directory, printing the name of each child node. When the traversal is complete, the code closes the directory handle. int traverse_dir ( const char *dirname )\n{\n struct fs_dirent *dirent ;\n struct fs_dir *dir ;\n char buf [ 64 ];\n uint8_t name_len ;\n int rc ;\n\n rc = fs_opendir ( dirname , dir );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Iterate through the parent directory, printing the name of each child * entry. The loop only terminates via a function return. */ \n while ( 1 ) {\n /* Retrieve the next child node. */ \n rc = fs_readdir ( dir , dirent ); \n if ( rc == FS_ENOENT ) {\n /* Traversal complete. */ \n return 0 ;\n } else if ( rc != 0 ) {\n /* Unexpected error. */ \n return - 1 ;\n }\n\n /* Read the child node s name from the file system. */ \n rc = fs_dirent_name ( dirent , sizeof buf , buf , name_len );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n /* Print the child node s name to the console. */ \n if ( fs_dirent_is_dir ( dirent )) {\n console_printf ( dir: );\n } else {\n console_printf ( file: );\n }\n console_printf ( %s\\n , buf );\n }\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_register/",
- "text": "fs_register\n\n\nint\n \nfs_register\n(\nconst\n \nstruct\n \nfs_ops\n \n*fops\n)\n\n\n\n\n\nRegisters a file system with the abstraction layer. On success, all calls into \nfs/fs\n will use the registered file system.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfops\n\n\nA pointer to const \nstruct fs_ops\n. Specifies which file system routines get mapped to the \nfs/fs\n API. All function pointers must be filled in.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_EEXIST\n if a file system has already been registered\n\n\n\n\nNotes\n\n\nOnly one file system can be registered. The registered file system is mounted in the root directory (\n/\n).\n\n\nHeader file\n\n\n#include\n \nfs/fs.h",
- "title": "fs_register"
- },
- {
- "location": "/os/modules/fs/fs/fs_register/#fs95register",
- "text": "int fs_register ( const struct fs_ops *fops ) Registers a file system with the abstraction layer. On success, all calls into fs/fs will use the registered file system.",
- "title": "fs_register"
- },
- {
- "location": "/os/modules/fs/fs/fs_register/#arguments",
- "text": "Argument Description fops A pointer to const struct fs_ops . Specifies which file system routines get mapped to the fs/fs API. All function pointers must be filled in.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_register/#returned-values",
- "text": "0 on success FS_EEXIST if a file system has already been registered",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_register/#notes",
- "text": "Only one file system can be registered. The registered file system is mounted in the root directory ( / ).",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_register/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/",
- "text": "fs_rename\n\n\nint\n \nfs_rename\n(\nconst\n \nchar\n \n*from\n, \nconst\n \nchar\n \n*to\n)\n\n\n\n\n\nPerforms a rename and / or move of the specified source path to the specified destination. The source path can refer to a file or a directory.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfrom\n\n\nThe source path\n\n\n\n\n\n\nto\n\n\nThe destination path\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nThe source path can refer to either a file or a directory. All intermediate directories in the destination path must already exist. If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory. If an object already exists at the specified destination path, this function causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example demonstrates how to use fs_rename() to perform a log rotation. In this example, there is one primary log and three archived logs. \nFS_ENOENT\n errors returned by \nfs_rename()\n are ignored; it is not an error if an archived log was never created.\n\n\nint\n\n\nrotate_logs\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nint\n \nrc\n;\n\n \n/* Rotate each of the log files. */\n\n \nrc\n \n=\n \nfs_rename\n(\n/var/log/messages.2\n, \n/var/log/messages.3\n)\n \nif\n (\nrc\n \n!=\n \n0\n \n \nrc\n \n!=\n \nFS_ENOENT\n) \nreturn\n \n-\n1\n;\n\n \nrc\n \n=\n \nfs_rename\n(\n/var/log/messages.1\n, \n/var/log/messages.2\n)\n \nif\n (\nrc\n \n!=\n \n0\n \n \nrc\n \n!=\n \nFS_ENOENT\n) \nreturn\n \n-\n1\n;\n\n \nrc\n \n=\n \nfs_rename\n(\n/var/log/messages.0\n, \n/var/log/messages.1\n)\n \nif\n (\nrc\n \n!=\n \n0\n \n \nrc\n \n!=\n \nFS_ENOENT\n) \nreturn\n \n-\n1\n;\n\n \nrc\n \n=\n \nfs_rename\n(\n/var/log/messages\n, \n/var/log/messages.0\n)\n \nif\n (\nrc\n \n!=\n \n0\n \n \nrc\n \n!=\n \nFS_ENOENT\n) \nreturn\n \n-\n1\n;\n\n \n/* Now create the new log file. */\n\n \nrc\n \n=\n \nfs_open\n(\n/var/log/messages\n, \nFS_ACCESS_WRITE\n \n|\n \nFS_ACCESS_TRUNCATE\n,\n \nfile\n);\n \nif\n (\nrc\n \n!=\n \n0\n) \nreturn\n \n-\n1\n;\n\n \nrc\n \n=\n \nfs_write\n(\nfile\n, \nCreating new log file.\\n\n, \n23\n);\n \nfs_close\n(\nfile\n);\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_rename"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/#fs95rename",
- "text": "int fs_rename ( const char *from , const char *to ) Performs a rename and / or move of the specified source path to the specified destination. The source path can refer to a file or a directory.",
- "title": "fs_rename"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/#arguments",
- "text": "Argument Description from The source path to The destination path",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/#notes",
- "text": "The source path can refer to either a file or a directory. All intermediate directories in the destination path must already exist. If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory. If an object already exists at the specified destination path, this function causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_rename/#example",
- "text": "This example demonstrates how to use fs_rename() to perform a log rotation. In this example, there is one primary log and three archived logs. FS_ENOENT errors returned by fs_rename() are ignored; it is not an error if an archived log was never created. int rotate_logs ( void )\n{\n struct fs_file *file ;\n int rc ;\n\n /* Rotate each of the log files. */ \n rc = fs_rename ( /var/log/messages.2 , /var/log/messages.3 )\n if ( rc != 0 rc != FS_ENOENT ) return - 1 ;\n\n rc = fs_rename ( /var/log/messages.1 , /var/log/messages.2 )\n if ( rc != 0 rc != FS_ENOENT ) return - 1 ;\n\n rc = fs_rename ( /var/log/messages.0 , /var/log/messages.1 )\n if ( rc != 0 rc != FS_ENOENT ) return - 1 ;\n\n rc = fs_rename ( /var/log/messages , /var/log/messages.0 )\n if ( rc != 0 rc != FS_ENOENT ) return - 1 ;\n\n /* Now create the new log file. */ \n rc = fs_open ( /var/log/messages , FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE ,\n file );\n if ( rc != 0 ) return - 1 ;\n\n rc = fs_write ( file , Creating new log file.\\n , 23 );\n fs_close ( file );\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/",
- "text": "fs_seek\n\n\nint\n \nfs_seek\n(\nstruct\n \nfs_file\n \n*file\n, \nuint32_t\n \noffset\n)\n\n\n\n\n\nPositions a file's read and write pointer at the specified offset. The offset is expressed as the number of bytes from the start of the file (i.e., seeking to offset 0 places the pointer at the first byte in the file).\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to reposition\n\n\n\n\n\n\noffset\n\n\nThe 0-based file offset to seek to\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nIf a file is opened in append mode, its write pointer is always positioned at the end of the file. Calling this function on such a file only affects the read pointer.\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThe following example reads four bytes from a file, starting at an offset of eight.\n\n\nint\n\n\nread_part1_middle\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nuint32_t\n \nbytes_read\n;\n \nuint8_t\n \nbuf\n[\n4\n];\n \nint\n \nrc\n;\n\n \nrc\n \n=\n \nfs_open\n(\n/data/parts/1.bin\n, \nFS_ACCESS_READ\n, \nfile\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* Advance to offset 8. */\n\n \nrc\n \n=\n \nfs_seek\n(\nfile\n, \n8\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* Read bytes 8, 9, 10, and 11. */\n\n \nrc\n \n=\n \nfs_read\n(\nfile\n, \n4\n, \nbuf\n, \nbytes_read\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* buf now contains up to 4 bytes of file data. */\n\n \nconsole_printf\n(\nread %u bytes\\n\n, \nbytes_read\n)\n }\n }\n\n \n/* Close the file. */\n\n \nfs_close\n(\nfile\n);\n }\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_seek"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/#fs95seek",
- "text": "int fs_seek ( struct fs_file *file , uint32_t offset ) Positions a file's read and write pointer at the specified offset. The offset is expressed as the number of bytes from the start of the file (i.e., seeking to offset 0 places the pointer at the first byte in the file).",
- "title": "fs_seek"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/#arguments",
- "text": "Argument Description file Pointer to the file to reposition offset The 0-based file offset to seek to",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/#notes",
- "text": "If a file is opened in append mode, its write pointer is always positioned at the end of the file. Calling this function on such a file only affects the read pointer.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_seek/#example",
- "text": "The following example reads four bytes from a file, starting at an offset of eight. int read_part1_middle ( void )\n{\n struct fs_file *file ;\n uint32_t bytes_read ;\n uint8_t buf [ 4 ];\n int rc ;\n\n rc = fs_open ( /data/parts/1.bin , FS_ACCESS_READ , file );\n if ( rc == 0 ) {\n /* Advance to offset 8. */ \n rc = fs_seek ( file , 8 );\n if ( rc == 0 ) {\n /* Read bytes 8, 9, 10, and 11. */ \n rc = fs_read ( file , 4 , buf , bytes_read );\n if ( rc == 0 ) {\n /* buf now contains up to 4 bytes of file data. */ \n console_printf ( read %u bytes\\n , bytes_read )\n }\n }\n\n /* Close the file. */ \n fs_close ( file );\n }\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_unlink/",
- "text": "fs_unlink\n\n\nint\n \nfs_unlink\n(\nconst\n \nchar\n \n*filename\n)\n\n\n\n\n\nUnlinks the file or directory at the specified path. This is the function to use if you want to delete a file or directory from the disk. If the path refers to a directory, all the directory's descendants are recursively unlinked. Any open file handles referring to an unlinked file remain valid, and can be read from and written to as long as they remain open.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nThe path of the file or directory to unlink\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThe following example creates a file and then immediately unlinks it. By unlinking the file, this function prevents other OS tasks from accessing it. When the function closes the file, it is deleted from the disk.\n\n\nint\n\n\nprocess_data\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nint\n \nrc\n;\n\n \n/* If the file doesn\nt exist, create it. If it does exist, truncate it to\n\n\n * zero bytes.\n\n\n */\n\n \nrc\n \n=\n \nfs_open\n(\n/tmp/buffer.bin\n, \nFS_ACCESS_WRITE\n \n|\n \nFS_ACCESS_TRUNCATE\n, \nfile\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* Unlink the file so that other tasks cannot access it. */\n\n \nfs_unlink\n(\n/tmp/buffer.bin\n)\n\n \n/* \nuse the file as a data buffer\n */\n\n\n \n/* Close the file. This operation causes the file to be deleted from\n\n\n * the disk because it was unlinked earlier (and it has no other open\n\n\n * file handles).\n\n\n */\n\n \nfs_close\n(\nfile\n);\n }\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_unlink"
- },
- {
- "location": "/os/modules/fs/fs/fs_unlink/#fs95unlink",
- "text": "int fs_unlink ( const char *filename ) Unlinks the file or directory at the specified path. This is the function to use if you want to delete a file or directory from the disk. If the path refers to a directory, all the directory's descendants are recursively unlinked. Any open file handles referring to an unlinked file remain valid, and can be read from and written to as long as they remain open.",
- "title": "fs_unlink"
- },
- {
- "location": "/os/modules/fs/fs/fs_unlink/#arguments",
- "text": "Argument Description filename The path of the file or directory to unlink",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_unlink/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_unlink/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_unlink/#example",
- "text": "The following example creates a file and then immediately unlinks it. By unlinking the file, this function prevents other OS tasks from accessing it. When the function closes the file, it is deleted from the disk. int process_data ( void )\n{\n struct fs_file *file ;\n int rc ;\n\n /* If the file doesn t exist, create it. If it does exist, truncate it to * zero bytes. */ \n rc = fs_open ( /tmp/buffer.bin , FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE , file );\n if ( rc == 0 ) {\n /* Unlink the file so that other tasks cannot access it. */ \n fs_unlink ( /tmp/buffer.bin )\n\n /* use the file as a data buffer */ \n\n /* Close the file. This operation causes the file to be deleted from * the disk because it was unlinked earlier (and it has no other open * file handles). */ \n fs_close ( file );\n }\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/",
- "text": "fs_write\n\n\nint\n \nfs_write\n(\nstruct\n \nfs_file\n \n*file\n, \nconst\n \nvoid\n \n*data\n, \nint\n \nlen\n)\n\n\n\n\n\nWrites the supplied data to the current offset of the specified file handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nFor files opened in append mode, the specified data is always written to the end.\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nint\n\n\nwrite_config\n(\nvoid\n)\n{\n \nstruct\n \nfs_file\n \n*file\n;\n \nint\n \nrc\n;\n\n \n/* If the file doesn\nt exist, create it. If it does exist, truncate it to\n\n\n * zero bytes.\n\n\n */\n\n \nrc\n \n=\n \nfs_open\n(\n/settings/config.txt\n, \nFS_ACCESS_WRITE\n \n|\n \nFS_ACCESS_TRUNCATE\n,\n \nfile\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* Write 5 bytes of data to the file. */\n\n \nrc\n \n=\n \nfs_write\n(\nfile\n, \nhello\n, \n5\n);\n \nif\n (\nrc\n \n==\n \n0\n) {\n \n/* The file should now contain exactly five bytes. */\n\n \nassert\n(\nfs_filelen\n(\nfile\n) \n==\n \n5\n);\n }\n\n \n/* Close the file. */\n\n \nfs_close\n(\nfile\n);\n }\n\n \nreturn\n \nrc\n \n==\n \n0\n \n?\n \n0\n \n:\n \n-\n1\n;\n}",
- "title": "fs_write"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/#fs95write",
- "text": "int fs_write ( struct fs_file *file , const void *data , int len ) Writes the supplied data to the current offset of the specified file handle.",
- "title": "fs_write"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/#arguments",
- "text": "Argument Description file Pointer to the file to write to data The data to write len The number of bytes to write",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/#notes",
- "text": "For files opened in append mode, the specified data is always written to the end.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fs_write/#example",
- "text": "int write_config ( void )\n{\n struct fs_file *file ;\n int rc ;\n\n /* If the file doesn t exist, create it. If it does exist, truncate it to * zero bytes. */ \n rc = fs_open ( /settings/config.txt , FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE ,\n file );\n if ( rc == 0 ) {\n /* Write 5 bytes of data to the file. */ \n rc = fs_write ( file , hello , 5 );\n if ( rc == 0 ) {\n /* The file should now contain exactly five bytes. */ \n assert ( fs_filelen ( file ) == 5 );\n }\n\n /* Close the file. */ \n fs_close ( file );\n }\n\n return rc == 0 ? 0 : - 1 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/",
- "text": "fsutil_read_file\n\n\nint\n \nfsutil_read_file\n(\nconst\n \nchar\n \n*path\n, \nuint32_t\n \noffset\n, \nuint32_t\n \nlen\n,\n \nvoid\n \n*dst\n, \nuint32_t\n \n*out_len\n)\n\n\n\n\n\nCalls fs_open(), fs_read(), and fs_close() to open a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\noffset\n\n\nPosition of the file's read pointer\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to attempt to read\n\n\n\n\n\n\ndst\n\n\nDestination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here. Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nNotes\n\n\nThis is a convenience function. It is useful when the amount of data to be read from the file is small (i.e., all the data read can easily fit in a single buffer).\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example demonstrates reading a small text file in its entirety and printing its contents to the console.\n\n\nint\n\n\nprint_status\n(\nvoid\n)\n{\n \nuint32_t\n \nbytes_read\n;\n \nuint8_t\n \nbuf\n[\n16\n];\n \nint\n \nrc\n;\n\n \n/* Read up to 15 bytes from the start of the file. */\n\n \nrc\n \n=\n \nfsutil_read_file\n(\n/cfg/status.txt\n, \n0\n, \nsizeof\n \nbuf\n \n-\n \n1\n, \nbuf\n,\n \nbytes_read\n);\n \nif\n (\nrc\n \n!=\n \n0\n) \nreturn\n \n-\n1\n;\n\n \n/* Null-terminate the string just read. */\n\n \nbuf\n[\nbytes_read\n] \n=\n \n\\0\n;\n\n \n/* Print the file contents to the console. */\n\n \nconsole_printf\n(\n%s\\n\n, \nbuf\n);\n\n \nreturn\n \n0\n;\n}",
- "title": "fsutil_read_file"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/#fsutil95read95file",
- "text": "int fsutil_read_file ( const char *path , uint32_t offset , uint32_t len ,\n void *dst , uint32_t *out_len ) Calls fs_open(), fs_read(), and fs_close() to open a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.",
- "title": "fsutil_read_file"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/#arguments",
- "text": "Argument Description path Pointer to the directory entry to query offset Position of the file's read pointer len Number of bytes to attempt to read dst Destination buffer to read into out_len On success, the number of bytes actually read gets written here. Pass null if you don't care.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/#notes",
- "text": "This is a convenience function. It is useful when the amount of data to be read from the file is small (i.e., all the data read can easily fit in a single buffer).",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_read_file/#example",
- "text": "This example demonstrates reading a small text file in its entirety and printing its contents to the console. int print_status ( void )\n{\n uint32_t bytes_read ;\n uint8_t buf [ 16 ];\n int rc ;\n\n /* Read up to 15 bytes from the start of the file. */ \n rc = fsutil_read_file ( /cfg/status.txt , 0 , sizeof buf - 1 , buf ,\n bytes_read );\n if ( rc != 0 ) return - 1 ;\n\n /* Null-terminate the string just read. */ \n buf [ bytes_read ] = \\0 ;\n\n /* Print the file contents to the console. */ \n console_printf ( %s\\n , buf );\n\n return 0 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_write_file/",
- "text": "fsutil_write_file\n\n\nint\n \nfsutil_write_file\n(\nconst\n \nchar\n \n*path\n, \nconst\n \nvoid\n \n*data\n, \nuint32_t\n \nlen\n)\n\n\n\n\n\nCalls fs_open(), fs_write(), and fs_close() to open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle. If the specified file already exists, it is truncated and overwritten with the specified data.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nfs/fs.h\n\n\n\n\n\n\nExample\n\n\nThis example creates a 4-byte file.\n\n\nint\n\n\nwrite_id\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Create the parent directory. */\n\n \nrc\n \n=\n \nfs_mkdir\n(\n/cfg\n);\n \nif\n (\nrc\n \n!=\n \n0\n \n \nrc\n \n!=\n \nFS_EALREADY\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \n/* Create a file and write four bytes to it. */\n\n \nrc\n \n=\n \nfsutil_write_file\n(\n/cfg/id.txt\n, \n1234\n, \n4\n);\n \nif\n (\nrc\n \n!=\n \n0\n) {\n \nreturn\n \n-\n1\n;\n }\n\n \nreturn\n \n0\n;\n}",
- "title": "fsutil_write_file"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_write_file/#fsutil95write95file",
- "text": "int fsutil_write_file ( const char *path , const void *data , uint32_t len ) Calls fs_open(), fs_write(), and fs_close() to open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle. If the specified file already exists, it is truncated and overwritten with the specified data.",
- "title": "fsutil_write_file"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_write_file/#arguments",
- "text": "Argument Description path Pointer to the file to write to data The data to write len The number of bytes to write",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_write_file/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_write_file/#header-file",
- "text": "#include fs/fs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/fs/fsutil_write_file/#example",
- "text": "This example creates a 4-byte file. int write_id ( void )\n{\n int rc ;\n\n /* Create the parent directory. */ \n rc = fs_mkdir ( /cfg );\n if ( rc != 0 rc != FS_EALREADY ) {\n return - 1 ;\n }\n\n /* Create a file and write four bytes to it. */ \n rc = fsutil_write_file ( /cfg/id.txt , 1234 , 4 );\n if ( rc != 0 ) {\n return - 1 ;\n }\n\n return 0 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/fatfs/",
- "text": "The FAT File System\n\n\nMynewt provides an implementation of the FAT filesystem which is currently\nsupported on MMC/SD cards.\n\n\nDescription\n\n\n\n\nFile Allocation Table (FAT) is a computer file system architecture and a family\nof industry-standard file systems utilizing it. The FAT file system is a legacy\nfile system which is simple and robust. It offers good performance even in\nlightweight implementations, but cannot deliver the same performance, reliability\nand scalability as some modern file systems.\n\n\n\n\nConfiguration\n\n\nfatfs\n configuration can be tweaked by editing \nfs/fatfs/include/fatfs/ffconf.h\n.\nThe current configuraton was chosen to minimize memory use and some options address\nlimitations existing in the OS:\n\n\n\n\nWrite support is enabled by default (can be disabled to minimize memory use).\n\n\nLong filename (up to 255) support is disabled.\n\n\nWhen writing files, time/dates are not persisted due to current lack of a\n standard \nhal_rtc\n interface.\n\n\nNo unicode support. Vanilla config uses standard US codepage 437.\n\n\nFormatting of new volumes is disabled.\n\n\nDefault number of volumes is configured to 1.\n\n\n\n\nAPI\n\n\nTo include \nfatfs\n on a project just include it as a dependency in your\nproject:\n\n\npkg.deps:\n - fs/fatfs\n\n\n\n\n\nIt can now be used through the standard file system abstraction functions as\ndescribed in \nFS API\n.\n\n\nExample\n\n\nAn example of using \nfatfs\n on a MMC card is provided on the\n\nMMC\n documentation.",
- "title": "FAT File System"
- },
- {
- "location": "/os/modules/fs/fatfs/#the-fat-file-system",
- "text": "Mynewt provides an implementation of the FAT filesystem which is currently\nsupported on MMC/SD cards.",
- "title": "The FAT File System"
- },
- {
- "location": "/os/modules/fs/fatfs/#description",
- "text": "File Allocation Table (FAT) is a computer file system architecture and a family\nof industry-standard file systems utilizing it. The FAT file system is a legacy\nfile system which is simple and robust. It offers good performance even in\nlightweight implementations, but cannot deliver the same performance, reliability\nand scalability as some modern file systems.",
- "title": "Description"
- },
- {
- "location": "/os/modules/fs/fatfs/#configuration",
- "text": "fatfs configuration can be tweaked by editing fs/fatfs/include/fatfs/ffconf.h .\nThe current configuraton was chosen to minimize memory use and some options address\nlimitations existing in the OS: Write support is enabled by default (can be disabled to minimize memory use). Long filename (up to 255) support is disabled. When writing files, time/dates are not persisted due to current lack of a\n standard hal_rtc interface. No unicode support. Vanilla config uses standard US codepage 437. Formatting of new volumes is disabled. Default number of volumes is configured to 1.",
- "title": "Configuration"
- },
- {
- "location": "/os/modules/fs/fatfs/#api",
- "text": "To include fatfs on a project just include it as a dependency in your\nproject: pkg.deps:\n - fs/fatfs It can now be used through the standard file system abstraction functions as\ndescribed in FS API .",
- "title": "API"
- },
- {
- "location": "/os/modules/fs/fatfs/#example",
- "text": "An example of using fatfs on a MMC card is provided on the MMC documentation.",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/",
- "text": "Newtron Flash Filesystem (nffs)\n\n\nMynewt includes the Newtron Flash File System (nffs). This file system is designed with two priorities that makes it suitable for embedded use: \n\n\n\n\nMinimal RAM usage\n\n\nReliability\n\n\n\n\nMynewt also provides an abstraction layer API (fs) to allow you to swap out nffs with a different file system of your choice.\n\n\nDescription\n\n\nAreas\n\n\nAt the top level, an nffs disk is partitioned into \nareas\n. An area is a region of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nWriting to one area does not restrict writes to other areas.\n\n\n\n\nRegarding property 1:\n Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible.\n\n\nRegarding property 2:\n Furthermore, some flash hardware imposes a restriction with regards to writes: writes within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.\n\n\nThus, each area must comprise a discrete number of blocks.\n\n\nInitialization\n\n\nAs part of overall system initialization, mynewt re-initialized the filesystem as follows:\n\n\n\n\nRestores an existing file system via detection.\n\n\nCreates a new file system via formatting.\n\n\n\n\nA typical initialization sequence is the following:\n\n\n\n\nDetect an nffs file system in a specific region of flash.\n\n\nIf no file system was detected, if configured to do so, format a new file system in the same flash region.\n\n\n\n\nNote that in the latter case, the behavior is controlled with a variable in the syscfg.yml file. If NFFS_DETECT_FAIL is set to 1, the system ignores NFFS filesystem detection issues, but unless a new filesystem is formatted manually, all filesystem access will fail. If NFFS_DETECT_FAIL is set to 2, the system will format a new filesystem - note however this effectively deletes all existing data in the NFFS flash areas.\n\n\nBoth methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of \nstruct nffs_area_desc\n configured as part of the BSP configureation.\n\n\nAfter nffs has been initialized, the application can access the file system via the \nfile system abstraction layer\n.\n\n\nData Structures\n\n\nThe \nfs/nffs\n package exposes the following data structures:\n\n\n\n\n\n\n\n\nStruct\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nstruct nffs_area_desc\n\n\nDescriptor for a single nffs area.\n\n\n\n\n\n\nstruct nffs_config\n\n\nConfiguration struct for nffs.\n\n\n\n\n\n\n\n\nAPI\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnffs_detect\n\n\nSearches for a valid nffs file system among the specified areas.\n\n\n\n\n\n\nnffs_format\n\n\nErases all the specified areas and initializes them with a clean nffs file system.\n\n\n\n\n\n\nnffs_init\n\n\nInitializes internal nffs memory and data structures.\n\n\n\n\n\n\n\n\nMiscellaneous measures\n\n\n\n\n\n\nRAM usage:\n\n\n\n\n24 bytes per inode\n\n\n12 bytes per data block\n\n\n36 bytes per inode cache entry\n\n\n32 bytes per data block cache entry\n\n\n\n\n\n\n\n\nMaximum filename size: 256 characters (no null terminator required)\n\n\n\n\nDisallowed filename characters: '/' and '\\0'\n\n\n\n\nInternals\n\n\nnffs implementation details can be found here:\n\n\n\n\nnffs_internals\n\n\n\n\nFuture enhancements\n\n\n\n\nError correction.\n\n\nEncryption.\n\n\nCompression.",
- "title": "toc"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#newtron-flash-filesystem-nffs",
- "text": "Mynewt includes the Newtron Flash File System (nffs). This file system is designed with two priorities that makes it suitable for embedded use: Minimal RAM usage Reliability Mynewt also provides an abstraction layer API (fs) to allow you to swap out nffs with a different file system of your choice.",
- "title": "Newtron Flash Filesystem (nffs)"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#description",
- "text": "",
- "title": "Description"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#areas",
- "text": "At the top level, an nffs disk is partitioned into areas . An area is a region of disk with the following properties: An area can be fully erased without affecting any other areas. Writing to one area does not restrict writes to other areas. Regarding property 1: Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible. Regarding property 2: Furthermore, some flash hardware imposes a restriction with regards to writes: writes within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written. Thus, each area must comprise a discrete number of blocks.",
- "title": "Areas"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#initialization",
- "text": "As part of overall system initialization, mynewt re-initialized the filesystem as follows: Restores an existing file system via detection. Creates a new file system via formatting. A typical initialization sequence is the following: Detect an nffs file system in a specific region of flash. If no file system was detected, if configured to do so, format a new file system in the same flash region. Note that in the latter case, the behavior is controlled with a variable in the syscfg.yml file. If NFFS_DETECT_FAIL is set to 1, the system ignores NFFS filesystem detection issues, but unless a new filesystem is formatted manually, all filesystem access will fail. If NFFS_DETECT_FAIL is set to 2, the system will format a new filesystem - note however this effectively deletes all existing data in the NFFS flash areas. Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of struct nffs_area_desc configured as part of the BSP configureation. After nffs has been initialized, the application can access the file system via the file system abstraction layer .",
- "title": "Initialization"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#data-structures",
- "text": "The fs/nffs package exposes the following data structures: Struct Description struct nffs_area_desc Descriptor for a single nffs area. struct nffs_config Configuration struct for nffs.",
- "title": "Data Structures"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#api",
- "text": "The functions available in this OS feature are: Function Description nffs_detect Searches for a valid nffs file system among the specified areas. nffs_format Erases all the specified areas and initializes them with a clean nffs file system. nffs_init Initializes internal nffs memory and data structures.",
- "title": "API"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#miscellaneous-measures",
- "text": "RAM usage: 24 bytes per inode 12 bytes per data block 36 bytes per inode cache entry 32 bytes per data block cache entry Maximum filename size: 256 characters (no null terminator required) Disallowed filename characters: '/' and '\\0'",
- "title": "Miscellaneous measures"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#internals",
- "text": "nffs implementation details can be found here: nffs_internals",
- "title": "Internals"
- },
- {
- "location": "/os/modules/fs/nffs/nffs/#future-enhancements",
- "text": "Error correction. Encryption. Compression.",
- "title": "Future enhancements"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_area_desc/",
- "text": "struct nffs_area_desc\n\n\nstruct\n \nnffs_area_desc\n {\n \nuint32_t\n \nnad_offset\n; \n/* Flash offset of start of area. */\n\n \nuint32_t\n \nnad_length\n; \n/* Size of area, in bytes. */\n\n \nuint8_t\n \nnad_flash_id\n; \n/* Logical flash id */\n\n};\n\n\n\n\n\nDescriptor for a single nffs area. An area is a region of disk with the following properties:\n\n\n\n\nAn area can be fully erased without affecting any other areas.\n\n\nWriting to one area does not restrict writes to other areas.\n\n\n\n\nRegarding property 1:\n Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible.\n\n\nRegarding property 2:\n Furthermore, some flash hardware imposes a restriction with regards to writes: writes within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written.\n\n\nThus, each area must comprise a discrete number of blocks.\n\n\nAn array of area descriptors is terminated by an entry with a \nnad_length\n value of 0.\n\n\nNotes\n\n\nTypically, a product's flash layout is exposed via its BSP-specific \nbsp_flash_dev()\n function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the \nstruct nffs_area_desc[]\n that nffs requires.\n\n\nHeader file\n\n\n#include\n \nnffs/nffs.h",
- "title": "struct nffs_area_desc"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_area_desc/#struct-nffs95area95desc",
- "text": "struct nffs_area_desc {\n uint32_t nad_offset ; /* Flash offset of start of area. */ \n uint32_t nad_length ; /* Size of area, in bytes. */ \n uint8_t nad_flash_id ; /* Logical flash id */ \n}; Descriptor for a single nffs area. An area is a region of disk with the following properties: An area can be fully erased without affecting any other areas. Writing to one area does not restrict writes to other areas. Regarding property 1: Generally, flash hardware divides its memory space into \"blocks.\" When erasing flash, entire blocks must be erased in a single operation; partial erases are not possible. Regarding property 2: Furthermore, some flash hardware imposes a restriction with regards to writes: writes within a block must be strictly sequential. For example, if you wish to write to the first 16 bytes of a block, you must write bytes 1 through 15 before writing byte 16. This restriction only applies at the block level; writes to one block have no effect on what parts of other blocks can be written. Thus, each area must comprise a discrete number of blocks. An array of area descriptors is terminated by an entry with a nad_length value of 0.",
- "title": "struct nffs_area_desc"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_area_desc/#notes",
- "text": "Typically, a product's flash layout is exposed via its BSP-specific bsp_flash_dev() function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the struct nffs_area_desc[] that nffs requires.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_area_desc/#header-file",
- "text": "#include nffs/nffs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_config/",
- "text": "struct nffs_config\n\n\nstruct\n \nnffs_config\n {\n \n/** Maximum number of inodes; default=1024. */\n\n \nuint32_t\n \nnc_num_inodes\n;\n\n \n/** Maximum number of data blocks; default=4096. */\n\n \nuint32_t\n \nnc_num_blocks\n;\n\n \n/** Maximum number of open files; default=4. */\n\n \nuint32_t\n \nnc_num_files\n;\n\n \n/** Inode cache size; default=4. */\n\n \nuint32_t\n \nnc_num_cache_inodes\n;\n\n \n/** Data block cache size; default=64. */\n\n \nuint32_t\n \nnc_num_cache_blocks\n;\n};\n\n\n\n\n\nThe file system is configured by populating fields in a global \nstruct nffs_config\n instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs_init().\n\n\nAny fields that are set to 0 (or not set at all) inherit the corresponding default value. This means that it is impossible to configure any setting with a value of zero.\n\n\nNotes\n\n\nThe global \nstruct nffs_config\n instance is exposed in \nnffs/nffs.h\n as follows:\n\n\nextern\n \nstruct\n \nnffs_config\n \nnffs_config\n;\n\n\n\n\n\nHeader file\n\n\n#include\n \nnffs/nffs.h",
- "title": "struct nffs_config"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_config/#struct-nffs95config",
- "text": "struct nffs_config {\n /** Maximum number of inodes; default=1024. */ \n uint32_t nc_num_inodes ;\n\n /** Maximum number of data blocks; default=4096. */ \n uint32_t nc_num_blocks ;\n\n /** Maximum number of open files; default=4. */ \n uint32_t nc_num_files ;\n\n /** Inode cache size; default=4. */ \n uint32_t nc_num_cache_inodes ;\n\n /** Data block cache size; default=64. */ \n uint32_t nc_num_cache_blocks ;\n}; The file system is configured by populating fields in a global struct nffs_config instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs_init(). Any fields that are set to 0 (or not set at all) inherit the corresponding default value. This means that it is impossible to configure any setting with a value of zero.",
- "title": "struct nffs_config"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_config/#notes",
- "text": "The global struct nffs_config instance is exposed in nffs/nffs.h as follows: extern struct nffs_config nffs_config ;",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_config/#header-file",
- "text": "#include nffs/nffs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_detect/",
- "text": "nffs_detect\n\n\nint\n \nnffs_detect\n(\nconst\n \nstruct\n \nnffs_area_desc\n \n*area_descs\n)\n\n\n\n\n\nSearches for a valid nffs file system among the specified areas. This function succeeds if a file system is detected among any subset of the supplied areas. If the area set does not contain a valid file system, a new one can be created via a separate call to nffs_format().\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\narea_descs\n\n\nThe set of areas to search. This array must be terminated with a 0-length area.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ECORRUPT if no valid file system was detected\n\n\nOther \nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nnffs/nffs.h\n\n\n\n\n\n\nExample\n\n\n/*** hw/hal/include/hal/flash_map.h */\n\n\n\n/*\n\n\n * Flash area types\n\n\n */\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n#define FLASH_AREA_NFFS 4\n\n\n\n\n\n\n/*** project/slinky/src/main.c */\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n\n \n/* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */\n\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\nNFFS_AREA_MAX\n];\n\n \n/* Initialize nffs\ns internal state. */\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Convert the set of flash blocks we intend to use for nffs into an array\n\n\n * of nffs area descriptors.\n\n\n */\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Attempt to restore an existing nffs file system from flash. */\n\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\n) {\n \n/* No valid nffs instance detected; format a new one. */\n\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n/* [ ... ] */\n\n}",
- "title": "nffs_detect"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_detect/#nffs95detect",
- "text": "int nffs_detect ( const struct nffs_area_desc *area_descs ) Searches for a valid nffs file system among the specified areas. This function succeeds if a file system is detected among any subset of the supplied areas. If the area set does not contain a valid file system, a new one can be created via a separate call to nffs_format().",
- "title": "nffs_detect"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_detect/#arguments",
- "text": "Argument Description area_descs The set of areas to search. This array must be terminated with a 0-length area.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_detect/#returned-values",
- "text": "0 on success FS_ECORRUPT if no valid file system was detected Other FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_detect/#header-file",
- "text": "#include nffs/nffs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_detect/#example",
- "text": "/*** hw/hal/include/hal/flash_map.h */ /* * Flash area types */ #define FLASH_AREA_BOOTLOADER 0 #define FLASH_AREA_IMAGE_0 1 #define FLASH_AREA_IMAGE_1 2 #define FLASH_AREA_IMAGE_SCRATCH 3 #define FLASH_AREA_NFFS 4 /*** project/slinky/src/main.c */ int main ( int argc , char **argv )\n{\n int rc ;\n int cnt ;\n\n /* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */ \n struct nffs_area_desc descs [ NFFS_AREA_MAX ];\n\n /* Initialize nffs s internal state. */ \n rc = nffs_init ();\n assert ( rc == 0 );\n\n /* Convert the set of flash blocks we intend to use for nffs into an array * of nffs area descriptors. */ \n cnt = NFFS_AREA_MAX ;\n rc = flash_area_to_nffs_desc ( FLASH_AREA_NFFS , cnt , descs );\n assert ( rc == 0 );\n\n /* Attempt to restore an existing nffs file system from flash. */ \n if ( nffs_detect ( descs ) == FS_ECORRUPT ) {\n /* No valid nffs instance detected; format a new one. */ \n rc = nffs_format ( descs );\n assert ( rc == 0 );\n }\n /* [ ... ] */ \n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_format/",
- "text": "nffs_format\n\n\nint\n \nnffs_format\n(\nconst\n \nstruct\n \nnffs_area_desc\n \n*area_descs\n)\n\n\n\n\n\nErases all the specified areas and initializes them with a clean nffs file system.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\narea_descs\n\n\nThe set of areas to format\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure.\n\n\n\n\nHeader file\n\n\n#include\n \nnffs/nffs.h\n\n\n\n\n\n\nExample\n\n\n/*** hw/hal/include/hal/flash_map.h */\n\n\n\n/*\n\n\n * Flash area types\n\n\n */\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n#define FLASH_AREA_NFFS 4\n\n\n\n\n\n\n/*** project/slinky/src/main.c */\n\n\n\nint\n\n\nmain\n(\nint\n \nargc\n, \nchar\n \n**argv\n)\n{\n \nint\n \nrc\n;\n \nint\n \ncnt\n;\n\n \n/* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */\n\n \nstruct\n \nnffs_area_desc\n \ndescs\n[\nNFFS_AREA_MAX\n];\n\n \n/* Initialize nffs\ns internal state. */\n\n \nrc\n \n=\n \nnffs_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Convert the set of flash blocks we intend to use for nffs into an array\n\n\n * of nffs area descriptors.\n\n\n */\n\n \ncnt\n \n=\n \nNFFS_AREA_MAX\n;\n \nrc\n \n=\n \nflash_area_to_nffs_desc\n(\nFLASH_AREA_NFFS\n, \ncnt\n, \ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Attempt to restore an existing nffs file system from flash. */\n\n \nif\n (\nnffs_detect\n(\ndescs\n) \n==\n \nFS_ECORRUPT\n) {\n \n/* No valid nffs instance detected; format a new one. */\n\n \nrc\n \n=\n \nnffs_format\n(\ndescs\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n }\n \n/* [ ... ] */\n\n}",
- "title": "nffs_format"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_format/#nffs95format",
- "text": "int nffs_format ( const struct nffs_area_desc *area_descs ) Erases all the specified areas and initializes them with a clean nffs file system.",
- "title": "nffs_format"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_format/#arguments",
- "text": "Argument Description area_descs The set of areas to format",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_format/#returned-values",
- "text": "0 on success FS error code on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_format/#header-file",
- "text": "#include nffs/nffs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_format/#example",
- "text": "/*** hw/hal/include/hal/flash_map.h */ /* * Flash area types */ #define FLASH_AREA_BOOTLOADER 0 #define FLASH_AREA_IMAGE_0 1 #define FLASH_AREA_IMAGE_1 2 #define FLASH_AREA_IMAGE_SCRATCH 3 #define FLASH_AREA_NFFS 4 /*** project/slinky/src/main.c */ int main ( int argc , char **argv )\n{\n int rc ;\n int cnt ;\n\n /* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */ \n struct nffs_area_desc descs [ NFFS_AREA_MAX ];\n\n /* Initialize nffs s internal state. */ \n rc = nffs_init ();\n assert ( rc == 0 );\n\n /* Convert the set of flash blocks we intend to use for nffs into an array * of nffs area descriptors. */ \n cnt = NFFS_AREA_MAX ;\n rc = flash_area_to_nffs_desc ( FLASH_AREA_NFFS , cnt , descs );\n assert ( rc == 0 );\n\n /* Attempt to restore an existing nffs file system from flash. */ \n if ( nffs_detect ( descs ) == FS_ECORRUPT ) {\n /* No valid nffs instance detected; format a new one. */ \n rc = nffs_format ( descs );\n assert ( rc == 0 );\n }\n /* [ ... ] */ \n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_init/",
- "text": "nffs_init\n\n\nint\n \nnffs_init\n(\nvoid\n)\n\n\n\n\n\nInitializes internal nffs memory and data structures. This must be called before any nffs operations are attempted.\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS error code\n on failure\n\n\n\n\nHeader file\n\n\n#include\n \nnffs/nffs.h",
- "title": "nffs_init"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_init/#nffs95init",
- "text": "int nffs_init ( void ) Initializes internal nffs memory and data structures. This must be called before any nffs operations are attempted.",
- "title": "nffs_init"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_init/#returned-values",
- "text": "0 on success FS error code on failure",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_init/#header-file",
- "text": "#include nffs/nffs.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/",
- "text": "Internals of nffs\n\n\nDisk structure\n\n\nOn disk, each area is prefixed with the following header:\n\n\n/** On-disk representation of an area header. */\n\n\nstruct\n \nnffs_disk_area\n {\n \nuint32_t\n \nnda_magic\n[\n4\n]; \n/* NFFS_AREA_MAGIC{0,1,2,3} */\n\n \nuint32_t\n \nnda_length\n; \n/* Total size of area, in bytes. */\n\n \nuint8_t\n \nnda_ver\n; \n/* Current nffs version: 0 */\n\n \nuint8_t\n \nnda_gc_seq\n; \n/* Garbage collection count. */\n\n \nuint8_t\n \nreserved8\n;\n \nuint8_t\n \nnda_id\n; \n/* 0xff if scratch area. */\n\n};\n\n\n\n\n\nBeyond its header, an area contains a sequence of disk objects, representing the contents of the file system. There are two types of objects: \ninodes\n and \ndata blocks\n. An inode represents a file or directory; a data block represents part of a file's contents.\n\n\n/** On-disk representation of an inode (file or directory). */\n\n\nstruct\n \nnffs_disk_inode\n {\n \nuint32_t\n \nndi_magic\n; \n/* NFFS_INODE_MAGIC */\n\n \nuint32_t\n \nndi_id\n; \n/* Unique object ID. */\n\n \nuint32_t\n \nndi_seq\n; \n/* Sequence number; greater supersedes\n\n\n lesser. */\n\n \nuint32_t\n \nndi_parent_id\n; \n/* Object ID of parent directory inode. */\n\n \nuint8_t\n \nreserved8\n;\n \nuint8_t\n \nndi_filename_len\n; \n/* Length of filename, in bytes. */\n\n \nuint16_t\n \nndi_crc16\n; \n/* Covers rest of header and filename. */\n\n \n/* Followed by filename. */\n\n};\n\n\n\n\n\nAn inode filename's length cannot exceed 256 bytes. The filename is not null-terminated. The following ASCII characters are not allowed in a filename:\n\n\n\n\n/ (slash character)\n\n\n\\0 (NUL character)\n\n\n\n\n/** On-disk representation of a data block. */\n\n\nstruct\n \nnffs_disk_block\n {\n \nuint32_t\n \nndb_magic\n; \n/* NFFS_BLOCK_MAGIC */\n\n \nuint32_t\n \nndb_id\n; \n/* Unique object ID. */\n\n \nuint32_t\n \nndb_seq\n; \n/* Sequence number; greater supersedes lesser. */\n\n \nuint32_t\n \nndb_inode_id\n; \n/* Object ID of owning inode. */\n\n \nuint32_t\n \nndb_prev_id\n; \n/* Object ID of previous block in file;\n\n\n NFFS_ID_NONE if this is the first block. */\n\n \nuint16_t\n \nndb_data_len\n; \n/* Length of data contents, in bytes. */\n\n \nuint16_t\n \nndb_crc16\n; \n/* Covers rest of header and data. */\n\n \n/* Followed by \nndb_data_len\n bytes of data. */\n\n};\n\n\n\n\n\nEach data block contains the ID of the previous data block in the file. Together, the set of blocks in a file form a reverse singly-linked list.\n\n\nThe maximum number of data bytes that a block can contain is determined at initialization-time. The result is the greatest number which satisfies all of the following restrictions:\n\n\n\n\nNo more than 2048.\n\n\nAt least two maximum-sized blocks can fit in the smallest area.\n\n\n\n\nThe 2048 number was chosen somewhat arbitrarily, and may change in the future.\n\n\nID space\n\n\nAll disk objects have a unique 32-bit ID. The ID space is partitioned as\nfollows:\n\n\n\n\n\n\n\n\nID range\n\n\nNode type\n\n\n\n\n\n\n\n\n\n\n0x00000000 - 0x0fffffff\n\n\nDirectory inodes\n\n\n\n\n\n\n0x10000000 - 0x7fffffff\n\n\nFile inodes\n\n\n\n\n\n\n0x80000000 - 0xfffffffe\n\n\nData blocks\n\n\n\n\n\n\n0xffffffff\n\n\nReserved (NFFS_ID_NONE)\n\n\n\n\n\n\n\n\nScratch area\n\n\nA valid nffs file system must contain a single \"scratch area.\" The scratch area does not contain any objects of its own, and is only used during garbage collection. The scratch area must have a size greater than or equal to each of the other areas in flash.\n\n\nRAM representation\n\n\nEvery object in the file system is stored in a 256-entry hash table. An object's hash key is derived from its 32-bit ID. Each list in the hash table is sorted by time of use; most-recently-used is at the front of the list. All objects are represented by the following structure:\n\n\n/**\n\n\n * What gets stored in the hash table. Each entry represents a data block or\n\n\n * an inode.\n\n\n */\n\n\nstruct\n \nnffs_hash_entry\n {\n \nSLIST_ENTRY\n(\nnffs_hash_entry\n) \nnhe_next\n;\n \nuint32_t\n \nnhe_id\n; \n/* 0 - 0x7fffffff if inode; else if block. */\n\n \nuint32_t\n \nnhe_flash_loc\n; \n/* Upper-byte = area idx; rest = area offset. */\n\n};\n\n\n\n\n\nFor each data block, the above structure is all that is stored in RAM. To acquire more information about a data block, the block header must be read from flash.\n\n\nInodes require a fuller RAM representation to capture the structure of the file system. There are two types of inodes: \nfiles\n and \ndirectories\n. Each inode hash entry is actually an instance of the following structure:\n\n\n/** Each inode hash entry is actually one of these. */\n\n\nstruct\n \nnffs_inode_entry\n {\n \nstruct\n \nnffs_hash_entry\n \nnie_hash_entry\n;\n \nSLIST_ENTRY\n(\nnffs_inode_entry\n) \nnie_sibling_next\n;\n \nunion\n {\n \nstruct\n \nnffs_inode_list\n \nnie_child_list\n; \n/* If directory */\n\n \nstruct\n \nnffs_hash_entry\n \n*nie_last_block_entry\n; \n/* If file */\n\n };\n \nuint8_t\n \nnie_refcnt\n;\n};\n\n\n\n\n\nA directory inode contains a list of its child files and directories (\nfie_child_list\n). These entries are sorted alphabetically using the ASCII character set.\n\n\nA file inode contains a pointer to the last data block in the file (\nnie_last_block_entry\n). For most file operations, the reversed block list must be walked backwards. This introduces a number of speed inefficiencies:\n\n\n\n\nAll data blocks must be read to determine the length of the file.\n\n\nData blocks often need to be processed sequentially. The reversed nature of the block list transforms this from linear time to an O(n^2) operation.\n\n\n\n\nFurthermore, obtaining information about any constituent data block requires a separate flash read.\n\n\nInode cache and Data Block cache\n\n\nThe speed issues are addressed by a pair of caches. Cached inodes entries contain the file length and a much more convenient doubly-linked list of cached data blocks. The benefit of using caches is that the size of the caches need not be proportional to the size of the file system. In other words, caches can address speed efficiency concerns without negatively impacting the file system's scalability.\n\n\nnffs requires both caches during normal operation, so it is not possible to disable them. However, the cache sizes are configurable, and both caches can be configured with a size of one if RAM usage must be minimized.\n\n\nThe following data structures are used in the inode and data block caches.\n\n\n/** Full data block representation; not stored permanently in RAM. */\n\n\nstruct\n \nnffs_block\n {\n \nstruct\n \nnffs_hash_entry\n \n*nb_hash_entry\n; \n/* Points to real block entry. */\n\n \nuint32_t\n \nnb_seq\n; \n/* Sequence number; greater\n\n\n supersedes lesser. */\n\n \nstruct\n \nnffs_inode_entry\n \n*nb_inode_entry\n; \n/* Owning inode. */\n\n \nstruct\n \nnffs_hash_entry\n \n*nb_prev\n; \n/* Previous block in file. */\n\n \nuint16_t\n \nnb_data_len\n; \n/* # of data bytes in block. */\n\n \nuint16_t\n \nreserved16\n;\n};\n\n\n\n\n\n/** Represents a single cached data block. */\n\n\nstruct\n \nnffs_cache_block\n {\n \nTAILQ_ENTRY\n(\nnffs_cache_block\n) \nncb_link\n; \n/* Next / prev cached block. */\n\n \nstruct\n \nnffs_block\n \nncb_block\n; \n/* Full data block. */\n\n \nuint32_t\n \nncb_file_offset\n; \n/* File offset of this block. */\n\n};\n\n\n\n\n\n/** Full inode representation; not stored permanently in RAM. */\n\n\nstruct\n \nnffs_inode\n {\n \nstruct\n \nnffs_inode_entry\n \n*ni_inode_entry\n; \n/* Points to real inode entry. */\n\n \nuint32_t\n \nni_seq\n; \n/* Sequence number; greater\n\n\n supersedes lesser. */\n\n \nstruct\n \nnffs_inode_entry\n \n*ni_parent\n; \n/* Points to parent directory. */\n\n \nuint8_t\n \nni_filename_len\n; \n/* # chars in filename. */\n\n \nuint8_t\n \nni_filename\n[\nNFFS_SHORT_FILENAME_LEN\n]; \n/* First 3 bytes. */\n\n};\n\n\n\n\n\n/** Doubly-linked tail queue of cached blocks; contained in cached inodes. */\n\n\nTAILQ_HEAD\n(\nnffs_block_cache_list\n, \nnffs_block_cache_entry\n);\n\n\n/** Represents a single cached file inode. */\n\n\nstruct\n \nnffs_cache_inode\n {\n \nTAILQ_ENTRY\n(\nnffs_cache_inode\n) \nnci_link\n; \n/* Sorted; LRU at tail. */\n\n \nstruct\n \nnffs_inode\n \nnci_inode\n; \n/* Full inode. */\n\n \nstruct\n \nnffs_cache_block_list\n \nnci_block_list\n; \n/* List of cached blocks. */\n\n \nuint32_t\n \nnci_file_size\n; \n/* Total file size. */\n\n};\n\n\n\n\n\nOnly file inodes are cached; directory inodes are never cached.\n\n\nWithin a cached inode, all cached data blocks are contiguous. E.g., if the start and end of a file are cached, then the middle must also be cached. A data block is only cached if its owning file is also cached.\n\n\nInternally, cached inodes are stored in a singly-linked list, ordered by time of use. The most-recently-used entry is the first element in the list. If a new inode needs to be cached, but the inode cache is full, the least-recently-used entry is freed to make room for the new one. The following operations cause an inode to be cached:\n\n\n\n\nQuerying a file's length.\n\n\nSeeking within a file.\n\n\nReading from a file.\n\n\nWriting to a file.\n\n\n\n\nThe following operations cause a data block to be cached:\n\n\n\n\nReading from the block.\n\n\nWriting to the block.\n\n\n\n\nIf one of the above operations is applied to a data block that is not currently cached, nffs uses the following procedure to cache the necessary block:\n\n\n\n\nIf none of the owning inode's blocks are currently cached, allocate a cached block entry corresponding to the requested block and insert it into the inode's list.\n\n\nElse if the requested file offset is less than that of the first cached block, bridge the gap between the inode's sequence of cached blocks and the block that now needs to be cached. This is accomplished by caching each block in the gap, finishing with the requested block.\n\n\nElse (the requested offset is beyond the end of the cache),\n\n\nIf the requested offset belongs to the block that immediately follows the end of the cache, cache the block and append it to the list.\n\n\nElse, clear the cache, and populate it with the single entry corresponding to the requested block.\n\n\n\n\n\n\n\n\nIf the system is unable to allocate a cached block entry at any point during the above procedure, the system frees up other blocks currently in the cache. This is accomplished as follows:\n\n\n\n\nIterate the inode cache in reverse (i.e., start with the least-recently-used entry). For each entry:\n\n\nIf the entry's cached block list is empty, advance to the next entry.\n\n\nElse, free all the cached blocks in the entry's list.\n\n\n\n\n\n\n\n\nBecause the system imposes a minimum block cache size of one, the above procedure will always reclaim at least one cache block entry. The above procedure may result in the freeing of the block list that belongs to the very inode being operated on. This is OK, as the final block to get cached is always the block being requested.\n\n\nDetection\n\n\nThe file system detection process consists of scanning a specified set of flash regions for valid nffs areas, and then populating the RAM representation of the file system with the detected objects. Detection is initiated with the \nnffs_detect()\n function.\n\n\nNot every area descriptor passed to \nnffs_detect()\n needs to reference a valid nffs area. Detection is successful as long as a complete file system is detected somewhere in the specified regions of flash. If an application is unsure where a file system might be located, it can initiate detection across the entire flash region.\n\n\nA detected file system is valid if:\n\n\n\n\nAt least one non-scratch area is present.\n\n\nAt least one scratch area is present (only the first gets used if there is more than one).\n\n\nThe root directory inode is present.\n\n\n\n\nDuring detection, each indicated region of flash is checked for a valid area header. The contents of each valid non-scratch area are then restored into the nffs RAM representation. The following procedure is applied to each object in the area:\n\n\n\n\nVerify the object's integrity via a crc16 check. If invalid, the object is discarded and the procedure restarts on the next object in the area.\n\n\nConvert the disk object into its corresponding RAM representation and insert it into the hash table. If the object is an inode, its reference count is initialized to 1, indicating ownership by its parent directory.\n\n\nIf an object with the same ID is already present, then one supersedes the other. Accept the object with the greater sequence number and discard the other.\n\n\nIf the object references a nonexistent inode (parent directory in the case of an inode; owning file in the case of a data block), insert a temporary \"dummy\" inode into the hash table so that inter-object links can be maintained until the absent inode is eventually restored. Dummy inodes are identified by a reference count of 0.\n\n\nIf a delete record for an inode is encountered, the inode's parent pointer is set to null to indicate that it should be removed from RAM.\n\n\n\n\nIf nffs encounters an object that cannot be identified (i.e., its magic number is not valid), it scans the remainder of the flash area for the next valid magic number. Upon encountering a valid object, nffs resumes the procedure described above.\n\n\nAfter all areas have been restored, a sweep is performed across the entire RAM representation so that invalid inodes can be deleted from memory.\n\n\nFor each directory inode:\n\n\n\n\nIf its reference count is 0 (i.e., it is a dummy), migrate its children to the \n/lost+found\n directory, and delete it from the RAM representation. This should only happen in the case of file system corruption.\n\n\nIf its parent reference is null (i.e., it was deleted), delete it and all its children from the RAM representation.\n\n\n\n\nFor each file inode:\n\n\n\n\nIf its reference count is 0 (i.e., it is a dummy), delete it from the RAM representation. This should only happen in the case of file system corruption. (We should try to migrate the file to the lost+found directory in this case, as mentioned in the todo section).\n\n\n\n\nWhen an object is deleted during this sweep, it is only deleted from the RAM representation; nothing is written to disk.\n\n\nWhen objects are migrated to the lost+found directory, their parent inode reference is permanently updated on the disk.\n\n\nIn addition, a single scratch area is identified during the detection process. The first area whose \nfda_id\n value is set to 0xff is designated as the file system scratch area. If no valid scratch area is found, the cause could be that the system was restarted while a garbage collection cycle was in progress. Such a condition is identified by the presence of two areas with the same ID. In such a case, the shorter of the two areas is erased and designated as the scratch area.\n\n\nFormatting\n\n\nA new nffs file system is created via formatting. Formatting is achieved via the \nnffs_format()\n function.\n\n\nDuring a successful format, an area header is written to each of the specified locations. One of the areas in the set is designated as the initial scratch area.\n\n\nFlash writes\n\n\nThe nffs implementation always writes in a strictly sequential fashion within an area. For each area, the system keeps track of the current offset. Whenever an object gets written to an area, it gets written to that area's current offset, and the offset is increased by the object's disk size.\n\n\nWhen a write needs to be performed, the nffs implementation selects the appropriate destination area by iterating though each area until one with sufficient free space is encountered.\n\n\nThere is no write buffering. Each call to a write function results in a write operation being sent to the flash hardware.\n\n\nNew objects\n\n\nWhenever a new object is written to disk, it is assigned the following properties:\n\n\n\n\nID:\n A unique value is selected from the 32-bit ID space, as appropriate for the object's type.\n\n\nSequence number:\n 0\n\n\n\n\nWhen a new file or directory is created, a corresponding inode is written to flash. Likewise, a new data block also results in the writing of a corresponding disk object.\n\n\nMoving/Renaming files and directories\n\n\nWhen a file or directory is moved or renamed, its corresponding inode is rewritten to flash with the following properties:\n\n\n\n\nID:\n Unchanged\n\n\nSequence number:\n Previous value plus one.\n\n\nParent inode:\n As specified by the move / rename operation.\n\n\nFilename:\n As specified by the move / rename operation.\n\n\n\n\nBecause the inode's ID is unchanged, all dependent objects remain valid.\n\n\nUnlinking files and directories\n\n\nWhen a file or directory is unlinked from its parent directory, a deletion record for the unlinked inode gets written to flash. The deletion record is an inode with the following properties:\n\n\n\n\nID:\n Unchanged\n\n\nSequence number:\n Previous value plus one.\n\n\nParent inode ID:\n NFFS_ID_NONE\n\n\n\n\nWhen an inode is unlinked, no deletion records need to be written for the inode's dependent objects (constituent data blocks or child inodes). During the next file system detection, it is recognized that the objects belong to a deleted inode, so they are not restored into the RAM representation.\n\n\nIf a file has an open handle at the time it gets unlinked, application code can continued to use the file handle to read and write data. All files retain a reference count, and a file isn't deleted from the RAM representation until its reference code drops to 0. Any attempt to open an unlinked file fails, even if the file is referenced by other file handles.\n\n\nWriting to a file\n\n\nThe following procedure is used whenever the application code writes to a file. First, if the write operation specifies too much data to fit into a single block, the operation is split into several separate write operations. Then, for each write operation:\n\n\n\n\nDetermine which existing blocks the write operation overlaps (n = number of overwritten blocks).\n\n\nIf \nn = 0\n, this is an append operation. Write a data block with the following properties:\n\n\nID:\n New unique value.\n\n\nSequence number:\n 0.\n\n\n\n\n\n\nElse \n(n \n 1)\n, this write overlaps existing data.\n\n\nFor each block in \n[1, 2, ... n-1]\n, write a new block containing the updated contents. Each new block supersedes the block it overwrites. That is, each block has the following properties:\n\n\nID:\n Unchanged\n\n\nSequence number:\n Previous value plus one.\n\n\n\n\n\n\nWrite the nth block. The nth block includes all appended data, if any. As with the other blocks, its ID is unchanged and its sequence number is incremented.\n\n\n\n\n\n\n\n\nAppended data can only be written to the end of the file. That is, \"holes\" are not supported.\n\n\nGarbage collection\n\n\nWhen the file system is too full to accommodate a write operation, the system must perform garbage collection to make room. The garbage collection procedure is described below:\n\n\n\n\nThe non-scratch area with the lowest garbage collection sequence number is selected as the \"source area.\" If there are other areas with the same sequence number, the one with the smallest flash offset is selected. \n\n\nThe source area's ID is written to the scratch area's header, transforming it into a non-scratch ID. This former scratch area is now known as the \"destination area.\"\n\n\nThe RAM representation is exhaustively searched for collectible objects. The following procedure is applied to each inode in the system:\n\n\nIf the inode is resident in the source area, copy the inode record to the destination area.\n\n\nIf the inode is a file inode, walk the inode's list of data blocks, starting with the last block in the file. Each block that is resident in the source area is copied to the destination area. If there is a run of two or more blocks that are resident in the source area, they are consolidated and copied to the destination area as a single new block (subject to the maximum block size restriction).\n\n\n\n\n\n\nThe source area is reformatted as a scratch sector (i.e., is is fully erased, and its header is rewritten with an ID of 0xff). The area's garbage collection sequence number is incremented prior to rewriting the header. This area is now the new scratch sector.",
- "title": "Internals"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#internals-of-nffs",
- "text": "",
- "title": "Internals of nffs"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#disk-structure",
- "text": "On disk, each area is prefixed with the following header: /** On-disk representation of an area header. */ struct nffs_disk_area {\n uint32_t nda_magic [ 4 ]; /* NFFS_AREA_MAGIC{0,1,2,3} */ \n uint32_t nda_length ; /* Total size of area, in bytes. */ \n uint8_t nda_ver ; /* Current nffs version: 0 */ \n uint8_t nda_gc_seq ; /* Garbage collection count. */ \n uint8_t reserved8 ;\n uint8_t nda_id ; /* 0xff if scratch area. */ \n}; Beyond its header, an area contains a sequence of disk objects, representing the contents of the file system. There are two types of objects: inodes and data blocks . An inode represents a file or directory; a data block represents part of a file's contents. /** On-disk representation of an inode (file or directory). */ struct nffs_disk_inode {\n uint32_t ndi_magic ; /* NFFS_INODE_MAGIC */ \n uint32_t ndi_id ; /* Unique object ID. */ \n uint32_t ndi_seq ; /* Sequence number; greater supersedes lesser. */ \n uint32_t ndi_parent_id ; /* Object ID of parent directory inode. */ \n uint8_t reserved8 ;\n uint8_t ndi_filename_len ; /* Length of filename, in bytes. */ \n uint16_t ndi_crc16 ; /* Covers rest of header and filename. */ \n /* Followed by filename. */ \n}; An inode filename's length cannot exceed 256 bytes. The filename is not null-terminated. The following ASCII characters are not allowed in a filename: / (slash character) \\0 (NUL character) /** On-disk representation of a data block. */ struct nffs_disk_block {\n uint32_t ndb_magic ; /* NFFS_BLOCK_MAGIC */ \n uint32_t ndb_id ; /* Unique object ID. */ \n uint32_t ndb_seq ; /* Sequence number; greater supersedes lesser. */ \n uint32_t ndb_inode_id ; /* Object ID of owning inode. */ \n uint32_t ndb_prev_id ; /* Object ID of previous block in file; NFFS_ID_NONE if this is the first block. */ \n uint16_t ndb_data_len ; /* Length of data contents, in bytes. */ \n uint16_t ndb_crc16 ; /* Covers rest of header and data. */ \n /* Followed by ndb_data_len bytes of data. */ \n}; Each data block contains the ID of the previous data block in the file. Together, the set of blocks in a file form a reverse singly-linked list. The maximum number of data bytes that a block can contain is determined at initialization-time. The result is the greatest number which satisfies all of the following restrictions: No more than 2048. At least two maximum-sized blocks can fit in the smallest area. The 2048 number was chosen somewhat arbitrarily, and may change in the future.",
- "title": "Disk structure"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#id-space",
- "text": "All disk objects have a unique 32-bit ID. The ID space is partitioned as\nfollows: ID range Node type 0x00000000 - 0x0fffffff Directory inodes 0x10000000 - 0x7fffffff File inodes 0x80000000 - 0xfffffffe Data blocks 0xffffffff Reserved (NFFS_ID_NONE)",
- "title": "ID space"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#scratch-area",
- "text": "A valid nffs file system must contain a single \"scratch area.\" The scratch area does not contain any objects of its own, and is only used during garbage collection. The scratch area must have a size greater than or equal to each of the other areas in flash.",
- "title": "Scratch area"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#ram-representation",
- "text": "Every object in the file system is stored in a 256-entry hash table. An object's hash key is derived from its 32-bit ID. Each list in the hash table is sorted by time of use; most-recently-used is at the front of the list. All objects are represented by the following structure: /** * What gets stored in the hash table. Each entry represents a data block or * an inode. */ struct nffs_hash_entry {\n SLIST_ENTRY ( nffs_hash_entry ) nhe_next ;\n uint32_t nhe_id ; /* 0 - 0x7fffffff if inode; else if block. */ \n uint32_t nhe_flash_loc ; /* Upper-byte = area idx; rest = area offset. */ \n}; For each data block, the above structure is all that is stored in RAM. To acquire more information about a data block, the block header must be read from flash. Inodes require a fuller RAM representation to capture the structure of the file system. There are two types of inodes: files and directories . Each inode hash entry is actually an instance of the following structure: /** Each inode hash entry is actually one of these. */ struct nffs_inode_entry {\n struct nffs_hash_entry nie_hash_entry ;\n SLIST_ENTRY ( nffs_inode_entry ) nie_sibling_next ;\n union {\n struct nffs_inode_list nie_child_list ; /* If directory */ \n struct nffs_hash_entry *nie_last_block_entry ; /* If file */ \n };\n uint8_t nie_refcnt ;\n}; A directory inode contains a list of its child files and directories ( fie_child_list ). These entries are sorted alphabetically using the ASCII character set. A file inode contains a pointer to the last data block in the file ( nie_last_block_entry ). For most file operations, the reversed block list must be walked backwards. This introduces a number of speed inefficiencies: All data blocks must be read to determine the length of the file. Data blocks often need to be processed sequentially. The reversed nature of the block list transforms this from linear time to an O(n^2) operation. Furthermore, obtaining information about any constituent data block requires a separate flash read.",
- "title": "RAM representation"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#inode-cache-and-data-block-cache",
- "text": "The speed issues are addressed by a pair of caches. Cached inodes entries contain the file length and a much more convenient doubly-linked list of cached data blocks. The benefit of using caches is that the size of the caches need not be proportional to the size of the file system. In other words, caches can address speed efficiency concerns without negatively impacting the file system's scalability. nffs requires both caches during normal operation, so it is not possible to disable them. However, the cache sizes are configurable, and both caches can be configured with a size of one if RAM usage must be minimized. The following data structures are used in the inode and data block caches. /** Full data block representation; not stored permanently in RAM. */ struct nffs_block {\n struct nffs_hash_entry *nb_hash_entry ; /* Points to real block entry. */ \n uint32_t nb_seq ; /* Sequence number; greater supersedes lesser. */ \n struct nffs_inode_entry *nb_inode_entry ; /* Owning inode. */ \n struct nffs_hash_entry *nb_prev ; /* Previous block in file. */ \n uint16_t nb_data_len ; /* # of data bytes in block. */ \n uint16_t reserved16 ;\n}; /** Represents a single cached data block. */ struct nffs_cache_block {\n TAILQ_ENTRY ( nffs_cache_block ) ncb_link ; /* Next / prev cached block. */ \n struct nffs_block ncb_block ; /* Full data block. */ \n uint32_t ncb_file_offset ; /* File offset of this block. */ \n}; /** Full inode representation; not stored permanently in RAM. */ struct nffs_inode {\n struct nffs_inode_entry *ni_inode_entry ; /* Points to real inode entry. */ \n uint32_t ni_seq ; /* Sequence number; greater supersedes lesser. */ \n struct nffs_inode_entry *ni_parent ; /* Points to parent directory. */ \n uint8_t ni_filename_len ; /* # chars in filename. */ \n uint8_t ni_filename [ NFFS_SHORT_FILENAME_LEN ]; /* First 3 bytes. */ \n}; /** Doubly-linked tail queue of cached blocks; contained in cached inodes. */ TAILQ_HEAD ( nffs_block_cache_list , nffs_block_cache_entry ); /** Represents a single cached file inode. */ struct nffs_cache_inode {\n TAILQ_ENTRY ( nffs_cache_inode ) nci_link ; /* Sorted; LRU at tail. */ \n struct nffs_inode nci_inode ; /* Full inode. */ \n struct nffs_cache_block_list nci_block_list ; /* List of cached blocks. */ \n uint32_t nci_file_size ; /* Total file size. */ \n}; Only file inodes are cached; directory inodes are never cached. Within a cached inode, all cached data blocks are contiguous. E.g., if the start and end of a file are cached, then the middle must also be cached. A data block is only cached if its owning file is also cached. Internally, cached inodes are stored in a singly-linked list, ordered by time of use. The most-recently-used entry is the first element in the list. If a new inode needs to be cached, but the inode cache is full, the least-recently-used entry is freed to make room for the new one. The following operations cause an inode to be cached: Querying a file's length. Seeking within a file. Reading from a file. Writing to a file. The following operations cause a data block to be cached: Reading from the block. Writing to the block. If one of the above operations is applied to a data block that is not currently cached, nffs uses the following procedure to cache the necessary block: If none of the owning inode's blocks are currently cached, allocate a cached block entry corresponding to the requested block and insert it into the inode's list. Else if the requested file offset is less than that of the first cached block, bridge the gap between the inode's sequence of cached blocks and the block that now needs to be cached. This is accomplished by caching each block in the gap, finishing with the requested block. Else (the requested offset is beyond the end of the cache), If the requested offset belongs to the block that immediately follows the end of the cache, cache the block and append it to the list. Else, clear the cache, and populate it with the single entry corresponding to the requested block. If the system is unable to allocate a cached block entry at any point during the above procedure, the system frees up other blocks currently in the cache. This is accomplished as follows: Iterate the inode cache in reverse (i.e., start with the least-recently-used entry). For each entry: If the entry's cached block list is empty, advance to the next entry. Else, free all the cached blocks in the entry's list. Because the system imposes a minimum block cache size of one, the above procedure will always reclaim at least one cache block entry. The above procedure may result in the freeing of the block list that belongs to the very inode being operated on. This is OK, as the final block to get cached is always the block being requested.",
- "title": "Inode cache and Data Block cache"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#detection",
- "text": "The file system detection process consists of scanning a specified set of flash regions for valid nffs areas, and then populating the RAM representation of the file system with the detected objects. Detection is initiated with the nffs_detect() function. Not every area descriptor passed to nffs_detect() needs to reference a valid nffs area. Detection is successful as long as a complete file system is detected somewhere in the specified regions of flash. If an application is unsure where a file system might be located, it can initiate detection across the entire flash region. A detected file system is valid if: At least one non-scratch area is present. At least one scratch area is present (only the first gets used if there is more than one). The root directory inode is present. During detection, each indicated region of flash is checked for a valid area header. The contents of each valid non-scratch area are then restored into the nffs RAM representation. The following procedure is applied to each object in the area: Verify the object's integrity via a crc16 check. If invalid, the object is discarded and the procedure restarts on the next object in the area. Convert the disk object into its corresponding RAM representation and insert it into the hash table. If the object is an inode, its reference count is initialized to 1, indicating ownership by its parent directory. If an object with the same ID is already present, then one supersedes the other. Accept the object with the greater sequence number and discard the other. If the object references a nonexistent inode (parent directory in the case of an inode; owning file in the case of a data block), insert a temporary \"dummy\" inode into the hash table so that inter-object links can be maintained until the absent inode is eventually restored. Dummy inodes are identified by a reference count of 0. If a delete record for an inode is encountered, the inode's parent pointer is set to null to indicate that it should be removed from RAM. If nffs encounters an object that cannot be identified (i.e., its magic number is not valid), it scans the remainder of the flash area for the next valid magic number. Upon encountering a valid object, nffs resumes the procedure described above. After all areas have been restored, a sweep is performed across the entire RAM representation so that invalid inodes can be deleted from memory. For each directory inode: If its reference count is 0 (i.e., it is a dummy), migrate its children to the /lost+found directory, and delete it from the RAM representation. This should only happen in the case of file system corruption. If its parent reference is null (i.e., it was deleted), delete it and all its children from the RAM representation. For each file inode: If its reference count is 0 (i.e., it is a dummy), delete it from the RAM representation. This should only happen in the case of file system corruption. (We should try to migrate the file to the lost+found directory in this case, as mentioned in the todo section). When an object is deleted during this sweep, it is only deleted from the RAM representation; nothing is written to disk. When objects are migrated to the lost+found directory, their parent inode reference is permanently updated on the disk. In addition, a single scratch area is identified during the detection process. The first area whose fda_id value is set to 0xff is designated as the file system scratch area. If no valid scratch area is found, the cause could be that the system was restarted while a garbage collection cycle was in progress. Such a condition is identified by the presence of two areas with the same ID. In such a case, the shorter of the two areas is erased and designated as the scratch area.",
- "title": "Detection"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#formatting",
- "text": "A new nffs file system is created via formatting. Formatting is achieved via the nffs_format() function. During a successful format, an area header is written to each of the specified locations. One of the areas in the set is designated as the initial scratch area.",
- "title": "Formatting"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#flash-writes",
- "text": "The nffs implementation always writes in a strictly sequential fashion within an area. For each area, the system keeps track of the current offset. Whenever an object gets written to an area, it gets written to that area's current offset, and the offset is increased by the object's disk size. When a write needs to be performed, the nffs implementation selects the appropriate destination area by iterating though each area until one with sufficient free space is encountered. There is no write buffering. Each call to a write function results in a write operation being sent to the flash hardware.",
- "title": "Flash writes"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#new-objects",
- "text": "Whenever a new object is written to disk, it is assigned the following properties: ID: A unique value is selected from the 32-bit ID space, as appropriate for the object's type. Sequence number: 0 When a new file or directory is created, a corresponding inode is written to flash. Likewise, a new data block also results in the writing of a corresponding disk object.",
- "title": "New objects"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#movingrenaming-files-and-directories",
- "text": "When a file or directory is moved or renamed, its corresponding inode is rewritten to flash with the following properties: ID: Unchanged Sequence number: Previous value plus one. Parent inode: As specified by the move / rename operation. Filename: As specified by the move / rename operation. Because the inode's ID is unchanged, all dependent objects remain valid.",
- "title": "Moving/Renaming files and directories"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#unlinking-files-and-directories",
- "text": "When a file or directory is unlinked from its parent directory, a deletion record for the unlinked inode gets written to flash. The deletion record is an inode with the following properties: ID: Unchanged Sequence number: Previous value plus one. Parent inode ID: NFFS_ID_NONE When an inode is unlinked, no deletion records need to be written for the inode's dependent objects (constituent data blocks or child inodes). During the next file system detection, it is recognized that the objects belong to a deleted inode, so they are not restored into the RAM representation. If a file has an open handle at the time it gets unlinked, application code can continued to use the file handle to read and write data. All files retain a reference count, and a file isn't deleted from the RAM representation until its reference code drops to 0. Any attempt to open an unlinked file fails, even if the file is referenced by other file handles.",
- "title": "Unlinking files and directories"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#writing-to-a-file",
- "text": "The following procedure is used whenever the application code writes to a file. First, if the write operation specifies too much data to fit into a single block, the operation is split into several separate write operations. Then, for each write operation: Determine which existing blocks the write operation overlaps (n = number of overwritten blocks). If n = 0 , this is an append operation. Write a data block with the following properties: ID: New unique value. Sequence number: 0. Else (n 1) , this write overlaps existing data. For each block in [1, 2, ... n-1] , write a new block containing the updated contents. Each new block supersedes the block it overwrites. That is, each block has the following properties: ID: Unchanged Sequence number: Previous value plus one. Write the nth block. The nth block includes all appended data, if any. As with the other blocks, its ID is unchanged and its sequence number is incremented. Appended data can only be written to the end of the file. That is, \"holes\" are not supported.",
- "title": "Writing to a file"
- },
- {
- "location": "/os/modules/fs/nffs/nffs_internals/#garbage-collection",
- "text": "When the file system is too full to accommodate a write operation, the system must perform garbage collection to make room. The garbage collection procedure is described below: The non-scratch area with the lowest garbage collection sequence number is selected as the \"source area.\" If there are other areas with the same sequence number, the one with the smallest flash offset is selected. The source area's ID is written to the scratch area's header, transforming it into a non-scratch ID. This former scratch area is now known as the \"destination area.\" The RAM representation is exhaustively searched for collectible objects. The following procedure is applied to each inode in the system: If the inode is resident in the source area, copy the inode record to the destination area. If the inode is a file inode, walk the inode's list of data blocks, starting with the last block in the file. Each block that is resident in the source area is copied to the destination area. If there is a run of two or more blocks that are resident in the source area, they are consolidated and copied to the destination area as a single new block (subject to the maximum block size restriction). The source area is reformatted as a scratch sector (i.e., is is fully erased, and its header is rewritten with an ID of 0xff). The area's garbage collection sequence number is incremented prior to rewriting the header. This area is now the new scratch sector.",
- "title": "Garbage collection"
- },
- {
- "location": "/os/modules/fs/otherfs/",
- "text": "Other File Systems\n\n\nLibraries use Mynewt's file system abstraction layer (\nfs/fs\n) for all file operations. Because clients use an abstraction layer, the underlying file system can be swapped out without affecting client code. This page documents the procedure for plugging a custom file system into the Mynewt file system abstraction layer.\n\n\n1. Specify \nfs/fs\n as a dependency of your file system package.\n\n\nThe file system package must register itself with the \nfs/fs\n package, so it must specify \nfs/fs\n as a dependency. As an example, part of the Newtron Flash File System (nffs) \npkg.yml\n is reproduced below. Notice the first item in the \npkg.deps\n list.\n\n\npkg.name: fs/nffs\npkg.deps:\n - fs/fs\n - hw/hal\n - libs/os\n - libs/testutil\n - sys/log\n\n\n\n\n\n2. Register your package's API with the \nfs/fs\n interface.\n\n\nThe \nfs/fs\n package calls into the underlying file system via a collection of function pointers. To plug your file system into the \nfs/fs\n API, you must assign these function pointers to the corresponding routines in your file system package.\n\n\nFor example, \nnffs\n registers itself with \nfs/fs\n as follows (from \nfs/nffs/src/nffs.c\n):\n\n\nstatic\n \nconst\n \nstruct\n \nfs_ops\n \nnffs_ops\n \n=\n {\n .\nf_open\n \n=\n \nnffs_open\n,\n .\nf_close\n \n=\n \nnffs_close\n,\n .\nf_read\n \n=\n \nnffs_read\n,\n .\nf_write\n \n=\n \nnffs_write\n,\n\n .\nf_seek\n \n=\n \nnffs_seek\n,\n .\nf_getpos\n \n=\n \nnffs_getpos\n,\n .\nf_filelen\n \n=\n \nnffs_file_len\n,\n\n .\nf_unlink\n \n=\n \nnffs_unlink\n,\n .\nf_rename\n \n=\n \nnffs_rename\n,\n .\nf_mkdir\n \n=\n \nnffs_mkdir\n,\n\n .\nf_opendir\n \n=\n \nnffs_opendir\n,\n .\nf_readdir\n \n=\n \nnffs_readdir\n,\n .\nf_closedir\n \n=\n \nnffs_closedir\n,\n\n .\nf_dirent_name\n \n=\n \nnffs_dirent_name\n,\n .\nf_dirent_is_dir\n \n=\n \nnffs_dirent_is_dir\n,\n\n .\nf_name\n \n=\n \nnffs\n\n};\n\n\nint\n\n\nnffs_init\n(\nvoid\n)\n{\n \n/* [...] */\n\n \nfs_register\n(\nnffs_ops\n);\n}\n\n\n\n\n\nHeader Files\n\n\nTo gain access to \nfs/fs\n's registration interface, include the following header:\n\n\n#include\n \nfs/fs_if.h",
- "title": "Other File Systems"
- },
- {
- "location": "/os/modules/fs/otherfs/#other-file-systems",
- "text": "Libraries use Mynewt's file system abstraction layer ( fs/fs ) for all file operations. Because clients use an abstraction layer, the underlying file system can be swapped out without affecting client code. This page documents the procedure for plugging a custom file system into the Mynewt file system abstraction layer.",
- "title": "Other File Systems"
- },
- {
- "location": "/os/modules/fs/otherfs/#1-specify-fsfs-as-a-dependency-of-your-file-system-package",
- "text": "The file system package must register itself with the fs/fs package, so it must specify fs/fs as a dependency. As an example, part of the Newtron Flash File System (nffs) pkg.yml is reproduced below. Notice the first item in the pkg.deps list. pkg.name: fs/nffs\npkg.deps:\n - fs/fs\n - hw/hal\n - libs/os\n - libs/testutil\n - sys/log",
- "title": "1. Specify fs/fs as a dependency of your file system package."
- },
- {
- "location": "/os/modules/fs/otherfs/#2-register-your-packages-api-with-the-fsfs-interface",
- "text": "The fs/fs package calls into the underlying file system via a collection of function pointers. To plug your file system into the fs/fs API, you must assign these function pointers to the corresponding routines in your file system package. For example, nffs registers itself with fs/fs as follows (from fs/nffs/src/nffs.c ): static const struct fs_ops nffs_ops = {\n . f_open = nffs_open ,\n . f_close = nffs_close ,\n . f_read = nffs_read ,\n . f_write = nffs_write ,\n\n . f_seek = nffs_seek ,\n . f_getpos = nffs_getpos ,\n . f_filelen = nffs_file_len ,\n\n . f_unlink = nffs_unlink ,\n . f_rename = nffs_rename ,\n . f_mkdir = nffs_mkdir ,\n\n . f_opendir = nffs_opendir ,\n . f_readdir = nffs_readdir ,\n . f_closedir = nffs_closedir ,\n\n . f_dirent_name = nffs_dirent_name ,\n . f_dirent_is_dir = nffs_dirent_is_dir ,\n\n . f_name = nffs \n}; int nffs_init ( void )\n{\n /* [...] */ \n fs_register ( nffs_ops );\n}",
- "title": "2. Register your package's API with the fs/fs interface."
- },
- {
- "location": "/os/modules/fs/otherfs/#header-files",
- "text": "To gain access to fs/fs 's registration interface, include the following header: #include fs/fs_if.h",
- "title": "Header Files"
- },
- {
- "location": "/os/modules/hal/hal/",
- "text": "Hardware Abstraction Layer\n\n\nDescription\n\n\nThe Hardware Abstraction Layer (HAL) in Mynewt is a low-level, base peripheral abstraction. HAL provides a core set of services that is implemented for each MCU supported by Mynewt. Device drivers are typically the software libraries that initialize the hardware and manage access to the hardware by higher layers of software. In the Mynewt OS, the layers can be depicted in the following manner.\n\n\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| app |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| (n)drivers |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| HAL | BSP |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n\n\n\n\n\n\n\n\n\nThe Board Support Package (BSP) abstracts board specific configurations e.g. CPU frequency, input voltage, LED pins, on-chip flash map etc.\n\n\n\n\n\n\nThe Hardware Abstraction Layer (HAL) abstracts architecture-specific functionality. It initializes and enables components within a master processor. It is designed to be portable across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.). It includes code that initializes and manages access to components of the board such as board buses (I2C, PCI, PCMCIA, etc.), off-chip memory (controllers, level 2+ cache, Flash, etc.), and off-chip I/O (Ethernet, RS-232, display, mouse, etc.)\n\n\n\n\n\n\nThe driver sits atop the BSP and HAL. It abstracts the common modes of operation for each peripheral device connected via the standard interfaces to the processor. There may be multiple driver implementations of differing complexities for a particular peripheral device. The drivers are the ones that register with the kernel\u2019s power management APIs, and manage turning on and off peripherals and external chipsets, etc. \n\n\n\n\n\n\nGeneral design principles\n\n\n\n\n\n\nThe HAL API should be simple. It should be as easy to implement for hardware as possible. A simple HAL API makes it easy to bring up new MCUs quickly.\n\n\n\n\n\n\nThe HAL API should portable across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.).\n\n\n\n\n\n\nExample\n\n\nA Mynewt contributor might write a light-switch driver that provides the functionality of an intelligent light\nswitch. This might involve using a timer, a General Purpose Output (GPO)\nto set the light to the on or off state, and flash memory to log the times the\nlights were turned on or off. The contributor would like this package to\nwork with as many different hardware platforms as possible, but can't\npossibly test across the complete set of hardware supported by Mynewt.\n\n\nSolution\n: The contributor uses the HAL APIs to control the peripherals.\nThe Mynewt team ensures that the underlying HAL devices all work equivalently\nthrough the HAL APIs. The contributors library is independent of the specifics\nof the hardware. \n\n\nDependency\n\n\nTo include the HAL within your project, simply add it to your package\ndependencies as follows:\n\n\npkg.deps:\n . . .\n hw/hal\n\n\n\n\n\nPlatform Support\n\n\nNot all platforms (MCU and BSP) support all HAL devices. Consult your MCU\nor BSP documentation to find out if you have hardware support for the\nperipherals you are interested in using. Once you verify support, then\nconsult the MCU implementation and see if the specific HAL interface (xxxx) you are\nusing is in the \nmcu/\nmcu-name\n/src/hal_xxxx.c\n implementation. Finally, you\ncan build your project and ensure that there are no unresolved hal_xxxx\nexternals.",
- "title": "toc"
- },
- {
- "location": "/os/modules/hal/hal/#hardware-abstraction-layer",
- "text": "",
- "title": "Hardware Abstraction Layer"
- },
- {
- "location": "/os/modules/hal/hal/#description",
- "text": "The Hardware Abstraction Layer (HAL) in Mynewt is a low-level, base peripheral abstraction. HAL provides a core set of services that is implemented for each MCU supported by Mynewt. Device drivers are typically the software libraries that initialize the hardware and manage access to the hardware by higher layers of software. In the Mynewt OS, the layers can be depicted in the following manner. +\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| app |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| (n)drivers |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| HAL | BSP |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+ The Board Support Package (BSP) abstracts board specific configurations e.g. CPU frequency, input voltage, LED pins, on-chip flash map etc. The Hardware Abstraction Layer (HAL) abstracts architecture-specific functionality. It initializes and enables components within a master processor. It is designed to be portable across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.). It includes code that initializes and manages access to components of the board such as board buses (I2C, PCI, PCMCIA, etc.), off-chip memory (controllers, level 2+ cache, Flash, etc.), and off-chip I/O (Ethernet, RS-232, display, mouse, etc.) The driver sits atop the BSP and HAL. It abstracts the common modes of operation for each peripheral device connected via the standard interfaces to the processor. There may be multiple driver implementations of differing complexities for a particular peripheral device. The drivers are the ones that register with the kernel\u2019s power management APIs, and manage turning on and off peripherals and external chipsets, etc.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal/#general-design-principles",
- "text": "The HAL API should be simple. It should be as easy to implement for hardware as possible. A simple HAL API makes it easy to bring up new MCUs quickly. The HAL API should portable across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.).",
- "title": "General design principles"
- },
- {
- "location": "/os/modules/hal/hal/#example",
- "text": "A Mynewt contributor might write a light-switch driver that provides the functionality of an intelligent light\nswitch. This might involve using a timer, a General Purpose Output (GPO)\nto set the light to the on or off state, and flash memory to log the times the\nlights were turned on or off. The contributor would like this package to\nwork with as many different hardware platforms as possible, but can't\npossibly test across the complete set of hardware supported by Mynewt. Solution : The contributor uses the HAL APIs to control the peripherals.\nThe Mynewt team ensures that the underlying HAL devices all work equivalently\nthrough the HAL APIs. The contributors library is independent of the specifics\nof the hardware.",
- "title": "Example"
- },
- {
- "location": "/os/modules/hal/hal/#dependency",
- "text": "To include the HAL within your project, simply add it to your package\ndependencies as follows: pkg.deps:\n . . .\n hw/hal",
- "title": "Dependency"
- },
- {
- "location": "/os/modules/hal/hal/#platform-support",
- "text": "Not all platforms (MCU and BSP) support all HAL devices. Consult your MCU\nor BSP documentation to find out if you have hardware support for the\nperipherals you are interested in using. Once you verify support, then\nconsult the MCU implementation and see if the specific HAL interface (xxxx) you are\nusing is in the mcu/ mcu-name /src/hal_xxxx.c implementation. Finally, you\ncan build your project and ensure that there are no unresolved hal_xxxx\nexternals.",
- "title": "Platform Support"
- },
- {
- "location": "/os/modules/hal/hal_api/",
- "text": "HAL Interfaces\n\n\nThe HAL supports separate interfaces for many peripherals. A brief\ndescription of the interfaces are shown below.\n\n\n\n\n\n\n\n\nHal Name\n\n\n Interface File \n\n\nDescription \n\n\n\n\n\n\n\n\n\n\nbsp\n\n\nhal_bsp.h\n\n\nAn hardware independent interface to identify and access underlying BSP.\n\n\n\n\n\n\nflash api for apps to use\n\n\nhal_flash.h\n\n\nA blocking interface to access flash memory.\n\n\n\n\n\n\nflash api for drivers to implement\n\n\nflash_map.h\n\n\nAn interface to query information about the flash map (regions and sectors)\n\n\n\n\n\n\ngpio\n\n\nhal_gpio.h\n\n\nAn interface for manipulating General Purpose Inputs and Outputs.\n\n\n\n\n\n\ni2c\n\n\nhal_i2c.h\n\n\nAn interface for controlling Inter-Integrated-Circuit (i2c) devices.\n\n\n\n\n\n\nOS tick\n\n\nhal_os_tick.h\n\n\nAn interface to set up interrupt timers or halt CPU in terms of OS ticks.\n\n\n\n\n\n\nspi\n\n\nhal_spi.h\n\n\nAn interface for controlling Serial Peripheral Interface (SPI) devices.\n\n\n\n\n\n\nsystem\n\n\nhal_system.h\n\n\nAn interface for starting and resetting the system.\n\n\n\n\n\n\ntimer\n\n\nhal_cputime.h\n\n\nAn interface for configuring and running HW timers\n\n\n\n\n\n\nuart\n\n\nhal_uart.h\n\n\nAn interface for communicating via asynchronous serial interface.\n\n\n\n\n\n\nwatchdog\n\n\nhal_watchdog.h\n\n\nAn interface for enabling internal hardware watchdogs.",
- "title": "Summary"
- },
- {
- "location": "/os/modules/hal/hal_api/#hal-interfaces",
- "text": "The HAL supports separate interfaces for many peripherals. A brief\ndescription of the interfaces are shown below. Hal Name Interface File Description bsp hal_bsp.h An hardware independent interface to identify and access underlying BSP. flash api for apps to use hal_flash.h A blocking interface to access flash memory. flash api for drivers to implement flash_map.h An interface to query information about the flash map (regions and sectors) gpio hal_gpio.h An interface for manipulating General Purpose Inputs and Outputs. i2c hal_i2c.h An interface for controlling Inter-Integrated-Circuit (i2c) devices. OS tick hal_os_tick.h An interface to set up interrupt timers or halt CPU in terms of OS ticks. spi hal_spi.h An interface for controlling Serial Peripheral Interface (SPI) devices. system hal_system.h An interface for starting and resetting the system. timer hal_cputime.h An interface for configuring and running HW timers uart hal_uart.h An interface for communicating via asynchronous serial interface. watchdog hal_watchdog.h An interface for enabling internal hardware watchdogs.",
- "title": "HAL Interfaces"
- },
- {
- "location": "/os/modules/hal/hal_bsp/hal_bsp/",
- "text": "hal_bsp\n\n\nThis is the hardware independent BSP (Board Support Package) Interface for Mynewt.\n\n\nDescription\n\n\nContains the basic operations to initialize, specify memory to include in coredump, configure interrupt priority etc.\n\n\nDefinition\n\n\nhal_bsp.h\n\n\nExamples",
- "title": "BSP"
- },
- {
- "location": "/os/modules/hal/hal_bsp/hal_bsp/#hal_bsp",
- "text": "This is the hardware independent BSP (Board Support Package) Interface for Mynewt.",
- "title": "hal_bsp"
- },
- {
- "location": "/os/modules/hal/hal_bsp/hal_bsp/#description",
- "text": "Contains the basic operations to initialize, specify memory to include in coredump, configure interrupt priority etc.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_bsp/hal_bsp/#definition",
- "text": "hal_bsp.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_bsp/hal_bsp/#examples",
- "text": "",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash/",
- "text": "hal_flash\n\n\nThe hardware independent interface to flash memory that is used by applications.\n\n\nDescription\n\n\nThe API offers basic initialization, read, write, erase, sector erase, and other operations.\n\n\nDefinition\n\n\nhal_flash.h\n\n\nExamples",
- "title": "flash API for apps"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash/#hal_flash",
- "text": "The hardware independent interface to flash memory that is used by applications.",
- "title": "hal_flash"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash/#description",
- "text": "The API offers basic initialization, read, write, erase, sector erase, and other operations.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash/#definition",
- "text": "hal_flash.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash/#examples",
- "text": "",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash_int/",
- "text": "hal_flash_int\n\n\nThe API that flash drivers have to implement.\n\n\nDescription\n\n\nThe BSP for the hardware will implement the structs defined in this API.\n\n\nDefinition\n\n\nhal_flash_int.h\n\n\nExamples\n\n\nThe Nordic nRF52 bsp implements the hal_flash_int API as seen in \nhal_bsp.c\n\n\nconst struct hal_flash *\nhal_bsp_flash_dev(uint8_t id)\n{\n /*\n * Internal flash mapped to id 0.\n */\n if (id != 0) {\n return NULL;\n }\n return \nnrf52k_flash_dev;\n}",
- "title": "flash_int"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash_int/#hal_flash_int",
- "text": "The API that flash drivers have to implement.",
- "title": "hal_flash_int"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash_int/#description",
- "text": "The BSP for the hardware will implement the structs defined in this API.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash_int/#definition",
- "text": "hal_flash_int.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_flash/hal_flash_int/#examples",
- "text": "The Nordic nRF52 bsp implements the hal_flash_int API as seen in hal_bsp.c const struct hal_flash *\nhal_bsp_flash_dev(uint8_t id)\n{\n /*\n * Internal flash mapped to id 0.\n */\n if (id != 0) {\n return NULL;\n }\n return nrf52k_flash_dev;\n}",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_gpio/hal_gpio/",
- "text": "hal_gpio\n\n\nThis is the hardware independent GPIO (General Purpose Input Output) Interface for Mynewt.\n\n\nDescription\n\n\nContains the basic operations to set and read General Purpose Digital I/O Pins\nwithin a Mynewt system.\n\n\nIndividual GPIOs are referenced in the APIs as \npins\n. However, in this interface the \npins\n are virtual GPIO pins. The MCU header file maps these virtual \npins\n to the physical GPIO ports and pins.\n\n\nTypically, the BSP code may define named I/O pins in terms of these virtual \npins\n to describe the devices attached to the physical pins.\n\n\nHere's a brief example so you can get the gist of the translation.\n\n\nSuppose my product uses the stm32F4xx processor. There already exists support for this processor within Mynewt. The processor has N ports (A,B,C..) of 16 GPIO pins per port. The MCU hal_gpio driver maps these to a set of virtual pins 0-N where port A maps to 0-15, Port B maps to 16-31, Port C maps to 32-47 and so on. The exact number of physical port (and virtual\nport pins) depends on the specific variant of the stm32F4xx. \n\n\nSo if I want to turn on port B pin 3, that would be virtual pin 1*16 + 3 = 19.\nThis translation is defined in the MCU implementation of\n\nhal_gpio.c\n\nfor the stmf32F4xx. Each MCU will typically have a different translation method\ndepending on its GPIO architecture.\n\n\nNow, when writing a BSP, it's common to give names to the relevant port pins that you are using. Thus, the BSP may define a mapping between a function and a virtual port pin in the \nbsp.h\n header file for the BSP. For example,\n\n\n#define SYSTEM_LED (37)\n#define FLASH_SPI_CHIP_SELECT (3)\n\n\n\n\n\nwould map the system indicator LED to virtual pin 37 which on the stm32F4xx would be Port C pin 5 and the chip select line for the external SPI flash to virtual pin 3 which on the stm32F4xxis port A pin 3.\n\n\nSaid another way, in this specific system we get\n\n\nSYSTEM_LED --\n hal_gpio virtual pin 37 --\n port C pin 5 on the stm34F4xx\n\n\n\n\n\nDefinition\n\n\nhal_gpio.h\n\n\nExamples\n\n\nBlinky\n\n\nBlinky uses the hal_gpio to blink the system LED. The blinky source code is available in the\n\nblinky repo\n.\nExamine how \nblinky_task_handler\n initializes and toggles the GPIO to control the LED.",
- "title": "GPIO"
- },
- {
- "location": "/os/modules/hal/hal_gpio/hal_gpio/#hal_gpio",
- "text": "This is the hardware independent GPIO (General Purpose Input Output) Interface for Mynewt.",
- "title": "hal_gpio"
- },
- {
- "location": "/os/modules/hal/hal_gpio/hal_gpio/#description",
- "text": "Contains the basic operations to set and read General Purpose Digital I/O Pins\nwithin a Mynewt system. Individual GPIOs are referenced in the APIs as pins . However, in this interface the pins are virtual GPIO pins. The MCU header file maps these virtual pins to the physical GPIO ports and pins. Typically, the BSP code may define named I/O pins in terms of these virtual pins to describe the devices attached to the physical pins. Here's a brief example so you can get the gist of the translation. Suppose my product uses the stm32F4xx processor. There already exists support for this processor within Mynewt. The processor has N ports (A,B,C..) of 16 GPIO pins per port. The MCU hal_gpio driver maps these to a set of virtual pins 0-N where port A maps to 0-15, Port B maps to 16-31, Port C maps to 32-47 and so on. The exact number of physical port (and virtual\nport pins) depends on the specific variant of the stm32F4xx. So if I want to turn on port B pin 3, that would be virtual pin 1*16 + 3 = 19.\nThis translation is defined in the MCU implementation of hal_gpio.c \nfor the stmf32F4xx. Each MCU will typically have a different translation method\ndepending on its GPIO architecture. Now, when writing a BSP, it's common to give names to the relevant port pins that you are using. Thus, the BSP may define a mapping between a function and a virtual port pin in the bsp.h header file for the BSP. For example, #define SYSTEM_LED (37)\n#define FLASH_SPI_CHIP_SELECT (3) would map the system indicator LED to virtual pin 37 which on the stm32F4xx would be Port C pin 5 and the chip select line for the external SPI flash to virtual pin 3 which on the stm32F4xxis port A pin 3. Said another way, in this specific system we get SYSTEM_LED -- hal_gpio virtual pin 37 -- port C pin 5 on the stm34F4xx",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_gpio/hal_gpio/#definition",
- "text": "hal_gpio.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_gpio/hal_gpio/#examples",
- "text": "",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_gpio/hal_gpio/#blinky",
- "text": "Blinky uses the hal_gpio to blink the system LED. The blinky source code is available in the blinky repo .\nExamine how blinky_task_handler initializes and toggles the GPIO to control the LED.",
- "title": "Blinky"
- },
- {
- "location": "/os/modules/hal/hal_i2c/hal_i2c/",
- "text": "hal_i2c\n\n\nThe hardware independent interface to I2C Devices.\n\n\nDescription\n\n\nAn Inter-Integrated Circuit (I\u00b2C ] I-squared-C) bus is a multi-master,\nmulti-save serial interface used to connect components on a circuit board\nand often peripherals devices located off the circuit board.\n\n\nI2C is often though of as a 2-wire protocol because it uses two wires (SDA, SCL)\nto send data between devices. \n\n\nFor a detailed description of I2C, see the \nI\u00b2C wikipedia page\n\n\nDefinition\n\n\nhal_i2c.h\n\n\nHAL_I2C Theory Of Operation\n\n\nAn I\u00b2C transaction typically involves acquiring the bus, sending and/or receiving\ndata and release the bus. The bus acquisition portion is important because\nthe bus is typically multi-master so other devices may be trying to read/write\nthe same peripheral. \n\n\nHAL_I2C implements a master interface to the I\u00b2C bus. Typical usage of the \ninterface would involve the following steps.\n\n\nInitialize an i2c device with:\n hal_i2c_init()\n\n\nWhen you wish to perform an i2c transaction, you call one or both of:\n hal_i2c_master_write();\n hal_i2c_master_read();\n\n\nThese functions will issue a START condition, followed by the device's\n7-bit I2C address, and then send or receive the payload based on the data\nprovided. This will cause a repeated start on the bus, which is valid in\nI2C specification, and the decision to use repeated starts was made to\nsimplify the I2C HAL. To set the STOP condition at an appropriate moment,\nyou set the \nlast_op\n field to a \n1\n in either function.\n\n\nFor example, in an I2C memory access you might write a register address and\nthen read data back via:\n hal_i2c_write(); -- write to a specific register on the device\n hal_i2c_read(); --- read back data, setting 'last_op' to '1'\n\n\nAn addition API was added called \nhal_i2c_probe\n. This command combines\n\nhal_i2c_begin()\n, \nhal_i2c_read\n, and \nhal_i2c_end()\n to try to read 0-bytes\nfrom a specific bus address. its intended to provide an easy way to probe\nthe bus for a specific device. NOTE: if the device is write-only, it will \nnot appear with this command.\n\n\nA slave API is pending for further release.\n\n\nHAL_I2C Data\n\n\nData to read/write is passed to the hal_i2c APIs via the \n\n\nstruct hal_i2c_master_data {\n uint8_t address; /* destination address */\n uint16_t len; /* number of bytes to transmit or receive */\n uint8_t *buffer; /* data buffer for transmit or receive */\n};\n\n\n\n\n\nbuffer\n is a pointer to the data to send. \nlen\n is the number of bytes\nto send over the bus. \naddress\n is a 7-bit bus address of the device.\n\n\nWhen I\u00b2C builds its address, it uses the 7-bit address plus a 1-bit R/W \n(read/write) indicator to identify the device and direction of the \ntransaction. Thus when using this API, you should use a 7-bit address\nin the data structure and ensure that address is a value between 0-127.\n\n\nAs an example, consider an I\u00b2C device address that looks like this:\n\n\n\n\n\n\n\n\nB7\n\n\nB6\n\n\nB5\n\n\nB4\n\n\nB3\n\n\nB2\n\n\nB1\n\n\nB0\n\n\n\n\n\n\n\n\n\n\n1\n\n\n0\n\n\n0\n\n\n0\n\n\n1\n\n\n1\n\n\n0\n\n\nR/W\n\n\n\n\n\n\nMSB\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nLSB\n\n\n\n\n\n\n\n\nIn the HAL_I2C API you would communicate with this device with address \n\n0b1000110\n, which is hex 0x46 or decimal 70. The I\u00b2C drive would add the R/W bit\nand transmit it as hex 0x8C (binary 10001100) or 0x8D (binary 10001101) depending whether it was a read or\nwrite command.",
- "title": "I2C"
- },
- {
- "location": "/os/modules/hal/hal_i2c/hal_i2c/#hal_i2c",
- "text": "The hardware independent interface to I2C Devices.",
- "title": "hal_i2c"
- },
- {
- "location": "/os/modules/hal/hal_i2c/hal_i2c/#description",
- "text": "An Inter-Integrated Circuit (I\u00b2C ] I-squared-C) bus is a multi-master,\nmulti-save serial interface used to connect components on a circuit board\nand often peripherals devices located off the circuit board. I2C is often though of as a 2-wire protocol because it uses two wires (SDA, SCL)\nto send data between devices. For a detailed description of I2C, see the I\u00b2C wikipedia page",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_i2c/hal_i2c/#definition",
- "text": "hal_i2c.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_i2c/hal_i2c/#hal_i2c-theory-of-operation",
- "text": "An I\u00b2C transaction typically involves acquiring the bus, sending and/or receiving\ndata and release the bus. The bus acquisition portion is important because\nthe bus is typically multi-master so other devices may be trying to read/write\nthe same peripheral. HAL_I2C implements a master interface to the I\u00b2C bus. Typical usage of the \ninterface would involve the following steps. Initialize an i2c device with:\n hal_i2c_init() When you wish to perform an i2c transaction, you call one or both of:\n hal_i2c_master_write();\n hal_i2c_master_read(); These functions will issue a START condition, followed by the device's\n7-bit I2C address, and then send or receive the payload based on the data\nprovided. This will cause a repeated start on the bus, which is valid in\nI2C specification, and the decision to use repeated starts was made to\nsimplify the I2C HAL. To set the STOP condition at an appropriate moment,\nyou set the last_op field to a 1 in either function. For example, in an I2C memory access you might write a register address and\nthen read data back via:\n hal_i2c_write(); -- write to a specific register on the device\n hal_i2c_read(); --- read back data, setting 'last_op' to '1' An addition API was added called hal_i2c_probe . This command combines hal_i2c_begin() , hal_i2c_read , and hal_i2c_end() to try to read 0-bytes\nfrom a specific bus address. its intended to provide an easy way to probe\nthe bus for a specific device. NOTE: if the device is write-only, it will \nnot appear with this command. A slave API is pending for further release.",
- "title": "HAL_I2C Theory Of Operation"
- },
- {
- "location": "/os/modules/hal/hal_i2c/hal_i2c/#hal_i2c-data",
- "text": "Data to read/write is passed to the hal_i2c APIs via the struct hal_i2c_master_data {\n uint8_t address; /* destination address */\n uint16_t len; /* number of bytes to transmit or receive */\n uint8_t *buffer; /* data buffer for transmit or receive */\n}; buffer is a pointer to the data to send. len is the number of bytes\nto send over the bus. address is a 7-bit bus address of the device. When I\u00b2C builds its address, it uses the 7-bit address plus a 1-bit R/W \n(read/write) indicator to identify the device and direction of the \ntransaction. Thus when using this API, you should use a 7-bit address\nin the data structure and ensure that address is a value between 0-127. As an example, consider an I\u00b2C device address that looks like this: B7 B6 B5 B4 B3 B2 B1 B0 1 0 0 0 1 1 0 R/W MSB LSB In the HAL_I2C API you would communicate with this device with address 0b1000110 , which is hex 0x46 or decimal 70. The I\u00b2C drive would add the R/W bit\nand transmit it as hex 0x8C (binary 10001100) or 0x8D (binary 10001101) depending whether it was a read or\nwrite command.",
- "title": "HAL_I2C Data"
- },
- {
- "location": "/os/modules/hal/hal_os_tick/hal_os_tick/",
- "text": "hal_os_tick\n\n\nThe hardware independent interface to set up interrupt timers or halt CPU in terms of OS ticks.\n\n\nDescription\n\n\nSet up the periodic timer to interrupt at a frequency of 'os_ticks_per_sec' using the following function call where 'prio' is the cpu-specific priority of the periodic timer interrupt. \n\n\nvoid\n \nos_tick_init\n(\nuint32_t\n \nos_ticks_per_sec\n, \nint\n \nprio\n);\n\n\n\n\n\nYou can halt CPU for up to \nn\n ticks:\n\n\nvoid\n \nos_tick_idle\n(\nos_time_t\n \nn\n);\n\n\n\n\n\nThe function implementations are in the mcu-specific directories such as \nhw/mcu/nordic/nrf51xxx/src/hal_os_tick.c\n.\n\n\nDefinition\n\n\nhal_os_tick.h\n\n\nExamples\n\n\nAn example of the API being used by the OS kernel for the Cortex M0 architecture to initialize and start the system clock timer can be seen in \nkernel/os/src/arch/cortex_m0/os_arch_arm.c\n.",
- "title": "OS Tick"
- },
- {
- "location": "/os/modules/hal/hal_os_tick/hal_os_tick/#hal_os_tick",
- "text": "The hardware independent interface to set up interrupt timers or halt CPU in terms of OS ticks.",
- "title": "hal_os_tick"
- },
- {
- "location": "/os/modules/hal/hal_os_tick/hal_os_tick/#description",
- "text": "Set up the periodic timer to interrupt at a frequency of 'os_ticks_per_sec' using the following function call where 'prio' is the cpu-specific priority of the periodic timer interrupt. void os_tick_init ( uint32_t os_ticks_per_sec , int prio ); You can halt CPU for up to n ticks: void os_tick_idle ( os_time_t n ); The function implementations are in the mcu-specific directories such as hw/mcu/nordic/nrf51xxx/src/hal_os_tick.c .",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_os_tick/hal_os_tick/#definition",
- "text": "hal_os_tick.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_os_tick/hal_os_tick/#examples",
- "text": "An example of the API being used by the OS kernel for the Cortex M0 architecture to initialize and start the system clock timer can be seen in kernel/os/src/arch/cortex_m0/os_arch_arm.c .",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_spi/hal_spi/",
- "text": "hal_spi\n\n\nSPI (Serial Peripheral Interface) is a synchronous 4-wire serial interface\ncommonly used to connect components in embedded systems.\n\n\nFor a detailed description of SPI, see \nWikipedia\n.\n\n\nDescription\n\n\nThe Mynewt HAL interface supports the SPI master functionality with both blocking and non-blocking interface. SPI slave functionality is supported in non-blocking mode.\n\n\nDefinition\n\n\nhal_spi.h\n\n\nHAL_SPI Theory Of Operation\n\n\nSPI is called a 4-wire interface because of the 4 signals, MISO, MOSI, CLK, \nand SS. The SS signal (slave select) is an active low signal that activates\na SPI slave device. This is how a master \"addresses\" a particular slave\ndevice. Often this signal is also referred to as \"chip select\" as it\nselects particular slave device for communications.\n\n\nThe Mynewt SPI HAL has blocking and non-blocking transfers. Blocking means that the API call\nto transfer a byte will wait until the byte completes transmissions before\nthe function returns. Blocking interface can be used for only the master slave SPI type.\nNon-blocking means he function returns control to the execution environment immediately after the API call and a callback function is executed at the completion of the transmission. Non-blocking interface can be used for both master and slave SPI types.\n\n\nThe \nhal_spi_config\n method in the API above allows the SPI to be configured with appropriate settings for master or slave. It Must be called after the spi is initialized (i.e. after hal_spi_init is called) and when the spi is disabled (i.e. user must call hal_spi_disable if the spi has been enabled through hal_spi_enable prior to calling this function). It can also be used to reconfigure an initialized SPI (assuming it is disabled as described previously).\n\n\nint\n \nhal_spi_config\n(\nint\n \nspi_num\n, \nstruct\n \nhal_spi_settings\n \n*psettings\n);\n\n\n\n\n\nThe SPI settings consist of the following:\n\n\nstruct\n \nhal_spi_settings\n {\n \nuint8_t\n \ndata_mode\n;\n \nuint8_t\n \ndata_order\n;\n \nuint8_t\n \nword_size\n;\n \nuint32_t\n \nbaudrate\n; \n/* baudrate in kHz */\n\n};\n\n\n\n\n\nThe Mynewt SPI HAL does not include built-in SS (Slave Select) signaling. It's up to the \nhal_spi user to control their own SS pins. Typically applications will do \nthis with GPIO.",
- "title": "SPI"
- },
- {
- "location": "/os/modules/hal/hal_spi/hal_spi/#hal_spi",
- "text": "SPI (Serial Peripheral Interface) is a synchronous 4-wire serial interface\ncommonly used to connect components in embedded systems. For a detailed description of SPI, see Wikipedia .",
- "title": "hal_spi"
- },
- {
- "location": "/os/modules/hal/hal_spi/hal_spi/#description",
- "text": "The Mynewt HAL interface supports the SPI master functionality with both blocking and non-blocking interface. SPI slave functionality is supported in non-blocking mode.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_spi/hal_spi/#definition",
- "text": "hal_spi.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_spi/hal_spi/#hal_spi-theory-of-operation",
- "text": "SPI is called a 4-wire interface because of the 4 signals, MISO, MOSI, CLK, \nand SS. The SS signal (slave select) is an active low signal that activates\na SPI slave device. This is how a master \"addresses\" a particular slave\ndevice. Often this signal is also referred to as \"chip select\" as it\nselects particular slave device for communications. The Mynewt SPI HAL has blocking and non-blocking transfers. Blocking means that the API call\nto transfer a byte will wait until the byte completes transmissions before\nthe function returns. Blocking interface can be used for only the master slave SPI type.\nNon-blocking means he function returns control to the execution environment immediately after the API call and a callback function is executed at the completion of the transmission. Non-blocking interface can be used for both master and slave SPI types. The hal_spi_config method in the API above allows the SPI to be configured with appropriate settings for master or slave. It Must be called after the spi is initialized (i.e. after hal_spi_init is called) and when the spi is disabled (i.e. user must call hal_spi_disable if the spi has been enabled through hal_spi_enable prior to calling this function). It can also be used to reconfigure an initialized SPI (assuming it is disabled as described previously). int hal_spi_config ( int spi_num , struct hal_spi_settings *psettings ); The SPI settings consist of the following: struct hal_spi_settings {\n uint8_t data_mode ;\n uint8_t data_order ;\n uint8_t word_size ;\n uint32_t baudrate ; /* baudrate in kHz */ \n}; The Mynewt SPI HAL does not include built-in SS (Slave Select) signaling. It's up to the \nhal_spi user to control their own SS pins. Typically applications will do \nthis with GPIO.",
- "title": "HAL_SPI Theory Of Operation"
- },
- {
- "location": "/os/modules/hal/hal_system/hal_sys/",
- "text": "hal_system\n\n\nA hardware independent interface for starting and resetting the system.\n\n\nDescription\n\n\nThe API allows the user to detect whether a debugger is connected, sissue a soft reset, and enumerate the reset causes. The functions are implemented in the MCU specific directories e.g. \nhal_reset_cause.c\n, \nhal_system.c\n, and \nhal_system_start.c\n in \n/hw/mcu/nordic/nrf52xxx/src/\n directory for Nordic nRF52 series of chips.\n\n\nDefinition\n\n\nhal_system.h\n\n\nExamples",
- "title": "System"
- },
- {
- "location": "/os/modules/hal/hal_system/hal_sys/#hal_system",
- "text": "A hardware independent interface for starting and resetting the system.",
- "title": "hal_system"
- },
- {
- "location": "/os/modules/hal/hal_system/hal_sys/#description",
- "text": "The API allows the user to detect whether a debugger is connected, sissue a soft reset, and enumerate the reset causes. The functions are implemented in the MCU specific directories e.g. hal_reset_cause.c , hal_system.c , and hal_system_start.c in /hw/mcu/nordic/nrf52xxx/src/ directory for Nordic nRF52 series of chips.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_system/hal_sys/#definition",
- "text": "hal_system.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_system/hal_sys/#examples",
- "text": "",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_timer/hal_timer/",
- "text": "hal_timer\n\n\nThe hardware independent timer structure and API to configure, initialize, and run timers.\n\n\nDescription\n\n\nThe HAL timer structure is shown below. The user can declare as many of these structures as required. They are enqueued on a particular HW timer queue when the user calls the hal_timer_start or hal_timer_start_at API. The user must have called hal_timer_set_cb before starting a timer.\n\n\nNOTE: the user should not have to modify/examine the contents of this structure; the hal timer API should be used.\n\n\nstruct\n \nhal_timer\n\n{\n \nvoid\n \n*bsp_timer\n; \n/* Internal platform specific pointer */\n\n \nhal_timer_cb\n \ncb_func\n; \n/* Callback function */\n\n \nvoid\n \n*cb_arg\n; \n/* Callback argument */\n\n \nuint32_t\n \nexpiry\n; \n/* Tick at which timer should expire */\n\n \nTAILQ_ENTRY\n(\nhal_timer\n) \nlink\n; \n/* Queue linked list structure */\n\n};\n\n\n\n\n\nDefinition\n\n\nhal_timer.h\n\n\nExamples",
- "title": "Timer"
- },
- {
- "location": "/os/modules/hal/hal_timer/hal_timer/#hal_timer",
- "text": "The hardware independent timer structure and API to configure, initialize, and run timers.",
- "title": "hal_timer"
- },
- {
- "location": "/os/modules/hal/hal_timer/hal_timer/#description",
- "text": "The HAL timer structure is shown below. The user can declare as many of these structures as required. They are enqueued on a particular HW timer queue when the user calls the hal_timer_start or hal_timer_start_at API. The user must have called hal_timer_set_cb before starting a timer. NOTE: the user should not have to modify/examine the contents of this structure; the hal timer API should be used. struct hal_timer \n{\n void *bsp_timer ; /* Internal platform specific pointer */ \n hal_timer_cb cb_func ; /* Callback function */ \n void *cb_arg ; /* Callback argument */ \n uint32_t expiry ; /* Tick at which timer should expire */ \n TAILQ_ENTRY ( hal_timer ) link ; /* Queue linked list structure */ \n};",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_timer/hal_timer/#definition",
- "text": "hal_timer.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_timer/hal_timer/#examples",
- "text": "",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_uart/hal_uart/",
- "text": "hal_uart\n\n\nThe hardware independent UART interface for Mynewt.\n\n\nDescription\n\n\nContains the basic operations to send and receive data over a UART\n(Universal Asynchronous Receiver Transmitter). It also includes the API to apply settings such as speed, parity etc. to the UART. The UART port should be closed before any reconfiguring. \n\n\nDefinition\n\n\nhal_uart.h\n\n\nExamples\n\n\nThis example shows a user writing a character to the uart in blocking mode where the UART has to block until character has been sent.\n\n\n/* write to the console with blocking */\n{\n char *str = \nHello World!\n;\n char *ptr = str;\n\n while(*ptr) {\n hal_uart_blocking_tx(MY_UART, *ptr++);\n }\n hal_uart_blocking_tx(MY_UART, \n\\n\n);\n}",
- "title": "UART"
- },
- {
- "location": "/os/modules/hal/hal_uart/hal_uart/#hal_uart",
- "text": "The hardware independent UART interface for Mynewt.",
- "title": "hal_uart"
- },
- {
- "location": "/os/modules/hal/hal_uart/hal_uart/#description",
- "text": "Contains the basic operations to send and receive data over a UART\n(Universal Asynchronous Receiver Transmitter). It also includes the API to apply settings such as speed, parity etc. to the UART. The UART port should be closed before any reconfiguring.",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_uart/hal_uart/#definition",
- "text": "hal_uart.h",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_uart/hal_uart/#examples",
- "text": "This example shows a user writing a character to the uart in blocking mode where the UART has to block until character has been sent. /* write to the console with blocking */\n{\n char *str = Hello World! ;\n char *ptr = str;\n\n while(*ptr) {\n hal_uart_blocking_tx(MY_UART, *ptr++);\n }\n hal_uart_blocking_tx(MY_UART, \\n );\n}",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_watchdog/hal_watchdog/",
- "text": "hal_watchdog\n\n\nThe hardware independent interface to enable internal hardware watchdogs.\n\n\nDescription\n\n\nThe \nhal_watchdog_init\n interface can be used to set a recurring watchdog timer to fire no sooner than in 'expire_secs' seconds. \n\n\nint\n \nhal_watchdog_init\n(\nuint32_t\n \nexpire_msecs\n);\n\n\n\n\n\nWatchdog needs to be then started with a call to \nhal_watchdog_enable()\n.\nWatchdog should be tickled periodically with a frequency smaller than 'expire_secs' using \nhal_watchdog_tickle()\n.\n\n\nDefinition\n\n\nhal_watchdog\n\n\nExamples\n\n\nThe OS initializes and starts a watchdog timer and tickles it periodically to check that the OS is running properly. This can be seen in \n/kernel/os/src/os.c\n.",
- "title": "Watchdog"
- },
- {
- "location": "/os/modules/hal/hal_watchdog/hal_watchdog/#hal_watchdog",
- "text": "The hardware independent interface to enable internal hardware watchdogs.",
- "title": "hal_watchdog"
- },
- {
- "location": "/os/modules/hal/hal_watchdog/hal_watchdog/#description",
- "text": "The hal_watchdog_init interface can be used to set a recurring watchdog timer to fire no sooner than in 'expire_secs' seconds. int hal_watchdog_init ( uint32_t expire_msecs ); Watchdog needs to be then started with a call to hal_watchdog_enable() .\nWatchdog should be tickled periodically with a frequency smaller than 'expire_secs' using hal_watchdog_tickle() .",
- "title": "Description"
- },
- {
- "location": "/os/modules/hal/hal_watchdog/hal_watchdog/#definition",
- "text": "hal_watchdog",
- "title": "Definition"
- },
- {
- "location": "/os/modules/hal/hal_watchdog/hal_watchdog/#examples",
- "text": "The OS initializes and starts a watchdog timer and tickles it periodically to check that the OS is running properly. This can be seen in /kernel/os/src/os.c .",
- "title": "Examples"
- },
- {
- "location": "/os/modules/hal/hal_in_libraries/",
- "text": "Using HAL in Your Libraries\n\n\nThis page describes the recommended way to implement libraries that \nutilize HAL functionality.\n\n\nAn example of the GPIO HAL being used by a driver for a UART bitbanger that programs the start bit, data bits, and stop bit can be seen in \nhw/drivers/uart/uart_bitbang/src/uart_bitbang.c\n\n\nAn example of the flash HAL being used by a file sytem can be seen in \nfs/nffs/src/nffs_flash.c\n.",
- "title": "Using HAL"
- },
- {
- "location": "/os/modules/hal/hal_in_libraries/#using-hal-in-your-libraries",
- "text": "This page describes the recommended way to implement libraries that \nutilize HAL functionality. An example of the GPIO HAL being used by a driver for a UART bitbanger that programs the start bit, data bits, and stop bit can be seen in hw/drivers/uart/uart_bitbang/src/uart_bitbang.c An example of the flash HAL being used by a file sytem can be seen in fs/nffs/src/nffs_flash.c .",
- "title": "Using HAL in Your Libraries"
- },
- {
- "location": "/os/modules/hal/hal_creation/",
- "text": "Creating New HAL Interfaces\n\n\nHAL API\n\n\nA HAL always includes header file with function declarations \nfor the HAL functionality in \n/hw/hal/include/hal\n.\nThe first argument of all functions in the interface typically include the virtual \ndevice_id of the device you are controlling. \n\n\nFor example, in \nhal_gpio.h\n \nthe device enumeration is the first argument to most methods and called \npin\n.\n\n\n void hal_gpio_write(int pin, int val);\n\n\n\n\n\nThe device_id (in this case called \npin\n) is not a physical device \n(actual hardware pin), but a virtual pin which is defined by the \nimplementation of the HAL (and documented in the implementation of the HAL).",
- "title": "Creating HAL"
- },
- {
- "location": "/os/modules/hal/hal_creation/#creating-new-hal-interfaces",
- "text": "",
- "title": "Creating New HAL Interfaces"
- },
- {
- "location": "/os/modules/hal/hal_creation/#hal-api",
- "text": "A HAL always includes header file with function declarations \nfor the HAL functionality in /hw/hal/include/hal .\nThe first argument of all functions in the interface typically include the virtual \ndevice_id of the device you are controlling. For example, in hal_gpio.h \nthe device enumeration is the first argument to most methods and called pin . void hal_gpio_write(int pin, int val); The device_id (in this case called pin ) is not a physical device \n(actual hardware pin), but a virtual pin which is defined by the \nimplementation of the HAL (and documented in the implementation of the HAL).",
- "title": "HAL API"
- },
- {
- "location": "/os/modules/drivers/driver/",
- "text": "Drivers\n\n\nDescription\n\n\nDevice drivers in the Mynewt context includes libraries that interface with devices external to the CPU. These devices are connected to the CPU via standard peripherals such as SPI, GPIO, I2C etc. Device drivers leverage the base HAL services in Mynewt to provide friendly abstractions to application developers. \n\n\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| app |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| (n)drivers |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| HAL | BSP |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n\n\n\n\n\n\n\n\n\nThe Board Support Package (BSP) abstracts board specific configurations e.g. CPU frequency, input voltage, LED pins, on-chip flash map etc.\n\n\n\n\n\n\nThe Hardware Abstraction Layer (HAL) abstracts architecture-specific functionality. It initializes and enables components within a master processor. It is designed to be portable across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.). It includes code that initializes and manages access to components of the board such as board buses (I2C, PCI, PCMCIA, etc.), off-chip memory (controllers, level 2+ cache, Flash, etc.), and off-chip I/O (Ethernet, RS-232, display, mouse, etc.)\n\n\n\n\n\n\nThe driver sits atop the BSP and HAL. It abstracts the common modes of operation for each peripheral device connected via the standard interfaces to the processor. There may be multiple driver implementations of differing complexities for a particular peripheral device. For example, for an Analog to Digital Converter (ADC) peripheral you might have a simple driver that does blocking ADC reads and uses the HAL only. You might have a more complex driver that can deal with both internal and external ADCs, and has chip specific support for doing things like DMA\u2019ing ADC reads into a buffer and posting an event to a task every \u2019n\u2019 samples. The drivers are the ones that register with the kernel\u2019s power management APIs, and manage turning on and off peripherals and external chipsets, etc. The Mynewt core repository comes with a base set of drivers to help the user get started.\n\n\n\n\n\n\nGeneral design principles\n\n\n\n\n\n\nDevice drivers should have a consistent structure and unified interface whenever possible. For example, we have a top-level package, \u201cadc\u201d, which contains the interface for all ADC drivers, and then we have the individual implementation of the driver itself. The following source files point to this:\n\n\n\n\nhigh-level ADC API: \nhw/drivers/adc/include/adc/adc.h\n \n\n\nimplementation of ADC for STM32F4: \nhw/drivers/adc/adc_stm32f4/src/adc_stm32f4.c\n (As of the 1.0.0-beta release, ADC for nRF51 and nRF52 are available at an external \nrepo\n. They are expected to be pulled into the core repo on Apache Mynewt after the license terms are clarified.). The only exported call in this example is \nint stm32f4_adc_dev_init(struct os_dev *, void *)\n which is passed as a function pointer to \nos_dev_create()\n in \nhal_bsp.c\n, when the adc device is created.\n\n\n\n\n\n\n\n\nDevice drivers should be easy to use. In Mynewt, creating a device initializes it as well, making it readily available for the user to open, use (e.g. read, configure etc.) and close. Creating a device is simple using \nos_dev_create(struct os_dev *dev, char *name, uint8_t stage, uint8_t priority, os_dev_init_func_t od_init, void *arg)\n. The \nod_init\n function is defined within the appropriate driver directory e.g. \nstm32f4_adc_dev_init\n in \nhw/drivers/adc/adc_stm32f4/src/adc_stm32f4.c\n for the ADC device initialization function. \n\n\n\n\n\n\nThe implementation should allow for builds optimized for minimal memory usage. Additional functionality can be enabled by writing a more complex driver (usually based on the simple implementation included by default in the core repository) and optionally compiling the relevant packages in. Typically, only a basic driver that addresses a device\u2019s core functionality (covering ~90% of use cases) is included in the Mynewt core repository, thus keeping the footprint small.\n\n\n\n\n\n\nThe implementation should allow a user to be able to instantiate multiple devices of a certain kind. In the Mynewt environment the user can, for example, maintain separate contexts for multiple ADCs over different peripheral connections such as SPI, I2C etc. It is also possible for a user to use a single peripheral interface (e.g. SPI) to drive multiple devices (e.g. ADC), and in that case the device driver has to handle the proper synchronization of the various tasks. \n\n\n\n\n\n\nDevice drivers should be MCU independent. In Mynewt, device creation and operation functions are independent of the underlying MCU. \n\n\n\n\n\n\nDevice drivers should be able to offer high-level interfaces for generic operations common to a particular device group. An example of such a class or group of devices is a group for sensors with generic operations such as channel discovery, configure, and read values. The organization of the driver directory is work in progress - so we encourage you to hop on the dev@ mailing list and offer your insights!\n\n\n\n\n\n\nDevice drivers should be searchable. The plan is to have the newt tool offer a \nnewt pkg search\n capability. This is work in progress. You are welcome to join the conversation on the dev@ mailing list!\n\n\n\n\n\n\nExample\n\n\nThe Mynewt core repo includes an example of a driver using the HAL to provide extra functionality - the UART driver. It uses HAL GPIO and UART to provide multiple serial ports on the NRF52 (but allowed on other platforms too.)\n\n\nThe gist of the driver design is that there is an API for the driver (for use by applications), and then sub-packages to that driver that implement that driver API using the HAL and BSP APIs.\n\n\nImplemented drivers\n\n\nDrivers live under \nhw/drivers\n. The current list of supported drivers includes:\n\n\n\n\n\n\n\n\nDriver\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nadc\n\n\nTODO: ADC driver.\n\n\n\n\n\n\nflash\n\n\nSPI/I2C flash drivers.\n\n\n\n\n\n\nlwip\n\n\nTODO: LWIP.\n\n\n\n\n\n\nmmc\n\n\nMMC/SD card driver.\n\n\n\n\n\n\nnimble\n\n\nNIMBLE.\n\n\n\n\n\n\nsensors\n\n\nTODO: sensors.\n\n\n\n\n\n\nuart\n\n\nTODO: UART driver.",
- "title": "toc"
- },
- {
- "location": "/os/modules/drivers/driver/#drivers",
- "text": "",
- "title": "Drivers"
- },
- {
- "location": "/os/modules/drivers/driver/#description",
- "text": "Device drivers in the Mynewt context includes libraries that interface with devices external to the CPU. These devices are connected to the CPU via standard peripherals such as SPI, GPIO, I2C etc. Device drivers leverage the base HAL services in Mynewt to provide friendly abstractions to application developers. +\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| app |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| (n)drivers |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\n| HAL | BSP |\n+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014+ The Board Support Package (BSP) abstracts board specific configurations e.g. CPU frequency, input voltage, LED pins, on-chip flash map etc. The Hardware Abstraction Layer (HAL) abstracts architecture-specific functionality. It initializes and enables components within a master processor. It is designed to be portable across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's MK64F12 etc.). It includes code that initializes and manages access to components of the board such as board buses (I2C, PCI, PCMCIA, etc.), off-chip memory (controllers, level 2+ cache, Flash, etc.), and off-chip I/O (Ethernet, RS-232, display, mouse, etc.) The driver sits atop the BSP and HAL. It abstracts the common modes of operation for each peripheral device connected via the standard interfaces to the processor. There may be multiple driver implementations of differing complexities for a particular peripheral device. For example, for an Analog to Digital Converter (ADC) peripheral you might have a simple driver that does blocking ADC reads and uses the HAL only. You might have a more complex driver that can deal with both internal and external ADCs, and has chip specific support for doing things like DMA\u2019ing ADC reads into a buffer and posting an event to a task every \u2019n\u2019 samples. The drivers are the ones that register with the kernel\u2019s power management APIs, and manage turning on and off peripherals and external chipsets, etc. The Mynewt core repository comes with a base set of drivers to help the user get started.",
- "title": "Description"
- },
- {
- "location": "/os/modules/drivers/driver/#general-design-principles",
- "text": "Device drivers should have a consistent structure and unified interface whenever possible. For example, we have a top-level package, \u201cadc\u201d, which contains the interface for all ADC drivers, and then we have the individual implementation of the driver itself. The following source files point to this: high-level ADC API: hw/drivers/adc/include/adc/adc.h implementation of ADC for STM32F4: hw/drivers/adc/adc_stm32f4/src/adc_stm32f4.c (As of the 1.0.0-beta release, ADC for nRF51 and nRF52 are available at an external repo . They are expected to be pulled into the core repo on Apache Mynewt after the license terms are clarified.). The only exported call in this example is int stm32f4_adc_dev_init(struct os_dev *, void *) which is passed as a function pointer to os_dev_create() in hal_bsp.c , when the adc device is created. Device drivers should be easy to use. In Mynewt, creating a device initializes it as well, making it readily available for the user to open, use (e.g. read, configure etc.) and close. Creating a device is simple using os_dev_create(struct os_dev *dev, char *name, uint8_t stage, uint8_t priority, os_dev_init_func_t od_init, void *arg) . The od_init function is defined within the appropriate driver directory e.g. stm32f4_adc_dev_init in hw/drivers/adc/adc_stm32f4/src/adc_stm32f4.c for the ADC device initialization function. The implementation should allow for builds optimized for minimal memory usage. Additional functionality can be enabled by writing a more complex driver (usually based on the simple implementation included by default in the core repository) and optionally compiling the relevant packages in. Typically, only a basic driver that addresses a device\u2019s core functionality (covering ~90% of use cases) is included in the Mynewt core repository, thus keeping the footprint small. The implementation should allow a user to be able to instantiate multiple devices of a certain kind. In the Mynewt environment the user can, for example, maintain separate contexts for multiple ADCs over different peripheral connections such as SPI, I2C etc. It is also possible for a user to use a single peripheral interface (e.g. SPI) to drive multiple devices (e.g. ADC), and in that case the device driver has to handle the proper synchronization of the various tasks. Device drivers should be MCU independent. In Mynewt, device creation and operation functions are independent of the underlying MCU. Device drivers should be able to offer high-level interfaces for generic operations common to a particular device group. An example of such a class or group of devices is a group for sensors with generic operations such as channel discovery, configure, and read values. The organization of the driver directory is work in progress - so we encourage you to hop on the dev@ mailing list and offer your insights! Device drivers should be searchable. The plan is to have the newt tool offer a newt pkg search capability. This is work in progress. You are welcome to join the conversation on the dev@ mailing list!",
- "title": "General design principles"
- },
- {
- "location": "/os/modules/drivers/driver/#example",
- "text": "The Mynewt core repo includes an example of a driver using the HAL to provide extra functionality - the UART driver. It uses HAL GPIO and UART to provide multiple serial ports on the NRF52 (but allowed on other platforms too.) The gist of the driver design is that there is an API for the driver (for use by applications), and then sub-packages to that driver that implement that driver API using the HAL and BSP APIs.",
- "title": "Example"
- },
- {
- "location": "/os/modules/drivers/driver/#implemented-drivers",
- "text": "Drivers live under hw/drivers . The current list of supported drivers includes: Driver Description adc TODO: ADC driver. flash SPI/I2C flash drivers. lwip TODO: LWIP. mmc MMC/SD card driver. nimble NIMBLE. sensors TODO: sensors. uart TODO: UART driver.",
- "title": "Implemented drivers"
- },
- {
- "location": "/os/modules/drivers/flash/",
- "text": "flash\n\n\nThe flash driver subsystem is a work in progress which aims at supporting\ncommon external SPI/I2C flash/eeprom memory chips. This is equivalent\nto what Linux calls \nMTD\n for \nMemory Technology Devices\n.\n\n\nAt the moment the only \nflash\n device that is already supported is the\nAT45DBxxx SPI flash family with the \nat45db\n driver.\n\n\nThe flash driver aims for full compatibility with the \nhal_flash\n API,\nwhich means initialization and usage can be performed by any \nfs\n that\nsupports the \nhal_flash\n interface.\n\n\nInitialization\n\n\nTo be compatible with the standard \nhal_flash\n interface, the \nat45db\n driver\nembeds a \nstruct hal_flash\n to its own \nstruct at45db_dev\n. The whole \nat45db_dev\n\nstruct is shown below.\n\n\nstruct\n \nat45db_dev\n {\n \nstruct\n \nhal_flash\n \nhal\n;\n \nstruct\n \nhal_spi_settings\n \n*settings\n;\n \nint\n \nspi_num\n;\n \nvoid\n \n*spi_cfg\n; \n/** Low-level MCU SPI config */\n\n \nint\n \nss_pin\n;\n \nuint32_t\n \nbaudrate\n;\n \nuint16_t\n \npage_size\n; \n/** Page size to be used, valid: 512 and 528 */\n\n \nuint8_t\n \ndisable_auto_erase\n; \n/** Reads and writes auto-erase by default */\n\n};\n\n\n\n\n\nTo ease with initialization a helper function \nat45db_default_config\n was added.\nIt returns an already initialized \nstruct at45db_dev\n leaving the user with just\nhaving to provide the SPI related config.\n\n\nTo initialize the device, pass the \nat45db_dev\n struct to \nat45db_init\n.\n\n\nint\n \nat45db_init\n(\nconst\n \nstruct\n \nhal_flash\n \n*dev\n);\n\n\n\n\n\nFor low-level access to the device the following functions are provided:\n\n\nint\n \nat45db_read\n(\nconst\n \nstruct\n \nhal_flash\n \n*dev\n, \nuint32_t\n \naddr\n, \nvoid\n \n*buf\n,\n \nuint32_t\n \nlen\n);\n\nint\n \nat45db_write\n(\nconst\n \nstruct\n \nhal_flash\n \n*dev\n, \nuint32_t\n \naddr\n, \nconst\n \nvoid\n \n*buf\n,\n \nuint32_t\n \nlen\n);\n\nint\n \nat45db_erase_sector\n(\nconst\n \nstruct\n \nhal_flash\n \n*dev\n, \nuint32_t\n \nsector_address\n);\n\nint\n \nat45db_sector_info\n(\nconst\n \nstruct\n \nhal_flash\n \n*dev\n, \nint\n \nidx\n, \nuint32_t\n \n*address\n,\n \nuint32_t\n \n*sz\n);\n\n\n\n\n\nAlso, \nnffs\n is able to run on the device due to the fact that standard \nhal_flash\n\ninterface compatibility is provided. Due to current limitations of \nnffs\n, it can\nonly run on \nat45db\n if the internal flash of the MCU is not being used.\n\n\nDependencies\n\n\nTo include the \nat45db\n driver on a project, just include it as a dependency in your\npkg.yml:\n\n\npkg.deps:\n - hw/drivers/flash/at45db\n\n\n\n\n\nHeader file\n\n\nThe \nat45db\n SPI flash follows the standard \nhal_flash\n interface but requires\nthat a special struct \n\n\n#include\n \nat45db/at45db.h\n\n\n\n\n\n\nExample\n\n\nThis following examples assume that the \nat45db\n is being used on a STM32F4 MCU.\n\n\nstatic\n \nconst\n \nint\n \nSPI_SS_PIN\n \n=\n \nMCU_GPIO_PORTA\n(\n4\n);\n\nstatic\n \nconst\n \nint\n \nSPI_SCK_PIN\n \n=\n \nMCU_GPIO_PORTA\n(\n5\n);\n\nstatic\n \nconst\n \nint\n \nSPI_MISO_PIN\n \n=\n \nMCU_GPIO_PORTA\n(\n6\n);\n\nstatic\n \nconst\n \nint\n \nSPI_MOSI_PIN\n \n=\n \nMCU_GPIO_PORTA\n(\n7\n);\n\n\nstruct\n \nstm32f4_hal_spi_cfg\n \nspi_cfg\n \n=\n {\n .\nss_pin\n \n=\n \nSPI_SS_PIN\n,\n .\nsck_pin\n \n=\n \nSPI_SCK_PIN\n,\n .\nmiso_pin\n \n=\n \nSPI_MISO_PIN\n,\n .\nmosi_pin\n \n=\n \nSPI_MOSI_PIN\n,\n .\nirq_prio\n \n=\n \n2\n\n};\n\n\nstruct\n \nat45db_dev\n \n*my_at45db_dev\n \n=\n \nNULL\n;\n\n\nmy_at45db_dev\n \n=\n \nat45db_default_config\n();\n\nmy_at45db_dev-\nspi_num\n \n=\n \n0\n;\n\nmy_at45db_dev-\nspi_cfg\n \n=\n \nspi_cfg\n;\n\nmy_at45db_dev-\nss_pin\n \n=\n \nspi_cfg\n.\nss_pin\n;\n\n\nrc\n \n=\n \nat45db_init\n((\nstruct\n \nhal_flash\n \n*\n) \nmy_at45db_dev\n);\n\nif\n (\nrc\n) {\n \n/* XXX: error handling */\n\n}\n\n\n\n\n\nThe enable \nnffs\n to run on the \nat45db\n, the \nflash_id\n 0 needs to map to\nprovide a mapping from 0 to this struct.\n\n\nconst\n \nstruct\n \nhal_flash\n \n*\n\n\nhal_bsp_flash_dev\n(\nuint8_t\n \nid\n)\n{\n \nif\n (\nid\n \n!=\n \n0\n) {\n \nreturn\n \nNULL\n;\n }\n \nreturn\n \nmy_at45db_dev\n;\n}",
- "title": "flash"
- },
- {
- "location": "/os/modules/drivers/flash/#flash",
- "text": "The flash driver subsystem is a work in progress which aims at supporting\ncommon external SPI/I2C flash/eeprom memory chips. This is equivalent\nto what Linux calls MTD for Memory Technology Devices . At the moment the only flash device that is already supported is the\nAT45DBxxx SPI flash family with the at45db driver. The flash driver aims for full compatibility with the hal_flash API,\nwhich means initialization and usage can be performed by any fs that\nsupports the hal_flash interface.",
- "title": "flash"
- },
- {
- "location": "/os/modules/drivers/flash/#initialization",
- "text": "To be compatible with the standard hal_flash interface, the at45db driver\nembeds a struct hal_flash to its own struct at45db_dev . The whole at45db_dev \nstruct is shown below. struct at45db_dev {\n struct hal_flash hal ;\n struct hal_spi_settings *settings ;\n int spi_num ;\n void *spi_cfg ; /** Low-level MCU SPI config */ \n int ss_pin ;\n uint32_t baudrate ;\n uint16_t page_size ; /** Page size to be used, valid: 512 and 528 */ \n uint8_t disable_auto_erase ; /** Reads and writes auto-erase by default */ \n}; To ease with initialization a helper function at45db_default_config was added.\nIt returns an already initialized struct at45db_dev leaving the user with just\nhaving to provide the SPI related config. To initialize the device, pass the at45db_dev struct to at45db_init . int at45db_init ( const struct hal_flash *dev ); For low-level access to the device the following functions are provided: int at45db_read ( const struct hal_flash *dev , uint32_t addr , void *buf ,\n uint32_t len ); int at45db_write ( const struct hal_flash *dev , uint32_t addr , const void *buf ,\n uint32_t len ); int at45db_erase_sector ( const struct hal_flash *dev , uint32_t sector_address ); int at45db_sector_info ( const struct hal_flash *dev , int idx , uint32_t *address ,\n uint32_t *sz ); Also, nffs is able to run on the device due to the fact that standard hal_flash \ninterface compatibility is provided. Due to current limitations of nffs , it can\nonly run on at45db if the internal flash of the MCU is not being used.",
- "title": "Initialization"
- },
- {
- "location": "/os/modules/drivers/flash/#dependencies",
- "text": "To include the at45db driver on a project, just include it as a dependency in your\npkg.yml: pkg.deps:\n - hw/drivers/flash/at45db",
- "title": "Dependencies"
- },
- {
- "location": "/os/modules/drivers/flash/#header-file",
- "text": "The at45db SPI flash follows the standard hal_flash interface but requires\nthat a special struct #include at45db/at45db.h",
- "title": "Header file"
- },
- {
- "location": "/os/modules/drivers/flash/#example",
- "text": "This following examples assume that the at45db is being used on a STM32F4 MCU. static const int SPI_SS_PIN = MCU_GPIO_PORTA ( 4 ); static const int SPI_SCK_PIN = MCU_GPIO_PORTA ( 5 ); static const int SPI_MISO_PIN = MCU_GPIO_PORTA ( 6 ); static const int SPI_MOSI_PIN = MCU_GPIO_PORTA ( 7 ); struct stm32f4_hal_spi_cfg spi_cfg = {\n . ss_pin = SPI_SS_PIN ,\n . sck_pin = SPI_SCK_PIN ,\n . miso_pin = SPI_MISO_PIN ,\n . mosi_pin = SPI_MOSI_PIN ,\n . irq_prio = 2 \n}; struct at45db_dev *my_at45db_dev = NULL ; my_at45db_dev = at45db_default_config (); my_at45db_dev- spi_num = 0 ; my_at45db_dev- spi_cfg = spi_cfg ; my_at45db_dev- ss_pin = spi_cfg . ss_pin ; rc = at45db_init (( struct hal_flash * ) my_at45db_dev ); if ( rc ) {\n /* XXX: error handling */ \n} The enable nffs to run on the at45db , the flash_id 0 needs to map to\nprovide a mapping from 0 to this struct. const struct hal_flash * hal_bsp_flash_dev ( uint8_t id )\n{\n if ( id != 0 ) {\n return NULL ;\n }\n return my_at45db_dev ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/drivers/mmc/",
- "text": "mmc\n\n\nThe MMC driver provides support for SPI based MMC/SDcard interfaces. It exports\na \ndisk_ops\n struct that can be used by any FS. Currently only \nfatfs\n can run\nover MMC.\n\n\nInitialization\n\n\nint\n \nmmc_init\n(\nint\n \nspi_num\n, \nvoid\n \n*spi_cfg\n, \nint\n \nss_pin\n)\n\n\n\n\n\nInitializes the mmc driver to be used by a FS.\n\n\nMMC uses the \nhal_gpio\n interface to access the SPI \nss_pin\n and the \nhal_spi\n\ninterface for the communication with the card. \nspi_cfg\n must be a hw dependent\nstructure used by \nhal_spi_init\n to initialize the SPI subsystem.\n\n\nDependencies\n\n\nTo include the \nmmc\n driver on a project, just include it as a dependency in your\npkg.yml:\n\n\npkg.deps:\n - hw/drivers/mmc\n\n\n\n\n\nReturned values\n\n\nMMC functions return one of the following status codes:\n\n\n\n\n\n\n\n\nReturn code\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nMMC_OK\n\n\nSuccess.\n\n\n\n\n\n\nMMC_CARD_ERROR\n\n\nGeneral failure on the card.\n\n\n\n\n\n\nMMC_READ_ERROR\n\n\nError reading from the card.\n\n\n\n\n\n\nMMC_WRITE_ERROR\n\n\nError writing to the card.\n\n\n\n\n\n\nMMC_TIMEOUT\n\n\nTimed out waiting for the execution of a command.\n\n\n\n\n\n\nMMC_PARAM_ERROR\n\n\nAn invalid parameter was given to a function.\n\n\n\n\n\n\nMMC_CRC_ERROR\n\n\nCRC error reading card.\n\n\n\n\n\n\nMMC_DEVICE_ERROR\n\n\nTried to use an invalid device.\n\n\n\n\n\n\nMMC_RESPONSE_ERROR\n\n\nA command received an invalid response.\n\n\n\n\n\n\nMMC_VOLTAGE_ERROR\n\n\nThe interface doesn't support the requested voltage.\n\n\n\n\n\n\nMMC_INVALID_COMMAND\n\n\nThe interface haven't accepted some command.\n\n\n\n\n\n\nMMC_ERASE_ERROR\n\n\nError erasing the current card.\n\n\n\n\n\n\nMMC_ADDR_ERROR\n\n\nTried to access an invalid address.\n\n\n\n\n\n\n\n\nHeader file\n\n\n#include\n \nmmc/mmc.h\n\n\n\n\n\n\nExample\n\n\nThis example runs on the STM32F4-Discovery and prints out a listing of\nthe root directory on the currently installed card.\n\n\n// NOTE: error handling removed for clarity!\n\n\n\nstruct\n \nstm32f4_hal_spi_cfg\n \nspi_cfg\n \n=\n {\n .\nss_pin\n \n=\n \nSPI_SS_PIN\n,\n .\nsck_pin\n \n=\n \nSPI_SCK_PIN\n,\n .\nmiso_pin\n \n=\n \nSPI_MISO_PIN\n,\n .\nmosi_pin\n \n=\n \nSPI_MOSI_PIN\n,\n .\nirq_prio\n \n=\n \n2\n\n};\n\n\nmmc_init\n(\n0\n, \nspi_cfg\n, \nspi_cfg\n.\nss_pin\n);\n\ndisk_register\n(\nmmc0\n, \nfatfs\n, \nmmc_ops\n);\n\n\nfs_opendir\n(\nmmc0:/\n, \ndir\n);\n\n\nwhile\n (\n1\n) {\n \nrc\n \n=\n \nfs_readdir\n(\ndir\n, \ndirent\n);\n \nif\n (\nrc\n \n==\n \nFS_ENOENT\n) {\n \nbreak\n;\n }\n\n \nfs_dirent_name\n(\ndirent\n, \nsizeof\n(\nout_name\n), \nout_name\n, \nu8_len\n);\n \nprintf\n(\n%s\\n\n, \nout_name\n);\n}\n\n\nfs_closedir\n(\ndir\n);",
- "title": "mmc"
- },
- {
- "location": "/os/modules/drivers/mmc/#mmc",
- "text": "The MMC driver provides support for SPI based MMC/SDcard interfaces. It exports\na disk_ops struct that can be used by any FS. Currently only fatfs can run\nover MMC.",
- "title": "mmc"
- },
- {
- "location": "/os/modules/drivers/mmc/#initialization",
- "text": "int mmc_init ( int spi_num , void *spi_cfg , int ss_pin ) Initializes the mmc driver to be used by a FS. MMC uses the hal_gpio interface to access the SPI ss_pin and the hal_spi \ninterface for the communication with the card. spi_cfg must be a hw dependent\nstructure used by hal_spi_init to initialize the SPI subsystem.",
- "title": "Initialization"
- },
- {
- "location": "/os/modules/drivers/mmc/#dependencies",
- "text": "To include the mmc driver on a project, just include it as a dependency in your\npkg.yml: pkg.deps:\n - hw/drivers/mmc",
- "title": "Dependencies"
- },
- {
- "location": "/os/modules/drivers/mmc/#returned-values",
- "text": "MMC functions return one of the following status codes: Return code Description MMC_OK Success. MMC_CARD_ERROR General failure on the card. MMC_READ_ERROR Error reading from the card. MMC_WRITE_ERROR Error writing to the card. MMC_TIMEOUT Timed out waiting for the execution of a command. MMC_PARAM_ERROR An invalid parameter was given to a function. MMC_CRC_ERROR CRC error reading card. MMC_DEVICE_ERROR Tried to use an invalid device. MMC_RESPONSE_ERROR A command received an invalid response. MMC_VOLTAGE_ERROR The interface doesn't support the requested voltage. MMC_INVALID_COMMAND The interface haven't accepted some command. MMC_ERASE_ERROR Error erasing the current card. MMC_ADDR_ERROR Tried to access an invalid address.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/drivers/mmc/#header-file",
- "text": "#include mmc/mmc.h",
- "title": "Header file"
- },
- {
- "location": "/network/ble/ble_intro/",
- "text": "BLE Introduction\n\n\nApache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack fully compliant with BLE 4.2 specifications. It is called NimBLE. \n\n\nBLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.\n\n\n\n\nFeature Support\n\n\nNimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT).\n\n\n\n\nLE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders\n\n\nLE Secure Connections featuring FIPS-compliant algorithms.\n\n\nLE Data Length Extension for higher throughput\n\n\nComing Soon\n: Assigning an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP)\n\n\n\n\nComponents\n\n\nA Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents:\n\n\n\n\n\n\nController\n\n\n\n\nPhysical Layer\n: adaptive frequency-hopping Gaussian Frequency Shift Keying (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing.\n\n\nLink Layer\n: with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time\n\n\n\n\n\n\n\n\nHost\n\n\n\n\nLogical Link Control and Adaptation Protocol (L2CAP)\n: provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. \n\n\nSecurity Manager (SM)\n: uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication \n\n\nAttribute protocol (ATT)\n: allows a device (\nServer\n) to expose certain pieces of data, known as \nAttributes\n, to another device (\nClient\n)\n\n\nGeneric Attribute Profile (GATT)\n: a framework for using the ATT protocol to exchange attributes encapsulated as \nCharacteristics\n or \nServices\n \n\n\nGeneric Access Profile (GAP)\n: a base profile which all Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. \n\n\nHost Controller Interface (HCI)\n: the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB.\n\n\n\n\n\n\n\n\nSubsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and things to consider while designing a NimBLE app.\n\n\n\n\nExample NimBLE projects\n\n\nMynewt comes with several built-in projects or applications using NimBLE. These allow users to try out NimBLE, understand how to use available services, and build their own applications using one or more of the examples as seed.\n\n\n\n\n\n\nbletiny\n : A simple shell application which provides a basic interface to the host-side of the BLE stack. Supported operations include GAP, GATT, and L2CAP.\n\n\n\n\n\n\nbleprph\n: A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It supports a maximum of one connection.\n\n\n\n\n\n\nblecent\n: A basic central device with no user interface. This application scans for a peripheral that supports the alert notification service (ANS). Upon discovering such a peripheral, blecent connects and performs the following actions:\n\n\n\n\nReads the ANS Supported New Alert Category characteristic.\n\n\nWrites the ANS Alert Notification Control Point characteristic.\n\n\nSubscribes to notifications for the ANS Unread Alert Status characteristic.\n\n\n\n\n\n\n\n\nblehci\n: Implements a BLE controller-only application. A separate host-only implementation, such as Linux's BlueZ, can interface with this application via HCI over UART.\n\n\n\n\n\n\nbleuart\n: Implements a simple BLE peripheral that supports the Nordic\n\nUART / Serial Port Emulation service",
- "title": "nimBLE"
- },
- {
- "location": "/network/ble/ble_intro/#ble-introduction",
- "text": "Apache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack fully compliant with BLE 4.2 specifications. It is called NimBLE. BLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.",
- "title": "BLE Introduction"
- },
- {
- "location": "/network/ble/ble_intro/#feature-support",
- "text": "NimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT). LE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders LE Secure Connections featuring FIPS-compliant algorithms. LE Data Length Extension for higher throughput Coming Soon : Assigning an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP)",
- "title": "Feature Support"
- },
- {
- "location": "/network/ble/ble_intro/#components",
- "text": "A Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents: Controller Physical Layer : adaptive frequency-hopping Gaussian Frequency Shift Keying (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing. Link Layer : with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time Host Logical Link Control and Adaptation Protocol (L2CAP) : provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. Security Manager (SM) : uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication Attribute protocol (ATT) : allows a device ( Server ) to expose certain pieces of data, known as Attributes , to another device ( Client ) Generic Attribute Profile (GATT) : a framework for using the ATT protocol to exchange attributes encapsulated as Characteristics or Services Generic Access Profile (GAP) : a base profile which all Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. Host Controller Interface (HCI) : the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB. Subsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and things to consider while designing a NimBLE app.",
- "title": "Components"
- },
- {
- "location": "/network/ble/ble_intro/#example-nimble-projects",
- "text": "Mynewt comes with several built-in projects or applications using NimBLE. These allow users to try out NimBLE, understand how to use available services, and build their own applications using one or more of the examples as seed. bletiny : A simple shell application which provides a basic interface to the host-side of the BLE stack. Supported operations include GAP, GATT, and L2CAP. bleprph : A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It supports a maximum of one connection. blecent : A basic central device with no user interface. This application scans for a peripheral that supports the alert notification service (ANS). Upon discovering such a peripheral, blecent connects and performs the following actions: Reads the ANS Supported New Alert Category characteristic. Writes the ANS Alert Notification Control Point characteristic. Subscribes to notifications for the ANS Unread Alert Status characteristic. blehci : Implements a BLE controller-only application. A separate host-only implementation, such as Linux's BlueZ, can interface with this application via HCI over UART. bleuart : Implements a simple BLE peripheral that supports the Nordic UART / Serial Port Emulation service",
- "title": "Example NimBLE projects"
- },
- {
- "location": "/os/modules/testutil/testutil/",
- "text": "testutil\n\n\nThe testutil package is a test framework that provides facilities for specifying test cases and recording test results.\n\n\nYou would use it to build regression tests for your library.\n\n\nDescription\n\n\nA package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its \nsrc/test\n directory. For example, the nffs package's test code is located in the following directory:\n\n\n * fs/nffs/src/test/\n\n\n\n\n\nThis directory contains the source and header files that implement the nffs test code.\n\n\nThe test code has access to all the header files in the following directories:\n\n\n * src\n * src/arch/\ntarget-arch\n\n * include\n * src/test\n * src/test/arch/\ntarget-arch\n\n * include directories of all package dependencies\n\n\n\n\n\nPackage test code typically depends on the testutil package, described later in this document.\n\n\nSome test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory.\n\n\nWhile building the test code (i.e., when the \ntest\n identity is specified), the newt tool defines the \nTEST\n macro. This macro is defined during compilation of all C source files in all projects and packages.\n\n\nTests are structured according to the following hierarchy:\n\n\n [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case]\n\n\n\n\n\nI.e., a test consists of test suites, and a test suite consists of test cases.\n\n\nThe test code uses testutil to define test suites and test cases.\n\n\nRegression test can then be executed using 'newt target test' command, or by including a call to your test suite from \nproject/test/src/test.c\n.\n\n\nExample\n\n\nThis Tutorial\n shows how to create a test suite\nfor a Mynewt package.\n\n\nData structures\n\n\nstruct tu_config {\n int tc_print_results;\n int tc_system_assert;\n\n tu_case_init_fn_t *tc_case_init_cb;\n void *tc_case_init_arg;\n\n tu_case_report_fn_t *tc_case_fail_cb;\n void *tc_case_fail_arg;\n\n tu_case_report_fn_t *tc_case_pass_cb;\n void *tc_case_pass_arg;\n\n tu_suite_init_fn_t *tc_suite_init_cb;\n void *tc_suite_init_arg;\n\n tu_restart_fn_t *tc_restart_cb;\n void *tc_restart_arg;\n};\nextern struct tu_config tu_config;\n\n\n\n\n\nThe global \ntu_config\n struct contains all the testutil package's settings.\nThis should be populated before \ntu_init()\n is called.\n\n\nList of Functions\n\n\n\n\nThe functions, and macros available in \ntestutil\n are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntu_init\n\n\nInitializes the test framework according to the contents of the tu_config struct.\n\n\n\n\n\n\nTEST_ASSERT\n\n\nAsserts that the specified condition is true.\n\n\n\n\n\n\nTEST_PASS\n\n\nReports a success result for the current test.\n\n\n\n\n\n\nTEST_SUITE\n\n\nDeclares a test suite function.\n\n\n\n\n\n\nTEST_CASE\n\n\nDefines a test case function.\n\n\n\n\n\n\nTEST_CASE_DECL\n\n\nDeclares a test case function. his is only required if the test case function exists in a different file than the test suite.\n\n\n\n\n\n\ntu_restart\n\n\nThis function is used when a system reset is necessary to proceed with testing.",
- "title": "toc"
- },
- {
- "location": "/os/modules/testutil/testutil/#testutil",
- "text": "The testutil package is a test framework that provides facilities for specifying test cases and recording test results. You would use it to build regression tests for your library.",
- "title": "testutil"
- },
- {
- "location": "/os/modules/testutil/testutil/#description",
- "text": "A package may optionally contain a set of test cases. Test cases are not normally compiled and linked when a package is built; they are only included\nwhen the \"test\" identity is specified. All of a package's test code goes in its src/test directory. For example, the nffs package's test code is located in the following directory: * fs/nffs/src/test/ This directory contains the source and header files that implement the nffs test code. The test code has access to all the header files in the following directories: * src\n * src/arch/ target-arch \n * include\n * src/test\n * src/test/arch/ target-arch \n * include directories of all package dependencies Package test code typically depends on the testutil package, described later in this document. Some test cases or test initialization code may be platform-specific. In such cases, the platform-specific function definitions are placed in arch subdirectories within the package test directory. While building the test code (i.e., when the test identity is specified), the newt tool defines the TEST macro. This macro is defined during compilation of all C source files in all projects and packages. Tests are structured according to the following hierarchy: [test]\n / \\\n [suite] [suite]\n / \\ / \\\n [case] [case] [case] [case] I.e., a test consists of test suites, and a test suite consists of test cases. The test code uses testutil to define test suites and test cases. Regression test can then be executed using 'newt target test' command, or by including a call to your test suite from project/test/src/test.c .",
- "title": "Description"
- },
- {
- "location": "/os/modules/testutil/testutil/#example",
- "text": "This Tutorial shows how to create a test suite\nfor a Mynewt package.",
- "title": "Example"
- },
- {
- "location": "/os/modules/testutil/testutil/#data-structures",
- "text": "struct tu_config {\n int tc_print_results;\n int tc_system_assert;\n\n tu_case_init_fn_t *tc_case_init_cb;\n void *tc_case_init_arg;\n\n tu_case_report_fn_t *tc_case_fail_cb;\n void *tc_case_fail_arg;\n\n tu_case_report_fn_t *tc_case_pass_cb;\n void *tc_case_pass_arg;\n\n tu_suite_init_fn_t *tc_suite_init_cb;\n void *tc_suite_init_arg;\n\n tu_restart_fn_t *tc_restart_cb;\n void *tc_restart_arg;\n};\nextern struct tu_config tu_config; The global tu_config struct contains all the testutil package's settings.\nThis should be populated before tu_init() is called.",
- "title": "Data structures"
- },
- {
- "location": "/os/modules/testutil/testutil/#list-of-functions",
- "text": "The functions, and macros available in testutil are: Function Description tu_init Initializes the test framework according to the contents of the tu_config struct. TEST_ASSERT Asserts that the specified condition is true. TEST_PASS Reports a success result for the current test. TEST_SUITE Declares a test suite function. TEST_CASE Defines a test case function. TEST_CASE_DECL Declares a test case function. his is only required if the test case function exists in a different file than the test suite. tu_restart This function is used when a system reset is necessary to proceed with testing.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/testutil/tu_init/",
- "text": "tu_init\n\n\nint tu_init(void)\n\n\n\n\n\nInitializes the test framework according to the contents of the \ntu_config\n struct. This function must be called before any tests are run.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nExample\n\n\nHere's an example of stand-alone code which allows the user to execute regression tests for sys/config package only.\n\n\n#ifdef PKG_TEST\n\nint\nmain(int argc, char **argv)\n{\n tu_config.tc_print_results = 1;\n tu_init();\n\n conf_init();\n config_test_all();\n\n return tu_any_failed;\n}\n\n#endif",
- "title": "tu_init"
- },
- {
- "location": "/os/modules/testutil/tu_init/#tu_init",
- "text": "int tu_init(void) Initializes the test framework according to the contents of the tu_config struct. This function must be called before any tests are run.",
- "title": " tu_init"
- },
- {
- "location": "/os/modules/testutil/tu_init/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/tu_init/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/tu_init/#example",
- "text": "Here's an example of stand-alone code which allows the user to execute regression tests for sys/config package only. #ifdef PKG_TEST\n\nint\nmain(int argc, char **argv)\n{\n tu_config.tc_print_results = 1;\n tu_init();\n\n conf_init();\n config_test_all();\n\n return tu_any_failed;\n}\n\n#endif",
- "title": "Example"
- },
- {
- "location": "/os/modules/testutil/test_assert/",
- "text": "TEST_ASSERT\n\n\nTEST_ASSERT(expression, fail_msg, ...)\n\n\n\n\n\nTEST_ASSERT_FATAL(expression, fail_msg, ...)\n\n\n\n\n\nAsserts that the specified condition is true. If the expression is true, nothing gets reported. \nfail_msg\n will be printed out if the expression is false. The expression argument is mandatory; the rest are optional. The fail_msg argument is a printf format string which specifies how the remaining arguments are parsed.\n\n\nTEST_ASSERT_FATAL()\n causes the current test case to be aborted, if expression fails.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nexpression\n\n\nCondition being tested. If it fails, test is considered a failure, and a message is printed out.\n\n\n\n\n\n\nfail_msg\n\n\nPointer to C string that contains a format string that follows the same specifications as format in printf.\n\n\n\n\n\n\n...\n\n\nDepending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in \n in stdarg.h.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nWhile \nconsole_printf\n, with its well understood formatting options in C, is more convenient and easy on the eyes than the raw output of \nconsole_write\n, the associated code size is considerably larger.\n\n\nExample\n\n\nExample #1:\n\n\nTEST_CASE(config_test_insert)\n{\n int rc;\n\n rc = conf_register(\nconfig_test_handler);\n TEST_ASSERT(rc == 0);\n}\n\n\n\n\n\nExample #2:\n\n\nTEST_CASE(nffs_test_unlink)\n{\n int rc;\n\n ....\n\n rc = nffs_format(nffs_area_descs);\n TEST_ASSERT_FATAL(rc == 0);\n\n ....\n}\n\n\n\n\n\nExample #3:\n\n\nstatic int \ncbmem_test_case_1_walk(struct cbmem *cbmem, struct cbmem_entry_hdr *hdr, \n void *arg)\n{\n ....\n\n rc = cbmem_read(cbmem, hdr, \nactual, 0, sizeof(actual));\n TEST_ASSERT_FATAL(rc == 1, \nCouldn\nt read 1 byte from cbmem\n);\n TEST_ASSERT_FATAL(actual == expected, \n \nActual doesn\nt equal expected (%d = %d)\n, actual, expected);\n\n ....\n}",
- "title": "TEST_ASSERT"
- },
- {
- "location": "/os/modules/testutil/test_assert/#test_assert",
- "text": "TEST_ASSERT(expression, fail_msg, ...) TEST_ASSERT_FATAL(expression, fail_msg, ...) Asserts that the specified condition is true. If the expression is true, nothing gets reported. fail_msg will be printed out if the expression is false. The expression argument is mandatory; the rest are optional. The fail_msg argument is a printf format string which specifies how the remaining arguments are parsed. TEST_ASSERT_FATAL() causes the current test case to be aborted, if expression fails.",
- "title": " TEST_ASSERT"
- },
- {
- "location": "/os/modules/testutil/test_assert/#arguments",
- "text": "Arguments Description expression Condition being tested. If it fails, test is considered a failure, and a message is printed out. fail_msg Pointer to C string that contains a format string that follows the same specifications as format in printf. ... Depending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in in stdarg.h.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/test_assert/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/test_assert/#notes",
- "text": "While console_printf , with its well understood formatting options in C, is more convenient and easy on the eyes than the raw output of console_write , the associated code size is considerably larger.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/testutil/test_assert/#example",
- "text": "Example #1: TEST_CASE(config_test_insert)\n{\n int rc;\n\n rc = conf_register( config_test_handler);\n TEST_ASSERT(rc == 0);\n} Example #2: TEST_CASE(nffs_test_unlink)\n{\n int rc;\n\n ....\n\n rc = nffs_format(nffs_area_descs);\n TEST_ASSERT_FATAL(rc == 0);\n\n ....\n} Example #3: static int \ncbmem_test_case_1_walk(struct cbmem *cbmem, struct cbmem_entry_hdr *hdr, \n void *arg)\n{\n ....\n\n rc = cbmem_read(cbmem, hdr, actual, 0, sizeof(actual));\n TEST_ASSERT_FATAL(rc == 1, Couldn t read 1 byte from cbmem );\n TEST_ASSERT_FATAL(actual == expected, \n Actual doesn t equal expected (%d = %d) , actual, expected);\n\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/testutil/test_pass/",
- "text": "TEST_PASS \n\n\nTEST_PASS(msg, ...)\n\n\n\n\n\nReports a success result for the current test. This function is not normally needed, as all successful tests automatically write an empty pass result at completion. It is only needed when the success result report should contain text. The msg argument is a printf format string\n which specifies how the remaining arguments are parsed. The result file\n produced by this function contains the following text:\n\n\n |\nfile\n:\nline-number\n| manual pass\n \nmsg\n\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmsg\n\n\nThis is a printf format string which specifies how the remaining arguments are parsed\n\n\n\n\n\n\n...\n\n\nDepending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in \n in stdarg.h.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nAfter this function is called, the remainder of the test case is not executed.",
- "title": "TEST_PASS"
- },
- {
- "location": "/os/modules/testutil/test_pass/#test_pass",
- "text": "TEST_PASS(msg, ...) Reports a success result for the current test. This function is not normally needed, as all successful tests automatically write an empty pass result at completion. It is only needed when the success result report should contain text. The msg argument is a printf format string\n which specifies how the remaining arguments are parsed. The result file\n produced by this function contains the following text: | file : line-number | manual pass\n msg",
- "title": " TEST_PASS "
- },
- {
- "location": "/os/modules/testutil/test_pass/#arguments",
- "text": "Arguments Description msg This is a printf format string which specifies how the remaining arguments are parsed ... Depending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in in stdarg.h.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/test_pass/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/test_pass/#notes",
- "text": "After this function is called, the remainder of the test case is not executed.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/testutil/test_suite/",
- "text": "TEST_SUITE \n\n\nTEST_SUITE(test_suite_name)\n\n\n\n\n\nDeclares a test suite function with the following type \nint test_suite_name(void)\n. This can then be called from either \nproject/test\n, or from main routine for package specific regression test.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntest_suite_name\n\n\nUsed as the function name for this test suite.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturn value is 0 if the test suite passed; nonzero if it failed. Generally, the return code is not used. It is expected that the individual test cases will pass/fail with tests done using \nTEST_ASSERT()\n.\n\n\nExample\n\n\nTEST_SUITE(os_sem_test_suite)\n{\n os_sem_test_basic();\n os_sem_test_case_1();\n os_sem_test_case_2();\n os_sem_test_case_3();\n os_sem_test_case_4();\n}",
- "title": "TEST_SUITE"
- },
- {
- "location": "/os/modules/testutil/test_suite/#test_suite",
- "text": "TEST_SUITE(test_suite_name) Declares a test suite function with the following type int test_suite_name(void) . This can then be called from either project/test , or from main routine for package specific regression test.",
- "title": " TEST_SUITE "
- },
- {
- "location": "/os/modules/testutil/test_suite/#arguments",
- "text": "Arguments Description test_suite_name Used as the function name for this test suite.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/test_suite/#returned-values",
- "text": "Return value is 0 if the test suite passed; nonzero if it failed. Generally, the return code is not used. It is expected that the individual test cases will pass/fail with tests done using TEST_ASSERT() .",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/test_suite/#example",
- "text": "TEST_SUITE(os_sem_test_suite)\n{\n os_sem_test_basic();\n os_sem_test_case_1();\n os_sem_test_case_2();\n os_sem_test_case_3();\n os_sem_test_case_4();\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/testutil/test_case/",
- "text": "TEST_CASE \n\n\nTEST_CASE(test_case_name)\n\n\n\n\n\nDefines a test case function with the following type \nint test_case_name(void)\n. This can then be called from regression test's \nTEST_SUITE()\n function.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntest_case_name\n\n\nUsed as the function name for this test case.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturn value is 0 if the test case passed; nonzero if it failed. Generally, the return code is not used. It is expected that the case will pass/fail with tests done using \nTEST_ASSERT()\n.\n\n\nExample\n\n\nTEST_CASE(config_test_insert)\n{\n ....\n}",
- "title": "TEST_CASE"
- },
- {
- "location": "/os/modules/testutil/test_case/#test_case",
- "text": "TEST_CASE(test_case_name) Defines a test case function with the following type int test_case_name(void) . This can then be called from regression test's TEST_SUITE() function.",
- "title": " TEST_CASE "
- },
- {
- "location": "/os/modules/testutil/test_case/#arguments",
- "text": "Arguments Description test_case_name Used as the function name for this test case.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/test_case/#returned-values",
- "text": "Return value is 0 if the test case passed; nonzero if it failed. Generally, the return code is not used. It is expected that the case will pass/fail with tests done using TEST_ASSERT() .",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/test_case/#example",
- "text": "TEST_CASE(config_test_insert)\n{\n ....\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/testutil/test_decl/",
- "text": "TEST_CASE_DECL \n\n\nTEST_CASE_DECL(test_case_name)\n\n\n\n\n\nDeclares a test case function with the following type \nint test_case_name(void)\n. This can then be called from regression test's \nTEST_SUITE()\n function. This is only required if the test case function \nexists in a different file than the test suite. This will allow the test suite\nto find the test case\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ntest_case_name\n\n\nUsed as the function name for this test case.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturn value is 0 if the test case passed; nonzero if it failed. Generally, the return code is not used. It is expected that the case will pass/fail with tests done using \nTEST_ASSERT()\n.\n\n\nExample file \ntest_cases.h\n\n\nTEST_CASE_DECL(test_case_1)\nTEST_CASE_DECL(test_case_2)\nTEST_CASE_DECL(test_case_3)",
- "title": "TEST_CASE_DECL"
- },
- {
- "location": "/os/modules/testutil/test_decl/#test_case_decl",
- "text": "TEST_CASE_DECL(test_case_name) Declares a test case function with the following type int test_case_name(void) . This can then be called from regression test's TEST_SUITE() function. This is only required if the test case function \nexists in a different file than the test suite. This will allow the test suite\nto find the test case",
- "title": " TEST_CASE_DECL "
- },
- {
- "location": "/os/modules/testutil/test_decl/#arguments",
- "text": "Arguments Description test_case_name Used as the function name for this test case.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/test_decl/#returned-values",
- "text": "Return value is 0 if the test case passed; nonzero if it failed. Generally, the return code is not used. It is expected that the case will pass/fail with tests done using TEST_ASSERT() .",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/test_decl/#example-file-test_casesh",
- "text": "TEST_CASE_DECL(test_case_1)\nTEST_CASE_DECL(test_case_2)\nTEST_CASE_DECL(test_case_3)",
- "title": "Example file test_cases.h"
- },
- {
- "location": "/os/modules/testutil/tu_restart/",
- "text": "tu_restart \n\n\nvoid tu_restart(void)\n\n\n\n\n\nThis function is used when a system reset is necessary to proceed with testing. For example, the OS is designed to run forever once started, so a test which creates several OS tasks and then starts the OS has no means of completing. This function, when called from such a test, gracefully ends the current test case and proceeds to the next test case.\n\n\nThe particulars of this function depend on whether it is called from a simulated environment. In a simulated environment, this function uses a \nlongjmp()\n call to break out of the current test case.\n\n\nArguments\n\n\nN/A\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nExample\n\n\nvoid\nos_test_restart(void)\n{\n ....\n\n tu_restart();\n}\n#endif",
- "title": "tu_restart"
- },
- {
- "location": "/os/modules/testutil/tu_restart/#tu_restart",
- "text": "void tu_restart(void) This function is used when a system reset is necessary to proceed with testing. For example, the OS is designed to run forever once started, so a test which creates several OS tasks and then starts the OS has no means of completing. This function, when called from such a test, gracefully ends the current test case and proceeds to the next test case. The particulars of this function depend on whether it is called from a simulated environment. In a simulated environment, this function uses a longjmp() call to break out of the current test case.",
- "title": " tu_restart "
- },
- {
- "location": "/os/modules/testutil/tu_restart/#arguments",
- "text": "N/A",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/testutil/tu_restart/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/testutil/tu_restart/#example",
- "text": "void\nos_test_restart(void)\n{\n ....\n\n tu_restart();\n}\n#endif",
- "title": "Example"
- },
- {
- "location": "/os/modules/devmgmt/newtmgr/",
- "text": "Newt Manager\n\n\nNewt Manager is the protocol that enables your Mynewt application to communicate remotely with your device running the Mynewt OS in order to configure, manage, conduct maintenance, and monitor it. The core device management module is called \nmgmt\n and offers multiple options for invoking the appropriate newt manager commands for various operations on the device e.g. enabling and collecting logs, configuring and retrieving stats, resetting the device etc. \n\n\n\n\nUse the \nnewtmgr\n package if reduced code footprint is your primary requirement and you do not have interoperability requirements upstream for device information, discovery, and connectivity.\n\n\nUse the \noicmgr\n package if interoperability and standards-based connectivity for device interaction is your primary requirement. This package supports the OIC (Open Interconnect Consortium) Specification 1.1.0 framework from Open Connectivity Foundation (OCF). \n\n\n\n\nInvoking Newt Manager commands\n\n\nThe diagram below indicates the two options available to the application developer to issue Newt Manager (\nnewtmgr\n) commands on a Mynewt device. The application may leverage the \nnewtmgr\n framework or the \noicmgr\n framework to call the newtmgr commands. The latter is described in the next chapter.\n\n\n\n\nnewtmgr\n\n\nThe newtmgr framework uses a simple request and response message format to send commands to the device. A message \nconsists of an eight byte header and the message payload. The message header specifies the newtmgr command. \nThe message payload contains the newtmgr request/response data and is encoded in \nCBOR (Concise Binary Object Representation) format. newtmgr supports BLE and serial connections.\n\n\nThe newtmgr framework has a smaller code size and memory footprint than oicmgr but does not support open connectivity.",
- "title": "toc"
- },
- {
- "location": "/os/modules/devmgmt/newtmgr/#newt-manager",
- "text": "Newt Manager is the protocol that enables your Mynewt application to communicate remotely with your device running the Mynewt OS in order to configure, manage, conduct maintenance, and monitor it. The core device management module is called mgmt and offers multiple options for invoking the appropriate newt manager commands for various operations on the device e.g. enabling and collecting logs, configuring and retrieving stats, resetting the device etc. Use the newtmgr package if reduced code footprint is your primary requirement and you do not have interoperability requirements upstream for device information, discovery, and connectivity. Use the oicmgr package if interoperability and standards-based connectivity for device interaction is your primary requirement. This package supports the OIC (Open Interconnect Consortium) Specification 1.1.0 framework from Open Connectivity Foundation (OCF).",
- "title": "Newt Manager"
- },
- {
- "location": "/os/modules/devmgmt/newtmgr/#invoking-newt-manager-commands",
- "text": "The diagram below indicates the two options available to the application developer to issue Newt Manager ( newtmgr ) commands on a Mynewt device. The application may leverage the newtmgr framework or the oicmgr framework to call the newtmgr commands. The latter is described in the next chapter.",
- "title": "Invoking Newt Manager commands"
- },
- {
- "location": "/os/modules/devmgmt/newtmgr/#newtmgr",
- "text": "The newtmgr framework uses a simple request and response message format to send commands to the device. A message \nconsists of an eight byte header and the message payload. The message header specifies the newtmgr command. \nThe message payload contains the newtmgr request/response data and is encoded in \nCBOR (Concise Binary Object Representation) format. newtmgr supports BLE and serial connections. The newtmgr framework has a smaller code size and memory footprint than oicmgr but does not support open connectivity.",
- "title": "newtmgr"
- },
- {
- "location": "/os/modules/devmgmt/oicmgr/",
- "text": "Using the OIC Framework\n\n\nApache Mynewt includes support for the OIC interoperability standard through the \noicmgr\n framework. Mynewt defines and exposes oicmgr as an OIC Server resource with the following identity and properties: \n\n\n\n\n\n \n\nURI\n \n\n/omgr\n\n\n\n\n\n\nResource Type\n(rt)\n\n\nx.mynewt.nmgr\n \n\n\n\nInterface\n(if)\n\n\noic.if_rw (default), oic.if.baseline\n\n\n\n\nDiscoverable\n\n\nYes\n\n\n\n\n\nThe newtmgr application tool uses CoAP (Constrained Application Protocol) requests to send commands to oicmgr.\n\nIt sends a CoAP request for \n/omgr\n as follows:\n\n\n\n\nSpecifies the newtmgr command to execute in the URI query string. \n\n\nUses a GET method for newtmgr commands that retreive information \nfrom your application, for example, the \ntaskstat\n and \nmpstat\n commands. \n\n\nUses a PUT method for newtmgr commands that send data to or modify the state of your application,\nfor example, the \necho\n or \ndatetime\n commands. \n\n\nSends the CBOR-encoded command request data in the CoAP message payload.\n\n\n\n\nThe \noicmgr\n framework supports transport over BLE, serial, and IP connections to the device.",
- "title": "Using Newt Manager in OIC framework"
- },
- {
- "location": "/os/modules/devmgmt/oicmgr/#using-the-oic-framework",
- "text": "Apache Mynewt includes support for the OIC interoperability standard through the oicmgr framework. Mynewt defines and exposes oicmgr as an OIC Server resource with the following identity and properties: URI /omgr Resource Type (rt) x.mynewt.nmgr Interface (if) oic.if_rw (default), oic.if.baseline Discoverable Yes \nThe newtmgr application tool uses CoAP (Constrained Application Protocol) requests to send commands to oicmgr. \nIt sends a CoAP request for /omgr as follows: Specifies the newtmgr command to execute in the URI query string. Uses a GET method for newtmgr commands that retreive information \nfrom your application, for example, the taskstat and mpstat commands. Uses a PUT method for newtmgr commands that send data to or modify the state of your application,\nfor example, the echo or datetime commands. Sends the CBOR-encoded command request data in the CoAP message payload. The oicmgr framework supports transport over BLE, serial, and IP connections to the device.",
- "title": "Using the OIC Framework"
- },
- {
- "location": "/os/modules/devmgmt/customize_newtmgr/",
- "text": "Customizing Newt Manager Usage with mgmt\n\n\nThe \nmgmt\n package enables you to customize Newt Manager (in either the newtmgr or oicmgr framerwork) to only process the\ncommands that your application uses. The newtmgr commands are divided into management groups.\nA manager package implements the commands for a group. It implements the handlers that \nprocess the commands for the group and registers the handlers with mgmt. \nWhen newtmgr or oicmgr receives a newtmgr command, \nit looks up the handler for the command (by management group id and command id) from mgmt and calls the \nhandler to process the command. \n\n\nThe system level management groups are listed in following table:\n\n\n\n\n\nManagement Group\n\n\nnewtmgr Commands\n\n\nPackage\n\n\n\n\n\n\nMGMT_GROUP_ID_DEFAULT\n\n\necho\n \ntaskstat\n \nmpstat\n \ndatetime\n \nreset\n\n\nmgmt/newtmgr/nmgr_os\n\n\n\n\n\n\nMGMT_GROUP_ID_IMAGE\n\n\nimage\n \n\n\nmgmt/imgmgr\n\n\n\n\n\n\nMGMT_GROUP_ID_STATS\n\n\nstat\n \n\n\nsys/stats\n\n\n\n\n\n\nMGMT_GROUP_ID_CONFIG\n\n\nconfig\n\n\nsys/config\n\n\n\n\n\n\nMGMT_GROUP_ID_LOGS\n\n\nlog\n\n\nsys/log\n\n\n\n\n\n\nMGMT_GROUP_ID_CRASH\n\n\ncrash\n\n\ntest/crash_test\n\n\n\n\n\n\nMGMT_GROUP_ID_RUNTEST\n\n\nrun\n\n\ntest/runtest\n\n\n\n\n\nBoth newtmgr and ocimgr process the MGMT_GROUP_ID_DEFAULT commands by default. You can also\nuse mgmt to add user defined management group commands.",
- "title": "Customizing Newt Manager Usage with mgmt"
- },
- {
- "location": "/os/modules/devmgmt/customize_newtmgr/#customizing-newt-manager-usage-with-mgmt",
- "text": "The mgmt package enables you to customize Newt Manager (in either the newtmgr or oicmgr framerwork) to only process the\ncommands that your application uses. The newtmgr commands are divided into management groups.\nA manager package implements the commands for a group. It implements the handlers that \nprocess the commands for the group and registers the handlers with mgmt. \nWhen newtmgr or oicmgr receives a newtmgr command, \nit looks up the handler for the command (by management group id and command id) from mgmt and calls the \nhandler to process the command. The system level management groups are listed in following table: Management Group newtmgr Commands Package MGMT_GROUP_ID_DEFAULT echo taskstat mpstat datetime reset mgmt/newtmgr/nmgr_os MGMT_GROUP_ID_IMAGE image mgmt/imgmgr MGMT_GROUP_ID_STATS stat sys/stats MGMT_GROUP_ID_CONFIG config sys/config MGMT_GROUP_ID_LOGS log sys/log MGMT_GROUP_ID_CRASH crash test/crash_test MGMT_GROUP_ID_RUNTEST run test/runtest \nBoth newtmgr and ocimgr process the MGMT_GROUP_ID_DEFAULT commands by default. You can also\nuse mgmt to add user defined management group commands.",
- "title": "Customizing Newt Manager Usage with mgmt"
- },
- {
- "location": "/os/modules/imgmgr/imgmgr/",
- "text": "Image Manager\n\n\nDescription\n\n\nThis library accepts incoming image management commands from newtmgr and acts on them.\n\n\nImages can be uploaded, present images listed, and system can be told to switch to another image.\n\n\nCurrently the package assumes that there are 2 image slots, one active one and another one in standby. When new image is uploaded, it replaces the one in standby slot. This is the model for scenario when MCU has internal flash only, it executes the code from that flash, and there is enough space to store 2 full images.\n\n\nImage manager interacts with bootloader by telling it to boot to a specific image. At the moment this has to be done by writing a file which contains a version number of the image to boot. Note that image manager itself does not replace the active image.\n\n\nImage manager also can upload files to filesystem as well as download them.\n\n\nNote that commands accessing filesystems (next boot target, file upload/download) will not be available unless project includes filesystem implementation.\n\n\nData structures\n\n\nN/A.\n\n\nList of Functions\n\n\n\n\nThe functions available in imgmgr are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nimgr_ver_parse\n\n\nParses character string containing specified image version number and writes that to given image_version struct.\n\n\n\n\n\n\nimgr_ver_str\n\n\nTakes version string from specified image_version struct and formats it into a printable string.",
- "title": "toc"
- },
- {
- "location": "/os/modules/imgmgr/imgmgr/#image-manager",
- "text": "",
- "title": "Image Manager"
- },
- {
- "location": "/os/modules/imgmgr/imgmgr/#description",
- "text": "This library accepts incoming image management commands from newtmgr and acts on them. Images can be uploaded, present images listed, and system can be told to switch to another image. Currently the package assumes that there are 2 image slots, one active one and another one in standby. When new image is uploaded, it replaces the one in standby slot. This is the model for scenario when MCU has internal flash only, it executes the code from that flash, and there is enough space to store 2 full images. Image manager interacts with bootloader by telling it to boot to a specific image. At the moment this has to be done by writing a file which contains a version number of the image to boot. Note that image manager itself does not replace the active image. Image manager also can upload files to filesystem as well as download them. Note that commands accessing filesystems (next boot target, file upload/download) will not be available unless project includes filesystem implementation.",
- "title": "Description"
- },
- {
- "location": "/os/modules/imgmgr/imgmgr/#data-structures",
- "text": "N/A.",
- "title": "Data structures"
- },
- {
- "location": "/os/modules/imgmgr/imgmgr/#list-of-functions",
- "text": "The functions available in imgmgr are: Function Description imgr_ver_parse Parses character string containing specified image version number and writes that to given image_version struct. imgr_ver_str Takes version string from specified image_version struct and formats it into a printable string.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_parse/",
- "text": "imgr_ver_parse \n\n\n int\n imgr_ver_parse(char *src, struct image_version *ver)\n\n\n\n\n\nParses character string containing image version number \nsrc\n and writes that to \nver\n. Version number string should be in format \n.\n.\n.\n. Major and minor numbers should be within range 0-255, revision between 0-65535 and build_number 0-4294967295.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsrc\n\n\nPointer to C string that contains version number being parsed\n\n\n\n\n\n\nver\n\n\nImage version number structure containing the returned value\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success and \n0 if version number string could not be parsed.\n\n\nNotes\n\n\nNumbers within the string are separated by \n.\n. The first number is the major number, and must be provided. Rest of the numbers (minor etc.) are optional.\n\n\nExample\n\n\nint main(int argc, char **argv)\n{\n struct image_version hdr_ver;\n int rc;\n ...\n\n rc = imgr_ver_parse(argv[3], \nhdr_ver);\n if (rc != 0) {\n print_usage(stderr);\n return 1;\n }\n ...\n}",
- "title": "imgr_ver_parse"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_parse/#imgr_ver_parse",
- "text": "int\n imgr_ver_parse(char *src, struct image_version *ver) Parses character string containing image version number src and writes that to ver . Version number string should be in format . . . . Major and minor numbers should be within range 0-255, revision between 0-65535 and build_number 0-4294967295.",
- "title": " imgr_ver_parse "
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_parse/#arguments",
- "text": "Arguments Description src Pointer to C string that contains version number being parsed ver Image version number structure containing the returned value",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_parse/#returned-values",
- "text": "0 on success and 0 if version number string could not be parsed.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_parse/#notes",
- "text": "Numbers within the string are separated by . . The first number is the major number, and must be provided. Rest of the numbers (minor etc.) are optional.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_parse/#example",
- "text": "int main(int argc, char **argv)\n{\n struct image_version hdr_ver;\n int rc;\n ...\n\n rc = imgr_ver_parse(argv[3], hdr_ver);\n if (rc != 0) {\n print_usage(stderr);\n return 1;\n }\n ...\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_str/",
- "text": "imgr_ver_str \n\n\n int\n imgr_ver_str(struct image_version *ver, char *dst)\n\n\n\n\n\nTakes the version string from \nver\n and formats that into a printable string to \ndst\n. Caller must make sure that \ndst\n contains enough space to hold maximum length version string. The convenience defininition for max length version string is named \nIMGMGR_MAX_VER_STR\n.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nver\n\n\nImage version number structure containing the value being formatted\n\n\n\n\n\n\ndst\n\n\nPointer to C string where results will be stored\n\n\n\n\n\n\n\n\nReturned values\n\n\nFunction returns the number of characters filled into the destination string.\n\n\nNotes\n\n\nIf build number is \n0\n in image version structure, it will be left out of the string.\n\n\nExample\n\n\nstatic void\nimgr_ver_jsonstr(struct json_encoder *enc, char *key,\n struct image_version *ver)\n{\n char ver_str[IMGMGR_MAX_VER_STR];\n int ver_len;\n ...\n ver_len = imgr_ver_str(ver, ver_str)\n ...\n}",
- "title": "imgr_ver_str"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_str/#imgr_ver_str",
- "text": "int\n imgr_ver_str(struct image_version *ver, char *dst) Takes the version string from ver and formats that into a printable string to dst . Caller must make sure that dst contains enough space to hold maximum length version string. The convenience defininition for max length version string is named IMGMGR_MAX_VER_STR .",
- "title": " imgr_ver_str "
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_str/#arguments",
- "text": "Arguments Description ver Image version number structure containing the value being formatted dst Pointer to C string where results will be stored",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_str/#returned-values",
- "text": "Function returns the number of characters filled into the destination string.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_str/#notes",
- "text": "If build number is 0 in image version structure, it will be left out of the string.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/imgmgr/imgr_ver_str/#example",
- "text": "static void\nimgr_ver_jsonstr(struct json_encoder *enc, char *key,\n struct image_version *ver)\n{\n char ver_str[IMGMGR_MAX_VER_STR];\n int ver_len;\n ...\n ver_len = imgr_ver_str(ver, ver_str)\n ...\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/baselibc/",
- "text": "Baselibc\n\n\nBaselibc is a very simple libc for embedded systems geared primarily for 32-bit microcontrollers in the \n10-100kB memory range. The library of basic system calls and facilities compiles to less than 5kB total \non Cortex-M3, and much less if some functions aren't used.\n\n\nThe code is based on klibc and tinyprintf modules, and licensed under the BSD license.\n\n\nBaselibc comes from https://github.com/PetteriAimonen/Baselibc.git\n\n\nDescription\n\n\nMynewt OS can utilize libc which comes with the compiler (e.g. newlib bundled with some binary \ndistributions of arm-none-eabi-gcc). However, you may choose to replace the libc with baselibc \nfor a reduced image size. Baselibc optimizes for size rather than performance, which is usually \na more important goal in embedded environments.\n\n\nHow to switch to baselibc\n\n\nIn order to switch from using libc to using baselibc you have to add the baselibc pkg as a dependency \nin the project pkg. Specifying this dependency ensures that the linker first looks for the functions \nin baselibc before falling back to libc while creating the executable. For example, project \nboot\n \nuses baselibc. Its project description file \nboot.yml\n looks like the following:\n\n\n project.name: boot\n project.identities: bootloader\n project.pkgs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util\n - libs/baselibc\n\n\n\n\n\nList of Functions\n\n\nDocumentation for libc functions is available from multiple places. One example is the on-line manual \npages at \nhttps://www.freebsd.org/cgi/man.cgi\n.\n\n\nbaselibc supports most libc functionality; \nmalloc()\n, printf-family, string handling, and conversion routines.\n\n\nThere is some functionality which is not available, e.g. support for floating point numbers, and limited support for 'long long'.",
- "title": "Baselibc library"
- },
- {
- "location": "/os/modules/baselibc/#baselibc",
- "text": "Baselibc is a very simple libc for embedded systems geared primarily for 32-bit microcontrollers in the \n10-100kB memory range. The library of basic system calls and facilities compiles to less than 5kB total \non Cortex-M3, and much less if some functions aren't used. The code is based on klibc and tinyprintf modules, and licensed under the BSD license. Baselibc comes from https://github.com/PetteriAimonen/Baselibc.git",
- "title": "Baselibc"
- },
- {
- "location": "/os/modules/baselibc/#description",
- "text": "Mynewt OS can utilize libc which comes with the compiler (e.g. newlib bundled with some binary \ndistributions of arm-none-eabi-gcc). However, you may choose to replace the libc with baselibc \nfor a reduced image size. Baselibc optimizes for size rather than performance, which is usually \na more important goal in embedded environments.",
- "title": "Description"
- },
- {
- "location": "/os/modules/baselibc/#how-to-switch-to-baselibc",
- "text": "In order to switch from using libc to using baselibc you have to add the baselibc pkg as a dependency \nin the project pkg. Specifying this dependency ensures that the linker first looks for the functions \nin baselibc before falling back to libc while creating the executable. For example, project boot \nuses baselibc. Its project description file boot.yml looks like the following: project.name: boot\n project.identities: bootloader\n project.pkgs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util\n - libs/baselibc",
- "title": "How to switch to baselibc"
- },
- {
- "location": "/os/modules/baselibc/#list-of-functions",
- "text": "Documentation for libc functions is available from multiple places. One example is the on-line manual \npages at https://www.freebsd.org/cgi/man.cgi . baselibc supports most libc functionality; malloc() , printf-family, string handling, and conversion routines. There is some functionality which is not available, e.g. support for floating point numbers, and limited support for 'long long'.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/json/json/",
- "text": "JSON\n\n\nJSON is a data interchange format. The description of this format can be found from IETF RFC 4627.\n\n\nDescription\n\n\nThis package helps in converting between C data types and JSON data objects. It supports both encoding and decoding.\n\n\nData structures\n\n\nEncoding\n\n\n/* Encoding functions */\n\n\ntypedef\n \nint\n (\n*json_write_func_t\n)(\nvoid\n \n*buf\n, \nchar\n \n*data\n,\n \nint\n \nlen\n);\n\n\nstruct\n \njson_encoder\n {\n \njson_write_func_t\n \nje_write\n;\n \nvoid\n \n*je_arg\n;\n \nint\n \nje_wr_commas\n:\n1\n;\n \nchar\n \nje_encode_buf\n[\n64\n];\n};\n\n\n\n\n\nHere's the data structure encoder funtions use, and it must be initialized by the caller. The key element is \nje_write\n, which is a function pointer which gets called whenever encoding routine is ready with encoded data. The element \nje_arg\n is passed to \nje_write\n as the first argument. The rest of the structure contents are for internal state management.\nThis function should collect all the data encoder function generates. It can collect this data to a flat buffer, chain of mbufs or even stream through.\n\n\n/**\n\n\n * For encode. The contents of a JSON value to encode.\n\n\n */\n\n\nstruct\n \njson_value\n {\n \nuint8_t\n \njv_pad1\n;\n \nuint8_t\n \njv_type\n;\n \nuint16_t\n \njv_len\n;\n\n \nunion\n {\n \nuint64_t\n \nu\n;\n \nfloat\n \nfl\n;\n \nchar\n \n*str\n;\n \nstruct\n {\n \nchar\n \n**keys\n;\n \nstruct\n \njson_value\n \n**values\n;\n } \ncomposite\n;\n } \njv_val\n;\n};\n\n\n\n\n\nThis data structure is filled with data to be encoded. It is best to fill this using the macros \nJSON_VALUE_STRING()\n or \nJSON_VALUE_STRINGN()\n when value is string, \nJSON_VALUE_INT()\n when value is an integer, and so forth.\n\n\nDecoding\n\n\n/* when you implement a json buffer, you must implement these functions */\n\n\n\n/* returns the next character in the buffer or \n\\0\n*/\n\n\ntypedef\n \nchar\n (\n*json_buffer_read_next_byte_t\n)(\nstruct\n \njson_buffer\n \n*\n);\n\n/* returns the previous character in the buffer or \n\\0\n */\n\n\ntypedef\n \nchar\n (\n*json_buffer_read_prev_byte_t\n)(\nstruct\n \njson_buffer\n \n*\n);\n\n/* returns the number of characters read or zero */\n\n\ntypedef\n \nint\n (\n*json_buffer_readn_t\n)(\nstruct\n \njson_buffer\n \n*\n, \nchar\n \n*buf\n, \nint\n \nn\n);\n\n\nstruct\n \njson_buffer\n {\n \njson_buffer_readn_t\n \njb_readn\n;\n \njson_buffer_read_next_byte_t\n \njb_read_next\n;\n \njson_buffer_read_prev_byte_t\n \njb_read_prev\n;\n};\n\n\n\n\n\nFunction pointers within this structure are used by decoder when it is reading in more data to decode.\n\n\nstruct\n \njson_attr_t\n {\n \nchar\n \n*attribute\n;\n \njson_type\n \ntype\n;\n \nunion\n {\n \nint\n \n*integer\n;\n \nunsigned\n \nint\n \n*uinteger\n;\n \ndouble\n \n*real\n;\n \nchar\n \n*string\n;\n \nbool\n \n*boolean\n;\n \nchar\n \n*character\n;\n \nstruct\n \njson_array_t\n \narray\n;\n \nsize_t\n \noffset\n;\n } \naddr\n;\n \nunion\n {\n \nint\n \ninteger\n;\n \nunsigned\n \nint\n \nuinteger\n;\n \ndouble\n \nreal\n;\n \nbool\n \nboolean\n;\n \nchar\n \ncharacter\n;\n \nchar\n \n*check\n;\n } \ndflt\n;\n \nsize_t\n \nlen\n;\n \nconst\n \nstruct\n \njson_enum_t\n \n*map\n;\n \nbool\n \nnodefault\n;\n};\n\n\n\n\n\nThis structure tells the decoder about a particular name/value pair. Structure must be filled in before calling the decoder routine \njson_read_object()\n.\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nattribute\n\n\nName of the value\n\n\n\n\n\n\ntype\n\n\nThe type of the variable; see enum json_type\n\n\n\n\n\n\naddr\n\n\nContains the address where value should be stored\n\n\n\n\n\n\ndflt\n\n\nDefault value to fill in, if this name is not found\n\n\n\n\n\n\nlen\n\n\nMax number of bytes to read in for value\n\n\n\n\n\n\nnodefault\n\n\nIf set, default value is not copied name\n\n\n\n\n\n\n\n\nList of Functions\n\n\nFunctions for encoding:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\njson_encode_object_start\n\n\nThis function starts the encoded JSON object.\n\n\n\n\n\n\njson_encode_object_key\n\n\nThis function writes out a name for a field, followed by \":\" character.\n\n\n\n\n\n\njson_encode_object_entry\n\n\nThis function writes out a name for a field, followed by \":\" character, and the value itself.\n\n\n\n\n\n\njson_encode_object_finish\n\n\nThis function finalizes the encoded JSON object.\n\n\n\n\n\n\n\n\nFunctions for decoding:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\njson_read_object\n\n\nThis function reads in JSON data stream, while looking for name/value pairs described in given attribites.",
- "title": "toc"
- },
- {
- "location": "/os/modules/json/json/#json",
- "text": "JSON is a data interchange format. The description of this format can be found from IETF RFC 4627.",
- "title": "JSON"
- },
- {
- "location": "/os/modules/json/json/#description",
- "text": "This package helps in converting between C data types and JSON data objects. It supports both encoding and decoding.",
- "title": "Description"
- },
- {
- "location": "/os/modules/json/json/#data-structures",
- "text": "",
- "title": "Data structures"
- },
- {
- "location": "/os/modules/json/json/#encoding",
- "text": "/* Encoding functions */ typedef int ( *json_write_func_t )( void *buf , char *data ,\n int len ); struct json_encoder {\n json_write_func_t je_write ;\n void *je_arg ;\n int je_wr_commas : 1 ;\n char je_encode_buf [ 64 ];\n}; Here's the data structure encoder funtions use, and it must be initialized by the caller. The key element is je_write , which is a function pointer which gets called whenever encoding routine is ready with encoded data. The element je_arg is passed to je_write as the first argument. The rest of the structure contents are for internal state management.\nThis function should collect all the data encoder function generates. It can collect this data to a flat buffer, chain of mbufs or even stream through. /** * For encode. The contents of a JSON value to encode. */ struct json_value {\n uint8_t jv_pad1 ;\n uint8_t jv_type ;\n uint16_t jv_len ;\n\n union {\n uint64_t u ;\n float fl ;\n char *str ;\n struct {\n char **keys ;\n struct json_value **values ;\n } composite ;\n } jv_val ;\n}; This data structure is filled with data to be encoded. It is best to fill this using the macros JSON_VALUE_STRING() or JSON_VALUE_STRINGN() when value is string, JSON_VALUE_INT() when value is an integer, and so forth.",
- "title": "Encoding"
- },
- {
- "location": "/os/modules/json/json/#decoding",
- "text": "/* when you implement a json buffer, you must implement these functions */ /* returns the next character in the buffer or \\0 */ typedef char ( *json_buffer_read_next_byte_t )( struct json_buffer * ); /* returns the previous character in the buffer or \\0 */ typedef char ( *json_buffer_read_prev_byte_t )( struct json_buffer * ); /* returns the number of characters read or zero */ typedef int ( *json_buffer_readn_t )( struct json_buffer * , char *buf , int n ); struct json_buffer {\n json_buffer_readn_t jb_readn ;\n json_buffer_read_next_byte_t jb_read_next ;\n json_buffer_read_prev_byte_t jb_read_prev ;\n}; Function pointers within this structure are used by decoder when it is reading in more data to decode. struct json_attr_t {\n char *attribute ;\n json_type type ;\n union {\n int *integer ;\n unsigned int *uinteger ;\n double *real ;\n char *string ;\n bool *boolean ;\n char *character ;\n struct json_array_t array ;\n size_t offset ;\n } addr ;\n union {\n int integer ;\n unsigned int uinteger ;\n double real ;\n bool boolean ;\n char character ;\n char *check ;\n } dflt ;\n size_t len ;\n const struct json_enum_t *map ;\n bool nodefault ;\n}; This structure tells the decoder about a particular name/value pair. Structure must be filled in before calling the decoder routine json_read_object() . Element Description attribute Name of the value type The type of the variable; see enum json_type addr Contains the address where value should be stored dflt Default value to fill in, if this name is not found len Max number of bytes to read in for value nodefault If set, default value is not copied name",
- "title": "Decoding"
- },
- {
- "location": "/os/modules/json/json/#list-of-functions",
- "text": "Functions for encoding: Function Description json_encode_object_start This function starts the encoded JSON object. json_encode_object_key This function writes out a name for a field, followed by \":\" character. json_encode_object_entry This function writes out a name for a field, followed by \":\" character, and the value itself. json_encode_object_finish This function finalizes the encoded JSON object. Functions for decoding: Function Description json_read_object This function reads in JSON data stream, while looking for name/value pairs described in given attribites.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/json/json_encode_object_entry/",
- "text": "json_encode_object_entry \n\n\n int json_encode_object_entry(struct json_encoder *encoder, char *key, struct json_value *val)\n\n\n\n\n\nThis function writes out a name for a field, followed by \":\" character, and the value itself. How value is treated depends on the type of the value.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nencoder\n\n\njson_encoder to use\n\n\n\n\n\n\nkey\n\n\nname to write out\n\n\n\n\n\n\nval\n\n\nvalue to write out\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success.\n\n\nExample\n\n\nstatic\n \nint\n\n\nimgr_list\n(\nstruct\n \nnmgr_jbuf\n \n*njb\n)\n{\n \nstruct\n \njson_encoder\n \n*enc\n;\n \nstruct\n \njson_value\n \narray\n;\n\n ...\n\n \njson_encode_object_start\n(\nenc\n);\n \njson_encode_object_entry\n(\nenc\n, \nimages\n, \narray\n);\n \njson_encode_object_finish\n(\nenc\n);\n\n \nreturn\n \n0\n;\n}",
- "title": "json_encode_object_entry"
- },
- {
- "location": "/os/modules/json/json_encode_object_entry/#json_encode_object_entry",
- "text": "int json_encode_object_entry(struct json_encoder *encoder, char *key, struct json_value *val) This function writes out a name for a field, followed by \":\" character, and the value itself. How value is treated depends on the type of the value.",
- "title": " json_encode_object_entry "
- },
- {
- "location": "/os/modules/json/json_encode_object_entry/#arguments",
- "text": "Arguments Description encoder json_encoder to use key name to write out val value to write out",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/json/json_encode_object_entry/#returned-values",
- "text": "0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/json/json_encode_object_entry/#example",
- "text": "static int imgr_list ( struct nmgr_jbuf *njb )\n{\n struct json_encoder *enc ;\n struct json_value array ;\n\n ...\n\n json_encode_object_start ( enc );\n json_encode_object_entry ( enc , images , array );\n json_encode_object_finish ( enc );\n\n return 0 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/json/json_encode_object_finish/",
- "text": "json_encode_object_finish \n\n\n int json_encode_object_finish(struct json_encoder *encoder)\n\n\n\n\n\nThis function finalizes the encoded JSON object. This means writing out the last \"}\" character.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nencoder\n\n\njson_encoder to use\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success.\n\n\nExample\n\n\nstatic\n \nint\n\n\nimgr_list\n(\nstruct\n \nnmgr_jbuf\n \n*njb\n)\n{\n \nstruct\n \njson_encoder\n \n*enc\n;\n \nstruct\n \njson_value\n \narray\n;\n\n ...\n\n \njson_encode_object_start\n(\nenc\n);\n \njson_encode_object_entry\n(\nenc\n, \nimages\n, \narray\n);\n \njson_encode_object_finish\n(\nenc\n);\n\n \nreturn\n \n0\n;\n}",
- "title": "json_encode_object_finish"
- },
- {
- "location": "/os/modules/json/json_encode_object_finish/#json_encode_object_finish",
- "text": "int json_encode_object_finish(struct json_encoder *encoder) This function finalizes the encoded JSON object. This means writing out the last \"}\" character.",
- "title": " json_encode_object_finish "
- },
- {
- "location": "/os/modules/json/json_encode_object_finish/#arguments",
- "text": "Arguments Description encoder json_encoder to use",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/json/json_encode_object_finish/#returned-values",
- "text": "0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/json/json_encode_object_finish/#example",
- "text": "static int imgr_list ( struct nmgr_jbuf *njb )\n{\n struct json_encoder *enc ;\n struct json_value array ;\n\n ...\n\n json_encode_object_start ( enc );\n json_encode_object_entry ( enc , images , array );\n json_encode_object_finish ( enc );\n\n return 0 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/json/json_encode_object_key/",
- "text": "json_encode_object_key \n\n\n int json_encode_object_key(struct json_encoder *encoder, char *key)\n\n\n\n\n\nThis function writes out a name for a field, followed by \":\" character. You would use this e.g. when the value that follows is a JSON object.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nencoder\n\n\njson_encoder to use\n\n\n\n\n\n\nkey\n\n\nname to write out\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success.\n\n\nExample\n\n\nint\n\n\nnmgr_def_taskstat_read\n(\nstruct\n \nnmgr_jbuf\n \n*njb\n)\n{\n ...\n\n \nstruct\n \njson_value\n \njv\n;\n\n \njson_encode_object_start\n(\nnjb-\nnjb_enc\n);\n \nJSON_VALUE_INT\n(\njv\n, \nNMGR_ERR_EOK\n);\n \njson_encode_object_entry\n(\nnjb-\nnjb_enc\n, \nrc\n, \njv\n);\n\n \njson_encode_object_key\n(\nnjb-\nnjb_enc\n, \ntasks\n);\n \njson_encode_object_start\n(\nnjb-\nnjb_enc\n);\n ...\n}",
- "title": "json_encode_object_key"
- },
- {
- "location": "/os/modules/json/json_encode_object_key/#json_encode_object_key",
- "text": "int json_encode_object_key(struct json_encoder *encoder, char *key) This function writes out a name for a field, followed by \":\" character. You would use this e.g. when the value that follows is a JSON object.",
- "title": " json_encode_object_key "
- },
- {
- "location": "/os/modules/json/json_encode_object_key/#arguments",
- "text": "Arguments Description encoder json_encoder to use key name to write out",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/json/json_encode_object_key/#returned-values",
- "text": "0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/json/json_encode_object_key/#example",
- "text": "int nmgr_def_taskstat_read ( struct nmgr_jbuf *njb )\n{\n ...\n\n struct json_value jv ;\n\n json_encode_object_start ( njb- njb_enc );\n JSON_VALUE_INT ( jv , NMGR_ERR_EOK );\n json_encode_object_entry ( njb- njb_enc , rc , jv );\n\n json_encode_object_key ( njb- njb_enc , tasks );\n json_encode_object_start ( njb- njb_enc );\n ...\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/json/json_encode_object_start/",
- "text": "json_encode_object_start \n\n\n int json_encode_object_start(struct json_encoder *encoder)\n\n\n\n\n\nThis function starts the encoded JSON object. Usually this means writing out the initial \"{\" character.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nencoder\n\n\njson_encoder to use\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success.\n\n\nExample\n\n\nstatic\n \nint\n\n\nimgr_list\n(\nstruct\n \nnmgr_jbuf\n \n*njb\n)\n{\n \nstruct\n \njson_encoder\n \n*enc\n;\n \nstruct\n \njson_value\n \narray\n;\n\n ...\n\n \njson_encode_object_start\n(\nenc\n);\n \njson_encode_object_entry\n(\nenc\n, \nimages\n, \narray\n);\n \njson_encode_object_finish\n(\nenc\n);\n\n \nreturn\n \n0\n;\n}",
- "title": "json_encode_object_start"
- },
- {
- "location": "/os/modules/json/json_encode_object_start/#json_encode_object_start",
- "text": "int json_encode_object_start(struct json_encoder *encoder) This function starts the encoded JSON object. Usually this means writing out the initial \"{\" character.",
- "title": " json_encode_object_start "
- },
- {
- "location": "/os/modules/json/json_encode_object_start/#arguments",
- "text": "Arguments Description encoder json_encoder to use",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/json/json_encode_object_start/#returned-values",
- "text": "0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/json/json_encode_object_start/#example",
- "text": "static int imgr_list ( struct nmgr_jbuf *njb )\n{\n struct json_encoder *enc ;\n struct json_value array ;\n\n ...\n\n json_encode_object_start ( enc );\n json_encode_object_entry ( enc , images , array );\n json_encode_object_finish ( enc );\n\n return 0 ;\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/json/json_read_object/",
- "text": "json_read_object \n\n\n int json_read_object(struct json_buffer *jb, const struct json_attr_t *attrs)\n\n\n\n\n\nThis function reads in JSON data stream, while looking for name/value pairs described in \nattrs\n. \nattrs\n is an array; end of the array is indicated by an entry with \nNULL\n as the name.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\njb\n\n\njson_decoder to use\n\n\n\n\n\n\nattrs\n\n\narray of attributes to look for\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success.\n\n\nExample\n\n\nstatic\n \nint\n\n\nimgr_upload\n(\nstruct\n \nnmgr_jbuf\n \n*njb\n)\n{\n ...\n \nconst\n \nstruct\n \njson_attr_t\n \noff_attr\n[\n4\n] \n=\n {\n [\n0\n] \n=\n {\n .\nattribute\n \n=\n \noff\n,\n .\ntype\n \n=\n \nt_uinteger\n,\n .\naddr\n.\nuinteger\n \n=\n \noff\n,\n .\nnodefault\n \n=\n \ntrue\n\n },\n [\n1\n] \n=\n {\n .\nattribute\n \n=\n \ndata\n,\n .\ntype\n \n=\n \nt_string\n,\n .\naddr\n.\nstring\n \n=\n \nimg_data\n,\n .\nlen\n \n=\n \nsizeof\n(\nimg_data\n)\n },\n [\n2\n] \n=\n {\n .\nattribute\n \n=\n \nlen\n,\n .\ntype\n \n=\n \nt_uinteger\n,\n .\naddr\n.\nuinteger\n \n=\n \nsize\n,\n .\nnodefault\n \n=\n \ntrue\n\n }\n };\n ...\n\n \nrc\n \n=\n \njson_read_object\n(\nnjb-\nnjb_buf\n, \noff_attr\n);\n \nif\n (\nrc\n \n||\n \noff\n \n==\n \nUINT_MAX\n) {\n \nrc\n \n=\n \nOS_EINVAL\n;\n \ngoto\n \nerr\n;\n }\n ...\n}",
- "title": "json_read_object"
- },
- {
- "location": "/os/modules/json/json_read_object/#json_read_object",
- "text": "int json_read_object(struct json_buffer *jb, const struct json_attr_t *attrs) This function reads in JSON data stream, while looking for name/value pairs described in attrs . attrs is an array; end of the array is indicated by an entry with NULL as the name.",
- "title": " json_read_object "
- },
- {
- "location": "/os/modules/json/json_read_object/#arguments",
- "text": "Arguments Description jb json_decoder to use attrs array of attributes to look for",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/json/json_read_object/#returned-values",
- "text": "0 on success.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/json/json_read_object/#example",
- "text": "static int imgr_upload ( struct nmgr_jbuf *njb )\n{\n ...\n const struct json_attr_t off_attr [ 4 ] = {\n [ 0 ] = {\n . attribute = off ,\n . type = t_uinteger ,\n . addr . uinteger = off ,\n . nodefault = true \n },\n [ 1 ] = {\n . attribute = data ,\n . type = t_string ,\n . addr . string = img_data ,\n . len = sizeof ( img_data )\n },\n [ 2 ] = {\n . attribute = len ,\n . type = t_uinteger ,\n . addr . uinteger = size ,\n . nodefault = true \n }\n };\n ...\n\n rc = json_read_object ( njb- njb_buf , off_attr );\n if ( rc || off == UINT_MAX ) {\n rc = OS_EINVAL ;\n goto err ;\n }\n ...\n}",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb/",
- "text": "Flash Circular Buffer (FCB)\n\n\nFlash circular buffer provides an abstration through which you can treat flash like a FIFO. You append entries to the end, and read data from the beginning.\n\n\nDescription\n\n\nElements in the flash contain the length of the element, the data within the element, and checksum over the element contents.\n\n\nStorage of elements in flash is done in a FIFO fashion. When user requests space for the next element, space is located at the end of the used area. When user starts reading, the first element served is the oldest element in flash.\n\n\nElements can be appended to the end of the area until storage space is exhausted. User has control over what happens next; either erase oldest block of data, thereby freeing up some space, or stop writing new data until existing data has been collected. FCB treats underlying storage as an array of flash sectors; when it erases old data, it does this a sector at a time.\n\n\nElements in the flash are checksummed. That is how FCB detects whether writing element to flash completed ok. It will skip over entries which don't have a valid checksum.\n\n\nUsage\n\n\nTo add an element to circular buffer:\n\n\n\n\nCall fcb_append() to get the location where data can be written. If this fails due to lack of space, you can call fcb_rotate() to make some. And then call fcb_append() again.\n\n\nUse flash_area_write() to write element contents.\n\n\nCall fcb_append_finish() when done. This completes the entry by calculating the checksum.\n\n\n\n\nTo read contents of the circular buffer:\n\n Call fcb_walk() with a pointer to your callback function.\n\n Within callback function copy in data from the element using flash_area_read(). You can tell when all data from within a sector has been read by monitoring returned element's area pointer. Then you can call fcb_rotate(), if you're done with that data.\n\n\nAlternatively:\n\n Call fcb_getnext() with 0 in element offset to get the pointer to oldest element.\n\n Use flash_area_read() to read element contents.\n* Call fcb_getnext() with pointer to current element to get the next one. And so on.\n\n\nData structures\n\n\nThis data structure describes the element location in the flash. You would use it figure out what parameters to pass to flash_area_read() to read element contents. Or to flash_area_write() when adding a new element.\n\n\nstruct\n \nfcb_entry\n {\n \nstruct\n \nflash_area\n \n*fe_area\n;\n \nuint32_t\n \nfe_elem_off\n;\n \nuint32_t\n \nfe_data_off\n;\n \nuint16_t\n \nfe_data_len\n;\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfe_area\n\n\nPointer to info about the flash sector. Pass this to flash_area_xx() routines.\n\n\n\n\n\n\nfe_elem_off\n\n\nByte offset from the start of the sector to beginning of element.\n\n\n\n\n\n\nfe_data_off\n\n\nByte offset from start of the sector to beginning of element data. Pass this to to flash_area_xx() routines.\n\n\n\n\n\n\nfe_data_len\n\n\nNumber of bytes in the element.\n\n\n\n\n\n\n\n\nThe following data structure describes the FCB itself. First part should be filled in by the user before calling fcb_init(). The second part is used by FCB for its internal bookkeeping.\n\n\nstruct\n \nfcb\n {\n \n/* Caller of fcb_init fills this in */\n\n \nuint32_t\n \nf_magic\n; \n/* As placed on the disk */\n\n \nuint8_t\n \nf_version\n; \n/* Current version number of the data */\n\n \nuint8_t\n \nf_sector_cnt\n; \n/* Number of elements in sector array */\n\n \nuint8_t\n \nf_scratch_cnt\n; \n/* How many sectors should be kept empty */\n\n \nstruct\n \nflash_area\n \n*f_sectors\n; \n/* Array of sectors, must be contiguous */\n\n\n \n/* Flash circular buffer internal state */\n\n \nstruct\n \nos_mutex\n \nf_mtx\n; \n/* Locking for accessing the FCB data */\n\n \nstruct\n \nflash_area\n \n*f_oldest\n;\n \nstruct\n \nfcb_entry\n \nf_active\n;\n \nuint16_t\n \nf_active_id\n;\n \nuint8_t\n \nf_align\n; \n/* writes to flash have to aligned to this */\n\n};\n\n\n\n\n\n\n\n\n\n\n\nElement\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nf_magic\n\n\nMagic number in the beginning of FCB flash sector. FCB uses this when determining whether sector contains valid data or not.\n\n\n\n\n\n\nf_version\n\n\nCurrent version number of the data. Also stored in flash sector header.\n\n\n\n\n\n\nf_sector_cnt\n\n\nNumber of elements in the f_sectors array.\n\n\n\n\n\n\nf_scratch_cnt\n\n\nNumber of sectors to keep empty. This can be used if you need to have scratch space for garbage collecting when FCB fills up.\n\n\n\n\n\n\nf_sectors\n\n\nArray of entries describing flash sectors to use.\n\n\n\n\n\n\nf_mtx\n\n\nLock protecting access to FCBs internal data.\n\n\n\n\n\n\nf_oldest\n\n\nPointer to flash sector containing the oldest data. This is where data is served when read is started.\n\n\n\n\n\n\nf_active\n\n\nFlash location where the newest data is. This is used by fcb_append() to figure out where the data should go to.\n\n\n\n\n\n\nf_active_id\n\n\nFlash sectors are assigned ever-increasing serial numbers. This is how FCB figures out where oldest data is on system restart.\n\n\n\n\n\n\nf_align\n\n\nSome flashes have restrictions on alignment for writes. FCB keeps a copy of this number for the flash here.\n\n\n\n\n\n\n\n\nList of Functions\n\n\nThe functions available in this OS feature are:\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb_init\n\n\nInitializes the FCB. After calling this, you can start reading/writing data from FCB.\n\n\n\n\n\n\nfcb_append\n\n\nStart writing a new element to flash.\n\n\n\n\n\n\nfcb_append_finish\n\n\nFinalizes the write of new element. FCB computes the checksum over the element and updates it in flash.\n\n\n\n\n\n\nfcb_walk\n\n\nWalks over all log entries in FCB.\n\n\n\n\n\n\nfcb_getnext\n\n\nFills given FCB location with information about next element.\n\n\n\n\n\n\nfcb_rotate\n\n\nErase the oldest sector in FCB.\n\n\n\n\n\n\nfcb_append_to_scratch\n\n\nIf FCB uses scratch blocks, use reserve blocks when FCB is filled.\n\n\n\n\n\n\nfcb_is_empty\n\n\nReturns 1 if there are no elements stored in FCB, otherwise returns 0.\n\n\n\n\n\n\nfcb_offset_last_n\n\n\nReturns the offset of n-th last element.\n\n\n\n\n\n\nfcb_clear\n\n\nWipes out all data in FCB.",
- "title": "toc"
- },
- {
- "location": "/os/modules/fcb/fcb/#flash-circular-buffer-fcb",
- "text": "Flash circular buffer provides an abstration through which you can treat flash like a FIFO. You append entries to the end, and read data from the beginning.",
- "title": "Flash Circular Buffer (FCB)"
- },
- {
- "location": "/os/modules/fcb/fcb/#description",
- "text": "Elements in the flash contain the length of the element, the data within the element, and checksum over the element contents. Storage of elements in flash is done in a FIFO fashion. When user requests space for the next element, space is located at the end of the used area. When user starts reading, the first element served is the oldest element in flash. Elements can be appended to the end of the area until storage space is exhausted. User has control over what happens next; either erase oldest block of data, thereby freeing up some space, or stop writing new data until existing data has been collected. FCB treats underlying storage as an array of flash sectors; when it erases old data, it does this a sector at a time. Elements in the flash are checksummed. That is how FCB detects whether writing element to flash completed ok. It will skip over entries which don't have a valid checksum.",
- "title": "Description"
- },
- {
- "location": "/os/modules/fcb/fcb/#usage",
- "text": "To add an element to circular buffer: Call fcb_append() to get the location where data can be written. If this fails due to lack of space, you can call fcb_rotate() to make some. And then call fcb_append() again. Use flash_area_write() to write element contents. Call fcb_append_finish() when done. This completes the entry by calculating the checksum. To read contents of the circular buffer: Call fcb_walk() with a pointer to your callback function. Within callback function copy in data from the element using flash_area_read(). You can tell when all data from within a sector has been read by monitoring returned element's area pointer. Then you can call fcb_rotate(), if you're done with that data. Alternatively: Call fcb_getnext() with 0 in element offset to get the pointer to oldest element. Use flash_area_read() to read element contents.\n* Call fcb_getnext() with pointer to current element to get the next one. And so on.",
- "title": "Usage"
- },
- {
- "location": "/os/modules/fcb/fcb/#data-structures",
- "text": "This data structure describes the element location in the flash. You would use it figure out what parameters to pass to flash_area_read() to read element contents. Or to flash_area_write() when adding a new element. struct fcb_entry {\n struct flash_area *fe_area ;\n uint32_t fe_elem_off ;\n uint32_t fe_data_off ;\n uint16_t fe_data_len ;\n}; Element Description fe_area Pointer to info about the flash sector. Pass this to flash_area_xx() routines. fe_elem_off Byte offset from the start of the sector to beginning of element. fe_data_off Byte offset from start of the sector to beginning of element data. Pass this to to flash_area_xx() routines. fe_data_len Number of bytes in the element. The following data structure describes the FCB itself. First part should be filled in by the user before calling fcb_init(). The second part is used by FCB for its internal bookkeeping. struct fcb {\n /* Caller of fcb_init fills this in */ \n uint32_t f_magic ; /* As placed on the disk */ \n uint8_t f_version ; /* Current version number of the data */ \n uint8_t f_sector_cnt ; /* Number of elements in sector array */ \n uint8_t f_scratch_cnt ; /* How many sectors should be kept empty */ \n struct flash_area *f_sectors ; /* Array of sectors, must be contiguous */ \n\n /* Flash circular buffer internal state */ \n struct os_mutex f_mtx ; /* Locking for accessing the FCB data */ \n struct flash_area *f_oldest ;\n struct fcb_entry f_active ;\n uint16_t f_active_id ;\n uint8_t f_align ; /* writes to flash have to aligned to this */ \n}; Element Description f_magic Magic number in the beginning of FCB flash sector. FCB uses this when determining whether sector contains valid data or not. f_version Current version number of the data. Also stored in flash sector header. f_sector_cnt Number of elements in the f_sectors array. f_scratch_cnt Number of sectors to keep empty. This can be used if you need to have scratch space for garbage collecting when FCB fills up. f_sectors Array of entries describing flash sectors to use. f_mtx Lock protecting access to FCBs internal data. f_oldest Pointer to flash sector containing the oldest data. This is where data is served when read is started. f_active Flash location where the newest data is. This is used by fcb_append() to figure out where the data should go to. f_active_id Flash sectors are assigned ever-increasing serial numbers. This is how FCB figures out where oldest data is on system restart. f_align Some flashes have restrictions on alignment for writes. FCB keeps a copy of this number for the flash here.",
- "title": "Data structures"
- },
- {
- "location": "/os/modules/fcb/fcb/#list-of-functions",
- "text": "The functions available in this OS feature are: Function Description fcb_init Initializes the FCB. After calling this, you can start reading/writing data from FCB. fcb_append Start writing a new element to flash. fcb_append_finish Finalizes the write of new element. FCB computes the checksum over the element and updates it in flash. fcb_walk Walks over all log entries in FCB. fcb_getnext Fills given FCB location with information about next element. fcb_rotate Erase the oldest sector in FCB. fcb_append_to_scratch If FCB uses scratch blocks, use reserve blocks when FCB is filled. fcb_is_empty Returns 1 if there are no elements stored in FCB, otherwise returns 0. fcb_offset_last_n Returns the offset of n-th last element. fcb_clear Wipes out all data in FCB.",
- "title": "List of Functions"
- },
- {
- "location": "/os/modules/fcb/fcb_init/",
- "text": "fcb_init\n\n\nint fcb_init(struct fcb *);\n\n\n\n\n\nInitializes FCB. This function walks through the given sectors, finding out how much data already exists in the flash.\nAfter calling this, you can start reading/writing data from FCB.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nStructure describing the FCB.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nNotes\n\n\nUser should fill in their portion of fcb before calling this function.\n\n\nExample",
- "title": "fcb_init"
- },
- {
- "location": "/os/modules/fcb/fcb_init/#fcb_init",
- "text": "int fcb_init(struct fcb *); Initializes FCB. This function walks through the given sectors, finding out how much data already exists in the flash.\nAfter calling this, you can start reading/writing data from FCB.",
- "title": "fcb_init"
- },
- {
- "location": "/os/modules/fcb/fcb_init/#arguments",
- "text": "Arguments Description fcb Structure describing the FCB.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_init/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_init/#notes",
- "text": "User should fill in their portion of fcb before calling this function.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_init/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_append/",
- "text": "fcb_append\n\n\nint fcb_append(struct fcb *fcb, uint16_t len, struct fcb_entry *append_loc);\n\n\n\n\n\nStart writing a new element to flash. This routine reserves the space in the flash by writing out the element header.\n\n\nWhen writing the contents for the entry, use append_loc-\nfl_area and append_loc-\nfl_data_off as arguments to flash_area_write(). When finished, call fcb_append_finish() with append_loc as argument.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB where data is written to.\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to reserve for the element.\n\n\n\n\n\n\nloc\n\n\nPointer to fcb_entry. fcb_append() will fill this with info about where the element can be written to.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\nFCB_ERR_NOSPACE is returned if FCB is full.\n\n\nNotes\n\n\nIf FCB is full, you need to make more space. This can be done by calling fcb_rotate(). Or if you've reserved scratch sectors, you can take those into use by calling fcb_append_to_scratch().\n\n\nExample",
- "title": "fcb_append"
- },
- {
- "location": "/os/modules/fcb/fcb_append/#fcb_append",
- "text": "int fcb_append(struct fcb *fcb, uint16_t len, struct fcb_entry *append_loc); Start writing a new element to flash. This routine reserves the space in the flash by writing out the element header. When writing the contents for the entry, use append_loc- fl_area and append_loc- fl_data_off as arguments to flash_area_write(). When finished, call fcb_append_finish() with append_loc as argument.",
- "title": "fcb_append"
- },
- {
- "location": "/os/modules/fcb/fcb_append/#arguments",
- "text": "Arguments Description fcb Points to FCB where data is written to. len Number of bytes to reserve for the element. loc Pointer to fcb_entry. fcb_append() will fill this with info about where the element can be written to.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_append/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.\nFCB_ERR_NOSPACE is returned if FCB is full.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_append/#notes",
- "text": "If FCB is full, you need to make more space. This can be done by calling fcb_rotate(). Or if you've reserved scratch sectors, you can take those into use by calling fcb_append_to_scratch().",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_append/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_append_finish/",
- "text": "fcb_append_finish\n\n\nint fcb_append_finish(struct fcb *fcb, struct fcb_entry *append_loc);\n\n\n\n\n\nFinalizes the write of new element. FCB computes the checksum over the element and updates it in flash.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB where data is written to.\n\n\n\n\n\n\nappend_loc\n\n\nPointer to fcb_entry. Use the fcb_entry returned by fcb_append().\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nNotes\n\n\nYou need to call fcb_append_finish() after writing the element contents. Otherwise FCB will consider this entry to be invalid, and skips over it when reading.\n\n\nExample",
- "title": "fcb_append_finish"
- },
- {
- "location": "/os/modules/fcb/fcb_append_finish/#fcb_append_finish",
- "text": "int fcb_append_finish(struct fcb *fcb, struct fcb_entry *append_loc); Finalizes the write of new element. FCB computes the checksum over the element and updates it in flash.",
- "title": "fcb_append_finish"
- },
- {
- "location": "/os/modules/fcb/fcb_append_finish/#arguments",
- "text": "Arguments Description fcb Points to FCB where data is written to. append_loc Pointer to fcb_entry. Use the fcb_entry returned by fcb_append().",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_append_finish/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_append_finish/#notes",
- "text": "You need to call fcb_append_finish() after writing the element contents. Otherwise FCB will consider this entry to be invalid, and skips over it when reading.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_append_finish/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_walk/",
- "text": "fcb_walk\n\n\ntypedef int (*fcb_walk_cb)(struct fcb_entry *loc, void *arg);\n\nint fcb_walk(struct fcb *fcb, struct flash_area *area, fcb_walk_cb cb,\n void *cb_arg);\n\n\n\n\n\nWalks over all log entries in FCB. Callback function cb gets called for every entry. If cb wants to stop the walk, it should return a non-zero value.\n\n\nIf specific flash_area is specified, only entries within that sector are walked over.\n\n\nEntry data can be read within the callback using flash_area_read(), using loc-\nfe_area, loc-\nfe_data_off, and loc-\nfe_data_len as arguments.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB where data is written to.\n\n\n\n\n\n\narea\n\n\nOptional. Pointer to specific entry in fcb's array of sectors.\n\n\n\n\n\n\ncb\n\n\nCallback function which gets called for every valid entry fcb_walk encounters.\n\n\n\n\n\n\ncb_arg\n\n\nOptional. Parameter which gets passed to callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nNotes\n\n\nExample",
- "title": "fcb_walk"
- },
- {
- "location": "/os/modules/fcb/fcb_walk/#fcb_walk",
- "text": "typedef int (*fcb_walk_cb)(struct fcb_entry *loc, void *arg);\n\nint fcb_walk(struct fcb *fcb, struct flash_area *area, fcb_walk_cb cb,\n void *cb_arg); Walks over all log entries in FCB. Callback function cb gets called for every entry. If cb wants to stop the walk, it should return a non-zero value. If specific flash_area is specified, only entries within that sector are walked over. Entry data can be read within the callback using flash_area_read(), using loc- fe_area, loc- fe_data_off, and loc- fe_data_len as arguments.",
- "title": "fcb_walk"
- },
- {
- "location": "/os/modules/fcb/fcb_walk/#arguments",
- "text": "Arguments Description fcb Points to FCB where data is written to. area Optional. Pointer to specific entry in fcb's array of sectors. cb Callback function which gets called for every valid entry fcb_walk encounters. cb_arg Optional. Parameter which gets passed to callback function.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_walk/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_walk/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_walk/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_getnext/",
- "text": "fcb_getnext\n\n\nint fcb_getnext(struct fcb *, struct fcb_entry *loc);\n\n\n\n\n\nGiven element in location in loc, return with loc filled in with information about next element.\n\n\nIf loc-\nle_elem_off is set to 0, fcb_getnext() will return info about the oldest element in FCB.\n\n\nEntry data can be read within the callback using flash_area_read(), using loc-\nfe_area, loc-\nfe_data_off, and loc-\nfe_data_len as arguments.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB where data is written to.\n\n\n\n\n\n\nloc\n\n\nInfo about element. On successful call\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\nReturns FCB_ERR_NOVAR when there are no more elements left.\n\n\nNotes\n\n\nExample",
- "title": "fcb_getnext"
- },
- {
- "location": "/os/modules/fcb/fcb_getnext/#fcb_getnext",
- "text": "int fcb_getnext(struct fcb *, struct fcb_entry *loc); Given element in location in loc, return with loc filled in with information about next element. If loc- le_elem_off is set to 0, fcb_getnext() will return info about the oldest element in FCB. Entry data can be read within the callback using flash_area_read(), using loc- fe_area, loc- fe_data_off, and loc- fe_data_len as arguments.",
- "title": "fcb_getnext"
- },
- {
- "location": "/os/modules/fcb/fcb_getnext/#arguments",
- "text": "Arguments Description fcb Points to FCB where data is written to. loc Info about element. On successful call",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_getnext/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.\nReturns FCB_ERR_NOVAR when there are no more elements left.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_getnext/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_getnext/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_rotate/",
- "text": "fcb_rotate\n\n\nint fcb_rotate(struct fcb *fcb);\n\n\n\n\n\nErase the oldest sector in FCB.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nNotes\n\n\nExample",
- "title": "fcb_rotate"
- },
- {
- "location": "/os/modules/fcb/fcb_rotate/#fcb_rotate",
- "text": "int fcb_rotate(struct fcb *fcb); Erase the oldest sector in FCB.",
- "title": "fcb_rotate"
- },
- {
- "location": "/os/modules/fcb/fcb_rotate/#arguments",
- "text": "Arguments Description fcb Points to FCB.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_rotate/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_rotate/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_rotate/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_append_to_scratch/",
- "text": "fcb_append_to_scratch\n\n\nint fcb_append_to_scratch(struct fcb *fcb);\n\n\n\n\n\nThis can be used if FCB created to have scratch block(s). Once FCB fills up with data, fcb_append() will fail. This routine can be called to start using the reserve block.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; nonzero on failure.\n\n\nNotes\n\n\nExample",
- "title": "fcb_append_to_scratch"
- },
- {
- "location": "/os/modules/fcb/fcb_append_to_scratch/#fcb_append_to_scratch",
- "text": "int fcb_append_to_scratch(struct fcb *fcb); This can be used if FCB created to have scratch block(s). Once FCB fills up with data, fcb_append() will fail. This routine can be called to start using the reserve block.",
- "title": "fcb_append_to_scratch"
- },
- {
- "location": "/os/modules/fcb/fcb_append_to_scratch/#arguments",
- "text": "Arguments Description fcb Points to FCB.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_append_to_scratch/#returned-values",
- "text": "Returns 0 on success; nonzero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_append_to_scratch/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_append_to_scratch/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_is_empty/",
- "text": "fcb_is_empty\n\n\nint fcb_is_empty(struct fcb *fcb);\n\n\n\n\n\nReturns 1 if there are no elements stored in FCB, otherwise returns 0.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB.\n\n\n\n\n\n\n\n\nReturned values\n\n\nSee description.\n\n\nNotes\n\n\nExample",
- "title": "fcb_is_empty"
- },
- {
- "location": "/os/modules/fcb/fcb_is_empty/#fcb_is_empty",
- "text": "int fcb_is_empty(struct fcb *fcb); Returns 1 if there are no elements stored in FCB, otherwise returns 0.",
- "title": "fcb_is_empty"
- },
- {
- "location": "/os/modules/fcb/fcb_is_empty/#arguments",
- "text": "Arguments Description fcb Points to FCB.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_is_empty/#returned-values",
- "text": "See description.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_is_empty/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_is_empty/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_offset_last_n/",
- "text": "fcb_offset_last_n\n\n\nint fcb_offset_last_n(struct fcb *fcb, uint8_t entries, uint32_t *last_n_off);\n\n\n\n\n\nReturns the offset of n-th last element.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB.\n\n\n\n\n\n\nentries\n\n\nHow many entries to leave.\n\n\n\n\n\n\nlast_n_off\n\n\nReturned offset.\n\n\n\n\n\n\n\n\nReturned values\n\n\n0 on success; non-zero on failure.\n\n\nNotes\n\n\nReturned offset is relative to beginning of the sector where the element is.\nTherefore, n-th last element must be found within the last sector of FCB.\n\n\nExample",
- "title": "fcb_offset_last_n"
- },
- {
- "location": "/os/modules/fcb/fcb_offset_last_n/#fcb_offset_last_n",
- "text": "int fcb_offset_last_n(struct fcb *fcb, uint8_t entries, uint32_t *last_n_off); Returns the offset of n-th last element.",
- "title": "fcb_offset_last_n"
- },
- {
- "location": "/os/modules/fcb/fcb_offset_last_n/#arguments",
- "text": "Arguments Description fcb Points to FCB. entries How many entries to leave. last_n_off Returned offset.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_offset_last_n/#returned-values",
- "text": "0 on success; non-zero on failure.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_offset_last_n/#notes",
- "text": "Returned offset is relative to beginning of the sector where the element is.\nTherefore, n-th last element must be found within the last sector of FCB.",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_offset_last_n/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/fcb/fcb_clear/",
- "text": "fcb_clear\n\n\nint fcb_clear(struct fcb *fcb);\n\n\n\n\n\nWipes out all data in FCB.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfcb\n\n\nPoints to FCB.\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns 0 on success; non-zero otherwise.\n\n\nNotes\n\n\nExample",
- "title": "fcb_clear"
- },
- {
- "location": "/os/modules/fcb/fcb_clear/#fcb_clear",
- "text": "int fcb_clear(struct fcb *fcb); Wipes out all data in FCB.",
- "title": "fcb_clear"
- },
- {
- "location": "/os/modules/fcb/fcb_clear/#arguments",
- "text": "Arguments Description fcb Points to FCB.",
- "title": "Arguments"
- },
- {
- "location": "/os/modules/fcb/fcb_clear/#returned-values",
- "text": "Returns 0 on success; non-zero otherwise.",
- "title": "Returned values"
- },
- {
- "location": "/os/modules/fcb/fcb_clear/#notes",
- "text": "",
- "title": "Notes"
- },
- {
- "location": "/os/modules/fcb/fcb_clear/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/stats/stats/",
- "text": "Statistics Module\n\n\nThe statistics module allows application, libraries, or drivers to\nrecord statistics that can be shown via the Newtmgr tool and console.\n\n\nThis allows easy integration of statistics for troubleshooting,\nmaintenance, and usage monitoring.\n\n\nBy creating and registering your statistics, they are automatically\nincluded in the Newtmgr shell and console APIs.\n\n\nImplementation Details\n\n\nA statistic is an unsigned integer that can be set by the \ncode. When building stats, the implementer chooses the size of the \nstatistic depending on the frequency of the statistic and the \nresolution required before the counter wraps. \n\n\nTypically the stats are incremented upon code events; however, they are \nnot limted to that purpose. \n\n\nStats are organized into sections. Each section of stats has its own\nname and can be queried separately through the API. Each section of stats\nalso has its own statistic size, allowing the user to separate large (64-bit)\nstatistics from small (16 bit statistics). NOTE: It is not currently possible\nto group different size stats into the same section. Please ensure all stats\nin a section have the same size.\n\n\nStats sections are currently stored in a single global stats group. \n\n\nStatistics are stored in a simple structure which contains a small\nstats header followed by a list of stats. The stats header contains:\n\n\nstruct stats_hdr {\n char *s_name;\n uint8_t s_size;\n uint8_t s_cnt;\n uint16_t s_pad1;\n#if MYNEWT_VAL(STATS_NAMES)\n const struct stats_name_map *s_map;\n int s_map_cnt;\n#endif\n STAILQ_ENTRY(stats_hdr) s_next;\n };\n\n\n\n\n\nThe fields define with in the \n#if MYNEWT_VAL(STATS_NAME)\n directive are only inincluded when the \nSTATS_NAMES\n syscfg setting is set to 1 and enables use statistic names.\n\n\n\nEnabling Statistic Names\n\n\nBy default, statistics are queried by number. You can use the \nSTATS_NAMES\n syscfg setting to enable statistic names and view the results by name. Enabling statistic names provides better descriptions in the reported statistics, but takes code space to store the strings within the image.\n\n\nTo enable statistic names, set the \nSTATS_NAMES\n value to 1 in the application \nsyscfg.yml\n file or use the \nnewt target set\n command to set the syscfg setting value. Here are examples for each method:\n\n\nMethod 1 - Set the value in the application \nsyscfg.yml\n files:\n\n\n\n# Package: apps/myapp\n\nsyscfg.vals:\n STATS_NAMES: 1\n\n\n\n\n\n\n\nMethod 2 - Set the target \nsyscfg\n variable: \n\n\nnewt target set myapp syscfg=STATS_NAMES=1\n\n\n\n\n\nNote:\n This \nnewt target set\n command only sets the syscfg variable for the \nSTATS_NAMES\n setting as an example. For your target, you should set the syscfg variable with the other settings that you want to override. \n\n\n\n\nAdding Stats to your code.\n\n\nCreating new stats table requires the following steps.\n\n\n\n\nInclude the stats header file \n\n\nDefine a stats section\n\n\nDeclare an instance of the section \n\n\nDefine the stat sections names table\n\n\nImplement stat in your code\n\n\nInitialize the stats\n\n\nRegister the stats\n\n\n\n\n\n\nInclude the stats header file\n\n\nAdd the stats library to your pkg.yml file for your package or app by adding\nthis line to your package dependencies.\n\n\npkg.deps:\n - \n@apache-mynewt-core/sys/stats\n\n\n\n\n\n\n\n\nAdd this include directive to code files using the stats library.\n\n\n#include \nstats/stats.h\n\n\n\n\n\n\n\n\nDefine a stats section\n\n\nYou must use the \nstats.h\n macros to define your stats table. A \nstats section definition looks like this. \n\n\nSTATS_SECT_START(my_stat_section)\n STATS_SECT_ENTRY(attempt_stat)\n STATS_SECT_ENTRY(error_stat)\nSTATS_SECT_END\n\n\n\n\n\n\n\nIn this case we chose to make the stats 32-bits each. \nstats.h\n supports three\ndifferent stats sizes through the following macros:\n\n\n\n\nSTATS_SIZE_16\n -- stats are 16 bits (wraps at 65536)\n\n\nSTATS_SIZE_32\n -- stats are 32 bits (wraps at 4294967296)\n\n\nSTATS_SIZE_64\n -- stats are 64-bits\n\n\n\n\nWhen this compiles/pre-processes, it produces a structure definition like this\n\n\nstruct stats_my_stat_section { \n struct stats_hdr s_hdr;\n uint32_t sattempt_stat;\n uint32_t serror_stat;\n};\n\n\n\n\n\n\n\nYou can see that the defined structure has a small stats structure\nheader and the two stats we have defined.\n\n\nDepending on whether these stats are used in multiple modules, you may need\nto include this definition in a header file.\n\n\n\n\nDeclaring a variable to hold the stats\n\n\nDeclare the global variable to hold your statistics. Since it is possible to\nhave multiple copies of the same section (for example a stat section for\neach of 5 identical peripherals), the variable name of the stats section \nmust be unique.\n\n\nSTATS_SECT_DECL(my_stat_section) g_mystat;\n\n\n\n\n\n\n\nAgain, if your stats section is used in multiple C files you will need to \ninclude the above definition in one of the C files and 'extern' this declaration \nin your header file.\n\n\nextern STATS_SECT_DECL(my_stat_section) g_mystat;\n\n\n\n\n\n\n\nDefine the stats section name table\n\n\nWhether or not you have \nSTATS_NAMES\n enabled, you must define \na stats name table. If \nSTATS_NAMES\n is not enabled, this will \nnot take any code space or image size. \n\n\n/* define a few stats for querying */\nSTATS_NAME_START(my_stat_section)\n STATS_NAME(my_stat_section, attempt_stat)\n STATS_NAME(my_stat_section, error_stat)\nSTATS_NAME_END(my_stat_section)\n\n\n\n\n\n\n\nWhen compiled by the preprocessor, it creates a structure that looks like this.\n\n\nstruct stats_name_map g_stats_map_my_stat_section[] = {\n { __builtin_offsetof (struct stats_my_stat_section, sattempt_stat), \nattempt_stat\n },\n { __builtin_offsetof (struct stats_my_stat_section, serror_stat), \nerror_stat\n },\n};\n\n\n\n\n\n\n\nThis table will allow the UI components to find a nice string name for the \nstat.\n\n\n\n\nImplement stats in your code.\n\n\nYou can use the \nSTATS_INC\n or \nSTATS_INCN\n macros to increment your statistics\nwithin your C-code. For example, your code may do this:\n\n\n STATS_INC(g_mystat, attempt_stat);\n rc = do_task();\n if(rc == ERR) { \n STATS_INC(g_mystat, error_stat); \n }\n\n\n\n\n\n\n\nInitialize the statistics\n\n\nYou must initialize the stats so they can be operated on by the stats\nlibrary. As per our example above, it would look like the following.\n\n\nThis tells the system how large each statistic is and the number of \nstatistics in the section. It also initialize the name information for\nthe statistics if enabled as shown above.\n\n\n rc = stats_init(\n STATS_HDR(g_mystat), \n STATS_SIZE_INIT_PARMS(g_mystat, STATS_SIZE_32), \n STATS_NAME_INIT_PARMS(my_stat_section));\n assert(rc == 0);\n\n\n\n\n\n\n\nRegister the statistic section\n\n\nIf you want the system to know about your stats, you must register them.\n\n\n rc = stats_register(\nmy_stats\n, STATS_HDR(g_mystat));\n assert(rc == 0);\n\n\n\n\n\n\n\nThere is also a method that does initialization and registration at the \nsame time, called \nstats_init_and_reg\n.\n\n\n\n\nRetrieving stats through console or Newtmgr\n\n\nIf you enable console in your project you can see stats through the \nserial port defined.\n\n\nThis is the stats as shown from the example above with names enabled.\n\n\nstat my_stats\n12274:attempt_stat: 3\n12275:error_stat: 0\n\n\n\n\n\n\n\nThis is the stats as shown from the example without names enabled.\n\n\nstat my_stats\n29149:s0: 3\n29150:s1: 0\n\n\n\n\n\n\n\nA note on multiple stats sections\n\n\nIf you are implementing a device with multiple instances, you may\nwant multiple stats sections with the exact same format.\n\n\nFor example, suppose I write a driver for an external distance sensor. My\ndriver supports up to 5 sensors and I want to record the stats of \neach device separately.\n\n\nThis works identically to the example above, except you would need to \nregister each one separately with a unique name. The stats system will\nnot let two sections be entered with the same name.",
- "title": "toc"
- },
- {
- "location": "/os/modules/stats/stats/#statistics-module",
- "text": "The statistics module allows application, libraries, or drivers to\nrecord statistics that can be shown via the Newtmgr tool and console. This allows easy integration of statistics for troubleshooting,\nmaintenance, and usage monitoring. By creating and registering your statistics, they are automatically\nincluded in the Newtmgr shell and console APIs.",
- "title": "Statistics Module"
- },
- {
- "location": "/os/modules/stats/stats/#implementation-details",
- "text": "A statistic is an unsigned integer that can be set by the \ncode. When building stats, the implementer chooses the size of the \nstatistic depending on the frequency of the statistic and the \nresolution required before the counter wraps. Typically the stats are incremented upon code events; however, they are \nnot limted to that purpose. Stats are organized into sections. Each section of stats has its own\nname and can be queried separately through the API. Each section of stats\nalso has its own statistic size, allowing the user to separate large (64-bit)\nstatistics from small (16 bit statistics). NOTE: It is not currently possible\nto group different size stats into the same section. Please ensure all stats\nin a section have the same size. Stats sections are currently stored in a single global stats group. Statistics are stored in a simple structure which contains a small\nstats header followed by a list of stats. The stats header contains: struct stats_hdr {\n char *s_name;\n uint8_t s_size;\n uint8_t s_cnt;\n uint16_t s_pad1;\n#if MYNEWT_VAL(STATS_NAMES)\n const struct stats_name_map *s_map;\n int s_map_cnt;\n#endif\n STAILQ_ENTRY(stats_hdr) s_next;\n }; The fields define with in the #if MYNEWT_VAL(STATS_NAME) directive are only inincluded when the STATS_NAMES syscfg setting is set to 1 and enables use statistic names.",
- "title": "Implementation Details"
- },
- {
- "location": "/os/modules/stats/stats/#enabling-statistic-names",
- "text": "By default, statistics are queried by number. You can use the STATS_NAMES syscfg setting to enable statistic names and view the results by name. Enabling statistic names provides better descriptions in the reported statistics, but takes code space to store the strings within the image. To enable statistic names, set the STATS_NAMES value to 1 in the application syscfg.yml file or use the newt target set command to set the syscfg setting value. Here are examples for each method: Method 1 - Set the value in the application syscfg.yml files: # Package: apps/myapp\n\nsyscfg.vals:\n STATS_NAMES: 1 Method 2 - Set the target syscfg variable: newt target set myapp syscfg=STATS_NAMES=1 Note: This newt target set command only sets the syscfg variable for the STATS_NAMES setting as an example. For your target, you should set the syscfg variable with the other settings that you want to override.",
- "title": "Enabling Statistic Names"
- },
- {
- "location": "/os/modules/stats/stats/#adding-stats-to-your-code",
- "text": "Creating new stats table requires the following steps. Include the stats header file Define a stats section Declare an instance of the section Define the stat sections names table Implement stat in your code Initialize the stats Register the stats",
- "title": "Adding Stats to your code."
- },
- {
- "location": "/os/modules/stats/stats/#include-the-stats-header-file",
- "text": "Add the stats library to your pkg.yml file for your package or app by adding\nthis line to your package dependencies. pkg.deps:\n - @apache-mynewt-core/sys/stats Add this include directive to code files using the stats library. #include stats/stats.h",
- "title": "Include the stats header file"
- },
- {
- "location": "/os/modules/stats/stats/#define-a-stats-section",
- "text": "You must use the stats.h macros to define your stats table. A \nstats section definition looks like this. STATS_SECT_START(my_stat_section)\n STATS_SECT_ENTRY(attempt_stat)\n STATS_SECT_ENTRY(error_stat)\nSTATS_SECT_END In this case we chose to make the stats 32-bits each. stats.h supports three\ndifferent stats sizes through the following macros: STATS_SIZE_16 -- stats are 16 bits (wraps at 65536) STATS_SIZE_32 -- stats are 32 bits (wraps at 4294967296) STATS_SIZE_64 -- stats are 64-bits When this compiles/pre-processes, it produces a structure definition like this struct stats_my_stat_section { \n struct stats_hdr s_hdr;\n uint32_t sattempt_stat;\n uint32_t serror_stat;\n}; You can see that the defined structure has a small stats structure\nheader and the two stats we have defined. Depending on whether these stats are used in multiple modules, you may need\nto include this definition in a header file.",
- "title": "Define a stats section"
- },
- {
- "location": "/os/modules/stats/stats/#declaring-a-variable-to-hold-the-stats",
- "text": "Declare the global variable to hold your statistics. Since it is possible to\nhave multiple copies of the same section (for example a stat section for\neach of 5 identical peripherals), the variable name of the stats section \nmust be unique. STATS_SECT_DECL(my_stat_section) g_mystat; Again, if your stats section is used in multiple C files you will need to \ninclude the above definition in one of the C files and 'extern' this declaration \nin your header file. extern STATS_SECT_DECL(my_stat_section) g_mystat;",
- "title": "Declaring a variable to hold the stats"
- },
- {
- "location": "/os/modules/stats/stats/#define-the-stats-section-name-table",
- "text": "Whether or not you have STATS_NAMES enabled, you must define \na stats name table. If STATS_NAMES is not enabled, this will \nnot take any code space or image size. /* define a few stats for querying */\nSTATS_NAME_START(my_stat_section)\n STATS_NAME(my_stat_section, attempt_stat)\n STATS_NAME(my_stat_section, error_stat)\nSTATS_NAME_END(my_stat_section) When compiled by the preprocessor, it creates a structure that looks like this. struct stats_name_map g_stats_map_my_stat_section[] = {\n { __builtin_offsetof (struct stats_my_stat_section, sattempt_stat), attempt_stat },\n { __builtin_offsetof (struct stats_my_stat_section, serror_stat), error_stat },\n}; This table will allow the UI components to find a nice string name for the \nstat.",
- "title": "Define the stats section name table"
- },
- {
- "location": "/os/modules/stats/stats/#implement-stats-in-your-code",
- "text": "You can use the STATS_INC or STATS_INCN macros to increment your statistics\nwithin your C-code. For example, your code may do this: STATS_INC(g_mystat, attempt_stat);\n rc = do_task();\n if(rc == ERR) { \n STATS_INC(g_mystat, error_stat); \n }",
- "title": "Implement stats in your code."
- },
- {
- "location": "/os/modules/stats/stats/#initialize-the-statistics",
- "text": "You must initialize the stats so they can be operated on by the stats\nlibrary. As per our example above, it would look like the following. This tells the system how large each statistic is and the number of \nstatistics in the section. It also initialize the name information for\nthe statistics if enabled as shown above. rc = stats_init(\n STATS_HDR(g_mystat), \n STATS_SIZE_INIT_PARMS(g_mystat, STATS_SIZE_32), \n STATS_NAME_INIT_PARMS(my_stat_section));\n assert(rc == 0);",
- "title": "Initialize the statistics"
- },
- {
- "location": "/os/modules/stats/stats/#register-the-statistic-section",
- "text": "If you want the system to know about your stats, you must register them. rc = stats_register( my_stats , STATS_HDR(g_mystat));\n assert(rc == 0); There is also a method that does initialization and registration at the \nsame time, called stats_init_and_reg .",
- "title": "Register the statistic section"
- },
- {
- "location": "/os/modules/stats/stats/#retrieving-stats-through-console-or-newtmgr",
- "text": "If you enable console in your project you can see stats through the \nserial port defined. This is the stats as shown from the example above with names enabled. stat my_stats\n12274:attempt_stat: 3\n12275:error_stat: 0 This is the stats as shown from the example without names enabled. stat my_stats\n29149:s0: 3\n29150:s1: 0",
- "title": "Retrieving stats through console or Newtmgr"
- },
- {
- "location": "/os/modules/stats/stats/#a-note-on-multiple-stats-sections",
- "text": "If you are implementing a device with multiple instances, you may\nwant multiple stats sections with the exact same format. For example, suppose I write a driver for an external distance sensor. My\ndriver supports up to 5 sensors and I want to record the stats of \neach device separately. This works identically to the example above, except you would need to \nregister each one separately with a unique name. The stats system will\nnot let two sections be entered with the same name.",
- "title": "A note on multiple stats sections"
- },
- {
- "location": "/os/modules/logs/logs/",
- "text": "Logging\n\n\nMynewt log package supports logging of information within a Mynewt application. It allows packages to define their own log streams with separate names. It also allows an application to control the output destination of logs. \n\n\n\nDescription\n\n\nIn the Mynewt OS, the log package comes in two versions:\n\n\n\n\n\n\nThe \nsys/log/full\n package implements the complete log functionality and API.\n\n\n\n\n\n\nThe \nsys/log/stub\n package implements stubs for the API.\n\n\n\n\n\n\nBoth packages export the \nlog\n API, and any package that uses the log API must list \nlog\n as a requirement in its \npkg.yml\n file as follows: \n\n\npkg.req_apis:\n - log\n\n\n\n\n\n\nThe application's \npkg.yml\n file specifies the version of the log package to use.\nA project that requires the full logging capability must list the \nsys/log/full\n package as a dependency in its \npkg.yml\n file:\n\n\npkg.deps:\n - sys/log/full\n\n\n\n\n\n\nYou can use the \nsys/log/stub\n package if you want to build your application without logging to reduce code size.\n\n\n\n\nCompile Time Settings\n\n\nTo save space at compile time, there is a compile time log level that\nincludes/excludes certain logs at compile time, saving image space. For \nexample, during debug, you can have significant logs present, but disable\nthese at compile time to ensure the code size limits are met.\n\n\nA compiler flag \nLOG_LEVEL\n can be set in your \ntarget.cflags\n or within\nyour app \npkg.cflags\n files to set the compile time log level. The \nlog level are defined in \n/sys/log/full/include/log/log.h\n\nbut must be added by number to your \nyml\n file.\n\n\nFor example:\n\n\n pkg.cflags -DLOG_LEVEL=3\n\n\n\n\n\nor \n\n\n newt target set my_target cflags=-DLOG_LEVEL=3\n\n\n\n\n\nwould both set the compile-time log level to \nLOG_LEVEL_ERROR\n. All logs\nof less than \nLOG_LEVEL_ERROR\n severity would be disabled at compile \ntime and take no space within the Mynewt application image.\n\n\nThese compile time settings are applicable to all logs registered with the\nsystem.\n\n\n\n\nLog\n\n\nEach log stream requires a \nlog\n structure to define its logging properties. \n\n\n\nLog Handler\n\n\nTo use logs, a log handler that handles the I/O from the log is required. The log package comes with three pre-built log handlers:\n\n\n\n\nconsole -- streams log events directly to the console port. Does\nnot support walking and reading.\n\n\ncbmem -- writes/reads log events to a circular buffer. Supports walking \nand reading for access by newtmgr and shell commands.\n\n\nfcb -- writes/reads log events to a \nflash circular buffer\n. Supports walking and reading for access by newtmgr and shell commands.\n\n\n\n\nIn addition, it is possible to create custom log handlers for other methods.\nExamples may include\n\n\n\n\nFlash file system\n\n\nFlat flash buffer\n\n\nStreamed over some other interface\n\n\n\n\nTo use logging, you typically do not need to create your own log handler. You can use one of the pre-built ones.\n\n\nA package or an application must define a variable of type \nstruct log\n and register a log handler for it with the log package. It must call the \nlog_register()\n function to specify the log handler to use:\n\n\nlog_register\n(\nchar\n \n*name\n, \nstruct\n \nlog\n \n*log\n, \nconst\n \nstruct\n \nlog_handler\n \n*lh\n, \nvoid\n \n*arg\n, \nuint8_t\n \nlevel\n)\n\n\n\n\n\nThe parameters are:\n\n\n\n\nname\n- Name of the log stream.\n\n\nlog\n - Log instance to register,\n\n\nlh\n - Pointer to the log handler. You can specify one of the pre-built ones: \n\n\nlog_console_handler\n for console\n\n\nlog_cbm_handler\n for circular buffer \n\n\nlog_fcb_handler\n for flash circular buffer\n\n\n\n\n\n\narg\n - Opaque argument that the specified log handler uses. The value of this argument depends on the log handler you specify:\n\n\nNULL for the \nlog_console_handler\n.\n\n\nPointer to an initialized \ncbmem\n structure (see \nutil/cbmem\n package) for the \nlog_cbm_handler\n.\n\n\nPointer to an initialized \nfcb_log\n structure (see \nfs/fcb\n package) for the \nlog_fcb_handler\n. \n\n\n\n\n\n\n\n\nTypically, a package that uses logging defines a global variable, such as \nmy_package_log\n, of type \nstruct log\n. The package can call the \nlog_register()\n function with default values, but usually an application will override the logging properties and where to log to. There are two ways a package can allow an application to override the values:\n\n\n\n\nDefine system configuration settings that an application can set and the package can then call the \nlog_register()\n function with the configuration values.\n\n\nMake the \nmy_package_log\n variable external and let the application call the \nlog_register()\n function to specify a log handler for its specific purpose. \n\n\n\n\nConfiguring Logging for Packages that an Application Uses\n\n\nHere is an example of how an application can set the log handlers for the logs of the packages that the application includes. \n\n\nIn this example, the \npackage1\n package defines the variable \npackage1_log\n of type \nstruct log\n and externs the variable. Similarly, the \npackage2\n package defines the variable \npackage2_log\n and externs the variable. The application sets logs for \npackage1\n to use console and sets logs for \npackage2\n to use a circular buffer.\n\n\n#include\n \npackage1/package1.h\n\n\n#include\n \npackage2/package2.h\n\n\n#include\n \nutil/cbmem.h\n\n\n\n#include\n \nlog/log.h\n\n\n\nstatic\n \nuint32_t\n \ncbmem_buf\n[\nMAX_CBMEM_BUF\n];\n\nstatic\n \nstruct\n \ncbmem\n \ncbmem\n;\n\n\n\nvoid\n \napp_log_init\n(\nvoid\n)\n{\n\n\n\n \nlog_register\n(\npackage1_log\n, \npackage1_log\n, \nlog_console_handler\n, \nNULL\n, \nLOG_SYSLEVEL\n);\n\n \ncbmem_init\n(\ncbmem\n, \ncbmem_buf\n, \nMAX_CBMEM_BUF\n);\n \nlog_register\n(\npackage2_log\n, \npackage2_log\n, \nlog_cbmem_handler\n, \ncbmem\n, \nLOG_SYSLEVEL\n);\n\n}\n\n\n\n\n\n\n\nImplementing a Package that Uses Logging\n\n\nThis example shows how a package logs to console. The package registers default logging properties to use the console, but allows an application to override the values. It defines the \nmy_package_log\n variable and makes it external so an application can override log handler.\n\n\nMake the \nmy_package_log\n variable external:\n\n\n/* my_package.h*/\n\n\n\n/* pick a unique name here */\n\n\nextern\n \nstruct\n \nlog\n \nmy_package_log\n;\n\n\n\n\n\n\n\nDefine the \nmy_package_log\n variable and register the console log handler: \n\n\n/* my_package.c */\n\n\n\nstruct\n \nlog\n \nmy_package_log\n;\n\n{\n ...\n\n \n/* register my log with a name to the system */\n\n \nlog_register\n(\nlog\n, \nmy_package_log\n, \nlog_console_handler\n, \nNULL\n, \nLOG_LEVEL_DEBUG\n);\n\n \nLOG_DEBUG\n(\nmy_package_log\n, \nLOG_MODULE_DEFAULT\n, \nbla\n);\n \nLOG_DEBUG\n(\nmy_package_log\n, \nLOG_MODULE_DEFAULT\n, \nbab\n);\n}\n\n\n\n\n\nLog API and Log Levels\n\n\nFor more information on the \nlog\n API and log levels, see the \nsys/log/full/include/log/log.h\n header file.",
- "title": "toc"
- },
- {
- "location": "/os/modules/logs/logs/#logging",
- "text": "Mynewt log package supports logging of information within a Mynewt application. It allows packages to define their own log streams with separate names. It also allows an application to control the output destination of logs.",
- "title": "Logging"
- },
- {
- "location": "/os/modules/logs/logs/#description",
- "text": "In the Mynewt OS, the log package comes in two versions: The sys/log/full package implements the complete log functionality and API. The sys/log/stub package implements stubs for the API. Both packages export the log API, and any package that uses the log API must list log as a requirement in its pkg.yml file as follows: pkg.req_apis:\n - log \nThe application's pkg.yml file specifies the version of the log package to use.\nA project that requires the full logging capability must list the sys/log/full package as a dependency in its pkg.yml file: pkg.deps:\n - sys/log/full \nYou can use the sys/log/stub package if you want to build your application without logging to reduce code size.",
- "title": "Description"
- },
- {
- "location": "/os/modules/logs/logs/#compile-time-settings",
- "text": "To save space at compile time, there is a compile time log level that\nincludes/excludes certain logs at compile time, saving image space. For \nexample, during debug, you can have significant logs present, but disable\nthese at compile time to ensure the code size limits are met. A compiler flag LOG_LEVEL can be set in your target.cflags or within\nyour app pkg.cflags files to set the compile time log level. The \nlog level are defined in /sys/log/full/include/log/log.h \nbut must be added by number to your yml file. For example: pkg.cflags -DLOG_LEVEL=3 or newt target set my_target cflags=-DLOG_LEVEL=3 would both set the compile-time log level to LOG_LEVEL_ERROR . All logs\nof less than LOG_LEVEL_ERROR severity would be disabled at compile \ntime and take no space within the Mynewt application image. These compile time settings are applicable to all logs registered with the\nsystem.",
- "title": "Compile Time Settings"
- },
- {
- "location": "/os/modules/logs/logs/#log",
- "text": "Each log stream requires a log structure to define its logging properties.",
- "title": "Log"
- },
- {
- "location": "/os/modules/logs/logs/#log-handler",
- "text": "To use logs, a log handler that handles the I/O from the log is required. The log package comes with three pre-built log handlers: console -- streams log events directly to the console port. Does\nnot support walking and reading. cbmem -- writes/reads log events to a circular buffer. Supports walking \nand reading for access by newtmgr and shell commands. fcb -- writes/reads log events to a flash circular buffer . Supports walking and reading for access by newtmgr and shell commands. In addition, it is possible to create custom log handlers for other methods.\nExamples may include Flash file system Flat flash buffer Streamed over some other interface To use logging, you typically do not need to create your own log handler. You can use one of the pre-built ones. A package or an application must define a variable of type struct log and register a log handler for it with the log package. It must call the log_register() function to specify the log handler to use: log_register ( char *name , struct log *log , const struct log_handler *lh , void *arg , uint8_t level ) The parameters are: name - Name of the log stream. log - Log instance to register, lh - Pointer to the log handler. You can specify one of the pre-built ones: log_console_handler for console log_cbm_handler for circular buffer log_fcb_handler for flash circular buffer arg - Opaque argument that the specified log handler uses. The value of this argument depends on the log handler you specify: NULL for the log_console_handler . Pointer to an initialized cbmem structure (see util/cbmem package) for the log_cbm_handler . Pointer to an initialized fcb_log structure (see fs/fcb package) for the log_fcb_handler . Typically, a package that uses logging defines a global variable, such as my_package_log , of type struct log . The package can call the log_register() function with default values, but usually an application will override the logging properties and where to log to. There are two ways a package can allow an application to override the values: Define system configuration settings that an application can set and the package can then call the log_register() function with the configuration values. Make the my_package_log variable external and let the application call the log_register() function to specify a log handler for its specific purpose.",
- "title": "Log Handler"
- },
- {
- "location": "/os/modules/logs/logs/#configuring-logging-for-packages-that-an-application-uses",
- "text": "Here is an example of how an application can set the log handlers for the logs of the packages that the application includes. In this example, the package1 package defines the variable package1_log of type struct log and externs the variable. Similarly, the package2 package defines the variable package2_log and externs the variable. The application sets logs for package1 to use console and sets logs for package2 to use a circular buffer. #include package1/package1.h #include package2/package2.h #include util/cbmem.h #include log/log.h static uint32_t cbmem_buf [ MAX_CBMEM_BUF ]; static struct cbmem cbmem ; void app_log_init ( void )\n{\n\n\n\n log_register ( package1_log , package1_log , log_console_handler , NULL , LOG_SYSLEVEL );\n\n cbmem_init ( cbmem , cbmem_buf , MAX_CBMEM_BUF );\n log_register ( package2_log , package2_log , log_cbmem_handler , cbmem , LOG_SYSLEVEL );\n\n}",
- "title": "Configuring Logging for Packages that an Application Uses"
- },
- {
- "location": "/os/modules/logs/logs/#implementing-a-package-that-uses-logging",
- "text": "This example shows how a package logs to console. The package registers default logging properties to use the console, but allows an application to override the values. It defines the my_package_log variable and makes it external so an application can override log handler. Make the my_package_log variable external: /* my_package.h*/ /* pick a unique name here */ extern struct log my_package_log ; Define the my_package_log variable and register the console log handler: /* my_package.c */ struct log my_package_log ;\n\n{\n ...\n\n /* register my log with a name to the system */ \n log_register ( log , my_package_log , log_console_handler , NULL , LOG_LEVEL_DEBUG );\n\n LOG_DEBUG ( my_package_log , LOG_MODULE_DEFAULT , bla );\n LOG_DEBUG ( my_package_log , LOG_MODULE_DEFAULT , bab );\n}",
- "title": "Implementing a Package that Uses Logging"
- },
- {
- "location": "/os/modules/logs/logs/#log-api-and-log-levels",
- "text": "For more information on the log API and log levels, see the sys/log/full/include/log/log.h header file.",
- "title": "Log API and Log Levels"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/",
- "text": "System Configuration and Initialization\n\n\nThis guide describes how Mynewt manages system configuration and initialization. It shows you how to \ntell Mynewt to use default or customized values to initialize packages that you develop or use to build a target. This guide:\n\n\n\n\nAssumes you have read the \nConcepts\n section that describes the Mynewt \npackage hierarchy and its use of the \npkg.yml\n and \nsyscfg.yml\n files. \n\n\nAssumes you have read the \nNewt Tool Theory of Operation\n and are familiar with how newt determines \npackage dependencies for your target build.\n\n\nCovers only the system initialization for hardware independent packages. It does not cover the Board Support Package (BSP) and other hardware dependent system initialization. \n\n\n\n\nMynewt defines several configuration parameters in the \npkg.yml\n and \nsyscfg.yml\n files. The newt tool uses this information to: \n\n\n\n\nGenerate a system initialization function that calls all the package-specific system initialization functions. \n\n\nGenerate a system configuration header file that contains all the package configuration settings and values.\n\n\nDisplay the system configuration settings and values in the \nnewt target config\n command.\n\n\n\n\nThe benefits with this approach include:\n\n\n\n\nAllows Mynewt developers to reuse other packages and easily change their configuration settings without updating source or header files when implementing new packages.\n\n\nAllows application developers to easily view the system configuration settings and values and determine the values to override for a target build.\n\n\n\n\n\n\nSystem Configuration Setting Definitions and Values\n\n\nA package can optionally:\n\n\n\n\nDefine and expose the system configuration settings to allow other packages to override \nthe default setting values. \n\n\nOverride the system configuration setting values defined by the packages that it depends on. \n\n\n\n\nYou use the \ndefs\n parameter in a \nsyscfg.yml\n file to define the system configuration settings \nfor a package. \ndefs\n is a mapping (or associative array) of system configuration setting definitions. It \nhas the following syntax: \n\n\nsyscfg.defs:\n PKGA_SYSCFG_NAME1:\n description:\n value:\n type:\n restrictions:\n PKGA_SYSCFG_NAME2:\n description:\n value:\n type:\n restrictions:\n\n\n\n\n\n\n\nEach setting definition consists of the following key-value mapping: \n\n\n\n\nA setting name for the key, such as \nPKGA_SYSCFG_NAME1\n in the syntax example above.\n\nNote:\n A system configuration setting name must be unique. The newt tool aborts the build \nwhen multiple packages define the same setting. \n\n\nA mapping of fields for the value. Each field itself is a key-value pair of attributes. The field keys are \ndescription\n, \nvalue\n, \ntype\n, and \nrestrictions\n. They are described in \nfollowing table:\n\n\n\n\n\n\n\n\nField\n\n\nDescription\n\n\n\n\n\n\ndescription\n\n\nDescribes the usage for the setting. \nThis field is optional.\n\n\n\n\nvalue\n\n\nSpecifies the default value for the setting. \nThis field is required.\n The value depends on the \ntype\n that you specify and can be an empty string. \n\n\n\ntype\n\n\nSpecifies the data type for the \nvalue\n field. \nThis field is optional.\n You can specify one of three types:\n\n\n\nraw\n - The \nvalue\n data is uninterpreted. This is the default \ntype\n.\n\n\ntask_priority\n - Specifies a Mynewt task priority number. The task priority number assigned to each setting must be unique and between 0 and 239. \nvalue\n can be one of the following: \n\n\n\nA number between 0 and 239 - The task priority number to use for the setting.\n\n\nany\n - Specify \nany\n to have newt automatically assign a priority for the setting. \nnewt alphabetically orders all system configuration settings of this type and assigns the next highest available \ntask priority number to each setting. \n\n\n\n\n\n\nflash_owner\n - Specifies a flash area. The \nvalue\n should be the name of a flash area \ndefined in the BSP flash map for your target board. \n\n\n\n\n\n\n\n\n\n\n\nrestrictions\n\n\nSpecifies a list of restrictions on the setting value. \nThis field is optional.\n You can specify two formats:\n\n\n\n$notnull\n - Specifies that the setting cannot have the empty string for a value. It essentially means that an empty string is not a sensible value and a package must override it with an appropriate value. \n\n\n\n\n\nexpression\n - Specifies a boolean expression of the form \n[!]\n>[if \n>]\n\n\nExamples:\n\n\n\nrestrictions: !LOG_FCB\n - When this setting is enabled, \nLOG_FCB\n must be disabled.\n\nrestrictions: LOG_FCB if 0 \n - When this setting is disabled, \nLOG_FCB\n must be enabled.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nExamples of Configuration Settings\n\n\nExample 1:\n The following example is an excerpt from the \nsys/log/full\n package \nsyscfg.yml\n file. It defines the \n\nLOG_LEVEL\n configuration setting to specify the log level and the \nLOG_NEWTMGR\n configuration setting to specify whether\nto enable or disable the newtmgr logging feature.\n\n\nsyscfg.defs:\n LOG_LEVEL:\n description: \nLog Level\n\n value: 0\n type: raw\n\n ... \n\n LOG_NEWTMGR: \n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n\n\n\n\n\n\nExample 2:\n The following example is an excerpt from the \nnet/nimble/controller\n package \nsyscfg.yml\n file. It defines the \nBLE_LL_PRIO\n \nconfiguration setting with a \ntask_priority\n type and assigns task priority 0 to the BLE link layer task.\n\n\nsyscfg.defs:\n BLE_LL_PRIO:\n description: \nBLE link layer task priority\n\n type: \ntask_priority\n\n value: 0\n\n\n\n\n\n\n\nExample 3:\n The following example is an excerpt from the \nfs/nffs\n package \nsyscfg.yml\n file. \n\n\nsyscfg.defs:\n NFFS_FLASH_AREA:\n description: \nThe flash area to use for the Newtron Flash File System\n\n type: flash_owner\n value:\n restrictions:\n - $notnull\n\n\n\n\n\nIt defines the \nNFFS_FLASH_AREA\n configuration setting with a \nflash_owner\n type indicating that a flash area needs to be specified for the Newtron Flash File System. The flash areas are typically defined by the BSP in its \nbsp.yml\n file. For example, the \nbsp.yml\n for nrf52dk board (\nhw/bsp/nrf52dk/bsp.yml\n) defines an area named \nFLASH_AREA_NFFS\n:\n\n\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x0007d000\n size: 12kB\n\n\n\n\n\nThe \nsyscfg.yml\n file for the same board (\nhw/bsp/nrf52dk/syscfg.yml\n) specifies that the above area be used for \nNFFS_FLASH_AREA\n.\n\n\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n COREDUMP_FLASH_AREA: FLASH_AREA_IMAGE_1\n\n\n\n\n\nNote that the \nfs/nffs/syscfg.yml\n file indicates that the \nNFFS_FLASH_AREA\n setting cannot be a null string; so a higher priority package must set a non-null value to it. That is exactly what the BSP package does. For more on priority of packages in setting values, see the next section.\n\n\n\n\nOverriding System Configuration Setting Values\n\n\nA package may use the \nvals\n parameter in its \nsyscfg.yml\n file to override the configuration values defined\nby other packages. This mechanism allows:\n\n\n\n\nMynewt developers to implement a package and easily override the system configuration setting values \n that are defined by the packages it depends on. \n\n\nApplication developers to easily and cleanly override default configuration settings in a single place and build a customized target. You can use the \nnewt target config show \ntarget-name\n command to check all the system configuration setting definitions and\n values in your target to determine the setting values to override. See \nnewt target\n. \n\n\n\n\nvals\n specifies the mappings of system configuration setting name-value pairs as follows: \n\n\nsyscfg.vals:\n PKGA_SYSCFG_NAME1: VALUE1\n PKGA_SYSCFG_NAME2: VALUE2\n ...\n PKGN_SYSCFG_NAME1: VALUEN\n\n\n\n\n\nNote\n: The newt tool ignores overrides of undefined system configuration settings. \n\n\n\n\nResolving Override Conflicts\n\n\nThe newt tool uses package priorities to determine whether a package can override a value and resolve conflicts when multiple packages override the same system configuration setting. The following rules apply:\n\n\n\n\nA package can only override the default values of system configuration settings that \n are defined by lower priority packages.\n\n\nWhen packages with different priorities override the same system configuration setting value, newt uses \n the value from the highest priority package.\n\n\nPackages of equal priority cannot override the same system configuration setting with different values. \n newt aborts the build unless a higher priority package also overrides the value.\n\n\n\n\nThe following package types are listed from highest to lowest priority:\n\n\n\n\nTarget\n\n\nApp\n\n\nunittest - A target can include either an app or unit test package, but not both.\n\n\nBSP\n\n\nLib - Includes all other system level packages such as os, lib, sdk, and compiler. (Note that a Lib package cannot override other Lib package settings.)\n\n\n\n\nIt is recommended that you override defaults at the target level instead of updating individual \npackage \nsyscfg.yml\n files.\n\n\n\n\nExamples of Overrides\n\n\nExample 4:\n The following example is an excerpt from the \napps/slinky\n package \nsyscfg.yml\n file. The application package overrides, \nin addition to other packages, the \nsys/log/full\n package system configuration settings defined in \nExample 1\n. It changes the LOG_NEWTMGR system configuration setting value from \n0\n to \n1\n.\n\n\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWTMGR: 1\n\n\n\n\n\nExample 5:\n The following example are excerpts from the \nhw/bsp/native\n package \nbsp.yml\n and \nsyscfg.yml\n files. \nThe package defines the flash areas for the BSP flash map in the \nbsp.yml\n file, and sets the \nNFFS_FLASH_AREA\n \nconfiguration setting value to use the flash area named \nFLASH_AREA_NFFS\n in the \nsyscfg.yml\n file.\n\n\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n size: 32kB\n\n\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n\n\n\n\n\n\n\nGenerated syscfg.h and Referencing System Configuration Settings\n\n\nThe newt tool processes all the package \nsyscfg.yml\n files and generates the\n\ntarget-path\n/generated/include/syscfg/syscfg.h\n include file with \n#define\n statements for each system configuration \nsetting defined. Newt creates a \n#define\n for a setting name as follows: \n\n\n\n\nAdds the prefix \nMYNEWT_VAL_\n.\n\n\nReplaces all occurrences of \"/\", \"-\", and \" \" in the setting name with \"_\".\n\n\nConverts all characters to upper case.\n\n\n\n\nFor example, the #define for my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME.\n\n\nNewt groups the settings in \nsyscfg.h\n by the packages that defined them. It also indicates the \npackage that changed a system configuration setting value. \n\n\nYou must use the \nMYNEWT_VAL()\n macro to reference a #define of a setting name in your header and source files. \nFor example, to reference the \nmy-config-name\n setting name, you use \nMYNEWT_VAL(MY_CONFIG_NAME)\n.\n\n\nNote:\n You only need to include \nsyscfg/syscfg.h\n in your source files to access the \nsyscfg.h\n file. The newt tool sets the correct include path to build your target. \n\n\nExample of syscfg.h and How to Reference a Setting Name\n\n\nExample 6\n: The following example are excerpts from a sample \nsyscfg.h\n file generated for an app/slinky target and \nfrom the \nsys/log/full\n package \nlog.c\n file that shows how to reference a setting name.\n\n\nThe \nsyscfg.h\n file shows the \nsys/log/full\n package definitions and also indicates that \napp/slinky\n \nchanged the value for the \nLOG_NEWTMGR\n settings. \n\n\n/**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#ifndef H_MYNEWT_SYSCFG_\n#define H_MYNEWT_SYSCFG_\n\n/**\n * This macro exists to ensure code includes this header when needed. If code\n * checks the existence of a setting directly via ifdef without including this\n * header, the setting macro will silently evaluate to 0. In contrast, an\n * attempt to use these macros without including this header will result in a\n * compiler error.\n */\n#define MYNEWT_VAL(x) MYNEWT_VAL_ ## x\n\n\n ...\n\n/*** kernel/os */\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_COUNT\n#define MYNEWT_VAL_MSYS_1_BLOCK_COUNT (12)\n#endif\n\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_SIZE\n#define MYNEWT_VAL_MSYS_1_BLOCK_SIZE (292)\n#endif\n\n ...\n\n/*** sys/log/full */\n\n#ifndef MYNEWT_VAL_LOG_LEVEL\n#define MYNEWT_VAL_LOG_LEVEL (0)\n#endif\n\n ...\n\n/* Overridden by apps/slinky (defined by sys/log/full) */\n#ifndef MYNEWT_VAL_LOG_NEWTMGR\n#define MYNEWT_VAL_LOG_NEWTMGR (1)\n#endif\n\n#endif\n\n\n\n\n\nThe \nlog_init()\n function in the \nsys/log/full/src/log.c\n file initializes the \nsys/log/full\n package. It checks the \n\nLOG_NEWTMGR\n setting value, using \nMYNEWT_VAL(LOG_NEWTMGR)\n, to determine whether the target application\nhas enabled the \nnewtmgr log\n functionality. It only registers the the callbacks to process the\n\nnewtmgr log\n commands when the setting value is non-zero.\n\n\nvoid\nlog_init(void)\n{\n int rc;\n\n /* Ensure this function only gets called by sysinit. */\n SYSINIT_ASSERT_ACTIVE();\n\n (void)rc;\n\n if (log_inited) {\n return;\n }\n log_inited = 1;\n ...\n\n#if MYNEWT_VAL(LOG_NEWTMGR)\n rc = log_nmgr_register_group();\n SYSINIT_PANIC_ASSERT(rc == 0);\n#endif\n}\n\n\n\n\n\n\n\nSystem Initialization\n\n\nDuring system startup, Mynewt creates a default event queue and a main task to process events from this queue. \nYou can override the \nOS_MAIN_TASK_PRIO\n and \nOS_MAIN_TASK_STACK_SIZE\n setting values defined by the \n\nkernel/os\n package to specify different task priority and stack size values.\n\n\nYour application's \nmain()\n function executes in the context of the main task and must perform the following:\n\n\n\n\nAt the start of \nmain()\n, call the Mynewt \nsysinit()\n function to initialize \nthe packages before performing any other processing.\n\n\nAt the end of \nmain()\n, wait for and dispatch events from the default event queue in an infinite loop. \n\n\n\n\nNote:\n You must include the \nsysinit/sysinit.h\n header file to access the \nsysinit()\n function.\n\n\nHere is an example of a \nmain()\n function:\n\n\nint\nmain(int argc, char **argv)\n{\n /* First, call sysinit() to perform the system and package initialization */\n sysinit();\n\n ... other application initialization processing....\n\n\n /* Last, process events from the default event queue. */\n while (1) {\n os_eventq_run(os_eventq_dflt_get());\n }\n /* main never returns */ \n}\n\n\n\n\n\n\n\nSpecifying Package Initialization Functions\n\n\nThe \nsysinit()\n function calls the \nsysinit_app()\n function to perform system \ninitialization for the packages in the target. You can, optionally, \nspecify one or more package initialization functions \nthat \nsysinit_app()\n calls to initialize a package. \n\n\nA package initialization function must have the following prototype:\n\n\nvoid init_func_name(void)\n\n\n\n\n\nPackage initialization functions are called in stages to ensure that lower priority\npackages are initialized before higher priority packages. A stage is an \ninteger value, 0 or higher, that specifies when an initialization function is \ncalled. Mynewt calls the package initialization functions \nin increasing stage number order. The call order for initialization functions with the \nsame stage number depends on the order the packages are processed,\nand you cannot rely on a specific call order for these functions. \n\n\nYou use the \npkg.init\n parameter in the \n\npkg.yml\n file to specify an initialization function and the stage number to call the function.\nYou can specify multiple initialization functions, with a different stage number for each function,\nfor the parameter values. This feature allows packages with interdependencies to\nperform initialization in multiple stages. \n\n\nThe \npkg.init\n parameter has the following syntax in the \npkg.yml\n file: \n\n\npkg.init: \n pkg_init_func1_name: pkg_init_func1_stage \n pkg_init_func2_name: pkg_init_func2_stage \n\n ...\n\n pkg_init_funcN_name: pkg_init_funcN_stage\n\n\n\n\n\nwhere \npkg_init_func#_name\n is the C function name of an initialization function, and \npkg_init_func#_stage\n \nis an integer value, 0 or higher, that indicates the stage when the \npkg_init_func#_name\n function is called. \n\n\nNote:\n The \npkg.init_function\n and \npkg.init_stage\n parameters introduced in a previous release for \nspecifying a package initialization function and a stage number are deprecated and have been \nretained to support the legacy format. They will not \nbe maintained for future releases and we recommend that you migrate to use the \npkg.init\n parameter.\n\n\n\n\nGenerated sysinit_app() Function\n\n\nThe newt tool processes the \npkg.init\n parameters in all the \npkg.yml\n files for a target,\ngenerates the \nsysinit_app()\n function in the \ntarget-path\n/generated/src/\ntarget-name\n-sysinit_app.c\n file, and \nincludes the file in the build. Here is an example \nsysinit_app()\n function:\n\n\n**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#if !SPLIT_LOADER\n\nvoid split_app_init(void);\nvoid os_pkg_init(void);\nvoid imgmgr_module_init(void);\n\n ...\n\nvoid stats_module_init(void);\n\nvoid\nsysinit_app(void)\n{\n\n /*** Stage 0 */\n /* 0.0: kernel/os */\n os_pkg_init();\n\n /*** Stage 2 */\n /* 2.0: sys/flash_map */\n flash_map_init();\n\n /*** Stage 10 */\n /* 10.0: sys/stats/full */\n stats_module_init();\n\n /*** Stage 20 */\n /* 20.0: sys/console/full */\n console_pkg_init();\n\n /*** Stage 100 */\n /* 100.0: sys/log/full */\n log_init();\n /* 100.1: sys/mfg */\n mfg_init();\n\n ....\n\n /*** Stage 300 */\n /* 300.0: sys/config */ \n config_pkg_init();\n\n /*** Stage 500 */\n /* 500.0: sys/id */\n id_init();\n /* 500.1: sys/shell */\n shell_init();\n\n ...\n\n /* 500.4: mgmt/imgmgr */\n imgmgr_module_init();\n\n /*** Stage 501 */\n /* 501.0: mgmt/newtmgr/transport/nmgr_shell */\n nmgr_shell_pkg_init();\n}\n#endif\n\n\n\n\n\n\n\nConditional Configurations\n\n\nYou can use the system configuration setting values to conditionally specify parameter values\nin \npkg.yml\n and \nsyscfg.yml\n files. The syntax is:\n\n\nparameter_name.PKGA_SYSCFG_NAME:\n parameter_value\n\n\n\n\n\nThis specifies that \nparameter_value\n is only set for \nparameter_name\n if the \nPKGA_SYSCFG_NAME\n configuration setting value \nis non-zero. Here is an example from the \nlibs/os\n package \npkg.yml\n file:\n\n\npkg.deps:\n - sys/sysinit\n - util/mem\n\npkg.deps.OS_CLI\n - sys/shell\n\n\n\n\n\nThis example specifies that the \nos\n package depends on the \nsysinit\n and \nmem\n packages, and also depends on the \n\nshell\n package when \nOS_CLI\n is enabled. \n\n\nThe newt tool aborts the build when it detects circular conditional dependencies.",
- "title": "toc"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#system-configuration-and-initialization",
- "text": "This guide describes how Mynewt manages system configuration and initialization. It shows you how to \ntell Mynewt to use default or customized values to initialize packages that you develop or use to build a target. This guide: Assumes you have read the Concepts section that describes the Mynewt \npackage hierarchy and its use of the pkg.yml and syscfg.yml files. Assumes you have read the Newt Tool Theory of Operation and are familiar with how newt determines \npackage dependencies for your target build. Covers only the system initialization for hardware independent packages. It does not cover the Board Support Package (BSP) and other hardware dependent system initialization. Mynewt defines several configuration parameters in the pkg.yml and syscfg.yml files. The newt tool uses this information to: Generate a system initialization function that calls all the package-specific system initialization functions. Generate a system configuration header file that contains all the package configuration settings and values. Display the system configuration settings and values in the newt target config command. The benefits with this approach include: Allows Mynewt developers to reuse other packages and easily change their configuration settings without updating source or header files when implementing new packages. Allows application developers to easily view the system configuration settings and values and determine the values to override for a target build.",
- "title": "System Configuration and Initialization"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#system-configuration-setting-definitions-and-values",
- "text": "A package can optionally: Define and expose the system configuration settings to allow other packages to override \nthe default setting values. Override the system configuration setting values defined by the packages that it depends on. You use the defs parameter in a syscfg.yml file to define the system configuration settings \nfor a package. defs is a mapping (or associative array) of system configuration setting definitions. It \nhas the following syntax: syscfg.defs:\n PKGA_SYSCFG_NAME1:\n description:\n value:\n type:\n restrictions:\n PKGA_SYSCFG_NAME2:\n description:\n value:\n type:\n restrictions: Each setting definition consists of the following key-value mapping: A setting name for the key, such as PKGA_SYSCFG_NAME1 in the syntax example above. Note: A system configuration setting name must be unique. The newt tool aborts the build \nwhen multiple packages define the same setting. A mapping of fields for the value. Each field itself is a key-value pair of attributes. The field keys are description , value , type , and restrictions . They are described in \nfollowing table: Field Description description Describes the usage for the setting. This field is optional. value Specifies the default value for the setting. This field is required. The value depends on the type that you specify and can be an empty string. type Specifies the data type for the value field. This field is optional. You can specify one of three types: raw - The value data is uninterpreted. This is the default type . task_priority - Specifies a Mynewt task priority number. The task priority number assigned to each setting must be unique and between 0 and 239. value can be one of the following: A number between 0 and 239 - The task priority number to use for the setting. any - Specify any to have newt automatically assign a priority for the setting. \nnewt alphabetically orders all system configuration settings of this type and assigns the next highest available \ntask priority number to each setting. flash_owner - Specifies a flash area. The value should be the name of a flash area \ndefined in the BSP flash map for your target board. restrictions Specifies a list of restrictions on the setting value. This field is optional. You can specify two formats: $notnull - Specifies that the setting cannot have the empty string for a value. It essentially means that an empty string is not a sensible value and a package must override it with an appropriate value. expression - Specifies a boolean expression of the form [!] >[if >] Examples: restrictions: !LOG_FCB - When this setting is enabled, LOG_FCB must be disabled. restrictions: LOG_FCB if 0 - When this setting is disabled, LOG_FCB must be enabled.",
- "title": "System Configuration Setting Definitions and Values"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#examples-of-configuration-settings",
- "text": "Example 1: The following example is an excerpt from the sys/log/full package syscfg.yml file. It defines the LOG_LEVEL configuration setting to specify the log level and the LOG_NEWTMGR configuration setting to specify whether\nto enable or disable the newtmgr logging feature. syscfg.defs:\n LOG_LEVEL:\n description: Log Level \n value: 0\n type: raw\n\n ... \n\n LOG_NEWTMGR: \n description: Enables or disables newtmgr command tool logging \n value: 0 Example 2: The following example is an excerpt from the net/nimble/controller package syscfg.yml file. It defines the BLE_LL_PRIO \nconfiguration setting with a task_priority type and assigns task priority 0 to the BLE link layer task. syscfg.defs:\n BLE_LL_PRIO:\n description: BLE link layer task priority \n type: task_priority \n value: 0 Example 3: The following example is an excerpt from the fs/nffs package syscfg.yml file. syscfg.defs:\n NFFS_FLASH_AREA:\n description: The flash area to use for the Newtron Flash File System \n type: flash_owner\n value:\n restrictions:\n - $notnull It defines the NFFS_FLASH_AREA configuration setting with a flash_owner type indicating that a flash area needs to be specified for the Newtron Flash File System. The flash areas are typically defined by the BSP in its bsp.yml file. For example, the bsp.yml for nrf52dk board ( hw/bsp/nrf52dk/bsp.yml ) defines an area named FLASH_AREA_NFFS : FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x0007d000\n size: 12kB The syscfg.yml file for the same board ( hw/bsp/nrf52dk/syscfg.yml ) specifies that the above area be used for NFFS_FLASH_AREA . syscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n COREDUMP_FLASH_AREA: FLASH_AREA_IMAGE_1 Note that the fs/nffs/syscfg.yml file indicates that the NFFS_FLASH_AREA setting cannot be a null string; so a higher priority package must set a non-null value to it. That is exactly what the BSP package does. For more on priority of packages in setting values, see the next section.",
- "title": "Examples of Configuration Settings"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#overriding-system-configuration-setting-values",
- "text": "A package may use the vals parameter in its syscfg.yml file to override the configuration values defined\nby other packages. This mechanism allows: Mynewt developers to implement a package and easily override the system configuration setting values \n that are defined by the packages it depends on. Application developers to easily and cleanly override default configuration settings in a single place and build a customized target. You can use the newt target config show target-name command to check all the system configuration setting definitions and\n values in your target to determine the setting values to override. See newt target . vals specifies the mappings of system configuration setting name-value pairs as follows: syscfg.vals:\n PKGA_SYSCFG_NAME1: VALUE1\n PKGA_SYSCFG_NAME2: VALUE2\n ...\n PKGN_SYSCFG_NAME1: VALUEN Note : The newt tool ignores overrides of undefined system configuration settings.",
- "title": "Overriding System Configuration Setting Values"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#resolving-override-conflicts",
- "text": "The newt tool uses package priorities to determine whether a package can override a value and resolve conflicts when multiple packages override the same system configuration setting. The following rules apply: A package can only override the default values of system configuration settings that \n are defined by lower priority packages. When packages with different priorities override the same system configuration setting value, newt uses \n the value from the highest priority package. Packages of equal priority cannot override the same system configuration setting with different values. \n newt aborts the build unless a higher priority package also overrides the value. The following package types are listed from highest to lowest priority: Target App unittest - A target can include either an app or unit test package, but not both. BSP Lib - Includes all other system level packages such as os, lib, sdk, and compiler. (Note that a Lib package cannot override other Lib package settings.) It is recommended that you override defaults at the target level instead of updating individual \npackage syscfg.yml files.",
- "title": "Resolving Override Conflicts"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#examples-of-overrides",
- "text": "Example 4: The following example is an excerpt from the apps/slinky package syscfg.yml file. The application package overrides, \nin addition to other packages, the sys/log/full package system configuration settings defined in Example 1 . It changes the LOG_NEWTMGR system configuration setting value from 0 to 1 . syscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWTMGR: 1 Example 5: The following example are excerpts from the hw/bsp/native package bsp.yml and syscfg.yml files. \nThe package defines the flash areas for the BSP flash map in the bsp.yml file, and sets the NFFS_FLASH_AREA \nconfiguration setting value to use the flash area named FLASH_AREA_NFFS in the syscfg.yml file. bsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n size: 32kB\n\n\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS",
- "title": "Examples of Overrides"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#generated-syscfgh-and-referencing-system-configuration-settings",
- "text": "The newt tool processes all the package syscfg.yml files and generates the target-path /generated/include/syscfg/syscfg.h include file with #define statements for each system configuration \nsetting defined. Newt creates a #define for a setting name as follows: Adds the prefix MYNEWT_VAL_ . Replaces all occurrences of \"/\", \"-\", and \" \" in the setting name with \"_\". Converts all characters to upper case. For example, the #define for my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME. Newt groups the settings in syscfg.h by the packages that defined them. It also indicates the \npackage that changed a system configuration setting value. You must use the MYNEWT_VAL() macro to reference a #define of a setting name in your header and source files. \nFor example, to reference the my-config-name setting name, you use MYNEWT_VAL(MY_CONFIG_NAME) . Note: You only need to include syscfg/syscfg.h in your source files to access the syscfg.h file. The newt tool sets the correct include path to build your target.",
- "title": "Generated syscfg.h and Referencing System Configuration Settings"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#example-of-syscfgh-and-how-to-reference-a-setting-name",
- "text": "Example 6 : The following example are excerpts from a sample syscfg.h file generated for an app/slinky target and \nfrom the sys/log/full package log.c file that shows how to reference a setting name. The syscfg.h file shows the sys/log/full package definitions and also indicates that app/slinky \nchanged the value for the LOG_NEWTMGR settings. /**\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#ifndef H_MYNEWT_SYSCFG_\n#define H_MYNEWT_SYSCFG_\n\n/**\n * This macro exists to ensure code includes this header when needed. If code\n * checks the existence of a setting directly via ifdef without including this\n * header, the setting macro will silently evaluate to 0. In contrast, an\n * attempt to use these macros without including this header will result in a\n * compiler error.\n */\n#define MYNEWT_VAL(x) MYNEWT_VAL_ ## x\n\n\n ...\n\n/*** kernel/os */\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_COUNT\n#define MYNEWT_VAL_MSYS_1_BLOCK_COUNT (12)\n#endif\n\n#ifndef MYNEWT_VAL_MSYS_1_BLOCK_SIZE\n#define MYNEWT_VAL_MSYS_1_BLOCK_SIZE (292)\n#endif\n\n ...\n\n/*** sys/log/full */\n\n#ifndef MYNEWT_VAL_LOG_LEVEL\n#define MYNEWT_VAL_LOG_LEVEL (0)\n#endif\n\n ...\n\n/* Overridden by apps/slinky (defined by sys/log/full) */\n#ifndef MYNEWT_VAL_LOG_NEWTMGR\n#define MYNEWT_VAL_LOG_NEWTMGR (1)\n#endif\n\n#endif The log_init() function in the sys/log/full/src/log.c file initializes the sys/log/full package. It checks the LOG_NEWTMGR setting value, using MYNEWT_VAL(LOG_NEWTMGR) , to determine whether the target application\nhas enabled the newtmgr log functionality. It only registers the the callbacks to process the newtmgr log commands when the setting value is non-zero. void\nlog_init(void)\n{\n int rc;\n\n /* Ensure this function only gets called by sysinit. */\n SYSINIT_ASSERT_ACTIVE();\n\n (void)rc;\n\n if (log_inited) {\n return;\n }\n log_inited = 1;\n ...\n\n#if MYNEWT_VAL(LOG_NEWTMGR)\n rc = log_nmgr_register_group();\n SYSINIT_PANIC_ASSERT(rc == 0);\n#endif\n}",
- "title": "Example of syscfg.h and How to Reference a Setting Name"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#system-initialization",
- "text": "During system startup, Mynewt creates a default event queue and a main task to process events from this queue. \nYou can override the OS_MAIN_TASK_PRIO and OS_MAIN_TASK_STACK_SIZE setting values defined by the kernel/os package to specify different task priority and stack size values. Your application's main() function executes in the context of the main task and must perform the following: At the start of main() , call the Mynewt sysinit() function to initialize \nthe packages before performing any other processing. At the end of main() , wait for and dispatch events from the default event queue in an infinite loop. Note: You must include the sysinit/sysinit.h header file to access the sysinit() function. Here is an example of a main() function: int\nmain(int argc, char **argv)\n{\n /* First, call sysinit() to perform the system and package initialization */\n sysinit();\n\n ... other application initialization processing....\n\n\n /* Last, process events from the default event queue. */\n while (1) {\n os_eventq_run(os_eventq_dflt_get());\n }\n /* main never returns */ \n}",
- "title": "System Initialization"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#specifying-package-initialization-functions",
- "text": "The sysinit() function calls the sysinit_app() function to perform system \ninitialization for the packages in the target. You can, optionally, \nspecify one or more package initialization functions \nthat sysinit_app() calls to initialize a package. A package initialization function must have the following prototype: void init_func_name(void) Package initialization functions are called in stages to ensure that lower priority\npackages are initialized before higher priority packages. A stage is an \ninteger value, 0 or higher, that specifies when an initialization function is \ncalled. Mynewt calls the package initialization functions \nin increasing stage number order. The call order for initialization functions with the \nsame stage number depends on the order the packages are processed,\nand you cannot rely on a specific call order for these functions. You use the pkg.init parameter in the pkg.yml file to specify an initialization function and the stage number to call the function.\nYou can specify multiple initialization functions, with a different stage number for each function,\nfor the parameter values. This feature allows packages with interdependencies to\nperform initialization in multiple stages. The pkg.init parameter has the following syntax in the pkg.yml file: pkg.init: \n pkg_init_func1_name: pkg_init_func1_stage \n pkg_init_func2_name: pkg_init_func2_stage \n\n ...\n\n pkg_init_funcN_name: pkg_init_funcN_stage where pkg_init_func#_name is the C function name of an initialization function, and pkg_init_func#_stage \nis an integer value, 0 or higher, that indicates the stage when the pkg_init_func#_name function is called. Note: The pkg.init_function and pkg.init_stage parameters introduced in a previous release for \nspecifying a package initialization function and a stage number are deprecated and have been \nretained to support the legacy format. They will not \nbe maintained for future releases and we recommend that you migrate to use the pkg.init parameter.",
- "title": "Specifying Package Initialization Functions"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#generated-sysinit_app-function",
- "text": "The newt tool processes the pkg.init parameters in all the pkg.yml files for a target,\ngenerates the sysinit_app() function in the target-path /generated/src/ target-name -sysinit_app.c file, and \nincludes the file in the build. Here is an example sysinit_app() function: **\n * This file was generated by Apache Newt (incubating) version: 1.0.0-dev\n */\n\n#if !SPLIT_LOADER\n\nvoid split_app_init(void);\nvoid os_pkg_init(void);\nvoid imgmgr_module_init(void);\n\n ...\n\nvoid stats_module_init(void);\n\nvoid\nsysinit_app(void)\n{\n\n /*** Stage 0 */\n /* 0.0: kernel/os */\n os_pkg_init();\n\n /*** Stage 2 */\n /* 2.0: sys/flash_map */\n flash_map_init();\n\n /*** Stage 10 */\n /* 10.0: sys/stats/full */\n stats_module_init();\n\n /*** Stage 20 */\n /* 20.0: sys/console/full */\n console_pkg_init();\n\n /*** Stage 100 */\n /* 100.0: sys/log/full */\n log_init();\n /* 100.1: sys/mfg */\n mfg_init();\n\n ....\n\n /*** Stage 300 */\n /* 300.0: sys/config */ \n config_pkg_init();\n\n /*** Stage 500 */\n /* 500.0: sys/id */\n id_init();\n /* 500.1: sys/shell */\n shell_init();\n\n ...\n\n /* 500.4: mgmt/imgmgr */\n imgmgr_module_init();\n\n /*** Stage 501 */\n /* 501.0: mgmt/newtmgr/transport/nmgr_shell */\n nmgr_shell_pkg_init();\n}\n#endif",
- "title": "Generated sysinit_app() Function"
- },
- {
- "location": "/os/modules/sysinitconfig/sysinitconfig/#conditional-configurations",
- "text": "You can use the system configuration setting values to conditionally specify parameter values\nin pkg.yml and syscfg.yml files. The syntax is: parameter_name.PKGA_SYSCFG_NAME:\n parameter_value This specifies that parameter_value is only set for parameter_name if the PKGA_SYSCFG_NAME configuration setting value \nis non-zero. Here is an example from the libs/os package pkg.yml file: pkg.deps:\n - sys/sysinit\n - util/mem\n\npkg.deps.OS_CLI\n - sys/shell This example specifies that the os package depends on the sysinit and mem packages, and also depends on the shell package when OS_CLI is enabled. The newt tool aborts the build when it detects circular conditional dependencies.",
- "title": "Conditional Configurations"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/",
- "text": "Validation and Error Messages\n\n\nWith multiple packages defining and overriding system configuration settings, it \nis easy to introduce conflicts and violations that are difficult to find. The \n\nnewt build \ntarget-name\n command validates the setting definitions and value \noverrides for all the packages in the target to ensure a valid and consistent build.\nIt aborts the build when it detects violations or ambiguities between packages.\n\nThe following sections describe the error conditions that newt detects and \nthe error messages that it outputs. For most errors, newt also outputs \nthe \nSetting history\n with the order of package overrides to help \nyou resolve the errors.\n\n\nNote:\n The \nnewt target config \ntarget-name\n command also detects \nerrors and outputs error messages at the top of the command output. \nThe command outputs the package setting definitions and values after it \noutputs the error messages. It is easy to miss the error messages at the top. \n\n\nValue Override Violations\n\n\nThe newt tool uses package priorities to resolve override conflicts. It uses \nthe value override from the highest priority package when multiple \npackages override the same setting. Newt checks for the following \noverride violations:\n\n\n\n\nAmbiguity Violation - Two packages of the same priority override a setting with \ndifferent values. And no higher priority package overrides the setting.\n\n\nPriority Violation - A package overrides a setting defined by a package with higher or \nequal priority. \n\n\n\n\nExample: Ambiguity Violation Error Message\n\n\nThe following example shows the error message that newt outputs for an ambiguity violation:\n\n\nError: Syscfg ambiguities detected:\n Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty]\nSetting history (newest -\n oldest):\n LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log/full:0]\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n and \napps/splitty\n packages \nin the split image target both override the same setting with different \nvalues. The \napps/slinky\n package sets the \nsys/log/full\n package \nLOG_NEWTMGR\n \nsetting to 1, and the \napps/splitty\n package sets the setting to 0. The \noverrides are ambiguous because both are \napp\n packages and \nhave the same priority. The following are excerpts of the defintion \nand the two overrides from the \nsyscfg.yml\n files that cause the error:\n\n\n#Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n#Package: apps/slinky\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n#Package: apps/splitty\nsyscfg.vals:\n LOG_NEWTMGR: 0\n\n\n\n\n\nExample: Priority Violation Error Message\n\n\nThe following example shows the error message that newt outputs for a priority violation \nwhere a package tries to change the setting that was defined by another package at \nthe same priority level:\n\n\nError: Priority violations detected (Packages can only override settings defined by packages of lower priority):\n Package: mgmt/newtmgr overriding setting: LOG_NEWTMGR defined by sys/log/full\n\nSetting history (newest -\n oldest):\n LOG_NEWTMGR: [sys/log/full:0]\n\n\n\n\n\nThe above error occurs because the \nmgmt/newtmgr\n lib package \noverrides the \nLOG_NEWTMGR\n setting that the \nsys/log/full\n lib package \ndefines. The following are excerpts of the definition and the override from the \n\nsyscfg.yml\n files that cause this error: \n\n\n#Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n#Package: mgmt/newtmgr\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n\n\n\n\n\n\nFlash Area Violations\n\n\nFor \nflash_owner\n type setting definitions, newt checks \nfor the following violations:\n\n\n\n\nAn undefined flash area is assigned to a setting.\n\n\nA flash area is assigned to multiple settings.\n\n\n\n\nExample: Undefined Flash Area Error Message\n\n\nThe following example shows the error message that newt outputs for an undefined flash area.\n\n\nBuilding target targets/sim_slinky\nError: Flash errors detected:\n Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST\n\nSetting history (newest -\n oldest):\n REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:]\n\n\n\n\n\nThe above error occurs because the \nhw/bsp/native\n package assigns the \nundefined \nFLASH_AREA_NOEXIST\n flash area to the \nsys/reboot\n package \n\nREBOOT_LOG_FLASH_AREA\n setting. The following are excerpts of the definition \nand the override from the \nsyscfg.yml\n files that cause the error:\n\n\n#Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: \nFlash Area to use for reboot log.\n\n type: flash_owner\n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST\n\n\n\n\n\nExample: Multiple Flash Area Assignment Error Message\n\n\nThe following example shows the error message that newt outputs when multiple \nsettings are assigned the same flash area:\n\n\nError: Flash errors detected:\n Multiple flash_owner settings specify the same flash area\n settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA\n flash area: FLASH_AREA_NFFS\n\nSetting history (newest -\n oldest):\n CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:]\n REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:]\n\n\n\n\n\nThe above error occurs because the \nhw/bsp/native\n package assigns \nthe \nFLASH_AREA_NFFS\n flash area to the \nsys/config/\n package \n\nCONFIG_FCB_FLASH_AREA\n setting, and the \napps/slinky\n package \nalso assigns \nFLASH_AREA_NFFS\n to the \nsys/reboot\n package \n\nREBOOT_LOG_FLASH_AREA\n setting. The following are excerpts of the \ntwo definitions and the two overrides from the \nsyscfg.yml\n files \nthat cause the error:\n\n\n# Package: sys/config\nsyscfg.defs.CONFIG_FCB:\n CONFIG_FCB_FLASH_AREA:\n description: \nThe flash area for the Config Flash Circular Buffer\n\n type: \nflash_owner\n\n value:\n\n# Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: \nThe flash area for the reboot log\n\n type: \nflash_owner\n \n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n\n#Package: apps/slinky\nsyscfg.vals: \n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS\n\n\n\n\n\n\n\nRestriction Violations\n\n\nFor setting definitions with \nrestrictions\n specified, newt checks for \nthe following violations:\n\n\n\n\nA setting with a \n$notnull\n restriction does not have a value. \n\n\nFor a setting with expression restrictions, some required setting \nvalues in the expressions evaluate to false. \n\n\n\n\nExample: $notnull Restriction Violation Error Message\n\n\nThe following example shows the error message that newt outputs when\na setting with \n$notnull\n restriction does not have a value:\n\n\nError: Syscfg restriction violations detected:\n NFFS_FLASH_AREA must not be null \n\nSetting history (newest -\n oldest):\n NFFS_FLASH_AREA: [fs/nffs:]\n\n\n\n\n\nThe above error occurs because the \nfs/nffs\n package defines the \nNFFS_FLASH_AREA\n \nsetting with a \n$notnull\n restriction and no packages override the setting. The \nfollowing is an excerpt of the definition in the \nsyscfg.yml\n file that causes the error:\n\n\n#Package: fs/nffs\nsyscfg.defs:\n NFFS_FLASH_AREA:\n description: \nThe flash area to use for the Newtron Flash File System\n\n type: flash_owner\n value:\n restrictions:\n - $notnull\n\n\n\n\n\nExample: Expression Restriction Violation Error Message\n\n\nThe following example shows the error message that newt outputs for \nan expression restriction violation:\n\n\nError: Syscfg restriction violations detected:\n CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA=\n\nSetting history (newest -\n oldest):\n CONFIG_FCB: [targets/sim_slinky:1, sys/config:0]\n CONFIG_FCB_FLASH_AREA: [sys/config:]\n\n\n\n\n\nThe above error occurs because the \nsys/config\n package defines the \nCONFIG_FCB\n setting with \na restriction that when set, requires that the \nCONFIG_FCB_FLASH_AREA\n setting must \nalso be set. The following are excerpts of the definition and the override from the \nsyscfg.yml\n \nfiles that cause the error:\n\n\n# Package: sys/config\nsyscfg.defs:\n CONFIG_FCB:\n description: \nUses Config Flash Circular Buffer\n\n value: 0\n restrictions:\n - \n!CONFIG_NFFS\n\n - \nCONFIG_FCB_FLASH_AREA\n\n\n# Package: targets/sim_slinky\nsyscfg.vals:\n CONFIG_FCB: 1\n\n\n\n\n\n\n\nTask Priority Violations\n\n\nFor \ntask_priority\n type setting definitions, newt checks for the following violations:\n\n\n\n\nA task priority number is assigned to multiple settings. \n\n\nThe task priority number is greater than 239.\n\n\n\n\nExample: Duplicate Task Priority Assignment Error Message\n\n\nThe following example shows the error message that newt outputs when\na task priority number is assigned to multiple settings.\n\n\nNote:\n The settings used in this example are not actual \napps/slinky\n and \nsys/shell\n settings.\nThese settings are created for this example because currently only one Mynewt package \ndefines a \ntask_priority\n type setting. \n\n\nError: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n package defines a \nSLINKY_TASK_PRIORITY\n \nsetting with a default task priority of 1 and the \nsys/shell\n package also defines a \n\nSHELL_TASK_PRIORITY\n setting with a default task priority of 1.\n\n\nExample: Invalid Task Priority Error Message\n\n\nThe following example shows the error message that newt outputs when\na setting is assigned an invalid task priority value:\n\n\nError: invalid priority value: value too great (\n 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n package defines the \nSLINKY_TASK_PRIORITY\n setting \nwith 240 for the default task priority value. \n\n\nNote:\n Newt does not output the \nSetting history\n with task priority violation error messages. \n\n\n\n\nDuplicate System Configuration Setting Definition\n\n\nA setting definition must be unique. Newt checks that only one package in the \ntarget defines a setting. The following example shows the error message that newt \noutputs when multiple packages define the \nLOG_NEWTMGR\n setting:\n\n\nError: setting LOG_NEWTMGR redefined\n\n\n\n\n\nNote:\n Newt does not output the \nSetting history\n with duplicate setting error messages. \n\n\n\nOverride of Undefined System Configuration Setting\n\n\nThe \nnewt build\n command ignores overrides of undefined system configuration settings. The command does not print a warning when you run it with the default log level. If you override a setting and the value is not assigned to the setting, you may have misspelled the setting name or a package no longer defines the setting. You have two options to troubleshoot this problem:\n\n\n\n\nRun the \nnewt target config show\n command to see the configuration setting definitions and overrides.\n\n\nRun the \nnewt build -ldebug\n command to build your target with DEBUG log level. \n\n\n\n\nNote: The \nnewt build -ldebug\n command generates lots of output and we recommend that you use the \nnewt target config show\n command option.\n\n\n\nExample: Ignoring Override of Undefined Setting Message\n\n\nThe following example shows that the \napps/slinky\n application overrides the \nLOG_NEWTMGR\n setting but omits the \nT\n as an example of an error and overrides the misspelled \nLOG_NEWMGR\n setting. Here is an excerpt from its \nsyscfg.yml\n file: \n\n\n#package: apps/slinky\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWMGR: 1\n\n\n\n\n\n\nThe \nnewt target config show slinky_sim\n command outputs the following WARNING message:\n\n\n2017/02/18 17:19:12.119 [WARNING] Ignoring override of undefined settings:\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA\n2017/02/18 17:19:12.119 [WARNING] Setting history (newest -\n oldest):\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS]\n\n\n\n\n\n\n\nThe \nnewt build -ldebug slinky_sim\n command outputs the following DEBUG message: \n\n\n2017/02/18 17:06:21.451 [DEBUG] Ignoring override of undefined settings:\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA\n2017/02/18 17:06:21.451 [DEBUG] Setting history (newest -\n oldest):\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS]\n\n\n\n\n\n\n\nBSP Package Overrides Undefined Configuration Settings\n\n\nYou might see a warning that indicates your application's BSP package is overriding some undefined settings. As you can see from the previous example, the WARNING message shows that the \nhw/bsp/native\n package is overriding the undefined \nNFFS_FLASH_AREA\n setting. This is not an error because of the way a BSP package defines and assigns its flash areas to packages that use flash memory.\n\n\nA BSP package defines, in its \nbsp.yml\n file, a flash area map of the flash areas on the board. A package that uses flash memory must define a flash area configuration setting name. The BSP package overrides the package's flash area setting with one of the flash areas from its flash area map. A BSP package overrides the flash area settings for all packages that use flash memory because it does not know the packages that an application uses. When an application does not include one of these packages, the flash area setting for the package is undefined. You will see a message that indicates the BSP package overrides this undefined setting.\n\n\nHere are excerpts from the \nhw/bsp/native\n package's \nbsp.yml\n and \nsyscfg.yml\n files for the \nslinky_sim\n target. The BSP package defines the flash area map in its \nbsp.yml\n file and overrides the flash area settings for all packages in its \nsyscfg.yml\n file. The \nslinky_sim\n target does not use the \nfs/nffs\n package which defines the \nNFFS_FLASH_AREA\n setting. Newt warns that the \nhw/bsp/native\n packages overrides the undefined \nNFFS_FLASH_AREA\n setting.\n\n\n# hw/bsp/native bsp.yml\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n FLASH_AREA_IMAGE_SCRATCH:\n device: 0\n offset: 0x000e0000\n size: 128kB\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n\n# hw/bsp/native syscfg.yml\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG",
- "title": "Validation and Error Messages"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#validation-and-error-messages",
- "text": "With multiple packages defining and overriding system configuration settings, it \nis easy to introduce conflicts and violations that are difficult to find. The newt build target-name command validates the setting definitions and value \noverrides for all the packages in the target to ensure a valid and consistent build.\nIt aborts the build when it detects violations or ambiguities between packages. \nThe following sections describe the error conditions that newt detects and \nthe error messages that it outputs. For most errors, newt also outputs \nthe Setting history with the order of package overrides to help \nyou resolve the errors. Note: The newt target config target-name command also detects \nerrors and outputs error messages at the top of the command output. \nThe command outputs the package setting definitions and values after it \noutputs the error messages. It is easy to miss the error messages at the top.",
- "title": "Validation and Error Messages"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#value-override-violations",
- "text": "The newt tool uses package priorities to resolve override conflicts. It uses \nthe value override from the highest priority package when multiple \npackages override the same setting. Newt checks for the following \noverride violations: Ambiguity Violation - Two packages of the same priority override a setting with \ndifferent values. And no higher priority package overrides the setting. Priority Violation - A package overrides a setting defined by a package with higher or \nequal priority.",
- "title": "Value Override Violations"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-ambiguity-violation-error-message",
- "text": "The following example shows the error message that newt outputs for an ambiguity violation: Error: Syscfg ambiguities detected:\n Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty]\nSetting history (newest - oldest):\n LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log/full:0] The above error occurs because the apps/slinky and apps/splitty packages \nin the split image target both override the same setting with different \nvalues. The apps/slinky package sets the sys/log/full package LOG_NEWTMGR \nsetting to 1, and the apps/splitty package sets the setting to 0. The \noverrides are ambiguous because both are app packages and \nhave the same priority. The following are excerpts of the defintion \nand the two overrides from the syscfg.yml files that cause the error: #Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: Enables or disables newtmgr command tool logging \n value: 0\n\n#Package: apps/slinky\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n#Package: apps/splitty\nsyscfg.vals:\n LOG_NEWTMGR: 0",
- "title": "Example: Ambiguity Violation Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-priority-violation-error-message",
- "text": "The following example shows the error message that newt outputs for a priority violation \nwhere a package tries to change the setting that was defined by another package at \nthe same priority level: Error: Priority violations detected (Packages can only override settings defined by packages of lower priority):\n Package: mgmt/newtmgr overriding setting: LOG_NEWTMGR defined by sys/log/full\n\nSetting history (newest - oldest):\n LOG_NEWTMGR: [sys/log/full:0] The above error occurs because the mgmt/newtmgr lib package \noverrides the LOG_NEWTMGR setting that the sys/log/full lib package \ndefines. The following are excerpts of the definition and the override from the syscfg.yml files that cause this error: #Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: Enables or disables newtmgr command tool logging \n value: 0\n\n#Package: mgmt/newtmgr\nsyscfg.vals:\n LOG_NEWTMGR: 1",
- "title": "Example: Priority Violation Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#flash-area-violations",
- "text": "For flash_owner type setting definitions, newt checks \nfor the following violations: An undefined flash area is assigned to a setting. A flash area is assigned to multiple settings.",
- "title": "Flash Area Violations"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-undefined-flash-area-error-message",
- "text": "The following example shows the error message that newt outputs for an undefined flash area. Building target targets/sim_slinky\nError: Flash errors detected:\n Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST\n\nSetting history (newest - oldest):\n REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:] The above error occurs because the hw/bsp/native package assigns the \nundefined FLASH_AREA_NOEXIST flash area to the sys/reboot package REBOOT_LOG_FLASH_AREA setting. The following are excerpts of the definition \nand the override from the syscfg.yml files that cause the error: #Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: Flash Area to use for reboot log. \n type: flash_owner\n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST",
- "title": "Example: Undefined Flash Area Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-multiple-flash-area-assignment-error-message",
- "text": "The following example shows the error message that newt outputs when multiple \nsettings are assigned the same flash area: Error: Flash errors detected:\n Multiple flash_owner settings specify the same flash area\n settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA\n flash area: FLASH_AREA_NFFS\n\nSetting history (newest - oldest):\n CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:]\n REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:] The above error occurs because the hw/bsp/native package assigns \nthe FLASH_AREA_NFFS flash area to the sys/config/ package CONFIG_FCB_FLASH_AREA setting, and the apps/slinky package \nalso assigns FLASH_AREA_NFFS to the sys/reboot package REBOOT_LOG_FLASH_AREA setting. The following are excerpts of the \ntwo definitions and the two overrides from the syscfg.yml files \nthat cause the error: # Package: sys/config\nsyscfg.defs.CONFIG_FCB:\n CONFIG_FCB_FLASH_AREA:\n description: The flash area for the Config Flash Circular Buffer \n type: flash_owner \n value:\n\n# Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: The flash area for the reboot log \n type: flash_owner \n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n\n#Package: apps/slinky\nsyscfg.vals: \n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS",
- "title": "Example: Multiple Flash Area Assignment Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#restriction-violations",
- "text": "For setting definitions with restrictions specified, newt checks for \nthe following violations: A setting with a $notnull restriction does not have a value. For a setting with expression restrictions, some required setting \nvalues in the expressions evaluate to false.",
- "title": "Restriction Violations"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-notnull-restriction-violation-error-message",
- "text": "The following example shows the error message that newt outputs when\na setting with $notnull restriction does not have a value: Error: Syscfg restriction violations detected:\n NFFS_FLASH_AREA must not be null \n\nSetting history (newest - oldest):\n NFFS_FLASH_AREA: [fs/nffs:] The above error occurs because the fs/nffs package defines the NFFS_FLASH_AREA \nsetting with a $notnull restriction and no packages override the setting. The \nfollowing is an excerpt of the definition in the syscfg.yml file that causes the error: #Package: fs/nffs\nsyscfg.defs:\n NFFS_FLASH_AREA:\n description: The flash area to use for the Newtron Flash File System \n type: flash_owner\n value:\n restrictions:\n - $notnull",
- "title": "Example: $notnull Restriction Violation Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-expression-restriction-violation-error-message",
- "text": "The following example shows the error message that newt outputs for \nan expression restriction violation: Error: Syscfg restriction violations detected:\n CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA=\n\nSetting history (newest - oldest):\n CONFIG_FCB: [targets/sim_slinky:1, sys/config:0]\n CONFIG_FCB_FLASH_AREA: [sys/config:] The above error occurs because the sys/config package defines the CONFIG_FCB setting with \na restriction that when set, requires that the CONFIG_FCB_FLASH_AREA setting must \nalso be set. The following are excerpts of the definition and the override from the syscfg.yml \nfiles that cause the error: # Package: sys/config\nsyscfg.defs:\n CONFIG_FCB:\n description: Uses Config Flash Circular Buffer \n value: 0\n restrictions:\n - !CONFIG_NFFS \n - CONFIG_FCB_FLASH_AREA \n\n# Package: targets/sim_slinky\nsyscfg.vals:\n CONFIG_FCB: 1",
- "title": "Example: Expression Restriction Violation Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#task-priority-violations",
- "text": "For task_priority type setting definitions, newt checks for the following violations: A task priority number is assigned to multiple settings. The task priority number is greater than 239.",
- "title": "Task Priority Violations"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-duplicate-task-priority-assignment-error-message",
- "text": "The following example shows the error message that newt outputs when\na task priority number is assigned to multiple settings. Note: The settings used in this example are not actual apps/slinky and sys/shell settings.\nThese settings are created for this example because currently only one Mynewt package \ndefines a task_priority type setting. Error: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1 The above error occurs because the apps/slinky package defines a SLINKY_TASK_PRIORITY \nsetting with a default task priority of 1 and the sys/shell package also defines a SHELL_TASK_PRIORITY setting with a default task priority of 1.",
- "title": "Example: Duplicate Task Priority Assignment Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-invalid-task-priority-error-message",
- "text": "The following example shows the error message that newt outputs when\na setting is assigned an invalid task priority value: Error: invalid priority value: value too great ( 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky The above error occurs because the apps/slinky package defines the SLINKY_TASK_PRIORITY setting \nwith 240 for the default task priority value. Note: Newt does not output the Setting history with task priority violation error messages.",
- "title": "Example: Invalid Task Priority Error Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#duplicate-system-configuration-setting-definition",
- "text": "A setting definition must be unique. Newt checks that only one package in the \ntarget defines a setting. The following example shows the error message that newt \noutputs when multiple packages define the LOG_NEWTMGR setting: Error: setting LOG_NEWTMGR redefined Note: Newt does not output the Setting history with duplicate setting error messages.",
- "title": "Duplicate System Configuration Setting Definition"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#override-of-undefined-system-configuration-setting",
- "text": "The newt build command ignores overrides of undefined system configuration settings. The command does not print a warning when you run it with the default log level. If you override a setting and the value is not assigned to the setting, you may have misspelled the setting name or a package no longer defines the setting. You have two options to troubleshoot this problem: Run the newt target config show command to see the configuration setting definitions and overrides. Run the newt build -ldebug command to build your target with DEBUG log level. Note: The newt build -ldebug command generates lots of output and we recommend that you use the newt target config show command option.",
- "title": "Override of Undefined System Configuration Setting"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#example-ignoring-override-of-undefined-setting-message",
- "text": "The following example shows that the apps/slinky application overrides the LOG_NEWTMGR setting but omits the T as an example of an error and overrides the misspelled LOG_NEWMGR setting. Here is an excerpt from its syscfg.yml file: #package: apps/slinky\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWMGR: 1 \nThe newt target config show slinky_sim command outputs the following WARNING message: 2017/02/18 17:19:12.119 [WARNING] Ignoring override of undefined settings:\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA\n2017/02/18 17:19:12.119 [WARNING] Setting history (newest - oldest):\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS] The newt build -ldebug slinky_sim command outputs the following DEBUG message: 2017/02/18 17:06:21.451 [DEBUG] Ignoring override of undefined settings:\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA\n2017/02/18 17:06:21.451 [DEBUG] Setting history (newest - oldest):\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS]",
- "title": "Example: Ignoring Override of Undefined Setting Message"
- },
- {
- "location": "/os/modules/sysinitconfig/sysconfig_error/#bsp-package-overrides-undefined-configuration-settings",
- "text": "You might see a warning that indicates your application's BSP package is overriding some undefined settings. As you can see from the previous example, the WARNING message shows that the hw/bsp/native package is overriding the undefined NFFS_FLASH_AREA setting. This is not an error because of the way a BSP package defines and assigns its flash areas to packages that use flash memory. A BSP package defines, in its bsp.yml file, a flash area map of the flash areas on the board. A package that uses flash memory must define a flash area configuration setting name. The BSP package overrides the package's flash area setting with one of the flash areas from its flash area map. A BSP package overrides the flash area settings for all packages that use flash memory because it does not know the packages that an application uses. When an application does not include one of these packages, the flash area setting for the package is undefined. You will see a message that indicates the BSP package overrides this undefined setting. Here are excerpts from the hw/bsp/native package's bsp.yml and syscfg.yml files for the slinky_sim target. The BSP package defines the flash area map in its bsp.yml file and overrides the flash area settings for all packages in its syscfg.yml file. The slinky_sim target does not use the fs/nffs package which defines the NFFS_FLASH_AREA setting. Newt warns that the hw/bsp/native packages overrides the undefined NFFS_FLASH_AREA setting. # hw/bsp/native bsp.yml\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n FLASH_AREA_IMAGE_SCRATCH:\n device: 0\n offset: 0x000e0000\n size: 128kB\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n\n# hw/bsp/native syscfg.yml\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG",
- "title": "BSP Package Overrides Undefined Configuration Settings"
- },
- {
- "location": "/network/ble/ble_intro/",
- "text": "BLE Introduction\n\n\nApache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack fully compliant with BLE 4.2 specifications. It is called NimBLE. \n\n\nBLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.\n\n\n\n\nFeature Support\n\n\nNimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT).\n\n\n\n\nLE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders\n\n\nLE Secure Connections featuring FIPS-compliant algorithms.\n\n\nLE Data Length Extension for higher throughput\n\n\nComing Soon\n: Assigning an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP)\n\n\n\n\nComponents\n\n\nA Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents:\n\n\n\n\n\n\nController\n\n\n\n\nPhysical Layer\n: adaptive frequency-hopping Gaussian Frequency Shift Keying (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing.\n\n\nLink Layer\n: with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time\n\n\n\n\n\n\n\n\nHost\n\n\n\n\nLogical Link Control and Adaptation Protocol (L2CAP)\n: provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. \n\n\nSecurity Manager (SM)\n: uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication \n\n\nAttribute protocol (ATT)\n: allows a device (\nServer\n) to expose certain pieces of data, known as \nAttributes\n, to another device (\nClient\n)\n\n\nGeneric Attribute Profile (GATT)\n: a framework for using the ATT protocol to exchange attributes encapsulated as \nCharacteristics\n or \nServices\n \n\n\nGeneric Access Profile (GAP)\n: a base profile which all Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. \n\n\nHost Controller Interface (HCI)\n: the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB.\n\n\n\n\n\n\n\n\nSubsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and things to consider while designing a NimBLE app.\n\n\n\n\nExample NimBLE projects\n\n\nMynewt comes with several built-in projects or applications using NimBLE. These allow users to try out NimBLE, understand how to use available services, and build their own applications using one or more of the examples as seed.\n\n\n\n\n\n\nbletiny\n : A simple shell application which provides a basic interface to the host-side of the BLE stack. Supported operations include GAP, GATT, and L2CAP.\n\n\n\n\n\n\nbleprph\n: A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It supports a maximum of one connection.\n\n\n\n\n\n\nblecent\n: A basic central device with no user interface. This application scans for a peripheral that supports the alert notification service (ANS). Upon discovering such a peripheral, blecent connects and performs the following actions:\n\n\n\n\nReads the ANS Supported New Alert Category characteristic.\n\n\nWrites the ANS Alert Notification Control Point characteristic.\n\n\nSubscribes to notifications for the ANS Unread Alert Status characteristic.\n\n\n\n\n\n\n\n\nblehci\n: Implements a BLE controller-only application. A separate host-only implementation, such as Linux's BlueZ, can interface with this application via HCI over UART.\n\n\n\n\n\n\nbleuart\n: Implements a simple BLE peripheral that supports the Nordic\n\nUART / Serial Port Emulation service",
- "title": "NimBLE Introduction"
- },
- {
- "location": "/network/ble/ble_intro/#ble-introduction",
- "text": "Apache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack fully compliant with BLE 4.2 specifications. It is called NimBLE. BLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.",
- "title": "BLE Introduction"
- },
- {
- "location": "/network/ble/ble_intro/#feature-support",
- "text": "NimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT). LE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders LE Secure Connections featuring FIPS-compliant algorithms. LE Data Length Extension for higher throughput Coming Soon : Assigning an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP)",
- "title": "Feature Support"
- },
- {
- "location": "/network/ble/ble_intro/#components",
- "text": "A Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents: Controller Physical Layer : adaptive frequency-hopping Gaussian Frequency Shift Keying (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing. Link Layer : with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time Host Logical Link Control and Adaptation Protocol (L2CAP) : provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. Security Manager (SM) : uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication Attribute protocol (ATT) : allows a device ( Server ) to expose certain pieces of data, known as Attributes , to another device ( Client ) Generic Attribute Profile (GATT) : a framework for using the ATT protocol to exchange attributes encapsulated as Characteristics or Services Generic Access Profile (GAP) : a base profile which all Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. Host Controller Interface (HCI) : the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB. Subsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and things to consider while designing a NimBLE app.",
- "title": "Components"
- },
- {
- "location": "/network/ble/ble_intro/#example-nimble-projects",
- "text": "Mynewt comes with several built-in projects or applications using NimBLE. These allow users to try out NimBLE, understand how to use available services, and build their own applications using one or more of the examples as seed. bletiny : A simple shell application which provides a basic interface to the host-side of the BLE stack. Supported operations include GAP, GATT, and L2CAP. bleprph : A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It supports a maximum of one connection. blecent : A basic central device with no user interface. This application scans for a peripheral that supports the alert notification service (ANS). Upon discovering such a peripheral, blecent connects and performs the following actions: Reads the ANS Supported New Alert Category characteristic. Writes the ANS Alert Notification Control Point characteristic. Subscribes to notifications for the ANS Unread Alert Status characteristic. blehci : Implements a BLE controller-only application. A separate host-only implementation, such as Linux's BlueZ, can interface with this application via HCI over UART. bleuart : Implements a simple BLE peripheral that supports the Nordic UART / Serial Port Emulation service",
- "title": "Example NimBLE projects"
- },
- {
- "location": "/network/ble/ble_sec/",
- "text": "BLE Security\n\n\nThe Bluetooth Low Energy security model includes five distinct security concepts as listed below. For detailed specifications, see BLUETOOTH SPECIFICATION Version 4.2 [Vol 1, Part A].\n\n\n\n\n\n\nPairing\n: The process for creating one or more shared secret keys. In LE a single link key is generated by combining contributions from each device into a link key used during pairing. \n\n\n\n\n\n\nBonding\n: The act of storing the keys created during pairing for use in subsequent connections in order to form a trusted device pair. \n\n\n\n\n\n\nDevice authentication\n: Verification that the two devices have the same keys (verify device identity)\n\n\n\n\n\n\nEncryption\n: Keeps message confidential. Encryption in Bluetooth LE uses AES-CCM cryptography and is performed in the \nController\n.\n\n\n\n\n\n\nMessage integrity\n: Protects against message forgeries.\n\n\n\n\n\n\nBluetooth LE uses four association models depending on the I/O capabilities of the devices. \n\n\n\n\n\n\nJust Works\n: designed for scenarios where at least one of the devices does not have a display capable of displaying a six digit number nor does it have a keyboard capable of entering six decimal digits.\n\n\n\n\n\n\nNumeric Comparison\n: designed for scenarios where both devices are capable of displaying a six digit number and both are capable of having the user enter \"yes\" or \"no\". A good example of this model is the cell phone / PC scenario.\n\n\n\n\n\n\nOut of Band\n: designed for scenarios where an Out of Band mechanism is used to both discover the devices as well as to exchange or transfer cryptographic numbers used in the pairing process.\n\n\n\n\n\n\nPasskey Entry\n: designed for the scenario where one device has input capability but does not have the capability to display six digits and the other device has output capabilities. A good example of this model is the PC and keyboard scenario.\n\n\n\n\n\n\nKey Generation\n\n\nKey generation for all purposes in Bluetooth LE is performed by the \nHost\n on each LE device independent of any other LE device. \n\n\nPrivacy Feature\n\n\nBluetooth LE supports an optional feature during connection mode and connection procedures that reduces the ability to track a LE device over a period of time by changing the Bluetooth device address on a frequent basis. \n\n\nThere are two variants of the privacy feature. \n\n\n\n\nIn the first variant, private addresses are resolved and generated by the \nHost\n.\n\n\nIn the second variant, private addresses are resolved and generated by the \nController\n without involving the Host after the Host provides the Controller device identity information. The Host may provide the Controller with a complete resolving list or a subset of the resolving list.\nDevice filtering becomes possible in the second variant when address resolution is performed in the Controller because the peer\u2019s device identity address can be resolved prior to checking whether it is in the white list.\n\n\n\n\nNote\n: When address resolution is performed exclusively in the Host, a device may experience increased power consumption because device filtering must be disabled. For more details on the privacy feature, refer to BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part C] (Published 02 December 2014), Page 592.",
- "title": "NimBLE Security"
- },
- {
- "location": "/network/ble/ble_sec/#ble-security",
- "text": "The Bluetooth Low Energy security model includes five distinct security concepts as listed below. For detailed specifications, see BLUETOOTH SPECIFICATION Version 4.2 [Vol 1, Part A]. Pairing : The process for creating one or more shared secret keys. In LE a single link key is generated by combining contributions from each device into a link key used during pairing. Bonding : The act of storing the keys created during pairing for use in subsequent connections in order to form a trusted device pair. Device authentication : Verification that the two devices have the same keys (verify device identity) Encryption : Keeps message confidential. Encryption in Bluetooth LE uses AES-CCM cryptography and is performed in the Controller . Message integrity : Protects against message forgeries. Bluetooth LE uses four association models depending on the I/O capabilities of the devices. Just Works : designed for scenarios where at least one of the devices does not have a display capable of displaying a six digit number nor does it have a keyboard capable of entering six decimal digits. Numeric Comparison : designed for scenarios where both devices are capable of displaying a six digit number and both are capable of having the user enter \"yes\" or \"no\". A good example of this model is the cell phone / PC scenario. Out of Band : designed for scenarios where an Out of Band mechanism is used to both discover the devices as well as to exchange or transfer cryptographic numbers used in the pairing process. Passkey Entry : designed for the scenario where one device has input capability but does not have the capability to display six digits and the other device has output capabilities. A good example of this model is the PC and keyboard scenario.",
- "title": "BLE Security"
- },
- {
- "location": "/network/ble/ble_sec/#key-generation",
- "text": "Key generation for all purposes in Bluetooth LE is performed by the Host on each LE device independent of any other LE device.",
- "title": "Key Generation"
- },
- {
- "location": "/network/ble/ble_sec/#privacy-feature",
- "text": "Bluetooth LE supports an optional feature during connection mode and connection procedures that reduces the ability to track a LE device over a period of time by changing the Bluetooth device address on a frequent basis. There are two variants of the privacy feature. In the first variant, private addresses are resolved and generated by the Host . In the second variant, private addresses are resolved and generated by the Controller without involving the Host after the Host provides the Controller device identity information. The Host may provide the Controller with a complete resolving list or a subset of the resolving list.\nDevice filtering becomes possible in the second variant when address resolution is performed in the Controller because the peer\u2019s device identity address can be resolved prior to checking whether it is in the white list. Note : When address resolution is performed exclusively in the Host, a device may experience increased power consumption because device filtering must be disabled. For more details on the privacy feature, refer to BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part C] (Published 02 December 2014), Page 592.",
- "title": "Privacy Feature"
- },
- {
- "location": "/network/ble/nimble_setup/",
- "text": "Set up a NimBLE application\n\n\nThis tutorial explains how to set up an application using the NimBLE stack. The\nend result will be a framework that you can use to create your own BLE\napplication using the nimble stack.\n\n\nThis tutorial assumes that you have already installed the newt tool and are\nfamiliar with its concepts.\n\n\nCreate a Mynewt project\n\n\nYou start by creating a project space for your own application work using the\nNewt tool (\nmy_proj1\n in this example) and installing all the additional apps\nand libraries available by adding the repo \napache-mynewt-core\n. See the\ntutorial on \nadding a repo\n for more on\nworking with repos.\n\n\n~/dev$ newt new my_proj1\nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in my_proj1...\nProject my_proj1 successfully created.\n~/dev$ tree my_proj1\nmy_proj1\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.yml\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 11 files\n\n~/dev$ cd my_proj1\n~/dev/my_proj1$ newt install\napache-mynewt-core\n\n\n\n\n\nNow it's time to create your own app.\n\n\nCreate an application package\n\n\n~/dev/my_proj1$ newt pkg new apps/ble_app -t app\nDownload package template for package type app.\nPackage successfully installed into /home/me/dev/my_proj1/apps/ble_app.\n\n\n\n\n\nYou now have an application called \napps/ble_app\n. It isn't terribly\ninteresting as far as applications go, but it does all the configuration and\nset up required of a Mynewt app. It will be a useful starting point for our\nBLE application.\n\n\nCreate the target\n\n\nNow you have to create the target that ties your application to a BSP. We will\ncall this target \"ble_tgt\".\n\n\n~/dev/my_proj1$ newt target create ble_tgt\nTarget targets/ble_tgt successfully created\n\n\n\n\n\nWe now have a new target:\n\n\n~/dev/my_proj1]$ tree targets/ble_tgt\ntargets/ble_tgt\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 target.yml\n\n\n\n\n\nThe target is not yet complete though! We need to set some target variables for\nthis project. Currently, the nimble stack has been ported to the Nordic nrf5x\nchipsets; specifically the nrf51 and nrf52. This application will use the nrf52\nbut we will also show the setup for the nrf51 in case your project uses that\nchip.\n\n\nHere is the command you will need to set up your target for the nRF52dk:\n\n\n~/dev/my_proj1$ newt target set ble_tgt \\\n app=apps/ble_app \\\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized\n\n\n\n\n\nHere is the command you will need to set up your target for the nRF51dk:\n\n\n~/dev/my_proj1$ newt target set ble_tgt \\\n app=apps/ble_app \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf51dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized\n\n\n\n\n\nEnter BLE\n\n\nSince our application will support BLE functionality, we need to give it access\nto a BLE stack. We do this by adding the necessary NimBLE packages to the\napp's dependency list. To enable a combined host-controller in the app, add\ndependencies for the NimBLE controller, host, and in-RAM transport to\n\napps/ble_app/pkg.yml\n:\n\n\npkg.deps:\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/sys/console/full\n\n - \n@apache-mynewt-core/sys/log/full\n\n - \n@apache-mynewt-core/sys/stats/full\n\n\n - \n@apache-mynewt-core/net/nimble/controller\n\n\n - \n@apache-mynewt-core/net/nimble/host\n\n\n - \n@apache-mynewt-core/net/nimble/transport/ram\n\n\n\n\n\n\nBuild the target\n\n\nNow would be a good time for a basic sanity check. Let's make sure the target builds.\n\n\n~/dev/my_proj1$ newt build ble_tgt\nBuilding target targets/ble_tgt\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c\n\n...snip...\n\nLinking /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.elf\nTarget successfully built: targets/ble_tgt\n\n\n\n\n\nNow let's try running our minimal application on actual hardware. Attach the target device to your computer and run the application with \nnewt run\n:\n\n\n~/dev/my_proj1$ newt run ble_tgt 0\nApp image succesfully generated: /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.img\n\n...snip...\n\nResetting target\n[Switching to Thread 57005]\n0x000000dc in ?? ()\n(gdb)\n\n\n\n\n\nYou can start the application by pressing \nc \nenter\n at the gdb prompt. When the excitement of watching the idle loop run wears off, quit gdb with \nctrl-c\n q \nenter\n.\n\n\nIf your target fails to build or run, you might want to revisit the \nproject\nblinky tutorial\n to see if there is a setup step\nyou missed. You may also find help by posting a question to the \nmailing\nlist\n or searching the archives.\n\n\nConclusion\n\n\nYou now have a fully functional BLE app (never mind that it doesn't actually do\nanything yet!). With all the necessary infrastructure in place, you can now\nstart turning this into a real application. A good next step would be to turn\nyour app into a beaconing device. The \nBLE iBeacon\ntutorial\n builds on this one and ends with a\nfunctioning iBeacon. For something a little more ambitious, the \nBLE\nperipheral project tutorial\n describes a NimBLE\nperipheral application in detail.",
- "title": "Set up application"
- },
- {
- "location": "/network/ble/nimble_setup/#set-up-a-nimble-application",
- "text": "This tutorial explains how to set up an application using the NimBLE stack. The\nend result will be a framework that you can use to create your own BLE\napplication using the nimble stack. This tutorial assumes that you have already installed the newt tool and are\nfamiliar with its concepts.",
- "title": "Set up a NimBLE application"
- },
- {
- "location": "/network/ble/nimble_setup/#create-a-mynewt-project",
- "text": "You start by creating a project space for your own application work using the\nNewt tool ( my_proj1 in this example) and installing all the additional apps\nand libraries available by adding the repo apache-mynewt-core . See the\ntutorial on adding a repo for more on\nworking with repos. ~/dev$ newt new my_proj1\nDownloading project skeleton from apache/incubator-mynewt-blinky...\nInstalling skeleton in my_proj1...\nProject my_proj1 successfully created.\n~/dev$ tree my_proj1\nmy_proj1\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 main.c\n\u251c\u2500\u2500 project.yml\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 pkg.yml\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 11 files\n\n~/dev$ cd my_proj1\n~/dev/my_proj1$ newt install\napache-mynewt-core Now it's time to create your own app.",
- "title": "Create a Mynewt project"
- },
- {
- "location": "/network/ble/nimble_setup/#create-an-application-package",
- "text": "~/dev/my_proj1$ newt pkg new apps/ble_app -t app\nDownload package template for package type app.\nPackage successfully installed into /home/me/dev/my_proj1/apps/ble_app. You now have an application called apps/ble_app . It isn't terribly\ninteresting as far as applications go, but it does all the configuration and\nset up required of a Mynewt app. It will be a useful starting point for our\nBLE application.",
- "title": "Create an application package"
- },
- {
- "location": "/network/ble/nimble_setup/#create-the-target",
- "text": "Now you have to create the target that ties your application to a BSP. We will\ncall this target \"ble_tgt\". ~/dev/my_proj1$ newt target create ble_tgt\nTarget targets/ble_tgt successfully created We now have a new target: ~/dev/my_proj1]$ tree targets/ble_tgt\ntargets/ble_tgt\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 target.yml The target is not yet complete though! We need to set some target variables for\nthis project. Currently, the nimble stack has been ported to the Nordic nrf5x\nchipsets; specifically the nrf51 and nrf52. This application will use the nrf52\nbut we will also show the setup for the nrf51 in case your project uses that\nchip. Here is the command you will need to set up your target for the nRF52dk: ~/dev/my_proj1$ newt target set ble_tgt \\\n app=apps/ble_app \\\n bsp=@apache-mynewt-core/hw/bsp/nrf52dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf52dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized Here is the command you will need to set up your target for the nRF51dk: ~/dev/my_proj1$ newt target set ble_tgt \\\n app=apps/ble_app \\\n bsp=@apache-mynewt-core/hw/bsp/nrf51dk \\\n build_profile=optimized\nTarget targets/ble_tgt successfully set target.app to apps/ble_app\nTarget targets/ble_tgt successfully set target.bsp to @apache-mynewt-core/hw/bsp/nrf51dk\nTarget targets/ble_tgt successfully set target.build_profile to optimized",
- "title": "Create the target"
- },
- {
- "location": "/network/ble/nimble_setup/#enter-ble",
- "text": "Since our application will support BLE functionality, we need to give it access\nto a BLE stack. We do this by adding the necessary NimBLE packages to the\napp's dependency list. To enable a combined host-controller in the app, add\ndependencies for the NimBLE controller, host, and in-RAM transport to apps/ble_app/pkg.yml : pkg.deps:\n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/sys/console/full \n - @apache-mynewt-core/sys/log/full \n - @apache-mynewt-core/sys/stats/full - @apache-mynewt-core/net/nimble/controller - @apache-mynewt-core/net/nimble/host - @apache-mynewt-core/net/nimble/transport/ram",
- "title": "Enter BLE"
- },
- {
- "location": "/network/ble/nimble_setup/#build-the-target",
- "text": "Now would be a good time for a basic sanity check. Let's make sure the target builds. ~/dev/my_proj1$ newt build ble_tgt\nBuilding target targets/ble_tgt\nCompiling repos/apache-mynewt-core/hw/hal/src/hal_common.c\nCompiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c ...snip... \nLinking /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.elf\nTarget successfully built: targets/ble_tgt Now let's try running our minimal application on actual hardware. Attach the target device to your computer and run the application with newt run : ~/dev/my_proj1$ newt run ble_tgt 0\nApp image succesfully generated: /home/me/dev/my_proj1/bin/targets/ble_tgt/app/apps/ble_app/ble_app.img ...snip... \nResetting target\n[Switching to Thread 57005]\n0x000000dc in ?? ()\n(gdb) You can start the application by pressing c enter at the gdb prompt. When the excitement of watching the idle loop run wears off, quit gdb with ctrl-c q enter . If your target fails to build or run, you might want to revisit the project\nblinky tutorial to see if there is a setup step\nyou missed. You may also find help by posting a question to the mailing\nlist or searching the archives.",
- "title": "Build the target"
- },
- {
- "location": "/network/ble/nimble_setup/#conclusion",
- "text": "You now have a fully functional BLE app (never mind that it doesn't actually do\nanything yet!). With all the necessary infrastructure in place, you can now\nstart turning this into a real application. A good next step would be to turn\nyour app into a beaconing device. The BLE iBeacon\ntutorial builds on this one and ends with a\nfunctioning iBeacon. For something a little more ambitious, the BLE\nperipheral project tutorial describes a NimBLE\nperipheral application in detail.",
- "title": "Conclusion"
- },
- {
- "location": "/network/ble/ini_stack/ble_ini_intro/",
- "text": "Nimble stack initialization\n\n\nWe are now going to explain how to set up your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize and set up your code. For example, the code sample shows modification of main.c in the application \n/src\n folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in \n/src/main.c\n or in the \nmain()\n function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the sections covering stack initialization.\n\n\nA note about the code samples: the \nmain()\n function in each code sample builds upon the previous example. However, code outside of \nmain()\n shows only what we add for each step. The last code sample shows the entire \nmain.c\n that we created.\n\n\nLet's start with a very basic \nmain()\n function (shown below). This \nmain()\n function is identical to the minimal version used in the \nSet up application\n introductory page. In this \nmain()\n all we are doing is initializing the Mynewt OS and starting it.\n\n\n#include\n \nassert.h\n\n\n#include\n \nos/os.h\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}\n\n\n\n\n\nThe Nimble stack requires a number of packages to be initialized prior to being started. We are going to add these one by one to the application and describe each.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ini_stack/ble_ini_intro/#nimble-stack-initialization",
- "text": "We are now going to explain how to set up your application to initialize the nimble stack and to get the basic stack, and its required modules, initialized and up and running. Note that the code shown here is an example of what is required for nimble stack operation; it is not intended to dictate to the developer exactly how to organize and set up your code. For example, the code sample shows modification of main.c in the application /src folder. The developer has the flexibility to organize the code as they see fit so this code does not need to reside in /src/main.c or in the main() function itself. The only possible issue is the order of some of the initializations. Where this order is important it is indicated in the sections covering stack initialization. A note about the code samples: the main() function in each code sample builds upon the previous example. However, code outside of main() shows only what we add for each step. The last code sample shows the entire main.c that we created. Let's start with a very basic main() function (shown below). This main() function is identical to the minimal version used in the Set up application introductory page. In this main() all we are doing is initializing the Mynewt OS and starting it. #include assert.h #include os/os.h int main ( void )\n{\n /* Initialize OS */ \n os_init ();\n\n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n} The Nimble stack requires a number of packages to be initialized prior to being started. We are going to add these one by one to the application and describe each.",
- "title": "Nimble stack initialization"
- },
- {
- "location": "/network/ble/ini_stack/ble_add_cpu/",
- "text": "Add cputime\n\n\nThe NimBLE stack requires \"cputime\". This is provided by the Mynewt HAL of the\nsame name. The cputime HAL provides a high resolution timer that is used by the\nnimble stack (as the BLE specification requires a fairly high resolution timer\nand has fairly tight timing requirements). The cputime HAL allows the user to\nspecify the timer resolution as different applications may require a different\nresolution. While the Nimble stack does not require a specific timer resolution\nper se, a resolution that is too large may affect performance and power\nefficiency. A suggested clock rate for HAL cputime for the nimble stack is 1\nMHz, or 1 microsecond per cputime tick. This provides enough resolution for\nmost needs while providing the Nimble stack enough resolution to implement the\nBLE specification.\n\n\nAdd the initialization of cputime to your application:\n\n\n#include\n \nhal/hal_cputime.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n\n \n/* Set cputime to count at 1 usec increments */\n\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Add cputime"
- },
- {
- "location": "/network/ble/ini_stack/ble_add_cpu/#add-cputime",
- "text": "The NimBLE stack requires \"cputime\". This is provided by the Mynewt HAL of the\nsame name. The cputime HAL provides a high resolution timer that is used by the\nnimble stack (as the BLE specification requires a fairly high resolution timer\nand has fairly tight timing requirements). The cputime HAL allows the user to\nspecify the timer resolution as different applications may require a different\nresolution. While the Nimble stack does not require a specific timer resolution\nper se, a resolution that is too large may affect performance and power\nefficiency. A suggested clock rate for HAL cputime for the nimble stack is 1\nMHz, or 1 microsecond per cputime tick. This provides enough resolution for\nmost needs while providing the Nimble stack enough resolution to implement the\nBLE specification. Add the initialization of cputime to your application: #include hal/hal_cputime.h int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init (); /* Set cputime to count at 1 usec increments */ rc = cputime_init ( 1000000 ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Add cputime"
- },
- {
- "location": "/network/ble/ini_stack/ble_mempool/",
- "text": "Create the System Memory Buffer Pool\n\n\nThe Nimble stack allocates packet buffers (called mbufs) from the system memory buffer pool (msys). The system memory buffer pool and mbufs are described in the OS manual; we suggest reading that section in order to become familiar with mbufs if you are not already familiar with them. Note that the application itself (the unique application code that you are writing) does not need to use mbufs and none of the BLE host API exposed to the application developer uses them. However, the Nimble stack does require the existence of the system memory pool.\n\n\nCreating the memory pool and registering it with the system memory buffer pool can be a bit tricky the first time. However, using the template provided below it should be much easier. The header file /net/nimble/include/nimble/ble.h, which should be included in main.c, contains some MBUF macros that you will need to create the memory pool used by msys. The macro \nBLE_MBUF_PAYLOAD_SIZE\n defines the maximum amount of user payload, plus overhead, that a link layer BLE PDU can contain. The macro \nBLE_MBUF_MEMBLOCK_OVERHEAD\n is the amount of overhead required by the Nimble stack in each memory block used by the mbuf pool. The macro \nMBUF_NUM_MBUFS\n defines the number of mbufs in the mbuf pool and is defined locally. The user must determine, based on application requirements and platform memory size, how many mbufs are required. For example, if your application expects to have many simultaneous connections you may want to increase the size of the mbuf pool. In the example below, we assume you are only using a small number of active connections (2 to 3).\n\n\nA note about the size of the mbufs and \nBLE_MBUF_PAYLOAD_SIZE\n. Msys allows for multiple mbuf pools of various size. Currently, the Nimble stack requires that msys has an mbuf pool registered that can accommodate the maximum size BLE LL PDU. Thus, we only show the creation of one mbuf pool of maximum size mbufs which gets registered to the system mbuf memory pool. We plan on modifying the Nimble stack so that smaller mbufs can be used (to conserve memory) but at this point in time you cannot modify \nBLE_MBUF_PAYLOAD_SIZE\n. Furthermore, you cannot add a mbuf pool of smaller size elements to the msys pool as the msys code might then allocate a mbuf that is too small for the nimble stack.\n\n\n/* Create a mbuf pool of BLE mbufs */\n\n\n#define MBUF_NUM_MBUFS (8)\n\n\n#define MBUF_BUF_SIZE OS_ALIGN(BLE_MBUF_PAYLOAD_SIZE, 4)\n\n\n#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + BLE_MBUF_MEMBLOCK_OVERHEAD)\n\n\n#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE)\n\n\n\n\nstruct\n \nos_mbuf_pool\n \ng_mbuf_pool\n;\n\nstruct\n \nos_mempool\n \ng_mbuf_mempool\n;\n\nos_membuf_t\n \ng_mbuf_buffer\n[\nMBUF_MEMPOOL_SIZE\n];\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n\n \nMBUF_NUM_MBUFS\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Create mem pool"
- },
- {
- "location": "/network/ble/ini_stack/ble_mempool/#create-the-system-memory-buffer-pool",
- "text": "The Nimble stack allocates packet buffers (called mbufs) from the system memory buffer pool (msys). The system memory buffer pool and mbufs are described in the OS manual; we suggest reading that section in order to become familiar with mbufs if you are not already familiar with them. Note that the application itself (the unique application code that you are writing) does not need to use mbufs and none of the BLE host API exposed to the application developer uses them. However, the Nimble stack does require the existence of the system memory pool. Creating the memory pool and registering it with the system memory buffer pool can be a bit tricky the first time. However, using the template provided below it should be much easier. The header file /net/nimble/include/nimble/ble.h, which should be included in main.c, contains some MBUF macros that you will need to create the memory pool used by msys. The macro BLE_MBUF_PAYLOAD_SIZE defines the maximum amount of user payload, plus overhead, that a link layer BLE PDU can contain. The macro BLE_MBUF_MEMBLOCK_OVERHEAD is the amount of overhead required by the Nimble stack in each memory block used by the mbuf pool. The macro MBUF_NUM_MBUFS defines the number of mbufs in the mbuf pool and is defined locally. The user must determine, based on application requirements and platform memory size, how many mbufs are required. For example, if your application expects to have many simultaneous connections you may want to increase the size of the mbuf pool. In the example below, we assume you are only using a small number of active connections (2 to 3). A note about the size of the mbufs and BLE_MBUF_PAYLOAD_SIZE . Msys allows for multiple mbuf pools of various size. Currently, the Nimble stack requires that msys has an mbuf pool registered that can accommodate the maximum size BLE LL PDU. Thus, we only show the creation of one mbuf pool of maximum size mbufs which gets registered to the system mbuf memory pool. We plan on modifying the Nimble stack so that smaller mbufs can be used (to conserve memory) but at this point in time you cannot modify BLE_MBUF_PAYLOAD_SIZE . Furthermore, you cannot add a mbuf pool of smaller size elements to the msys pool as the msys code might then allocate a mbuf that is too small for the nimble stack. /* Create a mbuf pool of BLE mbufs */ #define MBUF_NUM_MBUFS (8) #define MBUF_BUF_SIZE OS_ALIGN(BLE_MBUF_PAYLOAD_SIZE, 4) #define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + BLE_MBUF_MEMBLOCK_OVERHEAD) #define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE) struct os_mbuf_pool g_mbuf_pool ; struct os_mempool g_mbuf_mempool ; os_membuf_t g_mbuf_buffer [ MBUF_MEMPOOL_SIZE ]; int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 ); /* Create memory pool for Nimble packets and register with Msys */ rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS , MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool ); assert ( rc == 0 ); rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE , MBUF_NUM_MBUFS ); assert ( rc == 0 ); rc = os_msys_register ( g_mbuf_pool ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Create the System Memory Buffer Pool"
- },
- {
- "location": "/network/ble/ini_stack/ble_devadd/",
- "text": "Initialize the Device Address\n\n\nThe BLE specification requires that devices have an address (called a device address). This address can be either a public device address or a random device address. The current Nimble stack implementation requires that these addresses be defined somewhere in the application; they are not defined within the Nimble stack itself. This was done so that the entire application could have access to these addresses. We expect that we will move these addresses into the Nimble stack in a future release.\n\n\nThe two variables that must be defined are named \ng_dev_addr\n (public device address) and \ng_random_addr\n (static random address). The device address must be initialized prior to initializing the Nimble stack. The random address does not have to be initialized ahead of time as it is possible to set the random address in the Nimble controller when it is running. In this example, we only initialize the device address. The company OUI in this example is 0a:bb:cc; the unique portion is 11:22:33 for a device address equal to 0a:bb:cc:11:22:33. Note that we store the address in little endian order as BLE expects the OUI to be in the most significant bytes.\n\n\n/* Our global device address (public) */\n\n\nuint8_t\n \ng_dev_addr\n[\nBLE_DEV_ADDR_LEN\n];\n\n\n\n/* Our random address (static) */\n\n\nuint8_t\n \ng_random_addr\n[\nBLE_DEV_ADDR_LEN\n];\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Initialize our device address */\n\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Initialize device addr"
- },
- {
- "location": "/network/ble/ini_stack/ble_devadd/#initialize-the-device-address",
- "text": "The BLE specification requires that devices have an address (called a device address). This address can be either a public device address or a random device address. The current Nimble stack implementation requires that these addresses be defined somewhere in the application; they are not defined within the Nimble stack itself. This was done so that the entire application could have access to these addresses. We expect that we will move these addresses into the Nimble stack in a future release. The two variables that must be defined are named g_dev_addr (public device address) and g_random_addr (static random address). The device address must be initialized prior to initializing the Nimble stack. The random address does not have to be initialized ahead of time as it is possible to set the random address in the Nimble controller when it is running. In this example, we only initialize the device address. The company OUI in this example is 0a:bb:cc; the unique portion is 11:22:33 for a device address equal to 0a:bb:cc:11:22:33. Note that we store the address in little endian order as BLE expects the OUI to be in the most significant bytes. /* Our global device address (public) */ uint8_t g_dev_addr [ BLE_DEV_ADDR_LEN ]; /* Our random address (static) */ uint8_t g_random_addr [ BLE_DEV_ADDR_LEN ]; int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 ); /* Initialize our device address */ g_dev_addr [ 0 ] = 0x33 ; g_dev_addr [ 1 ] = 0x22 ; g_dev_addr [ 2 ] = 0x11 ; g_dev_addr [ 3 ] = 0xcc ; g_dev_addr [ 4 ] = 0xbb ; g_dev_addr [ 5 ] = 0x0a ; \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initialize the Device Address"
- },
- {
- "location": "/network/ble/ini_stack/ble_statpkg/",
- "text": "Initialize the statistics package\n\n\nThe NimBLE stack uses the statistics package. Initializing the statistics package is quite simple; all you need to do is enable it in your target's \nsyscfg.yml\n configuration file and re-build your app.\n\n\nsyscfg\n.\nvals\n:\n \n# Enable the shell task.\n\n \nSHELL_TASK\n: \n1\n\n\n \nSTATS_CLI\n: \n1",
- "title": "Initialize stats pkg"
- },
- {
- "location": "/network/ble/ini_stack/ble_statpkg/#initialize-the-statistics-package",
- "text": "The NimBLE stack uses the statistics package. Initializing the statistics package is quite simple; all you need to do is enable it in your target's syscfg.yml configuration file and re-build your app. syscfg . vals :\n # Enable the shell task. \n SHELL_TASK : 1 STATS_CLI : 1",
- "title": "Initialize the statistics package"
- },
- {
- "location": "/network/ble/ini_stack/ble_consolepkg/",
- "text": "Initializing the console package\n\n\nThe console is also required by the Nimble stack. The console is currently used for log output so it needs to be initialized. For this example, we are not going to use a console receive callback. All this means is that input from the console will not be accepted by default; the developer will have to install their own handler or use one provided by another package (the shell, for example). Just like statistics, the console is initialized by calling the console initialization function \nconsole_init()\n.\n\n\n#include\n \nconsole/console.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Init the console */\n\n\n \nrc\n \n=\n \nconsole_init\n(\nNULL\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Initialize console pkg"
- },
- {
- "location": "/network/ble/ini_stack/ble_consolepkg/#initializing-the-console-package",
- "text": "The console is also required by the Nimble stack. The console is currently used for log output so it needs to be initialized. For this example, we are not going to use a console receive callback. All this means is that input from the console will not be accepted by default; the developer will have to install their own handler or use one provided by another package (the shell, for example). Just like statistics, the console is initialized by calling the console initialization function console_init() . #include console/console.h int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 ); /* Init the console */ rc = console_init ( NULL ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initializing the console package"
- },
- {
- "location": "/network/ble/ini_stack/ble_controller_ini/",
- "text": "Initialize the NimBLE controller\n\n\nThe NimBLE controller is initialized via a call to \nble_ll_init()\n. This function is declared as follows:\n\n\nint\n \nble_ll_init\n(\nuint8_t\n \nll_task_prio\n, \nuint8_t\n \nnum_acl_pkts\n, \nuint16_t\n \nacl_pkt_size\n)\n\n\n\n\n\nThis function's parameters are documented below.\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nprio\n\n\nThe priority of the NimBLE controller task. A lower number corresponds to higher priority.\n\n\n\n\n\n\nnum_acl_pkts\n\n\nThe maximum number of outstanding data packets that the controller will accept from the host.\n\n\n\n\n\n\nacl_pkt_size\n\n\nThe maximum data packet size that the controller will accept from the host.\n\n\n\n\n\n\n\n\nprio\n:\n\n\nIf you are not familiar with multitasking, preemptive operating systems we\nhighly encourage you to read the Core OS section of Mynewt OS manual. It is up\nto the application developer to decide the priority of tasks in the system.\nNote that the lower the priority number the higher the priority in the OS. For\nexample, if a task is running at priority 5 and a task at priority 3 wants to\nrun, the task at priority 5 gets preempted as the other task is a higher\nproiority.\n\n\nIn the example shown below, the LL task is configured to have the highest\npriority (priority 0). We recommend making the BLE LL task the highest priority\ntask in your application as it has fairly rigorous timing requirements and\nallowing other tasks to preempt the LL task could cause undesirable behavior.\nNote that we do not force this to be the case as an application may require a\ntask to be even higher priority than the LL task. Just be warned: a task\nhigher in priority than the LL task should not perform actions that take too\nlong; even a few milliseconds could cause undesirable behavior.\n\n\nnum_acl_pkts\n and \nacl_pkt_size\n:\n\n\nThese two parameters are used to limit the amount of data the host tries to send through the controller. NimBLE uses the msys facility for allocating data packets, so the product of these arguments must not be larger than the total amount of memory allocated for msys. The below example uses some values that are reasonable for most uses.\n\n\n#include\n \ncontroller/ble_ll.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n \nstruct\n \nble_hs_cfg\n \ncfg\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for NimBLE packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Initialize the BLE LL */\n\n\n \nrc\n \n=\n \nble_ll_init\n(\n0\n, \n7\n, \n260\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Initialize controller"
- },
- {
- "location": "/network/ble/ini_stack/ble_controller_ini/#initialize-the-nimble-controller",
- "text": "The NimBLE controller is initialized via a call to ble_ll_init() . This function is declared as follows: int ble_ll_init ( uint8_t ll_task_prio , uint8_t num_acl_pkts , uint16_t acl_pkt_size ) This function's parameters are documented below. Parameter Description prio The priority of the NimBLE controller task. A lower number corresponds to higher priority. num_acl_pkts The maximum number of outstanding data packets that the controller will accept from the host. acl_pkt_size The maximum data packet size that the controller will accept from the host. prio : If you are not familiar with multitasking, preemptive operating systems we\nhighly encourage you to read the Core OS section of Mynewt OS manual. It is up\nto the application developer to decide the priority of tasks in the system.\nNote that the lower the priority number the higher the priority in the OS. For\nexample, if a task is running at priority 5 and a task at priority 3 wants to\nrun, the task at priority 5 gets preempted as the other task is a higher\nproiority. In the example shown below, the LL task is configured to have the highest\npriority (priority 0). We recommend making the BLE LL task the highest priority\ntask in your application as it has fairly rigorous timing requirements and\nallowing other tasks to preempt the LL task could cause undesirable behavior.\nNote that we do not force this to be the case as an application may require a\ntask to be even higher priority than the LL task. Just be warned: a task\nhigher in priority than the LL task should not perform actions that take too\nlong; even a few milliseconds could cause undesirable behavior. num_acl_pkts and acl_pkt_size : These two parameters are used to limit the amount of data the host tries to send through the controller. NimBLE uses the msys facility for allocating data packets, so the product of these arguments must not be larger than the total amount of memory allocated for msys. The below example uses some values that are reasonable for most uses. #include controller/ble_ll.h int main ( void )\n{\n int rc ;\n struct ble_hs_cfg cfg ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for NimBLE packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 ); /* Initialize the BLE LL */ rc = ble_ll_init ( 0 , 7 , 260 ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initialize the NimBLE controller"
- },
- {
- "location": "/network/ble/ini_stack/ble_parent_ini/",
- "text": "Create the host parent task\n\n\nThe NimBLE stack requires an application task to function. One application\ntask in particular is designated as the \nhost parent task\n. In addition to\napplication-specific work, the host parent task does work for NimBLE by\nprocessing events generated by the host.\n\n\nThe process of creating an OS task is described in the \nAdd Task\ntutorial\n.\n\n\nPriority:\n\nIt is up to you which priority to use for the host parent task. Unlike the\ncontroller, the host does not have any strict timing requirements, so the\npriority should be based on the application's needs. In the below example, we\nuse a priority of \n1\n.\n\n\nStack size:\n\nThe host parent task's stack needs to be sufficiently large to handle BLE\noperations. This depends on the set of BLE features your application uses, and\non the specifics application callbacks that the stack is configured to use. A\nsafe value is to use here is \n300 words\n; that is the value used in the below\nexample.\n\n\nThe parent task must do two things:\n\n\n\n\nCall \nble_hs_start()\n before starting its task loop.\n\n\nHandle \nOS_EVENT_T_TIMER\n events within its task loop.\n\n\n\n\nThe \nble_hs_start()\n function is declared as follows:\n\n\nint\n \nble_hs_start\n(\nvoid\n)\n\n\n\n\n\nThe \nble_hs_start()\n function causes the host to send a sequence of HCI\ncommands to the controller. This sequence of commands is necessary for the\nhost and controller to remain in sync.\n\n\nWe add an application task to our example below.\n\n\n#include\n \nos/os.h\n\n\n\n\n/** Application task. */\n\n\nstatic\n \nstruct\n \nos_task\n \napp_task\n;\n\n\n\n/** Application task event queue. */\n\n\nstatic\n \nstruct\n \nos_eventq\n \napp_evq\n;\n\n\n\n/** Application task stack. */\n\n\n#define APP_STACK_SIZE (OS_STACK_ALIGN(300))\n\n\nstatic\n \nos_stack_t\n \napp_stack\n[\nAPP_STACK_SIZE\n];\n\n\n\n/**\n\n\n * Application task.\n\n\n */\n\n\nstatic\n \nvoid\n\n\napp_task_handler\n(\nvoid\n \n*arg\n)\n\n{\n\n \nstruct\n \nos_callout_func\n \n*cf\n;\n\n \nstruct\n \nos_event\n \n*ev\n;\n\n \nint\n \nrc\n;\n\n\n\n \nrc\n \n=\n \nble_hs_start\n();\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n\n \nwhile\n (\n1\n) {\n\n \nev\n \n=\n \nos_eventq_get\n(\napp_evq\n);\n\n \nswitch\n (\nev-\nev_type\n) {\n\n \ncase\n \nOS_EVENT_T_TIMER\n:\n\n \ncf\n \n=\n (\nstruct\n \nos_callout_func\n \n*\n)\nev\n;\n\n \nassert\n(\ncf-\ncf_func\n);\n\n \ncf-\ncf_func\n(\ncf-\ncf_arg\n);\n\n \nbreak\n;\n\n \ndefault\n:\n\n\n \nassert\n(\n0\n);\n\n \nbreak\n;\n\n }\n\n }\n\n}\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize the BLE LL */\n\n \nrc\n \n=\n \nble_ll_init\n(\n0\n, \n7\n, \n260\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Initialize the application task. */\n\n\n \nos_eventq_init\n(\napp_evq\n);\n\n \nos_task_init\n(\napp_task\n, \napp\n, \napp_task_handler\n, \nNULL\n, \n1\n, \nOS_WAIT_FOREVER\n,\n\n \napp_stack\n, \nAPP_STACK_SIZE\n);\n\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Initialize parent task"
- },
- {
- "location": "/network/ble/ini_stack/ble_parent_ini/#create-the-host-parent-task",
- "text": "The NimBLE stack requires an application task to function. One application\ntask in particular is designated as the host parent task . In addition to\napplication-specific work, the host parent task does work for NimBLE by\nprocessing events generated by the host. The process of creating an OS task is described in the Add Task\ntutorial . Priority: \nIt is up to you which priority to use for the host parent task. Unlike the\ncontroller, the host does not have any strict timing requirements, so the\npriority should be based on the application's needs. In the below example, we\nuse a priority of 1 . Stack size: \nThe host parent task's stack needs to be sufficiently large to handle BLE\noperations. This depends on the set of BLE features your application uses, and\non the specifics application callbacks that the stack is configured to use. A\nsafe value is to use here is 300 words ; that is the value used in the below\nexample. The parent task must do two things: Call ble_hs_start() before starting its task loop. Handle OS_EVENT_T_TIMER events within its task loop. The ble_hs_start() function is declared as follows: int ble_hs_start ( void ) The ble_hs_start() function causes the host to send a sequence of HCI\ncommands to the controller. This sequence of commands is necessary for the\nhost and controller to remain in sync. We add an application task to our example below. #include os/os.h /** Application task. */ static struct os_task app_task ; /** Application task event queue. */ static struct os_eventq app_evq ; /** Application task stack. */ #define APP_STACK_SIZE (OS_STACK_ALIGN(300)) static os_stack_t app_stack [ APP_STACK_SIZE ]; /** * Application task. */ static void app_task_handler ( void *arg ) { struct os_callout_func *cf ; struct os_event *ev ; int rc ; rc = ble_hs_start (); assert ( rc == 0 ); while ( 1 ) { ev = os_eventq_get ( app_evq ); switch ( ev- ev_type ) { case OS_EVENT_T_TIMER : cf = ( struct os_callout_func * ) ev ; assert ( cf- cf_func ); cf- cf_func ( cf- cf_arg ); break ; default : assert ( 0 ); break ; } } } int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 );\n\n /* Initialize the BLE LL */ \n rc = ble_ll_init ( 0 , 7 , 260 );\n assert ( rc == 0 ); /* Initialize the application task. */ os_eventq_init ( app_evq ); os_task_init ( app_task , app , app_task_handler , NULL , 1 , OS_WAIT_FOREVER , app_stack , APP_STACK_SIZE ); /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Create the host parent task"
- },
- {
- "location": "/network/ble/ini_stack/ble_host_ini/",
- "text": "Initialize the NimBLE host\n\n\nThe Nimble host is initialized via a call to \nble_hs_init()\n. This function is declared as follows:\n\n\nint\n \nble_hs_init\n(\nstruct\n \nos_eventq\n \n*parent_evq\n, \nstruct\n \nble_hs_cfg\n \n*cfg\n)\n\n\n\n\n\nThe parameters are documented below.\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nparent_evq\n\n\nThe OS event queue that the host should use to schedule host-related operations.\n\n\n\n\n\n\ncfg\n\n\nA pointer to the desired host configuration, or \nNULL\n if you want to use the default settings.\n\n\n\n\n\n\n\n\nparent_evq\n:\n\n\nThis is the event queue associated with the \nhost parent task\n.\n\n\ncfg\n:\n\n\nAs mentioned above, passing a \ncfg\n value of \nNULL\n will initialize the Nimble\nhost with the default configuration. This is convenient while familiarizing\nyourself with the Nimble stack, but ultimately you will probably want to use a\ncustom configuration. For more information on configuring the host, see the\nNimble Configuration Guide (TBD).\n\n\nContinuing with our running example, we now add Nimble host initialization to\nthe \nmain()\n function. This application uses the default host configuration,\nso it specifies \nNULL\n as the second argument to \nble_hs_init()\n.\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\nint\n\n\nmain\n(\nvoid\n)\n{\n \nint\n \nrc\n;\n\n \n/* Initialize OS */\n\n \nos_init\n();\n\n \n/* Set cputime to count at 1 usec increments */\n\n \nrc\n \n=\n \ncputime_init\n(\n1000000\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Create memory pool for Nimble packets and register with Msys */\n\n \nrc\n \n=\n \nos_mempool_init\n(\ng_mbuf_mempool\n, \nMBUF_NUM_MBUFS\n,\n \nMBUF_MEMBLOCK_SIZE\n, \ng_mbuf_buffer\n[\n0\n], \nmbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_mbuf_pool_init\n(\ng_mbuf_pool\n, \ng_mbuf_mempool\n, \nMBUF_MEMBLOCK_SIZE\n,\n \nMBUF_NUM_MBUFS\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \nrc\n \n=\n \nos_msys_register\n(\ng_mbuf_pool\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize our device address */\n\n \ng_dev_addr\n[\n0\n] \n=\n \n0x33\n;\n \ng_dev_addr\n[\n1\n] \n=\n \n0x22\n;\n \ng_dev_addr\n[\n2\n] \n=\n \n0x11\n;\n \ng_dev_addr\n[\n3\n] \n=\n \n0xcc\n;\n \ng_dev_addr\n[\n4\n] \n=\n \n0xbb\n;\n \ng_dev_addr\n[\n5\n] \n=\n \n0x0a\n;\n\n \n/* Initialize the statistics package */\n\n \nrc\n \n=\n \nstats_module_init\n();\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize the BLE LL */\n\n \nrc\n \n=\n \nble_ll_init\n(\n0\n, \n7\n, \n260\n);\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n \n/* Initialize the application task. */\n\n \nos_eventq_init\n(\napp_evq\n);\n \nos_task_init\n(\napp_task\n, \napp\n, \napp_task_handler\n, \nNULL\n, \n1\n, \nOS_WAIT_FOREVER\n,\n \napp_stack\n, \nAPP_STACK_SIZE\n);\n\n\n \n/* Initialize the BLE host. */\n\n\n \nrc\n \n=\n \nble_hs_init\n(\napp_evq\n, \nNULL\n);\n\n \nassert\n(\nrc\n \n==\n \n0\n);\n\n\n \n/* Start the OS */\n\n \nos_start\n();\n\n \n/* os start should never return. If it does, this should be an error */\n\n \nassert\n(\n0\n);\n}",
- "title": "Initialize host"
- },
- {
- "location": "/network/ble/ini_stack/ble_host_ini/#initialize-the-nimble-host",
- "text": "The Nimble host is initialized via a call to ble_hs_init() . This function is declared as follows: int ble_hs_init ( struct os_eventq *parent_evq , struct ble_hs_cfg *cfg ) The parameters are documented below. Parameter Description parent_evq The OS event queue that the host should use to schedule host-related operations. cfg A pointer to the desired host configuration, or NULL if you want to use the default settings. parent_evq : This is the event queue associated with the host parent task . cfg : As mentioned above, passing a cfg value of NULL will initialize the Nimble\nhost with the default configuration. This is convenient while familiarizing\nyourself with the Nimble stack, but ultimately you will probably want to use a\ncustom configuration. For more information on configuring the host, see the\nNimble Configuration Guide (TBD). Continuing with our running example, we now add Nimble host initialization to\nthe main() function. This application uses the default host configuration,\nso it specifies NULL as the second argument to ble_hs_init() . #include host/ble_hs.h int main ( void )\n{\n int rc ;\n\n /* Initialize OS */ \n os_init ();\n\n /* Set cputime to count at 1 usec increments */ \n rc = cputime_init ( 1000000 );\n assert ( rc == 0 );\n\n /* Create memory pool for Nimble packets and register with Msys */ \n rc = os_mempool_init ( g_mbuf_mempool , MBUF_NUM_MBUFS ,\n MBUF_MEMBLOCK_SIZE , g_mbuf_buffer [ 0 ], mbuf_pool );\n assert ( rc == 0 );\n\n rc = os_mbuf_pool_init ( g_mbuf_pool , g_mbuf_mempool , MBUF_MEMBLOCK_SIZE ,\n MBUF_NUM_MBUFS );\n assert ( rc == 0 );\n\n rc = os_msys_register ( g_mbuf_pool );\n assert ( rc == 0 );\n\n /* Initialize our device address */ \n g_dev_addr [ 0 ] = 0x33 ;\n g_dev_addr [ 1 ] = 0x22 ;\n g_dev_addr [ 2 ] = 0x11 ;\n g_dev_addr [ 3 ] = 0xcc ;\n g_dev_addr [ 4 ] = 0xbb ;\n g_dev_addr [ 5 ] = 0x0a ;\n\n /* Initialize the statistics package */ \n rc = stats_module_init ();\n assert ( rc == 0 );\n\n /* Initialize the BLE LL */ \n rc = ble_ll_init ( 0 , 7 , 260 );\n assert ( rc == 0 );\n\n /* Initialize the application task. */ \n os_eventq_init ( app_evq );\n os_task_init ( app_task , app , app_task_handler , NULL , 1 , OS_WAIT_FOREVER ,\n app_stack , APP_STACK_SIZE ); /* Initialize the BLE host. */ rc = ble_hs_init ( app_evq , NULL ); assert ( rc == 0 ); \n /* Start the OS */ \n os_start ();\n\n /* os start should never return. If it does, this should be an error */ \n assert ( 0 );\n}",
- "title": "Initialize the NimBLE host"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs/",
- "text": "NimBLE Host\n\n\nIntroduction\n\n\nAt a high level, the NimBLE stack is divided into two components:\n\n\n\n\nHost\n\n\nController\n\n\n\n\nThis document is an API reference for the host component. If you are interested in the general structure of the NimBLE stack and its non-host components, you might want to read the \nBLE introduction\n.\n\n\nThe host sits directly below the application, and it serves as the interface to the application for all BLE operations.\n\n\nReference\n\n\n\n\nNimBLE Host Return Codes\n\n\nInitialization and Configuration\n\n\nGeneric Access Protocol (GAP)\n\n\nGeneric Attribute Profile (GATT) Client\n\n\nGeneric Attribute Profile (GATT) Server\n\n\nIdentity\n\n\nOther",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs/#nimble-host",
- "text": "",
- "title": "NimBLE Host"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs/#introduction",
- "text": "At a high level, the NimBLE stack is divided into two components: Host Controller This document is an API reference for the host component. If you are interested in the general structure of the NimBLE stack and its non-host components, you might want to read the BLE introduction . The host sits directly below the application, and it serves as the interface to the application for all BLE operations.",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs/#reference",
- "text": "NimBLE Host Return Codes Initialization and Configuration Generic Access Protocol (GAP) Generic Attribute Profile (GATT) Client Generic Attribute Profile (GATT) Server Identity Other",
- "title": "Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/",
- "text": "NimBLE Host Return Codes\n\n\n\n\nIntroduction\n\n\nSummary\n\n\nExample\n\n\n\n\n\n\nReturn Code Reference\n\n\nReturn codes - Core\n\n\nReturn codes - ATT\n\n\nReturn codes - HCI\n\n\nReturn codes - L2CAP\n\n\nReturn codes - Security manager (us)\n\n\nReturn codes - Security manager (peer)\n\n\n\n\n\n\n\n\nIntroduction\n\n\nSummary\n\n\nThe NimBLE host reports status to the application via a set of return codes. The host encompasses several layers of the Bluetooth specification that each defines its own set of status codes. Rather than \"abstract away\" information from lower layers that the application developer might find useful, the NimBLE host aims to indicate precisely what happened when something fails. Consequently, the host utilizes a rather large set of return codes.\n\n\nA return code of 0 indicates success. For failure conditions, the return codes are partitioned into five separate sets:\n\n\n\n\n\n\n\n\nSet\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\nCore\n\n\nErrors detected internally by the NimBLE host.\n\n\n\n\n\n\nATT\n\n\nThe ATT server has reported a failure via the transmission of an ATT Error Response. The return code corresponds to the value of the Error Code field in the response.\n\n\n\n\n\n\nHCI\n\n\nThe controller has reported an error to the host via a command complete or command status HCI event. The return code corresponds to the value of the Status field in the event.\n\n\n\n\n\n\nL2CAP\n\n\nAn L2CAP signaling procedure has failed and an L2CAP Command Reject was sent as a result. The return code corresponds to the value of the Reason field in the command.\n\n\n\n\n\n\nSecurity manager (us)\n\n\nThe host detected an error during a security manager procedure and sent a Pairing Failed command to the peer. The return code corresponds to the value of the Reason field in the Pairing Failed command.\n\n\n\n\n\n\nSecurity manager (peer)\n\n\nA security manager procedure failed because the peer sent us a Pairing Failed command. The return code corresponds to the value of the Reason field in the Pairing Failed command.\n\n\n\n\n\n\n\n\nThe return codes in the core set are defined by the NimBLE Host. The other sets are defined in the Bluetooth specification; the codes in this latter group are referred to as \nformal status codes\n. As defined in the Bluetooth specification, the formal status code sets are not disjoint. That is, they overlap. For example, the spec defines a status code of 1 to have all of the following meanings:\n\n\n\n\n\n\n\n\nLayer\n\n\nMeaning\n\n\n\n\n\n\n\n\n\n\nATT\n\n\nInvalid handle.\n\n\n\n\n\n\nHCI\n\n\nUnknown HCI command.\n\n\n\n\n\n\nL2CAP\n\n\nSignalling MTU exceeded.\n\n\n\n\n\n\nSM\n\n\nPasskey entry failed.\n\n\n\n\n\n\n\n\nClearly, the host can't just return an unadorned formal status code and expect the application to make sense of it. To resolve this ambiguity, the NimBLE host divides the full range of an int into several subranges. Each subrange corresponds to one of the five return code sets. For example, the ATT set is mapped onto the subrange \n[0x100, 0x200)\n. To indicate an ATT error of 3 (write not permitted), the NimBLE host returns a value 0x103 to the application.\n\n\nThe host defines a set of convenience macros for converting from a formal status code to NimBLE host status code. These macros are documented in the table below.\n\n\n\n\n\n\n\n\nMacro\n\n\nStatus code set\n\n\nBase value\n\n\n\n\n\n\n\n\n\n\nBLE_HS_ATT_ERR()\n\n\nATT\n\n\n0x100\n\n\n\n\n\n\nBLE_HS_HCI_ERR()\n\n\nHCI\n\n\n0x200\n\n\n\n\n\n\nBLE_HS_L2C_ERR()\n\n\nL2CAP\n\n\n0x300\n\n\n\n\n\n\nBLE_HS_SM_US_ERR()\n\n\nSecurity manager (us)\n\n\n0x400\n\n\n\n\n\n\nBLE_HS_SM_PEER_ERR()\n\n\nSecurity manager (peer)\n\n\n0x500\n\n\n\n\n\n\n\n\nExample\n\n\nThe following example demonstrates how an application might determine which error is being reported by the host. In this example, the application performs the GAP encryption procedure and checks the return code. To simplify the example, the application uses a hypothetical \nmy_blocking_enc_proc()\n function, which blocks until the pairing operation has completed.\n\n\nvoid\n\n\nencrypt_connection\n(\nuint16_t\n \nconn_handle\n)\n{\n \nint\n \nrc\n;\n\n \n/* Perform a blocking GAP encryption procedure. */\n\n \nrc\n \n=\n \nmy_blocking_enc_proc\n(\nconn_handle\n);\n \nswitch\n (\nrc\n) {\n \ncase\n \n0\n:\n\n \nconsole_printf\n(\nsuccess - link successfully encrypted\\n\n);\n \nbreak\n;\n\n \ncase\n \nBLE_HS_ENOTCONN\n:\n \nconsole_printf\n(\nfailure - no connection with handle %d\\n\n,\n \nconn_handle\n);\n \nbreak\n;\n\n \ncase\n \nBLE_HS_ERR_SM_US_BASE\n(\nBLE_SM_ERR_CONFIRM_MISMATCH\n)\n:\n\n \nconsole_printf\n(\nfailure - mismatch in peer\ns confirm and random \n\n \ncommands.\\n\n);\n \nbreak\n;\n\n \ncase\n \nBLE_HS_ERR_SM_PEER_BASE\n(\nBLE_SM_ERR_CONFIRM_MISMATCH\n)\n:\n\n \nconsole_printf\n(\nfailure - peer reports mismatch in our confirm and \n\n \nrandom commands.\\n\n);\n \nbreak\n;\n\n \ndefault\n:\n\n \nconsole_printf\n(\nfailure - other error: 0x%04x\\n\n, \nrc\n);\n \nbreak\n;\n }\n}\n\n\n\n\n\nReturn Code Reference\n\n\nHeader\n\n\nAll NimBLE host return codes are made accessible by including the following header:\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nReturn codes - Core\n\n\nThe precise meaning of each of these error codes depends on the function that returns it. The API reference for a particular function indicates the conditions under which each of these codes are returned.\n\n\n\n\n\n\n\n\nValue\n\n\nName\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0x00\n\n\nN/A\n\n\nSuccess\n\n\n\n\n\n\n0x01\n\n\nBLE_HS_EAGAIN\n\n\nTemporary failure; try again.\n\n\n\n\n\n\n0x02\n\n\nBLE_HS_EALREADY\n\n\nOperation already in progress or completed.\n\n\n\n\n\n\n0x03\n\n\nBLE_HS_EINVAL\n\n\nOne or more arguments are invalid.\n\n\n\n\n\n\n0x04\n\n\nBLE_HS_EMSGSIZE\n\n\nThe provided buffer is too small.\n\n\n\n\n\n\n0x05\n\n\nBLE_HS_ENOENT\n\n\nNo entry matching the specified criteria.\n\n\n\n\n\n\n0x06\n\n\nBLE_HS_ENOMEM\n\n\nOperation failed due to resource exhaustion.\n\n\n\n\n\n\n0x07\n\n\nBLE_HS_ENOTCONN\n\n\nNo open connection with the specified handle.\n\n\n\n\n\n\n0x08\n\n\nBLE_HS_ENOTSUP\n\n\nOperation disabled at compile time.\n\n\n\n\n\n\n0x09\n\n\nBLE_HS_EAPP\n\n\nApplication callback behaved unexpectedly.\n\n\n\n\n\n\n0x0a\n\n\nBLE_HS_EBADDATA\n\n\nCommand from peer is invalid.\n\n\n\n\n\n\n0x0b\n\n\nBLE_HS_EOS\n\n\nMynewt OS error.\n\n\n\n\n\n\n0x0c\n\n\nBLE_HS_ECONTROLLER\n\n\nEvent from controller is invalid.\n\n\n\n\n\n\n0x0d\n\n\nBLE_HS_ETIMEOUT\n\n\nOperation timed out.\n\n\n\n\n\n\n0x0e\n\n\nBLE_HS_EDONE\n\n\nOperation completed successfully.\n\n\n\n\n\n\n0x0f\n\n\nBLE_HS_EBUSY\n\n\nOperation cannot be performed until procedure completes.\n\n\n\n\n\n\n0x10\n\n\nBLE_HS_EREJECT\n\n\nPeer rejected a connection parameter update request.\n\n\n\n\n\n\n0x11\n\n\nBLE_HS_EUNKNOWN\n\n\nUnexpected failure; catch all.\n\n\n\n\n\n\n0x12\n\n\nBLE_HS_EROLE\n\n\nOperation requires different role (e.g., central vs. peripheral).\n\n\n\n\n\n\n0x13\n\n\nBLE_HS_ETIMEOUT_HCI\n\n\nHCI request timed out; controller unresponsive.\n\n\n\n\n\n\n0x14\n\n\nBLE_HS_ENOMEM_EVT\n\n\nController failed to send event due to memory exhaustion (combined host-controller only).\n\n\n\n\n\n\n0x15\n\n\nBLE_HS_ENOADDR\n\n\nOperation requires an identity address but none configured.\n\n\n\n\n\n\n\n\nReturn codes - ATT\n\n\n\n\n\n\n\n\nNimBLE Value\n\n\nFormal Value\n\n\nName\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0x0101\n\n\n0x01\n\n\nBLE_ATT_ERR_INVALID_HANDLE\n\n\nThe attribute handle given was not valid on this server.\n\n\n\n\n\n\n0x0102\n\n\n0x02\n\n\nBLE_ATT_ERR_READ_NOT_PERMITTED\n\n\nThe attribute cannot be read.\n\n\n\n\n\n\n0x0103\n\n\n0x03\n\n\nBLE_ATT_ERR_WRITE_NOT_PERMITTED\n\n\nThe attribute cannot be written.\n\n\n\n\n\n\n0x0104\n\n\n0x04\n\n\nBLE_ATT_ERR_INVALID_PDU\n\n\nThe attribute PDU was invalid.\n\n\n\n\n\n\n0x0105\n\n\n0x05\n\n\nBLE_ATT_ERR_INSUFFICIENT_AUTHEN\n\n\nThe attribute requires authentication before it can be read or written.\n\n\n\n\n\n\n0x0106\n\n\n0x06\n\n\nBLE_ATT_ERR_REQ_NOT_SUPPORTED\n\n\nAttribute server does not support the request received from the client.\n\n\n\n\n\n\n0x0107\n\n\n0x07\n\n\nBLE_ATT_ERR_INVALID_OFFSET\n\n\nOffset specified was past the end of the attribute.\n\n\n\n\n\n\n0x0108\n\n\n0x08\n\n\nBLE_ATT_ERR_INSUFFICIENT_AUTHOR\n\n\nThe attribute requires authorization before it can be read or written.\n\n\n\n\n\n\n0x0109\n\n\n0x09\n\n\nBLE_ATT_ERR_PREPARE_QUEUE_FULL\n\n\nToo many prepare writes have been queued.\n\n\n\n\n\n\n0x010a\n\n\n0x0a\n\n\nBLE_ATT_ERR_ATTR_NOT_FOUND\n\n\nNo attribute found within the given attribute handle range.\n\n\n\n\n\n\n0x010b\n\n\n0x0b\n\n\nBLE_ATT_ERR_ATTR_NOT_LONG\n\n\nThe attribute cannot be read or written using the Read Blob Request.\n\n\n\n\n\n\n0x010c\n\n\n0x0c\n\n\nBLE_ATT_ERR_INSUFFICIENT_KEY_SZ\n\n\nThe Encryption Key Size used for encrypting this link is insufficient.\n\n\n\n\n\n\n0x010d\n\n\n0x0d\n\n\nBLE_ATT_ERR_INVALID_ATTR_VALUE_LEN\n\n\nThe attribute value length is invalid for the operation.\n\n\n\n\n\n\n0x010e\n\n\n0x0e\n\n\nBLE_ATT_ERR_UNLIKELY\n\n\nThe attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.\n\n\n\n\n\n\n0x010f\n\n\n0x0f\n\n\nBLE_ATT_ERR_INSUFFICIENT_ENC\n\n\nThe attribute requires encryption before it can be read or written.\n\n\n\n\n\n\n0x0110\n\n\n0x10\n\n\nBLE_ATT_ERR_UNSUPPORTED_GROUP\n\n\nThe attribute type is not a supported grouping attribute as defined by a higher layer specification.\n\n\n\n\n\n\n0x0111\n\n\n0x11\n\n\nBLE_ATT_ERR_INSUFFICIENT_RES\n\n\nInsufficient Resources to complete the request.\n\n\n\n\n\n\n\n\nReturn codes - HCI\n\n\n\n\n\n\n\n\nNimBLE Value\n\n\nFormal Value\n\n\nName\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0x0201\n\n\n0x01\n\n\nBLE_ERR_UNKNOWN_HCI_CMD\n\n\nUnknown HCI Command\n\n\n\n\n\n\n0x0202\n\n\n0x02\n\n\nBLE_ERR_UNK_CONN_ID\n\n\nUnknown Connection Identifier\n\n\n\n\n\n\n0x0203\n\n\n0x03\n\n\nBLE_ERR_HW_FAIL\n\n\nHardware Failure\n\n\n\n\n\n\n0x0204\n\n\n0x04\n\n\nBLE_ERR_PAGE_TMO\n\n\nPage Timeout\n\n\n\n\n\n\n0x0205\n\n\n0x05\n\n\nBLE_ERR_AUTH_FAIL\n\n\nAuthentication Failure\n\n\n\n\n\n\n0x0206\n\n\n0x06\n\n\nBLE_ERR_PINKEY_MISSING\n\n\nPIN or Key Missing\n\n\n\n\n\n\n0x0207\n\n\n0x07\n\n\nBLE_ERR_MEM_CAPACITY\n\n\nMemory Capacity Exceeded\n\n\n\n\n\n\n0x0208\n\n\n0x08\n\n\nBLE_ERR_CONN_SPVN_TMO\n\n\nConnection Timeout\n\n\n\n\n\n\n0x0209\n\n\n0x09\n\n\nBLE_ERR_CONN_LIMIT\n\n\nConnection Limit Exceeded\n\n\n\n\n\n\n0x020a\n\n\n0x0a\n\n\nBLE_ERR_SYNCH_CONN_LIMIT\n\n\nSynchronous Connection Limit To A Device Exceeded\n\n\n\n\n\n\n0x020b\n\n\n0x0b\n\n\nBLE_ERR_ACL_CONN_EXISTS\n\n\nACL Connection Already Exists\n\n\n\n\n\n\n0x020c\n\n\n0x0c\n\n\nBLE_ERR_CMD_DISALLOWED\n\n\nCommand Disallowed\n\n\n\n\n\n\n0x020d\n\n\n0x0d\n\n\nBLE_ERR_CONN_REJ_RESOURCES\n\n\nConnection Rejected due to Limited Resources\n\n\n\n\n\n\n0x020e\n\n\n0x0e\n\n\nBLE_ERR_CONN_REJ_SECURITY\n\n\nConnection Rejected Due To Security Reasons\n\n\n\n\n\n\n0x020f\n\n\n0x0f\n\n\nBLE_ERR_CONN_REJ_BD_ADDR\n\n\nConnection Rejected due to Unacceptable BD_ADDR\n\n\n\n\n\n\n0x0210\n\n\n0x10\n\n\nBLE_ERR_CONN_ACCEPT_TMO\n\n\nConnection Accept Timeout Exceeded\n\n\n\n\n\n\n0x0211\n\n\n0x11\n\n\nBLE_ERR_UNSUPPORTED\n\n\nUnsupported Feature or Parameter Value\n\n\n\n\n\n\n0x0212\n\n\n0x12\n\n\nBLE_ERR_INV_HCI_CMD_PARMS\n\n\nInvalid HCI Command Parameters\n\n\n\n\n\n\n0x0213\n\n\n0x13\n\n\nBLE_ERR_REM_USER_CONN_TERM\n\n\nRemote User Terminated Connection\n\n\n\n\n\n\n0x0214\n\n\n0x14\n\n\nBLE_ERR_RD_CONN_TERM_RESRCS\n\n\nRemote Device Terminated Connection due to Low Resources\n\n\n\n\n\n\n0x0215\n\n\n0x15\n\n\nBLE_ERR_RD_CONN_TERM_PWROFF\n\n\nRemote Device Terminated Connection due to Power Off\n\n\n\n\n\n\n0x0216\n\n\n0x16\n\n\nBLE_ERR_CONN_TERM_LOCAL\n\n\nConnection Terminated By Local Host\n\n\n\n\n\n\n0x0217\n\n\n0x17\n\n\nBLE_ERR_REPEATED_ATTEMPTS\n\n\nRepeated Attempts\n\n\n\n\n\n\n0x0218\n\n\n0x18\n\n\nBLE_ERR_NO_PAIRING\n\n\nPairing Not Allowed\n\n\n\n\n\n\n0x0219\n\n\n0x19\n\n\nBLE_ERR_UNK_LMP\n\n\nUnknown LMP PDU\n\n\n\n\n\n\n0x021a\n\n\n0x1a\n\n\nBLE_ERR_UNSUPP_REM_FEATURE\n\n\nUnsupported Remote Feature / Unsupported LMP Feature\n\n\n\n\n\n\n0x021b\n\n\n0x1b\n\n\nBLE_ERR_SCO_OFFSET\n\n\nSCO Offset Rejected\n\n\n\n\n\n\n0x021c\n\n\n0x1c\n\n\nBLE_ERR_SCO_ITVL\n\n\nSCO Interval Rejected\n\n\n\n\n\n\n0x021d\n\n\n0x1d\n\n\nBLE_ERR_SCO_AIR_MODE\n\n\nSCO Air Mode Rejected\n\n\n\n\n\n\n0x021e\n\n\n0x1e\n\n\nBLE_ERR_INV_LMP_LL_PARM\n\n\nInvalid LMP Parameters / Invalid LL Parameters\n\n\n\n\n\n\n0x021f\n\n\n0x1f\n\n\nBLE_ERR_UNSPECIFIED\n\n\nUnspecified Error\n\n\n\n\n\n\n0x0220\n\n\n0x20\n\n\nBLE_ERR_UNSUPP_LMP_LL_PARM\n\n\nUnsupported LMP Parameter Value / Unsupported LL Parameter Value\n\n\n\n\n\n\n0x0221\n\n\n0x21\n\n\nBLE_ERR_NO_ROLE_CHANGE\n\n\nRole Change Not Allowed\n\n\n\n\n\n\n0x0222\n\n\n0x22\n\n\nBLE_ERR_LMP_LL_RSP_TMO\n\n\nLMP Response Timeout / LL Response Timeout\n\n\n\n\n\n\n0x0223\n\n\n0x23\n\n\nBLE_ERR_LMP_COLLISION\n\n\nLMP Error Transaction Collision\n\n\n\n\n\n\n0x0224\n\n\n0x24\n\n\nBLE_ERR_LMP_PDU\n\n\nLMP PDU Not Allowed\n\n\n\n\n\n\n0x0225\n\n\n0x25\n\n\nBLE_ERR_ENCRYPTION_MODE\n\n\nEncryption Mode Not Acceptable\n\n\n\n\n\n\n0x0226\n\n\n0x26\n\n\nBLE_ERR_LINK_KEY_CHANGE\n\n\nLink Key cannot be Changed\n\n\n\n\n\n\n0x0227\n\n\n0x27\n\n\nBLE_ERR_UNSUPP_QOS\n\n\nRequested QoS Not Supported\n\n\n\n\n\n\n0x0228\n\n\n0x28\n\n\nBLE_ERR_INSTANT_PASSED\n\n\nInstant Passed\n\n\n\n\n\n\n0x0229\n\n\n0x29\n\n\nBLE_ERR_UNIT_KEY_PAIRING\n\n\nPairing With Unit Key Not Supported\n\n\n\n\n\n\n0x022a\n\n\n0x2a\n\n\nBLE_ERR_DIFF_TRANS_COLL\n\n\nDifferent Transaction Collision\n\n\n\n\n\n\n0x022c\n\n\n0x2c\n\n\nBLE_ERR_QOS_PARM\n\n\nQoS Unacceptable Parameter\n\n\n\n\n\n\n0x022d\n\n\n0x2d\n\n\nBLE_ERR_QOS_REJECTED\n\n\nQoS Rejected\n\n\n\n\n\n\n0x022e\n\n\n0x2e\n\n\nBLE_ERR_CHAN_CLASS\n\n\nChannel Classification Not Supported\n\n\n\n\n\n\n0x022f\n\n\n0x2f\n\n\nBLE_ERR_INSUFFICIENT_SEC\n\n\nInsufficient Security\n\n\n\n\n\n\n0x0230\n\n\n0x30\n\n\nBLE_ERR_PARM_OUT_OF_RANGE\n\n\nParameter Out Of Mandatory Range\n\n\n\n\n\n\n0x0232\n\n\n0x32\n\n\nBLE_ERR_PENDING_ROLE_SW\n\n\nRole Switch Pending\n\n\n\n\n\n\n0x0234\n\n\n0x34\n\n\nBLE_ERR_RESERVED_SLOT\n\n\nReserved Slot Violation\n\n\n\n\n\n\n0x0235\n\n\n0x35\n\n\nBLE_ERR_ROLE_SW_FAIL\n\n\nRole Switch Failed\n\n\n\n\n\n\n0x0236\n\n\n0x36\n\n\nBLE_ERR_INQ_RSP_TOO_BIG\n\n\nExtended Inquiry Response Too Large\n\n\n\n\n\n\n0x0237\n\n\n0x37\n\n\nBLE_ERR_SEC_SIMPLE_PAIR\n\n\nSecure Simple Pairing Not Supported By Host\n\n\n\n\n\n\n0x0238\n\n\n0x38\n\n\nBLE_ERR_HOST_BUSY_PAIR\n\n\nHost Busy - Pairing\n\n\n\n\n\n\n0x0239\n\n\n0x39\n\n\nBLE_ERR_CONN_REJ_CHANNEL\n\n\nConnection Rejected due to No Suitable Channel Found\n\n\n\n\n\n\n0x023a\n\n\n0x3a\n\n\nBLE_ERR_CTLR_BUSY\n\n\nController Busy\n\n\n\n\n\n\n0x023b\n\n\n0x3b\n\n\nBLE_ERR_CONN_PARMS\n\n\nUnacceptable Connection Parameters\n\n\n\n\n\n\n0x023c\n\n\n0x3c\n\n\nBLE_ERR_DIR_ADV_TMO\n\n\nDirected Advertising Timeout\n\n\n\n\n\n\n0x023d\n\n\n0x3d\n\n\nBLE_ERR_CONN_TERM_MIC\n\n\nConnection Terminated due to MIC Failure\n\n\n\n\n\n\n0x023e\n\n\n0x3e\n\n\nBLE_ERR_CONN_ESTABLISHMENT\n\n\nConnection Failed to be Established\n\n\n\n\n\n\n0x023f\n\n\n0x3f\n\n\nBLE_ERR_MAC_CONN_FAIL\n\n\nMAC Connection Failed\n\n\n\n\n\n\n0x0240\n\n\n0x40\n\n\nBLE_ERR_COARSE_CLK_ADJ\n\n\nCoarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging\n\n\n\n\n\n\n\n\nReturn codes - L2CAP\n\n\n\n\n\n\n\n\nNimBLE Value\n\n\nFormal Value\n\n\nName\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0x0300\n\n\n0x00\n\n\nBLE_L2CAP_SIG_ERR_CMD_NOT_UNDERSTOOD\n\n\nInvalid or unsupported incoming L2CAP sig command.\n\n\n\n\n\n\n0x0301\n\n\n0x01\n\n\nBLE_L2CAP_SIG_ERR_MTU_EXCEEDED\n\n\nIncoming packet too large.\n\n\n\n\n\n\n0x0302\n\n\n0x02\n\n\nBLE_L2CAP_SIG_ERR_INVALID_CID\n\n\nNo channel with specified ID.\n\n\n\n\n\n\n\n\nReturn codes - Security manager (us)\n\n\n\n\n\n\n\n\nNimBLE Value\n\n\nFormal Value\n\n\nName\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0x0401\n\n\n0x01\n\n\nBLE_SM_ERR_PASSKEY\n\n\nThe user input of passkey failed, for example, the user cancelled the operation.\n\n\n\n\n\n\n0x0402\n\n\n0x02\n\n\nBLE_SM_ERR_OOB\n\n\nThe OOB data is not available.\n\n\n\n\n\n\n0x0403\n\n\n0x03\n\n\nBLE_SM_ERR_AUTHREQ\n\n\nThe pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices.\n\n\n\n\n\n\n0x0404\n\n\n0x04\n\n\nBLE_SM_ERR_CONFIRM_MISMATCH\n\n\nThe confirm value does not match the calculated compare value.\n\n\n\n\n\n\n0x0405\n\n\n0x05\n\n\nBLE_SM_ERR_PAIR_NOT_SUPP\n\n\nPairing is not supported by the device.\n\n\n\n\n\n\n0x0406\n\n\n0x06\n\n\nBLE_SM_ERR_ENC_KEY_SZ\n\n\nThe resultant encryption key size is insufficient for the security requirements of this device.\n\n\n\n\n\n\n0x0407\n\n\n0x07\n\n\nBLE_SM_ERR_CMD_NOT_SUPP\n\n\nThe SMP command received is not supported on this device.\n\n\n\n\n\n\n0x0408\n\n\n0x08\n\n\nBLE_SM_ERR_UNSPECIFIED\n\n\nPairing failed due to an unspecified reason.\n\n\n\n\n\n\n0x0409\n\n\n0x09\n\n\nBLE_SM_ERR_REPEATED\n\n\nPairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request.\n\n\n\n\n\n\n0x040a\n\n\n0x0a\n\n\nBLE_SM_ERR_INVAL\n\n\nThe Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range.\n\n\n\n\n\n\n0x040b\n\n\n0x0b\n\n\nBLE_SM_ERR_DHKEY\n\n\nIndicates to the remote device that the DHKey Check value received doesn\u2019t match the one calculated by the local device.\n\n\n\n\n\n\n0x040c\n\n\n0x0c\n\n\nBLE_SM_ERR_NUMCMP\n\n\nIndicates that the confirm values in the numeric comparison protocol do not match.\n\n\n\n\n\n\n0x040d\n\n\n0x0d\n\n\nBLE_SM_ERR_ALREADY\n\n\nIndicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process.\n\n\n\n\n\n\n0x040e\n\n\n0x0e\n\n\nBLE_SM_ERR_CROSS_TRANS\n\n\nIndicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.\n\n\n\n\n\n\n\n\nReturn codes - Security manager (peer)\n\n\n\n\n\n\n\n\nNimBLE Value\n\n\nFormal Value\n\n\nName\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0x0501\n\n\n0x01\n\n\nBLE_SM_ERR_PASSKEY\n\n\nThe user input of passkey failed, for example, the user cancelled the operation.\n\n\n\n\n\n\n0x0502\n\n\n0x02\n\n\nBLE_SM_ERR_OOB\n\n\nThe OOB data is not available.\n\n\n\n\n\n\n0x0503\n\n\n0x03\n\n\nBLE_SM_ERR_AUTHREQ\n\n\nThe pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices.\n\n\n\n\n\n\n0x0504\n\n\n0x04\n\n\nBLE_SM_ERR_CONFIRM_MISMATCH\n\n\nThe confirm value does not match the calculated compare value.\n\n\n\n\n\n\n0x0505\n\n\n0x05\n\n\nBLE_SM_ERR_PAIR_NOT_SUPP\n\n\nPairing is not supported by the device.\n\n\n\n\n\n\n0x0506\n\n\n0x06\n\n\nBLE_SM_ERR_ENC_KEY_SZ\n\n\nThe resultant encryption key size is insufficient for the security requirements of this device.\n\n\n\n\n\n\n0x0507\n\n\n0x07\n\n\nBLE_SM_ERR_CMD_NOT_SUPP\n\n\nThe SMP command received is not supported on this device.\n\n\n\n\n\n\n0x0508\n\n\n0x08\n\n\nBLE_SM_ERR_UNSPECIFIED\n\n\nPairing failed due to an unspecified reason.\n\n\n\n\n\n\n0x0509\n\n\n0x09\n\n\nBLE_SM_ERR_REPEATED\n\n\nPairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request.\n\n\n\n\n\n\n0x050a\n\n\n0x0a\n\n\nBLE_SM_ERR_INVAL\n\n\nThe Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range.\n\n\n\n\n\n\n0x050b\n\n\n0x0b\n\n\nBLE_SM_ERR_DHKEY\n\n\nIndicates to the remote device that the DHKey Check value received doesn\u2019t match the one calculated by the local device.\n\n\n\n\n\n\n0x050c\n\n\n0x0c\n\n\nBLE_SM_ERR_NUMCMP\n\n\nIndicates that the confirm values in the numeric comparison protocol do not match.\n\n\n\n\n\n\n0x050d\n\n\n0x0d\n\n\nBLE_SM_ERR_ALREADY\n\n\nIndicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process.\n\n\n\n\n\n\n0x050e\n\n\n0x0e\n\n\nBLE_SM_ERR_CROSS_TRANS\n\n\nIndicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.",
- "title": "Return codes"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#nimble-host-return-codes",
- "text": "Introduction Summary Example Return Code Reference Return codes - Core Return codes - ATT Return codes - HCI Return codes - L2CAP Return codes - Security manager (us) Return codes - Security manager (peer)",
- "title": "NimBLE Host Return Codes"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#introduction",
- "text": "",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#summary",
- "text": "The NimBLE host reports status to the application via a set of return codes. The host encompasses several layers of the Bluetooth specification that each defines its own set of status codes. Rather than \"abstract away\" information from lower layers that the application developer might find useful, the NimBLE host aims to indicate precisely what happened when something fails. Consequently, the host utilizes a rather large set of return codes. A return code of 0 indicates success. For failure conditions, the return codes are partitioned into five separate sets: Set Condition Core Errors detected internally by the NimBLE host. ATT The ATT server has reported a failure via the transmission of an ATT Error Response. The return code corresponds to the value of the Error Code field in the response. HCI The controller has reported an error to the host via a command complete or command status HCI event. The return code corresponds to the value of the Status field in the event. L2CAP An L2CAP signaling procedure has failed and an L2CAP Command Reject was sent as a result. The return code corresponds to the value of the Reason field in the command. Security manager (us) The host detected an error during a security manager procedure and sent a Pairing Failed command to the peer. The return code corresponds to the value of the Reason field in the Pairing Failed command. Security manager (peer) A security manager procedure failed because the peer sent us a Pairing Failed command. The return code corresponds to the value of the Reason field in the Pairing Failed command. The return codes in the core set are defined by the NimBLE Host. The other sets are defined in the Bluetooth specification; the codes in this latter group are referred to as formal status codes . As defined in the Bluetooth specification, the formal status code sets are not disjoint. That is, they overlap. For example, the spec defines a status code of 1 to have all of the following meanings: Layer Meaning ATT Invalid handle. HCI Unknown HCI command. L2CAP Signalling MTU exceeded. SM Passkey entry failed. Clearly, the host can't just return an unadorned formal status code and expect the application to make sense of it. To resolve this ambiguity, the NimBLE host divides the full range of an int into several subranges. Each subrange corresponds to one of the five return code sets. For example, the ATT set is mapped onto the subrange [0x100, 0x200) . To indicate an ATT error of 3 (write not permitted), the NimBLE host returns a value 0x103 to the application. The host defines a set of convenience macros for converting from a formal status code to NimBLE host status code. These macros are documented in the table below. Macro Status code set Base value BLE_HS_ATT_ERR() ATT 0x100 BLE_HS_HCI_ERR() HCI 0x200 BLE_HS_L2C_ERR() L2CAP 0x300 BLE_HS_SM_US_ERR() Security manager (us) 0x400 BLE_HS_SM_PEER_ERR() Security manager (peer) 0x500",
- "title": "Summary"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#example",
- "text": "The following example demonstrates how an application might determine which error is being reported by the host. In this example, the application performs the GAP encryption procedure and checks the return code. To simplify the example, the application uses a hypothetical my_blocking_enc_proc() function, which blocks until the pairing operation has completed. void encrypt_connection ( uint16_t conn_handle )\n{\n int rc ;\n\n /* Perform a blocking GAP encryption procedure. */ \n rc = my_blocking_enc_proc ( conn_handle );\n switch ( rc ) {\n case 0 : \n console_printf ( success - link successfully encrypted\\n );\n break ;\n\n case BLE_HS_ENOTCONN :\n console_printf ( failure - no connection with handle %d\\n ,\n conn_handle );\n break ;\n\n case BLE_HS_ERR_SM_US_BASE ( BLE_SM_ERR_CONFIRM_MISMATCH ) : \n console_printf ( failure - mismatch in peer s confirm and random \n commands.\\n );\n break ;\n\n case BLE_HS_ERR_SM_PEER_BASE ( BLE_SM_ERR_CONFIRM_MISMATCH ) : \n console_printf ( failure - peer reports mismatch in our confirm and \n random commands.\\n );\n break ;\n\n default : \n console_printf ( failure - other error: 0x%04x\\n , rc );\n break ;\n }\n}",
- "title": "Example"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-code-reference",
- "text": "",
- "title": "Return Code Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#header",
- "text": "All NimBLE host return codes are made accessible by including the following header: #include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-codes-core",
- "text": "The precise meaning of each of these error codes depends on the function that returns it. The API reference for a particular function indicates the conditions under which each of these codes are returned. Value Name Condition 0x00 N/A Success 0x01 BLE_HS_EAGAIN Temporary failure; try again. 0x02 BLE_HS_EALREADY Operation already in progress or completed. 0x03 BLE_HS_EINVAL One or more arguments are invalid. 0x04 BLE_HS_EMSGSIZE The provided buffer is too small. 0x05 BLE_HS_ENOENT No entry matching the specified criteria. 0x06 BLE_HS_ENOMEM Operation failed due to resource exhaustion. 0x07 BLE_HS_ENOTCONN No open connection with the specified handle. 0x08 BLE_HS_ENOTSUP Operation disabled at compile time. 0x09 BLE_HS_EAPP Application callback behaved unexpectedly. 0x0a BLE_HS_EBADDATA Command from peer is invalid. 0x0b BLE_HS_EOS Mynewt OS error. 0x0c BLE_HS_ECONTROLLER Event from controller is invalid. 0x0d BLE_HS_ETIMEOUT Operation timed out. 0x0e BLE_HS_EDONE Operation completed successfully. 0x0f BLE_HS_EBUSY Operation cannot be performed until procedure completes. 0x10 BLE_HS_EREJECT Peer rejected a connection parameter update request. 0x11 BLE_HS_EUNKNOWN Unexpected failure; catch all. 0x12 BLE_HS_EROLE Operation requires different role (e.g., central vs. peripheral). 0x13 BLE_HS_ETIMEOUT_HCI HCI request timed out; controller unresponsive. 0x14 BLE_HS_ENOMEM_EVT Controller failed to send event due to memory exhaustion (combined host-controller only). 0x15 BLE_HS_ENOADDR Operation requires an identity address but none configured.",
- "title": "Return codes - Core"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-codes-att",
- "text": "NimBLE Value Formal Value Name Condition 0x0101 0x01 BLE_ATT_ERR_INVALID_HANDLE The attribute handle given was not valid on this server. 0x0102 0x02 BLE_ATT_ERR_READ_NOT_PERMITTED The attribute cannot be read. 0x0103 0x03 BLE_ATT_ERR_WRITE_NOT_PERMITTED The attribute cannot be written. 0x0104 0x04 BLE_ATT_ERR_INVALID_PDU The attribute PDU was invalid. 0x0105 0x05 BLE_ATT_ERR_INSUFFICIENT_AUTHEN The attribute requires authentication before it can be read or written. 0x0106 0x06 BLE_ATT_ERR_REQ_NOT_SUPPORTED Attribute server does not support the request received from the client. 0x0107 0x07 BLE_ATT_ERR_INVALID_OFFSET Offset specified was past the end of the attribute. 0x0108 0x08 BLE_ATT_ERR_INSUFFICIENT_AUTHOR The attribute requires authorization before it can be read or written. 0x0109 0x09 BLE_ATT_ERR_PREPARE_QUEUE_FULL Too many prepare writes have been queued. 0x010a 0x0a BLE_ATT_ERR_ATTR_NOT_FOUND No attribute found within the given attribute handle range. 0x010b 0x0b BLE_ATT_ERR_ATTR_NOT_LONG The attribute cannot be read or written using the Read Blob Request. 0x010c 0x0c BLE_ATT_ERR_INSUFFICIENT_KEY_SZ The Encryption Key Size used for encrypting this link is insufficient. 0x010d 0x0d BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN The attribute value length is invalid for the operation. 0x010e 0x0e BLE_ATT_ERR_UNLIKELY The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested. 0x010f 0x0f BLE_ATT_ERR_INSUFFICIENT_ENC The attribute requires encryption before it can be read or written. 0x0110 0x10 BLE_ATT_ERR_UNSUPPORTED_GROUP The attribute type is not a supported grouping attribute as defined by a higher layer specification. 0x0111 0x11 BLE_ATT_ERR_INSUFFICIENT_RES Insufficient Resources to complete the request.",
- "title": "Return codes - ATT"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-codes-hci",
- "text": "NimBLE Value Formal Value Name Condition 0x0201 0x01 BLE_ERR_UNKNOWN_HCI_CMD Unknown HCI Command 0x0202 0x02 BLE_ERR_UNK_CONN_ID Unknown Connection Identifier 0x0203 0x03 BLE_ERR_HW_FAIL Hardware Failure 0x0204 0x04 BLE_ERR_PAGE_TMO Page Timeout 0x0205 0x05 BLE_ERR_AUTH_FAIL Authentication Failure 0x0206 0x06 BLE_ERR_PINKEY_MISSING PIN or Key Missing 0x0207 0x07 BLE_ERR_MEM_CAPACITY Memory Capacity Exceeded 0x0208 0x08 BLE_ERR_CONN_SPVN_TMO Connection Timeout 0x0209 0x09 BLE_ERR_CONN_LIMIT Connection Limit Exceeded 0x020a 0x0a BLE_ERR_SYNCH_CONN_LIMIT Synchronous Connection Limit To A Device Exceeded 0x020b 0x0b BLE_ERR_ACL_CONN_EXISTS ACL Connection Already Exists 0x020c 0x0c BLE_ERR_CMD_DISALLOWED Command Disallowed 0x020d 0x0d BLE_ERR_CONN_REJ_RESOURCES Connection Rejected due to Limited Resources 0x020e 0x0e BLE_ERR_CONN_REJ_SECURITY Connection Rejected Due To Security Reasons 0x020f 0x0f BLE_ERR_CONN_REJ_BD_ADDR Connection Rejected due to Unacceptable BD_ADDR 0x0210 0x10 BLE_ERR_CONN_ACCEPT_TMO Connection Accept Timeout Exceeded 0x0211 0x11 BLE_ERR_UNSUPPORTED Unsupported Feature or Parameter Value 0x0212 0x12 BLE_ERR_INV_HCI_CMD_PARMS Invalid HCI Command Parameters 0x0213 0x13 BLE_ERR_REM_USER_CONN_TERM Remote User Terminated Connection 0x0214 0x14 BLE_ERR_RD_CONN_TERM_RESRCS Remote Device Terminated Connection due to Low Resources 0x0215 0x15 BLE_ERR_RD_CONN_TERM_PWROFF Remote Device Terminated Connection due to Power Off 0x0216 0x16 BLE_ERR_CONN_TERM_LOCAL Connection Terminated By Local Host 0x0217 0x17 BLE_ERR_REPEATED_ATTEMPTS Repeated Attempts 0x0218 0x18 BLE_ERR_NO_PAIRING Pairing Not Allowed 0x0219 0x19 BLE_ERR_UNK_LMP Unknown LMP PDU 0x021a 0x1a BLE_ERR_UNSUPP_REM_FEATURE Unsupported Remote Feature / Unsupported LMP Feature 0x021b 0x1b BLE_ERR_SCO_OFFSET SCO Offset Rejected 0x021c 0x1c BLE_ERR_SCO_ITVL SCO Interval Rejected 0x021d 0x1d BLE_ERR_SCO_AIR_MODE SCO Air Mode Rejected 0x021e 0x1e BLE_ERR_INV_LMP_LL_PARM Invalid LMP Parameters / Invalid LL Parameters 0x021f 0x1f BLE_ERR_UNSPECIFIED Unspecified Error 0x0220 0x20 BLE_ERR_UNSUPP_LMP_LL_PARM Unsupported LMP Parameter Value / Unsupported LL Parameter Value 0x0221 0x21 BLE_ERR_NO_ROLE_CHANGE Role Change Not Allowed 0x0222 0x22 BLE_ERR_LMP_LL_RSP_TMO LMP Response Timeout / LL Response Timeout 0x0223 0x23 BLE_ERR_LMP_COLLISION LMP Error Transaction Collision 0x0224 0x24 BLE_ERR_LMP_PDU LMP PDU Not Allowed 0x0225 0x25 BLE_ERR_ENCRYPTION_MODE Encryption Mode Not Acceptable 0x0226 0x26 BLE_ERR_LINK_KEY_CHANGE Link Key cannot be Changed 0x0227 0x27 BLE_ERR_UNSUPP_QOS Requested QoS Not Supported 0x0228 0x28 BLE_ERR_INSTANT_PASSED Instant Passed 0x0229 0x29 BLE_ERR_UNIT_KEY_PAIRING Pairing With Unit Key Not Supported 0x022a 0x2a BLE_ERR_DIFF_TRANS_COLL Different Transaction Collision 0x022c 0x2c BLE_ERR_QOS_PARM QoS Unacceptable Parameter 0x022d 0x2d BLE_ERR_QOS_REJECTED QoS Rejected 0x022e 0x2e BLE_ERR_CHAN_CLASS Channel Classification Not Supported 0x022f 0x2f BLE_ERR_INSUFFICIENT_SEC Insufficient Security 0x0230 0x30 BLE_ERR_PARM_OUT_OF_RANGE Parameter Out Of Mandatory Range 0x0232 0x32 BLE_ERR_PENDING_ROLE_SW Role Switch Pending 0x0234 0x34 BLE_ERR_RESERVED_SLOT Reserved Slot Violation 0x0235 0x35 BLE_ERR_ROLE_SW_FAIL Role Switch Failed 0x0236 0x36 BLE_ERR_INQ_RSP_TOO_BIG Extended Inquiry Response Too Large 0x0237 0x37 BLE_ERR_SEC_SIMPLE_PAIR Secure Simple Pairing Not Supported By Host 0x0238 0x38 BLE_ERR_HOST_BUSY_PAIR Host Busy - Pairing 0x0239 0x39 BLE_ERR_CONN_REJ_CHANNEL Connection Rejected due to No Suitable Channel Found 0x023a 0x3a BLE_ERR_CTLR_BUSY Controller Busy 0x023b 0x3b BLE_ERR_CONN_PARMS Unacceptable Connection Parameters 0x023c 0x3c BLE_ERR_DIR_ADV_TMO Directed Advertising Timeout 0x023d 0x3d BLE_ERR_CONN_TERM_MIC Connection Terminated due to MIC Failure 0x023e 0x3e BLE_ERR_CONN_ESTABLISHMENT Connection Failed to be Established 0x023f 0x3f BLE_ERR_MAC_CONN_FAIL MAC Connection Failed 0x0240 0x40 BLE_ERR_COARSE_CLK_ADJ Coarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging",
- "title": "Return codes - HCI"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-codes-l2cap",
- "text": "NimBLE Value Formal Value Name Condition 0x0300 0x00 BLE_L2CAP_SIG_ERR_CMD_NOT_UNDERSTOOD Invalid or unsupported incoming L2CAP sig command. 0x0301 0x01 BLE_L2CAP_SIG_ERR_MTU_EXCEEDED Incoming packet too large. 0x0302 0x02 BLE_L2CAP_SIG_ERR_INVALID_CID No channel with specified ID.",
- "title": "Return codes - L2CAP"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-codes-security-manager-us",
- "text": "NimBLE Value Formal Value Name Condition 0x0401 0x01 BLE_SM_ERR_PASSKEY The user input of passkey failed, for example, the user cancelled the operation. 0x0402 0x02 BLE_SM_ERR_OOB The OOB data is not available. 0x0403 0x03 BLE_SM_ERR_AUTHREQ The pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices. 0x0404 0x04 BLE_SM_ERR_CONFIRM_MISMATCH The confirm value does not match the calculated compare value. 0x0405 0x05 BLE_SM_ERR_PAIR_NOT_SUPP Pairing is not supported by the device. 0x0406 0x06 BLE_SM_ERR_ENC_KEY_SZ The resultant encryption key size is insufficient for the security requirements of this device. 0x0407 0x07 BLE_SM_ERR_CMD_NOT_SUPP The SMP command received is not supported on this device. 0x0408 0x08 BLE_SM_ERR_UNSPECIFIED Pairing failed due to an unspecified reason. 0x0409 0x09 BLE_SM_ERR_REPEATED Pairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request. 0x040a 0x0a BLE_SM_ERR_INVAL The Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range. 0x040b 0x0b BLE_SM_ERR_DHKEY Indicates to the remote device that the DHKey Check value received doesn\u2019t match the one calculated by the local device. 0x040c 0x0c BLE_SM_ERR_NUMCMP Indicates that the confirm values in the numeric comparison protocol do not match. 0x040d 0x0d BLE_SM_ERR_ALREADY Indicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process. 0x040e 0x0e BLE_SM_ERR_CROSS_TRANS Indicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.",
- "title": "Return codes - Security manager (us)"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_return_codes/#return-codes-security-manager-peer",
- "text": "NimBLE Value Formal Value Name Condition 0x0501 0x01 BLE_SM_ERR_PASSKEY The user input of passkey failed, for example, the user cancelled the operation. 0x0502 0x02 BLE_SM_ERR_OOB The OOB data is not available. 0x0503 0x03 BLE_SM_ERR_AUTHREQ The pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices. 0x0504 0x04 BLE_SM_ERR_CONFIRM_MISMATCH The confirm value does not match the calculated compare value. 0x0505 0x05 BLE_SM_ERR_PAIR_NOT_SUPP Pairing is not supported by the device. 0x0506 0x06 BLE_SM_ERR_ENC_KEY_SZ The resultant encryption key size is insufficient for the security requirements of this device. 0x0507 0x07 BLE_SM_ERR_CMD_NOT_SUPP The SMP command received is not supported on this device. 0x0508 0x08 BLE_SM_ERR_UNSPECIFIED Pairing failed due to an unspecified reason. 0x0509 0x09 BLE_SM_ERR_REPEATED Pairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request. 0x050a 0x0a BLE_SM_ERR_INVAL The Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range. 0x050b 0x0b BLE_SM_ERR_DHKEY Indicates to the remote device that the DHKey Check value received doesn\u2019t match the one calculated by the local device. 0x050c 0x0c BLE_SM_ERR_NUMCMP Indicates that the confirm values in the numeric comparison protocol do not match. 0x050d 0x0d BLE_SM_ERR_ALREADY Indicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process. 0x050e 0x0e BLE_SM_ERR_CROSS_TRANS Indicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.",
- "title": "Return codes - Security manager (peer)"
- },
- {
- "location": "/network/ble/ble_hs/init/init/",
- "text": "NimBLE Host Init and Config Reference\n\n\nIntroduction\n\n\nThis section is a reference on initializing and configuring the NimBLE host.\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nBLE host init and config definitions\n\n\nFunctions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_hs_init\n\n\nInitializes the NimBLE host.\n\n\n\n\n\n\nble_hs_start\n\n\nSynchronizes the host with the controller by sending a sequence of HCI commands.\n\n\n\n\n\n\nble_hs_synced\n\n\nIndicates whether the host has synchronized with the controller.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/init/init/#nimble-host-init-and-config-reference",
- "text": "",
- "title": "NimBLE Host Init and Config Reference"
- },
- {
- "location": "/network/ble/ble_hs/init/init/#introduction",
- "text": "This section is a reference on initializing and configuring the NimBLE host.",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/init/init/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/init/init/#definitions",
- "text": "BLE host init and config definitions",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/init/init/#functions",
- "text": "Function Description ble_hs_init Initializes the NimBLE host. ble_hs_start Synchronizes the host with the controller by sending a sequence of HCI commands. ble_hs_synced Indicates whether the host has synchronized with the controller.",
- "title": "Functions"
- },
- {
- "location": "/network/ble/ble_hs/init/definitions/init_defs/",
- "text": "Other definitions\n\n\n/* Defines the IO capabilities for the local device. */\n\n\n#define BLE_HS_IO_DISPLAY_ONLY 0x00\n\n\n#define BLE_HS_IO_DISPLAY_YESNO 0x01\n\n\n#define BLE_HS_IO_KEYBOARD_ONLY 0x02\n\n\n#define BLE_HS_IO_NO_INPUT_OUTPUT 0x03\n\n\n#define BLE_HS_IO_KEYBOARD_DISPLAY 0x04\n\n\n\n\n\n\nstruct\n \nble_hs_cfg\n {\n \n/*** HCI settings. */\n\n \n/**\n\n\n * An HCI buffer is a \nflat\n 260-byte buffer. HCI buffers are used by the\n\n\n * controller to send unsolicited events to the host.\n\n\n *\n\n\n * HCI buffers can get tied up when the controller sends lots of\n\n\n * asynchronous / unsolicited events (i.e., non-acks). When the controller\n\n\n * needs to send one of these events, it allocates an HCI buffer, fills it\n\n\n * with the event payload, and puts it on a host queue. If the controller\n\n\n * sends a quick burst of these events, the buffer pool may be exhausted,\n\n\n * preventing the host from sending an HCI command to the controller.\n\n\n *\n\n\n * Every time the controller sends a non-ack HCI event to the host, it also\n\n\n * allocates an OS event (it is unfortunate that these are both called\n\n\n * \nevents\n). The OS event is put on the host-parent-task\ns event queue;\n\n\n * it is what wakes up the host-parent-task and indicates that an HCI event\n\n\n * needs to be processsed. The pool of OS events is allocated with the\n\n\n * same number of elements as the HCI buffer pool.\n\n\n */\n\n \nuint8_t\n \nmax_hci_bufs\n;\n\n \n/*** Connection settings. */\n\n \n/**\n\n\n * The maximum number of concurrent connections. This is set\n\n\n * automatically according to the build-time option\n\n\n * NIMBLE_OPT_MAX_CONNECTIONS.\n\n\n */\n\n \nuint8_t\n \nmax_connections\n;\n\n \n/*** GATT server settings. */\n\n \n/**\n\n\n * These are acquired at service registration time and never freed. You\n\n\n * need one of these for every service that you register.\n\n\n */\n\n \nuint16_t\n \nmax_services\n;\n\n \n/**\n\n\n * The total number of in-RAM client characteristic configuration\n\n\n * descriptors (CCCDs). One of these is consumed each time a peer\n\n\n * subscribes to notifications or indications for a characteristic that\n\n\n * your device serves. In addition, at service registration time, the host\n\n\n * uses one of these for each characteristic that supports notifications or\n\n\n * indications. So, the formula which guarantees no resource exhaustion\n\n\n * is:\n\n\n * (num-subscribable-characteristics) * (max-connections + 1)\n\n\n */\n\n \nuint16_t\n \nmax_client_configs\n;\n\n \n/**\n\n\n * An optional callback that gets executed upon registration of each GATT\n\n\n * resource (service, characteristic, or descriptor).\n\n\n */\n\n \nble_gatt_register_fn\n \n*gatts_register_cb\n;\n\n \n/**\n\n\n * An optional argument that gets passed to the GATT registration\n\n\n * callback.\n\n\n */\n\n \nvoid\n \n*gatts_register_arg\n;\n\n \n/*** GATT client settings. */\n\n \n/**\n\n\n * The maximum number of concurrent GATT client procedures. When you\n\n\n * initiate a GATT procedure (e.g., read a characteristic, discover\n\n\n * services, etc.), one of these is consumed. The resource is freed when\n\n\n * the procedure completes.\n\n\n */\n\n \nuint8_t\n \nmax_gattc_procs\n;\n\n \n/*** ATT server settings. */\n\n \n/**\n\n\n * The total number of local ATT attributes. Attributes are consumed at\n\n\n * service registration time and are never freed. Attributes are used by\n\n\n * GATT server entities: services, characteristics, and descriptors\n\n\n * according to the following formula:\n\n\n * (num-services + (num-characteristics * 2) + num-descriptors)\n\n\n *\n\n\n * Every characteristic that supports indications or notifications\n\n\n * automatically gets a descriptor. All other descriptors are specified by\n\n\n * the application at service registration time.\n\n\n */\n\n \nuint16_t\n \nmax_attrs\n;\n\n \n/**\n\n\n * A GATT server uses these when a peer performs a \nwrite long\n\n\n * characteristic values\n or \nwrite long characteristic descriptors\n\n\n * procedure. One of these resources is consumed each time a peer sends a\n\n\n * partial write. These procedures are not used often.\n\n\n */\n\n \nuint8_t\n \nmax_prep_entries\n;\n\n \n/*** L2CAP settings. */\n\n \n/**\n\n\n * Each connection requires three L2CAP channels (signal, ATT, and security\n\n\n * manager). In addition, the nimble host may allow channels to be created\n\n\n * \non the fly\n (connection-oriented channels). This functionality is not\n\n\n * available at the moment, so a safe formula to use is:\n\n\n * (max-connections * 3)\n\n\n */\n\n \nuint8_t\n \nmax_l2cap_chans\n;\n\n \n/**\n\n\n * The maximum number of concurrent L2CAP signalling procedures. Only one\n\n\n * L2CAP signalling procedure is supported: slave-initiated connection\n\n\n * update. You will never need more of these than the max number of\n\n\n * connections.\n\n\n */\n\n \nuint8_t\n \nmax_l2cap_sig_procs\n;\n\n \n/**\n\n\n * The maximum number of concurrent security manager procedures. Security\n\n\n * manager procedures include pairing and restoration of a bonded link.\n\n\n */\n\n \nuint8_t\n \nmax_l2cap_sm_procs\n;\n\n \n/*** Security manager settings. */\n\n \nuint8_t\n \nsm_io_cap\n;\n \nunsigned\n \nsm_oob_data_flag\n:\n1\n;\n \nunsigned\n \nsm_bonding\n:\n1\n;\n \nunsigned\n \nsm_mitm\n:\n1\n;\n \nunsigned\n \nsm_sc\n:\n1\n;\n \nunsigned\n \nsm_keypress\n:\n1\n;\n \nuint8_t\n \nsm_our_key_dist\n;\n \nuint8_t\n \nsm_their_key_dist\n;\n\n \n/*** Store settings. */\n\n \n/**\n\n\n * These function callbacks handle persistence of sercurity material\n\n\n * (bonding).\n\n\n */\n\n \nble_store_read_fn\n \n*store_read_cb\n;\n \nble_store_write_fn\n \n*store_write_cb\n;\n \nble_store_delete_fn\n \n*store_delete_cb\n;\n\n \n/*** privacy settings */\n\n \n/**\n\n\n * The frequency at which new resovlable private addresses are generated.\n\n\n * Units are seconds.\n\n\n */\n\n \nuint16_t\n \nrpa_timeout\n;\n};\n\n\n\n\n\nextern\n \nconst\n \nstruct\n \nble_hs_cfg\n \nble_hs_cfg_dflt\n;",
- "title": "Init and config definitions"
- },
- {
- "location": "/network/ble/ble_hs/init/definitions/init_defs/#other-definitions",
- "text": "/* Defines the IO capabilities for the local device. */ #define BLE_HS_IO_DISPLAY_ONLY 0x00 #define BLE_HS_IO_DISPLAY_YESNO 0x01 #define BLE_HS_IO_KEYBOARD_ONLY 0x02 #define BLE_HS_IO_NO_INPUT_OUTPUT 0x03 #define BLE_HS_IO_KEYBOARD_DISPLAY 0x04 struct ble_hs_cfg {\n /*** HCI settings. */ \n /** * An HCI buffer is a flat 260-byte buffer. HCI buffers are used by the * controller to send unsolicited events to the host. * * HCI buffers can get tied up when the controller sends lots of * asynchronous / unsolicited events (i.e., non-acks). When the controller * needs to send one of these events, it allocates an HCI buffer, fills it * with the event payload, and puts it on a host queue. If the controller * sends a quick burst of these events, the buffer pool may be exhausted, * preventing the host from sending an HCI command to the controller. * * Every time the controller sends a non-ack HCI event to the host, it also * allocates an OS event (it is unfortunate that these are both called * events ). The OS event is put on the host-parent-task s event queue; * it is what wakes up the host-parent-task and indicates that an HCI event * needs to be processsed. The pool of OS events is allocated with the * same number of elements as the HCI buffer pool. */ \n uint8_t max_hci_bufs ;\n\n /*** Connection settings. */ \n /** * The maximum number of concurrent connections. This is set * automatically according to the build-time option * NIMBLE_OPT_MAX_CONNECTIONS. */ \n uint8_t max_connections ;\n\n /*** GATT server settings. */ \n /** * These are acquired at service registration time and never freed. You * need one of these for every service that you register. */ \n uint16_t max_services ;\n\n /** * The total number of in-RAM client characteristic configuration * descriptors (CCCDs). One of these is consumed each time a peer * subscribes to notifications or indications for a characteristic that * your device serves. In addition, at service registration time, the host * uses one of these for each characteristic that supports notifications or * indications. So, the formula which guarantees no resource exhaustion * is: * (num-subscribable-characteristics) * (max-connections + 1) */ \n uint16_t max_client_configs ;\n\n /** * An optional callback that gets executed upon registration of each GATT * resource (service, characteristic, or descriptor). */ \n ble_gatt_register_fn *gatts_register_cb ;\n\n /** * An optional argument that gets passed to the GATT registration * callback. */ \n void *gatts_register_arg ;\n\n /*** GATT client settings. */ \n /** * The maximum number of concurrent GATT client procedures. When you * initiate a GATT procedure (e.g., read a characteristic, discover * services, etc.), one of these is consumed. The resource is freed when * the procedure completes. */ \n uint8_t max_gattc_procs ;\n\n /*** ATT server settings. */ \n /** * The total number of local ATT attributes. Attributes are consumed at * service registration time and are never freed. Attributes are used by * GATT server entities: services, characteristics, and descriptors * according to the following formula: * (num-services + (num-characteristics * 2) + num-descriptors) * * Every characteristic that supports indications or notifications * automatically gets a descriptor. All other descriptors are specified by * the application at service registration time. */ \n uint16_t max_attrs ;\n\n /** * A GATT server uses these when a peer performs a write long * characteristic values or write long characteristic descriptors * procedure. One of these resources is consumed each time a peer sends a * partial write. These procedures are not used often. */ \n uint8_t max_prep_entries ;\n\n /*** L2CAP settings. */ \n /** * Each connection requires three L2CAP channels (signal, ATT, and security * manager). In addition, the nimble host may allow channels to be created * on the fly (connection-oriented channels). This functionality is not * available at the moment, so a safe formula to use is: * (max-connections * 3) */ \n uint8_t max_l2cap_chans ;\n\n /** * The maximum number of concurrent L2CAP signalling procedures. Only one * L2CAP signalling procedure is supported: slave-initiated connection * update. You will never need more of these than the max number of * connections. */ \n uint8_t max_l2cap_sig_procs ;\n\n /** * The maximum number of concurrent security manager procedures. Security * manager procedures include pairing and restoration of a bonded link. */ \n uint8_t max_l2cap_sm_procs ;\n\n /*** Security manager settings. */ \n uint8_t sm_io_cap ;\n unsigned sm_oob_data_flag : 1 ;\n unsigned sm_bonding : 1 ;\n unsigned sm_mitm : 1 ;\n unsigned sm_sc : 1 ;\n unsigned sm_keypress : 1 ;\n uint8_t sm_our_key_dist ;\n uint8_t sm_their_key_dist ;\n\n /*** Store settings. */ \n /** * These function callbacks handle persistence of sercurity material * (bonding). */ \n ble_store_read_fn *store_read_cb ;\n ble_store_write_fn *store_write_cb ;\n ble_store_delete_fn *store_delete_cb ;\n\n /*** privacy settings */ \n /** * The frequency at which new resovlable private addresses are generated. * Units are seconds. */ \n uint16_t rpa_timeout ;\n}; extern const struct ble_hs_cfg ble_hs_cfg_dflt ;",
- "title": "Other definitions"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_start/",
- "text": "ble_hs_start\n\n\nint\n\n\nble_hs_start\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nSynchronizes the host with the controller by sending a sequence of HCI commands. This function must be called before any other host functionality is used, but it must be called after both the host and controller are initialized. Typically, the host-parent-task calls this function at the top of its task routine. If the host fails to synchronize with the controller (if the controller is not fully booted, for example), the host will attempt to resynchronize every 100 ms. For this reason, an error return code is not necessarily fatal.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_hs_start"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_start/#ble95hs95start",
- "text": "int ble_hs_start ( void )",
- "title": "ble_hs_start"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_start/#description",
- "text": "Synchronizes the host with the controller by sending a sequence of HCI commands. This function must be called before any other host functionality is used, but it must be called after both the host and controller are initialized. Typically, the host-parent-task calls this function at the top of its task routine. If the host fails to synchronize with the controller (if the controller is not fully booted, for example), the host will attempt to resynchronize every 100 ms. For this reason, an error return code is not necessarily fatal.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_start/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_start/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_init/",
- "text": "ble_hs_init\n\n\nint\n\n\nble_hs_init\n(\n \nstruct\n \nos_eventq\n \n*app_evq\n,\n \nstruct\n \nble_hs_cfg\n \n*cfg\n\n)\n\n\n\n\n\nDescription\n\n\nInitializes the NimBLE host. This function must be called before the OS is started. The NimBLE stack requires an application task to function. One application task in particular is designated as the \"host parent task\". In addition to application-specific work, the host parent task does work for NimBLE by processing events generated by the host.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\napp_evq\n\n\nThe event queue associated with the host parent task.\n\n\n\n\n\n\ncfg\n\n\nThe set of configuration settings to initialize the host with. Specify null for defaults.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_hs_init"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_init/#ble95hs95init",
- "text": "int ble_hs_init (\n struct os_eventq *app_evq ,\n struct ble_hs_cfg *cfg \n)",
- "title": "ble_hs_init"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_init/#description",
- "text": "Initializes the NimBLE host. This function must be called before the OS is started. The NimBLE stack requires an application task to function. One application task in particular is designated as the \"host parent task\". In addition to application-specific work, the host parent task does work for NimBLE by processing events generated by the host.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_init/#parameters",
- "text": "Parameter Description app_evq The event queue associated with the host parent task. cfg The set of configuration settings to initialize the host with. Specify null for defaults.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_init/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_synced/",
- "text": "ble_hs_synced\n\n\nint\n\n\nble_hs_synced\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nIndicates whether the host has synchronized with the controller. Synchronization must occur before any host procedures can be performed.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n1\n\n\nThe host and controller are in sync.\n\n\n\n\n\n\n0\n\n\nThe host and controller our out of sync.",
- "title": "ble_hs_synced"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_synced/#ble95hs95synced",
- "text": "int ble_hs_synced ( void )",
- "title": "ble_hs_synced"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_synced/#description",
- "text": "Indicates whether the host has synchronized with the controller. Synchronization must occur before any host procedures can be performed.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_synced/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/init/functions/ble_hs_synced/#returned-values",
- "text": "Value Condition 1 The host and controller are in sync. 0 The host and controller our out of sync.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/ble_gap/",
- "text": "NimBLE Host GAP Reference\n\n\nIntroduction\n\n\nThe Generic Access Profile (GAP) is responsible for all connecting, advertising, scanning, and connection updating operations.\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nBLE host GAP definitions\n\n\nFunctions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_gap_adv_active\n\n\nIndicates whether an advertisement procedure is currently in progress.\n\n\n\n\n\n\nble_gap_adv_rsp_set_fields\n\n\nConfigures the data to include in subsequent scan responses.\n\n\n\n\n\n\nble_gap_adv_set_fields\n\n\nConfigures the data to include in subsequent advertisements.\n\n\n\n\n\n\nble_gap_adv_start\n\n\nInitiates advertising.\n\n\n\n\n\n\nble_gap_adv_stop\n\n\nStops the currently-active advertising procedure.\n\n\n\n\n\n\nble_gap_conn_active\n\n\nIndicates whether a connect procedure is currently in progress.\n\n\n\n\n\n\nble_gap_conn_cancel\n\n\nAborts a connect procedure in progress.\n\n\n\n\n\n\nble_gap_conn_find\n\n\nSearches for a connection with the specified handle.\n\n\n\n\n\n\nble_gap_conn_rssi\n\n\nRetrieves the most-recently measured RSSI for the specified connection.\n\n\n\n\n\n\nble_gap_connect\n\n\nInitiates a connect procedure.\n\n\n\n\n\n\nble_gap_disc\n\n\nPerforms the Limited or General Discovery Procedures.\n\n\n\n\n\n\nble_gap_disc_active\n\n\nIndicates whether a discovery procedure is currently in progress.\n\n\n\n\n\n\nble_gap_disc_cancel\n\n\nCancels the discovery procedure currently in progress.\n\n\n\n\n\n\nble_gap_security_initiate\n\n\nInitiates the GAP encryption procedure.\n\n\n\n\n\n\nble_gap_terminate\n\n\nTerminates an established connection.\n\n\n\n\n\n\nble_gap_update_params\n\n\nInitiates a connection parameter update procedure.\n\n\n\n\n\n\nble_gap_wl_set\n\n\nOverwrites the controller's white list with the specified contents.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/ble_gap/#nimble-host-gap-reference",
- "text": "",
- "title": "NimBLE Host GAP Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/ble_gap/#introduction",
- "text": "The Generic Access Profile (GAP) is responsible for all connecting, advertising, scanning, and connection updating operations.",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/ble_gap/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/ble_gap/#definitions",
- "text": "BLE host GAP definitions",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/ble_gap/#functions",
- "text": "Function Description ble_gap_adv_active Indicates whether an advertisement procedure is currently in progress. ble_gap_adv_rsp_set_fields Configures the data to include in subsequent scan responses. ble_gap_adv_set_fields Configures the data to include in subsequent advertisements. ble_gap_adv_start Initiates advertising. ble_gap_adv_stop Stops the currently-active advertising procedure. ble_gap_conn_active Indicates whether a connect procedure is currently in progress. ble_gap_conn_cancel Aborts a connect procedure in progress. ble_gap_conn_find Searches for a connection with the specified handle. ble_gap_conn_rssi Retrieves the most-recently measured RSSI for the specified connection. ble_gap_connect Initiates a connect procedure. ble_gap_disc Performs the Limited or General Discovery Procedures. ble_gap_disc_active Indicates whether a discovery procedure is currently in progress. ble_gap_disc_cancel Cancels the discovery procedure currently in progress. ble_gap_security_initiate Initiates the GAP encryption procedure. ble_gap_terminate Terminates an established connection. ble_gap_update_params Initiates a connection parameter update procedure. ble_gap_wl_set Overwrites the controller's white list with the specified contents.",
- "title": "Functions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/",
- "text": "GAP events\n\n\ntypedef\n \nint\n \nble_gap_event_fn\n(\nstruct\n \nble_gap_event\n \n*ctxt\n, \nvoid\n \n*arg\n);\n\n\n\n\n\n#define BLE_GAP_EVENT_CONNECT 0\n\n\n#define BLE_GAP_EVENT_DISCONNECT 1\n\n\n#define BLE_GAP_EVENT_CONN_CANCEL 2\n\n\n#define BLE_GAP_EVENT_CONN_UPDATE 3\n\n\n#define BLE_GAP_EVENT_CONN_UPDATE_REQ 4\n\n\n#define BLE_GAP_EVENT_L2CAP_UPDATE_REQ 5\n\n\n#define BLE_GAP_EVENT_TERM_FAILURE 6\n\n\n#define BLE_GAP_EVENT_DISC 7\n\n\n#define BLE_GAP_EVENT_DISC_COMPLETE 8\n\n\n#define BLE_GAP_EVENT_ADV_COMPLETE 9\n\n\n#define BLE_GAP_EVENT_ENC_CHANGE 10\n\n\n#define BLE_GAP_EVENT_PASSKEY_ACTION 11\n\n\n#define BLE_GAP_EVENT_NOTIFY_RX 12\n\n\n#define BLE_GAP_EVENT_NOTIFY_TX 13\n\n\n#define BLE_GAP_EVENT_SUBSCRIBE 14\n\n\n\n\n\n\n/**\n\n\n * Represents a GAP-related event. When such an event occurs, the host\n\n\n * notifies the application by passing an instance of this structure to an\n\n\n * application-specified callback.\n\n\n */\n\n\nstruct\n \nble_gap_event\n {\n \n/**\n\n\n * Indicates the type of GAP event that occurred. This is one of the\n\n\n * BLE_GAP_EVENT codes.\n\n\n */\n\n \nuint8_t\n \ntype\n;\n\n \n/**\n\n\n * A discriminated union containing additional details concerning the GAP\n\n\n * event. The \ntype\n field indicates which member of the union is valid.\n\n\n */\n\n \nunion\n {\n \n/**\n\n\n * Represents a connection attempt. Valid for the following event\n\n\n * types:\n\n\n * o BLE_GAP_EVENT_CONNECT\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * The status of the connection attempt;\n\n\n * o 0: the connection was successfully established.\n\n\n * o BLE host error code: the connection attempt failed for\n\n\n * the specified reason.\n\n\n */\n\n \nint\n \nstatus\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n } \nconnect\n;\n\n \n/**\n\n\n * Represents a terminated connection. Valid for the following event\n\n\n * types:\n\n\n * o BLE_GAP_EVENT_DISCONNECT\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * A BLE host return code indicating the reason for the\n\n\n * disconnect.\n\n\n */\n\n \nint\n \nreason\n;\n\n \n/** Information about the connection prior to termination. */\n\n \nstruct\n \nble_gap_conn_desc\n \nconn\n;\n } \ndisconnect\n;\n\n \n/**\n\n\n * Represents an advertising report received during a discovery\n\n\n * procedure. Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_DISC\n\n\n */\n\n \nstruct\n \nble_gap_disc_desc\n \ndisc\n;\n\n \n/**\n\n\n * Represents an attempt to update a connection\ns parameters. If the\n\n\n * attempt was successful, the connection\ns descriptor reflects the\n\n\n * updated parameters.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_CONN_UPDATE\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * The result of the connection update attempt;\n\n\n * o 0: the connection was successfully updated.\n\n\n * o BLE host error code: the connection update attempt failed\n\n\n * for the specified reason.\n\n\n */\n\n \nint\n \nstatus\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n } \nconn_update\n;\n\n \n/**\n\n\n * Represents a peer\ns request to update the connection parameters.\n\n\n * This event is generated when a peer performs any of the following\n\n\n * procedures:\n\n\n * o L2CAP Connection Parameter Update Procedure\n\n\n * o Link-Layer Connection Parameters Request Procedure\n\n\n *\n\n\n * To reject the request, return a non-zero HCI error code. The value\n\n\n * returned is the reject reason given to the controller.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_L2CAP_UPDATE_REQ\n\n\n * o BLE_GAP_EVENT_CONN_UPDATE_REQ\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * Indicates the connection parameters that the peer would like to\n\n\n * use.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gap_upd_params\n \n*peer_params\n;\n\n \n/**\n\n\n * Indicates the connection parameters that the local device would\n\n\n * like to use. The application callback should fill this in. By\n\n\n * default, this struct contains the requested parameters (i.e.,\n\n\n * it is a copy of \npeer_params\n).\n\n\n */\n\n \nstruct\n \nble_gap_upd_params\n \n*self_params\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n } \nconn_update_req\n;\n\n \n/**\n\n\n * Represents a failed attempt to terminate an established connection.\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_TERM_FAILURE\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * A BLE host return code indicating the reason for the failure.\n\n\n */\n\n \nint\n \nstatus\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n } \nterm_failure\n;\n\n \n/**\n\n\n * Represents an attempt to change the encrypted state of a\n\n\n * connection. If the attempt was successful, the connection\n\n\n * descriptor reflects the updated encrypted state.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_ENC_CHANGE\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * Indicates the result of the encryption state change attempt;\n\n\n * o 0: the encrypted state was successfully updated;\n\n\n * o BLE host error code: the encryption state change attempt\n\n\n * failed for the specified reason.\n\n\n */\n\n \nint\n \nstatus\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n } \nenc_change\n;\n\n \n/**\n\n\n * Represents a passkey query needed to complete a pairing procedure.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_PASSKEY_ACTION\n\n\n */\n\n \nstruct\n {\n \n/** Contains details about the passkey query. */\n\n \nstruct\n \nble_gap_passkey_params\n \nparams\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n } \npasskey\n;\n\n \n/**\n\n\n * Represents a received ATT notification or indication.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_NOTIFY_RX\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * The contents of the notification or indication. If the\n\n\n * application wishes to retain this mbuf for later use, it must\n\n\n * set this pointer to NULL to prevent the stack from freeing it.\n\n\n */\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/** The handle of the relevant ATT attribute. */\n\n \nuint16_t\n \nattr_handle\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n\n \n/**\n\n\n * Whether the received command is a notification or an\n\n\n * indication;\n\n\n * o 0: Notification;\n\n\n * o 1: Indication.\n\n\n */\n\n \nuint8_t\n \nindication\n:\n1\n;\n } \nnotify_rx\n;\n\n \n/**\n\n\n * Represents a transmitted ATT notification or indication, or a\n\n\n * completed indication transaction.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_NOTIFY_TX\n\n\n */\n\n \nstruct\n {\n \n/**\n\n\n * The status of the notification or indication transaction;\n\n\n * o 0: Command successfully sent;\n\n\n * o BLE_HS_EDONE: Confirmation (indication ack) received;\n\n\n * o BLE_HS_ETIMEOUT: Confirmation (indication ack) never\n\n\n * received;\n\n\n * o Other return code: Error.\n\n\n */\n\n \nint\n \nstatus\n;\n\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n\n \n/** The handle of the relevant characterstic value. */\n\n \nuint16_t\n \nattr_handle\n;\n\n \n/**\n\n\n * Whether the transmitted command is a notification or an\n\n\n * indication;\n\n\n * o 0: Notification;\n\n\n * o 1: Indication.\n\n\n */\n\n \nuint8_t\n \nindication\n:\n1\n;\n } \nnotify_tx\n;\n\n \n/**\n\n\n * Represents a state change in a peer\ns subscription status. In this\n\n\n * comment, the term \nupdate\n is used to refer to either a notification\n\n\n * or an indication. This event is triggered by any of the following\n\n\n * occurrences:\n\n\n * o Peer enables or disables updates via a CCCD write.\n\n\n * o Connection is about to be terminated and the peer is\n\n\n * subscribed to updates.\n\n\n * o Peer is now subscribed to updates after its state was restored\n\n\n * from persistence. This happens when bonding is restored.\n\n\n *\n\n\n * Valid for the following event types:\n\n\n * o BLE_GAP_EVENT_SUBSCRIBE\n\n\n */\n\n \nstruct\n {\n \n/** The handle of the relevant connection. */\n\n \nuint16_t\n \nconn_handle\n;\n\n \n/** The value handle of the relevant characteristic. */\n\n \nuint16_t\n \nattr_handle\n;\n\n \n/** One of the BLE_GAP_SUBSCRIBE_REASON codes. */\n\n \nuint8_t\n \nreason\n;\n\n \n/** Whether the peer was previously subscribed to notifications. */\n\n \nuint8_t\n \nprev_notify\n:\n1\n;\n\n \n/** Whether the peer is currently subscribed to notifications. */\n\n \nuint8_t\n \ncur_notify\n:\n1\n;\n\n \n/** Whether the peer was previously subscribed to indications. */\n\n \nuint8_t\n \nprev_indicate\n:\n1\n;\n\n \n/** Whether the peer is currently subscribed to indications. */\n\n \nuint8_t\n \ncur_indicate\n:\n1\n;\n } \nsubscribe\n;\n };\n};\n\n\n\n\n\n#define BLE_GAP_CONN_MODE_NON 0\n\n\n#define BLE_GAP_CONN_MODE_DIR 1\n\n\n#define BLE_GAP_CONN_MODE_UND 2\n\n\n\n\n\n\n#define BLE_GAP_DISC_MODE_NON 0\n\n\n#define BLE_GAP_DISC_MODE_LTD 1\n\n\n#define BLE_GAP_DISC_MODE_GEN 2\n\n\n\n\n\n\nstruct\n \nble_gap_white_entry\n {\n \nuint8_t\n \naddr_type\n;\n \nuint8_t\n \naddr\n[\n6\n];\n};\n\n\n\n\n\n/*** Reason codes for the subscribe GAP event. */\n\n\n\n/** Peer\ns CCCD subscription state changed due to a descriptor write. */\n\n\n#define BLE_GAP_SUBSCRIBE_REASON_WRITE 1\n\n\n\n/** Peer\ns CCCD subscription state cleared due to connection termination. */\n\n\n#define BLE_GAP_SUBSCRIBE_REASON_TERM 2\n\n\n\n/**\n\n\n * Peer\ns CCCD subscription state changed due to restore from persistence\n\n\n * (bonding restored).\n\n\n */\n\n\n#define BLE_GAP_SUBSCRIBE_REASON_RESTORE 3\n\n\n\n\n\n\nstruct\n \nble_gap_sec_state\n {\n \nunsigned\n \nencrypted\n:\n1\n;\n \nunsigned\n \nauthenticated\n:\n1\n;\n \nunsigned\n \nbonded\n:\n1\n;\n};\n\n\n\n\n\n/**\n\n\n * @param discoverable_mode One of the following constants:\n\n\n * o BLE_GAP_DISC_MODE_NON\n\n\n * (non-discoverable; 3.C.9.2.2).\n\n\n * o BLE_GAP_DISC_MODE_LTD\n\n\n * (limited-discoverable; 3.C.9.2.3).\n\n\n * o BLE_GAP_DISC_MODE_GEN\n\n\n * (general-discoverable; 3.C.9.2.4).\n\n\n * @param connectable_mode One of the following constants:\n\n\n * o BLE_GAP_CONN_MODE_NON\n\n\n * (non-connectable; 3.C.9.3.2).\n\n\n * o BLE_GAP_CONN_MODE_DIR\n\n\n * (directed-connectable; 3.C.9.3.3).\n\n\n * o BLE_GAP_CONN_MODE_UND\n\n\n * (undirected-connectable; 3.C.9.3.4).\n\n\n */\n\n\nstruct\n \nble_gap_adv_params\n {\n \n/*** Mandatory fields. */\n\n \nuint8_t\n \nconn_mode\n;\n \nuint8_t\n \ndisc_mode\n;\n\n \n/*** Optional fields; assign 0 to make the stack calculate them. */\n\n \nuint16_t\n \nitvl_min\n;\n \nuint16_t\n \nitvl_max\n;\n \nuint8_t\n \nchannel_map\n;\n \nuint8_t\n \nfilter_policy\n;\n \nuint8_t\n \nhigh_duty_cycle\n:\n1\n;\n};\n\n\n\n\n\n#define BLE_GAP_ROLE_MASTER 0\n\n\n#define BLE_GAP_ROLE_SLAVE 1\n\n\n\n\n\n\nstruct\n \nble_gap_conn_desc\n {\n \nstruct\n \nble_gap_sec_state\n \nsec_state\n;\n \nuint8_t\n \npeer_ota_addr\n[\n6\n];\n \nuint8_t\n \npeer_id_addr\n[\n6\n];\n \nuint8_t\n \nour_id_addr\n[\n6\n];\n \nuint8_t\n \nour_ota_addr\n[\n6\n];\n \nuint16_t\n \nconn_handle\n;\n \nuint16_t\n \nconn_itvl\n;\n \nuint16_t\n \nconn_latency\n;\n \nuint16_t\n \nsupervision_timeout\n;\n \nuint8_t\n \npeer_ota_addr_type\n;\n \nuint8_t\n \npeer_id_addr_type\n;\n \nuint8_t\n \nour_id_addr_type\n;\n \nuint8_t\n \nour_ota_addr_type\n;\n \nuint8_t\n \nrole\n;\n \nuint8_t\n \nmaster_clock_accuracy\n;\n};\n\n\n\n\n\nstruct\n \nble_gap_conn_params\n {\n \nuint16_t\n \nscan_itvl\n;\n \nuint16_t\n \nscan_window\n;\n \nuint16_t\n \nitvl_min\n;\n \nuint16_t\n \nitvl_max\n;\n \nuint16_t\n \nlatency\n;\n \nuint16_t\n \nsupervision_timeout\n;\n \nuint16_t\n \nmin_ce_len\n;\n \nuint16_t\n \nmax_ce_len\n;\n};\n\n\n\n\n\nstruct\n \nble_gap_disc_params\n {\n \nuint16_t\n \nitvl\n;\n \nuint16_t\n \nwindow\n;\n \nuint8_t\n \nfilter_policy\n;\n \nuint8_t\n \nlimited\n:\n1\n;\n \nuint8_t\n \npassive\n:\n1\n;\n \nuint8_t\n \nfilter_duplicates\n:\n1\n;\n};\n\n\n\n\n\nstruct\n \nble_gap_upd_params\n {\n \nuint16_t\n \nitvl_min\n;\n \nuint16_t\n \nitvl_max\n;\n \nuint16_t\n \nlatency\n;\n \nuint16_t\n \nsupervision_timeout\n;\n \nuint16_t\n \nmin_ce_len\n;\n \nuint16_t\n \nmax_ce_len\n;\n};\n\n\n\n\n\nstruct\n \nble_gap_passkey_params\n {\n \nuint8_t\n \naction\n;\n \nuint32_t\n \nnumcmp\n;\n};\n\n\n\n\n\nstruct\n \nble_gap_disc_desc\n {\n \n/*** Common fields. */\n\n \nuint8_t\n \nevent_type\n;\n \nuint8_t\n \naddr_type\n;\n \nuint8_t\n \nlength_data\n;\n \nint8_t\n \nrssi\n;\n \nuint8_t\n \naddr\n[\n6\n];\n\n \n/*** LE advertising report fields; both null if no data present. */\n\n \nuint8_t\n \n*data\n;\n \nstruct\n \nble_hs_adv_fields\n \n*fields\n;\n\n \n/***\n\n\n * LE direct advertising report fields; direct_addr_type is\n\n\n * BLE_GAP_ADDR_TYPE_NONE if direct address fields are not present.\n\n\n */\n\n \nuint8_t\n \ndirect_addr_type\n;\n \nuint8_t\n \ndirect_addr\n[\n6\n];\n};",
- "title": "GAP definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/#gap-events",
- "text": "typedef int ble_gap_event_fn ( struct ble_gap_event *ctxt , void *arg ); #define BLE_GAP_EVENT_CONNECT 0 #define BLE_GAP_EVENT_DISCONNECT 1 #define BLE_GAP_EVENT_CONN_CANCEL 2 #define BLE_GAP_EVENT_CONN_UPDATE 3 #define BLE_GAP_EVENT_CONN_UPDATE_REQ 4 #define BLE_GAP_EVENT_L2CAP_UPDATE_REQ 5 #define BLE_GAP_EVENT_TERM_FAILURE 6 #define BLE_GAP_EVENT_DISC 7 #define BLE_GAP_EVENT_DISC_COMPLETE 8 #define BLE_GAP_EVENT_ADV_COMPLETE 9 #define BLE_GAP_EVENT_ENC_CHANGE 10 #define BLE_GAP_EVENT_PASSKEY_ACTION 11 #define BLE_GAP_EVENT_NOTIFY_RX 12 #define BLE_GAP_EVENT_NOTIFY_TX 13 #define BLE_GAP_EVENT_SUBSCRIBE 14 /** * Represents a GAP-related event. When such an event occurs, the host * notifies the application by passing an instance of this structure to an * application-specified callback. */ struct ble_gap_event {\n /** * Indicates the type of GAP event that occurred. This is one of the * BLE_GAP_EVENT codes. */ \n uint8_t type ;\n\n /** * A discriminated union containing additional details concerning the GAP * event. The type field indicates which member of the union is valid. */ \n union {\n /** * Represents a connection attempt. Valid for the following event * types: * o BLE_GAP_EVENT_CONNECT */ \n struct {\n /** * The status of the connection attempt; * o 0: the connection was successfully established. * o BLE host error code: the connection attempt failed for * the specified reason. */ \n int status ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n } connect ;\n\n /** * Represents a terminated connection. Valid for the following event * types: * o BLE_GAP_EVENT_DISCONNECT */ \n struct {\n /** * A BLE host return code indicating the reason for the * disconnect. */ \n int reason ;\n\n /** Information about the connection prior to termination. */ \n struct ble_gap_conn_desc conn ;\n } disconnect ;\n\n /** * Represents an advertising report received during a discovery * procedure. Valid for the following event types: * o BLE_GAP_EVENT_DISC */ \n struct ble_gap_disc_desc disc ;\n\n /** * Represents an attempt to update a connection s parameters. If the * attempt was successful, the connection s descriptor reflects the * updated parameters. * * Valid for the following event types: * o BLE_GAP_EVENT_CONN_UPDATE */ \n struct {\n /** * The result of the connection update attempt; * o 0: the connection was successfully updated. * o BLE host error code: the connection update attempt failed * for the specified reason. */ \n int status ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n } conn_update ;\n\n /** * Represents a peer s request to update the connection parameters. * This event is generated when a peer performs any of the following * procedures: * o L2CAP Connection Parameter Update Procedure * o Link-Layer Connection Parameters Request Procedure * * To reject the request, return a non-zero HCI error code. The value * returned is the reject reason given to the controller. * * Valid for the following event types: * o BLE_GAP_EVENT_L2CAP_UPDATE_REQ * o BLE_GAP_EVENT_CONN_UPDATE_REQ */ \n struct {\n /** * Indicates the connection parameters that the peer would like to * use. */ \n const struct ble_gap_upd_params *peer_params ;\n\n /** * Indicates the connection parameters that the local device would * like to use. The application callback should fill this in. By * default, this struct contains the requested parameters (i.e., * it is a copy of peer_params ). */ \n struct ble_gap_upd_params *self_params ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n } conn_update_req ;\n\n /** * Represents a failed attempt to terminate an established connection. * Valid for the following event types: * o BLE_GAP_EVENT_TERM_FAILURE */ \n struct {\n /** * A BLE host return code indicating the reason for the failure. */ \n int status ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n } term_failure ;\n\n /** * Represents an attempt to change the encrypted state of a * connection. If the attempt was successful, the connection * descriptor reflects the updated encrypted state. * * Valid for the following event types: * o BLE_GAP_EVENT_ENC_CHANGE */ \n struct {\n /** * Indicates the result of the encryption state change attempt; * o 0: the encrypted state was successfully updated; * o BLE host error code: the encryption state change attempt * failed for the specified reason. */ \n int status ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n } enc_change ;\n\n /** * Represents a passkey query needed to complete a pairing procedure. * * Valid for the following event types: * o BLE_GAP_EVENT_PASSKEY_ACTION */ \n struct {\n /** Contains details about the passkey query. */ \n struct ble_gap_passkey_params params ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n } passkey ;\n\n /** * Represents a received ATT notification or indication. * * Valid for the following event types: * o BLE_GAP_EVENT_NOTIFY_RX */ \n struct {\n /** * The contents of the notification or indication. If the * application wishes to retain this mbuf for later use, it must * set this pointer to NULL to prevent the stack from freeing it. */ \n struct os_mbuf *om ;\n\n /** The handle of the relevant ATT attribute. */ \n uint16_t attr_handle ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n\n /** * Whether the received command is a notification or an * indication; * o 0: Notification; * o 1: Indication. */ \n uint8_t indication : 1 ;\n } notify_rx ;\n\n /** * Represents a transmitted ATT notification or indication, or a * completed indication transaction. * * Valid for the following event types: * o BLE_GAP_EVENT_NOTIFY_TX */ \n struct {\n /** * The status of the notification or indication transaction; * o 0: Command successfully sent; * o BLE_HS_EDONE: Confirmation (indication ack) received; * o BLE_HS_ETIMEOUT: Confirmation (indication ack) never * received; * o Other return code: Error. */ \n int status ;\n\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n\n /** The handle of the relevant characterstic value. */ \n uint16_t attr_handle ;\n\n /** * Whether the transmitted command is a notification or an * indication; * o 0: Notification; * o 1: Indication. */ \n uint8_t indication : 1 ;\n } notify_tx ;\n\n /** * Represents a state change in a peer s subscription status. In this * comment, the term update is used to refer to either a notification * or an indication. This event is triggered by any of the following * occurrences: * o Peer enables or disables updates via a CCCD write. * o Connection is about to be terminated and the peer is * subscribed to updates. * o Peer is now subscribed to updates after its state was restored * from persistence. This happens when bonding is restored. * * Valid for the following event types: * o BLE_GAP_EVENT_SUBSCRIBE */ \n struct {\n /** The handle of the relevant connection. */ \n uint16_t conn_handle ;\n\n /** The value handle of the relevant characteristic. */ \n uint16_t attr_handle ;\n\n /** One of the BLE_GAP_SUBSCRIBE_REASON codes. */ \n uint8_t reason ;\n\n /** Whether the peer was previously subscribed to notifications. */ \n uint8_t prev_notify : 1 ;\n\n /** Whether the peer is currently subscribed to notifications. */ \n uint8_t cur_notify : 1 ;\n\n /** Whether the peer was previously subscribed to indications. */ \n uint8_t prev_indicate : 1 ;\n\n /** Whether the peer is currently subscribed to indications. */ \n uint8_t cur_indicate : 1 ;\n } subscribe ;\n };\n}; #define BLE_GAP_CONN_MODE_NON 0 #define BLE_GAP_CONN_MODE_DIR 1 #define BLE_GAP_CONN_MODE_UND 2 #define BLE_GAP_DISC_MODE_NON 0 #define BLE_GAP_DISC_MODE_LTD 1 #define BLE_GAP_DISC_MODE_GEN 2 struct ble_gap_white_entry {\n uint8_t addr_type ;\n uint8_t addr [ 6 ];\n}; /*** Reason codes for the subscribe GAP event. */ /** Peer s CCCD subscription state changed due to a descriptor write. */ #define BLE_GAP_SUBSCRIBE_REASON_WRITE 1 /** Peer s CCCD subscription state cleared due to connection termination. */ #define BLE_GAP_SUBSCRIBE_REASON_TERM 2 /** * Peer s CCCD subscription state changed due to restore from persistence * (bonding restored). */ #define BLE_GAP_SUBSCRIBE_REASON_RESTORE 3 struct ble_gap_sec_state {\n unsigned encrypted : 1 ;\n unsigned authenticated : 1 ;\n unsigned bonded : 1 ;\n}; /** * @param discoverable_mode One of the following constants: * o BLE_GAP_DISC_MODE_NON * (non-discoverable; 3.C.9.2.2). * o BLE_GAP_DISC_MODE_LTD * (limited-discoverable; 3.C.9.2.3). * o BLE_GAP_DISC_MODE_GEN * (general-discoverable; 3.C.9.2.4). * @param connectable_mode One of the following constants: * o BLE_GAP_CONN_MODE_NON * (non-connectable; 3.C.9.3.2). * o BLE_GAP_CONN_MODE_DIR * (directed-connectable; 3.C.9.3.3). * o BLE_GAP_CONN_MODE_UND * (undirected-connectable; 3.C.9.3.4). */ struct ble_gap_adv_params {\n /*** Mandatory fields. */ \n uint8_t conn_mode ;\n uint8_t disc_mode ;\n\n /*** Optional fields; assign 0 to make the stack calculate them. */ \n uint16_t itvl_min ;\n uint16_t itvl_max ;\n uint8_t channel_map ;\n uint8_t filter_policy ;\n uint8_t high_duty_cycle : 1 ;\n}; #define BLE_GAP_ROLE_MASTER 0 #define BLE_GAP_ROLE_SLAVE 1 struct ble_gap_conn_desc {\n struct ble_gap_sec_state sec_state ;\n uint8_t peer_ota_addr [ 6 ];\n uint8_t peer_id_addr [ 6 ];\n uint8_t our_id_addr [ 6 ];\n uint8_t our_ota_addr [ 6 ];\n uint16_t conn_handle ;\n uint16_t conn_itvl ;\n uint16_t conn_latency ;\n uint16_t supervision_timeout ;\n uint8_t peer_ota_addr_type ;\n uint8_t peer_id_addr_type ;\n uint8_t our_id_addr_type ;\n uint8_t our_ota_addr_type ;\n uint8_t role ;\n uint8_t master_clock_accuracy ;\n}; struct ble_gap_conn_params {\n uint16_t scan_itvl ;\n uint16_t scan_window ;\n uint16_t itvl_min ;\n uint16_t itvl_max ;\n uint16_t latency ;\n uint16_t supervision_timeout ;\n uint16_t min_ce_len ;\n uint16_t max_ce_len ;\n}; struct ble_gap_disc_params {\n uint16_t itvl ;\n uint16_t window ;\n uint8_t filter_policy ;\n uint8_t limited : 1 ;\n uint8_t passive : 1 ;\n uint8_t filter_duplicates : 1 ;\n}; struct ble_gap_upd_params {\n uint16_t itvl_min ;\n uint16_t itvl_max ;\n uint16_t latency ;\n uint16_t supervision_timeout ;\n uint16_t min_ce_len ;\n uint16_t max_ce_len ;\n}; struct ble_gap_passkey_params {\n uint8_t action ;\n uint32_t numcmp ;\n}; struct ble_gap_disc_desc {\n /*** Common fields. */ \n uint8_t event_type ;\n uint8_t addr_type ;\n uint8_t length_data ;\n int8_t rssi ;\n uint8_t addr [ 6 ];\n\n /*** LE advertising report fields; both null if no data present. */ \n uint8_t *data ;\n struct ble_hs_adv_fields *fields ;\n\n /*** * LE direct advertising report fields; direct_addr_type is * BLE_GAP_ADDR_TYPE_NONE if direct address fields are not present. */ \n uint8_t direct_addr_type ;\n uint8_t direct_addr [ 6 ];\n};",
- "title": "GAP events"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active/",
- "text": "ble_gap_adv_active\n\n\nint\n\n\nble_gap_adv_active\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nIndicates whether an advertisement procedure is currently in progress.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nNo advertisement procedure in progress.\n\n\n\n\n\n\n1\n\n\nAdvertisement procedure in progress.",
- "title": "ble_gap_adv_active"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active/#ble95gap95adv95active",
- "text": "int ble_gap_adv_active ( void )",
- "title": "ble_gap_adv_active"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active/#description",
- "text": "Indicates whether an advertisement procedure is currently in progress.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_active/#returned-values",
- "text": "Value Condition 0 No advertisement procedure in progress. 1 Advertisement procedure in progress.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields/",
- "text": "ble_gap_adv_rsp_set_fields\n\n\nint\n\n\nble_gap_adv_rsp_set_fields\n(\nconst\n \nstruct\n \nble_hs_adv_fields\n \n*rsp_fields\n)\n\n\n\n\n\nDescription\n\n\nConfigures the data to include in subsequent scan responses.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nadv_fields\n\n\nSpecifies the scan response data.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EBUSY\n\n\nAdvertising is in progress.\n\n\n\n\n\n\nBLE_HS_EMSGSIZE\n\n\nThe specified data is too large to fit in an advertisement.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_adv_rsp_set_fields"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields/#ble95gap95adv95rsp95set95fields",
- "text": "int ble_gap_adv_rsp_set_fields ( const struct ble_hs_adv_fields *rsp_fields )",
- "title": "ble_gap_adv_rsp_set_fields"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields/#description",
- "text": "Configures the data to include in subsequent scan responses.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields/#parameters",
- "text": "Parameter Description adv_fields Specifies the scan response data.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_rsp_set_fields/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EBUSY Advertising is in progress. BLE_HS_EMSGSIZE The specified data is too large to fit in an advertisement. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields/",
- "text": "ble_gap_adv_set_fields\n\n\nint\n\n\nble_gap_adv_set_fields\n(\nconst\n \nstruct\n \nble_hs_adv_fields\n \n*adv_fields\n)\n\n\n\n\n\nDescription\n\n\nConfigures the data to include in subsequent advertisements.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nadv_fields\n\n\nSpecifies the advertisement data.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EBUSY\n\n\nAdvertising is in progress.\n\n\n\n\n\n\nBLE_HS_EMSGSIZE\n\n\nThe specified data is too large to fit in an advertisement.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_adv_set_fields"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields/#ble95gap95adv95set95fields",
- "text": "int ble_gap_adv_set_fields ( const struct ble_hs_adv_fields *adv_fields )",
- "title": "ble_gap_adv_set_fields"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields/#description",
- "text": "Configures the data to include in subsequent advertisements.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields/#parameters",
- "text": "Parameter Description adv_fields Specifies the advertisement data.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_set_fields/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EBUSY Advertising is in progress. BLE_HS_EMSGSIZE The specified data is too large to fit in an advertisement. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start/",
- "text": "ble_gap_adv_start\n\n\nint\n\n\nble_gap_adv_start\n(\n \nuint8_t\n \nown_addr_type\n,\n \nuint8_t\n \npeer_addr_type\n,\n \nconst\n \nuint8_t\n \n*peer_addr\n,\n \nint32_t\n \nduration_ms\n,\n \nconst\n \nstruct\n \nble_gap_adv_params\n \n*adv_params\n,\n \nble_gap_event_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates advertising.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nown_addr_type\n\n\nThe type of address the stack should use for itself. Valid values are: \nBLE_ADDR_TYPE_PUBLIC\n \nBLE_ADDR_TYPE_RANDOM\n \nBLE_ADDR_TYPE_RPA_PUB_DEFAULT\n \nBLE_ADDR_TYPE_RPA_RND_DEFAULT\n\n\n\n\n\n\npeer_addr_type\n\n\nAddress type of the peer's identity address. Valid values are: \nBLE_ADDR_TYPE_PUBLIC\n \nBLE_ADDR_TYPE_RANDOM\n This parameter is ignored unless directed advertising is being used.\n\n\n\n\n\n\npeer_addr\n\n\nThe peer's six-byte identity address. This parameter is ignored unless directed advertising is being used.\n\n\n\n\n\n\nduration_ms\n\n\nThe duration of the advertisement procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_ADV_COMPLETE event is reported. Units are milliseconds. Specify BLE_HS_FOREVER for no expiration.\n\n\n\n\n\n\nadv_params\n\n\nAdditional arguments specifying the particulars of the advertising procedure.\n\n\n\n\n\n\ncb\n\n\nThe callback to associate with this advertising procedure. If advertising ends, the event is reported through this callback. If advertising results in a connection, the connection inherits this callback as its event-reporting mechanism.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_adv_start"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start/#ble95gap95adv95start",
- "text": "int ble_gap_adv_start (\n uint8_t own_addr_type ,\n uint8_t peer_addr_type ,\n const uint8_t *peer_addr ,\n int32_t duration_ms ,\n const struct ble_gap_adv_params *adv_params ,\n ble_gap_event_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gap_adv_start"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start/#description",
- "text": "Initiates advertising.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start/#parameters",
- "text": "Parameter Description own_addr_type The type of address the stack should use for itself. Valid values are: BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM BLE_ADDR_TYPE_RPA_PUB_DEFAULT BLE_ADDR_TYPE_RPA_RND_DEFAULT peer_addr_type Address type of the peer's identity address. Valid values are: BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM This parameter is ignored unless directed advertising is being used. peer_addr The peer's six-byte identity address. This parameter is ignored unless directed advertising is being used. duration_ms The duration of the advertisement procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_ADV_COMPLETE event is reported. Units are milliseconds. Specify BLE_HS_FOREVER for no expiration. adv_params Additional arguments specifying the particulars of the advertising procedure. cb The callback to associate with this advertising procedure. If advertising ends, the event is reported through this callback. If advertising results in a connection, the connection inherits this callback as its event-reporting mechanism. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_start/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop/",
- "text": "ble_gap_adv_stop\n\n\nint\n\n\nble_gap_adv_stop\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nStops the currently-active advertising procedure. A success return code indicates that advertising has been fully aborted; a new advertising procedure can be initiated immediately.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EALREADY\n\n\nThere is no active advertising procedure.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_adv_stop"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop/#ble95gap95adv95stop",
- "text": "int ble_gap_adv_stop ( void )",
- "title": "ble_gap_adv_stop"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop/#description",
- "text": "Stops the currently-active advertising procedure. A success return code indicates that advertising has been fully aborted; a new advertising procedure can be initiated immediately.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_adv_stop/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EALREADY There is no active advertising procedure. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active/",
- "text": "ble_gap_conn_active\n\n\nint\n\n\nble_gap_conn_active\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nIndicates whether a connect procedure is currently in progress.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nNo connect procedure in progress.\n\n\n\n\n\n\n1\n\n\nConnect procedure in progress.",
- "title": "ble_gap_conn_active"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active/#ble95gap95conn95active",
- "text": "int ble_gap_conn_active ( void )",
- "title": "ble_gap_conn_active"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active/#description",
- "text": "Indicates whether a connect procedure is currently in progress.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_active/#returned-values",
- "text": "Value Condition 0 No connect procedure in progress. 1 Connect procedure in progress.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel/",
- "text": "ble_gap_conn_cancel\n\n\nint\n\n\nble_gap_conn_cancel\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nAborts a connect procedure in progress.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_conn_cancel"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel/#ble95gap95conn95cancel",
- "text": "int ble_gap_conn_cancel ( void )",
- "title": "ble_gap_conn_cancel"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel/#description",
- "text": "Aborts a connect procedure in progress.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_cancel/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find/",
- "text": "ble_gap_conn_find\n\n\nint\n\n\nble_gap_conn_find\n(\n \nuint16_t\n \nhandle\n,\n \nstruct\n \nble_gap_conn_desc\n \n*out_desc\n\n)\n\n\n\n\n\nDescription\n\n\nSearches for a connection with the specified handle. If a matching connection is found, the supplied connection descriptor is filled correspondingly.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nhandle\n\n\nThe connection handle to search for.\n\n\n\n\n\n\nout_desc\n\n\nOn success, this is populated with information relating to the matching connection. Pass NULL if you don't need this information.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOTCONN\n\n\nNo matching connection was found.",
- "title": "ble_gap_conn_find"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find/#ble95gap95conn95find",
- "text": "int ble_gap_conn_find (\n uint16_t handle ,\n struct ble_gap_conn_desc *out_desc \n)",
- "title": "ble_gap_conn_find"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find/#description",
- "text": "Searches for a connection with the specified handle. If a matching connection is found, the supplied connection descriptor is filled correspondingly.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find/#parameters",
- "text": "Parameter Description handle The connection handle to search for. out_desc On success, this is populated with information relating to the matching connection. Pass NULL if you don't need this information.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_find/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOTCONN No matching connection was found.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_rssi/",
- "text": "ble_gap_conn_rssi\n\n\nint\n\n\nble_gap_conn_rssi\n(\n \nuint16_t\n \nconn_handle\n,\n \nint8_t\n \n*out_rssi\n\n)\n\n\n\n\n\nDescription\n\n\nRetrieves the most-recently measured RSSI for the specified connection. A connection's RSSI is updated whenever a data channel PDU is received.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nSpecifies the connection to query.\n\n\n\n\n\n\nout_rssi\n\n\nOn success, the retrieved RSSI is written here.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nHCI return code\n\n\nThe controller rejected the request.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_conn_rssi"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_rssi/#ble95gap95conn95rssi",
- "text": "int ble_gap_conn_rssi (\n uint16_t conn_handle ,\n int8_t *out_rssi \n)",
- "title": "ble_gap_conn_rssi"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_rssi/#description",
- "text": "Retrieves the most-recently measured RSSI for the specified connection. A connection's RSSI is updated whenever a data channel PDU is received.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_rssi/#parameters",
- "text": "Parameter Description conn_handle Specifies the connection to query. out_rssi On success, the retrieved RSSI is written here.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_conn_rssi/#returned-values",
- "text": "Value Condition 0 Success. HCI return code The controller rejected the request. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_connect/",
- "text": "ble_gap_connect\n\n\nint\n\n\nble_gap_connect\n(\n \nuint8_t\n \nown_addr_type\n,\n \nuint8_t\n \npeer_addr_type\n,\n \nconst\n \nuint8_t\n \n*peer_addr\n,\n \nint32_t\n \nduration_ms\n,\n \nconst\n \nstruct\n \nble_gap_conn_params\n \n*conn_params\n,\n \nble_gap_event_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates a connect procedure.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nown_addr_type\n\n\nThe type of address the stack should use for itself during connection establishment. \nBLE_ADDR_TYPE_PUBLIC\n \nBLE_ADDR_TYPE_RANDOM\n \nBLE_ADDR_TYPE_RPA_PUB_DEFAULT\n \nBLE_ADDR_TYPE_RPA_RND_DEFAULT\n\n\n\n\n\n\npeer_addr_type\n\n\nThe peer's address type. One of: \nBLE_HCI_CONN_PEER_ADDR_PUBLIC\n \nBLE_HCI_CONN_PEER_ADDR_RANDOM\n \nBLE_HCI_CONN_PEER_ADDR_PUBLIC_IDENT\n \nBLE_HCI_CONN_PEER_ADDR_RANDOM_IDENT\n \nBLE_GAP_ADDR_TYPE_WL\n\n\n\n\n\n\npeer_addr\n\n\nThe identity address of the peer to connect to. This parameter is ignored when the white list is used.\n\n\n\n\n\n\nduration_ms\n\n\nThe duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds.\n\n\n\n\n\n\nconn_params\n\n\nAdditional arguments specifying the particulars of the connect procedure. Specify null for default values.\n\n\n\n\n\n\ncb\n\n\nThe callback to associate with this connect procedure. When the connect procedure completes, the result is reported through this callback. If the connect procedure succeeds, the connection inherits this callback as its event-reporting mechanism.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_connect"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_connect/#ble95gap95connect",
- "text": "int ble_gap_connect (\n uint8_t own_addr_type ,\n uint8_t peer_addr_type ,\n const uint8_t *peer_addr ,\n int32_t duration_ms ,\n const struct ble_gap_conn_params *conn_params ,\n ble_gap_event_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gap_connect"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_connect/#description",
- "text": "Initiates a connect procedure.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_connect/#parameters",
- "text": "Parameter Description own_addr_type The type of address the stack should use for itself during connection establishment. BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM BLE_ADDR_TYPE_RPA_PUB_DEFAULT BLE_ADDR_TYPE_RPA_RND_DEFAULT peer_addr_type The peer's address type. One of: BLE_HCI_CONN_PEER_ADDR_PUBLIC BLE_HCI_CONN_PEER_ADDR_RANDOM BLE_HCI_CONN_PEER_ADDR_PUBLIC_IDENT BLE_HCI_CONN_PEER_ADDR_RANDOM_IDENT BLE_GAP_ADDR_TYPE_WL peer_addr The identity address of the peer to connect to. This parameter is ignored when the white list is used. duration_ms The duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds. conn_params Additional arguments specifying the particulars of the connect procedure. Specify null for default values. cb The callback to associate with this connect procedure. When the connect procedure completes, the result is reported through this callback. If the connect procedure succeeds, the connection inherits this callback as its event-reporting mechanism. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_connect/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc/",
- "text": "ble_gap_disc\n\n\nint\n\n\nble_gap_disc\n(\n \nuint8_t\n \nown_addr_type\n,\n \nint32_t\n \nduration_ms\n,\n \nconst\n \nstruct\n \nble_gap_disc_params\n \n*disc_params\n,\n \nble_gap_event_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nPerforms the Limited or General Discovery Procedures.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nown_addr_type\n\n\nThe type of address the stack should use for itself when sending scan requests. Valid values are: \nBLE_ADDR_TYPE_PUBLIC\n \nBLE_ADDR_TYPE_RANDOM\n \nBLE_ADDR_TYPE_RPA_PUB_DEFAULT\n \nBLE_ADDR_TYPE_RPA_RND_DEFAULT\n This parameter is ignored unless active scanning is being used.\n\n\n\n\n\n\nduration_ms\n\n\nThe duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds. Specify BLE_HS_FOREVER for no expiration.\n\n\n\n\n\n\ndisc_params\n\n\nAdditional arguments specifying the particulars of the discovery procedure.\n\n\n\n\n\n\ncb\n\n\nThe callback to associate with this discovery procedure. Advertising reports and discovery termination events are reported through this callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_disc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc/#ble95gap95disc",
- "text": "int ble_gap_disc (\n uint8_t own_addr_type ,\n int32_t duration_ms ,\n const struct ble_gap_disc_params *disc_params ,\n ble_gap_event_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gap_disc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc/#description",
- "text": "Performs the Limited or General Discovery Procedures.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc/#parameters",
- "text": "Parameter Description own_addr_type The type of address the stack should use for itself when sending scan requests. Valid values are: BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM BLE_ADDR_TYPE_RPA_PUB_DEFAULT BLE_ADDR_TYPE_RPA_RND_DEFAULT This parameter is ignored unless active scanning is being used. duration_ms The duration of the discovery procedure. On expiration, the procedure ends and a BLE_GAP_EVENT_DISC_COMPLETE event is reported. Units are milliseconds. Specify BLE_HS_FOREVER for no expiration. disc_params Additional arguments specifying the particulars of the discovery procedure. cb The callback to associate with this discovery procedure. Advertising reports and discovery termination events are reported through this callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active/",
- "text": "ble_gap_disc_active\n\n\nint\n\n\nble_gap_disc_active\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nIndicates whether a discovery procedure is currently in progress.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nNo discovery procedure in progress.\n\n\n\n\n\n\n1\n\n\nDiscovery procedure in progress.",
- "title": "ble_gap_disc_active"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active/#ble95gap95disc95active",
- "text": "int ble_gap_disc_active ( void )",
- "title": "ble_gap_disc_active"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active/#description",
- "text": "Indicates whether a discovery procedure is currently in progress.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_active/#returned-values",
- "text": "Value Condition 0 No discovery procedure in progress. 1 Discovery procedure in progress.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel/",
- "text": "ble_gap_disc_cancel\n\n\nint\n\n\nble_gap_disc_cancel\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nCancels the discovery procedure currently in progress. A success return code indicates that scanning has been fully aborted; a new discovery or connect procedure can be initiated immediately.\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EALREADY\n\n\nThere is no discovery procedure to cancel.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_disc_cancel"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel/#ble95gap95disc95cancel",
- "text": "int ble_gap_disc_cancel ( void )",
- "title": "ble_gap_disc_cancel"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel/#description",
- "text": "Cancels the discovery procedure currently in progress. A success return code indicates that scanning has been fully aborted; a new discovery or connect procedure can be initiated immediately.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_disc_cancel/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EALREADY There is no discovery procedure to cancel. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate/",
- "text": "ble_gap_security_initiate\n\n\nint\n\n\nble_gap_security_initiate\n(\nuint16_t\n \nconn_handle\n)\n\n\n\n\n\nDescription\n\n\nInitiates the GAP encryption procedure.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe handle corresponding to the connection to encrypt.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOTCONN\n\n\nThe there is no connection with the specified handle.\n\n\n\n\n\n\nBLE_HS_EALREADY\n\n\nAn encrpytion procedure for this connection is already in progress.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_security_initiate"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate/#ble95gap95security95initiate",
- "text": "int ble_gap_security_initiate ( uint16_t conn_handle )",
- "title": "ble_gap_security_initiate"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate/#description",
- "text": "Initiates the GAP encryption procedure.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate/#parameters",
- "text": "Parameter Description conn_handle The handle corresponding to the connection to encrypt.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_security_initiate/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOTCONN The there is no connection with the specified handle. BLE_HS_EALREADY An encrpytion procedure for this connection is already in progress. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate/",
- "text": "ble_gap_terminate\n\n\nint\n\n\nble_gap_terminate\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint8_t\n \nhci_reason\n\n)\n\n\n\n\n\nDescription\n\n\nTerminates an established connection.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe handle corresponding to the connection to terminate.\n\n\n\n\n\n\nhci_reason\n\n\nThe HCI error code to indicate as the reason for termination.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOTCONN\n\n\nThere is no connection with the specified handle.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_terminate"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate/#ble95gap95terminate",
- "text": "int ble_gap_terminate (\n uint16_t conn_handle ,\n uint8_t hci_reason \n)",
- "title": "ble_gap_terminate"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate/#description",
- "text": "Terminates an established connection.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate/#parameters",
- "text": "Parameter Description conn_handle The handle corresponding to the connection to terminate. hci_reason The HCI error code to indicate as the reason for termination.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_terminate/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOTCONN There is no connection with the specified handle. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params/",
- "text": "ble_gap_update_params\n\n\nint\n\n\nble_gap_update_params\n(\n \nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gap_upd_params\n \n*params\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates a connection parameter update procedure.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe handle corresponding to the connection to update.\n\n\n\n\n\n\nparams\n\n\nThe connection parameters to attempt to update to.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOTCONN\n\n\nThe there is no connection with the specified handle.\n\n\n\n\n\n\nBLE_HS_EALREADY\n\n\nA connection update procedure for this connection is already in progress.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_update_params"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params/#ble95gap95update95params",
- "text": "int ble_gap_update_params (\n uint16_t conn_handle ,\n const struct ble_gap_upd_params *params \n)",
- "title": "ble_gap_update_params"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params/#description",
- "text": "Initiates a connection parameter update procedure.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params/#parameters",
- "text": "Parameter Description conn_handle The handle corresponding to the connection to update. params The connection parameters to attempt to update to.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_update_params/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOTCONN The there is no connection with the specified handle. BLE_HS_EALREADY A connection update procedure for this connection is already in progress. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set/",
- "text": "ble_gap_wl_set\n\n\nint\n\n\nble_gap_wl_set\n(\n \nconst\n \nstruct\n \nble_gap_white_entry\n \n*white_list\n,\n \nuint8_t\n \nwhite_list_count\n\n)\n\n\n\n\n\nDescription\n\n\nOverwrites the controller's white list with the specified contents.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nwhite_list\n\n\nThe entries to write to the white list.\n\n\n\n\n\n\nwhite_list_count\n\n\nThe number of entries in the white list.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gap_wl_set"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set/#ble95gap95wl95set",
- "text": "int ble_gap_wl_set (\n const struct ble_gap_white_entry *white_list ,\n uint8_t white_list_count \n)",
- "title": "ble_gap_wl_set"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set/#description",
- "text": "Overwrites the controller's white list with the specified contents.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set/#parameters",
- "text": "Parameter Description white_list The entries to write to the white list. white_list_count The number of entries in the white list.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gap/functions/ble_gap_wl_set/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/ble_gattc/",
- "text": "NimBLE Host GATT Client Reference\n\n\nIntroduction\n\n\nThe Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The client half of the GATT API initiates GATT procedures.\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nBLE host GATT client definitions\n\n\nFunctions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_gattc_disc_all_chrs\n\n\nInitiates GATT procedure: Discover All Characteristics of a Service.\n\n\n\n\n\n\nble_gattc_disc_all_dscs\n\n\nInitiates GATT procedure: Discover All Characteristic Descriptors.\n\n\n\n\n\n\nble_gattc_disc_all_svcs\n\n\nInitiates GATT procedure: Discover All Primary Services.\n\n\n\n\n\n\nble_gattc_disc_chrs_by_uuid\n\n\nInitiates GATT procedure: Discover Characteristics by UUID.\n\n\n\n\n\n\nble_gattc_disc_svc_by_uuid\n\n\nInitiates GATT procedure: Discover Primary Service by Service UUID.\n\n\n\n\n\n\nble_gattc_exchange_mtu\n\n\nInitiates GATT procedure: Exchange MTU.\n\n\n\n\n\n\nble_gattc_find_inc_svcs\n\n\nInitiates GATT procedure: Find Included Services.\n\n\n\n\n\n\nble_gattc_indicate\n\n\nSends a characteristic indication.\n\n\n\n\n\n\nble_gattc_notify\n\n\nSends a characteristic notification.\n\n\n\n\n\n\nble_gattc_notify_custom\n\n\nSends a \"free-form\" characteristic notification.\n\n\n\n\n\n\nble_gattc_read\n\n\nInitiates GATT procedure: Read Characteristic Value.\n\n\n\n\n\n\nble_gattc_read_by_uuid\n\n\nInitiates GATT procedure: Read Using Characteristic UUID.\n\n\n\n\n\n\nble_gattc_read_long\n\n\nInitiates GATT procedure: Read Long Characteristic Values.\n\n\n\n\n\n\nble_gattc_read_mult\n\n\nInitiates GATT procedure: Read Multiple Characteristic Values.\n\n\n\n\n\n\nble_gattc_write\n\n\nInitiates GATT procedure: Write Characteristic Value.\n\n\n\n\n\n\nble_gattc_write_flat\n\n\nInitiates GATT procedure: Write Characteristic Value (flat buffer version).\n\n\n\n\n\n\nble_gattc_write_long\n\n\nInitiates GATT procedure: Write Long Characteristic Values.\n\n\n\n\n\n\nble_gattc_write_no_rsp\n\n\nInitiates GATT procedure: Write Without Response.\n\n\n\n\n\n\nble_gattc_write_no_rsp_flat\n\n\nInitiates GATT procedure: Write Without Response.\n\n\n\n\n\n\nble_gattc_write_reliable\n\n\nInitiates GATT procedure: Reliable Writes.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/ble_gattc/#nimble-host-gatt-client-reference",
- "text": "",
- "title": "NimBLE Host GATT Client Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/ble_gattc/#introduction",
- "text": "The Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The client half of the GATT API initiates GATT procedures.",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/ble_gattc/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/ble_gattc/#definitions",
- "text": "BLE host GATT client definitions",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/ble_gattc/#functions",
- "text": "Function Description ble_gattc_disc_all_chrs Initiates GATT procedure: Discover All Characteristics of a Service. ble_gattc_disc_all_dscs Initiates GATT procedure: Discover All Characteristic Descriptors. ble_gattc_disc_all_svcs Initiates GATT procedure: Discover All Primary Services. ble_gattc_disc_chrs_by_uuid Initiates GATT procedure: Discover Characteristics by UUID. ble_gattc_disc_svc_by_uuid Initiates GATT procedure: Discover Primary Service by Service UUID. ble_gattc_exchange_mtu Initiates GATT procedure: Exchange MTU. ble_gattc_find_inc_svcs Initiates GATT procedure: Find Included Services. ble_gattc_indicate Sends a characteristic indication. ble_gattc_notify Sends a characteristic notification. ble_gattc_notify_custom Sends a \"free-form\" characteristic notification. ble_gattc_read Initiates GATT procedure: Read Characteristic Value. ble_gattc_read_by_uuid Initiates GATT procedure: Read Using Characteristic UUID. ble_gattc_read_long Initiates GATT procedure: Read Long Characteristic Values. ble_gattc_read_mult Initiates GATT procedure: Read Multiple Characteristic Values. ble_gattc_write Initiates GATT procedure: Write Characteristic Value. ble_gattc_write_flat Initiates GATT procedure: Write Characteristic Value (flat buffer version). ble_gattc_write_long Initiates GATT procedure: Write Long Characteristic Values. ble_gattc_write_no_rsp Initiates GATT procedure: Write Without Response. ble_gattc_write_no_rsp_flat Initiates GATT procedure: Write Without Response. ble_gattc_write_reliable Initiates GATT procedure: Reliable Writes.",
- "title": "Functions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/definitions/ble_gattc_defs/",
- "text": "GATT Client Definitions\n\n\nstruct\n \nble_gatt_error\n {\n \nuint16_t\n \nstatus\n;\n \nuint16_t\n \natt_handle\n;\n};\n\n\n\n\n\nstruct\n \nble_gatt_svc\n {\n \nuint16_t\n \nstart_handle\n;\n \nuint16_t\n \nend_handle\n;\n \nuint8_t\n \nuuid128\n[\n16\n];\n};\n\n\n\n\n\nstruct\n \nble_gatt_attr\n {\n \nuint16_t\n \nhandle\n;\n \nuint16_t\n \noffset\n;\n \nstruct\n \nos_mbuf\n \n*om\n;\n};\n\n\n\n\n\nstruct\n \nble_gatt_chr\n {\n \nuint16_t\n \ndef_handle\n;\n \nuint16_t\n \nval_handle\n;\n \nuint8_t\n \nproperties\n;\n \nuint8_t\n \nuuid128\n[\n16\n];\n};\n\n\n\n\n\nstruct\n \nble_gatt_dsc\n {\n \nuint16_t\n \nhandle\n;\n \nuint8_t\n \nuuid128\n[\n16\n];\n};\n\n\n\n\n\ntypedef\n \nint\n \nble_gatt_mtu_fn\n(\nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gatt_error\n \n*error\n,\n \nuint16_t\n \nmtu\n, \nvoid\n \n*arg\n);\n\n\n\n\n\ntypedef\n \nint\n \nble_gatt_disc_svc_fn\n(\nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gatt_error\n \n*error\n,\n \nconst\n \nstruct\n \nble_gatt_svc\n \n*service\n,\n \nvoid\n \n*arg\n);\n\n\n\n\n\n/**\n\n\n * The host will free the attribute mbuf automatically after the callback is\n\n\n * executed. The application can take ownership of the mbuf and prevent it\n\n\n * from being freed by assigning NULL to attr-\nom.\n\n\n */\n\n\ntypedef\n \nint\n \nble_gatt_attr_fn\n(\nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gatt_error\n \n*error\n,\n \nstruct\n \nble_gatt_attr\n \n*attr\n,\n \nvoid\n \n*arg\n);\n\n\n\n\n\n/**\n\n\n * The host will free the attribute mbufs automatically after the callback is\n\n\n * executed. The application can take ownership of the mbufs and prevent them\n\n\n * from being freed by assigning NULL to each attribute\ns om field.\n\n\n */\n\n\ntypedef\n \nint\n \nble_gatt_reliable_attr_fn\n(\nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gatt_error\n \n*error\n,\n \nstruct\n \nble_gatt_attr\n \n*attrs\n,\n \nuint8_t\n \nnum_attrs\n, \nvoid\n \n*arg\n);\n\n\n\n\n\ntypedef\n \nint\n \nble_gatt_chr_fn\n(\nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gatt_error\n \n*error\n,\n \nconst\n \nstruct\n \nble_gatt_chr\n \n*chr\n, \nvoid\n \n*arg\n);\n\n\n\n\n\ntypedef\n \nint\n \nble_gatt_dsc_fn\n(\nuint16_t\n \nconn_handle\n,\n \nconst\n \nstruct\n \nble_gatt_error\n \n*error\n,\n \nuint16_t\n \nchr_def_handle\n,\n \nconst\n \nstruct\n \nble_gatt_dsc\n \n*dsc\n,\n \nvoid\n \n*arg\n);",
- "title": "GATT client definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/definitions/ble_gattc_defs/#gatt-client-definitions",
- "text": "struct ble_gatt_error {\n uint16_t status ;\n uint16_t att_handle ;\n}; struct ble_gatt_svc {\n uint16_t start_handle ;\n uint16_t end_handle ;\n uint8_t uuid128 [ 16 ];\n}; struct ble_gatt_attr {\n uint16_t handle ;\n uint16_t offset ;\n struct os_mbuf *om ;\n}; struct ble_gatt_chr {\n uint16_t def_handle ;\n uint16_t val_handle ;\n uint8_t properties ;\n uint8_t uuid128 [ 16 ];\n}; struct ble_gatt_dsc {\n uint16_t handle ;\n uint8_t uuid128 [ 16 ];\n}; typedef int ble_gatt_mtu_fn ( uint16_t conn_handle ,\n const struct ble_gatt_error *error ,\n uint16_t mtu , void *arg ); typedef int ble_gatt_disc_svc_fn ( uint16_t conn_handle ,\n const struct ble_gatt_error *error ,\n const struct ble_gatt_svc *service ,\n void *arg ); /** * The host will free the attribute mbuf automatically after the callback is * executed. The application can take ownership of the mbuf and prevent it * from being freed by assigning NULL to attr- om. */ typedef int ble_gatt_attr_fn ( uint16_t conn_handle ,\n const struct ble_gatt_error *error ,\n struct ble_gatt_attr *attr ,\n void *arg ); /** * The host will free the attribute mbufs automatically after the callback is * executed. The application can take ownership of the mbufs and prevent them * from being freed by assigning NULL to each attribute s om field. */ typedef int ble_gatt_reliable_attr_fn ( uint16_t conn_handle ,\n const struct ble_gatt_error *error ,\n struct ble_gatt_attr *attrs ,\n uint8_t num_attrs , void *arg ); typedef int ble_gatt_chr_fn ( uint16_t conn_handle ,\n const struct ble_gatt_error *error ,\n const struct ble_gatt_chr *chr , void *arg ); typedef int ble_gatt_dsc_fn ( uint16_t conn_handle ,\n const struct ble_gatt_error *error ,\n uint16_t chr_def_handle ,\n const struct ble_gatt_dsc *dsc ,\n void *arg );",
- "title": "GATT Client Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs/",
- "text": "ble_gattc_disc_all_chrs\n\n\nint\n\n\nble_gattc_disc_all_chrs\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nstart_handle\n,\n \nuint16_t\n \nend_handle\n,\n \nble_gatt_chr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Discover All Characteristics of a Service.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nstart_handle\n\n\nThe handle to begin the search at (generally the service definition handle).\n\n\n\n\n\n\nend_handle\n\n\nThe handle to end the search at (generally the last handle in the service).\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_disc_all_chrs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs/#ble95gattc95disc95all95chrs",
- "text": "int ble_gattc_disc_all_chrs (\n uint16_t conn_handle ,\n uint16_t start_handle ,\n uint16_t end_handle ,\n ble_gatt_chr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_disc_all_chrs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs/#description",
- "text": "Initiates GATT procedure: Discover All Characteristics of a Service.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. start_handle The handle to begin the search at (generally the service definition handle). end_handle The handle to end the search at (generally the last handle in the service). cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_chrs/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs/",
- "text": "ble_gattc_disc_all_dscs\n\n\nint\n\n\nble_gattc_disc_all_dscs\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nchr_val_handle\n,\n \nuint16_t\n \nchr_end_handle\n,\n \nble_gatt_dsc_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Discover All Characteristic Descriptors.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nchr_val_handle\n\n\nThe handle of the characteristic value attribute.\n\n\n\n\n\n\nchr_end_handle\n\n\nThe last handle in the characteristic definition.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_disc_all_dscs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs/#ble95gattc95disc95all95dscs",
- "text": "int ble_gattc_disc_all_dscs (\n uint16_t conn_handle ,\n uint16_t chr_val_handle ,\n uint16_t chr_end_handle ,\n ble_gatt_dsc_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_disc_all_dscs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs/#description",
- "text": "Initiates GATT procedure: Discover All Characteristic Descriptors.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. chr_val_handle The handle of the characteristic value attribute. chr_end_handle The last handle in the characteristic definition. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_dscs/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs/",
- "text": "ble_gattc_disc_all_svcs\n\n\nint\n\n\nble_gattc_disc_all_svcs\n(\n \nuint16_t\n \nconn_handle\n,\n \nble_gatt_disc_svc_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Discover All Primary Services.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone",
- "title": "ble_gattc_disc_all_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs/#ble95gattc95disc95all95svcs",
- "text": "int ble_gattc_disc_all_svcs (\n uint16_t conn_handle ,\n ble_gatt_disc_svc_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_disc_all_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs/#description",
- "text": "Initiates GATT procedure: Discover All Primary Services.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_all_svcs/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid/",
- "text": "ble_gattc_disc_chrs_by_uuid\n\n\nint\n\n\nble_gattc_disc_chrs_by_uuid\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nstart_handle\n,\n \nuint16_t\n \nend_handle\n,\n \nconst\n \nvoid\n \n*uuid128\n,\n \nble_gatt_chr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Discover Characteristics by UUID.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nstart_handle\n\n\nThe handle to begin the search at (generally the service definition handle).\n\n\n\n\n\n\nend_handle\n\n\nThe handle to end the search at (generally the last handle in the service).\n\n\n\n\n\n\nchr_uuid128\n\n\nThe 128-bit UUID of the characteristic to discover.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_disc_chrs_by_uuid"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid/#ble95gattc95disc95chrs95by95uuid",
- "text": "int ble_gattc_disc_chrs_by_uuid (\n uint16_t conn_handle ,\n uint16_t start_handle ,\n uint16_t end_handle ,\n const void *uuid128 ,\n ble_gatt_chr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_disc_chrs_by_uuid"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid/#description",
- "text": "Initiates GATT procedure: Discover Characteristics by UUID.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. start_handle The handle to begin the search at (generally the service definition handle). end_handle The handle to end the search at (generally the last handle in the service). chr_uuid128 The 128-bit UUID of the characteristic to discover. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_chrs_by_uuid/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid/",
- "text": "ble_gattc_disc_svc_by_uuid\n\n\nint\n\n\nble_gattc_disc_svc_by_uuid\n(\n \nuint16_t\n \nconn_handle\n,\n \nconst\n \nvoid\n \n*svc_uuid128\n,\n \nble_gatt_disc_svc_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Discover Primary Service by Service UUID.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nservice_uuid128\n\n\nThe 128-bit UUID of the service to discover.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_disc_svc_by_uuid"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid/#ble95gattc95disc95svc95by95uuid",
- "text": "int ble_gattc_disc_svc_by_uuid (\n uint16_t conn_handle ,\n const void *svc_uuid128 ,\n ble_gatt_disc_svc_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_disc_svc_by_uuid"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid/#description",
- "text": "Initiates GATT procedure: Discover Primary Service by Service UUID.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. service_uuid128 The 128-bit UUID of the service to discover. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_disc_svc_by_uuid/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu/",
- "text": "ble_gattc_exchange_mtu\n\n\nint\n\n\nble_gattc_exchange_mtu\n(\n \nuint16_t\n \nconn_handle\n,\n \nble_gatt_mtu_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Exchange MTU.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_exchange_mtu"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu/#ble95gattc95exchange95mtu",
- "text": "int ble_gattc_exchange_mtu (\n uint16_t conn_handle ,\n ble_gatt_mtu_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_exchange_mtu"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu/#description",
- "text": "Initiates GATT procedure: Exchange MTU.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_exchange_mtu/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs/",
- "text": "ble_gattc_find_inc_svcs\n\n\nint\n\n\nble_gattc_find_inc_svcs\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nstart_handle\n,\n \nuint16_t\n \nend_handle\n,\n \nble_gatt_disc_svc_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Find Included Services.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nstart_handle\n\n\nThe handle to begin the search at (generally the service definition handle).\n\n\n\n\n\n\nend_handle\n\n\nThe handle to end the search at (generally the last handle in the service).\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_find_inc_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs/#ble95gattc95find95inc95svcs",
- "text": "int ble_gattc_find_inc_svcs (\n uint16_t conn_handle ,\n uint16_t start_handle ,\n uint16_t end_handle ,\n ble_gatt_disc_svc_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_find_inc_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs/#description",
- "text": "Initiates GATT procedure: Find Included Services.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. start_handle The handle to begin the search at (generally the service definition handle). end_handle The handle to end the search at (generally the last handle in the service). cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_find_inc_svcs/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_indicate/",
- "text": "ble_gattc_indicate\n\n\nint\n\n\nble_gattc_indicate\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nchr_val_handle\n\n)\n\n\n\n\n\nDescription\n\n\nSends a characteristic indication. The content of the message is read from the specified characteristic.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nchr_val_handle\n\n\nThe value attribute handle of the characteristic to include in the outgoing indication.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_indicate"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_indicate/#ble95gattc95indicate",
- "text": "int ble_gattc_indicate (\n uint16_t conn_handle ,\n uint16_t chr_val_handle \n)",
- "title": "ble_gattc_indicate"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_indicate/#description",
- "text": "Sends a characteristic indication. The content of the message is read from the specified characteristic.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_indicate/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. chr_val_handle The value attribute handle of the characteristic to include in the outgoing indication.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_indicate/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify/",
- "text": "ble_gattc_notify\n\n\nint\n\n\nble_gattc_notify\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nchr_val_handle\n\n)\n\n\n\n\n\nDescription\n\n\nSends a characteristic notification. The content of the message is read from the specified characteristic.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nchr_val_handle\n\n\nThe value attribute handle of the characteristic to include in the outgoing notification.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_notify"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify/#ble95gattc95notify",
- "text": "int ble_gattc_notify (\n uint16_t conn_handle ,\n uint16_t chr_val_handle \n)",
- "title": "ble_gattc_notify"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify/#description",
- "text": "Sends a characteristic notification. The content of the message is read from the specified characteristic.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. chr_val_handle The value attribute handle of the characteristic to include in the outgoing notification.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom/",
- "text": "ble_gattc_notify_custom\n\n\nint\n\n\nble_gattc_notify_custom\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nchr_val_handle\n,\n \nstruct\n \nos_mbuf\n \n*txom\n\n)\n\n\n\n\n\nDescription\n\n\nSends a \"free-form\" characteristic notification. This function consumes the supplied mbuf regardless of the outcome.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nchr_val_handle\n\n\nThe attribute handle to indicate in the outgoing notification.\n\n\n\n\n\n\ntxom\n\n\nThe value to write to the characteristic.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_notify_custom"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom/#ble95gattc95notify95custom",
- "text": "int ble_gattc_notify_custom (\n uint16_t conn_handle ,\n uint16_t chr_val_handle ,\n struct os_mbuf *txom \n)",
- "title": "ble_gattc_notify_custom"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom/#description",
- "text": "Sends a \"free-form\" characteristic notification. This function consumes the supplied mbuf regardless of the outcome.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. chr_val_handle The attribute handle to indicate in the outgoing notification. txom The value to write to the characteristic.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_notify_custom/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read/",
- "text": "ble_gattc_read\n\n\nint\n\n\nble_gattc_read\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nattr_handle\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Read Characteristic Value.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattr_handle\n\n\nThe handle of the characteristic value to read.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_read"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read/#ble95gattc95read",
- "text": "int ble_gattc_read (\n uint16_t conn_handle ,\n uint16_t attr_handle ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_read"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read/#description",
- "text": "Initiates GATT procedure: Read Characteristic Value.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attr_handle The handle of the characteristic value to read. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid/",
- "text": "ble_gattc_read_by_uuid\n\n\nint\n\n\nble_gattc_read_by_uuid\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nstart_handle\n,\n \nuint16_t\n \nend_handle\n,\n \nconst\n \nvoid\n \n*uuid128\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Read Using Characteristic UUID.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nstart_handle\n\n\nThe first handle to search (generally the handle of the service definition).\n\n\n\n\n\n\nend_handle\n\n\nThe last handle to search (generally the last handle in the service definition).\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_read_by_uuid"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid/#ble95gattc95read95by95uuid",
- "text": "int ble_gattc_read_by_uuid (\n uint16_t conn_handle ,\n uint16_t start_handle ,\n uint16_t end_handle ,\n const void *uuid128 ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_read_by_uuid"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid/#description",
- "text": "Initiates GATT procedure: Read Using Characteristic UUID.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. start_handle The first handle to search (generally the handle of the service definition). end_handle The last handle to search (generally the last handle in the service definition). cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_by_uuid/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long/",
- "text": "ble_gattc_read_long\n\n\nint\n\n\nble_gattc_read_long\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nhandle\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Read Long Characteristic Values.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nhandle\n\n\nThe handle of the characteristic value to read.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_read_long"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long/#ble95gattc95read95long",
- "text": "int ble_gattc_read_long (\n uint16_t conn_handle ,\n uint16_t handle ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_read_long"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long/#description",
- "text": "Initiates GATT procedure: Read Long Characteristic Values.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. handle The handle of the characteristic value to read. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_long/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult/",
- "text": "ble_gattc_read_mult\n\n\nint\n\n\nble_gattc_read_mult\n(\n \nuint16_t\n \nconn_handle\n,\n \nconst\n \nuint16_t\n \n*handles\n,\n \nuint8_t\n \nnum_handles\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Read Multiple Characteristic Values.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nhandles\n\n\nAn array of 16-bit attribute handles to read.\n\n\n\n\n\n\nnum_handles\n\n\nThe number of entries in the \"handles\" array.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_read_mult"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult/#ble95gattc95read95mult",
- "text": "int ble_gattc_read_mult (\n uint16_t conn_handle ,\n const uint16_t *handles ,\n uint8_t num_handles ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_read_mult"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult/#description",
- "text": "Initiates GATT procedure: Read Multiple Characteristic Values.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. handles An array of 16-bit attribute handles to read. num_handles The number of entries in the \"handles\" array. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_read_mult/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write/",
- "text": "ble_gattc_write\n\n\nint\n\n\nble_gattc_write\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nos_mbuf\n \n*txom\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Write Characteristic Value. This function consumes the supplied mbuf regardless of the outcome.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattr_handle\n\n\nThe handle of the characteristic value to write to.\n\n\n\n\n\n\ntxom\n\n\nThe value to write to the characteristic.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_write"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write/#ble95gattc95write",
- "text": "int ble_gattc_write (\n uint16_t conn_handle ,\n uint16_t attr_handle ,\n struct os_mbuf *txom ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_write"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write/#description",
- "text": "Initiates GATT procedure: Write Characteristic Value. This function consumes the supplied mbuf regardless of the outcome.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attr_handle The handle of the characteristic value to write to. txom The value to write to the characteristic. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_flat/",
- "text": "ble_gattc_write_flat\n\n\nint\n\n\nble_gattc_write_flat\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nattr_handle\n,\n \nconst\n \nvoid\n \n*data\n,\n \nuint16_t\n \ndata_len\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Write Characteristic Value (flat buffer version).\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattr_handle\n\n\nThe handle of the characteristic value to write to.\n\n\n\n\n\n\nvalue\n\n\nThe value to write to the characteristic.\n\n\n\n\n\n\nvalue_len\n\n\nThe number of bytes to write.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_write_flat"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_flat/#ble95gattc95write95flat",
- "text": "int ble_gattc_write_flat (\n uint16_t conn_handle ,\n uint16_t attr_handle ,\n const void *data ,\n uint16_t data_len ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_write_flat"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_flat/#description",
- "text": "Initiates GATT procedure: Write Characteristic Value (flat buffer version).",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_flat/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attr_handle The handle of the characteristic value to write to. value The value to write to the characteristic. value_len The number of bytes to write. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_flat/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long/",
- "text": "ble_gattc_write_long\n\n\nint\n\n\nble_gattc_write_long\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nos_mbuf\n \n*txom\n,\n \nble_gatt_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Write Long Characteristic Values. This function consumes the supplied mbuf regardless of the outcome.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattr_handle\n\n\nThe handle of the characteristic value to write to.\n\n\n\n\n\n\ntxom\n\n\nThe value to write to the characteristic.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_write_long"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long/#ble95gattc95write95long",
- "text": "int ble_gattc_write_long (\n uint16_t conn_handle ,\n uint16_t attr_handle ,\n struct os_mbuf *txom ,\n ble_gatt_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_write_long"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long/#description",
- "text": "Initiates GATT procedure: Write Long Characteristic Values. This function consumes the supplied mbuf regardless of the outcome.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attr_handle The handle of the characteristic value to write to. txom The value to write to the characteristic. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_long/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp/",
- "text": "ble_gattc_write_no_rsp\n\n\nint\n\n\nble_gattc_write_no_rsp\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nos_mbuf\n \n*txom\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Write Without Response. This function consumes the supplied mbuf regardless of the outcome.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattr_handle\n\n\nThe handle of the characteristic value to write to.\n\n\n\n\n\n\ntxom\n\n\nThe value to write to the characteristic.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_write_no_rsp"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp/#ble95gattc95write95no95rsp",
- "text": "int ble_gattc_write_no_rsp (\n uint16_t conn_handle ,\n uint16_t attr_handle ,\n struct os_mbuf *txom \n)",
- "title": "ble_gattc_write_no_rsp"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp/#description",
- "text": "Initiates GATT procedure: Write Without Response. This function consumes the supplied mbuf regardless of the outcome.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attr_handle The handle of the characteristic value to write to. txom The value to write to the characteristic.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp_flat/",
- "text": "ble_gattc_write_no_rsp_flat\n\n\nint\n\n\nble_gattc_write_no_rsp_flat\n(\n \nuint16_t\n \nconn_handle\n,\n \nuint16_t\n \nattr_handle\n,\n \nconst\n \nvoid\n \n*data\n,\n \nuint16_t\n \ndata_len\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Write Without Response. This function consumes the supplied mbuf regardless of the outcome.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattr_handle\n\n\nThe handle of the characteristic value to write to.\n\n\n\n\n\n\nvalue\n\n\nThe value to write to the characteristic.\n\n\n\n\n\n\nvalue_len\n\n\nThe number of bytes to write.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_gattc_write_no_rsp_flat"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp_flat/#ble95gattc95write95no95rsp95flat",
- "text": "int ble_gattc_write_no_rsp_flat (\n uint16_t conn_handle ,\n uint16_t attr_handle ,\n const void *data ,\n uint16_t data_len \n)",
- "title": "ble_gattc_write_no_rsp_flat"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp_flat/#description",
- "text": "Initiates GATT procedure: Write Without Response. This function consumes the supplied mbuf regardless of the outcome.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp_flat/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attr_handle The handle of the characteristic value to write to. value The value to write to the characteristic. value_len The number of bytes to write.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_no_rsp_flat/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable/",
- "text": "ble_gattc_write_reliable\n\n\nint\n\n\nble_gattc_write_reliable\n(\n \nuint16_t\n \nconn_handle\n,\n \nstruct\n \nble_gatt_attr\n \n*attrs\n,\n \nint\n \nnum_attrs\n,\n \nble_gatt_reliable_attr_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nInitiates GATT procedure: Reliable Writes. This function consumes the supplied mbufs regardless of the outcome.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe connection over which to execute the procedure.\n\n\n\n\n\n\nattrs\n\n\nAn array of attribute descriptors; specifies which characteristics to write to and what data to write to them. The mbuf pointer in each attribute is set to NULL by this function.\n\n\n\n\n\n\nnum_attrs\n\n\nThe number of characteristics to write; equal to the number of elements in the 'attrs' array.\n\n\n\n\n\n\ncb\n\n\nThe function to call to report procedure status updates; null for no callback.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone",
- "title": "ble_gattc_write_reliable"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable/#ble95gattc95write95reliable",
- "text": "int ble_gattc_write_reliable (\n uint16_t conn_handle ,\n struct ble_gatt_attr *attrs ,\n int num_attrs ,\n ble_gatt_reliable_attr_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gattc_write_reliable"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable/#description",
- "text": "Initiates GATT procedure: Reliable Writes. This function consumes the supplied mbufs regardless of the outcome.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable/#parameters",
- "text": "Parameter Description conn_handle The connection over which to execute the procedure. attrs An array of attribute descriptors; specifies which characteristics to write to and what data to write to them. The mbuf pointer in each attribute is set to NULL by this function. num_attrs The number of characteristics to write; equal to the number of elements in the 'attrs' array. cb The function to call to report procedure status updates; null for no callback. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gattc/functions/ble_gattc_write_reliable/#returned-values",
- "text": "None",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/ble_gatts/",
- "text": "NimBLE Host GATT Server Reference\n\n\nIntroduction\n\n\nThe Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The server half of the GATT API handles registration and responding to GATT clients.\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nBLE host GATT server definitions\n\n\nFunctions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_gatts_add_svcs\n\n\nQueues a set of service definitions for registration.\n\n\n\n\n\n\nble_gatts_count_cfg\n\n\nAdjusts a host configuration object's settings to accommodate the specified service definition array.\n\n\n\n\n\n\nble_gatts_count_resources\n\n\nAccumulates counts of each resource type required by the specified service definition array.\n\n\n\n\n\n\nble_gatts_find_chr\n\n\nRetrieves the pair of attribute handles associated with a local GATT characteristic.\n\n\n\n\n\n\nble_gatts_find_dsc\n\n\nRetrieves the attribute handle associated with a local GATT descriptor.\n\n\n\n\n\n\nble_gatts_find_svc\n\n\nRetrieves the attribute handle associated with a local GATT service.\n\n\n\n\n\n\nble_gatts_register_svcs\n\n\nRegisters a set of services, characteristics, and descriptors to be accessed by GATT clients.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/ble_gatts/#nimble-host-gatt-server-reference",
- "text": "",
- "title": "NimBLE Host GATT Server Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/ble_gatts/#introduction",
- "text": "The Generic Attribute Profile (GATT) manages all activities involving services, characteristics, and descriptors. The server half of the GATT API handles registration and responding to GATT clients.",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/ble_gatts/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/ble_gatts/#definitions",
- "text": "BLE host GATT server definitions",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/ble_gatts/#functions",
- "text": "Function Description ble_gatts_add_svcs Queues a set of service definitions for registration. ble_gatts_count_cfg Adjusts a host configuration object's settings to accommodate the specified service definition array. ble_gatts_count_resources Accumulates counts of each resource type required by the specified service definition array. ble_gatts_find_chr Retrieves the pair of attribute handles associated with a local GATT characteristic. ble_gatts_find_dsc Retrieves the attribute handle associated with a local GATT descriptor. ble_gatts_find_svc Retrieves the attribute handle associated with a local GATT service. ble_gatts_register_svcs Registers a set of services, characteristics, and descriptors to be accessed by GATT clients.",
- "title": "Functions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/definitions/ble_gatts_defs/",
- "text": "GATT Server Definitions\n\n\ntypedef\n \nint\n \nble_gatt_access_fn\n(\nuint16_t\n \nconn_handle\n, \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nble_gatt_access_ctxt\n \n*ctxt\n, \nvoid\n \n*arg\n);\n\n\n\n\n\ntypedef\n \nuint16_t\n \nble_gatt_chr_flags\n;\n\n\n\n\n\nstruct\n \nble_gatt_chr_def\n {\n \n/**\n\n\n * Pointer to first element in a uint8_t[16]; use the BLE_UUID16 macro for\n\n\n * 16-bit UUIDs; NULL if there are no more characteristics in the service.\n\n\n */\n\n \nconst\n \nuint8_t\n \n*uuid128\n;\n\n \n/**\n\n\n * Callback that gets executed when this characteristic is read or\n\n\n * written.\n\n\n */\n\n \nble_gatt_access_fn\n \n*access_cb\n;\n\n \n/** Optional argument for callback. */\n\n \nvoid\n \n*arg\n;\n\n \n/**\n\n\n * Array of this characteristic\ns descriptors. NULL if no descriptors.\n\n\n * Do not include CCCD; it gets added automatically if this\n\n\n * characteristic\ns notify or indicate flag is set.\n\n\n */\n\n \nstruct\n \nble_gatt_dsc_def\n \n*descriptors\n;\n\n \n/** Specifies the set of permitted operations for this characteristic. */\n\n \nble_gatt_chr_flags\n \nflags\n;\n\n \n/** \n\n\n * At registration time, this is filled in with the characteristic\ns value\n\n\n * attribute handle.\n\n\n */\n\n \nuint16_t\n \n*\n \nconst\n \nval_handle\n;\n};\n\n\n\n\n\nstruct\n \nble_gatt_svc_def\n {\n \n/**\n\n\n * One of the following:\n\n\n * o BLE_GATT_SVC_TYPE_PRIMARY - primary service\n\n\n * o BLE_GATT_SVC_TYPE_SECONDARY - secondary service\n\n\n * o 0 - No more services in this array.\n\n\n */\n\n \nuint8_t\n \ntype\n;\n\n \n/**\n\n\n * Pointer to first element in a uint8_t[16]; use the BLE_UUID16 macro for\n\n\n * 16-bit UUIDs.\n\n\n */\n\n \nconst\n \nuint8_t\n \n*uuid128\n;\n\n \n/**\n\n\n * Array of pointers to other service definitions. These services are\n\n\n * reported as \nincluded services\n during service discovery. Terminate the\n\n\n * array with NULL.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n**includes\n;\n\n \n/**\n\n\n * Array of characteristic definitions corresponding to characteristics\n\n\n * belonging to this service.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_chr_def\n \n*characteristics\n;\n};\n\n\n\n\n\nstruct\n \nble_gatt_dsc_def\n {\n \n/**\n\n\n * The first element in a uint8_t[16]; use the BLE_UUID16 macro for 16-bit\n\n\n * UUIDs; NULL if there are no more descriptors in the characteristic.\n\n\n */\n\n \nuint8_t\n \n*uuid128\n;\n\n \n/** Specifies the set of permitted operations for this descriptor. */\n\n \nuint8_t\n \natt_flags\n;\n\n \n/** Callback that gets executed when the descriptor is read or written. */\n\n \nble_gatt_access_fn\n \n*access_cb\n;\n\n \n/** Optional argument for callback. */\n\n \nvoid\n \n*arg\n;\n};\n\n\n\n\n\n/**\n\n\n * Context for an access to a GATT characteristic or descriptor. When a client\n\n\n * reads or writes a locally registered characteristic or descriptor, an\n\n\n * instance of this struct gets passed to the application callback.\n\n\n */\n\n\nstruct\n \nble_gatt_access_ctxt\n {\n \n/**\n\n\n * Indicates the gatt operation being performed. This is equal to one of\n\n\n * the following values:\n\n\n * o BLE_GATT_ACCESS_OP_READ_CHR\n\n\n * o BLE_GATT_ACCESS_OP_WRITE_CHR\n\n\n * o BLE_GATT_ACCESS_OP_READ_DSC\n\n\n * o BLE_GATT_ACCESS_OP_WRITE_DSC\n\n\n */\n\n \nuint8_t\n \nop\n;\n\n \n/**\n\n\n * A container for the GATT access data.\n\n\n * o For reads: The application populates this with the value of the\n\n\n * characteristic or descriptor being read.\n\n\n * o For writes: This is already populated with the value being written\n\n\n * by the peer. If the application wishes to retain this mbuf for\n\n\n * later use, the access callback must set this pointer to NULL to\n\n\n * prevent the stack from freeing it.\n\n\n */\n\n \nstruct\n \nos_mbuf\n \n*om\n;\n\n \n/**\n\n\n * The GATT operation being performed dictates which field in this union is\n\n\n * valid. If a characteristic is being accessed, the chr field is valid.\n\n\n * Otherwise a descriptor is being accessed, in which case the dsc field\n\n\n * is valid.\n\n\n */\n\n \nunion\n {\n \n/**\n\n\n * The characteristic definition corresponding to the characteristic\n\n\n * being accessed. This is what the app registered at startup.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_chr_def\n \n*chr\n;\n\n \n/**\n\n\n * The descriptor definition corresponding to the descriptor being\n\n\n * accessed. This is what the app registered at startup.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_dsc_def\n \n*dsc\n;\n };\n};\n\n\n\n\n\n/**\n\n\n * Context passed to the registration callback; represents the GATT service,\n\n\n * characteristic, or descriptor being registered.\n\n\n */\n\n\nunion\n \nble_gatt_register_ctxt\n {\n \n/** Service; valid if op == BLE_GATT_REGISTER_OP_SVC. */\n\n \nstruct\n {\n \n/** The ATT handle of the service definition attribute. */\n\n \nuint16_t\n \nhandle\n;\n\n \n/**\n\n\n * The service definition representing the service being\n\n\n * registered.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n*svc_def\n;\n } \nsvc\n;\n\n \n/** Characteristic; valid if op == BLE_GATT_REGISTER_OP_CHR. */\n\n \nstruct\n {\n \n/** The ATT handle of the characteristic definition attribute. */\n\n \nuint16_t\n \ndef_handle\n;\n\n \n/** The ATT handle of the characteristic value attribute. */\n\n \nuint16_t\n \nval_handle\n;\n\n \n/**\n\n\n * The characteristic definition representing the characteristic being\n\n\n * registered.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_chr_def\n \n*chr_def\n;\n\n \n/**\n\n\n * The service definition corresponding to the characteristic\ns parent\n\n\n * service.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n*svc_def\n;\n } \nchr\n;\n\n \n/** Descriptor; valid if op == BLE_GATT_REGISTER_OP_DSC. */\n\n \nstruct\n {\n \n/** The ATT handle of the descriptor definition attribute. */\n\n \nuint16_t\n \nhandle\n;\n\n \n/**\n\n\n * The descriptor definition corresponding to the descriptor being\n\n\n * registered.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_dsc_def\n \n*dsc_def\n;\n\n \n/**\n\n\n * The characteristic definition corresponding to the descriptor\ns\n\n\n * parent characteristic.\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_chr_def\n \n*chr_def\n;\n\n \n/**\n\n\n * The service definition corresponding to the descriptor\ns grandparent\n\n\n * service\n\n\n */\n\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n*svc_def\n;\n } \ndsc\n;\n};\n\n\n\n\n\ntypedef\n \nvoid\n \nble_gatt_register_fn\n(\nuint8_t\n \nop\n,\n \nunion\n \nble_gatt_register_ctxt\n \n*ctxt\n,\n \nvoid\n \n*arg\n);\n\n\n\n\n\n/**\n\n\n * Contains counts of resources required by the GATT server. The contents of\n\n\n * this struct are generally used to populate a configuration struct before\n\n\n * the host is initialized.\n\n\n */\n\n\nstruct\n \nble_gatt_resources\n {\n \n/** Number of services. */\n\n \nuint16_t\n \nsvcs\n;\n\n \n/** Number of included services. */\n\n \nuint16_t\n \nincs\n;\n\n \n/** Number of characteristics. */\n\n \nuint16_t\n \nchrs\n;\n\n \n/** Number of descriptors. */\n\n \nuint16_t\n \ndscs\n;\n\n \n/**\n\n\n * Number of client characteristic configuration descriptors. Each of\n\n\n * these also contributes to the total descriptor count.\n\n\n */\n\n \nuint16_t\n \ncccds\n;\n\n \n/** Total number of ATT attributes. */\n\n \nuint16_t\n \nattrs\n;\n};",
- "title": "GATT server definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/definitions/ble_gatts_defs/#gatt-server-definitions",
- "text": "typedef int ble_gatt_access_fn ( uint16_t conn_handle , uint16_t attr_handle ,\n struct ble_gatt_access_ctxt *ctxt , void *arg ); typedef uint16_t ble_gatt_chr_flags ; struct ble_gatt_chr_def {\n /** * Pointer to first element in a uint8_t[16]; use the BLE_UUID16 macro for * 16-bit UUIDs; NULL if there are no more characteristics in the service. */ \n const uint8_t *uuid128 ;\n\n /** * Callback that gets executed when this characteristic is read or * written. */ \n ble_gatt_access_fn *access_cb ;\n\n /** Optional argument for callback. */ \n void *arg ;\n\n /** * Array of this characteristic s descriptors. NULL if no descriptors. * Do not include CCCD; it gets added automatically if this * characteristic s notify or indicate flag is set. */ \n struct ble_gatt_dsc_def *descriptors ;\n\n /** Specifies the set of permitted operations for this characteristic. */ \n ble_gatt_chr_flags flags ;\n\n /** * At registration time, this is filled in with the characteristic s value * attribute handle. */ \n uint16_t * const val_handle ;\n}; struct ble_gatt_svc_def {\n /** * One of the following: * o BLE_GATT_SVC_TYPE_PRIMARY - primary service * o BLE_GATT_SVC_TYPE_SECONDARY - secondary service * o 0 - No more services in this array. */ \n uint8_t type ;\n\n /** * Pointer to first element in a uint8_t[16]; use the BLE_UUID16 macro for * 16-bit UUIDs. */ \n const uint8_t *uuid128 ;\n\n /** * Array of pointers to other service definitions. These services are * reported as included services during service discovery. Terminate the * array with NULL. */ \n const struct ble_gatt_svc_def **includes ;\n\n /** * Array of characteristic definitions corresponding to characteristics * belonging to this service. */ \n const struct ble_gatt_chr_def *characteristics ;\n}; struct ble_gatt_dsc_def {\n /** * The first element in a uint8_t[16]; use the BLE_UUID16 macro for 16-bit * UUIDs; NULL if there are no more descriptors in the characteristic. */ \n uint8_t *uuid128 ;\n\n /** Specifies the set of permitted operations for this descriptor. */ \n uint8_t att_flags ;\n\n /** Callback that gets executed when the descriptor is read or written. */ \n ble_gatt_access_fn *access_cb ;\n\n /** Optional argument for callback. */ \n void *arg ;\n}; /** * Context for an access to a GATT characteristic or descriptor. When a client * reads or writes a locally registered characteristic or descriptor, an * instance of this struct gets passed to the application callback. */ struct ble_gatt_access_ctxt {\n /** * Indicates the gatt operation being performed. This is equal to one of * the following values: * o BLE_GATT_ACCESS_OP_READ_CHR * o BLE_GATT_ACCESS_OP_WRITE_CHR * o BLE_GATT_ACCESS_OP_READ_DSC * o BLE_GATT_ACCESS_OP_WRITE_DSC */ \n uint8_t op ;\n\n /** * A container for the GATT access data. * o For reads: The application populates this with the value of the * characteristic or descriptor being read. * o For writes: This is already populated with the value being written * by the peer. If the application wishes to retain this mbuf for * later use, the access callback must set this pointer to NULL to * prevent the stack from freeing it. */ \n struct os_mbuf *om ;\n\n /** * The GATT operation being performed dictates which field in this union is * valid. If a characteristic is being accessed, the chr field is valid. * Otherwise a descriptor is being accessed, in which case the dsc field * is valid. */ \n union {\n /** * The characteristic definition corresponding to the characteristic * being accessed. This is what the app registered at startup. */ \n const struct ble_gatt_chr_def *chr ;\n\n /** * The descriptor definition corresponding to the descriptor being * accessed. This is what the app registered at startup. */ \n const struct ble_gatt_dsc_def *dsc ;\n };\n}; /** * Context passed to the registration callback; represents the GATT service, * characteristic, or descriptor being registered. */ union ble_gatt_register_ctxt {\n /** Service; valid if op == BLE_GATT_REGISTER_OP_SVC. */ \n struct {\n /** The ATT handle of the service definition attribute. */ \n uint16_t handle ;\n\n /** * The service definition representing the service being * registered. */ \n const struct ble_gatt_svc_def *svc_def ;\n } svc ;\n\n /** Characteristic; valid if op == BLE_GATT_REGISTER_OP_CHR. */ \n struct {\n /** The ATT handle of the characteristic definition attribute. */ \n uint16_t def_handle ;\n\n /** The ATT handle of the characteristic value attribute. */ \n uint16_t val_handle ;\n\n /** * The characteristic definition representing the characteristic being * registered. */ \n const struct ble_gatt_chr_def *chr_def ;\n\n /** * The service definition corresponding to the characteristic s parent * service. */ \n const struct ble_gatt_svc_def *svc_def ;\n } chr ;\n\n /** Descriptor; valid if op == BLE_GATT_REGISTER_OP_DSC. */ \n struct {\n /** The ATT handle of the descriptor definition attribute. */ \n uint16_t handle ;\n\n /** * The descriptor definition corresponding to the descriptor being * registered. */ \n const struct ble_gatt_dsc_def *dsc_def ;\n\n /** * The characteristic definition corresponding to the descriptor s * parent characteristic. */ \n const struct ble_gatt_chr_def *chr_def ;\n\n /** * The service definition corresponding to the descriptor s grandparent * service */ \n const struct ble_gatt_svc_def *svc_def ;\n } dsc ;\n}; typedef void ble_gatt_register_fn ( uint8_t op ,\n union ble_gatt_register_ctxt *ctxt ,\n void *arg ); /** * Contains counts of resources required by the GATT server. The contents of * this struct are generally used to populate a configuration struct before * the host is initialized. */ struct ble_gatt_resources {\n /** Number of services. */ \n uint16_t svcs ;\n\n /** Number of included services. */ \n uint16_t incs ;\n\n /** Number of characteristics. */ \n uint16_t chrs ;\n\n /** Number of descriptors. */ \n uint16_t dscs ;\n\n /** * Number of client characteristic configuration descriptors. Each of * these also contributes to the total descriptor count. */ \n uint16_t cccds ;\n\n /** Total number of ATT attributes. */ \n uint16_t attrs ;\n};",
- "title": "GATT Server Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_cfg/",
- "text": "ble_gatts_count_cfg\n\n\nint\n\n\nble_gatts_count_cfg\n(\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n*defs\n,\n \nstruct\n \nble_hs_cfg\n \n*cfg\n\n)\n\n\n\n\n\nDescription\n\n\nAdjusts a host configuration object's settings to accommodate the specified service definition array. This function adds the counts to the appropriate fields in the supplied configuration object without clearing them first, so it can be called repeatedly with different inputs to calculate totals. Be sure to zero the GATT server settings prior to the first call to this function.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndefs\n\n\nThe service array containing the resource definitions to be counted.\n\n\n\n\n\n\ncfg\n\n\nThe resource counts are accumulated in this configuration object.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EINVAL\n\n\nThe svcs array contains an invalid resource definition.",
- "title": "ble_gatts_count_cfg"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_cfg/#ble95gatts95count95cfg",
- "text": "int ble_gatts_count_cfg (\n const struct ble_gatt_svc_def *defs ,\n struct ble_hs_cfg *cfg \n)",
- "title": "ble_gatts_count_cfg"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_cfg/#description",
- "text": "Adjusts a host configuration object's settings to accommodate the specified service definition array. This function adds the counts to the appropriate fields in the supplied configuration object without clearing them first, so it can be called repeatedly with different inputs to calculate totals. Be sure to zero the GATT server settings prior to the first call to this function.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_cfg/#parameters",
- "text": "Parameter Description defs The service array containing the resource definitions to be counted. cfg The resource counts are accumulated in this configuration object.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_cfg/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EINVAL The svcs array contains an invalid resource definition.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_resources/",
- "text": "ble_gatts_count_resources\n\n\nint\n\n\nble_gatts_count_resources\n(\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n*svcs\n,\n \nstruct\n \nble_gatt_resources\n \n*res\n\n)\n\n\n\n\n\nDescription\n\n\nAccumulates counts of each resource type required by the specified service definition array. This function is generally used to calculate some host configuration values prior to initialization. This function adds the counts to the appropriate fields in the supplied ble_gatt_resources object without clearing them first, so it can be called repeatedly with different inputs to calculate totals. Be sure to zero the resource struct prior to the first call to this function.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsvcs\n\n\nThe service array containing the resource definitions to be counted.\n\n\n\n\n\n\nres\n\n\nThe resource counts are accumulated in this struct.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EINVAL\n\n\nThe svcs array contains an invalid resource definition.",
- "title": "ble_gatts_count_resources"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_resources/#ble95gatts95count95resources",
- "text": "int ble_gatts_count_resources (\n const struct ble_gatt_svc_def *svcs ,\n struct ble_gatt_resources *res \n)",
- "title": "ble_gatts_count_resources"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_resources/#description",
- "text": "Accumulates counts of each resource type required by the specified service definition array. This function is generally used to calculate some host configuration values prior to initialization. This function adds the counts to the appropriate fields in the supplied ble_gatt_resources object without clearing them first, so it can be called repeatedly with different inputs to calculate totals. Be sure to zero the resource struct prior to the first call to this function.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_resources/#parameters",
- "text": "Parameter Description svcs The service array containing the resource definitions to be counted. res The resource counts are accumulated in this struct.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_count_resources/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EINVAL The svcs array contains an invalid resource definition.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr/",
- "text": "ble_gatts_find_chr\n\n\nint\n\n\nble_gatts_find_chr\n(\n \nconst\n \nvoid\n \n*svc_uuid128\n,\n \nconst\n \nvoid\n \n*chr_uuid128\n,\n \nuint16_t\n \n*out_def_handle\n,\n \nuint16_t\n \n*out_val_handle\n\n)\n\n\n\n\n\nDescription\n\n\nRetrieves the pair of attribute handles associated with a local GATT characteristic.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsvc_uuid128\n\n\nThe UUID of the parent service.\n\n\n\n\n\n\nchr_uuid128\n\n\nThe UUID of the characteristic to look up.\n\n\n\n\n\n\nout_def_handle\n\n\nOn success, populated with the handle of the characteristic definition attribute. Pass null if you don't need this value.\n\n\n\n\n\n\nout_val_handle\n\n\nOn success, populated with the handle of the characteristic value attribute. Pass null if you don't need this value.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOENT\n\n\nThe specified service or characteristic could not be found.",
- "title": "ble_gatts_find_chr"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr/#ble95gatts95find95chr",
- "text": "int ble_gatts_find_chr (\n const void *svc_uuid128 ,\n const void *chr_uuid128 ,\n uint16_t *out_def_handle ,\n uint16_t *out_val_handle \n)",
- "title": "ble_gatts_find_chr"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr/#description",
- "text": "Retrieves the pair of attribute handles associated with a local GATT characteristic.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr/#parameters",
- "text": "Parameter Description svc_uuid128 The UUID of the parent service. chr_uuid128 The UUID of the characteristic to look up. out_def_handle On success, populated with the handle of the characteristic definition attribute. Pass null if you don't need this value. out_val_handle On success, populated with the handle of the characteristic value attribute. Pass null if you don't need this value.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_chr/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOENT The specified service or characteristic could not be found.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs/",
- "text": "ble_gatts_register_svcs\n\n\nint\n\n\nble_gatts_register_svcs\n(\n \nconst\n \nstruct\n \nble_gatt_svc_def\n \n*svcs\n,\n \nble_gatt_register_fn\n \n*cb\n,\n \nvoid\n \n*cb_arg\n\n)\n\n\n\n\n\nDescription\n\n\nRegisters a set of services, characteristics, and descriptors to be accessed by GATT clients.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsvcs\n\n\nA table of the service definitions to be registered.\n\n\n\n\n\n\ncb\n\n\nThe function to call for each service, characteristic, and descriptor that gets registered.\n\n\n\n\n\n\ncb_arg\n\n\nThe optional argument to pass to the callback function.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOMEM\n\n\nRegistration failed due to resource exhaustion.\n\n\n\n\n\n\nBLE_HS_EINVAL\n\n\nThe service definition table contains an invalid element.",
- "title": "ble_gatts_register_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs/#ble95gatts95register95svcs",
- "text": "int ble_gatts_register_svcs (\n const struct ble_gatt_svc_def *svcs ,\n ble_gatt_register_fn *cb ,\n void *cb_arg \n)",
- "title": "ble_gatts_register_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs/#description",
- "text": "Registers a set of services, characteristics, and descriptors to be accessed by GATT clients.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs/#parameters",
- "text": "Parameter Description svcs A table of the service definitions to be registered. cb The function to call for each service, characteristic, and descriptor that gets registered. cb_arg The optional argument to pass to the callback function.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_register_svcs/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOMEM Registration failed due to resource exhaustion. BLE_HS_EINVAL The service definition table contains an invalid element.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_add_svcs/",
- "text": "ble_gatts_add_svcs\n\n\nint\n\n\nble_gatts_add_svcs\n(\nconst\n \nstruct\n \nble_gatt_svc_def\n \n*svcs\n)\n\n\n\n\n\nDescription\n\n\nQueues a set of service definitions for registration. All services queued in this manner get registered when ble_hs_init() is called.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsvcs\n\n\nAn array of service definitions to queue for registration. This array must be terminated with an entry whose 'type' equals 0.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOMEM\n\n\nHeap exhaustion.",
- "title": "ble_gatts_add_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_add_svcs/#ble95gatts95add95svcs",
- "text": "int ble_gatts_add_svcs ( const struct ble_gatt_svc_def *svcs )",
- "title": "ble_gatts_add_svcs"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_add_svcs/#description",
- "text": "Queues a set of service definitions for registration. All services queued in this manner get registered when ble_hs_init() is called.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_add_svcs/#parameters",
- "text": "Parameter Description svcs An array of service definitions to queue for registration. This array must be terminated with an entry whose 'type' equals 0.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_add_svcs/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOMEM Heap exhaustion.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc/",
- "text": "ble_gatts_find_svc\n\n\nint\n\n\nble_gatts_find_svc\n(\n \nconst\n \nvoid\n \n*uuid128\n,\n \nuint16_t\n \n*out_handle\n\n)\n\n\n\n\n\nDescription\n\n\nRetrieves the attribute handle associated with a local GATT service.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nuuid128\n\n\nThe UUID of the service to look up.\n\n\n\n\n\n\nout_handle\n\n\nOn success, populated with the handle of the service attribute. Pass null if you don't need this value.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOENT\n\n\nThe specified service could not be found.",
- "title": "ble_gatts_find_svc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc/#ble95gatts95find95svc",
- "text": "int ble_gatts_find_svc (\n const void *uuid128 ,\n uint16_t *out_handle \n)",
- "title": "ble_gatts_find_svc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc/#description",
- "text": "Retrieves the attribute handle associated with a local GATT service.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc/#parameters",
- "text": "Parameter Description uuid128 The UUID of the service to look up. out_handle On success, populated with the handle of the service attribute. Pass null if you don't need this value.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_svc/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOENT The specified service could not be found.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc/",
- "text": "ble_gatts_find_dsc\n\n\nint\n\n\nble_gatts_find_dsc\n(\n \nconst\n \nvoid\n \n*svc_uuid128\n,\n \nconst\n \nvoid\n \n*chr_uuid128\n,\n \nconst\n \nvoid\n \n*dsc_uuid128\n,\n \nuint16_t\n \n*out_handle\n\n)\n\n\n\n\n\nDescription\n\n\nRetrieves the attribute handle associated with a local GATT descriptor.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsvc_uuid128\n\n\nThe UUID of the grandparent service.\n\n\n\n\n\n\nchr_uuid128\n\n\nThe UUID of the parent characteristic.\n\n\n\n\n\n\ndsc_uuid128\n\n\nThe UUID of the descriptor ro look up.\n\n\n\n\n\n\nout_handle\n\n\nOn success, populated with the handle of the descripytor attribute. Pass null if you don't need this value.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_ENOENT\n\n\nThe specified service, characteristic, or descriptor could not be found.",
- "title": "ble_gatts_find_dsc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc/#ble95gatts95find95dsc",
- "text": "int ble_gatts_find_dsc (\n const void *svc_uuid128 ,\n const void *chr_uuid128 ,\n const void *dsc_uuid128 ,\n uint16_t *out_handle \n)",
- "title": "ble_gatts_find_dsc"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc/#description",
- "text": "Retrieves the attribute handle associated with a local GATT descriptor.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc/#parameters",
- "text": "Parameter Description svc_uuid128 The UUID of the grandparent service. chr_uuid128 The UUID of the parent characteristic. dsc_uuid128 The UUID of the descriptor ro look up. out_handle On success, populated with the handle of the descripytor attribute. Pass null if you don't need this value.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_gatts/functions/ble_gatts_find_dsc/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_ENOENT The specified service, characteristic, or descriptor could not be found.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/",
- "text": "NimBLE Host Identity Reference\n\n\nIntroduction\n\n\nThe identity API provides facilities for querying and configuring your device's addresses. BLE's addressing scheme is quite involved; the summary that follows is only a brief introduction.\n\n\nBLE defines four address types:\n\n\n\n\n\n\n\n\nType\n\n\nDescription\n\n\nIdentity?\n\n\nConfigured with\n\n\n\n\n\n\n\n\n\n\nPublic\n\n\nAddress assigned by manufacturer; the three most significant bytes form the manufacturer's OUI.\n\n\nYes\n\n\nN/A; read from controller at startup.\n\n\n\n\n\n\nStatic random\n\n\nRandomly generated address.\n\n\nYes\n\n\nble_hs_id_set_rnd()\n\n\n\n\n\n\nResolvable private (RPA)\n\n\nAddress randomly generated from an identity address and an identity resolving key (IRK).\n\n\nNo\n\n\nN/A; generated by controller periodically.\n\n\n\n\n\n\nNon-resolvable private (NRPA)\n\n\nRandomly generated address.\n\n\nNo\n\n\nble_hs_id_set_rnd()\n\n\n\n\n\n\n\n\nIdentity Addresses\n\n\nThe third column in the above table indicates the \nidentity\n property of each address type. An identity address never changes, and a device can be identified by one of its unique identity addresses.\n\n\nNon-identity addresses are used by devices supporting BLE privacy. A device using the privacy feature frequently changes its own address to a newly-generated non-identity address. By cycling its address, the device makes it impossible for eavesdroppers to track its location.\n\n\nA device can have up to two identity addresses at once: one public and one static random. As indicated in the above table, the public identity address cannot be configured; the static random identity address can be set by calling \nble_hs_id_set_rnd()\n.\n\n\nThe address type is selected on a per-GAP-procedure basis. Each time you initiate a GAP procedure, you indicate which address type the device should use for the duration of the procedure.\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nNone.\n\n\nFunctions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_hs_id_copy_addr\n\n\nRetrieves one of the device's identity addresses.\n\n\n\n\n\n\nble_hs_id_gen_rnd\n\n\nGenerates a new random address.\n\n\n\n\n\n\nble_hs_id_set_rnd\n\n\nSets the device's random address.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/#nimble-host-identity-reference",
- "text": "",
- "title": "NimBLE Host Identity Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/#introduction",
- "text": "The identity API provides facilities for querying and configuring your device's addresses. BLE's addressing scheme is quite involved; the summary that follows is only a brief introduction. BLE defines four address types: Type Description Identity? Configured with Public Address assigned by manufacturer; the three most significant bytes form the manufacturer's OUI. Yes N/A; read from controller at startup. Static random Randomly generated address. Yes ble_hs_id_set_rnd() Resolvable private (RPA) Address randomly generated from an identity address and an identity resolving key (IRK). No N/A; generated by controller periodically. Non-resolvable private (NRPA) Randomly generated address. No ble_hs_id_set_rnd()",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/#identity-addresses",
- "text": "The third column in the above table indicates the identity property of each address type. An identity address never changes, and a device can be identified by one of its unique identity addresses. Non-identity addresses are used by devices supporting BLE privacy. A device using the privacy feature frequently changes its own address to a newly-generated non-identity address. By cycling its address, the device makes it impossible for eavesdroppers to track its location. A device can have up to two identity addresses at once: one public and one static random. As indicated in the above table, the public identity address cannot be configured; the static random identity address can be set by calling ble_hs_id_set_rnd() . The address type is selected on a per-GAP-procedure basis. Each time you initiate a GAP procedure, you indicate which address type the device should use for the duration of the procedure.",
- "title": "Identity Addresses"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/#definitions",
- "text": "None.",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/ble_hs_id/#functions",
- "text": "Function Description ble_hs_id_copy_addr Retrieves one of the device's identity addresses. ble_hs_id_gen_rnd Generates a new random address. ble_hs_id_set_rnd Sets the device's random address.",
- "title": "Functions"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr/",
- "text": "ble_hs_id_copy_addr\n\n\nint\n\n\nble_hs_id_copy_addr\n(\n \nuint8_t\n \nid_addr_type\n,\n \nuint8_t\n \n*out_id_addr\n,\n \nint\n \n*out_is_nrpa\n\n)\n\n\n\n\n\nDescription\n\n\nRetrieves one of the device's identity addresses. The device can have two identity addresses: one public and one random. The id_addr_type argument specifies which of these two addresses to retrieve.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nid_addr_type\n\n\nThe type of identity address to retrieve. Valid values are: \nBLE_ADDR_TYPE_PUBLIC\n \nBLE_ADDR_TYPE_RANDOM\n\n\n\n\n\n\nout_id_addr\n\n\nOn success, the requested identity address is copied into this buffer. The buffer must be at least six bytes in size.\n\n\n\n\n\n\nout_is_nrpa\n\n\nOn success, the pointed-to value indicates whether the retrieved address is a non-resolvable private address.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EINVAL\n\n\nAn invalid address type was specified.\n\n\n\n\n\n\nBLE_HS_ENOADDR\n\n\nThe device does not have an identity address of the requested type.\n\n\n\n\n\n\nother\n\n\nOther ble host core code on error.",
- "title": "ble_hs_id_copy_addr"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr/#ble95hs95id95copy95addr",
- "text": "int ble_hs_id_copy_addr (\n uint8_t id_addr_type ,\n uint8_t *out_id_addr ,\n int *out_is_nrpa \n)",
- "title": "ble_hs_id_copy_addr"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr/#description",
- "text": "Retrieves one of the device's identity addresses. The device can have two identity addresses: one public and one random. The id_addr_type argument specifies which of these two addresses to retrieve.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr/#parameters",
- "text": "Parameter Description id_addr_type The type of identity address to retrieve. Valid values are: BLE_ADDR_TYPE_PUBLIC BLE_ADDR_TYPE_RANDOM out_id_addr On success, the requested identity address is copied into this buffer. The buffer must be at least six bytes in size. out_is_nrpa On success, the pointed-to value indicates whether the retrieved address is a non-resolvable private address.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_copy_addr/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EINVAL An invalid address type was specified. BLE_HS_ENOADDR The device does not have an identity address of the requested type. other Other ble host core code on error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd/",
- "text": "ble_hs_id_gen_rnd\n\n\nint\n\n\nble_hs_id_gen_rnd\n(\n \nint\n \nnrpa\n,\n \nuint8_t\n \n*out_addr\n\n)\n\n\n\n\n\nDescription\n\n\nGenerates a new random address. This function does not configure the device with the new address; the caller can use the address in subsequent operations.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nnrpa\n\n\nThe type of random address to generate: 0: static 1: non-resolvable private\n\n\n\n\n\n\nout_addr\n\n\nOn success, the generated address gets written here.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_hs_id_gen_rnd"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd/#ble95hs95id95gen95rnd",
- "text": "int ble_hs_id_gen_rnd (\n int nrpa ,\n uint8_t *out_addr \n)",
- "title": "ble_hs_id_gen_rnd"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd/#description",
- "text": "Generates a new random address. This function does not configure the device with the new address; the caller can use the address in subsequent operations.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd/#parameters",
- "text": "Parameter Description nrpa The type of random address to generate: 0: static 1: non-resolvable private out_addr On success, the generated address gets written here.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd/",
- "text": "ble_hs_id_set_rnd\n\n\nint\n\n\nble_hs_id_set_rnd\n(\nconst\n \nuint8_t\n \n*rnd_addr\n)\n\n\n\n\n\nDescription\n\n\nSets the device's random address. The address type (static vs. non-resolvable private) is inferred from the most-significant byte of the address. The address is specified in host byte order (little-endian!).\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nrnd_addr\n\n\nThe random address to set.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_hs_id_set_rnd"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd/#ble95hs95id95set95rnd",
- "text": "int ble_hs_id_set_rnd ( const uint8_t *rnd_addr )",
- "title": "ble_hs_id_set_rnd"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd/#description",
- "text": "Sets the device's random address. The address type (static vs. non-resolvable private) is inferred from the most-significant byte of the address. The address is specified in host byte order (little-endian!).",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd/#parameters",
- "text": "Parameter Description rnd_addr The random address to set.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd/#returned-values",
- "text": "Value Condition 0 Success. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/ble_att/",
- "text": "NimBLE Host ATT Client Reference\n\n\nIntroduction\n\n\nThe Attribute Protocol (ATT) is a mid-level protocol that all BLE devices use to exchange data. Data is exchanged when an ATT client reads or writes an attribute belonging to an ATT server. Any device that needs to send or receive data must support both the client and server functionality of the ATT protocol. The only devices which do not support ATT are the most basic ones: broadcasters and observers (i.e., beaconing devices and listening devices).\n\n\nMost ATT functionality is not interesting to an application. Rather than use ATT directly, an application uses the higher level GATT profile, which sits directly above ATT in the host. NimBLE exposes the few bits of ATT functionality which are not encompassed by higher level GATT functions. This section documents the ATT functionality that the NimBLE host exposes to the application.\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nNone.\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_att_mtu\n\n\nRetrieves the ATT MTU of the specified connection.\n\n\n\n\n\n\nble_att_set_preferred_mtu\n\n\nSets the preferred ATT MTU; the device will indicate this value in all subseqeunt ATT MTU exchanges.\n\n\n\n\n\n\nble_att_svr_read_local\n\n\nReads a locally registered attribute.\n\n\n\n\n\n\nble_att_svr_write_local\n\n\nWrites a locally registered attribute.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/ble_att/#nimble-host-att-client-reference",
- "text": "",
- "title": "NimBLE Host ATT Client Reference"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/ble_att/#introduction",
- "text": "The Attribute Protocol (ATT) is a mid-level protocol that all BLE devices use to exchange data. Data is exchanged when an ATT client reads or writes an attribute belonging to an ATT server. Any device that needs to send or receive data must support both the client and server functionality of the ATT protocol. The only devices which do not support ATT are the most basic ones: broadcasters and observers (i.e., beaconing devices and listening devices). Most ATT functionality is not interesting to an application. Rather than use ATT directly, an application uses the higher level GATT profile, which sits directly above ATT in the host. NimBLE exposes the few bits of ATT functionality which are not encompassed by higher level GATT functions. This section documents the ATT functionality that the NimBLE host exposes to the application.",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/ble_att/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/ble_att/#definitions",
- "text": "None. Function Description ble_att_mtu Retrieves the ATT MTU of the specified connection. ble_att_set_preferred_mtu Sets the preferred ATT MTU; the device will indicate this value in all subseqeunt ATT MTU exchanges. ble_att_svr_read_local Reads a locally registered attribute. ble_att_svr_write_local Writes a locally registered attribute.",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_mtu/",
- "text": "ble_att_mtu\n\n\nuint16_t\n\n\nble_att_mtu\n(\nuint16_t\n \nconn_handle\n)\n\n\n\n\n\nDescription\n\n\nRetrieves the ATT MTU of the specified connection. If an MTU exchange for this connection has occurred, the MTU is the lower of the two peers' preferred values. Otherwise, the MTU is the default value of 23.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nconn_handle\n\n\nThe handle of the connection to query.\n\n\n\n\n\n\n\n\nReturned values\n\n\nThe specified connection's ATT MTU.",
- "title": "ble_att_mtu"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_mtu/#ble95att95mtu",
- "text": "uint16_t ble_att_mtu ( uint16_t conn_handle )",
- "title": "ble_att_mtu"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_mtu/#description",
- "text": "Retrieves the ATT MTU of the specified connection. If an MTU exchange for this connection has occurred, the MTU is the lower of the two peers' preferred values. Otherwise, the MTU is the default value of 23.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_mtu/#parameters",
- "text": "Parameter Description conn_handle The handle of the connection to query.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_mtu/#returned-values",
- "text": "The specified connection's ATT MTU.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/",
- "text": "ble_att_set_preferred_mtu\n\n\nint\n\n\nble_att_set_preferred_mtu\n(\nuint16_t\n \nmtu\n)\n\n\n\n\n\nDescription\n\n\nSets the preferred ATT MTU; the device will indicate this value in all subseqeunt ATT MTU exchanges. The ATT MTU of a connection is equal to the lower of the two peers' preferred MTU values. The ATT MTU is what dictates the maximum size of any message sent during a GATT procedure. The specified MTU must be within the following range: [23, BLE_ATT_MTU_MAX]. 23 is a minimum imposed by the Bluetooth specification; BLE_ATT_MTU_MAX is a NimBLE compile-time setting.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nmtu\n\n\nThe preferred ATT MTU.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EINVAL\n\n\nThe specifeid value is not within the allowed range.",
- "title": "ble_att_set_preferred_mtu"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/#ble95att95set95preferred95mtu",
- "text": "int ble_att_set_preferred_mtu ( uint16_t mtu )",
- "title": "ble_att_set_preferred_mtu"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/#description",
- "text": "Sets the preferred ATT MTU; the device will indicate this value in all subseqeunt ATT MTU exchanges. The ATT MTU of a connection is equal to the lower of the two peers' preferred MTU values. The ATT MTU is what dictates the maximum size of any message sent during a GATT procedure. The specified MTU must be within the following range: [23, BLE_ATT_MTU_MAX]. 23 is a minimum imposed by the Bluetooth specification; BLE_ATT_MTU_MAX is a NimBLE compile-time setting.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/#parameters",
- "text": "Parameter Description mtu The preferred ATT MTU.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EINVAL The specifeid value is not within the allowed range.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/",
- "text": "ble_att_svr_read_local\n\n\nint\n\n\nble_att_svr_read_local\n(\n \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nos_mbuf\n \n**out_om\n\n)\n\n\n\n\n\nDescription\n\n\nReads a locally registered attribute. If the specified attribute handle coresponds to a GATT characteristic value or descriptor, the read is performed by calling the registered GATT access callback.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nattr_handle\n\n\nThe 16-bit handle of the attribute to read.\n\n\n\n\n\n\nout_om\n\n\nOn success, this is made to point to a newly-allocated mbuf containing the attribute data read.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nATT return code\n\n\nThe attribute access callback reports failure.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_att_svr_read_local"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/#ble95att95svr95read95local",
- "text": "int ble_att_svr_read_local (\n uint16_t attr_handle ,\n struct os_mbuf **out_om \n)",
- "title": "ble_att_svr_read_local"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/#description",
- "text": "Reads a locally registered attribute. If the specified attribute handle coresponds to a GATT characteristic value or descriptor, the read is performed by calling the registered GATT access callback.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/#parameters",
- "text": "Parameter Description attr_handle The 16-bit handle of the attribute to read. out_om On success, this is made to point to a newly-allocated mbuf containing the attribute data read.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/#returned-values",
- "text": "Value Condition 0 Success. ATT return code The attribute access callback reports failure. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/",
- "text": "ble_att_svr_write_local\n\n\nint\n\n\nble_att_svr_write_local\n(\n \nuint16_t\n \nattr_handle\n,\n \nstruct\n \nos_mbuf\n \n*om\n\n)\n\n\n\n\n\nDescription\n\n\nWrites a locally registered attribute. This function consumes the supplied mbuf regardless of the outcome. If the specified attribute handle coresponds to a GATT characteristic value or descriptor, the write is performed by calling the registered GATT access callback.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nattr_handle\n\n\nThe 16-bit handle of the attribute to write.\n\n\n\n\n\n\nom\n\n\nThe value to write to the attribute.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nATT return code\n\n\nThe attribute access callback reports failure.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_att_svr_write_local"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/#ble95att95svr95write95local",
- "text": "int ble_att_svr_write_local (\n uint16_t attr_handle ,\n struct os_mbuf *om \n)",
- "title": "ble_att_svr_write_local"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/#description",
- "text": "Writes a locally registered attribute. This function consumes the supplied mbuf regardless of the outcome. If the specified attribute handle coresponds to a GATT characteristic value or descriptor, the write is performed by calling the registered GATT access callback.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/#parameters",
- "text": "Parameter Description attr_handle The 16-bit handle of the attribute to write. om The value to write to the attribute.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/#returned-values",
- "text": "Value Condition 0 Success. ATT return code The attribute access callback reports failure. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/other/",
- "text": "NimBLE Host Other Reference\n\n\nIntroduction\n\n\nThis section is a reference on miscellaneous parts of the NimBLE host which don't fit anywhere else!\n\n\nHeader\n\n\n#include\n \nhost/ble_hs.h\n\n\n\n\n\n\nDefinitions\n\n\nNone.\n\n\nFunctions\n\n\n\n\n\n\n\n\nFunction\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nble_eddystone_set_adv_data_uid\n\n\nConfigures the device to advertise eddystone UID beacons.\n\n\n\n\n\n\nble_eddystone_set_adv_data_url\n\n\nConfigures the device to advertise eddystone URL beacons.\n\n\n\n\n\n\nble_hs_mbuf_att_pkt\n\n\nAllocates an mbuf suitable for an ATT command packet.\n\n\n\n\n\n\nble_hs_mbuf_from_flat\n\n\nAllocates a an mbuf and fills it with the contents of the specified flat buffer.\n\n\n\n\n\n\nble_hs_mbuf_to_flat\n\n\nCopies the contents of an mbuf into the specified flat buffer.\n\n\n\n\n\n\nble_ibeacon_set_adv_data\n\n\nConfigures the device to advertise iBeacons.\n\n\n\n\n\n\nble_uuid_128_to_16\n\n\nAttempts to convert the supplied 128-bit UUID into its shortened 16-bit form.\n\n\n\n\n\n\nble_uuid_16_to_128\n\n\nExpands a 16-bit UUID into its 128-bit form.",
- "title": "toc"
- },
- {
- "location": "/network/ble/ble_hs/other/other/#nimble-host-other-reference",
- "text": "",
- "title": "NimBLE Host Other Reference"
- },
- {
- "location": "/network/ble/ble_hs/other/other/#introduction",
- "text": "This section is a reference on miscellaneous parts of the NimBLE host which don't fit anywhere else!",
- "title": "Introduction"
- },
- {
- "location": "/network/ble/ble_hs/other/other/#header",
- "text": "#include host/ble_hs.h",
- "title": "Header"
- },
- {
- "location": "/network/ble/ble_hs/other/other/#definitions",
- "text": "None.",
- "title": "Definitions"
- },
- {
- "location": "/network/ble/ble_hs/other/other/#functions",
- "text": "Function Description ble_eddystone_set_adv_data_uid Configures the device to advertise eddystone UID beacons. ble_eddystone_set_adv_data_url Configures the device to advertise eddystone URL beacons. ble_hs_mbuf_att_pkt Allocates an mbuf suitable for an ATT command packet. ble_hs_mbuf_from_flat Allocates a an mbuf and fills it with the contents of the specified flat buffer. ble_hs_mbuf_to_flat Copies the contents of an mbuf into the specified flat buffer. ble_ibeacon_set_adv_data Configures the device to advertise iBeacons. ble_uuid_128_to_16 Attempts to convert the supplied 128-bit UUID into its shortened 16-bit form. ble_uuid_16_to_128 Expands a 16-bit UUID into its 128-bit form.",
- "title": "Functions"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_uid/",
- "text": "ble_eddystone_set_adv_data_uid\n\n\nint\n\n\nble_eddystone_set_adv_data_uid\n(\n \nstruct\n \nble_hs_adv_fields\n \n*adv_fields\n,\n \nvoid\n \n*uid\n\n)\n\n\n\n\n\nDescription\n\n\nConfigures the device to advertise eddystone UID beacons.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nadv_fields\n\n\nThe base advertisement fields to transform into an eddystone beacon. All configured fields are preserved; you probably want to clear this struct before calling this function.\n\n\n\n\n\n\nuid\n\n\nThe 16-byte UID to advertise.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EBUSY\n\n\nAdvertising is in progress.\n\n\n\n\n\n\nBLE_HS_EMSGSIZE\n\n\nThe specified data is too large to fit in an advertisement.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_eddystone_set_adv_data_uid"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_uid/#ble95eddystone95set95adv95data95uid",
- "text": "int ble_eddystone_set_adv_data_uid (\n struct ble_hs_adv_fields *adv_fields ,\n void *uid \n)",
- "title": "ble_eddystone_set_adv_data_uid"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_uid/#description",
- "text": "Configures the device to advertise eddystone UID beacons.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_uid/#parameters",
- "text": "Parameter Description adv_fields The base advertisement fields to transform into an eddystone beacon. All configured fields are preserved; you probably want to clear this struct before calling this function. uid The 16-byte UID to advertise.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_uid/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EBUSY Advertising is in progress. BLE_HS_EMSGSIZE The specified data is too large to fit in an advertisement. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_url/",
- "text": "ble_eddystone_set_adv_data_url\n\n\nint\n\n\nble_eddystone_set_adv_data_url\n(\n \nstruct\n \nble_hs_adv_fields\n \n*adv_fields\n,\n \nuint8_t\n \nurl_scheme\n,\n \nchar\n \n*url_body\n,\n \nuint8_t\n \nurl_body_len\n,\n \nuint8_t\n \nurl_suffix\n\n)\n\n\n\n\n\nDescription\n\n\nConfigures the device to advertise eddystone URL beacons.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nadv_fields\n\n\nThe base advertisement fields to transform into an eddystone beacon. All configured fields are preserved; you probably want to clear this struct before calling this function.\n\n\n\n\n\n\nurl_scheme\n\n\nThe prefix of the URL; one of the BLE_EDDYSTONE_URL_SCHEME values.\n\n\n\n\n\n\nurl_body\n\n\nThe middle of the URL. Don't include the suffix if there is a suitable suffix code.\n\n\n\n\n\n\nurl_body_len\n\n\nThe string length of the url_body argument.\n\n\n\n\n\n\nurl_suffix\n\n\nThe suffix of the URL; one of the BLE_EDDYSTONE_URL_SUFFIX values; use BLE_EDDYSTONE_URL_SUFFIX_NONE if the suffix is embedded in the body argument.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EBUSY\n\n\nAdvertising is in progress.\n\n\n\n\n\n\nBLE_HS_EMSGSIZE\n\n\nThe specified data is too large to fit in an advertisement.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_eddystone_set_adv_data_url"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_url/#ble95eddystone95set95adv95data95url",
- "text": "int ble_eddystone_set_adv_data_url (\n struct ble_hs_adv_fields *adv_fields ,\n uint8_t url_scheme ,\n char *url_body ,\n uint8_t url_body_len ,\n uint8_t url_suffix \n)",
- "title": "ble_eddystone_set_adv_data_url"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_url/#description",
- "text": "Configures the device to advertise eddystone URL beacons.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_url/#parameters",
- "text": "Parameter Description adv_fields The base advertisement fields to transform into an eddystone beacon. All configured fields are preserved; you probably want to clear this struct before calling this function. url_scheme The prefix of the URL; one of the BLE_EDDYSTONE_URL_SCHEME values. url_body The middle of the URL. Don't include the suffix if there is a suitable suffix code. url_body_len The string length of the url_body argument. url_suffix The suffix of the URL; one of the BLE_EDDYSTONE_URL_SUFFIX values; use BLE_EDDYSTONE_URL_SUFFIX_NONE if the suffix is embedded in the body argument.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_eddystone_set_adv_data_url/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EBUSY Advertising is in progress. BLE_HS_EMSGSIZE The specified data is too large to fit in an advertisement. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_att_pkt/",
- "text": "ble_hs_mbuf_att_pkt\n\n\nstruct\n \nos_mbuf\n \n*\n\n\nble_hs_mbuf_att_pkt\n(\nvoid\n)\n\n\n\n\n\nDescription\n\n\nAllocates an mbuf suitable for an ATT command packet. The resulting packet has sufficient leading space for: o ACM data header o L2CAP B-frame header o Largest ATT command base (prepare write request / response).\n\n\nParameters\n\n\nNone\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\nAn empty mbuf\n\n\nSuccess.\n\n\n\n\n\n\nnull\n\n\nMemory exhaustion.",
- "title": "ble_hs_mbuf_att_pkt"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_att_pkt/#ble95hs95mbuf95att95pkt",
- "text": "struct os_mbuf * ble_hs_mbuf_att_pkt ( void )",
- "title": "ble_hs_mbuf_att_pkt"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_att_pkt/#description",
- "text": "Allocates an mbuf suitable for an ATT command packet. The resulting packet has sufficient leading space for: o ACM data header o L2CAP B-frame header o Largest ATT command base (prepare write request / response).",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_att_pkt/#parameters",
- "text": "None",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_att_pkt/#returned-values",
- "text": "Value Condition An empty mbuf Success. null Memory exhaustion.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_from_flat/",
- "text": "ble_hs_mbuf_from_flat\n\n\nstruct\n \nos_mbuf\n \n*\n\n\nble_hs_mbuf_from_flat\n(\n \nconst\n \nvoid\n \n*buf\n,\n \nuint16_t\n \nlen\n\n)\n\n\n\n\n\nDescription\n\n\nAllocates a an mbuf and fills it with the contents of the specified flat buffer.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nbuf\n\n\nThe flat buffer to copy from.\n\n\n\n\n\n\nlen\n\n\nThe length of the flat buffer.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\nA newly-allocated mbuf\n\n\nSuccess.\n\n\n\n\n\n\nNULL\n\n\nMemory exhaustion.",
- "title": "ble_hs_mbuf_from_flat"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_from_flat/#ble95hs95mbuf95from95flat",
- "text": "struct os_mbuf * ble_hs_mbuf_from_flat (\n const void *buf ,\n uint16_t len \n)",
- "title": "ble_hs_mbuf_from_flat"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_from_flat/#description",
- "text": "Allocates a an mbuf and fills it with the contents of the specified flat buffer.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_from_flat/#parameters",
- "text": "Parameter Description buf The flat buffer to copy from. len The length of the flat buffer.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_from_flat/#returned-values",
- "text": "Value Condition A newly-allocated mbuf Success. NULL Memory exhaustion.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_to_flat/",
- "text": "ble_hs_mbuf_to_flat\n\n\nint\n\n\nble_hs_mbuf_to_flat\n(\n \nconst\n \nstruct\n \nos_mbuf\n \n*om\n,\n \nvoid\n \n*flat\n,\n \nuint16_t\n \nmax_len\n,\n \nuint16_t\n \n*out_copy_len\n\n)\n\n\n\n\n\nDescription\n\n\nCopies the contents of an mbuf into the specified flat buffer. If the flat buffer is too small to contain the mbuf's contents, it is filled to capacity and BLE_HS_EMSGSIZE is returned.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nom\n\n\nThe mbuf to copy from.\n\n\n\n\n\n\nflat\n\n\nThe destination flat buffer.\n\n\n\n\n\n\nmax_len\n\n\nThe size of the flat buffer.\n\n\n\n\n\n\nout_copy_len\n\n\nThe number of bytes actually copied gets written here.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EMSGSIZE\n\n\nThe flat buffer is too small to contain the mbuf's contents.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_hs_mbuf_to_flat"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_to_flat/#ble95hs95mbuf95to95flat",
- "text": "int ble_hs_mbuf_to_flat (\n const struct os_mbuf *om ,\n void *flat ,\n uint16_t max_len ,\n uint16_t *out_copy_len \n)",
- "title": "ble_hs_mbuf_to_flat"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_to_flat/#description",
- "text": "Copies the contents of an mbuf into the specified flat buffer. If the flat buffer is too small to contain the mbuf's contents, it is filled to capacity and BLE_HS_EMSGSIZE is returned.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_to_flat/#parameters",
- "text": "Parameter Description om The mbuf to copy from. flat The destination flat buffer. max_len The size of the flat buffer. out_copy_len The number of bytes actually copied gets written here.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_hs_mbuf_to_flat/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EMSGSIZE The flat buffer is too small to contain the mbuf's contents. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_ibeacon_set_adv_data/",
- "text": "ble_ibeacon_set_adv_data\n\n\nint\n\n\nble_ibeacon_set_adv_data\n(\n \nvoid\n \n*uuid128\n,\n \nuint16_t\n \nmajor\n,\n \nuint16_t\n \nminor\n\n)\n\n\n\n\n\nDescription\n\n\nConfigures the device to advertise iBeacons.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nuuid\n\n\nThe 128-bit UUID to advertise.\n\n\n\n\n\n\nmajor\n\n\nThe major version number to include in iBeacons.\n\n\n\n\n\n\nminor\n\n\nThe minor version number to include in iBeacons.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EBUSY\n\n\nAdvertising is in progress.\n\n\n\n\n\n\nCore return code\n\n\nUnexpected error.",
- "title": "ble_ibeacon_set_adv_data"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_ibeacon_set_adv_data/#ble95ibeacon95set95adv95data",
- "text": "int ble_ibeacon_set_adv_data (\n void *uuid128 ,\n uint16_t major ,\n uint16_t minor \n)",
- "title": "ble_ibeacon_set_adv_data"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_ibeacon_set_adv_data/#description",
- "text": "Configures the device to advertise iBeacons.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_ibeacon_set_adv_data/#parameters",
- "text": "Parameter Description uuid The 128-bit UUID to advertise. major The major version number to include in iBeacons. minor The minor version number to include in iBeacons.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_ibeacon_set_adv_data/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EBUSY Advertising is in progress. Core return code Unexpected error.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_128_to_16/",
- "text": "ble_uuid_128_to_16\n\n\nuint16_t\n\n\nble_uuid_128_to_16\n(\nconst\n \nvoid\n \n*uuid128\n)\n\n\n\n\n\nDescription\n\n\nAttempts to convert the supplied 128-bit UUID into its shortened 16-bit form.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nuuid128\n\n\nThe 128-bit UUID to attempt to convert. This must point to 16 contiguous bytes.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\nA positive 16-bit unsigned integer\n\n\nSuccess.\n\n\n\n\n\n\n0\n\n\nThe uuid cannot be represented in 16 bits.",
- "title": "ble_uuid_128_to_16"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_128_to_16/#ble95uuid9512895to9516",
- "text": "uint16_t ble_uuid_128_to_16 ( const void *uuid128 )",
- "title": "ble_uuid_128_to_16"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_128_to_16/#description",
- "text": "Attempts to convert the supplied 128-bit UUID into its shortened 16-bit form.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_128_to_16/#parameters",
- "text": "Parameter Description uuid128 The 128-bit UUID to attempt to convert. This must point to 16 contiguous bytes.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_128_to_16/#returned-values",
- "text": "Value Condition A positive 16-bit unsigned integer Success. 0 The uuid cannot be represented in 16 bits.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_16_to_128/",
- "text": "ble_uuid_16_to_128\n\n\nint\n\n\nble_uuid_16_to_128\n(\n \nuint16_t\n \nuuid16\n,\n \nvoid\n \n*out_uuid128\n\n)\n\n\n\n\n\nDescription\n\n\nExpands a 16-bit UUID into its 128-bit form.\n\n\nParameters\n\n\n\n\n\n\n\n\nParameter\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nuuid16\n\n\nThe 16-bit UUID to convert.\n\n\n\n\n\n\nout_uuid128\n\n\nOn success, the resulting 128-bit UUID gets written here.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n\n\n\n\nValue\n\n\nCondition\n\n\n\n\n\n\n\n\n\n\n0\n\n\nSuccess.\n\n\n\n\n\n\nBLE_HS_EINVAL\n\n\nUuid16 is not a valid 16-bit uuid.",
- "title": "ble_uuid_16_to_128"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_16_to_128/#ble95uuid951695to95128",
- "text": "int ble_uuid_16_to_128 (\n uint16_t uuid16 ,\n void *out_uuid128 \n)",
- "title": "ble_uuid_16_to_128"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_16_to_128/#description",
- "text": "Expands a 16-bit UUID into its 128-bit form.",
- "title": "Description"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_16_to_128/#parameters",
- "text": "Parameter Description uuid16 The 16-bit UUID to convert. out_uuid128 On success, the resulting 128-bit UUID gets written here.",
- "title": "Parameters"
- },
- {
- "location": "/network/ble/ble_hs/other/functions/ble_uuid_16_to_128/#returned-values",
- "text": "Value Condition 0 Success. BLE_HS_EINVAL Uuid16 is not a valid 16-bit uuid.",
- "title": "Returned values"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/",
- "text": "API for bletiny app\n\n\n\"bletiny\" is one of the sample applications that come with Mynewt. It is a simple shell application which provides a basic interface to the host-side of the BLE stack. \"bletiny\" includes all the possible roles (Central/Peripheral) and they may be run simultaneously. You can run bletiny on a board and issue commands that make it behave as a central or a peripheral with different peers. \n\n\nHighlighted below are some of the ways you can use the API to establish connections and discover services and characteristics from peer devices. For descriptions of the full API, go to the next sections on \nGAP in bletiny\n and \nGATT in bletiny\n.\n\n\nAll bletiny commands are prefixed with \nb\n. This prefix distinguished bletiny commands from other shell commands that are implemented by other Mynewt packages.\n\n\n\n\nSet device address.\n\n\nOn startup, bletiny has the following identity address configuration:\n\n\n\n\nPublic address: \n0a:0b:0c:0d:0e:0f\n\n\nRandom address: None\n\n\n\n\nThe below \nset\n commands can be used to change the address configuration:\n\n\nb set addr_type=public addr=\ndevice-address\n\nb set addr_type=random addr=\ndevice-address\n\n\n\n\n\n\nFor example:\n\n\nb set addr_type=public addr=01:02:03:04:05:06\nb set addr_type=random addr=c1:aa:bb:cc:dd:ee\n\n\n\n\n\nThe address configuration can be viewed with the \nb show addr\n command, as follows:\n\n\nb show addr\npublic_id_addr=01:02:03:04:05:06 random_id_addr=c1:aa:bb:cc:dd:ee\n\n\n\n\n\n\n\nInitiate a direct connection to a device\n\n\nIn this case, your board is acting as a central and initiating a connection with another BLE device. The example assumes you know the address of the peer, either by scanning for available peers or because you have set up the peer yourself.\n\n\nb conn own_addr_type=public peer_addr_type=public peer_addr=d4:f5:13:53:d2:43\n\nconnection established; handle=1 our_ota_addr_type=0 our_ota_addr=0a:0b:0c:0d:0e:0f out_id_addr_type=0 our_id_addr=0a:0b:0c:0d:0e:0f peer_addr_type=0 peer_addr=43:d2:53:13:f5:d4 conn_itvl=40 conn_latency=0 supervision_timeout=256 encrypted=0 authenticated=0 bonded=0\n\n\n\n\n\nThe \nhandle=1\n in the output indicates that it is connection-1.\n\n\n\n\nConfigure advertisements to include device name\n\n\nIn this case, your board is acting as a peripheral. \n\n\nb set adv_data name=\nyour-device-name\n\n\n\n\n\n\n\n\nBegin sending undirected general advertisements\n\n\nIn this case, your board is acting as a peripheral. \n\n\nb adv conn=und disc=gen\n\n\n\n\n\n\n\nShow established connections.\n\n\nb show conn\n\n\n\n\n\n\n\nDiscover and display peer's services, characteristics, and descriptors.\n\n\nThis is how you discover and then display the services of the peer you established earlier across connection-1.\n\n\nb disc full conn=1\n\nb show chr\n\n[ts=132425ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43\n[ts=132428ssb, mod=64 level=2] start=1 end=5 uuid=0x1800\n[ts=132433ssb, mod=64 level=2] start=6 end=16 uuid=0x1808\n[ts=132437ssb, mod=64 level=2] start=17 end=31 uuid=0x180a\n[ts=132441ssb, mod=64 level=2] start=32 end=65535 uuid=00000000-0000-1000-1000000000000000\n\n\n\n\n\n\n\nRead an attribute belonging to the peer\n\n\nb read conn=1 attr=21\n\n\n\n\n\n\n\nWrite to an attribute belonging to the peer\n\n\nb write conn=1 attr=3 value=0x01:0x02:0x03\n\n\n\n\n\n\n\nPerform a passive scan\n\n\nThis is how you tell your board to listen to all advertisements around it. The duration is specified in ms.\n\n\nb scan dur=1000 type=passive filt=no_wl",
- "title": "toc"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#api-for-bletiny-app",
- "text": "\"bletiny\" is one of the sample applications that come with Mynewt. It is a simple shell application which provides a basic interface to the host-side of the BLE stack. \"bletiny\" includes all the possible roles (Central/Peripheral) and they may be run simultaneously. You can run bletiny on a board and issue commands that make it behave as a central or a peripheral with different peers. Highlighted below are some of the ways you can use the API to establish connections and discover services and characteristics from peer devices. For descriptions of the full API, go to the next sections on GAP in bletiny and GATT in bletiny . All bletiny commands are prefixed with b . This prefix distinguished bletiny commands from other shell commands that are implemented by other Mynewt packages.",
- "title": "API for bletiny app"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#set-device-address",
- "text": "On startup, bletiny has the following identity address configuration: Public address: 0a:0b:0c:0d:0e:0f Random address: None The below set commands can be used to change the address configuration: b set addr_type=public addr= device-address \nb set addr_type=random addr= device-address For example: b set addr_type=public addr=01:02:03:04:05:06\nb set addr_type=random addr=c1:aa:bb:cc:dd:ee The address configuration can be viewed with the b show addr command, as follows: b show addr\npublic_id_addr=01:02:03:04:05:06 random_id_addr=c1:aa:bb:cc:dd:ee",
- "title": "Set device address."
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#initiate-a-direct-connection-to-a-device",
- "text": "In this case, your board is acting as a central and initiating a connection with another BLE device. The example assumes you know the address of the peer, either by scanning for available peers or because you have set up the peer yourself. b conn own_addr_type=public peer_addr_type=public peer_addr=d4:f5:13:53:d2:43 connection established; handle=1 our_ota_addr_type=0 our_ota_addr=0a:0b:0c:0d:0e:0f out_id_addr_type=0 our_id_addr=0a:0b:0c:0d:0e:0f peer_addr_type=0 peer_addr=43:d2:53:13:f5:d4 conn_itvl=40 conn_latency=0 supervision_timeout=256 encrypted=0 authenticated=0 bonded=0 The handle=1 in the output indicates that it is connection-1.",
- "title": "Initiate a direct connection to a device"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#configure-advertisements-to-include-device-name",
- "text": "In this case, your board is acting as a peripheral. b set adv_data name= your-device-name",
- "title": "Configure advertisements to include device name"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#begin-sending-undirected-general-advertisements",
- "text": "In this case, your board is acting as a peripheral. b adv conn=und disc=gen",
- "title": "Begin sending undirected general advertisements"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#show-established-connections",
- "text": "b show conn",
- "title": "Show established connections."
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#discover-and-display-peers-services-characteristics-and-descriptors",
- "text": "This is how you discover and then display the services of the peer you established earlier across connection-1. b disc full conn=1 b show chr [ts=132425ssb, mod=64 level=2] CONNECTION: handle=1 addr=d4:f5:13:53:d2:43\n[ts=132428ssb, mod=64 level=2] start=1 end=5 uuid=0x1800\n[ts=132433ssb, mod=64 level=2] start=6 end=16 uuid=0x1808\n[ts=132437ssb, mod=64 level=2] start=17 end=31 uuid=0x180a\n[ts=132441ssb, mod=64 level=2] start=32 end=65535 uuid=00000000-0000-1000-1000000000000000",
- "title": "Discover and display peer's services, characteristics, and descriptors."
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#read-an-attribute-belonging-to-the-peer",
- "text": "b read conn=1 attr=21",
- "title": "Read an attribute belonging to the peer"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#write-to-an-attribute-belonging-to-the-peer",
- "text": "b write conn=1 attr=3 value=0x01:0x02:0x03",
- "title": "Write to an attribute belonging to the peer"
- },
- {
- "location": "/network/ble/bletiny/bletiny_api/#perform-a-passive-scan",
- "text": "This is how you tell your board to listen to all advertisements around it. The duration is specified in ms. b scan dur=1000 type=passive filt=no_wl",
- "title": "Perform a passive scan"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/",
- "text": "GAP API for bletiny\n\n\n\n\nGeneric Access Profile (GAP) defines the generic procedures related to discovery of Bluetooth devices (idle mode procedures) and link management aspects of connecting to Bluetooth devices (connecting mode procedures). It also defines procedures related to use of different security levels. \n\n\nSeveral different modes and procedures may be performed simultaneously over an LE physical transport. The following modes and procedures are defined for use over an LE physical transport:\n\n\n\n\nBroadcast mode and observation procedure\n\n\nThese allow two devices to communicate in a unidirectional connectionless manner using the advertising events.\n\n\n\n\n\n\nDiscovery modes and procedures\n\n\nAll devices shall be in either non-discoverable mode or one of the discoverable modes.\n\n\nA device in the discoverable mode shall be in either the general discoverable mode or the limited discoverable mode.\n\n\nA device in non-discoverable mode will not be discovered by any device that is performing either the general discovery procedure or the limited discovery procedure.\n\n\n\n\n\n\nConnection modes and procedures\n\n\nallow a device to establish a connection to another device.\n\n\nallow updating of parameters of the connection \n\n\nallow termination of the connection \n\n\n\n\n\n\nBonding modes and procedures\n\n\nBonding allows two connected devices to exchange and store security and identity information to create a trusted relationship. \n\n\nBonding can occur only between two devices in bondable mode.\n\n\n\n\n\n\n\n\n\n\nUsage API\n\n\n\n\n\n\n\n\nItem No.\n\n\nModes and Procedures\n\n\nnimBLE command\n\n\n\n\n\n\n\n\n\n\n1\n\n\nBroadcast Mode\n\n\nb adv conn=non disc=x\n\n\n\n\n\n\n\n\nObservation Procedure\n\n\nb scan dur=x disc=x type=x filt=x\n\n\n\n\n\n\n2\n\n\nNon-Discoverable mode\n\n\nb adv conn=x disc=non\n\n\n\n\n\n\n\n\nLimited Discoverable mode\n\n\nb adv conn=x disc=ltd\n\n\n\n\n\n\n\n\nGeneral Discoverable mode\n\n\nb adv conn=x disc=gen\n\n\n\n\n\n\n\n\nLimited Discovery procedure\n\n\nb scan dur=x disc=ltd type=active filt=no_wl\n\n\n\n\n\n\n\n\nGeneral Discovery procedure\n\n\nb scan dur=x disc=gen type=active filt=no_wl\n\n\n\n\n\n\n\n\nName Discovery procedure\n\n\nb scan dur=x\n \n \nb scan cancel\n \n \nb conn peer_addr_type=x peer_addr=x\n \n \nb read uuid=0x2a00\n\n\n\n\n\n\n3\n\n\nNon-connectable mode\n\n\nb adv conn=non disc=x\n\n\n\n\n\n\n\n\nDirected connectable mode\n\n\nb adv conn=dir [own_addr_type=x] [disc=x] [dur=x]\n\n\n\n\n\n\n\n\nUndirected connectable mode\n\n\nb adv conn=und [own_addr_type=x] [disc=x] [dur=x]\n\n\n\n\n\n\n\n\nAuto connection establishment procedure\n\n\nb wl addr_type=x addr=x [addr_type=y addr=y] [...]\n \n \nb conn addr_type=wl\n\n\n\n\n\n\n\n\nGeneral connection establishment procedure\n\n\nb scan dur=x\n \n \nb scan cancel\n \n \nb conn peer_addr_type=x peer_addr=x\n\n\n\n\n\n\n\n\nSelective connection establishment procedure\n\n\nb wl addr_type=x addr=x [addr_type=y addr=y] [...]\n \n \nb scan filt=use_wl dur=x\n \n \nb scan cancel\n \n \nb conn peer_addr_type=x peer_addr=x [own_addr_type=x]\n\n\n\n\n\n\n\n\nDirect connection establishment procedure\n\n\nb conn addr_type=x addr=x [params]\n\n\n\n\n\n\n\n\nConnection parameter update procedure\n\n\nb update conn=x \nparams\n\n\n\n\n\n\n\n\nTerminate connection procedure\n\n\nb term conn=x\n\n\n\n\n\n\n4\n\n\nNon-Bondable mode\n\n\nb set sm_data bonding=0\n [*]\n\n\n\n\n\n\n\n\nBondable mode\n\n\nb set sm_data bonding=1\n [*]\n\n\n\n\n\n\n\n\nBonding procedure\n\n\nb sec start conn=x\n [*]\n\n\n\n\n\n\n\n\n[*]\n Security is disabled by default in bletiny. To use the bonding modes and procedures, add the \n-DNIMBLE_OPT_SM=1\n cflag to your target.\n\n\n\n\nAddress Types\n\n\n\n\n\n\n\n\nbletiny string\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npublic\n\n\nPublic address.\n\n\n\n\n\n\nrandom\n\n\nRandom static address.\n\n\n\n\n\n\nrpa_pub\n\n\nResolvable private address, public identity.\n\n\n\n\n\n\nrpa_rnd\n\n\nResolvable private address, random static identity.\n\n\n\n\n\n\nwl\n\n\nUse white list; ignore peer_addr parameter.\n\n\n\n\n\n\n\n\nConnection Parameters\n\n\nThe Connection parameter definitions can be found in Section 7.8.12 of the BLUETOOTH SPECIFICATION Version 4.2 [Vol 2, Part E].\n\n\n\n\n\n\n\n\nName\n\n\nDescription\n\n\nbletiny string\n\n\n\n\n\n\n\n\n\n\nLE_Scan_Interval\n\n\nRecommendation from the Host on how long the Controller should scan\n\n\nscan_itvl\n\n\n\n\n\n\nLE_Scan_Window\n\n\nRecommendation from the Host on how frequently the Controller should scan\n\n\nscan_window\n\n\n\n\n\n\nPeer_Address_Type\n\n\nWhether the peer is using a public or random address (see Address types table).\n\n\npeer_addr_type\n\n\n\n\n\n\nPeer_Address\n\n\nThe 6-byte device address of the peer; ignored if white list is used\n\n\npeer_addr\n\n\n\n\n\n\nOwn_Address_Type\n\n\nThe type of address to use when initiating the connection (see Address types table)\n\n\nown_addr_type\n\n\n\n\n\n\nConn_Interval_Min\n\n\nDefines minimum allowed connection interval\n\n\nitvl_min\n\n\n\n\n\n\nConn_Interval_Max\n\n\nDefines maximum allowed connection interval\n\n\nitvl_max\n\n\n\n\n\n\nConn_Latency\n\n\nDefines the maximum allowed connection latency\n\n\nlatency\n\n\n\n\n\n\nSupervision_Timeout\n\n\nLink supervision timeout for the connection.\n\n\ntimeout\n\n\n\n\n\n\nMinimum_CE_Length\n\n\nInformative parameter providing the Controller with the expected minimum length of the connection event\n\n\nmin_ce_len\n\n\n\n\n\n\nMaximum_CE_Length\n\n\nInformative parameter providing the Controller with the expected maximum length of the connection event\n\n\nmax_ce_len\n\n\n\n\n\n\nDuration\n\n\nNumber of milliseconds before aborting the connect attempt\n\n\ndur\n\n\n\n\n\n\n\n\nAdvertisment Parameters\n\n\n\n\n\n\n\n\nbletiny string\n\n\nDescription\n\n\nNotes\n\n\nDefault\n\n\n\n\n\n\n\n\n\n\nconn\n\n\nConnectable mode\n\n\nSee Connectable Modes table.\n\n\nund\n\n\n\n\n\n\ndisc\n\n\nDiscoverable mode\n\n\nSee Discoverable Modes table.\n\n\ngen\n\n\n\n\n\n\nown_addr_type\n\n\nThe type of address to advertise with\n\n\nSee Address Types table.\n\n\npublic\n\n\n\n\n\n\npeer_addr_type\n\n\nThe peer's address type\n\n\nOnly used for directed advertising; see Address Types table.\n\n\npublic\n\n\n\n\n\n\npeer_addr\n\n\nThe peer's address\n\n\nOnly used for directed advertising\n\n\nN/A\n\n\n\n\n\n\nchan_map\n\n\n\n\n\n\n0\n\n\n\n\n\n\nfilt\n\n\nThe filter policy\n\n\nSee Advertisement Filter Policies table.\n\n\nnone\n\n\n\n\n\n\nitvl_min\n\n\n\n\nunits=0.625ms\n\n\nnon: 100ms; und/dir: 30ms\n\n\n\n\n\n\nitvl_max\n\n\n\n\nunits=0.625ms\n\n\nnon: 150ms; und/dir: 60ms\n\n\n\n\n\n\nhd\n\n\nWhether to use high-duty-cycle\n\n\n0/1\n\n\n0\n\n\n\n\n\n\ndur\n\n\n\n\nMilliseconds\n\n\nForever\n\n\n\n\n\n\n\n\nAdvertisement Filter Policies\n\n\n\n\n\n\n\n\nbletiny string\n\n\nDescription\n\n\nNotes\n\n\n\n\n\n\n\n\n\n\nnone\n\n\nNo filtering. No whitelist used.\n\n\nDefault\n\n\n\n\n\n\nscan\n\n\nProcess all connection requests but only scans from white list.\n\n\n\n\n\n\n\n\nconn\n\n\nProcess all scan request but only connection requests from white list.\n\n\n\n\n\n\n\n\nboth\n\n\nIgnore all scan and connection requests unless in white list.",
- "title": "GAP in bletiny"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/#gap-api-for-bletiny",
- "text": "Generic Access Profile (GAP) defines the generic procedures related to discovery of Bluetooth devices (idle mode procedures) and link management aspects of connecting to Bluetooth devices (connecting mode procedures). It also defines procedures related to use of different security levels. Several different modes and procedures may be performed simultaneously over an LE physical transport. The following modes and procedures are defined for use over an LE physical transport: Broadcast mode and observation procedure These allow two devices to communicate in a unidirectional connectionless manner using the advertising events. Discovery modes and procedures All devices shall be in either non-discoverable mode or one of the discoverable modes. A device in the discoverable mode shall be in either the general discoverable mode or the limited discoverable mode. A device in non-discoverable mode will not be discovered by any device that is performing either the general discovery procedure or the limited discovery procedure. Connection modes and procedures allow a device to establish a connection to another device. allow updating of parameters of the connection allow termination of the connection Bonding modes and procedures Bonding allows two connected devices to exchange and store security and identity information to create a trusted relationship. Bonding can occur only between two devices in bondable mode.",
- "title": "GAP API for bletiny"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/#usage-api",
- "text": "Item No. Modes and Procedures nimBLE command 1 Broadcast Mode b adv conn=non disc=x Observation Procedure b scan dur=x disc=x type=x filt=x 2 Non-Discoverable mode b adv conn=x disc=non Limited Discoverable mode b adv conn=x disc=ltd General Discoverable mode b adv conn=x disc=gen Limited Discovery procedure b scan dur=x disc=ltd type=active filt=no_wl General Discovery procedure b scan dur=x disc=gen type=active filt=no_wl Name Discovery procedure b scan dur=x b scan cancel b conn peer_addr_type=x peer_addr=x b read uuid=0x2a00 3 Non-connectable mode b adv conn=non disc=x Directed connectable mode b adv conn=dir [own_addr_type=x] [disc=x] [dur=x] Undirected connectable mode b adv conn=und [own_addr_type=x] [disc=x] [dur=x] Auto connection establishment procedure b wl addr_type=x addr=x [addr_type=y addr=y] [...] b conn addr_type=wl General connection establishment procedure b scan dur=x b scan cancel b conn peer_addr_type=x peer_addr=x Selective connection establishment procedure b wl addr_type=x addr=x [addr_type=y addr=y] [...] b scan filt=use_wl dur=x b scan cancel b conn peer_addr_type=x peer_addr=x [own_addr_type=x] Direct connection establishment procedure b conn addr_type=x addr=x [params] Connection parameter update procedure b update conn=x params Terminate connection procedure b term conn=x 4 Non-Bondable mode b set sm_data bonding=0 [*] Bondable mode b set sm_data bonding=1 [*] Bonding procedure b sec start conn=x [*] [*] Security is disabled by default in bletiny. To use the bonding modes and procedures, add the -DNIMBLE_OPT_SM=1 cflag to your target.",
- "title": "Usage API"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/#address-types",
- "text": "bletiny string Description public Public address. random Random static address. rpa_pub Resolvable private address, public identity. rpa_rnd Resolvable private address, random static identity. wl Use white list; ignore peer_addr parameter.",
- "title": "Address Types"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/#connection-parameters",
- "text": "The Connection parameter definitions can be found in Section 7.8.12 of the BLUETOOTH SPECIFICATION Version 4.2 [Vol 2, Part E]. Name Description bletiny string LE_Scan_Interval Recommendation from the Host on how long the Controller should scan scan_itvl LE_Scan_Window Recommendation from the Host on how frequently the Controller should scan scan_window Peer_Address_Type Whether the peer is using a public or random address (see Address types table). peer_addr_type Peer_Address The 6-byte device address of the peer; ignored if white list is used peer_addr Own_Address_Type The type of address to use when initiating the connection (see Address types table) own_addr_type Conn_Interval_Min Defines minimum allowed connection interval itvl_min Conn_Interval_Max Defines maximum allowed connection interval itvl_max Conn_Latency Defines the maximum allowed connection latency latency Supervision_Timeout Link supervision timeout for the connection. timeout Minimum_CE_Length Informative parameter providing the Controller with the expected minimum length of the connection event min_ce_len Maximum_CE_Length Informative parameter providing the Controller with the expected maximum length of the connection event max_ce_len Duration Number of milliseconds before aborting the connect attempt dur",
- "title": "Connection Parameters"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/#advertisment-parameters",
- "text": "bletiny string Description Notes Default conn Connectable mode See Connectable Modes table. und disc Discoverable mode See Discoverable Modes table. gen own_addr_type The type of address to advertise with See Address Types table. public peer_addr_type The peer's address type Only used for directed advertising; see Address Types table. public peer_addr The peer's address Only used for directed advertising N/A chan_map 0 filt The filter policy See Advertisement Filter Policies table. none itvl_min units=0.625ms non: 100ms; und/dir: 30ms itvl_max units=0.625ms non: 150ms; und/dir: 60ms hd Whether to use high-duty-cycle 0/1 0 dur Milliseconds Forever",
- "title": "Advertisment Parameters"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GAP/#advertisement-filter-policies",
- "text": "bletiny string Description Notes none No filtering. No whitelist used. Default scan Process all connection requests but only scans from white list. conn Process all scan request but only connection requests from white list. both Ignore all scan and connection requests unless in white list.",
- "title": "Advertisement Filter Policies"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GATT/",
- "text": "GATT feature API for bletiny\n\n\n\n\nGATT(GENERIC ATTRIBUTE PROFILE) describes a service framework using the Attribute Protocol for discovering services, and for reading and writing characteristic values on a peer device. There are 11 features defined in the GATT Profile, and each of the features is mapped to procedures and sub-procedures: \n\n\n\n\n\n\n\n\nItem No.\n\n\nFeature\n\n\nSub-Procedure\n\n\nnimBLE command\n\n\n\n\n\n\n\n\n\n\n1\n\n\nServer Configuration\n\n\nExchange MTU\n\n\nb mtu\n\n\n\n\n\n\n2\n\n\nPrimary Service Discovery\n\n\nDiscover All Primary Services\n\n\nb disc svc conn=x\n\n\n\n\n\n\n\n\n\n\nDiscover Primary Services By Service UUID\n\n\nb disc svc conn=x uuid=x\n\n\n\n\n\n\n3\n\n\nRelationship Discovery\n\n\nFind Included Services\n\n\nb find inc_svcs conn=x start=x end=x\n\n\n\n\n\n\n4\n\n\nCharacteristic Discovery\n\n\nDiscover All Characteristic of a Service\n\n\nb disc chr conn=x start=x end=x\n\n\n\n\n\n\n\n\n\n\nDiscover Characteristic by UUID\n\n\nb disc chr conn=x start=x end=x uuid=x\n\n\n\n\n\n\n5\n\n\nCharacteristic Descriptor Discovery\n\n\nDiscover All Characteristic Descriptors\n\n\nb disc dsc conn=x start=x end=x\n\n\n\n\n\n\n6\n\n\nReading a Characteristic Value\n\n\nRead Characteristic Value\n\n\nb read conn=x attr=x\n\n\n\n\n\n\n\n\n\n\nRead Using Characteristic UUID\n\n\nb read conn=x start=x end=x uuid=x\n\n\n\n\n\n\n\n\n\n\nRead Long Characteristic Values\n\n\nb read conn=x attr=x long=1\n\n\n\n\n\n\n\n\n\n\nRead Multiple Characteristic Values\n\n\nb read conn=x attr=x attr=y attr=z\n\n\n\n\n\n\n7\n\n\nWriting a Characteristic Value\n\n\nWrite Without Response\n\n\nb write conn=x value=0xXX:0xXX no_rsp=1\n\n\n\n\n\n\n\n\n\n\nSigned Write Without Response\n\n\nNOT SUPPORTED\n\n\n\n\n\n\n\n\n\n\nWrite Characteristic Value\n\n\nb write conn=x attr=x value=0xXX:0xXX\n\n\n\n\n\n\n\n\n\n\nWrite Long Characteristic Values\n\n\nb write conn=x attr=x value=0xXX:0xXX long=1\n\n\n\n\n\n\n\n\n\n\nCharacteristic Value Reliable Writes\n\n\nb write conn=x attr=x value=0xXX:0xXX attr=y value=0xYY:0xYY\n\n\n\n\n\n\n8\n\n\nNotification of a Characteristic Value\n\n\nNotifications\n\n\nWrite \n0x01:0x00\n to CLIENT CONFIGURATION characteristic\n\n\n\n\n\n\n9\n\n\nIndication of a Characteristic Value\n\n\nIndications\n\n\nWrite \n0x02:0x00\n to CLIENT CONFIGURATION characteristic\n\n\n\n\n\n\n10\n\n\nReading a Characteristic Descriptor\n\n\nRead Characteristic Descriptors\n\n\nb read conn=x attr=x\n\n\n\n\n\n\n\n\n\n\nRead Long Characteristic Descriptors\n\n\nb read conn=x attr=x long=1\n\n\n\n\n\n\n11\n\n\nWriting a Characteristic Descriptor\n\n\nWrite Characteristic Descriptors\n\n\nb write conn=x value=0xXX:0xXX\n\n\n\n\n\n\n\n\n\n\nWrite Long Characteristic Descriptors\n\n\nb write conn=x value=0xXX:0xXX long=1\n\n\n\n\n\n\n\n\n\n\nUsing NimBLE commands\n\n\nAssuming you have discovered and established a BLE connection with at least one peer device (as explained earlier in \nAPI for bletiny app\n, you can find out what characteristics and services are available over these connections. Here is a recap.\n\n\nTo show established connections:\n\n\nb show conn\n\n\n\n\n\nTo show discovered services, characteristics, and descriptors:\n\n\nb show chr\n\n\n\n\n\nTo show connection RSSI:\n\n\nb show rssi conn=x",
- "title": "GATT in bletiny"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GATT/#gatt-feature-api-for-bletiny",
- "text": "GATT(GENERIC ATTRIBUTE PROFILE) describes a service framework using the Attribute Protocol for discovering services, and for reading and writing characteristic values on a peer device. There are 11 features defined in the GATT Profile, and each of the features is mapped to procedures and sub-procedures: Item No. Feature Sub-Procedure nimBLE command 1 Server Configuration Exchange MTU b mtu 2 Primary Service Discovery Discover All Primary Services b disc svc conn=x Discover Primary Services By Service UUID b disc svc conn=x uuid=x 3 Relationship Discovery Find Included Services b find inc_svcs conn=x start=x end=x 4 Characteristic Discovery Discover All Characteristic of a Service b disc chr conn=x start=x end=x Discover Characteristic by UUID b disc chr conn=x start=x end=x uuid=x 5 Characteristic Descriptor Discovery Discover All Characteristic Descriptors b disc dsc conn=x start=x end=x 6 Reading a Characteristic Value Read Characteristic Value b read conn=x attr=x Read Using Characteristic UUID b read conn=x start=x end=x uuid=x Read Long Characteristic Values b read conn=x attr=x long=1 Read Multiple Characteristic Values b read conn=x attr=x attr=y attr=z 7 Writing a Characteristic Value Write Without Response b write conn=x value=0xXX:0xXX no_rsp=1 Signed Write Without Response NOT SUPPORTED Write Characteristic Value b write conn=x attr=x value=0xXX:0xXX Write Long Characteristic Values b write conn=x attr=x value=0xXX:0xXX long=1 Characteristic Value Reliable Writes b write conn=x attr=x value=0xXX:0xXX attr=y value=0xYY:0xYY 8 Notification of a Characteristic Value Notifications Write 0x01:0x00 to CLIENT CONFIGURATION characteristic 9 Indication of a Characteristic Value Indications Write 0x02:0x00 to CLIENT CONFIGURATION characteristic 10 Reading a Characteristic Descriptor Read Characteristic Descriptors b read conn=x attr=x Read Long Characteristic Descriptors b read conn=x attr=x long=1 11 Writing a Characteristic Descriptor Write Characteristic Descriptors b write conn=x value=0xXX:0xXX Write Long Characteristic Descriptors b write conn=x value=0xXX:0xXX long=1",
- "title": "GATT feature API for bletiny"
- },
- {
- "location": "/network/ble/bletiny/bletiny_GATT/#using-nimble-commands",
- "text": "Assuming you have discovered and established a BLE connection with at least one peer device (as explained earlier in API for bletiny app , you can find out what characteristics and services are available over these connections. Here is a recap. To show established connections: b show conn To show discovered services, characteristics, and descriptors: b show chr To show connection RSSI: b show rssi conn=x",
- "title": "Using NimBLE commands"
- },
- {
- "location": "/network/ble/bletiny/bletiny_advdata/",
- "text": "Advertisement Data Fields\n\n\n\n\nThis part defines the advertisement data fields used in the \nbletiny\n app. For a complete list of all data types and formats used for Extended Inquiry Response (EIR), Advertising Data (AD), and OOB data blocks, refer to the Supplement to the Bluetooth Core Specification, CSSv6, available for download \nhere\n. \n\n\n\n\n\n\n\n\n\n\nName\n\n\nDefinition\n\n\nDetails\n\n\nbletiny Notes\n\n\n\n\n\n\n\n\n\n\nflags\n\n\nIndicates basic information about the advertiser.\n\n\nFlags used over the LE physical channel are: \n * Limited Discoverable Mode \n * General Discoverable Mode \n * BR/EDR Not Supported \n * Simultaneous LE and BR/EDR to Same Device Capable (Controller) \n * Simultaneous LE and BR/EDR to Same Device Capable (Host)\n\n\nNimBLE will auto-calculate if set to 0.\n\n\n\n\n\n\nuuids16\n\n\n16-bit Bluetooth Service UUIDs\n\n\nIndicates the Service UUID list is incomplete i.e. more 16-bit Service UUIDs available. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG.\n\n\nSet repeatedly for multiple service UUIDs.\n\n\n\n\n\n\nuuids16_is_complete\n\n\n16-bit Bluetooth Service UUIDs\n\n\nIndicates the Service UUID list is complete. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG.\n\n\n\n\n\n\n\n\nuuids32\n\n\n32-bit Bluetooth Service UUIDs\n\n\nIndicates the Service UUID list is incomplete i.e. more 32-bit Service UUIDs available. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG.\n\n\nSet repeatedly for multiple service UUIDs.\n\n\n\n\n\n\nuuids32_is_complete\n\n\n32-bit Bluetooth Service UUIDs\n\n\nIndicates the Service UUID list is complete. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG.\n\n\n\n\n\n\n\n\nuuids128\n\n\nGlobal 128-bit Service UUIDs\n\n\nMore 128-bit Service UUIDs available.\n\n\nSet repeatedly for multiple service UUIDs.\n\n\n\n\n\n\nuuids128_is_complete\n\n\nGlobal 128-bit Service UUIDs\n\n\nComplete list of 128-bit Service UUIDs\n\n\n\n\n\n\n\n\ntx_pwr_lvl\n\n\nTX Power Level\n\n\nIndicates the transmitted power level of the packet containing the data type. The TX Power Level data type may be used to calculate path loss on a received packet using the following equation: \n \n pathloss = Tx Power Level \u2013 RSSI \n \n where \u201cRSSI\u201d is the received signal strength, in dBm, of the packet received.\n\n\nNimBLE will auto-calculate if set to -128.\n\n\n\n\n\n\ndevice_class\n\n\nClass of device\n\n\nSize: 3 octets\n\n\n\n\n\n\n\n\nslave_itvl_range\n\n\nSlave Connection Interval Range\n\n\nContains the Peripheral\u2019s preferred connection interval range, for all logical connections. Size: 4 Octets . The first 2 octets defines the minimum value for the connection interval in the following manner: \n \n connIntervalmin = Conn_Interval_Min * 1.25 ms \n \n Conn_Interval_Min range: 0x0006 to 0x0C80 \n Value of 0xFFFF indicates no specific minimum. \n \n The other 2 octets defines the maximum value for the connection interval in the following manner: \n \n connIntervalmax = Conn_Interval_Max * 1.25 ms \n Conn_Interval_Max range: 0x0006 to 0x0C80 \n Conn_Interval_Max shall be equal to or greater than the Conn_Interval_Min. \n Value of 0xFFFF indicates no specific maximum.\n\n\n\n\n\n\n\n\nsvc_data_uuid16\n\n\nService Data - 16 bit UUID\n\n\nSize: 2 or more octets \n The first 2 octets contain the 16 bit Service UUID followed by additional service data\n\n\n\n\n\n\n\n\npublic_tgt_addr\n\n\nPublic Target Address\n\n\nDefines the address of one or more intended recipients of an advertisement when one or more devices were bonded using a public address. This data type shall exist only once. It may be sent in either the Advertising or Scan Response data, but not both.\n\n\n\n\n\n\n\n\nappearance\n\n\nAppearance\n\n\nDefines the external appearance of the device. The Appearance data type shall exist only once. It may be sent in either the Advertising or Scan Response data, but not both.\n\n\n\n\n\n\n\n\nadv_itvl\n\n\nAdvertising Interval\n\n\nContains the advInterval value as defined in the Core specification, Volume 6, Part B, Section 4.4.2.2.\n\n\n\n\n\n\n\n\nle_addr\n\n\nLE Bluetooth Device Address\n\n\nDefines the device address of the local device and the address type on the LE transport.\n\n\n\n\n\n\n\n\nle_role\n\n\nLE Role\n\n\nDefines the LE role capabilities of the device. \n 0x00 Only Peripheral Role supported \n 0x01 Only Central Role supported \n 0x02 Peripheral and Central Role supported, Peripheral Role preferred for connection establishment \n 0x03 Peripheral and Central Role supported, Central Role preferred for connection establishment \n 0x04 \u2013 0xFF Reserved for future use\n\n\n\n\n\n\n\n\nsvc_data_uuid32\n\n\nService Data - 32 bit UUID\n\n\nSize: 4 or more octets \n The first 4 octets contain the 32 bit Service UUID followed by additional service data\n\n\n\n\n\n\n\n\nsvc_data_uuid128\n\n\nService Data - 128 bit UUID\n\n\nSize: 16 or more octets \n The first 16 octets contain the 128 bit Service UUID followed by additional service data\n\n\n\n\n\n\n\n\nuri\n\n\nUniform Resource Identifier (URI)\n\n\nScheme name string and URI as a UTF-8 string\n\n\n\n\n\n\n\n\nmfg_data\n\n\nManufacturer Specific data\n\n\nSize: 2 or more octets \n The first 2 octets contain the Company Identifier Code followed by additional manufacturer specific data\n\n\n\n\n\n\n\n\neddystone_url",
- "title": "Advertisement Data Fields"
- },
- {
- "location": "/network/ble/bletiny/bletiny_advdata/#advertisement-data-fields",
- "text": "This part defines the advertisement data fields used in the bletiny app. For a complete list of all data types and formats used for Extended Inquiry Response (EIR), Advertising Data (AD), and OOB data blocks, refer to the Supplement to the Bluetooth Core Specification, CSSv6, available for download here . Name Definition Details bletiny Notes flags Indicates basic information about the advertiser. Flags used over the LE physical channel are: * Limited Discoverable Mode * General Discoverable Mode * BR/EDR Not Supported * Simultaneous LE and BR/EDR to Same Device Capable (Controller) * Simultaneous LE and BR/EDR to Same Device Capable (Host) NimBLE will auto-calculate if set to 0. uuids16 16-bit Bluetooth Service UUIDs Indicates the Service UUID list is incomplete i.e. more 16-bit Service UUIDs available. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. Set repeatedly for multiple service UUIDs. uuids16_is_complete 16-bit Bluetooth Service UUIDs Indicates the Service UUID list is complete. 16 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. uuids32 32-bit Bluetooth Service UUIDs Indicates the Service UUID list is incomplete i.e. more 32-bit Service UUIDs available. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. Set repeatedly for multiple service UUIDs. uuids32_is_complete 32-bit Bluetooth Service UUIDs Indicates the Service UUID list is complete. 32 bit UUIDs shall only be used if they are assigned by the Bluetooth SIG. uuids128 Global 128-bit Service UUIDs More 128-bit Service UUIDs available. Set repeatedly for multiple service UUIDs. uuids128_is_complete Global 128-bit Service UUIDs Complete list of 128-bit Service UUIDs tx_pwr_lvl TX Power Level Indicates the transmitted power level of the packet containing the data type. The TX Power Level data type may be used to calculate path loss on a received packet using the following equation: pathloss = Tx Power Level \u2013 RSSI where \u201cRSSI\u201d is the received signal strength, in dBm, of the packet received. NimBLE will auto-calculate if set to -128. device_class Class of device Size: 3 octets slave_itvl_range Slave Connection Interval Range Contains the Peripheral\u2019s preferred connection interval range, for all logical connections. Size: 4 Octets . The first 2 octets defines the minimum value for the connection interval in the following manner: connIntervalmin = Conn_Interval_Min * 1.25 ms Conn_Interval_Min range: 0x0006 to 0x0C80 Value of 0xFFFF indicates no specific minimum. The other 2 octets defines the maximum value for the connection interval in the following manner: connIntervalmax = Conn_Interval_Max * 1.25 ms Conn_Interval_Max range: 0x0006 to 0x0C80 Conn_Interval_Max shall be equal to or greater than the Conn_Interval_Min. Value of 0xFFFF indicates no specific maximum. svc_data_uuid16 Service Data - 16 bit UUID Size: 2 or more octets The first 2 octets contain the 16 bit Service UUID followed by additional service data public_tgt_addr Public Target Address Defines the address of one or more intended recipients of an advertisement when one or more devices were bonded using a public address. This data type shall exist only once. It may be sent in either the Advertising or Scan Response data, but not both. appearance Appearance Defines the external appearance of the device. The Appearance data type shall exist only once. It may be sent in either the Advertising or Scan Response data, but not both. adv_itvl Advertising Interval Contains the advInterval value as defined in the Core specification, Volume 6, Part B, Section 4.4.2.2. le_addr LE Bluetooth Device Address Defines the device address of the local device and the address type on the LE transport. le_role LE Role Defines the LE role capabilities of the device. 0x00 Only Peripheral Role supported 0x01 Only Central Role supported 0x02 Peripheral and Central Role supported, Peripheral Role preferred for connection establishment 0x03 Peripheral and Central Role supported, Central Role preferred for connection establishment 0x04 \u2013 0xFF Reserved for future use svc_data_uuid32 Service Data - 32 bit UUID Size: 4 or more octets The first 4 octets contain the 32 bit Service UUID followed by additional service data svc_data_uuid128 Service Data - 128 bit UUID Size: 16 or more octets The first 16 octets contain the 128 bit Service UUID followed by additional service data uri Uniform Resource Identifier (URI) Scheme name string and URI as a UTF-8 string mfg_data Manufacturer Specific data Size: 2 or more octets The first 2 octets contain the Company Identifier Code followed by additional manufacturer specific data eddystone_url",
- "title": "Advertisement Data Fields"
- },
- {
- "location": "/newt/newt_intro/",
- "text": "Newt Tool\n\n\nIntroduction\n\n\nNewt is a smart build and package management system for embedded contexts. It is a single tool that accomplishes both the following goals:\n\n\n\n\nsource package management \n\n\nbuild, debug and install.\n\n\n\n\nRationale\n\n\nIn order for the Mynewt operating system to work well for constrained environments across the many different types of microcontroller applications (from doorbells to medical devices to power grids), a system is needed that lets you select which packages to install and which packages to build.\n\n\nThe build systems for embedded devices are often fairly complicated and not well served for this purpose. For example, autoconf is designed for detecting system compatibility issues but not well suited when it comes to tasks like:\n\n\n\n\nBuilding for multiple targets\n\n\nDeciding what to build in and what not to build in\n\n\nManaging dependencies between components\n\n\n\n\nFortunately, solutions addressing these very issues can be found in source package management systems in higher level languages such as Javascript \n(Node), Go, PHP and Ruby. We decided to fuse their source management \nsystems with a make system built for embedded systems and create Newt.\n\n\nBuild System\n\n\nA good build system must allow the user to take a few common steps while developing embedded applications:\n\n\n\n\nGenerate full flash images\n\n\nDownload debug images to a target board using a debugger\n\n\nConditionally compile libraries \n code based upon build settings\n\n\n\n\nNewt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop:\n\n\n$ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\n\u251c\u2500\u2500 apps\n\n\u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml\n\n\u2514\u2500\u2500 targets\n\n \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files\n\n\n\n\n\n\n\nWhen Newt sees a directory tree that contains a \"project.yml\" file, it is smart enough to recognize it as the base directory of a project, and \nautomatically builds a package tree. It also recognizes two important package directories in the package tree - \"apps\" and \"targets\". More on these directories in \nNewt Theory of Ops\n.\n\n\nWhen Newt builds a target, it recursively resolves all package dependencies, and generates artifacts that are placed in the bin/targets/\ntarget-name\n/app/apps/\napp-name\n directory, where the bin directory is under the project base directory, \ntarget-name\n is the name of the target, and \napp-name\n is the name of the application. For our example \nmy_blinky_sim\n is the name of the target and \nblinky\n is the name of the application. The \nblinky.elf\n executable is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree:\n\n\ntree -L 6 bin/\nbin/\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 manifest.json\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 drivers\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 uart\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 repos\n\n\nsnip\n\n\n\n\n\n\n\n\nMore operations using Newt\n\n\nOnce a target has been built, Newt allows additional operations on the target. \n\n\n\n\nload\n: Download built target to board\n\n\ndebug\n: Open debugger session to target\n\n\nsize\n: Get size of target components\n\n\ncreate-image\n: Add image header to the binary image\n\n\nrun\n: Build, create image, load, and finally open a debug session with the target\n\n\ntarget\n: Create, delete, configure, and query a target\n\n\n\n\nFor more details on how Newt works, go to \nNewt - Theory of Operations\n.\n\n\n\n\nSource Management and Repositories\n\n\nThe other major element of the Newt tool is the ability to create reusable source distributions from a collection of code. \nA project can be a reusable container of source code.\n In other words, projects can be versioned and redistributed, not packages. A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack.\n\n\nA project that has been made redistributable is known as a \nrepository\n. \nRepositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky project's yml file which relies on apache-mynewt-core:\n\n\n$ more project.yml\n\nsnip\n\nproject.repositories:\n - apache-mynewt-core\n\n# Use github\ns distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core\n\n\n\n\n\n\n\nWhen you specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies:\n\n\n$ newt install\nDownloading repository description for apache-mynewt-core... success!\nDownloading repository incubator-mynewt-core (branch: develop) at \nhttps://github.com/apache/incubator-mynewt-core.git\nCloning into \n\n/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459\n...\nremote: Counting objects: 17601, done.\nremote: Compressing objects: 100% (300/300), done.\nremote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284\nReceiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.\nResolving deltas: 100% (10347/10347), done.\nChecking connectivity... done.\nRepos successfully installed\n\n\n\n\n\n\n\nNewt will install this repository in the \n/repos directory. In the case of blinky, the directory structure ends up looking like:\n\n\n$ tree -L 2\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u2500\u2500 blinky\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502 \u2514\u2500\u2500 apache-mynewt-core\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2514\u2500\u2500 unittest\n\n\n\n\n\n\n\nIn order to reference the installed repositories in packages, the \"@\" notation should be specified in the repository specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells the build system to look in the base directory of repos/apache-mynewt-core for the \nkernel/os\n, \nhw/hal\n, and \nsys/console/full\n packages.\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.deps:\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/sys/console/full\n\n\n\n\n\n\n\n\nAutocompletion in Bash\n\n\nNewt has the ability to autocomplete within \nbash\n. The following instructions allow MAC users to enable autocomplete within \nbash\n.\n\n\n\n\nInstall the autocomplete tools for bash via \nbrew install bash-completion\n\n\nTell your shell to use newt for autocompletion of newt via \ncomplete -C \"newt complete\" newt\n. You can add this to your .bashrc or other init file to have it automatically set for all bash shells.\n\n\n\n\nNotes:\n\n\n\n\nAutocomplete will give you flag hints, but only if you type a '-'. \n\n\nAutocomplete will not give you completion hints for the flag arguments (those optional things after the flag like \n-l DEBUG\n)\n\n\nAutocomplete uses newt to parse the project to find targets and libs.",
- "title": "toc"
- },
- {
- "location": "/newt/newt_intro/#newt-tool",
- "text": "",
- "title": "Newt Tool"
- },
- {
- "location": "/newt/newt_intro/#introduction",
- "text": "Newt is a smart build and package management system for embedded contexts. It is a single tool that accomplishes both the following goals: source package management build, debug and install.",
- "title": "Introduction"
- },
- {
- "location": "/newt/newt_intro/#rationale",
- "text": "In order for the Mynewt operating system to work well for constrained environments across the many different types of microcontroller applications (from doorbells to medical devices to power grids), a system is needed that lets you select which packages to install and which packages to build. The build systems for embedded devices are often fairly complicated and not well served for this purpose. For example, autoconf is designed for detecting system compatibility issues but not well suited when it comes to tasks like: Building for multiple targets Deciding what to build in and what not to build in Managing dependencies between components Fortunately, solutions addressing these very issues can be found in source package management systems in higher level languages such as Javascript \n(Node), Go, PHP and Ruby. We decided to fuse their source management \nsystems with a make system built for embedded systems and create Newt.",
- "title": "Rationale"
- },
- {
- "location": "/newt/newt_intro/#build-system",
- "text": "A good build system must allow the user to take a few common steps while developing embedded applications: Generate full flash images Download debug images to a target board using a debugger Conditionally compile libraries code based upon build settings Newt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop: $ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md \u251c\u2500\u2500 apps \u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml \u2514\u2500\u2500 targets \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files When Newt sees a directory tree that contains a \"project.yml\" file, it is smart enough to recognize it as the base directory of a project, and \nautomatically builds a package tree. It also recognizes two important package directories in the package tree - \"apps\" and \"targets\". More on these directories in Newt Theory of Ops . When Newt builds a target, it recursively resolves all package dependencies, and generates artifacts that are placed in the bin/targets/ target-name /app/apps/ app-name directory, where the bin directory is under the project base directory, target-name is the name of the target, and app-name is the name of the application. For our example my_blinky_sim is the name of the target and blinky is the name of the application. The blinky.elf executable is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree: tree -L 6 bin/\nbin/\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 manifest.json\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 drivers\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 uart\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 repos snip",
- "title": "Build System"
- },
- {
- "location": "/newt/newt_intro/#more-operations-using-newt",
- "text": "Once a target has been built, Newt allows additional operations on the target. load : Download built target to board debug : Open debugger session to target size : Get size of target components create-image : Add image header to the binary image run : Build, create image, load, and finally open a debug session with the target target : Create, delete, configure, and query a target For more details on how Newt works, go to Newt - Theory of Operations .",
- "title": "More operations using Newt"
- },
- {
- "location": "/newt/newt_intro/#source-management-and-repositories",
- "text": "The other major element of the Newt tool is the ability to create reusable source distributions from a collection of code. A project can be a reusable container of source code. In other words, projects can be versioned and redistributed, not packages. A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack. A project that has been made redistributable is known as a repository . \nRepositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky project's yml file which relies on apache-mynewt-core: $ more project.yml snip \nproject.repositories:\n - apache-mynewt-core\n\n# Use github s distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core When you specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies: $ newt install\nDownloading repository description for apache-mynewt-core... success!\nDownloading repository incubator-mynewt-core (branch: develop) at \nhttps://github.com/apache/incubator-mynewt-core.git\nCloning into /var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459 ...\nremote: Counting objects: 17601, done.\nremote: Compressing objects: 100% (300/300), done.\nremote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284\nReceiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.\nResolving deltas: 100% (10347/10347), done.\nChecking connectivity... done.\nRepos successfully installed Newt will install this repository in the /repos directory. In the case of blinky, the directory structure ends up looking like: $ tree -L 2\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u2500\u2500 blinky\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502 \u2514\u2500\u2500 apache-mynewt-core\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2514\u2500\u2500 unittest In order to reference the installed repositories in packages, the \"@\" notation should be specified in the repository specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells the build system to look in the base directory of repos/apache-mynewt-core for the kernel/os , hw/hal , and sys/console/full packages. $ more apps/blinky/pkg.yml snip \npkg.deps:\n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/sys/console/full",
- "title": "Source Management and Repositories"
- },
- {
- "location": "/newt/newt_intro/#autocompletion-in-bash",
- "text": "Newt has the ability to autocomplete within bash . The following instructions allow MAC users to enable autocomplete within bash . Install the autocomplete tools for bash via brew install bash-completion Tell your shell to use newt for autocompletion of newt via complete -C \"newt complete\" newt . You can add this to your .bashrc or other init file to have it automatically set for all bash shells. Notes: Autocomplete will give you flag hints, but only if you type a '-'. Autocomplete will not give you completion hints for the flag arguments (those optional things after the flag like -l DEBUG ) Autocomplete uses newt to parse the project to find targets and libs.",
- "title": "Autocompletion in Bash"
- },
- {
- "location": "/newt/newt_operation/",
- "text": "Newt Tool - Theory of Operations\n\n\nNewt has a fairly smart package manager that can read a directory tree, build a dependency tree, and emit the right build artifacts.\n\n\nBuilding dependencies\n\n\nNewt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop:\n\n\n$ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\n\u251c\u2500\u2500 apps\n\n\u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml\n\n\u2514\u2500\u2500 targets\n\n \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files\n\n\n\n\n\n\n\nWhen newt sees a directory tree that contains a \"project.yml\" file it knows that it is in the base directory of a project, and automatically builds a package tree. You can see that there are two essential package directories, \"apps\" and \"targets.\" \n\n\n\n\n\"apps\" Package Directory\n\n\napps\n is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called \nblinky\n in the \napps\n directory. The core repository \n@apache-mynewt-core\n comes with many additional sample apps in its \napps\n directory. At the time of this writing, there are several example BLE apps, the boot app, slinky app for using newt manager protocol, and more in that directory.\n\n\n@~/dev/myproj$ ls repos/apache-mynewt-core/apps/\nblecent blesplit boot sensors_test splitty\nblehci bletest fat2native slinky test\nbleprph bletiny ffs2native slinky_oic testbench\nbleprph_oic bleuart ocf_sample spitest timtest\n\n\n\n\n\nAlong with the \ntargets\n directory, \napps\n represents the top-level of the build tree for the particular project, and define the dependencies for the rest of the system. Mynewt users and developers can add their own apps to the project's \napps\n directory. \n\n\nThe app definition is contained in a \npkg.yml\n file. For example, blinky's \npkg.yml\n file is:\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: \nApache Mynewt \ndev@mynewt.incubator.apache.org\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps:\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/sys/console/full\n\n\n\n\n\n\n\n\nThis file says that the name of the package is apps/blinky, and it depends on the \nkernel/os,\nhw/hal\nand\nsys/console/full` packages.\n\n\nNOTE:\n @apache-mynewt-core is a repository descriptor, and this will be \ncovered in the \"repository\" section. \n\n\n\n\n\"targets\" Package Directory\n\n\ntargets\n is where targets are stored, and each target is a collection of parameters that must be passed to newt in order to generate a reproducible build. Along with the \napps\n directory, \ntargets\n represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies.\n\n\nMost targets consist of:\n\n\n\n\napp: The application to build\n\n\nbsp: The board support package to combine with that application\n\n\nbuild_profile: Either debug or optimized.\n\n\n\n\nThe \nmy_blinky_sim\n target that is included by default has the following settings:\n\n\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n$ ls targets/my_blinky_sim/\npkg.yml target.yml\n\n\n\n\n\nThere are helper functions to aid the developer specify parameters for a target. \n\n\n\n\nvals\n: Displays all valid values for the specified parameter type (e.g. bsp for a target)\n\n\ntarget show\n: Displays the variable values for either a specific target or all targets defined for the project\n\n\ntarget set\n: Sets values for target variables\n\n\n\n\nIn general, the three basic parameters of a target (\napp\n, \nbsp\n, and \nbuild_profile\n) are stored in the target's \ntarget.yml\n file in the targets/\ntarget-name\n directory, where \ntarget-name\n is the name of the target. You will also see a \npkg.yml\n file in the same directory. Since targets are packages, a \npkg.yml\n is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following:\n\n\n\n\nCflags: Any additional compiler flags you might want to specify to the build\n\n\nAflags: Any additional assembler flags you might want to specify to the build\n\n\nLflags: Any additional linker flags you might want to specify to the build\n\n\n\n\nYou can also override the values of the system configuration settings that are defined by the packages that your target includes. You override the values in your target's \nsyscfg.yml\n file (stored in the targets/\ntarget-name\n directory). You can use the \nnewt target config show\n command to see the configuration settings and values for your target, and use the \nnewt target set\n command to set the \nsyscfg\n variable and override the configuration setting values. You can also use an editor to create your target's \nsyscfg.yml\n file and add the setting values to the file. See \nSystem Configuration And Initialization\n for more information on system configuration settings.\n\n\n\n\nResolving dependencies\n\n\nWhen newt builds a project, it will:\n\n\n\n\nfind the top-level project.yml file\n\n\nrecurse the packages in the package tree, and build a list of all \nsource packages\n\n\n\n\nNewt then looks at the target that the user set, for example, blinky_sim:\n\n\n$ more targets/my_blinky_sim/\npkg.yml target.yml\n$ more targets/my_blinky_sim/target.yml\n### Target: targets/my_blinky_sim\ntarget.app: \napps/blinky\n\ntarget.bsp: \n@apache-mynewt-core/hw/bsp/native\n\ntarget.build_profile: \ndebug\n\n\n\n\n\n\n\n\nThe target specifies two major things:\n\n\n\n\nApplication (target.app): The application to build\n\n\nBoard Support Package (target.bsp): The board support package to build \nalong with that application.\n\n\n\n\nNewt builds the dependency tree specified by all the packages. While building this tree, it does a few other things:\n\n\n\n\nSets up the include paths for each package. Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nnewt structure must always be prefixed by the package name. For example, kernel/os has the following include tree and its include directory files contains the package name \"os\" before any header files. This is so in order to avoid any header file conflicts.\n\n\n\n\n$tree kernel/os/include\nkernel/os/include\n\u2514\u2500\u2500 os\n \u251c\u2500\u2500 arch\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m0\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m4\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 mips\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 sim\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 sim-mips\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u251c\u2500\u2500 endian.h\n \u251c\u2500\u2500 os.h\n \u251c\u2500\u2500 os_callout.h\n \u251c\u2500\u2500 os_cfg.h\n \u251c\u2500\u2500 os_cputime.h\n \u251c\u2500\u2500 os_dev.h\n \u251c\u2500\u2500 os_eventq.h\n \u251c\u2500\u2500 os_fault.h\n \u251c\u2500\u2500 os_heap.h\n \u251c\u2500\u2500 os_malloc.h\n \u251c\u2500\u2500 os_mbuf.h\n \u251c\u2500\u2500 os_mempool.h\n \u251c\u2500\u2500 os_mutex.h\n \u251c\u2500\u2500 os_sanity.h\n \u251c\u2500\u2500 os_sched.h\n \u251c\u2500\u2500 os_sem.h\n \u251c\u2500\u2500 os_task.h\n \u251c\u2500\u2500 os_test.h\n \u251c\u2500\u2500 os_time.h\n \u2514\u2500\u2500 queue.h\n\n\nsnip\n\n\n\n\n\n\n\n\n\n\n\n\nValidates API requirements. Packages can export APIs they \nimplement, (i.e. pkg.api: hw-hal-impl), and other packages can require \nthose APIs (i.e. pkg.req_api: hw-hal-impl).\n\n\n\n\n\n\nReads and validates the configuration setting definitions and values from the package \nsyscfg.yml\n files.\nIt generates a \nsyscfg.h\n header file that packages include in the source files in order to access the settings.\n\nIt also generates a system initialization function to initialize the packages.\nSee \nSystem Configuration And Initialization\n for more information.\n\n\n\n\n\n\nIn order to properly resolve all dependencies in the build system, newt recursively processes the package dependencies until there are no new dependencies. And it builds a big list of all the packages that need to be build.\n\n\nNewt then goes through this package list, and builds every package into \nan archive file.\n\n\nNOTE:\n The newt tool generates compiler dependencies for all of these packages, and only rebuilds the packages whose dependencies have changed. Changes in package \n project dependencies are also taken into account. It is smart, after all!\n\n\nProducing artifacts\n\n\nOnce newt has built all the archive files, it then links the archive files together. The linkerscript to use is specified by the board support package (BSP.)\n\n\nThe newt tool creates a bin directory under the base project directory, and places a target's build artifacts into the bin/targets/\ntarget-name\n/app/apps/\napp-name\n directory, where \ntarget-name\n is the name of the target and \napp-name\n is the name of the application. As an example, the \nblinky.elf\n executable for the \nblinky\n application defined by the \nmy_blinky_sim\n target is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the following source tree:\n\n\n$tree -L 9 bin/ bin/\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.d\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.o\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.o.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Contents\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 Info.plist\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Resources\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 DWARF\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 manifest.json\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_bsp_native.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_bsp_native.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 repos\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 apache-mynewt-core\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 hw\n\n\nsnip\n\n\n\n\n\n\n\n\nAs you can see, a number of files are generated:\n\n\n\n\nArchive File\n\n\n*.cmd: The command use to generate the object or archive file\n\n\n*.lst: The list file where symbols are located\n\n\n\n\nNote: The *.o object files that get put into the archive file are stored in the bin/targets/my_blinky_sim/app/apps/blinky/apps/blinky/src directory.\n\n\nDownload/Debug Support\n\n\nOnce a target has been build, there are a number of helper functions \nthat work on the target. These are:\n\n\n\n\nload\n Download built target to board\n\n\ndebug\n Open debugger session to target\n\n\nsize\n Size of target components\n\n\ncreate-image\n Add image header to target binary\n\n\nrun\n The equivalent of build, create-image, load, and debug on specified target\n\n\ntarget\n Create, delete, configure, and query a target\n\n\n\n\nload\n and \ndebug\n handles driving GDB and the system debugger. These \ncommands call out to scripts that are defined by the BSP.\n\n\n$ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh\n\nsnip\n\n. $CORE_PATH/hw/scripts/jlink.sh\n\nFILE_NAME=$BIN_BASENAME.elf\n\nif [ $# -gt 2 ]; then\n SPLIT_ELF_NAME=$3.elf\n # TODO -- this magic number 0x42000 is the location of the second image\n # slot. we should either get this from a flash map file or somehow learn\n # this from the image itself\n EXTRA_GDB_CMDS=\nadd-symbol-file $SPLIT_ELF_NAME 0x8000 -readnow\n\nfi\n\nJLINK_DEV=\nnRF52\n\n\njlink_debug\n\n\n\n\n\nThe idea is that every BSP will add support for the debugger environment \nfor that board. That way common tools can be used across various development boards and kits.",
- "title": "Newt Theory of Ops"
- },
- {
- "location": "/newt/newt_operation/#newt-tool-theory-of-operations",
- "text": "Newt has a fairly smart package manager that can read a directory tree, build a dependency tree, and emit the right build artifacts.",
- "title": "Newt Tool - Theory of Operations"
- },
- {
- "location": "/newt/newt_operation/#building-dependencies",
- "text": "Newt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop: $ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md \u251c\u2500\u2500 apps \u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml \u2514\u2500\u2500 targets \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files When newt sees a directory tree that contains a \"project.yml\" file it knows that it is in the base directory of a project, and automatically builds a package tree. You can see that there are two essential package directories, \"apps\" and \"targets.\"",
- "title": "Building dependencies"
- },
- {
- "location": "/newt/newt_operation/#apps-package-directory",
- "text": "apps is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called blinky in the apps directory. The core repository @apache-mynewt-core comes with many additional sample apps in its apps directory. At the time of this writing, there are several example BLE apps, the boot app, slinky app for using newt manager protocol, and more in that directory. @~/dev/myproj$ ls repos/apache-mynewt-core/apps/\nblecent blesplit boot sensors_test splitty\nblehci bletest fat2native slinky test\nbleprph bletiny ffs2native slinky_oic testbench\nbleprph_oic bleuart ocf_sample spitest timtest Along with the targets directory, apps represents the top-level of the build tree for the particular project, and define the dependencies for the rest of the system. Mynewt users and developers can add their own apps to the project's apps directory. The app definition is contained in a pkg.yml file. For example, blinky's pkg.yml file is: $ more apps/blinky/pkg.yml snip \npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: Apache Mynewt dev@mynewt.incubator.apache.org \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n\npkg.deps:\n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/sys/console/full This file says that the name of the package is apps/blinky, and it depends on the kernel/os, hw/hal and sys/console/full` packages. NOTE: @apache-mynewt-core is a repository descriptor, and this will be \ncovered in the \"repository\" section.",
- "title": "\"apps\" Package Directory"
- },
- {
- "location": "/newt/newt_operation/#targets-package-directory",
- "text": "targets is where targets are stored, and each target is a collection of parameters that must be passed to newt in order to generate a reproducible build. Along with the apps directory, targets represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies. Most targets consist of: app: The application to build bsp: The board support package to combine with that application build_profile: Either debug or optimized. The my_blinky_sim target that is included by default has the following settings: $ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n$ ls targets/my_blinky_sim/\npkg.yml target.yml There are helper functions to aid the developer specify parameters for a target. vals : Displays all valid values for the specified parameter type (e.g. bsp for a target) target show : Displays the variable values for either a specific target or all targets defined for the project target set : Sets values for target variables In general, the three basic parameters of a target ( app , bsp , and build_profile ) are stored in the target's target.yml file in the targets/ target-name directory, where target-name is the name of the target. You will also see a pkg.yml file in the same directory. Since targets are packages, a pkg.yml is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following: Cflags: Any additional compiler flags you might want to specify to the build Aflags: Any additional assembler flags you might want to specify to the build Lflags: Any additional linker flags you might want to specify to the build You can also override the values of the system configuration settings that are defined by the packages that your target includes. You override the values in your target's syscfg.yml file (stored in the targets/ target-name directory). You can use the newt target config show command to see the configuration settings and values for your target, and use the newt target set command to set the syscfg variable and override the configuration setting values. You can also use an editor to create your target's syscfg.yml file and add the setting values to the file. See System Configuration And Initialization for more information on system configuration settings.",
- "title": "\"targets\" Package Directory"
- },
- {
- "location": "/newt/newt_operation/#resolving-dependencies",
- "text": "When newt builds a project, it will: find the top-level project.yml file recurse the packages in the package tree, and build a list of all \nsource packages Newt then looks at the target that the user set, for example, blinky_sim: $ more targets/my_blinky_sim/\npkg.yml target.yml\n$ more targets/my_blinky_sim/target.yml\n### Target: targets/my_blinky_sim\ntarget.app: apps/blinky \ntarget.bsp: @apache-mynewt-core/hw/bsp/native \ntarget.build_profile: debug The target specifies two major things: Application (target.app): The application to build Board Support Package (target.bsp): The board support package to build \nalong with that application. Newt builds the dependency tree specified by all the packages. While building this tree, it does a few other things: Sets up the include paths for each package. Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nnewt structure must always be prefixed by the package name. For example, kernel/os has the following include tree and its include directory files contains the package name \"os\" before any header files. This is so in order to avoid any header file conflicts. $tree kernel/os/include\nkernel/os/include\n\u2514\u2500\u2500 os\n \u251c\u2500\u2500 arch\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m0\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m4\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 mips\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 sim\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 sim-mips\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u251c\u2500\u2500 endian.h\n \u251c\u2500\u2500 os.h\n \u251c\u2500\u2500 os_callout.h\n \u251c\u2500\u2500 os_cfg.h\n \u251c\u2500\u2500 os_cputime.h\n \u251c\u2500\u2500 os_dev.h\n \u251c\u2500\u2500 os_eventq.h\n \u251c\u2500\u2500 os_fault.h\n \u251c\u2500\u2500 os_heap.h\n \u251c\u2500\u2500 os_malloc.h\n \u251c\u2500\u2500 os_mbuf.h\n \u251c\u2500\u2500 os_mempool.h\n \u251c\u2500\u2500 os_mutex.h\n \u251c\u2500\u2500 os_sanity.h\n \u251c\u2500\u2500 os_sched.h\n \u251c\u2500\u2500 os_sem.h\n \u251c\u2500\u2500 os_task.h\n \u251c\u2500\u2500 os_test.h\n \u251c\u2500\u2500 os_time.h\n \u2514\u2500\u2500 queue.h snip Validates API requirements. Packages can export APIs they \nimplement, (i.e. pkg.api: hw-hal-impl), and other packages can require \nthose APIs (i.e. pkg.req_api: hw-hal-impl). Reads and validates the configuration setting definitions and values from the package syscfg.yml files.\nIt generates a syscfg.h header file that packages include in the source files in order to access the settings. \nIt also generates a system initialization function to initialize the packages.\nSee System Configuration And Initialization for more information. In order to properly resolve all dependencies in the build system, newt recursively processes the package dependencies until there are no new dependencies. And it builds a big list of all the packages that need to be build. Newt then goes through this package list, and builds every package into \nan archive file. NOTE: The newt tool generates compiler dependencies for all of these packages, and only rebuilds the packages whose dependencies have changed. Changes in package project dependencies are also taken into account. It is smart, after all!",
- "title": "Resolving dependencies"
- },
- {
- "location": "/newt/newt_operation/#producing-artifacts",
- "text": "Once newt has built all the archive files, it then links the archive files together. The linkerscript to use is specified by the board support package (BSP.) The newt tool creates a bin directory under the base project directory, and places a target's build artifacts into the bin/targets/ target-name /app/apps/ app-name directory, where target-name is the name of the target and app-name is the name of the application. As an example, the blinky.elf executable for the blinky application defined by the my_blinky_sim target is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the following source tree: $tree -L 9 bin/ bin/\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 src\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.d\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.o\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.o.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Contents\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 Info.plist\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Resources\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 DWARF\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 manifest.json\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_bsp_native.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_bsp_native.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 repos\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 apache-mynewt-core\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 hw snip As you can see, a number of files are generated: Archive File *.cmd: The command use to generate the object or archive file *.lst: The list file where symbols are located Note: The *.o object files that get put into the archive file are stored in the bin/targets/my_blinky_sim/app/apps/blinky/apps/blinky/src directory.",
- "title": "Producing artifacts"
- },
- {
- "location": "/newt/newt_operation/#downloaddebug-support",
- "text": "Once a target has been build, there are a number of helper functions \nthat work on the target. These are: load Download built target to board debug Open debugger session to target size Size of target components create-image Add image header to target binary run The equivalent of build, create-image, load, and debug on specified target target Create, delete, configure, and query a target load and debug handles driving GDB and the system debugger. These \ncommands call out to scripts that are defined by the BSP. $ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh snip \n. $CORE_PATH/hw/scripts/jlink.sh\n\nFILE_NAME=$BIN_BASENAME.elf\n\nif [ $# -gt 2 ]; then\n SPLIT_ELF_NAME=$3.elf\n # TODO -- this magic number 0x42000 is the location of the second image\n # slot. we should either get this from a flash map file or somehow learn\n # this from the image itself\n EXTRA_GDB_CMDS= add-symbol-file $SPLIT_ELF_NAME 0x8000 -readnow \nfi\n\nJLINK_DEV= nRF52 \n\njlink_debug The idea is that every BSP will add support for the debugger environment \nfor that board. That way common tools can be used across various development boards and kits.",
- "title": "Download/Debug Support"
- },
- {
- "location": "/newt/newt_ops/",
- "text": "Command Structure\n\n\nJust like verbs are actions in a sentence and adverbs modifiy verbs, so in the \nnewt\n tool, commands are actions and flags modify actions. A command can have subcommands. Arguments to commands and subcommands, with appropriate flags, dictate the execution and result of a command. \n\n\nFor instance, in the example below, the \nnewt\n command has the subcommand \ntarget set\n in which the argument 'my_target1' is the target whose attribute, \napp\n, is set to '@apache-mynewt-core/hw/bsp/nrf52dk'\n\n\n newt target set my_target1 app=@apache-mynewt-core/hw/bsp/nrf52dk\n\n\n\n\n\nGlobal flags work uniformly across \nnewt\n commands. Consider the flag \n-v, --verbose,\n It works both for command and subcommands, to generate verbose output. Likewise, the help flag \n-h\n or \n--help,\n to print helpful messsages.\n\n\nA command may additionally take flags specific to it. For example, the \n-n\n flag instructs \nnewt debug\n not to start GDB from command line.\n\n\n newt debug \ntarget-name\n -n\n\n\n\n\n\nIn addition to the \nNewt Tool Manual\n in docs, command-line help is available for each command (and subcommand), through the \n-h\n or \n--help\n options. \n\n\n newt target --help\n Commands to create, delete, configure, and query targets\n\n Usage:\n newt target [flags]\n newt target [command]\n\n Available Commands:\n amend Add, change, or delete values for multi-value target variables\n config View or populate a target\ns system configuration\n copy Copy target\n create Create a target\n delete Delete target\n dep View target\ns dependency graph\n revdep View target\ns reverse-dependency graph\n set Set target configuration variable\n show View target configuration variables\n\n Global Flags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n Use \nnewt target [command] --help\n for more information about a command.",
- "title": "toc"
- },
- {
- "location": "/newt/newt_ops/#command-structure",
- "text": "Just like verbs are actions in a sentence and adverbs modifiy verbs, so in the newt tool, commands are actions and flags modify actions. A command can have subcommands. Arguments to commands and subcommands, with appropriate flags, dictate the execution and result of a command. For instance, in the example below, the newt command has the subcommand target set in which the argument 'my_target1' is the target whose attribute, app , is set to '@apache-mynewt-core/hw/bsp/nrf52dk' newt target set my_target1 app=@apache-mynewt-core/hw/bsp/nrf52dk Global flags work uniformly across newt commands. Consider the flag -v, --verbose, It works both for command and subcommands, to generate verbose output. Likewise, the help flag -h or --help, to print helpful messsages. A command may additionally take flags specific to it. For example, the -n flag instructs newt debug not to start GDB from command line. newt debug target-name -n In addition to the Newt Tool Manual in docs, command-line help is available for each command (and subcommand), through the -h or --help options. newt target --help\n Commands to create, delete, configure, and query targets\n\n Usage:\n newt target [flags]\n newt target [command]\n\n Available Commands:\n amend Add, change, or delete values for multi-value target variables\n config View or populate a target s system configuration\n copy Copy target\n create Create a target\n delete Delete target\n dep View target s dependency graph\n revdep View target s reverse-dependency graph\n set Set target configuration variable\n show View target configuration variables\n\n Global Flags:\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands\n\n Use newt target [command] --help for more information about a command.",
- "title": "Command Structure"
- },
- {
- "location": "/newt/command_list/newt_build/",
- "text": "newt build \n\n\nBuild one or more targets. \n\n\nUsage:\n\n\n newt build \ntarget-name\n [target_name ...] [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nCompiles, links, and builds an ELF binary for the target named \ntarget-name\n. It builds an ELF file for the application specified by the \napp\n variable for the \ntarget-name\n target. The image can be loaded and run on the hardware specified by the \nbsp\n variable for the target. The command creates the 'bin/' directory under the project's base directory (that the \nnewt new\n command created) and stores the executable in the 'bin/targets/\ntarget-name\n/app/apps/\napp-name\n' directory.\n\n\nYou can specify a list of target names, separated by a space, to build multiple targets. \n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt build \n my_blinky_sim\n\n\nBuilds an executable for the \nmy_blinky_sim\n target. For example, if the \nmy_blinky_sim\n target has \napp\n set to \napps/blinky\n, you will find the generated .elf, .a, and .lst files in the 'bin/targets/my_blinky_sim/app/apps/blinky' directory.\n\n\n\n\n\n\n\n\nnewt build \n my_blinky_sim myble\n\n\nBuilds the images for the applications defined by the \nmy_blinky_sim\n and \nmyble\n targets.",
- "title": "newt build"
- },
- {
- "location": "/newt/command_list/newt_build/#newt-build",
- "text": "Build one or more targets.",
- "title": "newt build "
- },
- {
- "location": "/newt/command_list/newt_build/#usage",
- "text": "newt build target-name [target_name ...] [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_build/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_build/#description",
- "text": "Compiles, links, and builds an ELF binary for the target named target-name . It builds an ELF file for the application specified by the app variable for the target-name target. The image can be loaded and run on the hardware specified by the bsp variable for the target. The command creates the 'bin/' directory under the project's base directory (that the newt new command created) and stores the executable in the 'bin/targets/ target-name /app/apps/ app-name ' directory. You can specify a list of target names, separated by a space, to build multiple targets.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_build/#examples",
- "text": "Sub-command Usage Explanation newt build my_blinky_sim Builds an executable for the my_blinky_sim target. For example, if the my_blinky_sim target has app set to apps/blinky , you will find the generated .elf, .a, and .lst files in the 'bin/targets/my_blinky_sim/app/apps/blinky' directory. newt build my_blinky_sim myble Builds the images for the applications defined by the my_blinky_sim and myble targets.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_clean/",
- "text": "newt clean \n\n\nDelete build artifacts for one or more targets. \n\n\nUsage:\n\n\n newt clean \ntarget-name\n [target-name...] | all [flags]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nDeletes all the build artifacts generated for the \ntarget-name\n target. It does not delete the target definition. You can specify a list of targets, separated by a space, to delete the artifacts for multiple targets, or specify \nall\n to delete the artifacts for all targets.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt clean myble\n\n\nDeletes the 'bin/targets/myble' directory where all the build artifacts generated from the \nmyble\n target build are stored.\n\n\n\n\n\n\n\n\nnewt clean my_blinky_sim myble\n\n\nDeletes the 'bin/targets/my_blinky_sim' and the 'bin/targets/myble' directories where all the artifacts generated from the \nmy_blinky_sim\n and \nmyble\n target builds are stored.\n\n\n\n\n\n\n\n\nnewt clean all\n\n\nRemoves the artifacts for all target builds. Deletes the top level 'bin' directory.",
- "title": "newt clean"
- },
- {
- "location": "/newt/command_list/newt_clean/#newt-clean",
- "text": "Delete build artifacts for one or more targets.",
- "title": "newt clean "
- },
- {
- "location": "/newt/command_list/newt_clean/#usage",
- "text": "newt clean target-name [target-name...] | all [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_clean/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_clean/#description",
- "text": "Deletes all the build artifacts generated for the target-name target. It does not delete the target definition. You can specify a list of targets, separated by a space, to delete the artifacts for multiple targets, or specify all to delete the artifacts for all targets.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_clean/#examples",
- "text": "Sub-command Usage Explanation newt clean myble Deletes the 'bin/targets/myble' directory where all the build artifacts generated from the myble target build are stored. newt clean my_blinky_sim myble Deletes the 'bin/targets/my_blinky_sim' and the 'bin/targets/myble' directories where all the artifacts generated from the my_blinky_sim and myble target builds are stored. newt clean all Removes the artifacts for all target builds. Deletes the top level 'bin' directory.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_create_image/",
- "text": "newt create-image \n\n\nCreate and sign an image by adding an image header to the binary file created for a target. Version number in the header is set to \nversion\n. To sign an image provide a .pem file for the signing-key and an optional key-id.\n\n\nUsage:\n\n\n newt create-image \ntarget-name\n \nversion\n [signing-key [key-id]][flags]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nAdds an image header to the created binary file for the \ntarget-name\n target. The image version is set to \nversion\n. It creates a \napp-name\n.img\n file for the image, where \napp-name\n is the value specified in the target \napp\n variable, and stores the file in the '/bin/targets/\ntarget-name\n/app/apps/\napp-name\n/' directory. A \nmanifest.json\n build manifest file is also generated in the same directory. This build manifest contains information such as build time, version, image name, a hash to identify the image, packages actually used to create the build, and the target for which the image is built.\n\n\nTo sign an image, provide a .pem file for the \nsigning-key\n and an optional \nkey-id\n. \nkey-id\n must be a value between 0-255.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt create-image myble2 1.0.1.0\n\n\nCreates an image for target \nmyble2\n and assigns it version \n1.0.1.0\n. \n \n For the following target definition: \n targets/myble2 \n app=@apache-mynewt-core/apps/bletiny \n bsp=@apache-mynewt-core/hw/bsp/nrf52pdk \n build_profile=optimized \n cflags=-DSTATS_NAME_ENABLE \n \n the created image is 'bin/targets/myble2/app/apps/bletiny/bletiny.img' and the manifest is 'bin/targets/myble2/app/apps/bletiny/manifest.json'\n\n\n\n\n\n\n\n\nnewt create-image myble2 1.0.1.0 private.pem\n\n\nCreates an image for target \nmyble2\n and assigns it the version \n1.0.1.0\n. Signs the image using private key specified by the private.pem file.",
- "title": "newt create-image"
- },
- {
- "location": "/newt/command_list/newt_create_image/#newt-create-image",
- "text": "Create and sign an image by adding an image header to the binary file created for a target. Version number in the header is set to version . To sign an image provide a .pem file for the signing-key and an optional key-id.",
- "title": "newt create-image "
- },
- {
- "location": "/newt/command_list/newt_create_image/#usage",
- "text": "newt create-image target-name version [signing-key [key-id]][flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_create_image/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_create_image/#description",
- "text": "Adds an image header to the created binary file for the target-name target. The image version is set to version . It creates a app-name .img file for the image, where app-name is the value specified in the target app variable, and stores the file in the '/bin/targets/ target-name /app/apps/ app-name /' directory. A manifest.json build manifest file is also generated in the same directory. This build manifest contains information such as build time, version, image name, a hash to identify the image, packages actually used to create the build, and the target for which the image is built. To sign an image, provide a .pem file for the signing-key and an optional key-id . key-id must be a value between 0-255.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_create_image/#examples",
- "text": "Sub-command Usage Explanation newt create-image myble2 1.0.1.0 Creates an image for target myble2 and assigns it version 1.0.1.0 . For the following target definition: targets/myble2 app=@apache-mynewt-core/apps/bletiny bsp=@apache-mynewt-core/hw/bsp/nrf52pdk build_profile=optimized cflags=-DSTATS_NAME_ENABLE the created image is 'bin/targets/myble2/app/apps/bletiny/bletiny.img' and the manifest is 'bin/targets/myble2/app/apps/bletiny/manifest.json' newt create-image myble2 1.0.1.0 private.pem Creates an image for target myble2 and assigns it the version 1.0.1.0 . Signs the image using private key specified by the private.pem file.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_debug/",
- "text": "newt debug \n\n\nOpen a debugger session to a target. \n\n\nUsage:\n\n\n newt debug \ntarget-name\n [flag]\n\n\n\n\n\nFlags:\n\n\n --extrajtagcmd string Extra commands to send to JTAG software\n -n, --noGDB Do not start GDB from command line\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nOpens a debugger session to the image built for the \ntarget-name\n target.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt debug myble2\n\n\nOpens a J-Link connection and starts a GNU gdb session to debug bin/targets/myble2/app/apps/bletiny/bletiny.elf when the target is as follows: \n \n targets/myble2 \n app=@apache-mynewt-core/apps/bletiny \n bsp=@apache-mynewt-core/hw/bsp/nrf52pdk \n build_profile=optimized \n cflags=-DSTATS_NAME_ENABLE\n\n\n\n\n\n\n\n\nnewt debug myble2 -n\n\n\nOpens a J-Link connection bin/targets/myble2/app/apps/bletiny/bletiny.elf but do not start GDB on the command line.",
- "title": "newt debug"
- },
- {
- "location": "/newt/command_list/newt_debug/#newt-debug",
- "text": "Open a debugger session to a target.",
- "title": "newt debug "
- },
- {
- "location": "/newt/command_list/newt_debug/#usage",
- "text": "newt debug target-name [flag]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_debug/#flags",
- "text": "--extrajtagcmd string Extra commands to send to JTAG software\n -n, --noGDB Do not start GDB from command line",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_debug/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_debug/#description",
- "text": "Opens a debugger session to the image built for the target-name target.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_debug/#examples",
- "text": "Sub-command Usage Explanation newt debug myble2 Opens a J-Link connection and starts a GNU gdb session to debug bin/targets/myble2/app/apps/bletiny/bletiny.elf when the target is as follows: targets/myble2 app=@apache-mynewt-core/apps/bletiny bsp=@apache-mynewt-core/hw/bsp/nrf52pdk build_profile=optimized cflags=-DSTATS_NAME_ENABLE newt debug myble2 -n Opens a J-Link connection bin/targets/myble2/app/apps/bletiny/bletiny.elf but do not start GDB on the command line.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_help/",
- "text": "newt help \n\n\nDisplay the help text for the newt command line tool:\n\n\nNewt allows you to create your own embedded application based on the Mynewt \noperating system. Newt provides both build and package management in a single \ntool, which allows you to compose an embedded application, and set of \nprojects, and then build the necessary artifacts from those projects. For more \ninformation on the Mynewt operating system, please visit \nhttps://mynewt.apache.org/. \n\n\n\n\n\nUsage:\n\n\n newt help [command]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nAvailable Commands:\n\n\n build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug \ntarget\n\n size Size of target components\n sync Synchronize project dependencies\n target Command for manipulating targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt help target\n\n\nDisplays the help text for the newt \ntarget\n command\n\n\n\n\n\n\n\n\nnewt help\n\n\nDisplays the help text for newt tool",
- "title": "newt help"
- },
- {
- "location": "/newt/command_list/newt_help/#newt-help",
- "text": "Display the help text for the newt command line tool: Newt allows you to create your own embedded application based on the Mynewt \noperating system. Newt provides both build and package management in a single \ntool, which allows you to compose an embedded application, and set of \nprojects, and then build the necessary artifacts from those projects. For more \ninformation on the Mynewt operating system, please visit \nhttps://mynewt.apache.org/.",
- "title": "newt help "
- },
- {
- "location": "/newt/command_list/newt_help/#usage",
- "text": "newt help [command]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_help/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_help/#available-commands",
- "text": "build Build one or more targets\n clean Delete build artifacts for one or more targets\n create-image Add image header to target binary\n debug Open debugger session to target\n info Show project info\n install Install project dependencies\n load Load built target to board\n mfg Manufacturing flash image commands\n new Create a new project\n pkg Create and manage packages in the current workspace\n run build/create-image/download/debug target \n size Size of target components\n sync Synchronize project dependencies\n target Command for manipulating targets\n test Executes unit tests for one or more packages\n upgrade Upgrade project dependencies\n vals Display valid values for the specified element type(s)\n version Display the Newt version number",
- "title": "Available Commands:"
- },
- {
- "location": "/newt/command_list/newt_help/#examples",
- "text": "Sub-command Usage Explanation newt help target Displays the help text for the newt target command newt help Displays the help text for newt tool",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_info/",
- "text": "newt info \n\n\nShow information about the current project.\n\n\nUsage:\n\n\n newt info [flags]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nDisplays the repositories in the current project (the local as well as all the external repositories fetched). It also displays the packages in the local repository.",
- "title": "newt info"
- },
- {
- "location": "/newt/command_list/newt_info/#newt-info",
- "text": "Show information about the current project.",
- "title": "newt info "
- },
- {
- "location": "/newt/command_list/newt_info/#usage",
- "text": "newt info [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_info/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_info/#description",
- "text": "Displays the repositories in the current project (the local as well as all the external repositories fetched). It also displays the packages in the local repository.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_install/",
- "text": "newt install \n\n\nInstall project dependencies. \n\n\nUsage:\n\n\n newt install [flags]\n\n\n\n\n\nFlags:\n\n\n -f, --force Force install of the repositories in project, regardless of what exists in repos directory\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nThis command downloads the description for all the repositories specified in the \nproject.yml\n file for the current project, and installs the correct versions of all the packages specified by the project dependencies. \n\n\nYou must run this command from within the current project directory. (Remember to \ncd\n into this project directory after you use \nnewt new\n to create this project before you run \nnewt install\n.)",
- "title": "newt install"
- },
- {
- "location": "/newt/command_list/newt_install/#newt-install",
- "text": "Install project dependencies.",
- "title": "newt install "
- },
- {
- "location": "/newt/command_list/newt_install/#usage",
- "text": "newt install [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_install/#flags",
- "text": "-f, --force Force install of the repositories in project, regardless of what exists in repos directory",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_install/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_install/#description",
- "text": "This command downloads the description for all the repositories specified in the project.yml file for the current project, and installs the correct versions of all the packages specified by the project dependencies. You must run this command from within the current project directory. (Remember to cd into this project directory after you use newt new to create this project before you run newt install .)",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_load/",
- "text": "newt load \n\n\nLoad application image onto the board for a target. \n\n\nUsage:\n\n\n newt load \ntarget-name\n [flags]\n\n\n\n\n\nFlags:\n\n\n --extrajtagcmd string Extra commands to send to JTAG software\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nUses download scripts to automatically load, onto the connected board, the image built for the app defined by the \ntarget-name\n target If the wrong board is connected or the target definition is incorrect (i.e. the wrong values are given for bsp or app), the command will fail with error messages such as \nCan not connect to J-Link via USB\n or \nUnspecified error -1\n.",
- "title": "newt load"
- },
- {
- "location": "/newt/command_list/newt_load/#newt-load",
- "text": "Load application image onto the board for a target.",
- "title": "newt load "
- },
- {
- "location": "/newt/command_list/newt_load/#usage",
- "text": "newt load target-name [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_load/#flags",
- "text": "--extrajtagcmd string Extra commands to send to JTAG software",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_load/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_load/#description",
- "text": "Uses download scripts to automatically load, onto the connected board, the image built for the app defined by the target-name target If the wrong board is connected or the target definition is incorrect (i.e. the wrong values are given for bsp or app), the command will fail with error messages such as Can not connect to J-Link via USB or Unspecified error -1 .",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_mfg/",
- "text": "newt mfg \n\n\nCommands to create, build, and upload manufacturing image. \n\n\nUsage:\n\n\n newt mfg [flags]\n newt mfg [command]\n\n\n\n\n\nAvailable Commands:\n\n\n create Create a manufacturing flash image\n deploy Build and upload a manufacturing image (build + load)\n load Load a manufacturing flash image onto a device\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\ncreate\n\n\nA manufacturing image specifies 1) a boot loader target, and 2) one or more image targets. Assuming the manufacturing entity has been created and defined in the \nmfgs/\nmfg image name\n/\n package (see Examples below), this command collects the manufacturing related files in the newly created \nbin/mfgs/\nmfg image name\n directory. The collection includes manifests with the image build time, version, manufacturing package build time, image ID (or hash) etc. It is essentially a snapshot of the image data and metadata uploaded to the device flash at manufacturing time. Note that the command expects the targets and images to have already been built using \nnewt build\n and \nnewt create-image\n commands.\n\n\n\n\n\n\ndeploy\n\n\nA combination of build and load commands to put together and upload manufacturing image on to the device.\n\n\n\n\n\n\nload\n\n\nLoads the manufacturing package onto to the flash of the connected device.\n\n\n\n\n\n\n\n\nExamples\n\n\nSuppose you have created two targets (one for the bootloader and one for the \nblinky\n app). \n\n\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/rb_blinky\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n build_profile=debug\ntargets/rb_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n build_profile=optimized\n\n\n\n\n\nCreate the directory to hold the mfg packages.\n\n\n$ mkdir -p mfgs/rb_blinky_rsa\n\n\n\n\n\nThe \nrb_blinky_rsa\n package needs a pkg.yml file. In addition it is needs a mfg.yml file to specify the two constituent targets. An example of each file is shown below.\n\n\n$ more mfgs/rb_blinky_rsa/pkg.yml \npkg.name: \nmfgs/rb_blinky_rsa\n\npkg.type: \nmfg\n\npkg.description: \npkg.author: \npkg.homepage: \n\n\n\n\n\n$ more mfgs/rb_blinky_rsa/mfg.yml \nmfg.bootloader: \ntargets/rb_boot\n\nmfg.images:\n - \ntargets/rb_blinky\n\n\n\n\n\n\nBuild the bootloader and app images.\n\n\n$ newt build rb_boot\n$ newt create-image rb_blinky 0.0.1\n\n\n\n\n\nRun the \nnewt mfg create\n command to collect all the manufacturing snapshot files.\n\n\n$ newt mfg create rb_blinky_rsa\nCreating a manufacturing image from the following files:\n\nsnip\n\nGenerated the following files:\n\nsnip\n\n$",
- "title": "newt mfg"
- },
- {
- "location": "/newt/command_list/newt_mfg/#newt-mfg",
- "text": "Commands to create, build, and upload manufacturing image.",
- "title": "newt mfg "
- },
- {
- "location": "/newt/command_list/newt_mfg/#usage",
- "text": "newt mfg [flags]\n newt mfg [command]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_mfg/#available-commands",
- "text": "create Create a manufacturing flash image\n deploy Build and upload a manufacturing image (build + load)\n load Load a manufacturing flash image onto a device",
- "title": "Available Commands:"
- },
- {
- "location": "/newt/command_list/newt_mfg/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_mfg/#description",
- "text": "Sub-command Explanation create A manufacturing image specifies 1) a boot loader target, and 2) one or more image targets. Assuming the manufacturing entity has been created and defined in the mfgs/ mfg image name / package (see Examples below), this command collects the manufacturing related files in the newly created bin/mfgs/ mfg image name directory. The collection includes manifests with the image build time, version, manufacturing package build time, image ID (or hash) etc. It is essentially a snapshot of the image data and metadata uploaded to the device flash at manufacturing time. Note that the command expects the targets and images to have already been built using newt build and newt create-image commands. deploy A combination of build and load commands to put together and upload manufacturing image on to the device. load Loads the manufacturing package onto to the flash of the connected device.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_mfg/#examples",
- "text": "Suppose you have created two targets (one for the bootloader and one for the blinky app). $ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\ntargets/rb_blinky\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n build_profile=debug\ntargets/rb_boot\n app=@apache-mynewt-core/apps/boot\n bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n build_profile=optimized Create the directory to hold the mfg packages. $ mkdir -p mfgs/rb_blinky_rsa The rb_blinky_rsa package needs a pkg.yml file. In addition it is needs a mfg.yml file to specify the two constituent targets. An example of each file is shown below. $ more mfgs/rb_blinky_rsa/pkg.yml \npkg.name: mfgs/rb_blinky_rsa \npkg.type: mfg \npkg.description: \npkg.author: \npkg.homepage: $ more mfgs/rb_blinky_rsa/mfg.yml \nmfg.bootloader: targets/rb_boot \nmfg.images:\n - targets/rb_blinky Build the bootloader and app images. $ newt build rb_boot\n$ newt create-image rb_blinky 0.0.1 Run the newt mfg create command to collect all the manufacturing snapshot files. $ newt mfg create rb_blinky_rsa\nCreating a manufacturing image from the following files: snip \nGenerated the following files: snip \n$",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_new/",
- "text": "newt new \n\n\nCreate a new project from a skeleton. Currently, the default skeleton is the \nblinky repository\n in Apache Mynewt (or \nhttps://github.com/apache/incubator-mynewt-blinky\n on its github mirror.)\n\n\nUsage:\n\n\n newt new \nproject-name\n [flags]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nCreates a new project named \nproject-name\n from the default skeleton \nblinky repository\n in Apache Mynewt (or \nhttps://github.com/apache/incubator-mynewt-blinky\n on its github mirror.)\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt new test_project\n\n\nCreates a new project named \ntest_project\n using the default skeleton from the \napache/incubator-mynewt-blinky\n repository.",
- "title": "newt new"
- },
- {
- "location": "/newt/command_list/newt_new/#newt-new",
- "text": "Create a new project from a skeleton. Currently, the default skeleton is the blinky repository in Apache Mynewt (or https://github.com/apache/incubator-mynewt-blinky on its github mirror.)",
- "title": "newt new "
- },
- {
- "location": "/newt/command_list/newt_new/#usage",
- "text": "newt new project-name [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_new/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_new/#description",
- "text": "Creates a new project named project-name from the default skeleton blinky repository in Apache Mynewt (or https://github.com/apache/incubator-mynewt-blinky on its github mirror.)",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_new/#examples",
- "text": "Sub-command Usage Explanation newt new test_project Creates a new project named test_project using the default skeleton from the apache/incubator-mynewt-blinky repository.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_pkg/",
- "text": "newt pkg \n\n\nCommands for creating and manipulating packages.\n\n\nUsage:\n\n\n newt pkg [command] [flags] \n\n\n\n\n\nFlags:\n\n\n -t, --type string Type of package to create: pkg, bsp, sdk. (default \npkg\n)\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nThe pkg command provides subcommands to create and manage packages. The subcommands take one or two \npackage-name\n arguments.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\ncopy\n\n\nThe copy \nsrc-pkg\n \ndst-pkg\n command creates the new \ndst-pkg\n package by cloning the \nsrc-pkg\n package.\n\n\n\n\n\n\nmove\n\n\nThe move \nold-pkg\n \nnew-pkg\n command moves the \nold-pkg\n package to the \nnew-pkg\n package.\n\n\n\n\n\n\nnew\n\n\nThe new \nnew-pkg\n command creates a new package named \nnew-pkg\n, from a template, in the current directory. You can create a package of type \npkg\n, \nbsp\n, or \nsdk\n. The default package type is \npkg\n. You use the -t flag to specify a different package type.\n\n\n\n\n\n\nremove\n\n\nThe remove \nmy-pkg\n command deletes the \nmy-pkg\n package.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\ncopy\n\n\nnewt pkg copy \napps/bletiny apps/new_bletiny\n\n\nCopies the \napps/bletiny\n package to the \napps/new_bletiny\n.\n\n\n\n\n\n\nmove\n\n\nnewt pkg move \napps/slinky apps/new_slinky\n\n\nMoves the \napps/slinky\n package to the \napps/new_slinky\n package.\n\n\n\n\n\n\nnew\n\n\nnewt pkg new apps/new_slinky\n\n\nCreates a package named \napps/new_slinky\n of type \npkg\n in the current directory.\n\n\n\n\n\n\nnew\n\n\nnewt pkg new hw/bsp/myboard -t bsp\n\n\nCreates a package named \nhw/bsp/myboard\n of type \nbsp\n in the current directory.\n\n\n\n\n\n\nremove\n\n\nnewt pkg remove hw/bsp/myboard\n\n\nRemoves the \nhw/bsp/myboard\n package.",
- "title": "newt pkg"
- },
- {
- "location": "/newt/command_list/newt_pkg/#newt-pkg",
- "text": "Commands for creating and manipulating packages.",
- "title": "newt pkg "
- },
- {
- "location": "/newt/command_list/newt_pkg/#usage",
- "text": "newt pkg [command] [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_pkg/#flags",
- "text": "-t, --type string Type of package to create: pkg, bsp, sdk. (default pkg )",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_pkg/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_pkg/#description",
- "text": "The pkg command provides subcommands to create and manage packages. The subcommands take one or two package-name arguments. Sub-command Explanation copy The copy src-pkg dst-pkg command creates the new dst-pkg package by cloning the src-pkg package. move The move old-pkg new-pkg command moves the old-pkg package to the new-pkg package. new The new new-pkg command creates a new package named new-pkg , from a template, in the current directory. You can create a package of type pkg , bsp , or sdk . The default package type is pkg . You use the -t flag to specify a different package type. remove The remove my-pkg command deletes the my-pkg package.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_pkg/#examples",
- "text": "Sub-command Usage Explanation copy newt pkg copy apps/bletiny apps/new_bletiny Copies the apps/bletiny package to the apps/new_bletiny . move newt pkg move apps/slinky apps/new_slinky Moves the apps/slinky package to the apps/new_slinky package. new newt pkg new apps/new_slinky Creates a package named apps/new_slinky of type pkg in the current directory. new newt pkg new hw/bsp/myboard -t bsp Creates a package named hw/bsp/myboard of type bsp in the current directory. remove newt pkg remove hw/bsp/myboard Removes the hw/bsp/myboard package.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_run/",
- "text": "newt run \n\n\nA single command to do four steps - build a target, create-image, load image on a board, and start a debug session with the image on the board.\n\n\nNote\n: If the version number is omitted: \n\n\n\n\nThe create-image step is skipped for a bootloader target.\n\n\nYou will be prompted to enter a version number for an application target.\n\n\n\n\nUsage:\n\n\n newt run \ntarget-name\n [\nversion\n][flags] \n\n\n\n\n\nFlags:\n\n\n --extrajtagcmd string Extra commands to send to JTAG software\n -n, --noGDB Do not start GDB from the command line\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nSame as running \nbuild \ntarget-name\n, \ncreate-image \ntarget-name\n \nversion\n, \nload \ntarget-name\n, and \ndebug \ntarget-name\n.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt run blink_rigado\n\n\nCompiles and builds the image for the \napp\n and the \nbsp\n defined for target \nblink_rigado\n, loads the image onto the board, and opens an active GNU gdb debugging session to run the image.\n\n\n\n\n\n\n\n\nnewt run ble_rigado 0.1.0.0\n\n\nCompiles and builds the image for the \napp\n and the \nbsp\n defined for target \nble_rigado\n, signs and creates the image with version number 0.1.0.0, loads the image onto the board, and opens an active GNU gdb debugging session to run the image. \n \n Note that if there is no bootloader available for a particular board/kit, a signed image creation step is not necessary.",
- "title": "newt run"
- },
- {
- "location": "/newt/command_list/newt_run/#newt-run",
- "text": "A single command to do four steps - build a target, create-image, load image on a board, and start a debug session with the image on the board. Note : If the version number is omitted: The create-image step is skipped for a bootloader target. You will be prompted to enter a version number for an application target.",
- "title": "newt run "
- },
- {
- "location": "/newt/command_list/newt_run/#usage",
- "text": "newt run target-name [ version ][flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_run/#flags",
- "text": "--extrajtagcmd string Extra commands to send to JTAG software\n -n, --noGDB Do not start GDB from the command line",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_run/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_run/#description",
- "text": "Same as running build target-name , create-image target-name version , load target-name , and debug target-name .",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_run/#examples",
- "text": "Sub-command Usage Explanation newt run blink_rigado Compiles and builds the image for the app and the bsp defined for target blink_rigado , loads the image onto the board, and opens an active GNU gdb debugging session to run the image. newt run ble_rigado 0.1.0.0 Compiles and builds the image for the app and the bsp defined for target ble_rigado , signs and creates the image with version number 0.1.0.0, loads the image onto the board, and opens an active GNU gdb debugging session to run the image. Note that if there is no bootloader available for a particular board/kit, a signed image creation step is not necessary.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_size/",
- "text": "newt size \n\n\nCalculates the size of target components for a target.\n\n\nUsage:\n\n\n newt size \ntarget-name\n [flags]\n\n\n\n\n\nFlags:\n\n\n -F, --flash Print FLASH statistics\n -R, --ram Print RAM statistics\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nDisplays the RAM and FLASH size of each component for the \ntarget-name\n target. \n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt size blink_rigado\n\n\nInspects and lists the RAM and Flash memory that each component (object files and libraries) for the \nblink_rigado\n target.\n\n\n\n\n\n\n\n\nExample output for \nnewt size blink_rigado\n:\n\n\n$ newt size blink_rigado\n FLASH RAM \n 9 223 *fill*\n 1052 0 baselibc.a\n 195 1116 blinky.a\n 616 452 bmd300eval.a\n 64 0 cmsis-core.a\n 124 0 crt0.o\n 8 0 crti.o\n 16 0 crtn.o\n 277 196 full.a\n 20 8 hal.a\n 96 1068 libg.a\n 1452 0 libgcc.a\n 332 28 nrf52xxx.a\n 3143 677 os.a\n\nobjsize\n text data bss dec hex filename\n 7404 1172 2212 10788 2a24 /Users/\nusername\n/dev/rigado/bin/blink_rigado/apps/blinky/blinky.elf",
- "title": "newt size"
- },
- {
- "location": "/newt/command_list/newt_size/#newt-size",
- "text": "Calculates the size of target components for a target.",
- "title": "newt size "
- },
- {
- "location": "/newt/command_list/newt_size/#usage",
- "text": "newt size target-name [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_size/#flags",
- "text": "-F, --flash Print FLASH statistics\n -R, --ram Print RAM statistics",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_size/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_size/#description",
- "text": "Displays the RAM and FLASH size of each component for the target-name target.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_size/#examples",
- "text": "Sub-command Usage Explanation newt size blink_rigado Inspects and lists the RAM and Flash memory that each component (object files and libraries) for the blink_rigado target.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_size/#example-output-for-newt-size-blink_rigado",
- "text": "$ newt size blink_rigado\n FLASH RAM \n 9 223 *fill*\n 1052 0 baselibc.a\n 195 1116 blinky.a\n 616 452 bmd300eval.a\n 64 0 cmsis-core.a\n 124 0 crt0.o\n 8 0 crti.o\n 16 0 crtn.o\n 277 196 full.a\n 20 8 hal.a\n 96 1068 libg.a\n 1452 0 libgcc.a\n 332 28 nrf52xxx.a\n 3143 677 os.a\n\nobjsize\n text data bss dec hex filename\n 7404 1172 2212 10788 2a24 /Users/ username /dev/rigado/bin/blink_rigado/apps/blinky/blinky.elf",
- "title": "Example output for newt size blink_rigado:"
- },
- {
- "location": "/newt/command_list/newt_sync/",
- "text": "newt sync \n\n\nSynchronize and refresh the contents of the local copy of all the repositories used in the project with the latest updates maintained in the remote repositories. \n\n\nUsage:\n\n\n newt sync [flags]\n\n\n\n\n\nFlags:\n\n\n -f, --force Force overwrite of existing remote repository\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nSynchronize project dependencies and repositories. Prior to 1.0.0 release, the command deletes and resynchronizes each repository. Post 1.0.0, it will abort the synchronization if there are any local changes to any repository. Using the -f to force overwrite of existing repository will stash and save the changes while pulling in all the latest changes from the remote repository.",
- "title": "newt sync"
- },
- {
- "location": "/newt/command_list/newt_sync/#newt-sync",
- "text": "Synchronize and refresh the contents of the local copy of all the repositories used in the project with the latest updates maintained in the remote repositories.",
- "title": "newt sync "
- },
- {
- "location": "/newt/command_list/newt_sync/#usage",
- "text": "newt sync [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_sync/#flags",
- "text": "-f, --force Force overwrite of existing remote repository",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_sync/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_sync/#description",
- "text": "Synchronize project dependencies and repositories. Prior to 1.0.0 release, the command deletes and resynchronizes each repository. Post 1.0.0, it will abort the synchronization if there are any local changes to any repository. Using the -f to force overwrite of existing repository will stash and save the changes while pulling in all the latest changes from the remote repository.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_target/",
- "text": "newt target \n\n\nCommands to create, delete, configure and query targets. \n\n\nUsage:\n\n\n newt target [command] [flags]\n\n\n\n\n\nAvailable Commands:\n\n\n amend Add, change, or delete values for multi-value target variables\n config View or populate a target\ns system configuration settings\n copy Copy target\n create Create a target\n delete Delete target\n dep View target\ns dependency graph\n revdep View target\ns reverse-dependency graph\n set Set target configuration variable\n show View target configuration variables\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nThe target command provides subcommands to create, build, delete, and query targets. The subcommands take one or two \ntarget-name\n arguments. \n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\namend\n\n\nThe amend command allows you to add, change, or delete values for multi-value target variables that you have set with the \nnewt target set\n command. The format of the amend command is: \nnewt target amend \ntarget-name\n \nvar-name=var-value\n [var-name=var-value...] \nSpecify the \n-d\n flag to delete values.\nThe following multi-value variables can be amended: \naflags\n, \ncflags\n, \nlflags\n, \nsyscfg\n. \nThe \nvar-value\n format depends on the \nvar-name\n as follows: \naflags\n, \ncflags\n, \nlflags\n: A string of flags, with each flag separated by a space. These variables are saved in the target's \npkg.yml\n file.\nsyscfg\n: The \nsyscfg\n variable allows you to assign values to configuration settings in your target's \nsyscfg.yml\n file. \nThe format is \nsyscfg=setting-name1=setting-value1[:setting-name2=setting-value2...]\n, where \nsetting-name1\n is a configuration setting name and \nsetting-value1\n is the value to assign to \nsetting-name1\n. If \nsetting-value1\n is not specified, the setting is set to value \n1\n. You use a \n:\n to delimit each setting when you amend multiple settings.\nTo delete a system configuration setting, you only need to specify the setting name. For example, \nsyscfg=setting-name1:setting-name2\n deletes configuration settings named \nsetting-name1\n and \nsetting-name2\n. \n\n\n\n\n\n\nconfig\n\n\nThe config command allows you to view or populate a target's system configuration settings. A target's system configuration settings include the settings of all the packages it includes. The settings for a package are listed in the package's \nsyscfg.yml\n file. The \nconfig\n command has two subcommands: \nshow\n and \ninit\n. \n The config show \ntarget-name\n command displays the system configuration setting definitions and values for all the packages that the \ntarget-name\n target includes. \nThe config init \ntarget-name\n command populates the target's \nsyscfg.yml\n file with the system configuration values for all the packages that the \ntarget-name\n target includes.\n\n\n\n\n\n\ncopy\n\n\nThe copy \nsrc-target\n \ndst-target\n command creates a new target named \ndst-target\n by cloning the \nsrc-target\n target.\n\n\n\n\n\n\ncreate\n\n\nThe create \ntarget-name\n command creates an empty target named \ntarget-name\n. It creates the \ntargets/target-name\n directory and the skeleton \npkg.yml\n and \ntarget.yml\n files in the directory.\n\n\n\n\n\n\ndelete\n\n\nThe delete \ntarget-name\n command deletes the description for the \ntarget-name\n target. It deletes the 'targets/target-name' directory. It does not delete the 'bin/targets/target-name' directory where the build artifacts are stored. If you want to delete the build artifacts, run the \nnewt clean \ntarget-name\n command \nbefore\n deleting the target.\n\n\n\n\n\n\ndep\n\n\nThe dep \ntarget-name\n command displays a dependency tree for the packages that the \ntarget-name\n target includes. It shows each package followed by the list of libraries or packages that it depends on.\n\n\n\n\n\n\nrevdep\n\n\nThe revdep \ntarget-name\n command displays the reverse dependency tree for the packages that the \ntarget-name\n target includes. It shows each package followed by the list of libraries or packages that depend on it.\n\n\n\n\n\n\nset\n\n\nThe set \ntarget-name\n \nvar-name=var-value\n [var-name=var-value...] command sets variables (attributes) for the \ntarget-name\n target. The set command overwrites your current variable values. \nThe valid \nvar-name\n values are: \napp\n, \nbsp\n, \nloader\n, \nbuild_profile\n, \ncflags\n, \nlflags\n, \naflags\n, \nsyscfg\n. \nThe \nvar-value\n format depends on the \nvar-name\n as follows: \napp\n, \nbsp\n, \nloader\n: @\nsource-path\n, where \nsource-path\n is the directory containing the application or bsp source. These variables are stored in the target's target.yml file. For a simulated target, e.g. for software testing purposes, set \nbsp\n to \n@apache-mynewt-core/hw/bsp/native\n.\n \nbuild_profile\n: \noptimized\n or \ndebug\naflags\n, \ncflags\n, \nlflags\n: A string of flags, with each flag separated by a space. These variables are saved in the target's \npkg.yml\n file.\nsyscfg\n: The \nsyscfg\n variable allows you to assign values to configuration settings in your target's \nsyscfg.yml\n file. \nThe format is \nsyscfg=setting-name1=setting-value1[:setting-name2=setting-value2...]\n, where \nsetting-name1\n is a configuration setting name and \nsetting-value1\n is the value to assign to \nsetting-name1\n. If \nsetting-value1\n is not specified, the setting is set to value \n1\n. You use a \n:\n to delimit each setting when you set multiple settings. \nYou can specify \nvar-name=\n or \nvar-name=\"\"\n to unset a variable value.\n \nWarning\n: For multi-value variables, the command overrides all existing values. Use the \nnewt target amend\n command to change or add new values for a multi-value variable after you have set the variable value. The multi-value variables are: \naflags\n, \ncflags\n, \nlflags\n, and \nsyscfg\n.\nTo display all the existing values for a target variable (attribute), you can run the \nnewt vals \nvariable-name\n command. For example, \nnewt vals app\n displays the valid values available for the variable \napp\n for any target.\n\n\n\n\n\n\nshow\n\n\nThe show [target-name] command shows the values of the variables (attributes) for the \ntarget-name\n target. When \ntarget-name\n is not specified, the command shows the variables for all the targets that are defined for your project.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\namend\n\n\nnewt target amend myble syscfg=CONFIG_NEWTMGR=0 cflags=\"-DTEST\"\n\n\nChanges (or adds) the \nCONFIG_NEWTMGR\n variable to value 0 in the \nsyscfg.yml\n file and adds the -DTEST flag to \npkg.cflags\n in the \npkg.yml\n file for the \nmyble\n target. Other syscfg setting values and cflags values are not changed.\n\n\n\n\n\n\namend\n\n\nnewt target amend myble -d syscfg=LOG_LEVEL:CONFIG_NEWTMGR cflags=\"-DNDEBUG\"\n\n\nDeletes \nLOG_LEVEL\n and \nCONFIG_NEWTMGR\n settings from the \nsyscfg.yml\n file and the -DTEST flag from \npkg.cflags\n for the \nmyble\n target. Other syscfg setting values and cflags values are not changed.\n\n\n\n\n\n\nconfig show\n\n\nnewt target config show rb_blinky\n\n\nShows the system configuration settings for all the packages that the \nrb_blinky\n target includes.\n\n\n\n\n\n\nconfig init\n\n\nnewt target config init my_blinky\n\n\nCreates and populates the \nmy_blinky\n target's \nsyscfg.yml\n file with the system configuration setting values from all the packages that the \nmy_blinky\n target includes.\n\n\n\n\n\n\ncopy\n\n\nnewt target copy \nrb_blinky rb_bletiny\n\n\nCreates the \nrb_bletiny\n target by cloning the \nrb_blinky\n target.\n\n\n\n\n\n\ncreate\n\n\nnewt target create \nmy_new_target\n\n\nCreates the \nmy_newt_target\n target. It creates the \ntargets/my_new_target\n directory and creates the skeleton \npkg.yml\n and \ntarget.yml\n files in the directory.\n\n\n\n\n\n\ndelete\n\n\nnewt target delete rb_bletiny\n\n\nDeletes the \nrb_bletiny\n target. It deletes the \ntargets/rb_bletiny\n directory.\n\n\n\n\n\n\ndep\n\n\nnewt target dep myble\n\n\nDisplays the dependency tree of all the package dependencies for the \nmyble\n target. It lists each package followed by a list of packages it depends on.\n\n\n\n\n\n\nrevdep\n\n\nnewt target revdep myble\n\n\nDisplays the reverse dependency tree of all the package dependencies for the \nmyble\n target. It lists each package followed by a list of packages that depend on it.\n\n\n\n\n\n\nset\n\n\nnewt target set myble \napp=@apache-mynewt-core/apps/bletiny\n\n\nUse \nbletiny\n as the application to build for the \nmyble\n target.\n\n\n\n\n\n\nset\n\n\nnewt target set myble \ncflags=\"-DNDEBUG -Werror\"\n\n\nSet \npkg.cflags\n variable with \n-DNDEBUG -Werror\n in the \nmyble\n target's \npkg.yml\n file..\n\n\n\n\n\n\nset\n\n\nnewt target set myble syscfg=LOG_NEWTMGR=0:CONFIG_NEWTMGR\n\n\nSets the \nsyscfg.vals\n variable in the \nmyble\n target's \nsyscfg.yml\n file with the setting values: LOG_NEWTMGR: 0 and CONFIG_NEWTMGR: 1. CONFIG_NEWTMGR is set to 1 because a value is not specified.\n\n\n\n\n\n\nset\n\n\nnewt target set myble cflags=\n\n\nUnsets the \npkg.cflags\n variable in the \nmyble\n target's \npkg.yml\n file.\n\n\n\n\n\n\nshow\n\n\nnewt target show myble\n\n\nShows all variable settings for the \nmyble\n target, i.e. the values that app, bsp, build_profile, cflags, aflags, ldflags, syscfg variables are set to. Note that not all variables have to be set for a target.\n\n\n\n\n\n\nshow\n\n\nnewt target show\n\n\nShows all the variable settings for all the targets defined for the project.",
- "title": "newt target"
- },
- {
- "location": "/newt/command_list/newt_target/#newt-target",
- "text": "Commands to create, delete, configure and query targets.",
- "title": "newt target "
- },
- {
- "location": "/newt/command_list/newt_target/#usage",
- "text": "newt target [command] [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_target/#available-commands",
- "text": "amend Add, change, or delete values for multi-value target variables\n config View or populate a target s system configuration settings\n copy Copy target\n create Create a target\n delete Delete target\n dep View target s dependency graph\n revdep View target s reverse-dependency graph\n set Set target configuration variable\n show View target configuration variables",
- "title": "Available Commands:"
- },
- {
- "location": "/newt/command_list/newt_target/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_target/#description",
- "text": "The target command provides subcommands to create, build, delete, and query targets. The subcommands take one or two target-name arguments. Sub-command Explanation amend The amend command allows you to add, change, or delete values for multi-value target variables that you have set with the newt target set command. The format of the amend command is: newt target amend target-name var-name=var-value [var-name=var-value...] Specify the -d flag to delete values. The following multi-value variables can be amended: aflags , cflags , lflags , syscfg . The var-value format depends on the var-name as follows: aflags , cflags , lflags : A string of flags, with each flag separated by a space. These variables are saved in the target's pkg.yml file. syscfg : The syscfg variable allows you to assign values to configuration settings in your target's syscfg.yml file. The format is syscfg=setting-name1=setting-value1[:setting-name2=setting-value2...] , where setting-name1 is a configuration setting name and setting-value1 is the value to assign to setting-name1 . If setting-value1 is not specified, the setting is set to value 1 . You use a : to delimit each setting when you amend multiple settings. To delete a system configuration setting, you only need to specify the setting name. For example, syscfg=setting-name1:setting-name2 deletes configuration settings named setting-name1 and setting-name2 . config The config command allows you to view or populate a target's system configuration settings. A target's system configuration settings include the settings of all the packages it includes. The settings for a package are listed in the package's syscfg.yml file. The config command has two subcommands: show and init . The config show target-name command displays the system configuration setting definitions and values for all the packages that the target-name target includes. The config init target-name command populates the target's syscfg.yml file with the system configuration values for all the packages that the target-name target includes. copy The copy src-target dst-target command creates a new target named dst-target by cloning the src-target target. create The create target-name command creates an empty target named target-name . It creates the targets/target-name directory and the skeleton pkg.yml and target.yml files in the directory. delete The delete target-name command deletes the description for the target-name target. It deletes the 'targets/target-name' directory. It does not delete the 'bin/targets/target-name' directory where the build artifacts are stored. If you want to delete the build artifacts, run the newt clean target-name command before deleting the target. dep The dep target-name command displays a dependency tree for the packages that the target-name target includes. It shows each package followed by the list of libraries or packages that it depends on. revdep The revdep target-name command displays the reverse dependency tree for the packages that the target-name target includes. It shows each package followed by the list of libraries or packages that depend on it. set The set target-name var-name=var-value [var-name=var-value...] command sets variables (attributes) for the target-name target. The set command overwrites your current variable values. The valid var-name values are: app , bsp , loader , build_profile , cflags , lflags , aflags , syscfg . The var-value format depends on the var-name as follows: app , bsp , loader : @ source-path , where source-path is the directory containing the application or bsp source. These variables are stored in the target's target.yml file. For a simulated target, e.g. for software testing purposes, set bsp to @apache-mynewt-core/hw/bsp/native . build_profile : optimized or debug aflags , cflags , lflags : A string of flags, with each flag separated by a space. These variables are saved in the target's pkg.yml file. syscfg : The syscfg variable allows you to assign values to configuration settings in your target's syscfg.yml file. The format is syscfg=setting-name1=setting-value1[:setting-name2=setting-value2...] , where setting-name1 is a configuration setting name and setting-value1 is the value to assign to setting-name1 . If setting-value1 is not specified, the setting is set to value 1 . You use a : to delimit each setting when you set multiple settings. You can specify var-name= or var-name=\"\" to unset a variable value. Warning : For multi-value variables, the command overrides all existing values. Use the newt target amend command to change or add new values for a multi-value variable after you have set the variable value. The multi-value variables are: aflags , cflags , lflags , and syscfg . To display all the existing values for a target variable (attribute), you can run the newt vals variable-name command. For example, newt vals app displays the valid values available for the variable app for any target. show The show [target-name] command shows the values of the variables (attributes) for the target-name target. When target-name is not specified, the command shows the variables for all the targets that are defined for your project.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_target/#examples",
- "text": "Sub-command Usage Explanation amend newt target amend myble syscfg=CONFIG_NEWTMGR=0 cflags=\"-DTEST\" Changes (or adds) the CONFIG_NEWTMGR variable to value 0 in the syscfg.yml file and adds the -DTEST flag to pkg.cflags in the pkg.yml file for the myble target. Other syscfg setting values and cflags values are not changed. amend newt target amend myble -d syscfg=LOG_LEVEL:CONFIG_NEWTMGR cflags=\"-DNDEBUG\" Deletes LOG_LEVEL and CONFIG_NEWTMGR settings from the syscfg.yml file and the -DTEST flag from pkg.cflags for the myble target. Other syscfg setting values and cflags values are not changed. config show newt target config show rb_blinky Shows the system configuration settings for all the packages that the rb_blinky target includes. config init newt target config init my_blinky Creates and populates the my_blinky target's syscfg.yml file with the system configuration setting values from all the packages that the my_blinky target includes. copy newt target copy rb_blinky rb_bletiny Creates the rb_bletiny target by cloning the rb_blinky target. create newt target create my_new_target Creates the my_newt_target target. It creates the targets/my_new_target directory and creates the skeleton pkg.yml and target.yml files in the directory. delete newt target delete rb_bletiny Deletes the rb_bletiny target. It deletes the targets/rb_bletiny directory. dep newt target dep myble Displays the dependency tree of all the package dependencies for the myble target. It lists each package followed by a list of packages it depends on. revdep newt target revdep myble Displays the reverse dependency tree of all the package dependencies for the myble target. It lists each package followed by a list of packages that depend on it. set newt target set myble app=@apache-mynewt-core/apps/bletiny Use bletiny as the application to build for the myble target. set newt target set myble cflags=\"-DNDEBUG -Werror\" Set pkg.cflags variable with -DNDEBUG -Werror in the myble target's pkg.yml file.. set newt target set myble syscfg=LOG_NEWTMGR=0:CONFIG_NEWTMGR Sets the syscfg.vals variable in the myble target's syscfg.yml file with the setting values: LOG_NEWTMGR: 0 and CONFIG_NEWTMGR: 1. CONFIG_NEWTMGR is set to 1 because a value is not specified. set newt target set myble cflags= Unsets the pkg.cflags variable in the myble target's pkg.yml file. show newt target show myble Shows all variable settings for the myble target, i.e. the values that app, bsp, build_profile, cflags, aflags, ldflags, syscfg variables are set to. Note that not all variables have to be set for a target. show newt target show Shows all the variable settings for all the targets defined for the project.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_test/",
- "text": "newt test \n\n\nExecute unit tests for one or more packages. \n\n\nUsage:\n\n\n newt test \npackage-name\n [package-names...] | all [flags]\n\n\n\n\n\nFlags:\n\n\n -e, --exclude string Comma separated list of packages to exclude\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nExecutes unit tests for one or more packages. You specify a list of packages, separated by space, to test multiple packages in the same command, or specify \nall\n to test all packages. When you use the \nall\n option, you may use the \n-e\n flag followed by a comma separated list of packages to exclude from the test.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt test \n@apache-mynewt-core/kernel/os\n\n\nTests the \nkernel/os\n package in the \napache-mynewt-core\n repository.\n\n\n\n\n\n\n\n\nnewt test kernel/os encoding/json\n\n\nTests the \nkernel/os\n and \nencoding/json\n packages in the current repository.\n\n\n\n\n\n\n\n\nnewt test all\n\n\nTests all packages.\n\n\n\n\n\n\n\n\nnewt test all -e net/oic,encoding/json\n\n\nTests all packages except for the \nnet/oic\n and the \nencoding/json\n packages.",
- "title": "newt test"
- },
- {
- "location": "/newt/command_list/newt_test/#newt-test",
- "text": "Execute unit tests for one or more packages.",
- "title": "newt test "
- },
- {
- "location": "/newt/command_list/newt_test/#usage",
- "text": "newt test package-name [package-names...] | all [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_test/#flags",
- "text": "-e, --exclude string Comma separated list of packages to exclude",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_test/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_test/#description",
- "text": "Executes unit tests for one or more packages. You specify a list of packages, separated by space, to test multiple packages in the same command, or specify all to test all packages. When you use the all option, you may use the -e flag followed by a comma separated list of packages to exclude from the test.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_test/#examples",
- "text": "Sub-command Usage Explanation newt test @apache-mynewt-core/kernel/os Tests the kernel/os package in the apache-mynewt-core repository. newt test kernel/os encoding/json Tests the kernel/os and encoding/json packages in the current repository. newt test all Tests all packages. newt test all -e net/oic,encoding/json Tests all packages except for the net/oic and the encoding/json packages.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_upgrade/",
- "text": "newt upgrade \n\n\nUpgrade project dependencies.\n\n\nUsage:\n\n\n newt upgrade [flags] \n\n\n\n\n\nFlags:\n\n\n -f, --force Force upgrade of the repositories to latest state in project.yml\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nUpagrades your project and package dependencies. If you have changed the project.yml description for the project, you need to run this command to update all the package dependencies.",
- "title": "newt upgrade"
- },
- {
- "location": "/newt/command_list/newt_upgrade/#newt-upgrade",
- "text": "Upgrade project dependencies.",
- "title": "newt upgrade "
- },
- {
- "location": "/newt/command_list/newt_upgrade/#usage",
- "text": "newt upgrade [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_upgrade/#flags",
- "text": "-f, --force Force upgrade of the repositories to latest state in project.yml",
- "title": "Flags:"
- },
- {
- "location": "/newt/command_list/newt_upgrade/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_upgrade/#description",
- "text": "Upagrades your project and package dependencies. If you have changed the project.yml description for the project, you need to run this command to update all the package dependencies.",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_vals/",
- "text": "newt vals \n\n\nDisplay valid values for the specified element type(s).\n\n\nUsage:\n\n\n newt vals \nelement-type\n [element-types...] [flags]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nDescription\n\n\nDisplays valid values for the specified element type(s). You must set valid values for one or more elements when you define a package or a target. Valid element types are:\n\n\n\n\napi\n\n\napp\n\n\nbsp\n\n\nbuild_profile\n\n\ncompiler\n\n\nlib\n\n\nsdk\n\n\ntarget\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt vals api\n\n\nShows the possible values for APIs a package may specify as required. For example, the \npkg.yml\n for \nadc\n specifies that it requires the api named \nADC_HW_IMPL\n, one of the values listed by the command.\n\n\n\n\n\n\n\n\nExample output for \nnewt vals bsp\n:\n\n\nThis lists all possible values that may be assigned to a target's bsp attribute.\n\n\n$ newt vals bsp\nbsp names:\n @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n @apache-mynewt-core/hw/bsp/bmd300eval\n @apache-mynewt-core/hw/bsp/ci40\n @apache-mynewt-core/hw/bsp/frdm-k64f\n @apache-mynewt-core/hw/bsp/native\n @apache-mynewt-core/hw/bsp/nrf51-arduino_101\n @apache-mynewt-core/hw/bsp/nrf51-blenano\n @apache-mynewt-core/hw/bsp/nrf51dk\n @apache-mynewt-core/hw/bsp/nrf51dk-16kbram\n @apache-mynewt-core/hw/bsp/nrf52dk\n @apache-mynewt-core/hw/bsp/nucleo-f401re\n @apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard\n @apache-mynewt-core/hw/bsp/rb-nano2\n @apache-mynewt-core/hw/bsp/stm32f4discovery\n$ newt target set sample_target bsp=@apache-mynewt-core/hw/bsp/rb-nano2\n\n\n\n\n\nObviously, this output will grow as more board support packages are added for new boards and MCUs.",
- "title": "newt vals"
- },
- {
- "location": "/newt/command_list/newt_vals/#newt-vals",
- "text": "Display valid values for the specified element type(s).",
- "title": "newt vals "
- },
- {
- "location": "/newt/command_list/newt_vals/#usage",
- "text": "newt vals element-type [element-types...] [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_vals/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_vals/#description",
- "text": "Displays valid values for the specified element type(s). You must set valid values for one or more elements when you define a package or a target. Valid element types are: api app bsp build_profile compiler lib sdk target",
- "title": "Description"
- },
- {
- "location": "/newt/command_list/newt_vals/#examples",
- "text": "Sub-command Usage Explanation newt vals api Shows the possible values for APIs a package may specify as required. For example, the pkg.yml for adc specifies that it requires the api named ADC_HW_IMPL , one of the values listed by the command.",
- "title": "Examples"
- },
- {
- "location": "/newt/command_list/newt_vals/#example-output-for-newt-vals-bsp",
- "text": "This lists all possible values that may be assigned to a target's bsp attribute. $ newt vals bsp\nbsp names:\n @apache-mynewt-core/hw/bsp/arduino_primo_nrf52\n @apache-mynewt-core/hw/bsp/bmd300eval\n @apache-mynewt-core/hw/bsp/ci40\n @apache-mynewt-core/hw/bsp/frdm-k64f\n @apache-mynewt-core/hw/bsp/native\n @apache-mynewt-core/hw/bsp/nrf51-arduino_101\n @apache-mynewt-core/hw/bsp/nrf51-blenano\n @apache-mynewt-core/hw/bsp/nrf51dk\n @apache-mynewt-core/hw/bsp/nrf51dk-16kbram\n @apache-mynewt-core/hw/bsp/nrf52dk\n @apache-mynewt-core/hw/bsp/nucleo-f401re\n @apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard\n @apache-mynewt-core/hw/bsp/rb-nano2\n @apache-mynewt-core/hw/bsp/stm32f4discovery\n$ newt target set sample_target bsp=@apache-mynewt-core/hw/bsp/rb-nano2 Obviously, this output will grow as more board support packages are added for new boards and MCUs.",
- "title": "Example output for newt vals bsp:"
- },
- {
- "location": "/newt/command_list/newt_version/",
- "text": "newt version \n\n\nDisplay the version of the newt tool you have installed\n\n\nUsage:\n\n\n newt version [flags]\n\n\n\n\n\nGlobal Flags:\n\n\n -h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default \nWARN\n)\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don\nt output anything\n -v, --verbose Enable verbose output when executing commands\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewt version\n\n\nDisplays the version of the newt tool you have installed",
- "title": "newt version"
- },
- {
- "location": "/newt/command_list/newt_version/#newt-version",
- "text": "Display the version of the newt tool you have installed",
- "title": "newt version "
- },
- {
- "location": "/newt/command_list/newt_version/#usage",
- "text": "newt version [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newt/command_list/newt_version/#global-flags",
- "text": "-h, --help Help for newt commands\n -j, --jobs int Number of concurrent build jobs (default 8)\n -l, --loglevel string Log level (default WARN )\n -o, --outfile string Filename to tee output to\n -q, --quiet Be quiet; only display error output\n -s, --silent Be silent; don t output anything\n -v, --verbose Enable verbose output when executing commands",
- "title": "Global Flags:"
- },
- {
- "location": "/newt/command_list/newt_version/#examples",
- "text": "Sub-command Usage Explanation newt version Displays the version of the newt tool you have installed",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/overview/",
- "text": "Newt Manager\n\n\nNewt Manager (newtmgr) is the application tool that enables a user to communicate with and manage remote devices running the Mynewt OS. It uses a connection profile to establish a connection with a device and sends command requests to the device. The tool follows the same command structure as the \nnewt tool\n. \n\n\nAvailable high-level commands\n\n\nThe following are the high-level newtmgr commands. Some of these commands have subcommands. You can use the -h flag to get help for each command. See the documentation for each command in this guide if you need more information and examples.\n\n\nAvailable Commands:\n\n config Read or write a config value on a device\n conn Manage newtmgr connection profiles\n crash Send a crash command to a device\n datetime Manage datetime on a device\n echo Send data to a device and display the echoed back data\n fs Access files on a device\n image Manage images on a device\n log Manage logs on a device\n mpstat Read memory pool statistics from a device\n reset Send reset request to a device\n run Run test procedures on a device\n stat Read statistics from a device\n taskstat Read task statistics from a device\n\nFlags:\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received",
- "title": "toc"
- },
- {
- "location": "/newtmgr/overview/#newt-manager",
- "text": "Newt Manager (newtmgr) is the application tool that enables a user to communicate with and manage remote devices running the Mynewt OS. It uses a connection profile to establish a connection with a device and sends command requests to the device. The tool follows the same command structure as the newt tool .",
- "title": "Newt Manager"
- },
- {
- "location": "/newtmgr/overview/#available-high-level-commands",
- "text": "The following are the high-level newtmgr commands. Some of these commands have subcommands. You can use the -h flag to get help for each command. See the documentation for each command in this guide if you need more information and examples. Available Commands:\n\n config Read or write a config value on a device\n conn Manage newtmgr connection profiles\n crash Send a crash command to a device\n datetime Manage datetime on a device\n echo Send data to a device and display the echoed back data\n fs Access files on a device\n image Manage images on a device\n log Manage logs on a device\n mpstat Read memory pool statistics from a device\n reset Send reset request to a device\n run Run test procedures on a device\n stat Read statistics from a device\n taskstat Read task statistics from a device\n\nFlags:\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Available high-level commands"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_config/",
- "text": "newtmgr config \n\n\nRead and write config values on a device.\n\n\nUsage:\n\n\n newtmgr config \nvar-name\n [var-value] -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nReads and sets the value for the \nvar-name\n config variable on a device. Specify a \nvar-value\n to set the value for the \nvar-name\n variable. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr config myvar -c profile01\n\n\nReads the \nmyvar\n config variable value from a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nnewtmgr config myvar 2 -c profile01\n\n\nSets the \nmyvar\n config variable to the value \n2\n on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr config"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_config/#newtmgr-config",
- "text": "Read and write config values on a device.",
- "title": "newtmgr config "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_config/#usage",
- "text": "newtmgr config var-name [var-value] -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_config/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_config/#description",
- "text": "Reads and sets the value for the var-name config variable on a device. Specify a var-value to set the value for the var-name variable. Newtmgr uses the conn_profile connection profile to connect to the device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_config/#examples",
- "text": "Sub-command Usage Explanation newtmgr config myvar -c profile01 Reads the myvar config variable value from a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. newtmgr config myvar 2 -c profile01 Sets the myvar config variable to the value 2 on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/",
- "text": "newtmgr conn \n\n\nManage newtmgr connection profiles.\n\n\nUsage:\n\n\n newtmgr conn [command] [flags] \n\n\n\n\n\nFlags:\n\n\n -h, --help help for conn\n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n --name string name of target BLE device; overrides profile setting\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --timeout float timeout in seconds (partial seconds allowed) (default 10)\n -r, --tries int total number of tries in case of timeout (default 1)\n\n\n\n\n\nDescription\n\n\nThe conn command provides subcommands to add, delete, and view connection profiles. A connection profile specifies information on how to connect and communicate with a remote device. Newtmgr commands use the information from a connection profile to send newtmgr requests to remote devices.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nadd\n\n\nThe newtmgr conn add \nconn_profile\n \nvar-name=value ...\n command creates a connection profile named \nconn_profile\n. The command requires the \nconn_profile\n name and a list of, space separated, var-name=value pairs. The var-names are: \ntype\n, and \nconnstring\n. \nThe valid values for each var-name parameter are: \ntype\n: The connection type. Valid values are: \nserial\n: Newtmgr protocol over a serial connection.\n \noic_serial\n: OIC protocol over a serial connection.\n \nudp\n:newtmgr protocol over UDP.\n \noic_udp\n: OIC protocol over UDP.\nble\n newtmgr protocol over BLE. This type uses native OS BLE support \n \noic_ble\n: OIC protocol over BLE. This type uses native OS BLE support. \n \nbhd\n: newtmgr protocol over BLE. This type uses the blehostd implemenation.\n \noic_bhd\n: OIC protocol over BLE. This type uses the blehostd implementation. \nconnstring\n: The physical or virtual address for the connection. \n The format of the \nconnstring\n value depends on the connection \ntype\n value as follows:\nserial\n and \noic_serial\n: A quoted string with two, comma separated, \nattribute=value\n pairs. The attribute names and value format for each attribute are: \ndev\n: (Required) The name of the serial port to use. For example: \n/dev/ttyUSB0\n on a Linux platform or \nCOM1\n on a Windows platform .\nbaud\n: (Optional) A number that specifies the buad rate for the connection. Defaults to \n115200\n if the attribute is not specified.\n \nExample: connstring=\"dev=/dev/ttyUSB0, baud=9600\"\n \nNote:\n The 1.0 format, which only requires a serial port name, is still supported. For example, \nconnstring=/dev/ttyUSB0\n.\nudp\n and \noic_udp\n: The peer ip address and port number that the newtmgr or oicmgr on the remote device is listening on. It must be of the form: \n[\nip-address\n]:\nport-number\n. \nble\n and \noic_ble\n: The format is a quoted string of, comma separated, \nattribute=value\n pairs. The attribute names and the value for each attribute are:\npeer_name\n: A string that specifies the name the peer BLE device advertises.\nNote\n: If this attribute is specified, you do not need to specify a value for the \npeer_id\n attribute.\npeer_id\n: The peer BLE device address or UUID. The format depends on the OS that the newtmgr tool is running on:\nLinux\n: 6 byte BLE address. Each byte must be a hexidecimal number and separated by a colon.\nMacOS\n: 128 bit UUID.\nNote\n: This value is only used when a peer name is not specified for the connection profile or with the \n--name\n flag option. \nctlr_name\n: (Optional) Controller name. This value depends on the OS that the newtmgr tool is running on. \nNotes\n: \nYou must specify \nconnstring=\" \"\n if you do not specify any attribute values.\nYou can use the \n--name\n flag to specify a device name when you issue a newtmgr command that communicates with a BLE device. You can use this flag to override or in lieu of specifying a \npeer_name\n or \npeer_id\n attribute in the connection profile.\nbhd\n and \noic_bhd\n: The format is a quoted string of, comma separated, \nattribute=value\n pairs. The attribute names and the value format for each attribute are: \npeer_name\n: A string that specifies the name the peer BLE device advertises. \nNote\n: If this attribute is specified, you do not need to specify values for the \npeer_addr\n and \npeer_addr_type\n attributes.\n \npeer_addr\n: A 6 byte peer BLE device address. Each byte must be a hexidecimal number and separated by a colon. You must also specify a \npeer_addr_type\n value for the device address. \nNote:\n This value is only used when a peer name is not specified for the connection profile or with the \n--name\n flag option.\n \npeer_addr_type\n: The peer address type. Valid values are:\npublic\n: Public address assigned by the manufacturer.\n \nrandom\n: Static random address.\nrpa_pub\n: Resolvable Private Address with public identity address.\nrpa_rnd\n: Resolvable Private Address with static random identity address.\nNote:\n This value is only used when a peer name is not specified for the connection profile or with the \n--name\n flag option.\nown_addr_type\n: (Optional) The address type of the BLE controller for the host that the newtmgr tool is running on. See the \npeer_addr_type\n attribute for valid values. Defaults to \nrandom\n. \nctlr_path\n: The path of the port that is used to connect the BLE controller to the host that the newtmgr tool is running on.\n \nNote\n: You can use the \n--name\n flag to specify a device name when you issue a newtmgr command that communicates with a BLE device. You can use this flag to override or in lieu of specifying a \npeer_name\n or \npeer_addr\n attribute in the connection profile.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\ndelete\n\n\nThe newtmgr conn delete \nconn_profile\n command deletes the \nconn_profile\n connection profile.\n\n\n\n\n\n\nshow\n\n\nThe newtmgr conn show [conn_profile] command shows the information for the \nconn_profile\n connection profile. It shows information for all the connection profiles if \nconn_profile\n is not specified.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nadd\n\n\nnewtmgr conn add myserial02 type=oic_serial connstring=/dev/ttys002\n\n\nCreates a connection profile, named \nmyserial02\n, to communicate over a serial connection at 115200 baud rate with the oicmgr on a device that is connected to the host on port /dev/ttys002.\n\n\n\n\n\n\nadd\n\n\nnewtmgr conn add myserial03 type=serial connstring=\"dev=/dev/ttys003, baud=57600\"\n\n\nCreates a connection profile, named \nmyserial03\n, to communicate over a serial connection at 57600 baud rate with the newtmgr on a device that is connected to the host on port /dev/ttys003.\n\n\n\n\n\n\nadd\n\n\nnewtmgr conn add myudp5683 type=oic_udp\nconnstring=[127.0.0.1]:5683\n\n\nCreates a connection profile, named \nmyudp5683\n, to communicate over UDP with the oicmgr on a device listening on localhost and port 5683.\n\n\n\n\n\n\nadd\n\n\nnewtmgr conn add mybleprph type=ble connstring=\"peer_name=nimble-bleprph\"\n\n\nCreates a connection profile, named \nmybleprph\n, to communicate over BLE, using the native OS BLE support, with the newtmgr on a device named \nnimble-bleprph\n.\n\n\n\n\n\n\nadd\n\n\nnewtmgr conn add myble\ntype=ble connstring=\" \"\n\n\nCreates a connection profile, named \nmyble\n, to communicate over BLE, using the native OS BLE support, with the newtmgr on a device. You must use the \n--name\n flag to specify the device name when you issue a newtmgr command that communicates with the device.\n\n\n\n\n\n\nadd\n\n\nnewtmgr conn add myblehostd type=oic_bhd connstring=\"peer_name=nimble-bleprph,ctlr_path=/dev/cu.usbmodem14221\"\n\n\nCreates a connection profile, named \nmyblehostd\n, to communicate over BLE, using the blehostd implementation, with the oicmgr on a device named \nnimble-bleprph\n. The BLE controller is connected to the host on USB port /dev/cu.usbmodem14211 and uses static random address.\n\n\n\n\n\n\ndelete\n\n\nnewtmgr conn delete myserial02\n\n\nDeletes the connection profile named \nmyserial02\n\n\n\n\n\n\ndelete\n\n\nnewtmgr conn delete myserial02\n\n\nDeletes the connection profile named \nmyserial02\n\n\n\n\n\n\nshow\n\n\nnewtmgr conn show myserial01\n\n\nDisplays the information for the \nmyserial01\n connection profile.\n\n\n\n\n\n\nshow\n\n\nnewtmgr conn show\n\n\nDisplays the information for all connection profiles.",
- "title": "newtmgr conn"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/#newtmgr-conn",
- "text": "Manage newtmgr connection profiles.",
- "title": "newtmgr conn "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/#usage",
- "text": "newtmgr conn [command] [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/#flags",
- "text": "-h, --help help for conn",
- "title": "Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/#global-flags",
- "text": "-c, --conn string connection profile to use.\n --name string name of target BLE device; overrides profile setting\n -l, --loglevel string log level to use (default info )\n -t, --timeout float timeout in seconds (partial seconds allowed) (default 10)\n -r, --tries int total number of tries in case of timeout (default 1)",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/#description",
- "text": "The conn command provides subcommands to add, delete, and view connection profiles. A connection profile specifies information on how to connect and communicate with a remote device. Newtmgr commands use the information from a connection profile to send newtmgr requests to remote devices. Sub-command Explanation add The newtmgr conn add conn_profile var-name=value ... command creates a connection profile named conn_profile . The command requires the conn_profile name and a list of, space separated, var-name=value pairs. The var-names are: type , and connstring . The valid values for each var-name parameter are: type : The connection type. Valid values are: serial : Newtmgr protocol over a serial connection. oic_serial : OIC protocol over a serial connection. udp :newtmgr protocol over UDP. oic_udp : OIC protocol over UDP. ble newtmgr protocol over BLE. This type uses native OS BLE support oic_ble : OIC protocol over BLE. This type uses native OS BLE support. bhd : newtmgr protocol over BLE. This type uses the blehostd implemenation. oic_bhd : OIC protocol over BLE. This type uses the blehostd implementation. connstring : The physical or virtual address for the connection. The format of the connstring value depends on the connection type value as follows: serial and oic_serial : A quoted string with two, comma separated, attribute=value pairs. The attribute names and value format for each attribute are: dev : (Required) The name of the serial port to use. For example: /dev/ttyUSB0 on a Linux platform or COM1 on a Windows platform . baud : (Optional) A number that specifies the buad rate for the connection. Defaults to 115200 if the attribute is not specified. Example: connstring=\"dev=/dev/ttyUSB0, baud=9600\" Note: The 1.0 format, which only requires a serial port name, is still supported. For example, connstring=/dev/ttyUSB0 . udp and oic_udp : The peer ip address and port number that the newtmgr or oicmgr on the remote device is listening on. It must be of the form: [ ip-address ]: port-number . ble and oic_ble : The format is a quoted string of, comma separated, attribute=value pairs. The attribute names and the value for each attribute are: peer_name : A string that specifies the name the peer BLE device advertises. Note : If this attribute is specified, you do not need to specify a value for the peer_id attribute. peer_id : The peer BLE device address or UUID. The format depends on the OS that the newtmgr tool is running on: Linux : 6 byte BLE address. Each byte must be a hexidecimal number and separated by a colon. MacOS : 128 bit UUID. Note : This value is only used when a peer name is not specified for the connection profile or with the --name flag option. ctlr_name : (Optional) Controller name. This value depends on the OS that the newtmgr tool is running on. Notes : You must specify connstring=\" \" if you do not specify any attribute values. You can use the --name flag to specify a device name when you issue a newtmgr command that communicates with a BLE device. You can use this flag to override or in lieu of specifying a peer_name or peer_id attribute in the connection profile. bhd and oic_bhd : The format is a quoted string of, comma separated, attribute=value pairs. The attribute names and the value format for each attribute are: peer_name : A string that specifies the name the peer BLE device advertises. Note : If this attribute is specified, you do not need to specify values for the peer_addr and peer_addr_type attributes. peer_addr : A 6 byte peer BLE device address. Each byte must be a hexidecimal number and separated by a colon. You must also specify a peer_addr_type value for the device address. Note: This value is only used when a peer name is not specified for the connection profile or with the --name flag option. peer_addr_type : The peer address type. Valid values are: public : Public address assigned by the manufacturer. random : Static random address. rpa_pub : Resolvable Private Address with public identity address. rpa_rnd : Resolvable Private Address with static random identity address. Note: This value is only used when a peer name is not specified for the connection profile or with the --name flag option. own_addr_type : (Optional) The address type of the BLE controller for the host that the newtmgr tool is running on. See the peer_addr_type attribute for valid values. Defaults to random . ctlr_path : The path of the port that is used to connect the BLE controller to the host that the newtmgr tool is running on. Note : You can use the --name flag to specify a device name when you issue a newtmgr command that communicates with a BLE device. You can use this flag to override or in lieu of specifying a peer_name or peer_addr attribute in the connection profile. delete The newtmgr conn delete conn_profile command deletes the conn_profile connection profile. show The newtmgr conn show [conn_profile] command shows the information for the conn_profile connection profile. It shows information for all the connection profiles if conn_profile is not specified.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_conn/#examples",
- "text": "Sub-command Usage Explanation add newtmgr conn add myserial02 type=oic_serial connstring=/dev/ttys002 Creates a connection profile, named myserial02 , to communicate over a serial connection at 115200 baud rate with the oicmgr on a device that is connected to the host on port /dev/ttys002. add newtmgr conn add myserial03 type=serial connstring=\"dev=/dev/ttys003, baud=57600\" Creates a connection profile, named myserial03 , to communicate over a serial connection at 57600 baud rate with the newtmgr on a device that is connected to the host on port /dev/ttys003. add newtmgr conn add myudp5683 type=oic_udp connstring=[127.0.0.1]:5683 Creates a connection profile, named myudp5683 , to communicate over UDP with the oicmgr on a device listening on localhost and port 5683. add newtmgr conn add mybleprph type=ble connstring=\"peer_name=nimble-bleprph\" Creates a connection profile, named mybleprph , to communicate over BLE, using the native OS BLE support, with the newtmgr on a device named nimble-bleprph . add newtmgr conn add myble type=ble connstring=\" \" Creates a connection profile, named myble , to communicate over BLE, using the native OS BLE support, with the newtmgr on a device. You must use the --name flag to specify the device name when you issue a newtmgr command that communicates with the device. add newtmgr conn add myblehostd type=oic_bhd connstring=\"peer_name=nimble-bleprph,ctlr_path=/dev/cu.usbmodem14221\" Creates a connection profile, named myblehostd , to communicate over BLE, using the blehostd implementation, with the oicmgr on a device named nimble-bleprph . The BLE controller is connected to the host on USB port /dev/cu.usbmodem14211 and uses static random address. delete newtmgr conn delete myserial02 Deletes the connection profile named myserial02 delete newtmgr conn delete myserial02 Deletes the connection profile named myserial02 show newtmgr conn show myserial01 Displays the information for the myserial01 connection profile. show newtmgr conn show Displays the information for all connection profiles.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_crash/",
- "text": "newtmgr crash \n\n\nSend a crash command to a device.\n\n\nUsage:\n\n\n newtmgr crash \ndiv0|jump0|ref0|assert|wdog\n -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nSends a crash command to a device to run one of the following crash tests: \ndiv0\n, \njump0\n, \nref0\n, \nassert\n, \nwdog\n. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr crash div0\n-c profile01\n\n\nSends a request to a device to execute a divide by 0 test. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nnewtmgr crash ref0\n-c profile01\n\n\nSends a request to a device to execute a nil pointer reference test. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr crash"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_crash/#newtmgr-crash",
- "text": "Send a crash command to a device.",
- "title": "newtmgr crash "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_crash/#usage",
- "text": "newtmgr crash div0|jump0|ref0|assert|wdog -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_crash/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_crash/#description",
- "text": "Sends a crash command to a device to run one of the following crash tests: div0 , jump0 , ref0 , assert , wdog . Newtmgr uses the conn_profile connection profile to connect to the device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_crash/#examples",
- "text": "Sub-command Usage Explanation newtmgr crash div0 -c profile01 Sends a request to a device to execute a divide by 0 test. Newtmgr connects to the device over a connection specified in the profile01 connection profile. newtmgr crash ref0 -c profile01 Sends a request to a device to execute a nil pointer reference test. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_datetime/",
- "text": "newtmgr datetime \n\n\nManage datetime on a device.\n\n\nUsage:\n\n\n newtmgr datetime [datetime-value] -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nReads or sets the datetime on a device. Specify a \ndatetime-value\n in the command to set the datetime on the device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\nNote\n: You must specify the \ndatetime-value\n in the RFC 3339 format. \n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr datetime\n-c profile01\n\n\nReads the datetime value from a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nnewtmgr datetime 2017-03-01T22:44:00\n-c profile01\n\n\nSets the datetime on a device to March 1st 2017 22:44:00 UTC. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nnewtmgr datetime 2017-03-01T22:44:00-08:00\n-c profile01\n\n\nSets the datetime on a device to March 1st 2017 22:44:00 PST. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr datetime"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_datetime/#newtmgr-datetime",
- "text": "Manage datetime on a device.",
- "title": "newtmgr datetime "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_datetime/#usage",
- "text": "newtmgr datetime [datetime-value] -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_datetime/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_datetime/#description",
- "text": "Reads or sets the datetime on a device. Specify a datetime-value in the command to set the datetime on the device. Newtmgr uses the conn_profile connection profile to connect to the device. Note : You must specify the datetime-value in the RFC 3339 format.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_datetime/#examples",
- "text": "Sub-command Usage Explanation newtmgr datetime -c profile01 Reads the datetime value from a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. newtmgr datetime 2017-03-01T22:44:00 -c profile01 Sets the datetime on a device to March 1st 2017 22:44:00 UTC. Newtmgr connects to the device over a connection specified in the profile01 connection profile. newtmgr datetime 2017-03-01T22:44:00-08:00 -c profile01 Sets the datetime on a device to March 1st 2017 22:44:00 PST. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_echo/",
- "text": "newtmgr echo \n\n\nSend data to a device and display the echoed back data.\n\n\nUsage:\n\n\n newtmgr echo \ntext\n -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nSends the \ntext\n to a device and outputs the text response from the device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device. \n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr echo hello\n-c profile01\n\n\nSends the text 'hello' to a device and displays the echoed back data. Newtmgr connects to the device over a connection specified in the \nprofile01\n profile.",
- "title": "newtmgr echo"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_echo/#newtmgr-echo",
- "text": "Send data to a device and display the echoed back data.",
- "title": "newtmgr echo "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_echo/#usage",
- "text": "newtmgr echo text -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_echo/#global-flags",
- "text": "-c, --conn string connection profile to use\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_echo/#description",
- "text": "Sends the text to a device and outputs the text response from the device. Newtmgr uses the conn_profile connection profile to connect to the device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_echo/#examples",
- "text": "Sub-command Usage Explanation newtmgr echo hello -c profile01 Sends the text 'hello' to a device and displays the echoed back data. Newtmgr connects to the device over a connection specified in the profile01 profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_fs/",
- "text": "newtmgr fs\n\n\nAccess files on a device.\n\n\nUsage:\n\n\n newtmgr fs [command] -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nThe fs command provides the subcommands to download a file from and upload a file to a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\ndownload\n\n\nThe newtmgr download \nsrc-filename\n \ndst-filename\n command downloads the file named \nsrc-filename\n from a device and names it \ndst-filename\n on your host.\n\n\n\n\n\n\nupload\n\n\nThe newtmgr upload \nsrc-filename\n \ndst-filename\n command uploads the file named \nsrc-filename\n to a device and names the file \ndst-filename\n on the device.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\ndownload\n\n\nnewtmgr fs download /cfg/mfg mfg.txt -c profile01\n\n\nDownloads the file name \n/cfg/mfg\n from a device and names the file \nmfg.txt\n on your host. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nupload\n\n\nnewtmgr fs upload mymfg.txt /cfg/mfg -c profile01\n\n\nUploads the file name \nmymfg.txt\n to a device and names the file \ncfg/mfg\n on the device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr fs"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_fs/#newtmgr-fs",
- "text": "Access files on a device.",
- "title": "newtmgr fs"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_fs/#usage",
- "text": "newtmgr fs [command] -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_fs/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_fs/#description",
- "text": "The fs command provides the subcommands to download a file from and upload a file to a device. Newtmgr uses the conn_profile connection profile to connect to the device. Sub-command Explanation download The newtmgr download src-filename dst-filename command downloads the file named src-filename from a device and names it dst-filename on your host. upload The newtmgr upload src-filename dst-filename command uploads the file named src-filename to a device and names the file dst-filename on the device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_fs/#examples",
- "text": "Sub-command Usage Explanation download newtmgr fs download /cfg/mfg mfg.txt -c profile01 Downloads the file name /cfg/mfg from a device and names the file mfg.txt on your host. Newtmgr connects to the device over a connection specified in the profile01 connection profile. upload newtmgr fs upload mymfg.txt /cfg/mfg -c profile01 Uploads the file name mymfg.txt to a device and names the file cfg/mfg on the device. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/",
- "text": "newtmgr image \n\n\nManage images on a device.\n\n\nUsage:\n\n\n newtmgr image [command] -c \nconnection_profile\n [flags] \n\n\n\n\n\nFlags:\n\n\n -h, --help help for image\n\n\n\n\n\n\nThe coredownload subcommand uses the following local flags:\n\n\n -n, --bytes uint32 Number of bytes of the core to download \n -e, --elfify Create an ELF file \n --offset unint32 Offset of the core file to start the download \n\n\n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use\n -l, --loglevel string log level to use (default \ninfo\n)\n --name string name of target BLE device; overrides profile setting\n -t, --timeout float timeout in seconds (partial seconds allowed) (default 10)\n -r, --tries int total number of tries in case of timeout (default 1)\n\n\n\n\n\n\n\nDescription\n\n\nThe image command provides subcommands to manage core and image files on a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nconfirm\n\n\nThe newtmgr image confirm [hex-image-hash] command makes an image setup permanent on a device. If a \nhex-image-hash\n 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.\n\n\n\n\n\n\ncoreconvert\n\n\nThe newtmgr image coreconvert \ncore-filename\n \nelf-file\n command converts the \ncore-filename\n core file to an ELF format and names it \nelf-file\n. \n \nNote\n: This command does not download the core file from a device. The core file must exist on your host.\n\n\n\n\n\n\ncoredownload\n\n\nThe newtmgr image coredownload \ncore-filename\n command downloads the core file from a device and names the file \ncore-filename\n on your host. Use the local flags under Flags to customize the command.\n\n\n\n\n\n\ncoreerase\n\n\nThe newtmgr image coreerase command erases the core file on a device.\n\n\n\n\n\n\ncorelist\n\n\nThe newtmgr image corelist command lists the core(s) on a device.\n\n\n\n\n\n\nerase\n\n\nThe newtmgr image erase 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.\n\n\n\n\n\n\nlist\n\n\nThe newtmgr image list command displays information for the images on a device.\n\n\n\n\n\n\ntest\n\n\nThe newtmgr test \nhex-image-hash\n command tests the image, identified by the \nhex-image-hash\n hash value, on next reboot.\n\n\n\n\n\n\nupload\n\n\nThe newtmgr image upload \nimage-file\n command uploads the \nimage-file\n image file to a device.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nconfirm\n\n\nnewtmgr confirm\n-c profile01\n\n\nMakes the current image setup on a device permanent. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nconfirm\n\n\nnewtmgr confirm\nbe9699809a049...73d77f\n-c profile01\n\n\nMakes the image, identified by the \nbe9699809a049...73d77f\n hash value, setup on a device permanent. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ncoreconvert\n\n\nnewtmgr image coreconvert mycore mycore.elf\n\n\nConverts the \nmycore\n file to the ELF format and saves it in the \nmycore.elf\n file.\n\n\n\n\n\n\ncoredownload\n\n\nnewtmgr image coredownload \nmycore -c profile01\n\n\nDownloads the core from a device and saves it in the \nmycore\n file. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ncoredownload\n\n\nnewtmgr image coredownload \nmycore -e \n-c profile01\n\n\nDownloads the core from a device, converts the core file into the ELF format, and saves it in the \nmycore\n file. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ncoredownload\n\n\nnewtmgr image coredownload \nmycore \n--offset 10 -n 30\n-c profile01\n\n\nDownloads 30 bytes, starting at offset 10, of the core from a device and saves it in the \nmycore\n file. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ncoreerase\n\n\nnewtmgr image coreerase \n-c profile01\n\n\nErases the core file on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ncorelist\n\n\nnewtmgr image corelist\n-c profile01\n\n\nLists the core files on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nerase\n\n\nnewtmgr image erase\n-c profile01\n\n\nErases the image, if unused, from the secondary image slot on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nlist\n\n\nnewtmgr image list\n-c profile01\n\n\nLists the images on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ntest\n\n\nnewtmgr image test \nbe9699809a049...73d77f\n\n\nTests the image, identified by the \nbe9699809a049...73d77f\n hash value, during the next reboot on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nupload\n\n\nnewtmgr image \nupload bletiny.img\n-c profile01\n\n\nUploads the \nbletiny.img\n image to a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr image"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/#newtmgr-image",
- "text": "Manage images on a device.",
- "title": "newtmgr image "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/#usage",
- "text": "newtmgr image [command] -c connection_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/#flags",
- "text": "-h, --help help for image \nThe coredownload subcommand uses the following local flags: -n, --bytes uint32 Number of bytes of the core to download \n -e, --elfify Create an ELF file \n --offset unint32 Offset of the core file to start the download",
- "title": "Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/#global-flags",
- "text": "-c, --conn string connection profile to use\n -l, --loglevel string log level to use (default info )\n --name string name of target BLE device; overrides profile setting\n -t, --timeout float timeout in seconds (partial seconds allowed) (default 10)\n -r, --tries int total number of tries in case of timeout (default 1)",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/#description",
- "text": "The image command provides subcommands to manage core and image files on a device. Newtmgr uses the conn_profile connection profile to connect to the device. Sub-command Explanation confirm The newtmgr image confirm [hex-image-hash] command makes an image setup permanent on a device. If a hex-image-hash 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. coreconvert The newtmgr image coreconvert core-filename elf-file command converts the core-filename core file to an ELF format and names it elf-file . Note : This command does not download the core file from a device. The core file must exist on your host. coredownload The newtmgr image coredownload core-filename command downloads the core file from a device and names the file core-filename on your host. Use the local flags under Flags to customize the command. coreerase The newtmgr image coreerase command erases the core file on a device. corelist The newtmgr image corelist command lists the core(s) on a device. erase The newtmgr image erase 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. list The newtmgr image list command displays information for the images on a device. test The newtmgr test hex-image-hash command tests the image, identified by the hex-image-hash hash value, on next reboot. upload The newtmgr image upload image-file command uploads the image-file image file to a device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_image/#examples",
- "text": "Sub-command Usage Explanation confirm newtmgr confirm -c profile01 Makes the current image setup on a device permanent. Newtmgr connects to the device over a connection specified in the profile01 connection profile. confirm newtmgr confirm be9699809a049...73d77f -c profile01 Makes the image, identified by the be9699809a049...73d77f hash value, setup on a device permanent. Newtmgr connects to the device over a connection specified in the profile01 connection profile. coreconvert newtmgr image coreconvert mycore mycore.elf Converts the mycore file to the ELF format and saves it in the mycore.elf file. coredownload newtmgr image coredownload mycore -c profile01 Downloads the core from a device and saves it in the mycore file. Newtmgr connects to the device over a connection specified in the profile01 connection profile. coredownload newtmgr image coredownload mycore -e -c profile01 Downloads the core from a device, converts the core file into the ELF format, and saves it in the mycore file. Newtmgr connects to the device over a connection specified in the profile01 connection profile. coredownload newtmgr image coredownload mycore --offset 10 -n 30 -c profile01 Downloads 30 bytes, starting at offset 10, of the core from a device and saves it in the mycore file. Newtmgr connects to the device over a connection specified in the profile01 connection profile. coreerase newtmgr image coreerase -c profile01 Erases the core file on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. corelist newtmgr image corelist -c profile01 Lists the core files on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. erase newtmgr image erase -c profile01 Erases the image, if unused, from the secondary image slot on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. list newtmgr image list -c profile01 Lists the images on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. test newtmgr image test be9699809a049...73d77f Tests the image, identified by the be9699809a049...73d77f hash value, during the next reboot on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. upload newtmgr image upload bletiny.img -c profile01 Uploads the bletiny.img image to a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_logs/",
- "text": "newtmgr log \n\n\nManage logs on a device.\n\n\nUsage:\n\n\n newtmgr log [command] [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nThe log command provides subcommands to manage logs on a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nclear\n\n\nThe newtmgr log clear command clears the logs on a device.\n\n\n\n\n\n\nlevel_list\n\n\nThe newtmgr level_list command shows the log levels on a device.\n\n\n\n\n\n\nlist\n\n\nThe newtmgr log list command shows the log names on a device.\n\n\n\n\n\n\nmodule_list\n\n\nThe newtmgr log module_list command shows the log module names on a device.\n\n\n\n\n\n\nshow\n\n\nThe newtmgr log show command shows the logs on a device.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nclear\n\n\nnewtmgr log clear\n-c profile01\n\n\nClears the logs on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nlevel_list\n\n\nnewtmgr log level_list \n-c profile01\n\n\nShows the log levels on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nlist\n\n\nnewtmgr log list\n-c profile01\n\n\nShows the log names on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nmodule_list\n\n\nnewtmgr log module_list\n-c profile01\n\n\nShows the log module names on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nshow\n\n\nnewtmgr log show\n-c profile01\n\n\nShows the logs on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr log"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_logs/#newtmgr-log",
- "text": "Manage logs on a device.",
- "title": "newtmgr log "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_logs/#usage",
- "text": "newtmgr log [command] [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_logs/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_logs/#description",
- "text": "The log command provides subcommands to manage logs on a device. Newtmgr uses the conn_profile connection profile to connect to the device. Sub-command Explanation clear The newtmgr log clear command clears the logs on a device. level_list The newtmgr level_list command shows the log levels on a device. list The newtmgr log list command shows the log names on a device. module_list The newtmgr log module_list command shows the log module names on a device. show The newtmgr log show command shows the logs on a device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_logs/#examples",
- "text": "Sub-command Usage Explanation clear newtmgr log clear -c profile01 Clears the logs on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. level_list newtmgr log level_list -c profile01 Shows the log levels on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. list newtmgr log list -c profile01 Shows the log names on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. module_list newtmgr log module_list -c profile01 Shows the log module names on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. show newtmgr log show -c profile01 Shows the logs on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_mpstats/",
- "text": "newtmgr mpstat \n\n\nRead memory pool statistics from a device.\n\n\nUsage:\n\n\n newtmgr mpstat -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nReads and displays the memory pool statistics from a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device. It lists the following statistics for each memory pool: \n\n\n\n\nname\n: Memory pool name\n\n\nblksz\n: Size (number of bytes) of each memory block \n\n\ncnt\n: Number of blocks allocated for the pool\n\n\nfree\n: Number of free blocks \n\n\nmin\n: The lowest number of free blocks that were available\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr mpstat -c profile01\n\n\nReads and displays the memory pool statistics from a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nHere is an example output for the \nmyble\n application from the \nEnabling Newt Manager in any app\n tutiorial:\n\n\nnewtmgr mpstat -c myserial \nReturn Code = 0\n name blksz cnt free min\n ble_l2cap_sig_proc_pool 20 1 1 1\n ble_att_svr_prep_entry_pool 12 64 64 64\n ble_hci_ram_evt_hi_pool 72 2 2 1\n ble_hs_hci_ev_pool 16 10 10 9\n ble_att_svr_entry_pool 20 75 0 0\n ble_gattc_proc_pool 56 4 4 4\n bletiny_dsc_pool 28 64 64 64\n ble_hs_conn_pool 84 1 1 1\n ble_gap_update 24 1 1 1\n bletiny_svc_pool 32 32 32 32\n ble_gatts_clt_cfg_pool 12 2 1 1\n msys_1 292 12 9 6\n ble_hci_ram_evt_lo_pool 72 8 8 8\n ble_l2cap_chan_pool 24 3 3 3\n bletiny_chr_pool 36 64 64 64",
- "title": "newtmgr mpstat"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_mpstats/#newtmgr-mpstat",
- "text": "Read memory pool statistics from a device.",
- "title": "newtmgr mpstat "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_mpstats/#usage",
- "text": "newtmgr mpstat -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_mpstats/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_mpstats/#description",
- "text": "Reads and displays the memory pool statistics from a device. Newtmgr uses the conn_profile connection profile to connect to the device. It lists the following statistics for each memory pool: name : Memory pool name blksz : Size (number of bytes) of each memory block cnt : Number of blocks allocated for the pool free : Number of free blocks min : The lowest number of free blocks that were available",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_mpstats/#examples",
- "text": "Sub-command Usage Explanation newtmgr mpstat -c profile01 Reads and displays the memory pool statistics from a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. Here is an example output for the myble application from the Enabling Newt Manager in any app tutiorial: newtmgr mpstat -c myserial \nReturn Code = 0\n name blksz cnt free min\n ble_l2cap_sig_proc_pool 20 1 1 1\n ble_att_svr_prep_entry_pool 12 64 64 64\n ble_hci_ram_evt_hi_pool 72 2 2 1\n ble_hs_hci_ev_pool 16 10 10 9\n ble_att_svr_entry_pool 20 75 0 0\n ble_gattc_proc_pool 56 4 4 4\n bletiny_dsc_pool 28 64 64 64\n ble_hs_conn_pool 84 1 1 1\n ble_gap_update 24 1 1 1\n bletiny_svc_pool 32 32 32 32\n ble_gatts_clt_cfg_pool 12 2 1 1\n msys_1 292 12 9 6\n ble_hci_ram_evt_lo_pool 72 8 8 8\n ble_l2cap_chan_pool 24 3 3 3\n bletiny_chr_pool 36 64 64 64",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_reset/",
- "text": "newtmgr reset \n\n\nSend a reset request to a device.\n\n\nUsage:\n\n\n newtmgr reset \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nResets a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr reset\n-c profile01\n\n\nResets a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr reset"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_reset/#newtmgr-reset",
- "text": "Send a reset request to a device.",
- "title": "newtmgr reset "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_reset/#usage",
- "text": "newtmgr reset conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_reset/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_reset/#description",
- "text": "Resets a device. Newtmgr uses the conn_profile connection profile to connect to the device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_reset/#examples",
- "text": "Sub-command Usage Explanation newtmgr reset -c profile01 Resets a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_run/",
- "text": "newtmgr run \n\n\nRun test procedures on a device.\n\n\nUsage:\n\n\n newtmgr run [command] -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nThe run command provides subcommands to run test procedures on a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nlist\n\n\nThe newtmgr run list command lists the registered tests on a device.\n\n\n\n\n\n\ntest\n\n\nThe newtmgr run test [all\ntestname] [token-value] command runs the \ntestname\n test or all tests on a device. All tests are run if \nall\n or no \ntestname\n is specified. If a \ntoken-value\n is specified, the token value is output with the log messages.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\nlist\n\n\nnewtmgr run\nlist -c profile01\n\n\nLists all the registered tests on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ntest\n\n\nnewtmgr run \ntest all\n201612161220\n-c profile01\n\n\nRuns all the tests on a device. Outputs the \n201612161220\n token with the log messages. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\ntest\n\n\nnewtmgr run \ntest mynewtsanity\n-c profile01\n\n\nRuns the \nmynewtsanity\n test on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.",
- "title": "newtmgr run"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_run/#newtmgr-run",
- "text": "Run test procedures on a device.",
- "title": "newtmgr run "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_run/#usage",
- "text": "newtmgr run [command] -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_run/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_run/#description",
- "text": "The run command provides subcommands to run test procedures on a device. Newtmgr uses the conn_profile connection profile to connect to the device. Sub-command Explanation list The newtmgr run list command lists the registered tests on a device. test The newtmgr run test [all testname] [token-value] command runs the testname test or all tests on a device. All tests are run if all or no testname is specified. If a token-value is specified, the token value is output with the log messages.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_run/#examples",
- "text": "Sub-command Usage Explanation list newtmgr run list -c profile01 Lists all the registered tests on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. test newtmgr run test all 201612161220 -c profile01 Runs all the tests on a device. Outputs the 201612161220 token with the log messages. Newtmgr connects to the device over a connection specified in the profile01 connection profile. test newtmgr run test mynewtsanity -c profile01 Runs the mynewtsanity test on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile.",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_stat/",
- "text": "newtmgr stat\n\n\nRead statistics from a device.\n\n\nUsage:\n\n\n newtmgr stat [stats_name] -c \nconn_profile\n [flags] \n newtmgr stat [command] -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nDisplays statistic for the Stats named \nstats_name\n from a device. You can use the \nlist\n subcommand to get a list of the Stats names from the device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device.\n\n\n\n\n\n\n\n\nSub-command\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nThe newtmgr stat [stats_name] command displays the statistics for the \nstats_name\n Stats from a device. It displays the list of Stats names if a \nstats_name\n value is not specified.\n\n\n\n\n\n\nlist\n\n\nThe newtmgr stat list command displays the list of Stats names from a device.\n\n\n\n\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr stat ble_att -c profile01\n\n\nDisplays the \nble_att\n statistics on a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nnewtmgr stat -c profile01\n\n\nDisplays the list of Stats names from a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\nlist\n\n\nnewtmgr stat list -c profile01\n\n\nDisplays the list of Stats names from a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nHere are some example outputs for the \nmyble\n application from the \nEnabling Newt Manager in any app\n tutiorial:\n\n\nThe statistics for the ble_att Stats:\n\n\n$ newtmgr stat ble_att -c myserial\nReturn Code = 0\nStats Name: ble_att\n read_type_req_rx: 0\n read_rsp_rx: 0\n read_group_type_rsp_tx: 0\n prep_write_rsp_tx: 0\n find_type_value_req_tx: 0\n read_type_rsp_rx: 0\n read_mult_req_rx: 0\n notify_req_tx: 0\n indicate_req_tx: 0\n\n ...\n write_cmd_rx: 0\n prep_write_rsp_rx: 0\n read_type_rsp_tx: 0\n read_req_tx: 0\n read_mult_req_tx: 0\n read_group_type_req_rx: 0\n write_rsp_tx: 0\n exec_write_rsp_rx: 0\n\n\n\n\n\nThe list of Stats names:\n\n\n$ newtmgr stat -c myserial\n[stat ble_l2cap ble_att ble_gap ble_gattc ble_gatts ble_hs ble_ll_conn ble_ll ble_phy]\nReturn Code = 0\n\n\n\n\n\nThe list of Stats names using the list subcommand:\n\n\n$ newtmgr stat list -c myserial\n[stat ble_l2cap ble_att ble_gap ble_gattc ble_gatts ble_hs ble_ll_conn ble_ll ble_phy]\nReturn Code = 0",
- "title": "newtmgr stat"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_stat/#newtmgr-stat",
- "text": "Read statistics from a device.",
- "title": "newtmgr stat"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_stat/#usage",
- "text": "newtmgr stat [stats_name] -c conn_profile [flags] \n newtmgr stat [command] -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_stat/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_stat/#description",
- "text": "Displays statistic for the Stats named stats_name from a device. You can use the list subcommand to get a list of the Stats names from the device. Newtmgr uses the conn_profile connection profile to connect to the device. Sub-command Explanation The newtmgr stat [stats_name] command displays the statistics for the stats_name Stats from a device. It displays the list of Stats names if a stats_name value is not specified. list The newtmgr stat list command displays the list of Stats names from a device.",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_stat/#examples",
- "text": "Sub-command Usage Explanation newtmgr stat ble_att -c profile01 Displays the ble_att statistics on a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. newtmgr stat -c profile01 Displays the list of Stats names from a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. list newtmgr stat list -c profile01 Displays the list of Stats names from a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. Here are some example outputs for the myble application from the Enabling Newt Manager in any app tutiorial: The statistics for the ble_att Stats: $ newtmgr stat ble_att -c myserial\nReturn Code = 0\nStats Name: ble_att\n read_type_req_rx: 0\n read_rsp_rx: 0\n read_group_type_rsp_tx: 0\n prep_write_rsp_tx: 0\n find_type_value_req_tx: 0\n read_type_rsp_rx: 0\n read_mult_req_rx: 0\n notify_req_tx: 0\n indicate_req_tx: 0\n\n ...\n write_cmd_rx: 0\n prep_write_rsp_rx: 0\n read_type_rsp_tx: 0\n read_req_tx: 0\n read_mult_req_tx: 0\n read_group_type_req_rx: 0\n write_rsp_tx: 0\n exec_write_rsp_rx: 0 The list of Stats names: $ newtmgr stat -c myserial\n[stat ble_l2cap ble_att ble_gap ble_gattc ble_gatts ble_hs ble_ll_conn ble_ll ble_phy]\nReturn Code = 0 The list of Stats names using the list subcommand: $ newtmgr stat list -c myserial\n[stat ble_l2cap ble_att ble_gap ble_gattc ble_gatts ble_hs ble_ll_conn ble_ll ble_phy]\nReturn Code = 0",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_taskstats/",
- "text": "newtmgr taskstat \n\n\nRead task statistics from a device.\n\n\nUsage:\n\n\n newtmgr taskstat -c \nconn_profile\n [flags] \n\n\n\n\n\nGlobal Flags:\n\n\n -c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\n\n\n\n\nDescription\n\n\nReads and displays the task statistics from a device. Newtmgr uses the \nconn_profile\n connection profile to connect to the device. It lists the following statistics for each task: \n\n\n\n\ntask\n: Task name\n\n\npri\n: Task priority\n\n\nruntime\n: The time (ms) that the task has been running for\n\n\ncsw\n: Number of times the task has switched context\n\n\nstksz\n: Stack size allocated for the task \n\n\nstkuse\n: Actual stack size the task uses\n\n\nlast_checkin\n: Last sanity checkin with the \nSanity Task\n\n\nnext_checkin\n: Next sanity checkin\n\n\n\n\nExamples\n\n\n\n\n\n\n\n\nSub-command\n\n\nUsage\n\n\nExplanation\n\n\n\n\n\n\n\n\n\n\n\n\nnewtmgr taskstat\n-c profile0\n\n\nReads and displays the task statistics from a device. Newtmgr connects to the device over a connection specified in the \nprofile01\n connection profile.\n\n\n\n\n\n\n\n\nHere is an example output for the \nmyble\n application from the \nEnabling Newt Manager in any app\n tutiorial:\n\n\nnewtmgr taskstat -c myserial \nReturn Code = 0\n task pri tid runtime csw stksz stkuse last_checkin next_checkin\n idle 255 0 151917 47 64 34 0 0\n main 127 1 2 59 512 188 0 0\n ble_ll 0 2 0 14 80 56 0 0",
- "title": "newtmgr taskstat"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_taskstats/#newtmgr-taskstat",
- "text": "Read task statistics from a device.",
- "title": "newtmgr taskstat "
- },
- {
- "location": "/newtmgr/command_list/newtmgr_taskstats/#usage",
- "text": "newtmgr taskstat -c conn_profile [flags]",
- "title": "Usage:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_taskstats/#global-flags",
- "text": "-c, --conn string connection profile to use.\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received",
- "title": "Global Flags:"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_taskstats/#description",
- "text": "Reads and displays the task statistics from a device. Newtmgr uses the conn_profile connection profile to connect to the device. It lists the following statistics for each task: task : Task name pri : Task priority runtime : The time (ms) that the task has been running for csw : Number of times the task has switched context stksz : Stack size allocated for the task stkuse : Actual stack size the task uses last_checkin : Last sanity checkin with the Sanity Task next_checkin : Next sanity checkin",
- "title": "Description"
- },
- {
- "location": "/newtmgr/command_list/newtmgr_taskstats/#examples",
- "text": "Sub-command Usage Explanation newtmgr taskstat -c profile0 Reads and displays the task statistics from a device. Newtmgr connects to the device over a connection specified in the profile01 connection profile. Here is an example output for the myble application from the Enabling Newt Manager in any app tutiorial: newtmgr taskstat -c myserial \nReturn Code = 0\n task pri tid runtime csw stksz stkuse last_checkin next_checkin\n idle 255 0 151917 47 64 34 0 0\n main 127 1 2 59 512 188 0 0\n ble_ll 0 2 0 14 80 56 0 0",
- "title": "Examples"
- },
- {
- "location": "/newtmgr/install_mac/",
- "text": "Installing Newtmgr on Mac OS\n\n\nNewtmgr is supported on Mac OS X 64 bit platforms and has been tested on Mac OS 10.9 and higher.\n\n\nThis page shows you how to install the following versions of newtmgr:\n\n\n\n\nThe latest stable release version (1.0.0)\n\n\nThe latest from the master branch (unstable)\n\n\n\n\nNote:\n If you would like to contribute to the newtmgr tool, see \nSetting Up Go Environment to Contribute to Newt and Newtmgr Tools\n.\n\n\nAdding the runtimeco/homebrew-mynewt Tap:\n\n\nYou should have added the runtimeco/homebrew-mynewt tap when you installed the \nnewt\n tool. Run the following commands if you have not done so:\n\n\n$brew tap runtimeco/homebrew-mynewt\n$brew update\n\n\n\n\n\n\n\nInstalling the Latest Release Version of Newtmgr\n\n\nInstall the latest stable release version (1.0.0) of newtmgr:\n\n\nbrew install mynewt-newtmgr\n==\n Installing mynewt-newtmgr from runtimeco/mynewt\n==\n Downloading https://github.com/runtimeco/binary-releases/raw/master/mynewt-newt-tools_1.0.0/mynewt-newtmgr-1.0.0.mavericks.bottle.tar.gz\n==\n Downloading from https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/mynewt-newtmgr-1.0.0.maveric\n######################################################################## 100.0%\n==\n Pouring mynewt-newtmgr-1.0.0.mavericks.bottle.tar.gz\n\ud83c\udf7a /usr/local/Cellar/mynewt-newtmgr/1.0.0: 3 files, 15.2MB\n\n\n\n\n\n\n\nNote:\n This installs the newtmgr 1.0.0 binary that has been tested on Mac OS 10.9 and higher. If you are running an earlier version of Mac OS, the installation will install the latest version of Go and compile newtmgr locally.\n\n\n\nCheck that you are using the installed version of newtmgr:\n\n\n$which newtmgr\n/usr/local/bin/newtmgr\nls -l /usr/local/bin/newtmgr\nlrwxr-xr-x 1 user staff 42 Apr 15 09:14 /usr/local/bin/newtmgr -\n ../Cellar/mynewt-newtmgr/1.0.0/bin/newtmgr\n\n\n\n\n\nNote:\n If you previously built newtmgr from source and the output of \nwhich newtmgr\n shows \"$GOPATH/bin/newtmgr\", you will need to move \"$GOPATH/bin\" after \"/usr/local/bin\" in your $PATH.\n\n\n\nGet information about newtmgr:\n\n\n$newtmgr help\nNewtmgr helps you manage remote devices running the Mynewt OS\n\nUsage:\n newtmgr [flags]\n newtmgr [command]\n\nAvailable Commands:\n config Read or write a config value on a device\n conn Manage newtmgr connection profiles\n crash Send a crash command to a device\n datetime Manage datetime on a device\n echo Send data to a device and display the echoed back data\n fs Access files on a device\n image Manage images on a device\n log Manage logs on a device\n mpstat Read memory pool statistics from a device\n reset Send reset request to a device\n run Run test procedures on a device\n stat Read statistics from a device\n taskstat Read task statistics from a device\n\nFlags:\n -c, --conn string connection profile to use\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\nUse \nnewtmgr [command] --help\n for more information about a command.\n\n\n\n\n\n\n\nInstalling Newtmgr from the Master Branch\n\n\nWe recommend that you use the latest stable release version (1.0.0) of newtmgr. If you would like to use the master branch with the latest updates, you can install newtmgr from the HEAD of the master branch. \n\n\n Notes: \n\n\n\n\nThe master branch may be unstable.\n\n\nThis installation will install the latest version of Go on your computer, if it is not installed, and compile newtmgr locally. \n\n\n\n\n\nIf you already installed newtgmr, unlink the current version:\n\n\n$brew unlink mynewt-newtmgr\n\n\n\n\n\n\nInstall the latest unstable version of newtmgr from the master branch:\n\n\n$brew install --HEAD mynewt-newtmgr\n==\n Installing mynewt-newtmgr from runtimeco/mynewt\n==\n Cloning https://github.com/apache/incubator-mynewt-newt.git\nCloning into \n/Users/\nuser\n/Library/Caches/Homebrew/mynewt-newtmgr--git\n...\nremote: Counting objects: 623, done.\nremote: Compressing objects: 100% (501/501), done.\nremote: Total 623 (delta 154), reused 323 (delta 84), pack-reused 0\nReceiving objects: 100% (623/623), 1.10 MiB | 0 bytes/s, done.\nResolving deltas: 100% (154/154), done.\n==\n Checking out branch master\n==\n go install\n\ud83c\udf7a /usr/local/Cellar/mynewt-newtmgr/HEAD-409f7d3: 3 files, 15.1MB, built in 14 seconds\n\n\n\n\n\n\nTo switch back to the stable release version (1.0.0) of newtmgr, you can run:\n\n\n$brew switch mynewt-newtmgr 1.0.0\nCleaning /usr/local/Cellar/mynewt-newtmgr/1.0.0\nCleaning /usr/local/Cellar/mynewt-newtmgr/HEAD-409f7d3\n1 links created for /usr/local/Cellar/mynewt-newtmgr/1.0.0",
- "title": "Install Newtmgr On Mac OS"
- },
- {
- "location": "/newtmgr/install_mac/#installing-newtmgr-on-mac-os",
- "text": "Newtmgr is supported on Mac OS X 64 bit platforms and has been tested on Mac OS 10.9 and higher. This page shows you how to install the following versions of newtmgr: The latest stable release version (1.0.0) The latest from the master branch (unstable) Note: If you would like to contribute to the newtmgr tool, see Setting Up Go Environment to Contribute to Newt and Newtmgr Tools .",
- "title": "Installing Newtmgr on Mac OS"
- },
- {
- "location": "/newtmgr/install_mac/#adding-the-runtimecohomebrew-mynewt-tap",
- "text": "You should have added the runtimeco/homebrew-mynewt tap when you installed the newt tool. Run the following commands if you have not done so: $brew tap runtimeco/homebrew-mynewt\n$brew update",
- "title": "Adding the runtimeco/homebrew-mynewt Tap:"
- },
- {
- "location": "/newtmgr/install_mac/#installing-the-latest-release-version-of-newtmgr",
- "text": "Install the latest stable release version (1.0.0) of newtmgr: brew install mynewt-newtmgr\n== Installing mynewt-newtmgr from runtimeco/mynewt\n== Downloading https://github.com/runtimeco/binary-releases/raw/master/mynewt-newt-tools_1.0.0/mynewt-newtmgr-1.0.0.mavericks.bottle.tar.gz\n== Downloading from https://raw.githubusercontent.com/runtimeco/binary-releases/master/mynewt-newt-tools_1.0.0/mynewt-newtmgr-1.0.0.maveric\n######################################################################## 100.0%\n== Pouring mynewt-newtmgr-1.0.0.mavericks.bottle.tar.gz\n\ud83c\udf7a /usr/local/Cellar/mynewt-newtmgr/1.0.0: 3 files, 15.2MB Note: This installs the newtmgr 1.0.0 binary that has been tested on Mac OS 10.9 and higher. If you are running an earlier version of Mac OS, the installation will install the latest version of Go and compile newtmgr locally. \nCheck that you are using the installed version of newtmgr: $which newtmgr\n/usr/local/bin/newtmgr\nls -l /usr/local/bin/newtmgr\nlrwxr-xr-x 1 user staff 42 Apr 15 09:14 /usr/local/bin/newtmgr - ../Cellar/mynewt-newtmgr/1.0.0/bin/newtmgr Note: If you previously built newtmgr from source and the output of which newtmgr shows \"$GOPATH/bin/newtmgr\", you will need to move \"$GOPATH/bin\" after \"/usr/local/bin\" in your $PATH. \nGet information about newtmgr: $newtmgr help\nNewtmgr helps you manage remote devices running the Mynewt OS\n\nUsage:\n newtmgr [flags]\n newtmgr [command]\n\nAvailable Commands:\n config Read or write a config value on a device\n conn Manage newtmgr connection profiles\n crash Send a crash command to a device\n datetime Manage datetime on a device\n echo Send data to a device and display the echoed back data\n fs Access files on a device\n image Manage images on a device\n log Manage logs on a device\n mpstat Read memory pool statistics from a device\n reset Send reset request to a device\n run Run test procedures on a device\n stat Read statistics from a device\n taskstat Read task statistics from a device\n\nFlags:\n -c, --conn string connection profile to use\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default info )\n -t, --trace print all bytes transmitted and received\n\nUse newtmgr [command] --help for more information about a command.",
- "title": "Installing the Latest Release Version of Newtmgr"
- },
- {
- "location": "/newtmgr/install_mac/#installing-newtmgr-from-the-master-branch",
- "text": "We recommend that you use the latest stable release version (1.0.0) of newtmgr. If you would like to use the master branch with the latest updates, you can install newtmgr from the HEAD of the master branch. Notes: The master branch may be unstable. This installation will install the latest version of Go on your computer, if it is not installed, and compile newtmgr locally. \nIf you already installed newtgmr, unlink the current version: $brew unlink mynewt-newtmgr \nInstall the latest unstable version of newtmgr from the master branch: $brew install --HEAD mynewt-newtmgr\n== Installing mynewt-newtmgr from runtimeco/mynewt\n== Cloning https://github.com/apache/incubator-mynewt-newt.git\nCloning into /Users/ user /Library/Caches/Homebrew/mynewt-newtmgr--git ...\nremote: Counting objects: 623, done.\nremote: Compressing objects: 100% (501/501), done.\nremote: Total 623 (delta 154), reused 323 (delta 84), pack-reused 0\nReceiving objects: 100% (623/623), 1.10 MiB | 0 bytes/s, done.\nResolving deltas: 100% (154/154), done.\n== Checking out branch master\n== go install\n\ud83c\udf7a /usr/local/Cellar/mynewt-newtmgr/HEAD-409f7d3: 3 files, 15.1MB, built in 14 seconds \nTo switch back to the stable release version (1.0.0) of newtmgr, you can run: $brew switch mynewt-newtmgr 1.0.0\nCleaning /usr/local/Cellar/mynewt-newtmgr/1.0.0\nCleaning /usr/local/Cellar/mynewt-newtmgr/HEAD-409f7d3\n1 links created for /usr/local/Cellar/mynewt-newtmgr/1.0.0",
- "title": "Installing Newtmgr from the Master Branch"
- },
- {
- "location": "/newtmgr/install_linux/",
- "text": "Installing Newtmgr on Linux\n\n\nYou can install the latest stable release (1.0.0) of the newtmgr tool from a Debian binary package (amd64) or from a Debian source package. This page shows you how to:\n\n\n\n\n\n\nSet up your computer to retrieve Debian packages from the runtimeco debian package repository. \n\n\nNote:\n You can skip this step if you already set up your computer to access the runtimeco debian repository when you installed the newt tool. \n\n\n\n\n\n\nInstall the latest stable release version of newtmgr from a Debian binary package. \n\n\n\n\nInstall the latest stable release version of newtmgr from a Debian source package.\n\n\n\n\nIf you are installing on an amd64 platform, we recommend that you install from the binary package.\n\n\nNote:\n We have tested the newtmgr tool binary and apt-get install from the runtimeco Debian package repository for Ubuntu version 16. Earlier Ubuntu versions (for example: Ubuntu 14) may have incompatibility with the repository. We recommend that you upgrade Ubuntu on your computer.\n\n\nNote:\n See \nSetting Up an Go Environment to Contribute to Newt and Newtmgr Tools\n if you want to: \n\n\n\n\nUse the newtmgr tool with the latest updates from the master branch. The master branch may be unstable and we recommend that you use the latest stable release version.\n\n\nContribute to the newtmgr tool. \n\n\n\n\n\n\nSetting Up Your Computer to Get Packages from runtimeco\n\n\nThe newtmgr Debian packages are stored in a private repository on \nhttps://github/runtimeco/debian-mynewt\n. You must set up the following on your computer to retreive packages from the repository:\n\n\nNote\n: You only need to perform this setup once on your computer and you may have already done so when you installed the newt tool. \n\n\n\n\nInstall the \napt-transport-https\n package to use HTTPS to retrieve packages. \n\n\nDownload the public key for the runtimeco debian repository and import the key into the apt keychain.\n\n\nAdd the repository for the binary and source packages to the apt source list.\n\n\n\n\n\nInstall the apt-transport-https package:\n\n\n$sudo apt-get update\n$sudo apt-get install apt-transport-https\n\n\n\n\n\n\n\nDownload the public key for the runtimeco apt repo (\nNote:\n There is a \n-\n after \napt-key add\n):\n\n\nwget -qO - https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/mynewt.gpg.key | sudo apt-key add -\n\n\n\n\n\n\n\nAdd the repository for the binary and source packages to the \nmynewt.list\n apt source list file.\n\n\n$sudo -s\n[sudo] password for \nuser\n:\nroot$ cat \n /etc/apt/sources.list.d/mynewt.list \nEOF\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\nEOF\nroot$exit\n\n\n\n\n\nNote:\n Do not forget to exit the root shell.\n\n\n\nVerify the content of the source list file:\n\n\n$more /etc/apt/sources.list.d/mynewt.list\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\n\n\n\n\n\n\nUpdate the available packages:\n\n\n$sudo apt-get update\n\n\n\n\n\n\n\nNote:\n If you are not using Ubuntu version 16, you may see the following errors. We recommend that you upgrade Ubuntu. We have provided instructions on how to manually download and install the binary package if you choose not to upgrade, but you will want to upgrade Ubuntu if you are installing from source. \n\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/source/Sources Ht\ntpError404\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-amd64/Packa\nges Bad header line\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-i386/Packag\nes HttpError404\n\nE: Some index files failed to download. They have been ignored, or old ones used instead.\n\n\n\n\n\n \n\n\nInstalling the Latest Release of Newtmgr from a Binary Package\n\n\nFor Linux amd64 platforms, you can install the latest stable version (1.0.0) of newtmgr from the newtmgr Debian binary package:\n\n\n$sudo apt-get install newtmgr\nReading package lists... Done\nBuilding dependency tree \nReading state information... Done\nThe following NEW packages will be installed:\n newtmgr\n0 upgraded, 1 newly installed, 0 to remove and 204 not upgraded.\nNeed to get 0 B/2,312 kB of archives.\nAfter this operation, 11.5 MB of additional disk space will be used.\nSelecting previously unselected package newtmgr.\n(Reading database ... 211647 files and directories currently installed.)\nPreparing to unpack .../newtmgr_1.0.0-1_amd64.deb ...\nUnpacking newtmgr (1.0.0-1) ...\nSetting up newtmgr (1.0.0-1) \n\n\n\n\n\n\n\nNote:\n If you are not using Ubuntu version 16 and are not able to update the runtimeco Debian package repo on your computer successfully, you can manually download and install the newtmgr_1.0.0-1_amd64.deb binary package as follows:\n\n\n$wget https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/pool/main/n/newtmgr/newtmgr_1.0.0-1_amd64.deb\n$sudo dpkg -i newtmgr_1.0.0-1_amd64.deb\n\n\n\n\n\n\nSee \nChecking the Installed Version of Newtmgr\n to verify that you are using the installed version of newtmgr.\n\n\n\n\nInstalling the Latest Stable Release of Newtmgr from a Source Package\n\n\nIf you are running Linux on a different architecture, you can install the Debian source package for the latest stable release (1.0.0) of newtmgr. The installation of the source package builds the newtmgr binary and creates a Debian binary package that you then install.\n\n\nNote\n: Newtmgr version 1.0.0 has been tested on Linux amd64 platforms. \n\n\n\n\nInstalling Go\n\n\nYou need Go version 1.7.6 or higher to build Newtmgr version 1.0.0. Currently, the latest Go version that Ubuntu installs is 1.6. Run \ngo version\n to check if you have Go 1.7.6 installed. You can download Go from \nhttps://golang.org/dl/\n.\n\n\n\n\nInstalling from the Source Package\n\n\nCreate a directory and change into the directory, download the source package, and build a binary package from the source package:\n\n\nmkdir newtmgr_source\n$cd newtmgr_source\n$sudo apt-get --build source newtmgr\n[sudo] password for \nuser\n: \n\nsudo apt-get --build source newtmgr\nReading package lists... Done\nNeed to get 1,867 kB of source archives.\nGet:1 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newtmgr 1.0.0-1 (dsc) [822 B]\nGet:2 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newtmgr 1.0.0-1 (tar) [1,864 kB]\nGet:3 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newtmgr 1.0.0-1 (diff) [2,372 B]\nFetched 1,867 kB in 1s (1,767 kB/s) \n\n ...\n\ndpkg-deb: building package \nnewtmgr\n in \n../newtmgr_1.0.0-1_amd64.deb\n.\n dpkg-genchanges --build=any,all \n../newtmgr_1.0.0-1_amd64.changes\ndpkg-genchanges: info: binary-only upload (no source code included)\n dpkg-source --after-build newtmgr-1.0.0\ndpkg-buildpackage: info: binary-only upload (no source included)\nW: Can\nt drop privileges for downloading as file \nnewtmgr_1.0.0-1.dsc\n couldn\nt be accessed by user \n_apt\n. - pkgAcquire::Run (13: Permission denied)\n\n\n\n\n\nNote:\n You can ignore the \"Permission denied\" warning message at the end of the command.\n\n\n\nInstall the newtmgr binary package that is created from the source package:\n\n\nNote:\n The file name for the binary package has the format: newtmgr_1.0.0-1_\narch\n.deb, where \narch\n is a value that identifies your host architecture.\n\n\n$sudo dpkg -i newtmgr_1.0.0-1_amd64.deb \nSelecting previously unselected package newtmgr.\n(Reading database ... 215099 files and directories currently installed.)\nPreparing to unpack newtmgr_1.0.0-1_amd64.deb ...\nUnpacking newtmgr (1.0.0-1) ...\nSetting up newtmgr (1.0.0-1) ...\n\n\n\n\n\n\n\n Checking the Installed Version of Newtmgr\n\n\nAfter you have installed newtmgr from either a Debian binary or source package, check that you are using the installed version of newtmgr from \n/usr/bin\n. \n\n\nCheck the modification time of the binary and the newtmgr tool that you are using:\n\n\n$ls -l /usr/bin/newtmgr\n-rwxr-xr-x 1 root root 11473328 Apr 25 10:10 /usr/bin/newtmgr\n$which newtmgr\n/usr/bin/newtmgr\n\n\n\n\n\nNote:\n If you previously built newtmgr from source and the output of \nwhich newtmgr\n shows \"$GOPATH/bin/newtmgr\", you will need to move \"$GOPATH/bin\" after \"/usr/bin\" for your PATH environment variable and export it.\n\n\n\nGet information about newtmgr:\n\n\n$newtmgr\nNewtmgr helps you manage remote devices running the Mynewt OS\n\nUsage:\n newtmgr [flags]\n newtmgr [command]\n\nAvailable Commands:\n config Read or write a config value on a device\n conn Manage newtmgr connection profiles\n crash Send a crash command to a device\n datetime Manage datetime on a device\n echo Send data to a device and display the echoed back data\n fs Access files on a device\n image Manage images on a device\n log Manage logs on a device\n mpstat Read memory pool statistics from a device\n reset Send reset request to a device\n run Run test procedures on a device\n stat Read statistics from a device\n taskstat Read task statistics from a device\n\nFlags:\n -c, --conn string connection profile to use\n -h, --help Help for newtmgr commands\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --trace print all bytes transmitted and received\n\nUse \nnewtmgr [command] --help\n for more information about a command.\n\n\n\n\n\n```",
- "title": "Install Newtmgr On Linux"
- },
- {
- "location": "/newtmgr/install_linux/#installing-newtmgr-on-linux",
- "text": "You can install the latest stable release (1.0.0) of the newtmgr tool from a Debian binary package (amd64) or from a Debian source package. This page shows you how to: Set up your computer to retrieve Debian packages from the runtimeco debian package repository. Note: You can skip this step if you already set up your computer to access the runtimeco debian repository when you installed the newt tool. Install the latest stable release version of newtmgr from a Debian binary package. Install the latest stable release version of newtmgr from a Debian source package. If you are installing on an amd64 platform, we recommend that you install from the binary package. Note: We have tested the newtmgr tool binary and apt-get install from the runtimeco Debian package repository for Ubuntu version 16. Earlier Ubuntu versions (for example: Ubuntu 14) may have incompatibility with the repository. We recommend that you upgrade Ubuntu on your computer. Note: See Setting Up an Go Environment to Contribute to Newt and Newtmgr Tools if you want to: Use the newtmgr tool with the latest updates from the master branch. The master branch may be unstable and we recommend that you use the latest stable release version. Contribute to the newtmgr tool.",
- "title": "Installing Newtmgr on Linux"
- },
- {
- "location": "/newtmgr/install_linux/#setting-up-your-computer-to-get-packages-from-runtimeco",
- "text": "The newtmgr Debian packages are stored in a private repository on https://github/runtimeco/debian-mynewt . You must set up the following on your computer to retreive packages from the repository: Note : You only need to perform this setup once on your computer and you may have already done so when you installed the newt tool. Install the apt-transport-https package to use HTTPS to retrieve packages. Download the public key for the runtimeco debian repository and import the key into the apt keychain. Add the repository for the binary and source packages to the apt source list. \nInstall the apt-transport-https package: $sudo apt-get update\n$sudo apt-get install apt-transport-https Download the public key for the runtimeco apt repo ( Note: There is a - after apt-key add ): wget -qO - https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/mynewt.gpg.key | sudo apt-key add - Add the repository for the binary and source packages to the mynewt.list apt source list file. $sudo -s\n[sudo] password for user :\nroot$ cat /etc/apt/sources.list.d/mynewt.list EOF\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\nEOF\nroot$exit Note: Do not forget to exit the root shell. \nVerify the content of the source list file: $more /etc/apt/sources.list.d/mynewt.list\ndeb https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main\ndeb-src https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest main \nUpdate the available packages: $sudo apt-get update Note: If you are not using Ubuntu version 16, you may see the following errors. We recommend that you upgrade Ubuntu. We have provided instructions on how to manually download and install the binary package if you choose not to upgrade, but you will want to upgrade Ubuntu if you are installing from source. W: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/source/Sources Ht\ntpError404\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-amd64/Packa\nges Bad header line\n\nW: Failed to fetch https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/dists/latest/main/binary-i386/Packag\nes HttpError404\n\nE: Some index files failed to download. They have been ignored, or old ones used instead.",
- "title": "Setting Up Your Computer to Get Packages from runtimeco"
- },
- {
- "location": "/newtmgr/install_linux/#installing-the-latest-release-of-newtmgr-from-a-binary-package",
- "text": "For Linux amd64 platforms, you can install the latest stable version (1.0.0) of newtmgr from the newtmgr Debian binary package: $sudo apt-get install newtmgr\nReading package lists... Done\nBuilding dependency tree \nReading state information... Done\nThe following NEW packages will be installed:\n newtmgr\n0 upgraded, 1 newly installed, 0 to remove and 204 not upgraded.\nNeed to get 0 B/2,312 kB of archives.\nAfter this operation, 11.5 MB of additional disk space will be used.\nSelecting previously unselected package newtmgr.\n(Reading database ... 211647 files and directories currently installed.)\nPreparing to unpack .../newtmgr_1.0.0-1_amd64.deb ...\nUnpacking newtmgr (1.0.0-1) ...\nSetting up newtmgr (1.0.0-1) Note: If you are not using Ubuntu version 16 and are not able to update the runtimeco Debian package repo on your computer successfully, you can manually download and install the newtmgr_1.0.0-1_amd64.deb binary package as follows: $wget https://raw.githubusercontent.com/runtimeco/debian-mynewt/master/pool/main/n/newtmgr/newtmgr_1.0.0-1_amd64.deb\n$sudo dpkg -i newtmgr_1.0.0-1_amd64.deb \nSee Checking the Installed Version of Newtmgr to verify that you are using the installed version of newtmgr.",
- "title": "Installing the Latest Release of Newtmgr from a Binary Package"
- },
- {
- "location": "/newtmgr/install_linux/#installing-the-latest-stable-release-of-newtmgr-from-a-source-package",
- "text": "If you are running Linux on a different architecture, you can install the Debian source package for the latest stable release (1.0.0) of newtmgr. The installation of the source package builds the newtmgr binary and creates a Debian binary package that you then install. Note : Newtmgr version 1.0.0 has been tested on Linux amd64 platforms.",
- "title": "Installing the Latest Stable Release of Newtmgr from a Source Package"
- },
- {
- "location": "/newtmgr/install_linux/#installing-go",
- "text": "You need Go version 1.7.6 or higher to build Newtmgr version 1.0.0. Currently, the latest Go version that Ubuntu installs is 1.6. Run go version to check if you have Go 1.7.6 installed. You can download Go from https://golang.org/dl/ .",
- "title": "Installing Go"
- },
- {
- "location": "/newtmgr/install_linux/#installing-from-the-source-package",
- "text": "Create a directory and change into the directory, download the source package, and build a binary package from the source package: mkdir newtmgr_source\n$cd newtmgr_source\n$sudo apt-get --build source newtmgr\n[sudo] password for user : \n\nsudo apt-get --build source newtmgr\nReading package lists... Done\nNeed to get 1,867 kB of source archives.\nGet:1 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newtmgr 1.0.0-1 (dsc) [822 B]\nGet:2 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newtmgr 1.0.0-1 (tar) [1,864 kB]\nGet:3 https://raw.githubusercontent.com/runtimeco/debian-mynewt/master latest/main newtmgr 1.0.0-1 (diff) [2,372 B]\nFetched 1,867 kB in 1s (1,767 kB/s) \n\n ...\n\ndpkg-deb: building package newtmgr in ../newtmgr_1.0.0-1_amd64.deb .\n dpkg-genchanges --build=any,all ../newtmgr_1.0.0-1_amd64.changes\ndpkg-genchanges: info: binary-only upload (no source code included)\n dpkg-source --after-build newtmgr-1.0.0\ndpkg-buildpackage: info: binary-only upload (no source included)\nW: Can t drop privileges for downloading as file newtmgr_1.0.0-1.dsc couldn t be accessed by user _apt . - pkgAcquire::Run (13: Permission denied) Note: You can ignore the \"Permission denied\" warning message at the end of the command. \nInstall the newtmgr binary package that is created from the source package: Note: The file name for the binary package has the format: newtmgr_1.0.0-1_ arch .deb, where arch is a value that identifies your host architecture. $sudo dpkg -i newtmgr_1.0.0-1_amd64.deb \nSelecting previously unselected package newtmgr.\n(Reading database ... 215099 files and directories currently installed.)\nPreparing to unpack newtmgr_1.0.0-1_amd64.deb ...\nUnpacking newtmgr (1.0.0-1) ...\nSetting up newtmgr (1.0.0-1) ...",
- "title": "Installing from the Source Package"
- },
- {
- "location": "/newtmgr/install_windows/",
- "text": "Installing Newtmgr on Windows\n\n\nYou can build and install the newtmgr tool from the latest source on the master branch. Newtmgr is a Go (golang) package. This guide shows you how to install the tool from source. It assumes that you already installed the \nnewt tool on Windows\n and have the Windows development environment and Go workspace set up.\n\n\nDownloading and Installing the Newtmgr Tool\n\n\nThe newtmgr Go package is \nmynewt.apache.org/newtmgr/newtmgr\n. It is stored in the \nApache Mynewt newtmgr tool repository mirrored on github\n.\n\n\nRun the \ngo get\n command, from your Go workspace, to download, build, and install the newtmgr tool:\n\n\n$cd $GOPATH\n$go get mynewt.apache.org/newtmgr/newtmgr\n$cd $GOPATH/src/mynewt.apache.org/newtmgr\n$ls\nDISCLAIMER NOTICE newtmgr\nLICENSE README.md nmxact\n$git status\nOn branch master\nYour branch is up-to-date with \norigin/master\n.\n\nnothing to commit, working directory clean\n\n\n\n\n\n\nCheck that the newtmgr binary is installed and you are using the one from \n$GOPATH/bin\n:\n\n\n$ls $GOPATH/bin/newtmgr\n~/dev/go/bin/newtmgr\n$which newtmgr\n~/dev/go/bin/newtmgr\n\n\n\n\n\n\nGet information about the newtmgr tool:\n\n\n$newtmgr\nNewtmgr helps you manage remote devices running the Mynewt OS\n\nUsage:\n newtmgr [flags]\n newtmgr [command]\n\nAvailable Commands:\n config Read or write config value on target\n conn Manage newtmgr connection profiles\n crash Send crash command to remote endpoint using newtmgr\n datetime Manage datetime on the device\n echo Send data to remote endpoint using newtmgr, and receive data back\n fs Access files on device\n help Help about any command\n image Manage images on remote instance\n log Handles log on remote instance\n mpstat Read mempool statistics from a remote endpoint\n reset Performs a soft reset of target device\n run Run procedures on remote device\n stat Read statistics from a remote endpoint\n taskstat Read statistics from a remote endpoint\n\nFlags:\n -c, --conn string connection profile to use.\n -n, --devicename string name of target BLE device; overrides profile setting\n -h, --help help for newtmgr\n -l, --loglevel string log level to use (default \ninfo\n)\n -t, --timeout float timeout in seconds (partial seconds allowed) (defaul t 10)\n -r, --tries int total number of tries in case of timeout (default 1)\n\nUse \nnewtmgr [command] --help\n for more information about a command.",
- "title": "Install Newtmgr On Windows"
- },
- {
- "location": "/newtmgr/install_windows/#installing-newtmgr-on-windows",
- "text": "You can build and install the newtmgr tool from the latest source on the master branch. Newtmgr is a Go (golang) package. This guide shows you how to install the tool from source. It assumes that you already installed the newt tool on Windows and have the Windows development environment and Go workspace set up.",
- "title": "Installing Newtmgr on Windows"
- },
- {
- "location": "/newtmgr/install_windows/#downloading-and-installing-the-newtmgr-tool",
- "text": "The newtmgr Go package is mynewt.apache.org/newtmgr/newtmgr . It is stored in the Apache Mynewt newtmgr tool repository mirrored on github . Run the go get command, from your Go workspace, to download, build, and install the newtmgr tool: $cd $GOPATH\n$go get mynewt.apache.org/newtmgr/newtmgr\n$cd $GOPATH/src/mynewt.apache.org/newtmgr\n$ls\nDISCLAIMER NOTICE newtmgr\nLICENSE README.md nmxact\n$git status\nOn branch master\nYour branch is up-to-date with origin/master .\n\nnothing to commit, working directory clean \nCheck that the newtmgr binary is installed and you are using the one from $GOPATH/bin : $ls $GOPATH/bin/newtmgr\n~/dev/go/bin/newtmgr\n$which newtmgr\n~/dev/go/bin/newtmgr \nGet information about the newtmgr tool: $newtmgr\nNewtmgr helps you manage remote devices running the Mynewt OS\n\nUsage:\n newtmgr [flags]\n newtmgr [command]\n\nAvailable Commands:\n config Read or write config value on target\n conn Manage newtmgr connection profiles\n crash Send crash command to remote endpoint using newtmgr\n datetime Manage datetime on the device\n echo Send data to remote endpoint using newtmgr, and receive data back\n fs Access files on device\n help Help about any command\n image Manage images on remote instance\n log Handles log on remote instance\n mpstat Read mempool statistics from a remote endpoint\n reset Performs a soft reset of target device\n run Run procedures on remote device\n stat Read statistics from a remote endpoint\n taskstat Read statistics from a remote endpoint\n\nFlags:\n -c, --conn string connection profile to use.\n -n, --devicename string name of target BLE device; overrides profile setting\n -h, --help help for newtmgr\n -l, --loglevel string log level to use (default info )\n -t, --timeout float timeout in seconds (partial seconds allowed) (defaul t 10)\n -r, --tries int total number of tries in case of timeout (default 1)\n\nUse newtmgr [command] --help for more information about a command.",
- "title": "Downloading and Installing the Newtmgr Tool"
- },
- {
- "location": "/known_issues/",
- "text": "Known Issues\n\n\nHere is a list of known issues and workarounds:\n\n\n\n\n\n\nnewt install\n returns the following error:\n\n\nReadDesc: No matching branch for apache-mynewt-core repo\nNo matching branch for apache-mynewt-core repo\n\n\n\n\n\nThe apache-mynewt-core Git repository location has changed due to Mynewt's graduation from an incubator project to an Apache top level project. The HTTP redirect to the new location may fail for some users. \n\n\nWorkaround:\n Edit the \nproject.yml\n file and change the line \nrepo: incubator-mynewt-core\n as shown in the following example to \nrepo: mynewt-core\n:\n\n\n repository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core",
- "title": "Known Issues"
- },
- {
- "location": "/known_issues/#known-issues",
- "text": "Here is a list of known issues and workarounds: newt install returns the following error: ReadDesc: No matching branch for apache-mynewt-core repo\nNo matching branch for apache-mynewt-core repo The apache-mynewt-core Git repository location has changed due to Mynewt's graduation from an incubator project to an Apache top level project. The HTTP redirect to the new location may fail for some users. Workaround: Edit the project.yml file and change the line repo: incubator-mynewt-core as shown in the following example to repo: mynewt-core : repository.apache-mynewt-core:\n type: github\n vers: 1-latest\n user: apache\n repo: incubator-mynewt-core",
- "title": "Known Issues"
- },
- {
- "location": "/faq/go_env/",
- "text": "Contributing to Newt or Newtmgr Tools\n\n\nNewt and Newtmgr are written in Go (golang). This guide shows you how to install Go and setup your environment to update and build the tools if you want to: \n\n\n\n\nContribute to newt or newtmgr features or fix bugs.\n\n\nBuild the tools with latest updates from the master branch on a Linux platform.\n\n\n\n\nThis guide shows you how to perform the following:\n\n\n\n\nInstall Go on either Mac OS X or Linux. (Tasks that are specific to each platform are called out.)\n\n\nSetup the Go environment.\n\n\nDownload the source, build, and install the newt or newtmgr tools.\n\n\nUpdate and rebuild the tools. \n\n\n\n\nNote:\n You will also need to read and follow the instructions from the \nFAQ\n to set up your git repos to submit changes.\n\n\nStep 1: Installing Go\n\n\nThe latest master branch of newt and newtmgr requires GO version 1.7.6 or higher. You can skip this step and proceed to Step 2 if you already have Go version 1.7.6 or higher installed.\n\n\n\n\nInstalling Go on Mac OS X\n\n\nIf you do not have Homebrew installed, run the following command. You will be prompted for your sudo password.\n\n\n$ ruby -e \n$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\n\n\n\n\n\n\nYou can also extract (or \ngit clone\n) Homebrew and install it to /usr/local.\n\n\n\nUse brew to install Go:\n\n\n$ brew install go\n==\n \n...\n... \n==\n *Summary*\n\ud83c\udf7a //usr/local/Cellar/go/1.8.1: 7,030 files, 281.8MB, built in 1 minute 12 seconds\n\n\n\n\n\nYou can also download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.\n\n\n\n\nInstalling Go on Linux\n\n\nYou can download Go from \nhttps://golang.org/dl/\n.\n\n\n\n\nStep 2: Setting Up Your Go Environment\n\n\nThis section describes the Go environment and how to setup a Go workspace. If you already have a Go workspace for your other Go projects, you can skip this step and proceed to Step 3.\n\n\nGo provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the newt or newtmgr package repository into your local Go environment. The Go language environment dictates a specific directory structure, or workspace in Go parlance. It must contain three sibling directories with the names \nsrc\n, \npkg\n and \nbin\n: \n\n\n\n\nsrc contains Go source files organized into packages (one package per directory)\n\n\npkg contains package objects\n\n\nbin contains the Go application executables that Go builds and installs.\n\n\n\n\nThe \nGOPATH\n environment variable specifies the location of your workspace. To setup this workspace environment, create a \ndev\n directory and then a \ngo\n directory under it. Set the GOPATH environment variable to this directory where you will clone the newt and newtmgr repositories.\n\n\n$ cd $HOME\n$ mkdir -p dev/go \n$ cd dev/go\n$ export GOPATH=`pwd`\n\n\n\n\n\n\nAdd the following export statements to your ~/.bash_profile file and source the file:\n\n\nexport GOPATH=$HOME/dev/go\nexport PATH=$GOPATH/bin:$PATH\n\n\n\n\n\n\n\nStep 3: Downloading the Source and Installing the Tools\n\n\nNewt and newtmgr are individual Go packages and have their own git repositories. You can download the source and install one or both tools.\n\n\nWe use the \ngo get\n command to download the source, build, and install the binary in the \n$GOPATH/bin\n directory. \n\n\n\n\nDownloading and Installing the Newt Tool\n\n\nThe newt Go package is \nmynewt.apache.org/newt/newt\n and is stored in the \nApache Mynewt newt tool repository mirrored on github\n. \n\n\nDownload the newt package source and install the tool:\n\n\n$cd $GOPATH\n$go get mynewt.apache.org/newt/newt\n$cd $GOPATH/src/mynewt.apache.org/newt\n$ls \nDISCLAIMER RELEASE_NOTES.md util\nINSTALLING.md build.sh viper\nLICENSE newt yaml\nNOTICE newtmgr\nREADME.md newtvm\n$git status\nOn branch master\nYour branch is up-to-date with \norigin/master\n.\n\nnothing to commit, working directory clean\n\n\n\n\n\n\n\nNote:\n The source code under the \nnewtmgr\n directory is no longer used or updated. The current \nnewtmgr\n source has its own Git repository.\n\n\n\nCheck that the newt binary is installed and you are using the one from \n $GOPATH/bin\n:\n\n\n$ls $GOPATH/bin/newt\n~/dev/go/bin/newt\n$which newt\n~/dev/go/bin/newt\n$newt version\nApache Newt (incubating) version: 1.0.0-dev\n\n\n\n\n\n\n\nDownloading and Installing the Newtmgr Tool\n\n\nThe newtmgr Go package is \nmynewt.apache.org/newtmgr/newtmgr\n. It is stored in the \nApache Mynewt newtmgr tool repository mirrored on github\n.\n\n\nDownload the newtmgr package and install the tool:\n\n\nNote:\n \n-ldflags -s\n must be passed to the \ngo get\n command.\n\n\n$cd $GOPATH\n$go get -ldflags -s mynewt.apache.org/newtmgr/newtmgr\n$cd $GOPATH/src/mynewt.apache.org/newtmgr\n$ls\nDISCLAIMER NOTICE newtmgr\nLICENSE README.md nmxact\n$git status\nOn branch master\nYour branch is up-to-date with \norigin/master\n.\n\nnothing to commit, working directory clean\n\n\n\n\n\n\nCheck that the newtmgr binary is installed and you are using the one from \n$GOPATH/bin\n:\n\n\n$ls $GOPATH/bin/newtmgr\n~/dev/go/bin/newtmgr\n$which newtmgr\n~/dev/go/bin/newtmgr\n\n\n\n\n\n\n\nStep 4: Updating and Rebuilding the Tools:\n\n\nThis section shows you how to rebuild the newt and newtmgr tools with the latest updates from the master branch or after you have made changes in your branch. \n\n\nHere is the general procedure to rebuild either the newt or newtmgr tool. The only difference is the directory where you will be executing the commands from. You will need to repeat the procedure to rebuild both tools.\n\n\n\n\nChange to the directory where the local Git repository for the tool is installed.\n\n\nPull the latest changes from the master branch. If you made changes you will need to rebase with \norigin master\n (See \nFAQ\n).\n\n\nBuild and install the tool.\n\n\n\n\n\nChange to the directory where the source for the tool is installed.\n\n\nFor the \nnewt\n tool:\n\n\n$cd $GOPATH/src/mynewt.apache.org/newt/newt\n\n\n\n\n\nFor the \nnewtmgr\n tool:\n\n\n$cd $GOPATH/src/mynewt.apache.org/newtmgr/newtmgr\n\n\n\n\n\n\nAfter you change to the specific tool directory, get the latest updates from the master branch. If you made changes and need to rebase with the origin, add the \n--rebase origin master\n arguments to the \ngit pull\n command:\n\n\n$git pull \n\n\n\n\n\n\nBuild and install the tool. The updated binary will be installed in the \n$GOPATH/bin\n directory: \n\n\n(\nNote:\n \n-ldflags -s\n must be passed to the \ngo install\n command if you are rebuilding newtmgr)\n\n\n$go install\n\n\n\n\n\nYou can run the \nls -l\n command to check the modification time for the binary to ensure the new version is installed.",
- "title": "Setting Up Go to Contribute to Newt and Newtmgr Tools"
- },
- {
- "location": "/faq/go_env/#contributing-to-newt-or-newtmgr-tools",
- "text": "Newt and Newtmgr are written in Go (golang). This guide shows you how to install Go and setup your environment to update and build the tools if you want to: Contribute to newt or newtmgr features or fix bugs. Build the tools with latest updates from the master branch on a Linux platform. This guide shows you how to perform the following: Install Go on either Mac OS X or Linux. (Tasks that are specific to each platform are called out.) Setup the Go environment. Download the source, build, and install the newt or newtmgr tools. Update and rebuild the tools. Note: You will also need to read and follow the instructions from the FAQ to set up your git repos to submit changes.",
- "title": "Contributing to Newt or Newtmgr Tools"
- },
- {
- "location": "/faq/go_env/#step-1-installing-go",
- "text": "The latest master branch of newt and newtmgr requires GO version 1.7.6 or higher. You can skip this step and proceed to Step 2 if you already have Go version 1.7.6 or higher installed.",
- "title": "Step 1: Installing Go"
- },
- {
- "location": "/faq/go_env/#installing-go-on-mac-os-x",
- "text": "If you do not have Homebrew installed, run the following command. You will be prompted for your sudo password. $ ruby -e $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install) You can also extract (or git clone ) Homebrew and install it to /usr/local. \nUse brew to install Go: $ brew install go\n== \n...\n... \n== *Summary*\n\ud83c\udf7a //usr/local/Cellar/go/1.8.1: 7,030 files, 281.8MB, built in 1 minute 12 seconds You can also download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.",
- "title": "Installing Go on Mac OS X"
- },
- {
- "location": "/faq/go_env/#installing-go-on-linux",
- "text": "You can download Go from https://golang.org/dl/ .",
- "title": "Installing Go on Linux"
- },
- {
- "location": "/faq/go_env/#step-2-setting-up-your-go-environment",
- "text": "This section describes the Go environment and how to setup a Go workspace. If you already have a Go workspace for your other Go projects, you can skip this step and proceed to Step 3. Go provides an environment to compile Go code, construct Go packages, and import Go code. You will use Go commands to import the newt or newtmgr package repository into your local Go environment. The Go language environment dictates a specific directory structure, or workspace in Go parlance. It must contain three sibling directories with the names src , pkg and bin : src contains Go source files organized into packages (one package per directory) pkg contains package objects bin contains the Go application executables that Go builds and installs. The GOPATH environment variable specifies the location of your workspace. To setup this workspace environment, create a dev directory and then a go directory under it. Set the GOPATH environment variable to this directory where you will clone the newt and newtmgr repositories. $ cd $HOME\n$ mkdir -p dev/go \n$ cd dev/go\n$ export GOPATH=`pwd` \nAdd the following export statements to your ~/.bash_profile file and source the file: export GOPATH=$HOME/dev/go\nexport PATH=$GOPATH/bin:$PATH",
- "title": "Step 2: Setting Up Your Go Environment"
- },
- {
- "location": "/faq/go_env/#step-3-downloading-the-source-and-installing-the-tools",
- "text": "Newt and newtmgr are individual Go packages and have their own git repositories. You can download the source and install one or both tools. We use the go get command to download the source, build, and install the binary in the $GOPATH/bin directory.",
- "title": "Step 3: Downloading the Source and Installing the Tools"
- },
- {
- "location": "/faq/go_env/#downloading-and-installing-the-newt-tool",
- "text": "The newt Go package is mynewt.apache.org/newt/newt and is stored in the Apache Mynewt newt tool repository mirrored on github . Download the newt package source and install the tool: $cd $GOPATH\n$go get mynewt.apache.org/newt/newt\n$cd $GOPATH/src/mynewt.apache.org/newt\n$ls \nDISCLAIMER RELEASE_NOTES.md util\nINSTALLING.md build.sh viper\nLICENSE newt yaml\nNOTICE newtmgr\nREADME.md newtvm\n$git status\nOn branch master\nYour branch is up-to-date with origin/master .\n\nnothing to commit, working directory clean Note: The source code under the newtmgr directory is no longer used or updated. The current newtmgr source has its own Git repository. \nCheck that the newt binary is installed and you are using the one from $GOPATH/bin : $ls $GOPATH/bin/newt\n~/dev/go/bin/newt\n$which newt\n~/dev/go/bin/newt\n$newt version\nApache Newt (incubating) version: 1.0.0-dev",
- "title": "Downloading and Installing the Newt Tool"
- },
- {
- "location": "/faq/go_env/#downloading-and-installing-the-newtmgr-tool",
- "text": "The newtmgr Go package is mynewt.apache.org/newtmgr/newtmgr . It is stored in the Apache Mynewt newtmgr tool repository mirrored on github . Download the newtmgr package and install the tool: Note: -ldflags -s must be passed to the go get command. $cd $GOPATH\n$go get -ldflags -s mynewt.apache.org/newtmgr/newtmgr\n$cd $GOPATH/src/mynewt.apache.org/newtmgr\n$ls\nDISCLAIMER NOTICE newtmgr\nLICENSE README.md nmxact\n$git status\nOn branch master\nYour branch is up-to-date with origin/master .\n\nnothing to commit, working directory clean \nCheck that the newtmgr binary is installed and you are using the one from $GOPATH/bin : $ls $GOPATH/bin/newtmgr\n~/dev/go/bin/newtmgr\n$which newtmgr\n~/dev/go/bin/newtmgr",
- "title": "Downloading and Installing the Newtmgr Tool"
- },
- {
- "location": "/faq/go_env/#step-4-updating-and-rebuilding-the-tools",
- "text": "This section shows you how to rebuild the newt and newtmgr tools with the latest updates from the master branch or after you have made changes in your branch. Here is the general procedure to rebuild either the newt or newtmgr tool. The only difference is the directory where you will be executing the commands from. You will need to repeat the procedure to rebuild both tools. Change to the directory where the local Git repository for the tool is installed. Pull the latest changes from the master branch. If you made changes you will need to rebase with origin master (See FAQ ). Build and install the tool. \nChange to the directory where the source for the tool is installed. For the newt tool: $cd $GOPATH/src/mynewt.apache.org/newt/newt For the newtmgr tool: $cd $GOPATH/src/mynewt.apache.org/newtmgr/newtmgr \nAfter you change to the specific tool directory, get the latest updates from the master branch. If you made changes and need to rebase with the origin, add the --rebase origin master arguments to the git pull command: $git pull \nBuild and install the tool. The updated binary will be installed in the $GOPATH/bin directory: ( Note: -ldflags -s must be passed to the go install command if you are rebuilding newtmgr) $go install You can run the ls -l command to check the modification time for the binary to ensure the new version is installed.",
- "title": "Step 4: Updating and Rebuilding the Tools:"
- },
- {
- "location": "/faq/ide/",
- "text": "Developing Mynewt Applications with Visual Studio Code\n\n\nThis guide shows you how to set up Visual Studio Code to develop and debug Mynewt applications. Visual Studio Code is supported on Mac OS, Linux, and Windows. This guide shows you how to:\n\n\n\n\nInstall Visual Studio Code. \n\n\nInstall the C/C++ and debugger extensions.\n\n\nDefine task configurations to build Mynewt applications.\n\n\nDefine debugger configurations to debug Mynewt applications. \n\n\nLaunch the debugger. \n\n\n\n\nPrerequisites:\n\n\n\n\nHave Internet connectivity to fetch remote Mynewt components.\n\n\nHave a computer to build a Mynewt application.\n\n\n\n\nPerform \nnative installation\n for the Mynewt tools and toolchains.\n\n\nNote:\n For Windows platforms, ensure that the MinGW bash you install is added to your Windows Path. In addition, if you are using Windows 10 WSL, you must have the MinGW bash before the Windows 10 WSL bash in your Windows Path.\n\n\n\n\n\n\nRead the Mynewt OS Concepts section.\n\n\n\n\nCreate a project space (directory structure) and populate it with the core code repository (apache-mynewt-core) or know how to as explained in Creating Your First Project. \n\n\nComplete one of the \nBlinky Tutorials\n.\n\n\n\n\nNotes:\n \n\n\n\n\nThis guide is not a tutorial for Visual Studio Code. It assumes you are familiar with Visual Studio Code. If this is your first time using Visual Studio Code, we recommend that you read the Visual Studio Code \ndocumentation and tutorials\n and evaluate whether you would like to use it to develop Mynewt applications. \n\n\nThis guide uses Visual Studio Code on Windows. Visual Studio Code is supported on Linux and Mac OS but may have some variations in the keyboard shortcuts and command names for these platforms. \n\n\nYou can also use the Eclipse IDE to develop Mynewt applications. See \nhttps://www.codecoup.pl/blog/hacking-mynewt-in-eclipse\n for more details. On Windows platforms, you must also ensure the MinGW bash is set in your Windows Path as described in the prerequisites.\n\n\n\n\nInstalling Visual Studio Code\n\n\nDownload and install Visual Studio Code from \nhttps://code.visualstudio.com/\n.\n\n\nInstalling the C/C++ and Debugger Extensions\n\n\nYou need to install two extensions:\n\n\n\n\n\n\nThe C/C++ extension from Microsoft. This extension provides language support such as symbol searching, signatuare help, go to definition, and go to declaration.\n\n\n\n\n\n\nThe Native Debug extension from webfreak. This extension provides GDB support. \n\n\n\n\n\n\n\nTo install the C/C++ extension:\n\n\n\n\nPress \nCtrl-P\n to open the search box.\n\n\nType \next install cpptools\n in the search box and press Enter. You should see the extension at the top of the list. \n\n\nClick \nInstall\n to install the extension. \n\n\n\n\n\nTo install the Native Debugger:\n\n\n\n\nPress \nCtrl-P\n to open the search box.\n\n\nType \next install webfreak.debug\n in the search box and press Enter. You should see the Native Debug extension at the top of the list.\n\n\nClick \nInstall\n to install the extension. \n\n\n\n\n\nDefining Tasks for Mynewt Projects\n\n\nTwo main concepts in Visual Studio Code are workspaces and tasks. A workspace represents a folder that is open. You can open multiple workspaces and switch between workspaces. \n\n\nTasks allow you to integrate the external tools and operations that are used to build or test your project into Visual Studio Code. Tasks are run from and the task results can be analyzed in Visual Studio Code. Tasks are defined within the scope of a workspace. This means that the tasks you define for a workspace only apply to the given workspace.\n\n\n\n\nAssociating a Mynewt Project to a Workspace\n\n\nFor your Mynewt project, your Visual Studio Code workspace is the Mynewt project base directory. For example, if you create a project named \nmyproj\n under the \n~/dev\n directory, then you open the \n~/dev/myproj\n folder for your workspace. \n\n\nSelect \nFile\n \n \nOpen Folder\n, and select the \nmyproj\n folder from the \nSelect Folder\n dialog box to open the folder.\n\n\n\n\nDefining Visual Studio Code Tasks to Build and Debug Mynewt Applications\n\n\nYou define Visual Studio Code tasks to build and debug your Mynewt targets in Visual Studio Code. We use the Blinky application for the Arduino Zero board from the \nBlinky On Arduino Zero Tutorial\n to illustrate how to define the tasks to build and debug the Arduino blinky bootloader and application targets.\n\n\nPerform the following steps to create the tasks to build and debug the Arduino blinky bootloader and appliction targets:\n\n\nStep 1: Press \nCtrl-Shift-P\n, type \ntask\n, and select \nTasks:Configure Task Runner\n from the search results. \n\n\nStep 2: Select \nOthers\n (scroll down to the bottom of the list) to create a task runner for external commands. \n\n\n\n\n\n\nTasks are defined in the \ntasks.json\n file. You should see the \n.vscode\n folder created in the \nMYPROJ\n folder and a \ntasks.json\n file created in the \n.vscode\n folder. The \ntasks.json\n file has the following default values. \n\n\n\n\n\n\n\n\nThe sample \ntasks.json\n file defines a simple task that runs the echo command with \"Hello World\" as the argument. \n\n\nStep 3: Delete the content from the \ntasks.json\n file, add the following definitions, and press \nCtrl-S\n to save the file.\n\n\n{\n \nversion\n: \n0.1.0\n,\n \ncommand\n: \nnewt\n,\n \nechoCommand\n: true,\n \nisShellCommand\n: true,\n\n \ntasks\n:[\n {\n \ntaskName\n: \nbuild_arduino_boot\n,\n \nargs\n: [\nbuild\n, \narduino_boot\n],\n \nsuppressTaskName\n: true\n },\n {\n \ntaskName\n: \nbuild_arduino_blinky\n,\n \nargs\n: [\nbuild\n, \narduino_blinky\n],\n \nisBuildCommand\n: true, \n \nsuppressTaskName\n: true\n },\n {\n \ntaskName\n: \ncreate_arduino_blinky\n,\n \nargs\n: [\ncreate-image\n, \narduino_blinky\n, \n1.0.0\n],\n \nsuppressTaskName\n:true\n }, \n {\n \ntaskName\n: \ndebug_arduino_blinky\n,\n \nargs\n: [\ndebug\n, \narduino_blinky\n, \n-n\n],\n \nsuppressTaskName\n: true\n }\n ]\n}\n\n\n\n\n\n\nThe \ntasks.json\n file specifies the tasks that are run to build and debug the Arduino blinky targets. Each task runs a \nnewt\n command. The \nnewt\n command to run and the arguments for the \nnewt\n command are passed in the \nargs\n property for each task. \n\n\nThe following tasks are defined in this example:\n\n\n\n\nbuild_arduino_boot\n: Runs the \nnewt build arduino_boot\n command to build the arduino_boot target.\n\n\n\n\nbuild_arduino_blinky\n: Runs the \nnewt build arduino_blinky\n command to build the arduino_blinky target. \n\n\nNote:\n This task sets the \nisBuildCommand\n property to \ntrue\n. This is an optional property that, when set to true, allows you to run the \nTasks: Run Build Task\n(\nCtrl-Shift-B\n) command to start the task.\n\n\n\n\n\n\ncreate_arduino_blinky\n: Runs the \nnewt create-image arduino_blinky\n command to create the image file.\n\n\n\n\ndebug_arduino_blinky\n: Runs the \nnewt build arduino_blinky -n\n command to debug the arduino_blinky target. The \n-n\n flag is specified to start only the GDB server and not the GDB client. We will launch the GDB client from Visual Studio Code.\n\n\n\n\nFor more information on tasks and all supported properties, see the \nVisual Studio Code Task documentation\n.\n\n\n\n\nRunning a Task\n\n\nTo run a task, press \nCtrl-Shift-P\n, type \ntask\n on the search box, and select \nTasks: Run Task\n. The tasks that you define in the \ntasks.json\n file are listed. Select the task to run. \n\n\nThe following is an example of running the \nbuild_arduino_boot\n task:\n\n\n\n\n\n\n\n\n\n\n\n\n\nNote\n:To run the \nbuild_arduino_linky\n task, you can use the keyboard shortcut \nCtrl-Shift-B\n because the task has the property \nisBuildCommand\n set to true. \n\n\n\n\nDefining Tasks for Other Newt Commands\n\n\nOther newt commands, such as the \nnewt load\n command, do not need to run from within Visual Studio Code. You can define a task for each command as a convenience and run the command as a task, or you can run the newt command on the command line from the Visual Studio Code integrated terminal or an external terminal.\n\n\nTo create the tasks for the \nnewt load arduino_boot\n and \nnewt laod arduino_blinky\n commands, add the following definitions to the \ntasks.json\n file:\n\n\n {\n \ntaskName\n: \nload_arduino_boot\n,\n \nargs\n: [\nload\n, \narduino_boot\n],\n \nsuppressTaskName\n:true\n }, \n {\n \ntaskName\n: \nload_arduino_blinky\n,\n \nargs\n: [\nload\n, \narduino_blinky\n],\n \nsuppressTaskName\n:true\n }, \n\n\n\n\n\n\nTo run a command from the Visual Studio integrated terminal, instead of starting a task, press \nCtrl-`\n to launch the integrated terminal and enter the command on the prompt:\n\n\n\n\n\n\n\nDefining Debugger Configurations\n\n\nYou need to define a debugger configuration to launch the GDB debugger from within Visual Studio Code: \n\n\nStep 1: Select \nDebug\n \n \nOpen Configuration\n, and select the \nGDB\n environment.\n\n\n\n\n\n\n\n\nYou should see a default \nlaunch.json\n file created in the \n.vscode\n folder.\n\n\n\n\n\n\n\n\nStep 2: Delete the content from the \nlaunch.json\n file, add the following definitions, and press 'Ctrl-S' to save the file.\n\n\n{\n \nversion\n: \n0.2.0\n,\n \nconfigurations\n: [\n {\n \nname\n: \ngdb_arduino_blinky\n,\n \ntype\n: \ngdb\n,\n \nrequest\n: \nattach\n,\n \nexecutable\n: \n${workspaceRoot}\\\\bin\\\\targets\\\\arduino_blinky\\\\app\\\\apps\\\\blinky\\\\blinky.elf\n,\n \ntarget\n: \n:3333\n,\n \ncwd\n: \n${workspaceRoot}\n,\n \ngdbpath\n: \nC:\\\\Program Files (x86)\\\\GNU Tools ARM Embedded\\\\4.9 2015q2\\\\bin\\\\arm-none-eabi-gdb.exe\n,\n \nremote\n: true\n\n }\n ]\n}\n\n\n\n\n\n\nThis defines a \ngdb_arduino_blinky\n debugger configuration. It specifies: \n\n\n\n\nThe debugger is type \ngdb\n.\n\n\nTo use the \nblinky.elf\n file for the executable. \n\n\nTo use port 3333 to connect with the remote target.\n\n\nTo use arm-none-eabi-gdb for the GDB program. \n\n\n\n\n\nDebugging Your Application\n\n\nTo debug your application, start the GDB server and launch the GDB session from Visual Studio Code. For the the arduino blinky example, perform the following:\n\n\nStep 1: Run the debug_arduino_blinky task to start the GDB server. Perform the following:\n\n\n\n\nPress \nCtrl-Shift-P\n and type \ntask\n in the search box. \n\n\nSelect \nTasks:Run Task\n \n \ndebug_arduino_blinky\n.\n\n\nPress \nCtrl-Shift-U\n to open the Output Panel and see the OpenOCD GDB Server output.\n\n \n\n\n\n\n\n\n\n\nStep 2: Start the GDB session. Perform the following: \n\n\n\n\nPress \nCtrl-Shift-Y\n to view the Debug Console. \n\n\nPress the Debugging icon on the activity bar (Ctrl-Shift-D) to bring up the Debug Side Bar.\n\n\nSelect \ngdb_arduino_blinky\n from the DEBUG drop down menu. \n\n\nPress the green play button to start the gdb session.\n\n\n\n\n\n\n\n\nStep 3: Debug your application. You should see a debug session similar to the one shown below:\n\n\n\n\nFor more information on how to use the Visual Studio Code Debugger, see the \nVisual Studio Code debugging documentation\n.\n\n\nWorking with Multiple Mynewt Applications\n\n\nAs mentioned previously, each mynewt project corresponds to a Visual Studio Code workspace. If you have multiple Mynewt application targets defined in same project, you will need to define build and debug tasks for each target in the \ntasks.json\n file and debugger configurations for the targets in the \nlaunch.json\n file for the workspace. If you have a different Mynewt project for each mynewt application, you will need to define build and debug tasks in the \ntasks.json\n file and the debugger configuration in the \nlaunch.json\n file for each workspace.",
- "title": "Using an IDE to Develop Mynewt Applications"
- },
- {
- "location": "/faq/ide/#developing-mynewt-applications-with-visual-studio-code",
- "text": "This guide shows you how to set up Visual Studio Code to develop and debug Mynewt applications. Visual Studio Code is supported on Mac OS, Linux, and Windows. This guide shows you how to: Install Visual Studio Code. Install the C/C++ and debugger extensions. Define task configurations to build Mynewt applications. Define debugger configurations to debug Mynewt applications. Launch the debugger. Prerequisites: Have Internet connectivity to fetch remote Mynewt components. Have a computer to build a Mynewt application. Perform native installation for the Mynewt tools and toolchains. Note: For Windows platforms, ensure that the MinGW bash you install is added to your Windows Path. In addition, if you are using Windows 10 WSL, you must have the MinGW bash before the Windows 10 WSL bash in your Windows Path. Read the Mynewt OS Concepts section. Create a project space (directory structure) and populate it with the core code repository (apache-mynewt-core) or know how to as explained in Creating Your First Project. Complete one of the Blinky Tutorials . Notes: This guide is not a tutorial for Visual Studio Code. It assumes you are familiar with Visual Studio Code. If this is your first time using Visual Studio Code, we recommend that you read the Visual Studio Code documentation and tutorials and evaluate whether you would like to use it to develop Mynewt applications. This guide uses Visual Studio Code on Windows. Visual Studio Code is supported on Linux and Mac OS but may have some variations in the keyboard shortcuts and command names for these platforms. You can also use the Eclipse IDE to develop Mynewt applications. See https://www.codecoup.pl/blog/hacking-mynewt-in-eclipse for more details. On Windows platforms, you must also ensure the MinGW bash is set in your Windows Path as described in the prerequisites.",
- "title": "Developing Mynewt Applications with Visual Studio Code"
- },
- {
- "location": "/faq/ide/#installing-visual-studio-code",
- "text": "Download and install Visual Studio Code from https://code.visualstudio.com/ .",
- "title": "Installing Visual Studio Code"
- },
- {
- "location": "/faq/ide/#installing-the-cc-and-debugger-extensions",
- "text": "You need to install two extensions: The C/C++ extension from Microsoft. This extension provides language support such as symbol searching, signatuare help, go to definition, and go to declaration. The Native Debug extension from webfreak. This extension provides GDB support. \nTo install the C/C++ extension: Press Ctrl-P to open the search box. Type ext install cpptools in the search box and press Enter. You should see the extension at the top of the list. Click Install to install the extension. To install the Native Debugger: Press Ctrl-P to open the search box. Type ext install webfreak.debug in the search box and press Enter. You should see the Native Debug extension at the top of the list. Click Install to install the extension.",
- "title": "Installing the C/C++ and Debugger Extensions"
- },
- {
- "location": "/faq/ide/#defining-tasks-for-mynewt-projects",
- "text": "Two main concepts in Visual Studio Code are workspaces and tasks. A workspace represents a folder that is open. You can open multiple workspaces and switch between workspaces. Tasks allow you to integrate the external tools and operations that are used to build or test your project into Visual Studio Code. Tasks are run from and the task results can be analyzed in Visual Studio Code. Tasks are defined within the scope of a workspace. This means that the tasks you define for a workspace only apply to the given workspace.",
- "title": "Defining Tasks for Mynewt Projects"
- },
- {
- "location": "/faq/ide/#associating-a-mynewt-project-to-a-workspace",
- "text": "For your Mynewt project, your Visual Studio Code workspace is the Mynewt project base directory. For example, if you create a project named myproj under the ~/dev directory, then you open the ~/dev/myproj folder for your workspace. Select File Open Folder , and select the myproj folder from the Select Folder dialog box to open the folder.",
- "title": "Associating a Mynewt Project to a Workspace"
- },
- {
- "location": "/faq/ide/#defining-visual-studio-code-tasks-to-build-and-debug-mynewt-applications",
- "text": "You define Visual Studio Code tasks to build and debug your Mynewt targets in Visual Studio Code. We use the Blinky application for the Arduino Zero board from the Blinky On Arduino Zero Tutorial to illustrate how to define the tasks to build and debug the Arduino blinky bootloader and application targets. Perform the following steps to create the tasks to build and debug the Arduino blinky bootloader and appliction targets: Step 1: Press Ctrl-Shift-P , type task , and select Tasks:Configure Task Runner from the search results. Step 2: Select Others (scroll down to the bottom of the list) to create a task runner for external commands. \nTasks are defined in the tasks.json file. You should see the .vscode folder created in the MYPROJ folder and a tasks.json file created in the .vscode folder. The tasks.json file has the following default values. The sample tasks.json file defines a simple task that runs the echo command with \"Hello World\" as the argument. Step 3: Delete the content from the tasks.json file, add the following definitions, and press Ctrl-S to save the file. {\n version : 0.1.0 ,\n command : newt ,\n echoCommand : true,\n isShellCommand : true,\n\n tasks :[\n {\n taskName : build_arduino_boot ,\n args : [ build , arduino_boot ],\n suppressTaskName : true\n },\n {\n taskName : build_arduino_blinky ,\n args : [ build , arduino_blinky ],\n isBuildCommand : true, \n suppressTaskName : true\n },\n {\n taskName : create_arduino_blinky ,\n args : [ create-image , arduino_blinky , 1.0.0 ],\n suppressTaskName :true\n }, \n {\n taskName : debug_arduino_blinky ,\n args : [ debug , arduino_blinky , -n ],\n suppressTaskName : true\n }\n ]\n} \nThe tasks.json file specifies the tasks that are run to build and debug the Arduino blinky targets. Each task runs a newt command. The newt command to run and the arguments for the newt command are passed in the args property for each task. The following tasks are defined in this example: build_arduino_boot : Runs the newt build arduino_boot command to build the arduino_boot target. build_arduino_blinky : Runs the newt build arduino_blinky command to build the arduino_blinky target. Note: This task sets the isBuildCommand property to true . This is an optional property that, when set to true, allows you to run the Tasks: Run Build Task ( Ctrl-Shift-B ) command to start the task. create_arduino_blinky : Runs the newt create-image arduino_blinky command to create the image file. debug_arduino_blinky : Runs the newt build arduino_blinky -n command to debug the arduino_blinky target. The -n flag is specified to start only the GDB server and not the GDB client. We will launch the GDB client from Visual Studio Code. For more information on tasks and all supported properties, see the Visual Studio Code Task documentation .",
- "title": "Defining Visual Studio Code Tasks to Build and Debug Mynewt Applications"
- },
- {
- "location": "/faq/ide/#running-a-task",
- "text": "To run a task, press Ctrl-Shift-P , type task on the search box, and select Tasks: Run Task . The tasks that you define in the tasks.json file are listed. Select the task to run. The following is an example of running the build_arduino_boot task: Note :To run the build_arduino_linky task, you can use the keyboard shortcut Ctrl-Shift-B because the task has the property isBuildCommand set to true.",
- "title": "Running a Task"
- },
- {
- "location": "/faq/ide/#defining-tasks-for-other-newt-commands",
- "text": "Other newt commands, such as the newt load command, do not need to run from within Visual Studio Code. You can define a task for each command as a convenience and run the command as a task, or you can run the newt command on the command line from the Visual Studio Code integrated terminal or an external terminal. To create the tasks for the newt load arduino_boot and newt laod arduino_blinky commands, add the following definitions to the tasks.json file: {\n taskName : load_arduino_boot ,\n args : [ load , arduino_boot ],\n suppressTaskName :true\n }, \n {\n taskName : load_arduino_blinky ,\n args : [ load , arduino_blinky ],\n suppressTaskName :true\n }, \nTo run a command from the Visual Studio integrated terminal, instead of starting a task, press Ctrl-` to launch the integrated terminal and enter the command on the prompt:",
- "title": "Defining Tasks for Other Newt Commands"
- },
- {
- "location": "/faq/ide/#defining-debugger-configurations",
- "text": "You need to define a debugger configuration to launch the GDB debugger from within Visual Studio Code: Step 1: Select Debug Open Configuration , and select the GDB environment. You should see a default launch.json file created in the .vscode folder. \nStep 2: Delete the content from the launch.json file, add the following definitions, and press 'Ctrl-S' to save the file. {\n version : 0.2.0 ,\n configurations : [\n {\n name : gdb_arduino_blinky ,\n type : gdb ,\n request : attach ,\n executable : ${workspaceRoot}\\\\bin\\\\targets\\\\arduino_blinky\\\\app\\\\apps\\\\blinky\\\\blinky.elf ,\n target : :3333 ,\n cwd : ${workspaceRoot} ,\n gdbpath : C:\\\\Program Files (x86)\\\\GNU Tools ARM Embedded\\\\4.9 2015q2\\\\bin\\\\arm-none-eabi-gdb.exe ,\n remote : true\n\n }\n ]\n} \nThis defines a gdb_arduino_blinky debugger configuration. It specifies: The debugger is type gdb . To use the blinky.elf file for the executable. To use port 3333 to connect with the remote target. To use arm-none-eabi-gdb for the GDB program.",
- "title": "Defining Debugger Configurations"
- },
- {
- "location": "/faq/ide/#debugging-your-application",
- "text": "To debug your application, start the GDB server and launch the GDB session from Visual Studio Code. For the the arduino blinky example, perform the following: Step 1: Run the debug_arduino_blinky task to start the GDB server. Perform the following: Press Ctrl-Shift-P and type task in the search box. Select Tasks:Run Task debug_arduino_blinky . Press Ctrl-Shift-U to open the Output Panel and see the OpenOCD GDB Server output. Step 2: Start the GDB session. Perform the following: Press Ctrl-Shift-Y to view the Debug Console. Press the Debugging icon on the activity bar (Ctrl-Shift-D) to bring up the Debug Side Bar. Select gdb_arduino_blinky from the DEBUG drop down menu. Press the green play button to start the gdb session. \nStep 3: Debug your application. You should see a debug session similar to the one shown below: \nFor more information on how to use the Visual Studio Code Debugger, see the Visual Studio Code debugging documentation .",
- "title": "Debugging Your Application"
- },
- {
- "location": "/faq/ide/#working-with-multiple-mynewt-applications",
- "text": "As mentioned previously, each mynewt project corresponds to a Visual Studio Code workspace. If you have multiple Mynewt application targets defined in same project, you will need to define build and debug tasks for each target in the tasks.json file and debugger configurations for the targets in the launch.json file for the workspace. If you have a different Mynewt project for each mynewt application, you will need to define build and debug tasks in the tasks.json file and the debugger configuration in the launch.json file for each workspace.",
- "title": "Working with Multiple Mynewt Applications"
- },
- {
- "location": "/faq/how_to_edit_docs/",
- "text": "How to Edit Docs\n\n\nObjective\n\n\nLearn the process of editing docs by adding some content to a test document.\n\n\nMarkdown, MkDocs, Mou\n\n\nThe Mynewt documentation you see on the Apache incubator website is a bunch of HTML files generated using MkDocs which is a simple static site generation tool geared towards building project documentation. You can read about it at \nhttp://www.mkdocs.org\n. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool (which in our case is MkDocs).\n\n\nThe HTML pages are generated periodically after changes have been reviewed and accepted into the master branch.\n\n\nAccess to the Apache repo\n\n\nGet an account on Apache. You do not need a committer account to view the website or clone the repository but you need it to push changes to it.\n\n\nIf you are not a committer, you may follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is \nhttps://git-wip-us.apache.org/docs/workflow.html\n. You will find the steps described in more detail later in this tutorial.\n\n\nEditing an existing page\n\n\n\n\nCreate a fork on the \ngithub mirror\n.\n\n\nCreate a new branch to work on your documentation and move to that branch.\n\n\n\n\n $ git checkout -b \nyour-branch-name\n\n\n\n\n\n\n\n\nMake changes directly on github.com. Generate a pull request. Alternatively, you can edit locally on your machine, push the branch (or the changes in the branch) to your fork on github.com, and then generate a pull request.\n\n\n\n\nAdding a new page\n\n\nIf you create a new file somewhere in the \ndocs\n subdirectory to add a new page, you have to add a line in the \nmkdocs.yml\n file at the correct level. For example, if you add a new module named \"Wi-Fi\" by creating a new file named \nwifi.md\n in the \nnetwork\n directory, you have to insert the following line under \nNetworking User Guide\n in the \nmkdocs.yml\n file (at the same level as the \ndocs\n directory). In this example, a link will show up in the navigation bar on the left under \"Networking User Guide\" titled \"Wi-Fi\" and take the user to the contents of the 'wifi.md' file when the link is clicked. \n Note: The change will show up on this \nMynewt site\n only after your pull request is merged in and the updated site is generated.\n\n\n - \nWi-Fi\n: \nwifi.md\n\n\n\n\n\n\nLocal preview of HTML files\n\n\nYou have the option to install MkDocs and do a local conversion yourself to preview the pages using the built-in webserver that comes with MkDocs. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will).\n\n\n $ python --version\n Python 2.7.2\n $ pip --version\n pip 1.5.2\n $ pip install mkdocs\n\n\n\n\n\nYou will then run the built-in webserver from the root of the documentation directory using the command \nmkdocs serve\n. The root directory for documentation is \nincubator-mynewt-site\n or the directory with the \nmkdocs.yml\n file.\n\n\n $ ls\n docs images mkdocs.yml\n $ mkdocs serve\n\n\n\n\n\nThen go to \nhttp://127.0.0.1:8000\n to preview your pages and see how they will look on the website. \nRemember that the \nMyNewt website\n itself will not be updated.\n\n\nFor more information on MkDocs go to \nhttp://www.mkdocs.org\n.",
- "title": "Edit Docs"
- },
- {
- "location": "/faq/how_to_edit_docs/#how-to-edit-docs",
- "text": "",
- "title": "How to Edit Docs"
- },
- {
- "location": "/faq/how_to_edit_docs/#objective",
- "text": "Learn the process of editing docs by adding some content to a test document.",
- "title": "Objective"
- },
- {
- "location": "/faq/how_to_edit_docs/#markdown-mkdocs-mou",
- "text": "The Mynewt documentation you see on the Apache incubator website is a bunch of HTML files generated using MkDocs which is a simple static site generation tool geared towards building project documentation. You can read about it at http://www.mkdocs.org . Documentation source files are written in Markdown, and configured with a single YAML configuration file. Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool (which in our case is MkDocs). The HTML pages are generated periodically after changes have been reviewed and accepted into the master branch.",
- "title": "Markdown, MkDocs, Mou"
- },
- {
- "location": "/faq/how_to_edit_docs/#access-to-the-apache-repo",
- "text": "Get an account on Apache. You do not need a committer account to view the website or clone the repository but you need it to push changes to it. If you are not a committer, you may follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is https://git-wip-us.apache.org/docs/workflow.html . You will find the steps described in more detail later in this tutorial.",
- "title": "Access to the Apache repo"
- },
- {
- "location": "/faq/how_to_edit_docs/#editing-an-existing-page",
- "text": "Create a fork on the github mirror . Create a new branch to work on your documentation and move to that branch. $ git checkout -b your-branch-name Make changes directly on github.com. Generate a pull request. Alternatively, you can edit locally on your machine, push the branch (or the changes in the branch) to your fork on github.com, and then generate a pull request.",
- "title": "Editing an existing page"
- },
- {
- "location": "/faq/how_to_edit_docs/#adding-a-new-page",
- "text": "If you create a new file somewhere in the docs subdirectory to add a new page, you have to add a line in the mkdocs.yml file at the correct level. For example, if you add a new module named \"Wi-Fi\" by creating a new file named wifi.md in the network directory, you have to insert the following line under Networking User Guide in the mkdocs.yml file (at the same level as the docs directory). In this example, a link will show up in the navigation bar on the left under \"Networking User Guide\" titled \"Wi-Fi\" and take the user to the contents of the 'wifi.md' file when the link is clicked. Note: The change will show up on this Mynewt site only after your pull request is merged in and the updated site is generated. - Wi-Fi : wifi.md",
- "title": "Adding a new page"
- },
- {
- "location": "/faq/how_to_edit_docs/#local-preview-of-html-files",
- "text": "You have the option to install MkDocs and do a local conversion yourself to preview the pages using the built-in webserver that comes with MkDocs. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will). $ python --version\n Python 2.7.2\n $ pip --version\n pip 1.5.2\n $ pip install mkdocs You will then run the built-in webserver from the root of the documentation directory using the command mkdocs serve . The root directory for documentation is incubator-mynewt-site or the directory with the mkdocs.yml file. $ ls\n docs images mkdocs.yml\n $ mkdocs serve Then go to http://127.0.0.1:8000 to preview your pages and see how they will look on the website. Remember that the MyNewt website itself will not be updated. For more information on MkDocs go to http://www.mkdocs.org .",
- "title": "Local preview of HTML files"
- },
- {
- "location": "/faq/answers/",
- "text": "FAQ\n\n\nHere are some lists, grouped by categories, of frequently asked questions. \n\n\nMynewt software questions:\n\n\n\n\nHow do I reduce the code size for my Mynewt image?\n\n\n\n\nAdministrative questions:\n\n\n\n\nHow do I submit a bug?\n\n\nHow do I request a feature?\n\n\nHow do I submit a patch if I am not a committer?\n\n\nCan I merge my own Pull Request into the git repo if I am a committer?\n\n\nHow do I make changes to documentation?\n\n\nHow do I make changes to documentation using an editor on my laptop?\n\n\n\n\n\n\n How do I submit a bug?\n\n\n\nIf you do not have a JIRA account sign up for an account on \nJIRA\n.\n\n\nSubmit a request to the @dev mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. You can view the issues on JIRA for the MYNEWT project without an account but you need to log in for reporting a bug. \n\n\nLog in. Choose the \"MYNEWT\" project. Click on the \"Create\" button to create a ticket. Choose \"Bug\" as the Issue Type. Fill in the bug description, how it is triggered, and other details. \n\n\n How do I request a feature?\n\n\n\nIf you do not have a JIRA account sign up for an account on \nJIRA\n.\n\n\nSubmit a request to the @dev mailing list for your JIRA username to be added to the Apache Mynewt (MYNEWT) project. You can view the issues on JIRA for the MYNEWT project without an account but you need to log in for reporting a bug. \n\n\nLog in. Choose the \"MYNEWT\" project. Click on the \"Create\" button to create a ticket. Choose \"Wish\" as the Issue Type. Fill in the feature description, benefits, and any other implementation details. Note in the description whether you want to work on it yourself. \n\n\nIf you are not a committer and you wish to work on it, someone who is on the committer list will have to review your request and assign it to you. You will have to refer to this JIRA ticket in your pull request.\n\n\nI am not on the committer list. How do I submit a patch?\n\n\n\n\nYou submit your proposed changes for your peers with committer status to review and merge.\n\n\nThe process to submit a Pull Request on github.com is described on the \nConfluence page for the project\n. \n\n\nI am a committer in the project. Can I merge my own Pull Request into the git repository?\n\n\n\nYes, but only if your Pull Request has been reviewed and approved by another committer in Apache Mynewt.\nThe process to merge a Pull Request is described on the \nConfluence page for the project\n.\n\n\nI would like to make some edits to the documentation. What do I do?\n\n\n\nYou submit your proposed changes for your peers with committer status to review and merge. \n\n\nGo to the \ndocumentation mirror\n on github.com.\n\n\nNavigate to the file you wish to edit on github.com. All the technical documentation is in Markdown files under the \n/docs\n directory. Click on the pencil icon (\"Edit the file in your fork of this project\") and start making changes.\n\n\nClick the green \"Propose file change\" button. You will be directed to the page where you can start a pull request from the branch that was created for you. The branch is gets an automatic name \npatch-#\n where # is a number. Click on the green \"Compare \n pull request\" to open the pull request.\n\n\nIn the comment for the pull request, include a description of the changes you have made and why. Github will automatically notify everyone on the commits@mynewt.incubator.apache.org mailing list about the newly opened pull requests. You can open a pull request even if you don't think the code is ready for merging but want some discussion on the matter.\n\n\nUpon receiving notification, one or more committers will review your work, ask for edits or clarifications, and merge when your proposed changes are ready.\n\n\nIf you want to withdraw the pull request simply go to your fork \nhttps://github.com/\nyour github username\n/incubator-mynewt-site\n and click on \"branches\". You should see your branch under \"Your branches\". Click on the delete icon.\n\n\nI would like to make some edits to the documentation but want to use an editor on my own laptop. What do I do?\n\n\n\nYou submit your proposed changes for your peers with committer status to review and merge. \n\n\nGo to the \ndocumentation mirror\n on github.com. You need to create your own fork of the repo in github.com by clicking on the \"Fork\" button on the top right. Clone the forked repository into your laptop (using \ngit clone\n from a terminal or using the download buttons on the github page)and create a local branch for the edits and switching to it (using \ngit checkout -b \nnew-branchname\n or GitHub Desktop). \n\n\nMake your changes using the editor of your choice. Push that branch to your fork on github. Then submit a pull request from that branch on your github fork.\n\n\nThe review and merge process is the same as other pull requests described for earlier questions.",
- "title": "FAQ"
- },
- {
- "location": "/faq/answers/#faq",
- "text": "Here are some lists, grouped by categories, of frequently asked questions. Mynewt software questions: How do I reduce the code size for my Mynewt image? Administrative questions: How do I submit a bug? How do I request a feature? How do I submit a patch if I am not a committer? Can I merge my own Pull Request into the git repo if I am a committer? How do I make changes to documentation? How do I make changes to documentation using an editor on my laptop?",
- "title": "FAQ"
- }
- ]
-}
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_att/ble_att/index.html b/develop/network/ble/ble_hs/ble_att/ble_att/index.html
deleted file mode 100644
index 0be045f31f..0000000000
--- a/develop/network/ble/ble_hs/ble_att/ble_att/index.html
+++ /dev/null
@@ -1,602 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_att/ble_att/"> -->
- <link rel="shortcut icon" href="../../../../../img/favicon.ico">
-
- <title>toc - 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">
- <link href="../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="toc">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../ble_intro/
-">BLE User Guide</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../../../ble_intro/">NimBLE Introduction</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../ble_sec/">NimBLE Security</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../nimble_setup/">Set up application</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ini_stack/ble_ini_intro/">Initialize stack</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_hs/">NimBLE Host API</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../../ble_hs_return_codes/">Return codes</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../init/init/">Init and config</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_gap/ble_gap/">GAP</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_gattc/ble_gattc/">GATT client</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_gatts/ble_gatts/">GATT server</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_hs_id/ble_hs_id/">Identity</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li class="active"><a href="./">ATT</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ../functions/ble_att_mtu/
-">Functions</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../other/other/">Other</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../bletiny/bletiny_api/">bletiny app Usage API</a>
-
-
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../ble_hs/">NimBLE Host API</a></li>
-
-
-
- <li>» ATT</li>
-
-
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/network/ble/ble_hs/ble_att/ble_att.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="nimble-host-att-client-reference"><font color="F2853F" style="font-size:24pt">NimBLE Host ATT Client Reference</font></h2>
-<h3 id="introduction">Introduction</h3>
-<p>The Attribute Protocol (ATT) is a mid-level protocol that all BLE devices use to exchange data. Data is exchanged when an ATT client reads or writes an attribute belonging to an ATT server. Any device that needs to send or receive data must support both the client and server functionality of the ATT protocol. The only devices which do not support ATT are the most basic ones: broadcasters and observers (i.e., beaconing devices and listening devices).</p>
-<p>Most ATT functionality is not interesting to an application. Rather than use ATT directly, an application uses the higher level GATT profile, which sits directly above ATT in the host. NimBLE exposes the few bits of ATT functionality which are not encompassed by higher level GATT functions. This section documents the ATT functionality that the NimBLE host exposes to the application.</p>
-<h3 id="header">Header</h3>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span><span style="color: #633820">#include</span> <span style="color: #177500">"host/ble_hs.h"</span><span style="color: #633820"></span>
-</pre></div>
-
-
-<h3 id="definitions">Definitions</h3>
-<p>None.</p>
-<table>
-<thead>
-<tr>
-<th>Function</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td><a href="../functions/ble_att_mtu/">ble_att_mtu</a></td>
-<td>Retrieves the ATT MTU of the specified connection.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_att_set_preferred_mtu/">ble_att_set_preferred_mtu</a></td>
-<td>Sets the preferred ATT MTU; the device will indicate this value in all subseqeunt ATT MTU exchanges.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_att_svr_read_local/">ble_att_svr_read_local</a></td>
-<td>Reads a locally registered attribute.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_att_svr_write_local/">ble_att_svr_write_local</a></td>
-<td>Writes a locally registered attribute.</td>
-</tr>
-</tbody>
-</table>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../../ble_hs_id/functions/ble_hs_id_set_rnd/>
- <span class="fa fa-arrow-left"></span>
- Previous: ble_hs_id_set_rnd
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../functions/ble_att_mtu/>
- Next: ble_att_mtu
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_att/functions/ble_att_mtu/index.html b/develop/network/ble/ble_hs/ble_att/functions/ble_att_mtu/index.html
deleted file mode 100644
index ac1b278d10..0000000000
--- a/develop/network/ble/ble_hs/ble_att/functions/ble_att_mtu/index.html
+++ /dev/null
@@ -1,628 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_att/functions/ble_att_mtu/"> -->
- <link rel="shortcut icon" href="../../../../../../img/favicon.ico">
-
- <title>ble_att_mtu - 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">
- <link href="../../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="ble_att_mtu">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../../../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../../ble_intro/
-">BLE User Guide</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../../../../ble_intro/">NimBLE Introduction</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../ble_sec/">NimBLE Security</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../nimble_setup/">Set up application</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../ini_stack/ble_ini_intro/">Initialize stack</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs/">NimBLE Host API</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../../../ble_hs_return_codes/">Return codes</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../init/init/">Init and config</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gap/ble_gap/">GAP</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gattc/ble_gattc/">GATT client</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gatts/ble_gatts/">GATT server</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs_id/ble_hs_id/">Identity</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_att/">ATT</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ./
-">Functions</a>
-
-
- <ul>
-
-
-
- <li class="active">
- <a href="./">ble_att_mtu</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_set_preferred_mtu/">ble_att_set_preferred_mtu</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_svr_read_local/">ble_att_svr_read_local</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_svr_write_local/">ble_att_svr_write_local</a>
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../other/other/">Other</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../bletiny/bletiny_api/">bletiny app Usage API</a>
-
-
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../ble_att/">ATT</a></li>
-
-
-
- <li>» Functions</li>
-
-
-
- <li>» ble_att_mtu</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/network/ble/ble_hs/ble_att/functions/ble_att_mtu.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="ble95att95mtu"><font color="#F2853F" style="font-size:24pt">ble_att_mtu</font></h2>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span><span style="color: #A90D91">uint16_t</span>
-<span style="color: #000000">ble_att_mtu</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</span>)
-</pre></div>
-
-
-<h3 id="description">Description</h3>
-<p>Retrieves the ATT MTU of the specified connection. If an MTU exchange for this connection has occurred, the MTU is the lower of the two peers' preferred values. Otherwise, the MTU is the default value of 23.</p>
-<h3 id="parameters">Parameters</h3>
-<table>
-<thead>
-<tr>
-<th><em>Parameter</em></th>
-<th><em>Description</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>conn_handle</td>
-<td>The handle of the connection to query.</td>
-</tr>
-</tbody>
-</table>
-<h3 id="returned-values">Returned values</h3>
-<p>The specified connection's ATT MTU.</p>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../../ble_att/>
- <span class="fa fa-arrow-left"></span>
- Previous: ATT
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../ble_att_set_preferred_mtu/>
- Next: ble_att_set_preferred_mtu
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/index.html b/develop/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/index.html
deleted file mode 100644
index 49c3bd0212..0000000000
--- a/develop/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/index.html
+++ /dev/null
@@ -1,645 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu/"> -->
- <link rel="shortcut icon" href="../../../../../../img/favicon.ico">
-
- <title>ble_att_set_preferred_mtu - 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">
- <link href="../../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="ble_att_set_preferred_mtu">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../../../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../../ble_intro/
-">BLE User Guide</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../../../../ble_intro/">NimBLE Introduction</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../ble_sec/">NimBLE Security</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../nimble_setup/">Set up application</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../ini_stack/ble_ini_intro/">Initialize stack</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs/">NimBLE Host API</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../../../ble_hs_return_codes/">Return codes</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../init/init/">Init and config</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gap/ble_gap/">GAP</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gattc/ble_gattc/">GATT client</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gatts/ble_gatts/">GATT server</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs_id/ble_hs_id/">Identity</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_att/">ATT</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ../ble_att_mtu/
-">Functions</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../ble_att_mtu/">ble_att_mtu</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">ble_att_set_preferred_mtu</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_svr_read_local/">ble_att_svr_read_local</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_svr_write_local/">ble_att_svr_write_local</a>
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../other/other/">Other</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../bletiny/bletiny_api/">bletiny app Usage API</a>
-
-
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../ble_att/">ATT</a></li>
-
-
-
- <li>» <a href="../ble_att_mtu/">Functions</a></li>
-
-
-
- <li>» ble_att_set_preferred_mtu</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/network/ble/ble_hs/ble_att/functions/ble_att_set_preferred_mtu.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="ble95att95set95preferred95mtu"><font color="#F2853F" style="font-size:24pt">ble_att_set_preferred_mtu</font></h2>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span><span style="color: #A90D91">int</span>
-<span style="color: #000000">ble_att_set_preferred_mtu</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">mtu</span>)
-</pre></div>
-
-
-<h3 id="description">Description</h3>
-<p>Sets the preferred ATT MTU; the device will indicate this value in all subseqeunt ATT MTU exchanges. The ATT MTU of a connection is equal to the lower of the two peers' preferred MTU values. The ATT MTU is what dictates the maximum size of any message sent during a GATT procedure. The specified MTU must be within the following range: [23, BLE_ATT_MTU_MAX]. 23 is a minimum imposed by the Bluetooth specification; BLE_ATT_MTU_MAX is a NimBLE compile-time setting.</p>
-<h3 id="parameters">Parameters</h3>
-<table>
-<thead>
-<tr>
-<th><em>Parameter</em></th>
-<th><em>Description</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>mtu</td>
-<td>The preferred ATT MTU.</td>
-</tr>
-</tbody>
-</table>
-<h3 id="returned-values">Returned values</h3>
-<table>
-<thead>
-<tr>
-<th><em>Value</em></th>
-<th><em>Condition</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>0</td>
-<td>Success.</td>
-</tr>
-<tr>
-<td>BLE_HS_EINVAL</td>
-<td>The specifeid value is not within the allowed range.</td>
-</tr>
-</tbody>
-</table>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../ble_att_mtu/>
- <span class="fa fa-arrow-left"></span>
- Previous: ble_att_mtu
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../ble_att_svr_read_local/>
- Next: ble_att_svr_read_local
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/index.html b/develop/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/index.html
deleted file mode 100644
index eaab0b1362..0000000000
--- a/develop/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/index.html
+++ /dev/null
@@ -1,656 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local/"> -->
- <link rel="shortcut icon" href="../../../../../../img/favicon.ico">
-
- <title>ble_att_svr_read_local - 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">
- <link href="../../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="ble_att_svr_read_local">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../../../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../../ble_intro/
-">BLE User Guide</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../../../../ble_intro/">NimBLE Introduction</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../ble_sec/">NimBLE Security</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../nimble_setup/">Set up application</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../ini_stack/ble_ini_intro/">Initialize stack</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs/">NimBLE Host API</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../../../ble_hs_return_codes/">Return codes</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../init/init/">Init and config</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gap/ble_gap/">GAP</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gattc/ble_gattc/">GATT client</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gatts/ble_gatts/">GATT server</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs_id/ble_hs_id/">Identity</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_att/">ATT</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ../ble_att_mtu/
-">Functions</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../ble_att_mtu/">ble_att_mtu</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_set_preferred_mtu/">ble_att_set_preferred_mtu</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">ble_att_svr_read_local</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_svr_write_local/">ble_att_svr_write_local</a>
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../other/other/">Other</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../bletiny/bletiny_api/">bletiny app Usage API</a>
-
-
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../ble_att/">ATT</a></li>
-
-
-
- <li>» <a href="../ble_att_mtu/">Functions</a></li>
-
-
-
- <li>» ble_att_svr_read_local</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/network/ble/ble_hs/ble_att/functions/ble_att_svr_read_local.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="ble95att95svr95read95local"><font color="#F2853F" style="font-size:24pt">ble_att_svr_read_local</font></h2>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span><span style="color: #A90D91">int</span>
-<span style="color: #000000">ble_att_svr_read_local</span>(
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">attr_handle</span>,
- <span style="color: #A90D91">struct</span> <span style="color: #000000">os_mbuf</span> <span style="color: #000000">**out_om</span>
-)
-</pre></div>
-
-
-<h3 id="description">Description</h3>
-<p>Reads a locally registered attribute. If the specified attribute handle coresponds to a GATT characteristic value or descriptor, the read is performed by calling the registered GATT access callback.</p>
-<h3 id="parameters">Parameters</h3>
-<table>
-<thead>
-<tr>
-<th><em>Parameter</em></th>
-<th><em>Description</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>attr_handle</td>
-<td>The 16-bit handle of the attribute to read.</td>
-</tr>
-<tr>
-<td>out_om</td>
-<td>On success, this is made to point to a newly-allocated mbuf containing the attribute data read.</td>
-</tr>
-</tbody>
-</table>
-<h3 id="returned-values">Returned values</h3>
-<table>
-<thead>
-<tr>
-<th><em>Value</em></th>
-<th><em>Condition</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>0</td>
-<td>Success.</td>
-</tr>
-<tr>
-<td><a href="../../../ble_hs_return_codes/#return-codes-att">ATT return code</a></td>
-<td>The attribute access callback reports failure.</td>
-</tr>
-<tr>
-<td><a href="../../../ble_hs_return_codes/#return-codes-core">Core return code</a></td>
-<td>Unexpected error.</td>
-</tr>
-</tbody>
-</table>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../ble_att_set_preferred_mtu/>
- <span class="fa fa-arrow-left"></span>
- Previous: ble_att_set_preferred_mtu
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../ble_att_svr_write_local/>
- Next: ble_att_svr_write_local
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/index.html b/develop/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/index.html
deleted file mode 100644
index b6ba467f6a..0000000000
--- a/develop/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/index.html
+++ /dev/null
@@ -1,656 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local/"> -->
- <link rel="shortcut icon" href="../../../../../../img/favicon.ico">
-
- <title>ble_att_svr_write_local - 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">
- <link href="../../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="ble_att_svr_write_local">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../../../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../../os/os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../../ble_intro/
-">BLE User Guide</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../../../../ble_intro/">NimBLE Introduction</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../ble_sec/">NimBLE Security</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../nimble_setup/">Set up application</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../ini_stack/ble_ini_intro/">Initialize stack</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs/">NimBLE Host API</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../../../ble_hs_return_codes/">Return codes</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../init/init/">Init and config</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gap/ble_gap/">GAP</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gattc/ble_gattc/">GATT client</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_gatts/ble_gatts/">GATT server</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ble_hs_id/ble_hs_id/">Identity</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_att/">ATT</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ../ble_att_mtu/
-">Functions</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../ble_att_mtu/">ble_att_mtu</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_set_preferred_mtu/">ble_att_set_preferred_mtu</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../ble_att_svr_read_local/">ble_att_svr_read_local</a>
- </li>
-
-
-
-
-
- <li class="active">
- <a href="./">ble_att_svr_write_local</a>
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../other/other/">Other</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../bletiny/bletiny_api/">bletiny app Usage API</a>
-
-
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../ble_att/">ATT</a></li>
-
-
-
- <li>» <a href="../ble_att_mtu/">Functions</a></li>
-
-
-
- <li>» ble_att_svr_write_local</li>
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/network/ble/ble_hs/ble_att/functions/ble_att_svr_write_local.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="ble95att95svr95write95local"><font color="#F2853F" style="font-size:24pt">ble_att_svr_write_local</font></h2>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span><span style="color: #A90D91">int</span>
-<span style="color: #000000">ble_att_svr_write_local</span>(
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">attr_handle</span>,
- <span style="color: #A90D91">struct</span> <span style="color: #000000">os_mbuf</span> <span style="color: #000000">*om</span>
-)
-</pre></div>
-
-
-<h3 id="description">Description</h3>
-<p>Writes a locally registered attribute. This function consumes the supplied mbuf regardless of the outcome. If the specified attribute handle coresponds to a GATT characteristic value or descriptor, the write is performed by calling the registered GATT access callback.</p>
-<h3 id="parameters">Parameters</h3>
-<table>
-<thead>
-<tr>
-<th><em>Parameter</em></th>
-<th><em>Description</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>attr_handle</td>
-<td>The 16-bit handle of the attribute to write.</td>
-</tr>
-<tr>
-<td>om</td>
-<td>The value to write to the attribute.</td>
-</tr>
-</tbody>
-</table>
-<h3 id="returned-values">Returned values</h3>
-<table>
-<thead>
-<tr>
-<th><em>Value</em></th>
-<th><em>Condition</em></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>0</td>
-<td>Success.</td>
-</tr>
-<tr>
-<td><a href="../../../ble_hs_return_codes/#return-codes-att">ATT return code</a></td>
-<td>The attribute access callback reports failure.</td>
-</tr>
-<tr>
-<td><a href="../../../ble_hs_return_codes/#return-codes-core">Core return code</a></td>
-<td>Unexpected error.</td>
-</tr>
-</tbody>
-</table>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../ble_att_svr_read_local/>
- <span class="fa fa-arrow-left"></span>
- Previous: ble_att_svr_read_local
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../../../other/other/>
- Next: Other
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_gap/ble_gap/index.html b/develop/network/ble/ble_hs/ble_gap/ble_gap/index.html
deleted file mode 100644
index fd4d9a4d2b..0000000000
--- a/develop/network/ble/ble_hs/ble_gap/ble_gap/index.html
+++ /dev/null
@@ -1,667 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_gap/ble_gap/"> -->
- <link rel="shortcut icon" href="../../../../../img/favicon.ico">
-
- <title>toc - 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">
- <link href="../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="toc">
-
-
- <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.0.0</a> released (March 22, 2017)
- </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="/latest/os/introduction">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="/develop/os/introduction"
- selected="selected"
- >
- Version: develop (latest)
- </option>
-
- <option
- value="/v0_9_0/os/introduction"
-
- >
- Version: 0.9.0
- </option>
-
- <option
- value="/v1_0_0/os/introduction"
-
- >
- Version: 1.0.0
- </option>
-
-</select>
-</li>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/introduction/">Mynewt Documentation</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/get_started/get_started/">Basic Setup</a>
-
-
- </li>
-
-
-
-
-
- <li >
- <a href="../../../../../os/get_started/vocabulary/">Concepts</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/tutorials/tutorials/">Tutorials</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../../../os/os_user_guide/">OS User Guide</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../../../ble_intro/
-">BLE User Guide</a>
-
-
- <ul>
-
-
-
- <li >
- <a href="../../../ble_intro/">NimBLE Introduction</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../ble_sec/">NimBLE Security</a>
- </li>
-
-
-
-
-
- <li >
- <a href="../../../nimble_setup/">Set up application</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../ini_stack/ble_ini_intro/">Initialize stack</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_hs/">NimBLE Host API</a>
-
-
- <ul>
-
-
-
-
-
- <li >
- <a href="../../ble_hs_return_codes/">Return codes</a>
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../init/init/">Init and config</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li class="active"><a href="./">GAP</a>
-
-
- <ul>
-
-
-
-
-
-
-
- <li><a href="
- ../definitions/ble_gap_defs/
-">Definitions</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li><a href="
- ../functions/ble_gap_adv_active/
-">Functions</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_gattc/ble_gattc/">GATT client</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_gatts/ble_gatts/">GATT server</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_hs_id/ble_hs_id/">Identity</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../ble_att/ble_att/">ATT</a>
-
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../other/other/">Other</a>
-
-
- </li>
-
-
-
- </ul>
-
- </li>
-
-
-
-
-
-
-
- <li ><a href="../../../bletiny/bletiny_api/">bletiny app Usage API</a>
-
-
- </li>
-
-
-
- </ul>
-
- </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="/develop/os/introduction">Docs</a></li>
-
-
-
- <li>» <a href="../../ble_hs/">NimBLE Host API</a></li>
-
-
-
- <li>» GAP</li>
-
-
-
-
-
- <li class="wy-breadcrumbs-aside">
-
- <a href="https://github.com/apache/incubator-mynewt-site/blob/develop/docs/network/ble/ble_hs/ble_gap/ble_gap.md"
- class="icon icon-github"> Edit on GitHub</a>
-
- </li>
-
- </ul>
-</div>
- </div>
-
-
- <h2 id="nimble-host-gap-reference"><font color="F2853F" style="font-size:24pt">NimBLE Host GAP Reference</font></h2>
-<h3 id="introduction">Introduction</h3>
-<p>The Generic Access Profile (GAP) is responsible for all connecting, advertising, scanning, and connection updating operations.</p>
-<h3 id="header">Header</h3>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span></span><span style="color: #633820">#include</span> <span style="color: #177500">"host/ble_hs.h"</span><span style="color: #633820"></span>
-</pre></div>
-
-
-<h3 id="definitions">Definitions</h3>
-<p><a href="../definitions/ble_gap_defs/">BLE host GAP definitions</a></p>
-<h3 id="functions">Functions</h3>
-<table>
-<thead>
-<tr>
-<th>Function</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td><a href="../functions/ble_gap_adv_active/">ble_gap_adv_active</a></td>
-<td>Indicates whether an advertisement procedure is currently in progress.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_adv_rsp_set_fields/">ble_gap_adv_rsp_set_fields</a></td>
-<td>Configures the data to include in subsequent scan responses.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_adv_set_fields/">ble_gap_adv_set_fields</a></td>
-<td>Configures the data to include in subsequent advertisements.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_adv_start/">ble_gap_adv_start</a></td>
-<td>Initiates advertising.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_adv_stop/">ble_gap_adv_stop</a></td>
-<td>Stops the currently-active advertising procedure.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_conn_active/">ble_gap_conn_active</a></td>
-<td>Indicates whether a connect procedure is currently in progress.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_conn_cancel/">ble_gap_conn_cancel</a></td>
-<td>Aborts a connect procedure in progress.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_conn_find/">ble_gap_conn_find</a></td>
-<td>Searches for a connection with the specified handle.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_conn_rssi/">ble_gap_conn_rssi</a></td>
-<td>Retrieves the most-recently measured RSSI for the specified connection.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_connect/">ble_gap_connect</a></td>
-<td>Initiates a connect procedure.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_disc/">ble_gap_disc</a></td>
-<td>Performs the Limited or General Discovery Procedures.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_disc_active/">ble_gap_disc_active</a></td>
-<td>Indicates whether a discovery procedure is currently in progress.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_disc_cancel/">ble_gap_disc_cancel</a></td>
-<td>Cancels the discovery procedure currently in progress.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_security_initiate/">ble_gap_security_initiate</a></td>
-<td>Initiates the GAP encryption procedure.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_terminate/">ble_gap_terminate</a></td>
-<td>Terminates an established connection.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_update_params/">ble_gap_update_params</a></td>
-<td>Initiates a connection parameter update procedure.</td>
-</tr>
-<tr>
-<td><a href="../functions/ble_gap_wl_set/">ble_gap_wl_set</a></td>
-<td>Overwrites the controller's white list with the specified contents.</td>
-</tr>
-</tbody>
-</table>
-
- <div class="row">
-
-
-
-
-<ul class="nav nav-pills" style="margin-bottom: 10px">
- <li>
-
- <a href=../../init/functions/ble_hs_synced/>
- <span class="fa fa-arrow-left"></span>
- Previous: ble_hs_synced
- </a>
-
- </li>
- <li class="pull-right">
-
- <a href=../definitions/ble_gap_defs/>
- Next: GAP definitions
- <span class="fa fa-arrow-right"></span>
- </a>
-
- </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">
- <img src="/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="https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg"><img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /></a>
- </div>
- </div>
-</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>
-
- </body>
-</html>
\ No newline at end of file
diff --git a/develop/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/index.html b/develop/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/index.html
deleted file mode 100644
index 97d4127d5c..0000000000
--- a/develop/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/index.html
+++ /dev/null
@@ -1,1041 +0,0 @@
-<!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="canonical" href="http://mynewt.apache.org/network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/"> -->
- <link rel="shortcut icon" href="../../../../../../img/favicon.ico">
-
- <title>GAP definitions - 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">
- <link href="../../../../../../extra.css" rel="stylesheet">
-
- <!-- 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="GAP definitions">
-
-
- <div class="container">
- <div class="row v2-main-banner">
(This diff was longer than 20,000 lines, and has been truncated...)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services