Installing the software


Argyll doesn't come with any installation programs or scripts, so installation is a manual process. Because things are mostly self-contained, this isn't particularly onerous. In general the steps are:

1) Provide somewhere for the executables to reside
2) Provide a means of the shell finding the executables
3) Setup the system to be able to use instruments (USB in particular)

Microsoft Windows
Apple OS X
Linux/UNIX X11

If you have a Spyder 2 colorimeter, please also see spyd2en.


Microsoft Windows:

You will need to unzip the downloaded file in the location you have chosen to hold the executable files (perhaps somewhere like \bin\argyll). I would NOT put them in \Program Files\argyll, since spaces in directory or file names and command line environments are a very bad mix, and will cause you endless problems. You should also configure your %PATH% environment variable to give access to the executables from your command line environment. Look in  Start->ControlPanel->System->Environment or Start->ControlPanel->System->Advanced->EnvironmentVariables for where to add this directory to your %PATH%. Note that a ';' character separates each directory in the path, and you should probably add your new directory at the end. The .zip file also contains several useful reference files (such as scanner chart recognition templates, sample illumination spectrum etc.) in the ref sub-directory, all the current documentation in a doc sub-directory, and instrument USB drivers in the libusbw directory.

If you are using a serial connected instrument, then there is nothing special to do to enable this.

If you are using a USB connected instrument, then suitable USB drivers may need to be installed.

NOTE that if you are updating to a new version of Argyll, that it may be necessary to uninstall all the Argyll USB devices, and re-install them, to update the relevant libusb-win32 system driver and dll. (This is true for updating to Argyll Version 0.70).

If you currently don't have any applications that talk to your instrument using USB, then it is relatively simple to use the drivers provided with Argyll. On plugging the instrument in, MSWindows should pop up a "New Hardware" dialog, and ask you for drivers. Navigate the dialog until you are able to direct it where to look for drivers. Using the "Browse.." selection, locate the libusbw directory within the argyll files, and select the appropriate instrument .inf file (ie. DTP94.inf, i1Disp.inf etc.), and then continue with  the installation wizard.

Note that the "Huey" colorimeter appears as an HID (USB Human Interface Device Class) device, and hence will be assigned to the default MSWindows HID driver, rather than popping a "New Hardware" dialog. If your version of Argyll has been compiled with MSWindows HID driver support (as the binary distribution does), then you do not need to install an Argyll libusbw driver. If your version of Argyll does not have HID driver support (no DDK available), then you will need to switch the "Huey" from the HID driver to a libusbw driver (see below).

If you currently have applications other than Argyll accessing your USB connected instrument, then you have a choice to make. You can replace the existing USB drivers used on that device with the ones provided with Argyll, using the MSWindows device manager to "update drivers" for that device, browsing for, then selecting the .inf file provided with Argyll. Once the Argyll drivers are installed, you can most easily switch between the different drivers using "update drivers", and using  the "display a list of known drivers" option, switching backwards and forwards between the original drivers and the Argyll drivers. Note that for the "Huey" colorimeter when not using the HID driver support, you will have to locate the device labelled "USB Human Interface Device" that corresponds to the "Huey", and "update" it to the Argyll supplied "Huey.inf" libusbw driver. You can then switch backwards and forwards the same as other devices.

The alternative is to go to the libusb-win32 web site, and download and then install the "filter drivers", - see <http://libusb-win32.sourceforge.net./#downloads>. This may then let you access the device using Argyll, without disabling access by existing applications. (I haven't tried this, so I'm not sure how well it works).
You don't make use of the Argyll .inf file using this approach.


Apple OS X:

You will need to unzip the downloaded file in the location you have chosen to hold the executable files. Typically this might be in /usr/local/argyll, or perhaps $HOME/bin/argyll. You will also have to configure your $PATH environment variable to give access to the executables from your command line environment. If you are unfamiliar with how to do this, consult an appropriate tutorial, e.g. <ShellIntro>. The .zip file also contains several useful reference files (such as scanner chart recognition templates, sample illumination spectrum etc.) in the ref sub-directory, as well as all the current documentation in a doc sub-directory.

