Lets assume, no printing device is attached to the system. Running capsprinter to list all currently attached and online printer devices will result into an empty list:

$ capsprinter list
No printer available

Note: If capsprinter returns with an error message instead, the so called DBUS Activation doesn't seem to work.

But in the background this command triggers the CAPS Printing Coordinator as a service. Something like the following should happen in the journal.

$ journalctrl
[…]
CAPS dbus-daemon[82]: [system] Activating via systemd: service name='org.caps.printing' unit='caps-printing-coordinator.service' requested by ':1.27' (uid=0 pid=xxx comm="capsprinter list ")
CAPS systemd[1]: Starting caps-printing-coordinator.service...
CAPS caps-printing-coordinator[17000]: CAPS printing coordinator daemon startup...
CAPS dbus-daemon[82]: [system] Successfully activated service 'org.caps.printing'
CAPS systemd[1]: Started caps-printing-coordinator.service.

Similar actions happen, if you connect a printer device to your system.

Note: Verbosity is "info"

If the components of the CAPS universe are already present at your host, but no matching printer driver yet, you will get the following systemd journal entry:

CAPS kernel: usb 1-1: new full-speed USB device number 2 using musb-hdrc
CAPS kernel: usblp 1-1:1.0: usblp0: USB Bidirectional printer dev 2 if 0 alt 0 proto 2 vid 0x04F9 pid 0x0027
CAPS systemd[1]: Created slice system-caps\x2dprinter.slice.
CAPS systemd[1]: Starting Printing Driver at /dev/usb/lp0...
CAPS caps-printer-prep[150]: Reading config settings from INI file '/etc/caps/caps.ini'
CAPS caps-printer-prep[150]: Merging more config settings from INI file '/etc/caps/capsmanagement.ini'
CAPS caps-printer-prep[150]: Starting printer discovering process for device node '/dev/usb/lp0'...
CAPS caps-printer-prep[150]: Error: no printer driver available for the discovered 'HL-2030 series' printer made by 'Brother'
CAPS caps-printer-prep[150]: Info: printer's USB vendor ID is 04f9, its USB product ID is 0027
CAPS caps-printer-prep[150]: Info: printer's serial number (less important) is: XXXXXXXX
CAPS caps-printer-prep[150]: Info: printer's IEEE ID is: MFG:Brother;CMD:PJL,HBP;MDL:HL-2030 series;CLS:PRINTER;
CAPS caps-printer-prep[150]: Solution: install a printer driver for this printer device first
CAPS systemd[1]: caps-printer@-dev-usb-lp0.service: Control process exited, code=exited status=22
CAPS systemd[1]: caps-printer@-dev-usb-lp0.service: Failed with result 'exit-code'.
CAPS systemd[1]: Failed to start Printing Driver at /dev/usb/lp0.

If the matching printer driver is already installed, the journal entry differs:

