http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/network/ble/ble_intro/index.html ---------------------------------------------------------------------- diff --git a/develop/network/ble/ble_intro/index.html b/develop/network/ble/ble_intro/index.html index 0559e2e..6cbb372 100644 --- a/develop/network/ble/ble_intro/index.html +++ b/develop/network/ble/ble_intro/index.html @@ -452,9 +452,9 @@ <ul class="nav nav-pills" style="margin-bottom: 10px"> <li> - <a href=../../../os/modules/sysinitconfig/sysinitconfig/> + <a href=../../../os/modules/sysinitconfig/sysconfig_error/> <span class="fa fa-arrow-left"></span> - Previous: System Configuration And Initialization + Previous: Validation and Error Messages </a> </li>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/newt/newt_operation/index.html ---------------------------------------------------------------------- diff --git a/develop/newt/newt_operation/index.html b/develop/newt/newt_operation/index.html index 91211c8..2d2fbc6 100644 --- a/develop/newt/newt_operation/index.html +++ b/develop/newt/newt_operation/index.html @@ -373,7 +373,7 @@ <p><br></p> -<p>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." </p> +<p>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." </p> <p><br></p> <h4 id="apps-package-directory">"apps" Package Directory</h4> <p><code>apps</code> is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called <code>blinky</code> in the <code>apps</code> directory. The core repository <code>@apache-mynewt-core</code> comes with many additional sample apps in its <code>apps</code> 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.</p> @@ -409,7 +409,7 @@ depends on kernel/os, hw/hal and sys/console/full packages.</p> covered in the "repository" section. </p> <p><br></p> <h4 id="targets-package-directory">"targets" Package Directory</h4> -<p><code>targets</code> 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 <code>apps</code> directory, <code>targets</code> represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies.</p> +<p><code>targets</code> 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 <code>apps</code> directory, <code>targets</code> represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies.</p> <p>Most targets consist of:</p> <ul> <li>app: The application to build</li> @@ -464,9 +464,9 @@ target.build_profile: "debug" <li>Board Support Package (target.bsp): The board support package to build along with that application.</li> </ul> -<p>Newt goes and builds the dependency tree specified by all the packages. While building this tree, it does a few other things:</p> +<p>Newt builds the dependency tree specified by all the packages. While building this tree, it does a few other things:</p> <ul> -<li>Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the +<li>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 newt structure must always be prefixed by the package name. For example, libs/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.</li> </ul> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ tree @@ -510,16 +510,24 @@ newt structure must always be prefixed by the package name. For example, libs/os <p><br></p> <ul> -<li>API requirements are validated. Packages can export APIs they +<li> +<p>Validates API requirements. Packages can export APIs they implement, (i.e. pkg.api: hw-hal-impl), and other packages can require -those APIs (i.e. pkg.req_api: hw-hal-impl).</li> +those APIs (i.e. pkg.req_api: hw-hal-impl).</p> +</li> +<li> +<p>Reads and validates the configuration setting definitions and values from the package <code>syscfg.yml</code> files. +It generates a <code>syscfg.h</code> header file that packages include in the source files inorder to access the settings.<br /> +It also generates a system initialization function to initialize the packages. +See <a href="../../os/modules/sysinitconfig/sysinitconfig/">System Configuration And Initialization</a> for more information.</p> +</li> </ul> -<p>In order to properly resolve all dependencies in the build system, Newt recursively processes the package dependencies until there are no new dependencies or features (because features can add dependencies.) And it builds a big list of all the packages that need to be build.</p> +<p>In order to properly resolve all dependencies in the build system, newt recursively processes the package dependencies until there are no new dependencies or features (because features can add dependencies.) And it builds a big list of all the packages that need to be build.</p> <p>Newt then goes through this package list, and builds every package into an archive file.</p> -<p><strong>NOTE:</strong> 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!</p> +<p><strong>NOTE:</strong> 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!</p> <h3 id="producing-artifacts">Producing artifacts</h3> -<p>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.)</p> +<p>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.)</p> <p>NOTE: One common use of the "features" option above is to overwrite which linkerscript is used, based upon whether or not the BSP is being build for a raw image, bootable image or bootloader itself.</p> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/get_started/project_create/index.html ---------------------------------------------------------------------- diff --git a/develop/os/get_started/project_create/index.html b/develop/os/get_started/project_create/index.html index ec0c35a..86718ae 100644 --- a/develop/os/get_started/project_create/index.html +++ b/develop/os/get_started/project_create/index.html @@ -579,6 +579,7 @@ Compiling image_validate.c <p><strong>NOTE:</strong> If you've installed the latest gcc using homebrew on your Mac, you will likely be running gcc-6. Make sure you have adjusted the compiler.yml configuration to reflect that as noted in <a href="../native_tools/">Native Install Option</a>. You can choose to downgrade to gcc-5 in order to use the default gcc compiler configuration for MyNewt.</p> +<p><strong>NOTE</strong> 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 multiboot gcc (e.g. gcc-multilib if you running on a 64-bit Ubuntu).</p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ brew uninstall gcc-6 $ brew link gcc-5 </pre></div> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/modules/sysinitconfig/sysconfig_error/index.html ---------------------------------------------------------------------- diff --git a/develop/os/modules/sysinitconfig/sysconfig_error/index.html b/develop/os/modules/sysinitconfig/sysconfig_error/index.html new file mode 100644 index 0000000..9b56ed5 --- /dev/null +++ b/develop/os/modules/sysinitconfig/sysconfig_error/index.html @@ -0,0 +1,877 @@ +<!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/os/modules/sysinitconfig/sysconfig_error/";> --> + <link rel="shortcut icon" href="../../../../img/favicon.ico"> + + <title>Validation and Error Messages - 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="Validation and Error Messages"> + + + <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-b1</a> released (Dec 13, 2016) + </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> + + <!-- Search, Navigation and Repo links --> + <ul class="nav navbar-nav navbar-right"> + + </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> + +</select> +</li> + + + + + + + + + + + + + + + + + + + + + + <li ><a href="../../../introduction/">Mynewt Documentation</a> + + + <ul> + + + + + + + + <li ><a href="../../../get_started/get_started/">Basic Setup</a> + + + </li> + + + + + + <li > + <a href="../../../get_started/vocabulary/">Concepts</a> + </li> + + + + + + + + <li ><a href="../../../tutorials/tutorials/">Tutorials</a> + + + </li> + + + + + + + + <li ><a href="../../../os_user_guide/">OS User Guide</a> + + + <ul> + + + + + + + + <li ><a href="../../../core_os/mynewt_os/">OS Core</a> + + + </li> + + + + + + + + <li ><a href="../../../core_os/porting/port_os/">Porting to your Platform</a> + + + </li> + + + + + + + + <li ><a href="../../console/console/">Console</a> + + + </li> + + + + + + + + <li ><a href="../../shell/shell/">Shell</a> + + + </li> + + + + + + + + <li ><a href="../../split/split/">Split Images</a> + + + </li> + + + + + + + + <li ><a href="../../bootloader/bootloader/">Bootloader</a> + + + </li> + + + + + + + + <li><a href=" + + + ../../fs/fs/fs/ + +">File System</a> + + + </li> + + + + + + + + <li ><a href="../../hal/hal/">Hardware Abstraction Layer</a> + + + </li> + + + + + + + + <li ><a href="../../drivers/driver/">Drivers</a> + + + </li> + + + + + + + + <li ><a href="../../testutil/testutil/">Test Utilities</a> + + + </li> + + + + + + + + <li ><a href="../../devmgmt/newtmgr/">Device Management with Newt Manager</a> + + + </li> + + + + + + + + <li ><a href="../../imgmgr/imgmgr/">Image Manager</a> + + + </li> + + + + + + <li > + <a href="../../baselibc/">Baselibc library</a> + </li> + + + + + + + + <li ><a href="../../elua/elua/">Embedded Lua</a> + + + </li> + + + + + + + + <li ><a href="../../json/json/">JSON</a> + + + </li> + + + + + + + + <li ><a href="../../fcb/fcb/">Flash Circular Buffer</a> + + + </li> + + + + + + + + <li ><a href="../../stats/stats/">Stats</a> + + + </li> + + + + + + + + <li ><a href="../../logs/logs/">Logs</a> + + + </li> + + + + + + + + <li ><a href="../sysinitconfig/">System Configuration And Initialization</a> + + + <ul> + + + + + + <li class="active"> + <a href="./">Validation and Error Messages</a> + </li> + + + + </ul> + + </li> + + + + </ul> + + </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> + + + + </ul> + + </li> + + + + + + + + <li><a href=" + ../../../../faq/how_to_edit_docs/ +">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 pull-right"> + <li><a href="/develop/os/introduction">Docs</a></li> + + + + <li>» <a href="../../../os_user_guide/">OS User Guide</a></li> + + + + <li>» <a href="../sysinitconfig/">System Configuration And Initialization</a></li> + + + + <li>» Validation and Error Messages</li> + + + + </ul> +</div> + </div> + + <h2 id="validation-and-error-messages">Validation and Error Messages</h2> +<p>With multiple packages defining and overriding system configuration settings, it +is easy to introduce conflicts and violations that are difficult to find. The +<code>newt build <target-name></code> command validates the setting definitions and value +overrides for all the packages in the target to ensure a valid and consistent build. +It aborts the build when it detects violations or ambiguities between packages.<br /> +The following sections describe the error conditions that newt detects and +the error messages that it outputs. For most errors, newt also outputs +the <code>Setting history</code> with the order of package overrides to help +you resolve the errors.</p> +<p><strong>Note:</strong> The <code>newt target config <target-name></code> command also detects +errors and outputs error messages at the top of the command output. +The command outputs the package setting definitions and values after it +outputs the error messages. It is easy to miss the error messages at the top. </p> +<h3 id="value-override-violations">Value Override Violations</h3> +<p>The newt tool uses package priorities to resolve override conflicts. It uses +the value override from the highest priority package when multiple +packages override the same setting. Newt checks for the following +override violations:</p> +<ul> +<li>Ambiguity Violation - Two packages of the same priority override a setting with +different values. And no higher priority package overrides the setting.</li> +<li>Priority Violation - A package overrides a setting defined by a package with higher or +equal priority (TODO: Change error message to indicate a more general priority violation instead of only lateral overrides)</li> +</ul> +<h4 id="example-ambiguity-violation-error-message">Example: Ambiguity Violation Error Message</h4> +<p>The following example shows the error message that newt outputs for an ambiguity violation:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: Syscfg ambiguities detected: + Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty] +Setting history (newest -> oldest): + LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log:0] +</pre></div> + + +<p>The above error occurs because the <code>apps/slinky</code> and <code>apps/splitty</code> packages +in the split image target both override the same setting with different +values. The <code>apps/slinky</code> package sets the <code>sys/log</code> package <code>LOG_NEWTMGR</code> +setting to 1, and the <code>apps/splitty</code> package sets the setting to 0. The +overrides are ambiguous because both are <code>app</code> packages and +have the same priority. The following are excerpts of the defintion +and the two overrides from the <code>syscfg.yml</code> files that cause the error:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">#Package: sys/log/ +syscfg.defs: + LOG_NEWTMGR: + description: 'Enables or disables newtmgr command tool logging' + value: 0 + +#Package: apps/slinky +syscfg.vals: + LOG_NEWTMGR: 1 + +#Package: apps/splitty +syscfg.vals: + LOG_NEWTMGR: 0 +</pre></div> + + +<h4 id="example-priority-violation-error-message">Example: Priority Violation Error Message</h4> +<p>The following example shows the error message that newt outputs for a lateral violation where a package tries to change the setting that was defined by another package at the same priority level:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: Lateral overrides detected (bottom-priority packages cannot override settings): + Package: mgmt/newtmgr, Setting: LOG_NEWTMGR + +Setting history (newest -> oldest): + LOG_NEWTMGR: [sys/log:0] +</pre></div> + + +<p>The above error occurs because the <code>mgmt/newtmgr</code> lib package +overrides the <code>LOG_NEWTMGR</code> setting that the <code>sys/log</code> lib package +defines. The following are excerpts of the definition and the override from the +<code>syscfg.yml</code> files that cause this error: </p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">#Package: sys/log +syscfg.defs: + LOG_NEWTMGR: + description: 'Enables or disables newtmgr command tool logging' + value: 0 + +#Package: mgmt/newtmgr +syscfg.vals: + LOG_NEWTMGR: 1 +</pre></div> + + +<p><br></p> +<h3 id="flash-area-violations">Flash Area Violations</h3> +<p>For <code>flash_owner</code> type setting definitions, newt checks +for the following violations:</p> +<ul> +<li>An undefined flash area is assigned to a setting.</li> +<li>A flash area is assigned to multiple settings.</li> +</ul> +<h4 id="example-undefined-flash-area-error-message">Example: Undefined Flash Area Error Message</h4> +<p>The following example shows the error message that newt outputs for an undefined flash area.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Building target targets/sim_slinky +Error: Flash errors detected: + Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST + +Setting history (newest -> oldest): + REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:] +</pre></div> + + +<p>The above error occurs because the <code>hw/bsp/native</code> package assigns the +undefined <code>FLASH_AREA_NOEXIST</code> flash area to the <code>sys/reboot</code> package +<code>REBOOT_LOG_FLASH_AREA</code> setting. The following are excerpts of the definition +and the override from the <code>syscfg.yml</code> files that cause the error:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">#Package: sys/reboot +syscfg.defs: + REBOOT_LOG_FLASH_AREA: + description: 'Flash Area to use for reboot log.' + type: flash_owner + value: + +#Package: hw/bsp/native +syscfg.vals: + REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST +</pre></div> + + +<h4 id="example-multiple-flash-area-assignment-error-message">Example: Multiple Flash Area Assignment Error Message</h4> +<p>The following example shows the error message that newt outputs when multiple +settings are assigned the same flash area:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: Flash errors detected: + Multiple flash_owner settings specify the same flash area + settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA + flash area: FLASH_AREA_NFFS + +Setting history (newest -> oldest): + CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:] + REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:] +</pre></div> + + +<p>The above error occurs because the <code>hw/bsp/native</code> package assigns +the <code>FLASH_AREA_NFFS</code> flash area to the <code>sys/config/</code> package +<code>CONFIG_FCB_FLASH_AREA</code> setting, and the <code>apps/slinky</code> package +also assigns <code>FLASH_AREA_NFFS</code> to the <code>sys/reboot</code> package +<code>REBOOT_LOG_FLASH_AREA</code> setting. The following are excerpts of the +two definitions and the two overrides from the <code>syscfg.yml</code> files +that cause the error:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># Package: sys/config +syscfg.defs.CONFIG_FCB: + CONFIG_FCB_FLASH_AREA: + description: 'The flash area for the Config Flash Circular Buffer' + type: 'flash_owner' + value: + +# Package: sys/reboot +syscfg.defs: + REBOOT_LOG_FLASH_AREA: + description: 'The flash area for the reboot log' + type: 'flash_owner' + value: + +#Package: hw/bsp/native +syscfg.vals: + CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS + +#Package: apps/slinky +syscfg.vals: + REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS +</pre></div> + + +<p><br></p> +<h3 id="restriction-violations">Restriction Violations</h3> +<p>For setting definitions with <code>restrictions</code> specified, newt checks for +the following violations:</p> +<ul> +<li>A setting with a <code>$notnull</code> restriction does not have a value. </li> +<li>For a setting with expression restrictions, some required setting +values in the expressions evaluate to false. </li> +</ul> +<h4 id="example-notnull-restriction-violation-error-message">Example: $notnull Restriction Violation Error Message</h4> +<p>The following example shows the error message that newt outputs when +a setting with <code>$notnull</code> restriction does not have a value:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: Syscfg restriction violations detected: + NFFS_FLASH_AREA must not be null + +Setting history (newest -> oldest): + NFFS_FLASH_AREA: [fs/nffs:] +</pre></div> + + +<p>The above error occurs because the <code>fs/nffs</code> package defines the <code>NFFS_FLASH_AREA</code> +setting with a <code>$notnull</code> restriction and no packages override the setting. The +following is an excerpt of the definition in the <code>syscfg.yml</code> file that causes the error:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">#Package: fs/nffs +syscfg.defs: + NFFS_FLASH_AREA: + description: 'The flash area to use for the Newtron Flash File System' + type: flash_owner + value: + restrictions: + - $notnull +</pre></div> + + +<h4 id="example-expression-restriction-violation-error-message">Example: Expression Restriction Violation Error Message</h4> +<p>The following example shows the error message that newt outputs for +an expression restriction violation:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: Syscfg restriction violations detected: + CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA= + +Setting history (newest -> oldest): + CONFIG_FCB: [targets/sim_slinky:1, sys/config:0] + CONFIG_FCB_FLASH_AREA: [sys/config:] +</pre></div> + + +<p>The above error occurs because the <code>sys/config</code> package defines the <code>CONFIG_FCB</code> setting with +a restriction that when set, requires that the <code>CONFIG_FCB_FLASH_AREA</code> setting must +also be set. The following are excerpts of the definition and the override from the <code>syscfg.yml</code> +files that cause the error:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"># Package: sys/config +syscfg.defs: + CONFIG_FCB: + description: 'Uses Config Flash Circular Buffer' + value: 0 + restrictions: + - '!CONFIG_NFFS' + - 'CONFIG_FCB_FLASH_AREA' + +# Package: targets/sim_slinky +syscfg.vals: + CONFIG_FCB: 1 +</pre></div> + + +<p><br></p> +<h3 id="task-priority-violations">Task Priority Violations</h3> +<p>For <code>task_priority</code> type setting definitions, newt checks for the following violations:</p> +<ul> +<li>A task priority number is assigned to multiple settings. </li> +<li>The task priority number is greater than 239.</li> +</ul> +<h4 id="example-duplicate-task-priority-assignment-error-message">Example: Duplicate Task Priority Assignment Error Message</h4> +<p>The following example shows the error message that newt outputs when +a task priority number is assigned to multiple settings.</p> +<p><strong>Note:</strong> The settings used in this example are not actual <code>apps/slinky</code> and <code>sys/shell</code> settings. +These settings are created for this example because currently only one Mynewt package +defines a <code>task_priority</code> type setting. </p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1 +</pre></div> + + +<p>The above error occurs because the <code>apps/slinky</code> package defines a <code>SLINKY_TASK_PRIORITY</code> +setting with a default task priority of 1 and the <code>sys/shell</code> package also defines a +<code>SHELL_TASK_PRIORITY</code> setting with a default task priority of 1.</p> +<h4 id="example-invalid-task-priority-error-message">Example: Invalid Task Priority Error Message</h4> +<p>The following example shows the error message that newt outputs when +a setting is assigned an invalid task priority value:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: invalid priority value: value too great (> 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky +</pre></div> + + +<p>The above error occurs because the <code>apps/slinky</code> package defines the <code>SLINKY_TASK_PRIORITY</code> setting +with 240 for the default task priority value. </p> +<p><strong>Note:</strong> Newt does not output the <code>Setting history</code> with task priority violation error messages. </p> +<p><br></p> +<h3 id="duplicate-system-configuration-setting-definition">Duplicate System Configuration Setting Definition</h3> +<p>A setting definition must be unique. Newt checks that only one package in the +target defines a setting. The following example shows the error message that newt +outputs when multiple packages define the <code>LOG_NEWTMGR</code> setting:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">Error: setting LOG_NEWTMGR redefined +</pre></div> + + +<p><strong>Note:</strong> Newt does not output the <code>Setting history</code> with duplicate setting error messages. </p> + + <div class="row"> + + + + +<ul class="nav nav-pills" style="margin-bottom: 10px"> + <li> + + <a href=../sysinitconfig/> + <span class="fa fa-arrow-left"></span> + Previous: System Configuration And Initialization + </a> + + </li> + <li class="pull-right"> + + <a href=../../../../network/ble/ble_intro/> + Next: NimBLE Introduction + <span class="fa fa-arrow-right"></span> + </a> + + </li> +</ul> + </div> + <footer class="row"> + <div class="col-xs-12"> + + <p class="copyright">Copyright © 2015 The Apache Software Foundation, Licensed under the Apache License, Version 2.0 Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</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"> + MyNewt is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. + </small> + <img src="/img/egg-logo2.png" alt="Apache Incubator" title="Apache Incubator"> + </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 http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/modules/sysinitconfig/sysinitconfig/index.html ---------------------------------------------------------------------- diff --git a/develop/os/modules/sysinitconfig/sysinitconfig/index.html b/develop/os/modules/sysinitconfig/sysinitconfig/index.html index e09de65..7b1a786 100644 --- a/develop/os/modules/sysinitconfig/sysinitconfig/index.html +++ b/develop/os/modules/sysinitconfig/sysinitconfig/index.html @@ -450,6 +450,14 @@ + + + <li > + <a href="../sysconfig_error/">Validation and Error Messages</a> + </li> + + + </ul> </li> @@ -541,7 +549,7 @@ </div> </div> - <h1 id="system-configuration-and-initialization">System Configuration and Initialization</h1> + <h2 id="system-configuration-and-initialization">System Configuration and Initialization</h2> <p>This guide describes how Mynewt manages system configuration and initialization. It shows you how to tell Mynewt to use default or customized values to initialize packages that you develop or use to build a target. This guide:</p> <ul> @@ -591,7 +599,7 @@ has the following syntax: </p> <p>Each setting definition consists of the following key-value mapping: </p> <ul> <li>A setting name for the key, such as <code>PKGA_SYSCFG_NAME1</code> in the syntax example above. -Note: A system configuration setting name must be unique. The newt tool aborts the build +<strong>Note:</strong> A system configuration setting name must be unique. The newt tool aborts the build when multiple packages define the same setting. </li> <li>A mapping of fields for the value. Each field itself is a key-value pair of attributes. The field keys are <code>description</code>, <code>value</code>, <code>type</code>, and <code>restrictions</code>. They are described in following table:</li> @@ -636,8 +644,8 @@ defined in the BSP flash map for your target board. <li><code>expression</code> - Specifies a boolean expression of the form <code>[!]<required-setting>[if <base-value>]</code> <br>Examples: <ul> -<li><code>restrictions: !LOG_FCB</code> - Can only enable this setting when <code>LOG_FCB</code> is false. -<li><code>restrictions: LOG_FCB if 0 </code> - Can only disable this setting when <code>LOG_FCB</code> is true. +<li><code>restrictions: !LOG_FCB</code> - When this setting is enabled, <code>LOG_FCB</code> must be disabled. +<li><code>restrictions: LOG_FCB if 0 </code> - When this setting is disabled, <code>LOG_FCB</code> must be enabled. </ul> </li> </ul> @@ -646,7 +654,7 @@ defined in the BSP flash map for your target board. </table> <p><br></p> -<h4 id="examples-of-configuration-settings">Examples of configuration settings</h4> +<h4 id="examples-of-configuration-settings">Examples of Configuration Settings</h4> <p><strong>Example 1:</strong> The following example is an excerpt from the <code>sys/log</code> package <code>syscfg.yml</code> file. It defines the <code>LOG_LEVEL</code> configuration setting to specify the log level and the <code>LOG_NEWTMGR</code> configuration setting to specify whether to enable or disable the newtmgr logging feature.</p> @@ -725,7 +733,7 @@ by other packages. This mechanism allows:</p> </pre></div> -<p>Note: The newt tool ignores overrides of undefined system configuration settings. </p> +<p><strong>Note</strong>: The newt tool ignores overrides of undefined system configuration settings. </p> <p><br></p> <h4 id="resolving-override-conflicts">Resolving Override Conflicts</h4> <p>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:</p> @@ -743,14 +751,14 @@ by other packages. This mechanism allows:</p> <li>App</li> <li>unittest - A target can include either an app or unit test package, but not both.</li> <li>BSP</li> -<li>Lib - Includes all other system level packages such as os, lib, sdk, and compiler.</li> +<li>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.)</li> </ul> <p>It is recommended that you override defaults at the target level instead of updating individual package <code>syscfg.yml</code> files.</p> <p><br></p> <h4 id="examples-of-overrides">Examples of Overrides</h4> <p><strong>Example 4:</strong> The following example is an excerpt from the <code>apps/slinky</code> package <code>syscfg.yml</code> file. The application package overrides, -in addition to other packages, the <code>sys/log</code> package system configuration settings defined in <em>Example 1</em>. It changes the LOG_NEWTMGR system configuration setting value from <code>0</code> to <code>1</code>.</p> +in addition to other packages, the <code>sys/log</code> package system configuration settings defined in <strong>Example 1</strong>. It changes the LOG_NEWTMGR system configuration setting value from <code>0</code> to <code>1</code>.</p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">syscfg.vals: # Enable the shell task. SHELL_TASK: 1 @@ -795,25 +803,43 @@ syscfg.vals: <p><br></p> -<h3 id="generated-syscfgh">Generated syscfg.h</h3> +<h3 id="generated-syscfgh-and-referencing-system-configuration-settings">Generated syscfg.h and Referencing System Configuration Settings</h3> <p>The newt tool processes all the package <code>syscfg.yml</code> files and generates the <code><target-path>/generated/include/syscfg/syscfg.h</code> include file with <code>#define</code> statements for each system configuration -setting defined. newt creates a <code>#define</code> for a setting name as follows: </p> +setting defined. Newt creates a <code>#define</code> for a setting name as follows: </p> <ul> <li>Adds the prefix <code>MYNEWT_VAL_</code>.</li> <li>Replaces all occurrences of "/", "-", and " " in the setting name with "_".</li> <li>Converts all characters to upper case.</li> </ul> -<p>For example, the #define for <code>my-config-name</code> setting name is <code>MYNEWT_VAL_MY_CONFIG_NAME</code>.</p> +<p>For example, the #define for my-config-name setting name is MYNEWT_VAL_MY_CONFIG_NAME.</p> <p>Newt groups the settings in <code>syscfg.h</code> by the packages that defined them. It also indicates the package that changed a system configuration setting value. </p> +<p>You must use the <code>MYNEWT_VAL()</code> macro to reference a #define of a setting name in your header and source files. +For example, to reference the <code>my-config-name</code> setting name, you use <code>MYNEWT_VAL(MY_CONFIG_NAME)</code>.</p> <p><strong>Note:</strong> You only need to include <code>syscfg/syscfg.h</code> in your source files to access the <code>syscfg.h</code> file. The newt tool sets the correct include path to build your target. </p> -<p>Here is an excerpt from a sample <code>syscfg.h</code> file generated for an app/slinky target. It lists -the <code>sys/log</code> package definitions and also indicates that <code>app/slinky</code> changed the value -for the <code>LOG_NEWTMGR</code> settings. </p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">#ifndef H_MYNEWT_SYSCFG_ +<h4 id="example-of-syscfgh-and-how-to-reference-a-setting-name">Example of syscfg.h and How to Reference a Setting Name</h4> +<p><strong>Example 6</strong>: The following example are excerpts from a sample <code>syscfg.h</code> file generated for an app/slinky target and +from the <code>sys/log</code> package <code>log.c</code> file that shows how to reference a setting name.</p> +<p>The <code>syscfg.h</code> file shows the <code>sys/log</code> package definitions and also indicates that <code>app/slinky</code> +changed the value for the <code>LOG_NEWTMGR</code> settings. </p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">/** + * This file was generated by Apache Newt (incubating) version: 1.0.0-dev + */ + +#ifndef H_MYNEWT_SYSCFG_ #define H_MYNEWT_SYSCFG_ +/** + * This macro exists to ensure code includes this header when needed. If code + * checks the existence of a setting directly via ifdef without including this + * header, the setting macro will silently evaluate to 0. In contrast, an + * attempt to use these macros without including this header will result in a + * compiler error. + */ +#define MYNEWT_VAL(x) MYNEWT_VAL_ ## x + + ... /*** kernel/os */ @@ -844,6 +870,34 @@ for the <code>LOG_NEWTMGR</code> settings. </p> </pre></div> +<p>The <code>log_init()</code> function in the <code>sys/log/src/log.c</code> file initializes the <code>sys/log</code> package. It checks the +<code>LOG_NEWTMGR</code> setting value, using <code>MYNEWT_VAL(LOG_NEWTMGR)</code>, to determine whether the target application +has enabled the <code>newtmgr log</code> functionality. It only registers the the callbacks to process the +<code>newtmgr log</code> commands when the setting value is non-zero.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">void +log_init(void) +{ + int rc; + + /* Ensure this function only gets called by sysinit. */ + SYSINIT_ASSERT_ACTIVE(); + + (void)rc; + + if (log_inited) { + return; + } + log_inited = 1; + ... + +#if MYNEWT_VAL(LOG_NEWTMGR) + rc = log_nmgr_register_group(); + SYSINIT_PANIC_ASSERT(rc == 0); +#endif +} +</pre></div> + + <p><br></p> <h3 id="system-initialization">System Initialization</h3> <p>An application's <code>main()</code> function must first call the Mynewt <code>sysinit()</code> function to @@ -877,10 +931,10 @@ are initialized before higher priority packages.</p> <p>where <code>stage_number</code> is a number that indicates when this init function is called relative to the other package init functions. Mynewt calls the package init functions in increasing stage number order and in alphabetic order of init function names for functions in the same stage. - <em>Note:</em> The init function will be called at stage 0 if <code>pkg.init_stage</code> is not specified.</p> + <strong>Note:</strong> The init function will be called at stage 0 if <code>pkg.init_stage</code> is not specified.</p> </li> </ul> -<p><em>Note:</em> You must include the <code>sysinit/sysinit.h</code> header file to access the <code>sysinit()</code> function.</p> +<p><strong>Note:</strong> You must include the <code>sysinit/sysinit.h</code> header file to access the <code>sysinit()</code> function.</p> <p><br></p> <h4 id="generated-sysinit_app-function">Generated sysinit_app() Function</h4> <p>The newt tool processes the <code>init_function</code> and <code>init_stage</code> parameters in all the pkg.yml files for a target, @@ -978,8 +1032,8 @@ pkg.deps.OS_CLI </li> <li class="pull-right"> - <a href=../../../../network/ble/ble_intro/> - Next: NimBLE Introduction + <a href=../sysconfig_error/> + Next: Validation and Error Messages <span class="fa fa-arrow-right"></span> </a> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/tutorials/STM32F303/index.html ---------------------------------------------------------------------- diff --git a/develop/os/tutorials/STM32F303/index.html b/develop/os/tutorials/STM32F303/index.html index 9bd5fcc..a650118 100644 --- a/develop/os/tutorials/STM32F303/index.html +++ b/develop/os/tutorials/STM32F303/index.html @@ -355,8 +355,13 @@ - <li > - <a href="../air_quality_sensor/">Air-quality Sensor project</a> + + + <li><a href=" + ../air_quality_sensor/ +">Air-quality Sensor project</a> + + </li> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/tutorials/add_newtmgr/index.html ---------------------------------------------------------------------- diff --git a/develop/os/tutorials/add_newtmgr/index.html b/develop/os/tutorials/add_newtmgr/index.html index 1ad853a..fab0065 100644 --- a/develop/os/tutorials/add_newtmgr/index.html +++ b/develop/os/tutorials/add_newtmgr/index.html @@ -278,8 +278,13 @@ - <li > - <a href="../air_quality_sensor/">Air-quality Sensor project</a> + + + <li><a href=" + ../air_quality_sensor/ +">Air-quality Sensor project</a> + + </li> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/tutorials/add_shell/index.html ---------------------------------------------------------------------- diff --git a/develop/os/tutorials/add_shell/index.html b/develop/os/tutorials/add_shell/index.html index dd2ccbe..de87a07 100644 --- a/develop/os/tutorials/add_shell/index.html +++ b/develop/os/tutorials/add_shell/index.html @@ -278,8 +278,13 @@ - <li > - <a href="../air_quality_sensor/">Air-quality Sensor project</a> + + + <li><a href=" + ../air_quality_sensor/ +">Air-quality Sensor project</a> + + </li> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/170decb3/develop/os/tutorials/air_quality_ble/index.html ---------------------------------------------------------------------- diff --git a/develop/os/tutorials/air_quality_ble/index.html b/develop/os/tutorials/air_quality_ble/index.html new file mode 100644 index 0000000..4c0bc79 --- /dev/null +++ b/develop/os/tutorials/air_quality_ble/index.html @@ -0,0 +1,736 @@ +<!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/os/tutorials/air_quality_ble/";> --> + <link rel="shortcut icon" href="../../../img/favicon.ico"> + + <title>Bluetooth-enabled Air Quality Sensor - 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="Bluetooth-enabled Air Quality Sensor"> + + + <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-b1</a> released (Dec 13, 2016) + </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> + + <!-- Search, Navigation and Repo links --> + <ul class="nav navbar-nav navbar-right"> + + </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> + +</select> +</li> + + + + + + + + + + + + + + + + + + + + + + <li ><a href="../../introduction/">Mynewt Documentation</a> + + + <ul> + + + + + + + + <li ><a href="../../get_started/get_started/">Basic Setup</a> + + + </li> + + + + + + <li > + <a href="../../get_started/vocabulary/">Concepts</a> + </li> + + + + + + + + <li ><a href="../tutorials/">Tutorials</a> + + + <ul> + + + + + + + + <li><a href=" + ../arduino_zero/ +">Project Blinky</a> + + + </li> + + + + + + + + <li ><a href="../repo/add_repos/">Work with repositories</a> + + + </li> + + + + + + <li > + <a href="../tasks_lesson/">Tasks and Priority Management</a> + </li> + + + + + + <li > + <a href="../wi-fi_on_arduino/">Enable Wi-Fi on Arduino Zero</a> + </li> + + + + + + <li > + <a href="../unit_test/">Write a Test Suite for a Package</a> + </li> + + + + + + + + <li><a href=" + ../air_quality_sensor/ +">Air-quality Sensor project</a> + + + <ul> + + + + <li > + <a href="../air_quality_sensor/">Basic Air Quality Sensor</a> + </li> + + + + + + <li class="active"> + <a href="./">Bluetooth-enabled Air Quality Sensor</a> + </li> + + + + </ul> + + </li> + + + + + + <li > + <a href="../event_queue/">Add task to manage multiple events</a> + </li> + + + + + + + + <li><a href=" + ../project-slinky/ +">Project Slinky for remote comms</a> + + + </li> + + + + + + <li > + <a href="../add_newtmgr/">Enable newtmgr in any app</a> + </li> + + + + + + <li > + <a href="../add_shell/">Enable the OS Shell and Console</a> + </li> + + + + + + <li > + <a href="../bletiny_project/">BLE app to check stats via console</a> + </li> + + + + + + + + <li ><a href="../bleprph/bleprph-intro/">BLE peripheral project</a> + + + </li> + + + + + + <li > + <a href="../ibeacon/">BLE iBeacon</a> + </li> + + + + + + <li > + <a href="../blehci_project/">BLE HCI interface</a> + </li> + + + + </ul> + + </li> + + + + + + + + <li ><a href="../../os_user_guide/">OS User Guide</a> + + + </li> + + + + + + + + <li><a href=" + ../../../network/ble/ble_intro/ +">BLE User Guide</a> + + + </li> + + + + + + + + <li ><a href="../../../newt/newt_intro/">Newt Tool Guide</a> + + + </li> + + + + + + + + <li ><a href="../../../newtmgr/overview/">Newt Manager Guide</a> + + + </li> + + + + </ul> + + </li> + + + + + + + + <li><a href=" + ../../../faq/how_to_edit_docs/ +">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 pull-right"> + <li><a href="/develop/os/introduction">Docs</a></li> + + + + <li>» <a href="../tutorials/">Tutorials</a></li> + + + + <li>» <a href="../air_quality_sensor/">Air-quality Sensor project</a></li> + + + + <li>» Bluetooth-enabled Air Quality Sensor</li> + + + + </ul> +</div> + </div> + + <h2 id="air-quality-sensor-project-via-bluetooth">Air quality sensor project via Bluetooth</h2> +<p>This is a follow-on project to the <a href="../air_quality_sensor/">Basic Air Quality Sensor</a> project; so it is +assumed that you have worked through that project and have your CO<sub>2</sub> sensor working properly with +your Arduino Primo board. </p> +<p>So let's get started making this thing Bluetooth enabled!</p> +<h3 id="add-bluetooth-gatt-services">Add Bluetooth GATT Services</h3> +<p>Since we already built the previous demo on the <a href="../bleprph/bleprph-app/">bluetooth peripheral</a> basic +app most of the bluetooth plumbing has already been taken care of for us. What's left is for us +to add the required GATT services for advertising the Carbon Dioxide sensor so that +other devices can get those values.</p> +<p>First, we'll define the GATT Services in <code>apps/air_quality/src/bleprph.h</code>.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/* Sensor Data */</span> +<span style="color: #177500">/* e761d2af-1c15-4fa7-af80-b5729002b340 */</span> +<span style="color: #A90D91">static</span> <span style="color: #A90D91">const</span> <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">gatt_svr_svc_co2_uuid</span>[<span style="color: #1C01CE">16</span>] <span style="color: #000000">=</span> { + <span style="color: #1C01CE">0x40</span>, <span style="color: #1C01CE">0xb3</span>, <span style="color: #1C01CE">0x20</span>, <span style="color: #1C01CE">0x90</span>, <span style="color: #1C01CE">0x72</span>, <span style="color: #1C01CE">0xb5</span>, <span style="color: #1C01CE">0x80</span>, <span style="color: #1C01CE">0xaf</span>, + <span style="color: #1C01CE">0xa7</span>, <span style="color: #1C01CE">0x4f</span>, <span style="color: #1C01CE">0x15</span>, <span style="color: #1C01CE">0x1c</span>, <span style="color: #1C01CE">0xaf</span>, <span style="color: #1C01CE">0xd2</span>, <span style="color: #1C01CE">0x61</span>, <span style="color: #1C01CE">0xe7</span> }; +<span style="color: #633820">#define CO2_SNS_TYPE 0xDEAD</span> +<span style="color: #633820">#define CO2_SNS_STRING "SenseAir K30 CO2 Sensor"</span> +<span style="color: #633820">#define CO2_SNS_VAL 0xBEAD</span> + +<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">gatt_co2_val</span>; +</pre></div> + + +<p>You can use any hex values you choose for the sensor type and sensor values, and you can +even forget the sensor type and sensor string definitions altogether but they make +the results look nice in our Bleutooth App.</p> +<p>Next we'll add those services to <code>apps/air_quality/src/gatt_svr.c</code>.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span> +<span style="color: #000000">gatt_svr_sns_access</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</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">ble_gatt_access_ctxt</span> <span style="color: #000000">*ctxt</span>, + <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>); + +<span style="color: #A90D91">static</span> <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">gatt_co2_val_len</span>; +</pre></div> + + +<p>Make sure it is added as <em>primary</em> service.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">const</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_svc_def</span> <span style="color: #000000">gatt_svr_svcs</span>[] <span style="color: #000000">=</span> { + { + <span style="color: #177500">/*** Service: Security test. */</span> + .<span style="color: #000000">type</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_SVC_TYPE_PRIMARY</span>, + .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_svc_sec_test_uuid</span>, + .<span style="color: #000000">characteristics</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_chr_def</span>[]) { { + <span style="color: #177500">/*** Characteristic: Random number generator. */</span> + .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_sec_test_rand_uuid</span>, + .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_access_sec_test</span>, + .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_READ</span> <span style="color: #000000">|</span> <span style="color: #000000">BLE_GATT_CHR_F_READ_ENC</span>, + }, { + <span style="color: #177500">/*** Characteristic: Static value. */</span> + .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_sec_test_static_uuid</span>, + .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_access_sec_test</span>, + .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_READ</span> <span style="color: #000000">|</span> + <span style="color: #000000">BLE_GATT_CHR_F_WRITE</span> <span style="color: #000000">|</span> <span style="color: #000000">BLE_GATT_CHR_F_WRITE_ENC</span>, + }, { + <span style="color: #1C01CE">0</span>, <span style="color: #177500">/* No more characteristics in this service. */</span> + } }, + }, + { + <span style="color: #177500">/*** CO2 Level Notification Service. */</span> + .<span style="color: #000000">type</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_SVC_TYPE_PRIMARY</span>, + .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_svc_co2_uuid</span>, + .<span style="color: #000000">characteristics</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">struct</span> <span style="color: #000000">ble_gatt_chr_def</span>[]) { { + .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">CO2_SNS_TYPE</span>), + .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_sns_access</span>, + .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_READ</span>, + }, { + .<span style="color: #000000">uuid128</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">CO2_SNS_VAL</span>), + .<span style="color: #000000">access_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_sns_access</span>, + .<span style="color: #000000">flags</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GATT_CHR_F_NOTIFY</span>, + }, { + <span style="color: #1C01CE">0</span>, <span style="color: #177500">/* No more characteristics in this service. */</span> + } }, + }, + { + <span style="color: #1C01CE">0</span>, <span style="color: #177500">/* No more services. */</span> + }, +}; +</pre></div> + + +<p>Next we need to tell the GATT Server how to handle requests for CO<sub>2</sub> readings :</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span> +<span style="color: #000000">gatt_svr_sns_access</span>(<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">conn_handle</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">ble_gatt_access_ctxt</span> <span style="color: #000000">*ctxt</span>, + <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>) +{ + <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">uuid16</span>; + <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>; + + <span style="color: #000000">uuid16</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_uuid_128_to_16</span>(<span style="color: #000000">ctxt->chr->uuid128</span>); + <span style="color: #000000">assert</span>(<span style="color: #000000">uuid16</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>); + + <span style="color: #A90D91">switch</span> (<span style="color: #000000">uuid16</span>) { + <span style="color: #A90D91">case</span> <span style="color: #000000">CO2_SNS_TYPE</span>: + <span style="color: #000000">assert</span>(<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>); + <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">os_mbuf_append</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #000000">CO2_SNS_STRING</span>, <span style="color: #A90D91">sizeof</span> <span style="color: #000000">CO2_SNS_STRING</span>); + <span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">"CO2 SENSOR TYPE READ: %s\n"</span>, <span style="color: #000000">CO2_SNS_STRING</span>); + <span style="color: #A90D91">return</span> <span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">?</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">:</span> <span style="color: #000000">BLE_ATT_ERR_INSUFFICIENT_RES</span>; + + <span style="color: #A90D91">case</span> <span style="color: #000000">CO2_SNS_VAL</span>: + <span style="color: #A90D91">if</span> (<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_WRITE_CHR</span>) { + <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">gatt_svr_chr_write</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #1C01CE">0</span>, + <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_co2_val</span>, + <span style="color: #000000">&gatt_co2_val</span>, + <span style="color: #000000">&gatt_co2_val_len</span>); + <span style="color: #A90D91">return</span> <span style="color: #000000">rc</span>; + } <span style="color: #A90D91">else</span> <span style="color: #A90D91">if</span> (<span style="color: #000000">ctxt->op</span> <span style="color: #000000">==</span> <span style="color: #000000">BLE_GATT_ACCESS_OP_READ_CHR</span>) { + <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">os_mbuf_append</span>(<span style="color: #000000">ctxt->om</span>, <span style="color: #000000">&gatt_co2_val</span>, + <span style="color: #A90D91">sizeof</span> <span style="color: #000000">gatt_co2_val</span>); + <span style="color: #A90D91">return</span> <span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">?</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">:</span> <span style="color: #000000">BLE_ATT_ERR_INSUFFICIENT_RES</span>; + } + + <span style="color: #A90D91">default</span><span style="color: #000000">:</span> + <span style="color: #000000">assert</span>(<span style="color: #1C01CE">0</span>); + <span style="color: #A90D91">return</span> <span style="color: #000000">BLE_ATT_ERR_UNLIKELY</span>; + } +} +</pre></div> + + +<p>Now it's time to go into our <code>apps/air_quality/src/main.c</code> and change how we read CO<sub>2</sub> readings and +respond to requests. </p> +<p>We'll need a task handler with an event queue for the CO<sub>2</sub> 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.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/* CO2 Task settings */</span> +<span style="color: #633820">#define CO2_TASK_PRIO 5</span> +<span style="color: #633820">#define CO2_STACK_SIZE (OS_STACK_ALIGN(336))</span> +<span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">co2_evq</span>; +<span style="color: #A90D91">struct</span> <span style="color: #000000">os_task</span> <span style="color: #000000">co2_task</span>; +<span style="color: #A90D91">bssnz_t</span> <span style="color: #A90D91">os_stack_t</span> <span style="color: #000000">co2_stack</span>[<span style="color: #000000">CO2_STACK_SIZE</span>]; +</pre></div> + + +<p>And of course we'll need to go to our <code>main()</code> and do all the standard task and event setup we +normally do by adding the following. Again, remember to delete all the shell event queues and tasks.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/* Initialize sensor eventq */</span> +<span style="color: #000000">os_eventq_init</span>(<span style="color: #000000">&co2_evq</span>); + +<span style="color: #177500">/* Create the CO2 reader task. </span> +<span style="color: #177500"> * All sensor reading operations are performed in this task.</span> +<span style="color: #177500"> */</span> +<span style="color: #000000">os_task_init</span>(<span style="color: #000000">&co2_task</span>, <span style="color: #C41A16">"sensor"</span>, <span style="color: #000000">co2_task_handler</span>, + <span style="color: #A90D91">NULL</span>, <span style="color: #000000">CO2_TASK_PRIO</span>, <span style="color: #000000">OS_WAIT_FOREVER</span>, + <span style="color: #000000">co2_stack</span>, <span style="color: #000000">CO2_STACK_SIZE</span>); +</pre></div> + + +<p>We'll also need to add a task handler -- since we initialized it above:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/**</span> +<span style="color: #177500"> * Event loop for the sensor task.</span> +<span style="color: #177500"> */</span> +<span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span> +<span style="color: #000000">co2_task_handler</span>(<span style="color: #A90D91">void</span> <span style="color: #000000">*unused</span>) +{ + <span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) { + <span style="color: #000000">co2_read_event</span>(); + <span style="color: #177500">/* Wait 2 second */</span> + <span style="color: #000000">os_time_delay</span>(<span style="color: #000000">OS_TICKS_PER_SEC</span> <span style="color: #000000">*</span> <span style="color: #1C01CE">2</span>); + + } +} +</pre></div> + + +<p>And finally, we'll take care of that <code>co2_read_event()</code> function:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">int</span> +<span style="color: #000000">co2_read_event</span>(<span style="color: #A90D91">void</span>) +{ + <span style="color: #A90D91">int</span> <span style="color: #000000">value</span>; + <span style="color: #A90D91">enum</span> <span style="color: #000000">senseair_read_type</span> <span style="color: #000000">type</span> <span style="color: #000000">=</span> <span style="color: #000000">SENSEAIR_CO2</span>; + <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">chr_val_handle</span>; + <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>; + + <span style="color: #000000">value</span> <span style="color: #000000">=</span> <span style="color: #000000">senseair_read</span>(<span style="color: #000000">type</span>); + <span style="color: #A90D91">if</span> (<span style="color: #000000">value</span> <span style="color: #000000">>=</span> <span style="color: #1C01CE">0</span>) { + <span style="color: #000000">console_printf</span>(<span style="color: #C41A16">"Got %d\n"</span>, <span style="color: #000000">value</span>); + } <span style="color: #A90D91">else</span> { + <span style="color: #000000">console_printf</span>(<span style="color: #C41A16">"Error while reading: %d\n"</span>, <span style="color: #000000">value</span>); + <span style="color: #A90D91">goto</span> <span style="color: #000000">err</span>; + } + <span style="color: #000000">gatt_co2_val</span> <span style="color: #000000">=</span> <span style="color: #000000">value</span>; + <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gatts_find_chr</span>(<span style="color: #000000">gatt_svr_svc_co2_uuid</span>, <span style="color: #000000">BLE_UUID16</span>(<span style="color: #000000">CO2_SNS_VAL</span>), <span style="color: #A90D91">NULL</span>, <span style="color: #000000">&chr_val_handle</span>); + <span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>); + <span style="color: #000000">ble_gatts_chr_updated</span>(<span style="color: #000000">chr_val_handle</span>); + <span style="color: #A90D91">return</span> (<span style="color: #1C01CE">0</span>); +<span style="color: #000000">err</span>: + <span style="color: #A90D91">return</span> (<span style="color: #000000">rc</span>); +} +</pre></div> + + +<p>You'll notice that it looks eeirily similar to a portion of the shell event we created +earlier. This one simply reads and updates the CO<sub>2</sub> value and sends that over BLE to any +connected clients instead. </p> +<p>We can now build, create-image and load the app onto our Arduino Primo board, and then +connect and see the updated values! The image below shows the results using MyNewt Sensor Reader, +a Mac OS X app developed for connecting to MyNewt devices over Bluetooth but you can also use LightBlue +or any other application that can connect to, and read, Bluetooth data.</p> +<p><img alt="MyNewt Sensor Reader" src="../pics/MyNewtSensorReader.jpg" /></p> +<p>Congratulations!!</p> + + <div class="row"> + + + + +<ul class="nav nav-pills" style="margin-bottom: 10px"> + <li> + + <a href=../air_quality_sensor/> + <span class="fa fa-arrow-left"></span> + Previous: Basic Air Quality Sensor + </a> + + </li> + <li class="pull-right"> + + <a href=../event_queue/> + Next: Add task to manage multiple events + <span class="fa fa-arrow-right"></span> + </a> + + </li> +</ul> + </div> + <footer class="row"> + <div class="col-xs-12"> + + <p class="copyright">Copyright © 2015 The Apache Software Foundation, Licensed under the Apache License, Version 2.0 Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</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"> + MyNewt is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. + </small> + <img src="/img/egg-logo2.png" alt="Apache Incubator" title="Apache Incubator"> + </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
