A CUPS and eCS (OS/2) How To

Author: Peter Brown
email: losepete@…

Revision 1	14/08/2008	Peter Brown
Revisions to filenames	29/12/2008	Paul Smedley
Revisions to USB section	29/03/2009	Paul Smedley
Revisions to the list of required software and brief description of software sections	11/04/2009	Ed Durrant
Additional details about using USB interface and visual instructions around set up of CUPS web admin printer install	12/04/2009	Ed Durrant
Additional visual instructions around set up of OS/2 printer object to use CUPS attached printer	13/04/2009	Ed Durrant
Changes to the desktop printer object setup based on the later versions of the files for clarification	10/07/2009	Ed Durrant
Various formatting improvements and clarifications	2010-11-08	Alex Taylor
Formatting improvements and clarifications, continued	2010-12-11	Alex Taylor
Added warning about the (hard-learned) pitfalls of prndrv -d	2011-02-17	Alex Taylor

CONTENTS

Brief Preamble

Why install CUPS? - and what is it?

List of required software

Brief description of the software packages

Installation

Configuration of CUPS Printer

Local printers - Parallel attached

Local printers - USB attached

CUPS printer install - Network attached and USB attached

Step by step visual CUPS printer setup in web admin program (USB or Network connected)

Creating a Desktop Printer Object to use with CUPS

Step by step visual OS2 printer object setup for a CUPS attached printer

Brief Preamble

Hopefully this text will provide a clear enough "How To" for anyone to be able to follow.

I am using my experience of getting a Canon PIXMA iP4000 inkjet printer working with, firstly, CUPS and then creating an OS/2 Printer Object that is capable of outputting print jobs through CUPS.

I do use specific Drive Letter(s) in the following text that may need to be changed to reflect the correct drive letter on your systems. Most of the Paths used are specific to the CUPS installation; those that are not may need to be changed for your systems.

Why install CUPS? - and what is it?

​Common Unix Printing System answers the "what is it?" bit. It's a generic framework for printer driver packages. You install CUPS plus a driver package that supports your printer, and if all goes well you can print. :-) See the CupsFaq for more information on how it works specifically.

What does it support? - Support for actual printers is handled by the individual driver packages.

• List of supported printers under Gutenprint: ​http://gutenprint.sourceforge.net/p_Supported_Printers.php (Gutenprint is the biggest and most commonly-used driver package)
• List of supported printers under Splix: ​http://splix.ap2c.org/ (Splix supports some Samsung and Xerox printers)
• List of supported printers under HPLIP: ​http://hplipopensource.com/hplip-web/supported_devices/index.html (HPLIP supports various Hewlett-Packard printers)

Why install CUPS? - Simply because it is capable of supporting a lot of modern printers and is being continually updated to support more. The old OS/2 printer drivers are not that good with new printers. If you are lucky enough to find a driver that works with your modern printer, those drivers will not be updated to take advantage of all the features whereas the CUPS driver will.

CUPS can provide drivers for more current printers - and should provide many extra capabilities missing from the OS/2 drivers.

It basically works by tricking the OS & applications into thinking that the printer is a PostScript printer, even if it isn't. PostScript is a well-supported, standardized printer language; the object of the exercise is to end up with an eCS(OS/2) PostScript printer object that prints using CUPS.

List of required software

The CUPS port is available at ​http://svn.netlabs.org/ecups/wiki/CupsPort - you can download in WPI format (all packages) or as individual ZIP files. If you download the individual files, remember that you need the following packages.

Always required:

• CUPS OS/2 binary

• GhostScript OS/2 binary

• At least one of the following driver packages (choose the one which supports your printer):
  • Gutenprint (many printers)
  • Splix (Samsung/Xerox printers) - also requires custom GCC runtime: ​http://smedley.info/gcc432.zip
  • HPLIP

• eCups port driver (CUPS.PDR)

• eCups print driver (ECUPS.DRV), CUPS-specific PostScript printer driver

