K8055 Driver - Provides /proc/k8055 Files

k8055d v0.1.4

A kernel driver for Velleman K8055 USB Experiment Interface Boards.

Copyright (C) 2010 Alexander Bruines <abruines@users.sourceforge.net>
                                       or <sempher_pie@hotmail.com>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

===============================================================================

Contents:
=========
- Introduction.
- What does this driver do.
- Problems with other drivers (usbhid) in combination with k8055d.
- How to compile and install the driver.

Introduction:
=============

The K8055 is an USB device sold by the company Velleman (www.velleman.be).
The full name of the device is 'K8055 USB Experiment Interface Board' and
basicly gives the user some digital and analog inputs and outputs.
This device is sold as kit or pre assembled and comes with a propriaty
Windows(tm) shared library (dll) and software development kit (SDK).

Of course, this just won't do for linux systems. So I decided to write a
linux driver for the K8055, or at least try.
I also decided that a /proc interface would be appropriate.

I quickly discovered that there is another linux software package that works
with the K8055; libk8055 (libk8055.sourceforge.net). While libk8055 tries to
emulate the windows library as much as possible in order to assist in porting
windows programs and to create new (linux) programs written in C (or Python),
this driver sets asside the windows SDK and is more focused on being able to
use the K8055 'the linux way' ie. reading and writing the inputs and outputs
as if they were files.

The main reason I wrote this driver besides wanting the /proc interface is
to learn. This is the first 'real' linux program that I have written.

Which package you prefer is up to you. I found libk8055 a very usefull tool 
and its source code helped me a lot when writing this driver. In fact I doubt
that I would have come this far so quickly if it weren't for libk8055.

So naturally:

   Credits are due to Sven Lindberg <k8055 @ mrbrain.mine.nu> for writing
   libk8055. see <http://libk8055.sourceforge.net/>
   He did all the hard work of figuring out how to control the k8055,
   and how to calculate the debounce values for the counters.
   I used his work as a guide for some of the USB code in this driver.
   I also used his method of calculating the debounce values.

   libk8055 is

   Copyleft (C) 2005 by Sven Lindberg
      <k8055@k8055.mine.nu>

   Copyright (C) 2007 by Pjetur G. Hjaltason
      <pjetur@pjetur.net>
      Commenting, general rearrangement of code, bugfixes,
      python interface with swig and simple k8055 python class


What does this driver do:
=========================

When the driver is loaded, it wil create the directory '/proc/k8055'.

Each connected K8055 creates an other subdirectory named after the address the
board was set to with the SK5/SK6 jumpers. The address range of the K8055 is
0...3, so with the maximum of four connected boards the '/proc/k8055' 
directory looks like:

   '/proc/k8055/0'      K8055 at address 0
   '/proc/k8055/1'      K8055 at address 1
   '/proc/k8055/2'      K8055 at address 2
   '/proc/k8055/3'      K8055 at address 3

Each of these directories contains the following files:

   'inputs'
                                 Read:  Current status of all digital inputs.
                                 Write: -

   'in1' ... 'in5'
                                 Read:  Status of a specific digital input.
                                 Write: -

   'outputs'
                                 Read:  Current status of all digital outputs.
                                 Write: (Re)set several digital outputs at once.

   'out1' ... 'out8'
                                 Read:  Status of a specific digital output.
                                 Write: (Re)set a specific digital output.

   'adc1' and 'adc2'
                                 Read:  Status of ADC 1 and 2 (8bit resolution)
                                 Write: -

   'dac1' and 'dac2'
                                 Read:  Status of DAC 1 and 2 (8bit resolution)
                                 Write: Set DAC 1 or 2 to specific value (8bit)

   'counter1' and 'counter2'
                                 Read:  Status of counter 1 and 2 (16bit)
                                 Write: Resets the counter to 0
                                 (counter1/2 counts digital input 1/2)

   'debounce1' and 'debounce2'
                                 Read:  Debounce time for counter 1 or 2.
                                 Write: Debounce time for counter 1 or 2.
                                 (times are in milliseconds (0...7450))

Some usage examples:

   'echo 255 > /proc/k8055/0/outputs'        Set all digital outputs on the
                                             K8055 at address 0.

   'cat /proc/k8055/3/in4'                   Display the status of digital
                                             input 4 of K8055 at address 3.

   // C Example to set all digital outputs on board #2
   FILE *fp = fopen ("/proc/k8055/2/outputs", "r+");
   fputs ("255", fp);


Problems with other drivers (usbhid) in combination with k8055d:
================================================================

!! This problem should only occur on 'normal' PC's, on OpenWrt the module is
inserted __before__ usbhid. !!

After trying to load k8055d on my PC for the first time, I very quickly 
discovered that usbhid kept 'stealing' the device. The k8055d driver did not 
even get a chance.

Luckily, the commandline tool from libk8055 showed me a way to detach the
K8055 device from the usbhid driver from userspace.
I haven't tried to do this from kernelspace and don't even know if this would
be possible. In a futere version of k8055d however, this would be a preffered
method if I don't find a better way. (Perhaps it would be possible to 
blacklist the K8055 for usbhid at runtime, when the k8055d module is inserted)

For now you can use the k8055-detach utillity to accomplish this. The utillity
reports any connected K8055 devices and then detaches them from the driver they
are currently assigned to. This must be done before inserting the k8055d module.

Starting from version 0.1.3 there another utility is provided to assist in
loading the k8055 kernel module.

k8055-connect is a shell script that first disconnects any K8055 board using
k8055-detach, and then (re)loads the K8055 kernel module.

How to compile and install the driver:
======================================

A. for OpenWrt:

   I have only tested this version with Kamikaze Backfire 10.3.1-rc3 (linux 2.6)
   on an Asus WL-500G Premium WiFi router.

   Unzip the k8055d sources to the 'package' directory of your buildroot.
   Then from the top directory of your buildroot, execute 'make menuconfig'.
   The driver is located in 'Kernel Modules--> other modules--> kmod-k8055d',
   select it to build as a module (M) and exit.

   You could just execute 'make' now to build OpenWrt, this process will 
   eventually build this package, but will take a long time to complete.
   A faster method would be to execute 'make package/<name>-compile',
   where <name> is the directory name of the package to build (k8055d-0.1.3).
   When the driver is successfully build the binary package is located in the
   'buildroot/bin/packages' directory.

   To install the package, copy it to the /tmp directory of your device and
   execute 'opkg install /tmp/kmod-k8055d_0.1.3_<linux version>.ipk' on the
   device.

   Compiling the driver using the OpenWrt SDK is currently untested.
   How to get a working buildroot is beyond the scope of this readme,
   please consult the OpenWrt documentation for more information.

B. for ia32/amd64 P.C.

   This package mainly targets OpenWrt but since it was easier/quicker
   to be able to test the driver on a 'normal' computer there is some added
   support for building this module on a 'normal' PC.
   The last time this was tested was on oktober 28th 2010 using a fresh
   Debian testing install (ia32 and amd64) and using the following commands:

   su
   apt-get install module-assistant libusb-dev sudo
   module-assistant prepare
   exit
   tar -xf <path to k8055d.tar.gz>
   cd <path to k8055d source>
   make
   su
   make install
   exit

   To load the driver (this must be done after the board is plugged in):

   su
   k8055-connect
   exit

   This will first disconnect the K8055 board from its current driver (usualy
   usbhid) and then removes and re-inserts the k8055d kernel module.
   Re-inserting the kernel module causes usbcore to assign the board to k8055d.