CAPS kernel: usb 1-1: new full-speed USB device number 3 using musb-hdrc
CAPS kernel: usblp 1-1:1.0: usblp0: USB Bidirectional printer dev 3 if 0 alt 0 proto 2 vid 0x04F9 pid 0x0027
CAPS systemd[1]: Starting Printing Driver at /dev/usb/lp0...
CAPS caps-printer-prep[167]: Reading config settings from INI file '/etc/caps/caps.ini' <---- LOUD
CAPS caps-printer-prep[167]: Merging more config settings from INI file '/etc/caps/capsmanagement.ini' <--- LOUD
CAPS caps-printer-prep[167]: Starting printer discovering process for device node '/dev/usb/lp0'...
CAPS caps-printer-prep[167]: Printer device at '/dev/usb/lp0' is already known. Preparation skipped.
CAPS systemd[1]: Started Printing Driver at /dev/usb/lp0.
CAPS caps-printer[169]: Reading config settings from INI file '/etc/caps/caps.ini' <--- LOUD
CAPS caps-printer[169]: Merging more config settings from INI file '/etc/caps/capsmanagement.ini' <--- LOUD
CAPS caps-printer[169]: Going to launch printer driver for device node '/dev/usb/lp0'...
CAPS caps-printer[169]: Info: driver configuration file: 'caps-brother-HL2030-driver.ini' <--- LOUD
CAPS caps-printer[169]: Info: device specific parameter directory: 'printer_6PqHu2' <--- LOUD
CAPS caps-printer[169]: - Brief description: 'Brother, HL-20 monochrome laser printer' <--- LOUD
CAPS caps-printer[169]: - Vendor: 'Brother' <--- LOUD
CAPS caps-printer[169]: - Device: 'HL-2030' <--- LOUD
CAPS caps-printer[169]: HL series driver is starting
CAPS caps-printer[169]: Reading the base settings from INI file '/etc/caps/drivers/capsdriver.ini' <--- LOUD
CAPS caps-printer[169]: Reading the default settings from INI file '/usr/share/caps/drivers/caps-brother-HL2030-driver.ini' <--- LOUD
CAPS caps-printer[169]: Merging more default features from INI file '/etc/caps/drivers/hl20-driver.ini' <--- LOUD
CAPS caps-printer[169]: Reading device specific INI files from parameter directory '/var/lib/caps/printer_6PqHu2' <--- LOUD
CAPS caps-printer[169]: HL series driver is up and running

Die Angaben über INI-Dateien könnte auch einfach "LOUD" und nicht INFO sein:

CAPS kernel: usb 1-1: new full-speed USB device number 3 using musb-hdrc
CAPS kernel: usblp 1-1:1.0: usblp0: USB Bidirectional printer dev 3 if 0 alt 0 proto 2 vid 0x04F9 pid 0x0027
CAPS systemd[1]: Starting Printing Driver at /dev/usb/lp0...
CAPS caps-printer-prep[167]: Starting printer discovering process for device node '/dev/usb/lp0'...
CAPS caps-printer-prep[167]: Printer device at '/dev/usb/lp0' is already known. Preparation skipped. <--- hier die Infos des Benutzers ausgeben? Also die Gerätespezifischen INI-Sachen eher "Preparation skipped eher" weglassen. Es fügt keine wirkliche Info hinzu.
CAPS systemd[1]: Started Printing Driver at /dev/usb/lp0.
CAPS caps-printer[169]: Info: description: 'Brother, HL-20 monochrome laser printer'
CAPS caps-printer[169]: Info: connected to: '/dev/usb/lp0'
CAPS caps-printer[169]: Info: vendor: 'Brother'
CAPS caps-printer[169]: Info: device: 'HL-2030'
CAPS caps-printer[169]: Going to launch printer driver for 'Brother, HL-20 monochrome laser printer'

Then the driver itself is launching:

CAPS caps-printer[169]: HL series driver is starting
CAPS caps-printer[169]: HL series driver is up and running

Todo:: How to get the CAPS Printer Device Parameter Directory of a specific printer? Should be in a library!

Tools at hand

Frequently Used Tools

If you want to print your document:

capsdoprint

If you need a backward compatible way to print your document:

lpr

If you need to get an overview about your printers:

capsprinter

If you need the name of the CAPS Printer Device Parameter Directory for a specific printer device

capsprndir

Sometimes Used Tools

A helper tool to get an overview about the CAPS universe directory setup:

capsinfo

A helper tool to collect setup and run-time information to create a bug report:

caps-report

Information at hand

  /
  |
  +--- etc
  |     |
  |     +--- caps                        (CAPS Configuration Directory)
  |     |      |
  |     |      +--- drivers              (CAPS Printer Driver Configuration Directory)
  |
  +--- usr
  |     |
  |     +--- bin                         (Tools Directory)
  |     |
  |     +--- lib                         (Library Directory)
  |     |
  |     +--- libexec
  |     |      |
  |     |      +--- caps                 (CAPS Printer Driver Executables Directory)
  |     |      |
  |     |
  |     +--- include                     (Header File Directory)
  |     |
  |     +--- sbin                        (Service Executables Directory)
  |     |
  |     +--- share
  |     |      |
  |     |      +--- caps
  |     |      |     |
  |     |      |     +--- drivers        (CAPS Printer Driver Database Directory)
  |
  +--- var
  |     |
  |     +--- lib
  |     |     |
  |     |     +--- caps                  (CAPS Printer Device Database Directory)
  |     |     |      |
  |     |     |      +--- printer_dhfgez (CAPS Printer Device Parameter Directory)
  |     |
  |     +--- spool
  |     |     |
  |     |     +--- caps                  (CAPS Document Storage Directory)
  |     |     |

