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 scopediot/namespace. Device-local MDPL request/result topics usemdpl/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 notMqttEnvelopes 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:
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.