Installing the Linux MiniMag Configuration Driver

Audience: Merchants' technical staff, I/S application administrators.

These notes come from /mit/ecommerce/dev/src/idtech/README. You may wish to consult the current version of that file for the latest rules on building and installing the driver.

I. Get or Build driver binary:

You may need to compile it if the binary for your platform doesn't load because of a mismatch with your kernel. Linux seems to be picky that way.

Get the source from:
/mit/ecommerce/src/idt-minimag.c

To Build: (on Athena 9.1 or 9.2, Red Hat Linux 2.4 kernel)

    cc -c -D__KERNEL__  -DMODULE -I /usr/src/linux-`uname -r`/include \
    -Wall -Wstrict-prototypes -Wno-trigraphs -O2 -fomit-frame-pointer \
    -fno-strict-aliasing -fno-common -Wno-unused  \
    idt-minimag.c

II. Installing the Driver and System Configuration

 (a) Install the driver in /lib/modules/`uname -r`/kernel/drivers/usb/
     (e.g. /lib/modules/2.4.18-5/kernel/drivers/usb/ )

      cp /mit/ecommerce/arch/@sys/lib/idt-minimag.o /lib/modules/`uname -r`/kernel/drivers/usb/

    Add this line to the end of /etc/modules.conf:

      add below idt-minimag usbcore

    e.g.
      echo "add below idt-minimag usbcore" >> /etc/modules.conf


    Then, regenerate the modules.dep file:
    (Ignore any warnings about unresolved symbols)

      depmod -a


 (b) The minimag driver MUST be loaded BEFORE the hid, keybdev, and
   input modules, since the "hid" module also recognizes the MiniMag as
   a USB keyboard (class HID) and will claim it.  The "minimag" driver
   must get the first crack at the device.
    
   Unfortunately there doesn't seem to be any precise way to control which
   driver driver is bound to a device:  When the device is noticed
   (at boot time or when it's plugged in),
   the first driver to match it is allowed to claim it.
   If one driver grabs all HID-class devices, and another is looking
   specifically for the MiniMag, the HID driver will still get it if it is
   first in line even though it doesn't "deserve" it.
    
   On a running system without any active USB input devices, you may be
   able to get away with rmmod'ing hid, keybdev, input in that order.
   Then insmod the idt-minimag driver.  Note that the "hotplug" system
   will automatically insmod the input and hid drivers when the MiniMag
   is plugged in, but *first* the kernel's USB subsystem will give
   control to the idt-minimag driver because it came first in the search
   order.  Example:

	rmmod hid
	rmmod keybdev
	rmmod input
	insmod idt-minimag

   When there are other USB devices in use, you have to do some
   surgery to ensure the idt-minimag driver comes first in the pecking order:

     i. Edit /etc/rc.d/rc.sysinit -- this runs when Linux boots.
        In the section where it does "modprobe hid", insert a line
        before that to "cold-plug" the minimag driver first, e.g.

         action $"Load idt-minimag driver first: " modprobe idt-minimag

       (see diffs below)

     ii. plug in the minimag unit and reboot.

  (c) Create a device file or two with e.g.

        mknod /dev/usb/minimag0 c 180 216
        mknod /dev/usb/minimag1 c 180 217

     ..If this minor number is already in use, you'll have to
     change USB_MINIMAG_MINOR_BASE in the driver source and recompile.

III. Using the driver:

 (a) Now you can send configuration commands to the MiniMag simply by writing
     text to the device, e.g. printf "/e/d/fn\r" > /dev/usb/minimag0
     Remember to wait for the device to beep (once for success, twice for
     failure) - the driver pauses about half a second after each character,
     so be patient.

 (b) To use the MiniMag as a card reader (after you finish configuring):

      - Unplug the MiniMag reader from the USB port.
     
      - rmmod idt-minimag
 	(so the the configuration driver won't be chosen)

      - Plug it back in.


--------------- diffs to "cold plug" the idt-minimag driver
                so it can coexist with other USB HID devices:

*** /etc/rc.d/rc.sysinit.orig   Fri Apr 19 05:55:02 2002
--- /etc/rc.d/rc.sysinit        Mon Aug 19 22:13:58 2002
***************
*** 172,177 ****
--- 172,178 ----
      aliases=`/sbin/modprobe -c | awk '/^alias usb-controller/ { print $3 }'`
      if [ -n "$aliases" -a "$aliases" != "off" ] ; then
        modprobe usbcore
+       action $"Kludging minimag driver: " modprobe idt-minimag
        action $"Mounting USB filesystem: "  mount -t usbdevfs usbdevfs /proc/bus/usb
        for alias in $aliases ; do
                [ "$alias" != "off" ] && action $"Initializing USB controller ($alias): " modprobe $alias