diff --git a/point_of_sale/posbox/index.rst b/point_of_sale/posbox/index.rst index 7972e8879..0b8166bf0 100644 --- a/point_of_sale/posbox/index.rst +++ b/point_of_sale/posbox/index.rst @@ -1,8 +1,8 @@ ====== -Posbox +POSBox ====== -Posbox Setup Guide +POSBox Setup Guide ================== .. image:: media/posbox_setup.png @@ -10,10 +10,10 @@ Posbox Setup Guide Prerequisites ------------- -Before you start setting up your Posbox make sure you have everything. +Before you start setting up your POSBox make sure you have everything. You will need : -* The Posbox +* The POSBox * A 2A Power adapter * A computer or tablet with an up-to-date web browser * A running SaaS or Odoo instance with the Point of Sale installed @@ -28,11 +28,11 @@ You will need : Step By Step Setup Guide ------------------------ -Current version of the posbox (since 2015) +Current version of the POSBox (since 2015) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: media/posbox_2_doc_schema.svg -Old version of the posbox (before 2015) +Old version of the POSBox (before 2015) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: media/posbox_doc_schema.svg @@ -58,7 +58,7 @@ hardware might work as well. * **Scale**: Connect your scale and power it on. * **Ethernet**: If you do not wish to use Wi-Fi, plug in the Ethernet - cable. Make sure this will connect the posbox to the same network as + cable. Make sure this will connect the POSBox to the same network as your POS device. * **Wi-Fi**: If you do not wish to use Ethernet, plug in a Linux @@ -68,16 +68,16 @@ hardware might work as well. Ethernet cable, because all Wi-Fi functionality will be bypassed when a wired network connection is available. -Power the posbox +Power the POSBox ~~~~~~~~~~~~~~~~ -Plug the power adapter into the posbox, a bright red status led should +Plug the power adapter into the POSBox, a bright red status led should light up. -Make sure the posbox is ready +Make sure the POSBox is ready ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once powered, The posbox needs a while to boot. Once the Posbox is +Once powered, The POSBox needs a while to boot. Once the POSBox is ready, it should print a status receipt with its IP address. Also the status LED, just next to the red power LED, should be permanently lit green. @@ -85,36 +85,36 @@ green. Setup the Point of Sale ~~~~~~~~~~~~~~~~~~~~~~~~ -To setup the posbox in the Point of Sale go to :menuselection:`Point +To setup the POSBox in the Point of Sale go to :menuselection:`Point of Sale --> Configuration --> Settings` and select your Point of -Sale. Scroll down to the ``Hardware Proxy / PosBox`` section and +Sale. Scroll down to the ``Hardware Proxy / POSBox`` section and activate the options for the hardware you want to use through the -posbox. Specifying the IP of the Posbox is recommended (it is printed -on the receipt that gets printed after booting up the posbox). When +POSBox. Specifying the IP of the POSBox is recommended (it is printed +on the receipt that gets printed after booting up the POSBox). When the IP is not specified the Point of Sale will attempt to find it on the local network. -If you are running multiple Point of Sales on the same Posbox, make sure +If you are running multiple Point of Sales on the same POSBox, make sure that only one of them has Remote Scanning/Barcode Scanner activated. -It might be a good idea to make sure the Posbox IP never changes in +It might be a good idea to make sure the POSBox IP never changes in your network. Refer to your router documentation on how to achieve this. Launch the Point of Sale ~~~~~~~~~~~~~~~~~~~~~~~~~ -If you didn't specify the Posbox's IP address in the configuration, +If you didn't specify the POSBox's IP address in the configuration, the POS will need some time to perform a network scan to find the -Posbox. This is only done once. +POSBox. This is only done once. -The Point of Sale is now connected to the Posbox and your hardware +The Point of Sale is now connected to the POSBox and your hardware should be ready to use. Wi-Fi configuration ------------------- -The posbox is Wi-Fi-capable. In order to use it you'll need a Linux +The POSBox is Wi-Fi-capable. In order to use it you'll need a Linux compatible USB Wi-Fi adapter. Most commercially available Wi-Fi adapters are Linux compatible. Officially supported are Wi-Fi adapters with a Ralink 5370 chipset. @@ -123,64 +123,64 @@ Make sure not to plug in an Ethernet cable, as all Wi-Fi related functionality will be disabled when a wired network connection is available. -When the posbox boots with a Wi-Fi adapter it will start its own Wi-Fi +When the POSBox boots with a Wi-Fi adapter it will start its own Wi-Fi Access Point called "Posbox" you can connect to. The receipt that gets -printed when the posbox starts will reflect this. In order to make the -posbox connect to an already existing Wi-Fi network, go to the -homepage of the posbox (indicated on the receipt) and go to the Wi-Fi +printed when the POSBox starts will reflect this. In order to make the +POSBox connect to an already existing Wi-Fi network, go to the +homepage of the POSBox (indicated on the receipt) and go to the Wi-Fi configuration page. On there you can choose a network to connect to. Note that we only support open and WPA(2)-PSK networks. When connecting to a WPA-secured network, fill in the password field. The -posbox will attempt to connect to the specified network and will print -a new posbox status receipt after it has connected. +POSBox will attempt to connect to the specified network and will print +a new POSBox status receipt after it has connected. -If you plan on permanently setting up the posbox with Wi-Fi, you can +If you plan on permanently setting up the POSBox with Wi-Fi, you can use the "persistent" checkbox on the Wi-Fi configuration page when connecting to a network. This will make the network choice persist across reboots. This means that instead of starting up its own "Posbox" network it will always attempt to connect to the specified network after it boots. -When the posbox fails to connect to a network it will fall back to +When the POSBox fails to connect to a network it will fall back to starting it's own "Posbox" Access Point. If connection is lost with a -Wi-Fi network after connecting to it, the Posbox will attempt to +Wi-Fi network after connecting to it, the POSBox will attempt to re-establish connection automatically. Multi-POS Configuration ----------------------- The advised way to setup a multi Point of Sale shop is to have one -Posbox per Point of Sale. In this case it is mandatory to manually -specify the IP address of each Posbox in each Point of Sale. You must -also configure your network to make sure the Posbox's IP addresses +POSBox per Point of Sale. In this case it is mandatory to manually +specify the IP address of each POSBox in each Point of Sale. You must +also configure your network to make sure the POSBox's IP addresses don't change. Please refer to your router documentation. -Posboxless Guide (advanced) +POSBoxless Guide (advanced) =========================== .. image:: media/posboxless_setup.png 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 +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 Odoo. You may also run into issues specific to your distribution or to your particular setup and hardware configuration. Drivers for the various types of supported hardware are provided as -Odoo modules. In fact, the posbox runs an instance of Odoo that the +Odoo modules. In fact, the POSBox runs an instance of Odoo that the Point of Sale communicates with. The instance of Odoo running on the -posbox is very different from a 'real' Odoo instance however. It does +POSBox is very different from a 'real' Odoo instance however. It does not handle *any* business data (eg. POS orders), but only serves as a gateway between the Point of Sale and the hardware. The goal of this section will be to setup a local Odoo instance that -behaves like the Odoo instance running on the Posbox. +behaves like the Odoo instance running on the POSBox. Image building process ---------------------- -We generate the official posbox images using the scripts in +We generate the official POSBox images using the scripts in https://github.com/odoo/odoo/tree/8.0/addons/point_of_sale/tools/posbox. More specifically, we run `posbox_create_image.sh `_. @@ -197,7 +197,7 @@ Summary of the image creation process The image creation process starts by downloading the latest `Raspbian `_ image. It then locally mounts this Raspbian image and copies over some files and scripts that will make -the Raspbian image turn itself into a posbox when it boots. These +the Raspbian image turn itself into a POSBox when it boots. These scripts will update Raspbian, remove non-essential packages and install required packages. In order to boot Raspbian we use qemu, which is capable of providing ARM emulation. After this, the emulated @@ -301,16 +301,16 @@ The IP address field in the POS configuration must be either server on the machine that you'll use as the Point of Sale device. You can also leave it empty. -Posbox Technical Documentation +POSBox Technical Documentation ============================== Technical Overview ------------------ -The Posbox Hardware +The POSBox Hardware ~~~~~~~~~~~~~~~~~~~ -The Posbox's Hardware is based on a `Raspberry Pi 2 +The POSBox's Hardware is based on a `Raspberry Pi 2 `_, a popular single-board computer. The Raspberry Pi 2 is powered with a 2A micro-usb power adapter. 2A is needed to give enough power to the @@ -324,22 +324,22 @@ Compatible Peripherals Officially supported hardware is listed on the `POS Hardware page `_. -The Posbox Software +The POSBox Software ~~~~~~~~~~~~~~~~~~~ -The Posbox runs a heavily modified Raspbian Linux installation, a +The POSBox runs a heavily modified Raspbian Linux installation, a Debian derivative for the Raspberry Pi. It also runs a barebones installation of Odoo which provides the webserver and the drivers. The hardware drivers are implemented as Odoo modules. Those modules are all prefixed with ``hw_*`` and they are the only modules that are -running on the Posbox. Odoo is only used for the framework it -provides. No business data is processed or stored on the Posbox. The +running on the POSBox. Odoo is only used for the framework it +provides. No business data is processed or stored on the POSBox. The Odoo instance is a shallow git clone of the ``8.0`` branch. -The root partition on the Posbox is mounted read-only, ensuring that +The root partition on the POSBox is mounted read-only, ensuring that we don't wear out the SD card by writing to it too much. It also ensures that the filesystem cannot be corrupted by cutting the power -to the Posbox. Linux applications expect to be able to write to +to the POSBox. Linux applications expect to be able to write to certain directories though. So we provide a ramdisk for /etc and /var (Raspbian automatically provides one for /tmp). These ramdisks are setup by ``setup_ramdisks.sh``, which we run before all other init @@ -356,47 +356,47 @@ Logs of the running Odoo server can be found at: ``/var/log/odoo/odoo.log`` -Various posbox related scripts (eg. wifi-related scripts) running on -the posbox will log to /var/log/syslog and those messages are tagged +Various POSBox related scripts (eg. wifi-related scripts) running on +the POSBox will log to /var/log/syslog and those messages are tagged with ``posbox_*``. -Accessing the Posbox +Accessing the POSBox -------------------- Local Access ~~~~~~~~~~~~ -If you plug a QWERTY USB keyboard into one of the Posbox's USB ports, +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 GNU/Linux computer and perform +POSBox, you can use it as a small GNU/Linux computer and perform various administration tasks, like viewing some logs. -The posbox will automatically log in as root on the default tty. +The POSBox will automatically log in as root on the default tty. Remote Access ~~~~~~~~~~~~~ -If you have the Posbox's IP address and an SSH client you can access -the Posbox's system remotely. The login credentials are +If you have the POSBox's IP address and an SSH client you can access +the POSBox's system remotely. The login credentials are ``pi``/``raspberry``. -Updating The Posbox Software +Updating The POSBox Software ---------------------------- -Only upgrade the Posbox if you experience problems or want to use +Only upgrade the POSBox if you experience problems or want to use newly implemented features. -The best way to update the Posbox software is to download a new +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 detail in `this tutorial `_, just replace the standard Raspberry Pi image with the latest one found at `the official -posbox image page `_. This +POSBox image page `_. This method of upgrading will ensure that you're running the latest version -of the Posbox software. +of the POSBox software. The second way of upgrading is through the built in upgrade interface -that can be reached through the posbox homepage. The nice thing about +that can be reached through the POSBox homepage. The nice thing about upgrading like this is that you don't have to flash a new image. This upgrade method is limited to what it can do however. It can not eg. update installed configuration files (like @@ -410,33 +410,33 @@ When in doubt, always use the first method of upgrading. Troubleshoot ============ -The POS cannot connect to the Posbox +The POS cannot connect to the POSBox ------------------------------------ -- The easiest way to make sure the Posbox is properly set-up is to turn +- 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 address in case + indicating any error if encountered or the POSBox's IP address in case of success. If no receipt is printed, check the following steps: -- Make sure the Posbox is powered on, indicated by a brightly lit red +- Make sure the POSBox is powered on, indicated by a brightly lit red status LED. -- Make sure the Posbox is ready, this is indicated by a brightly lit - green status LED just next to the red power status LED. The Posbox +- Make sure the POSBox is ready, this is indicated by a brightly lit + green status LED just next to the red power status LED. The POSBox should be ready ~2 minutes after it is started. -- 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 +- 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 addresses 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 + 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 configuration, - make sure it correspond to the printed on the Posbox's status +- If you have specified the POSBox's IP address in the configuration, + 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 configuration. + the POSBox's IP address in the POS configuration. The Barcode Scanner is not working ---------------------------------- @@ -445,7 +445,7 @@ The Barcode Scanner is not working Enter after each barcode. This is the default configuration of most barcode readers. Refer to the barcode reader documentation for more information. -- The Posbox needs a 2A power supply to work with some barcode +- 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 @@ -453,27 +453,27 @@ The Barcode Scanner is not working 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. + recognized by the POSBox. The Barcode Scanner is not working reliably ------------------------------------------- - Make sure that no more than one device with 'Scan via - Proxy'/'Barcode Scanner' enabled are connected to the Posbox at the + Proxy'/'Barcode Scanner' 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 +- 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. + 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 +- The POSBox does not support all languages and characters. It currently supports Latin and Cyrillic based scripts, with basic Japanese support. @@ -492,7 +492,7 @@ The cashdrawer does not open Credits ======= -The Posbox project was developed by Frédéric van der Essen with the +The POSBox project was developed by Frédéric van der Essen with the kind help of Gary Malherbe, Fabien Meghazi, Nicolas Wisniewsky, Dimitri Del Marmol, Joren Van Onder and Antony Lesuisse. @@ -514,7 +514,7 @@ partners who backed the campaign with founding partner bundles: - OpusVL And also the partners who've backed the development with the Founding -Posbox Bundle: +POSBox Bundle: - Willow IT - E\. Akhalwaya & Sons