docs: added tutorials overview and tutorial 6

docs/tutorials/overview.md

@@ -0,0 +1,29 @@
+# CORE Tutorials
+
+These tutorials will cover various use cases within CORE. These
+tutorials will provide example python, gRPC, XML, and related files, as well
+as an explanation for their usage and purpose.
+
+## Checklist
+
+These are the items you should become familiar with for running all the tutorials below.
+
+* [Install CORE](../install.md)
+* [Tutorial Setup](setup.md)
+
+## Tutorials
+
+* [Tutorial 1 - Wired Network](tutorial1.md)
+    * Covers interactions when using a simple 2 node wired network
+* [Tutorial 2 - Wireless Network](tutorial2.md)
+    * Covers interactions when using a simple 3 node wireless network
+* [Tutorial 3 - Basic Mobility](tutorial3.md)
+    * Covers mobility interactions when using a simple 3 node wireless network
+* [Tutorial 4 - Tests](tutorial4.md)
+    * Covers automating scenarios as tests to validate software
+* [Tutorial 5 - Access Windows](tutorial5.md)
+    * Covers using the RJ45 node to connect a Windows OS
+* [Tutorial 6 - Improve Visuals](tutorial6.md)
+    * Covers changing the look of a scenario within the CORE GUI
+* [Tutorial 7 - EMANE](tutorial7.md)
+    * Covers using EMANE within CORE for higher fidelity RF networks

docs/tutorials/tutorial6.md

@@ -0,0 +1,97 @@
+# Tutorial 6 - Improved Visuals
+
+## Overview
+
+This tutorial will cover changing the node icons, changing the background, and changing or hiding links.
+
+## Files
+
+Below is the list of files used for this tutorial.
+
+* drone.png - icon for a drone
+* demo.py - a mobility script for a node
+* terrain.png - a background
+* completed-scenario.xml - the scenario after making all changes below
+
+## Running this Tutorial
+
+This section will cover running this sample tutorial that develops a scenario file.
+
+* Ensure that **/etc/core/core.conf** has **grpcaddress** set to **0.0.0.0**
+* Make sure the **core-daemon** is running in a terminal
+    ```shell
+    sudop core-daemon
+    ```
+* In another terminal run the GUI
+    ```shell
+    core-gui
+    ```
+
+### Changing Node Icons
+
+* Create three MDR nodes
+   <p align="center">
+     <img src="/static/tutorial6/create-nodes.png" width="80%">
+   </p>
+* Double click on each node for configuration, click the icon and set it to use the **drone.png** image
+   <p align="center">
+     <img src="/static/tutorial6/configure-icon.png" width="50%">
+   </p>
+* Use **Session -> Options** and set **Control Network 0** to **172.16.0.0./24**
+
+### Linking Nodes to WLAN
+
+* Add a WLAN Node
+* Link the three prior MDR nodes to the WLAN node
+   <p align="center">
+     <img src="/static/tutorial6/linked-nodes.png" width="50%">
+   </p>
+* Click play to start the scenario
+* Observe wireless links being created
+   <p align="center">
+     <img src="/static/tutorial6/wlan-links.png" width="50%">
+   </p>
+* Click stop to end the scenario
+* Right click the WLAN node and select **Edit -> Hide**
+* Now you can view the nodes in isolation
+   <p align="center">
+     <img src="/static/tutorial6/hidden-nodes.png" width="50%">
+   </p>
+
+### Changing Canvas Background
+
+* Click **Canvas -> Wallpaper** to set the background to terrain.png
+   <p align="center">
+     <img src="/static/tutorial6/select-wallpaper.png" width="50%">
+   </p>
+* Click play to start the scenario again
+* You now have a scenario with drone icons, terrain background, links displayed and hidden WLAN node
+   <p align="center">
+     <img src="/static/tutorial6/scenario-with-terrain.png" width="80%">
+   </p>
+
+## Adding Mobility
+
+* Open and play the **completed-scenario.xml**
+* Double click on **n1** and run the **demo.py** script
+   ```shell
+   # node id is first parameter, second is total nodes
+   /opt/core/venv/bin/python demo.py 1 3
+   ```
+* Let it run to see the link break as the node 1 drone approches the right side
+   <p align="center">
+     <img src="/static/tutorial6/only-node1-moving.png" width="80%">
+   </p>
+* Repeat for other nodes, double click on **n2** and **n3** and run the demo.py script
+   ```shell
+   # n2
+   /opt/core/venv/bin/python demo.py 2 3
+   # n3
+   /opt/core/venv/bin/python demo.py 3 3
+   ```
+* You can turn off wireless links via **View -> Wireless Links**
+* Observe nodes moving in parallel tracks, when the far right is reached, the node will move down
+  and then move to the left. When the far left is reached, the drone will move down and then move to the right.
+   <p align="center">
+     <img src="/static/tutorial6/scenario-with-motion.png" width="80%">
+   </p>

