Minimal Efficient Telemetry Reporting Using Mesh (METRUM) Status: Draft Version: 0.2
Abstract
This document specifies a protocol for sensor telemetry over Reticulum networks. It defines a publish-subscribe pattern using Reticulum's destination announce mechanism for discovery and standardized CBOR tags for efficient sensor data representation.
-
Introduction
This specification defines a protocol for sending telemetry data over Reticulum networks. It leverages standardized CBOR tags for structured sensor data representation and Reticulum's native capabilities for network transport, discovery, and security.
METRUM uses CBOR Tag 120 (IoT Data Point) as its primary data format, with Tag 103 (Geographic Coordinates) for location information when relevant. Together, these provide a complete representation for IoT telemetry that is both efficient and standardized.
-
Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Publisher: A node that produces telemetry data Subscriber: A node that consumes telemetry data IoT Data Point: A measurement value with associated metadata (timestamp, location) Geographic Coordinates: Location information in WGS-84 reference system
-
Protocol Overview
The protocol follows a publish-subscribe pattern:
- Publishers announce their presence with metadata describing available metrics
- Subscribers listen for announces and establish links to publishers
- Subscribers send subscription requests over links
- Publishers maintain subscriber lists and send telemetry data to subscribers
- Data is formatted using standardized CBOR tags
-
Publisher Behavior
4.1. Announce Mechanism
Publishers MUST create a Reticulum destination with appropriate identity. Publishers MUST announce periodically using CBOR-encoded app_data that includes:
- "type": Set to "telemetry"
- "metrics": Array of available metrics
- "version": Protocol version, currently "0.2"
4.2. Subscription Handling
Publishers MUST maintain a list of subscriber destinations. Upon receiving a subscription message, publishers SHOULD validate the request and add the subscriber to their list.
Publishers SHOULD remove subscribers from their list when the corresponding Reticulum link is broken.
- Subscriber Behavior
5.1. Discovery
Subscribers MUST register announce handlers to detect publishers. Subscribers SHOULD filter announces by app_data type field. The publisher's identity serves as the unique identifier for establishing connections.
5.2. Subscription
Subscribers MUST establish a link to desired publishers. Subscribers MUST send a subscription message containing:
- "subscribe": Boolean set to true
- "version": Protocol version, currently "0.2"
- Message Formats
6.1. Telemetry Data Structure
Each telemetry message MUST be a CBOR map containing:
- "metric": String name of the measurement
- "data": IoT Data Point (Tag 120) containing the measurement value and metadata
6.2. IoT Data Point (Tag 120)
METRUM uses CBOR Tag 120 to represent IoT Data Points as defined in its specification.
Tag 120 MUST be applied in one of two ways:
-
Simple format: 120(value) This indicates a data point with the current UTC time as timestamp and undefined location.
-
Array format: 120([value, timestamp_tag, location_tag]) Where:
- value: The measurement value (REQUIRED)
- timestamp_tag: Tag 1(epoch_time) (OPTIONAL)
- location_tag: Tag 103([lat, lon, ...]) (OPTIONAL)
If the timestamp is omitted or null, it MUST be interpreted as the current UTC time. If the location is omitted or null, it MUST be interpreted as undefined geographic coordinates.
6.3. Geographic Coordinates (Tag 103)
When location information is included, METRUM uses CBOR Tag 103 as defined in its specification.
Tag 103 MUST be applied to an array with 2-4 elements:
103([latitude, longitude, elevation, uncertainty])
Where:
-
latitude: Decimal degrees (positive = North) (REQUIRED)
-
longitude: Decimal degrees (positive = East) (REQUIRED)
-
elevation: Height in meters (OPTIONAL)
-
uncertainty: Location uncertainty in meters (OPTIONAL)
The coordinate reference system MUST be WGS-84. Omitting or setting elevation or uncertainty to null indicates these values are not provided.
6.4. Data Models and Examples
The following examples illustrate common telemetry data patterns using the CBOR tags:
6.4.1. Basic Measurement
A simple temperature reading without location:
{
"metric": "temperature",
"data": 120([23.5, 1(1500000000)])
}
6.4.2. Geo-tagged Measurement
A temperature reading with full location context:
{
"metric": "temperature",
"data": 120([23.5, 1(1500000000), 103([44.78659, 20.44890, 117, 5])])
}
Where the location array represents [latitude, longitude, elevation, uncertainty].
-
Protocol Evolution
This protocol is designed to evolve with Reticulum's capabilities. When Reticulum implements "group destinations" in future versions, METRUM will be extended to utilize this feature for more efficient multicast delivery of telemetry data to multiple subscribers.
-
Security Considerations
This protocol inherits security properties from Reticulum. All telemetry data is encrypted using Reticulum's mechanisms. Access control is provided through Reticulum's authentication capabilities.
-
References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC8428] Jennings, C., et al., "Sensor Measurement Lists (SenML)", RFC 8428, August 2018.
[RNS] Qvist, M., "Reticulum Network Stack", https://github.com/markqvist/Reticulum
[TAG120] Vidovic, D., "CBOR Tag 120 - Internet of Things Data Points", https://github.com/allthingstalk/cbor/blob/master/CBOR-Tag120-Internet-of-Things-Data-Points.md
[TAG103] Vidovic, D., "CBOR Tag 103 - Geographic Coordinates", https://github.com/allthingstalk/cbor/blob/master/CBOR-Tag103-Geographic-Coordinates.md
[WGS-84] National Imagery and Mapping Agency, "Department of Defense World Geodetic System 1984", NIMA TR8350.2, January 2000.