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

Some of the explanations were wrong/outdated.
We also add a troubleshooting guide with most
common problems.

iot/config.rst

@@ -7,6 +7,6 @@ Configuration
    :glob:
 
    config/connect
+   config/pos
    config/flash_sdcard
-   config/iot_notfound
+   config/troubleshooting
-   config/pos

iot/config/flash_sdcard.rst

@@ -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
+Go to the IoT Box homepage, click on *Update*, next to the version number.
-`Etcher <https://www.balena.io/>`__, It’s a free and
+If a new version of the IoT Box image is available, you will see a
-open-source utility used for burning image files. Install and launch it.
+*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.
+.. note::
-Select the drive to flash (where your SD Card is) and click on
+   This process can take more than 30 minutes. Do not turn off or unplug
-*Flash*!.
+   the IoT Box as it would leave it in an inconsistent state. 
-
-Now, your image will be automatically updated. You just have to wait 5 minutes for it to finish.
 
 .. 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

@@ -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/pos.rst

@@ -10,9 +10,7 @@ Prerequisites
 
 Before starting, make sure you have the following:
 
--  An IoT Box
+-  An IoT Box, with its power adapter.
-
--  A 2A Power adapter with pi 3 b+ 2.5 A
 
 -  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
+-  **Printer**: Connect a supported receipt printer to a USB port or to
-page <https://www.odoo.com/page/pos-ipad-android-hardware>`__, but
+   the network and power it on.
-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
+   barcode scanner to be compatible it must end barcodes with an Enter
-   must be configured in **US QWERTY**. It also must end barcodes
+   character (keycode 28). This is most likely the default configuration
-   with an Enter character (keycode 28). This is most likely the
+   of your barcode scanner.
-   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
+-  **Customer Display**: Connect a monitor to the IoT Box using an HDMI
-   cable. Make sure this will connect the IoT Box to the same
+   cable. You can also access the Customer Display from any other computer
-   network as your POS device.
+   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.
+-  **Payment terminal**: The connection process depends on the terminal,
-   Make sure not to plug in an Ethernet cable when booting, because
+   please refer to the :doc:`payment terminals documentation
-   all Wi-Fi functionality will be bypassed when a wired network
+   <../../point_of_sale/payment>`.
-   connection is available on boot.
 
 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
+:menuselection:`Point of Sale --> Configuration --> PoS`, tick *IoT Box*
-the IoT Box you want to connect with. Save the changes.
+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

@@ -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.

iot/devices/camera.rst

@@ -11,12 +11,9 @@ the chosen quality control point.
 Connection
 ==========
 
-To connect the camera to the *IoT Box*, simply combine the two by
+To connect the camera to the *IoT Box*, simply connect the two by
 cable.
 
-.. note::
-   In some cases, a serial to USB adapter could be needed.
-
 If your camera is a `*supported
 one* <https://www.odoo.com/page/iot-hardware>`__, there is no need to
 set up anything as it will be detected as soon as it is connected.
@@ -24,13 +21,6 @@ set up anything as it will be detected as soon as it is connected.
 .. image:: media/camera_01.png
    :align: center
 
-In some cases, you could need to restart the box and download your
-camera’s drivers from the box. To do so, go to your *IoT Box Home
-Page* and click on *drivers list*. Then, click on load drivers.
-
-.. image:: media/camera_02.png
-   :align: center
-
 Link a Camera to a Quality Control Point
 ========================================
 

iot/devices/footswitch.rst

@@ -5,18 +5,15 @@ Connect a Footswitch
 When working, it is always better to have your two hands available.
 Using Odoo’s *IoT Box* and a footswitch will allow it.
 
-In fact, you will be able to go from one screen to another by using your
+In fact, you will be able to go from one screen to another and perform
-foot and the footswitch. Really convenient, it can be configured in a
+actions by using your foot and the footswitch. Really convenient, it
-few steps.
+can be configured in a few steps.
 
 Connection
 ==========
 
 Connecting the footswitch to the *IoT Box* is easy, you just have to
-combine the two by cable.
+connect the two by cable.
-
-.. note::
-   In some cases, a serial to USB adapter may be needed.
 
 If your footswitch is a `supported
 one <https://www.odoo.com/page/iot-hardware>`__, there is no need to
@@ -25,14 +22,6 @@ set up anything since it will be automatically detected when connected.
 .. image:: media/footswitch_01.png
    :align: center
 
