addons/hw_proxy/doc/index.rst

   1 ====================
   2 PosBox Documentation
   3 ====================
   4
   5 Posbox Setup Guide
   6 ==================
   7
   8 Prerequisites
   9 -------------
  10
  11 Before you start setting up your PosPox make sure you have everything.
  12 You will need :
  13
  14 -  The PosBox
  15 -  A 2A Power adapter
  16 -  A computer or tablet with an up to date Firefox, Chrome or Safari web
  17    browser (we recommend Chrome)
  18 -  A running SaaS or V8.0 OpenERP Instance with the Point of Sale
  19    Installed.
  20 -  A local network set up with DHCP ( this is the default setting )
  21 -  A RJ45 Ethrnet Cable
  22 -  An Epson USB TM-T20 Printer or another compatible printer.
  23 -  A Honewell Voyager USB Barcode Scanner or another compatible scanner.
  24 -  An Epson compatible cash drawer.
  25
  26 Setup
  27 -----
  28
  29 .. image:: _images/posbox_doc_schema.png
  30     :width: 100%
  31     :align: center
  32
  33 1) Power the PosBox.
  34 ~~~~~~~~~~~~~~~~~~~~
  35
  36 Plug the PosBox to the 2A Power Adapter, a bright red status led should
  37 light up.
  38
  39 2) Connect it to the Local Network
  40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  41
  42 Connect the PosBox to the Local Network with the RJ45 Cable. Make sure
  43 You connect the PosBox to the same Network as your POS device. Once
  44 connected a bright yellow status led should light up, and a green status
  45 led should flash.
  46
  47 3) Connect the USB Printer
  48 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  49
  50 Put a paper roll in the printer, power it up, then connect it to one of
  51 the PosBox's USB port
  52
  53 4) Connect the cash drawer
  54 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  55
  56 The cash drawer should be connected to the printer with the RJ25 cable
  57
  58 5) Connect the USB Barcode Scanner
  59 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  60
  61 Connect the usb barcode scanner to one of the PosBox's USB port. The
  62 Barcode Scanner should immediately light up and emit a loud beep.
  63
  64 6) Configure the USB Barcode Scanner
  65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  66
  67 The barcode scanner should be configured in QWERTY and emit a new line /
  68 return symbol after each scan. This is most likely the default
  69 configuration of your barcode scanner.
  70
  71 7) Make sure the PosBox is ready
  72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73
  74 Once powered, The PosBox needs less than a minute to boot. Once the
  75 PosBox is ready, it should print a status receipt with its IP Adress.
  76 Also, the last status led, just after the red power status led, should
  77 be permanently lit green.
  78
  79 8) Set up the Point of Sale
  80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  81
  82 Make sure to activate the 'Print via Proxy', 'Remote Scanning' or
  83 'Cashdrawer' options in the Point of Sale configuration. If you are
  84 using firefox, you must manually specify the PosBox's IP address which
  85 was printed on the status receipt.
  86
  87 If you are running multiple Point of Sales on the same PosBox, make sure
  88 that only one of them has Remote Scanning activated.
  89
  90 9) Launch the Point of Sale.
  91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92
  93 If you didn't spcecify the PosBox's IP address in the config, the POS
  94 will need some time to perform a network scan to find the PosBox. This
  95 is only done once.
  96
  97 The Point of Sale is now connected to the PosBox and your Hardware
  98 should be ready to use.
  99
 100 PosBoxless Setup Guide
 101 ======================
 102
 103 If you are running your Point of Sale on a debian-based linux
 104 distribution, you do not need the PosBox as you can run its software
 105 locally. However the installation process is not foolproof. You'll need
 106 at least to know how to install and run openerp. You may also run into
 107 issues specific to your distribution or to your particular setup and
 108 hardware configuration.
 109
 110 Prerequisites
 111 -------------
 112
 113 -  A debian based linux distribution (Debian, Ubuntu, Mint, etc.)
 114 -  A running trunk version of the OpenERP server
 115 -  You must uninstall any esc-pos printer driver as it will conflict
 116    with OpenERP's built-in driver.
 117
 118 Setup
 119 -----
 120
 121 1) Extra dependencies
 122 ~~~~~~~~~~~~~~~~~~~~~
 123
 124 The driver modules requires the installation of new python modules:
 125
 126 ::
 127
 128     $ sudo pip install pyserial
 129     $ sudo pip install --pre pyusb
 130
 131 2) Database Setup
 132 ~~~~~~~~~~~~~~~~~
 133
 134 You must create a database called ``posbox`` with the modules
 135 ``hw_proxy``, ``hw_escpos``, and ``hw_scanner`` installed.
 136
 137 3) Access Rights
 138 ~~~~~~~~~~~~~~~~
 139
 140 The drivers need raw access to the printer and barcode scanner devices.
 141 Doing so requires a bit system administration. First we are going to
 142 create a group that has haccess to usb devices:
 143
 144 ::
 145
 146     $ sudo groupadd usbusers
 147
 148 Then we add the user who will run the OpenERP server to ``usbusers``
 149
 150 ::
 151
 152     $ sudo useradd -G usbusers USERNAME
 153
 154 Then we need to create a udev rule that will automatically allow members
 155 of ``usbusers`` to access raw usb devices. To do so create a file called
 156 ``99-usbusers.rule`` in the ``/etc/udev/rules.d/`` directory with the
 157 following content:
 158
 159 ::
 160
 161     SUBSYSTEM=="usb", GROUP="usbusers", MODE="0660"
 162     SUBSYSTEMS=="usb", GROUP="usbusers", MODE="0660"
 163
 164 Then you need to reboot your machine.
 165
 166 4) Start the local OpenERP Installl
 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168
 169 We must launch the OpenERP server on the port ``8069`` with the correct
 170 database settings:
 171
 172 ::
 173
 174     $ ./server/openerp-server --addons-path=addons,web/addons --db-filter='^posbox$' \
 175             --xmlrpc-port=8069 -d posbox
 176
 177 5) Check that everything works
 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 179
 180 Plug all your hardware to your machine's USB ports, and go to
 181 ``http://localhost/hw_proxy/status`` refresh the page a few times and
 182 see if all your devices are indicated as *Connected*. Possible source of
 183 errors are: The paths on the distribution differ from the paths expected
 184 by the drivers, another process has grabbed exclusive access to the
 185 devices, the udev rules do not apply or a superceeded by others.
 186
 187 5) Automatically Start OpenERP
 188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 189
 190 You must now make sure that this OpenERP install is automatically
 191 started after boot. There are various ways to do so, and how to do it
 192 depends on your particular setup. We use *systemd* on the PosBox, but
 193 *upstart* or *sysvinit* are other options.
 194
 195 6) Set up the Point of Sale
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 198 Make sure that one of the posbox Make sure the IP Adress field in the
 199 POS Config is either ``127.0.0.1`` or ``localhost`` or simply leave it
 200 empty.
 201
 202 PosBox Technical Documentation
 203 ==============================
 204
 205 Technical Overview
 206 ------------------
 207
 208 The PosBox Hardware
 209 ~~~~~~~~~~~~~~~~~~~
 210
 211 The PosBox's Hardware is based on a model B Raspberry Pi, a popular
 212 open-source micro-computer. The Raspberry Pi is powered with a 2A
 213 micro-usb power adapter. 2A is needed to give enough power to the
 214 barcode scanners. And we recommend Samsung power adapters for their
 215 availability and reliability ( but beware of counterfeits ). The
 216 Raspberry is protected by a ModMyPi Raspberry Pi Case. The Software is
 217 installed on a 8Gb Class 10 or Higher SD Card. The SD Card's class is
 218 important to ensure good performances. All this hardware is easily
 219 available worldwide from independant vendors.
 220
 221 Compatible Peripherals
 222 ~~~~~~~~~~~~~~~~~~~~~~
 223
 224 -  Printers:
 225
 226    -  Epson TM-T20
 227    -  Support for Other Esc-Pos compatible printers can be easily added
 228       on a case-by-case basis, please see the *Unsupported Printers*
 229       chapter of this manual.
 230
 231 -  Barcode Scannners:
 232
 233    -  Metapace S61
 234    -  Honeywell Voyager 95x0 Series.
 235    -  Most other barcode scanners should work out of the box. Some
 236       barcode scanners need more power than the PosBox can provide and
 237       must be plugged in a self-powered USB HUB. This is the case for
 238       Datalogic Barcode Scanners.
 239
 240 -  Cash Drawers:
 241
 242    -  As the cash drawers are connected to the printer, All Epson
 243       compatible cash drawers should work out of the Box.
 244
 245 The PosBox Software
 246 ~~~~~~~~~~~~~~~~~~~
 247
 248 The PosBox runs a Raspbian Linux distribution, a Debian derivative
 249 optimized for the Raspberry Pi. It also runs a barebones install of
 250 OpenERP which provides the webserver and the drivers. The printer &
 251 scanner drivers are implemented as openerp modules. Those modules are
 252 named ``hw_proxy``, ``hw_escpos``, ``hw_scanner`` and are the only
 253 modules installed and running. OpenERP is only used for the framework it
 254 provides. No business data is processed or stored on the PosBox. The
 255 OpenERP install is a full bazaar clone of the ``trunk`` branch, and can
 256 thus be updated trough the usual means.
 257
 258 We use systemd to manage the Openerp server. Systemd makes sure OpenERP
 259 starts up at boot and is always up and running. Its systemd unit file is
 260 called ``openerp.service``, and can be found in
 261 ``/etc/systemd/system/openerp.service``. The systemd version used is
 262 quite old and thus ``journalctl`` is not available. All logs can be
 263 found in instead ``/var/logs/syslog``
 264
 265 We removed all graphical software from the default install to reduce to
 266 image size but nothing prevents you from reinstalling them.
 267
 268 Local Access
 269 ~~~~~~~~~~~~
 270
 271 If you plug a QWERTY USB keyboard into one of the PosBox's USB ports,
 272 and if you connect a computer monitor to the *HDMI* port of the PosBox,
 273 you can use it as a small UNIX computer and perform various
 274 administration tasks.
 275
 276 Once the PosBox is ready press ``ALT-F2`` to access the login prompt.
 277 The login is ``pi`` and the password ``admin``. The OpenERP install is
 278 in the ``~/openerp`` directory along with a few scripts to help with
 279 debugging and administration.
 280
 281 Remote Access
 282 ~~~~~~~~~~~~~
 283
 284 If you have the PosBox's IP address and a SSH client you can access the
 285 PosBox's system remotely. The login / password are ``pi``/``admin``
 286
 287 Unsupported Printers
 288 ~~~~~~~~~~~~~~~~~~~~
 289
 290 The PosBox should be able to print to any ESC-POS printer, not just the
 291 Epson TM-T20. If You have such a printer, you can activate it with the
 292 following steps:
 293
 294 -  Get local or remote access to the PosBox.
 295 -  Plug in your printer
 296 -  type ``lsusb`` in a prompt
 297 -  Find your printer in the list of connected USB devices
 298 -  Find your printer's vendor id: It consists of two hexadecimal numbers
 299    separated by a colon.
 300 -  Edit ``~/openerp/addons/hw_escpos/escpos/supported_devices.py`` and
 301    add an entry for your printer.
 302 -  Restar The PosBox.
 303 -  If everything works properly you can send your printer's name and
 304    vendor ID to ``support@openerp.com`` and we'll add it to the list of
 305    supported devices.
 306
 307 Updating The PosBox Software
 308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 309
 310 The best way to update the PosBox software is to download a new version
 311 of the image and flash the SD-Card with it. This operation is described
 312 in details on the following tutorial
 313 ``http://elinux.org/RPi_Easy_SD_Card_Setup``, just replace the standard
 314 raspberry pi image to the latest one found at
 315 ``http://nightly.openerp.com/trunk/posbox/``
 316
 317 Troubleshoot
 318 ------------
 319
 320 The POS cannot connect to the PosBox.
 321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 322
 323 -  The easiest way to make sure the PosBox is properly set-up is to turn
 324    it on with the printer plugged in as it will print a receipt
 325    indicating any error if encountered or the PosBox's IP adress in case
 326    of success. If no receipt is printed, check the following steps:
 327 -  Make sure the PosBox is powered on, indicated by a brightly lid red
 328    status LED.
 329 -  Make sure the PosBox is ready, this is indicated by a brightly lid
 330    green status LED just above the red power status LED. The PosBox
 331    should be ready one minute after it is powered on.
 332 -  Make sure the PosBox is connected to the Network. This is indicated
 333    by a brightly lid yellow status LED.
 334 -  Make sure the PosBox is connected to the same network as your POS
 335    device. Both the device and the posbox should be visible in the list
 336    of connected devices on your network router.
 337 -  Make sure that your LAN is set up with DHCP, and gives ip Address in
 338    the range 192.168.0.X, 192.168.1.X, 10.0.0.X. If you cannot setup
 339    your LAN that way, you must manually set up your PosBox's ip-address.
 340    See the relevant paragraph in the Setup chapter of this documentation
 341 -  If you have specified the PosBox's IP address in the config, make
 342    sure it correspond to the printed on the PosBox's status receipt.
 343 -  Make sure that the POS is not loaded over HTTPS.
 344 -  A bug in Firefox's HTTP implementation prevents the autodiscovery
 345    from working reliably. When using Firefox you should manually set up
 346    the PosBox's ip address in the POS config.
 347
 348 The Barcode Scanner is not working
 349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 350
 351 -  The PosBox needs a 2A power supply to work with some barcode
 352    scanners. If you are not using the provided power supply, make sure
 353    the one you use has enough power.
 354 -  Some barcode scanners will need more than 2A and will not work, or
 355    will work unreliably, even with the provided power supply. In those
 356    case you can plug the barcode scanner in a self-powered USB Hub.
 357 -  Some poorly built barcode scanners do not advertise themselves as
 358    barcode scanners but as a usb keyboard instead, and will not be
 359    recognized by the PosBox.
 360
 361 The Barcode Scanner is not working reliably
 362 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 363
 364 -  Make sure that no more than one device with 'Scan via Proxy' enabled
 365    are connected to the PosBox at the same time.
 366
 367 Printing the receipt takes too much time.
 368 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 369
 370 -  A small delay before the first print is expected, as the PosBox will
 371    do some preprocessing to speed up the next printings. If you suffer
 372    delays afterwards it is most likely due to poor network connection
 373    between the POS and the PosBox.
 374
 375 Some characters are not correctly printed on the receipt.
 376 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 377
 378 -  The PosBox does not support all languages and characters. It
 379    currently supports latin and cyrillic based scripts, with basic
 380    japanese support.
 381
 382 The Printer is Offline
 383 ~~~~~~~~~~~~~~~~~~~~~~
 384
 385 -  The PosBox only supports EPSON TM-T20 printers. Make sure the printer
 386    is connected, powered, has enough paper and has its lid closed, and
 387    does is not in an error status. If the error persists, please contact
 388    support.
 389
 390 The Cashdrawer does not open.
 391 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 392
 393 -  The cashdrawer should be connected to the printer and should be
 394    activated in the POS Configuration
 395