EMANE

EMANE (Extendable Mobile Ad-hoc Network Emulator) is an open source distributed emulation framework which provides wireless network experimenters with a highly flexible modular environment for use during the design, development and testing of simple and complex network architectures. EMANE uses a physical layer model to account for signal propagation, antenna profile effects and interference sources in order to provide a realistic environment for wireless experimentation. Individual radio model plugins are used to emulate the lowest layers of a waveform and can be combined with existing Software Defined Radio (SDR) implementations to enable shared code emulation.

Visit the EMANE Wiki for information on using and deploying EMANE.

---

Contents

• Emulator Plugins
• Common Component Interfaces
• Emulator Physical Layer
• Developer FAQ

---

Emulator Plugins

EMANE supports 4 types of plugins:

1. Radio Models emulate the lowest layers of a waveform. Functionality typically includes: Channel access protocols (TDMA, CSMA/CA, FDMA, CDMA) and QoS features (Queuing, Acknowledgments, Retries, Fragmentation, Segmentation).
   
   • The EMANE distribution contains three Radio Models:
     • RF Pipe Model
     • IEEE 802.11abg Model
     • TDMA Event Scheduler Model
   • The distribution contains one Utility Model
     • Comm Effect Model
       A Utility Model is not a Radio Model. It uses the features of the emulator to apply effects to traffic without specific notions related to wireless communication.
   • The distribution contains one Hello World Model:
     • Bypass Model
       A simple model that does not do much of anything other than implement all the required plugin methods.
2. Application/Emulation Transport Boundaries manage the messaging between applications running outside the emulator and the emulation stack. Transport boundaries create the entry/exit mechanism used to get IP or non-IP traffic in to and out of the emulator.
   • The EMANE distribution contains two transports:
     • Virtual Transport
     • Raw Transport
3. Event Generators create scenario events that are delivered to NEMs in order change environmental characteristics. Events are delivered opaquely to registered radio model instances so individual radio models may require their own specialized events. Whenever possible we advocate reusing EMANE standard events over creating new events that do the same thing.
   
   • The EMANE distribution contains one event generator:
     • Emulation Event Log (EEL) Generator
       See http://downloads.pf.itd.nrl.navy.mil/docs/mnmtools/EmulationScriptSchemaDescription.pdf
       A generator that creates all of the EMANE distribution events from flat text files:
       • AntennaProfileEvent
       • CommEffectEvent
       • LocationEvent
       • PathlossEvent
4. Event Agents turn EMANE events into usable forms suitable for processing by applications outside of the emulator.
   • The EMANE distribution contains one agent:
     • GPSD Location Agent
       An agent that converts location events into NMEA strings and writes them out to a pseudo terminal to emulate an attached GPS receiver.

---

Common Component Interfaces

Each type of plugin derives from its own specific base class but they all share certain class interfaces that are used to manage plugin life cycles and framework interaction.

• Component Interface used to transition plugin states.
  
• Buildable Interface used to associate a plugin with a unique application instance id.
• Platform Service User Interface used to give a plugin access to general emulator services.
• Running State Mutable Interface used to request running-state configuration changes.

Each plugin has access to general services provided by the emulator.

• Configuration Service used to register plugin configuration items.
• Event Service used to register events of interest and to send events.
• Log Service used to emit log messages.
• Statistic Service used to create numeric and non numeric statistics and statistic tables which are accessible from outside the emulator.
• Timer Service used to schedule timed events.
• File Descriptor Service used to register file descriptors for functor queue servicing.

---

Emulator Physical Layer

The emulator physical layer provides the following functionality:

• Propagation Model Support
  • 2-Ray
  • Freespace
  • Precomputed
• Receive Power Calculation
• Antenna Gain Support
• Noise Processing
• Frequency Diversity
• Collaborative Transmission
• Radio Model Interface Support

Radio Models can access per frequency noise information tracked by the emulator physical layer using the Spectrum Service.

---

Developer FAQ

