[IMP] hw_proxy: initial commit for the posbox's documentation
bzr revid: fva@openerp.com-20140218141129-sa4bhpi535sd7uhb
This commit is contained in:
parent
e53dd423e0
commit
49e81fb133
|
@ -0,0 +1,390 @@
|
|||
====================
|
||||
PosBox Documentation
|
||||
====================
|
||||
|
||||
Posbox Setup Guide
|
||||
==================
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before you start setting up your PosPox make sure you have everything.
|
||||
You will need :
|
||||
|
||||
- The PosBox
|
||||
- A 2A Power adapter
|
||||
- A computer or tablet with an up to date Firefox, Chrome or Safari web
|
||||
browser (we recommend Chrome)
|
||||
- A running SaaS or V8.0 OpenERP Instance with the Point of Sale
|
||||
Installed.
|
||||
- A local network set up with DHCP ( this is the default setting )
|
||||
- A RJ45 Ethrnet Cable
|
||||
- An Epson USB TM-T20 Printer or another compatible printer.
|
||||
- A Honewell Voyager USB Barcode Scanner or another compatible scanner.
|
||||
- An Epson compatible cash drawer.
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
1) Power the PosBox.
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Plug the PosBox to the 2A Power Adapter, a bright red status led should
|
||||
light up.
|
||||
|
||||
2) Connect it to the Local Network
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Connect the PosBox to the Local Network with the RJ45 Cable. Make sure
|
||||
You connect the PosBox to the same Network as your POS device. Once
|
||||
connected a bright yellow status led should light up, and a green status
|
||||
led should flash.
|
||||
|
||||
3) Connect the USB Printer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Put a paper roll in the printer, power it up, then connect it to one of
|
||||
the PosBox's USB port
|
||||
|
||||
4) Connect the cash drawer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The cash drawer should be connected to the printer with the RJ25 cable
|
||||
|
||||
5) Connect the USB Barcode Scanner
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Connect the usb barcode scanner to one of the PosBox's USB port. The
|
||||
Barcode Scanner should immediately light up and emit a loud beep.
|
||||
|
||||
6) Configure the USB Barcode Scanner
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The barcode scanner should be configured in QWERTY and emit a new line /
|
||||
return symbol after each scan. This is most likely the default
|
||||
configuration of your barcode scanner.
|
||||
|
||||
7) Make sure the PosBox is ready
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Once powered, The PosBox needs less than a minute to boot. Once the
|
||||
PosBox is ready, it should print a status receipt with its IP Adress.
|
||||
Also, the last status led, just after the red power status led, should
|
||||
be permanently lit green.
|
||||
|
||||
8) Set up the Point of Sale
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Make sure to activate the 'Print via Proxy', 'Remote Scanning' or
|
||||
'Cashdrawer' options in the Point of Sale configuration. If you are
|
||||
using firefox, you must manually specify the PosBox's IP address which
|
||||
was printed on the status receipt.
|
||||
|
||||
If you are running multiple Point of Sales on the same PosBox, make sure
|
||||
that only one of them has Remote Scanning activated.
|
||||
|
||||
9) Launch the Point of Sale.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you didn't spcecify the PosBox's IP address in the config, the POS
|
||||
will need some time to perform a network scan to find the PosBox. This
|
||||
is only done once.
|
||||
|
||||
The Point of Sale is now connected to the PosBox and your Hardware
|
||||
should be ready to use.
|
||||
|
||||
PosBoxless Setup Guide
|
||||
======================
|
||||
|
||||
If you are running your Point of Sale on a debian-based linux
|
||||
distribution, you do not need the PosBox as you can run its software
|
||||
locally. However the installation process is not foolproof. You'll need
|
||||
at least to know how to install and run openerp. You may also run into
|
||||
issues specific to your distribution or to your particular setup and
|
||||
hardware configuration.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
- A debian based linux distribution (Debian, Ubuntu, Mint, etc.)
|
||||
- A running trunk version of the OpenERP server
|
||||
- You must uninstall any esc-pos printer driver as it will conflict
|
||||
with OpenERP's built-in driver.
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
1) Extra dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The driver modules requires the installation of new python modules:
|
||||
|
||||
::
|
||||
|
||||
$ sudo pip install pyserial
|
||||
$ sudo pip install --pre pyusb
|
||||
|
||||
2) Database Setup
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must create a database called ``posbox`` with the modules
|
||||
``hw_proxy``, ``hw_escpos``, and ``hw_scanner`` installed.
|
||||
|
||||
3) Access Rights
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The drivers need raw access to the printer and barcode scanner devices.
|
||||
Doing so requires a bit system administration. First we are going to
|
||||
create a group that has haccess to usb devices:
|
||||
|
||||
::
|
||||
|
||||
$ sudo groupadd usbusers
|
||||
|
||||
Then we add the user who will run the OpenERP server to ``usbusers``
|
||||
|
||||
::
|
||||
|
||||
$ sudo useradd -G usbusers USERNAME
|
||||
|
||||
Then we need to create a udev rule that will automatically allow members
|
||||
of ``usbusers`` to access raw usb devices. To do so create a file called
|
||||
``99-usbusers.rule`` in the ``/etc/udev/rules.d/`` directory with the
|
||||
following content:
|
||||
|
||||
::
|
||||
|
||||
SUBSYSTEM=="usb", GROUP="usbusers", MODE="0660"
|
||||
SUBSYSTEMS=="usb", GROUP="usbusers", MODE="0660"
|
||||
|
||||
Then you need to reboot your machine.
|
||||
|
||||
4) Start the local OpenERP Installl
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We must launch the OpenERP server on the port ``8069`` with the correct
|
||||
database settings:
|
||||
|
||||
::
|
||||
|
||||
$ ./server/openerp-server --addons-path=addons,web/addons --db-filter='^posbox$' --xmlrpc-port=8069 -d posbox
|
||||
|
||||
5) Check that everything works
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Plug all your hardware to your machine's USB ports, and go to
|
||||
``http://localhost/hw_proxy/status`` refresh the page a few times and
|
||||
see if all your devices are indicated as *Connected*. Possible source of
|
||||
errors are: The paths on the distribution differ from the paths expected
|
||||
by the drivers, another process has grabbed exclusive access to the
|
||||
devices, the udev rules do not apply or a superceeded by others.
|
||||
|
||||
5) Automatically Start OpenERP
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must now make sure that this OpenERP install is automatically
|
||||
started after boot. There are various ways to do so, and how to do it
|
||||
depends on your particular setup. We use *systemd* on the PosBox, but
|
||||
*upstart* or *sysvinit* are other options.
|
||||
|
||||
6) Set up the Point of Sale
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Make sure that one of the posbox Make sure the IP Adress field in the
|
||||
POS Config is either ``127.0.0.1`` or ``localhost`` or simply leave it
|
||||
empty.
|
||||
|
||||
PosBox Technical Documentation
|
||||
==============================
|
||||
|
||||
Technical Overview
|
||||
------------------
|
||||
|
||||
The PosBox Hardware
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The PosBox's Hardware is based on a model B Raspberry Pi, a popular
|
||||
open-source micro-computer. The Raspberry Pi is powered with a 2A
|
||||
micro-usb power adapter. 2A is needed to give enough power to the
|
||||
barcode scanners. And we recommend Samsung power adapters for their
|
||||
availability and reliability ( but beware of counterfeits ). The
|
||||
Raspberry is protected by a ModMyPi Raspberry Pi Case. The Software is
|
||||
installed on a 8Gb Class 10 or Higher SD Card. The SD Card's class is
|
||||
important to ensure good performances. All this hardware is easily
|
||||
available worldwide from independant vendors.
|
||||
|
||||
Compatible Peripherals
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Printers:
|
||||
|
||||
- Epson TM-T20
|
||||
- Support for Other Esc-Pos compatible printers can be easily added
|
||||
on a case-by-case basis, please see the *Unsupported Printers*
|
||||
chapter of this manual.
|
||||
|
||||
- Barcode Scannners:
|
||||
|
||||
- Metapace S61
|
||||
- Honeywell Voyager 95x0 Series.
|
||||
- Most other barcode scanners should work out of the box. Some
|
||||
barcode scanners need more power than the PosBox can provide and
|
||||
must be plugged in a self-powered USB HUB. This is the case for
|
||||
Datalogic Barcode Scanners.
|
||||
|
||||
- Cash Drawers:
|
||||
|
||||
- As the cash drawers are connected to the printer, All Epson
|
||||
compatible cash drawers should work out of the Box.
|
||||
|
||||
The PosBox Software
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The PosBox runs a Raspbian Linux distribution, a Debian derivative
|
||||
optimized for the Raspberry Pi. It also runs a barebones install of
|
||||
OpenERP which provides the webserver and the drivers. The printer &
|
||||
scanner drivers are implemented as openerp modules. Those modules are
|
||||
named ``hw_proxy``, ``hw_escpos``, ``hw_scanner`` and are the only
|
||||
modules installed and running. OpenERP is only used for the framework it
|
||||
provides. No business data is processed or stored on the PosBox. The
|
||||
OpenERP install is a full bazaar clone of the ``trunk`` branch, and can
|
||||
thus be updated trough the usual means.
|
||||
|
||||
We use systemd to manage the Openerp server. Systemd makes sure OpenERP
|
||||
starts up at boot and is always up and running. Its systemd unit file is
|
||||
called ``openerp.service``, and can be found in
|
||||
``/etc/systemd/system/openerp.service``. The systemd version used is
|
||||
quite old and thus ``journalctl`` is not available. All logs can be
|
||||
found in instead ``/var/logs/syslog``
|
||||
|
||||
We removed all graphical software from the default install to reduce to
|
||||
image size but nothing prevents you from reinstalling them.
|
||||
|
||||
Local Access
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If you plug a QWERTY USB keyboard into one of the PosBox's USB ports,
|
||||
and if you connect a computer monitor to the *HDMI* port of the PosBox,
|
||||
you can use it as a small UNIX computer and perform various
|
||||
administration tasks.
|
||||
|
||||
Once the PosBox is ready press ``ALT-F2`` to access the login prompt.
|
||||
The login is ``pi`` and the password ``admin``. The OpenERP install is
|
||||
in the ``~/openerp`` directory along with a few scripts to help with
|
||||
debugging and administration.
|
||||
|
||||
Remote Access
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
If you have the PosBox's IP address and a SSH client you can access the
|
||||
PosBox's system remotely. The login / password are ``pi``/``admin``
|
||||
|
||||
Unsupported Printers
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The PosBox should be able to print to any ESC-POS printer, not just the
|
||||
Epson TM-T20. If You have such a printer, you can activate it with the
|
||||
following steps:
|
||||
|
||||
- Get local or remote access to the PosBox.
|
||||
- Plug in your printer
|
||||
- type ``lsusb`` in a prompt
|
||||
- Find your printer in the list of connected USB devices
|
||||
- Find your printer's vendor id: It consists of two hexadecimal numbers
|
||||
separated by a colon.
|
||||
- Edit ``~/openerp/addons/hw_escpos/escpos/supported_devices.py`` and
|
||||
add an entry for your printer.
|
||||
- Restar The PosBox.
|
||||
- If everything works properly you can send your printer's name and
|
||||
vendor ID to ``support@openerp.com`` and we'll add it to the list of
|
||||
supported devices.
|
||||
|
||||
Updating The PosBox Software
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The best way to update the PosBox software is to download a new version
|
||||
of the image and flash the SD-Card with it. This operation is described
|
||||
in details on the following tutorial
|
||||
``http://elinux.org/RPi_Easy_SD_Card_Setup``, just replace the standard
|
||||
raspberry pi image to the latest one found at
|
||||
``http://nightly.openerp.com/trunk/posbox/``
|
||||
|
||||
Troubleshoot
|
||||
------------
|
||||
|
||||
The POS cannot connect to the PosBox.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- The easiest way to make sure the PosBox is properly set-up is to turn
|
||||
it on with the printer plugged in as it will print a receipt
|
||||
indicating any error if encountered or the PosBox's IP adress in case
|
||||
of success. If no receipt is printed, check the following steps:
|
||||
- Make sure the PosBox is powered on, indicated by a brightly lid red
|
||||
status LED.
|
||||
- Make sure the PosBox is ready, this is indicated by a brightly lid
|
||||
green status LED just above the red power status LED. The PosBox
|
||||
should be ready one minute after it is powered on.
|
||||
- Make sure the PosBox is connected to the Network. This is indicated
|
||||
by a brightly lid yellow status LED.
|
||||
- Make sure the PosBox is connected to the same network as your POS
|
||||
device. Both the device and the posbox should be visible in the list
|
||||
of connected devices on your network router.
|
||||
- Make sure that your LAN is set up with DHCP, and gives ip Address in
|
||||
the range 192.168.0.X, 192.168.1.X, 10.0.0.X. If you cannot setup
|
||||
your LAN that way, you must manually set up your PosBox's ip-address.
|
||||
See the relevant paragraph in the Setup chapter of this documentation
|
||||
- If you have specified the PosBox's IP address in the config, make
|
||||
sure it correspond to the printed on the PosBox's status receipt.
|
||||
- Make sure that the POS is not loaded over HTTPS.
|
||||
- A bug in Firefox's HTTP implementation prevents the autodiscovery
|
||||
from working reliably. When using Firefox you should manually set up
|
||||
the PosBox's ip address in the POS config.
|
||||
|
||||
The Barcode Scanner is not working
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- The PosBox needs a 2A power supply to work with some barcode
|
||||
scanners. If you are not using the provided power supply, make sure
|
||||
the one you use has enough power.
|
||||
- Some barcode scanners will need more than 2A and will not work, or
|
||||
will work unreliably, even with the provided power supply. In those
|
||||
case you can plug the barcode scanner in a self-powered USB Hub.
|
||||
- Some poorly built barcode scanners do not advertise themselves as
|
||||
barcode scanners but as a usb keyboard instead, and will not be
|
||||
recognized by the PosBox.
|
||||
|
||||
The Barcode Scanner is not working reliably
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Make sure that no more than one device with 'Scan via Proxy' enabled
|
||||
are connected to the PosBox at the same time.
|
||||
|
||||
Printing the receipt takes too much time.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- A small delay before the first print is expected, as the PosBox will
|
||||
do some preprocessing to speed up the next printings. If you suffer
|
||||
delays afterwards it is most likely due to poor network connection
|
||||
between the POS and the PosBox.
|
||||
|
||||
Some characters are not correctly printed on the receipt.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- The PosBox does not support all languages and characters. It
|
||||
currently supports latin and cyrillic based scripts, with basic
|
||||
japanese support.
|
||||
|
||||
The Printer is Offline
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- The PosBox only supports EPSON TM-T20 printers. Make sure the printer
|
||||
is connected, powered, has enough paper and has its lid closed, and
|
||||
does is not in an error status. If the error persists, please contact
|
||||
support.
|
||||
|
||||
The Cashdrawer does not open.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- The cashdrawer should be connected to the printer and should be
|
||||
activated in the POS Configuration
|
||||
|
Loading…
Reference in New Issue