NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[FIX] iot: Update and fix IoT documentation (#776)

Browse Source 
Some of the explanations were wrong/outdated.
We also add a troubleshooting guide with most
common problems.
This commit is contained in:
Antoine Prieëls
2020-10-22 14:32:59 +02:00
committed by GitHub
parent b3f119724d
commit d00e0bd870
19 changed files with 206 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files
iot/config/flash_sdcard.rst
+24 -9
View File
@@ -5,18 +5,33 @@ Flashing your SD Card
In some case, you may need to reflash your IoT Box’s SD Card to benefit
from our latest updates.
Updating your SD Card with Etcher
Upgrade from the IoT Box homepage
=================================
Go to Balena’s website and download
`Etcher <https://www.balena.io/>`__, It’s a free and
open-source utility used for burning image files. Install and launch it.
Go to the IoT Box homepage, click on *Update*, next to the version number.
If a new version of the IoT Box image is available, you will see a
*Upgrade to ___* button a the bottom of the page, the IoT Box will then
flash itself to the new version of the IoT Box. All of your configurations
will be saved.
Now, download the latest image `here <http://nightly.odoo.com/master/posbox/iotbox/>`__, and extract it from the zip file. Then, open *Etcher* and select the image.
Select the drive to flash (where your SD Card is) and click on
*Flash*!.
Now, your image will be automatically updated. You just have to wait 5 minutes for it to finish.
.. note::
This process can take more than 30 minutes. Do not turn off or unplug
the IoT Box as it would leave it in an inconsistent state.
.. image:: media/flash_sdcard01.png
:align: center
Upgrade with Etcher
===================
Go to Balena’s website and download `Etcher <https://www.balena.io/>`__.
It’s a free and open-source utility used for burning image files.
Install and launch it. Download the latest image from `nightly
<http://nightly.odoo.com/master/iotbox/>`__.
Then, open *Etcher* and select *Flash from file*, find the image you just
downloaded. Insert the IoT Box SD card into your computer and select it.
Click on *Flash* and wait for the process to finish.
.. image:: media/flash_sdcard02.png
:align: center
iot/config/iot_notfound.rst
-24
View File
@@ -1,24 +0,0 @@
=================
IoT Box not found
=================
When using your IoT Box, a common issue you might encounter is that your
box is not found on your database. Fortunately, there are a few easy
steps you can follow to find your IoT box.
HTTPS Issues
============
Your IoT Box is not found? You probably have https issues!
To check it, go to your database and verify if your database address
starts with an https (like https://www.odoo.com). If this is the case,
then you may have problems with your IoT Box image. It should be version
18.12 or later.
If your IoT Box image is from an earlier version, then you will have to
reflash the SD card of your IoT Box to update the image (the latest
image can be found `here <http://nightly.odoo.com/master/posbox/iotbox/>`__).
.. seealso::
- :doc:`flash_sdcard`
iot/config/media/flash_sdcard01.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 79 KiB

iot/config/media/flash_sdcard02.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

iot/config/media/troubleshooting_barcode_01.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

iot/config/media/troubleshooting_printer_01.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

iot/config/media/troubleshooting_printer_02.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

iot/config/pos.rst
+24 -121
View File
@@ -10,9 +10,7 @@ Prerequisites
Before starting, make sure you have the following:
- An IoT Box
- A 2A Power adapter with pi 3 b+ 2.5 A
- An IoT Box, with its power adapter.
- A computer or tablet with an up-to-date web browser
@@ -21,16 +19,13 @@ Before starting, make sure you have the following:
- A local network setup with DHCP (this is the default setting)
- An Epson USB TM-T20 Printer or another ESC/POS compatible printer
(officially supported printers are listed at the `POS Hardware
page <https://www.odoo.com/page/pos-ipad-android-hardware>`__)
- A Honeywell Eclipse USB Barcode Scanner or another compatible scanner
- An Epson compatible cash drawer
- An RJ45 Ethernet Cable (optional, WiFi is built in)
- Any of the supported hardware (receipt printer, barcode scanner,
cash drawer, payment terminal, scale, customer display, etc.).
The list of supported hardware can be found on the `POS Hardware
page <https://www.odoo.com/page/point-of-sale-hardware>`__
Set Up
~~~~~~~
@@ -38,128 +33,36 @@ To connect hardware to the PoS, the first step is to connect an IoT Box
to your database. For this, follow this
:doc:`documentation <connect>`.
.. image:: media/pos02.png
:align: center
Then, you have to connect the peripheral devices to your IoT Box.
Officially supported hardware is listed on `the POS Hardware
page <https://www.odoo.com/page/pos-ipad-android-hardware>`__, but
other hardware might work as well.
- **Printer**: Connect an ESC/POS printer to a USB port and power it
on.
- **Printer**: Connect a supported receipt printer to a USB port or to
the network 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.
barcode scanner to be compatible it 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 IoT Box to the same
network as your POS device.
- **Customer Display**: Connect a monitor to the IoT Box using an HDMI
cable. You can also access the Customer Display from any other computer
by accessing the IoT Box homepage and clicking on the *POS Display*
button.
- **Wi-Fi**: The current version of the IoT Box has Wi-Fi built in.
Make sure not to plug in an Ethernet cable when booting, because
all Wi-Fi functionality will be bypassed when a wired network
connection is available on boot.
- **Payment terminal**: The connection process depends on the terminal,
please refer to the :doc:`payment terminals documentation
<../../point_of_sale/payment>`.
Once it's done, you can connect the IoT Box to your PoS. For this, go in
:menuselection:`Point of Sale --> Configuration --> PoS`, tick the box "IoT Box" and select
the IoT Box you want to connect with. Save the changes.
:menuselection:`Point of Sale --> Configuration --> PoS`, tick *IoT Box*
and select the devices you want to use in this Point of Sale. Save the
changes.
.. image:: media/pos02.png
:align: center
Set up is done, you can launch a new PoS Session.
Troubleshoot
~~~~~~~~~~~~
The PoS cannot connect to the IoT Box
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The easiest way to make sure the IoT Box 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 IoT Box's IP address
in case of success. If no receipt is printed, check the following
steps:
- Make sure the IoT Box is powered on, indicated by a brightly lit red
status LED.
- Make sure the IoT Box is ready, this is indicated by a brightly lit
green status LED just next to the red power status LED. The IoT
Box should be ready ~2 minutes after it is started.
- Make sure the IoT Box is connected to the same network as your POS
device. Both the device and the IoT Box should be visible in the
list of connected devices on your network router.
- If you specified the IoT Box's IP address in the configuration, make
sure it corresponds to the ip address printed on the IoT Box's
status receipt.
- Make sure that the POS is not loaded over HTTPS.
- A bug in Firefox's HTTP implementation might prevent the
autodiscovery from working reliably. You could also manually set
up the IoT Box's IP address in the POS configuration.
The Barcode Scanner is not working
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The barcode scanner must be configured in US QWERTY and emit an Enter
after each barcode. This is the default configuration of most
barcode readers. Refer to the barcode reader documentation for
more information.
- The IoT Box 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 IoT Box.
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 IoT Box at the same time.
Printing the receipt takes too much time
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- A small delay before the first print is expected, as the IoT Box 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 IoT Box.
Some characters are not correctly printed on the receipt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The IoT Box does not support all languages and characters. It
currently supports Latin and Cyrillic based scripts, with basic
Japanese support.
The printer is offline
^^^^^^^^^^^^^^^^^^^^^^
- Make sure the printer is connected, powered, has enough paper and has
its lid closed, and is not reporting an error. 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.
iot/config/troubleshooting.rst
+134
View File
@@ -0,0 +1,134 @@
===============
Troubleshooting
===============
IoT Box Connection
==================
I can't find the pairing code to connect my IoT Box
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The pairing code should be printed on receipt printers connected to the
IoT Box and should also be displayed on connected monitors.
The pairing code doesn't show under the following circumstances:
- The IoT Box is already connected to an Odoo database;
- The IoT Box is not connected to the Internet;
- The code is only valid for 5 minutes after the IoT Box has started. It's
automatically removed from connected displays when this delay has expired;
- The version of the IoT Box image is too old. It should use version 20.06
or more recent. If your IoT Box image is from an earlier version, then
you will have to reflash the SD card of your IoT Box to update the image
(see :doc:`Flashing your SD Card <flash_sdcard>`)
If you are not in any of the cases listed above, make sure that the IoT Box
has correctly started, by checking that a fixed green LED is showing next to
the micro-USB port.
I've connected my IoT Box but it's not showing in my database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you connect an IoT Box to a database, the IoT Box might restart, if
that is the case, it might take up to one minute before appearing in your
database. If after some time the IoT is still not showing, make sure that
your database can be reached from the IoT Box and that your server doesn't
use a multi-database environment.
My IoT Box is connected to my database, but cannot be reached
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure that the IoT Box and the device running the browser are located
on the same network as the IoT Box cannot be reached from outside the local
network.
Printer
=======
My printer is not detected
~~~~~~~~~~~~~~~~~~~~~~~~~~
If one of your printers doesn't show up in your devices list, go to the
IoT Box homepage and make sure that it is listed under *Printers*.
.. image:: media/troubleshooting_printer_01.png
:align: center
If your printer is not present on the IoT Box homepage, hit
*Printers Server*, go to the *Administration* tab and click on
*Add Printer*. If you can't find your printer in the list, it's probably
not connected properly.
My printer outputs random text
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For most printers, the correct driver should be automatically detected
and selected. However, in some cases, the automatic detection mechanism
might not be enough, and if no driver is found the printer might print
random characters.
The solution is to manually select the corresponding driver. On the IoT
Box homepage, click on *Printers Server*, go to the *Printers*
tab and select the printer in the list. In the Administration dropdown,
click on *Modify Printer*. Follow the steps and select the Make and Model
corresponding to your printer.
.. image:: media/troubleshooting_printer_02.png
:align: center
.. note::
Epson and Star receipt printers and Zebra label printers do not
need a driver to work. Make sure that no driver is selected for those
printers.
My Zebra Printer doesn't print anything
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Zebra printers are quite sensitive to the format of the ZPL code that is
printed. If nothing comes out of the printer or blank labels are printed,
try changing the format of the report that is sent to the printer by
accessing :menuselection:`Settings ~~> Technical ~~> Views` in developer
mode and look for the corresponding template.
Barcode Scanner
===============
The characters read by the barcode scanner don't match the barcode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, we assume that your barcode scanner is configured in US
QWERTY. This is the default configuration of most barcode readers.
If your barcode scanner uses a different layout, please go to the
form view of your device and select the correct one.
Nothing happens when a barcode is scanned
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure that the correct device is selected in your Point of Sale
configuration and that your barcode is configured to send an ENTER
character (keycode 28) at the end of every barcode.
The barcode scanner is detected as a keyboard
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 IoT Box.
You can manually change the device type by going to its form view and
activating the *Is scanner* option.
.. image:: media/troubleshooting_barcode_01.png
:align: center
Cashdrawer
==========
The cashdrawer does not open
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The cashdrawer should be connected to the printer and the *Cashdrawer*
checkbox should be ticked in the POS configuration.