mkdocs.yml

@@ -39,9 +39,11 @@ nav:
       - Ubuntu: install_ubuntu.md
       - CentOS: install_centos.md
   - Tutorials:
+      - Overview: tutorials/overview.md
       - Setup: tutorials/setup.md
       - Tutorial 1: tutorials/tutorial1.md
       - Tutorial 4: tutorials/tutorial4.md
+      - Tutorial 6: tutorials/tutorial6.md
       - Tutorial 7: tutorials/tutorial7.md
   - Detailed Topics:
       - GUI: gui.md

package/examples/tutorials/tutorial6/completed-scenario.xml

@@ -0,0 +1,114 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<scenario name="/tmp/tmpaghphwl7">
+  <networks>
+    <network id="4" name="n4" icon="" canvas="1" type="WIRELESS">
+      <position x="170.0" y="184.0" lat="47.577493888263376" lon="-122.13003351477549" alt="2.0"/>
+      <wireless>
+        <configuration name="movement" value="1"/>
+        <configuration name="max-range" value="400.0"/>
+        <configuration name="bandwidth" value="54000000"/>
+        <configuration name="delay" value="5000"/>
+        <configuration name="jitter" value="0"/>
+        <configuration name="loss-range" value="300.0"/>
+        <configuration name="loss-factor" value="1.0"/>
+        <configuration name="loss" value="0.0"/>
+      </wireless>
+    </network>
+  </networks>
+  <devices>
+    <device id="1" name="n1" icon="/usr/share/core/examples/tutorials/tutorial6/drone.png" canvas="1" type="mdr" class="" image="">
+      <position x="303.0" y="25.0" lat="47.57893917036898" lon="-122.12824137578366" alt="2.0"/>
+      <configservices>
+        <service name="zebra"/>
+        <service name="IPForward"/>
+        <service name="OSPFv3MDR"/>
+      </configservices>
+    </device>
+    <device id="2" name="n2" icon="/usr/share/core/examples/tutorials/tutorial6/drone.png" canvas="1" type="mdr" class="" image="">
+      <position x="205.0" y="158.0" lat="47.57773022643051" lon="-122.12956189925131" alt="2.0"/>
+      <configservices>
+        <service name="zebra"/>
+        <service name="IPForward"/>
+        <service name="OSPFv3MDR"/>
+      </configservices>
+    </device>
+    <device id="3" name="n3" icon="/usr/share/core/examples/tutorials/tutorial6/drone.png" canvas="1" type="mdr" class="" image="">
+      <position x="120.0" y="316.0" lat="47.57629400111251" lon="-122.13070725123856" alt="2.0"/>
+      <configservices>
+        <service name="zebra"/>
+        <service name="IPForward"/>
+        <service name="OSPFv3MDR"/>
+      </configservices>
+    </device>
+  </devices>
+  <links>
+    <link node1="1" node2="4">
+      <iface1 id="0" name="eth0" mac="00:00:00:aa:00:00" ip4="10.0.0.1" ip4_mask="32" ip6="2001::1" ip6_mask="128"/>
+    </link>
+    <link node1="2" node2="4">
+      <iface1 id="0" name="eth0" mac="00:00:00:aa:00:01" ip4="10.0.0.2" ip4_mask="32" ip6="2001::2" ip6_mask="128"/>
+    </link>
+    <link node1="3" node2="4">
+      <iface1 id="0" name="eth0" mac="00:00:00:aa:00:02" ip4="10.0.0.3" ip4_mask="32" ip6="2001::3" ip6_mask="128"/>
+    </link>
+  </links>
+  <configservice_configurations>
+    <service name="zebra" node="1"/>
+    <service name="IPForward" node="1"/>
+    <service name="OSPFv3MDR" node="1"/>
+    <service name="zebra" node="2"/>
+    <service name="IPForward" node="2"/>
+    <service name="OSPFv3MDR" node="2"/>
+    <service name="zebra" node="3"/>
+    <service name="IPForward" node="3"/>
+    <service name="OSPFv3MDR" node="3"/>
+  </configservice_configurations>
+  <session_origin lat="47.579166412353516" lon="-122.13232421875" alt="2.0" scale="150.0"/>
+  <session_options>
+    <configuration name="controlnet" value=""/>
+    <configuration name="controlnet0" value="172.16.0.0/24"/>
+    <configuration name="controlnet1" value=""/>
+    <configuration name="controlnet2" value=""/>
+    <configuration name="controlnet3" value=""/>
+    <configuration name="controlnet_updown_script" value=""/>
+    <configuration name="enablerj45" value="1"/>
+    <configuration name="preservedir" value="0"/>
+    <configuration name="enablesdt" value="0"/>
+    <configuration name="sdturl" value="tcp://127.0.0.1:50000/"/>
+    <configuration name="ovs" value="0"/>
+    <configuration name="platform_id_start" value="1"/>
+    <configuration name="nem_id_start" value="1"/>
+    <configuration name="link_enabled" value="1"/>
+    <configuration name="loss_threshold" value="30"/>
+    <configuration name="link_interval" value="1"/>
+    <configuration name="link_timeout" value="4"/>
+    <configuration name="mtu" value="0"/>
+  </session_options>
+  <session_metadata>
+    <configuration name="shapes" value="[]"/>
+    <configuration name="edges" value="[]"/>
+    <configuration name="hidden" value="[4]"/>
+    <configuration name="canvas" value="{&quot;gridlines&quot;: true, &quot;canvases&quot;: [{&quot;id&quot;: 1, &quot;wallpaper&quot;: &quot;/usr/share/core/examples/tutorials/tutorial6/terrain.png&quot;, &quot;wallpaper_style&quot;: 1, &quot;fit_image&quot;: false, &quot;dimensions&quot;: [1000, 750]}]}"/>
+  </session_metadata>
+  <default_services>
+    <node type="mdr">
+      <service name="zebra"/>
+      <service name="OSPFv3MDR"/>
+      <service name="IPForward"/>
+    </node>
+    <node type="PC">
+      <service name="DefaultRoute"/>
+    </node>
+    <node type="prouter"/>
+    <node type="router">
+      <service name="zebra"/>
+      <service name="OSPFv2"/>
+      <service name="OSPFv3"/>
+      <service name="IPForward"/>
+    </node>
+    <node type="host">
+      <service name="DefaultRoute"/>
+      <service name="SSH"/>
+    </node>
+  </default_services>
+</scenario>

