REST API Reference

Returns the current emulator status.

Response:

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.

Response:

Initialize the device tree.

Responses:

Start device simulation.

Responses:

Stop device simulation.

Responses:

The stop also stops the devices added to the session one by one (POST /api/devices, POST /api/devices/batch and the stored devices /api/init recreates) and frees their ports; only devices started on their own with POST /api/devices/startNew or POST /api/storedDevices/{clientId}/start keep running.

Reset to initial state.

Responses:

The API has no authentication, so a stored secret is never handed back: pskKey, authKeyStorePass, trustStorePass, aliasPass and dbPassword are reported as * when something is stored, and as the empty string when nothing is. See Secrets.

Response:

Persists the supplied fields to gui_connection_options.properties. Rejected with 400 EMULATOR_NOT_STOPPED while the emulator is initialized or started.

For the five secret fields listed under Secrets, * means "keep the stored value" — which is what a form posts back when the password field was not touched. An empty string clears the secret, anything else replaces it.

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.

guiRenderingType must be one of FULL, LAZY, OFF (matches the desktop GuiRenderingType enum).

Query parameters:

Responses: 204 set · 400 EMULATOR_NOT_STOPPED while the emulator is initialized or running · 400 PROTOCOL_NOT_FOUND for a protocol the emulator has not loaded.

Each option carries a secret flag, taken from the $<key>.secret=true line of the protocol’s <protocol>_gui.properties. A free-text option flagged secret — the MQTT password, the USP secret, the LwM2M OSCORE master secret — reports its value as * instead of what is stored. An option with a fixed list of choices is not masked: it publishes every one of its choices anyway, so masking the selected one would hide nothing and leave the control matching none of them.

For a key flagged secret, means "keep the stored value", an empty string clears it and anything else replaces it. For every other key is stored literally — swallowing it there would be a silent edit. Answers 204, or 400 BAD_REQUEST when no option map arrives or an option value is null; nothing is applied then.

Returns the transport (or MTP) selector of the current protocol together with the ports declared for each transport — this is what the Single Emulator form renders above Server Port. Protocols without a transport selector (MQTT, FSH_HUB, DUSUN) return an empty object.

Response (LWM2M):

For USP the key is mtp and the options are STOMP, CoAP, WebSocket and MQTT.

Response:

connection says whether the device is connected to its server now, as the device’s own protocol reports it. It is on every entry of this list and on GET /api/devices/{clientId}, and takes one of three values:

What each protocol counts as its server’s confirmation, and what clears it:

status is the device’s own status line as its protocol stack writes it (SN12345→registered, dev-1 → no connection, an exception message): free text that reads differently in every protocol, kept for people to read. To tell whether a device is connected, read connection, not status — an MQTT device’s status goes on reading connected after the broker has dropped it.

Returns detailed information about a single device, including its full parameter list. Responds 404 DEVICE_NOT_FOUND when no device with the given clientId is active.

Response:

Responses: 204 sent · 404 DEVICE_NOT_FOUND.

Responses: 200 the parameters · 404 DEVICE_NOT_FOUND.

Sends a LwM2M deregistration (CoAP DELETE /rd) for every running LwM2M device and stops it. Use this to let an external test (for example the ACS e2e rig) validate the ACS deregister handling on demand. Without this endpoint, the only way to stop devices was a process teardown, which may not send a clean DELETE /rd.

Request: no body.

Example:

With ?details=true (POST /api/lwm2m/deregister?details=true) a successful call answers 200 OK with the devices it deregistered instead of 204; nothing else changes, and with no running LwM2M device it answers the same 409:

Responses:

Returns the current autoupdate configuration for a parameter.

Response:

Responds 404 PARAMETER_NOT_FOUND when the device has no such parameter, or there is no such device.

Schedules / reschedules / removes the autoupdater for a single parameter (or for every device when global=true).

When dataset is non-empty it overrides min/max/step/stepType. stepType is one of INCREASE, DECREASE, RANDOM.