Note: The printer_dhfgez" in the "CAPS Device Parameter Directory is an example here. Refer CAPS Printer Device Parameter Directory for more details.

CAPS Configuration Directory

Directory contains basic configuration INI files for all CAPS universe components.

The CAPS Printer Driver Configuration Directory is also located here as a subdirectory.

Refer Setup the CAPS Configuration Directory as well.

CAPS Printer Driver Database Directory

This directory provides Device Description INI files and thus, forms a database about installed/supported printer devices. For each printer device one of such file exists (if the suitable printer driver is installed).

Each INI file provides information about the supported printer device to enable CAPS to identify the suitable printer driver for it.

Each printer driver installs here its own set of Device Description INI files for all printer devices it supports.

It's not possible to share Device Description INI files, each of it is unique and describes exactly one printer device.

But it is possible to have more than one printer driver supporting a specific printer device. In this case more than one INI file exists, matching the same printer device, but refers to different printer drivers. For example, a printer device able to work with a vendor specific data protocol or PCL can be run with its native printer driver or the generic PCL printer driver. In this case the first printer device match always wins.

All INI files in this directory should be owned by root.

Refer Setup the CAPS Driver Database Directory as well.

CAPS Printer Device Parameter Directory

This is a unique subdirectory on a per printer device in the CAPS Printer Device Database Directory. It contains specific configurations for exactly one printer device.
All files from this directory are read-in and the read-in order follows the Sorted INI.

Note: The capsprndir helper tool can retrieve the directory specific for a printer device.

CAPS Document Storage Directory

Directory used to temporarily store the documents to print and other printing related files. This directory needs to be writable (guess why) and large enough to hold the files until they are printed.

Note: You will see files in this directory only, if debugging is enabled. Else all files are invisible and get removed in a self-removing manner automatically if no longer used.; This directory must be writable and should use a filesystem which supports invisible files (refer O_TMPFILE flag in the open() syscall or caps_helper_invisible_file_create()), it must be owned by lp and group lp.

Refer Setup CAPS Document Storage Directory as well.

CAPS Printer Driver Configuration Directory

This directory provides Driver Feature Configuration INI files for some printer driver default settings if appropriate. If settings do not match a printer device requirement, they can be overwritten on a printer device specific base (refer CAPS Printer Device Parameter Directory).

Each printer driver installs here its own driver specific configuration INI file with its default settings (if any). Its file name is referenced in the Device Description INI file. This driver specific configuration INI file can be shared between all driver users (e.g. printing devices), because it's read-only.

Refer Setup the CAPS Driver Configuration Directory as well.

CAPS Printer Driver Executables Directory

This directory collects the installed printer driver executables. They are referenced in the Device Description INI files in the CAPS Printer Driver Database Directory and thus, CAPS is able to run the printing device's matching printer driver.

Each printer driver installs here its own executable. It can be shared between multiple printer devices.

All executable files in this directory should be owned by root.

Refer Setup CAPS Driver Executables Directory as well.

CAPS Printer Device Database Directory

This directory stores the Printer Device Database, maintained by CAPS. And it contains printer device specific parameters in printer device unique subdirectories (refer CAPS Printer Device Parameter Directory for details).

Refer Setup the CAPS Device Database Directory as well.

All CAPS universe components including the printer drivers use a specific set of INI files for their run-time configuration. More than one of such INI file sets do exist.

It depends on the type of the CAPS universe component which set it uses.

The following sets not only mention the specific INI files, they show the read-in order as well. This order is important, because latter INI files can overwrite settings already made by former INI files.

