TkKasse Manual

The intended audience for this book are system administrators, who have to install and configure TkKasse for the use at a specific site, and as well distributors of TkKasse-driven cash desk sytems and their customers, who like to get an overview over its hardware, software and administration requirements.

What you can read in this manual: This manual (hopefully) covers the topics of installation and configuration of the TkKasse cash desk system, starting from the hardware requirements and ending with customization of the server and client programs. Inbetween, a pile of useful information on how TkKasse works internally is dumped on you, dear reader. With this information, you should be able to solve most problems that may occur when installing and configuring TkKasse.

What this manual covers not: You won't read anything in this manual about how the TkKasse client programs are used. This is information needed by the everyday user, e.g. the waiters in the restaurant you are installing TkKasse at. This topic is described in the TkKasse User Manual. Neither this manual is a developer manual. It gives somewhat useful information also to the (wannabe) TkKasse developer, but that's not enough to fully understand the internals. A developer manual ist not planned yet.

This book is divided into several chapters:

Chapter 1: Planning Your Cash Desk System: Here we take a overview about computer cash desk systems in general and TkKasse in particular: What are the benefits, where are the obstacles? What kind of hardware setup for my computerized cash desk should I use? How can I save money?
Chapter 2: Installing TkKasse: There are some things to mention when installing TkKasse. This chapter describes how to install the packages, or install from sources, which other software is required and how it should be configured. You get an overview on TkKasse's version numbering scheme, too, so you know which branch to use for update when bugfixes or feature-enriched versions should be installed.
Chapter 3: Configuring and Customizing TkKasse: This chapter focuses on TkKasse's configuration itself. All configuration files are explained. You as the system administrator will learn how to use the RONK-Configurator to share some configuration work — namely typing the restaurant's menu into the computer — with the restaurant staff.
Chapter 4: Troubleshooting: As a lot of trouble can be persistent through all the chapters above, its possible solutions are collected in this chapter. In addition to a simple Q & A section, solutions to hard-to-nail-down problems are collected here.
Appendix: In the Appendix you will find collaborated lists of files, configuration directives and other reference data.

When you had read all the information in this book and there are still questions left, feel free to contact the author, your questions and especially your suggestions for improvements are always welcome.

Chapter 1. Planning Your Cash Desk System

1.1. "Why would you like to use a computerized cash desk?"

You are crazy! — No, probably not. But, before you decide to dump your current cash desk, which is running smooth and fine, you have to be really, really sure what the benefits of a computer-based cash desk system are.

There a many types of cashiers and cash desk systems available. The main properties in which they differ are:

Hardware: (Work in progress)
Stand-Alone vs. Cash Desk System: (Work in progress)
Back-Office Functions: (Work in progress)

1.2. Setting up Your Computer System

1.2.1. Requirements

For TkKasse you need a server computer e.g. Intel-PC, Apple Macintosh, others, from the 400MHz/128MB RAM class up. More RAM is recommended. You can use the same computer for server and client.
The operating system of your server has to be UNIX-compatible (e.g. Linux, *-BSD, Mac-OS X, Solaris). TkKasse was developed to run on SuSE Linux, but there should be no big problems with other flavours of UNIX. However, this has not been deeply tested yet. TkKasse will not run on any kind of Microsoft Windows, as MS-Windows addicts expect software to be seriously broken by design, and TkKasse isn't. I can't break it just for the sake of these people's mindset.
You need at least one POS printer, as TkKasse will be pretty useless if it can't print receipts. Models with ESC/P(OS) printer language should be preferred, as a generic driver exist for those. Other drivers have to be developed first.

1.2.2. System Setup

The following scenarios, or any mix of them, are possible:

Single computer

In that setup, you have to install all the components of TkKasse on the same computer. All communication between server and client program(s) is done via network code in any case, so you need to setup TCP/IP properly (you need no network hardware to do this). You need the X-Window system running, as the client program needs it. All hardware is attached directly to the server computer.

Server computer is running TkKasse-Server, cash desk computers are running TkKasse-Client

(Work in progress)

This is the most complicated setup, and it doesn't work properly with TkKasse-1.0 due to a design bug in the printer selection scheme. Please stay tuned for TkKasse-1.1, where this bug will be solved!

Server computer is running TkKasse-Server and TkKasse-Clients, Cash desk computers just display the TkKasse-Client program window.

For this setup, often referred as Terminal server setup, nearly everything is the same as in the Single computer setup from TkKasse's point of view. However, you need to be aware of the caveats of a terminal server. This manual doesn't describe how to set up a terminal server.

Chapter 2. Installing TkKasse

2.1. A Note on Version Numbering