The parameter is found on the device itself, so this works in the web service and for devices started from Single mode. A parameter is rescheduled at once when its device is running; otherwise the setting is kept for the next start.

Responses: 204 applied · 400 BAD_REQUEST — no body, an invalid value, or no such device or parameter · 400 AUTOUPDATE_FAILED — the autoupdater could not be applied.

The values a parameter has taken on the device, oldest first, up to the last 50, each with the time it was recorded. Values are recorded while Param rendering is FULL or LAZY; with OFF nothing is recorded and recorded is false.

Response:

Responses: 200 the history · 404 DEVICE_NOT_FOUND — no such device · 404 PARAMETER_NOT_FOUND — the device has no parameter by that name.

Creates, initializes and starts one device from a template and persists it to storage. The emulator does not have to be initialized first.

Request body (DeviceTemplateDto) — only clientId is required; every other field falls back to the global configuration:

For securityMode: "X509" use authKeyStorePath, authKeyStorePass, trustStorePath, trustStorePass, authCertAlias and aliasPass instead of the PSK pair. protocolOptions keys match the protocol’s <protocol>_gui.properties.

pskKey, authKeyStorePass, trustStorePass, aliasPass and any secret protocolOptions entry accept *, which leaves the field unset so the device inherits the configured value — see Secrets. The same applies to POST /api/devices/batch.

Responses:

Starts a device that was stopped.

Responses: 204 started · 400 DEVICE_START_FAILED · 404 DEVICE_NOT_FOUND.

Stops one running device without affecting the others. Its stored configuration is kept.

Responses: 204 stopped · 400 DEVICE_STOP_FAILED · 404 DEVICE_NOT_FOUND.

Stops the device and removes it from both the active list and the persistent storage. A client ID that is only present in storage can be deleted too.

Responses: 204 deleted · 400 DEVICE_DELETE_FAILED · 404 DEVICE_NOT_FOUND, a client ID known neither as an active nor as a stored device.

Points a single device at a different server. Only non-empty fields are applied (serverPort must be greater than 0).

Responses: 204 updated · 404 DEVICE_NOT_FOUND.

Creates one device in an already initialized emulator, optionally against its own server. The device starts with the next POST /api/start.

Responses: 200 the created device · 400 NOT_INITIALIZED, DEVICE_ALREADY_EXISTS or DEVICE_CREATION_FAILED.

Creates several devices at once, each from its own DeviceTemplateDto (same fields as Create and Start a Device). The emulator must be initialized.

Responses: 200 the list of created devices · 400 NOT_INITIALIZED or DEVICE_CREATION_FAILED (and BAD_REQUEST for a template, as for Create and Start a Device).

Returns the list of stored DeviceTemplateDto entries, with their secrets masked: pskKey, authKeyStorePass, trustStorePass, aliasPass, and any protocolOptions entry whose key the template’s protocol declares secret, all come back as *.

A stored record whose protocol names none of the emulator’s protocols does not fail the list. Its protocol’s option declarations cannot be read, so its protocolOptions are masked by name alone: a key containing password, passwd, psw, secret or pskkey, in any case, comes back as *.

Loads a configuration from storage, recreates the device and starts it.

Responses: 200 the started device · 400 DEVICE_START_FAILED · 404 STORED_DEVICE_NOT_FOUND.

Responses: 204 removed · 404 STORED_DEVICE_NOT_FOUND. The running device with the same ID, if any, is not touched.

Empties devices.json.

Response: 204.

Runs /crts and /sen with the factory certificate of the device. The emulator cancels the pending automatic task and plans the next task from the result. After a successful enrollment, a running device restarts once to connect with the EST certificate.

The request has no body.

Response 200: the EST status JSON. See EST status.

A VALIDATION failure can have the reason leaf-expired. The server issued a leaf that is already past notAfter by the clock of the emulator. The emulator keeps the current certificate and the pending key.

