Excamera I2CDriver User manual

I2CDriver User Guide 1
Last updated on May 31, 2019
Contents
1 Overview 3
1.1 Features ................................ 3
2 Getting Started 4
3 Software installation 5
3.1 Windows ............................... 5
3.2 Linux .................................. 7
3.3 MacOS ................................ 7
4 APIs 9
4.1 Python 2 and 3 ............................ 9
4.1.1 Reference ........................... 11
4.2 C/C++ ................................. 14
5 Using I2CDriver 15
5.1 The display .............................. 15
5.2 The GUI ................................ 16
5.3 The command-line tool i2ccl .................... 16
5.4 Monitor mode ............................. 17
5.5 Capture mode ............................ 18
5.5.1 Command line ........................ 18
5.5.2 GUI .............................. 19
©2019 Excamera Labs

I2CDriver User Guide 2
6 Examples 20
6.1 Color Compass ............................ 20
6.2 Egg Timer ............................... 21
6.3 Take-a-ticket ............................. 21
7 Technical notes 22
7.1 Port names .............................. 22
7.2 Decreasing the USB latency timer ................. 22
7.3 Temperature sensor ......................... 23
7.4 Raw protocol ............................. 24
7.5 Pull-up resistors ........................... 26
7.6 Specifications ............................. 28
8 Support information 29
Index 30
©2019 Excamera Labs

I2CDriver User Guide 3
1 Overview
I2CDriver is an easy-to-use, open source tool for controlling I2C devices. It
works with Windows, Mac, and Linux, and has a built-in color screen that shows
a live dashboard of all the I2C activity. It uses a standard FTDI USB serial chip
to talk to the PC, so no special drivers need to be installed. The board includes
a separate 3.3 V supply with voltage and current monitoring.
1.1 Features
•Live display: shows you exactly what it’s doing all the time
•Supports all I2C features: 7- and 10-bit I2C addressing, clock stretching,
bus arbitration, and sustained I2C transfers at 400 and 100 kHz
•I2C pullups: programmable I2C pullup resistors, with automatic tuning
•USB voltage monitoring: USB line voltage monitor to detect supply
problems, to 0.01 V
•Target power monitoring: target device high-side current measurement,
to 5 mA
•Three I2C ports: three identical I2C ports, each with power and I2C sig-
nals
•Jumpers: three sets of high-quality color coded 100mm jumpers included
•3.3 V output: output levels are 3.3 V, all are 5 V tolerant
•Sturdy componentry: uses an FTDI USB serial adapter, and Silicon
Labs automotive-grade EFM8 controller
•Open hardware: the design, firmware and all tools are under BSD li-
cense
•Flexible control: GUI, command-line, C/C++, and Python 2/3 host soft-
ware provided for Windows, Mac, and Linux
©2019 Excamera Labs

I2CDriver User Guide 4
2 Getting Started
When you first connect I2CDriver to the USB port, the display blinks white for a
moment then shows something like this:
Connect the three sets of colored hookup wires as shown, following the same
sequence as on the colored label:
GND black
VCC red
SDA blue
SCL yellow
The top two signals carry power, the VCC line supplies 3.3 volts.
Across the top of the display I2CDriver continuously measures the USB bus
voltage and the current output.
©2019 Excamera Labs

I2CDriver User Guide 5
3 Software installation
The source for all the I2CDriver software is the repository. Available are:
• a Windows/Mac/Linux GUI
• a Windows/Mac/Linux command-line
• Python 2 and 3 bindings
• Windows/Mac/Linux C/C++ bindings
Installation of the GUI and command-line utilities varies by platform.
3.1 Windows
This installer contains the GUI and command-line utilities.
The GUI shortcut is installed on the desktop:
launching it brings up the control window:
©2019 Excamera Labs

I2CDriver User Guide 6
If there is only one serial device, the I2CDriver device should be automatically
selected. If there is more than one device, select its COM port from the pull-
down menu at the top. Once connected, you can select a connected I2C device
and write and read data.
The command line utility i2ccl is also installed. For example to display status
information:
c:\>"c:\Program Files\Excamera Labs\I2CDriver\i2ccl.exe" COM6 i
uptime 8991 4.957 V 30 mA 25.8 C SDA=1 SCL=1 speed=100 kHz
©2019 Excamera Labs

I2CDriver User Guide 7
See below for more information on the command-line syntax.
3.2 Linux
The GUI is included in the i2cdriver Python package, compatible with both
Python 2 and 3. To install it, open a shell prompt and do:
sudo pip install i2cdriver
Then run it with
i2cgui.py
For the command-line tool, clone the repository, then do:
cd i2cdriver/c
make -f linux/Makefile
sudo make -f linux/Makefile install
i2ccl /dev/ttyUSB0 i
and you should see something like:
uptime 1651 4.971 V 0 mA 21.2 C SDA=1 SCL=1 speed=100 kHz
3.3 MacOS
The GUI is included in the i2cdriver Python package, compatible with both
Python 2 and 3. To install it, open a shell prompt and do:
sudo pip install i2cdriver
Then run it with
i2cgui.py
©2019 Excamera Labs

