A small tutorial to yans

Get yans source code and build it

Obviously, you need to get a copy of the yans simulator. Its latest released version is available from its website but you can also get the developement version from our mercurial repository. This repository can be browsed with a simple web browser (in case you want to simply monitor the status of the development) from the following url.

Once you have gotten a copy of the yans source code, you need to build it. Build instructions are located in the README. Basically, it is a matter of running the make command: the first time you run it, the Makefile will attempt to detect your system's configuration and will store it in the config.mk file which you can then edit in case something went wrong.

Once the build is complete, you should have:

The source tree

The yans source tree is organized in a very classic way: the code used to build the yans library is located under the src directory while the samples directory contains various sample scenarios which you can use as a starting point for your own simulation scenarios. The src directory contains:

The sample directory contains numerous scenarios. The simplest scenario simulates a pair of ipv4 hosts connected together through a duplex ethernet link and exchanging udp packets in one direction only. This scenario is located in the samples/main-simple.cc file.

The simple sample scenario

The scenario starts by creating the ethernet network interfaces which are connected together with en ethernet cable. Each interface must be given a mac address:

	/* setup the ethernet network itself. */
	EthernetNetworkInterface *eth_client, *eth_server;
	eth_client = new EthernetNetworkInterface ("eth0");
	eth_server = new EthernetNetworkInterface ("eth0");
	eth_client->set_mac_address (MacAddress ("00:00:00:00:00:01"));
	eth_server->set_mac_address (MacAddress ("00:00:00:00:00:02"));
	Cable *cable = new Cable ();
	cable->connect_to (eth_client, eth_server);
Then, each interface is given an ipv4 address and subnet mask:
	/* associate ipv4 addresses to the ethernet network elements */
	eth_client->set_ipv4_address (Ipv4Address ("192.168.0.3"));
	eth_client->set_ipv4_mask (Ipv4Mask ("255.255.255.0"));
	eth_server->set_ipv4_address (Ipv4Address ("192.168.0.2"));
	eth_server->set_ipv4_mask (Ipv4Mask ("255.255.255.0"));
	eth_client->set_up ();
	eth_server->set_up ();
The network nodes are created and connected to the ethernet network interfaces:
	/* create hosts for the network elements*/
	Host *hclient, *hserver;
	hclient = new Host ("client");
	hserver = new Host ("server");
	hclient->add_interface (eth_client);
	hserver->add_interface (eth_server);
Since we have no routing protocol running on these nodes, we must configure the node's routing tables statically:
	/* setup the routing tables. */
	hclient->get_routing_table ()->set_default_route (Ipv4Address ("192.168.0.2"),
							  eth_client);
	hserver->get_routing_table ()->set_default_route (Ipv4Address ("192.168.0.3"),
							  eth_server);
We create a pair of Udp source and sink objects which interface with a host's udp/ipv4 stack:
	/* create udp source endpoint. */
	UdpSource *source = new UdpSource (hclient);
	source->bind (Ipv4Address ("192.168.0.3"), 1025);
	source->set_peer (Ipv4Address ("192.168.0.2"), 1026);
	source->unbind_at (11.0);
	/* create udp sink endpoint. */
	UdpSink *sink = new UdpSink (hserver);
	sink->bind (Ipv4Address ("192.168.0.2"), 1026);
	sink->unbind_at (11.0);
Then, a traffic generator is connected to the udp source:
	PeriodicGenerator *generator = new PeriodicGenerator ();
	generator->set_packet_interval (0.01);
	generator->set_packet_size (100);
	generator->start_at (1.0);
	generator->stop_at (500.0);
	generator->set_send_callback (make_callback (&UdpSource::send, source));
And a traffic analyzer is connected to the udp sink:
	TrafficAnalyser *analyser = new TrafficAnalyser ();
	sink->set_receive_callback (make_callback (&TrafficAnalyser::receive, analyser));
At this point, the simulation is ready to run:
	/* run simulation */
	Simulator::run ();
When Simulator::run returns, the simulation is completed so we ask the traffic analyzer to print a bunch of statistics on the arrival pattern of the packets:
	analyser->print_stats ();
Finally, because we like to clean up correctly the memory after us, we must destroy all the objects we created and ensure the simulation's memory is freed:
	/* destroy network */
	delete eth_client;
	delete eth_server;
	delete cable;
	delete source;
	delete generator;
	delete sink;
	delete analyser;
	delete hclient;
	delete hserver;
	[...]
	Simulator::destroy ();

This sample scenario was built during the build of the yans library and was installed as build-dir/bin/main-simple.

Conclusion

This tour of the simple scenario highlights a few important aspects of yans: