diff --git a/src/point-to-point-layout/doc/point-to-point-dumbbell.rst b/src/point-to-point-layout/doc/point-to-point-dumbbell.rst new file mode 100644 index 000000000..5645109f1 --- /dev/null +++ b/src/point-to-point-layout/doc/point-to-point-dumbbell.rst @@ -0,0 +1,166 @@ +.. include:: replace.txt +.. highlight:: cpp + +Point to Point Dumbbell Topology Helper +--------------------------------------- + +This is an introduction to dumbbell topology helper to complement the +``PointToPointDumbbellHelper`` doxygen. + +Model Description +***************** + +The |ns3| :cpp:class:`PointToPointDumbbellHelper` class is used to create nodes, add +point-to-point connections between them and position them in a dumbbell type +layout. It provides several functions that give complete control over the node +creation, IPv4/IPv6 address assignment and node positioning (defining bounding +box). + +It accepts the number of leaf nodes that are to be created on the left, number +of leaf nodes to be created on the right, and the ``PointToPointHelper`` +objects for the left side, right side and router nodes. These +``PointToPointHelper`` objects define Device and Channel attributes for the +nodes in the respective ``NodeContainer`` for left, right and router nodes. It +then connects all the left leaf nodes to the left router and all the right +leaf nodes to the right router. Thus, all the left leaf nodes are connected +to the left router, which is connected to the right router, and the right +router is connected to all the right leaf nodes. + +It provides a feature to position the nodes in a dumbbell type layout to help +visualize the topology. This is achieved through a function called +``BoundingBox`` which requires coordinate limits as parameters, and then +positions all the nodes within the limits specified to it in a dumbbell layout +which is described later in this documentation. + +It also provides a function ``InstallStack`` which takes a +``InternetStackHelper`` object for installing the ``InternetStack`` on the +nodes, function ``AssignIpv4Addresses`` which takes ``Ipv4AddressHelper`` +objects for the left, right and router nodes for assigning IPv4 address to +each node. It provides a function ``AssignIpv6Addresses`` which takes a +``Ipv6Address`` address base and a ``Ipv6Prefix`` prefix for assigning +IPv6Adddress to every node. + +Node Positioning +================ + +The algorithm used by the ``BoundingBox`` function to position the leaf nodes +and router nodes uses properties of a circle to correctly place the nodes even +when the user specified coordinate constraints are not enough to place nodes +accurately. + +It accepts the minimum upper left X-axis coordinate, minimum upper left Y-axis +coordinate, maximum lower right X-axis coordinate and maximum lower right Y- +axis coordinate. These limits are used by the algorithm to position the nodes +in a dumbbell type layout. It automatically adjusts the nodes according to the +parameters passed to it, and if the parameters specified are too less than +required, it positions them in a straight line. + +This feature is useful if the user wants to visualize the topology using any +supported visualization tool such as PyViz or NetAnim. + +Using PointToPointDumbbellHelper +================================ + +A dumbbell topology with point-to-point links can be configured by using the +``PointToPointDumbbellHelper``. The first task is to create two +``PointToPointHelper`` objects: one for the leaf nodes and the other for the +router nodes as shown below:: + + PointToPointHelper p2pLeaf; + p2pLeaf.SetDeviceAttribute ("DataRate", StringValue ("10Mbps")); + p2pLeaf.SetChannelAttribute ("Delay", StringValue ("2ms")); + + PointToPointHelper p2pRouter; + p2pRouter.SetDeviceAttribute ("DataRate", StringValue ("5Mbps")); + p2pRouter.SetChannelAttribute ("Delay", StringValue ("10ms")); + +After creating the ``PointToPointHelper`` objects, we need to instantiate the +``PointToPointDumbbellHelper``:: + + PointToPointDumbbellHelper dumbbell (nLeftLeaf, p2pLeaf, nRightLeaf, + p2pLeaf, p2pRouter); + +It is also possible to create two separate ``PointToPointHelper`` objects for +left leaf nodes and right leaf nodes. In this case, a total of three +``PointToPointHelper`` objects should be created: one for the left leaf nodes, +one for right leaf nodes and one for the router nodes as shown below:: + + PointToPointHelper p2pLeft; + p2pLeft.SetDeviceAttribute ("DataRate", StringValue ("10Mbps")); + p2pLeft.SetChannelAttribute ("Delay", StringValue ("2ms")); + + PointToPointHelper p2pRight; + p2pRight.SetDeviceAttribute ("DataRate", StringValue ("15Mbps")); + p2pRight.SetChannelAttribute ("Delay", StringValue ("5ms")); + + PointToPointHelper p2pRouter; + p2pRouter.SetDeviceAttribute ("DataRate", StringValue ("5Mbps")); + p2pRouter.SetChannelAttribute ("Delay", StringValue ("10ms")); + +In this case, we instantiate the ``PointToPointDumbbellHelper`` as shown below:: + + PointToPointDumbbellHelper dumbbell (nLeftLeaf, p2pLeft, nRightLeaf, + p2pRight, p2pRouter); + +After this, we can tell the helper to position the nodes in a dumbbell layout. +This is done to improve the visualization of the topology and can be achieved +by calling the ``BoundingBox`` function:: + + // ulx -> Minimum Upper Left X coordinate + // uly -> Minimum Upper Left Y coordinate + // lrx -> Maximum Lower Right X coordinate + // lry -> Maximum Lower Right Y coordinate + dumbbell.BoundingBox (ulx, uly, lrx, lry); + +Next, we need to install an Internet Stack on the nodes. We have to +instantiate a ``InternetStackHelper`` object for this, and pass it as a +parameter to ``InstallStack`` function:: + + InternetStackHelper stack; + dumbbell.InstallStack (stack); + +Subsequently, we have to assign a IPv4/IPv6 address to the nodes as shown +below:: + + // IPv4 + Ipv4AddressHelper leftIp, rightIp, routerIp; + leftIp.SetBase ("10.1.1.0", "255.255.255.0"); + rightIp.SetBase ("10.2.1.0", "255.255.255.0"); + routerIp.SetBase ("10.3.1.0", "255.255.255.0"); + + dumbbell.AssignIpv4Addresses (leftIp, rightIp, routerIp); + +For IPv6 address:: + + // IPv6 + Ipv6Address addrBase ("2001:1::"); + Ipv6Prefix prefix (64) + + dumbbell.AssignIpv6Addresses (addrBase, prefix); + +Example +******* + +The example for this helper is `dumbbell-animation.cc` located in +``src/netanim/examples``. The following command shows the available command- +line options for this example:: + + $ ./waf --run "dumbbell-animation --PrintHelp" + +The following command sets up a dumbbell topology with the default +configuration:: + + $ ./waf --run dumbbell-animation + +The following command sets up a dumbbell topology with 6 left leaf nodes and 9 +right leaf nodes:: + + $ ./waf --run "dumbbell-animation --nLeftLeaf=6 --nRightLeaf=9" + +The following command sets up a dumbbell topology with 10 left leaf nodes and +10 right leaf nodes:: + + $ ./waf --run "dumbbell-animation --nLeaf=10" + +The expected output from the previous commands is a XML file to playback the +animation using NetAnim.