I2CDriver User Guide 8
For the command-line tool, clone the repository , then do:
cd i2cdriver/c
make -f linux/Makefile
sudo make -f linux/Makefile install
i2ccl /dev/cu.usbserial-DO00QS8D i
(substituting your actual I2CDriver’s ID for DO00QS8D) and you should see some-
thing like:
uptime 1651 4.971 V 5 mA 21.2 C SDA=1 SCL=1 speed=100 kHz
Note that the port to use is /dev/cu.usbserial-XXXXXXXX, as explained here.
©2019 Excamera Labs

I2CDriver User Guide 9
4 APIs
4.1 Python 2 and 3
The I2CDriver bindings can be installed with pip like this:
pip install i2cdriver
then from Python you can read an LM75B temperature sensor with:
>>> import i2cdriver
>>> i2c = i2cdriver.I2CDriver("/dev/ttyUSB0")
>>> d=i2cdriver.EDS.Temp(i2c)
>>> d.read()
17.875
>>> d.read()
18.0
You can print a bus scan with:
>>> i2c.scan()
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- 1C -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
48 -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
68 -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
[28, 72, 104]
The Python GUI (which uses wxPython) can be run with:
python i2cgui.py
©2019 Excamera Labs

I2CDriver User Guide 10
which depending on your distribution looks something like this:
There are more examples in the samples folder in the repository.
The module has extensive help strings:
>>> help(i2cdriver)
displays the API documentation.
©2019 Excamera Labs

I2CDriver User Guide 11
4.1.1 Reference
class i2cdriver.I2CDriver(port=’/dev/ttyUSB0’,reset=True)
A connected I2CDriver.
Variables
•product – product code e.g. i2cdriver1
•serial – serial string of I2CDriver
•uptime – time since I2CDriver boot, in seconds
•voltage – USB voltage, in V
•current – current used by attached device, in mA
•temp – temperature, in degrees C
•scl – state of SCL
•sda – state of SDA
•speed – current device speed in KHz (100 or 400)
•mode – IO mode (I2C or bitbang)
•pullups – programmable pullup enable pins
•ccitt crc – CCITT-16 CRC of all transmitted and re-
ceived bytes
init (port=’/dev/ttyUSB0’,reset=True)
Connect to a hardware i2cdriver.
Parameters
•port (str ) – The USB port to connect to
•reset (bool ) – Issue an I2C bus reset on connection
setspeed(s)
Set the I2C bus speed.
Parameters s(int ) – speed in KHz, either 100 or 400
setpullups(s)
Set the I2CDriver pullup resistors
Parameters s– 6-bit pullup mask
©2019 Excamera Labs

I2CDriver User Guide 12
scan(silent=False)
Performs an I2C bus scan. If silent is False, prints a map of devices.
Returns a list of the device addresses.
>>> i2c.scan()
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- 1C -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
48 -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
68 -- -- -- -- -- -- --
-- -- -- -- -- -- -- --
[28, 72, 104]
reset()
Send an I2C bus reset
start(dev,rw)
Start an I2C transaction
Parameters
•dev – 7-bit I2C device address
•rw – read (1) or write (0)
To write bytes [0x12,0x34] to device 0x75:
>>> i2c.start(0x75,0)
>>> i2c.write([0x12,034])
(continues on next page)
©2019 Excamera Labs

I2CDriver User Guide 13
(continued from previous page)
>>> i2c.stop()
read(l)
Read l bytes from the I2C device, and NAK the last byte
write(bb)
Write bytes to the selected I2C device
Parameters bb – sequence to write
stop()
stop the i2c transaction
regrd(dev,reg,fmt=’B’)
Read a register from a device.
Parameters
•dev – 7-bit I2C device address
•reg – register address 0-255
•fmt –struct.unpack() format string for the register
contents
If device 0x75 has a 16-bit register 102, it can be read with:
>>> i2c.regrd(0x75,102,">H")
4999
regwr(dev,reg,*vv)
Write a devices register.
Parameters
•dev – 7-bit I2C device address
•reg – register address 0-255
•vv – sequence of values to write
To set device 0x34 byte register 7 to 0xA1:
©2019 Excamera Labs

I2CDriver User Guide 14
>>> i2c.regwr(0x34,7, [0xa1])
If device 0x75 has a big-endian 16-bit register 102 you can set it to
4999 with:
>>> i2c.regwr(0x75,102, struct.pack(">H",4999))
monitor(s)
Enter or leave monitor mode
Parameters s–True to enter monitor mode, False to leave
getstatus()
Update all status variables
4.2 C/C++
I2CDriver is contained in a single source file with a single header. Both are in
this subdirectory. Usage follows the Python API and is fairly self-explanatory.
©2019 Excamera Labs

