Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v0_9_0 / os / modules / hal / hal_i2c / hal_i2c / index.html
blob: 8cbde50dcd5bd231d139d818736dd8bea50c0070 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../../img/favicon.ico">
<title>I2C - Apache Mynewt</title>
<link href="../../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../../../css/highlight.css">
<link href="../../../../../css/base.css" rel="stylesheet">
<link href="../../../../../css/custom.css" rel="stylesheet">
<link href="../../../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="I2C">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" selected="selected" >
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="../../../bootloader/bootloader/">Bootloader</a>
</li>
<li><a href="
../../../fs/fs/fs/
">File System</a>
</li>
<li ><a href="../../hal/">Hardware Abstraction Layer</a>
<ul>
<li >
<a href="../../hal_architecture/">Architecture</a>
</li>
<li><a href="
../../hal_api/
">API</a>
<ul>
<li >
<a href="../../hal_api/">Summary</a>
</li>
<li >
<a href="../../hal_adc/hal_adc/">ADC</a>
</li>
<li >
<a href="../../hal_cputime/hal_cpu_timer/">CPU timer</a>
</li>
<li >
<a href="../../hal_dac/hal_dac/">DAC</a>
</li>
<li><a href="
../../hal_flash/hal_flash/
">Flash memory</a>
</li>
<li >
<a href="../../hal_gpio/hal_gpio/">GPIO</a>
</li>
<li class="active">
<a href="./">I2C</a>
</li>
<li >
<a href="../../hal_pwm/hal_pwm/">PWM</a>
</li>
<li >
<a href="../../hal_spi/hal_spi/">SPI</a>
</li>
<li >
<a href="../../hal_system/hal_sys/">System</a>
</li>
<li >
<a href="../../hal_uart/hal_uart/">UART</a>
</li>
</ul>
</li>
<li >
<a href="../../hal_in_libraries/">Using HAL</a>
</li>
<li >
<a href="../../hal_creation/">Creating HAL</a>
</li>
</ul>
</li>
<li ><a href="../../../testutil/testutil/">Test Utilities</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="../../../stats/stats/">Stats</a>
</li>
<li ><a href="../../../logs/logs/">Logs</a>
</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>
<li >
<a href="../../../../../known_issues/">Known Issues</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">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; <a href="os/modules/hal/hal_api/">API</a></li>
<li>&raquo; <a href="os/modules/hal/hal/">Hardware Abstraction Layer</a></li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; I2C</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 0.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>
<h1 id="hal_i2c">hal_i2c</h1>
<p>The hardware independent interface to I2C Devices.</p>
<h3 id="description">Description</h3>
<p>An Inter-Integrated Circuit (I²C ] I-squared-C) bus is a multi-master,
multi-save serial interface used to connect components on a circuit board
and often peripherals devices located off the circuit board.</p>
<p>I2C is often though of as a 2-wire protocol because it uses two wires (SDA, SCL)
to send data between devices. </p>
<p>For a detailed description of I2C, see the <a href="https://en.wikipedia.org/wiki/I²C">I²C wikipedia page</a></p>
<h3 id="definition">Definition</h3>
<p><a href="https://github.com/apache/incubator-mynewt-larva/blob/master/hw/hal/include/hal/hal_i2c.h">hal_i2c.h</a></p>
<h3 id="hal_i2c-theory-of-operation">HAL_I2C Theory Of Operation</h3>
<p>An I²C transaction typically involves acquiring the bus, sending and/or receiving
data and release the bus. The bus acquisition portion is important because
the bus is typically multi-master so other devices may be trying to read/write
the same peripheral. </p>
<p>HAL_I2C implements a master interface to the I²C bus. Typical usage of the
interface would involve the following steps.</p>
<ol>
<li>initialize an I²C device using <code>hal_i2c_init</code></li>
<li>when you want to perform an I²C transaction:<ol>
<li>Issue the <code>hal_i2c_begin()</code> command. </li>
<li>Issue one or more <code>hal_i2c_read</code> and/or <code>hal_i2c_write</code> commands</li>
<li>Issue the <code>hal_i2c_end()</code> command.</li>
</ol>
</li>
</ol>
<p>An addition API was added called <code>hal_i2c_probe</code>. This command combines
<code>hal_i2c_begin()</code>, <code>hal_i2c_read</code>, and <code>hal_i2c_end()</code> to try to read 0-bytes
from a specific bus address. its intended to provide an easy way to probe
the bus for a specific device. NOTE: if the device is write-only, it will
not appear with this command.</p>
<h3 id="hal_i2c-data">HAL_I2C Data</h3>
<p>Data to read/write is passed to the hal_i2c APIs via the </p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code>struct hal_i2c_master_data {
uint8_t address; /* destination address */
uint16_t len; /* number of bytes to transmit or receive */
uint8_t *buffer; /* data buffer for transmit or receive */
};
</code></pre></div>
<p><code>buffer</code> is a pointer to the data to send. <code>len</code> is the number of bytes
to send over the bus. <code>address</code> is a 7-bit bus address of the device.</p>
<p>When I²C builds its address, it uses the 7-bit address plus a 1-bit R/W
(read/write) indicator to identify the device and direction of the
transaction. Thus when using this API, you should use a 7-bit address
in the data structure and ensure that address is a value between 0-127.</p>
<p>As an example, consider an I²C device address that looks like this:</p>
<table>
<thead>
<tr>
<th>B7</th>
<th>B6</th>
<th>B5</th>
<th>B4</th>
<th>B3</th>
<th>B2</th>
<th>B1</th>
<th>B0</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>1</td>
<td>1</td>
<td>0</td>
<td>R/W</td>
</tr>
<tr>
<td>MSB</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>LSB</td>
</tr>
</tbody>
</table>
<p>In the HAL_I2C API you would communicate with this device with address
<code>0b1000110</code>, which is hex 0x46 or decimal 70. The I²C drive would add the R/W bit
and transmit it as hex 0x8D or 0x8D depending whether it was a read or
write command.</p>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../../../js/highlight.pack.js"></script>
<script src="../../../../../js/base.js"></script>
<script src="../../../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>