i2csvg is a Python tool to read I2C transactions from a text file and generate svg pictures of them. It also supports SMBus transactions and the smbus subdirectory contains examples of how to use the tool to generate all the transactions from section 6.5 of the SMBus Specification 3.0
Two source representations are supported. The first is a more readable format and describes transactions in text. The second is a hex-dump of values written to the I2C FIFO. In either format a line starting with a # is taken as a comment and a line staring with a T will be used to generate a title in the output.
To assist in parsing debug output the tool can be given a prefix. Only lines with the prefix will be processed (after removal of the prefix).
The textual description includes the flags and value written to the I2C host interface FIFO to make the transaction. The flags and data may be separated by whitespace. The flags are letters representing each of the 5 control bits written to the FIFO:
| Flag | Use |
|---|---|
| S | Send a start signal before the data |
| P | Send a stop signal after the data |
| R | Read transaction (data value indicates how many bytes to read) |
| C | With R, allows read to continue by ACK of the last byte read |
| N | NACK OK, do not raise an error on a NACK |
| . | A dot is guaranteed to be ignored in the input, it is included in the text output format to help readability |
The flags may occur in any order (but not be repeated) and additional characters will be ignored. In general other than dot (.) other characters should be avoided since they may be used by future versions of the tool!
The value may be an integer (binary, octal, decimal and hex supported) or one of the special values that change how the output is drawn:
| Value | Use |
|---|---|
| A0 | Address with direction bit set to 0 (write) |
| A1 | Address with direction bit set to 1 (read) |
| A2 | Address in SMBus Quick command with direction bit used for data |
| M | Multi-byte transaction, drawn as D1, D2 ... DN (like SMBus) |
| ‘tag’ | In single quotes: Tag for the value that is drawn in output |
Lines of the input may consist of a single flag+value per line or a comma separated list of flag+value pairs.
In the hexdump source format tool processes the raw 13-bit data that is written to the I2C FIFO. This is normally in hex (preceded with 0x) but the tool will accept binary, octal or decimal. Lines of input may consist of a single hex value, multiple values separated by commas (and optionally whitespace) or multiple values separated by whitespace.
The output file generated depends on the options specified.
| Type | Options |
|---|---|
.svg | If multiple output files are generated or debug/text not selected |
.html | If debug/text is selected and svg is generated |
.txt | If debug/test is selected and no svg is generated (--nosvg) |
The example commands assume $REPO_TOP is set to the toplevel directory of the repo.
The i2csvg tool does not depend on any other packages.
The i2csvg/examples directory contains some example I2C files. For simple examples text can be piped in to the tool using echo.
A simple I2C write consists of a Start with Address and direction bit of zero, and a single data byte (4 in the example) with a Stop.
The baseline tool will generate an svg file (which can be viewed in a browser) that includes the diagrammatic form of the transaction and a line with the comma separated structured text form.
$ cd $REPO_TOP/util $ echo "SA0, P4" | ./i2csvg.py > out.svg
The text version (which is just the input with more structured formatting) can be viewed in the terminal by suppressing the svg output. This output will always have the five flags in order and five characters in the flags field (including a . if the flag is not set):
$ cd $REPO_TOP/util $ echo "SA0, P4" | ./i2csvg.py --text --nosvg S.... A0 .P... 0x4
The debug version is intended for tool development:
$ cd $REPO_TOP/util $ echo "SA0, P4" | ./i2csvg.py --debug --nosvg I2cOp(read=False, rcont=False, start=True, stop=False, nackok=False, mvalue=False, adr=True, size=10, fbyte=0, tag=None) I2cOp(read=False, rcont=False, start=False, stop=True, nackok=False, mvalue=False, adr=False, size=10, fbyte=4, tag=None)
If svg generation is not suppressed then the text or debug output and the svg are generated in an HTML file.
$ cd $REPO_TOP/util $ echo "SA0, P4" | ./i2csvg.py --text > out.html
The smbus directory contains files with each of the commands listed in section 6.5 of the SMBus 3.0 specification. These can be used to generate an HTML file with all the transactions expanded.
$ cd $REPO_TOP/util $ ./i2csvg.py i2csvg/smbus/*.txt > out.html
Alternatively, these can all be converted to individual svg files (for example for inclusion in documents) with the --multiout command. The output filename matches the input filename with the extension replaced with .svg. Note that if the --text or --debug flags are given then the output will be HTML and the extension will be .html.
$ cd $REPO_TOP/util $ ls i2csvg/smbus 01-Quick.txt 04-WriteWord.txt 07-BlockRead.txt 10-Write32.txt 02-SendByte.txt 05-ReadByte.txt 07-BlockWrite.txt 11-Read32.txt 03-ReceiveByte.txt 05-ReadWord.txt 08-BlockWrRdPCall.txt 12-Write64.txt 04-WriteByte.txt 06-ProcessCall.txt 09-HostNotify.txt 13-Read64.txt $ ./i2csvg.py --multiout i2csvg/smbus/*.txt $ ls i2csvg/smbus 01-Quick.svg 04-WriteWord.svg 07-BlockRead.svg 10-Write32.svg 01-Quick.txt 04-WriteWord.txt 07-BlockRead.txt 10-Write32.txt 02-SendByte.svg 05-ReadByte.svg 07-BlockWrite.svg 11-Read32.svg 02-SendByte.txt 05-ReadByte.txt 07-BlockWrite.txt 11-Read32.txt 03-ReceiveByte.svg 05-ReadWord.svg 08-BlockWrRdPCall.svg 12-Write64.svg 03-ReceiveByte.txt 05-ReadWord.txt 08-BlockWrRdPCall.txt 12-Write64.txt 04-WriteByte.svg 06-ProcessCall.svg 09-HostNotify.svg 13-Read64.svg 04-WriteByte.txt 06-ProcessCall.txt 09-HostNotify.txt 13-Read64.txt
The examples directory contains example output from a microcontroller using the I2C interface. Mixed in to the other debug output are lines produced when writes are done to the I2C FIFO. These lines are prefixed by I2CF: Prior to a transaction a title line starting with T is produced. This output can be processed to give a simple text representation:
$ cd $REPO_TOP/util $ ./i2csvg.py --nosvg --text --fifodata --prefix=I2CF: i2csvg/examples/traceout.txt T read sensor S.... 0x40 .PR.. 0x1 T fix value S.... 0x41 ..... 0x22 .P... 0x33
Or the output can be converted into pictures for display in a browser:
$ cd $REPO_TOP/util $ ./i2csvg.py --text --fifodata --prefix=I2CF: i2csvg/examples/traceout.txt > out.html