CHANGES.txt

pylibftdi changes
=================

0.23.0
------
* Added: #12 - pid & vid selection when opening a new `Device` - thanks @maraxen!
* Minor API change:
  * removed use of kwargs for Device() and Driver() arguments, replacing with keyword-only
    arguments. Tthis is unlikely to cause issues in most cases, and protects against typos
    or incorrect arguments.
  * one valid case requiring change is passing in a `libftdi_search` argument; if this is
    required, create a driver instance separately (with this parameter) and pass it to
    `Device()` using the new `driver` keyword-only parameter.
* Various bumps and fixes to linting dependencies

0.22.0
------
* Fix: #7 - support for Python3.12
* Fix: #6 - prevent BitBangDevice.port values exceeding 8 bits
* Bumps to linting dependencies (ruff, mypy, black, pylint)

0.21.0
------
* Breaking changes:
  * Python 3.7+ is now required for pylibftdi.
  * Driver.libusb_version() and libftdi_version() now return strings rather than bytestrings for textual version info
* Development changes:
  * Type hinting has been added - thanks @WhatTheFuzz!
  * Moved to a `src` layout. See https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/
  * Switched from `setuptools` to `poetry` for development.
  * Linting and style changes (Ruff & black) have been applied throughout.
  * Additional unit tests, especially covering library loading.
  * Added a Dockerfile and Makefile for development and testing.
  * Added GitHub Actions CI for linting and unittests.

0.20.0
------
* Removed claims of Python2 support, added warnings that Python2 support
  will be removed in future releases.
  NOTE: Future releases will require Python 3.6 or later.
* Fix to `ftdi_get_library_version`, broken on M1 Macs. See Github issue #2.
  Thanks to @wrigby for diagnosing and fixing this.

0.19.0
------
* Moved to GitHub (and git, obviously!) following deprecation of Mercurial
  on bitbucket.org. No other changes beyond URL updates, docs pointing to
  GitHub etc. Note that references to old bitbucket issues will stop being
  helpful very soon, but there's not much I can do about this.

0.18.1
~~~~~~
* fixed - list_devices example was broken for Python3 following 0.18.0

