Additional configuration file features

This page assumes you are familiar with the basics of a configuration file, as described for instance in the first tutorial

Necessary task parameters

Each task must provide values for the parameters Enabled and Entity Label. The Enabled parameter describes when this particular task is enabled (that is, will actually run). Entity Label assigns the task a human readable name. This name is also used within the dune framework in various situations, e.g. to identify the source of an incoming IMC message.

# This task will be active in the Simulation and Hardware profile
[SimulationSupervisor]
Enabled      = Always
Entity Label = Simulation Supervisor

Enabled can either be set to Never, Always or to a profile like Simulation or Hardware. It can also be set to several profiles, see next example.

Task path/naming convention

The task is identified from the path/name given in the brackets. The path is written with a period (".") to separate subfolders. For instance, to start a task located in src/Control/AUV/Attitude, use

[Control.AUV.Attitude]
Enabled      = Always
Entity Label = AUV Attitude Controller

Including sub-configuration files

For practical reasons, it can be beneficial to divide one large configuration file into several smaller ones. Each small file can contain information about a task belonging to a logical group like Transports or Simulations. To include such sub-files, use

[Require auv/basic.ini]
# or
[Include auv/basic.ini]

The difference between the two is that a failure to find the described file will terminate the program when using Require, while Include will simply print a warning. Use the latter with caution.

For inspiration, see how the configuration file lauv-seacon-1.ini requires several sub-files (which again can include other configuration files).

Defining vehicle name

The name of the vehicle is defined under the pseudo-task [General]. This section must be included for communication with neptus or other vehicles. For instance:

[General]
Vehicle = lauv-seacon-1

The IMC address

The vehicle name supplied is used to find the vehicles IMC address. For this to work, the configuration file common/imc-addresses.ini must always be included. This is typically done within a basis-file for your vehicle group (see for instance auv/basic.ini).

Profiles

A profile is a way to start your set of tasks with different configuration dependent on the situation. The profiles Simulation and Hardware are always available. For instance, when a UAV is started with the Hardware profile, it expects to be able to connect to a physical autopilot over a serial connection. But, if started in Simulation, it can be configured to connect to a local autopilot instance on the host.

Multiple instances of the same task

Instances of the same task (that may or may not run simultaneously) is distinguished by the name given after a / in the task specification. Consider the (not very realistic) example

[MyController/default]
Enabled      = Always
Entity Label = Default Controller

[MyController/redundant]
Enabled      = Hardware
Entity Label = A redundant controller

When using the Hardware profile, two instances of the task MyController is started. In any other profile, only the task named MyController/default is run.

Creating custom profiles

Sometimes, it might be useful to create additional profiles other than the default Simulation and Hardware profiles. This can easily be done in a configuration file like this:

myConfig.ini:

[Profiles]
SimulationRC = Special simulation mode where some hardware are used for user input

[RCInput]
Enabled      = SimulationRC
Entity Label = RC user input

Dune can now be started with ./dune -c myConfig -p SimulationRC

Update parameters online

Parameters can be updated online by using the IMC-messages SetEntityParameters / GetEntityParameters. This can also be done from Neptus:

1. Neptus needs xml-files which holds parameter information for each vehicle. These can be generated by dune -c config -p Profile -X <path>. Place them in <neptus-dir>/conf/params/
2. In your console, open View->System Configuration. Enable the check-box "Access Developer Parameters"

Appending parameters to an already configured task

In some situations, it is useful to have a base configuration file that can be included across many different vehicles, see e.g. auv/transports.ini that sets up the basic transports and logging of AUVs. Suppose that you want to transport exactly the same IMC messages as in transports.ini. Then you could simply add [Require auv/transports.ini] to your ini-file. If you want some additional IMC, lets say DesiredLinearState, you would add the following to your ini-file:

[Require auv/transports.ini]

[Transports.UDP]
Transports+       = DesiredLinearState

Please note that the '+' has to directly follow the parameter name, Transports in this case, as opposed to the param += value syntax known from many programming languages.