docs/source/helpers.rst

ndnSIM helpers
==============

Helpers are very important components of ndnSIM, especially for writing simulation
scenarios.  The following summarizes helpers and their basic usage.

NDN Stack Helpers
-----------------

:ndnsim:`StackHelper` is used to install ndnSIM network stack on requested nodes, as well
        to provide a simple way configure several important parameters of NDN simulation.

Example:

.. code-block:: c++

        StackHelper ndnHelper;
        NodeContainer nodes;
        ...
        ndnHelper.Install(nodes);

Routing
+++++++

All forwarding strategies require knowledge of where Interests can be forwarded
(Forwarding Information Base).

.. note::
   By default, all nodes have empty FIB.  You need either to manually configure routes,
   use global routing controller, or (not recommended) enable default routes.

Manually routes (FIB Helper)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :ndnsim:`FIB helper <FibHelper>` interacts with the FIB manager of NFD by sending
special Interest commands to the manager in order to add/remove a next hop from FIB
entries or add routes to the FIB manually (manual configuration of FIB).

Adding a route to the FIB manually:

    .. code-block:: c++

       Ptr<Node> node = ...     // some node
       std::string prefix = ... // some prefix
       Ptr<ndn::Face> face = ... // NDN face that belongs to the node and through which prefix is accessible
       int32_t metric = ...     // some routing metric
       FibHelper::AddRoute(node, prefix, face, metric);

:ndnsim:`FIB helper <FibHelper>` has few other AddRoute overloads that may be easier to
        use.  For example, when setting up manual routes between nodes connected with
        PointToPointNetDevice's, it is simpler to use the overload that accepts two nodes
        (face will be automatically determined by the helper).

.. @todo Implement RemoveRoute and add documentation about it

..
   Adding a next hop to a FIB entry (if any) that matches a given name prefix for a topology node:

       .. code-block:: c++

          Ptr<Node> node = .. // Get the desired node
          FibHelper::AddRoute(parameters, node);

..
   Removing a next hop from a FIB entry (if any) that matches a given name prefix for a topology node:

       .. code-block:: c++

          Ptr<Node> node = // Get the desired node
          nfd::ControlParameters parameters;
          parameters.setName(prefix);
          FibHelper::RemoveNextHop(parameters, node);


Automatic Shortest Path Routes (Global Routing Helper)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To simplify FIB management in large topologies, ndnSIM contains a global routing
controller (:ndnsim:`helper <GlobalRoutingHelper>` and :ndnsim:`special interface
<GlobalRouter>`), similar in spirit to ``Ipv4GlobalRoutingHelper``.

There are several necessary steps, in order to take advantage of the global routing controller:

* install :ndnsim:`special interfaces <GlobalRouter>` on nodes

   .. code-block:: c++

     NodeContainer nodes;
     ...
     GlobalRoutingHelper ndnGlobalRoutingHelper;
     ndnGlobalRoutingHelper.Install(nodes);

* specify which node exports which prefix using :ndnsim:`GlobalRoutingHelper::AddOrigins`

   .. code-block:: c++

     Ptr<Node> producer; // producer node that exports prefix
     std::string prefix; // exported prefix
     ...
     ndnGlobalRoutingHelper.AddOrigins(prefix, producer);

* calculate and install FIBs on every node using :ndnsim:`GlobalRoutingHelper::CalculateRoutes`

   .. code-block:: c++

     GlobalRoutingHelper::CalculateRoutes();

Forwarding Strategy
+++++++++++++++++++

ndnSIM 2.0 exactly like NFD allows different namespaces to be associated with different
forwarding strategies.  By default, the following forwarding strategy configuration is defined:

+--------------------+------------------------------+-----------------------------------------------+
| Namespace          | Strategy                     | Strategy Name                                 |
+====================+==============================+===============================================+
| ``/``              | :nfd:`fw::BestRouteStrategy` | ``/localhost/nfd/strategy/best-route``        |
+--------------------+------------------------------+-----------------------------------------------+
| ``/localhost``     | :nfd:`fw::BroadcastStrategy` | ``/localhost/nfd/strategy/broadcast``         |
+--------------------+------------------------------+-----------------------------------------------+
| ``/localhost/nfd`` | :nfd:`fw::BestRouteStrategy` | ``/localhost/nfd/strategy/best-route``        |
+--------------------+------------------------------+-----------------------------------------------+
| ``/ndn/broadcast`` | :nfd:`fw::BroadcastStrategy` | ``/localhost/nfd/strategy/broadcast``         |
+--------------------+------------------------------+-----------------------------------------------+