• Libc files required for CUPS - ​ftp://ftp.netlabs.org/pub/gcc/libc-0.6.3-csd3.zip (you may have these already, especially if you are running eComStation)

May be required

• USB helper driver (required for USB printing only) - ​http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip (again, you may have this already if you use a recent version of eCS)

• PRNDRV.EXE (this is a program that will "clean up" printer entries in the INI files) - ​http://www.os2site.com/sw/comm/faxworks/prndrv.exe

• USB backend (if you are intending to use a USB connected printer) - ​http://download.smedley.info/cups-usb-backend-20090309.zip (Note: This is only required for older versions of CUPS. The latest (1.4.4 and up) releases of the CUPS zip file include the USB backend, so this download is not needed. However the tests here were performed when that was not the case, so I have left this link in for reference in any case).

These are described in more detail below.

Brief description of the software packages

CUPS consists of several packages that work together to provide emulated PostScript printing on raster printers. The core components on all platforms are the CUPS daemon, GhostScript, and the driver packages (Gutenprint, Splix, HPLIP etc.).

The remaining packages are specific to the OS/2 port (a.k.a. eCups):

• The Libc and GCC files are required support files (the GCC runtime is required by Splix).

• PRNDRV.EXE - a useful command line utility for listing installed printers and deleting those that are no longer wanted. (Note: Be careful when using 'prndrv -d', as it is very easy to accidentally delete the key PM_DEVICE_DRIVERS -> ECUPS [= path to ECUPS.DRV] from OS2.INI - which will prevent all ECUPS printers from working, until you either fix the INI file manually or install a new ECUPS device.)

• The eCups printer driver (ECUPS.DRV) is a customized version of the OS/2 PostScript driver (PSCRIPT.DRV) which has most of the popular CUPS PPD files already included, and can be updated as new printers become supported in CUPS. It also has a few tweaks and bugfixes to make it work better with CUPS. (For this reason, using the original IBM PostScript driver for CUPS printing is not really recommended, although it may happen to work for you.)

• The eCups printer port driver (CUPS.PDR) provides the "hook-up" between an OS/2 Printer Object and the actual CUPS printer.

