This is a public API!

A third‑party app sends control commands to field devices and receives both an immediate command acknowledgement and an eventual state‑change notification.

Transport & Topics

Publish commands to: resource/commands
QoS: 2 (exactly‑once delivery negotiated by MQTT)
Subscribe for responses & notifications: application/third-party/appName/instanceId

Always include a unique correlationId in requests and verify the same value in responses/notifications. JWT must be valid; otherwise the gateway returns an error response.

Allways subscribe to topic application/third-party/appName/instanceId where appId value is appName.instanceIdin request payload!

Message Envelopes (Common)

Command Request

{
  "messageType": "commandMessage",
  "appId": "appName.instanceId",
  "brand": "Bimetri",
  "jwtToken": "replace-with-your-token",
  "userId": 12345,
  "organizationId": 23456,
  "command": "<command>",
  "correlationId": "<unique-id>",
  "parameters": { /* command-specific */ }
}

Command Response

{
  "messageType": "commandResponse",
  "correlationId": "<same-as-request>",
  "result": "<sent|not_send|failed|send_no_ack|unauthorized>",
  "reason": "<human-readable>",
  "data": { /* command-specific echo & device info */ }
}

Notification (Async)

{
  "messageType": "notification",
  "appId": "appName.instanceId",
  "correlationId": "<same-as-request-or-omitted>",
  "command": "<command>",
  "notificationType": "<event>",
  "userName": "<who-triggered>",
  "userId": 12345,
  "parameters": { /* event-specific payload */ }
}

Responses typically acknowledge queuing (e.g., result = “sent”), while notifications carry the final device state. Treat notifications as the source of truth for UI state.

1) `setExtDO` Command

Set an external digital output (relay/DO) to on/off.

Request

{
  "messageType": "commandMessage",
  "appId": "flexyWattApp.1",
  "brand": "Bimetri",
  "jwtToken": "replace-with-your-token",
  "userId": 12345,
  "organizationId": 23456,
  "command": "setExtDO",
  "correlationId": "100",
  "parameters": {
    "resourceId": 101,
    "output": 4,
    "status": 0
  }
}

Parameters

resourceId (number) – Target device identifier.
output (number) – Output index/port (1‑based unless otherwise provisioned).
status (number) – Desired state: 1 (on/closed), 0 (off/open).

Some deployments may validate output ranges per model; invalid ports will yield an error response.

For this example (due to "appId": "flexyWattApp.1"); subscribe to topic application/third-party/flexyWattApp/1 or application/third-party/flexyWattApp/# (for all instances) to receive responses and async notifications.

Immediate Response

{
  "messageType": "commandResponse",
  "correlationId": "100",
  "result": "sent",
  "reason": "Command Queued",
  "data": {
    "command": "setExtDO",
    "resourceId": 101,
    "brand": "Bimetri",
    "model": "BMM620",
    "networkId": "26:AA:E0:23:23:5E"
  }
}

Error Response (Example)

{
  "messageType": "commandResponse",
  "correlationId": "100",
  "result": "not_send",
  "reason": "The user does not have access rights to the resource!",
  "data": {
    "command": "setExtDO",
    "resourceId": 101,
    "userId": 12345
  }
}

State‑Change Notification

Emitted when the device confirms the output’s actual state.

{
  "messageType": "notification",
  "appId": "flexyWattApp.1",
  "correlationId": "100",
  "command": "setExtDO",
  "notificationType": "extDOStateChanged",
  "userName": "Flexywatt User",
  "userId": 12345,
  "parameters": {
    "resourceId": 101,
    "brand": "Bimetri",
    "model": "BMM620",
    "networkId": "26:AA:E0:23:23:5E",
    "organizationId": 23456,
    "output": 4,
    "status": 1
  }
}

Use the pair (resourceId, output) plus correlationId to de‑duplicate and to reconcile UI state after reconnects.

Consumer Guidance

QoS & retries: Expect duplicate deliveries at QoS 1. Make handlers idempotent.
Timeouts: If no notification arrives, surface the queued state and allow users to retry.
Security: Store tokens securely; rotate when expired; never log full JWTs.
Tracing: Log correlationId on both publish and receive paths for observability.

Before You Start

PUB/SUB API Reference

Third Party Application → Resource Commands

Transport & Topics

Message Envelopes (Common)

Command Request

Command Response

Notification (Async)

1) `setExtDO` Command

Request

Parameters

Immediate Response

Error Response (Example)

State‑Change Notification

Consumer Guidance

​Transport & Topics

​Message Envelopes (Common)

​Command Request

​Command Response

​Notification (Async)

​1) setExtDO Command

​Request

​Parameters

​Immediate Response

​Error Response (Example)

​State‑Change Notification

​Consumer Guidance

Transport & Topics

Message Envelopes (Common)

Command Request

Command Response

Notification (Async)

1) `setExtDO` Command

Request

Parameters

Immediate Response

Error Response (Example)

State‑Change Notification

Consumer Guidance