[[TOC(Software/eAM*, depth=2, heading=Aggregate Managers)]]

== METIS II 5G Visualization - Trace Extension ==

TODO Intro...

[[BR]]
=== Adding the Trace Extension code to METIS II 5G Visualization source ===

The following documentation gives an overview of the changes that have to be made to the original METIS II simulator for it to have the ability to generate pairwise attenuation traces for selected objects in the simulator.

 1.	Adding an empty object to the scene:
  a.	Under the Hierarchy tab, select the ‘Stage’ object, right click on it and choose ‘Create Empty’.
  b.	Rename it to Tracker and under the Inspector tab of Unity, click Add Component button.
  c.	Select Scripts and add the [attachment:TrackObject_Test.cs TrackObject_Test.cs] file
  d.	Alternatively, add a new script and paste the code from Track Object_Test.cs after renaming the class Track Object_Test to whatever name was given to the script.

 2.	Adding tags to !GameObjects:
  a.	Under the project tab, search for the object Antenna5G_01
  b.	In the inspector tab, click on the Tag dropdown and choose ‘Add Tag..’.
  c.	In the Tags and Layers window, inside the Inspector tab, click on ‘+’ and add the tag “Antenna”.
  d.	Now, select Antenna5G_01 from the Project tab and the tag ‘Antenna’ should be available. Click on Antenna to add that tag to the !GameObject.
  e.	Repeat the same steps for the following objects
   i.	Person, !StaticPerson – Pedestrian
   ii.	!MadridGrid, MadridGridRectangle8, MadridGridRectangle10, !MadridGridSquare – Building
   iii.	Sensor – Sensor
   iv.	lamp-single-ap-002 – Lightpole
   v.	CarSedan01 – Car
   vi.	Bus – Bus

 3.	Adding Collider to !GameObjects:
  a.	For getting a list of the objects the ray hits between the source and the destination object, it is necessary to add Box Colliders to each of the objects that the ray might pass through.
  b.	For the models !MadridGrid, MadridGridRectangle8, MadridGridRectangle10, Person, !StaticPerson and Sensor, add Box Collider components 
  c.	For adding it, select the model from the Project tab and in the Inspector tab, select !AddComponent -> Physics -> Box Collider.

 4.	Generating a build:
  a.	Once all of the above has been done, generate a build by selecting File -> Build Settings
  b.	Choose the Target Platform, Architecture and hit Build.
  c.	Make sure that the config file “config.xml” is located in the running directory. In its absence, the simulator runs normally.

[[BR]]
=== XML Configuration File ===

Sample XML configuration: [attachment:config.xml config.xml]

Below is a brief overview of the different sections of the XML config file and how they function. The above sample file is used for reference.

{{{
<?xml version="1.0" encoding="utf-8"?>
<config>
<links>
    <link name="1" default_attn="9999" max_obj="9" />
    <link name="2" default_attn="9999" max_obj="5" />
</links>
}}}
 
'''<links> ... </links>'''

The links section defines how many independent sets of connections objects in the simulator may have (eg. multi-homing). It can be thought of in terms of [wiki:foo Sandbox 4] as the number of available attenuator matrices. Each matrix (ie. each link set) is independent of the other. The default attenuation (dB) per matrix (link set) is defined in this section and used in cases where maximum attenuation is calculated between a pair of objects or an object pair is not defined. The maximum number of objects per matrix (link set) is also defined here for proper formatting of the generated trace file.

{{{
<objects>
    <object name="1" type="Car" id="12">
      <link name="1">2,3</link>
      <link name="2">3,4</link>
    </object>
    <object name="2" type="Bus" id="4">
      <link name="1">5,6</link>
      <link name="2">3,5</link>
    </object>

...

</objects>
}}}

'''<objects> ... </objects>'''

This section defines the objects that the user wishes to track (and generate trace data for). The object "name" is a number used to map the object to the corresponding trace output values. In the case of Sandbox 4... The "type" determines the subset of objects to which the object of interest belongs and the "id" corresponds to the specific object in that subset.

  ||='''Object Type'''=||= '''Valid Id''' =||
  ||  Building  || ''none'' ||
  ||  Car  || 0 - 404 ||
  ||  Bus  || 0 - 5 ||
  ||  Pedestrian  || 0 - 115 ||
  ||  Microcell  || 0 - 5 ||
  ||  Macrocell  || 0 - 3 ||
  ||  Sensor  || 0 - 9 ||

{{{
  <attenuations>
    <attn factor="3" type="Bus" />
    <attn factor="2" type="Car" />
    <attn factor="1" type="Building" />
    <attn factor="2" type="Pedestrian" />
    <attn factor="6" type="Antenna" />
  </attenuations>
  <sim_parameters max_time="180" time_int="1000" frequency = "100"/>
</config>
}}}

'''<attenuations> ... </attenuations>'''

Path loss attenuations of different objects in the simulation are defined here. These are the attenuations of objects obstructing line of sight between the two objects for which the pairwise attenuation is being calculated. These factors are not taken into account for the pair of objects themselves.

 ||= '''Type''' =||='''Description''' =||
 ||  Bus  || Path loss attenuation of a bus ||
 ||  Car  || Path loss attenuation of a car ||
 ||  Building  || Path loss attenuation of a building ||
 ||  Pedestrian  || Path loss attenuation of a pedestrian ||
 ||  Antenna  || Path loss attenuation of a rooftop antenna ||

'''<sim_parameters> ... </sim_parameters>'''

This section contains additional trace related simulation parameters.

 ||='''Parameter'''=||='''Description''' =||
 ||  max_time  || Number of seconds to run the simulation ||
 ||  time_int  || Number of miliseconds between calculating pairwise attenuations ||
 ||  frequency  || Frequency (in MHz) to use as a baseline for attenuation calculations ||

[[BR]]
=== Trace Output CSV File ===

The output trace file generated at the end of a simulation run is formatted in accordance with the requirements of the [wiki:/Software/eAM/mInstr Instrumentation AM] service for trace replay.