Machine configurations

MaCI consists of a group of standalone Modules. All machines usually provide multiple services at the same time, like movement controls and sensor data. Each Module in MaCI is normally designed to handle only one specific task, for example; SpeedCtrl over motor controller hardware. If we want to flexibly define a full configuration for some specific machine, we need Machine configurations. Machine configuration consists of a master configuration and a group of module configuratios effectively defining features of a specific machine.

Building configurations

Machine configurations are group of XML-documents, which describe the features of the machine. Each machine has one master configuration file (<machine_name>.mconf), and any number of module configuration files (<module_name>.conf). Creating configurations for modules was already discussed under section Modules, so it won't be described again here.

Under MaCI, there is a directory named 'conf', which contains basic configuration for every module. These are MaCI-machine building blocks.

To create a new machine, follow these steps:

  1. Create a directory for the new machine under 'MaCI/machines' directory. In case you are creating a different "flavor" of an existing machine, the directory should be placed under the main machine directory. For example; to create a special configuration for J2B2 to be used on course AS-84.3145 on year 2008, you could create directory 'MaCI/machines/J2B2/AS843145_2008'. When creating a completely new machine, you should still create a subdirectory named 'std' to support adding new versions of the machine in the future.
  2. Copy file 'MaCI/machines/template/std/somemachine.mconf' to your new machines directory and rename it appropriately (like 'J2B2.mconf').
  3. Copy any number of '*.conf' files from the 'MaCI/conf' directory to your new machines directory. Also make sure that you copy all the files related to modules configuration. For example; the ESC629-module uses a separate configuration file 'ESC629.xml' to define driver settings. Information about dependencies should be found from the module configuration file.
  4. Modify the machine configuration file to match your desired hardware configuration. For details on how to do this, keep reading :)

Machine configuration file details

This document describes the version 0.1 of the "Machine Configuration File, (MaCF)"-specification.

In this section we will split the template machine configuration in parts and describe each part in detail.

<?xml version="1.0"?>
<machine version="0.1">

This part contains the 'root' key of the configuration XML-document. The keyword machine is required for the Launcher to be able to identify the file correctly. Property version stands for the "Machine Configuration File (MaCF)"-specification version this configuration is based on. Currently the newest MaCF-specification is 0.1. The version property is optional, but should be defined to make it easier to track problems with future Launcher versions and old configuration files.

<!-- Freeform machine name -->
<name>Some Machine</name>

Here we define the machine name. The name is a relatively short free form string identifying the machine. The machine name is used for different identification purposes, like identifying correct machines from MaCI-service discovery.

<!-- Freeform machine description -->
<description>This is a template file for defining machine configurations.</description>

Defining machine description. Description is a free form string also used for identification purposes only. (Over GIMnet or by just while reading the configuration files)

<!-- MaCI parameters -->
  <!-- GIMnet access point config. If entry is empty or missing, the Launcher -->
  <!-- commandline/default parameters are used-->

These define GIMnet specific parameters. Parameters GIMnetAP_host and GIMnetAP_port define the address and port of the GIMnet access point this machine should connect to. If these parameters are left empty (nothing between the tags), or left out completely (no tags defined) the parameters defined on the higher level will be used instead. (Some parameters can be saved on the Launcher configuration itself). Remember however that as these settings override the settings defined by Launcher, each module configuration can override these settings with their own parameters again.

  <!-- MaCI group config. If entry is empty or missing, the Launcher -->
  <!-- commandline/defautl parameters are used -->

The entity Group defines name of the MaCI-Group this machine (== all modules in this machine) belong to. All MaCI-modules sharing the same Group name are assumed to be part of the same machine even if the 'Machine' consists of multiple machines split on multiple computers. This is useful for example if we have a "Localization"-service based on external camera data but the localization is really part of the machine itself, we can define the external service to be virtually part of a specific machine. Remember that each module configuration can override this parameter with their own parameters.

<!-- Specify working directory of this machine. (All unspecified directories will use -->
<!-- this as their current working directory. If this is empty or unspecified, the -->
<!-- machine configuration directory will be used as the default working directory -->

Defines working directory for the Launcher while executing this machine. The working directory affects on paths used as parameters. If this field is left empty, the Launcher will execute the machine configuration in the configuration directory itself. If this field is non-empty, the Launcher will attempt to do 'chdir()' to the specified directory prior to this call. The workdir is executed from the current directory (Where the launcher was called at).

<!-- List of module configurations belonging to this machine -->
  <!-- You can specify multiple files explicitly... -->

  <!-- ... or by using regular expressions (Be careful not to intersect with explicit files) -->

Define modules to be executed by this machine. All the modules defined here will be loaded and executed by the Launcher. Subkeys are defined as follows:

  • FILE - tags. These specify configuration files explicitly. Like 'ESC629.conf' specifies that the configuration file 'ESC629.conf' should be loaded and executed.
  • PATTERN - tags. These allow you to specify files using wildcards (in fact, it requires to use regular expressions). The example pattern selects all files in the current working directory whose filename ends with '.conf'. Beware that no filtering is done between files matched with pattern and files specified with the 'file' tag, so it is possible to load the same configuration twice if it is first specified as a 'file' and then matched with a pattern.

End of machine configuration file.

Module configuration file details

For details about creating/modifying module configuration files, see the Modules section.

Launching configurations

To be able to use the previously built Machine configuration, we need a way to execute it. For this reason we have a software called 'Launcher'. Launcher is a software which reads the machine configuration and executes all the required modules.

Using the Launcher to Execute machine

QuickStart: Just go to directory 'MaCI/launcher' and type:

./Launcher -M ../machines/<machinename>/<flavor>

For example, to launch a J2B2 robot with standard configuration:

./Launcher -M ../machines/J2B2/std

After this, just sit back and BE IN CONTROL! X-D

Using the Launcher to selectively compile modules for a machine

As MaCI consists of multiple modules, of which only a fraction at a time is required for a single machine to run, there is no sense in compiling all the modules under MaCI every time. To assist users in building just the required modules per machine, the Launcher has selective Building feature. This feature uses information in module configuration file on how to compile the specific module. Each module can have a arbitrarily complex expression for compiling the module, as the command specified is executed directly using 'system()' call.

Using this feature is simple, just call the Launcher like: (Note the '-B' flag instead of the '-M' flag used for launching a Machine)

./Launcher -B ../machines/J2B2/std

This command only runs the compile command on per module basis. So if your Makefiles are not correct, the compile process may produce incomplete builds. To be sure that the selective build is always using the most current sources available, use the script './rm_all_objects' located in the directory GIM/src. This script removes all object files recursively under GIM/src, effectively causing a rebuild of all objects during the selective build cycle.

After the machine is compiled with the '-B' flag, the machine is ready to be run using the ordinary '-M' flag.