Which file one should download? There are so many of it! To answer that, you have to know the version numbering scheme of Tkkasse. It reads TkKasse-Server-1.0.1-3 etc. :

The number in front of the first dot designates the main branch. Packages with the same branch number may be mixed. If the main branch number differs, e.g. server and client will not communicate correctly and your setup won't work.
The second number tells you the feature branch. Each package is updated seperately and so are the version numbers. Packages with different feature branch numbers will work together nicely.
The third number is the the bugfix counter. Only bugs are fixed in those versions, no new features — which may produce new bugs — are implemented.
The number behind the dash is the package counter and is incremented over each package released. So it is of very little use for you.

As new features will be developed over the time, as well as bugfixes are released, it is adviseable to use always the latest version of a branch, meaning only to use bugfix versions and keep using the same branch as long as possible. A branch will be kept under development as long there are registered users which are still using it.

2.2. From RPM/DEB Packages

Get the rpm/deb [1] packages from the sf.net file release system. You can also refer to the TkKasse Version Reference table to get the right version of the package you want to install.

Next thing is to install the packages. You won't need to install all packages on all computers you want to use TkKasse. This is a client-server software — you remember?

2.2.1. Server Computer Installation

On the computer you want to run the TkKasse server, do the following:

Install the following packages provided by your OS distribution:
- SuSE Linux (Version 9.1 or newer): Use Yast to install
  - bash
  - coreutils
  - itcl (Version 3.3 or newer)
  - pwdutils
  - sysvinit (Version 2.85 or newer)
  - tcl (Version 8.4.6 or newer)
  - tcllib (Version 1.6 or newer)
  - tclx (Version 8.4 or newer)
  - xmlstarlet (Version 0.8.1-29) — only needed if you want to use the TkKasse-RONK-Configurator
  Additional packages may be selected automatically by Yast.
Install the TkKasse packages for the server in the correct order.
1. tclcrypt
2. TkKasse-Server
3. TkKasse-i18-en (or whatever localisation you like to use)
4. TkKasse-Example-Config (if you need it for reference)
5. TkKasse-RONK-Configurator (if you want to use it)
Configure the server properly. See Configuring and Customizing TkKasse. If you just want TkKasse to show its looks, install the TkKasse-Example-Config package. It contains a simple configuration which has to be tuned only a little bit to work with your setup.
Include the TkKasse server into the startup sequence. It depends on your OS how to achieve that:
- SuSE Linux (Version 9.1 or newer)
  Start Yast, choose System->Runlevel Editor, scroll down to tkkassed and activate the service. If you prefer the expert mode offered by Yast here,choose Service will be started in following runlevels: 3 (and 5, if X11 is used on the server computer, e.g. in a terminal server setup).

2.2.2. Client Computer Installation

On each client computer (or on the terminal server only, if you have a pure terminal server setup) you like to use the TkKasse client — the program the waiters will use —, do the following:

Install the following packages provided by your OS distribution:
- SuSE Linux (Version 9.1 or newer): Use Yast to install
  - bash
  - blt (Version 2.4 or newer)
  - coreutils
  - itcl (Version 3.3 or newer)
  - iwidgets (Version 4.1 or newer)
  - tcl (Version 8.4.6 or newer)
  - tix (Version 8.1.4 or newer)
  - tk (Version 8.4.6 or newer)
  Additional packages may be selected automatically by Yast.
Install the TkKasse packages for the client in the correct order.
1. TkKasse-Client
2. TkKasse-i18-en (or whatever localisation you like to use)

2.3. From Sources

It is possible to install TkKasse from sources, but not adviseable. As all packages apart from tclcrypt contain only scripts and data, they need not to be compiled and such, no Makefile is provided with them. You have to copy all the files to their correct locations yourself, change all permissions yourself, change the TkKasse server start script... It is complicated, and if you want to do it, please contact the author at

<tkkasse@users.sf.net>

for help.

Chapter 3. Configuring and Customizing TkKasse

3.1. Configuration at a Glance

I suspect "What do I have to configure?" will be your first question.

Configuration Items:

The Restaurant's Menu

The most important part of the configuration. The menu of the restaurant has to be available for TkKasse — it has to know all the prices for the articles and their code numbers, too. Read how to set this up, with or without the help of the OpenOffice.org office package, in section The Restaurant's Menu

Waiter accounts

You may configure TkKasse to have only one user account, and let all waiters use this account. But often, it is desireable to set up an account for each waiter in the restaurant. Read how to do it in Waiter accounts

Receipt Printers

Receipt printers have an important role in TkKasse's function. You can configure as many printers as you want and tell TkKasse to use one or the other for certain cash desks or receipt types. Read how to configure the server program in Receipt Printers.