package/examples/tutorials/tutorial6/demo.py

@@ -0,0 +1,103 @@
+import sys
+import time
+
+from core.api.grpc import client
+from core.api.grpc.wrappers import Position
+
+
+# start_row can be used to share a search
+def find_next_position(arr, start_row):
+    # find next position with value of 0 for 'not visited'
+    min_rows, min_cols = (25, 25)
+    rows, cols = (470, 900)
+    if start_row < min_rows:
+        start_row = min_rows
+    for y in range(start_row, rows):
+        for x in range(min_cols, cols):
+            if (y % 2) == 0:
+                print(f"search_x={x}")
+                print(f"search_y={y}")
+                val = arr[x][y]
+                if (val == 0) or (val == 100):
+                    return x,y
+            else:
+                search_x = cols - (x - min_cols + 1)
+                print(f"search_x={search_x}")
+                print(f"search_y={y}")
+                val = arr[search_x][y]
+                if val == 0:
+                    return search_x,y
+
+
+def move(current_x, current_y, to_x, to_y):
+    # move 1 pixel
+    speed = 1
+    if to_x > current_x:
+        move_x = current_x + speed
+    elif to_x < current_x:
+        move_x = current_x - speed
+    else:
+        move_x = current_x
+    if to_y > current_y:
+        move_y = current_y + speed
+    elif to_y < current_y:
+        move_y = current_y - speed
+    else:
+        move_y = current_y
+    return move_x, move_y
+
+
+def main():
+    n = len(sys.argv)
+    if (n < 3):
+        print("Usage: core-python demo.py <node num> <total search nodes>")
+        exit()
+
+    # number of search nodes
+    num_search_nodes = int(sys.argv[2])
+
+    # create grpc client and connect
+    core = client.CoreGrpcClient("172.16.0.254:50051")
+    core.connect()
+
+    # get session
+    sessions = core.get_sessions()
+    rows_per_zone = (499 - 25) / num_search_nodes
+    node_number =  int(sys.argv[1])
+    y_start = (node_number - 1) * int(rows_per_zone)
+    current_x = 25
+    current_y =  y_start
+
+    # max x and y
+    rows, cols = (470, 900)
+    arr = [[0 for i in range(rows)] for j in range(cols)]
+    print(arr, "before")
+
+    # place target
+    # update one element as target
+    arr[200][165] = 100
+    print(arr, "after")
+
+    while True:
+        val = arr[current_x][current_y]
+        # if position has target, stop
+        if val == 100:
+            print(f"found target, position={position}")
+        else:
+            #update one element for this starting position
+            arr[current_x][current_y] = 1
+            # move
+            to_x, to_y = find_next_position(arr, y_start)
+            print(f"next x={to_x}, next y={to_y}")
+            x, y = move(current_x, current_y, to_x, to_y)
+            # command the move
+            position = Position(x , y)
+            print(f"move to position {position}")
+            core.move_node(sessions[0].id, node_number, position=position)
+            current_x = x
+            current_y = y
+        time.sleep(.25)
+
+
+if __name__ == "__main__":
+    main()