The qrencode application is a tool to rapidly produce qrcodes. Qrcodes are handy little images that embed information many cell-phone cameras can read to do a number of tasks like provide a link to install applications, provide links to web sites or videos, or to add contacts into the address book. With qrencode, in seconds you can generate these images.
According to WikiPedia QRCodes were introduced by the automotive industry for tracking parts. QRCodes gone beyond part tracking to a myriad of applications. Their popularity has increased in the consumer market with the advent of smart-phones with cameras that are able to scan in and process a qrcode. Their use spans many genra include entertainment, educations, and automation.
The qrencode application discussed in this entry was created by Fukuchi Kentaro and can be found on his website or, more easily obtained through your distro’s package management system. The website primarily discusses the use of libqrencode, the library which other applications can bind to to create qrcodes. The package itself comes with a binary that allows the creation of qrcodes.
The basic syntax is:
qrencode [option] [string]
String can also be a redirect from a file. For example, if the desire is to create a qrcode that embeds this website’s URL simply enter:
qrencode -o lits.png http://www.linuxintheshell.org
That would generate this simple qrcode:
On an Android phone there is an application called barcode scanner that is more than likely installed by default or easily grabbed from the market. If you scan the image above you will be prompted on what to do with the URL embedded in the image.
At its core, qrencode is that simple to use. Take note in the example above, the minimum requirement to execute the program is to provide the -o option which specifies the output file. The output is always a PNG file. Take note, you do not have to pass it a string on the command line, qrencode will take standard in as the input until you hit ctrl-d to stop:
qrencode -o poem.png
now if I type in the following:
This is my poem
typing away to see
what it does to you phone
That produces this qrcode and if scanned with your phone will produce the text above and some options on what to do with the text:
Notice the size differences between the qrcodes created. The code containing the url is a bit smaller than the poem. By default qrencode auto chooses the version level to use. The symbol version level of a qrcode determines the amount of data that can be held in the image. More accurately it sets the number of modules for the image and along with the Error Collection level (-l) determines the amount of data the qrcode can contain. The value can be from 1 to 40. Symbol version 1 defines a qrcode with 21 modules: “21 x 21.” Each successive version level adds and additional 4 modules per side up to version 40 with 177 modules per side: “177×177.”
In conjunction with service level the error correction level can be defined. Error correction level sets the capacity for the data to be read or “corrected” should the code become “dirty or damaged.” There are four error correction levels: L (~7%), M (~15%), Q (~25%), H (~30%) . The higher the error correction level the less data that can be stored in the qrcode image. Recall that qrcodes were first designed for tracking parts in the automotive industry. The error level was to compensate for factory environments which can get quite dirty. Thus error levels Q and H are typically used in environments where the potential to damage or dirty up the qrcode is high. Level L is suitable for clean room environments. Level M is suitable for all other instances. By default, qrencode uses Level L. If you plan on using the qrcode on print material you may want to go with level M.
One more factor to consider that impacts the size of the qrcode is the module depth, or dpi of each module. By default qrencode uses a dpi of 72. This is fine for screen resolution but for print consider higher dpi as applicable.
More information regarding the application and design of qrcodes can be found at the denso-wave website. In conjunction with the Wikipedia page mentioned above it should provide a great starting point learning the qrcode standard. The also provide a handy table breaking down the amount of data each service level can hold by error correction level.
With regards to the above information, qrcode utilizes the following defaults to generate the qrcode:
- Symbol Version Number – auto – based upon input string (option -v)
- Error Correction Level – L (option -l)
- Dpi – 72dpi (option -d)
- Pixel Size – 3 (option -s)
- Margin Width – 4 pixels (option -m)
Margin width was not discussed above. Standard qrcodes require a margin width of 4 modules. There is a definition for microCode which defines a width of 2 modules. The margin is the area around the qrcode and cannot contain any data.
For most purposes the defaults will suffice. If we wanted to encode the URL for Hacker Public Radio the command would be:
qrencode -o hprQR.png http://hackerpublicradio.org
But if this url was to be used on posters to be tacked up around town announcing the release of Linux in the Shell on HPR, we might want to consider passing a few extra parameters:
qrencode -o hprQRLitSPoster.png -l H -v 10 -d 300 / http://hackerpublicradio.org
The resulting qrcodes:
Note that the images above are not the original images created, and are not show at their full size in this post (click to see full size, your phone may have a hard time deciphering them). They were created using the commands above and then put into a third image using the Gimp to display on this page at a reduced dpi (for the second qrcode) as 300 dpi is not worth wasting bits for the screen.
One of the more useful applications for a qrcode is to encode vcard information making it easy to import a contact into your phone. To do this create a text file that contains the information you would like imported as a contact into a person’s address book (for the vcard syntax start at the wikipedia page):
ORG:Linux in the Shell
Take care! Note that there is no space between the vcard field type “:” and the entry. NO SPACES AFTER THE COLON!!!
To create the qrcode for this vcard:
qrencode -o myVcard.png < myvcardinfo.txt
That generates this image:
Scanning this qrcode will now provide you and the world wide web of spammers with my email so you can give me feedback!
Storing a large amount of data in a qrcode may result in a qrcode that is very large and not practical to put on the media it was designed for. A qrcode can be broken down into smaller, individual qrcodes that hold just a piece of the data and can be formatted in a more practical way for display on the chosen media. This process is called created a Structured qrcode. The switch to use is -S and also requires that you pass the version (-v) of the qrcodes you want to create. Instead of a single qrcode, qrencode will create a number of smaller qrcodes at the level of the version you specified:
qrencode -S -v 15 -o hpr.png < hpr_initrd.txt
In this example the original qrcode would look like this:
The above command created 4 qrcodes of version 15 size so they could be placed into a document horizontally:
Each qrcode contains about a quarter of the data. If you scan them in the reader should be able to reconstruct the contents as they originally appeared.
You can create some interesting qrcodes through the use of the version and error correction levels and an image manipulation program like the Gimp:
This qrcode was created with the following syntax:
qrencode -l H -v 5 -o tllts.org < http://www.tllts.org
The Gimp was used to add the “TLLTS” in the center. Because of the error correction and the version level scanners are able to reconstruct the contents of the qrcode even though part of the qrcode is “damaged.” Altering a qrcode this way will require some trial and error to get the desired results.
Entry 001 explains the use of qrencode to generate qrcodes. This is just the tip of the iceberg to generating qrcodes. For more information consult the following references used to create this entry:
- libqrencode – website and repository for qrencode and libqrencode
- Documentation of the qrencode library
- WikiPedia entry on qrcode
- QRCode.com webpage
- WikiPedia entry on vcard
- Embedding vcard in qrcode blog entry on You Have The Source
If the video is not clear enough view it off the YouTube website and select size 2 or full screen. Or download the video in Ogg Theora format:
- LITS 002 – qrencode Ogg Theora Video (right click, save to download)
Thank you very much