From 49e81fb1339d836c310730d708fab447445a404d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20van=20der=20Essen?= Date: Tue, 18 Feb 2014 15:11:29 +0100 Subject: [PATCH] [IMP] hw_proxy: initial commit for the posbox's documentation bzr revid: fva@openerp.com-20140218141129-sa4bhpi535sd7uhb --- addons/hw_proxy/doc/index.rst | 390 ++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 addons/hw_proxy/doc/index.rst diff --git a/addons/hw_proxy/doc/index.rst b/addons/hw_proxy/doc/index.rst new file mode 100644 index 00000000000..c44f9c870bc --- /dev/null +++ b/addons/hw_proxy/doc/index.rst @@ -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 +