diff --git a/docs/static/tutorial2/wireless-config-delay.png b/docs/static/tutorial2/wireless-config-delay.png new file mode 100644 index 00000000..b375af76 Binary files /dev/null and b/docs/static/tutorial2/wireless-config-delay.png differ diff --git a/docs/static/tutorial2/wireless-configuration.png b/docs/static/tutorial2/wireless-configuration.png new file mode 100644 index 00000000..9b87959c Binary files /dev/null and b/docs/static/tutorial2/wireless-configuration.png differ diff --git a/docs/static/tutorial2/wireless.png b/docs/static/tutorial2/wireless.png new file mode 100644 index 00000000..8543117d Binary files /dev/null and b/docs/static/tutorial2/wireless.png differ diff --git a/docs/static/tutorial3/mobility-script.png b/docs/static/tutorial3/mobility-script.png new file mode 100644 index 00000000..6f32e5b1 Binary files /dev/null and b/docs/static/tutorial3/mobility-script.png differ diff --git a/docs/static/tutorial3/motion_continued_breaks_link.png b/docs/static/tutorial3/motion_continued_breaks_link.png new file mode 100644 index 00000000..cc1f5dcd Binary files /dev/null and b/docs/static/tutorial3/motion_continued_breaks_link.png differ diff --git a/docs/static/tutorial3/motion_from_ns2_file.png b/docs/static/tutorial3/motion_from_ns2_file.png new file mode 100644 index 00000000..704cc1d9 Binary files /dev/null and b/docs/static/tutorial3/motion_from_ns2_file.png differ diff --git a/docs/static/tutorial3/move-n2.png b/docs/static/tutorial3/move-n2.png new file mode 100644 index 00000000..befcd4b0 Binary files /dev/null and b/docs/static/tutorial3/move-n2.png differ diff --git a/docs/tutorials/tutorial2.md b/docs/tutorials/tutorial2.md new file mode 100644 index 00000000..4c1c9fb3 --- /dev/null +++ b/docs/tutorials/tutorial2.md @@ -0,0 +1,145 @@ +# Tutorial 2 - Wireless Network + +## Overview + +This tutorial will cover the use of a 3 node scenario in CORE. Then +running a chat server on one node and a chat client on the other. The client will +send a simple message and the server will log receipt of the message. + +## Files + +Below is the list of files used for this tutorial. + +* scenario.xml - 3 node CORE xml scenario file (wireless) +* scenario.py - 3 node CORE gRPC python script (wireless) + +## Running with the XML Scenario File + +This section will cover running this sample tutorial using the +XML scenario file, leveraging an NS2 mobility file. + +* Make sure the **core-daemon** is running a terminal + ```shell + sudop core-daemon + ``` +* In another terminal run the GUI + ```shell + core-gui + ``` +* In the GUI menu bar select **File->Open...** +* Navigate to and select this tutorials **scenario.xml** file +* You can now click play to start the session +

+ +

+* Note that OSPF routing protocol is included in the scenario to provide routes to other nodes, as they are discovered +* Double click node **n4** to open a terminal and ping node **n2** + ```shell + ping -c 2 10.0.0.2 + PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data. + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=20.2 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=20.2 ms + + --- 10.0.0.2 ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 1000ms + rtt min/avg/max/mdev = 20.168/20.173/20.178/0.005 ms + ``` + +### Configuring Delay + +* Right click on the **wlan1** node and select **WLAN Config**, then set delay to 500000 +

+ +

+* Using the open terminal for node **n4**, ping **n2** again, expect about 2 seconds delay + ```shell + ping -c 5 10.0.0.2 + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=2001 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=2000 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=63 time=2000 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=63 time=2000 ms + 64 bytes from 10.0.0.2: icmp_seq=5 ttl=63 time=2000 ms + + --- 10.0.0.2 ping statistics --- + 5 packets transmitted, 5 received, 0% packet loss, time 4024ms + rtt min/avg/max/mdev = 2000.176/2000.438/2001.166/0.376 ms, pipe 2 + ``` + +### Configure Loss + +* Right click on the **wlan1** node and select **WLAN Config**, set delay back to 5000 and loss to 10 +

+ +

