I2COUT

Syntax: I2COUT Pin, SlaveID,{Address {\LowAddress},} [OutputData]

Function

Send data to 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 device's SDA pin) and, indirectly, the other required pin (for connection to the device's SCL pin). See explanation below. Both I/O pins will be toggled between output and input mode during the I2COUT command and both will be set to input mode by the end of the I2COUT 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 send data to. 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 send data to. This argument must be used along with the Address argument.
• OutputData is a list of variables, constants, expressions and formatters that tells I2COUT how to format outgoing data. I2COUTcan transmit individual or repeating bytes, convert values into decimal, hexadecimal or binary text representations, or transmit strings of bytes from variable arrays. These actions can be combined in any order in the OutputData 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 I2COUT command allows the BASIC Stamp to send data to an I²C device.

The following is an example of the I2COUT command:

  I2COUT 0, $A0, 5, [100]

This code will transmit a "write" command to an I²C device (connected to I/O pins 0 and 1), followed by an address of 5 and finally will transmit the number 100.

The example above will write a byte of data to location 5 of a 24LC16B EEPROM from Microchip. The figure below shows the proper wiring for this example to work. The SlaveID argument ($A0) is both the ID of the chip and the command to write to the chip; the 0 means write. The Address argument (5) is the EEPROM location to write to.

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

The I2COUT command's OutputData argument is similar to the DEBUG and SEROUT command's OutputData argument. This means data can be sent as literal text, ASCII character values, repetitive values, decimal, hexadecimal and binary translations and string data as in the examples below. (Assume the 24LC16B EEPROM is being used).

value   VAR     Byte

Setup:
  value = 65
 
Main:
  I2COUT 0, $A0, 0, [value]             ' send ASCII character "A"
  I2COUT 0, $A0, 0, [REP value\5]       ' send "A" five times, i.e., "AAAAA"
  I2COUT 0, $A0, 0, [DEC value]         ' send "6" and "5"
  I2COUT 0, $A0, 0, [HEX value]         ' send "4" and "1"
  I2COUT 0, $A0, 0, [BIN value]         ' send "1000001"
  END

The tables below list all the available conversion formatters and special formatters available to the I2COUT command. See the DEBUG and SEROUT commands for additional information and examples of their use.

1. Fixed-digit formatters like DEC4 will pad the number with leading 0s if necessary; ex: DEC4 65 sends 0065. If a number is larger than the specified number of digits, the leading digits will be dropped; ex: DEC4 56422 sends 6422.
2. Signed modifiers work under two's complement rules.

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) where the OutputData is to be written (the first location if more than one byte is written). Note that the Address argument is optional and may be left unspecified for devices that don't require an address parameter.

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 I2COUT command, this data byte is transmitted by the BASIC Stamp and received by the device. 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 I2COUT command is intended for output only, it actually overrides the "R/W" bit (bit 0) in the SlaveID argument. This is done to avoid device conflicts should the value be mistyped. Put simply, this means commands such as:

  I2COUT 0, $A0, 10, [0] 

...and:

  I2COUT 0, $A1, 10, [0]

...both transmit the same thing ($A0, then 10, then the data). Even though the I2COUT 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 I2COUT command does not support multiple I²C masters and the BASIC Stamp cannot operate as an I²C slave device.