Two modes of operation are available for running OpenAirInterface
software in radio emulation mode: Linux User Mode environment and Linux Real Time environment (RTAI). The first can provide real-time behaviour on-average
, in the sense that radio frame timing is respected on a long-term basis. The second is almost real-time since the protocol stack runs under RTAI with strict frame timinig. Small deviations can be expected if the emulated network is set up using ethernet as an emulation medium since L2 traffic transits Linux user-space. Single-machine based emulation is strictly real-time.
The user-mode simulation is used primarily for development and testing purposes, specifically when new code is to be tested and integrated with the entire protocol stack. Any instabilities in the L2 protocol stack have an effect on user-space and thus do not corrupt the kernel. The network device, however, is still part of the kernel, so be careful if modifications are made to it.
Setting up your environment
You must define some environment variable to compile and run the emulation platform, add the following to the appropriate startup scripts (.bashrc or .bash_profile, etc.)
# export OPENAIR2_DIR=place you put openair2
# export OPENAIR3_DIR=place you put openair3
We suggest you create a directory openair which has openair2 and openair3 as sub-directories. openair1 too if you downloaded it, but you don't need it for emulation. These have to be defined as above for the compilation/execution to work properly.
USER MODE SIMULATION
A user-mode simulation consists of one L2 process in Linux user-space comprising several instances of the protocol stack. It can operate with or whithout the Linux IP stack, which is virtualized if more than one node instance is running on the same physical machine (i.e. without ethernet communication). Several nodes may run on one machine through virtualization of L2 protocols and networking device.
A good place to start is the EXAMPLES directory in "openair2".
You just "cd" to the EXAMPLES directory like
# cd $OPENAIR2_DIR/EXAMPLES
and choose one of the examples (say VIRTUAL_EMUL_3_NODES_IPv4) which is a virtual network of one clusterhead (basestation) and 3 terminals using IPv4 as a traffic stimulus. You should try to make this work. Go to the directory and do:
make user (or make userclean)
Compiling (see the Makefiles in the EXAMPLE directories)
From openair2 compile the user-space simulation as
# make mac_sim
To compile nasmesh.ko with netlink support see OpenAirRTCompilation.
You must compile it either with address translation (if running on a single machine) or with netlink support only, if distributed on several machines.
Running (see the start_xxx scripts in the EXAMPLES directory)
The syntax for running the software is the following:
# ./mac_sim machine_id
- Machine_id is the Id of the current PC where we are lanching the simulation (between 0 & 7)
NB: When running the simulation on more than one machine, you must start the machine with Id 0 first. Once the last machine has started
NB2: Multicast support must be enable in the kernel and a route must be active : do a
# route add -net 126.96.36.199 netmask 240.0.0.0 dev ethX)
where ethX is the ethernet device you are using to interconnect the emulated nodes. It may be worth using machines with a second interface to dedicate traffic for the L2 emulation.
Example Topology File
The simulation environment reads a topology file in SIMULATION/openair_topology.top
. An example is the following for 3 nodes on 3 separate machines:
00 08 09
000010 023162 023162
023162 000010 000010
023162 000010 000010
The field Nb_nodes
indicates the number of nodes in the network. Nodes_list
gives the id's of the nodes (0-7 represent clusterheads, 8-255 represent regular nodes). Rssi_matrix_entries
gives the pairwise average RSSI between nodes in the network on a linear scale (i.e. a larger number means a better signal). Nb_machines
is the number of machines over which the simulation is carried out (for one node per machine Nb_nodes
precedes the node list attached to the machine which is indicated by Nb_inst
which first indicates the number of instances on the machine and Inst_list
are the node id's for each instance.
REAL TIME MODE SIMULATION
Compiling & Running:
Compile the openair_emul.ko and openair_l2.ko and nasmesh.ko (either with or without address translation depending on your scenario) as described in OpenAirRTCompilation
. Two addtional user-space module is required when the network is used a transport medium (i.e. more than one machine in a simulation), "bypass_phy" which controls MAC Pdus exchange between the PCs of the simulation. To compile it from the top openair2 directory type:
# make clean; make bypass_phy
The other is rt_emul, which is an IOCTL interface to invoke the layer 2 process scheduler and emulation medium. It is compiled as
# cd SIMULATION/USER_TOOLS/RT_EMUL_LAUNCHER
Running the simulation is done via rt_emul
. It takes one argument (0-2). 0 configures the simulation by reading the openair_topology.top file (see above) and the PHY configuration files ( openair_config.cfg, openair_scenario.scn convariance_matrix.dat
). The PHY configuration files are found in SIMULATION
directory. You should not need to change them at this point.
NB: When running the simulation on more than one machine, you must start the machine with Id 0 first, since it acts as a timing-synchronization reference for the simulation.