+* Using the open terminal for node **n4**, ping **n2** again, expect to notice considerable loss + ```shell + ping -c 10 10.0.0.2 + PING 10.0.0.2 (10.0.0.2) 56(84) bytes of data. + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=63 time=20.4 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=63 time=20.5 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=63 time=20.2 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=63 time=20.8 ms + 64 bytes from 10.0.0.2: icmp_seq=5 ttl=63 time=21.9 ms + 64 bytes from 10.0.0.2: icmp_seq=8 ttl=63 time=22.7 ms + 64 bytes from 10.0.0.2: icmp_seq=9 ttl=63 time=22.4 ms + 64 bytes from 10.0.0.2: icmp_seq=10 ttl=63 time=20.3 ms + + --- 10.0.0.2 ping statistics --- + 10 packets transmitted, 8 received, 20% packet loss, time 9064ms + rtt min/avg/max/mdev = 20.188/21.143/22.717/0.967 ms + ``` +* Make sure to set loss back to 0 when done + +## Running with the gRPC Python Script + +This section will cover running this sample tutorial using the +gRPC python script and providing mobility over the gRPC interface. + +* Make sure the **core-daemon** is running a terminal + ```shell + sudop core-daemon + ``` +* In another terminal run the GUI + ```shell + core-gui + ``` +* From another terminal run the **scenario.py** script + ```shell + /opt/core/venv/bin/python scenario.py + ``` +* In the GUI dialog box select the session and click connect +* You will now have joined the already running scenario + +

+ +

+ +## Running Software + +We will now leverage the installed Chat App software to stand up a server and client +within the nodes of our scenario. You can use the bases of the running scenario from +either **scenario.xml** or the **scenario.py** gRPC script. + +* In the GUI double click on node **n4**, this will bring up a terminal for this node +* In the **n4** terminal, run the server + ```shell + export PATH=$PATH:/usr/local/bin + chatapp-server + ``` +* In the GUI double click on node **n2**, this will bring up a terminal for this node +* In the **n2** terminal, run the client + ```shell + export PATH=$PATH:/usr/local/bin + chatapp-client -a 10.0.0.4 + ``` +* This will result in **n2** connecting to the server +* In the **n2** terminal, type a message at the client prompt + ```shell + >>hello world + ``` +* Observe that text typed at client then appears in the terminal of **n4** + ```shell + chat server listening on: :9001 + [server] 10.0.0.2:53684 joining + [10.0.0.2:53684] hello world + ``` diff --git a/docs/tutorials/tutorial3.md b/docs/tutorials/tutorial3.md new file mode 100644 index 00000000..0bc36c1d --- /dev/null +++ b/docs/tutorials/tutorial3.md @@ -0,0 +1,154 @@ +# Tutorial 3 - Basic Mobility + +## Overview + +This tutorial will cover using a 3 node scenario in CORE with basic mobility. +Mobility can be provided from a NS2 file or by including mobility commands in a gRPC script. + +## Files + +Below is the list of files used for this tutorial. + +* movements1.txt - a NS2 mobility input file +* scenario.xml - 3 node CORE xml scenario file (wireless) +* scenario.py - 3 node CORE gRPC python script (wireless) +* printout.py - event listener + +## Running with XML file using NS2 Movement + +This section will cover running this sample tutorial using the XML scenario + file, leveraging an NS2 file for mobility. + +* Make sure the **core-daemon** is running a terminal + ```shell + sudop core-daemon + ``` +* In another terminal run the GUI + ```shell + core-gui + ``` +* Observe the format of the N2 file, cat movements1.txt. Note that this file was manually developed. + ```shell + $node_(1) set X_ 208.1 + $node_(1) set Y_ 211.05 + $node_(1) set Z_ 0 + $ns_ at 0.0 "$node_(1) setdest 208.1 211.05 0.00" + $node_(2) set X_ 393.1 + $node_(2) set Y_ 223.05 + $node_(2) set Z_ 0 + $ns_ at 0.0 "$node_(2) setdest 393.1 223.05 0.00" + $node_(4) set X_ 499.1 + $node_(4) set Y_ 186.05 + $node_(4) set Z_ 0 + $ns_ at 0.0 "$node_(4) setdest 499.1 186.05 0.00" + $ns_ at 1.0 "$node_(1) setdest 190.1 225.05 0.00" + $ns_ at 1.0 "$node_(2) setdest 393.1 225.05 0.00" + $ns_ at 1.0 "$node_(4) setdest 515.1 186.05 0.00" + $ns_ at 2.0 "$node_(1) setdest 175.1 250.05 0.00" + $ns_ at 2.0 "$node_(2) setdest 393.1 250.05 0.00" + $ns_ at 2.0 "$node_(4) setdest 530.1 186.05 0.00" + $ns_ at 3.0 "$node_(1) setdest 160.1 275.05 0.00" + $ns_ at 3.0 "$node_(2) setdest 393.1 275.05 0.00" + $ns_ at 3.0 "$node_(4) setdest 530.1 186.05 0.00" + $ns_ at 4.0 "$node_(1) setdest 160.1 300.05 0.00" + $ns_ at 4.0 "$node_(2) setdest 393.1 300.05 0.00" + $ns_ at 4.0 "$node_(4) setdest 550.1 186.05 0.00" + $ns_ at 5.0 "$node_(1) setdest 160.1 275.05 0.00" + $ns_ at 5.0 "$node_(2) setdest 393.1 275.05 0.00" + $ns_ at 5.0 "$node_(4) setdest 530.1 186.05 0.00" + $ns_ at 6.0 "$node_(1) setdest 175.1 250.05 0.00" + $ns_ at 6.0 "$node_(2) setdest 393.1 250.05 0.00" + $ns_ at 6.0 "$node_(4) setdest 515.1 186.05 0.00" + $ns_ at 7.0 "$node_(1) setdest 190.1 225.05 0.00" + $ns_ at 7.0 "$node_(2) setdest 393.1 225.05 0.00" + $ns_ at 7.0 "$node_(4) setdest 499.1 186.05 0.00" + ``` +* In the GUI menu bar select **File->Open...**, and select this tutorials **scenario.xml** file +* You can now click play to start the session +* Select the play button on the Mobility Player to start mobility +* Observe movement of the nodes +* Note that OSPF routing protocol is included in the scenario to build routing table so that routes to other nodes are known and when the routes are discovered, ping will work + +

