Using POSper/Installation guide

Program installation

Step 1. Install java

POSper is an application developed in java and to execute it you will need the java runtime enviroment from Sun Microsystems versions 1.6 or greater. To install the java runtime enviroment follow the instructions of the link http://java.com/en/download/index.jsp.

If you are going to use a serial or USB device like ticket printer or cash drawer you must in addition download RXTX 2.1.7 from http://rxtx.qbang.org. Other than mentioned in the RXTX install instructions the RXTX library for your system can be placed in the POSper install directory. This is a safe way to retain the RXTX library when you ugrade your Java version. The RXTXserial.jar file is already present in libs.

Step 2. Download and unpack POSper

Download the last version of the binary package of POSper from Sourceforge [1]. Extract the files to an empty folder.

Step 3. Configure and run it!

Refer to the file readme.txt in the directory you've POSper extracted to. Follow the instructions.

When running POSper for the first time you will be asked a password that allows you to create a new database. This password is always 'setup' and cannot be changed. It exists only for safety reasons to avoid an existing database to be overwritten in case of database or network errors. Never enter this password when a database should already exist.

Setting up your Program in Windows

1. Once you have unzipped POSper into your folder, find the file called "posper.exe” (it will look like a gear in a program window). Right-Click on it and select “Create Shortcut”. Then drag that Short-cut onto your desktop.

2. The Short-cut that you just pasted onto your desktop is the icon that you double-click on to open your program. Before you go ahead and Double-click on it run the configuration program config.exe which allows you to choose another than the default HSQL database - see readme.txt.

3. Follow instructions in "Setting up your program : Common" below

Setting up your Program in Linux

0. These instructions assume you're using Nautilus.

1. Once you have unzipped POSper into your folder, find the file called "posper". It looks like a piece of paper with a grey gear on top.

2. Right click it and select "make link"

3. Drag 'n' drop this link to your desktop, which you can now doubleclick to run POSper. Before you go ahead and Double-click on it run the configuration program config.exe which allows you to choose another than the default HSQL database - see readme.txt.

4. Follow instructions in "Setting up your program : Common" below

Setting up your Program in Mac OS X

First make sure that you are running the latest version of Java. It can be obtained from the Apple Developer website.

0. Unzip the POSper folder into your Applications directory. Instructions in readme.txt that refer to Linux are also valid for MAC OS X.

1. To configure POSper, double clik on "config" and follow the instructions.

2. The next time you want to use POSper double-click on the file "posper" You can create a shortcut by dragging this file to your dock.

Database configuration

IMPORTANT: Before you proceed to the setup described in 'Setting up your Program : Common', you need to decide which database system to use and go through the configuration steps below.

POSper uses hibernate to store the application data including but not limited to products, sales, and users. Hibernate supports a wide variety of database systems such as HSQLDB[2], PostgreSQL[3], and MySQL[4].

It is strongly recommended to use a production grade database like PostgreSQL or MySQL for productive systems!

To configure the database go to the configuration panel in POSper or run the file "config.exe" in windows or "config" in linux.

The database configuration section is at the top in the "Database" section.

Driver library: Is the file provided by the database engine vendor that contains the JDBC driver that allows java programs to comunicate with the database.

Driver class: Is the java class name that implements the JDBC driver. This name is also defined by the database engine vendor.

URL: Is the connection string that uses JDBC to localize JDBC, the driver, and the database.

User: The name of the database user.

Password: The password of the database user.

HSQLDB

The default configuration of POSper uses HSQLDB for data storage. The HSQLDB library is distributed with the binary package of POSper and you do not have to worry about the database configuration if you want to use this database.

HSQLDB is a simple SQL relational database engine, potentially less efficient than other database engines.

PostgreSQL

To use POSper with PostgreSQL you must have a PostgreSQL server running and the JDBC driver for PostgreSQL. To download the server and the JDBC driver follow the link http://www.postgresql.org/download.html. After the database server is installed and running you have to create an empty database for POSper and a database user with privileges to connect to this database. For further assistance with this process, reference the PostgreSQL documentation[5].

The JDBC driver file for PostgreSQL is named "postgresql-<version_number>.jdbc3.jar" and the class name is "org.postgresql.Driver".

An example of a database configuration using PostgreSQL as database engine is:

Driver library: postgresql-8.0.309.jdbc3.jar  
Driver class: org.postgresql.Driver  
URL: jdbc:postgresql://localhost:5432/posper
User adrian  
Password: adrian

With these parameters a PostgreSQL database server is in localhost listening in the 5432 port and with an empty database called posper. The user adrian has privileges to connect to this database.

MYSQL

To use POSper with MySQL is very similar as PostgreSQL, you must have a MySQL server running and the MySQL Connector/J. To download the MySQL server and the MySQL Connector/J follow the link http://dev.mysql.com/downloads/. To install MySQL follow the link http://dev.mysql.com/doc/. After the database server is installed you must create an empty database for POSper and a database user with privileges to connect to this database. For further assistance with this process, reference the MySQL documentation[6].

It is recommended to download the MySQL Tools along with the MySQL Server. The tool MySQL Administrator is very helpful in creating an empty schema and setting up the users if you're not familiar with command line MySQL.

Note that Oracle has declared End Of Life for MySQL Tools and replaced them by MySQL WorkbBench. While WorkBench is a great program it lacks some features MySQLAdministrator had: scheduled backups and the ability to backup InnoDB databases in one transaction are only available in the commercial version (sad story).

