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-simulatordoes not depend onfederated-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:
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,
chunkSizeclamps to 1 and a late round'sfromRowruns past the end of the client's range, while the final round still forcedtoRow = clientRowCount.roundSlice(3, 5, 5)returned[4, 3). In the generic CSV engine that throws fromList.subList(4, 3); in the HAR/ECG adapters the loop simply never runs, so the round publishes zero observations silently. BothfromRowand 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"). OnceMqttTimeSeriesIngestorbegan rejecting envelopes from another experiment (BL-206), a clone —AdminMonitoringService.cloneExperimentaccepts 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 toCANONICAL_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:
- Iterates from
currentRound + 1tototalRounds. - Sends an SSE
sim-round-sentevent after each round (whensseEventBusis 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-roundnever usesadvanceSimulationRoundon error — it usesmarkSimulationSessionError(), preservingcurrentRound.pauseandresumeredirect with&msg=no-sessionwhen there is no active session, without propagating an exception.MqttClientDataFlowInjector's adapter cache uses a composite keytype:path:maxClients:experimentIdto invalidate correctly when parameters change between sessions (BL-207 addedexperimentId).
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