Ir para o conteúdo

03 — IoT Topics per Experiment

Additional topics beyond the 02-topics-and-payloads.md document, which covers only the fl/ 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

iot/clients/{clientId}/entities/{windowId}/observations
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

iot/clients/{clientId}/entities/{beatId}/observations
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)

iot/clients/{clientId}/entities/{beatId}/events

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)

fl/experiments/{expId}/clients/{clientId}/announce

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.java
  • modules/federated-common/src/main/java/br/ufma/lsdi/common/mqtt/MqttTopics.java
  • modules/federated-simulator/src/main/java/br/ufma/lsdi/simulator/
  • modules/federated-local-cdm/src/main/java/br/ufma/lsdi/localcdm/timeseries/MqttTimeSeriesIngestor.java
  • docs/mqtt/02-topics-and-payloads.md — generic FL and IoT topics