# 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`

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 `pyftdi.ftdi.Ftdi` instance with the `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 EEPROM configuration tool documentation.

### `i2cscan`

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

### `pyterm`

`pyterm.py` is a simple serial terminal that can be used to test the serial port feature, see the Mini serial terminal 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 options switches

PyFtdi tools share many common option switches:

`-d`

  Enable debug mode, which emits Python traceback on exceptions

`-h`

  Show quick help and exit

`-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 URL would be `ftdi://ftdi:0x9999/1`

  > - `mycompany=0x666:myproduct=0xcafe`, vid:pid complete syntax with aliases; matching FTDI URLs could be:

  >   - `ftdi://0x666:0x9999/1`

  >   - `ftdi://mycompany:myproduct/1`

  >   - `ftdi://mycompany:0x9999/1`

  >   - …

`-v`

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

`-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 Virtual test framework.