For most devices there is nothing special to do. Plug in and go. For some devices though (specifically, if you want to use the HCFR colorimeter), the default OS X class drivers will grab the device, preventing Argyll from accessing it. To overcome this, you need to install a codeless kernel extension if you wish to use the HCFR colorimeter, that prevents this from happening. From the command line you need to create a directory called Argyll.kext somewhere convenient, and then place in it one file called Info.plist, containing the following:

    ----------------- cut here ---------------------
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <key>CFBundleDevelopmentRegion</key> <string>English</string>
       <key>CFBundleGetInfoString</key> <string>Libusb USB device Shield</string>
       <key>CFBundleIdentifier</key> <string>com.libusb.USB_Shield</string>
       <key>CFBundleInfoDictionaryVersion</key> <string>6.0</string>
       <key>CFBundleName</key> <string>Libusb USB device Shield</string>
       <key>CFBundlePackageType</key> <string>KEXT</string>
       <key>CFBundleSignature</key> <string>????</string>
       <key>CFBundleVersion</key> <string>6.0</string>
       <key>IOKitPersonalities</key>
       <dict>
           <key>HCFR</key>
           <dict>
               <key>CFBundleIdentifier</key> <string>com.apple.driver.AppleUSBComposite</string>
               <key>IOClass</key> <string>AppleUSBComposite</string>
               <key>IOProviderClass</key> <string>IOUSBDevice</string>
               <key>idVendor</key> <integer>1243</integer>
               <key>idProduct</key> <integer>91</integer>
           </dict>
       </dict>
       <key>OSBundleCompatibleVersion</key> <string>1.8</string>
       <key>OSBundleLibraries</key>
       <dict>
           <key>com.apple.kernel.iokit</key> <string>6.0</string>
       </dict>
   </dict>
   </plist>
    ----------------- cut here ---------------------

(You can also copy this from the source installation in libusb/Argyll.kext)

You then need to install it by using:

  sudo cp -R Argyll.kext /System/Library/Extensions

supplying the appropriate root password when prompted.
Reboot the system to activate the extension.


Lunix/UNIX using X11:

You will need to unzip the downloaded file in the location you have chosen to hold the executable files. Typically this might be in /usr/local/argyll, or perhaps $HOME/bin/argyll. You will also have to configure your $PATH environment variable to give access to the executables from your command line environment. The .zip file also contains several useful reference files (such as scanner chart recognition templates, sample illumination spectrum etc.) in the ref sub-directory, as well as all the current HTML documentation in a doc sub-directory. You may want to copy things to more standard locations such as /usr/local/bin, /usr/local/argyll/bin etc., depending on the conventions used on your system.

Note on the system bell:

When reading strips using the Eye-One Pro instrument, the system bell is used to indicate when the instrument the ready to be used, and to provide feedback on any problems. On some Linux installations the system bell may be disabled. As well as checking the terminal and GUI sound preferences, you may have to enable the used of the PC speaker driver, which can be done by adding the command /sbin/modprobe pcspkr to the /etc/rc.local startup script. You may also have to run xset b 100 1000 200 in your local setup, if you are running in an X11 environment.

Note on X11 multi-monitor setups:

When working with a multi-monitor X11 configuration, note that you will only be able to individually calibrate monitors if the multi-window extension you are using (if any), supports access to the individual screen Video LUT tables that are used for calibration. The native X11 multi-screen addressing supports this, as does the Xinerama extension.

The proprietary NVidia TwinView and ATI MergeFB extensions do not support access to the individual screen Video LUTs, so calibration of each screen independently is impossible if either of these extensions are running. You can try doing a calibration for the screens that do have accessible Video LUTs with these proprietary extensions, or ignore calibration and rely purely on display profiling. Use the dispwin utility to figure out what works on your system.
If these limitations trouble you, then as a customer of NVidia or ATI, perhaps you should contact them and urge them to fix the problems with Video LUT access in their proprietary multi-monitor extensions, bringing their support for multi-monitors on X11 up to the same standards as other operating systems. When RandR V1.2 becomes more popular, this may also solve this problem.

Fixing access to Video LUTs:

Some users have noted that their default X11 installation doesn't properly enable access to the video card Video Lookup Tables (RAMDAC). The Video LUTs are used for display calibration purposes, and a warning will be issues by the dispcal and dispread utilities if there is a problem with this.

The problem may be because certain X11 extensions aren't being loaded by default. You may want to check that you have

  Load  "extmod"

in the appropriate (or any) section of your Xorg.conf file, to allow the XF86Video LUT extensions to function correctly.

Setting up instrument access:
Serial instruments:
If you are using a color instrument on a serial port, note that a serial mouse may occupy the first port (/dev/ttyS0), so you will have to discover which physical port maps to which tty, and that if you are not running as root, you may have to change the permissions on the serial port you are using for the instruments. One way of changing the permissions is to do this manually:

(as root:)  chmod 666 /dev/ttyS1

