Merge pull request #40 from syleam/9.0-add-stock_scanner-module

[9.0] Add stock scanner module

stock_scanner/README.rst

@@ -0,0 +1,258 @@
+.. image:: https://img.shields.io/badge/licence-AGPL--3-blue.svg
+   :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
+   :alt: License: AGPL-3
+
+====================================================
+Stock Scanner : WorkFlow engine for scanner hardware
+====================================================
+
+This module allows managing barcode readers with simple scenarios:
+
+- You can define a workfow for each object (stock picking, inventory, sale, etc)
+- Works with all scanner hardware model (just SSH client required)
+
+Some demo/tutorial scenarios are available in the "demo" directory of the module.
+These scenarios, are automatically imported when installing a new database with demo data.
+
+Installation
+============
+
+
+The "sentinel.py" specific ncurses client is available in the "hardware" directory.
+This application is a separate client, and can be run on any device.
+
+For mobile devices, like Windows Mobile or Android smart barcode scanners, we usually install it on a server, accessed through SSH.
+
+If you plan to use the specific "sentinel.py", you will need the "openobject-library" Python module, available from pip:
+
+    $ sudo pip install "openobject-library<2"
+
+.. note::
+
+   You must use openobject-library earlier than 2.0 with Odoo.
+   The version 2.0 of openobject-library only implements the Net-RPC protocol, which was removed from v7.
+
+To test the module, some modules provide scenario.
+
+Configuration
+=============
+
+In Odoo
+-------
+
+Declare hardware
+^^^^^^^^^^^^^^^^
+
+You have to declare some hardware scanners in Odoo.
+
+Go to "Inventory > Configuration > Scanner Configuration > Scanner Hardware" and create a new record.
+
+The "step type code" sent by the "sentinel.py" client at start-up is the IP address of the hardware, if connected through SSH.
+
+If needed enable Login/Logout
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The module come with 2 predifined scenarii for Login and Logout. The functionality is disabled by default and the user to use in
+Odoo must be specified in the .oerp_sentinelrc file used by sentinel and can be overriden on the Scanner Hardware definition
+in Odoo. 
+
+If the Login/logout functionality is enabled, when a user start a session with sentinel, only the Login scenario is displayed on the
+screen. The scenario will prompt the user for its login and pwd. If the authentication succeed, each interaction with Odoo will be done
+using the uid of the connected user. Once connected, a Logout scenario is displayed in the list of available scenarii and the Login
+scenario no more appear. 
+
+The Login/logout functionality enable you to specify on the scenario a list of users and/or a list of groups with access to the scenario.
+
+To enable the Login/logout functionality:
+    * Go to "Settings > Warehouse" and check the checkbox Login/logout scenarii enabled.
+    * Create a *Technical User* 'sentinel' **without roles in Human Resources** and with 'Sentinel: technical users' checked.
+    * Use this user to launch your sentinel session.
+
+Be careful, the role *Sentinel: technical users* is a technical role and should only be used by sentinel.
+
+The timeout of sessions is managed by a dedicated cron that reset the inactive sessions. The timeout can be configured on 
+settings. "Settings > Warehouse"
+
+For the sentinel.py client
+--------------------------
+
+The sentinel.py client needs a config file in the standard `ini` format, which is not automatically created.
+This file can be named `.oerp_sentinelrc`, `.openerp_sentinelrc` or `.odoo_sentinelrc`, and can be located in the current working directory, or in the user's home directory.
+
+The user put in the configuration file is used by the sentinel.py client to connect to Odoo.
+It can be overriden by hardware by setting the `User` field, to execute steps with the defined user, without having to create a configuration file per used that will need to connect.
+
+This file simply contains information for server connection (hostname, port, username, password and database).
+
+    [openerp]
+    host = localhost
+    password = admin
+    database = demo
+
+See the `hardware/odoo_sentinelrc.sample` file for an example.
+
+**Note** : If you want to copy the application outside this git repository, you will need to copy the i18n folder too.
+
+Autoconfiguration feature
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `sentinel.py` client has an autoconfiguration feature, used to automatically recognize the hardware being connected.
+During initialization, the `sentinel.py` client tries to detect an SSH connection, and sends the terminal's IP address as terminal code.
+If the IP address is found on the `code` field on a configured hardware in the database, this hardware configuration will automatically be used.
+If the IP address is not found, the client will ask the user to type (or scan) a code.
+
+This can be used only if the Odoo server and the connected hardware are on the same network.
+
+Writing scenario
+----------------
+
+Creation
+^^^^^^^^
+
+The preferred way to start the creation of a scenario is to create steps and transitions in diagram view.
+
+Once your steps are created, you can write python code directly from Odoo, or you can export the scenario to write the python code with your preferred code editor.
+
+In the python code of each step, some variables are available :
+    - cr : Cursor to the database
+    - uid : ID of the user executing the step (user used to log in with the sentinel, or user configured on the hardware, if any)
+    - pool : Pooler to the database
+    - env : Environment used to execute the scenario (new API)
+    - model : Pooler on the model configured on the scenario
+    - custom : Pooler on the custom values model
+    - term : Recordset on the current scenario
+    - context : Context used on the step
+    - m or message : Last message sent by the hardware
+    - t or terminal : Browse record on the hardware executing the step
+    - tracer : Value of the tracer of the used transition to access this step
+    - wkf or workflow : Workflow service
+    - scenario : Recordset on the current scenario for the hardware
+    - _ : The translation function provided by Odoo (useable like in any other python file)
+
+Some of these variables are also available on transition conditions execution.
+
+As stated previously, the step must always return:
+
+- A step type code, in the `act` variable
+- A message to display on the hardware screen, in the `res` variable
+- Optionally, a default value, in the `val` variable
+
+Step types
+^^^^^^^^^^
+
+The step types are mostly managed by the client.
+
+The standard step types are :
+
+- M : Simple message
+- F : Final step, like M, but ends the scenario
+- T : Text input
+- N : Number input (integer)
+- Q : Quantity input (float)
+- L : List
+- E : Error message, like M, but displayed with different colors
+- C : Confirm input
+- A : Automatic step. This type is used to automatically execute the next step
+
+.. note::
+
+   The automatic step often needs to define a value in `val`, corresponding to the value the user must send.
+   This step type is generally used as replacement of another type, at the end of the step code, by redefining the `act` variable in some cases, for example when a single value is available for a list step.
+
+Import
+^^^^^^
+
+Scenarios are automatically imported on a module update, like any other data.
+You just have to add the path to your `Scenario_Name.scenario` files in the `data` or `demo` sections in the `__openerp__.py` file.
+
+Export
+^^^^^^
+
+The export script is in the `script` directory of the module
+
+A scenario is exported as a set of files, containing :
+    - Scenario_Name.scenario : Global description of the scenario (name, warehouses, steps, transitions, etc.)
+    - A .py file per step : The name of the file is the XML ID of the step
+
+Using a test file
+^^^^^^^^^^^^^^^^^
+
+When developing scenarios, you will often have the same steps to run.
+The sentinel.py client allows you to supply a file, which contains the keys pressed during the scenario.
+
+You can define the file to use in the configuration file, on the "test_file" key.
+This file will be read instead of calling the curses methods when the scenario is waiting for a user input (including line feed characters).
+When the file has been fully read, the client exits.
+
+A sample test file can be found in the "Step Types" demo scenario.
+
+*Special keys* :
+For special keys (arrows, delete, etc.), you must write a line containing ':', followed by the curses key code.
+
+Valid key codes are :
+    - KEY_DOWN : Down arrow
+    - KEY_UP : Up arrow
+    - KEY_LEFT : Left arrow
+    - KEY_RIGHT : Right arrow
+    - KEY_BACKSPACE : Backspace
+    - KEY_DC : Delete
+
+Usage
+=====
+
+On start-up, the client lists available scenarii.
+When the user selects a scenario, the current scenario and step are stored on the hardware configuration's entry in Odoo.
+
+When the client sends a message to the server, the next step is selected depending on the current step and the message sent.
+Then, the server returns the result of the step, which contains its type code and the text to display on the hardware screen.
+Unlike the standard Odoo Workflow, each step needs to find a valid transition, because a step needs to be displayed on the hardware screen at all times.
+
+.. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
+   :alt: Try me on Runbot
+   :target: https://runbot.odoo-community.org/runbot/154/8.0
+
+A client for the Datalogic PowerScan scanners was developped for a very early version or this module.
+The files have been removed, but are still available in the `git repository history
+<https://github.com/OCA/stock-logistics-workflow/tree/527f033e9d31fe822562d4716104f37f6ce1f88c/stock_scanner/hardware/datalogic/PowerScan>`_.
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues
+<https://github.com/OCA/stock-logistics-workflow/issues>`_. In case of trouble, please
+check there if your issue has already been reported. If you spotted it first,
+help us smashing it by providing a detailed and welcomed `feedback
+<https://github.com/OCA/stock-logistics-workflow/issues/new?body=module:%20stock_scanner%0Aversion:%208.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Credits
+=======
+
+Images
+------
+
+* Odoo Community Association: `Icon <https://github.com/OCA/maintainer-tools/blob/master/template/module/static/description/icon.svg>`_.
+
+Contributors
+------------
+* Alexandre Fayolle <afayolle.ml@free.fr>
+* Christophe CHAUVET <christophe.chauvet@syleam.fr>
+* Damien Crier <damien@crier.me>
+* Laetitia Gangloff <laetitia.gangloff@acsone.eu>
+* Laurent Mignon <laurent.mignon@acsone.eu>
+* Olivier Dony <odo@openerp.com>
+* Sebastien LANGE <sebastien.lange@syleam.fr>
+* Sylvain Garancher <sylvain.garancher@syleam.fr>
+
+Maintainer
+----------
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+This module is maintained by the OCA.
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+To contribute to this module, please visit https://odoo-community.org.

