-------------------------------------------------------------------------------- Quick-Start Guide for libcalccables set-up -------------------------------------------------------------------------------- A burning issue with this library and GNU/Linux is good set-up of device access. GNU/Linux is secure because it heavily relies on permissions. But it may become a nightmare in some situations. On Fedora, when using the Fedora RPMs on repo.calcforge.org, link cables will just work as long as you're logged in locally to the machine (not over e.g. SSH). However, we cannot easily support this in the upstream source code at this time, as not all distributions ship the required tools and as they change frequently in Fedora. Therefore, this document describes methods for manual setup using standard *nix groups. For reference, the method used by the RPM packages is described as well, see the last section. On the first run, you should always run your program as root. By this way, you will be almost sure to run it with success. If you want to run your program as a simple user, you must take care of permissions. This is explained below. -------------------------------------------------------------------------------- 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 libcalccables 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), using an alternative, groupless setup detailed in the last section If you have a parallel port printer, for libcalccables 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), using an alternative, groupless setup detailed in the last section -------------------------------------------------------------------------------- SilverLink cable -------------------------------------------------------------------------------- For SilverLink cable, things are more complicated... - The following technique can be used for manual setup (using POSIX groups, as used e.g. on Debian) on udev-using systems: It may depend on your distribution, but you will have to add a rule to /etc/udev. As a template, you can create an /etc/udev/rules.d/20-calccables.rules file with the following rules: # SilverLink ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0451", SYSFS{idProduct}=="e001", MODE="0660", GROUP="plugdev" # TI-84+ DirectLink ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0451", SYSFS{idProduct}=="e003", MODE="0660", GROUP="plugdev" # TI-89 Titanium DirectLink ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0451", SYSFS{idProduct}=="e004", MODE="0660", GROUP="plugdev" # TI-84+ SE DirectLink ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0451", SYSFS{idProduct}=="e008", MODE="0660", GROUP="plugdev" # TI-Nspire DirectLink ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0451", SYSFS{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. At last, you will have to add the user to the group 'plugdev' (edit /etc/group and add your username after the ':'). Like this: plugdev:x:46:romain - On some distributions (e.g. Fedora), an alternative, groupless setup detailed in the last section can also be used. -------------------------------------------------------------------------------- Groupless setup for udev >= 143 with either systemd or udev-acl and ConsoleKit -------------------------------------------------------------------------------- The above manual setup methods require users to be manually added to groups to hand out device access. If this is not desired, on some distributions, it is also possible to set up the system so 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 varies depending on the individual distribution and its age. The following procedure works for systems using udev 143 or newer with systemd or the old udev-acl enabled, such as Fedora >= 12. This setup is used by the RPM in the CalcForge repository for Fedora, so its users need not worry about permissions, they will get access to their devices automatically when logged in locally (not over the network) to their machine. 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. In newer distributions, the functionality of both udev-acl and ConsoleKit has been taken over by systemd. To use this setup, create a /lib/udev/rules.d/69-libcalccables.rules file with the following contents: ACTION!="add", GOTO="libcalccables_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="libcalccables_end" The above is the syntax for udev >= 165. For versions 143 <= n <= 153 of udev, replace all instances of ENV{ID_PDA}="1" with ENV{ACL_MANAGE}="1" in the above. For versions 154 <= n <= 164 of udev, replace all instances of ENV{ID_PDA}="1" with TAG+="udev-acl" in the above. (Versions of udev <= 142 need to use a more complex setup based on HAL, or the group-based setup described further up in this document.)