but you may find that this has to be done on every system start. A way this can be automated is to add the chmod command to the /etc/rc.serial file (you may have to create this file if it doesn't exist. Check the /etc/rc.sysinit script, to make sure that the rc.serial file is being invoked.)

On more modern Linux systems, the serial ports are probably being created by the udev system, so modifying the udev configuration is a neater way to go. You could for example, create a  10-Argyll.permissionsfile:

    ----------------- cut here ---------------------
    # Color instrument serial ports
    # Should have an "argyll" group, but do it crudely for now,
    ttyS1:root:uucp:0666
    ----------------- cut here ---------------------

and then install it as /etc/udev/permissions.d/10-Argyll.permissions, making sure it has owner root, group root, permissions 644.

USB using hotplug:
Some systems appear to be setup with udev rules that automatically cope with libusb devices, making the right devices appear in the file system, and setting their permissions appropriately. Other systems have USB access problems similar to those with serial ports,  and these can be solved by modifying the appropriate hotplug or udev configuration files. You need to be running as root to make these changes to your system.

Under older versions of Linux, you should look into the hotplug system configuration. You know you are running this because the /etc/hotplug directory exists on your system.

Assuming we want to configure for all Argyll supported USB instruments, copy the file libusb/Argyll.usermap from the binary or source distribution into  /etc/hotplug/usb/Argyll.usermap with owner root, group root, permissions 644. It should contain something like:

    ----------------- cut here ---------------------
# Detect instruments by their USB VID and PID
# DTP20
Argyll 0x0003 0x0765 0xd020 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# DTP92Q - not tested
Argyll 0x0003 0x0765 0xd092 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# DTP94
Argyll 0x0003 0x0765 0xd094 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# MonacoOPTIX (Same as i1 Display 1)
Argyll 0x0003 0x0670 0x0001 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# i1 Display
Argyll 0x0003 0x0971 0x2003 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# i1 Pro
Argyll 0x0003 0x0971 0x2000 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# Colorimtre HCFR
Argyll 0x0003 0x04DB 0x005B 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# Spyder 2
Argyll 0x0003 0x085C 0x0200 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
#
# Huey
Argyll 0x0003 0x0971 0x2005 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
    ----------------- cut here ---------------------

 (For even older versions, append the lines above to /etc/hotplug/usb.usermap, and you may have to run update-usb.usermap)

Then copy the file libusb/Argyll from the binary or source distribution into /etc/hotplug/usb/Argyll with owner root, group root, permissions 644. It should contain something like:

    ----------------- cut here ---------------------
    #!/bin/sh
    # Simply enable permissions.
    if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ]
    then
        # Should have a "pci" group, or "argyll" group, but do it crudely for now,
        # by making it world readable.
        # chgrp baz "${DEVICE}"
        # chmod 660 "${DEVICE}"
        chmod 666 "${DEVICE}"
    fi
    ----------------- cut here ---------------------

USB using udev, #1:
Newer Linux systems use udev in preference to hotplug, so the approach is slightly different: Copy the file libusb/45-Argyll.rules from the binary or source distribution into /etc/udev/rules.d/45-Argyll.rules with owner root, group root, permissions 644.  It should contain something like:

  ----------------- cut here ---------------------
# udev rule to change permissions so that the USB instruments can be accessed by argyll
# MODE="660", GROUP="argyll" would be better here.

# DTP20
SYSFS{idVendor}=="0765", SYSFS{idProduct}=="d020", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# DTP92Q - not tested
SYSFS{idVendor}=="0765", SYSFS{idProduct}=="d092", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# DTP94
SYSFS{idVendor}=="0765", SYSFS{idProduct}=="d094", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# MonacoOPTIX (Same as i1 Display 1)
SYSFS{idVendor}=="0670", SYSFS{idProduct}=="0001", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# i1Display
SYSFS{idVendor}=="0971", SYSFS{idProduct}=="2003", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# i1Pro
SYSFS{idVendor}=="0971", SYSFS{idProduct}=="2000", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# Colorimtre HCFR
SYSFS{idVendor}=="04DB", SYSFS{idProduct}=="005B", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# Spyder 2
SYSFS{idVendor}=="085C", SYSFS{idProduct}=="0200", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"

# Huey
SYSFS{idVendor}=="0971", SYSFS{idProduct}=="2005", PROGRAM="/bin/sh -c 'K=%k; K=$${K#usbdev}; printf bus/usb/%%03i/%%03i $${K%%%%.*} $${K#*.}'", NAME="%c",  MODE="666"
    ----------------- cut here ---------------------

Note that the "SYSFS==.." lines are one long line. You may need to run /sbin/udevtrigger/sbin/udevcontrol reload_rules or  /sbin/udevstart to get the new file noticed.
USB using udev, #2:
Other even more recent systems (Ubuntu ?) may work with a simplified udev rule:

  ----------------- cut here ---------------------
