docs: Adding a new example of how to use AnnotatedTopologyReader, as well as a new FAQ section with a couple of commonly asked questions.
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 5ea290e..d65f4eb 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -1,6 +1,8 @@
Examples
========
+.. _simple-scenario:
+
Simple scenario
---------------
@@ -45,6 +47,10 @@
Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
+ // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
// Creating nodes
NodeContainer nodes;
nodes.Create (3);
@@ -89,6 +95,8 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
+.. _9-node-grid-example:
+
9-node grid example
-------------------
@@ -144,6 +152,10 @@
Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
+ // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
// Creating 3x3 topology
PointToPointHelper p2p;
PointToPointGridHelper grid (3, 3, p2p);
@@ -195,3 +207,125 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid
+.. _9-node-grid-example-using-topology-plugin:
+
+9-node grid example using topology plugin
+-----------------------------------------
+
+Instead of defining topology directly as in :ref:`simple-scenario` or using specialized helpers as in :ref:`9-node-grid-example`, ndnSIM provides experimental extended versions of TopologyReader classes: :ndnsim:`AnnotatedTopologyReader` and :ndnsim:`RocketfuelWeightsReader`.
+
+While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with `Rocketfuel <http://www.cs.washington.edu/research/networking/rocketfuel/>`_ topology and link weights files (examples will be provided later), :ndnsim:`AnnotatedTopologyReader` is a general-use tool that allows creation of any custom topologies.
+The based format for the input file the :ndnsim:`AnnotatedTopologyReader` expects::
+
+ # any empty lines and lines starting with '#' symbol is ignored
+
+ # The file should contain exactly two sections: router and link, each starting with the corresponding keyword
+
+ # router section defines topology nodes and their relative positions (e.g., to use in visualizer)
+ router
+
+ # each line in this section represents one router and should have the following data
+ # node comment yPos xPos
+ Node0 NA 3 1
+ Node1 NA 3 2
+ Node2 NA 3 3
+ Node3 NA 2 1
+ Node4 NA 2 2
+ Node5 NA 2 3
+ Node6 NA 1 1
+ Node7 NA 1 2
+ Node8 NA 1 3
+ # Note that `node` can be any string. It is possible to access to the node by name using Names::Find, see examples.
+
+ # link section defines point-to-point links between nodes and characteristics of these links
+ link
+
+ # Each line should be in the following format (only first two are required, the rest can be omitted)
+ # srcNode dstNode bandwidth metric delay queue
+ # bandwidth: link bandwidth
+ # metric: routing metric
+ # delay: link delay
+ # queue: MaxPackets for transmission queue on the link (both directions)
+ Node0 Node1 1Mbps 1 10ms 10
+ Node0 Node3 1Mbps 1 10ms 10
+ Node1 Node2 1Mbps 1 10ms 10
+ Node1 Node4 1Mbps 1 10ms 10
+ Node2 Node5 1Mbps 1 10ms 10
+ Node3 Node4 1Mbps 1 10ms 10
+ Node3 Node6 1Mbps 1 10ms 10
+ Node4 Node5 1Mbps 1 10ms 10
+ Node4 Node7 1Mbps 1 10ms 10
+ Node5 Node8 1Mbps 1 10ms 10
+ Node6 Node7 1Mbps 1 10ms 10
+ Node7 Node8 1Mbps 1 10ms 10
+
+
+If you save the topology file to `topo.txt` in the current directory, then the following code will duplicate the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`:
+
+.. code-block:: c++
+
+ #include "ns3/core-module.h"
+ #include "ns3/network-module.h"
+ #include "ns3/ndnSIM-module.h"
+
+ using namespace ns3;
+
+ int
+ main (int argc, char *argv[])
+ {
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
+ AnnotatedTopologyReader topologyReader ("", 25);
+ topologyReader.SetFileName ("topo.txt");
+ topologyReader.Read ();
+
+ // Install CCNx stack on all nodes
+ ndn::StackHelper ccnxHelper;
+ ccnxHelper.InstallAll ();
+
+ // Installing global routing interface on all nodes
+ ndn::GlobalRoutingHelper ccnxGlobalRoutingHelper;
+ ccnxGlobalRoutingHelper.InstallAll ();
+
+ // Getting containers for the consumer/producer
+ Ptr<Node> producer = Names::Find<Node> ("Node8");
+ NodeContainer consumerNodes;
+ consumerNodes.Add (Names::Find<Node> ("Node0"));
+
+ // Install CCNx applications
+ std::string prefix = "/prefix";
+
+ ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
+ consumerHelper.SetPrefix (prefix);
+ consumerHelper.SetAttribute ("Frequency", StringValue ("100")); // 100 interests a second
+ consumerHelper.Install (consumerNodes);
+
+ ndn::AppHelper producerHelper ("ns3::ndn::Producer");
+ producerHelper.SetPrefix (prefix);
+ producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
+ producerHelper.Install (producer);
+
+ // Add /prefix origins to ndn::GlobalRouter
+ ccnxGlobalRoutingHelper.AddOrigins (prefix, producer);
+
+ // Calculate and install FIBs
+ ccnxGlobalRoutingHelper.CalculateRoutes ();
+
+ Simulator::Stop (Seconds (20.0));
+
+ Simulator::Run ();
+ Simulator::Destroy ();
+
+ return 0;
+ }
+
+As you can see, scenario code became more compact and more readable.
+
+:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes.
+First, you can use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.
+
+Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in the above example.
+For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers all created nodes with names specified in topology file.
+For more information about `Names` class, please refer to `NS-3 documentation <.. http://www.nsnam.org/doxygen/classns3_1_1_names.html>`_
+.