[REF][MOV] documentation apocalypse

Prior to this commit, the Odoo documentation was mainly split between two repositories: odoo/odoo/doc and odoo/documentation-user. Some bits of documentation were also hosted elsewhere (e.g., wiki, upgrade, ...). This was causing several problems among which: - The theme, config, Makefile, and similar technical resources had to be duplicated. This resulted in inconsistent layout, features, and build environments from one documentation to another. - Some pages did not fit either documentation as they were relevant for both users and developers. Some were relevant to neither of the two (e.g., DB management). - Cross-doc references had to be absolute links and they broke often. - Merging large image files in the developer documentation would bloat the odoo/odoo repository. Some contributions had to be lightened to avoid merging too many images (e.g., Odoo development tutorials). - Long-time contributors to the user documentation were chilly about going through the merging process of the developer documentation because of the runbot, mergebot, `odoo-dev` repository, etc. - Some contributors would look for the developer documentation in the `odoo/documentation-user` repository. - Community issues about the user documentation were submitted on the `odoo/odoo` repository and vice-versa. Merging all documentations in one repository will allow us to have one place, one theme, one work process, and one set of tools (build environment, ...) for all of the Odoo docs. As this is a good opportunity to revamp the layout of the documentation, a brand new theme replaces the old one. It features a new way to navigate the documentation, centered on the idea of always letting the reader know what is the context (enclosing section, child pages, page structure ...) of the page they are reading. The previous theme would quickly confuse readers as they navigated the documentation and followed cross-application links. The chance is also taken to get rid of all the technical dangling parts, performance issues, and left-overs. Except for some page-specific JS scripts, the Odoo theme Sphinx extension is re-written from scratch based on the latest Sphinx release to benefit from the improvements and ease future contributions. task-2351938 task-2352371 task-2205684 task-2352544 Closes #945
2021-04-30 12:40:29 +02:00
parent eac5e9f865
commit e3fee2cf46
2471 changed files with 39885 additions and 60126 deletions
@@ -0,0 +1,12 @@
+=============
+Configuration
+=============
+
+.. toctree::
+   :titlesonly:
+   :glob:
+
+   config/connect
+   config/flash_sdcard
+   config/iot_notfound
+   config/pos
@@ -0,0 +1,81 @@
+===================================
+Connect an IoT Box to your database
+===================================
+
+Install the Internet of Things (IoT) App on your Odoo Database.
+
+.. image:: media/connect01.png
+   :align: center
+
+Go in the IoT App and click on Connect on the IoT Boxes page.
+
+.. image:: media/connect02.png
+   :align: center
+
+Follow the steps to connect your IoT Box.
+
+.. image:: media/connect03.png
+   :align: center
+
+Ethernet Connection
+~~~~~~~~~~~~~~~~~~~
+
+1. Connect to the IoT Box all the devices that have to be connected with
+   cables (ethernet, usb devices, etc.).
+
+2. Power on the IoT Box.
+
+3. Read the Pairing Code from a screen or a receipt printer connected to the IoT Box.
+
+   .. image:: media/connect04.png
+
+4. Input the Pairing Code and click on the Pair button.
+
+.. note::
+   Recent changes in modern web browsers forced us to modify the connection wizard.
+   If your screen is different from the screenshots, make sure that the
+   ``iot_pairing`` module is installed.
+
+WiFi Connection
+~~~~~~~~~~~~~~~
+
+1. Power on the IoT Box
+
+2. Copy the token
+
+   .. image:: media/connect05.png
+
+3. Connect to the IoT Box WiFi Network (make sure there is no ethernet
+   cable plugged in your computer).
+
+   .. image:: media/connect06.png
+
+4. You will be redirected to the IoT Box Homepage (if it doesn't work,
+   connect to the IP address of the box). Give a name to your IoT Box (not
+   required) and paste the token, then click on next.
+
+   .. image:: media/connect07.png
+
+   .. tip::
+      If you are on Runbot, do not forget to add the -all or -base in the
+      token (e.g. this token
+      **http://375228-saas-11-5-iot-f3f920.runbot16.odoo.com\|4957098401**
+      should become
+      **http://375228-saas-11-5-iot-f3f920-all.runbot16.odoo.com\|4957098401**).
+
+5. Choose the WiFi network you want to connect with (enter the password
+   if there is one) and click on Submit. Wait a few seconds before being
+   redirected to your database.
+
+   .. image:: media/connect08.png
+
+You should now see the IoT Box.
+
+.. image:: media/connect09.png
+   :align: center
+
+IoT Box Schema
+~~~~~~~~~~~~~~
+
+.. image:: media/connect10.png
+   :align: center
@@ -0,0 +1,22 @@
+=====================
+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
+=================================
+
+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.
+
+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.
+
+.. image:: media/flash_sdcard01.png
+   :align: center
@@ -0,0 +1,25 @@
+=================
+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>`__).
+
+You can find the documentation about SD card flashing here (`here <https://docs.google.com/document/d/1bqKsZhWqMqI4mhv4ltF61M_QPiBCHygYjjvkhsCTdaY/edit>`__).
+
+
@@ -0,0 +1,165 @@
+===========================
+Use the IoT Box for the PoS
+===========================
+
+.. image:: media/pos01.png
+    :align: center
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before starting, make sure you have the following:
+
+-  An IoT Box
+
+-  A 2A Power adapter with pi 3 b+ 2.5 A
+
+-  A computer or tablet with an up-to-date web browser
+
+-  A running SaaS or Odoo instance with the Point of Sale and IoT apps
+   installed
+
+-  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)
+
+Set Up 
+~~~~~~~
+
+To connect hardware to the PoS, the first step is to connect an IoT Box
+to your database. For this, follow this
+`documentation <https://docs.google.com/document/d/1vhWrSSlSdJcRYe4tjPpXKYVMTD47lVK3ysyYc7tJDlA/edit#>`__.
+
+.. 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.
+
+-  **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 IoT Box to the same
+   network as your POS device.
+
+-  **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.
+
+Once it's done, you can connect the IoT Box to your PoS. For this, go in
+Point of Sale > Configuration > PoS, tick the box "IoT Box" and select
+the IoT Box you want to connect with. Save the changes.
+
+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.
@@ -0,0 +1,12 @@
+=======
+Devices
+=======
+
+.. toctree::
+   :titlesonly:
+   :glob:
+
+   devices/measurement_tool
+   devices/camera
+   devices/footswitch
+   devices/printer
@@ -0,0 +1,55 @@
+================
+Connect a Camera
+================
+
+When using your *IoT Box* in Odoo, you could need to use a camera. As
+it can be done in a few steps, this device is really easy to configure.
+Then, you can use it in your manufacturing process and link it to a
+control point. Doing so will allow you to take pictures when you reach
+the chosen quality control point.
+
+Connection
+==========
+
+To connect the camera to the *IoT Box*, simply combine 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.
+
+.. 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
+========================================
+
+With the Manufacturing app
+--------------------------
+
+In your *Quality app*, you can setup the device on a *Quality Control
+Point*. Go to the *Control Points* menu, under *Quality Control*
+and open the control point you want to link with the camera.
+
+Now, you can edit the control point and select the device from the
+dropdown list. Now, hit save.
+
+.. image:: media/camera_03.png
+   :align: center
+
+Then, your camera can be used with the picked *Control Point*. During
+the manufacturing process, reaching the *Quality Control Point* you
+chose before will allow you to take a picture.
+
+.. image:: media/camera_04.png
+   :align: center
@@ -0,0 +1,53 @@
+====================
+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
+foot and the footswitch. Really convenient, it 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.
+
+.. 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
+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
+=================================
+
+To link the footswitch to an action, it needs to be configured on a
+workcenter. Go to the workcenter you want to use the footswitch in and
+add the device in the *IoT Triggers* tab. Then, you can link it to an
+action and also add a key to trigger it.
+
+.. image:: media/footswitch_03.png
+   :align: center
+
+Note that the one that is first in the list will be chosen. So, the
+order matters! In the picture above, using the footswitch will, for
+example, automatically skip the current part of the process you work on.
+
+.. note::
+		When you are on the work order screen, a status button indicates if you
+		are correctly connected to the footswitch.
@@ -0,0 +1,60 @@
+==========================
+Connect a Measurement Tool
+==========================
+
+With Odoo’s *IoT Box*, it is possible to connect measurement tools to
+your database. Find the list of supported devices here: `Supported
+devices <https://www.odoo.com/page/iot-hardware>`__,.
+
+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
+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
+====================
+
+Activate the Bluetooth on your device (see your device manual for
+further explanation) and the IoT Box will automatically try to connect
+to the device.
+
+Here is an example of what it should look like:
+
+.. image:: media/measurement_tool_03.png
+   :align: center
+
+Link a measurement tool to a quality control point
+==================================================
+
+With the Manufacturing app
+--------------------------
+
+In your *Quality app*, you can setup a device on your *Quality
+Control Points*. To do so, go to the *Control Points* menu, under
+*Quality Control* and open the control point to which you want to
+assign a measurement tool.
+
+Now, you can edit the control point and choose the device from the
+dropdown list. Then, hit save.
+
+.. image:: media/measurement_tool_04.png
+   :align: center
+
+Now, your measurement tool is linked to the chosen *Control Point*.
+The value, which needs to be changed manually, will be automatically
+updated while the tool is being used.
+
+.. image:: media/measurement_tool_05.png
+   :align: center
@@ -0,0 +1,138 @@
+=================
+Connect a Printer
+=================
+
+When using your *IoT Box* in Odoo, you could need to use a printer.
+Doing so is easy and convenient as it can be done in a few steps. Then,
+you can use it to print receipts, orders or even reports in different
+Odoo apps.
+
+Connection
+==========
+
+To connect the printer to the *IoT Box*, you just have to combine the
+two by cable.
+
+.. 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.
+
+.. 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
+================
+
+To Work Orders
+--------------
+
+You can link *Work Orders* to printers via a *Quality Control Point*
+to print labels for manufactured products.
+
+To do so, you need to create a *Quality Control Point* from the
+*Quality* app. Then, you can select the correct manufacturing
+operation and the work order operation. In type, choose *Print Label*
+and hit save.
+
+.. image:: media/printer_03.png
+   :align: center
+
+Now, each time you reach the quality control point for the chosen
+product, a *Print Label* button will appear.
+
+.. image:: media/printer_04.png
+   :align: center
+
+To Reports
+----------
+
+You can also link a type of report to a certain printer. In the *IoT*
+app, go to the *Devices* menu and select the printer you want to set
+up.
+
+.. image:: media/printer_05.png
+   :align: center
+
+Now, go to the *Printer Reports* tab.
+
+.. image:: media/printer_06.png
+   :align: center
+
+Hit edit and then, click on *Add a line*. In the window that shows up,
+check all the types of reports that should be linked to this printer.
+Click on select and save.
+
+.. image:: media/printer_07.png
+   :align: center
+
+Now, each time you click on *Print* in the control panel, instead of
+downloading a PDF, it will send it to the selected printer and
+automatically print it.
+
+Print Receipts from the PoS
+---------------------------
+
+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
+check the *IoT Box* feature. Then, enable the *Receipt Printer*.
+
+.. image:: media/printer_08.png
+   :align: center
+
+Now, on your *PoS* view, you will be able to print different kinds of
+tickets: **receipts**, **sale details** and **bills**.
+
+For the receipt, it will be printed once the order is validated. The
+process is automated when you enable the feature in your *PoS*.
+
+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
+of the current day.
+
+.. image:: media/printer_09.png
+   :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
+the left panel. Click on it and it will print the bill.
+
+.. image:: media/printer_10.png
+   :align: center
+
+Print Orders in the kitchen
+---------------------------
+
+In restaurant mode, you can send order tickets to the kitchen.
+
+To do so, go to the *PoS* app and open your *PoS* settings. Then,
+tick *Order Printer*.
+
+.. image:: media/printer_11.png
+   :align: center
+
+Now, go to the *Printers* menu. Hit create and select the *IoT Box*
+with all the categories of product that should be printed in the
+*Printer Product Categories* field.
+
+.. 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.