# udev rule to recognize instruments and put them in the plugdev groupl

# DTP20
 SYSFS{idVendor}=="0765", SYSFS{idProduct}=="d020", GROUP="plugdev"

# DTP92Q (not testedt)
SYSFS{idVendor}=="0765", SYSFS{idProduct}=="d092", GROUP="plugdev"

# DTP94
SYSFS{idVendor}=="0765", SYSFS{idProduct}=="d094", GROUP="plugdev"

# MonacoOPTIX (Same as i1 Display 1)
SYSFS{idVendor}=="0670", SYSFS{idProduct}=="0001", GROUP="plugdev"

# i1Display
SYSFS{idVendor}=="0971", SYSFS{idProduct}=="2003", GROUP="plugdev"

# i1Pro
SYSFS{idVendor}=="0971", SYSFS{idProduct}=="2000", GROUP="plugdev"

# Colorimtre HCFR
SYSFS{idVendor}=="04DB", SYSFS{idProduct}=="005B", GROUP="plugdev"

# Spyder 2
SYSFS{idVendor}=="085C", SYSFS{idProduct}=="0200", GROUP="plugdev"

# Huey
SYSFS{idVendor}=="0971", SYSFS{idProduct}=="2005", GROUP="plugdev"
    ----------------- cut here ---------------------

You may want to refer to this document for more guidance on writing udev rules

USB using HAL:
Even newer Linux systems may be using HAL to set hardware attributes:

/usr/share/PolicyKit/policy/color-device-file.policy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN" "http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">
<policyconfig>
  <action id="org.freedesktop.hal.device-access.color">
    <description>Directly access color meter devices</description>
    <message>System policy prevents access to the color meter devices</message>
    <defaults>
      <allow_inactive>no</allow_inactive>
      <allow_active>yes</allow_active>
    </defaults>
  </action>
</policyconfig>

/usr/share/hal/fdi/10osvendor/19-color.fdi  should contain something like:

<?xml version="1.0" encoding="UTF-8"?>
<deviceinfo version="0.2">
  <!-- Color meter devices known to Argyll CMS
       FDI creation: Nicolas Mailhot <nicolas.mailhot at laposte.net>
       with input from David Zeuthen and Frédéric Crozat -->
  <device>
    <!-- HCFR association -->
    <match key="usb_device.vendor_id" int="0x04DB">
      <!-- Display colorimeter -->
      <match key="usb_device.product_id" int="0x005B">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
    </match>
    <!-- MonacoOPTIX -->
    <match key="usb_device.vendor_id" int="0x0670">
      <!-- Eye-One Display 1 - display colorimeter -->
      <match key="usb_device.product_id" int="0x0001">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
    </match>
    <!-- X-Rite -->
    <match key="usb_device.vendor_id" int="0x0765">
      <!-- DTP20 "Pulse" - "swipe" type reflective spectrometer, that can be used un-tethered. -->
      <match key="usb_device.product_id" int="0xd020">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
      <!-- DTP92Q - CRT display colorimeter. (Not tested) -->
      <match key="usb_device.product_id" int="0xd092">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
      <!-- DTP94 "Optix XR" or "Optix XR2" - display colorimeter -->
      <match key="usb_device.product_id" int="0xd094">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
    </match>
    <!-- ColorVision -->
    <match key="usb_device.vendor_id" int="0x085C">
      <!-- Spyder 2 - display colorimeter -->
      <match key="usb_device.product_id" int="0x0200">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
    </match>
    <!-- Gretag-Macbeth -->
    <match key="usb_device.vendor_id" int="0x0971">
      <!-- Eye-One Pro - spot and "swipe" reflective/emissive spectrometer -->
      <match key="usb_device.product_id" int="0x2000">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
      <!-- Eye-One Display - display colorimeter -->
      <match key="usb_device.product_id" int="0x2003">
        <append key="info.capabilities" type="strlist">access_control</append>
        <merge key="access_control.type" type="string">color</merge>
        <merge key="access_control.file" type="copy_property">linux.device_file</merge>
      </match>
    </match>
    <!-- Huey - display colorimeter
     The Huey falsely declares itself as HID device -->
    <match key="@info.parent:usb_device.vendor_id" int="0x0971">
      <match key="info.capabilities" contains="usbraw">
        <match key="@info.parent:usb_device.product_id" int="0x2005">
          <append key="info.capabilities" type="strlist">access_control</append>
          <merge key="access_control.type" type="string">color</merge>
          <merge key="access_control.file" type="copy_property">linux.device_file</merge>
        </match>
      </match>
    </match>
  </device>
</deviceinfo>