The kind is one of REFUSED, UNAVAILABLE, HANDSHAKE, PIN_MISMATCH, TIMEOUT, CONFIG, VALIDATION. A CONFIG failure gives 409 with the reason token only. The reason contains only the characters A-Z, a-z, 0-9, ., _, -, and at most 64 characters. An unexpected internal error gives 502 TIMEOUT unexpected-error.

Runs /crts and /sren with the current EST certificate. A successful re-enrollment restarts a running device once.

The request has no body. The response is the same as for Enroll, with one more token.

Returns the EST state of the endpoint. The state survives a restart of the device, stop, and the re-creation of the device.

Response 200:

Answer 200 also for a device that never started. Most fields are then null or empty. The emulator computes the status when you send the request. The fields enrolled and the certificate fields use the current effective EST address, the current pin, and the current clock. A new certificate appears in the status only together with its operation, outcome, CA list, and next plan. If the fleet address or pin changes, or if notAfter passes, the status shows not enrolled without a restart. The status of a stopped device shows the est/options overrides immediately.

Overrides EST options for this device only. The emulator sends nothing and does not restart the device.

The body is a JSON map with string values. Allowed keys:

Rules:

Returns available MTP types and their port suggestions.

mtpType is one of STOMP, CoAP, WebSocket, MQTT. NOTE: The Web GUI sets MTP through the Protocol Options tab (/api/protocolOptions) — this endpoint is primarily for scripting / Swagger.

Responses: 200 the ports of that MTP type · 400 EMULATOR_NOT_STOPPED while the emulator is initialized or running · 400 INVALID_MTP_TYPE for a type with no ports configured.

Writes the current device list and parameter values to configuration/snapshot.json.

Returns 204 on success, 400 NOTHING_TO_SAVE when there are no devices to 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.

Returns 204 on success, 404 SNAPSHOT_NOT_FOUND when the snapshot file is missing, 400 BAD_REQUEST when the emulator is not idle.

Returns the JavaScript body of function onParamUpdated(param, device, ctx) persisted in configuration/rules.js, together with engineAvailable — whether this runtime has a JavaScript engine at all.

status is error, with error, when the rules.js found at startup did not compile — no rule is active then. lastRuntimeError is the last failure of the active rule while it ran.

Response:

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.

Returns 501 with code RULES_UNAVAILABLE only when the runtime has no JavaScript engine. The emulator ships the standalone Nashorn engine, so this means its jar is missing from the classpath.

Returns the human-readable help text shown by Help in the Rules dialog and in the desktop Rules tab.

Reads the parameters of the CPE with the given serial, for the selected protocol, from the ACS database and writes them over the active device tree file. Initialize tree then loads them. dbPassword "*" means the stored password.

Response:

Responses: 200 written · 400 BAD_REQUEST — DB address or CPE serial missing, or no protocol selected · 400 EMULATOR_NOT_STOPPED — the emulator is initialized or running · 404 CPE_NOT_FOUND · 422 EXTRACT_FAILED — the database could not be read or the file could not be written · 501 EXTRACT_UNAVAILABLE — the emulator cannot read this protocol’s trees from the database (CoAP, DUSUN).

Returns entries with sequence number strictly greater than since, plus the highest seq present so the client can advance its cursor.

Response:

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.

Empties the server-side ring buffer. The seq counter is not reset — instead the response returns the current seq so the client can resync.

Response:

A file of the same name is overwritten — except when it is the device tree of an initialized session, which answers 409 CONFIG_FILE_IN_USE: that tree is held in memory and re-read per device, so replacing it would leave the session and the file describing two different device trees under one name. Stop the emulator first.

Only a device tree can be deleted: filename is the bare name of an .xml file in the configuration directory, as GET /api/configFiles lists it. Anything else answers 400 BAD_REQUEST in the error body before any file is looked up — another kind of file kept there (devices.json, rules.js, a <protocol>_gui.properties), a path separator (/ or \), .., a drive letter, or . and .. themselves.

Deleting the file the emulator loads as its device tree answers 409 CONFIG_FILE_ACTIVE; select another file first. The check is made on the name before the file is looked up, so it applies whether or not the emulator is initialized.