1. Can you create additional threads inside a Radio Model or Utility Model?
   You can create additional threads but you might want to see if your design can be modified to not require them. All NEM layers are assigned a dedicated functor queue thread. Each of the running-state plugin API messages are converted to a function object and placed on the functor queue of the receiving NEM layer for processing. The receiving NEM layer's functor queue thread works each message off sequentially, preserving the API message order. You can get a lot of miles out of using the functor queue in conjunction with the TimerService for delayed processing, including not needing synchronization objects since the functor queue is single threaded.
   The following methods are enqueued on the functor queue for processing:
   • processEvent
   • processDownstreamPacket
   • processDownstreamControl
   • processConfiguration
   • processTimedEvent
   • processUpstreamPacket
   • processUpstreamControl
2. Why should you not block in processEvent, processDownstreamPacket, processDownstreamControl, processConfiguration, processTimedEvent, processUpstreamPacket and processUpstreamControl?
   Since those calls are serially executed by the NEM layer's functor queue, blocking will delay your ability to handle the next message. Instead you should look at using the Timer Service.
3. Should you use the emulator physical layer when developing your own radio model?
   Yes. While it is possible to write your own physical layer plugin, it is strongly discouraged. The emulator physical layer provides features that are required by most wireless radio models and will significantly reduce your development and test cycles. In addition, it minimizes compatibility issues with current and future versions of EMANE. If your radio model requires features within the emulator physical layer that are not currently supported, feel free to contact us to discuss potential short and long term implementation solutions.
4. Should you use the VirtualTransport or the RawTransport when building a shared code radio model for use with the upper layers of a Software Defined Radio (SDR)?
   No, you should not use either. When connecting SDR waveforms to EMANE, custom transports should be developed and embedded within the SDR at the Modem Hardware Abstraction Layer (MHAL). EMANE provides application level APIs to make developing a custom transport very easy. If you are using either the VirtualTransport or the RawTransport to simply pass messages between your radio model plugin and your SDR code, you are doing something wrong. See TransportBuilder for details, below is sample code for embedding a transport in your own application using libemane.
   

   #include <emane/application/logger.h>
   #include <emane/application/transportbuilder.h>
   
   ...
   
   // create and EMANE logger and set the initial level
   EMANE::Application::Logger logger;
      
   logger.setLogLevel(EMANE::DEBUG_LEVEL);
       
   // create a transport builder
   EMANE::Application::TransportBuilder transportBuilder;
       
   // build YOUR transport along with an adapter
   auto items =
     transportBuilder.buildTransportWithAdapter<MyWaveform::Transport>(id, // nem id
          {{"yourconfigparamname",{"yourconfigparamvalue"}}}, //ConfigurationUpdateRequest
          "localhost:8181", // platform endpoint
          "localhost:8281"); // transport endpoint
   
   // store a borrowed reference to YOUR transport instance for your use
   MyWaveform::Transport * pTransport{std::get<0>(items)};
   
   EMANE::Application::TransportAdapters adapters{};
   
   // move ownership of the TransportAdapter
   adapters.push_back(std::move(std::get<1>(items)));
       
   // create application instance UUID 
   uuid_t uuid;
   uuid_generate(uuid);
   
   // create the transport manager and initialize with an empty EMANE::ConfigurationUpdateRequest
   // ownership of adapters transfered to the TransportManager
   auto pTransportManager = 
      transportBuilder.buildTransportManager(uuid,adapters,{});
       
   // start the adapter and transport
   pTransportManager->start();
       
   // post-start the adapter and transport
   pTransportManager->postStart();
   
   ... all the real work
   
   // stop the adapter and transport
   pTransportManager->stop();
       
   // destroy the adapter and transport
   pTransportManager->destroy();

5. Why must StatisticNumeric, StatisticNonNumeric and StatisticTable component members be pointers?
   Statistics and statistic tables are owned by the emulator infrastructure. You declare members to be pointers to the appropriate statistic type and then in your component's initialize method you must register each statistic and statistic table using the StatisticRegistrar. The registration methods will return a borrowed reference (you don't own it, you don't clean it up) to your statistic or statistic table. See Statistic Service for details.
6. Does the duration of a DownstreamPacket need to hold true to the payload length and datarate?
   No, you can set packet duration to whatever makes sense. The emulator physical layer is not aware of the datarate. If desired, you can add metadata to DownstreamPackets but maintain the duration dictated by the radio model channel access protocol (i.e. RTS/CTS etc.). See Radio Model Interfacing for more information.