Introduction
~~~~~~~~~~~~

Starting with version 2.3 the PicoHarp software can also be used under Linux. 
This requires that Wine is installed (see http://www.winehq.org). We have successfully 
tested with Wine 1.1.4 and 1.1.5. You can run the regular software setup (setup.exe) 
as under Windows. Instead of installing a device driver, running under Linux with 
Wine requires that you have Libusb 0.1.12 installed 
(see http://libusb.sourceforge.net/). Furthermore, the interface library 
pquwstub.dll.so must be installed in /usr/lib/wine. You can find it in the subfolder 
Linux on your distribution media. 

Libusb Access Permissions 
~~~~~~~~~~~~~~~~~~~~~~~~~

For device access through libusb, your kernel needs support for the USB filesystem 
(usbfs) and that filesystem must be mounted. This is done automatically, 
if /etc/fstab contains a line like this: 

usbfs /proc/bus/usb usbfs defaults 0 0 

This should routinely be the case if you installed any of the mainstream Linux distributions. 
The permissions for the device files used by libusb must be adjusted for user access. 
Otherwise only root can use the device(s). The device files are located in /proc/bus/usb/. 
Any manual change would not be permanent, however. The permissions will be reset after reboot 
or replugging the device. A much more elegant way of finding the right files and setting the 
suitable permissions is by means of hotplugging scripts or udev. Which mechanism you can use 
depends on the Linux distribution you have. While the hotplug package was standard until 
recently, newer distributions starting from Fedora Core 5, Kubuntu 6.10 and SuSe 10.1 replace 
hotplug with udev. 

Hotplug 
~~~~~~~

For automated setting of the device file permissions with hotplug you have to add an entry to 
the hotplug usermaps. These files are located in /etc/hotplug/. If the entire hotplug directory 
does not exist, you probably don't have the hotplug package installed. This may be because your 
distribution is rather old (you may still be able to install hotplug) or it is very new and uses 
udev instead of hotplug (see section below). Every line in the hotplug usermap files is for one 
device, the line starts with a name that will also be used for a handler script. Here we are 
trying to get a PicoHarp300 device working, so let's call the entry "PicoHarp300". The next 
entry is always 0x0003. The following two entries are the vendor ID (0x0e0d for PicoQuant) and 
the product ID (0x0003 for the PicoHarp 300). The remaining fields are all set to 0. The line for 
the PicoHarp should look like below. The whole string should be on one line. Here it may wrap 
around due to limited page width: 

PicoHarp300 0x0003 0x0e0d 0x0003 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 

The handler script PicoHarp300 gets started when the device is connected or disconnected. 
It looks like this: 

#!/bin/bash
if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ]
then
  chown root "${DEVICE}"
  chgrp users "${DEVICE}"
  chmod 666 "${DEVICE}"
fi

When the PicoHarp gets switched on or connected, the hotplug system will recognize it and will 
run the script, which will then change the permissions on the device file associated with the 
device to 666, which means that everybody can both read and write from/to this device. Note that 
this may be regarded as a security gap. If you whish tighter access control you can create a 
dedicated group for PicoHarp users and give access only to that group. Both a usermap file 
PicoHarp300.usermap and the handler script PicoHarp300 are provided in the Linux folder on the 
distribution media. Copying both of them to /etc/hotplug/usb/ should be sufficient to set up acces 
control via hotplugging for your PicoHarp. 

Udev 
~~~~

As noted above, recent distributions such as Fedora Core 5 & SuSe 10.1 and later replace hotplug 
with udev. You won't find /etc/hotplug in this case. Instead, you can use udev to create the 
devices so they are readable and writable by non-priveleged users. The udev rules are contained 
in files in /etc/udev/rules.d. Udev processes these files in alphabetical order. The default file 
is usually called 50-udev.rules. Don't change this file as it could be overwritten when you 
upgrade udev. Instead, write your custom rule for the PicoHarp in a separate file. The contents 
of this file for the handling of the PicoHarp 300 should be: 

SYSFS{idVendor}=="0d0e", SYSFS{idProduct}=="0003", MODE="0666" 

A suitable rules file PicoHarp.rules is provided in the Linux folder on the distribution media. 
You can simply copy it to the rules.d folder. The install script in the same folder does just this. 
Note that the name of the rules file is important. Each time a device is detected by the hotplug 
system, the files are read in alphabetical order, line by line, until a match is found. Note that 
different distributions may use different rule file names for various categories. For instance, 
Kubuntu organizes the rules into further files: 20-names.rules, 40-permissions.rules, and 
60-symlinks.rules. In Fedora they are not separated by those categories, as you can see by 
studying 50-udev.rules. Instead of editing the existing files, it is therefore usually recommended 
to put all of your modifications in a separate file like 10-udev.rules or 10-local.rules. 
The low number at the beginning of the file name ensures it will be processed before the default 
file. However, later rules that are more general (applying to a whole class of devices) may later 
override the desired acecss rights. This is the case for USB devices handled through Libusb. It 
is therefore important that you use a rules file for the PicoHarp that gets evaluated after the 
general case. The default naming PicoHarp300.rules most likely ensures this. 

Note that there are different udev implementations with different command sets. On some 
distributions you must reboot to activate changes, on others you can reload rule changes and 
restart udev with these commands: 

# udevcontrol reload_rules
# udevstart


Limitations 
~~~~~~~~~~~

As noted above, when running under Linux, the PicoHarp software uses Libusb. However, the current 
version 0.1.12 of Libusb has an internal limitation of the block size it can handle in one transfer.
 This is currently 16 kBytes. Larger transfers are internally broken down into chunks of 16 kBytes. 
This unfortunately spoils any efforts of the PicoHarp software to improve throughput by means of 
large block sizes. Therefore, you may observe lower USB throughput than under Windows. The throughput 
limitation of Libusb can be lifted by a patch that permits efficient handling of large blocks. 
At the time of this writing the patch is not yet officially released. Please email us if you are 
interested in this solution. Another limitation is the current implementation of Wine's viewer for 
chm help files. You may observe some glitches when using the online help facility. Finally, please 
note that running the PicoHarp software under Linux/Wine is an experimental feature that cannot 
be covered by regular product support.