ELCCR-1267 - add documentation to Submaps

Change-Id: I1833c7ecdf03e349a593f3b35274293cfbe85dbb

2 files changed, 348 insertions, 3 deletions

diff --git a/doc/book-enea-edge-getting-started/doc/book.xml b/doc/book-enea-edge-getting-started/doc/book.xml
index f317f15..e74ac85 100644
--- a/doc/book-enea-edge-getting-started/doc/book.xml
+++ b/doc/book-enea-edge-getting-started/doc/book.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
 <!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED">
@@ -7,8 +7,7 @@
   <title><trademark class="registered">Enea</trademark> Edge Getting
   Started</title>
 
-  <subtitle>Release Version <xi:include
-  href="../../eltf_params_updated.xml"
+  <subtitle>Release Version <xi:include href="../../eltf_params_updated.xml"
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xpointer="element(EneaEdge_REL_VER/1)" /></subtitle>
 
@@ -37,6 +36,8 @@
   <xi:include href="log_collector.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
+  <xi:include href="submaps.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
   <xi:include href="grafana.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <xi:include href="troubleshooting.xml"
diff --git a/doc/book-enea-edge-getting-started/doc/submaps.xml b/doc/book-enea-edge-getting-started/doc/submaps.xml
new file mode 100644
index 0000000..bdb769e
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/submaps.xml
@@ -0,0 +1,344 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="submaps">
+  <title>Submaps</title>
+
+  <para>The System domain of the Enea Edge Managemement application can be
+  split into different submaps, used to organize the uCPE devices more 
+    effectively. Each domain is organized like a tree, with each submap being 
+    able to have several other submaps within it. Each device can be placed in 
+    only one submap and the user can create virtual links between devices.</para>
+
+  <para>Submaps support managed and unmanaged uCPE devices. An unmanaged 
+    device is an icon that looks like a device within the 
+    <emphasis role="bold">Map</emphasis> (it supports links and has a similar 
+    icon) but is not a real managed device.</para>
+
+  <section id="submap_op">
+    <title>Submap Operations</title>
+
+    <para>In the <emphasis role="bold">System</emphasis> view, right-clicking
+    on a submap opens up a menu with the following operations:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Add Submap</para>
+
+        <para>This option is used for adding a new submap, placed in the
+        <emphasis role="bold">System</emphasis> view under the current one in
+        the tree. The new submap will also be added in the <emphasis
+        role="bold">Map</emphasis> view of the parent submap.</para>
+
+        <para>When selecting this option, the following fields need to be set
+        in the <emphasis role="bold">Add Submap</emphasis> window that
+        pops-up:</para>
+
+        <table id="submap_props">
+            <title>Submap properties</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry>Name</entry>
+
+                  <entry>The name of the domain map. This is
+                  mandatory.</entry>
+                </row>
+
+                <row>
+                  <entry>Description</entry>
+
+                  <entry>A text description of the domain map.</entry>
+                </row>
+
+                <row>
+                  <entry>Background Color</entry>
+
+                  <entry>The background color of the domain map. Possible
+                  values: white, black, blue, cyan, grey, green, magenta,
+                  orange, pink, red, yellow.</entry>
+                </row>
+
+                <row>
+                  <entry>Background Image</entry>
+
+                  <entry>The background image of the domain map.</entry>
+                </row>
+
+                <row>
+                  <entry>Icon Image</entry>
+
+                  <entry>The icon image of the domain map.</entry>
+                </row>
+
+                <row>
+                  <entry>Snap to Grid</entry>
+
+                  <entry>True if a placed device should snap to the grid
+                  automatically.</entry>
+                </row>
+
+                <row>
+                  <entry>X Grid (px)</entry>
+
+                  <entry>The number of pixels between placement positions in
+                  the horizontal position in the grid. Disabled if
+                  <literal>Snap to Grid</literal> is false.</entry>
+                </row>
+
+                <row>
+                  <entry>Y Grid (px)</entry>
+
+                  <entry>The number of pixels between placement positions in
+                  the vertical position in the grid. Disabled if <literal>Snap
+                  to Grid</literal> is false.</entry>
+                </row>
+
+                <row>
+                  <entry>Direction</entry>
+
+                  <entry>This value describes the direction of sorting the
+                  items (horizontal or vertical).</entry>
+                </row>
+
+                <row>
+                  <entry>Sort Method</entry>
+
+                  <entry>This value describes the sorting method used when
+                  arranging icons. Natural is [a1,a2,a11] and Alphabetical is
+                  [a1,a11,a2].</entry>
+                </row>
+
+                <row>
+                  <entry>Arrangement Wrap</entry>
+
+                  <entry>This value indicates the maximum number of items
+                  placed before wrapping to the next row or column.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+        <note>
+          <para><literal>Snap to Grid</literal>, <literal>Direction</literal>
+          and <literal>Sort Method</literal> have the <literal>System
+          Default</literal> option. This option can be set by accessing
+          <emphasis role="bold">System</emphasis>, selecting <emphasis
+          role="bold">Configuration</emphasis> under the <emphasis
+          role="bold">Properties</emphasis> tab, and navigating to the <emphasis
+          role="bold">GUI</emphasis> tab.</para>
+
+          <para>More images for backgrounds and icons can be uploaded by
+          accessing <emphasis role="bold">System</emphasis>, selecting
+          <emphasis role="bold">Media Files</emphasis> under the <emphasis
+          role="bold">Icons</emphasis> tab or the <emphasis
+          role="bold">Backgrounds</emphasis> tab, respectively.</para>
+        </note>
+      </listitem>
+
+      <listitem>
+        <para>Remove Submap</para>
+
+        <para>This option is used for removing the current submap. The submap
+        must be empty, all children submaps or uCPE Devices must be deleted first.</para>
+      </listitem>
+
+      <listitem>
+        <para>Properties</para>
+
+        <para>This option is used for viewing and/or editing the properties of
+        the current submap. For more details please see the <link
+        linkend="submap_props">Submap properties</link> table.</para>
+      </listitem>
+
+      <listitem>
+        <para>Move Device</para>
+
+        <para>This option is used for adding devices to the current submap.
+        All devices appear in this list (placed and unplaced). If the device
+        is already added to a submap, it will be moved from that submap to the
+        current one.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="map_op">
+    <title>Map Operations</title>
+
+    <para>Right-clicking anywhere in the <emphasis role="bold">Map</emphasis>
+    view opens up a menu with the following operations:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Place Device</para>
+
+        <para>This option is used for adding one or more devices in the
+        current submap. Only unplaced devices appear in this list.</para>
+      </listitem>
+
+      <listitem>
+        <para>Move Device</para>
+
+        <para>This option is used for moving one or more devices from other
+        submaps to the current submap. All devices appear in this list (placed
+        and unplaced). If the device is already added to a submap, it will be
+        removed from that submap.</para>
+      </listitem>
+
+      <listitem>
+        <para>Add Unmanaged</para>
+
+        <para>This option is used for creating an unmanaged device. An
+        unmanaged device is represented by an icon in the current view that
+        looks like a device (it supports links and has a similar icon) but 
+          is not a real managed device. It will be automatically placed in the current
+        submap. When selecting this option, the following fields need to be
+        set in the <emphasis role="bold">Add Unmanaged</emphasis> window that
+        pops-up:</para>
+
+        <table id="unmanaged_props">
+            <title>Unmanaged device properties</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry>Name</entry>
+
+                  <entry>The name of the device.</entry>
+                </row>
+
+                <row>
+                  <entry>Description</entry>
+
+                  <entry>A text description of the device.</entry>
+                </row>
+
+                <row>
+                  <entry>Icon Image</entry>
+
+                  <entry>The icon image of the device.</entry>
+                </row>
+
+                <row>
+                  <entry>Status</entry>
+
+                  <entry>The status of the device.</entry>
+                </row>
+
+                <row>
+                  <entry>Status Tooltip</entry>
+
+                  <entry>The tooltip for the device status.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+      </listitem>
+
+      <listitem>
+        <para>Add Link</para>
+
+        <para>This option is used for creating a virtual link between two
+        devices. They can be any two devices, it does not matter if they are
+        unplaced, placed in the current submap or placed in any other submap.
+        When selecting this option, the following fields need to be set in the
+        <emphasis role="bold">Add Link</emphasis> window:</para>
+
+        <table id="link_props">
+            <title>Link properties</title>
+
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry>Name</entry>
+
+                  <entry>The name of the link.</entry>
+                </row>
+
+                <row>
+                  <entry>Description</entry>
+
+                  <entry>A text description of the link.</entry>
+                </row>
+
+                <row>
+                  <entry>From</entry>
+
+                  <entry>One of the endpoints of the link.</entry>
+                </row>
+
+                <row>
+                  <entry>To</entry>
+
+                  <entry>The 2nd endpoint of the link.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+      </listitem>
+
+      <listitem>
+        <para>Properties</para>
+
+        <para>This option is used for viewing and/or editing the properties of
+        the current submap. For more details please see the <link
+        linkend="submap_props">Submap properties</link> table.</para>
+      </listitem>
+
+      <listitem>
+        <para>Arrange icons</para>
+
+        <para>This option can be used to auto-arrange devices placed in the
+        current submap. The rearrangement is done based on the submap's
+        properties.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="device_op">
+    <title>Device Operations</title>
+
+    <para>In the <emphasis role="bold">Map</emphasis> view, right-clicking on
+    a device opens up a menu with the following operations:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Links...</para>
+
+        <para>This option is used for viewing all links to and from that
+        device.</para>
+      </listitem>
+
+      <listitem>
+        <para>Remove</para>
+
+        <para>For managed devices, this option is used for removing the device
+        from the map. The managed device will not be removed completely from
+        the Enea Edge Management application, but will be moved to the <emphasis
+        role="bold">Unplaced</emphasis> submap instead.</para>
+
+        <para>For unmanaged devices, this option removes the device altogether
+        from the Enea Edge Management application.</para>
+      </listitem>
+
+      <listitem>
+        <para>Add Link</para>
+
+        <para>This option is used for creating a virtual link between two
+        devices. They can be any two devices, it does not matter if they are
+        unplaced, placed in the current submap or placed in any other submap.
+        The current device is already selected as the <emphasis
+        role="bold">From</emphasis> endpoint in the <emphasis role="bold">Add
+        Link</emphasis> pop-up. For more details please see the <link
+        linkend="link_props">Link properties</link> table.</para>
+      </listitem>
+
+      <listitem>
+        <para>Properties</para>
+
+        <para>This option is used for viewing and editing the properties of an
+        unmanaged device. For more details please see the <link
+        linkend="unmanaged_props">Unmanaged device properties</link> table.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+</chapter>
\ No newline at end of file