366 lines
21 KiB
HTML
366 lines
21 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="94" MadCap:lastWidth="853" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
|
|
<head><title>I2CIN</title>
|
|
<link href="../../SkinSupport/MadCap.css" rel="stylesheet" />
|
|
<link href="../../Resources/Stylesheets/BSE_Help.css" rel="stylesheet" />
|
|
<script src="../../SkinSupport/MadCapAll.js" type="text/javascript">
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<h1 class="code">I2CIN</h1>
|
|
<div class="ImagePlusCaption">
|
|
<div class="Col2">
|
|
<p>
|
|
<img src="../../graphics/pgm_icon2p.gif" border="0" alt="BS2p icon" title="BS2p icon" />
|
|
<img src="../../graphics/pgm_icon2pe.gif" border="0" alt="BS2pe icon" title="BS2pe icon" />
|
|
<img src="../../graphics/pgm_icon2px.gif" border="0" alt="BS2px icon" title="BS2px icon" />
|
|
</p>
|
|
</div>
|
|
<p style="text-align: right;"><a href="../ExampleTopics/I2cInOutEx.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">I2CIN / I2COUT Example</a>
|
|
</p>
|
|
<p> </p>
|
|
</div>
|
|
<p class="clear"> </p>
|
|
<p> </p>
|
|
<p class="PlainText">Syntax: <span class="keyword_in_text">I2CIN</span> <![CDATA[ ]]><i>Pin</i>,<i> SlaveID</i>,<i><![CDATA[ ]]></i>{<i>Address </i>{\<i>LowAddress</i>},} [<i>InputData</i>]</p>
|
|
<h2>Function</h2>
|
|
<p class="PlainText">Receive data from a device using the I<sup>2</sup>C<sup>®</sup> protocol.
|
|
|
|
</p>
|
|
<ul>
|
|
<li value="1"><b><i>Pin</i></b> is a variable/constant/expression (0 or 8) that specifies
|
|
which I/O pins to use. I<sup>2</sup>C devices require two I/O pins to communicate.
|
|
The <i>Pin</i> argument serves a double purpose; specifying the first pin (for
|
|
connection to the devices's SDA pin) and, indirectly, the other required pin (for
|
|
connection to the devices's SCL pin). See explanation below. Both I/O pins will
|
|
be toggled between output and input mode during the <span class="keyword_in_text">I2CIN</span> command and both
|
|
will be set to input mode by the end of the <span class="keyword_in_text">I2CIN</span> command.</li>
|
|
<li value="2"><b><i>SlaveID</i></b> is a variable/constant/expression (0 - 255) indicating
|
|
the unique ID of the I<sup>2</sup>C device.</li>
|
|
<li value="3"><b><i>Address</i></b> is a variable/constant/expression (0 - 255) indicating
|
|
the desired address within the I<sup>2</sup>C device to receive data from. The
|
|
<i>Address</i> argument may be used with the optional <i>LowAddress</i> argument
|
|
to indicate a word-sized address value. Note that some devices like the
|
|
PCF8574 do not require an internal address, so this parameter is optional (BS2p
|
|
firmware 1.3 or later is required to omit the <i>Address</i> parameter).</li>
|
|
<li value="4"><b><i>LowAddress</i></b> is a variable/constant/expression (0 - 255)
|
|
indicating the low-byte of the word-sized address within the I<sup>2</sup>C
|
|
device to receive data from. This argument must be used along with the
|
|
<i>Address</i> argument.</li>
|
|
<li value="5"><b><i>InputData</i></b> is a list of variables and modifiers that tells
|
|
<span class="keyword_in_text">I2CIN</span> what to do with incoming data. <span class="keyword_in_text">I2CIN</span> can store data in a
|
|
variable or array, interpret numeric text (decimal, binary, or hex) and store
|
|
the corresponding value in a variable, wait for a fixed or variable sequence
|
|
of bytes, or ignore a specified number of bytes. These actions can be combined
|
|
in any order in the <i>InputData</i> list.</li>
|
|
</ul>
|
|
<h2>Quick Facts</h2>
|
|
<table width="100%" cellpadding="4" cellspacing="0" border="1">
|
|
<tr bgcolor="#CFCFCF">
|
|
<td align="center"> </td>
|
|
<td align="center" colspan="2">BS2p, BS2pe, and BS2px</td>
|
|
</tr>
|
|
<tr>
|
|
<td width="250" align="center" bgcolor="#CFCFCF">Value of <i>Pin</i></td>
|
|
<td width="40%" align="center">0</td>
|
|
<td width="40%" align="center">8</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" bgcolor="#CFCFCF">I/O Pin Arrangement</td>
|
|
<td>0: Serial Data (SDA) pin<br></br>1: Serial Clock (SCL) pin</td>
|
|
<td>8: Serial Data (SDA) pin<br></br>9: Serial Clock (SCL) pin</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" bgcolor="#CFCFCF">Transmission Rate</td>
|
|
<td colspan="2">Approximately 81 kBits/sec (BS2p), 45 kBits/sec (BS2pe),
|
|
83 kBits/sec (BS2px) -- not including overhead.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" bgcolor="#CFCFCF">Special Notes</td>
|
|
<td colspan="2">Both the SDA and SCL pins must have 4.7 kΩ
|
|
pull-up resisters.<br /> The I2CIN command does not allow for multiple masters.<br /> The BASIC Stamp cannot operate as an I<sup>2</sup>C slave device.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" bgcolor="#CFCFCF">Related Commands</td>
|
|
<td align="center" colspan="2">
|
|
<p colspan="2" align="center"><a href="I2COUT.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">I2COUT</a>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<h2>Explanation</h2>
|
|
<p class="PlainText">The I<sup>2</sup>C protocol is a form of synchronous serial communication
|
|
developed by Philips Semiconductor. It only requires two I/O pins and both
|
|
pins can be shared between multiple I<sup>2</sup>C devices. The <span class="keyword_in_text">I2CIN</span>command allows the BASIC Stamp to receive data from an I<sup>2</sup>C device.</p>
|
|
<p class="PlainText">The following is an example of the <span class="keyword_in_text">I2CIN</span> command:</p><pre class="BScode" xml:space="preserve">
|
|
result VAR Byte
|
|
|
|
Main:
|
|
I2CIN 0, $A1, 0, [result]
|
|
STOP
|
|
</pre>
|
|
<p class="PlainText">This code will transmit a "read" command to an I<sup>2</sup>C device (connected
|
|
to I/O pins 0 and 1) and then will receive one byte and store it in the variable
|
|
<i>result</i>. Though it may seem strange, the <span class="keyword_in_text">I2CIN</span> command first transmits
|
|
some data and then receives data. It must first transmit information (ID, read/write
|
|
and address) in order to tell the I<sup>2</sup>C device what information it would
|
|
like to receive. The exact information transmitted ($A1, 0) depends on the
|
|
I<sup>2</sup>C device that is being used.</p>
|
|
<p class="PlainText">The example above will read a byte of data from location 0 of a 24LC16B EEPROM
|
|
from Microchip. The figure below shows the proper wiring for this example to work.
|
|
The <i>SlaveID</i> argument ($A1) is both the ID of the chip and the command to
|
|
read from the chip; the 1 means read. The <i>Address</i> argument (0) is the EEPROM
|
|
location to read from. Note that the <span class="keyword_in_text">I2CIN</span> command will make up to eight
|
|
attempts to connect to the addressed device. If the device does not properly
|
|
respond, the <span class="keyword_in_text">I2CIN</span> command will timeout and the <i>InputData</i> will
|
|
remain unchanged.</p>
|
|
<p class="PlainText"><b>Note</b>: The 4.7 kΩ resisters are required for the <span class="keyword_in_text">I2CIN</span>command to function properly.</p>
|
|
<center>
|
|
<img src="../../graphics/24lc16_sch.gif" width="262" height="234" border="0">
|
|
</img>
|
|
</center>
|
|
<p class="PlainText">The <span class="keyword_in_text">I2CIN</span> command's <i>InputData</i> argument is similar to the
|
|
<span class="keyword_in_text">SERIN</span> command's <i>InputData</i> argument. This means data can be received
|
|
as ASCII character values, decimal, hexadecimal and binary translations and string
|
|
data as in the examples below. (Assume the 24LC16B EEPROM is used and it has the
|
|
string, "Value: 3A:101" stored, starting at location 0).</p><pre class="BScode" xml:space="preserve">
|
|
value VAR Byte(13)
|
|
|
|
Main:
|
|
I2CIN 0, $A1, 0, [value] ' receive ASCII code for "V"
|
|
I2CIN 0, $A1, 0, [DEC value] ' receive number 3
|
|
I2CIN 0, $A1, 0, [HEX value] ' receive number $3A
|
|
I2CIN 0, $A1, 0, [BIN value] ' receive number %101
|
|
I2CIN 0, $A1, 0, [STR value\13] ' receive string "Value: 3A:101"
|
|
STOP
|
|
</pre>
|
|
<p class="PlainText">The tables below list all the available conversion formatters and special
|
|
formatters available to the <span class="keyword_in_text">I2CIN</span> command. See the <a href="SERIN.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">SERIN</a> command for additional information and examples
|
|
of their use.</p>
|
|
<table width="100%" cellpadding="4" cellspacing="0" border="1">
|
|
<tr bgcolor="#CFCFCF" align="center" valign="top">
|
|
<td width="15%">Conversion Formatter</td>
|
|
<td width="45%">Type of Number</td>
|
|
<td width="30%">Numeric Characters Accepted</td>
|
|
<td width="10%">Notes</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>DEC{1..5}</td>
|
|
<td>Decimal, optionally limited to 1 - 5 digits</td>
|
|
<td>0 through 9</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>SDEC{1..5}</td>
|
|
<td>Signed decimal, optionally limited to 1 - 5 digits</td>
|
|
<td>-, 0 through 9</td>
|
|
<td>1,2</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>HEX{1..4}</td>
|
|
<td>Hexadecimal, optionally limited to 1 - 4 digits</td>
|
|
<td>0 through 9, A through F</td>
|
|
<td>1,3</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>SHEX{1..4}</td>
|
|
<td>Signed hexadecimal, optionally limited to 1 - 4 digits </td>
|
|
<td>-, 0 through 9, A through F</td>
|
|
<td>1,2,3</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>IHEX{1..4}</td>
|
|
<td>Indicated hexadecimal, optionally limited to 1 - 4 digits</td>
|
|
<td>$, 0 through 9, A through F</td>
|
|
<td>1,3,4</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>ISHEX{1..4}</td>
|
|
<td>Signed, indicated hexadecimal, optionally limited to 1 - 4 digits</td>
|
|
<td>-, $, 0 through 9, A through F</td>
|
|
<td>1,2,3,4</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>BIN{1..16}</td>
|
|
<td>Binary, optionally limited to 1 - 16 digits</td>
|
|
<td>0, 1</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>SBIN{1..16}</td>
|
|
<td>Signed binary, optionally limited to 1 - 16 digits</td>
|
|
<td>-, 0, 1</td>
|
|
<td>1,2</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>IBIN{1..16}</td>
|
|
<td>Indicated binary, optionally limited to 1 - 16 digits</td>
|
|
<td>%, 0, 1</td>
|
|
<td>1,4</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>ISBIN{1..16}</td>
|
|
<td>Signed, indicated binary, optionally limited to 1 - 16 digits</td>
|
|
<td>-, %, 0, 1</td>
|
|
<td>1,2,4</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>NUM</td>
|
|
<td>Generic numeric input; hex or binary number must be indicated</td>
|
|
<td>$, %, 0 through 9, A through F</td>
|
|
<td>1,3,4</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>SNUM</td>
|
|
<td>Similar to NUM with value treated as signed with range -32768 to +32767</td>
|
|
<td>-, $, %, 0 through 9, A through F</td>
|
|
<td>1,2,3,4</td>
|
|
</tr>
|
|
</table>
|
|
<ol>
|
|
<li value="1">All numeric conversions will continue to accept new data until receiving
|
|
either the specified number of digits (ex: three digits for DEC3) or a non-numeric
|
|
character.</li>
|
|
<li value="2">To be recognized as part of a number, the minus sign (-) must immediately
|
|
precede a numeric character. The minus sign character occurring in non-numeric
|
|
text is ignored and any character (including a space) between a minus and a number
|
|
causes the minus to be ignored.</li>
|
|
<li value="3">The hexadecimal formatters are not case-sensitive; "a" through "f" means
|
|
the same as "A" through "F".</li>
|
|
<li value="4">Indicated hexadecimal and binary formatters ignore all characters, even valid
|
|
numerics, until they receive the appropriate prefix ($ for hexadecimal, % for
|
|
binary). The indicated formatters can differentiate between text and hexadecimal
|
|
(ex: ABC would be interpreted by HEX as a number but IHEX would ignore it unless
|
|
expressed as $ABC). Likewise, the binary version can distinguish the decimal
|
|
number 10 from the binary number %10. A prefix occurring in non-numeric text
|
|
is ignored, and any character (including a space) between a prefix and a number
|
|
causes the prefix to be ignored. Indicated, signed formatters require that the
|
|
minus sign come before the prefix, as in -$1B45.</li>
|
|
</ol>
|
|
<p> </p>
|
|
<table width="100%" cellpadding="4" cellspacing="0" border="1">
|
|
<tr bgcolor="#CFCFCF" align="center" valign="top">
|
|
<td width="20%">Special Formatter</td>
|
|
<td width="80%">Action</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">STR ByteArray \L {\E}</td>
|
|
<td>Input a character string of length L into an array. If specified, an end
|
|
character E causes the string input to end before reaching length L. Remaining
|
|
bytes are filled with 0s (zeros).</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">WAITSTR ByteArray {\L}</td>
|
|
<td>Wait for a sequence of bytes matching a string stored in an array variable,
|
|
optionally limited to L characters. If the optional L argument is left off,
|
|
the end of the array-string must be marked by a byte containing a zero (0).</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">SKIP Length</td>
|
|
<td>Ignore Length bytes of characters.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">SPSTR Length</td>
|
|
<td>Buffer Length bytes (up to 126) of serial characters to Scratchpad RAM,
|
|
starting at location 0. Use <a href="GET.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">GET</a> to retrieve the characters.</td>
|
|
</tr>
|
|
</table>
|
|
<p> </p>
|
|
<p class="PlainText">The I<sup>2</sup>C protocol has a well-defined standard for the information
|
|
passed at the start of each transmission. First of all, any information sent must
|
|
be transmitted in units of one byte (8-bits). The first byte, we call the
|
|
<i>SlaveID</i>, is an 8-bit pattern whose upper 7-bits contain the unique ID of
|
|
the device you wish to communicate with. The lowest bit indicates whether this
|
|
is a write operation (0) or a read operation (1). Here is the <i>SlaveID</i> <![CDATA[ ]]>format:</p>
|
|
<center>
|
|
<table cellpadding="4" cellspacing="0" border="1">
|
|
<tr align="center" bgcolor="#CFCFCF">
|
|
<td width="35">7</td>
|
|
<td width="35">6</td>
|
|
<td width="35">5</td>
|
|
<td width="35">4</td>
|
|
<td width="35">3</td>
|
|
<td width="35">2</td>
|
|
<td width="35">1</td>
|
|
<td width="35">0</td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>A<sub>6</sub></td>
|
|
<td>A<sub>5</sub></td>
|
|
<td>A<sub>4</sub></td>
|
|
<td>A<sub>3</sub></td>
|
|
<td>A<sub>2</sub></td>
|
|
<td>A<sub>1</sub></td>
|
|
<td>A<sub>0</sub></td>
|
|
<td>R/W</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
<p> </p>
|
|
<p class="PlainText">The second byte, immediately following the <i>SlaveID</i>, is the <i>Address</i>.
|
|
It indicates the 8-bit address (within the device) containing the data you would
|
|
like to receive.</p>
|
|
<p class="PlainText">Some devices require more than eights bits of address. For this case, the optional
|
|
<i>LowAddress</i> argument can be used for the low-byte of the required address.
|
|
When using the <i>LowAddress</i> argument, the <i>Address</i> argument is effectively
|
|
the high-byte of the address value. For example, if the entire address value is
|
|
2050, use 8 for the Address argument and 2 for the <i>LowAddress</i> argument
|
|
(8 * 256 + 2 = 2050).</p>
|
|
<p class="PlainText">Following the last address byte is the first byte of data. This data byte may
|
|
be transmitted or received by the BASIC Stamp. In the case of the <span class="keyword_in_text">I2CIN</span>command, this data byte is transmitted by the device and received by the BASIC
|
|
Stamp. Additionally, multiple data bytes can follow the address, depending on the
|
|
I<sup>2</sup>C device. Note that every device has different limitations regarding
|
|
how may contiguous bytes they can receive or transmit in one session. Be aware of
|
|
these device limitations and program accordingly.</p>
|
|
<p class="PlainText">Every I<sup>2</sup>C transmission session begins with a Start Condition and
|
|
ends with a Stop Condition. Additionally, immediately after every byte is
|
|
transmitted, an extra clock cycle is used to send or receive an acknowledgment
|
|
signal (ACK). All of these operations are automatically taken care of by the
|
|
<span class="keyword_in_text">I2CIN</span> command so that you need not be concerned with them. The general
|
|
I<sup>2</sup>C transmission format is shown below.</p>
|
|
<center>
|
|
<img src="../../graphics/i2c_packet.gif" width="531" height="245" border="0">
|
|
</img>
|
|
</center>
|
|
<p class="PlainText">Since the <span class="keyword_in_text">I2CIN</span> command is intended for input only, it actually overrides
|
|
the "R/W" bit (bit 0) in the <i>SlaveID</i> argument. This is done so that it can
|
|
use the I<sup>2</sup>C protocol's "Combined Format" for receiving data. Put simply,
|
|
this means a command such as:
|
|
|
|
</p><pre class="BScode" xml:space="preserve"> I2CIN 0, $A1, 10, [result]</pre>
|
|
<p class="PlainText">...actually transmits $A0, then 10, then $A1 and then it reads the data back from the device. The $A0 means "write", the 10 is the address to write to and, finally, the $A1 indicates a change of direction; to "read" the location, instead. Even though the <span class="keyword_in_text">I2CIN</span> command really doesn't care what the value of the <i>SlaveID</i>'s LSB is, it is suggested that you still set it appropriately for clarity.
|
|
</p>
|
|
<p class="PlainText">Also note that the <span class="keyword_in_text">I2CIN</span> command does not support multiple I<sup>2</sup>C
|
|
masters and the BASIC Stamp cannot operate as an I<sup>2</sup>C slave device.</p>
|
|
<div class="Col2">
|
|
<div class="MasterFoot">
|
|
<p MadCap:conditions="BSEconditions.BSEWebHelp (Primary)-INCLUDE"><a href="../../HomeTopics/HomePage.htm">Go to Welcome page</a>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div class="Col2">
|
|
<div class="MasterFoot">
|
|
<p style="text-align: right;"><span class="ContactInfoProjectName">BASIC Stamp Help</span> <![CDATA[ ]]><span class="ContactInfoVersion#">Version 2.5.4</span> <![CDATA[ ]]></p>
|
|
<p style="text-align: right;">Copyright © <span class="ContactInfoCompanyName">Parallax Inc.</span></p>
|
|
<p style="text-align: right;"><span class="SystemShortDate">8/8/2012</span>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">/* <![CDATA[ */
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-285614-1']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
/* ]]> */</script>
|
|
<script type="text/javascript" src="../../SkinSupport/MadCapBodyEnd.js">
|
|
</script>
|
|
</body>
|
|
</html> |