
Installing Linux-GPIB user space
--------------------------------------------------------------------------

A) First steps:
--------------------------------------------------------------------------

o) Unpacking the Software:

        "linux-gpib-user-x.x.x" contains the userspace components of
	Linux-GPIB (the C library, etc.).  For a functioning system
	you will also need the driver components contained in
	"linux-gpib-kernel-x.x.x" or the GPIB drivers in the kernel
	sources from linux kernel version 6.13
	onwards. "linux-gpib-kernel-x.x.x" contains the code for gpib
	modules which are loaded into Linux kernel.  This install file
	describes the installation of "linux-gpib-user-x.x.x".
	
	Unpack the archives with the 'tar' program, for example
	'tar -xzf linux-gpib-user-x.x.x.tar.gz'


B) Installing Linux-GPIB user space
--------------------------------------------------------------------------

o) cd to your linux-gpib-user-x.x.x directory and run the
	'./configure' script.  Typically it would be run as:
	
	./configure --sysconfdir=/etc
	
	Run './configure --help' for a list of additional options.
	
	If the configure script does not exist (you are using a git
	clone), it can be generated by running the './bootstrap'
	script.  You will need automake, autoconf, etc. to generate
	the configure script.

	Type 'make'.  Now the package will be compiled.

	Type 'make install' (as root).  This will
	install the library, header files, etc.  Make sure the
	directory you installed the shared library to is listed in
	your /etc/ld.so.conf file, so that ld can find libgpib.so.  If
	the directory is not listed, add it and then run 'ldconfig'.

	With the default setup, to give a user access to the
	computer's gpib boards you will have to add them to the group
	'gpib'.  If this group does not already exist on your computer
	you may add it by running the command 'groupadd gpib' as root.
	You can then use the 'usermod' tool or edit /etc/groups to
	change the groups the user account belongs to.  Or, you could
	change the permissions on the device files /dev/gpib[0-15] to
	something you like better.  If you are using udev, you can set
	the permissions on the gpib device files with a line like:
	KERNEL=="gpib[0-9]*", MODE="0660", GROUP="gpib" in your udev
	rules.  This is already done by default if you ran
	./configure --sysconfdir=/etc.
        (see $(sysconfdir)/udev/rules.d/98-gpib-generic.rules
	installed by 'make install')

	In the unlikely case you are not using udev, you can use
	'chmod' (or edit devfsd.conf if you are using devfs) to change
	the device file permissions.  You may also need to manually
	create the device files /dev/gpibX if they don't already
	exist.  This can be done by running
	'make device_files_install'.

o) Documentation

        The documentation is installed in the following directories of
        the DATAROOTDIR specified by the --datarootdir option to
        .configure. By default $DATAROOTDIR=/usr/local/share.

	- manpages in $DATAROOTDIR/man
	  Ensure that your manpath includes this directory for direct
	  access to the linux-gpib manpages. Normally it includes
	  the default installation path /usr/local/share/man

	- html docs in $DATAROOTDIR/doc/linux-gpip-user/html
	  Point your browser to the t1.html file there to
	  start at the top index.

        The pdf version of the docs is not part of the installation
	and can be found at linux-gpib-user-x.x.x/doc/linux-gpib.pdf
	
C) Configuring the driver modules
   -----------------------------

o) PCMCIA cards

        If you have a really old system (kernel_version 2.4.x) that uses
        cardmgr from pcmcia_cs please see below.

	For all other systems (pcmciautils):
	Load the appropriate module for your pcmcia card with
        modprobe.  For example with an NI PCMCIA card:
	sudo modprobe tnt4882
	For other cards consult Table 2 Supported Hardware
        Matrix in the linux-gpib.pdf doc for the name of the module to
        load that corresponds to your PCMCIA card.  Then run
        gpib_config, for example: sudo gpib_config --minor 0

	cardmgr based systems:
	These systems are supported by Linux-GPIB version 3.1.x.  See
	the "linux-gpib for 2.4.x kernels" folder for the relevant
	linux-gpib package at:
	https://sourceforge.net/projects/linux-gpib/files/

