vending-machine-dev.rst

.. SPDX-FileCopyrightText: Huawei Inc.
..
.. SPDX-License-Identifier: CC-BY-4.0

Vending Machine Blueprint Applications Interface and Protocol
#############################################################

.. contents::
   :depth: 4

Communication Protocol
**********************

The "Vending Machine" blueprint will take advantage of two applications: a UI
and an "IO Controller". These applications will exchange messages over a
defined interface using a specific protocol. For the scope of this
specification, the communication will happen over plain WebSockets/TCP.

Specification
-------------

In terms of roles, we have a client and a server. The "IO Controller" acts as a
server while the "UI" process, as a client.

As a minimum client/server specification, the applications will exchange
messages as per the following diagram:

.. code-block::

   ┌────────────────┐     selection      ┌─────────────────────┐
   │                ├───────────────────>┤                     │
   │                │                    │                     │
   │                │     deliver        │ IO                  │
   │ UI Application ├───────────────────>┤ Control Application │
   │    (client)    │                    │      (server)       │
   │                │     delivered      │                     │
   │                │◄───────────────────┤                     │
   └────────────────┘                    └─────────────────────┘

Static information can be set in configuration files shared between both
applications (e.g. for items name, a timeout for simulated actions, number of
item slots, etc.).

Server application is made on generic concepts inspired by WoT/WebThings:

- properties: set a *selection* of products
  - selection is a fixed size array and items are identified from indices in
  this array while the values represent the associated item quantity
- actions: request a *deliver* order
  - order also contain the current selection as a parameter
- events: *delivered* event will notify that the *deliver* action was finished
  - event is delivered based on the *addEventSubscription* subscription message

Thoses objects will be used through websockets's messages on default endpoint
(ie: `<ws://localhost:8888/>`).

Client request's payloads are formatted using JSON structures. Below there is
an example for each of the types defined:

Properties
==========

.. code-block:: json

    {
      "messageType": "setProperty",
      "data": {
          "selection": [0, 0, 0, 1]
      }
    }

Actions
=======

.. code-block:: json

    {
      "messageType": "requestAction",
      "data": {
        "deliver": {
          "input": {
            "selection": [0, 1, 0, 0]
          }
        }
      }
    }

Events
======

The client needs to send a subscription message once and listen from server's
event messages:

.. code-block:: json

    {
      "messageType": "addEventSubscription",
      "data": {
        "delivered": {}
      }
    }

.. code-block:: json

    {
      "messageType": "event",
      "data": {
        "delivered": {}
      }
    }

Inter-application message flow
------------------------------

The UI and Control applications will adhere to the message schema defined
above. The message flow is described as it follows:

.. code-block::

   ┌────┐                      ┌────┐
   │    │                      │    │
   │    │                      │    │
   │    │      selection       │    │
   │    ├─────────────────────►│    │
   │    │                      │    │
   │    │      selection       │    │
   │    ├─────────────────────►│    │
   │    │                      │    │
   │    │      selection       │    │
   │    ├─────────────────────►│    │
   │    │                      │    │
   │    │                      │    │
   │    │ [...]                │    │
   │    │                      │    │
   │ UI │ [...]                │ IO │
   │    │                      │    │
   │    │                      │    │
   │    ├─────────────────────►│    │
   │    │                      │    │
   │    │                      │    │
   │    │        deliver       │    │
   │    ├─────────────────────►│    │
   │    │                      │    │
   │    │       delivered      │    │
   │    │◄─────────────────────┤    │
   │    │                      │    │
   │    │                      │    │
   │    │                      │    │
   │    │                      │    │
   │    │                      │    │
   └────┘                      └────┘

Detailed example flow:

Firstly, client is intializing by subscribing for server's future **"delivered" events**:

.. code-block:: json

    {
      "messageType": "addEventSubscription",
      "data": {
        "delivered": {}
      }
    }

Client's application is setting an empty selection on server and then UI will
wait for user inputs:

.. code-block:: json

    {
      "messageType": "setProperty",
      "data": {
        "selection": [0, 0, 0, 0]
      }
    }

User selects one product (one of type "1"):

- UI will be updated accordigly
- The client process makes a request to the server to set **selection
  "property"**

.. code-block:: json

   {
     "messageType": "setProperty",
     "data": {
       "selection": [0, 1, 0, 0]
     }
   }

The IO Controller will turn on the associated LEDs to show another visual
indication.

Then the user decides to add 1 more product of type "3":

.. code-block:: json

   {
     "messageType": "setProperty",
     "data": {
       "selection": [0, 1, 0, 1]
     }
   }