0.18.0
~~~~~~
* fixed - memory leak in list_devices() (Bitbucket issue #34)
* changed - examples now written for (and require) Python3 (Bitbucket issue #35)
* new - more helpful platform-dependent error messages
* added - __main__.py module to support `python -im pylibftdi`
* added - `index` parameter to Device() constructor to allow indexing
  into the list returned from Driver.list_devices(). Useful to access
  e.g. the second device where PID differs between the first two devices
  and device_index would reset to zero for each PID/VID combination.
* Removed the ftdi_osx_driver_reload/unload scripts. These complicated cross-
  platform packaging and error messages / docs have been updated to include
  appropriate instructions.

0.17.0
~~~~~~
* new - added 0x6015 USB PID to the default PID list, supporting FT230 devices
* fixed - updated ftdi_osx_driver_re/unload scripts to support Python3
* fixed - auto_detach bug on some systems (Bitbucket issue #27)
* *API CHANGE* - Moved `auto_detach`, `chunk_size` and `lazy_open` to class
  attributes which can be easily overridden in subclasses, or in kwargs.
  This means that any program using these as *positional* arguments needs
  to change to use them as keyword parameters. Note: all but `device_id` and
  `mode` may become keyword-only arguments in the future.

0.16.1.2
~~~~~~~~
* rebuilt to fix install issue on macOS

0.16.1.1
~~~~~~~~
* changed / fixed - still getting segfault in some situations with
  combination of auto_detach=True and libftdi 0.x, so auto_detach
  is now only supported in libftdi 1.0+ and ignored otherwise.

0.16.1
~~~~~~
* fixed - segfault opening `Device` instances when `auto_detach` used and
  running on early (pre 1.0) versions of `libftdi`.

0.16.0
~~~~~~
* new/changed - Automatic driver detach. By default, calls
  `libusb_set_auto_detach_kernel_driver()` on  newly opened devices, to
  restore kernel drivers after close.  Note this only seems to have an
  effect on Linux, as far as I can tell.
  Disable with `Device(..., auto_detach=False)`
* new - serial_transfer example which checks that pseudo-random data send
  over a serial connection is correctly transferred.
* new - `modem_status` property on SerialDevice() object, 16-bit value where
  each bit represents a different value such as 'Overrun Error'. See docstring
  or documentation for ftdi_poll_modem_status function in libftdi.
* fixed - reset FTDI latency timer to default (16ms) on device instantiation
* changed - Python2.6 is no longer supported.
* changed - now uses incremental codecs when doing text-based transfer.

0.15
~~~~
* new - additional `pylibftdi.Driver` methods: `libusb_version` to report
  on the version of the libusb library
* new - `info` example, which displays additional info about the enviroment
  pylibftdi is running in; run with `python -m pylibftdi.examples.info` or
  similar.
* changed - `libftdi_search` argument to `Driver()` can now give a path name
  referencing the libftdi library.
* changed - libftdi is now opened on first use, not immediately when
  creating a `Driver` instance.
* changed - missing libraries now raise `pylibftdi.LibraryMissingError`.
  This subclasses `FtdiError`, so should remain compatible with existing
  usage, but allows this to be caught explicitly.
* fixed - finding the libftdi library on Windows has been improved/fixed;
  find_library does not work consistently across Windows / Python
  versions...
* More test cases covering bitbang usage

0.14.2
~~~~~~
* new - optional device_index parameter to `Device()` constructor, select
  devices by index rather than (just) serial number / description as per
  device_id

0.14.1
~~~~~~
* install - only install the ftdi_osx_driver_* scripts if we're installing
  to an OS X machine

0.14
~~~~

* refactor - split the `Device` class from the driver.py module into its
  own 'device.py' module
* refactor - fix tests so they work both standalone and when run via e.g.
  python -m unittest discover
* change - now resets the flow control and baudrate during device
  initialisation
* new - SerialDevice class - supports properties for various serial lines
  (CTS, DTS, RI as inputs; DTR, DSR as outputs)
* new - ftdi_osx_driver_{re,un}load scripts to disable / re-enable the
  built-in drivers supplied on Mac OS X
* new - midi_output example - using pylibftdi to output MIDI data

0.13
~~~~

* When finding and opening a device, don't just present the last error (which
  may well be a 'device not found (-3)' error, but more specific ones. Avoids
  issues where errors opening a device were being masked as pylibftdi would
  continue looking for other devices to open, and report on failure to find
  any of them.
* Don't error out on failure during string retrieval part of device
  enumeration (list_devices) on failure to read product manufacturer,
  description or serial number (bitbucket issue #10)
* Fix Driver.libftdi_version() for older library versions (which don't report
  version information...)
* USB_PID_LIST now defaults to 0x6001, 0x6010, 0x6011, 0x6014. The new
  entries are 0x6010 and 0x6011. Note that USB_PID has been removed, and
  USB_VID has been replaced with FTDI_VENDOR_ID
* Updated documentation, specifically regarding use on OS X Mavericks
* Added serial_loopback example test, for investigating ongoing issues with
  UB232H module serial loopback losses...

0.12
~~~~
* Optimisation on accessing port property when direction is set to ALL_OUTPUTS
  - don't bother reading the pins first. Makes ``port`` identical to ``latch``
  in this case.
* Support for libftdi 1.x, used by preference over ftdi 0.x. The specific
  driver search can be given as a string (or tuple of strings) to the
  ``Driver`` constructor, e.g. the default is equivalent to::

      >>> d = Driver()
      >>> # equivalent to...
      >>> d = Driver(('ftdi1', 'libftdi1', 'ftdi', 'libftdi'))
      >>> # and if we wanted to use ftdi 0.x on Linux:
      >>> d = Driver('ftdi')

  The driver in use can be determined by ``Driver.libftdi_version()`` method::

      >>> from pylibftdi import Driver
      >>> Driver().libftdi_version()
      (1, 0, 0, '1.0', 'v1.0-6-gafb9082')
      >>> Driver('ftdi').libftdi_version()
      (0, 99, 0, '0.99', 'v0.17-305-g50d77f8')

* Support for MS Windows (which requires the 'lib' prefix on ftdi searching -
  previously absent).
* Minor bug fixes

0.11
~~~~

* API changes
    * Device() parameter 'interface' has been renamed to 'interface_select',
      as it wasn't clear what this meant. Symbolic constants 'INTERFACE_ANY',
      'INTERFACE_A'/B/C/D are provided in the pylibftdi package namespace.
    * Device() parameter 'buffer_size' has been renamed to 'chunk_size' because
      there isn't any buffering going on, so it was potentially misleading.
    * new 'latch' property on BitBangDevices reflects current state of output
      latch, for better defined behaviour on read-modify-write operations on
      mixed-direction ports.
* fixed the bit_server example; run as
      python -m pylibftdi.examples.bit_server
* docstring clean-ups
* BitBangDevice now reads device pin state on startup, so read/rmw operations
  across process runs now work as expected; for example previously running::

      >>> from pylibftdi import BitBangDevice
      >>> d = BitBangDevice()
      >>> d.port = 1
      >>> ^D

      # restart interpreter

      >>> from pylibftdi import BitBangDevice
      >>> d = BitBangDevice()
      >>> d.port |= 2

  would have cleared D0, but now keeps it high (so d.port == 3)
* setup.py will now use setuptools/distribute if installed, allowing the
  'develop' target.

0.10.3
~~~~~~
* lots more documentation, cleaned up, on readthedocs. Still in progress though.
* Experimental support for multi-device interfaces ``Device(interface=1)``

0.10.2
~~~~~~
* include examples subpackage
* ensure examples work under Python3
* 'python -m pylibftdi.examples.led_flash' should now work and pulse D0

0.10.1
~~~~~~
* maintenance build to fix installation issues
* USB_VID_LIST/USB_PID_LIST exposed directly as pylibftdi attributes

0.10
~~~~
* support for FT232H via iteration over lists USB_VID_LIST/USB_PID_LIST in
  driver.py (FT232H uses different PID)
* support for 'buffering' - i.e. chunking reads and writes to allow
  interruption (i.e. KeyboardInterrupt) in what could otherwise be a very long
  uninterruptable extension code call.
* reset device to serial mode on open() (previously could be left in bitbang mode)
* moved docs -> /doc
* moved pylibftdi/tests -> /tests - makes python -m unittest discover etc work better
* removed legacy support for Driver() to acting as a Device()
* API for Bus class now requires .device rather than .driver (this still needs
  improving at some point)

0.9
~~~
* improved and extended tests
* made a start on some Sphinx-based documentation
* fixed long-standing issue with input from a BitBangDevice
* allow the PID/VID to be changed
* add new examples
    * basic web server to toggle / read IO bits
    * magic_candle.py - example of using input and output together
    * pin_read.py - read and match values on device pins
* All of this needs some tidying, but it fixes some key issues and has been unreleased too long.

0.8.1
~~~~~
* fix issue with bitbang following API changes in 0.8
* add tests for bitbang mode
* refactor tests; fix text-based tests in Python3
* slight refactor Device() to improve testability (_read and _write methods)

0.8
~~~
* added some unit tests
* API changes:
    * when opening a device with a device_id parameter, this will now check
      against both serial number and (if that fails), the device description.
      Opening by device type (under the same proviso that an arbitrary device
      will be selected if multiple matching devices are attached as when no
      device_id is given) is frequently easier than matching by serial number.
    * added flush(), flush_input() and flush_output() operations. This is
      modelled after the pySerial API providing separate flush operations, and
      gets the Device API closer to that of files.
    * increased file-API compatibility, with line-oriented methods and iteration

0.7
~~~
* support multiple attached devices
* API changes:
    * separation between driver and device. Generally, now use Device() /
      BitBangDevice() rather than Driver / BitBangDriver(), though older code
      _should_ still work via some shims (though with Deprecation warnings).
    * first parameter in Device() and BitBangDevice() is a device ID - the serial
      number string of the target device.
    * open() is generally no longer required on Devices. This is to more closely
      model the file() API.

0.6
~~~
* same source now works on both Python2.6+ and Python3.

0.5
~~~
* fix various bugs found by pyflakes
* improve module organisation, while providing interface compatibility

0.4.1
~~~~~
* fix release issue

0.4
~~~
* fixed embarrassing bug which caused things not to work on Linux
  (is now find_library('ftdi') instead of find_library('libftdi'))
* lots of error checking, new FtdiError exception. Before it just
  tended to segfault if things weren't just-so.
* get_error() is now get_error_string().  It's still early enough
  to change the API, and if I thought it was get_error_string
  multiple times when I wrote the error checking code, it probably
  should be the more natural thing.

0.3
~~~
* added some examples
* new Bus class in pylibftdi (though it probably belongs somewhere else)
* first release on PyPI

0.2
~~~
* fixed various bugs
* added ftdi_fn and set_baudrate functions in Driver class
* changed interface in BitBangDriver to direction/port properties
  rather than overriding the read/write functions, which are therefore
  still available as in the Driver class.

0.1
~~~
* first release. Tested with libftdi 0.18 on Mac OS X 10.6 and Linux
  (stock EEEPC 701 Xandros Linux, Ubuntu 10.04)