Bash Item Tracking System (BITS)
by Charles Martin <HiTechCharles@gmail.com>
http://bitspos.sourceforge.net
TABLE OF CONTENTS
1: Introduction
1.1: What is bits?
1.2: System Requirements
1.3: Things bits can, and cannot do
1.4: Why the name BITS?
1.5: Installing and Removing BITS
2: Configuration
2.1: Guided setup using bitsconfig
2.2: Explanations of files and settings
2.2.1: Item & Price file
2.2.2: Hourly time announcement
2.2.3: Number of transactions between auto stats displays
2.2.4: Voice Prompts
2.2.5: Tutor message file
2.2.6: Show tutor messages when products are sold
2.2.7: Edit task times file
2.2.8: Display task reminders at specified times
2.2.9: Cashier away message
2.2.10: Business or Company Name
2.2.11: Change Calculator
2.2.12: Sales Tax
2.3: The .bits directory
3: How to use bits
3.1: Starting bits
3.2: Keystrokes
3.3: Tracking sales
3.4: Selling statistics
3.5: Transaction log
3.6: Locking the keyboard
3.7: Automatic data recovery
3.8: End-of-day sales reports
4: Additional Tasks
4.1: Access all available functions with bitsmenu
4.2: View latest sales report (viewnewestreport)
4.3: Choose, and display a sales report from a list (viewallreports)
4.4: Check transaction logs (viewlog)
4.5: Configure bits (bitsconfig)
4.6: Delete sales reports, logs, or recovery files (removefiles)
4.7: Read the Help file
4.8: Keyboard Chart
1. INTRODUCTION
===============
1.1: WHAT IS BITS?
BITS is the Bash Item Tracking System. This program will help you
run a small snack bar, concession stand, or any other operation where
you would like to track sales. Bits is easy to set up, and use. All
that is needed is the names and prices of items, and answers to some
simple questions.
1.2: SYSTEM REQUIREMENTS
Bits is written in a language called bash, which is a command
interpreter found on nearly all Unix and Linux systems. If you
use Unix, Linux, or any other operating system capable of running
bash, the software can be used. If you run windows, a program
called cygwin (http://www.cygwin.com) will help you run bash
programs. There are a few required packages that need to be
installed, these are listed in section 1.5.
1.3: THINGS BITS CAN AND CANNOT DO
Bits is able to:
* Track sales by marking items when they are sold.
* Display messages when a specific item sells.
* Can display helpful messages at specific times of day
* Remembers how many customers come in each hour of the day, which
gives you an idea when the business is busy, and when it is not.
* Get product and customer stats at any time.
* After items are selected, bits totals up the cost of items, and
figures out how much change to give back.
* Complete transaction log is kept for each day, and each customer
for that day, including time, items purchased, total cost, and
amount of change given back.
* Optional sales tax collection by adding tax to customer's purchases.
* Creates easy to follow sales reports that detail all of the
day's activity.
Bits is not able to:
* Keep a running count of available inventory, it just tells what
is selling, how much cash was taken in, and when customers come.
* Does not compile information gathered over multiple days. The
data collected from bits would feed nicely into a database or
spreadsheet for easy retrieval and analysis.
1.4: WHY THE NAME BITS?
For some strange reason, I knew I wanted the name BITS. Since the
project is made up of one large program, and other smaller ones. It is
bits that come together to make the whole.
After figuring out that it would be called BITS, it took a couple of
weeks to find the right words to stand for the letters. One afternoon,
my brain came up with "bash item tracking system". "Bash" is the
programming language, and "Item Tracking System" is what the program
does. It seemed to fit with the goals of the project so I kept the
name ever since.
1.5: INSTALLING AND REMOVING BITS
To install, first go into a terminal and change into the directory
where the bits package was downloaded. Next, extract the files with
this command:
tar -xvf bits-2.4.tar.gz
Afterwords, a new directory will be created under the current
one called bits2. Change to this directory with
cd bits2
finally, to install bits, run the installer as root by issuing the command
sudo ./bitssetup install
There are a few special programs that bits relies on. Most of these will
already be on your system, but one or two may need to be installed with
your system's package manager. The package names and functions are:
less - file viewer
sox - play sound files
bc - calculator
tput - screen & cursor control
date - date and time formatting
tr - translate ore remove desired characters from text
time - Get elapsed time and other info after a program runs
column - format data into columns
If everything went OK, you will see an installation success
message. To remove bits, you can run this command as root
from any directory (since bits is already installed.)
sudo bitssetup remove
Once bits is installed, the bits2 directory, and the downloaded file
can safely be removed. You must be root to install since files are copied
to important system directories. Installation is optional, you can
run bits programs from the downloaded package, such as:
./bits
./bitsmenu
For the remainder of this file, it will be assumed that bits is
installed on your system. If not installed, just run the
program in question while in the directory containing the bits files.
2: CONFIGURATION
=================
2.1: GUIDED SETUP USING BITSCONFIG
Bits comes with a step-by-step configuration program, which will
let you create the files you need, and set your preferences. The
configuration program will run the first time bits is started.
Start the configuration tool by going into your terminal, and
running this command:
bitsconfig
You can run it by using your graphical environment's "run program"
option, which is often accessed with the keyboard using ALT+F2.
Run the command bitsconfig, and make sure to check the "Run in
terminal" check box.
2.2: Explanations of files and settings
The bits configuration program will ask thirteen questions. Three of
them will let you edit files, and the others will set preferences.
The order of the explanations in this section match the order
of the questions in the configuration program.
2.2.1: ITEM & PRICE FILE
The Item & Price file (items file from now on) stores the names
and prices of all items that you sell. If this is your first time
through the program, an editor will be launched with the file open.
otherwise, you will just be asked if you want to change it. Once
you start editing the file, you can start typing in your items and
prices.
For each product, write the name, such as large coffee.
On the next line, put the price of the item using only
numbers. Continue this pattern for additional items.
Here is what an items file would look like:
Small Coffee
0.75
Large Coffee
1.00
Hot Tea
0.75
After you are done editing, save the file and exit the editor.
2.2.2: HOURLY TIME ANNOUNCEMENT
Enabling hourly time announcements will display the time at the top
of each hour. This is enabled by default.
2.2.3: NUMBER OF TRANSACTIONS BETWEEN AUTO STATS DISPLAYS
For this setting, you pick a number of transactions that should take
place between displaying the selling statistics automatically. For
example, if the number 5 was used, the stats would show every 5
customers. Use 0 to completely disable this feature, the default is 6.
2.2.4: VOICE PROMPTS
When most actions are preformed, you can have voice prompts that speak.
For example, when you show the keyboard help, the message on the screen
is read. Most messages that bits displays are read when voice is on.
Voice can be turned on or off. The default is off.
2.2.5: TUTOR MESSAGE FILE
Tutor messages are small notes that show up when a particular product
is sold. A tutor message for a bag of microwave popcorn could read
"Heat popcorn for 2 minutes and 30 seconds in the microwave."
All of the tutor messages are gathered into one file. Each line in
this file corresponds with a product. The order of the lines match
the order of products in the item & price file. If you do not need
a message for an item, leave that line blank, and move to the next.
To get the order of your products, run the command bitsquick to get
a list of your items. The letters before each item will be explained
in Section 3. For example, if your first product is coffee, the first
line of the tutor message file should contain a message about coffee.
2.2.6: SHOW TUTOR MESSAGES WHEN PRODUCTS ARE SOLD
After you set up your tutor messages, you can choose whether to display
those messages. Answer yes if messages should show, or no if messages
should not display. The default is for messages to be silent.
2.2.7: EDIT TASK TIME FILE
To be reminded to do tasks at specific times of day, set up the task time file.
One task is defined per line. Its form is:
<time> - <Reminder message>
An example task times file would look like this:
7:00 AM - Business is open, unlock front doors
10:00 AM - Restock refrigerator
2:00 PM - Shop is closed, begin shutdown tasks
2.2.8: DISPLAY TASK REMINDERS AT SPECIFIED TIMES
This option controls the displaying of your set reminders. Answering yes
will show them, no will not. The default is no.
2.2.9: CASHIER AWAY MESSAGE
When the computer will be unattended or want to prevent accidental
keystrokes, the keyboard can be locked. When this is done, you can
control the message that displays. Type any one-line message, and
hit ENTER. For more about screen locking, see section 3.6 in this
file. If there is no input when this question is asked, an away
message will be provided.
2.2.10: BUSINESS OR COMPANY NAME
This setting controls the name put atop your sales reports. Just
type the desired name, and hit enter. The default is "Bash Item
Tracking System" if no input is given.
2.2.11: CHANGE CALCULATOR
The change calculator asks how much the customer paid, so bits can
figure out the correct change. The payment and change amounts go
into the transaction log. (See section 3.5.) When asked, just type
in the customer's payment amount using numbers and the decimal point.
If there is change due, bits will tell you how much. The default for
this function is off.
During input, hit enter with no entry or a value of 0 to cancel the
current sale. The letter E can be used to stand for exact change.
2.2.12: SALES TAX
Sales tax can be applied automatically to customer's purchases.
A list of states and their sales tax will appear. To choose a
state, just type in its two-letter state code, such has MI for
Michigan. To disable sales tax collection, type NT.
To use a value of your choosing, type CV, and you will be
prompted for the desired tax percentage. Use numbers and
the decimal point.
Statistics views and reports will show the total sales tax
collected for the current session, and the income amount
does not include the sales tax paid by customers. Tax
is disabled by default.
2.3: THE .bits DIRECTORY
The configuration, log, report, and recovery files are placed in
the .bits directory, located in the user's home directory. Inside
the main bits folder, are the following files:
* bits.conf - bits configuration file
* items - Names and prices of all products for sale
* messages - Tutor message file
* times - time-based reminder messages
* bits-keylist - Generated by bitsquick, which shows all
keyboard functions
There are three sub directories within the .bits directory:
* logs - holds transaction logs, one for each day.
* recovery - Contains all of the data needed to recover the
sales data in case of a program crash or power outage.
This directory will either be empty or contain the
customertraffic, itemssold, misc, and sessioninfo files.
* reports - Holds sales reports, which are created when
completing a bits session. A list of all reports can be
viewed with the viewallreports command.
3: HOW BITS WORKS
==================
3.1: STARTING BITS
Bits can be started in one of two ways, depending on where the
program is.
If bits has been installed, use a terminal or your desktop
environment to run the command
bits
To run from within the downloaded package, extract it, and go into
the newly created bits2 directory, and run
./bits
Once bits is started, you will get a welcome message. If you have not
created an item & price file, you will be taken through bitsconfig to
answer the necessary questions, and make the needed files.
3.2: KEYSTROKES
After start-up, there are several keys used to operate the program.
For each key, a section number with more details is in parenthesis.
Press ? in bits to see this list.
A-Z Mark items as sold (Section 3.3)
: Lock screen (Section 3.6)
? Help (You're reading it now!)
1 Display selling statistics (Section 3.4)
! Shorter stats display (Section 3.4)
2 View transaction log (Section 3.5
3 Cancel a sale (Section3.3)
5 Show product letters (Section3.3)
7 Give current date and time
0 Exit (Section 3.8)
3.3: TRACKING SALES
Bits works on the principal of letting the computer know when items
are sold. From that, bits can track total sales, customer traffic
patterns, and what time the last sale was made. Optionally, a
message can be shown for each product when it sells for extra
information. Reminders can come up that let you know about
tasks that need to be performed. If used, sales tax will be added
to the customer's total.
After bits looks over your list of products, it assigns each a
letter of the alphabet. This letter is used to mark that
item as sold. Your first product in your item & price file
will get the letter A, the second item will get B, and so on,
for a maximum of 26 products.
When a customer purchases items, just press the letters that
correspond with the products that were sold. As you do this,
the items that you are selecting show up together on the screen.
When you are done marking items for a customer, either wait ten
seconds, or press the space bar to tell bits that you are finished
selecting items.
If you have the change calculator enabled, you are asked how much
the customer has paid. Just type the amount. (Numbers and decimal
only.) The current sale can be canceled during numeric input by
leaving it blank or typing 0. Use the letter 'e' to quickly use
exact change. If the customer is to receive change, the amount
will be shown. That's all it takes!
There are a couple of useful keys that deal with canceling the
current sale, and showing the proper letters to mark items.
To find out which letter to use with each product, press the
5 key. It may be helpful to run the bitsquick command, which
generates a file with your product letters that you can print.
(See section 4.8 for more details on the bitsquick command.)
If you make a mistake while selecting items, press the 3 key
to cancel the current set of selections and start over.
3.4: SELLING STATISTICS
As you progress through the day, you will have handled many
transactions. To see all of the information bits provides,
press the 1 key.
In the first section, the number of sales for each product
appears. Following that, the number of customers for each
hour of the day is displayed. The final group of lines
show total customers, items sold, income, and last time a
sale was made. Per-customer calculations, and total
sales tax collected appear last.
This same information goes into the sales report that is created
when you exit. See section 3.8 for more information about the
reports. To see just the totals, rather than the sales
for all products, use the ! key instead of 1.
3.5: TRANSACTION LOG
A customer thinks he was short-changed. How do you check? Open
up the detailed transaction log by pressing the 2 key. For each
customer, a record of the time, items purchased, cost, customer
payment, and amount of change is given. There is one log for
each day, even if more than one complete bits session is involved.
If change calculator is disabled, the amount of change and customer
payment details will be omitted from the log.
Once the log opens, use the arrows to scroll, space to go down
one screen, and q to quit. Bits lets you know that it's ready
for input after exiting the log.
3.6: LOCKING THE KEYBOARD
When the person operating the computer is taking a break, or if
you need to get the crumbs out of your keyboard, it is a good
idea to prevent accidental key presses by locking the keyboard.
To lock the keyboard, hit the : (colon) key. After pressing
that key, a message displays that shows others that the
cashier is away. (This message is changeable in the
configuration program, bitsconfig.)
While the keyboard is locked, the keys will type letters,
but will not mark items or perform functions. This allows
others to leave messages on the screen. Anything can be typed
in this mode. Any reminders that happen during screen lock will
not be shown. To return to normal operation, type the word
unlock on a blank line. Lock and unlock times are put into the
transaction log, as well as the total time away from the computer.
3.7: AUTOMATIC DATA RECOVERY
Computers crash, lose power, restart themselves, or just plain
misbehave. Rest assured that bits can recover from any accident
or interruption. Each time a product is sold, recovery data is
written to disk.
If your bits session is interrupted, just run bits again to
recover from the last session. Everything is the way it was
before the problem occurred. To remove the recovery data, and
start from scratch, exit bits, and use the command
removefiles -r
(See section 4.6 for more details on the removefiles command.)
3.8: END-OF-DAY SALES REPORTS
The day is finally over. How do you get a nice report out of
this pile of bits? Press the 0 key on the keyboard to end bits
and generate a report. You will be asked if you are sure you
want to exit. Press the Y key to generate the report, N will
return you to the program.
When the report is ready, you will be asked
whether to view the new report. Press Y for yes, or N for no. Either
way, all reports are saved for later viewing with the
viewnewestreport and viewallreports commands. (See the
appropriate sections in chapter 4.)
4: ADDITIONAL TASKS
====================
4.1: ACCESS ALL AVAILABLE FUNCTIONS WITH bitsmenu
For the easiest experience, a menu can be used to access any part
of the bits system. The only command you need to remember is
bitsmenu
When you run this, you are able to start the main program, tweak
its settings, view reports and logs, remove files, and view the
help file and keyboard chart. Press the letter for the option
you want. All options available from the menu will be outlined
in this chapter. The commands you can use for the different
operations are in parenthesis. Only the command for removing
files, (removefiles) supports command line options.
4.2: VIEW LATEST SALES REPORT (viewnewestreport)
All reports are saved together in a reports directory. To look at
the newest one, use N from the bits menu or the command
viewnewestreport
The newest report will show up on the screen. If there are no
reports to look at, you will be alerted to this fact. Exit bits
completely, and wait for it to say that the report was saved.
4.3: CHOOSE, AND DISPLAY A SALES REPORT FROM A LIST (viewallreports)
To see all available reports, use R from the menu or run
viewallreports
The 26 newest reports are shown from newest to oldest. Hit the
letter next to the one you want to look at it. To see a different
one, run the command again. The actual report files are stored in
your home directory under the .bits/reports directory.
4.4: CHECK TRANSACTION LOGS (viewlog)
To see action logs for any one day, run viewlog and choose the date
you want displayed by letter. Up to 26 different logs can be listed.
Log files are stored in the logs directory under the bits main directory.
4.5: CONFIGURE BITS (bitsconfig)
The configuration process is outlined in chapter 2. To change
settings, press C in the bits menu or run
bitsconfig
Go completely through the config program to allow bits to start correctly.
4.6: DELETE SALES REPORTS, LOGS, OR RECOVERY FILES (removefiles)
When it's time for spring cleaning or if you need to remove
recovery data, press D from the menu or type the command
removefiles
With this tool, sales reports, recovery data, or logs can be
deleted from your system. Press R for recovery data, S for
sales reports, L for logs, or A for all data types. If bits
is running, you will not be able to remove recovery files.
Exit bits with CONTROL+C and try again. This prevents not
having recovery files while you are working.
removefiles has command line options that allow removing
files easily. You can use -a for all, -l for logs, -r for
recovery data, or -s for sales reports.
4.7: Reading the help file
To read this file from the menu, you can press the H key from
within bitsmenu. The help file is in /usr/share/doc/bits,
or in the docs directory within the installation package.
4.8: KEYBOARD CHART (bitsquick)
The keyboard chart will show the alphabetic letter assignment
for each product, as well as its selling price. At the end,
all bits function keys are listed. The chart shows on-screen,
and a file with this same list is saved in your .bits directory
as bits-keylist.
Last updated Wednesday, November 9, 2011