o) USB devices

        USB devices can be configured automatically by the udev
	subsystem. When devices matching the udev rules are detected
	it triggers the execution of the gpib udev configuration
	scripts.  By default the scripts are installed in
	/usr/local/lib/udev. The target install directory can be
	customized with the --with-udev-libdir=DIR option when running
	./configure
	
	If your device requires external firmware you will need to
	install firmware files for your device. A tarball is available
	from https://github.com/fmhess/linux_gpib_firmware. Make sure
	you have the "fxload" and "udev" packages installed on your
	computer.  The udev scripts will automatically upload the
	firmware to your device and load the driver module when the
	device is detected.  If you have errors, check your system log
	files (not dmesg) for messages from the udev scripts: The udev
	rules in should be installed in /etc/udev/rules.d/. This is
	already done by default if you used ./configure
	--sysconfdir=/etc. The udev rules invoke the udev
	configuration scripts. Note: make install will not overwrite
	existing files in $sysconfdir/udev/rules.d/.

	The provided 99-xxx.rules files need not be edited. For an
	interface requiring a firmware load they will automatically
	invoke the fxload utility. Once the firmware is loaded the
	udev subsystem triggers the addition of the interface with the
	'firmware loaded product id'. This runs 98-gpib-generic.rules
	if customized to recognise the interface will add the
	appropriate --minor, --pad or other options to the
	GPIB_CONFIG_OPTIONS environment variable. Then the
	99-xxx.rules file is run again, this time with the actions for
	the interface with firmware. This will add the --board-type
	option in the GPIB_CONFIG_OPTIONS environment variable and
	invoke the gpib_udev_config script which runs gpib_config with
	the options contained in the GPIB_CONFIG_OPTIONS environment
	variable to initialise the interface. If you specify the
	--minor, --pad and --system-controller options in the
	98-gpib-generic.rules file for a particular board by serial
	number or device path, that board does not need to have an
	entry in the gpib.conf file.

	Using multiple-boards of the same type requires udev
	support. This is because by default gpib_config will be
	invoked for minor 0 for each board. You can associate specific
	board indexes (aka minors) by serial number or device
	path. This is done by uncommenting, duplicating and editing
	the example entries in the 98_gpib_generic.rules file for each
	interface. Using serial number it does not matter which usb
	ports you use.  Using device path the association will be made
	with the physical usb port in your system. To obtain the
	serial numbers or device paths for your adapters plug them in
	and check the syslog for the output from the gpib_udev_config
	script. The order of the messages will correspond to the order
	in which you plugged the adapters in: sudo tail -100
	/var/log/messages | grep gpib_udev_config

	In order to reload the rules files after editing you can use
	sudo udevadm control -R

	lpvo self made usb gpib adapter:
   	The lpvo DIY adapter uses a FTDI USB-Serial chip which by default
	loads the ftdi_sio driver module.
 	The gpib adapter can be enabled after a reboot with the commands:

 	    sudo rmmod ftdi_sio lpvo_usb_gpib
	    sudo modprobe lpvo_usb_gpi

	or, enabled automatically for all subsequent boots, by copying
	linux-gpib-user-x.x.x/usb/lpvo_usb_gpib/lpvo_usb_gpib.conf
	to
	/etc/modprobe.d

D) Configuring the GPIB-Library
-------------------------------

	You may edit $sysconfdir/gpib.conf to set the interface
	defaults for gpib_config, and add any devices you wish to open
	via ibfind().  See the documentation in doc/linux-gpib.pdf for
	more information.

	For non-usb devices or systems without udev support you need to
	run the 'gpib_config' utility to setup the driver before you
	can use it (the 'minor' options specifies which board index
	you are setting up):

	gpib_config --minor 0
	
E) Trying it out
----------------

	You may find the examples/ibtest program useful as a starting
	point in trying out your setup.  The examples/ibterm program
	provides a simple terminal interface to send commands to a
	specific instrument and view the responses.

F) Bindings for other languages
-------------------------------

	The bindings to other languages will be enabled by default in the
	'./configure' script.  They will not be built if you disable
	them with the appropriate configure option, or if the necessary
	header files/libraries are not found on your machine.

	Note: for the guile bindings you need to have the guile 1.8
	package installed.

G) Uninstalling
---------------

	Type 'make uninstall' as root in the same directory from which
	the package was originally installed. (linux-gpib-user-x.x.x/)

	Note: The configuration file and udev rules are not
	uninstalled by this procedure. They need to be removed
	manually if you wish to re-install the standard distribution
	configuration file and udev rules later since existing files are
	not overwritten by the install procedure. Check the following
	file and directory:

	      $sysconfdir/gpib.conf
	      $sysconfdir/udev/rules.d/