Ir para o conteúdo

Component: IoT Replay Simulator and Session-Based Simulation

Responsibility

The federated-simulator module replays dataset observations and events over MQTT and plays generic simulation-data packages. The monitor's round-based session state and controls live in federated-rest-api (SimulationSession, SimulationRoundEngine, and MqttClientDataFlowInjector).

Implementation

Item Value
Module modules/federated-simulator
Java package br.ufma.lsdi.simulator
Execution script scripts/run-iot-simulator.sh
Monitor integration The API module invokes the replay engine from its simulation-session routes

ADR-004: federated-simulator does not depend on federated-rest-api. The Maven dependency graph is acyclic; the REST API depends on the simulator, not the other way around.


1. IoT Dataset Replay

MqttDatasetReplaySimulator

Orchestrates dataset replay over the configured MQTT gateway. Production runs publish through the real Paho broker connection; in-memory MQTT is a test fixture only.

MqttDatasetReplaySimulator simulator = new MqttDatasetReplaySimulator(mqttGateway, signatureService);

// Full replay of all clients
simulator.replayAllClients(adapter, clientIds);

// Replay of a specific round
simulator.replayAllClients(adapter, clientIds, roundNumber, totalRounds);

Run via script:

# UCI HAR
sh scripts/run-iot-simulator.sh har

# ECG5000
sh scripts/run-iot-simulator.sh ecg

HarMqttReplayAdapter

Publishes UCI HAR Dataset observation windows as MQTT messages per client/subject.

Method Description
replayAll() Publishes all observations for all clients
replayAllRound(roundNumber, totalRounds) Publishes the observation slice for the given round
replayClientRound(clientId, roundNumber, totalRounds) Publishes the slice for a specific client

Deterministic slicing per round (DatasetPartitioner.roundSlice):

chunkSize = max(1, clientRowCount / totalRounds)
fromRow   = min((roundNumber - 1) * chunkSize, clientRowCount)
toRow     = (roundNumber >= totalRounds) ? clientRowCount : min(fromRow + chunkSize, clientRowCount)
return RowRange(fromRow, max(fromRow, toRow))

The last round absorbs all remaining records, guaranteeing full coverage without data loss.

Fixed defect — inverted range. When a client has fewer rows than rounds, chunkSize clamps to 1 and a late round's fromRow runs past the end of the client's range, while the final round still forced toRow = clientRowCount. roundSlice(3, 5, 5) returned [4, 3). In the generic CSV engine that throws from List.subList(4, 3); in the HAR/ECG adapters the loop simply never runs, so the round publishes zero observations silently. Both fromRow and the final bound are now clamped, so the range is always valid: 0 <= fromRow <= toRowExclusive <= clientRowCount.

Published topic: mhub/{clientId}/service_topic/{entityId} (CDDL, scoped by client — BL-237) with a signed MqttEnvelope<ObservationMessage>. Note this is not iot/clients/{clientId}/entities/… — the canonical per-client topic exists in IotTopics and is subscribed by MqttTimeSeriesIngestor, but no replay adapter publishes there today. Because the CDDL topic now carries clientId in its own path, isolation between clients is structural — the same guarantee the canonical topic already had — and does not depend on the envelope's senderId. The envelope's senderId is still built with ClientSenderScope.senderIdFor(prefix, clientId) for audit/signing purposes and because CDDL event topics (object discovered/disconnected) remain global and still rely on it for scoping; see 07-data-component.md for the historical cross-client ingestion bug that motivated ClientSenderScope in the first place.

Experiment scoping (BL-207)

Both adapters take the experimentId to declare in the envelope; the 4-argument constructor keeps the canonical id:

new HarMqttReplayAdapter(root, gateway, signatures, maxClients);                    // canonical
new HarMqttReplayAdapter(root, gateway, signatures, maxClients, "exp-har-...-run2"); // clone

Fixed defect. The field used to be hardcoded (experimentId = "exp-har-smartphones-001"). Once MqttTimeSeriesIngestor began rejecting envelopes from another experiment (BL-206), a clone — AdminMonitoringService.cloneExperiment accepts any new id — received zero data: the replay published under the canonical id while the client listened under the clone's. Null/blank falls back to CANONICAL_EXPERIMENT_ID.

SimulationRoundEngine's adapter cache key gained the experimentId for the same reason — without it, a clone reusing the same dataset path and maxClients would be handed the canonical experiment's cached adapter and publish under the wrong id.

EcgMqttReplayAdapter

Publishes ECG5000 heartbeats as MQTT messages per client, analogous to HarMqttReplayAdapter. The 5 clients receive deterministic slices with seed=42.


2. Round-Based Simulation Session

Implemented in BL-053 and BL-054 — allows controlling the execution of federated experiments round by round via the web monitor, without needing the command line.