The :ndnsim:`Strategy Choice helper <StrategyChoiceHelper>` interacts with the Strategy
Choice manager of NFD by sending special Interest commands to the manager in order to
specify the desired per-name prefix forwarding strategy for one, more or all the nodes of a topology.

This helper should be used as follows:

    .. code-block:: c++

       StrategyChoiceHelper::Install(nodes, prefix, strategyName);

or (for a forwarding strategy to be installed in all the topology nodes):

    .. code-block:: c++

       StrategyChoiceHelper::InstallAll(prefix, strategyName);

Content Store
+++++++++++++

ndnSIM uses NFD's content store implementation, maximum size of which can be controlled using
:ndnsim:`StackHelper::setCsSize()`:

      .. code-block:: c++

         ndnHelper.setCsSize(<max-size-in-packets>);
         ...
         ndnHelper.Install(nodes);

.. note::

    Unless specified in the simulation scenario, default maximum size of the content store is
    100 Data packets.

.. note::

    NFD's content store implementation takes full consideration of Interest selectors, however
    is not yet flexible when it comes to cache replacement policies.  Feature to extend CS
    flexibility is currently in active development (refer to `Issue #2219 on NFD Redmine
    <http://redmine.named-data.net/issues/2219>`_) and for the time being, we have ported the
    old ndnSIM 1.0 content store implementations to the new code base.  These implementations
    feature different cache replacement policies, but have very limited support for Interest
    selectors.  If your scenario relies on proper selector processing, do not use these
    implementations as the simulation results most likely be incorrect.

    To select old content store implementations, use :ndnsim:`SetOldContentStore
    <StackHelper::SetOldContentStore>` StackHelper method:

          .. code-block:: c++

             ndnHelper.SetOldContentStore("<content store implementation>",
                                         ["<optional parameter>", "<optional parameter's value>" [, ...]]);
             ...
             ndnHelper.Install (nodes);

    In simulation scenarios it is possible to select one of :ref:`the existing implementations
    of the content store or implement your own <content store>`.


Application Helper
------------------

:ndnsim:`AppHelper` simplifies task of creating, configuring, and installing ndnSIM
applications.


The basic usage of the :ndnsim:`AppHelper`:

* Create helper for specific applications class:

   .. code-block:: c++

      // Create helper for the consumer generating Interests with constant rate
      AppHelper consumerHelper("ns3::ndn::ConsumerCbr");

* Assign prefix on which application operates (either generating Interests using this name
  or satisfying Interests for this name) using :ndnsim:`AppHelper::SetPrefix`:

   .. code-block:: c++

      consumerHelper.SetPrefix(prefix);

* Assign application-specific attributes using :ndnsim:`AppHelper::SetAttribute`:

   .. code-block:: c++

      // Set frequency parameter
      consumerHelper.SetAttribute("Frequency", StringValue ("10")); // 10 interests a second

* Install application on one or more nodes:

   .. code-block:: c++

      NodeContainer nodes;
      ...
      consumerHelper.Install(nodes)

.. _Link Control Helper:

Link Control Helper
-------------------

Some scenarios require failing certain links between NDN nodes at certain times.  NS-3 does not
provide ability to actually "break" the link between nodes.  However, it provides facility to
set up a loss model to simulate packet drops in the channel.  Using the properly set up loss
model on both sides of the point-to-point link, it is possible to emulate link breakage.

To simplify these operations, ndnSIM includes :ndnsim:`ndn::LinkControlHelper` that allows
scheduling of link failures and failure recoveries:


    .. code-block:: c++

        #include "ns3/ndnSIM/helper/ndn-link-control-helper.hpp"

        ...

        Simulator::Schedule(Seconds(10.0), ndn::LinkControlHelper::FailLink, node1, node2);
        Simulator::Schedule(Seconds(15.0), ndn::LinkControlHelper::UpLink, node1, node2);

Usage of this helper is demonstrated in :ref:`Simple scenario with link failures`.