REST API Reference

The TR-069 Emulator exposes two REST controllers. Both are served on the same host/port (8555) and documented interactively in Swagger UI.

Overview

Base path UI mode Purpose

/api

Load Test Mode

Configure and run a batch of emulated CPEs; device-level speed/WiFi/invoke helpers.

/apiV2

Single Emulator Mode

Full per-device lifecycle: start/stop individual devices, browse and edit the parameter tree, trigger events, read logs. MCP-friendly.

Base URLs

http://localhost:8555/api      # Load Test controller
http://localhost:8555/apiV2    # Single Mode controller

Interactive Documentation

http://localhost:8555/swagger-ui.html   # Swagger UI
http://localhost:8555/v3/api-docs        # OpenAPI 3 spec (JSON)

For a lightweight liveness check use GET /api/status (returns 200 with Running/Stopped) or GET /apiV2/activeEmulators. The Spring Boot Actuator endpoints (/actuator/**) are not exposed by the running service.

Content Type

Request and response bodies are application/json unless noted otherwise (some endpoints return text/plain or application/octet-stream).

Load Test API (/api)

Backs Load Test Mode. The emulator keeps one shared configuration (the EmulatorParameter set, persisted to start_params.properties); Start launches a batch from it.

Configuration & Status

Method & Path Description Body / Response

GET /api/properties

Get the current emulator configuration

Response: EmulatorPropertiesDto

POST /api/properties

Update the configuration (ACS, batch size, options) and persist it

Body: EmulatorPropertiesDto → 204

GET /api/status

Current run status

text/plain: Running or Stopped

GET /api/periodic

Get the periodic-inform interval

Response: { "periodic": 30 }

POST /api/periodic

Set the periodic-inform interval (seconds)

Body: { "periodic": 60 } → 204

Lifecycle

Method & Path Description Body / Response

POST /api/start

Start the configured batch

no body → 204

POST /api/stop

Stop the batch

no body → 204

POST /api/stop

Stop the batch, optionally clearing caches

Body: { "clearCaches": true } → 204

Device Actions

All take a serial body: { "serial": "SERIAL001" }.

Method & Path Description

POST /api/invokeSerial

Trigger a 6 CONNECTION REQUEST event for the device (starts a session if not already in one)

POST /api/makeSpeedDelay

Apply a 3-second speed delay to the device

POST /api/resetDelay

Clear the speed delay for the device

POST /api/resetWifi

Reset WiFi parameters (channel and SNR) for the device

Parameter Tree Files

Method & Path Description Body / Response

GET /api/paramsXmlList

List XML files in parameterstree/

Response: ["cpe_params.xml", …​]

GET /api/paramsXml

Get the active device-tree file

Response: { "paramsXml": "cpe_params.xml" }

POST /api/paramsXml

Set the active device-tree file (reloads the tree)

Body: { "paramsXml": "cpe_params.xml" } → 204

POST /api/uploadParamsXml

Upload an XML file (form field file)

multipart/form-data → { success, message, filename }

POST /api/deleteParamsXml

Delete an XML file (not the active one)

Body: { "paramsXml": "old.xml" } → { success, message, filename }

Updatable Parameters

Method & Path Description Body / Response

GET /api/updatableParameters

Get the global auto-update list

Response: array of Parameter

POST /api/updatableParameters

Replace the global auto-update list

Body: array of Parameter → 204

Single Mode API (/apiV2)

Backs Single Emulator Mode. Operations are per device, addressed by serial. Designed to be automation/MCP friendly.

Configuration

Method & Path Description Body / Response

GET /apiV2/config

Frontend config (default ACS URL)

Response: { "defaultAcsUrl": "http://ftacs:8080/ftacs/ACS" }

Device Lifecycle

Method & Path Description Body / Response

POST /apiV2/start

Start a new device. Query saveConfig (default true) also stores the config.

Body: InitDeviceDto → { success, serial, message } (200/409)

POST /apiV2/stop

Stop and remove a running device

Body: { "serial": "FT001SN00001" } → 204

GET /apiV2/activeEmulators

List running devices

Response: array of { serial, manufacturer, productClass, oui, modelName, parameterFile, acsUrl, isRunning }

GET /apiV2/isEmulatorRunning?serial=

Is the device running?

Response: { serial, running }

GET /apiV2/sessionStatus?serial=

Is the device in an active TR-069 session?

Response: { serial, inSession }

POST /apiV2/reboot

Reset uptime and fire a 1 BOOT event

Body: { "serial": "…​" } → 204

POST /apiV2/factoryReset

Restart from stored config and fire 0 BOOTSTRAP

Body: { "serial": "…​" } → 204/404

POST /apiV2/cloneDevice

Copy a device config to a new serial

Body: { sourceSerial, newSerial } → InitDeviceDto (200/404)

GET /apiV2/deviceId?serial=

TR-069 DeviceId (Manufacturer, OUI, ProductClass, SerialNumber, …​)

Response: string map

GET /apiV2/statistics

Overall counts

Response: { activeEmulators, storedConfigurations, emulatorsInSession }

Stored Devices

Method & Path Description Body / Response

GET /apiV2/storedDevices

List saved configurations

Response: array of InitDeviceDto

GET /apiV2/storedDevice?serial=

Get one saved configuration

Response: InitDeviceDto (200/404)

POST /apiV2/saveDevice

Save a configuration without starting

Body: InitDeviceDto → 204

POST /apiV2/deleteStoredDevice

Delete a saved configuration

Body: { "serial": "…​" } → 204

POST /apiV2/startStored

Start from a saved configuration

Body: { "serial": "…​" } → { success, serial, message } (200/404/409)

POST /apiV2/startProtocol

Start from a base tree in parameterstree/base/ (TR-098 / TR-181)

Body: { protocol, serial?, acsUrl? } → StartResult (200/400/409)

Parameter Operations

Method & Path Description Body / Response

GET /apiV2/parameters?serial=

Full parameter tree (can be large)

Response: array of { name, value, type, notification, writable }

GET /apiV2/parametersByPrefix?serial=&prefix=

Parameters under a path prefix

Response: array of ParameterInfo

GET /apiV2/parameterNames?serial=&path=&nextLevel=

Names under a path (TR-069 GetParameterNames). nextLevel=true → immediate children only

Response: array of { name, isObject }

GET /apiV2/parameterValue?serial=&parameterName=

Single value lookup

Response: { name, value, type } (200/404)

GET /apiV2/parameterFullInfo?serial=&parameterName=

Full metadata for one parameter

Response: ParameterInfo (200/404)

GET /apiV2/parameterExists?serial=&pattern=

Existence check; {i} = numeric index, * = wildcard

Response: { exists, count, matchingParameters[] }

GET /apiV2/searchParameters?serial=&nameContains=&valueContains=&limit=

Search by name/value (default limit=100)

Response: array of ParameterInfo

POST /apiV2/changeParameter

Set one value (no ValueChange event)

Body: { serial, parameterName, parameterValue } → 204

POST /apiV2/changeParameters

Set many values; fires ValueChange if any has active notification

Body: { serial, parameters: { "Path": "value" } } → 200/204

POST /apiV2/setParameterValue

Set one value the way a real CPE does; fires a 4 VALUE CHANGE Inform if the parameter has active notification. Preserves the existing type.

Body: { serial, parameterName, parameterValue } → 200 (ValueChange fired) / 204

POST /apiV2/changeNotification

Set notification level: 0 off, 1 passive, 2 active

Body: { serial, parameterName, notification } → 204

POST /apiV2/addObject

Add an object instance (e.g. a new SSID)

Body: { serial, parentPath } → { instanceNumber, objectPath }

POST /apiV2/addParameter

Add one parameter; type/writable/notification resolved from the CWMP template

Body: { serial, name, value } → 204

POST /apiV2/deleteObject

Delete an object/branch and everything under it

Body: { serial, objectName } → 204

Events

Method & Path Description Body / Response

POST /apiV2/invoke

Trigger a TR-069 event (see TR-069 Event Codes)

Body: { serial, eventName } → 204/409

POST /apiV2/changePeriodic

Set the periodic-inform interval (seconds; 0 disables)

Body: { serial, value } → 204

Logs

Method & Path Description Body / Response

GET /apiV2/getLog?serial=

Download the full log file

application/octet-stream (200/404)

GET /apiV2/getLogContent?serial=&lines=&fromPosition=

Log content for live viewing; supports incremental reads

text/plain; header X-File-Position for the next read

GET /apiV2/logStatistics?serial=

Log counts

Response: { totalLines, fileSizeBytes, errorCount, warnCount, infoCount, debugCount }

POST /apiV2/clearLog

Clear the device log

Body: { "serial": "…​" } → 204/404

Updatable Parameters & Tree Files

Method & Path Description Body / Response

GET /apiV2/updatableParameters?serial=

Get the device’s auto-update list

Response: array of Parameter

POST /apiV2/updatableParameters

Set the device’s auto-update list

Body: { serial, parameters: [Parameter, …​] } → 204

GET /apiV2/paramsXmlList

List available parameter-tree templates

Response: ["cpe_params.xml", …​]

POST /apiV2/uploadParamTree

Upload a parameter-tree XML (form field file)

multipart/form-data → filename

TR-069 Event Codes

Used by POST /apiV2/invoke (eventName, case-sensitive — use the exact names below). See also Protocol Support — Event Codes.

Event Name Code Meaning

BootStrap

0

Initial setup / factory reset

Boot

1

Device reboot

Periodic

2

Scheduled inform

ValueChange

4

Parameter with active notification changed

ConnectionRequest

6

ACS-initiated connection request

TransferComplete

7

Download/upload completed

Diagnostics

8

Diagnostics complete

DUStateChangeComplete

11

Deployment-unit state change complete
The Single Mode Invoke Event dropdown exposes codes 0, 1, 2, 4, 6, 7, 8. DUStateChangeComplete (11) can only be triggered through this API, not from the dropdown.

Data Models

EmulatorPropertiesDto (/api)

Mirrors the EmulatorParameter set. Used by GET/POST /api/properties.

Field Type Example Description

protocol

string

http

ACS protocol (http/https)

host

string

localhost

ACS host

port

integer

8080

ACS port

url

string

ftacs/ACS

ACS URL path

groups

integer

1

Number of device groups

concurrent

integer

1

Devices per group

registrationGroup

integer

0

Registration group id

delay

integer

0

Delay between registrations (ms)

spread

integer

0

Startup spread

startDateTime

string

``

Scheduled start (DD-MM-YYYY HH24:MI:SS)

periodicInformEnabled

boolean

true

Enable periodic inform

connectionRequestEnabled

boolean

true

Enable Connection Request listener

withoutInitialInform

boolean

false

Skip the initial inform

randomRetryCount

boolean

false

Randomise retry counts

transferEmulation

boolean

false

Emulate Download/Upload transfers

transferEmulationDelay

string

0,100,500

Transfer delay(s)

loadingMode

boolean

false

Lightweight (inform-only) mode

fileLogEnabled

boolean

true

Per-device file logging

paramsXml

string

cpe_params.xml

Active parameter-tree file

taskDelayGetParameterValues

integer

11

GetParameterValues execution delay (s)

taskDelaySetParameterValues

integer

11

SetParameterValues execution delay (s)

taskDelayGetParameterNames

integer

11

GetParameterNames execution delay (s)

taskDelayGetParameterAttributes

integer

11

GetParameterAttributes execution delay (s)

taskDelaySetParameterAttributes

integer

11

SetParameterAttributes execution delay (s)

taskDelayAddObject

integer

11

AddObject execution delay (s)

taskDelayDeleteObject

integer

11

DeleteObject execution delay (s)

taskDelayDownload

integer

11

Download execution delay (s)

taskDelayUpload

integer

11

Upload execution delay (s)

taskDelayReboot

integer

11

Reboot execution delay (s)

taskDelayFactoryReset

integer

11

FactoryReset execution delay (s)

taskDelayChangeDuState

integer

11

ChangeDUState (TR-157) execution delay (s)

taskDelayGetRpcMethods

integer

11

GetRPCMethods execution delay (s)

Task execution delays hold the emulated CPE for the given number of seconds before it processes each ACS-issued RPC, modelling real-CPE "thinking time". The default is 11 seconds for every task type; set a value to 0 to disable the delay for that task. The delay is applied globally (all devices) and reactively (non-blocking). Kicked (Kick URL) is not emulated and therefore has no delay. For Download/Upload/ChangeDUState this delay is added on top of their transfer/DU-state emulation delays. When start_params.properties predates these keys (upgrade from a version before 5.0.1), the defaults apply automatically and are listed in a single log line at startup — sessions that used to complete near-instantly will now take ~11 seconds per RPC until the delays are tuned or set to 0.

InitDeviceDto (/apiV2)

Used by start, saveDevice, cloneDevice and the storedDevices responses.

Field Type Example Required Description

serial

string

FT001SN00001

Yes

Unique device serial

acsUrl

string

http://localhost:8080/acs

No

ACS URL (defaults to DEFAULT_ACS_URL)

parameterFile

string

cpe_params.xml

No

Tree file from parameterstree/

enableHttpConnectionRequest

boolean

true

No

Start the per-device CR listener

updatableParameters

array

see Parameter

No

Auto-updating parameters

running

boolean

true

No

Managed by the system

Parameter (auto-update entry)

Field Type Description

name

string

Full parameter path

type

INT | BOOL | STRING

Data type (default INT)

stepType

RANDOM | INCREMENT | DECREMENT | DEFAULT

Update mode (default DEFAULT)

min / max

integer

Value range (numeric types)

step

integer

Step size for increment/decrement

array

string[]

Optional fixed value set

Error Handling

Standard HTTP status codes are used:

Status Meaning

200 OK

Success with a response body

204 No Content

Success, no body (most mutations)

400 Bad Request

Invalid parameters or file

404 Not Found

Device, parameter or stored config not found

409 Conflict

Operation conflicts with current state (e.g. already running, device in session)

500 Internal Server Error

Unexpected server error

Error responses, where a body is returned, use:

{ "error": "Error message description" }