The framework provides the functionality for different software modules to communicate with each other in an easy and safe way.

A framework can be launched by creating an instance in your application.

#include <fw/Framework.h>
using namespace mira;
int main(int argc, char** argv)
{
    Framework framework(argc, argv);
    // run the framework main loop
    return framework.run();
}

Alternatively, you can run the tools mira or miracenter that start up a framework. These tools also provide configuration methods for the framework via configuration files, see Writing a Configuration File.

TODO:

communication of Software modules (Middleware) , ...
Figure that shows different software modules (some in one processes, some in different processes, some on other machines) that are communicating

Authorities

To be able to access the framework, a software module needs to create an Authority. Authorities are used to control access rights and to identify the software modules. Within its Authority, the software module is free to do almost anything (creating additional threads, etc.). Hence, you can also think about an Authority as some kind of sandbox.

An authority can be created easily as follows:

Authority authority("namespace", "name");

Here, the namespace and the name of the Authority need to be specified. For more details please refer to Authorities.

You can also work with Units or MicroUnits, higher-level classes that allow to create software modules more easily. Units and MicroUnits implicitely create an Authority for you.

For additional information please refer to Authorities and Units

Communication

For communication with other software modules outside of the Authorities sandbox, the framework provides two mechanisms: Channels and Remote Procedure Calls (RPC). The framework handles the communication fully transparently, no matter if the communication partners are located within the same process or if they are distributed over different processes or machines. It also handles concurrent access to the same data within one process fully autonomously.

Channels

Channels are used to store and transport data between different software modules. Channels are usually used for continuous or periodic data flow between modules. The Channels are named and typed, hence you need to specify the channel's name and its type when accessing the channel.

For putting data into a Channel you need to publish the Channel once:

Channel<Pose2> poseChannel = publish<Pose2>("Pose2");

Afterwards you can easily write data directly to the channel by obtaining a write accessor:

ChannelWrite<Pose2> w = poseChannel.write();
w->x()   = ...
w->y()   = ...
w->phi() = ...

For reading data from a Channel, you need to subscribe the Channel once:

Channel<Pose2> poseChannel = subscribe<Pose2>("Pose2");

Afterwards you can easily read the data directly from the channel by obtaining a read accessor:

ChannelRead<Pose2> w = poseChannel.read();

cout << w->x() << w->y() << w->phi() ...

Besides, Channels provide a much wider variety of functionality, e.g. a notification mechanism when new data arrives, reading data from the past, interpolating data stored in Channels, event handling, etc. For more details please refer to Channels and Publishing / Subscribing.

Remote Procedure Calls (RPC)

Remote Procedure Calls allow your software module to call a procedure or method of a service that is provided by another software module. The service may be located locally in the same framework within the same process or in a different process or even on a different machine.

In contrast to Channels, which are used for continuous data transfer, RPC calls can be used to trigger actions or state changes in other modules, to configure them, to initiate certain processes or behaviours, to obtain information from the service or to perform a computation that is done by the service.

A remote service method can be called easily as follows (e.g. somewhere in a Unit or MicroUnit):

callService<int>("MyService", "myMethod", 1.23f);
//          ^        ^            ^         ^
//    Return-Type  Service-Name  Method    Variable number of parameters

Here, the return type of the called method needs to be specified as template parameter. Moreover, the name of the service, the method to call, and parameters that shall be passed to the method need to be specified.

For details how to obtain the return value, how to wait for the successful temination of the call and how to offer your own services please refer to Services and Remote Procedure Calls.