/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

External Simulators

Keywords on this page
WordMeaningExample
SimulatorA program that pretends to be real hardware, for local runsaq-simulator
TickOne round: every sensor of one building reads onceEvery 10 s
ubusThe call interface of an OpenWrt routerPOST /<sensorId>/ubus
StationA phone connected to a router(mac, rssi)
RSSIHow loud a phone is at a router, in dBm. Closer to 0 is louder−62 dBm
ProbeA short call a phone sends while looking for networksHeard up to −92 dBm

Ambitwin ships three simulators. They are not microservices: they stand in for hardware that, at a real site, sits outside the cluster.

SimulatorLocationImagePretends to be
Sensorsimulators/sensor-simulator/, Nodeambitwin-simulatorThermostats (temperature), people counters (peopleCount)
Air qualitysimulators/aq-simulator/, Pythonambitwin-aq-simulatorAir-quality stations (airQuality)
Routerssimulators/ap-simulator/, Pythonambitwin-ap-simulatorOpenWrt routers (router), polled by devices/ap-collector

Why simulators stay outside the cluster


What is simulated

Exactly the sensors placed in the digital twin. A simulator starts empty and simulates only what telemetry sends it at start.

Device kindSimulatorEach tick, per sensor
temperaturesensor-simulatorOne temperature reading, in the sensor’s room
peopleCountsensor-simulatorOne peopleCount reading, in the sensor’s room
airQualityaq-simulatorOne airQuality reading, in the sensor’s room, with its own drifting state
routerap-simulatorNo reading: it answers ubus calls with station lists. ap-collector turns them into a Wi-Fi tick, and telemetry counts it into totalDeviceCount and ratioDeviceCount

Start and run

  1. A user with the right to edit the building presses Start simulator: PUT /telemetry/simulation/buildings/{id}.
  2. telemetry reads the building’s sensors and splits them by device kind, using SIMULATORS.
  3. telemetry sends each simulator POST /control/start with its share. An empty list stops that building.
  4. sensor-simulator and aq-simulator send one signed batch every 10 s to their TELEMETRY_INGEST_URL.
  5. ap-simulator only answers. ap-collector asks it, every 5 s.
sequenceDiagram
    autonumber
    participant UI as dashboard, browser
    participant T as telemetry
    participant S as sensor-simulator
    participant A as aq-simulator
    participant P as ap-simulator
    participant W as digital-twin
    participant C as ap-collector

    UI->>T: PUT /telemetry/simulation/buildings/b1
    T->>T: read b1's sensors, split by kind
    par
        T->>S: POST /control/start, b1, thermostats and people counters
    and
        T->>A: POST /control/start, b1, air-quality stations
    and
        T->>P: POST /control/start, b1, routers
        P->>W: rooms and router positions of b1
    end
    T-->>UI: 204

    loop every 10 s
        S->>T: POST /telemetry/ingest, signed batch
        A->>T: POST /telemetry/ingest, signed batch
    end
    loop every 15 s
        C->>T: GET /telemetry/collector, which routers exist
    end
    loop every 5 s
        C->>P: POST /sensorId/ubus, station list of each router
        C->>T: POST /telemetry/observations, signed Wi-Fi tick
    end
StepData
1Only the building id. telemetry checks the caller may edit it
3–5{ buildingId, sensors: [{ sensorId, sensorType, roomId }] }, pinned by schemas/fixtures/simulation-start.json
6Room boxes and, when placed, router positions. A failed read answers 502
8, 9{ buildingId, readings: [...] }, signed with TELEMETRY_INGEST_SECRET
12One building’s stations per router, signed with the building’s key or TELEMETRY_INGEST_SECRET

Stop (DELETE) tells every simulator to drop the building. Status (GET) is running when any simulator runs it. The browser never calls a simulator.


Control API

Called by telemetry only. Every simulator’s tests assert the same start body.