‍Example: If you increase the verbosity in the base caps.ini, all CAPS universe components become more verbose.
If you increase the verbosity in a latter INI file, only some CAPS universe components become more verbose. Refer CAPS universe verbosity setup via INI File for details.

INI file set used by the Printer Preparation Tool

INI file set used by the Printer Driver Launcher

A printing provider/printer driver gets its run-time configuration from a set of INI files. Whenever a printing driver launches, libcapsprovider reads in these INI files and merges their content into one key/value database the printing driver can query. The content of the key/value database is intended to configure and parametrize the printing driver at run-time.

INI File name	Meaning	Expected Location
caps.ini	Shared initialization	CAPS Configuration Directory
capsdriver.ini	Shared class initialization	CAPS Printer Driver Configuration Directory
devicedriver.ini (see note)	Device Description	CAPS Printer Driver Database Directory
feature.ini (see note)	Driver Feature Configuration	optional, CAPS Printer Driver Configuration Directory
parameter.ini (see note)	Printing Device Parameters	CAPS Printer Device Parameter Directory

Note: The devicedriver.ini is only an example name for a Device Description INI file. Its real name correlates with the printing device.; The feature.ini is only an example name for a Driver Feature Configuration INI file. It is defined in the devicedriver.ini and is optional.; The parameter.ini is only an example for one of the Printing Device Parameters INI files. All INI files from the physical printing device's directory are read-in.

The Device Description INI file comes with its printer driver source package.

The Driver Feature Configuration INI files is an optional file and comes with its printer driver source package. It contains various default settings for features this printer driver (may) provides. If the printing device or printing driver has no special features, this file does not exist.

The Printing Device Parameters INI files are run-time specific and some of them are created by helper tools when the physical printing device occurs the very first time.

While the Device Description INI file and the Driver Feature Configuration INI file are static and not to be changed by the user, the Printing Device Parameters INI files are intended to be adapted and extended by the user.

Due to this behaviour a user can adapt/change/overwrite all default configurations made by the static INI files on a per printer device base.

A run-time configuration for one physical printing device can look like this:

${sysconfdir}/caps/caps.ini CAPS universe global base configuration

${sysconfdir}/caps/drivers/capsdriver.ini CAPS universe printer driver configuration

${datarootdir}/caps/drivers/caps_printer_XY.ini Device Description INI file
                                        \___ brief='Some Generic Brief Description'
                                        |___ vendor='Vendor's Name'
                                        |___ device='Device's Name'
                                        |___ Pointer to the 'printer_XY.ini' Driver Feature Configuration INI file

${sysconfdir}/caps/drivers/printer_XY.ini Driver Driver Feature Configuration INI files
                                   \___ Default settings for generic features

${localstatedir}/caps/devices/printer_xzdtz/service.ini Printing Device Parameters
                                              \___ name='My Own Printing Providers Unique Name'

${localstatedir}/caps/devices/printer_xzdtz/info.ini Printing Device Parameters
                                              \___ location='My Description Of The Printer's Location'
                                              |___ brief='My Brief Printer Description'

${localstatedir}/caps/devices/printer_xzdtz/feature.ini Printing Device Parameters
                                              \___ some user adapted features

Note: The printer_xzdtz directory name is an example only. Each physical printer device has its own unique directory; The used filenames in the parameter directory (e.g. info.ini and feature.ini) are examples only. You can name them as you like.

For more details about the content of the Device Description INI file refer Device Description INI files.

As mentioned above, the Printing Device Parameters INI files are intended to be adapted by the user. At most the following keywords need your attention:

Section [info]

An example

[info]
name=frieselfrasel
location=Inside your processor

Mandatory keys are

Key	Description
name	Unique name for this printing device, free text
location	Location description of the physical printing device, free text

names's value is used to register this printing device at the printing coordinator
location's value is forwared to the printing coordinator to describe the printing device's location

Since the name keyword at first uses an auto generated value, it is the first value, a user should change to his needs. Its value will be used later on as the printer's name in all printing and status commands (refer commands capsprinter, capsdoprint or lpr).