Data Storage

The good message is: You don't have to set up a database server like PostgreSQL for getting TkKasse to work. The bad message is: This may change in the future.

But for now, a simple directory is sufficient. Read how to set this up in Data Storage.

Various Server Settings

Some other configuration settings for the server are present. Read about them in Various Server Settings.

Client Settings

The client has a configuration, too. Read about it in Client Settings.

In addition, you may ask where to change the configuration. Read more about the configuration files in the next section.

3.2. Configuration Files

All the configuration for the TkKasse server program is done by files inside the /etc/opt/tkkasse directory. The server reads the files settings, articles, printers, users, in that order. Besides from the different permissions for the users file, which is for security reasons unreadable to the world, they are totally equivalent. You may e.g. put printer settings into the articles file but if you do it's less tidy and thus, error prone.

All the configuration files are simply scripts written in the tcl scripting language, with itcl OOP support. The common commands inside these scripts are special procedures defined by TkKasse, but you can use any tcl command inside the configuration files.

You very likely get a mess nobody can clean up if you use the whole power of tcl here. I encourage you to stick to the commands and settings given in the example configuration files provided as a separate package.

The same as above applies to the client program. It reads the file /etc/opt/tkkasse/client, and additionally a (hidden) file named .tkkasse residing in the home directory of the user (this has nothing to do with TkKasse's internal waiter accounts) which has logged in into the machine and is running the client.

Whenever you have changed a server configuration file, you have to restart the server process to apply the new settings. All Clients will lose their connection to the server in that moment, so don't do it while somebody is working. However, no data is lost, as the server process automatically saves all data to disk on its shutdown, and re-reads them on its next startup.

The client program has to be restarted only if its own configuration has been changed.

3.2.1. A Note on Tcl Syntax

If you don't want to learn Tcl just for configuring TkKasse, please read this section.

Tcl is a command and list oriented language. Each command consists of a logical line, in which the command list items (command names, option names, parameters) are separated by whitespace (that is space and tab). The logical line ends with the first unmasked line end. Two consequences come from this: Parameters containing whitespace must be enclosed by braces or double-quotes and in-command editor line ends (that means: the single newline character at the end of each line) have to be masked out by a directly preceding backslash. You can make remarks in the configuration files by using the # command. Note this is a command, too, so it has to be at the beginning of the line to work as a comment command. If you remind these rules, editing TkKasse's configuration files should be no problem for you.

3.2.2. The Restaurant's Menu

The Restaurant's Menu is configured in the file /etc/opt/tkkasse/articles. It consist of a hierachical list of item that a customer may buy. Think of a bush where you can't see the root, which has up to 10 main trunks and leaves counted “0” to “9”, which is the number to press to choose this trunk or leaf. Each of the trunks have again up to ten trunks or leaves.

Now think of the trunks as groups of articles you sell, like

:TkKasse::ArticleGroup ::articleGroup0 -key 1 -name Speisen

which is german for “Dishes” (in contrary to the various beverages). Each dish you sell has now a number starting with 1. Whenever the waiter types “1” as the first digit of the article number, the article list will select “Dishes”, as this is the group with the key “1”. Then, let us assume, the waiter presses “3”. Now the article group with the key “13” is selected, as this is the list of keypresses the waiter has done. This article group

::TkKasse::ArticleGroup ::articleGroup3 -key 13 -name Salate

is denoted “Salate” (“Salads”). Then the waiter presses the “1” key again. Now an article was selected. It has the key “131”:

::TkKasse::Article ::article7 -key 131 -name {Kleiner Salatteller} -price 340 -service kitchen

Why this is known by TkKasse as an article, in contrary to an article group before? Simple, because the object type is TkKasse::Article now. Any article has a name, a price which must be expressed in the smallest unit of you currency (Euro Cent here) and a default point of service.

You can define articles with the price 0, like for “Various”. The waiter can then fill in a price on his own by adding an “extra” to this bill item.

The point of service can be bar and kitchen. The point of service selects the printer at which “order receipts” will be printed. It can be changed for each article by the waiter. If you only have one printer at the bar you should divide the articles into the ones that are made by the chef, and the ones arranged by the waiters, anyway. You can configure a single printer to print all the receipts.

The “service” field and the printer selection done by the waiter only affect “order receipts”. Receipts for the guest are always printed at that printer which was set up for this in the printer configuration.

Whenever the waiter presses a digit where no group or article exists, nothing happens.

If you define an article which cannot be reached by pressing keys and thus, going through the groups, that article is invisible to the waiters. Avoid this by always defining the groups first.

The last line of the articles file makes all the articles and groups you defined visible to the waiter (shortened):

::TkKasse::ArticleManager ::mainArticleManager -articles {::articleGroup0 ::articleGroup1 ::articleGroup2 ... ::articleGroup60 ::articleGroup61 ::articleGroup62 ::article0 ::article1 ::article2 ... ::article195 ::article196 ::article197}

You can use the RONK-Configurator to generate the article and group list from an OpenOffice.org spreadsheet file. That way, the restaurant owner can do all the changes in the sprechsheet himself, leaving you only the work to convert it. The example configuration was generated by doing so with the spreadsheet tkkasse.conf.sxc included in the RONK-Configurator package.

3.2.3. Waiter accounts

Let's take a look into the users file:

::TkKasse::User ::user0 -name {Thomas H�bscher} -shortname ThH -login thuebsch -password {$1$9Kkbl77U$/ZHsLbSsM2JiX5/vbe/R6/} -rights {printCashRegisterReceipt cleanUp} -flags {}

In the line above, an object ::user0 of the type ::TkKasse::User is created. The constructor takes the user name "Thomas H�bscher" which is used on the display and receipts, the short name "ThH", which is used on receipts and the login name "thuebsch" which is used internally. Further, there is a password hash "$1$9Kkbl77U$/ZHsLbSsM2JiX5/vbe/R6/", which in this case represent the password "abc" in MD5 encrypted fashion. The "rights" argument can take any list of strings, but so far, only the strings "printCashRegisterReceipt" and "cleanUp" are evaluated by TkKasse; others are just ignored. Please take all parameters as mandatory for now.

The password hashes can be created from the plaintext passwords with the help of the tkkassepasswd script, which is included in the TkKasse-RONK-Configurator package. It takes plaintext passwords from stdin and outputs the MD5 hashes to stdout.

You can use the RONK-Configurator package to generate the user list from an OpenOffice.org spreadsheet file.

Other user definitions of this type follow. The last line reads as follows:

::TkKasse::UserManager ::mainUserManager -users {::user0 ::user1 ::user2}

Here an object ::mainUserManager of the type ::TkKasse::UserManager is created. The object has to be named this way, as the TkKasse server directly uses this object. The constructor takes a list of user objects managed by this ::mainUserManager, here the previously created user objects ::user0, ::user1 and ::user2.

3.2.4. Receipt Printers

(Work in progress)

3.2.5. Data Storage

Setting up data storage is easy, as the TkKasse server is handling all data alone. It needs a directory which belongs to user "tkkassed" and group "tkkassed", and permissions set to "rwxr-x---". The directory is set up automatically at /var/opt/tkkasse if you install the TkKasse-Server package. However, you can change the directory path in the file /etc/opt/tkkasse/settings Just change the line set DATA_PATH /var/opt/tkkasse to anything you like.

In a near future release, TkKasse's data storage facilities will change drastically. TkKasse will support a number of different storage backends (like an embedded DB, or an SQL DB). It is unclear how the data format may change in the future: if you build tools on the current data format, please notify the TkKasse developers so they keep you and your tools in mind when they change everything!

3.2.6. Various Server Settings

There are some other configuration items in the file /etc/opt/tkkasse/settings:

set LOGLEVEL debug: The first is the debug level. You can basically control how important a log message must be to get into syslog. Loglevels are debug, info, notice, warn, err, crit, alert, emerg, the same as in syslog. If you set the loglevel to "debug", all messages are copied into /var/log/tkkassed, too. However, debug messages are never sent to syslog. Make sure you set the loglevel at least to info after your cash desk was set up properly, otherwise you will get a really big /var/log/tkkassed file, which clutters up your disk space.
set SERVER_PORT 19150: The next setting is the TCP server port the TkKasse server should listen for connections. This has to be the same port number as set in the client configuration.

3.2.7. Client Settings

The client settings can be either configured globally in the file /etc/opt/tkkasse/client or locally in the home directory (~/.tkkasse) of the account the cash desk runs under. As all waiters share the same account, I encourage you to use the global settings. The following are the defaults given in the client itself:

set SERVER_HOST localhost: This is the name or IP address of the computer the TkKasse Server is running on. It may be set to “localhost” in a single computer or terminal server setup.
set SERVER_PORT 19150: The next setting is the TCP server port at which the TkKasse server is listening for connections. This has to be the same port number as set in the server configuration.
set CONNECT_ON_STARTUP 1: This setting controls if the client should connect to the TkKasse Server automatically or not. As this is recommanded, “yes” (or 1) is the default.
set LOADING_FAILED_MESSAGE "Laden des Paketes %s fehlgeschlagen.": This is an error message shown if something went wrong while initializing the client before the localisation package yould be loaded. You may change this into a description in your language. The default german text reads “Failed to load package %s.” where %s is automatically changed to the package name which could not be loaded. (This should be “msgcat” in any case, as the message is changed to the localisation default as soon as that one is loaded.)
set LOADING_MESSAGE "Lade Paket %s...": This is the same, but before any error. The default german text reads “Loading package %s.” where %s is automatically changed to the package name again.
set SPLASH_SCREEN 1: This setting determines if a splash (startup) screen is shown. On by default.
set SPLASH_SCREEN_NO_DECORATION 1: If the startup screen should have window manager decorations, set this to 0.
set SPLASH_SCREEN_TITLE "TkKasse - Willkommen": This is the window title of the splash screen before any localisation has been loaded.
set HELP_COMMAND "konqueror %u": Whenever the waiter uses the help function of the client program, the command set by this option is launched. %u is automatically subsituted with the help URL.
set HELP_URL file:/usr/share/doc/packages/tkkasse/: This is the default help URL (wrong, though, should be “file:/usr/share/doc/packages/TkKasse-Doc/usermanual.html”) on SuSE.
set MAIL_COMMAND "kmail --subject %s --msg %t %a": This last one is for the Support button which is shown in the detailed view of the “Oops” dialog. It is there to make it easy to mail a detailed bug report to the support people. Please configure this setting properly for your site. %s is substituted by a subject given in the localisation file, %t is substituted by the error message and stack trace and %a is substituted by the email adress of the support people, also given in the localisation file.

Chapter 4. Troubleshooting

4.1. Status and error messages from the server

The server uses the syslog facility of the operating system to report status messages. You may look into the file /var/log/messages, if you have a standard syslog setup. If the server is in debug mode, it reports even some messages more in the file /var/log/tkkassed. As the latter file is not in the log rotation scheme of the operating system, it is adviseable to turn off the debug mode as soon your setup works as expected.

4.2. Error messages from the client

Besides from simple error messages, which appear if the user has done something wrong, the client has another error window, named TkKasse - Program Failure. It appears only if the program has a bug. By pressing the Details button, you will get a stacktrace of the error, which can help in debugging. Thus it is possible to dismiss the error by pressing the Bummer! button, one should paste this backtrace into an email to the TkKasse developers and subsequently restart the client.

4.3. FAQ

4.3.1. How do I start the TkKasse server?

The server is started by the skript /etc/rc.d/tkkassed.Type /etc/rc.d/tkkassed start or (SuSE Linux only) rctkkassed start . Stopping the server is similar.

4.3.2. How do I start the server every time the computer starts?

SuSE Linux (Version 9.1 or newer): Use Yast->System->Runlevel Editor and select tkkassed, then Start. The TkKasse server is now started and marked for start in system runlevels 3 and 5, so it will start up with next system start, too.

4.3.3. How do I start the TkKasse client?

Just type /opt/tkkasse/bin/tkkasse at a shell prompt. You can set up a menu item/desktop icon for this in your favourite desktop environment.

4.3.4. I get an error message: expected integer but got "<menubar.program.underline>" when I start the client.

You forgot to install the correct localisation package, or your system has a default locale which is not supported yet. So far, the only supported locales are: de_DE, de_AT, de_CH (TkKasse-i18n-de package) and en_GB, en_US (TkKasse-i18n-en package). Set up the locale properly or just start the client with LANG=en_GB /opt/tkkasse/bin/tkkasse or similar.

The system default locale affects the server, too! It will not work unless you insert an export LANG=en_GB or similar below the line export TCLLIBPATH="$LIBPATH $TCLLIBPATH" (this is about line 40 of that file).

The next version of TkKasse will address this locale problem another way and will offer a regular configuration option to set up a different locale just for TkKasse.

4.3.5. The tax switch hasn't any effect, the tax is always zero.

Simple reason: nobody told me the tax rates for other countries than Germany so far. If you know your local tax rates, please provide them to me.

4.3.6. What's about this “work in progress”? I never see any change at the website!

Again a simple reason: I don't have so much time to work on TkKasse I want to. There are other projects (“real life”, you know) which take my time. If you become a part of my “real life”, e.g. by offering a job, money or just chatting about TkKasse, you are likely to get more attention and maybe I can help you to fix your problems with TkKasse.

Installation and Configuration

Jan Kandziora

Colophon

Preface

Chapter 1. Planning Your Cash Desk System

Chapter 2. Installing TkKasse

Chapter 3. Configuring and Customizing TkKasse

Chapter 4. Troubleshooting

Index

Notes