MethodEndpointBodyEffect
POST/control/start{ buildingId, sensors: [{ sensorId, sensorType, roomId }] }Replaces what the building simulates. Empty sensors stops it. Any other key, like a URL or a coordinate, is refused
POST/control/stop{ buildingId }Stops the building. Stopping one never simulated succeeds
GET/control/status?buildingId=X—{ isRunning }

The router simulator

It fakes the routers, not their readings. Stations still travel router → ap-collector → Wi-Fi tick → telemetry, so the real counting runs on simulated data.

Routers

People

SettingDefaultMeaning
AP_SIM_PHONES_PER_ROOM4Phones per room
AP_SIM_PASSERSBY_PER_HOUR30People walking past outside, heard through the walls
AP_SIM_PROBE_RANDOM_MAC_FRACTION1.0Share of probes sent with a random address, as phones do

Signal

Path loss with walls and floors, then noise.

NumberValue
Loudness at 1 m−40 dBm
Path loss exponent2.2
Each wall−5 dB
Each floor slab−18 dB
Slow shadowingσ 4 dB, changes over 30 s
Fast fadingσ 2 dB per poll
Gain spread, router / phone±3 dB / ±4 dB
Phone joins a routerat −82 dBm or louder
Phone roamsbelow −72 dBm, to a router 8 dB louder
Phone dropsbelow −88 dBm
Router forgets an idle phoneafter 300 s
Probe heardat −92 dBm or louder

Example, from the defaults before noise. A phone 10 m from a router:

Hand tests

EndpointDoes
POST /debug/kill/{ap}The router stops answering, with 503
POST /debug/revive/{ap}It answers again
GET /debug/ground-truth?buildingId=XWhere every phone really is, to score an estimate against

What ap-collector reads in dev

devices/ap-collector/collector.dev.json:

KeyValueMeaning
pollIntervalS5Station lists asked every 5 s
syncIntervalS15Router list read from telemetry every 15 s
endpointTemplatehttp://ap-simulator:3000/{sensorId}/ubusSimulated routers have no address of their own, so this fills it
ubuscollector / collectorRouter login
subscribeProbestrueListen to probe events too

Stop. ap-simulator drops the building, so its routers stop answering. The next Wi-Fi tick lists none of them as answered, and telemetry stores nothing for those rooms.


Configuration

VariableRead byDefaultPurpose
TELEMETRY_INGEST_URLsensor, air qualityhttp://gateway/telemetry/ingestWhere readings go. Set by the simulator’s own environment, never by a caller
TELEMETRY_INGEST_SECRETsensor, air qualityemptyThe shared key that signs for any building. Dev only
DIGITAL_TWIN_URLroutershttp://digital-twin:3000Where the building’s rooms come from
AP_SIM_*routerssee PeopleCrowd size and probe addresses
TELEMETRY_SERVICE_URLap-collectorhttp://gateway/telemetryBase for /collector and /observations
TELEMETRY_SERVICE_SECRETap-collectorTELEMETRY_INGEST_SECRETSigns the Wi-Fi tick

sensor-simulator’s numbers are fixed in simulatorService.ts; a change needs a new image.

ParameterDefaultMeaning
delay10000 msTime between batches
peopleCountRange0 to 50Random headcount per people counter per tick
temperatureRange18.0 to 30.0Random °C per thermostat per tick, 2 decimals

aq-simulator’s physics, scenarios and sensor errors live in physics.py, scenarios.py and errors.py. Its tick is 10 s.


Running the simulators

The three simulators and ap-collector all start with just stack dev.

just stack dev --no-simulators   # skip the three simulators; ap-collector still runs
just stack dev --no-devices      # skip ap-collector
just stack dev aq                # skip only the air-quality simulator

Alone, against a stack on the host:

docker run -p 3001:3000 --add-host host.docker.internal:host-gateway \
  -e TELEMETRY_INGEST_URL=http://host.docker.internal/telemetry/ingest \
  -e TELEMETRY_INGEST_SECRET=<secret> \
  ghcr.io/nickghignatti/ambitwin-simulator:latest

Gaps