ELCCR-2189: user documentation for tile server maps

Change-Id: I0bfcec8c04ed9a968b5a22e05de80d5411706405

2 files changed, 420 insertions, 164 deletions

diff --git a/doc/book-enea-edge-getting-started/doc/images/create_tileserver.png b/doc/book-enea-edge-getting-started/doc/images/create_tileserver.png
new file mode 100644
index 0000000..169ad81
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/create_tileserver.png
diff --git a/doc/book-enea-edge-getting-started/doc/submaps.xml b/doc/book-enea-edge-getting-started/doc/submaps.xml
index bdb769e..70ed856 100644
--- a/doc/book-enea-edge-getting-started/doc/submaps.xml
+++ b/doc/book-enea-edge-getting-started/doc/submaps.xml
@@ -1,38 +1,43 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
-<chapter id="submaps">
-  <title>Submaps</title>
+<chapter id="maps">
+  <title>Maps</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>
+  <section id="submaps">
+    <title>Submaps</title>
 
-  <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>
+    <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>
 
-  <section id="submap_op">
-    <title>Submap Operations</title>
+    <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>
 
-    <para>In the <emphasis role="bold">System</emphasis> view, right-clicking
-    on a submap opens up a menu with the following operations:</para>
+    <section id="submap_op">
+      <title>Submap Operations</title>
 
-    <itemizedlist>
-      <listitem>
-        <para>Add Submap</para>
+      <para>In the <emphasis role="bold">System</emphasis> view,
+      right-clicking on a submap opens up a menu with the following
+      operations:</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>
+      <itemizedlist>
+        <listitem>
+          <para>Add 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>
+          <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>
 
-        <table id="submap_props">
+          <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">
@@ -118,84 +123,86 @@
             </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">
+          <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">
@@ -232,18 +239,18 @@
               </tbody>
             </tgroup>
           </table>
-      </listitem>
+        </listitem>
 
-      <listitem>
-        <para>Add Link</para>
+        <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>
+          <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">
+          <table id="link_props">
             <title>Link properties</title>
 
             <tgroup cols="2">
@@ -274,71 +281,320 @@
               </tbody>
             </tgroup>
           </table>
-      </listitem>
+        </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>
+  </section>
 
-      <listitem>
-        <para>Properties</para>
+  <section id="tileserver">
+    <title>Tile Server Map</title>
 
-        <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>
+    <para>The Enea Edge Management application has the capacity to render a map from a tile
+    server. Each uCPE device can have a set location and will be automatically
+    placed on the tile server map at its exact location.</para>
 
-      <listitem>
-        <para>Arrange icons</para>
+    <section id="tileserver_config">
+      <title>Tile Server Configuration</title>
 
-        <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>
+      <para>To configure the tile server map, perform the following steps in
+      the Enea Edge Management application:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Access the <emphasis role="bold">System</emphasis> menu and
+          select <emphasis role="bold">Configuration</emphasis>. A new window
+          will open.</para>
+        </listitem>
 
-  <section id="device_op">
-    <title>Device Operations</title>
+        <listitem>
+          <para>In the <emphasis role="bold">System Configuration</emphasis>
+          window, under the <emphasis role="bold">Properties</emphasis> tab,
+          navigate to the <emphasis role="bold">GUI</emphasis> tab.</para>
+        </listitem>
 
-    <para>In the <emphasis role="bold">Map</emphasis> view, right-clicking on
-    a device opens up a menu with the following operations:</para>
+        <listitem>
+          <para>Under the <emphasis role="bold">Tile Server</emphasis>
+          category, the user can set the following properties:</para>
 
-    <itemizedlist>
-      <listitem>
-        <para>Links...</para>
+          <table id="submap_props">
+            <title>Tile Server properties</title>
 
-        <para>This option is used for viewing all links to and from that
-        device.</para>
-      </listitem>
+            <tgroup cols="2">
+              <tbody>
+                <row>
+                  <entry>Name</entry>
 
-      <listitem>
-        <para>Remove</para>
+                  <entry>The name of the domain map. This is
+                  mandatory.</entry>
+                </row>
 
-        <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>
+                <row>
+                  <entry>Tile server URL</entry>
 
-        <para>For unmanaged devices, this option removes the device altogether
-        from the Enea Edge Management application.</para>
-      </listitem>
+                  <entry>The URL of the tile server's XYZ.</entry>
+                </row>
 
-      <listitem>
-        <para>Add Link</para>
+                <row>
+                  <entry>TileJSON URL</entry>
 
-        <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>
+                  <entry>The URL of the TileJSON configuration file. Leave it 
+                    blank if the tile server used does not support json
+                  configuration files.</entry>
+                </row>
 
-      <listitem>
-        <para>Properties</para>
+                <row>
+                  <entry>Tile server attribution</entry>
 