I2CDriver User Guide 15
5 Using I2CDriver
5.1 The display
The main display on the screen has three sections. The top section is a heat-
map showing all 112 legal I2C addresses. Devices that are currently active
are white. Inactive devices fade to yellow, purple and finally blue. The middle
section is a symbolic interpretation of current I2C traffic. Details on this are
below. The bottom two lines show a representation of the SDA (blue) and SCL
(yellow) signals.
The symbolic decode section shows I2C transactions as they happen. Start
and stop are shown as Sand Psymbols. After a Ssymbol the address
byte is shown, with a right arrow (write) or left arrow (read). There are gray
lines connecting the address byte to its heat-map indicator. Following this is a
series of data bytes. Each byte is shown in hex, with either a green dot (ACK)
©2019 Excamera Labs

I2CDriver User Guide 16
or red dot (NACK).
So for example the above sequence is showing
• Start, write to address 45
• Write byte 7A
• Repeated Start, read from address 45
• Read byte 00
• Read byte A2
• Stop
The above sequence is very typical for reading registers from an I2C Device.
Note that the final NACK (red dot) is not an error condition, but the standard
way of handling the last byte of read transaction.
5.2 The GUI
(TBD: describe how each button in the GUI works)
5.3 The command-line tool i2ccl
i2ccl is the same on all platforms.
The first parameter to the command is the serial port, which depends on your
operating system. All following parameters are control commands. These are:
©2019 Excamera Labs

I2CDriver User Guide 17
idisplay status information (uptime, voltage, current, temperature)
ddevice scan
wdev bytes write bytes to I2C device dev
psend a STOP
rdev N read Nbytes from I2C device dev, then STOP
menter I2C bus monitor mode
For example the command:
i2ccl /dev/ttyUSB0 r 0x48 2
reads two bytes from the I2C device at address 0x48. So with an LM75B tem-
perature sensor connected you might see output like:
0x16,0x20
which indicates a temperature of about 22 ◦C.
I2C devices usually have multiple registers. To read register 3 of the LM75B,
you first write the register address 3, then read two bytes as before:
i2ccl /dev/ttyUSB0 w 0x48 3 r 0x48 2
0x50,0x00
Which shows that register 3 has the value 0x5000.
5.4 Monitor mode
In monitor mode, the I2CDriver does not write any data to the I2C bus. Instead
it monitors bus traffic and draws it on the display. This makes it an ideal tool for
troubleshooting and debugging I2C hardware and software.
To show that it is in monitor mode, the I2CDriver changes the character in the
top-left of the display from Dto M.
There are several ways of entering monitor mode:
• use the command-line tool:
©2019 Excamera Labs

I2CDriver User Guide 18
i2ccl m
• from the GUI check the ”Monitor” box
• from Python issue:
i2c.monitor(True)
and to exit:
i2c.monitor(False)
• connect a terminal to the I2CDriver (at 1000000 8N1) and type the mchar-
acter, then type any character to exit monitor mode
5.5 Capture mode
In capture mode, the I2CDriver does not write any data to the I2C bus. Instead
it monitors bus traffic and transmits it via USB for recording on the PC.
5.5.1 Command line
There is a Python sample program that can be used to capture traffic on the
command-line at capture.py.
Running it with the I2CDriver address as an argument puts the I2CDriver into
capture mode: the character in the top-left of the display changes from Dto C.
$python samples/capture.py /dev/ttyUSB0
Now capturing traffic to
standard output (human-readable)
log.csv
Hit CTRL-C to leave capture mode
<START 0x14 WRITE ACK>
<WRITE 0x02 ACK>
<WRITE 0x22 ACK>
<STOP>
^C
©2019 Excamera Labs

I2CDriver User Guide 19
Capture finished
When run, it displays any traffic on standard output. It also writes a traffic
summary to log.csv which can be examined and processed by any tool that
can accept CSV files.
5.5.2 GUI
The GUI also supports capture to CSV file.
Clicking “Capture mode” starts the capture and prompts for a destination CSV
file. The character in the top-left of the display changes from Dto C. Capture
continues until you click “Capture mode” again.
©2019 Excamera Labs

I2CDriver User Guide 20
6 Examples
The Python samples directory contains short examples of using all Electric
Dollar Store I2C modules:
Module Function Sample
DIG2 2-digit 7-seg display EDS-DIG2.py
LED RGB LED EDS-LED.py
POT potentiometer EDS-POT.py
BEEP Piezo beeper EDS-BEEP.py
REMOTE IR remote receiver EDS-REMOTE.py
EPROM CAT24C512 64 Kbyte EPROM EDS-EPROM.py
MAGNET LIS3MDL magnetometer EDS-MAGNET.py
TEMP LM75B temperature sensor EDS-TEMP.py
ACCEL RT3000C Accelerometer EDS-ACCEL.py
CLOCK HT1382 real-time clock EDS-CLOCK.py
All demos and applications are run the same way, supplying the I2CDriver on
the command-line. For example:
python EDS-LED.py COM16
Also included are some small applications which demonstrate combinations of
modules.
6.1 Color Compass
Source code: EDS-color-compass.py
Color compass uses MAGNET and LED, reading the current magnetic field
direction and rendering it as a color on the LED. As you twist the module, the
color changes. For example there is a particular direction for pure red, as well
as all other colors. The code reads the magnetic field direction, scales the
values to 0-255, and sets the LED color.
©2019 Excamera Labs