diff --git a/daemon/core/gui/data/xmls/emane-demo-eel.xml b/daemon/core/gui/data/xmls/emane-demo-eel.xml new file mode 100644 index 00000000..4162458c --- /dev/null +++ b/daemon/core/gui/data/xmls/emane-demo-eel.xml @@ -0,0 +1,146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/daemon/core/gui/data/xmls/emane-demo-files.xml b/daemon/core/gui/data/xmls/emane-demo-files.xml new file mode 100644 index 00000000..da6f9c70 --- /dev/null +++ b/daemon/core/gui/data/xmls/emane-demo-files.xml @@ -0,0 +1,146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/daemon/core/gui/data/xmls/emane-demo-gpsd.xml b/daemon/core/gui/data/xmls/emane-demo-gpsd.xml new file mode 100644 index 00000000..06bc54dc --- /dev/null +++ b/daemon/core/gui/data/xmls/emane-demo-gpsd.xml @@ -0,0 +1,146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/daemon/core/gui/data/xmls/emane-demo-precomputed.xml b/daemon/core/gui/data/xmls/emane-demo-precomputed.xml new file mode 100644 index 00000000..a19acba6 --- /dev/null +++ b/daemon/core/gui/data/xmls/emane-demo-precomputed.xml @@ -0,0 +1,146 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/emane.md b/docs/emane.md index bbd3b0a4..c2f3f3b9 100644 --- a/docs/emane.md +++ b/docs/emane.md @@ -50,6 +50,25 @@ can also subscribe to EMANE location events and move the nodes on the canvas as they are moved in the EMANE emulation. This would occur when an Emulation Script Generator, for example, is running a mobility script. +## EMANE in CORE + +This section will cover some high level topics and examples for running and +using EMANE in CORE. + +You can find more detailed tutorials and examples at the +[EMANE Tutorial](https://github.com/adjacentlink/emane-tutorial/wiki). + +Every topic below assumes CORE, EMANE, and OSPF MDR have been installed. + +> **WARNING:** demo files will be found within the new `core-pygui` + +|Topic|Model|Description| +|---|---|---| +|[XML Files](emane/files.md)|RF Pipe|Overview of generated XML files used to drive EMANE| +|[GPSD](emane/gpsd.md)|RF Pipe|Overview of running and integrating gpsd with EMANE| +|[Precomputed](emane/precomputed.md)|RF Pipe|Overview of using the precomputed propagation model| +|[EEL](emane/eel.md)|RF Pipe|Overview of using the Emulation Event Log (EEL) Generator| + ## EMANE Configuration The CORE configuration file **/etc/core/core.conf** has options specific to diff --git a/docs/emane/eel.md b/docs/emane/eel.md new file mode 100644 index 00000000..ade060da --- /dev/null +++ b/docs/emane/eel.md @@ -0,0 +1,103 @@ +# EMANE Emulation Event Log (EEL) Generator +* Table of Contents +{:toc} + +## Overview +Introduction to using the EMANE event service and eel files to provide events. + +[EMANE Demo 1](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-1) +for more specifics. + +### Run Demo +1. Select `Open...` within the GUI +1. Load `emane-demo-eel.xml` +1. Click ![Start Button](../static/gui/start.gif) +1. After startup completes, double click n1 to bring up the nodes terminal + +## Example Demo +This demo will go over defining an EMANE event service and eel file to drive +an emane event service. + +### Viewing Events +On n1 we will use the EMANE event dump utility to listen to events. +```shell +root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0 +``` + +### Sending Events +On the host machine we will create the following files and start the +EMANE event service targeting the control network. + +> **WARNING:** make sure to set the `eventservicedevice` to the proper control +> network value + +Create `eventservice.xml` with the following contents. +```shell + + + + + + + +``` + +Next we will create the `eelgenerator.xml` file. The EEL Generator is actually +a plugin that loads sentence parsing plugins. The sentence parsing plugins know +how to convert certain sentences, in this case commeffect, location, velocity, +orientation, pathloss and antennaprofile sentences, into their corresponding +emane event equivalents. + +* commeffect:eelloadercommeffect:delta +* location,velocity,orientation:eelloaderlocation:delta +* pathloss:eelloaderpathloss:delta +* antennaprofile:eelloaderantennaprofile:delta + +These configuration items tell the EEL Generator which sentences to map to +which plugin and whether to issue delta or full updates. + +Create `eelgenerator.xml` with the following contents. +```shell + + + + + + + + + + + +``` + +Finally, create `scenario.eel` with the following contents. +```shell +0.0 nem:1 pathloss nem:2,90.0 +0.0 nem:2 pathloss nem:1,90.0 +0.0 nem:1 location gps 40.031075,-74.523518,3.000000 +0.0 nem:2 location gps 40.031165,-74.523412,3.000000 +``` + +Start the EMANE event service using the files created above. +```shell +emaneeventservice eventservice.xml -l 3 +``` + +### Sent Events +If we go back to look at our original terminal we will see the events logged +out to the terminal. + +```shell +root@n1:/tmp/pycore.46777/n1.conf# emaneevent-dump -i ctrl0 +[1601858142.917224] nem: 0 event: 100 len: 66 seq: 1 [Location] + UUID: 0af267be-17d3-4103-9f76-6f697e13bcec + (1, {'latitude': 40.031075, 'altitude': 3.0, 'longitude': -74.823518}) + (2, {'latitude': 40.031165, 'altitude': 3.0, 'longitude': -74.523412}) +[1601858142.917466] nem: 1 event: 101 len: 14 seq: 2 [Pathloss] + UUID: 0af267be-17d3-4103-9f76-6f697e13bcec + (2, {'forward': 90.0, 'reverse': 90.0}) +[1601858142.917889] nem: 2 event: 101 len: 14 seq: 3 [Pathloss] + UUID: 0af267be-17d3-4103-9f76-6f697e13bcec + (1, {'forward': 90.0, 'reverse': 90.0}) +``` diff --git a/docs/emane/files.md b/docs/emane/files.md new file mode 100644 index 00000000..62729ac8 --- /dev/null +++ b/docs/emane/files.md @@ -0,0 +1,160 @@ +# EMANE XML Files +* Table of Contents +{:toc} + +## Overview +Introduction to the XML files generated by CORE used to drive EMANE for +a given node. + +[EMANE Demo 0](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-0) +may provide more helpful details. + +## Run Demo +1. Select `Open...` within the GUI +1. Load `emane-demo-files.xml` +1. Click ![Start Button](../static/gui/start.gif) +1. After startup completes, double click n1 to bring up the nodes terminal + +## Example Demo +We will take a look at the files generated in the example demo provided. In this +case we are running the RF Pipe model. + +### Generated Files + +|Name|Description| +|---|---| +|\-platform.xml|configuration file for the emulator instances| +|\-nem.xml|configuration for creating a NEM| +|\-mac.xml|configuration for defining a NEMs MAC layer| +|\-phy.xml|configuration for defining a NEMs PHY layer| +|\-trans-virtual.xml|configuration when a virtual transport is being used| +|\-trans.xml|configuration when a raw transport is being used| + +### Listing File +Below are the files within n1 after starting the demo session. + +```shell +root@n1:/tmp/pycore.46777/n1.conf# ls +eth0-mac.xml eth0-trans-virtual.xml n1-platform.xml var.log +eth0-nem.xml ipforward.sh quaggaboot.sh var.run +eth0-phy.xml n1-emane.log usr.local.etc.quagga var.run.quagga +``` + +### Platform XML +The root configuration file used to run EMANE for a node is the platform xml file. +In this demo we are looking at `n1-platform.xml`. + +* lists all configuration values set for the platform +* The unique nem id given for each interface that EMANE will create for this node +* The path to the file(s) used for definition for a given nem + +```shell +root@n1:/tmp/pycore.46777/n1.conf# cat n1-platform.xml + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### NEM XML +The nem definition will contain reference to the transport, mac, and phy xml +definitions being used for a given nem. + +```shell +root@n1:/tmp/pycore.46777/n1.conf# cat eth0-nem.xml + + + + + + + +``` + +### MAC XML +MAC layer configuration settings would be found in this file. CORE will write +out all values, even if the value is a default value. + +```shell +root@n1:/tmp/pycore.46777/n1.conf# cat eth0-mac.xml + + + + + + + + + + + + + + +``` + +### PHY XML +PHY layer configuration settings would be found in this file. CORE will write +out all values, even if the value is a default value. + +```shell +root@n1:/tmp/pycore.46777/n1.conf# cat eth0-phy.xml + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Transport XML +```shell +root@n1:/tmp/pycore.46777/n1.conf# cat eth0-trans-virtual.xml + + + + + + +``` diff --git a/docs/emane/gpsd.md b/docs/emane/gpsd.md new file mode 100644 index 00000000..193fba78 --- /dev/null +++ b/docs/emane/gpsd.md @@ -0,0 +1,104 @@ +# EMANE GPSD Integration +* Table of Contents +{:toc} + +## Overview +Introduction to integrating gpsd in CORE with EMANE. + +[EMANE Demo 0](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-0) +may provide more helpful details. + +> **WARNING:** requires installation of [gpsd](https://gpsd.gitlab.io/gpsd/index.html) + +## Run Demo +1. Select `Open...` within the GUI +1. Load `emane-demo-gpsd.xml` +1. Click ![Start Button](../static/gui/start.gif) +1. After startup completes, double click n1 to bring up the nodes terminal + +## Example Demo +This section will cover how to run a gpsd location agent within EMANE, that will +write out locations to a pseudo terminal file. That file can be read in by the +gpsd server and make EMANE location events available to gpsd clients. + +### EMANE GPSD Event Daemon +First create an `eventdaemon.xml` file on n1 with the following contents. +```shell + + + + + + + +``` + +Then create the `gpsdlocationagent.xml` file on n1 with the following contents. +```shell + + + + + +``` + +Start the EMANE event agent. This will facilitate feeding location events +out to a pseudo terminal file defined above. +```shell +emaneeventd eventdaemon.xml -r -d -l 3 -f emaneeventd.log +``` + +Start gpsd, reading in the pseudo terminal file. +```shell +gpsd -G -n -b $(cat gps.pty) +``` + +### EMANE EEL Event Daemon + +EEL Events will be played out from the actual host machine over the designated +control network interface. Create the following files in the same directory +somewhere on your host. + +Create `eventservice.xml` on the host machine with the following contents. + +> **NOTE:** make sure the below eventservicedevice matches the control network +> device being used on the host for EMANE + +```shell + + + + + + + +``` + +Create `eelgenerator.xml` on the host machine with the following contents. +```shell + + + + + + + + + + + +``` + +Create `scenario.eel` file with the following contents. +```shell +0.0 nem:1 location gps 40.031075,-74.523518,3.000000 +0.0 nem:2 location gps 40.031165,-74.523412,3.000000 +``` + +Start the EEL event service, which will send the events defined in the file above +over the control network to all EMANE nodes. These location events will be received +and provided to gpsd. This allow gpsd client to connect to and get gps locations. +```shell +emaneeventservice eventservice.xml -l 3 +``` + diff --git a/docs/emane/precomputed.md b/docs/emane/precomputed.md new file mode 100644 index 00000000..a8f89769 --- /dev/null +++ b/docs/emane/precomputed.md @@ -0,0 +1,80 @@ +# EMANE Procomputed +* Table of Contents +{:toc} + +## Overview +Introduction to using the precomputed propagation model. + +[EMANE Demo 1](https://github.com/adjacentlink/emane-tutorial/wiki/Demonstration-1) +for more specifics. + +### Run Demo +1. Select `Open...` within the GUI +1. Load `emane-demo-precomputed.xml` +1. Click ![Start Button](../static/gui/start.gif) +1. After startup completes, double click n1 to bring up the nodes terminal + +## Example Demo +This demo is uing the RF Pipe model witht he propagation model set to +precomputed. + +### Failed Pings +Due to using precomputed and having not sent any pathloss events, the nodes +cannot ping eachother yet. + +Open a terminal on n1. +```shell +root@n1:/tmp/pycore.46777/n1.conf# ping 10.0.0.2 +connect: Network is unreachable +``` + +### EMANE Shell +You can leverage `emanesh` to investigate why packets are being dropped. +```shell +root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy BroadcastPacketDropTable0 UnicastPacketDropTable0 +nem 1 phy BroadcastPacketDropTable0 +| NEM | Out-of-Band | Rx Sensitivity | Propagation Model | Gain Location | Gain Horizon | Gain Profile | Not FOI | Spectrum Clamp | Fade Location | Fade Algorithm | Fade Select | +| 2 | 0 | 0 | 169 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | + +nem 1 phy UnicastPacketDropTable0 +| NEM | Out-of-Band | Rx Sensitivity | Propagation Model | Gain Location | Gain Horizon | Gain Profile | Not FOI | Spectrum Clamp | Fade Location | Fade Algorithm | Fade Select | +``` + +In the example above we can see that the reason packets are being dropped is due to +the propogation model and that is because we have not issued any pathloss events. +You can run another command to validate if you have received any pathloss events. +```shell +root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable +nem 1 phy PathlossEventInfoTable +| NEM | Forward Pathloss | Reverse Pathloss | +``` + +### Pathloss Events +On the host we will send pathloss events from all nems to all other nems. + +> **NOTE:** make sure properly specify the right control network device + +```shell +emaneevent-pathloss 1:2 90 -i +``` + +Now if we check for pathloss events on n2 we will see what was just sent above. +```shell +root@n1:/tmp/pycore.46777/n1.conf# emanesh localhost get table nems phy PathlossEventInfoTable +nem 1 phy PathlossEventInfoTable +| NEM | Forward Pathloss | Reverse Pathloss | +| 2 | 90.0 | 90.0 +``` + +You should also now be able to ping n1 from n2. +```shell +root@n1:/tmp/pycore.46777/n1.conf# ping -c 3 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=64 time=3.06 ms +64 bytes from 10.0.0.2: icmp_seq=2 ttl=64 time=2.12 ms +64 bytes from 10.0.0.2: icmp_seq=3 ttl=64 time=1.99 ms + +--- 10.0.0.2 ping statistics --- +3 packets transmitted, 3 received, 0% packet loss, time 2001ms +rtt min/avg/max/mdev = 1.991/2.393/3.062/0.479 ms +```