+ +

+ +## Running with the gRPC Script + +This section covers using a gRPC script to create and provide scenario movement. + +* Make sure the **core-daemon** is running a terminal + ```shell + sudop core-daemon + ``` +* From another terminal run the **scenario.py** script + ```shell + /opt/core/venv/bin/python scenario.py + ``` +* In another terminal run the GUI + ```shell + core-gui + ``` +* In the GUI dialog box select the session and click connect +* You will now have joined the already running scenario +* In the terminal running the **scenario.py**, hit a key to start motion +

+ +

+* Observe the link between **n3** and **n4** is shown and then as motion continues the link breaks +

+ +

+ +## Running the Chat App Software + +This section covers using one of the above 2 scenarios to run software within +the nodes. + +* In the GUI double click on **n4**, this will bring up a terminal for this node +* in the **n4** terminal, run the server + ```shell + export PATH=$PATH:/usr/local/bin + chatapp-server + ``` +* In the GUI double click on **n2**, this will bring up a terminal for this node +* In the **n2** terminal, run the client + ```shell + export PATH=$PATH:/usr/local/bin + chatapp-client -a 10.0.0.4 + ``` +* This will result in **n2** connecting to the server +* In the **n2** terminal, type a message at the client prompt and hit enter + ```shell + >>hello world + ``` +* Observe that text typed at client then appears in the server terminal + ```shell + chat server listening on: :9001 + [server] 10.0.0.2:53684 joining + [10.0.0.2:53684] hello world + ``` + +## Running Mobility from a Node + +This section provides an example for running a script within a node, that +leverages a control network in CORE for issuing mobility using the gRPC +API. + +* Edit the following line in **/etc/core/core.conf** + ```shell + grpcaddress = 0.0.0.0 + ``` +* Start the scenario from the **scenario.xml** +* From the GUI open **Session -> Options** and set **Control Network** to **172.16.0.0/24** +* Click to play the scenario +* Double click on **n2** to get a terminal window +* From the terminal window for **n2**, run the script + ```shell + /opt/core/venv/bin/python move-node2.py + ``` +* Observe that node 2 moves and continues to move + +

+ +