Refer the tool capsprndir how to retrieve the unique Printing Device Parameters directory matching a specific printer device.

Just print

From the user's point of view it is just simple to print some kind of document.

Note: It depends on a compile time configuration, what kind of documents are supported. PDF you can always assume as supported. And maybe PNG, PWG-raster and JPEG.

From a console you can use the tool capsdoprint.

 $ capsdoprint this_document.pdf

If your application uses the features of libcapsclient it can do the same.

Everything is easy if you run only one printer device at a time. All the tools then default to this printer device. If you run more than one printer at a time, then you always need to additionally define the specific printer device you want to print to.

Note: There isn't something like a default printer. Because it makes no sense. If this printer isn't connected or simply offline, you can't print to it.

You can adapt the way your document gets printed to the printer's medium. For this, you can use the so called printing parameters.

Goal: what you see is what you get

Simple use cases

Trouble Shooting

This section should help you when it comes to trouble using the CAPS universe.

Messages you may face

More trouble to be solved

Developer's programming failures

Run-time related errors

Run-time related warnings

Run-time related information

Brother HL Laser Printer Trouble shooting

Samsung ML Laser Printer Trouble shooting

USB Printer Driver Start

For a full helpful bug report some environment information are useful to help the developers to find the root cause of the bug.

Thus, please include the output of the following tools to your bugreport:

capsinfo.sh: Get the pkgconfig Setup

caps-report: Extract Setup and Run-Time Information

TBD: Where to send to (email)

Early verbosity Setup

Using the other available methods to change the verbosity might be too late for the interesting part of your own application start-up. In this case you can use an environment variable to do some kind of early verbosity setup.

The environment variable CAPS_START_VERBOSITY can be used to overwrite the regular start-up verbosity level of LIBCAPS_VERBOSITY_DEFAULT. You can use the same verbosity words as defined in CAPS universe verbosity setup via INI File to define the start-up verbosity level.

For example:

CAPS_START_VERBOSITY=noisy caps-printing-coordinator

Verbosity Setup via INI

All executables related to the printing coordinator use a shared and an individual set of run-time INI files to support a generic way to configure their verbosity level.

By adding the following entry to a carefully selected INI file, you can limit the verbosity change to a specific component of the CAPS universe or set it for all components at once.

‍Examples: if you modify the caps.ini file, all CAPS universe components are affected. When modifying the capsdriver.ini file instead, only printer drivers are affected (but all at once), but not the printing coordinator itself.

The entry to add is the section [debug] and the keyword verbosity:

[debug]
verbosity=<level>

The supported level words are:

panic sets up LIBCAPS_PANIC
error sets up LIBCAPS_ERROR
warn sets up LIBCAPS_WARN
info sets up LIBCAPS_INFO
loud sets up LIBCAPS_LOUD
noisy sets up LIBCAPS_NOISY
debug sets up LIBCAPS_DEBUG

Note: The 'debug' verbosity word only works if debugging support was enabled at build-time.
If libcapsbase wasn't compiled with debugging support, no other component can make use of 'debug'. If libcapsbase was compiled with debugging support it depends on the other components (debugging support enabled or nor) if they make use of it.

Attention: Might interfere with CAPS universe early verbosity setup

Overview

Tools at hand

Information at hand

Just print

Trouble Shooting

Supported Printer

In Detail

How it works

Tools at hand

Frequently Used Tools

Sometimes Used Tools

Information at hand

CAPS Configuration Directory

CAPS Printer Driver Database Directory

CAPS Printer Device Parameter Directory

CAPS Document Storage Directory

CAPS Printer Driver Configuration Directory

CAPS Printer Driver Executables Directory

CAPS Printer Device Database Directory

INI file set used by the CAPS universe printing coordinator

INI file set used by CAPS universe services

INI file set used by CAPS universe printer drivers

INI file set used by the Printer Preparation Tool

INI file set used by the Printer Driver Launcher

Section [info]

An example

Mandatory keys are

Just print

Goal: what you see is what you get

Simple use cases

Further Reading

Trouble Shooting

Early verbosity Setup

Verbosity Setup via INI