I²C¶

Technically, the correct name for this two-wire serial bus is Inter-IC bus or I²C, though it is sometimes written as I2C. I²C uses two pins:

SCL – Serial Clock Line
SDA – Serial Data line (bidirectional)

Because both the value and direction (input versus output) of the SCL and SDA pins must be rapidly and precisely controlled, dedicated I²C support functions have been added to SNAPpy. Using the following functions, your SNAPpy script can operate as an I²C bus master and can interact with I²C slave devices:

i2cInit() – Prepare IO for I²C operations
i2cWrite() – Send data over I²C to another device
i2cRead() – Read data from I²C device
getI2cResult() – Check the result of the other I²C functions

To allow these functions to be as fast as possible, the IO pins used for I²C SDA and SCL are fixed. The IO pins that are reserved for I²C varies by platform, so refer to SNAP Modules. These pins are not dedicated for I²C, so if you are not using the I²C functions, you may use the reserved pins for other functions.

Unlike CBUS and SPI, I²C does not use separate Chip Select pins. The initial data bytes of each I²C transaction specify an I²C address. Only the addressed device will respond, so no additional GPIO pins are needed.

The specifics of which bytes to send to a given I²C slave device (and what the response will look like) depend on the I²C device itself. You will have to refer to the manufacturer’s data sheet for any given device to which you wish to interface.

I²C Restart¶

Usually, I²C read and write commands begin with a hardware handshake sequence referred to as an “I²C Start” and end with a mirror-image hardware handshake sequence referred to as an “I²C Stop”. The original implementations of i2cRead() and i2cWrite() automatically generate these handshake sequences for you.

A typical use case looks something like this:

bytes_to_write   = <sets up for the next i2cRead()>
addressing_bytes = <address that begins the actual read>

i2cWrite(bytes_to_write, retries, ignoreFirstAck)
info = i2cRead(addressing_bytes, retries, ignoreFirstAck)

This use case works with a wide variety of I²C chips. However, various manufacturers have introduced new parts that won’t work with the above code snippet. This is because the “I²C Stop” sequence generated at the end of the i2cWrite() function resets the I²C chip’s internal address registers, thus undoing the setup that was accomplished by writing bytes_to_write. Instead of an “I²C Start, I²C Stop, I²C Start, I²C Stop” sequence, these devices require an “I²C Start, I²C Restart, I²C Stop” sequence.

Note

To determine if your particular I²C device requires an “I²C Restart”, refer to the manufacturer’s datasheet for the I²C part. Some manufacturer data sheets refer to the “I²C Restart” as a “Repeated Start.”

Beginning in SNAP 2.5, an optional endWithRestart argument was introduced to the i2cWrite() function which allows you to interact with these devices natively. Just change the above example to include the new parameter:

i2cWrite(bytes_to_write, retries, ignoreFirstAck, True)   # Passing True for endWithRestart
info = i2cRead(addressing_bytes, retries, ignoreFirstAck)

Prior to SNAP 2.5, the only way to interface to devices having this “I²C Restart” requirement was to implement a custom version of the i2cWrite() functionality in your own SNAPpy script, using the lower-level SNAPpy setPinDir(), readPin(), and writePin() functions.

I2C¶

I2C Restart¶

I²C¶

I²C Restart¶