i2csvg – Generate svg pictures of I2C commands from text description

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).

Textual Source Format

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:

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:

Lines of the input may consist of a single flag+value per line or a comma separated list of flag+value pairs.

Hexdump source format

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.

Output file format

The output file generated depends on the options specified.

The example commands assume $REPO_TOP is set to the toplevel directory of the repo.

Setup

The i2csvg tool does not depend on any other packages.

Examples using i2csvg.py

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

Example use in Debugging

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