blob: fbb1625ceeb98b10c64ada8ebe73a7373eb20533 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Sensor Listener API &mdash; Apache Mynewt latest documentation</title>
<link rel="shortcut icon" href="../../../_static/mynewt-logo-only-newt32x32.png"/>
<link rel="stylesheet" href="../../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/sphinx_theme.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/bootstrap-3.0.3.min.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/v2.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/custom.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/restructuredtext.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/css/overrides.css" type="text/css" />
<link rel="index" title="Index"
href="../../../genindex.html"/>
<link rel="search" title="Search" href="../../../search.html"/>
<link rel="top" title="Apache Mynewt latest documentation" href="../../../index.html"/>
<link rel="up" title="Mynewt Sensor Framework Overview" href="sensor_framework.html"/>
<link rel="next" title="Sensor Notifier API" href="sensor_notifier_api.html"/>
<link rel="prev" title="Sensor Manager API" href="sensor_mgr_api.html"/>
<script src="../../../_static/js/modernizr.min.js"></script>
<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="not-front page-documentation" role="document" >
<div id="wrapper">
<div class="container">
<div id="banner" class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="../../../_static/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released April 4, 2024)
</div>
</div>
</div>
</div>
<header>
<nav id="navbar" class="navbar navbar-inverse" 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>
<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>
<a href="/about/">About</a>
</li>
<li>
<a href="/talks/">Talks</a>
</li>
<li class="active">
<a href="/documentation/">Documentation</a>
</li>
<li>
<a href="/download/">Download</a>
</li>
<li>
<a href="/community/">Community</a>
</li>
<li>
<a href="/events/">Events</a>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
</ul>
</div>
</div>
</nav>
</header>
<!-- STARTS MAIN CONTENT -->
<div id="main-content">
<div id="breadcrumb">
<div class="container">
<a href="/documentation/">Docs</a> /
<a href="../../os_user_guide.html">OS User Guide</a> /
<a href="sensor_framework.html">Mynewt Sensor Framework Overview</a> /
Sensor Listener API
<div class="sourcelink">
<a href="https://github.com/apache/mynewt-core/edit/master/docs/os/modules/sensor_framework/sensor_listener_api.rst" class="icon icon-github"
rel="nofollow"> Edit on GitHub</a>
</div>
</div>
</div>
<!-- STARTS CONTAINER -->
<div class="container">
<!-- STARTS .content -->
<div id="content" class="row">
<!-- STARTS .container-sidebar -->
<div class="container-sidebar col-xs-12 col-sm-3">
<div id="docSidebar" class="sticky-container">
<div role="search" class="sphinx-search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search documentation" class="search-documentation" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<!-- Note: only works when deployed -->
<select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest" selected>
Version: latest
</option>
<option value="/v1_12_0" >
Version: 1.12.0
</option>
<option value="/v1_11_0" >
Version: 1.11.0
</option>
<option value="/v1_10_0" >
Version: 1.10.0
</option>
<option value="/v1_9_0" selected="selected" >
Version: 1.9.0
</option>
<option value="/v1_8_0" >
Version: 1.8.0
</option>
<option value="/v1_7_0" >
Version: 1.7.0
</option>
<option value="/v1_6_0" >
Version: 1.6.0
</option>
<option value="/v1_5_0" >
Version: 1.5.0
</option>
<option value="/v1_4_0" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select>
<div class="region region-sidebar">
<div class="docs-menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../get_started/index.html">Setup &amp; Get Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../concepts.html">Concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../tutorials/tutorials.html">Tutorials</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../external_links.html">Third-party Resources</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../os_user_guide.html">OS User Guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../core_os/mynewt_os.html">Kernel</a></li>
<li class="toctree-l2"><a class="reference internal" href="../system_modules.html">System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../hal/hal.html">Hardware Abstraction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bootloader/bootloader.html">Secure Bootloader</a></li>
<li class="toctree-l2"><a class="reference internal" href="../split/split.html">Split Images</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../core_os/porting/port_os.html">Porting Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../baselibc.html">Baselibc</a></li>
<li class="toctree-l2"><a class="reference internal" href="../drivers/driver.html">Drivers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../devmgmt/newtmgr.html">Device Management with Newt Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mcumgr/mcumgr.html">Device Management with MCUmgr</a></li>
<li class="toctree-l2"><a class="reference internal" href="../imgmgr/imgmgr.html">Image Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sysinitconfig/sysinitconfig.html">Compile-Time Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sysinitdown/sysinitdown.html">System Initialization and Shutdown</a></li>
<li class="toctree-l2"><a class="reference internal" href="../extcmd/extcmd.html">Build-Time Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../fs/fs.html">File System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../fcb/fcb.html">Flash Circular Buffer</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="sensor_framework.html">Sensor Framework</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="sensor_api.html">Sensor API</a></li>
<li class="toctree-l3"><a class="reference internal" href="sensor_mgr_api.html">Sensor Manager API</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Sensor Listener API</a></li>
<li class="toctree-l3"><a class="reference internal" href="sensor_notifier_api.html">Sensor Notifier API</a></li>
<li class="toctree-l3"><a class="reference internal" href="sensor_oic.html">OIC Sensor API</a></li>
<li class="toctree-l3"><a class="reference internal" href="sensor_shell.html">Sensor Shell</a></li>
<li class="toctree-l3"><a class="reference internal" href="sensor_driver.html">Sensor Device Driver</a></li>
<li class="toctree-l3"><a class="reference internal" href="sensor_create.html">Creating and Configuring Sensor Devices</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../testutil/testutil.html">Test Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../json/json.html">JSON</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mfg/mfg.html">Manufacturing support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../bsp/index.html">Board support</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../network/index.html">BLE User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../newt/index.html">Newt Tool Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../newtmgr/index.html">Newt Manager Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../mynewt_faq/index.html">Mynewt FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../misc/index.html">Appendix</a></li>
</ul>
</div>
</div>
</div>
<!-- ENDS STICKY CONTAINER -->
</div>
<!-- ENDS .container-sidebar -->
<div class="col-xs-12 col-sm-9">
<div class="alert alert-warning">
<p>
Version 1.9.0 is not the most recent version of the
Apache Mynewt documentation. Click <a href="/latest">here</a> to
read the latest version.
</p>
</div>
<div class="">
<div class="rst-content">
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="sensor-listener-api">
<h1>Sensor Listener API<a class="headerlink" href="#sensor-listener-api" title="Permalink to this headline"></a></h1>
<p>The sensor listener API allows an application to register listeners for
sensors and get notified whenever sensor data are read from the sensor
devices. An application calls the <code class="docutils literal notranslate"><span class="pre">sensor_register_listener()</span></code>
function to register a listener that specifies the callback function and
the types of sensor data to listen for from a sensor device.</p>
<p>When the <code class="docutils literal notranslate"><span class="pre">sensor_read()</span></code> function defined in the <a class="reference internal" href="sensor_api.html"><span class="doc">sensor
API</span></a> is called to read
the sensor data for the specified sensor types from a sensor, the
<code class="docutils literal notranslate"><span class="pre">sensor_read()</span></code> function calls the listener callback, passing it the
sensor data that is read from the sensor.</p>
<p>An application calls the <code class="docutils literal notranslate"><span class="pre">sensor_unregister_listener()</span></code> function to
unregister a listener if it no longer needs notifications when data is
read from a sensor.</p>
<p>An application can use listeners in conjunction with the sensor manager
poller. An application can configure a polling interval for a sensor and
register a listener for the sensor types it wants to listen for from the
sensor. When the sensor manager poller reads the sensor data from the
sensor at each polling interval, the listener callback is called with
the sensor data passed to it.</p>
<p>An application can also use listeners for other purposes. For example,
an application that uses the OIC sensor server may want to register
listeners. The OIC sensor server handles all the OIC requests for the
sensor resources and an application does not know about the OIC
requests. An application can install a listener if it wants to know
about a request for a sensor resource or use the sensor data that the
OIC sensor server reads from the sensor.</p>
<div class="section" id="data-structures">
<h2>Data Structures<a class="headerlink" href="#data-structures" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">sensor_listener</span></code> data structure represents a listener. You
must initialize a listener structure with a bit mask of the sensor types
to listen for from a sensor, a callback function that is called when
sensor data is read for one of the sensor types, and an opaque argument
to pass to the callback before you call the
<code class="docutils literal notranslate"><span class="pre">sensor_register_listener()</span></code> function to register a listener.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">sensor_listener</span><span class="w"> </span><span class="p">{</span>
<span class="p">{</span>
<span class="w"> </span><span class="cm">/* The type of sensor data to listen for, this is interpreted as a</span>
<span class="cm"> * mask, and this listener is called for all sensor types on this</span>
<span class="cm"> * sensor that match the mask.</span>
<span class="cm"> */</span>
<span class="w"> </span><span class="n">sensor_type_t</span><span class="w"> </span><span class="n">sl_sensor_type</span><span class="p">;</span>
<span class="w"> </span><span class="cm">/* Sensor data handler function, called when has data */</span>
<span class="w"> </span><span class="n">sensor_data_func_t</span><span class="w"> </span><span class="n">sl_func</span><span class="p">;</span>
<span class="w"> </span><span class="cm">/* Argument for the sensor listener */</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">sl_arg</span><span class="p">;</span>
<span class="w"> </span><span class="cm">/* Next item in the sensor listener list. The head of this list is</span>
<span class="cm"> * contained within the sensor object.</span>
<span class="cm"> */</span>
<span class="w"> </span><span class="n">SLIST_ENTRY</span><span class="p">(</span><span class="n">sensor_listener</span><span class="p">)</span><span class="w"> </span><span class="n">sl_next</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
</div>
<div class="section" id="api">
<h2>API<a class="headerlink" href="#api" title="Permalink to this headline"></a></h2>
<dl class="c function">
<dt id="c.sensor_register_listener">
<span class="target" id="group___sensor_listener_a_p_i_1ga06663efb641ae3b2811edbc41717b2f8"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">sensor_register_listener</span></code><span class="sig-paren">(</span><em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="#c.sensor_register_listener" title="sensor"><span class="pre">sensor</span></a> <span class="pre">*</span><em><span class="pre">sensor</span></em>, <em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="sensor_api.html#c.sensor_listener" title="sensor_listener"><span class="pre">sensor_listener</span></a> <span class="pre">*</span><em><span class="pre">listener</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.sensor_register_listener" title="Permalink to this definition"></a><br /></dt>
<dd><p>Register a sensor listener. </p>
<p>This allows a calling application to receive callbacks for data from a given sensor object.</p>
<p>For more information on the type of callbacks available, see the documentation for the sensor listener structure.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">sensor</span></code>: The sensor to register a listener on </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">listener</span></code>: The listener to register onto the sensor</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.sensor_unregister_listener">
<span class="target" id="group___sensor_listener_a_p_i_1ga482580fc7387091e1aaf9454ed526d7c"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">sensor_unregister_listener</span></code><span class="sig-paren">(</span><em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="#c.sensor_unregister_listener" title="sensor"><span class="pre">sensor</span></a> <span class="pre">*</span><em><span class="pre">sensor</span></em>, <em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="sensor_api.html#c.sensor_listener" title="sensor_listener"><span class="pre">sensor_listener</span></a> <span class="pre">*</span><em><span class="pre">listener</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.sensor_unregister_listener" title="Permalink to this definition"></a><br /></dt>
<dd><p>Un-register a sensor listener. </p>
<p>This allows a calling application to clear callbacks for a given sensor object.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">sensor</span></code>: The sensor object </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">listener</span></code>: The listener to remove from the sensor listener list</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
<dl class="c function">
<dt id="c.sensor_register_err_func">
<span class="target" id="group___sensor_listener_a_p_i_1ga7e50688ddf7e84350d5fb7091a4b8693"></span><span class="pre">int</span> <code class="sig-name descname"><span class="pre">sensor_register_err_func</span></code><span class="sig-paren">(</span><em class="property"><span class="pre">struct</span></em> <a class="reference internal" href="#c.sensor_register_err_func" title="sensor"><span class="pre">sensor</span></a> <span class="pre">*</span><em><span class="pre">sensor</span></em>, <a class="reference internal" href="sensor_api.html#c.sensor_error_func_t" title="sensor_error_func_t"><span class="pre">sensor_error_func_t</span></a> <em><span class="pre">err_fn</span></em>, <span class="pre">void</span> <span class="pre">*</span><em><span class="pre">arg</span></em><span class="sig-paren">)</span><a class="headerlink" href="#c.sensor_register_err_func" title="Permalink to this definition"></a><br /></dt>
<dd><p>Register a sensor error callback. </p>
<p>The callback is executed when the sensor manager fails to read from the given sensor.</p>
<p><dl class="simple">
<dt><strong>Return</strong></dt><dd><p>0 on success, non-zero error code on failure. </p>
</dd>
<dt><strong>Parameters</strong></dt><dd><ul class="breatheparameterlist simple">
<li><p><code class="docutils literal notranslate"><span class="pre">sensor</span></code>: The sensor to register an error callback on. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">err_fn</span></code>: The function to execute when a read fails. </p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">arg</span></code>: Optional argument to pass to the callback.</p></li>
</ul>
</dd>
</dl>
</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="rst-footer-buttons row" role="navigation" aria-label="footer navigation">
<a href="sensor_notifier_api.html" class="btn btn-neutral float-right" title="Sensor Notifier API" accesskey="n">Next: Sensor Notifier API <span class="fa fa-arrow-circle-right"></span></a>
<a href="sensor_mgr_api.html" class="btn btn-neutral" title="Sensor Manager API" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: Sensor Manager API</a>
</div>
</div>
</div>
</div>
<!-- ENDS CONTENT SECTION -->
</div>
<!-- ENDS .content -->
</div>
</div>
<footer>
<div class="container">
<div 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="../../../_static/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="">
<img src="../../../_static/img/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
</div>
</div>
</footer>
</div>
<!-- ENDS #wrapper -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../../',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
LINK_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<script type="text/javascript" src="../../../_static/js/bootstrap-3.0.3.min.js"></script>
<script type="text/javascript" src="../../../_static/js/affix.js"></script>
<script type="text/javascript" src="../../../_static/js/main.js"></script>
</body>
</html>