Ir para o conteúdo

MQTT — HDT-AF Federated Bus

This folder documents the federated MQTT bus and its topic contracts. Round control and signed client updates use MQTT 5 with TLS/mTLS; discovery, consent synchronization, package download, and artifact transfer also use HTTPS REST. Android's MDPL request/result topics are device-local CDDL traffic, not remote MQTT topics.

Index

Document Content
01-envelope.md Envelope structure, required fields, signature, and JSON schema
02-topics-and-payloads.md All system topics with direction, payload, and examples
03-topics-iot-per-experiment.md Per-experiment IoT property codes, events, and client announce topic

Java implementation

Federated protocol (fl/)

Class Module Responsibility
MqttTopics federated-common Generates standardized topic strings
MqttEnvelope<T> federated-common Envelope record + signed() method + verify()
MqttGateway federated-common Interface: publish() and subscribe()
MqttMessageHandler federated-common Functional interface for message handlers
InMemoryMqttGateway federated-common test sources Test fixture; not a production transport
MqttClientUpdateCollector federated-orchestrator Collects ClientUpdateMessage per round (moved from federated-aggregator in BL-244)

Time-series ingestion (iot/ / mhub/)

Class Module Responsibility
IotTopics federated-common Generates IoT and CDDL topic strings (iot/clients/{id}/..., mhub/{clientId}/service_topic/...)
ObservationMessage federated-common DTO for a sensor reading via MQTT
EventMessage federated-common DTO for a discrete event via MQTT
TimeWindow federated-common Value object for time-window filtering (br.ufma.lsdi.common.model)
MqttTimeSeriesIngestor federated-local-cdm Subscribes to IoT/CDDL topics and persists to the TimeSeriesStore
MqttTrafficMonitorService + MongoMqttMessageStore federated-rest-api Passively archives full envelopes from all MQTT topics when MongoDB is configured
SqliteTimeSeriesStore federated-local-cdm SQLite persistence for observations, events, and entities
TimeSeriesDatasetBuilder federated-local-cdm Builds an InMemoryLocalCdmRepository from the store

Schema

The envelope's JSON schema is at schemas/mqtt/envelope.schema.json.

Mandatory rules

  • Federated control topics use fl/experiments/{experimentId}/; IoT observations use the separately scoped iot/ namespace. Device-local MDPL request/result topics use mdpl/ only through CDDL and must not be forwarded to the remote broker.
  • Federated protocol messages are wrapped in MqttEnvelope<T> with the sender's X.509 or HMAC signature (verify() + verifyPayloadIntegrity()). The device-local CDDL MDPL messages are not MqttEnvelopes and never leave the device.
  • fl/ carries signed round control and update metadata. iot/ topics can carry observation payloads; the Android client does not publish its locally acquired sensor readings to the remote broker. Restrict topic ACLs and MQTT archives to the data scope they are authorized to access.
  • In production: MQTT 5 with mandatory TLS and mTLS to authenticate clients, orchestrator, and aggregator.
  • Per-topic authorization must prevent a client from publishing into another client's or experiment's namespace.
  • The optional MongoDB archive subscribes to # and stores complete envelopes, including IoT/CDDL payloads; see component 19 for privacy and retention requirements.

Local TLS/mTLS provisioning

The Docker Compose setup exposes only the ssl://localhost:8883 listener; the broker requires a client certificate and does not allow anonymous connections. For development, generate a CA and local PKCS12 keystores:

sh scripts/generate-mqtt-tls.sh
docker compose up -d mosquitto

The files under deploy/mqtt/tls/ are ignored by Git. Configure processes running outside Docker with MQTT_BROKER_URL, MQTT_TLS_TRUSTSTORE, MQTT_TLS_TRUSTSTORE_PASSWORD, MQTT_TLS_KEYSTORE, and MQTT_TLS_KEYSTORE_PASSWORD; see .env.example.