MADS Introduction

MADS

Multi-Agent Distributed System for monitoring and control of industrial processes (but not only...)

Architecture

The architecture is based on a distributed network of processes, called agents, connected via ZeroMQ protocol as publishers-subscribers, using a central broker for network discovery and settings sharing.

Agents can be implemented as monolithic processes, i.e. a single executable that performs a specific task, or as plugins, i.e. shared libraries that can be loaded at runtime by a general purpose executable.

Plugins can be of three different types:

• Sources: they grab data from the field and publish them to the broker
• Filters: they receive data from other sources or filters, process them, and publish the results to the broker
• Sinks: they receive data from the broker and process them locally (visualizing, logging, bridging to other networks, etc.)

There are three corresponding general purpose, plugin-based agents, named source, filter, and sink.

Some specific monolithic agents are also available for common tasks, such as logger, which saves incoming data to a MongoDB database.

%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart LR
    broker["Broker"]
    source["Source"]
    filter["Filter"]
    sink["Sink"]
    monolithic["Mon. source"]
    source_plugin["Source Plugin"]
    filter_plugin["Filter Plugin"]
    sink_plugin["Sink Plugin"]
    source_plugin <--> source
    filter_plugin <--> filter
    sink_plugin <--> sink
    source --> broker
    filter --> broker
    broker --> sink
    monolithic --> broker
    broker --> filter
    sink --> field
    broker --> logger
    logger --> mongodb[(MongoDB)]

Loading

Settings

The settings are stored in an INI file according to the TOML format. By defaut, the setting file is read by the broker (which must be the first process to start), and then passed to the other processes via a ZeroMQ REQ/REP socket. This way, all agents share the same settings even if they run on different filesystems.

The settings file is divided into sections, one for each agent. The section name is the name of the executable file, without the path and the extension. For example, the settings for the logger agent are stored in a section named [logger].

An [agents] section is also present, which contains the settings that are meant to be shared among all agents.

Database

The logger agent can log all the messages to a plain file or to a MongoDB database (or both). MongoDB is the preferred route: file output is just for debugging purposes.

The suggested way to install MongoDB is via Docker. The following command will install the latest version of MongoDB in a Docker container, and will expose the default port (27017) to the host machine.

docker run --name mads-mongo --restart unless-stopped -v </local/path/to/your>/db:/data/db -p27017:27017 -d mongo

which will store the database under </local/path/to/your>/db.

The Logger agent connects to a MongoDB instance. The URI of the database (possibly on a different machine) is specified in the mads.ini file, as well as the name of the database to be used.

For each and every message received by the logger agent, it saves a new document on a table named as the topic of the message. The document contains the following fields:

• _id: a unique identifier for the document, automatically generated by MongoDB
• timestamp: the timestamp of the message
• message: the message itself, as a JSON object
• error: error message when the JSON is not valid

Commands

The installation folder can be set by the CMAKE_INSTALL_PREFIX variable. A good path is /usr/local, so that the executables will be copied to /usr/local/bin, which is in the system path.

Then there is a central command for managing the system: mads. It is actually a shell script that dispatches the actual command to the real executables, or sub-commands.

Available sub-commands are:

• broker: executes the ZeroMQ broker
• logger: executes the MongoDB logger
• source: it needs the path of a source plugin as a first argument
• filter: it needs the path of a source plugin as a first argument
• sink: it needs the path of a source plugin as a first argument
• feedback: starts the feedback agent, which prints all traffic on console
• service <service_name> <command> [arguments...]: for creating a Systems service (Linux only)

Note that the plugin-based agents search for plugins in the /usr/local/lib directory, unless a full path is given.

Create a service

To create a service, you first test a given agent launch command with its arguments, for example:

mads source serial_reader.plugin -s tcp://mads-broker.local:9092

If it works, as expected (also do mads source -h to check possible options), then just add service <desired_name> after the mads word, e.g.:

mads service <desired_name> source serial_reader.plugin -s tcp://mads-broker.local:9092

This will print the text description of the Systemd service to be created. To actually save it, just prepend the whole command with sudo. Finally, you have to enable and start the service:

sudo systemctl enable <desired_name>
sudo systemctl start <desired_name>

---