K575 Version 1.1-beta and 2.0-beta: README and HOWTO Contents ******** Overview What do I have to do to install the whole thing ? What does the Makefile do? What is left for me to do? Which new functions can I use now? Errormessages Warnings Overview ******** The Keithley Model 575 (K575) is a Measurment and Control System can read and generate analog and digital Signals. It consists of *-one-* analog-digital-converter which can be multiplexed on 16 input-channels and has five digital-analog-converters. The analog-digital-converter supplies 16 bit values (0..65520!!) and the digital-analog-converters expect 12 bit inputs (0..4095). Furthermore the K575 has 4 digital-channels with 8 bit. Each of these can be used as input or output. As a default channel 0 is for input and channel 1 is for output. What do I have to do to install the whole thing ? ************************************************** 1. Open your PC and insert the 8 bit card provided by Keithley. Choose an unused interrupt. If you have a PCI-PnP board, do not forget to tell the BIOS to reserve an interrupt for the card. 2. Check on your Linux-Kernel: To install the module you have to enable modules and version-control when compiling your kernel. Thus the module has to be compiled on a system with the same kernel-version as the one you want to use it on. You are on the safe side if you compile the module on the system you are planning to use it on. Of course you need a C-compiler gcc (> version 2.6.3). 3. Now you really only need to run the 'make all' as root. Please look at it first to make sure it does not overwrite anything you need. What does the Makefile do? ************************** 1. The makefile compiles all the software you will need: a) K575 -- the kernel module b) k575lib.o -- the library with all the *new* C-functions to control the Keithley-box c) k575lib.h -- the headers for all these new functions 2. The makefile copies everthing where it belongs i) /usr/local/sbin/K575 ii) /usr/local/include/k575lib.o iii) /usr/local/include/k575lib.h 3. The makefile makes a new character-device in your /dev/ called K575 with the following command: mknod /dev/K575 c 31 0 4. The makefile inserts the K575 module into your kernel. What is left for me to do? ************************** 1. You have to insert some lines in your boot-script e.g.[/etc/rc.d/rc.local:] if [ -f /usr/local/sbin/K575 ]; then insmod /usr/local/sbin/K575 echo " inserting Keithley module" fi 2. Write a small C-programme to test the installation or compile the demo-programme in the user directory. There is a makefile for this, too. Do not forget to include the include in your C-programme and include the /usr/local/include/k575lib.o when you compile it. Which new functions can I use now? ********************************** void K575_StartTimer(); This function starts the timer. If controlling a system you often want to tell it how often it should read new data etc. int K575_Time_ms() Here the time in msec since you started the timer is returned. void K575_open() With this command the data-exchange between PC and Keithley-Box is started. void K575_close() This ends the data-exchange. void K575_Write_mV (int channel, int voltage_mV); A useful function which allows you to set the voltage voltage_mV (-10000..+10000) in mV to channel (0..4). int K575_Read_mV (int channel, int gain, int filter); An other useful function which allows you to read the voltage from channel (1..15) compared to ground. The returned value is (-10000..+10000) the voltage in mV. The voltage may be from the range -10V to +10V or 0 to +10V depending on the gain. With the gain it is possible to programme the internal amplifier. Positive values for gain only measure voltages >= 0, negative gains can measure both posivive and negative voltages. Possible gains are 1, 2, 5, 10, 20, 50 and 100 as well as -1, -2, -5, -10, -20, -50 and -100. With the filter variable you can chose from one of the Filters the Keithley-box has, in order to filter disturbances of a high frequency. Possible values are 2 for 2 kHz and 100 for 100 kHz. If you want to switch between different input channels quickly, 100 kHz is recommended. void K575_SelectOut(int channel) Configures channel (0..3) as output-channel void K575_SelectIn(int channel) Configures channel (0..3) as input-channel void K575_SetByte(int channel, unsigned value) Sets all 8 bits of channel (0..3) to value (0..255) int K575_GetByte(int channel) Gets 8 bits from channel (0..3). Return value 0..255 void K575_SetBit(int bit) Sets a single bit. The bits are numbered according to the following function single-bit (0..31) = (8 * channel) + bit. void K575_UnsetBit(int bit) Unsets a single bit. The bits are numbered according to the following function single-bit (0..31) = (8 * channel) + bit. int K575_GetBit(int bit) Returns the value of a single bit (0..31) void K575_SetAnalog(int channel, unsigned voltage) Sets an internal register of the K575-box in order to change the output later. Channel may be 0..4, voltage 0..4095 with 0=-10V and 4095=+10V. void K575_OutAnalog() Changes the output of all channels to the value set in the internal register. void K575_WriteAnalog(int channel, unsigned voltage) Changes the output of *one* channel Channel may be 0..4, voltage 0..4095 with 0=-10V and 4095=+10V. void K575_Convert(int channel, int gain, int filter) This function converts a voltage between channel 0..15 and ground to digits and saves it in an internal register. The voltage may be from the range -10V to +10V or 0 to +10V depending on the gain. With the gain it is possible to programme the internal amplifier. Positive values for gain only measure voltages >0, negative gains can measure both posivive and negative voltages. Possible gains are 1, 2, 5, 10, 20, 50 and 100 as well as -1, -2, -5, -10, -20, -50 and -100. With the filter variable you can chose from one of the Filters the Keithley-box has in order to filter disturbances of a high frequency. Possible values are 2 for 2 kHz and 100 for 100 kHz. If you want to switch between different input channels quickly, 100 kHz is recommended. void K575_ConvertDiff(int channel, int gain, int filter) This function converts a voltage between channel 0..7 and channel 0+8..7+8 to digits and saves it in an internal register. With this function it is possible to measure voltages with different grounds. unsigned K575_IsConversionReady() A 0 is returned, if the one of the conversions from above has not yet finished, otherwise you get something != 0. unsigned K575_GetConvertedValue() This function returns the value from K575_Convert or K575_ConvertDiff if the conversion has finished. Otherwise the programme aborts with an error message. The result is out of 0..65520. unsigned K575_ReadAnalog(int channel, int gain, int filter) A simple function to read a voltage between channel 0..15 and ground. The gain can be chosen as in void K575_Convert the same as the filter. The result is out of 0..65520. unsigned K575_ReadAnalogDiff(int channel, int gain, int filter) Analog to K575_ReadAnalog with the differece that you can measure voltages between channels 0-8, 1-9, 2-10 .. and 7-15. Errormessages ************* The only error recognized is missing power at the Keithley-box. No further errors are supported. Warnings ******** - If you switch between two inputchannels too quickly, you may get wrong return-values, as the Keithley-box has only one A/D-converter which takes some time to convert the voltage. Experience has shown that you can relie on the results if you simply measure a few times and forget the first few values. A Pentium 90 seems to supply good results if you measure 13(!) times and forget about the first 12 results. - When starting the Keithley-Box all the outputs are set to 0. This means that you have -10V(!) on every output channel! - When measuring the maximum voltage of +10V gives you an int of 65520 and not the expected 65535 (=2^(16) -1).