stock_scanner/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+# © 2015 Sylvain Garancher <sylvain.garancher@syleam.fr>
+# © 2015 Damien CRIER <damien.crier@objectif-pi.com>
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html).
+
+from . import load_scenario
+from . import models
+from . import wizard

stock_scanner/__openerp__.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+# © 2011-2015 Sylvain Garancher <sylvain.garancher@syleam.fr>
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html).
+
+{
+    'name': 'Stock Scanner',
+    'summary': 'Allows managing barcode readers with simple scenarios',
+    'version': '9.0.1.0.0',
+    'category': 'Generic Modules/Inventory Control',
+    'website': 'https://odoo-community.org/',
+    'author': 'SYLEAM,'
+              'ACSONE SA/NV,'
+              'Odoo Community Association (OCA)',
+    'license': 'AGPL-3',
+    'application': True,
+    'installable': True,
+    'depends': [
+        'product',
+        'stock',
+    ],
+    'data': [
+        'security/stock_scanner_security.xml',
+        'security/ir.model.access.csv',
+        'data/stock_scanner.xml',
+        'data/ir_cron.xml',
+        'data/scenarios/Login/Login.scenario',
+        'data/scenarios/Logout/Logout.scenario',
+        'wizard/stock_scanner_config_wizard_view.xml',
+        'views/menu.xml',
+        'views/scanner_scenario.xml',
+        'views/scanner_scenario_step.xml',
+        'views/scanner_scenario_transition.xml',
+        'views/scanner_scenario_custom.xml',
+        'views/scanner_hardware.xml',
+    ],
+    'demo': [
+        'demo/stock_scanner_demo.xml',
+        'demo/Tutorial/Tutorial.scenario',
+        'demo/Tutorial/Step_types/Step_types.scenario',
+        'demo/Tutorial/Sentinel/Sentinel.scenario',
+    ],
+    'images': [
+        'images/scanner_hardware.png',
+        'images/scanner_scenario.png',
+        'images/scanner_screen.png',
+    ],
+}

