edouard@3925: Introduction to SVGHMI
edouard@3925: ======================
edouard@3925: 
edouard@3925: +-----------------------------+-------------------------------------------------------------------------------+
edouard@3925: |                             | SVGHMI is a SVG based HMI toolkit. With it, PLC programmers and HMI designers |
edouard@3925: | .. image:: svhgmi_pitch.svg | can efficiently produce Scalable Web Based HMIs. <br />  <br /> HMI design    |
edouard@3925: |                             | happens in `Inkscape  <https://inkscape.org>`_.                               |
edouard@3925: |                             | Designer freely draws HMI pages and widgets following WYSIWYG principle.      |
edouard@3925: +-----------------------------+-------------------------------------------------------------------------------+
edouard@3925: 
edouard@3925: WYSIWYG HMI design with Inkscape
edouard@3925: --------------------------------
edouard@3925: 
edouard@3925:     "**What You See Is What You Get**, is a system in which editing software
edouard@3925:     allows content to be edited in a form that resembles its appearance when
edouard@3925:     printed or displayed as a finished product."
edouard@3925:     
edouard@3925:     -- Oxford English Dictionary
edouard@3925: 
edouard@3925: Widgets can be selected from customizable widget library and drag'n'dropped
edouard@3925: directly in Inkscape.
edouard@3925: 
edouard@3925: .. image:: svghmi_dnd.svg
edouard@3925: 
edouard@3925: SVGHMI's Page and Widget roles are assigned to SVG elements by changing objects
edouard@3925: name and description in Inkscape.
edouard@3925: 
edouard@3925: .. image:: svhgmi_inkscape.svg
edouard@3925: 
edouard@3925: HMI tree scale together with PLC instance tree
edouard@3925: ----------------------------------------------
edouard@3925: 
edouard@3925: In SVGHMI, **scalability** applies to both graphics and data. Once HMI and PLC
edouard@3925: are associated in a first version of a machine, it is easy to extend both of
edouard@3925: them simultaneously. In most cases DRY principle applies. PLC code or SVG
edouard@3925: elements can be re-used and extended.
edouard@3925: 
edouard@3925: PLC data exposed to HMI is represented in an "HMI Tree" deduced from PLC
edouard@3925: program. More precisely, HMI Tree is a simplified subset of POU instances tree.
edouard@3925: PLC  programmer selects variables to be exposed by assigning them a derived
edouard@3925: HMI_* type. For example HMI_REAL is used instead of REAL to expose a floating
edouard@3925: point variable.
edouard@3925: 
edouard@3925: .. image:: svghmi_trees.svg
edouard@3925: 
edouard@3925: In order to reduce HMI Tree complexity, structure of POU instance tree is not
edouard@3925: preserved by default. Only POUs having a single HMI_NODE variable defined
edouard@3925: appear in HMI Tree. This allows to expose variables that are spread in a
edouard@3925: complex hierarchy of POUs in a single HMI Tree node.
edouard@3925: 
edouard@3925: .. image:: svghmi_types.svg
edouard@3925: 
edouard@3925: Re-usable widgets and pages
edouard@3925: ---------------------------
edouard@3925: 
edouard@3925: HMI elements are SVG elements whose labels start with ``HMI:``.  They can be
edouard@3925: widgets or pages, and can point to locations in HMI tree with a path starting
edouard@3925: with a ``/``, and with ``/``-separated hierarchical levels.
edouard@3925: For example, ``/THIS/IS/A/VALID/HMI_TREE/PATH``.
edouard@3925: 
edouard@3925: ``HMI:Switch@/GREENLIGHT``
edouard@3925:     "Switch" type widget bound to a variable named GREENLIGHT at root of HMI tree
edouard@3925: 
edouard@3925: Each ``HMI:Page`` has a unique name. ``HMI:Jump`` and ``HMI:Back`` widgets are
edouard@3925: used to switch to other pages. PLC can also trigger page change autonomously.
edouard@3925: HMI must have at least one SVG element labelled ``HMI:Page:Home``. ``Home`` is
edouard@3925: a special page name: it will make this page the landing page when HMI is loaded.
edouard@3925: 
edouard@3925: .. image:: svhgmi_pages.svg
edouard@3925: 
edouard@3925: ``HMI:Page:Home``
edouard@3925:     Mandatory "Home" page declaration
edouard@3925: 
edouard@3925: ``HMI:Jump:Home``
edouard@3925:     Change current page to "Home" page when clicked
edouard@3925: 
edouard@3925: ``HMI:Back``
edouard@3925:     Change current page back to previous page when clicked
edouard@3925: 
edouard@3925: Pages and groups of widgets can be dynamically re-based to another compatible
edouard@3925: HMI Tree location. They can then be be re-used as HMI components, paired with
edouard@3925: corresponding POU instances on PLC side.
edouard@3925: 
edouard@3925: Simple yet powerful widgets
edouard@3925: ---------------------------
edouard@3925: 
edouard@3925: Widgets are meant to be as simple as possible. Still, they can become complex
edouard@3925: when implementing interactions that cannot be broken down into multiple
edouard@3925: independent widgets.
edouard@3925: 
edouard@3925: +------------------------------------+---------------------------------+
edouard@3925: | Meter Widget Template (`HMI:Meter`)|      Voltmeter (`HMI:Meter`)    | 
edouard@3925: +====================================+=================================+
edouard@3925: | .. image:: svghmi_meter.svg        | .. image:: svghmi_voltmeter.svg |
edouard@3925: +------------------------------------+---------------------------------+
edouard@3925: 
edouard@3925: HMI and pages have their own local variables allowing interaction in between
edouard@3925: widgets bypassing HMI Tree. For example, position of `HMI:Scrollbar` can be
edouard@3925: directly connected to a position in `HMI:JSONTable` with a page local
edouard@3925: variable.
edouard@3925: 
edouard@3925: How does it work ?
edouard@3925: ------------------
edouard@3925: 
edouard@3925: HMI's client and server code is generated during SVGHMI build, based on PLC 
edouard@3925: code and HMI design.
edouard@3925: 
edouard@3925: .. image:: svghmi_overview.svg
edouard@3925: 
edouard@3925: SVGHMI build is part of Beremiz build, available in IDE and command line.