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. The configuration files as well as the browser-driven configuration interface are explained.
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)
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. If you run Linux you may look for the Linux Terminal Server Project.

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-2.3-17 etc. :

The number in front of the first dot designates the main branch. From time to time, I'm so disappointed by the pile of trash TkKasse has developed into I'll spin up and down the whole codebase, rip things up that worked (more or less) and replace them by a whole new structure which is expandable for future use.
Don't expect anything working smooth and clean when you update to a new main branch. Most times, there are a lot of caveats I haven't forseen and we'll need to email a lot.
(For both reasons, that number is also know as “nervous breakdown number”.)
The second number tells you the feature branch. In difference to version 1.x to 2.2, the server and client package now must have both the same main and feature branch number. Packages with different feature branch numbers will not work together nicely any more.
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. The stable branch will get bugfix support as long there are registered users which are still using it.

2.2. Updating to Version 2.3

As the whole packaging changed form version 2.2 to version 2.3, please make a backup of you cash register data (in /var/opt/tkkasse) and your configuration (in /etc/opt/tkkasse) and remove all the old packages completely, even all the files in these both directories. The new package structure consist only of two packages, TkKasse-Server and TkKasse-Client and is much simpler to maintain (for you and me).

Version 2.3 has a different configuration interface, which does not use configuration files, but an sqlite3 database. For that reason, the old configuration files /etc/opt/tkkasse/articles and /etc/opt/tkkasse/users cannot be used any more. You have to create the passprases and user records again within the new web configuration tool. To avoid too much extra work, I put up a small script /opt/tkkasse/bin/articles2csv which transforms the old articles file format into a csv file, which can subsequently be imported into the new configuration database by using the web configuration tool. There is no script for the user configuration files, as it is more work to write it than to create the user records again. The printer configuration file format has changed abit, but it is still a file — this is work in progress.

2.3. From RPM/DEB Packages

Get the rpm/deb [1] packages from the sf.net file release system. You can also refer to the Website to get the latest packages.

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.3.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
sqlite (Version 3 or newer)
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)

Additional packages may be selected automatically by YaST.

As the icons for the BackOffice component of TkKasse are not included into the tkkasse distribution, you'll have to install an icon theme (e.g. crystalsvg) and link it to /opt/kde3/share/icons/default.kde. This is already done by YaST if you installed KDE on the machine. In the future, TkKasse will include it's own icon theme.

Install the TkKasse packages for the server in the correct order.
1. tclcrypt (optional, available for i386/32Bit only)
2. tclhttpd (Version 3.5.1-jk2, see note!)
3. sqlite-tcl (Version 3.2.3-jk1, see note!)
4. TkKasse-Server
Include the TkKasse server and the TkKasse back office 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). Do the same for tkkassebod.
Configure TkKasse properly. See Configuring and Customizing TkKasse. (A basic configuration which you can tune to fit your needs is installed by the server package.)

The packages tclhttpd-3.5.1-jk2 and sqlite-tcl-3.2.3-jk1 are created from software of other projects, but included into the TkKasse distribution for convenience reasons: For tclhttpd, no package exists and “make install” or “checkinstall” create a package that violates the filesystem hierarchy standard in /opt. For sqlite, SuSE missed to include the tcl language bindings the original sqlite package offers. The sqlite-tcl-3.2.3-jk1 adds two files needed for the tcl language to your system. If you like TkKasse, please visit those both projects' web sites, too.

2.3.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.0.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.4. 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. Overview

Beginning with version 2.3, TkKasse has a browser driven configuration interface. You can use it when the tkkassebod (TkKasse BackOffice daemon) is running. See here. This new configuration interface allows you to change the restaurant's menu, the users and their passphrases/keys so far. The printer, client, and basic server configuration is still done by files. See below for detailed instructions.

3.2. Browser driven configuration

You can access the new configuration interface via http://ip_address_of_server:19151/.

3.2.1. The Restaurant's Menu

The Restaurant's menu is configured in the Configuration->Articles section. 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 are the numbers to press to choose this trunk or leaf. Each of the trunks have again up to ten trunks or leaves.

(work in progress)

3.2.2. Waiter accounts

The waiters accounts are configured in the Configuration->Users and Configuration->Keys sections.

(work in progress)

3.3. Configuration Files

Some of the configuration for the TkKasse server programs is still done by files inside the /etc/opt/tkkasse directory. The tkkasse server reads the files settings and printers. The tkkkassebod BackOffice Server reads the settings file. These both 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.3.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.3.2. 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.3.3. Locale and Encoding

This is set in /etc/opt/tkkasse/settings:

set LOCALE de_DE: As the system locale is not set up properly on starting time of tkkassed and tkkassebod in many distibutions, you can set the locale TkKasse should use here.
set ENCODING utf-8: The same as for the locale applies to the system encoding. Most time, the distribution will not set it up properly. Set it here.

3.3.4. Receipt Printers

