I2CIN

Syntax: I2CIN Pin, SlaveID,{Address {\LowAddress},} [InputData]

Function

Receive data from a device using the I²C^® protocol.

• Pin is a variable/constant/expression (0 or 8) that specifies which I/O pins to use. I²C devices require two I/O pins to communicate. The Pin 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 I2CIN command and both will be set to input mode by the end of the I2CIN command.
• SlaveID is a variable/constant/expression (0 - 255) indicating the unique ID of the I²C device.
• Address is a variable/constant/expression (0 - 255) indicating the desired address within the I²C device to receive data from. The Address argument may be used with the optional LowAddress 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 Address parameter).
• LowAddress is a variable/constant/expression (0 - 255) indicating the low-byte of the word-sized address within the I²C device to receive data from. This argument must be used along with the Address argument.
• InputData is a list of variables and modifiers that tells I2CIN what to do with incoming data. I2CIN 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 InputData list.

Quick Facts

Explanation

The I²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²C devices. The I2CINcommand allows the BASIC Stamp to receive data from an I²C device.

The following is an example of the I2CIN command:

result  VAR     Byte

Main:
  I2CIN 0, $A1, 0, [result]
  STOP

This code will transmit a "read" command to an I²C device (connected to I/O pins 0 and 1) and then will receive one byte and store it in the variable result. Though it may seem strange, the I2CIN 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²C device what information it would like to receive. The exact information transmitted ($A1, 0) depends on the I²C device that is being used.

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 SlaveID argument ($A1) is both the ID of the chip and the command to read from the chip; the 1 means read. The Address argument (0) is the EEPROM location to read from. Note that the I2CIN command will make up to eight attempts to connect to the addressed device. If the device does not properly respond, the I2CIN command will timeout and the InputData will remain unchanged.

Note: The 4.7 kΩ resisters are required for the I2CINcommand to function properly.

The I2CIN command's InputData argument is similar to the SERIN command's InputData 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).

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

The tables below list all the available conversion formatters and special formatters available to the I2CIN command. See the SERIN command for additional information and examples of their use.

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.
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.
3. The hexadecimal formatters are not case-sensitive; "a" through "f" means the same as "A" through "F".
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.

The I²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 SlaveID, 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 SlaveID format:

The second byte, immediately following the SlaveID, is the Address. It indicates the 8-bit address (within the device) containing the data you would like to receive.

Some devices require more than eights bits of address. For this case, the optional LowAddress argument can be used for the low-byte of the required address. When using the LowAddress argument, the Address 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 LowAddress argument (8 * 256 + 2 = 2050).

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 I2CINcommand, 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²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.

Every I²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 I2CIN command so that you need not be concerned with them. The general I²C transmission format is shown below.

Since the I2CIN command is intended for input only, it actually overrides the "R/W" bit (bit 0) in the SlaveID argument. This is done so that it can use the I²C protocol's "Combined Format" for receiving data. Put simply, this means a command such as:

  I2CIN 0, $A1, 10, [result]

...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 I2CIN command really doesn't care what the value of the SlaveID's LSB is, it is suggested that you still set it appropriately for clarity.

Also note that the I2CIN command does not support multiple I²C masters and the BASIC Stamp cannot operate as an I²C slave device.