-If it is not a supported one, you may need to restart the box and
-download your footswitch’s drivers from the box. To do so, go to the
-*IoT Box Home Page* and click on *drivers list*. Then, click on load
-drivers.
-
-.. image:: media/footswitch_02.png
-   :align: center
-
 Link a Footswitch to a Workcenter
 =================================
 

iot/devices/measurement_tool.rst

@@ -10,19 +10,11 @@ Connect in USB
 ==============
 
 To add a device connected by USB, just plug the USB cable in the *IoT
-Box*, restart the Box and the device should appear in your Odoo
+Box*, and the device should appear in your Odoo database.
-database.
 
 .. image:: media/measurement_tool_01.png
    :align: center
 
-If the device is not found, make sure the drivers have well been loaded
-on your IoT Box. For this, connect to the *IoT Box Homepage* and click
-on load drivers.
-
-.. image:: media/measurement_tool_02.png
-   :align: center
-
 Connect in Bluetooth
 ====================
 

iot/devices/printer.rst

@@ -10,15 +10,9 @@ Odoo apps.
 Connection
 ==========
 
-To connect the printer to the *IoT Box*, you just have to combine the
+The IoT Box supports printers connected through USB, network or Bluetooth.
-two by cable.
+`Supported printers <https://www.odoo.com/page/iot-hardware>`__ will be
-
+detected automatically and will appear in the *Devices* list of your IoT app.
-.. note::
-         Sometimes, a serial to USB adapter may be needed.
-
-If your printer is a `supported
-one <https://www.odoo.com/page/iot-hardware>`__, there is no need to set up anything
-because it will be automatically detected as soon as it is connected.
 
 .. note::
          The printer can take up to two minutes to appear in your devices list.
@@ -26,13 +20,6 @@ because it will be automatically detected as soon as it is connected.
 .. image:: media/printer_01.png
    :align: center
 
-In some cases, you may need to restart the box and download your
-printer’s drivers from the box. To do so, go to the *IoT Box Home
-Page* and click on *drivers list*. Then, click on load drivers.
-
-.. image:: media/printer_02.png
-   :align: center
-
 Link the Printer
 ================
 
@@ -89,17 +76,18 @@ You can link a printer to your *Point of Sale* app so you can print
 receipts directly from your *PoS*.
 
 Doing so is really easy. Go to your *Point of Sale* app and open your
-*PoS* settings, under *Configuration*. There, click on *Edit* and
+*Point of Sale* settings, under *Configuration*. There, click on *Edit*
-check the *IoT Box* feature. Then, enable the *Receipt Printer*.
+and check the *IoT Box* feature. Then, choose your *Receipt Printer*
+from the dropdown.
 
 .. image:: media/printer_08.png
    :align: center
 
-Now, on your *PoS* view, you will be able to print different kinds of
+Now, you will be able to print different kinds of tickets from your *POS*:
-tickets: **receipts**, **sale details** and **bills**.
+**receipts**, **sale details** and **bills**.
 
-For the receipt, it will be printed once the order is validated. The
+Receipts are printed once the order is validated. The process is
-process is automated when you enable the feature in your *PoS*.
+automated when you enable the feature in your *PoS* configuration.
 
 Sales details can be printed by clicking on the printer icon on the
 navbar at the top of the *PoS*. It will print the details of the sales
@@ -109,8 +97,8 @@ of the current day.
    :align: center
 
 As for the bill, it is only available in restaurant mode. In your
-restaurant settings, activate bills and a *Bill* button will appear in
+restaurant settings, activate *Print Bills* and a *Bill* button will
-the left panel. Click on it and it will print the bill.
+appear in the left panel of the *PoS*.
 
 .. image:: media/printer_10.png
    :align: center
@@ -126,13 +114,13 @@ tick *Order Printer*.
 .. image:: media/printer_11.png
    :align: center
 
-Now, go to the *Printers* menu. Hit create and select the *IoT Box*
+Now, go to the *Printers* menu. Hit create, select the printer from
-with all the categories of product that should be printed in the
+the dropdown and, in the *Printer Product Categories* field, choose
-*Printer Product Categories* field.
+all the categories of products that should be printed on this printer.
 
 .. image:: media/printer_12.png
    :align: center
 
 In the *PoS*, when you add or remove a product from one of the
 selected categories, the button *Order* will be green. If you click on
-it, a ticket will be printed.
+it, the IoT Box will print a receipt on the corresponding printer.