Skip to content

[TUTORIAL] How to Start Playing with IPP Sample Software

Jump to bottom
Kurt Pfeifle edited this page Nov 25, 2019 · 3 revisions

The following mini-tutorial first (a) gives a high level overview over basic IPP Everywhere concepts; and then (b) gives a few hints how to re-produce and extend the commands which were shown in my ASCIIcast/ASCIInema movie. This ASCIIcast is linked below. It is recommended to watch it, before you start playing with the software:

asciicast

Three initial tipps for watching the ASCIIcast:

  1. You can pause it any time you want, and later continue it, should it run too fast for you.
  2. You can copy'n'past stuff (commands, URIs etc.) from the viewer window.
  3. Use [ctrl]+[-] to zoom out should your browser's default zoom setting not show the complete viewer window.

If you are a Linux user, you can easily re-enact all the commands from above ASCIIcast without a need of prior building of the IPP Sample binaries from their sources: just download the latest AppImage, make it executable and run it. Details further below...

What is IPP?

IPP is the Internet Printing Protocol, implemented by CUPS, running on macOS and most Linux system for printing. IPP is specified and standardized by the ISTO PWG (IEEE Industry Standards and Technology Organization / Printer Working Group).

The newest incarnation of IPP, called "IPP Everywhere", is designed to bring "driverless" printing to the world, across all major operating system platforms.

How can driverless printing possibly work? Simple:

  1. There are no longer any "proprietary" printer languages exclusive for a printer. IPP-enabled printers...

    • ...MUST support PWG Raster and JPEG as print job spooling formats and
    • ...MUST support PDF as a print job spooling format when the printer uses IPP/2.1 and IPP/2.2. (PDF support is optional for a printer using IPP/2.0).

  2. IPP-enabled printers are able to respond to queries investigating about their capabilities. ("Can you print duplex? Can you print in color? Do you support stapling? Have you got paper with A3 dimensions loaded? How much ink do you have left?" etc.pp.)

  3. IPP-enabled clients are able to query printers prior to any print job submissions. Thusly they can "learn" about a target printer's capabilities. Then they can bring up and offer only these job options in their user interface for users' selection which are supported on the target printer.

  4. IPP clients sends job as PDF (or PWG-Raster), alongside the desired job options expressed as "IPP Job Attributes".

Have you ever used iPads or iPhones to print via "AirPrint"? Then you've experienced a (much simplified and stripped-down) incarnation of driverless printing which was inspired by the PWG's early efforts for IPP Everywhere!

What is the IPP Sample Software?

This software is a sample implementation for the IPP Everywhere specification. Its repository is on GitHub:

The current version is not yet the final release, but identifies as Beta 1 ("v1.0b1").

What is an AppImage?

AppImages are a way to package applications in a very elegant and efficient way into a single directly runnable file. This makes them capable to run across a large range of Linux distributions without change. They sport the following features:

  • They follow the paradigm "One App == One File" which makes handling them super-easy.
  • No need to install ANY framework or install a new "package manager" prior to use them.
  • No need for root privileges.
  • No need to "install" an AppImage. Simply run it. (Just make it executable first.)
  • Run from any location (including USB thumb drives or Windows/SMB/Samba network shares).
  • Do not interfere and mess with the system libraries under the control of the native package management software.
  • Can auto-update to newer version via "binary delta" downloads to save bandwidth and time. (Requires the AppImage packager to have correctly followed a few rules.)
  • Can run multiple versions of the same software side by side.
  • Integrate into desktop environment (add menu entries, use correct icons, etc.) when (optional) appimaged daemon is running. (This daemon will auto-discover additions and removals of AppImages on a system.)

You can read more about AppImages here:

Re-duplicating this ASCIIcast

You can re-duplicate what I demo-ed in above ASCIIcast by downloading my latest AppImage (only available for 64bit Linux systems) of the IPP Sample Software:

 wget -c https://github.com/KurtPfeifle/ippsample/releases/download/continuous/ippsample-x86_64.AppImage

