Document function to load gazebo world parameters from XML to code

[hamishwillee]

https://github.com/PX4/sitl_gazebo/pull/167 introduces a function that uses tinyxml to parse parameters on XML files into C++ usable variables. This is used in the multi-vehicle simulation to allow a single sdf model file (with basic model options and parameters) for all cloned instances of a model, but with differentiate properties (such as udp ports) for individual model instances.

This needs to be documented so that it can be reused as needed:

• Why is it needed
• When and why should it be used.
• How it works

Information should be in (or below) the Gazebo doc

[korotkoves]

@hamishwillee please review this text for errors (grammar and others). May be you add it to Devguide more properly than I can.

Simplified signature: model_param(WORLD_NAME, MODEL_NAME, PARAM, PARAM_VALUE)

Function uses tinyxml library to parse model parameters from XML file into C++ usable variables. Can be used in any plugin inside sitl_gazebo.

It tries to open WORLD_NAME.xml in current path (where we execute Gazebo) and iterates xml tags. If it see tag with "name" attribute (parameters for model with that name) or tag without it (parameters for all models) it searches tag inside and copy it's value to PARAM_VALUE variable.

It is usefull, if we have single sdf model file (with basic model options and parameters) for one or more model instances but want to get (or change) some options/parameters for all or some model instances without sdf file modification.

Multi vehicle simulation project(https://github.com/acsl-mipt/multiple-sitl/tree/for-px4-pr), for example, uses it to set different udp ports for individual quadcopter model instance.

For self world and model name, mavlink_udp_port option and mavlink_udpport variable with int type: model_param(world_->GetName(), model_->GetName(), "mavlink_udp_port", mavlink_udp_port_);

Options file for 3 iris quadcopters:

<?xml version="1.0" ?>
<options>
  <model name="iris1"><mavlink_udp_port>15019</mavlink_udp_port></model>
  <model name="iris2"><mavlink_udp_port>15029</mavlink_udp_port></model>
  <model name="iris3"><mavlink_udp_port>15039</mavlink_udp_port></model>
</options>

[hamishwillee]

@korotkoves Excellent job - all the information needed there. I'll tidy it as needed when I'm back from my break.

[julianoes]

Note that after this PR building gazebo requires the tinyxml dependency. That will need to be added to the docs too.