REST API Reference
The IoT Emulator provides a comprehensive REST API for automation and integration.
Endpoints
Status & Control
Get Status
Returns the current emulator status.
GET /api/statusResponse:
{
"protocol": "LWM2M",
"initialized": true,
"started": true,
"deviceCount": 5
}Get Version Info
Returns build and version metadata, backed by Spring Boot BuildProperties and GitProperties. Git fields are best-effort and may be null when the JAR is built outside a Git working tree.
GET /api/versionResponse:
{
"version": "v.7.0.5 b.0.0.26",
"productVersion": "7.0.5",
"buildVersion": "0.0.26",
"buildTime": "2026-06-05T10:15:30Z",
"name": "iot-emulator",
"artifact": "gui",
"group": "com.friendly.emulator",
"commit": "1fc5cf5e...",
"commitShort": "1fc5cf5",
"commitTime": "2026-06-04T22:53:00Z",
"branch": "emul_docker"
}Configuration
Get Configuration
GET /api/configResponse:
{
"protocol": "USP",
"serverIp": "192.168.1.100",
"serverPort": 5683,
"clientId": "device-001",
"serialNumber": "SN12345",
"manufacturer": "MyCompany",
"modelName": "Model1",
"clientIp": "0.0.0.0",
"clientPort": 56830,
"clientsCount": 1,
"concurrentClients": 1,
"delaySec": 1,
"securityMode": "NONE",
"pskId": "",
"pskKey": "",
"authKeyStorePath": "",
"authKeyStorePass": "",
"trustStorePath": "",
"trustStorePass": "",
"authCertAlias": "",
"aliasPass": "",
"mtp": "STOMP",
"guiRenderingType": "FULL",
"paramUpdateEnabled": true,
"loggingEnabled": true,
"failResponse": false,
"dbAddress": "localhost",
"dbPort": 3306,
"dbLogin": "root",
"dbPassword": "",
"dbCatalog": "acs",
"dbCpeSerial": ""
}Update Configuration
Persists the supplied fields to gui_connection_options.properties. Rejected with 400 while the emulator is initialized or started.
POST /api/config
Content-Type: application/json
{
"serverIp": "192.168.1.100",
"serverPort": 5683,
...
}Update Runtime Options
Sub-set of /api/config that is allowed while the emulator is running. Covers the footer toggles (rendering type, logging, fail response, param update) and is also called from onchange handlers so changes take effect immediately.
POST /api/config/runtime
Content-Type: application/json
{
"guiRenderingType": "FULL",
"paramUpdateEnabled": true,
"loggingEnabled": true,
"failResponse": false
}guiRenderingType must be one of FULL, LAZY, OFF (matches the desktop GuiRenderingType enum).
Devices
List Devices
GET /api/devicesResponse:
[
{
"clientId": "device-001",
"serialNumber": "SN12345",
"clientPort": 56830,
"manufacturer": "MyCompany",
"modelName": "Model1"
}
]Get Device by Client ID
Returns detailed information about a single device, including its full parameter list. Responds 404 when no device with the given clientId is active.
GET /api/devices/{clientId}Response:
{
"clientId": "device-001",
"serialNumber": "SN12345",
"clientPort": 56830,
"manufacturer": "MyCompany",
"modelName": "Model1",
"status": "REGISTERED",
"protocol": "LWM2M",
"parameters": [
{ "name": "Device.DeviceInfo.Manufacturer", "value": "MyCompany", "type": "string" }
]
}Update Device Parameter Value
PUT /api/devices/{clientId}/parameters/{paramName}
Content-Type: application/json
{
"value": "42"
}Get Autoupdate Config
Returns the current autoupdate configuration for a parameter.
GET /api/devices/{clientId}/parameters/{paramName}/autoupdateResponse:
{
"autoupdatable": true,
"global": false,
"min": 0,
"max": 1000,
"step": 1,
"stepType": "INCREASE",
"period": 3000,
"deviation": 0,
"randomizeStepType": false,
"dataset": ""
}Apply Autoupdate Config
Schedules / reschedules / removes the autoupdater for a single parameter (or for every device when global=true).
POST /api/devices/{clientId}/parameters/{paramName}/autoupdate
Content-Type: application/json
{
"autoupdatable": true,
"global": false,
"min": 0,
"max": 1000,
"step": 1,
"stepType": "INCREASE",
"period": 3000,
"deviation": 0,
"randomizeStepType": false,
"dataset": "10|20|30"
}When dataset is non-empty it overrides min/max/step/stepType. stepType is one of INCREASE, DECREASE, RANDOM.
Snapshot
Save Snapshot
Writes the current device list and parameter values to configuration/snapshot.json.
POST /api/snapshot/saveReturns 204 on success, 400 when there are no devices to snapshot.
Load Snapshot
Restores the device list and parameter tree from configuration/snapshot.json and re-initializes the emulator session. The emulator must be stopped/reset before calling.
POST /api/snapshot/loadReturns 204 on success, 404 when the snapshot file is missing, 400 when the emulator is not idle.
Rules (JS hook on parameter updates)
Get Current Rule
Returns the JavaScript body of function onParamUpdated(param, device, ctx) persisted in configuration/rules.js.
GET /api/ruleResponse:
{
"code": "var p = device.params.get('Foo'); p.updatable = false;",
"status": "ok"
}Compile & Save Rule
Compiles the supplied JavaScript via the emulator’s rule engine and writes it to configuration/rules.js. Returns 200 with status: "ok" on success, 400 with status: "error" and a populated error field on compilation failure.
POST /api/rule
Content-Type: application/json
{
"code": "if (param.name == 'X') { device.params.get('Y').updatable = false; }"
}Logs
The Logs endpoints expose the in-memory ring buffer (capacity ≈ 500 entries) of raw protocol messages observed by the emulator.
Poll Logs
Returns entries with sequence number strictly greater than since, plus the highest seq present so the client can advance its cursor.
GET /api/logs?since=0Response:
{
"lastSeq": 42,
"entries": [
{
"seq": 42,
"time": "12:34:56.789",
"deviceName": "device-001",
"direction": "IN",
"event": "registration",
"messageOptions": "GET /3/0/0 block1 {empty}",
"payload": "{...}",
"rawMessage": "..."
}
]
}For incremental polling, call with since=<lastSeq> from the previous response. On an empty batch, lastSeq is still advanced to the current server seq so the next poll skips already-seen entries.