This repository has been archived on 2024-09-22. You can view files and clone it, but cannot push or open issues or pull requests.
pbi-ide/help/BasicStampHelp/Content/LanguageTopics/Commands/I2CIN.htm

366 lines
21 KiB
HTML
Raw Normal View History

<?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>&#160;</p>
</div>
<p class="clear">&#160;</p>
<p>&#160;</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">&#160;</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>&#160;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>&#160;</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>&#160;</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>&#160;</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 ©&#160;<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>