Documentation

MaCI structure

MaCI is based on "divide and conquer" idea, in the sense that it organizes itself into logical subdirectories:

  • bus
  • drivers
  • interfaces
  • modules
  • machines

Bus and drivers directories are MaCI independent drivers for communicating with the physical devices.

Bus directory contains drivers for various bus devices (serial, can, ioport), which are separeted because these drivers are (may or should be) used by drivers in their implementation. In other words bus contains reusable communication drivers for the drivers (if needed).

Driver directory has set of (linux) drivers for physical devices. The driver can be completely standalone driver, without any dependency to MaCI, or at most it uses MaCI bus driver e.g. for serial communication. If you ever have written any (functional) driver for any device which might be used in robot control, you may contribute it here. The only implementation guidelines for the drivers are that they should have clear and well documented API, that is the API should be easily understandable to others.

Interface directory has pure interfaces. A MaCI interface is generalized (as much as possible or feasible) way of communicate the module specific data between the modules. An interface should specify three different parts:

  • Data type - the data that this interface represents
  • Data interpreter - encapsulates the data types for transmission of the data between client and server. The recommended way for encapsulation is to use BinBag container class.
  • Client/Server - This is the pairing that makes MaCI, well MaCI. The "server" implements the data interpreter to provide the abstracted service into the GIMnet. Client is the piece which is used by other modules to communicate with the server part. The server means service provider and client consumer. There is no strict client-server architecture (actually in many case the "server" in GIMnet is more active component than "client").

Reason for these definitions are:

  • Data definitions should always be separated from other implementation. This simplifies the users effort to find out what is the content of the packages.
  • Data interpreter (used with BinBag) allows flexible integration of different data types to interface. For user the interpreter should offer helpful methods for adding or reading the packets.The interface can also be extended later. For very simple interfaces there does not have to be intepreters.
  • Client/Server pair is the whole idea of MaCI. Client/Server pair implements MaCI base classes, and thus the module will be MaCI module, with unified functionalities.

Module directory has all the implemented MaCI modules. A module is combination of driver and interface. It is an implementation of the interface (or many interfaces) using specific hardware. A module may also be "reusable" module such as localization, mapping or planning modules, which implements algorithm to some MaCI interface. The module may have one or more services (interfaces) that it provides and it may also implement one or more clients. Module should have default type of XML configuration file, so that it can be used with Launcer-program.

Machine directory is for different robot/machine implementations. The machine is build up by combining one or more modules, which have their own configuration file. The specific machine also has configuration file for machine wide definitions. The Launcher-application starts all modules using the configuration files and the modules sets up the communication dependencies using the GIMnet.


Principle image of a machine composed in MaCI way