03 — IoT Topics per Experiment¶
Additional topics beyond the
02-topics-and-payloads.mddocument, which covers only thefl/namespace (federated learning) and the generic IoT topics. This document details the entity types, property codes, and events specific to each experiment, as well as the patterns for extending support to new experiments.
Topics added in this document¶
| Topic | Experiment | New relative to doc 02 |
|---|---|---|
iot/clients/{id}/entities/{windowId}/observations |
HAR | entityType=smartphone_activity_window, 561 specific propertyCode values |
iot/clients/{id}/entities/{beatId}/observations |
ECG | entityType=ecg_heartbeat, 140 time points t001…t140 + ecg_class_label |
iot/clients/{id}/entities/{beatId}/events |
ECG | eventTypeCode=ecg_anomaly with severity mapping per class |
fl/experiments/{expId}/clients/{clientId}/announce |
All | Client discovery via MQTT (not documented in doc 02) |
1. HAR Experiment — UCI Smartphones¶
Experiment ID: exp-har-smartphones-001
Replay adapter: HarMqttReplayAdapter
Client mapping¶
Each UCI HAR subject (1–30) corresponds to a clientId. The maximum number of subjects is configurable in the replay.
Observations topic¶
| Field | Value |
|---|---|
entityId |
window-00001, window-00002, … (2.56 s window) |
entityType |
smartphone_activity_window |
propertySystem |
uci-har |
unitUcum |
normalized |
observedAt |
base 2026-01-01T00:00:00Z + offset per window |
Property codes (propertyCode)¶
Each window publishes 562 observations — 561 features + 1 activity label:
| Range | Description |
|---|---|
f001_tBodyAcc-mean()-X … f561_angle(Z,gravityMean) |
561 features of the HAR vector (time and frequency domain) |
activity_label |
Activity label as valueNumeric (1–6) and valueText (WALKING, WALKING_UPSTAIRS, WALKING_DOWNSTAIRS, SITTING, STANDING, LAYING) |
Subscription wildcards¶
iot/clients/1/entities/+/observations # all windows for subject 1
iot/clients/+/entities/+/observations # all windows for all subjects
2. ECG Experiment — ECG5000 Anomaly Detection¶
Experiment ID: exp-ecg5000-anomaly-001
Replay adapter: EcgMqttReplayAdapter
Client mapping¶
5,000 heartbeats distributed across up to 5 clients (~1,000 heartbeats/client).
Observations topic¶
| Field | Value |
|---|---|
entityId |
beat-00001, beat-00002, … |
entityType |
ecg_heartbeat |
propertySystem |
ecg-sensor / ecg-classifier |
unitUcum |
normalized_mv (time points) · class_id (label) |
observedAt |
~900 ms interval between heartbeats (~67 bpm) |
Property codes (propertyCode)¶
Each heartbeat publishes 141 observations — 140 time points + 1 label:
| propertyCode | Description |
|---|---|
t001 … t140 |
Normalized amplitude of each time point of the heartbeat |
ecg_class_label |
MIT-BIH class as valueNumeric (1–5) and valueText (N, R, V, L, E) |
Events topic (anomalies)¶
Published only when class ≠ 1 (non-normal heartbeat):
{
"entityId": "beat-00001",
"entityType": "ecg_heartbeat",
"eventTypeCode": "ecg_anomaly",
"eventTypeSystem": "mit-bih-classifier",
"eventStart": "2026-01-01T00:00:00Z",
"severity": "high"
}
Severity mapping per class:
| MIT-BIH class | Label | severity |
|---|---|---|
| 2 — R | Right Bundle Branch Block | low |
| 3 — V | Premature Ventricular Contraction | high |
| 4 — L | Left Bundle Branch Block | moderate |
| 5 — E | Paced Beat | low |
Subscription wildcards¶
iot/clients/1/entities/+/observations # observations for client 1
iot/clients/1/entities/+/events # events (anomalies) for client 1
iot/clients/+/entities/+/events # all anomalies
4. Client Announce Topic (added — not in doc 02)¶
Java method: MqttTopics.clientAnnounce(experimentId, clientId)
Subscription wildcard (Admin API): fl/experiments/+/clients/+/announce
Published by the client on startup, announcing its availability to participate in rounds. The Web Monitor (Admin API) subscribes to the wildcard and automatically registers new clients discovered via MQTT.
{
"clientId": "client-har-001",
"experimentId": "exp-har-smartphones-001",
"deviceType": "docker-jvm",
"runtimeVersion": "Java 25",
"capabilities": ["JVM_SERVER"],
"available": true,
"announcedAt": "2026-06-23T10:00:00Z"
}
ClientAnnouncePayload(clientId, experimentId, deviceType, runtimeVersion, capabilities, available, announcedAt).)
5. Pattern for New Experiments¶
To add support for a new data type, follow this pattern:
5.1 Define entityType and propertyCode¶
entityType = {domain}_{entity_type}
e.g.: "wearable_heart_rate", "industrial_vibration_sensor"
propertyCode = short code with no spaces
e.g.: "bpm", "spo2", "accel_x", "temp_celsius"
5.2 Create the replay adapter¶
Implement a class following the pattern of HarMqttReplayAdapter or EcgMqttReplayAdapter:
public class MyExperimentMqttReplayAdapter {
// Publishes ObservationMessage via IotTopics.entityObservation(clientId, entityId)
// Publishes EventMessage via IotTopics.entityEvent(clientId, entityId)
// Signs the envelope with HmacSignatureService
}
5.3 Register in IotDatasetReplayApp¶
Add a new case to the main() method of IotDatasetReplayApp:
case "my-exp" -> new MyExperimentMqttReplayAdapter(mqttGateway, signatures, datasetPath, maxClients).replayAll();
5.4 Document in this file¶
Add a new section following the pattern of sections 1–3, specifying:
- default entityType and entityId
- propertyCode for each observation
- eventTypeCode for each event (if any)
- Severity mapping (if any)
- Recommended subscription wildcards
6. Full flow: File → MQTT → SQLite → Training¶
Raw file (CSV/zip)
│
▼
Replay Adapter (HarMqttReplayAdapter | EcgMqttReplayAdapter | MqttDatasetReplaySimulator)
│ publishes ObservationMessage / EventMessage with a signed envelope
▼
PahoMqttGateway (MQTT 5 TLS :8883) ←── mhub/{clientId}/service_topic/... or iot/clients/{id}/entities/...
│
▼
MqttTimeSeriesIngestor
│ verifies signature + integrity · converts to LocalObservation / LocalEvent
▼
SqliteTimeSeriesStore ({dataRoot}/timeseries.db)
│ tables: mqtt_observations, mqtt_events, mqtt_entities
▼
DataComponent.loadLocalCdmRepository(clientId, experimentId)
│
▼
InMemoryLocalCdmRepository
│
▼
DataComponent.authorizedTrainingView(...) ←── filters by DataSchemaSpec + TimeWindow
│
▼
TrainingLocalModel.execute(TrainingContext)
References¶
modules/federated-common/src/main/java/br/ufma/lsdi/common/mqtt/IotTopics.javamodules/federated-common/src/main/java/br/ufma/lsdi/common/mqtt/MqttTopics.javamodules/federated-simulator/src/main/java/br/ufma/lsdi/simulator/modules/federated-local-cdm/src/main/java/br/ufma/lsdi/localcdm/timeseries/MqttTimeSeriesIngestor.javadocs/mqtt/02-topics-and-payloads.md— generic FL and IoT topics