The simulator: virtual devices

The simulator lets a developer create and operate virtual devices on the real broker. A virtual device is treated as a real device by the platform: it is registered through POST /devices/register, it has its own broker session and credential, and it emits the same kinds of messages a hardware device emits. A developer who has no ALYT hardware can still see telemetry arrive, send commands, and observe liveness and availability changes. This works in a sandbox only, and the house keeps working when the cloud is down; a household sees less than staff.

What a virtual device is

A virtual device is a Device row created the same way as hardware, with the developer’s claims forwarded when the pairing token is minted. Its serial is in the sandbox band, and from that point on the platform treats it like any other device. The broker credential is registered once and then belongs to that device. The simulator holds one broker session per virtual device.

From the outside, the device behaves like hardware in the places developers care about:

• retained availability with a last will
• status on heartbeat
• telemetry on a period
• response for each command

The device is visible through the developer gateway and through the same MQTT flows the rest of the platform uses.

Supported profiles and capabilities

The simulator exposes the profile set below. Each profile has a model, capabilities, telemetry, and commands.

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 developer sees the controls the device actually supports. If the device reports features: ["dim", ...], the bridge uses that to present matching controls. This avoids the case where the catalogue offers a control the device cannot honor.

Commands and responses

Commands arrive as the platform sends them: { commandId, command, payload }. The console and phone use a thing envelope with set and press, and developer code may send the flat form as well. These are the same shape inside the simulator.

An unknown command is answered rejected; it is never swallowed.

The simulator also handles the full command lifecycle on the broker side. A pending command is published, then marked as sent when it is delivered. If a command cannot be delivered because it has no property or it was already acknowledged, it becomes undeliverable. If broker delivery fails, it stays pending.

Scenarios

A developer can place a device into a scenario and watch its behavior change.

Scenario	What the device does
NORMAL	heartbeat and telemetry on schedule
OFFLINE	says nothing but holds the socket open; the platform’s grace window marks it offline
LOW_BATTERY	battery telemetry falls to 8 percent
SENSOR_ERROR	fault: sensor_error on the status channel, and the failed metric stops
BURST	twenty telemetry messages a second, bounded by the tenant’s 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 scenario can be temporary: seconds returns it to NORMAL afterwards. If the simulator container restarts, every device comes back in the scenario it was left in.

Routes under /v1

The simulator is exposed through the developer gateway under /v1.

Route	Scope
GET /developers/simulator/devices?tenantId=	simulator:write (or a session)
POST /developers/simulator/devices { tenantId, propertyId, roomId?, profile, name? }	simulator:write
POST /developers/simulator/devices/:id/scenario { tenantId, scenario, seconds? }	simulator:write
DELETE /developers/simulator/devices/:id?tenantId=	simulator:write

Only a tenant whose code is in the X band can hold a virtual device, and only its ADMIN can create one. A virtual device never joins a house.

The VIRTUAL_DEVICES ceiling limits how many virtual devices a sandbox can hold. The default is 20.

What a fresh sandbox starts with

Verification provisions five virtual devices: 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 down, verification does not fail; the developer creates the devices later from the dashboard.

What the simulator changes for the platform

Two platform gaps become visible the first time a virtual device runs:

• A queued command now gets published. POST /devices/:id/commands writes a pending CommandHistory row, and the bridge sweeps pending rows every two seconds, publishes each on the device’s commands topic, and marks it sent.
• A device can now report what it supports. Device.features can be carried in a status report, and the bridge writes it onto the row so the catalogue can show the controls the device honors.

What to know about credentials and quota

The simulator keeps the device credential in SimulatedDevice.state. The credential belongs to that device and reaches only that device’s own topics in a sandbox tenant. It does not give access to a house.

The MQTT quota is counted where the messages are made, in the simulator, using the same Redis key the gateway reads. If the quota is spent, the device goes silent and the event is logged.

Coverage and limits

Virtual devices cover the device flow, liveness, telemetry, commands, and alerts. They do not create a new connector kind. A SIMULATED connector kind is still owed so a sandbox can have virtual things and exercise integrations through the catalogue.