I2CDriver User Guide 1 Last updated on May 31, 2019 Contents 1 Overview 1.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 2 Getting Started 4 3 Software installation 3.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 MacOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 7 7 4 APIs 9 4.1 Python 2 and 3 . . . . . . . . . . . . . . . . . . . . . .
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 7.1 Port names . . . . . . . . . . . . . 7.2 Decreasing the USB latency timer 7.3 Temperature sensor . . . . . . . . 7.4 Raw protocol . . . . . . . . . . . . 7.5 Pull-up resistors . . . . . . . . . . 7.6 Specifications .
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.
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.
I2CDriver User Guide 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.
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 pulldown 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.
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.
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 something 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.
I2CDriver User Guide 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.
I2CDriver User Guide 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.
I2CDriver User Guide 4.1.1 Reference class i2cdriver.I2CDriver(port=’/dev/ttyUSB0’, reset=True) A connected I2CDriver. Variables • product – product code e.g.
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.
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.
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.
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 heatmap 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.
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.
I2CDriver User Guide 17 i display status information (uptime, voltage, current, temperature) d device scan w dev bytes write bytes to I2C device dev p send a STOP r dev N read N bytes from I2C device dev, then STOP m enter 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 temperature sensor connected you might see output like: 0x16,0x20 which indicates a temperature of about 22 ◦ C.
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 m character, 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.
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 D to C. Capture continues until you click “Capture mode” again.
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.
I2CDriver User Guide 21 6.2 Egg Timer Source code: EDS-egg-timer.py The demo uses POT, DIG2 and BEEPER to make a simple kitchen egg timer. Twisting the POT sets a countdown time in seconds, and after it’s released the ticker starts counting. When it reaches “00” it flashes and beeps. 6.3 Take-a-ticket Source code: EDS-take-a-ticket.py This demo runs a take-a-ticket display for a store or deli counter, using REMOTE, DIG2 and BEEP modules.
I2CDriver User Guide 22 7 Technical notes 7.1 Port names The serial port that I2CDriver appears at depends on your operating system. On Windows, it appears as COM1, COM2, COM3 etc. You can use the Device Manager or the MODE command to display the available ports. This article describes how to set a device to a fixed port. On Linux, it appears as /dev/ttyUSB0, 1, 2 etc. The actual number depends on the order that devices were added.
I2CDriver User Guide 23 7.3 Temperature sensor The temperature sensor is located in the on-board EFM8 microcontroller. It is calibrated at manufacture to within 2 ◦ C.
I2CDriver User Guide 24 7.4 Raw protocol I2CDriver uses a serial protocol to send and receive I2C commands. Connect to the I2CDriver at 1M baud, 8 bits, no parity, 1 stop bit (1000000 8N1). Because many I2CDriver commands are ASCII, you can control it interactively from any terminal application that can connect at 1M baud. For example typing u and s toggles the CS line and ? displays the status info.
I2CDriver User Guide 25 The host should send: s 0x90 Start write to device 45 0xc0 0x7a Write 1 byte s 0x91 Start read from device 45 0x80 Read 1 byte p Stop The status response is always 80 characters, space padded. For example:: [i2cdriver1 DO01JUOO 000000061 4.971 000 23.
I2CDriver User Guide 26 7.5 Pull-up resistors I2CDriver has 6 programmable pull-up resistors, 3 each for SDA and SCL. 6 control bits each enable or disable a pull-up resistor. These bits are: bit resistor 0 2.2K to SDA 1 4.3K to SDA 2 4.7K to SDA 3 2.2K to SCL 4 4.3K to SCL 5 4.7K to SCL At boot the two 4.7K resistors are enabled. By setting combinations of parallel resistors, a range of pull-up strengths can be achieved: 4.7K 4.3K 2.2K pull-up strength 0 0 0 0 (i.e.
I2CDriver User Guide 27 In Python, the pullups are controlled by the setpullups() method, and the state can be read from the pullups variable. Both are 6-bit values as above. The GUI has a control for the pull-up resistors. It sets the same pull-up strength for both SDA and SCL.
I2CDriver User Guide 28 7.6 Specifications DC characteristics min typ max units Voltage accuracy 0.01 V Current accuracy 5 mA Temperature accuracy ◦ ±2 C SDA,SCL low voltage high voltage 2.7 Output current Current consumption 0.6 V 5.8 V 470 mA 25 mA AC characteristics min I2C speed typ 100 max units 400 Kbps 150 ppm 31.
I2CDriver User Guide 8 Support information Technical and product support is available at support@i2cdriver.com I2CDriver is built and maintained by Excamera Labs.
Index init () (i2cdriver.I2CDriver method), 11 Monitor mode, 17 monitor() (i2cdriver.I2CDriver method), 14 bus scan, 9, 17 protocol, 24 Capture mode, 18 pull-ups, 26 capture.py, 18 read() (i2cdriver.I2CDriver method), CRC, 25 13 display, 15 register read, 17 drivers regrd() (i2cdriver.I2CDriver C/C++, 14 Linux, 7 method), 13 regwr() (i2cdriver.I2CDriver Mac, 7 method), 13 Python, 9 Remote control, 21 Windows, 5 reset() (i2cdriver.I2CDriver method), 12 Example Beeper, 21 scan() (i2cdriver.
I2CDriver User Guide uptime, 28 USB latency, 22 ports, 22 write() (i2cdriver.
