Network structure

template
basics
easy
Author
Affiliation

Paolo Bosetti

University of Trento

Published

June 4, 2025

Modified

June 12, 2026

Abstract

Illustrate a typical MADS network structure and its requirements.

Architecture

The typical architecture of a MADS network can be represented as:

MADS Network p1 Plugin 1 a1 Agent 1 (source) p1->a1 broker broker a1->broker p2 Plugin 2 a2 Agent 2 (filter) p2->a2 a2->broker p3 Plugin 3 a3 Agent 3 (sink) p3->a3 a3->broker a4 Monolithic Agent (filter) a4->broker mongo MongoDB logger logger broker->logger logger->mongo BSON
Figure 1: MADS Network
Important

Remember that the above schematic represent processes, regardless the physical machine on which they are being executed.

For example, the whole network could run on a single workstation, or it could be conversely distributed over multiple devices connected to the same IP network, each device running a single process/node.

In the figure Figure 1, the solid lines represent a ZeroMQ connection over TCP/IP, which uses compressed JSON as a data encoding protocol. Compression is preformed with the snappy library. The dashed line, conversely, represents the proprietary MongoDB protocol, with data serialized as BSON (Binary-JSON).

The broker

What is the broker purpose?

The broker solves the issue of knowing multiple network addresses when you have a number of devices participating to the same distributed system.

With the aid of the broker, any separate device partaking to the MADS network only needs to know a single hostname/IP address: that of the machine running the broker.

Warning

There can only be a single broker per network.

Running the broker is quite simple:

mads broker

The agents

Agents can be:

  • monolithic: implemented as a single executable inheriting the Mads::Agent C++ class.
  • plug-in: a single executable that on runtime loads a proper plug-in (i.e. a dynamically loaded library)

Regardless the type, agent can have three different behaviors:

  • source: they provide information to the network (e.g. by reading sensors)
  • filter: they operate and transform received information
  • sink: they consume information received from the network (e.g. to store or visualize)

The MADS installer provides three general purpose agents, aptly named source, filter, and sink, that are designe do load proper plugins. The command mads plugin can be used to generate a suitable template for a new plugin to be developed.

Network layout

At the bare minimum, a MADS network requires:

  • the broker
  • the MongoDB database
  • the logger agent

The MADS installers provide broker and logger, but MongoDB must be installed separatedly. The easiest route is to it via Docker.

Ideally, broker, logger and database should run on a single machine, having enough resources to store the data flow on the database, while agents can be distributed over multiple device.

Note

According to our testing, Linux is the best choice for running MADS broker and logger in terms of performance.

Any other agent can be run on the same machine or on a separate machine. In the latter case, it must be started with the -s option stating the broker address, e.g.: -s tcp://<hostname>:9092, where <hostname> shall be replaced with the proper host name, if available, or with the machine IP address. This is the only address that any agent needs to know in order to connect to the MADS network.

To help you find out the proper address, you can use the -n list broker option:

> mads broker -n list
Available network adapters:
[       lo0] - 127.0.0.1
[       en0] - 192.168.1.220
[ bridge100] - 198.19.249.3

This shows that the host has three network interfaces. The public one is probably en0 (your names may vary). Now quit the broker and relaunch it as:

> mads broker -n en0
Reading settings from /Users/p4010/usr/local/etc/mads.ini [broker]
Using network interface en0
Binding broker frontend (XSUB) at tcp://*:9090
Binding broker backend (XPUB) at tcp://*:9091
Binding broker shared settings (REP) at tcp://*:9092
Timecode FPS: 25
Settings are provided on tcp://127.0.0.1:9092 (loopback)
Advertising service on UDP discovery port 39092 with room name 'mads'
            (preferring loopback for local agents)
CTRL-C to immediate exit
Type P to pause, R to resume, I for information, Q to clean quit
N to show next IP address, X to restart and reload settings

Look at the line Settings are provided on tcp://127.0.0.1:9092 (loopback): If you repeatedly press N, it shows you the settings URI for all the available network interfaces. Suppose that the wired Ethernet en0 is the one you want to use, note its URI (e.g. tcp://192.168.1.220:9092), then cycle the available addresses until you find the settings URI to be used for agents running on other machines:

mads feedback -s tcp://192.168.1.220:9092
ImportantAdverising the serice (v2.1.0+)

Note the lines starting with Advertising...: since MADS v2.1.0, the broker advertises its presence on all the local networks via UDP, so that agents can automatically discover it without needing to know its address. This is a very useful feature for plug-and-play applications. The feature is documented here: Auto-discovery.

Where to go next

Once you have the bare minimum running, the next step is to configure and customize your distributed steps. In detail, you will have to:

  1. learn how to develop your custom agents. This can be done in three ways:
    • by developing your own monolithic agent, using the MADS C++17 library (hardest, high performance and maximum flexibility)
    • by implementing a C++17 plugin (hard, high performance, some compromise in flexibility)
    • by using the Python wrapper agent and implementing the details in Python (easy, limited performance and flexibility)
  2. learn how to make your agents into services (only on linux)
  3. learn how to synchronize time on multiple devices
  4. learn how to analyze the data collected by the MongoDB database
Back to top