--------------------------------------------------------------------------------
                Quick-Start Guide for libticables2 set-up
--------------------------------------------------------------------------------

An issue with this library, on GNU/Linux, is properly setting up access to
devices. The *nix family, to which GNU/Linux belongs, is less insecure than old
Windows versions because it heavily relies on separation and permissions... but
as a consequence, it becomes harder to use in some situations.

This document describes methods for manual setup of access to cables and
calculators on the parallel, serial and USB cables.

On the first run, you may want to run your program as root. This way, you will
be almost sure to run it successfully.
On the long run, you should of course run your program as a regular
(non-privileged) user, and for this, you need to take care of permissions, as
explained by this document.


--------------------------------------------------------------------------------
ParallelLink cable
--------------------------------------------------------------------------------

The node is '/dev/parportX". You must have r/w permissions on this device, and
the device must not be locked exclusively by any other parallel port driver
(such as some CUPS drivers for parallel port printers) - otherwise libticables2
won't be able to acquire and use the port.
This can be done by:
 - giving up r/w permissions to others (chmod ugo+rw /dev/parport?) or, better,
 - adding your user to the group 'lp' (edit /etc/group and add your
   username after the ':').
   Example 1:
     crw-rw-rw- 1 root lp 99, 0 2005-02-26 07:39 parport0
   Example 2:
     lp:x:7:romain
- On some distributions (e.g. Fedora 12), an alternative, groupless setup
  detailed below can also be used.

If you have a parallel port printer, for libticables2 to work, you may need to
stop the CUPS printing service (the way to do this depends on your distribution)
and unload the 'lp' kernel module (`rmmod lp` as root), so as to liberate the
exclusive lock on the parallel port held by CUPS / the printer driver.


--------------------------------------------------------------------------------
BlackLink & GrayLink cables
--------------------------------------------------------------------------------

The node is '/dev/ttySx". You must have r/w permissions on this device.
This can be done by:
 - giving up r/w permissions to others (chmod ugo+rw /dev/ttyS0) or, better,
 - adding your user to the group 'dialout' (edit /etc/group and add your
   username after the ':').
   Example 1:
     crw-rw-rw-  1 root dialout 4, 64 2006-02-08 13:40 /dev/ttyS0
   Example 2:
     dialout:x:20:romain
- On some distributions (e.g. Fedora 12), an alternative, groupless setup
  detailed below can also be used.


--------------------------------------------------------------------------------
Groupless setup for udev >= 143 with udev-acl and ConsoleKit / systemd
--------------------------------------------------------------------------------

On most modern distributions, it is possible to set up the system so that the
user physically in front of the computer, if any, gets access to what's assumed
to be his/her calculator automatically. The exact procedure used to vary
depending on the individual distribution and its age, but seems to have become
stable for years. The following procedure works for systems using udev 143 or
newer with udev-acl enabled, such as Fedora 12.

How udev-acl works is that a nice system service called ConsoleKit keeps track
of what user(s) is/are currently logged in locally. The udev-acl tool uses this
information to hand out ACLs for these devices to those users.

To use this setup, create a /etc/udev/rules.d/69-libticables.rules file with
the contents listed below.
ACTION!="add", GOTO="libticables_end"

# serial device (assume TI calculator)
KERNEL=="ttyS[0-3]", ENV{ID_PDA}="1"
# parallel device (assume TI calculator)
SUBSYSTEM=="ppdev", ENV{ID_PDA}="1"
# SilverLink
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="e001", ENV{ID_PDA}="1"
# TI-84+ DirectLink
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="e003", ENV{ID_PDA}="1"
# TI-89 Titanium DirectLink
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="e004", ENV{ID_PDA}="1"
# TI-84+ SE DirectLink
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="e008", ENV{ID_PDA}="1"
# TI-Nspire DirectLink
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="e012", ENV{ID_PDA}="1"

LABEL="libticables_end"

IMPORTANT NOTE:
    * on 143 <= udev <= 165, replace ENV{ID_PDA}="1" by ENV{ACL_MANAGE}="1".


--------------------------------------------------------------------------------
Old group-based setup for the SilverLink and DirectLink cables
--------------------------------------------------------------------------------

This is mentioned for historical purposes, as it worked for years on Debian and
derivative distros using udev. It uses a POSIX group. You should use the
group-less setup described above instead.

Like the group-less setup, it requires adding a set of udev rules.

To use this setup, create a /etc/udev/rules.d/20-ticables.rules file with
the contents listed below.
# SilverLink
ACTION=="add", SUBSYSTEM=="usb_device", ATTR{idVendor}=="0451",
ATTR{idProduct}=="e001", MODE="0660", GROUP="plugdev"
# TI-84+ DirectLink
ACTION=="add", SUBSYSTEM=="usb_device", ATTR{idVendor}=="0451",
ATTR{idProduct}=="e003", MODE="0660", GROUP="plugdev"
# TI-89 Titanium DirectLink
ACTION=="add", SUBSYSTEM=="usb_device", ATTR{idVendor}=="0451",
ATTR{idProduct}=="e004", MODE="0660", GROUP="plugdev"
# TI-84+ SE DirectLink
ACTION=="add", SUBSYSTEM=="usb_device", ATTR{idVendor}=="0451",
ATTR{idProduct}=="e008", MODE="0660", GROUP="plugdev"
# TI-Nspire DirectLink
ACTION=="add", SUBSYSTEM=="usb_device", ATTR{idVendor}=="0451",
ATTR{idProduct}=="e012", MODE="0660", GROUP="plugdev"

The template relies on a group called 'plugdev'. If it doesn't exist, you will
have to create it or choose another group which matches better your system.

You will have to add the user to the group 'plugdev' (by using one of the
user/group management tools, or editing /etc/group + /etc/gshadow to add your
username after the ':'). For example, the line will become:

        plugdev:x:46:romain