The user confirms the order by pressing the relevant UI element, then a
**"deliver" action"** is sent from client to the server:

.. code-block:: json

   {
     "messageType": "requestAction",
     "data": {
       "deliver": {
         "input": {
           "selection": [0, 1, 0, 1]
         }
       }
     }
   }

The UI application will be blocked until ready or timeout is reached:

- watchdog/timeout timer starts on UI/client
- UI waits for the **delivered** event

Processing is done server-side and **delivered event** is triggered:

.. code-block:: json

   {
     "messageType": "event",
     "data": {
       "delivered": {}
     }
   }

The UI is unblocked and ready for new selection (it should reinitialized to
empty).

If no "delivered" event after a defined timeout, the UI will display an "out of
order" message and show a "reset" button to refresh for the next order.

Software Dependencies Versions
------------------------------

Oniro Project supports the following libraries for message encoding/decoding/parsing and
the communication protocol:

* `libwebsockets <https://libwebsockets.org/>`_ 4.0.1

* `cjson <https://github.com/DaveGamble/cJSON/>`_ 1.7.13 (to be upgraded to
  1.7.14 for OpenHarmony convergence)

* `json-c <https://github.com/json-c/json-c>`_ 0.13.1

Extra software could be integrated if needed:

* `libmicrohttpd <https://git.gnunet.org/libmicrohttpd.git/tree/src/include/microhttpd.h>`_

For prototyping purposes server can be easily implemented using
`webthings framework <https://webthings.io/>`_.


Message schema
--------------

Selection Message Schema
========================

The schema for the "selection" messages is:

.. code-block:: json

   {
     "$schema": "http://json-schema.org/draft-07/schema",
     "$id": "http://example.com/example.json",
     "type": "object",
     "title": "The root schema",
     "description": "The root schema comprises the entire JSON document.",
     "default": {},
     "examples": [
       {
         "messageType": "setProperty",
         "data": {
           "selection": [
             0,
             1,
             0,
             0
           ]
         }
       }
     ],
     "required": [
       "messageType",
       "data"
     ],
     "properties": {
       "messageType": {
         "$id": "#/properties/messageType",
         "type": "string",
         "title": "The messageType schema",
         "default": "",
         "examples": [
           "setProperty"
         ]
       },
       "data": {
         "$id": "#/properties/data",
         "type": "object",
         "title": "The data schema",
         "default": {},
         "examples": [
           {
             "selection": [
               0,
               1,
               0,
               0
             ]
           }
         ],
         "required": [
           "selection"
         ],
         "properties": {
           "selection": {
             "$id": "#/properties/data/properties/selection",
             "type": "array",
             "title": "The selection schema",
             "default": [],
             "examples": [
               [
                 0,
                 1
               ]
             ],
             "additionalItems": true,
             "items": {
               "$id": "#/properties/data/properties/selection/items",
               "anyOf": [
                 {
                   "$id": "#/properties/data/properties/selection/items/anyOf/0",
                   "type": "integer",
                   "title": "The first anyOf schema",
                   "default": 0,
                   "examples": [
                     0,
                     1
                   ]
                 }
               ]
             }
           }
         },
         "additionalProperties": true
       }
     },
     "additionalProperties": true
   }

Deliver Message Schema
======================

The schema for the "deliver" messages is:

