Variables¶

Read and write PLC variables by symbol path. Requires feature flag Variables enabled.

Read Variable¶

Endpoint: Read Variable API_VARIABLES_READ

status: implemented

component: Variables

method: GET

route: /api/plcs/{plcId}/variables/{symbolPath}

policy: ReadAccess

implements: FEAT_VARIABLES

Requires role >= viewer and scope ads:read.

curl http://localhost:5000/api/plcs/Line1/variables/MAIN.nCounter

{
  "data": { "symbol": "MAIN.nCounter", "value": 42, "typeName": "UDINT" },
  "error": null
}

Batch Read¶

Endpoint: Batch Read API_VARIABLES_BATCH_READ

status: implemented

component: Variables

method: GET

route: /api/plcs/{plcId}/variables?paths={symbolPath}

policy: ReadAccess

implements: FEAT_VARIABLES

Reads multiple variables in one request. Maximum 100 symbols per request.

Each symbol is read independently: one unreadable symbol does not fail the whole request. The response is always 200, and each entry under values carries either its value/typeName on success, or a non-null error describing why that one symbol failed — the other symbols in the same batch are unaffected.

curl "http://localhost:5000/api/plcs/Line1/variables?paths=MAIN.a&paths=MAIN.b&paths=MAIN.typo"

{
  "data": {
    "values": {
      "MAIN.a": { "symbol": "MAIN.a", "value": 1, "typeName": "UDINT" },
      "MAIN.b": { "symbol": "MAIN.b", "value": 2, "typeName": "UDINT" },
      "MAIN.typo": { "symbol": "MAIN.typo", "value": null, "typeName": null, "error": "Symbol 'MAIN.typo' not found." }
    }
  },
  "error": null
}

Write Variable¶

Endpoint: Write Variable API_VARIABLES_WRITE

status: implemented

component: Variables

method: PUT

route: /api/plcs/{plcId}/variables/{symbolPath}

policy: WriteAccess

implements: FEAT_VARIABLES, REQ_SEC_SYMBOL_GUARD, REQ_SEC_VALUE_CONSTRAINTS, REQ_SEC_WRITE_AUTH

Requires role >= operator and scope ads:write.

curl -X PUT http://localhost:5000/api/plcs/Line1/variables/MAIN.nCounter \
  -H "Content-Type: application/json" \
  -d '{"value": 100}'

Batch Write¶

Endpoint: Batch Write API_VARIABLES_BATCH_WRITE

status: implemented

component: Variables

method: PUT

route: /api/plcs/{plcId}/variables

policy: WriteAccess

implements: FEAT_VARIABLES, REQ_SEC_SYMBOL_GUARD, REQ_SEC_VALUE_CONSTRAINTS, REQ_SEC_WRITE_AUTH

Maximum 100 symbols per request.

curl -X PUT http://localhost:5000/api/plcs/Line1/variables \
  -H "Content-Type: application/json" \
  -d '{"values": {"MAIN.a": 1, "MAIN.b": 2}}'

Value Constraints¶

Endpoint: Get Value Constraints API_VARIABLES_CONSTRAINTS

status: implemented

component: Variables

method: GET

route: /api/plcs/{plcId}/constraints/{symbolPath}

policy: ReadAccess

implements: FEAT_VARIABLES, REQ_SEC_VALUE_CONSTRAINTS

Returns the configured validation constraints for a symbol, including Min, Max, Enum, Pattern, and ReadOnly fields. If no constraints are configured for the symbol, the response contains empty/null fields.

curl http://localhost:5000/api/plcs/Line1/constraints/MAIN.nSpeed

{
  "data": { "symbol": "MAIN.nSpeed", "min": 0, "max": 100, "enum": null, "pattern": null, "readOnly": false },
  "error": null
}

Writes are validated against these constraints. A write that violates a constraint returns 400 with error code VALUE_OUT_OF_RANGE.

Symbol Access Control¶

Write operations are checked against the symbol access guard configured per PLC (see Configuration). If a symbol is denied by the allowlist/denylist rules, the API returns 403 with error code SYMBOL_WRITE_DENIED.