uniportio

^{Written by admin}

Uniportio

Universal parallel Port Input Output library by legolas558



http://uniportio.sourceforge.net/



Uniportio is an input/output (IO) C library wich offers a common API to
have real mode
and permission-restricted access to parallel port under Windows, Linux and
MS-DOS
operative systems.



Download from SourceForge.net

How to compile

Since uniportio
is a C library, you will need a C compiler (we suggest the usage of GCC for any operative
system you may be targeting to) and possibly an IDE (on
Windows
platforms, try Dev-C++
or MS
VC++ Express).



Then you may want to give a look to the example program provviden with
the library; there is also an example MSVC project.

Using the API

Using uniportio
in your program is quite easy, let's see the example program lpttest.c with a
brief
discussion for each significative block of code:

Including the definitions

#include "uniportio.h"

This preprocessor directive will tell the compiler to use the uniportio
library definitions, be sure to specify the correct path or have your
automatic includes directories correctly configured.



Depending on the defines your pre-processor supplies you may get the
message Warning: Using
raw port mode (unidentified OS); if you get this message
check your compiler definitions (linux
for Linux and WIN32
for Windows).

Choosing
the LPT port

#define			LPT_PORT			 0x378

We make a definition here to choose the LPT port memory address; if you
are using uniportio
on Linux you can also define LPT_PORT
as "/dev/parport0" or any other file-mapped device (see Linux notes), the library will
automatically recognize it.



Another possible value can be 0x278, meaning LPT2 on most PC-compatible
systems.

Starting the library

int main() {
			 unsigned char cr, dr, sr;
			 printf("lpttest uniportio example application
(c) 2005-2007 legolas558

");

This is a standard console application program, nothing to say
about it. If you are going to distribute your application you
should display somewhere a credits message about uniportio, as
explained in the license.

			 
			 if (!upio_start(LPT_PORT, 1)) {
			 			printf("uniportio: %s
", upio_error);
			 			return -1;
			 } else
			 			printf("uniportio: port %x initialized
", LPT_PORT);

The above code will try to initialize the underlaying communication
system and eventually show the error (and exit) if the initialization
fails. The most common errors are DeviceIOControl Error
under Windows and Cannot
open/claim access errors under Linux, meaning
that your device is misconfigured or that the port is in use. Useless
to say, on MS-DOS there will never be such problems because it is not a
multi-tasking OS.



The first parameter of upio_start()
is the port (see above Choosing
the LPT port) while the second can be 1 or 0 depending if you
are querying for priviledged
(1) or unpriviledged
(0) parallel port access; priviledged port access will make exclusive
usage of the port (it is the suggested mode to use), however may
not be always available depending on your OS and/or
user rights/configuration.



See Linux notes to
understand how to query for unpriviledged parallel port access.



There is also an extended function, upio_start_ex(),
which allows to get the port write and port read function vectors.

Reading something

			 cr = upio_portreadb(UPIO_CONTROL_REG); 
			 dr = upio_portreadb(UPIO_DATA_REG); 
			 sr = upio_portreadb(UPIO_STATUS_REG); 

With the above three lines of code we have read three bytes from the
parallel port, querying for each of the three LPT registers. Note that UPIO_CONTROL_REG, UPIO_DATA_REG and UPIO_STATUS_REG are
currently the only three valid constants for upio_portreadb()
and upio_portwriteb()
source/destination parameter (the first).



The return value (unsigned
char) of upio_portreadb()
returns us the byte read from the specified parallel port register.

Processing input

			 
			 printf("LPT control register is:	%x", (int)cr);
			 printf("LPT data register is:	%x", (int)dr);
			 printf("LPT status register is:	%x", (int)sr);

Now it is time to process the input data, this example program simply
prints out the bytes of each register, but you may probably need to
look for a specific bit (read more about parallel
port registers).

Sending output

	
	if (cr & 4)
	cr &= 0xFB;
	else
	cr |= 4;
	
	upio_portwriteb(UPIO_CONTROL_REG, cr);

In this example we will invert bit #3 of the control register
(nInitialize SPP signal) and write back the byte value. Use a
multitester to notice the effect.



The upio_portwriteb() function has no return value (of type void) and takes in
a second parameter (of type unsigned
char) which is the byte to be written on the specified
register.

Finishing

			 
			 upio_end();
}

Once finished using uniportio you should always call upio_end() or
otherwise other applications may have troubles at accessing
the parallel port.



This example is also available
online from here.

Windows notes

Unpriviledged mode is not available under win32 platforms,
this is an
OS limitation.

The win32 implementation is based on the (c) http://logix4u.net
implementation.



You will have to define WIN32 in order to compile the source code for
Windows; also remember to link against advapi32.lib.

Linux notes

Querying for priviledged parallel port access (through the memory
address) may fail if you are not root; don't worry, you can use
uniportio also as a simple user, read the below explanation.

Mounting parport

If you do not have a mounted parport on Linux, use:

	 mknod /dev/parport0 c 99 0

	 chmod 666 /dev/parport0

And, only if needed:

	 rmmod lp

	 modprobe parport

This will allow you to use the following uniportio API call:

	 upio_start("/dev/parport0", false);	 

MS-DOS notes

Unpriviledged mode is not
supported under MS-DOS due to the nature of the DOS operative system,
which always grant priviledged access to the parallel port.

Development status

Integration with C/C++ is painless, for other languages a DLL exposing the uniportio API is under construction and should be available soon.

Development status

The upio_getpin()
and upio_setpin()
functions should ease the task of getting/setting a specific pin status
but they are currently not working (mostly due to programmer's
lazyness), they need further testing. Just use upio_portreadb()
and upio_portwriteb()
which have been successfully tested on Windows and Linux.



If you find a bug please submit a (detailed) bug report to the project
bug tracker, for any other information/comment feel free to
contact the author.



Uniportio is
open source, the code gets updated (not very often) via SVN,
you may want to give a look and possibly help
testing/developing too.

License

Uniportio is
released under a BSD-like license (see LICENSE.TXT in the
distribution packages), basically you can use it for free but not for
commerical purposes without the author's express written consent.

Last updated ( Monday, 01 October 2007 )