Metrum

Metrum: A Telemetry System for Reticulum Networks

Metrum is an open-source telemetry system designed for Reticulum networks. It provides a standardized way to collect, process, and transmit sensor data, enabling efficient and reliable communication between devices and nodes.

Git Repository

How Metrum Works

Metrum is a framework designed for sending telemetry data (sensor readings) over Reticulum networks. It implements a publisher-subscriber pattern that allows sensor data to be efficiently transmitted from sensor nodes (publishers) to data collection nodes (subscribers).

Key components of the system include:

1. Publisher: Collects data from sensors and distributes it to interested subscribers
2. Subscriber: Discovers publishers and subscribes to their sensor data
3. Reticulum Network: The underlying transport mechanism that enables communication
4. SenML Format: A standardized format for representing sensor measurements
5. CBOR Encoding: Efficient binary serialization for compact data transmission

The Publisher Side

The publisher in Metrum operates as follows:

1. Initialization:

   • The publisher is created with a specific sensor interface
   • It establishes its identity on the Reticulum network
   • It announces its presence as a telemetry publisher

2. Sensor Data Collection:

   • Periodically reads data from connected sensors
   • Formats this data according to the SenML specification
   • Encodes the data using CBOR for efficient transmission

3. Data Distribution:

   • Manages a list of active subscribers
   • Distributes sensor readings to all subscribed nodes
   • Periodically re-announces its presence to allow new subscribers to discover it

The sensors are abstracted through a SensorInterface class, which handles the specifics of reading from physical or virtual sensors.

The Subscriber Side

The subscriber operates as follows:

1. Discovery:

   • Monitors the Reticulum network for publisher announcements
   • Records information about discovered publishers

2. Connection:

   • Establishes links to publishers of interest
   • Sends subscription requests to activate the data flow

3. Data Processing:

   • Receives CBOR-encoded SenML data from publishers
   • Decodes the data and processes it through a callback function
   • In the provided example, stores the data in InfluxDB for later analysis
   • Implements a retry queue for handling temporary database unavailability

4. Reconnection:

   • Monitors the status of publisher connections
   • Automatically attempts to reconnect to disconnected publishers

Communication Flow

The communication between publisher and subscriber follows these steps:

1. The publisher announces its presence on the Reticulum network
2. The subscriber discovers the publisher through these announcements
3. The subscriber establishes a connection to the publisher
4. The subscriber sends a subscription request
5. The publisher adds the subscriber to its active list
6. The publisher periodically collects and transmits sensor data
7. The subscriber receives, processes, and stores the data

This approach allows for a flexible and resilient system where publishers and subscribers can dynamically discover each other and establish communication without centralized coordination.

Data Format

The data is structured using SenML (Sensor Measurement Lists), which provides a standardized way to represent sensor readings. A SenML record typically includes:

• Name: Identifies the sensor or measurement (e.g., "temperature")
• Value: The actual reading value
• Unit: The unit of measurement (e.g., "Celsius")
• Timestamp: When the reading was taken

This structured format ensures that all sensor data is properly labeled and can be correctly interpreted by the receiving systems.

Advantages of this Architecture

1. Decentralization: No single point of failure in the system
2. Flexibility: Easy to add new sensors or subscribers
3. Efficiency: CBOR encoding minimizes bandwidth usage
4. Standardization: Using SenML ensures interoperability
5. Resilience: Automatic reconnection and data queuing handle network instability

This architecture makes Metrum well-suited for sensor networks in challenging environments or where network connections may be intermittent.

Diátaxis Structure

Our documentation is structured around the four needs identified by Diátaxis:

• Tutorials: Step-by-step guides for getting started with Metrum.
• How-to Guides: Practical instructions for achieving specific goals with Metrum.
• Technical Reference: Detailed descriptions of Metrum's components, APIs, and interfaces.
• Explanation: In-depth discussions of Metrum's architecture, design decisions, and underlying principles.

This structure allows us to provide a comprehensive and user-friendly documentation set that addresses the needs of different users.

Contributors

• Tom Hensel code@jitter.eu, DO2THX, 5620