This document acts both as a user manual and a support document for Nokkis - a distributed ticket system utilizing QR codes.
Nokkis consists of two distinct subsystems: the client, that takes care of checking the tickets; and the server, that manages the tickets database and communicates the latest data between all connected clients. While the clients can act as standalone applications, it's highly recommended to install and configure both systems.
To compile the Nokkis client application, Java 1.5 (or later), gcc 4.0 (or later) and OpenCV 1.0 (or later) has to be installed on your computer. Ubuntu Linux 9.04 is the preferred operating system, but the client should also work on Windows XP, Windows Vista or Mac OS X 10.5.
- Install OpenCV from the command-line:
- Install Java Development Kit 1.5 or later. e.g.:
- Make sure you have JAVA_HOME environment variable set:
- Compile and run Nokkis client with:
- First install Xcode 3 and MacPorts.
- Then install OpenCV from the command-line:
- Now compile and run Nokkis client with:
- Install MinGW and MSYS. Add MinGW and MSYS bin directories to your PATH environment variable (go to Control panel -> System -> Advanced -> Environment variables).
- Install MinGW gcc version 4.3 or later (not included in MinGW currently).
- Install Apache Ant.
- Set ANT_HOME environment variable pointing to the directory where you installed it
- add Ant's bin directory to your PATH.
- Install Java 1.5 SDK or later.
- Make sure you have JAVA_HOME environment variable set. If not, set it to point to your Java SDK directory.
- Install OpenCV (1.1-pre or later recommended).
- Add Nokkis lib/opencv/win32 directory to your PATH.
- Compile and run Nokkis client from the command-line with:
Nokkis server application requires MySQL 5 and PHP 5 with PEAR and HTTP Request package (http://pear.php.net/package/HTTP_Request) to be installed. A LAMP setup (Linux-Apache-MySQL-PHP) is recommended, but in practice any other operating system and web server combination should work, too.
These instructions assume you're using LAMP as the server environment.
- Install and configure Apache. Make sure you have AllowOverride All for the directory where Nokkis server is going to be installed.
- Install MySQL 5. Make sure that you use UTF-8 as the default encoding!
- Install PHP 5 + PEAR. Enable MySQL and GD lib extensions in PHP (php.ini):
- Install PEAR HTTP Request module:
- Extract the Nokkis server files (nokkis-server.tar.gz) in any directory that is reached by the webserver (or configure your httpd.conf accordingly).
- Create a MySQL database called "nokkis" and add a MySQL user with needed privileges:
- Setup the Nokkis database - on command line:
- Edit nokkis-config.inc.php where needed:
- Edit .htaccess file in the REST sub-directory so that it has the correct URL to Nokkis REST/nokkis-api.php file:
- Test the Nokkis server installation by browsing to the Nokkis REST API URL - if the installation succeeded, you'll see the following reply:
- Test the Nokkis server admin by browsing to http://<nokkis-server-url>/admin/
This chapter provides short guidelines on how to use both the Nokkis client and server parts.
The included server administration interface has pages to add and modify events, creating tickets, managing the clients and browsing log messages.
The Nokkis client uses XML-formatted files to initialize itself. The only file the user needs to edit by hand is normally the client configuration file (config.xml). The client tickets file (tickets.xml) can be downloaded from Nokkis server admin clients page. The client cache file (cache.xml) contains always the latest tickets data. If the client is not connected to internet, or there's temporary network problems, you can edit or add tickets manually in cache file. Note that if a network connection to server is resumed, the server overrides manual changes to cache file!
The client processes always the tickets data in following order:
- Read data from the tickets file (tickets.xml).
- If a cache file (cache.xml) exists, update the tickets data from there.
- If using Nokkis server and there's internet connectivity, update the tickets data from there.
- Periodically update tickets from Nokkis server and write the cache contents to file (cache.xml).
Any missing client configuration parameters results in using default values as listed below:
First make sure that you have proper config.xml and tickets.xml files placed in the root of the Nokkis client folder. The client can be now launched with
The client is ready to work when the text in the top bar in the graphical user interface says "Place the ticket in front of the web camera".
After that, a ticket can be checked by placing it in the front of the web camera of the client computer. The graphical user interface of the client features a camera view box showing what the camera sees. Using this you can make sure that the ticket is placed correctly and it can be recognized by the client. For the best possible recognizability of a ticket, you should make sure the ticket faces the camera nicely. Also lighting conditions should be taken care of, even though in most cases this shouldn't be a problem.
A possible client laptop setup & ticket placement:
When client has recognized the barcode of the ticket, it shows a result information in the top bar and a result sign on the left and plays a corresponding sound:
- Barcode read ok: The barcode and the event were found, the event has already started but not yet ended, barcode was found unused and valid. Access should be granted. A positive sound can be heard.
- Barcode read failed: Access shouldn't be granted. A negative sound can be heard.
- Barcode was not found: A ticket corresponding to the barcode could not be found.
- Barcode is invalid: The ticket corresponding to the barcode has been set unvalid.
- Barcode is already used: The ticket has already been used.
- Event was not found: There is no event for the ticket shown.
- Event has not yet started: Event has not yet started.
- Event has already ended: Event has already ended.
If, for some reason, the client software or the computer running it crashes, the only thing you need to do is to relaunch the client application. The information about used tickets is recovered from the cache file and server.
You can quit the client application by pressing the q key or by closing the window (not in fullscreen mode).
- None, at the moment
- There is no real user support in Nokkis server API
- Database can store a minimal set of user data (user id, external id, email address), but none of the API functions accept any of the data
- Requiring the HTTP Request PEAR package for the Nokkis server installation was a result of having restricted access to db.cs.helsinki.fi server during development. In production use it'd be probably easier and cleaner to use PHP's own cURL extension.
- Server admin pages aren't feature-complete. For example sorting options and browsing to data on separate pages aren't fully implemented.
- Due to technical difficulties with PHP, update event in REST API is handled through HTTP/POST, not HTTP/PUT as intended.
- http://opencv.willowgarage.com/wiki/ - OpenCV Wiki, information about installation on
various platforms (Linux, Mac, Windows).
- http://java.sun.com/ - Java SDK downloads and documentation.
- http://ant.apache.org/ - Apache ANT homepage and downloads.
- http://www.mingw.org/ - MinGW and MSYS downloads.
- http://www.macports.org/ - MacPorts needed for Mac OS X installation.