User manual

Interfacing to external I
2
C slave devices
Technically, the correct name for this two-wire serial bus is Inter-IC bus or I
2
C, though it is somemes wrien as
I2C. Informaon on this popular two-wire hardware interface is readily available on the Web;
hp:/www.i2c-
bus.org/ is one starng point you could use. In parcular look for a document called “The I2C-bus and how to
use it (including specificaons).”
I
2
C uses two pins:
• SCL – Serial Clock Line
• SDA – Serial Data line (bidireconal)
Because both the value and direcon (input versus output) of the SCL and SDA pins must be rapidly and
precisely controlled, dedicated I
2
C support funcons have been added to SNAPpy.
NOTE– Parameters shown below in red are only available on selected hardware plaorms and/or
soware versions, beginning with release 2.5. See the SNAP Reference Manual for more details.
• i2cInit(enablePullups, SCL_pin, SDA_pin) – Prepare for I
2
C operaons (call this to set up for I
2
C)
• i2cWrite(byteStr, retries, ignoreFirstAck, endWithRestart) – Send data over I
2
C to another device
• i2cRead(byteStr, numToRead, retries, ignoreFirstAck) – Read data from device
• getI2cResult() – Check the result of the other funcons
These rounes are covered in more detail in the SNAP Reference Manual.
Using these rounes, your SNAPpy script can operate as an I
2
C bus master, and can interact with I
2
C slave
devices.
When performing I
2
C interacons, fixed IO pin assignments are usually used. For example, on an RF100 the
following IO pins are used:
• GPIO 17 is always used as the I
2
C SDA (data) line
• GPIO 18 is always used as the I
2
C SCL (clock) line
Excepons are the STM32W108xB plaorm, and (as of SNAP version 2.5) the ATmega128RFxx plaorms. On
these plaorms, the i2cInit() funcon takes two addional plaorms that specify which IO pins to use for I
2
C
clock (SCL) and data (SDA). (For backwards compability, you do not have to specify values for the SCL_pin and
SDA_pin parameters on ATmega128RFxx plaorms. If you do not, SNAP will default the pins to GPIO_18 and
GPIO_17, respecvely.)
NOTE – These pins are only dedicated if you are actually using the I
2
C funcons. If not, they remain
available for other funcons.
Refer to the plaorm-specific secon for your hardware (located at the back of the SNAP Reference Manual) for
the pin assignments for your plaorm.
Unlike CBUS and SPI, I
2
C does not use separate “chip select” lines. The inial data bytes of each I
2
C transacon
specify an “I
2
C address.” Only the addressed device will respond. So, no addional GPIO pins are needed.
The specifics of which bytes to send to a given I
2
C slave device (and what the response will look like) depend on
the I
2
C device itself. You will have to refer to the manufacturer’s data sheet for any given device to which you
wish to interface.
For examples of using the new SNAPpy I
2
C funcons to interface to external devices, look at the following scripts
that are bundled with Portal:
SNAP® Network Operang System 41