Generating QR Codes in Linux
Creating and Reading QR CodesBy
With the right tools, you can create your own QR code squares with information you want to share on a business card, in a letter, or on your website.
Read errors of unreliable, one-dimensional bar codes often caused interruptions in industrial production, prompting companies like Toyota and its subsidiary Denso Wave to develop as early as 1994 a new code for acquiring stock data. The new matrix bar code was designed to store more information than the traditional bar code and to stay legible, even if the label was dirty, wrinkled, or partially destroyed.
The quick response code, or QR code, comprises a matrix of square dots instead of the usual lines. Measuring up to 177 by 177 dots, the QR code encodes up to 4,296 characters, compared with a bar code that encodes just 13.
Thanks to numerous free reader apps for smartphones, QR codes have gained in popularity in recent years. Posters, catalogs, magazines, business cards, and even television screens display the small squares, offering additional information or URLs for microsites.
On My Mark!
The quickest way to create a QR code is with the Qrencode command-line utility. Any major distribution can install Qrencode via the package manager. The following command then creates a QR code containing the text “Hello World!” (Figure 1):
$ qrencode -o qrcode.png 'Hello World!'
The generated QR code ends up in the qrcode.png file. If the file already exists, it’s overwritten without prompting. If you have at least version 3.3.0 (qrencode -V), Qrencode can generate an EPS graphic,
$ qrencode -t EPS -o qrcode.eps 'Hello World!'
or ASCII output (Figure 2).
In the QR code image, the software creates a white border the width of one dot. This facilitates the process of deciphering the code for programs or the smartphone later on. If desirable, you can increase or decrease the edge with the -m parameter; in the following example the border width would be 10 code pixels:
$ qrencode -m 10 -o qrcode.png 'Hello World!'
If you are saving the QR code in PNG format, the -s parameter specifies the height of a black QR code pixel. By default, Qrencode draws every black dot three by three pixels. The program creates a slightly smaller QR code with quite a wide margin with the following command:
$ qrencode -s 2 -m 10 -o qrcode.png 'Hello World!'
A white border appears around the QR code that is exactly 20 screen pixels wide (10 QR code dots in width, with each dot two pixels). If you are creating EPS images, the only parameter available is -m; -s moves the entire QR code out of the image in this case. To control the resolution of PNGs further, use the -d parameter to define the dpi.
Besides the specified data, the QR code contains additional error correction information. If a portion of the image is damaged, it allows you to reconstruct the missing or illegible data. The more additional information the QR code contains, the more heavily damaged it can be without becoming useless.
Increasing the error tolerance increases the size of the image because you need more black dots (Figure 3).
The QR code standard thus uses four levels of error correction: H level allows you to read all data if 30 percent of the QR code is destroyed, Q level if 25 percent is unreadable, and M level if just 15 percent is unintelligible. At the lowest level, L, only 7 percent of the data can be faulty. In Qrencode, the -l parameter selects the error correction level. The possible values are pretty much what you would expect: L, M, Q, and H.
The level you choose depends on the proposed use. If you expect the QR code to be exposed to external influences (e.g., wind, weather, graffiti) or if you are planning to manipulate the image deliberately (see the “Intruders” box), you will want the highest level, H. On a business card, the lowest level, L, is sufficient. If in doubt, simply omit the -l parameter. The program then uses level L by default.
Qrencode lets you encode any text, including URLs. You only need to use single quotes if blanks and non-standard characters appear in the text:
$ qrencode -o lpm.png http://www.linuxpromagazine.com
All modern QR code readers recognize that this is a web address and will offer to open it in the browser.
Getting an QR-encoded address automatically to enter a smartphone owner’s address book is more difficult. In this case, you need to enter your address and some additional, cryptic information:
$ qrencode -o address.png 'BEGIN:VCARD VERSION:4.0 FN: N:Schuermann;Tim;;; ADR:;;Putzbrunner Str. 71;Munich;;81739; END:VCARD'
Typing this is not exactly easy, so to make life easier, you might prefer a QR code generator with a graphical user interface, such as QtQR.
As the name suggests, QtQR is based on Qt. The tool relies on Python and the python-qrtools library. You can simply install the program via the package manager on Ubuntu. For other distributions, you will find the source code and RPM and DEB packages on the project’s download page.
The main window in QtQR is quite simple: Top left in the selection you can set what data you want to store in the QR code. For an address, choose Contact Information (PhoneBook). Depending on the type of information, QtQR displays appropriate fields (Figure 4).
As you fill out the fields, the program creates the corresponding QR code on the right. You can resize the code at top right. Pixel Size lets you set the number of pixels per square dot the QR code uses, whereas Margin Size lets you specify the size of the margin. Error Correction lets you define the correction level. Once you have set all parameters, save the code as a PNG file by clicking the Save QRCode button.
Portable QR-Code Generator
If QtQR’s capabilities do not meet your needs, you can try Portable QR-Code Generator. It also encodes geographical coordinates and WiFi access data, which can be useful if you want to offer guests quick access to WiFi as a hotel or coffee shop operator, for example.
Because Portable QR-Code Generator is written in Java, you must first install a Java run-time environment via the package manager. On Ubuntu, launch the Software Center and find the OpenJDK Java 7 runtime; on openSUSE 12.3, the matching package goes by the name java-1_7_0-openjdk.
The ZIP archive of the portable QR code generator is available from the project’s Downloads page (to download, click on the Herunterladen link under the .zip entry). Unzip the file on your hard drive, open a terminal window, change to the directory with the extracted files, and run the command:
$ java -jar QRCodeGen.jar
The main window appears, and a small preview window (Figure 5) shows you the QR code.
In the main window, look at the top edge first. Depending on the data you want to store in the code, click on the appropriate tab; that is, to save a URL, open the URL tab, and for an address, use VCard v4.
In the selected tab, the program displays appropriate fields. For an address, you will see more tabs that group the information, but you only need to fill out the required fields. If you do not want to specify a phone number, simply ignore the Telephone tab. If the address is already in a vCard file, you can import it by clicking Read VCard.
Once you have entered the data to encode, click on Generate. The results appear in the preview window. Plain text (in the Text tab) and geographic coordinates (in the Geo URI tab) are exceptions; the preview shows the code during entry.
You can define the size of the QR codes, as well as the error correction level at the bottom left under QR Code options section. In contrast to the previously featured tools, the Portable QR code generator allows you to specify the dimensions for the final image.
If you set Requested size (pixel) to 400, the resulting QR code image is 400 screen pixels wide. However, if you want to specify the size of each dot in the code, set Mode to Module size, then in Module size (pixel) define the number of pixels to form a dot. Additionally, you can select a specific Character encoding (see the “Character Encoding” box).
To the right, in the QR Code details panel, you will see some statistics that reveal, among other things, how many bytes of payload (Data byes) the QR code currently displayed contains. To check the text that the Portable QR code generator actually dumped into the QR code, look at the bottom of the window; the details are in the Data field.
You can copy the generated QR code to the clipboard (Edit | Copy QR Code to clipboard) or save a PNG format image file with File | Save As.
KDE users have an easy way to convert text into QR code: Copy some text to the clipboard, click the Klipper tool (the scissors) in the system section of the control bar at the bottom, and select Show Barcode. Unfortunately, the interface does not let you save the QR code shown on the left side (Figure 6) or copy it to the clipboard. Your only workaround is to grab a screenshot with KSnapshot. For a single QR code this will still be faster than installing one of the other tools.
A possible alternative is the slightly older KBarcode4-light. To use it, first install PyQt via the package manager. On openSUSE 12.3 and Ubuntu, it resides in the python-qt4 package. Next, unpack the KBarcode4-light archive, which you downloaded off the web. In the src subdirectory, run the python kbarcode.py command.
In the window that now appears (Figure 7), select the QR Code item in the Encoding drop-down, then type the text to encode in Value, and press Generate. The resulting QR code appears at the bottom. Pressing Save as PDF lets you save the code in a text file.
Theoretically, it’s possible to export the QR code as an image file, but clicking Save on modern distributions only leads to an error message in the terminal. Another alternative is to click Copy and then paste the Clipboard contents into another program. The options offered in the Basic Options and Extra Options tabs are useless for QR codes.
Although dozens of apps are out there for reading QR codes with smartphones, only a few fairly rudimentary programs exist for Linux. If you have QtQR installed, press Decode in the bottom right corner of the main window. The program either accepts the QR code as an image file (Decode from File), or reads it via a webcam (Decode from Webcam).
However, QtQR is quite picky: For example, it does not interpret QR codes for dots of exactly one pixel. Additionally, the program stubbornly insists that the text contains ISO-8859-1 character encoding. If you have a QR code image file, one option is to use the Libdecodeqr-simpletest program, which is actually only intended as an example program for programmers on how to read codes in their own programs with the Libdecodeqr library. However, it is excellent for reading codes at the command line.
On Ubuntu, you can install the reader from the libdecodeqr-examples package with:
sudo apt-get install libdecodeqr-examples
Owners of other distros first need to install a C++ compiler, make, and developer files from OpenCV (on openSUSE, in the opencv-devel package). Then, use the archive of the current version from the Latest Stable Source Code section. Extract it on your hard drive, and in the resulting src subdirectory, enter the following three commands: ./configure, make and sudo make install.
As soon as the program exists on your hard drive, you can decipher QR code in the qrcode.png file with the following command:
$ libdecodeqr-simpletest qrcode.png
… at least in theory; the practical results will be disappointing in many cases. In my tests, libdecodeqr-simpletest simply refused to see any data in the QR codes (Figure 8).
Touch the Bar!
A much better alternative is ZBar. This program reads QR codes from files or via a connected webcam. Ubuntu includes the small tool in the zbar-tools package. On other distributions, you first need to run the package manager to install the developer packages for Qt4, PyGTK and ImageMagick. On openSUSE 12.3, they are named libqt4-devel, python-gtk-devel, and ImageMagick-devel.
If you want to read the QR code with the webcam, you additionally need the kernel header files; on openSUSE 12.3, they are located in the kernel-devel package. If you want to do without this function, you must use the --disable-video configuration parameter to disable it explicitly. After unpacking the source code, you can install the software with ./configure && make && sudo make install. To decode a PNG file with a QR code in ZBar, use:
zbarimg -d <file>.png
The -d parameter ensures that a window with the QR code appears (Figure 9) in addition to the decoded information in the terminal window.
If you want to read a QR code with a camera, you need to launch zbarcam. This pops up a preview window with the image from the webcam. Now hold up the QR code to the camera. Once the program has detected the code, it draws a green border around the QR code and prints the data in the terminal window (see the Big and Colorful” box).
You can disable the preview with the --nodisplay switch; raw delivers the raw data, and xml packages the data in an XML format. The above three parameters help if you want to integrate the tool into a script. The parameters --raw and --xml can also be used with zbarimg.
Of the tested programs, Portable QR-Code Generator offers the greatest functionality. Data entry is also convenient in a variety of tabs. Qrencode creates QR codes more quickly, and it is easy to scripted so you generate QR codes in batches. KBarcode4-light is deprecated, but it is the only program that can generate PDF files; the EPS images created by Qrencode offer similar output.
QtQR is especially recommended for decoding QR codes in PNG format. ZBar is a candidate for the command line that is also excellently suited for use in shell scripts. Along with a webcam, you could use it to create a small terminal for reading QR codes. libdecodeqr-simpletest is hardly usable in production and basically not worth installing.
Tim Schürmann is a freelance computer scientist and author. Besides books, Tim has published various articles in magazines and on websites.
Lennart Poettering wants to change the way Linux developers talk to each other.
Enterprise giant frees itself from ink and home PCs (and visa versa).
Mozilla’s product think tank sinks silently into history.
TODO group will focus on open source tools in large-scale environments.
New tool will look like GParted but support a wider range of storage technologies.
New public key pinning feature will help prevent man-in-the-middle attacks.
Carnegie Mellon researchers say 3 million pages could fall down the phishing hole in the next year.
The US government rolls new best-practice rules for protecting SSH.
Klaus Knopper announces the latest version of his iconic Live Linux system.
All websites that use these popular CMS tools could be vulnerable to denial of service attacks if users don't install the updates.