X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=decoders%2Fi2c%2F__init__.py;h=5216e01602a4498c031532ef71ffa6438b6f3e24;hb=271acd3bde96474c7ed5f822d470f555af8e7d93;hp=9e7856e0884e47c5f3386b57ead4424870000afe;hpb=64c29e28e0efa184319f7831b3eca18c7f73f7d0;p=libsigrokdecode.git

diff --git a/decoders/i2c/__init__.py b/decoders/i2c/__init__.py
index 9e7856e..5216e01 100644
--- a/decoders/i2c/__init__.py
+++ b/decoders/i2c/__init__.py
@@ -18,5 +18,66 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+I2C protocol decoder.
+
+The Inter-Integrated Circuit (I2C) bus is a bidirectional, multi-master
+bus using two signals (SCL = serial clock line, SDA = serial data line).
+
+There can be many devices on the same bus. Each device can potentially be
+master or slave (and that can change during runtime). Both slave and master
+can potentially play the transmitter or receiver role (this can also
+change at runtime).
+
+Possible maximum data rates:
+ - Standard mode: 100 kbit/s
+ - Fast mode: 400 kbit/s
+ - Fast-mode Plus: 1 Mbit/s
+ - High-speed mode: 3.4 Mbit/s
+
+START condition (S): SDA = falling, SCL = high
+Repeated START condition (Sr): same as S
+Data bit sampling: SCL = rising
+STOP condition (P): SDA = rising, SCL = high
+
+All data bytes on SDA are exactly 8 bits long (transmitted MSB-first).
+Each byte has to be followed by a 9th ACK/NACK bit. If that bit is low,
+that indicates an ACK, if it's high that indicates a NACK.
+
+After the first START condition, a master sends the device address of the
+slave it wants to talk to. Slave addresses are 7 bits long (MSB-first).
+After those 7 bits, a data direction bit is sent. If the bit is low that
+indicates a WRITE operation, if it's high that indicates a READ operation.
+
+Later an optional 10bit slave addressing scheme was added.
+
+Documentation:
+http://www.nxp.com/acrobat/literature/9398/39340011.pdf (v2.1 spec)
+http://www.nxp.com/acrobat/usermanuals/UM10204_3.pdf (v3 spec)
+http://en.wikipedia.org/wiki/I2C
+
+Protocol output format:
+
+I2C packet:
+[<cmd>, <data>]
+
+<cmd> is one of:
+  - 'START' (START condition)
+  - 'START REPEAT' (Repeated START condition)
+  - 'ADDRESS READ' (Slave address, read)
+  - 'ADDRESS WRITE' (Slave address, write)
+  - 'DATA READ' (Data, read)
+  - 'DATA WRITE' (Data, write)
+  - 'STOP' (STOP condition)
+  - 'ACK' (ACK bit)
+  - 'NACK' (NACK bit)
+
+<data> is the data or address byte associated with the 'ADDRESS*' and 'DATA*'
+command. Slave addresses do not include bit 0 (the READ/WRITE indication bit).
+For example, a slave address field could be 0x51 (instead of 0xa2).
+For 'START', 'START REPEAT', 'STOP', 'ACK', and 'NACK' <data> is None.
+
+'''
+
 from .i2c import *