Device API¶

Read and write device tag values, execute operator commands, and query alarm states. Device operations are routed through Orleans grains — each device instance is managed by a DeviceInstanceGrain on the site server.

Info

Device API endpoints are served by the site server, not the cloud API. The base URL is your site server address (e.g. https://mt-arthur.consystence.site or https://localhost:5000 in development).

List Device Instances¶

GET /api/sites/{siteId}/devices¶

List all device instances at a site.

Response (200):

{
  "data": [
    {
      "id": "pump-01",
      "name": "Pump 1",
      "typeId": "consystence.pump.centrifugal",
      "typeVersion": "1.2.0",
      "location": "Sump Room North",
      "processId": "demo-pump-station",
      "status": "running"
    },
    {
      "id": "pump-02",
      "name": "Pump 2",
      "typeId": "consystence.pump.centrifugal",
      "typeVersion": "1.2.0",
      "location": "Sump Room North",
      "processId": "demo-pump-station",
      "status": "stopped"
    }
  ]
}

Get Device Instance¶

GET /api/sites/{siteId}/devices/{deviceId}¶

Returns full device details including current tag values, active alarms, and configuration.

Response (200):

{
  "id": "pump-01",
  "name": "Pump 1",
  "typeId": "consystence.pump.centrifugal",
  "typeVersion": "1.2.0",
  "location": "Sump Room North",
  "processId": "demo-pump-station",
  "status": "running",
  "tags": {
    "Running": { "value": true, "timestamp": "2026-02-18T10:30:00Z" },
    "Faulted": { "value": false, "timestamp": "2026-02-18T10:30:00Z" },
    "Speed": { "value": 1485.2, "unit": "RPM", "timestamp": "2026-02-18T10:30:01Z" },
    "Current": { "value": 42.7, "unit": "A", "timestamp": "2026-02-18T10:30:01Z" },
    "BearingTempDE": { "value": 58.3, "unit": "°C", "timestamp": "2026-02-18T10:30:01Z" },
    "BearingTempNDE": { "value": 55.1, "unit": "°C", "timestamp": "2026-02-18T10:30:01Z" }
  },
  "activeAlarms": []
}

Read Tag Values¶

GET /api/sites/{siteId}/devices/{deviceId}/tags¶

Read current values for all tags on a device instance.

GET /api/sites/{siteId}/devices/{deviceId}/tags/{tagName}¶

Read a single tag value.

Response (200):

{
  "name": "Speed",
  "value": 1485.2,
  "dataType": "real",
  "unit": "RPM",
  "timestamp": "2026-02-18T10:30:01Z",
  "quality": "good"
}

Write Tag Values¶

PUT /api/sites/{siteId}/devices/{deviceId}/tags/{tagName}¶

Write a value to a writable tag. Requires Operator role or higher.

Request:

{
  "value": 1600.0
}

Response (200):

{
  "name": "SpeedSetpoint",
  "value": 1600.0,
  "previousValue": 1500.0,
  "timestamp": "2026-02-18T10:31:00Z"
}

The write is forwarded through the DeviceInstanceGrain → EdgeDeviceGrain → PLC. The response confirms the value was accepted.

Execute Commands¶

POST /api/sites/{siteId}/devices/{deviceId}/commands/{commandId}¶

Execute an operator command on a device instance. Requires Operator role or higher.

Request:

{}

For commands with parameters (e.g. set_speed):

{
  "parameters": {
    "speed": 1600.0
  }
}

Response (200):

{
  "commandId": "start",
  "deviceId": "pump-01",
  "status": "executed",
  "executedBy": "operator@bhp.com",
  "executedAt": "2026-02-18T10:31:00Z",
  "auditId": "cmd-a3f1c9e0"
}

Note

All command executions are audit logged. The auditId can be used to retrieve the full audit record.

Precondition failures¶

If the command's preconditions are not met, the response indicates which conditions failed:

Response (409):

{
  "error": {
    "code": "PRECONDITION_FAILED",
    "message": "Command preconditions not met",
    "details": [
      { "condition": "!{tags.Running}", "result": false, "reason": "Pump is already running" }
    ]
  }
}

Active Alarms¶

GET /api/sites/{siteId}/devices/{deviceId}/alarms¶

List active alarms for a device instance.

Response (200):

{
  "data": [
    {
      "id": "bearing_temp_high",
      "name": "Bearing Temp High",
      "priority": "warning",
      "category": "mechanical",
      "activatedAt": "2026-02-18T10:25:00Z",
      "acknowledged": false,
      "message": "Bearing temperature exceeds 75°C"
    }
  ]
}

POST /api/sites/{siteId}/devices/{deviceId}/alarms/{alarmId}/acknowledge¶

Acknowledge an active alarm. Requires Operator role or higher.

Response (200):

{
  "id": "bearing_temp_high",
  "acknowledged": true,
  "acknowledgedBy": "operator@bhp.com",
  "acknowledgedAt": "2026-02-18T10:32:00Z"
}