-        <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>
+                  <entry>The attribution to be displayed on the map.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+        </listitem>
+
+        <listitem>
+          <para>Press the <emphasis role="bold">Apply</emphasis> button. The
+          <emphasis role="bold">Saved successfully</emphasis> message will be
+          shown.</para>
+        </listitem>
+      </orderedlist>
+
+      <note>
+        <para>The Browser Cross-Origin Resource Sharing (CORS) policy prevents
+        requests from HTTPS to an external HTTP. This means that if the default
+        HTTPS configuration is used for the Enea Edge Management application,
+        the application will not be able to reach a tile server that is
+        accessible only through HTTP. In this case a proxy can be installed that 
+          provides a gateway for HTTPS calls to HTTP. Optionally, HTTP web access 
+          can be used for accessing the Enea Edge Management application.</para>
+      </note>
+    </section>
+
+    <section id="tileserver_create">
+      <title>Creating the Tile Server View</title>
+
+      <para>To create a tile server view, perform the following steps in the
+      Enea Edge Management application:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Access the <emphasis role="bold">Security</emphasis> menu and
+          select <emphasis role="bold">Configuration</emphasis>. A new window
+          will open.</para>
+        </listitem>
+
+        <listitem>
+          <para>In the <emphasis role="bold">Security Configuration</emphasis>
+          window, navigate to the <emphasis role="bold">Views</emphasis> tab.
+          The <emphasis role="bold">Views Table</emphasis> will be
+          shown.</para>
+        </listitem>
+
+        <listitem>
+          <para>Press the <emphasis role="bold">Add</emphasis> button. A new
+          window will open.</para>
+        </listitem>
+
+        <listitem>
+          <para>In the <emphasis role="bold">Create View</emphasis> window,
+            set a name for the TileServer view, select <literal>tileserver</literal> 
+            in the <emphasis role="bold">Map Type</emphasis> drop-down menu and place the
+          admin user in the right-hand side listbox.</para>
+        </listitem>
+
+        <listitem>
+          <para>Press the <emphasis role="bold">OK</emphasis> button. The
+          current window will close and the success message <emphasis
+          role="bold">Created successfully</emphasis> will be shown.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>A new entry will be added in the <emphasis role="bold">Views
+      Table</emphasis>.</para>
+
+      <figure>
+        <title>Create a tile server view</title>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" contentwidth="600"
+                       fileref="images/create_tileserver.png" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+
+      <para>In the main window, select the newly created tile server view in
+      the <emphasis role="bold">View</emphasis> drop-down menu. Upon a correct
+      configuration, the map will be loaded.</para>
+    </section>
+
+    <section id="tileserver_latlon">
+      <title>Setting uCPE Device Location</title>
+
+      <para>To set the location of a managed uCPE device, perform the
+      following steps:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Access the <emphasis role="bold">Device</emphasis> menu and
+          select <emphasis role="bold">Manage</emphasis>. A new window will
+          open.</para>
+        </listitem>
+
+        <listitem>
+          <para>In the <emphasis role="bold">Manage Devices</emphasis> window,
+          navigate to the <emphasis role="bold">Devices</emphasis> tab. The
+          <emphasis role="bold">Managed Devices Table</emphasis> will be
+          shown.</para>
+        </listitem>
+
+        <listitem>
+          <para>Select de desired uCPE device. The device's properties will be
+          shown on the right side of the window.</para>
+        </listitem>
+
+        <listitem>
+          <para>Navigate to the <emphasis role="bold">Location</emphasis> tab.
+          Latitude and longitude can be set here.</para>
+
+          <note>
+            <para>Latitude and longitude should be in the decimal degrees (DD)
+            format.</para>
+          </note>
+        </listitem>
+
+        <listitem>
+          <para>Press the <emphasis role="bold">Apply</emphasis> button. The
+          <emphasis role="bold">Saved successfully</emphasis> message will be
+          shown.</para>
+
+          <para>The device will be automatically added on the map in the tile
+          server view. If the device is already added on the tile server map,
+          its location will be updated.</para>
+        </listitem>
+      </orderedlist>
+    </section>
+
+    <section id="tileserver_map">
+      <title>Placing the uCPE Device on the Map</title>
+
+      <para>To place a uCPE device on the map in the tile server view, perform
+      the following steps:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Right-click on the map and choose the <emphasis
+          role="bold">Place device</emphasis> option. A new window will
+          open.</para>
+        </listitem>
+
+        <listitem>
+          <para>In the <emphasis role="bold">Add Device</emphasis> window,
+          select the desired device.</para>
+        </listitem>
+
+        <listitem>
+          <para>If the <emphasis role="bold">Override device
+          location</emphasis> checkbox is left unchecked, the device will be placed at
+          the coordonates previously set in the <emphasis
+          role="bold">Location</emphasis> tab.</para>
+        </listitem>
+
+        <listitem>
+          <para>If the <emphasis role="bold">Override device
+          location</emphasis> checkbox is checked, the coordonates set on the device 
+            previously will be ignored, and the device will be placed at the cursor's
+          position.</para>
+
+          <note>
+            <para>Checking the <emphasis role="bold">Override device
+            location</emphasis> checkbox does not alter the coordonates
+            already set for the device.</para>
+          </note>
+        </listitem>
+      </orderedlist>
+
+      <para>A device already placed on the map can be dragged and dropped
+      inside the map. Coordonates will not be changed.</para>
+
+      <para>If two or more uCPE devices are too close together on the map, and 
+        the current zoom level cannot accomodate all their icons, a cluster
+      will be shown. The cluster is represented by a large circle that
+      displays a number representing the number of devices it contains. The
+      color of the cluster changes according to the alarms of the devices in
+      the cluster.</para>
+
+      <para>Once clicked, the cluster will zoom in to a degree where all
+      elements can be distinguished. When hovering over the cluster, a window
+      with information about the cluster will be available. It will contain
+      the number of the devices in the cluster, as well as their status. The
+      Devices link will open a drop-down menu that contains all the devices.</para>
+    </section>
   </section>
 </chapter>
\ No newline at end of file