.. code-block:: json

   {
     "$schema": "http://json-schema.org/draft-07/schema",
     "$id": "http://example.com/example.json",
     "type": "object",
     "title": "The root schema",
     "description": "The root schema comprises the entire JSON document.",
     "default": {},
     "examples": [
       {
         "messageType": "requestAction",
         "data": {
           "deliver": {
             "input": {
               "selection": [
                 0,
                 1,
                 0,
                 0
               ]
             }
           }
         }
       }
     ],
     "required": [
       "messageType",
       "data"
     ],
     "properties": {
       "messageType": {
         "$id": "#/properties/messageType",
         "type": "string",
         "title": "The messageType schema",
         "default": "",
         "examples": [
           "requestAction"
         ]
       },
       "data": {
         "$id": "#/properties/data",
         "type": "object",
         "title": "The data schema",
         "default": {},
         "examples": [
           {
             "deliver": {
               "input": {
                 "selection": [
                   0,
                   1,
                   0,
                   0
                 ]
               }
             }
           }
         ],
         "required": [
           "deliver"
         ],
         "properties": {
           "deliver": {
             "$id": "#/properties/data/properties/deliver",
             "type": "object",
             "title": "The deliver schema",
             "default": {},
             "examples": [
               {
                 "input": {
                   "selection": [
                     0,
                     1,
                     0,
                     0
                   ]
                 }
               }
             ],
             "required": [
               "input"
             ],
             "properties": {
               "input": {
                 "$id": "#/properties/data/properties/deliver/properties/input",
                 "type": "object",
                 "title": "The input schema",
                 "default": {},
                 "examples": [
                   {
                     "selection": [
                       0,
                       1,
                       0,
                       0
                     ]
                   }
                 ],
                 "required": [
                   "selection"
                 ],
                 "properties": {
                   "selection": {
                     "$id": "#/properties/data/properties/deliver/properties/input/properties/selection",
                     "type": "array",
                     "title": "The selection schema",
                     "default": [],
                     "examples": [
                       [
                         0,
                         1
                       ]
                     ],
                     "additionalItems": true,
                     "items": {
                       "$id": "#/properties/data/properties/deliver/properties/input/properties/selection/items",
                       "anyOf": [
                         {
                           "$id": "#/properties/data/properties/deliver/properties/input/properties/selection/items/anyOf/0",
                           "type": "integer",
                           "title": "The first anyOf schema",
                           "default": 0,
                           "examples": [
                             0,
                             1
                           ]
                         }
                       ]
                     }
                   }
                 },
                 "additionalProperties": true
               }
             },
             "additionalProperties": true
           }
         },
         "additionalProperties": true
       }
     },
     "additionalProperties": true
   }

Delivered Message Schema
========================

The schema for the "delivered" messages is:

.. code-block:: json

   {
     "$schema": "http://json-schema.org/draft-07/schema",
      "type": "object",
      "title": "The root schema",
      "description": "The root schema comprises the entire JSON document.",
      "default": {},
      "examples": [
        {
          "messageType": "event",
          "data": {
            "delivered": {}
          }
        }
      ],
      "required": [
        "messageType",
        "data"
      ],
      "properties": {
        "messageType": {
          "$id": "#/properties/messageType",
          "type": "string",
          "title": "The messageType schema",
          "description": "An explanation about the purpose of this instance.",
          "default": "",
          "examples": [
            "event"
          ]
        },
        "data": {
          "$id": "#/properties/data",
          "type": "object",
          "title": "The data schema",
          "description": "An explanation about the purpose of this instance.",
          "default": {},
          "examples": [
            {
              "delivered": {}
            }
          ],
          "required": [
            "delivered"
          ],
          "properties": {
            "delivered": {
              "$id": "#/properties/data/properties/delivered",
              "type": "object",
              "title": "The delivered schema",
              "description": "An explanation about the purpose of this instance.",
              "default": {},
              "examples": [
                {}
              ],
              "required": [],
              "additionalProperties": true
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
  }

Previous event will be notified if the client sends a subscription message:

.. code-block:: json

   {
     "$schema": "http://json-schema.org/draft-07/schema",
     "$id": "http://example.com/example.json",
     "type": "object",
     "title": "The root schema",
     "description": "The root schema comprises the entire JSON document.",
     "default": {},
     "examples": [
       {
         "messageType": "addEventSubscription",
         "data": {
           "delivered": {}
         }
       }
     ],
     "required": [
       "messageType",
       "data"
     ],
     "properties": {
       "messageType": {
         "$id": "#/properties/messageType",
         "type": "string",
         "title": "The messageType schema",
         "description": "An explanation about the purpose of this instance.",
         "default": "",
         "examples": [
           "addEventSubscription"
         ]
       },
       "data": {
         "$id": "#/properties/data",
         "type": "object",
         "title": "The data schema",
         "description": "An explanation about the purpose of this instance.",
         "default": {},
         "examples": [
           {
             "delivered": {}
           }
         ],
         "required": [
           "delivered"
         ],
         "properties": {
           "delivered": {
             "$id": "#/properties/data/properties/delivered",
             "type": "object",
             "title": "The delivered schema",
             "description": "An explanation about the purpose of this instance.",
             "default": {},
             "examples": [
               {}
             ],
             "required": [],
             "additionalProperties": true
           }
         },
         "additionalProperties": true
       }
     },
     "additionalProperties": true
   }

Current assumptions
-------------------

* Both of the applications (server/client, "UI"/"IO Controller" are running on
  the same, Linux-based target.
* The quantity of a selection is maximum "1". This means that the selection
  array can contain values of 0 or 1.
* The availability from the perspective of the "IO Controller" is infinite.