.. include:: defs.rst

.. _tools:

Tools
-----

Overview
~~~~~~~~

PyFtdi_ comes with a couple of scripts designed to help using PyFtdi_ APIs,
and can be useful to quick start working with PyFtdi_.

Scripts
~~~~~~~

.. _ftdi_urls:

``ftdi_urls``
`````````````

This tiny script ``ftdi_urls.py`` to list the available, *i.e.* detected,
FTDI devices connected to the host, and the URLs than can be used to open a
:py:class:`pyftdi.ftdi.Ftdi` instance with the
:py:class:`pyftdi.ftdi.Ftdi.open_from_url` family and ``configure`` methods.


``ftconf``
``````````

``ftconf.py`` is a companion script to help managing the content of
the FTDI EEPROM from the command line. See the :ref:`ftconf` documentation.


.. _i2cscan:

``i2cscan``
```````````

The ``i2cscan.py`` script helps to discover which I2C devices
are connected to the FTDI I2C bus.


.. _pyterm.py:

``pyterm``
``````````

``pyterm.py`` is a simple serial terminal that can be used to test the serial
port feature, see the :ref:`pyterm` documentation.


Where to find these tools?
~~~~~~~~~~~~~~~~~~~~~~~~~~

These scripts can be downloaded from PyFtdiTools_, and are also installed along
with the PyFtdi_ module on the local host.

The location of the scripts depends on how PyFtdi_ has been installed and the
type of hosts:

* on linux and macOS, there are located in the ``bin/`` directory, that is the
  directory where the Python interpreter is installed.

* on Windows, there are located in the ``Scripts/`` directory, which is a
  subdirectory of the directory where the Python interpreter is installed.


.. _common_option_switches:

Common options switches
~~~~~~~~~~~~~~~~~~~~~~~

PyFtdi_ tools share many common option switches:

.. _option_d:

``-d``
  Enable debug mode, which emits Python traceback on exceptions

.. _option_h:

``-h``
  Show quick help and exit

.. _option_P_:

``-P <vidpid>``
  Add custom vendor and product identifiers.

  PyFtdi_ only recognizes FTDI official USB vendor identifier (*0x403*) and
  the USB identifiers of their products.

  In order to use alternative VID/PID values, the PyFtdi_ tools accept the
  ``-P`` option to describe those products

  The ``vidpid`` argument should match the following format:

  ``[vendor_name=]<vendor_id>:[product_name=]<product_id>``

  * ``vendor_name`` and ``product_name`` are optional strings, they may be
    omitted as they only serve as human-readable aliases for the vendor and
    product names. See example below.
  * ``vendor_id`` and ``product_id`` are mandatory strings that should resolve
    into 16-bit integers (USB VID and PID values). They may either be expressed
    as decimal or hexadecimal syntax.

  This option may be repeated as many times as required to add support for
  several custom devices.

  examples:

   * ``0x403:0x9999``, *vid:pid* short syntax, with no alias names;
     a matching FTDI :ref:`URL <url_scheme>` would be ``ftdi://ftdi:0x9999/1``
   * ``mycompany=0x666:myproduct=0xcafe``, *vid:pid* complete syntax with
     aliases; matching FTDI :ref:`URLs <url_scheme>` could be:

     * ``ftdi://0x666:0x9999/1``
     * ``ftdi://mycompany:myproduct/1``
     * ``ftdi://mycompany:0x9999/1``
     * ...

.. _option_v:

``-v``
  Increase verbosity, useful for debugging the tool. It can be repeated to
  increase more the verbosity.

.. _option_V_:

``-V <virtual>``
  Load a virtual USB device configuration, to use a virtualized FTDI/EEPROM
  environment. This is useful for PyFtdi_ development, and to test EEPROM
  configuration with a virtual setup. This option is not useful for regular
  usage. See :ref:`virtual_framework`.