stock_scanner/data/ir_cron.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" ?>
+<openerp>
+    <data noupdate="1">
+        <record id="hardware_reset_user_id_on_timeout" model="ir.cron">
+            <field name="name">Remove the current user_id and scenario values on session timeout</field>
+            <field name="interval_number">1</field>
+            <field name="interval_type">minutes</field>
+            <field name="nextcall">2014-02-10 21:00:00</field>
+            <field name="numbercall">-1</field>
+            <field eval="False" name="doall"/>
+            <field eval="False" name="active"/>
+            <field name="model">scanner.hardware</field>
+            <field name="function">timeout_session</field>
+        </record>
+    </data>
+</openerp>

stock_scanner/data/scenarios/Login/Login.scenario

@@ -0,0 +1,20 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<scenario noupdate="1">
+  <group_ids>stock_scanner.group_stock_scanner_sentinel</group_ids>
+  <name>Login</name>
+  <sequence>0</sequence>
+  <notes/>
+  <parent_id/>
+  <shared_custom>False</shared_custom>
+  <active>False</active>
+  <model_id>scanner.hardware</model_id>
+  <type>scenario</type>
+  <id>stock_scanner.scanner_scenario_login</id>
+  <Step id="stock_scanner.scanner_scenario_login_step_error" name="Authentication error" no_back="False" step_back="False" step_start="False" step_stop="False"/>
+  <Step id="stock_scanner.scanner_scenario_login_step_done" name="Authentication OK" no_back="False" step_back="False" step_start="False" step_stop="True"/>
+  <Step id="stock_scanner.scanner_scenario_login_step_login" name="Login name" no_back="True" step_back="True" step_start="True" step_stop="False"/>
+  <Step id="stock_scanner.scanner_scenario_login_step_pwd" name="Pwd" no_back="False" step_back="False" step_start="False" step_stop="False"/>
+  <Transition condition="terminal.check_credentials(terminal.tmp_val1, message)[0]" from_id="stock_scanner.scanner_scenario_login_step_pwd" id="stock_scanner.scanner_scenario_transition_pwd_to_done" name="Authenticate" sequence="0" to_id="stock_scanner.scanner_scenario_login_step_done" tracer="" transition_type="keyboard"/>
+  <Transition condition="True" from_id="stock_scanner.scanner_scenario_login_step_pwd" id="stock_scanner.scanner_scenario_transition_pwd_to_error" name="Authentication error" sequence="10" to_id="stock_scanner.scanner_scenario_login_step_error" tracer="" transition_type="keyboard"/>
+  <Transition condition="True" from_id="stock_scanner.scanner_scenario_login_step_login" id="stock_scanner.scanner_scenario_transition_login_to_pwd" name="Login entered -&gt; Enter password" sequence="0" to_id="stock_scanner.scanner_scenario_login_step_pwd" tracer="" transition_type="keyboard"/>
+</scenario>

stock_scanner/data/scenarios/Login/stock_scanner.scanner_scenario_login_step_done.py

@@ -0,0 +1,13 @@
+# flake8: noqa
+'Use <m> or <message> to retrieve the data transmitted by the scanner.'
+'Use <t> or <terminal> to retrieve the running terminal browse record.'
+'Put the returned action code in <act>, as a single character.'
+'Put the returned result or message in <res>, as a list of strings.'
+'Put the returned value in <val>, as an integer'
+
+terminal.login(terminal.tmp_val1, message)
+
+act = 'F'
+res = [
+    _('You are now authenticated as %s !') % terminal.tmp_val1,
+]

stock_scanner/data/scenarios/Login/stock_scanner.scanner_scenario_login_step_error.py

@@ -0,0 +1,12 @@
+# flake8: noqa
+'Use <m> or <message> to retrieve the data transmitted by the scanner.'
+'Use <t> or <terminal> to retrieve the running terminal browse record.'
+'Put the returned action code in <act>, as a single character.'
+'Put the returned result or message in <res>, as a list of strings.'
+'Put the returned value in <val>, as an integer'
+
+act = 'E'
+res = [
+    _('Wrong login/password'),
+]
+val = True

stock_scanner/data/scenarios/Login/stock_scanner.scanner_scenario_login_step_login.py

@@ -0,0 +1,11 @@
+# flake8: noqa
+'Use <m> or <message> to retrieve the data transmitted by the scanner.'
+'Use <t> or <terminal> to retrieve the running terminal browse record.'
+'Put the returned action code in <act>, as a single character.'
+'Put the returned result or message in <res>, as a list of strings.'
+'Put the returned value in <val>, as an integer'
+
+act = 'T'
+res = [
+    _('Login ?'),
+]