diff --git a/mkdocs.yml b/mkdocs.yml index 8f48bef1..c2fbc03c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,11 +41,13 @@ nav: - Tutorials: - Overview: tutorials/overview.md - Setup: tutorials/setup.md - - Tutorial 1: tutorials/tutorial1.md - - Tutorial 4: tutorials/tutorial4.md - - Tutorial 5: tutorials/tutorial5.md - - Tutorial 6: tutorials/tutorial6.md - - Tutorial 7: tutorials/tutorial7.md + - Tutorial 1 - Wired Network: tutorials/tutorial1.md + - Tutorial 2 - Wireless Network: tutorials/tutorial2.md + - Tutorial 3 - Basic Mobility: tutorials/tutorial3.md + - Tutorial 4 - Tests: tutorials/tutorial4.md + - Tutorial 5 - RJ45 Node: tutorials/tutorial5.md + - Tutorial 6 - Improve Visuals: tutorials/tutorial6.md + - Tutorial 7 - EMANE: tutorials/tutorial7.md - Detailed Topics: - GUI: gui.md - Node Types: diff --git a/package/examples/tutorials/tutorial2/scenario.py b/package/examples/tutorials/tutorial2/scenario.py new file mode 100644 index 00000000..f5992efc --- /dev/null +++ b/package/examples/tutorials/tutorial2/scenario.py @@ -0,0 +1,39 @@ +from core.api.grpc import client +from core.api.grpc.wrappers import NodeType, Position + + +def main(): + # interface helper + iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64") + + # create grpc client and connect + core = client.CoreGrpcClient() + core.connect() + + # add session + session = core.create_session() + + # create nodes + position = Position(x=200, y=200) + wlan = session.add_node(1, name="wlan1", _type=NodeType.WIRELESS_LAN, position=position) + position = Position(x=100, y=100) + node1 = session.add_node(2, name="n2", model="mdr", position=position) + position = Position(x=300, y=100) + node2 = session.add_node(3, name="n3", model="mdr", position=position) + position = Position(x=500, y=100) + node3 = session.add_node(4, name="n4", model="mdr", position=position) + + # create links + iface1 = iface_helper.create_iface(node1.id, 0) + session.add_link(node1=node1, node2=wlan, iface1=iface1) + iface1 = iface_helper.create_iface(node2.id, 0) + session.add_link(node1=node2, node2=wlan, iface1=iface1) + iface1 = iface_helper.create_iface(node3.id, 0) + session.add_link(node1=node3, node2=wlan, iface1=iface1) + + # start session + core.start_session(session) + + +if __name__ == "__main__": + main() diff --git a/package/examples/tutorials/tutorial2/scenario.xml b/package/examples/tutorials/tutorial2/scenario.xml new file mode 100644 index 00000000..ee60f792 --- /dev/null +++ b/package/examples/tutorials/tutorial2/scenario.xml @@ -0,0 +1,98 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/package/examples/tutorials/tutorial3/move-node2.py b/package/examples/tutorials/tutorial3/move-node2.py new file mode 100644 index 00000000..7769b991 --- /dev/null +++ b/package/examples/tutorials/tutorial3/move-node2.py @@ -0,0 +1,32 @@ +import time + +from core.api.grpc import client +from core.api.grpc.wrappers import Position + + +def main(): + # create grpc client and connect + core = client.CoreGrpcClient("172.16.0.254:50051") + core.connect() + + # get session + sessions = core.get_sessions() + + print("sessions=", sessions) + for i in range(300): + position = Position(x= 100, y = 100 + i) + core.move_node(sessions[0].id, 2, position=position) + time.sleep(1) + print("press enter to quit") + input() + + +if __name__ == "__main__": + main() + + + + + + + diff --git a/package/examples/tutorials/tutorial3/movements1.txt b/package/examples/tutorials/tutorial3/movements1.txt new file mode 100644 index 00000000..b8271016 --- /dev/null +++ b/package/examples/tutorials/tutorial3/movements1.txt @@ -0,0 +1,33 @@ +$node_(1) set X_ 208.1 +$node_(1) set Y_ 211.05 +$node_(1) set Z_ 0 +$ns_ at 0.0 "$node_(1) setdest 208.1 211.05 0.00" +$node_(2) set X_ 393.1 +$node_(2) set Y_ 223.05 +$node_(2) set Z_ 0 +$ns_ at 0.0 "$node_(2) setdest 393.1 223.05 0.00" +$node_(4) set X_ 499.1 +$node_(4) set Y_ 186.05 +$node_(4) set Z_ 0 +$ns_ at 0.0 "$node_(4) setdest 499.1 186.05 0.00" +$ns_ at 1.0 "$node_(1) setdest 190.1 225.05 0.00" +$ns_ at 1.0 "$node_(2) setdest 393.1 225.05 0.00" +$ns_ at 1.0 "$node_(4) setdest 515.1 186.05 0.00" +$ns_ at 2.0 "$node_(1) setdest 175.1 250.05 0.00" +$ns_ at 2.0 "$node_(2) setdest 393.1 250.05 0.00" +$ns_ at 2.0 "$node_(4) setdest 530.1 186.05 0.00" +$ns_ at 3.0 "$node_(1) setdest 160.1 275.05 0.00" +$ns_ at 3.0 "$node_(2) setdest 393.1 275.05 0.00" +$ns_ at 3.0 "$node_(4) setdest 530.1 186.05 0.00" +$ns_ at 4.0 "$node_(1) setdest 160.1 300.05 0.00" +$ns_ at 4.0 "$node_(2) setdest 393.1 300.05 0.00" +$ns_ at 4.0 "$node_(4) setdest 550.1 186.05 0.00" +$ns_ at 5.0 "$node_(1) setdest 160.1 275.05 0.00" +$ns_ at 5.0 "$node_(2) setdest 393.1 275.05 0.00" +$ns_ at 5.0 "$node_(4) setdest 530.1 186.05 0.00" +$ns_ at 6.0 "$node_(1) setdest 175.1 250.05 0.00" +$ns_ at 6.0 "$node_(2) setdest 393.1 250.05 0.00" +$ns_ at 6.0 "$node_(4) setdest 515.1 186.05 0.00" +$ns_ at 7.0 "$node_(1) setdest 190.1 225.05 0.00" +$ns_ at 7.0 "$node_(2) setdest 393.1 225.05 0.00" +$ns_ at 7.0 "$node_(4) setdest 499.1 186.05 0.00" diff --git a/package/examples/tutorials/tutorial3/scenario.py b/package/examples/tutorials/tutorial3/scenario.py new file mode 100644 index 00000000..c9bad6e7 --- /dev/null +++ b/package/examples/tutorials/tutorial3/scenario.py @@ -0,0 +1,53 @@ +import time + +from core.api.grpc import client +from core.api.grpc.wrappers import NodeType, Position + + +def main(): + # interface helper + iface_helper = client.InterfaceHelper(ip4_prefix="10.0.0.0/24", ip6_prefix="2001::/64") + + # create grpc client and connect + core = client.CoreGrpcClient() + core.connect() + + # add session + session = core.create_session() + + # create nodes + position = Position(x=200, y=200) + wlan = session.add_node(3, name="wlan3", _type=NodeType.WIRELESS_LAN, position=position) + position = Position(x=100, y=100) + node1 = session.add_node(1, name="n1", model="mdr", position=position) + position = Position(x=300, y=100) + node2 = session.add_node(2, name="n2", model="mdr", position=position) + position = Position(x=500, y=100) + node3 = session.add_node(4, name="n4", model="mdr", position=position) + + # create links + iface1 = iface_helper.create_iface(node1.id, 0) + session.add_link(node1=node1, node2=wlan, iface1=iface1) + iface1 = iface_helper.create_iface(node2.id, 0) + session.add_link(node1=node2, node2=wlan, iface1=iface1) + iface1 = iface_helper.create_iface(node3.id, 0) + session.add_link(node1=node3, node2=wlan, iface1=iface1) + + # start session + core.start_session(session) + input("start motion, press enter") + + # move node 4 + for i in range(300): + position = Position(x=500 + i, y=100) + core.move_node(session.id, 4, position=position) + time.sleep(1) + x = 800 + for i in range(300): + position = Position(x=800 - i, y=100) + core.move_node(session.id, 4, position=position) + time.sleep(1) + + +if __name__ == "__main__": + main() diff --git a/package/examples/tutorials/tutorial3/scenario.xml b/package/examples/tutorials/tutorial3/scenario.xml new file mode 100644 index 00000000..dbe68d4d --- /dev/null +++ b/package/examples/tutorials/tutorial3/scenario.xml @@ -0,0 +1,124 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +