The simulator: virtual devices
The simulator lets a developer create virtual devices in a sandbox tenant, put them into rooms, run scenarios, and remove them. Each virtual device behaves like a real device on the broker, so telemetry, status, and command handling appear in the same flows the API already uses. In the developer dashboard, you can see the device serial, connection state, active scenario, and the device ID, then change the scenario or delete the device.
What you can do
Section titled “What you can do”Virtual devices are created through the developer gateway and appear in your sandbox home. The page shows a create form with a profile selector and a room selector, then a list of your virtual devices. Each row shows:
- the device name
- the serial
- whether it is
connectedor still joining - the current scenario
- the scenario end time when one is set
- the device ID
After creation, the device registers through the same route hardware uses and appears in GET /v1/devices.
Create and remove devices
Section titled “Create and remove devices”Use POST /developers/simulator/devices to create a virtual device. The request body includes tenantId, propertyId, roomId?, profile, and name?. The page reads the available profiles from the simulator metadata when present, with HUB, SPEAKER, LIGHT, SENSOR, and THERMOSTAT as the supported choices shown in the UI.
Use DELETE /developers/simulator/devices/:id?tenantId= to remove a virtual device.
Creation is limited by the sandbox ceiling shown on the page. The default ceiling is 20. A sandbox tenant in the X band may hold virtual devices, and only its ADMIN may create one. A virtual device never joins a house.
Scenarios
Section titled “Scenarios”Use POST /developers/simulator/devices/:id/scenario to switch a device into a scenario. The request body includes tenantId, scenario, and optional seconds?.
The page shows these scenarios:
| Scenario | What the device does |
|---|---|
NORMAL | heartbeat and telemetry on schedule |
OFFLINE | says nothing but keeps the socket open; the platform grace window marks it offline |
LOW_BATTERY | battery telemetry falls to 8 percent |
SENSOR_ERROR | fault: sensor_error appears on the status channel, and the failed metric stops |
BURST | twenty telemetry messages a second, bounded by the tenant MQTT_MESSAGES quota |
FLAPPING | disconnects and reconnects every thirty seconds, so the last will fires each time |
SLOW | answers a command after five seconds |
A non-NORMAL scenario runs for five minutes and then reverts. If you restart the simulator container, each device comes back in the scenario it had when it stopped.
Access and sandbox rules
Section titled “Access and sandbox rules”The simulator creates devices only for the developer sandbox tenant associated with your session. It uses the sandbox credentials, not household access. Household permissions are narrower than staff permissions, and LIVE credentials only apply to their own installed connector. DEV credentials act in the developer sandbox.
A fresh sandbox starts with five virtual devices provisioned for verification: a hub and a speaker in the Living Room, a light in the Kitchen, a sensor in the Bedroom, and a thermostat in the Office. If the simulator is unavailable during verification, the verification does not fail; you can create the devices later from the dashboard.
Broker behavior
Section titled “Broker behavior”A virtual device is a real device on the real broker. It keeps a broker session, publishes retained availability, sends status on each heartbeat, sends telemetry on a period, and replies with a response to every command. Unknown commands are rejected.
The command envelope used by the console and phone is one shape inside the simulator, and developer code may also send the flat form. Commands include the platform form with { commandId, command, payload }, the thing envelope with set carrying { capability, key, value } or press carrying { key }, and the simulator responds to unsupported commands with rejected.
The device capabilities shown by the simulator follow the profile:
| Profile | Model | Capabilities | Telemetry | Commands |
|---|---|---|---|---|
| HUB | ALSIMH | VOICE, HUB | uptime, wake words, RSSI | identify, reboot, set listening |
| SPEAKER | ALSIMS | MEDIA_PLAYER | volume, playing | play, pause, next, set volume or muted |
| LIGHT | ALSIML | LIGHT | power, brightness, watts | set power, brightness, colorTemp |
| SENSOR | ALSIMN | SENSOR, BATTERY | temperature, humidity, battery | none |
| THERMOSTAT | ALSIMT | THERMOSTAT | setpoint, ambient, heating | set setpoint, mode |
A status report may include features, and the catalogue uses that to offer only the controls the device supports.
Limits and timing
Section titled “Limits and timing”The simulator follows the same quota and delivery limits as the platform:
- A device may see one
commandIdtwice and must treat it as once. - A command that is sent while the device is between sessions can be retried after the device is heard again, if it is still unanswered after 30 seconds.
- Retries happen up to five times and never past ten minutes.
- The broker dispatch sweep runs every two seconds.
OFFLINEis detected by the platform grace window, not by the simulator silently changing state.BURSTis limited by the tenantMQTT_MESSAGESquota.
Notes for developers
Section titled “Notes for developers”The simulator creates a device as a real registration, so serials follow the sandbox band and uniqueness rules used by the platform. It also preserves the device credential for that virtual device, and quota is counted where the messages are made.
If you are testing commands, telemetry, or liveness, the simulator is the way to do it without hardware. If you are testing connector behavior, the simulator covers device flow, liveness, telemetry, commands, and alerts, but not a separate simulated connector kind for virtual things and integrations.