moved a bunch of garbage (things that have nothing to do in root) to _trash
This commit is contained in:
parent
d094982b2c
commit
3226ed29ec
2610 changed files with 0 additions and 0 deletions
191
_trash/lib/python3.11/site-packages/pyftdi/doc/api/i2c.rst
Normal file
191
_trash/lib/python3.11/site-packages/pyftdi/doc/api/i2c.rst
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
|
||||
.. include:: ../defs.rst
|
||||
|
||||
:mod:`i2c` - |I2C| API
|
||||
----------------------
|
||||
|
||||
.. module :: pyftdi.i2c
|
||||
|
||||
|
||||
Quickstart
|
||||
~~~~~~~~~~
|
||||
|
||||
Example: communication with an |I2C| GPIO expander
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Instantiate an I2C controller
|
||||
i2c = I2cController()
|
||||
|
||||
# Configure the first interface (IF/1) of the FTDI device as an I2C master
|
||||
i2c.configure('ftdi://ftdi:2232h/1')
|
||||
|
||||
# Get a port to an I2C slave device
|
||||
slave = i2c.get_port(0x21)
|
||||
|
||||
# Send one byte, then receive one byte
|
||||
slave.exchange([0x04], 1)
|
||||
|
||||
# Write a register to the I2C slave
|
||||
slave.write_to(0x06, b'\x00')
|
||||
|
||||
# Read a register from the I2C slave
|
||||
slave.read_from(0x00, 1)
|
||||
|
||||
Example: mastering the |I2C| bus with a complex transaction
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from time import sleep
|
||||
|
||||
port = I2cController().get_port(0x56)
|
||||
|
||||
# emit a START sequence is read address, but read no data and keep the bus
|
||||
# busy
|
||||
port.read(0, relax=False)
|
||||
|
||||
# wait for ~1ms
|
||||
sleep(0.001)
|
||||
|
||||
# write 4 bytes, without neither emitting the start or stop sequence
|
||||
port.write(b'\x00\x01', relax=False, start=False)
|
||||
|
||||
# read 4 bytes, without emitting the start sequence, and release the bus
|
||||
port.read(4, start=False)
|
||||
|
||||
See also pyi2cflash_ module and ``tests/i2c.py``, which provide more detailed
|
||||
examples on how to use the |I2C| API.
|
||||
|
||||
|
||||
Classes
|
||||
~~~~~~~
|
||||
|
||||
.. autoclass :: I2cPort
|
||||
:members:
|
||||
|
||||
.. autoclass :: I2cGpioPort
|
||||
:members:
|
||||
|
||||
.. autoclass :: I2cController
|
||||
:members:
|
||||
|
||||
|
||||
Exceptions
|
||||
~~~~~~~~~~
|
||||
|
||||
.. autoexception :: I2cIOError
|
||||
.. autoexception :: I2cNackError
|
||||
.. autoexception:: I2cTimeoutError
|
||||
|
||||
|
||||
GPIOs
|
||||
~~~~~
|
||||
|
||||
See :doc:`../gpio` for details
|
||||
|
||||
Tests
|
||||
~~~~~
|
||||
|
||||
|I2C| sample tests expect:
|
||||
* TCA9555 device on slave address 0x21
|
||||
* ADXL345 device on slave address 0x53
|
||||
|
||||
Checkout a fresh copy from PyFtdi_ github repository.
|
||||
|
||||
See :doc:`../pinout` for FTDI wiring.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# optional: specify an alternative FTDI device
|
||||
export FTDI_DEVICE=ftdi://ftdi:2232h/1
|
||||
# optional: increase log level
|
||||
export FTDI_LOGLEVEL=DEBUG
|
||||
# be sure to connect the appropriate I2C slaves to the FTDI I2C bus and run
|
||||
PYTHONPATH=. python3 pyftdi/tests/i2c.py
|
||||
|
||||
|
||||
.. _i2c_limitations:
|
||||
|
||||
Caveats
|
||||
~~~~~~~
|
||||
|
||||
Open-collector bus
|
||||
``````````````````
|
||||
|
||||
|I2C| uses only two bidirectional open collector (or open drain) lines, pulled
|
||||
up with resistors. These resistors are also required on an |I2C| bus when an
|
||||
FTDI master is used.
|
||||
|
||||
However, most FTDI devices do not use open collector outputs. Some software
|
||||
tricks are used to fake open collector mode when possible, for example to
|
||||
sample for slave ACK/NACK, but most communication (R/W, addressing, data)
|
||||
cannot use open collector mode. This means that most FTDI devices source
|
||||
current to the SCL and SDA lines. FTDI HW is able to cope with conflicting
|
||||
signalling, where FTDI HW forces a line the high logical level while a slave
|
||||
forces it to the low logical level, and limits the sourced current. You may
|
||||
want to check your schematics if the slave is not able to handle 4 .. 16 mA
|
||||
input current in SCL and SDA, for example. The maximal source current depends
|
||||
on the FTDI device and the attached EEPROM configuration which may be used to
|
||||
limit further down the sourced current.
|
||||
|
||||
Fortunately, FT232H device is fitted with real open collector outputs, and
|
||||
PyFtdi always enable this mode on SCL and SDA lines when a FT232H device is
|
||||
used.
|
||||
|
||||
Other FTDI devices such as FT2232H, FT4232H and FT4232HA do not support open
|
||||
collector mode, and source current to SCL and SDA lines.
|
||||
|
||||
Clock streching
|
||||
```````````````
|
||||
|
||||
Clock stretching is supported through a hack that re-uses the JTAG adaptative
|
||||
clock mode designed for ARM devices. FTDI HW drives SCL on ``AD0`` (`BD0`), and
|
||||
samples the SCL line on : the 8\ :sup:`th` pin of a port ``AD7`` (``BD7``).
|
||||
|
||||
When a FTDI device without an open collector capability is used
|
||||
(FT2232H, FT4232H, FT4232HA) the current sourced from AD0 may prevent proper
|
||||
sampling ofthe SCL line when the slave attempts to strech the clock. It is
|
||||
therefore recommended to add a low forward voltage drop diode to `AD0` to
|
||||
prevent AD0 to source current to the SCL bus. See the wiring section.
|
||||
|
||||
Speed
|
||||
`````
|
||||
|
||||
Due to the FTDI MPSSE engine limitations, the actual bitrate for write
|
||||
operations over I2C is very slow. As the I2C protocol enforces that each I2C
|
||||
exchanged byte needs to be acknowledged by the peer, a I2C byte cannot be
|
||||
written to the slave before the previous byte has been acknowledged by the
|
||||
slave and read back by the I2C master, that is the host. This requires several
|
||||
USB transfer for each byte, on top of each latency of the USB stack may add up.
|
||||
With the introduction of PyFtdi_ v0.51, read operations have been optimized so
|
||||
that long read operations are now much faster thanwith previous PyFtdi_
|
||||
versions, and exhibits far shorter latencies.
|
||||
|
||||
Use of PyFtdi_ should nevetherless carefully studied and is not recommended if
|
||||
you need to achieve medium to high speed write operations with a slave
|
||||
(relative to the I2C clock...). Dedicated I2C master such as FT4222H device is
|
||||
likely a better option, but is not currently supported with PyFtdi_ as it uses
|
||||
a different communication protocol.
|
||||
|
||||
.. _i2c_wiring:
|
||||
|
||||
Wiring
|
||||
~~~~~~
|
||||
|
||||
.. figure:: ../images/i2c_wiring.png
|
||||
:scale: 50 %
|
||||
:alt: I2C wiring
|
||||
:align: right
|
||||
|
||||
Fig.1: FT2232H with clock stretching
|
||||
|
||||
* ``AD0`` should be connected to the SCL bus
|
||||
* ``AD1`` and ``AD2`` should be both connected to the SDA bus
|
||||
* ``AD7`` should be connected to the SCL bus, if clock streching is required
|
||||
* remaining pins can be freely used as regular GPIOs.
|
||||
|
||||
*Fig.1*:
|
||||
|
||||
* ``D1`` is only required when clock streching is used along with
|
||||
FT2232H, FT4232H or FT4232HA devices. It should not be fit with an FT232H.
|
||||
* ``AD7`` may be used as a regular GPIO with clock stretching is not required.
|
||||
Loading…
Add table
Add a link
Reference in a new issue