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