The MySQL Connector/J package contains the JDBC driver that POSper needs to connect to the MySQL database server. The driver library file is named "mysql-connector-java-<version_number>-bin.jar" and the driver class name is "com.mysql.jdbc.Driver". To obtain this package, visit: http://www.mysql.com/products/connector/j/

Once you have downloaded MySQL Connector/J package, unzip the contents and place it in the same folder where POSper resides. For your convenience the connector mysql-connector-java-5.0.8-bin.jar is already included in the POSper distribution and you can use it with MySQL 5.0 or greater.

An example of a database configuration using MySQL as database engine is:

Driver library: mysql-connector-java-5.0.8-bin.jar
Driver class: com.mysql.jdbc.Driver  
URL: jdbc:mysql://localhost:3306/posper
User: adrian
Password: adrian

With these parameters a MySQL database server is in localhost listening on the 3306 port and with an empty database called posper. The user adrian must have privileges to connect to this database.

Setting up the mySQL Database for utf8 Code Tables

utf8 is used in many Arabic, Eastern and Asian environments.
So, if for instance, you want to input Chinese characters you need to reconfigure POSper and mySQL.
You can then input western characters and utf8 characters encodings into POSper :

Procedure (for LINUX sects) :
Database Setup and Configuration (before running Posper) :

• Logon into your mySQL Query Browser and configure
  

CREATE DATABASE posperdb CHARACTER SET utf8 COLLATE utf8_bin;
then make use of the database :
USE posperdb;
don't forget to check whether this has been successful or not.

• Lookup the mySQL configuration file my.conf, it's probably in /etc/mysql/
  

and edit my.conf, as root, the section after [mysqld]:
[mysqld]
default-character-set=utf8

• In the POSper DATABASE configuration edit the url :
  

jdbc:mysql://localhost:3306/posperdb?useUnicode=true&characterEncoding=utf8

Tested with POSper 1.0-851, Ubuntu 10.04 32 & 64 Bit Desktop, Java 1.6.0_22
Sources I have used and I found useful to read on :

• http://wiki.openbravo.com/wiki/OpenbravoPOS_FAQ#Right-to-left_language_support_.28Arabic_and_Hebrew.29
  
• http://confluence.atlassian.com/display/DOC/Configuring+Database+Character+Encoding
  
• http://dev.mysql.com/doc/refman/5.1/en/sql-syntax-server-administration.html
  

Setting up your Program : Common

1. You'll see the splash screen with a status bar telling you each step of startup as it happens.

2. You will then see the Opening Screen for “POSper”. Now click on “Admin”.

3. You should now see your sales window. On the left side of the Screen are some menus for you to select from. Under “Administration”, click “Stock”, and then “Taxes”. By default, "no tax" and a sample tax of 5% are available.

4. If you need to add more taxes, click the new button (shows as a star on a piece of paper, third from the right). Then choose a unique id, name the tax, and pick a percent.

5. Once you are finished adding any taxes you need, click on the save button (the floppy disk, first button from the right).

6. Go back now under “Administration”, and click “Stock” again.

7. Now click the button that says “Categories.”

8. You will be brought to a screen very much like the Tax screen. Here is where you categorize your food items. Under “ID”, it always needs a number. I suggest making each category an increment of 100. So for example, I will type “100” in the “ID” and then under the “Category”, I will type in “Coke Cans”. Then the next, “200”, and “Little Debbies.” Figure out how you want to categorize your food items and then make your categories. You can also add pictures for each category. Make sure you save after each category.

9. After you have made all of your categories, you will need to type in your products. “Administration”, then “Stock”, then “Products”.

10. Once again, each item must have it’s own unique number. For instance, for “Mr. Pibb”, type in a Reference like 101, and for “Mello Yellow”, a Reference like 102.

11. For Buy price, try and figure out how much each individual item costs you, if you do not know, type in some number below what you are selling it at. Either way, you need to type in a number to make the program happy. (Ex. For Coke 20 oz bottles, a case of 24 costs $15.05. So I divide $15.05 by 24 and end up with .627, so I then type “.627” into the “Buy Price” (You can give it as many digits as you like, and it will figure it out).

12. For “Sell price”, enter the amount that you intend to sell the item at. So for Coke, that number would be “1.00”. Immediately it will fill in two of the boxes for you. Now Beside “Tax”, select the appropriate tax (for instance "no tax") and for “Category” select the category you wish for the item to be in for ex. “Coke Bottles”.

13. To save the product click the icon with the flower on it.

14. Repeat step 12 to 15 for each product you'd like to add.

15. Click "maintenance" and then "users" in the administration panel. Note that POSper provides 4 default users : "Guest", "Admin", "Manager" and "Employee" (each has permissions consistent with their name). You can delete these default users if you want to customize all four roles, or you can leave some or all of the defaults intact.

16. To add a new user, click the icon with the flower on it. Type in the name under “Name”, and then select their role. If you want the user to be active, make sure the visible checkbox is on. If it isn't, they won't show up in the login menu. Role provides permissions to the new user. A Guest is only able to make sales. An Employee can have a password and can perform sales, refunds, and payments. A manager is able to do all of this and also has access to reporting. An admin has access to all the functionality in the system.

17. Setup is now complete and the system is ready to go!

NOTE: Once you have followed all the steps above run POSper. It will now populate the database for you, and you're off and running.