For now, the receipt printers are still set in a configuration file, /etc/opt/tkkasse/printers. As that file will be obsoleted in the future by the browser driven configuration interface and is on the other hand well commented, I suggest you to read the comments in the file to get more information on printer configuration. If you don't see through it, please contact me.

3.3.5. Various Server Settings

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

set CONFIGURATION_DATABASE_PATH $CONFIGURATION_PATH/configuration.sqlite3: This is the path and filename of the configuration database. Leave this alone if you don't plan to put the configuration database on a removeable media.
set CONFIGURATION_DATABASE_TYPE sqlite3: The configururation database type has to be sqlite3 for now. Leave this setting alone.
set AUTOSAVE_INTERVAL 600: TkKasse will autmatically save its cash register contents every $AUTOSAVE_INTERVAL seconds to $DATA_PATH/cr-autosave. If you don't need this feature, set it to 0.
set LOGLEVEL debug: 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: This 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.3.6. 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 IBUTTON_KEYS 0

If you want to use waiter keys instead of passphrases, buy so-called iButton keys, a matching keylock and connect it to the client computer. Then you have to install OWFS and set this flag to 1. You don't need the complete owfs/FUSE for TkKasse, but only the onewire libraries and owtcl from the owfs project.

This is more complicated than it sounds. Please contact the author if you plan to use a keylock. To make it work in a terminal server setup, the owserver software of OWFS must be installed on the terminals, which is not so trivial.

set ONEWIRE_CONNECTION usb1

This option is only valid if IBUTTON_KEYS is set to 1. Put the name/number of the usb port you connected the iButton keylock to here. For RS-232 keylock adaptors, use a device node like /dev/ttyS0. In a terminal server setup, the hostname or IP address of the terminal has to be put here. In that case, each terminal needs it's own client configuration file, too. This can be achieved by setting up different unix accounts for each terminal and use the ~/.tkkasse client configuaration file in the account's home directory.

set SHOW_MENU 1

If the waiters are well trained or you use a POS keyboard, the menubar is pretty useless. Here you can deactivate it to get some more pixels height for the other data.

set SELECT_BILL_ON_LOGIN 0

Set this to 1 if you want the bill view automatically selected after the waiter logged in. This is useful when using waiter keys, but has some drawbacks with keyboard focus, which may end up into a client lock up so far. Don't use this option if you have fallen into that trap.

set SELECT_BILL_AFTER_BILL_CLOSE 0

Set this to 1 if you want the bill view automatically selected another bill was closed. Again, this has some drawbacks with keyboard focus, which may end up into a client lock up. Don't use this option if you have fallen into that trap.

set SERVER_HOST localhost

This is the hostname 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 recommended, “yes” (or 1) is the default.

set AUTO_LOGIN_CREDENTIALS [ list [ list auto jseese ] ]

A client may automatically login any number of users defined in the server configuration (here “jseese”). As this is a security risk, you have to “Allow automatic login” within the User configuration for the specified users.

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.

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 script /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 TkKasse BackOffice server?

Similiar to the TkKasse server. It is the script /etc/rc.d/tkkassebod. Type /etc/rc.d/tkkassebod start or (SuSE Linux only) rctkkassebod start .

4.3.3. 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. Do the same for tkkassebod.

4.3.4. 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.5. I get an error message: expected integer but got "<menubar.program.underline>" when I start the client.

Your system has a default locale which is not supported yet. So far, the only supported locales are: de_DE, de_AT, de_CH, en_GB, en_US. 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 uncomment/change the line set LOCALE de_DE in the /etc/opt/tkkasse/settings file to match your locale.

4.3.6. Special characters (e.g. Umlaut) are not displayed correctly.

The system default encoding is not set on server startup! Uncomment/change the line set ENCODING utf-8 in the /etc/opt/tkkasse/settings file to match your encoding.

4.3.7. The VAT switch hasn't any effect, the VAT is always zero.

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

4.3.8. Importing csv files doesn't get special characters (e.g. Umlaut) right.

The reason for this bug is again tclhttpd, which expects all data to be iso8859-1 coded. Use iconv to convert your (UTF-8 coded) files. iconv -futf-8 -tiso8859-1 <articles.csv >articles.csv.iso8859-1 (Internally, all data is recoded into unicode and written to the client and printers properly.)

4.3.9. The import/export charset within misc settings doesn't seem to have any effect.

They have an effect, but it's confusing. The reason is a kind of double- or triple- encoding which is done by your web browser, the tclhttpd web server tkkasse's configuration relies on and tcl itself. I'll investigate this problem further. Sorry for the inconvenience.

4.3.10. 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.

4.3.11. Some keyboard shortcuts doesn't seem to work.

The window manager may claim some shortcuts for itself. Use a window manage that doesn't. I prefer Matchbox , but mwm will do it's job, too. If you just wan't to try out TkKasse, you can use Ctrl+Alt+Return to grab keyboard focus for TkKasse exclusively. The grab is released automatically after 5s.

Please note that during the 5s grab, no other programm will be able to receive keypresses.

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