Install the ROS2 environment, see https://github.com/nps-ros2/nps-ros2-examples/wiki/Installing-the-ROS2-Environment.

Install the ns3_testbed repository which contains support scripts and code. For consistency with documentation, we suggest cloning under ~/gits:

mkdir ~/gits
cd gits
git clone https://github.com/nps-ros2/ns3_testbed.git

Developers that have RSA keys installed may prefer to clone using git clone [email protected]:nps-ros2/ns3_testbed.git.

Install the network namespaces and network topology allowing robot network connectivity to be simulated on one machine, see Installing Network Namespaces and Network Topology.

Download and build the ns-3 network simulator, see Installing ns-3.

Build the network simulator programs that flow network data between robots:

cd ~/gits/ns3_testbed/ns3_programs
mkdir build
cd build
cmake ..
make

These programs flow network traffic between robots. The ns3_mobility program flows Wifi traffic between robot nodes based on Wifi simulation parameters such as the specific Wifi protocol, the antenna strength, and the antenna mobility model. The ns3_csma program flows network traffic between robot nodes based on a wired network model.

Configure the robot's antenna mobility model, see Configuring ns-3 behavior.

Build the C++ program that runs the ROS2 robot nodes:

cd ~/gits/ns3_testbed/cpp_testbed_runner
colcon build

This will create program testbed_runner at ~/gits/ns3_testbed/cpp_testbed_runner/build/cpp_testbed_runner/testbed_runner and will also copy some scenario files including example1.csv from ~/gits/ns3_testbed/csv_setup to ~/gits/ns3_testbed/cpp_testbed_runner/build/cpp_testbed_runner.

If you want to design your own robot scenario instead of using the default of example1.csv, see Designing your Robot Scenario.

Start the ns-3 Wifi simulator in its own command window. Select the robot count ([-c <count>]) and range length ([-l <length>]). Start only the number of robots you need. Robots not participating in traffic but in range will receive traffic, which consumes network bandwidth.

cd ~/gits/ns3_testbed/ns3_programs/build
./ns3_mobility [-c <count>] [-l <length>]

The ns3_mobility program captures all network traffic between the various robots for analysis in files named ~/gits/ns3_testbed/ns3_programs/build/ns3_mobility_capture-*.pcap. This capture is more complete than captures you obtain using Wireshark's capture feature because it also includes 802.11 MAC packets which flow below the IP layer. You may open and view these pcap files using Wireshark.

The testbed_runner program starts the robots, each in its own thread and in its own network namespace. For example Robot R1 starts in network namespace nn1. Start the robots from root since root permission is required for running threads within network namespaces. Options are verbose mode ([-v]), to enable pipes ([-p]), to use network namespaces ([-n]), to select your robot count ([-c <count>]), to select the CSV input file ([-i <input setup file>], and to stagger the start time of your robots ([-s]), which will stagger the start times at 88 ms intervals. If using verbose mode, you may wish to direct output to a file. Run testbed_runner in a separate command window.

For example to run 5 nodes in their own network namespace in verbose mode for scenario example_keep_last_5.csv, directing verbose output to file example_out for post processing by the plot_analytics.py tool, type:

sudo /bin/bash
cd ~/gits/ns3_testbed/cpp_testbed_runner/build/cpp_testbed_runner
./testbed_runner -n -v -c 5 -i example_keep_last_5.csv > example_out

Graph latency (captured by running testbed_runner in verbose mode (-v) or captured by the testbed GUI) by running the plot_latency.py program. Specify the input data file ([-i <input file>], the maximum latency value for the graph ([-m <max latency in ms>]), whether to write output to PDF ([-w <filename prefix>]), and the name of the graph (<dataset name>):

cd ~/gits/ns3_testbed/testbed_monitor
./plot_analytics.py <input file> <dataset name> [-m <max latency>] [-b <bar period>] [-w <filename prefix>] <dataset name>

See file https://github.com/nps-ros2/ns3_testbed/blob/master/cpp_testbed_runner/src/testbed_robot_callbacks.cpp tx and rx sections for details about the network metadata logs used for plotting graph latency.

Although not required, it may be useful to start Wireshark to see the real-time network load on the various Tap devices:

sudo wireshark

A testbed monitor GUI is available for showing a table of network flows in real time. It requires that the testbed_runner program be running in pipe (-p) mode in order to receive information about network flows. Start the testbed monitor GUI in its own command window, selecting the filename to output to ([-o <output file>]):

cd  ~/gits/ns3_testbed/testbed_monitor
./testbed_monitor.py [-o <output file>]

Stop the testbed monitor by closing the GUI window and then pressing Ctrl-C in the window it was launched from. It is good to have the testbed monitor running before running the robots because the robots will block if the named Linux pipe, which the testbed GUI drains, fills up. Also, this allows the output file to capture all packets. When working smoothly, latency variance in the GUI table will stabilize and the message index will increment at a consistent rate.