Excamera I2CDriver User manual

I2CDriver and I2CMini User Guide 1
Last updated on February 10, 2021
Contents
1 Overview 3
1.1 Features ................................ 3
2 Getting Started 4
3 Software installation 6
3.1 Windows ............................... 6
3.2 Linux .................................. 8
3.3 MacOS ................................ 9
4 APIs 10
4.1 Python 2 and 3 ............................ 10
4.2 C/C++ ................................. 12
5 Using I2CDriver 13
5.1 The display .............................. 13
5.2 The GUI ................................ 15
5.3 The command-line tool i2ccl .................... 19
5.4 Monitor mode ............................. 20
5.5 Capture mode ............................ 20
5.5.1 Command line ........................ 21
5.5.2 GUI .............................. 21
6 Examples 23
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 2
6.1 Color Compass ............................ 23
6.2 Egg Timer ............................... 24
6.3 Take-a-ticket ............................. 24
7 Technical notes 25
7.1 Port names .............................. 25
7.2 Decreasing the USB latency timer ................. 25
7.3 Temperature sensor ......................... 26
7.4 Raw protocol ............................. 27
7.4.1 ?: transmit status info .................... 28
7.4.2 e: echo byte ......................... 29
7.4.3 1: set speed to 100 KHz ................... 29
7.4.4 4: set speed to 400 KHz ................... 30
7.4.5 s: START ........................... 30
7.4.6 0x80-bf : read 1-64 bytes, NACK the final byte ...... 30
7.4.7 0xc0-ff : write 1-64 bytes .................. 31
7.4.8 a: read N bytes, ACK every byte .............. 31
7.4.9 p: send STOP ........................ 31
7.4.10 x: reset I2C bus ........................ 32
7.4.11 r: register read ........................ 32
7.4.12 d: scan devices, return 112 status bytes .......... 33
7.4.13 m: enter monitor mode .................... 33
7.4.14 c: enter capture mode .................... 33
7.4.15 b: enter bitbang mode .................... 33
7.4.16 i: leave bitmang, return to I2C mode. ........... 34
7.4.17 u: set pullup control lines .................. 34
7.4.18 : reboot ............................ 34
7.5 Pull-up resistors ........................... 34
7.6 Bitbang mode ............................. 35
7.7 Capture mode ............................ 37
7.8 Specifications ............................. 39
8 Troubleshooting 40
9 Support information 40
Index 41
©2021 Excamera Labs

I2CDriver and I2CMini 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.
I2CMini is a reduced-size version of I2CDriver suitable for use in embedded
devices. It is 100% compatible with I2CDriver but lacks a display, current or
voltage monitoring. In every other respect it behaves identically to I2CDriver.
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
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 4
2 Getting Started
When you first connect I2CDriver to the USB port, the display blinks white for a
moment then displays the initial status screen:
Connect the three sets of colored hookup wires as shown, following the same
sequence as on the colored label:
GND black signal ground
VCC red 3.3 V supply
SDA blue I2C data
SCL yellow I2C clock
Across the top of the display I2CDriver continuously shows the USB bus voltage
and the current output.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 5
I2CMini also has a micro USB connector. Its Qwiic connector is polarized; it at-
taches as shown. The color coding for the signals is the same as for I2CDriver.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 6
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:
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 7
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, and added to the Windows
PATH. For example to display status information:
c:\>i2ccl COM6 i
uptime 8991 4.957 V 30 mA 25.8 C SDA=1 SCL=1 speed=100 kHz
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 8
The COM port can be found using the MODE command to list connected ports.
You can use the Device Manager or the MODE command to display the available
ports.
The Windows convention for COM10 and above is that they must be prefixed by
\\.\, for example:
c:\>i2ccl \\.\COM11 i
See (section 7.1 ”Port names”) for details on how to fix a device to a port
number permanently.
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
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 9
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
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.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 10
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
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 11
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, and the Python module is documented in full
at
https://i2cdriver.readthedocs.io/en/latest/index.html.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 12
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.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 13
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. Addresses that are currently active
are white. Inactive addresses 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). The gray lines
connect 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) or red dot
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 14
(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.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 15
5.2 The GUI
The GUI is a straightforward way of interacting with I2C devices. For example,
here I2CDriver is connected to some I2C peripherals: an LM75B temperature
sensor and two 7-segment display modules.
Starting the GUI and connecting to the I2CDriver on COM16 shows the temper-
ature sensor at address 48 and the two display modules at addresses 14 and
15.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 16
Selecting address 48 and clicking on read reads a single byte from the temper-
ature sensor. The I2CDriver display shows the traffic immediately.
This LM75B sensor reports temperature in Celcius, so the hex byte 1A repre-
sents a temperature of 26 ◦C.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 17
Selecting the left-hand display (address 14) and entering the hex values 01 19
then clicking on write sets the first LED to the digits 19.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 18
Similarly selecting address 15 and entering the hex values 01 85 then clicking
on write sets the second LED to 85.
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 19
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:
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 write to a device register, use
the wcommand. Using the same device at address 0x48, writing the two byte
value 0x25,0x26 to register 2 is:
i2ccl /dev/ttyUSB0 w 0x48 2,0x25,0x26 p
To read register 3 of the LM75B, first write the register address 3, then read
two bytes as above:
i2ccl /dev/ttyUSB0 w 0x48 3 r 0x48 2
0x50,0x00
©2021 Excamera Labs

I2CDriver and I2CMini User Guide 20
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:
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.
©2021 Excamera Labs