Source

pylibftdi / doc / installation.rst

Diff from to

doc/installation.rst

 
     $ pip install pylibftdi
 
+Depending on your environment, you may want to use either the ``--user`` flag,
+or prefix the command with ``sudo`` to gain root privileges.
+
 Windows
 -------
 
 Linux
 -----
 
-Debian package `libftdi-dev` should give you what you need.
+On Debian like systems (including Ubuntu, Mint, Debian, etc), the package
+`libftdi-dev` should give you what you need as far as the libftdi library
+is concerned.
 
 One potential issue is with permissions to access the device, which can be
-seen as a error when opening devices (with a '-4' error code).
+seen as a error when opening devices (with a '-4' or '-8' error code).
 The solution is to add udev rules to deal with the devices - the following
 works for me under Arch linux::
 
-   SUBSYSTEMS="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", GROUP=="users", MODE="0660"
-   SUBSYSTEMS="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", GROUP=="users", MODE="0660"
+   SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", GROUP=="users", MODE="0660"
+   SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", GROUP=="users", MODE="0660"
+
+Under other distributions, other group names are probably needed. On Ubuntu
+(12.04 here) I use the ``dialout`` group. Create a file
+``/etc/udev/rules.d/99-libftdi.rules`` containing::
+
+   SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", GROUP=="dialout", MODE="0660"
+   SUBSYSTEMS=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", GROUP=="dialout", MODE="0660"
 
 Some FTDI devices may use other USB PIDs. Use `lsusb` or similar to
 determine the exact values to use (or try checking `dmesg` output on
-device insertion / removal).
-You'll also probably find a more appropriate GROUP than 'users' depending
-on your Linux distribution.
+device insertion / removal). ``udevadm monitor --environment`` is also helpful,
+but note that the environment 'keys' it gives are different to the attributes
+(filenames within /sys/devices/...) which the ATTRS will match. Perhaps ENV{}
+matches work just as well, though I've only tried matching on ATTRS.
+
+Note that changed udev rules files will be picked up automatically by the udev
+daemon, but will only be acted upon on device actions, so unplug/plug in the
+device to check whether you're latest rules iteration actually works :-)
+
+See http://wiki.debian.org/udev for more on writing udev rules.
+
+Testing installation
+--------------------
+
+Connect your device, and run the following (as a regular user)::
+
+    $ python -m pylibftdi.examples.list_devices
+
+If all goes well, the program should report information about each connected
+device. If no information is printed, but it is when run with ``sudo``, a
+possibility is permissions problems - see the section under Linux above
+regarding udev rules.
+
+If the above works correctly, then try the following::
+
+    $ python -m pylibftdi.examples.led_flash
+
+Even without any LED connected, this should 'work' without any error - quit
+with Ctrl-C. Likely errors at this point are either permissions problems
+(e.g. udev rules not working), or not finding the device at all - although
+the earlier stage is likely to have failed if this were the case.
+
+Feel free to contact me (@codedstructure) if you have any issues with
+installation, though be aware I don't have much in the way of Windows systems
+to test.