The port driver component in particular is crucial, because normal OS/2 applications only know how to print to an OS/2 Printer Object - not a CUPS printer! What happens is that the OS/2 Printer Object sends print data to a port (like a parallel/serial/USB port or an LPR network queue, and so on) which is defined by a port driver. In this case, we are implementing another type of port to be available alongside these. This driver allows the OS/2 print "engine" to talk to the CUPS daemon, which turn talks to the physical printer either over the network or over a USB connection (using what it calls a "backend", which is basically CUPS's own internal equivalent of a port driver).

Note that we don't use the OS/2 USB port driver when using a USB attached printer via CUPS - we always use the CUPS port driver and then let the CUPS daemon control the physical IO traffic to the printer. The same is true for other connection types like network connections - in all cases, CUPS manages the connection.

As far as CUPS goes internally, the data flow is as follows:

PRINTER <-> IO Driver "backend" <-> CUPS daemon (CUPSD.exe) <-- CUPS admin webpage (config, test print etc.)

The above suffices for printing using CUPS's own internal mechanisms. What the port driver does, in conjunction with an OS/2 Printer Object, is allow normal OS/2 programs (which know nothing about CUPS) to print to CUPS printers. So the data flow becomes:

PRINTER <-> IO Driver "backend" <-> CUPS daemon (CUPSD.exe) <-> eCups Port Driver (CUPS.PDR) <-> PostScript printer driver (ECUPS.PDR) <-> OS/2 printer support <-> OS/2 application.

Installation

There is now a !WarpIN package available (see the CupsPort page) but it is still somewhat experimental, and may not contain the latest versions. The instructions below assume you are installing manually, i.e. from zipfiles.

• The basic CUPS install (using Gutenprint) consists of unzipping the packages in the root directory of a drive (doesn't have to be the boot drive):

• GhostScript needs to be unzipped into \gs - so that you end up with for example, x:\gs\gs8.70 (some zip packages contain the \gs upper directory, some don't - so make sure you end up with the correct directory structure).

• cups-*.zip needs to be unzipped into the root directory, thereby creating the \cups directory

• gutenprint*.zip needs to be unzipped into the root directory, which will create the \gutenprint directory as well as add some required files to the \cups directory.

At the end of this process, you should have 3 new directories of the root directory of your chosen drive:

\cups
\gutenprint
\gs

• Have a read of the \cups\readme.os2 before proceeding to get an idea of what you are going to do; especially if attempting to setup a USB printer.

• If installing PRNDRV.EXE, put this file somewhere that you can find it; I put it into J:\Programs\Utils\PrnDrv

• The libc0*.dll and GCC*.dll files should be put into a directory specified within the LIBPATH - either \ecs\dll or \os2\dll are good choices.

Other files can be unzipped now or later as they are required as follows:

• The eCups printer driver can be put into a directory of your choice. You will then point the printer install dialog at this directory during the install process; OS/2 will then automatically copy the files to `\OS2\DLL\ECUPS' (which it will create if necessary).

• The eCups printer port driver - copy cupslpr.exe into \tcpip\bin and cups.pdr into \os2\dll

The Splix package should be installed in place of the Gutenprint package if you are installing one of the Splix-supported Samsung or Xerox printers; ditto for HPLIP. Note: This how-to doesn't cover Splix or HPLIP usage yet.

Configuration of CUPS Printer

Local printers - Parallel attached

CUPS does not currently support printing directly to Parallel printers but there is a workaround.

1] Create a Printer object using the Null printer driver and select the LPTn port as the Output Port in the printer object Properties

2] Start the OS/2 lpd daemon (\tcpip\bin\lpd.exe). To prevent lpd.exe from printing the control file page (an almost blank page with few lines of information good only for debug purpose) specify also the "-c" parameter.

When creating the CUPS printer in the below section (CUPS printer) use lpd://localhost/<printer_name> as the Device URI: where <printer_name> is the Physical name of the OS/2 Printer object - as shown on the Properties, View page - created in 1] above. Note this may not be the same as the name given to the printer during creation.

e.g. If you created a printer with the object name Canon iP4000 in the Printers folder open the Properties for that printer and check the name displayed on the View page - it shows CanoniP4 here. So in the above example the device URI should be

lpd://localhost/CanoniP4

Thanks to Rodney and others who supplied the above information regarding using locally attached printers with CUPS.

Local printers - USB attached

This set-up was performed on eComStation 2.0 RC6a. It has been reported that some older versions of the operating systems USB support files can cause problems, so please ensure you download and install the latest USB OS level support before you attempt this configuration. (ie ​http://en.ecomstation.ru/projects/usbtools/download/usbcalls-20060807.zip)

If you have a USB cable attached printer load the USB backend expand the zip file into the \cups\lib\cups\backend directory.

Note I have been told that on the latest release of the CUPS package, the usb.exe file is included so you don't need to download it - so just make sure it is in the \cups\lib\cups\backend directory.

Now go to this directory on the command line make sure your printer is turned on and run usb.exe with no parameters and you should get a display something like this:

[J:\cups\lib\cups\backend]usb.exe

INFO: list_devices INFO: usb_find_busses=1 INFO: usb_find_devices=1 INFO: open_device

direct usb://HP/Officejet%206300%20series?serial=CN88TFB0P504J4&interface=1 "HP
Officejet 6300 series" "HP Officejet 6300 series" "MFG:HP;MDL:Officejet 6300 ser
ies;CMD:MLC,PCL,PML,DW-PCL,DESKJET,DYN;1284.4DL:4d,4e,1;CLS:PRINTER;DES:Q8061A;S
N:CN88TFB0P504J4;S:038000C484001021002c1800007c2880011;J: ;Z:
0102,0503d549016449,0600;BT:000000000000,4F66666963656A6574203633303020736572696
573,0000008F,60;" ""
INFO: close_device

If you don't get such a display, check that your USB support is working correctly and that you have connected the printer with a known good cable to a known good port.

By putting usb.exe into the backends directory when cupsd.exe starts it knows that when asked by the web administration page, that it should check USB ports as well as network and other ports for new devices.

CUPS printer install

Start \cups\sbin\cupsd.exe

I created a program object for this with the Start Minimized and Close Window on exit checked in the Properties, Session tab; the object Properties should also have the Working directory set as Drive:\cups\sbin (where Drive is the drive letter that cups is installed to). This object can be put in the Startup folder so that cupsd.exe is started automatically at bootup.
You can of course also auto start this at boot-up by putting the following lines in \startup.cmd (or in the network startup file \MPTN\BIN\setup.cmd)

CD \cups\sbin
start /min cupsd.exe

I recommend using the CUPS browser interface to Add a Printer. Fire up your browser and point it at ​http://localhost:631/ (cups home page) and when that has loaded click Add Printer.

I added the following (network connected) Canon PIXMA P4000 colour inkjet (raster) printer and will be using this printer as the example. The text after the "-" is to outline the purpose

Name: PIXMA - what you want to call the printer

Location: Router LPT1 - where it is physically located; ie connected to the Router's LPT1 port

Description: Canon PIXMA iP4000 Inkjet - brief description of printer

Continue - click when happy with above section

Device: Choose an appropriate selection for device connection: ie: LPD/LPR Host or Printer

IPP for USB printers - the detected printer should be available for selection. For other types of attachment, more information will be required.

• Example: Device URI: lpd://192.168.2.1/lpt1 - address of device for LPD printer

Continue - click when happy with above section

Make: Canon - select printer make - for USB printers, an attempt will be made to confirm the correct PPD file to use

Continue - click when happy with above section

Model: Canon PIXMA iP4000 - CUPS+Gutenprint v5.2.0-beta3(en) Simplified - select correct driver; Simplified recommended

Add Printer - click when happy with above section

After clicking Add Printer the interface informs me that the printer has been added and loads the options for the printer - this can take a little while. It is a good idea to have a look through and make sure the options look useable - especially Media Size, Resolution and Image Type. When satisfied click Set Printer Options and the interface reports "Printer PIXMA has been configured successfully."

I then clicked on the Printers tab and then clicked the Print Test Page button. Shortly after the Test Page popped out of the printer looking fine.

Well, that is the very easy bit finished...

Referring to the readme.os2 file I used the command line to print a 2 page document; I opened a command line window in \cups\bin and gave it a try:-

[H:\cups\bin]lpr -P PIXMA \cups\share\cups\data\PReCS20.ps

After a short wait the printer burst into action and delivered 2 pages of output that look fine.

That is the next easy bit finished...

Step by step visual CUPS printer setup in web admin program (USB or Network connected)

First of all start your web browser and point it at ​http://localhost:631/

Now click on the administration tab

Then click on "Find new printers"

In this case, as my printer is both connected to the network and connected by a USB cable to my PC, both connections are listed - select whichever you wish to set up at this point.

A description is already filled in for you, but feel free to change the text as you wish.

Select the correct printer driver - in my case as my Officejet 6310 is not listed I use the OJ 7110 instead - I have found this works fine
(you can always change this later to find the best match for your printer).

Set up the default printer options that you want to use.

That's it ! You have now set up your printer under CUPS - press the send test page and hopefully you'll get a nice printout. The next stage is now to set up the OS/2 print object to print to the CUPS Daemon - see those details later in this documentation.

Creating a Desktop Printer Object to use with CUPS

Now to hook CUPS up to the rest of the system so that CUPS can be used for output by applications such as OpenOffice Writer (wordprocessor) and PMView (images).

1] Unzip the eCUPS printer driver package (At time of writing ecups-20090323.zip) into \os2\dll\ecups - this avoids any problems with any existing postscript driver in \os2\dll\pscript.

2] Either double-click the 'install printer' object in the printers folder and select local printer or Open the Desktop -> Templates folder and drag the Printer template to the Desktop to start the Create printer routine. Press the 'install new printer driver' button. Select 'other ecomstation printer driver'. Enter \os2\dll\ecups in the directory field and click Refresh in order to see the list of printers.

Name the printer - PIXMA in this case

Select the output port - I used LPT1 initially and installed the cups printer port later

Select the (pscript) driver for the printer - Canon PIXMA iP4000

3] Unzip the eCuPS printer port package (currently cupsportdriver-20090410.zip) putting the files into the following locations

cups.pdr into \os2\dll

cupslpr.exe into \tcpip\bin

4] Right Mouse Button on the new Desktop Printer Object and select Properties

Select Printer driver tab

Check the Default printer driver is correctly selected

Set Job Properties: Paper Size, Tray, Media Type, Resolution must match the settings in the CUPS printer - and Save

Select Output port tab

Click Install new port button

Select the CUPS port and click Install

each additional CUPS connected printer that you wish to install will get its own CUPS port CUPS1, CUPS2, CUPS3 etc.)

• if the port is not visible but the CUPS.pdr file is in \os2\dll click on install new port/New port drivers and set the directory to \os2\dll and click Refresh. The CUPS port should appear, select this and press install.

Right mouse button on CUPSx CUPSPORTx and select properties. The required settings for the CUPS port are

Host: localhost - or use 127.0.0.1

Printer: PIXMA (this should be the same name as used for creating the CUPS printer in the CUPS admin above) press OK.

Leave 'send as binary file" selected.

Close Printer Properties

That should be setup complete so time to print a test page

Verify that cupsd.exe is running *Before* testing

Drag'n'Drop \cups\share\cups\data\testprint.ps onto the new Desktop Printer Object

Select Printer-specific in the following dialog

You should get the CUPS Test Page printed from your OS/2 Desktop Printer Object

The next test is to print a multiple page document from your favourite wordprocessor, followed by printing any other document types from an appropriate application, eg Photos from PMView, using your new OS/2 Desktop Printer.

Step by step visual OS2 printer object setup for a CUPS attached printer

Open the printer folder and click on add printer:

Select local printer.

Click on install printer driver, click on "other printer driver location" and type in where you put the eCUPS printer driver (I suggested \OS2\DLL\CUPS earlier) - then press the refresh key. all the printers in the CUPS file will now appear, scroll down and select the printer driver for your printer (or a near model), and press Install.

Press OK to load the driver. Now change the printer name field to something reasonable from "printer" that is currently in the field and press the create key and your printer object will be created and the install dialog will close (but you haven't finished yet ....).

Open the properties of your new printer object and select the "printer driver" tab, make sure the new driver is highlighted in both boxes.
You can press the job properties button as this point if you wish but you'll find the settings are the same as you set when you created the printer in the CUPS admin webpage. If you look at the properties of the Printer driver you can also set some printer parameters. In general I leave these areas as they are.
Now press on the "output port" tab and press install new port:

Because you put the eCUPS Port Driver into OS2\DLL earlier, you will now get a whole lot of CUPS drivers to chose from - simply highlight CUPS1 and press "install"

Double click the new port driver and you will get its configuration panel - this is where we link the OS/2 print system to the CUPS print system! - The first field says "localhost" we will leave that as it is as the printer is connected to this PC - if it was connected to CUPS running on another PC, you could put that PCs IP address or hostname in here. What is important is the second field - this is the name of the printer within the CUPS configuration - you'll see I have loaded up the CUPS web admin page in manage printer to show you this - in this case the name is "HP_Officejet_6300_series". Press "save properties" and close the printer setup panels and you are finished. just to prove this ....

Here is the printer dialog in Firefox with the new CUPS connected printer available to print the same as any other OS/2 printer !

Have fun and thanks to Paul Smedley for all his good work !