Point of Sale Hardware Setup

Current version of the POSBox (since 2015)

Connect peripheral devices

Officially supported hardware is listed on the POS Hardware page, but other hardware might work as well.

• Printer: Connect an ESC/POS printer to a USB port and power it on.
• Cash drawer: The cash drawer should be connected to the printer with an RJ25 cable.
• Barcode scanner: Connect your barcode scanner. In order for your barcode scanner to be compatible it must behave as a keyboard and must be configured in US QWERTY. It also must end barcodes with an Enter character (keycode 28). This is most likely the default configuration of your barcode scanner.
• 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 your POS device.
• Wi-Fi: The current version of the POSBox has Wi-Fi built in. Make sure not to plug in an Ethernet cable, because all Wi-Fi functionality will be bypassed when a wired network connection is available.

Power the POSBox

Plug the power adapter into the POSBox, a bright red status led should light up.

Make sure the POSBox is ready

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.

Setup the Point of Sale

To setup the POSBox in the Point of Sale go to :menuselection:`Point of Sale --> Configuration --> Point of Sale` and select your Point of Sale. Scroll down to the PoSBox / Hardware Proxy 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 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 Sale 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 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, 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.

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 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 Raspbian OS will shut itself down. We then once again locally mount the image, remove the scripts that were used to initialize the image at boot and we copy over some extra configuration files. The resulting image is then ready to be tested and used.

Extra dependencies

Because Odoo runs on Python 2, you need to check which version of pip you need to use.

# pip --version

If it returns something like:

pip 1.5.6 from /usr/local/lib/python3.3/dist-packages/pip-1.5.6-py3.3.egg (python 3.3)

You need to try pip2 instead.

If it returns something like:

pip 1.4.1 from /usr/lib/python2.7/dist-packages (python 2.7)

You can use pip.

The driver modules requires the installation of new python modules:

# pip install pyserial

# pip install pyusb==1.0.0b1

# pip install qrcode

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 access to USB devices

# groupadd usbusers

Then we add the user who will run the Odoo server to usbusers

# usermod -a -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.rules 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.

Start the local Odoo instance

We must launch the Odoo server with the correct settings

$ ./odoo.py --load=web,hw_proxy,hw_posbox_homepage,hw_posbox_upgrade,hw_scale,hw_scanner,hw_escpos

Test the instance

Plug all your hardware to your machine's USB ports, and go to http://localhost:8069/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 superseded by others.

Automatically start Odoo

You must now make sure that this Odoo install is automatically started after boot. There are various ways to do so, and how to do it depends on your particular setup. Using the init system provided by your distribution is probably the easiest way to accomplish this.

Setup the Point of Sale

The IP address field in the POS configuration must be either 127.0.0.1 or localhost if you're running the created Odoo server on the machine that you'll use as the Point of Sale device. You can also leave it empty.

The POSBox Hardware

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 barcode scanners. The Software is installed on a 8Gb Class 10 or Higher SD Card. All this hardware is easily available worldwide from independent vendors.

Compatible Peripherals

Officially supported hardware is listed on the POS Hardware page.

The POSBox Software

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 Odoo instance is a shallow git clone of the 11.0 branch.

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 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 scripts by running it in /etc/init.d/rcS. The ramdisks are named /etc_ram and /var_ram respectively. Most data from /etc and /var is copied to these tmpfs ramdisks. In order to restrict the size of the ramdisks, we do not copy over certain things to them (eg. apt related data). We then bind mount them over the original directories. So when an application writes to /etc/foo/bar it's actually writing to /etc_ram/foo/bar. We also bind mount / to /root_bypass_ramdisks to be able to get to the real /etc and /var during development.

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 with posbox_*.

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 GNU/Linux computer and perform various administration tasks, like viewing some logs.

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 pi/raspberry.