SimulationSession

Immutable record representing the session's state machine:

public record SimulationSession(
    String experimentId,
    String status,          // ACTIVE | PAUSED | DONE | ERROR
    int currentRound,       // current round (0 = before the first)
    int totalRounds,        // total planned rounds
    String lastMessage      // diagnostic message (e.g., reason for ERROR)
)

Available transitions (immutable — produce a new instance):

Method Transition
withRoundSent(n) increments currentRound to n
withStatus("PAUSED") pauses without changing currentRound
withStatus("DONE") marks as complete
withStatus("ERROR", msg) records an error without changing currentRound

SimulationRoundEngine

BL-246: SimulationRoundEngine is now a thin facade over ClientDataFlowInjector — it holds no MqttGateway reference itself and delegates every method (sendRound, registerCsvSchema, registerCsvSplitRatios, registerClientIds, csvValidationRowCount, clearCache, evict, publishedByClient) to the configured injector. MqttClientDataFlowInjector is the production implementation — it is the only class that actually publishes replay data via MQTT (delegating to HarMqttReplayAdapter/EcgMqttReplayAdapter/CsvDatasetSimulationSource, exactly the same logic that used to live directly in SimulationRoundEngine). The two-argument constructor below is preserved unchanged for callers (AdminWebServer) — it just builds a MqttClientDataFlowInjector internally:

SimulationRoundEngine engine = new SimulationRoundEngine(mqttGateway, signatureService);
SimulationRoundEngine.RoundResult result = engine.sendRound(session);

A second constructor, SimulationRoundEngine(ClientDataFlowInjector injector), lets tests inject a fake that implements only inject(session) — the other ClientDataFlowInjector methods have no-op default implementations, so a minimal fake never needs to override CSV-schema/client-id bookkeeping it doesn't care about.

Internal cache (inside MqttClientDataFlowInjector): ConcurrentHashMap<String, Object> keyed by "type:path:maxClients:experimentId" to avoid reloading the CSV on every round.

session.datasetType() accepts: "har", "ecg", or "csv" (BL-088, generic tabular replay via CsvDatasetSimulationSource — see 16-generic-dataset-simulation.md).

Environment variable

Variable Default Description
SIM_HMAC_SECRET "web-sim-secret-dev" HMAC secret for signing the MQTT envelopes published by the session. In production, it must be random and secure. The -dev suffix makes it clear the default value is unsuitable for production.

Simulation Session HTTP Routes

AdminWebServer exposes the following routes under /experiments/{id}/sim-session/:

Method Route Action
GET /experiments/{id}/sim-session Shows the session's current state (HTML)
POST /experiments/{id}/sim-session/start Starts the session (parameters: type, path, maxClients, totalRounds)
POST /experiments/{id}/sim-session/send-round Executes and advances one round
POST /experiments/{id}/sim-session/run-all Executes all remaining rounds in sequence
POST /experiments/{id}/sim-session/pause Pauses the session
POST /experiments/{id}/sim-session/resume Resumes a paused session
POST /experiments/{id}/sim-session/stop Ends the session
GET /api/experiments/{id}/sim-session Session state as JSON (200) or 404 with no session

The "▶ Session" tab is shown in AdminHtmlLayout.experimentTabs() for all experiments.

run-all route

Executes all remaining rounds in sequence:

POST /experiments/{id}/sim-session/run-all
  • Iterates from currentRound + 1 to totalRounds.
  • Sends an SSE sim-round-sent event after each round (when sseEventBus is available).
  • On error in any round, stops the loop and marks the session as ERROR.

Session JSON API

// GET /api/experiments/{id}/sim-session
{
  "experiment_id": "exp-har-smartphones-001",
  "status": "ACTIVE",
  "current_round": 2,
  "total_rounds": 5,
  "last_message": ""
}

// No active session:
// 404 {"error": "no active session"}

Implemented invariants

  • send-round never uses advanceSimulationRound on error — it uses markSimulationSessionError(), preserving currentRound.
  • pause and resume redirect with &msg=no-session when there is no active session, without propagating an exception.
  • MqttClientDataFlowInjector's adapter cache uses a composite key type:path:maxClients:experimentId to invalidate correctly when parameters change between sessions (BL-207 added experimentId).

Tests

Simulation-session tests live in modules/federated-rest-api/src/test/java/...; the exact count changes with the checkout:

  • SessionStateTests (5): state machine, transitions, immutability
  • ServiceSessionTests (10): start, advance, pause, resume, stop, markError
  • HttpRouteTests (6): start/send-round/pause/resume/stop routes, JSON API
  • Additional BL-054 tests (8): ERROR state, run-all, removed silent catch, JSON API 404