This specification describes the CUPS command file format (application/vnd.cups-command) which is used to send printer maintenance commands to a printer in a device-independent way. The current specification supports basic maintenance functions such as head cleaning and self-test pages and query functions such as auto-configure, report supply levels, and report status.
Printer drivers advertise support for the CUPS command file
format by providing a filter for the
application/vnd.cups-command file type. Applications
can determine if a printer supports printing of CUPS command
files by checking the printer-type attribute for the
CUPS_PRINTER_COMMANDS capability bit.
In addition, the PPD file for a printer can contain a
cupsCommands keyword that provides a list of supported
commands separated by spaces, for example:
*cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels ReportStatus"
If no cupsCommands keyword is provided, the command filter
must support AutoConfigure,
Clean,
PrintSelfTestPage,
and ReportLevels. The scheduler also
provides the printer-commands attribute containing the list of
supported commands.
CUPS command files are ASCII text files. The first line of a CUPS command file MUST contain:
#CUPS-COMMAND
After that, each line is either a command or a comment. Comments begin with the # character, e.g.:
# This is a comment
Commands are any sequence of letters, numbers, and punctuation characters optionally followed by parameters separated by whitespace, e.g.:
Clean all PrintSelfTestPage
Command names are case-insensitive, so "PRINTSELFTESTPAGE", "printselftestpage", and "PrintSelfTestPage" are equivalent. Vendor-specific commands should use a domain name prefix, e.g.:
com.vendor.foo com.vendor.bar param param2 ... paramN
The following are the standard commands supported by the format. The only
required command is
PrintSelfTestPage.
AutoConfigure
The AutoConfigure command updates the printer's PPD file
and driver state information to reflect the current configuration of the
printer. There are no arguments for this command.
Example:
#CUPS-COMMAND AutoConfigure
Clean colorname
The Clean command performs a standard print head cleaning. The
"colorname" parameter specifies which color or head to clean. If a printer does
not support cleaning of individual colors or cartridges, then all colors are
cleaned. Command filters MUST support the "all" colorname. Other standard color
names include "black", "color", "photo", "cyan", "magenta", "yellow",
"light-cyan", "light-magenta", "light-black", "light-gray", and "dark-gray".
Example:
#CUPS-COMMAND Clean all
PrintAlignmentPage pass
The PrintAlignmentPage command prints a head alignment page on
the printer. The "pass" parameter provides a pass number from 1 to N. The number
of passes is device-dependent.
Example:
#CUPS-COMMAND PrintAlignmentPage 1
PrintSelfTestPage
The PrintSelfTestPage command prints a self-test page on the
printer. Typically this page shows whether all jets on a print head are
functioning and that the print feed mechanisms are working properly.
Example:
#CUPS-COMMAND PrintSelfTestPage
ReportLevels
The ReportLevels command queries the supply levels on a printer
and reports "marker-colors", "marker-levels", "marker-names", and
"marker-types" attributes using "ATTR:" messages sent to the scheduler. This
command should also report the current printer status using "STATE:" messages
like the ReportStatus command.
Example:
#CUPS-COMMAND ReportLevels
ReportStatus
The ReportStatus command queries the printer for its current
status and reports it using "STATE:" messages sent to the scheduler.
Example:
#CUPS-COMMAND ReportLevels
SetAlignment pass value ... valueN
The SetAlignment command sets print head alignment values. The
"pass" parameter is a number from 1 to N. All parameters are
device-dependent.
Example:
#CUPS-COMMAND SetAlignment 1 14