Alternatively, point your browser to github.com/KurtPfeifle/ippsample/releases, scroll to 'Continuos build -> Assets' and select the *.AppImage file to download

(Or just click this direct link to download it with the help of your browser: https://github.com/KurtPfeifle/ippsample/releases/download/continuous/ippsample-x86_64.AppImage )

If you are familiar with AppImages already -- this one pushes the envelope and is a bit "unusual":

  1. It has not a GUI application embedded, but works with the CLI.
  2. It does not follow the "One File == One App" paradigm, but rather a "One File == Multiple Apps".

Hence, the main name of the AppImage, 'ippsample' is not an App or embedded executable by itself. Instead it is used to let you run the four embedded CLI utilities (ippfind, ippserver, ipptool and ippproxy) as 'sub-commands' (similar as busybox works, if you are familiar with that).

After download, you have to make the AppImage executable:

 chmod +x ippsample-xperimental-x86_64.AppImage

Now you can already start to use it:

 ./ippsample-xperimental-x86_64.AppImage

However, in the long run, always typing ippsample-xperimental-x86_64.AppImage feels awkward... I recommend you to either symlink to (re-name) the original AppImage to something shorter, like ippsample. Then, to run ippfind without additional arguments, simply type:

 ippsample ippfind [ENTER]

The same applies to any of the other sub-commands:

 ippsample ippserver [ENTER]
 ippsample ippproxy [ENTER]
 ippsample ipptool [ENTER]

If you run ippsample without any sub-command, it is falling back to the default sub-command, ippserver, and runs just that.

To see an overview of all the options you have which are specific to this AppImage, run

 ippsample --help

Here's an overview about the most important ones:

  ippsample --listman                           # List all embedded manual pages
  ippsample --man ippfind                       # Show manual page for ippfind
  ippsample --man ippserver                     # Show manual page for ippserver
  ippsample --man ippproxy                      # Show manual page for ippproxy
  ippsample --man ipptool                       # Show manual page for ipptool

  ippsample --html ippfind                      # Open HTML version of manpage in default browser
  ippsample --html [ippserver|ippproxy]         # Open other manpages as HTML
  ippsample --html [ipptoolfile|ipptool]        # Open other manpages as HTML
  
  ippsample --listtest                          # List all .test files which are embedded in AppImage
  ippsample --cat get-printer-attributes.test   # Print contents of 'get-printer-attributes.test' file
  ippsample --listtestdoc                       # List all embedded .pdf, .jpg, .pcl, .pwg-raster, .ps, .3mf, .sla, .scad and .stl test docs
  ippsample --extracttestdoc <filename>         # Extract and save named test document from AppImage
                              
  ippsample --appimage-help                     # Show options which are common to ALL recent AppImages
  ippsample --appimage-extract                  # Unpack AppImage contents into AppDir 'squashfs-root'

You want to re-duplicate and then play on your own with what this tutorial demos? Then prepare TWO terminals and place them next to each other on your screen.

Start 'ippserver'

In the FIRST terminal you should now run this command:

 ippsample ippserver -v -p 22222 "MyIPPSampleTestServer"
 
 --
 #    -v         - For SOME verbosity (needed to see / note down the ipp:// URI you need to use to query this ippserver process)
 #    -p 22222   - Specify a port number for ippserver to use (optional)
 #    "NAME"     - Pick your own (required).

Now cancel the process again ([ctrl]+[c]), and restart it with increased verbosity:

 ippsample ippserver -vv -p 22222 "MyIPPSampleTestServer"
 
 --
 #    -vv        - For maximum verbosity (optional; without it you won't see much)

Find 'ippserver' instance on the network

In the SECOND terminal, run:

 ippsample ippfind

The output should show AT LEAST a line with an URI using "22222" port. Use this line whenever you are asked to use an "IPP URI". If you have shared CUPS queues or IPP-enabled printers in your LAN, these will show up as well. In MY case (as can be seen in the ASCIIcast above), this IPP URI was:

 ipp://lenjessie2.local:22222/ipp/print

You may want to watch what happens in the first terminal, whenever you fire a command in your second...

Start an IPP Client

The built-in utility ipptool can do all kinds of typical IPP client stuff when communicating with another IPP endpoint (IPP print server or IPP-capable printer).

The IPP is a protocol which is largely based on HTTP (limiting itself to POST operations -- IPP doesn't use PUT, GET or any of the other HTTP methods!), however it uses binary encodings for all of its operation codes.

This poses a little problem for humans: they will have a lot of difficulties to learn and specify any binary encoded HTTP POST operation on the command line.

Along comes ipptool: this utility can translate clear-text instructions it reads from a text file into the binary encodings used by IPP and send them to the other IPP end point. The only requirement is that these clear-text instructions are written in a specific syntax using clear text IPP keywords (which can be mastered more easily by human testers).

The specific syntax/language and keywords for ipptool are well defined. There are different ways provided by the AppImage enabling you to learn about that syntax:

  1. To read its manpage, run:

     ippsample --man ipptoolfile

  2. Look at the list of usable example text files (usually suffixed as .test) by running:

     ippsample --listtest

  3. Look at the content of such a .test file by running:

     ippsample --cat create-job.test

  4. You can even extract such a .test file by running:

     ippsample --cat create-job.test > my-create-job.test

    After extracting it to 'my-create-job.test' you can easily modify it. Then use it for your further learning experience by letting ipptool read it for interactions with ippserver.

Query for Printer Capabilities

To query the IPP capabilities of the newly started ippserver process faking one (default) IPP printer, try this:

 ippsample ipptool -t -v ipp://<your-uri-from-above>/ipp/print get-printer-attributes.test

Print Jobs to 'ippserver'

 ippsample ipptool -f color.jpg       -t -v ipp://<your-host-spec-from-above>/ipp/print  print-job.test  # send embedded 'color.jpg' to print
 ippsample ipptool -f document-a4.pdf -t -v ipp://<your-host-spec-from-above>/ipp/print  print-job.test  # send embedded 'document-a4.pdf'
 ippsample ipptool -f ./mylocal.pdf   -t -v ipp://<your-host-spec-from-above>/ipp/print  print-job.test  # use path to PDF (outside AppImage)

Query about Completed Jobs

 ippsample ipptool                    -t -v ipp://<your-host-spec-from-above>/ipp/print  get-completed-jobs.test

Bonus Track

Has your ippsample ippfind command from above discovered IPP-capable printer devices in your network? Even some you didn't know about previously?

This happened to two different friends of mine recently, after I had let them play with a preview version of my AppImage. One of them had bought his printer already three years ago. He was utterly shocked to learn that his printer could consume PDF files and that it supported IPP. Nobody at MediaMarkt had told him, and neither had it been advertised by the respective vendor. Which is a big, big shame... To me this is not so heavy a surprise, because MOST consumer printers which appeared on the market in the last few years already support PDF-direct and IPP printing (albeit maybe not to the fullest extend).

You now know how to run the get-printer-attributes.test and get-printer-attributes-2.0.test queries against the respective IPP URIs of your devices. Make use of them. Test your printers!

Let's see how IPP- and PDF-compliant they are... Complain to the vendors if they didn't implement IPP correctly... :-) Let's make IPP Everywhere more popular!

In Conclusion

From here, I'm expecting you to start learning to walk the IPP walk on your own... :-)

Any questions or suggestions?
Find me on Twitter: @pdfkungfoo,
or on StackOverflow: Kurt Pfeifle,
or join the AppImage IRC channel on Freenode: #AppImage.

P.S.:

This tutorial is not approved by ISTO-PWG. Hence all errors or mistakes contained therein are my personal responsibility.

The IPP Sample Software implements IPP Everywhere™, IPP 3D, and many other IPP standards and extensions.

Clone this wiki locally