SmartVOX Gateway ThingsBoard MQTT API 0.2.0 documentation

SmartVOX Gateway ThingsBoard MQTT API 0.2.0

MQTT API for integration with ThingsBoard IoT Platform (https://thingsboard.io/).

What this API is for

This API documents the SmartVOX Gateway application running on a Teltonika RUT976 router.

The gateway connects a SmartVOX LoRa mesh network to ThingsBoard and enables both:

Data upload (gateway status + SmartVOX device states).
Remote control (alerts and refresh requests via RPC).

Technically, this API is based on ThingsBoard MQTT Device/Gateway conventions:

System overview

In a typical deployment:

SmartVOX devices (SV/SVI/SR/SB/SC/SLG families) communicate over SmartVOX LoRa mesh.
SLG (LoRa <-> USB modem) is connected to the RUT976 through USB.
RUT976 hosts the SmartVOX Gateway app and provides network uplink (Ethernet / Wi-Fi / 5G).

The app can:

✔️ receive and publish gateway states,
✔️receive and publish states for devices on the SmartVOX radio network,
✔️ receive server-side RPC requests from ThingsBoard (trigger alerts, refresh states),
✔️ send client-side RPC requests to ThingsBoard when alerts are propagated from the radio network.

Product references

Product range: SmartVOX product range

Devices summary

Family	Main role in SmartVOX Gateway	References	Specific notes
SV SV230 / SV012	Voice sounders (with/without beacon) used to broadcast synchronized alarms and voice instructions.	Radio Voice Sounder with Beacon Radio Voice Sounder	Outdoor/industrial deployment.
SVI	Indoor voice siren with flash for evacuation/lockdown instructions in public facilities.	Wireless Voice Siren with Flash	Indoor-focused form factor.
SR SR1 / SR4	Portable operator remotes to trigger predefined alert scenarios.	1-Button Radio Remote Control 4-Button Radio Remote Control	Portable operator-trigger device family.
SC SC / SCW	Manual call points (standard/waterproof) for immediate local emergency triggering.	Radio Manual Call Point Waterproof Radio Manual Call Point	Standard and waterproof variants.
SB SB6	Fixed multi-button control box for supervised scenario triggering.	6-Button Radio Remote Control Box	Typically installed in control rooms/security posts.
SLG	LoRa-to-USB modem bridging SmartVOX mesh traffic with the gateway app; also relays mesh traffic.	No public page yet	Front LEDs: Power (device powered), Run (blinking when active), Link (off: ThingsBoard disabled, blinking: connecting, steady: connected), Fault (SLG or RUT976 fault).
RUT976	Industrial router running SmartVOX Gateway app and providing secure IP uplink to ThingsBoard.	RUT976 Wiki RUT976 Product Page	Can use Ethernet, Wi-Fi, or 5G uplink to reach ThingsBoard.

Data sent to ThingsBoard

The SmartVOX Gateway API is organized into 3 functional groups:

1) Gateway states

Data about the gateway itself (SmartVOX app + attached SLG modem).

Main operations:
- SEND gatewayDeviceAttributes
- SEND gatewayDeviceTelemetry
Published topics:
- v1/devices/me/attributes
- v1/devices/me/telemetry
Typical payload content:
- identity/configuration (appVersion, radioModem metadata),
- runtime state (connectionState, modem operational status).

2) Network device states

Data about SmartVOX devices present on the LoRa mesh network (SV/SVI/SR/SC/SB/SLG).

Glossary: attributes = static or slow-changing metadata; telemetry = runtime state sampled over time; faults = abnormal conditions; status = live operational indicators.

Main operations:
Published topics:
- v1/gateway/connect
- v1/gateway/disconnect
- v1/gateway/attributes
- v1/gateway/telemetry

Common attributes (v1/gateway/attributes)

ts: attribute timestamp (milliseconds).
type: device type (SV230, SV012, SVI, SR, SC, SB, SLG).
name: device name (up to 15 chars, no spaces).
groups: group membership (group IDs 0..15).

Common telemetry (v1/gateway/telemetry)

connectionState: online, offline, or pending.
keepAlive:
- intervalSec: expected keepalive period.
- elapsedSinceLastRxSec: elapsed time since last radio frame.
- timeUntilNextRxSec: expected remaining time until next keepalive.
network (radio quality/path metrics):
- hopCount: number of radio hops.
- nearbySrc / nearbyLqi: nearest relay/source and its LQI.
- worstSrc / worstLqi: weakest observed path and its LQI.
faults: device-type specific fault flags.
status: device-type specific live status fields.

Important behavior

When connectionState is offline or pending, network, faults and status are explicitly null.

Device-specific properties by type

Device type	Specific attributes	Specific faults	Specific status
SR (remote controls)	`keypadVersion`: detected keypad type/capability (`not-connected`, `1-button`, `4-buttons`, `unknown`).	`batteryFault`: low or invalid battery state. `keypadFault`: keypad not detected or malfunctioning. (+ common `systemFault`)	`batteryLevel`: current battery level indicator reported by the remote (raw scale `0..255`).
SV230 / SV012 / SVI (voice sounders)	`psuBackupDisabled`: indicates whether backup battery takeover is disabled by configuration.	`psuMainsFault`: mains power missing/faulty. `psuBackupFault`: backup battery/power backup path fault. (+ common `systemFault`)	No dedicated status field (device health is mainly represented through faults and connection state).
SC (manual call points)	No extra attribute beyond common fields	`battery1Fault`/`battery2Fault`: battery channel fault detected. `tamperActive`: enclosure tamper/open event currently active. (+ common `systemFault`)	`buttonActive`: call point trigger currently active. `battery1Level`/`battery2Level`: level indicators for both batteries (raw scale `0..255`).
SB (6-button control boxes)	No extra attribute beyond common fields	`battery1Fault`/`battery2Fault`: battery channel fault detected. (+ common `systemFault`)	`keylockActive`: front-panel key lock enabled/active. `battery1Level`/`battery2Level`: level indicators for both batteries (raw scale `0..255`).
SLG (radio modem)	`psuMonitoringEnabled`: power module supervision is enabled and reported upstream.	`hostCommLost`: SLG <-> host (RUT976 app) communication lost. `psuCommLost`: SLG <-> PSU communication lost. `psuMainsFault`: mains power fault. `psuBatteryFault`: PSU battery fault. `psuInternalFault`: internal PSU fault. `uplinkFault`: upstream connectivity fault. (+ common `systemFault`)	`uplinkConnected`: SLG uplink path to the gateway/backend is currently established.

3) RPC requests

Bidirectional command flow between ThingsBoard and SmartVOX Gateway.

Server-side RPC (ThingsBoard -> Gateway -> ThingsBoard)

Operations:
- RECEIVE serverSideRpcRequest
- SEND serverSideRpcResponse
Topics:
- request from ThingsBoard: v1/devices/me/rpc/request/$request_id
- response to ThingsBoard: v1/devices/me/rpc/response/+
Typical methods:
- alert trigger/stop methods,
- device refresh request (refreshDevices).

Client-side RPC (Gateway -> ThingsBoard)

Operation:
- SEND clientSideRpcRequest
Topic:
- request published by gateway: v1/devices/me/rpc/request/$request_id
Typical usage:
- radio-originated alert propagation to ThingsBoard.

Servers

mqtt://thingsboard.cloud/mqttthingsboard
Security:
User/Password
ThingsBoard device access token is used as MQTT username (password is empty unless custom broker policy requires otherwise).
object

Operations

SEND v1/devices/me/attributes
Gateway static/identity attributes sent to ThingsBoard (app version, modem identity and configuration).

Publishes gateway identity/configuration attributes. Typical usage: at startup, after configuration changes, and whenever SLG modem identity/config changes.

Operation IDgatewayDeviceAttributes
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDmessage
Gateway identity/configuration payload. Includes SmartVOX Gateway app version and SLG modem metadata (when available).

object [Gateway Attributes (ThingsBoard MQTT v1/devices/me/attributes)]
Payload published by the SmartVOX Gateway to ThingsBoard under v1/devices/me/attributes.

Examples
#1 Example
{ "ts": 1730000000123, "appVersion": "v1.3.0", "radioModem": { "id": "1AB5", "type": "SLG", "name": "GW_OFFICE", "groups": [ 0, 2 ], "channel": 0, "panId": "8888", "encryptionKey": "", "fwVersion": "v1.3.0" } }

#2 Example
{ "ts": 1730000000123, "appVersion": "v1.3.0", "radioModem": null }
SEND v1/devices/me/telemetry
Gateway runtime telemetry sent to ThingsBoard (online/offline state and modem operational state).

Publishes gateway health/operational telemetry. Typical usage: periodic heartbeat and state transitions (online/offline, modem operational status).

Operation IDgatewayDeviceTelemetry
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDmessage
Gateway runtime telemetry payload. Exposes connectivity state and radio modem operational status for monitoring dashboards/alarms.

object [Gateway Telemetry (ThingsBoard MQTT v1/devices/me/telemetry)]
Examples
#1 Example
{ "ts": 1730000000999, "connectionState": "online", "radioModem": { "isOperational": true } }

#2 Example
{ "ts": 1730000000999, "connectionState": "offline", "radioModem": { "isOperational": false } }
SEND v1/gateway/connect
Notification that a SmartVOX radio device is now visible/connected through the gateway.

Announces that a SmartVOX radio device is connected/seen on the mesh network through this gateway. Helps ThingsBoard keep device presence up to date.

Operation IDnetworkDeviceConnect
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDmessage
Notification that a SmartVOX device became reachable on the radio network.

object [Network Connect (ThingsBoard MQTT v1/gateway/connect)]
Examples
#1 Example
{ "device": "04AF", "type": "SV230" }
SEND v1/gateway/disconnect
Notification that a SmartVOX radio device is disconnected or no longer reachable.

Announces that a SmartVOX radio device is disconnected or no longer reachable. Helps ThingsBoard reflect radio network availability changes.

Operation IDnetworkDeviceDisconnect
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDmessage
Notification that a SmartVOX device became unreachable on the radio network.

object [Network Disconnect (ThingsBoard MQTT v1/gateway/disconnect)]
Examples
#1 Example
{ "device": "04AF" }

SEND v1/gateway/attributes

Batched SmartVOX device attributes for all known devices on the LoRa mesh network.

Publishes batched attributes for SmartVOX devices (type, groups, device-specific capabilities). Payload is keyed by radio device ID.

Operation IDnetworkDevicesAttributes

Available only on servers:

thingsboard

object

Accepts the following message:

application/json

Message IDmessage

Batched SmartVOX network device attributes keyed by radio device ID. Each entry describes static/slow-changing metadata used to classify and configure UI behavior.

object [Network Devices Attributes (ThingsBoard MQTT v1/gateway/attributes)]

Examples

#1 Example - SR attributes example

SR device requires `keypadVersion`.

{
  "10B2": {
    "ts": 1730000000210,
    "type": "SR",
    "name": "SR-10B2",
    "groups": [],
    "keypadVersion": "4-buttons"
  }
}

#2 Example - SV230 attributes example

SV230/SV012/SVI devices require `psuBackupDisabled`.

{
  "04AF": {
    "ts": 1730000000200,
    "type": "SV230",
    "name": "Siren-04AF",
    "groups": [
      0,
      1
    ],
    "psuBackupDisabled": false
  }
}

#3 Example - SLG attributes example

SLG devices require `psuMonitoringEnabled`.

{
  "1AB5": {
    "ts": 1730000000300,
    "type": "SLG",
    "name": "GWLINK-1AB5",
    "groups": [
      2
    ],
    "psuMonitoringEnabled": true
  }
}

#4 Example

{
  "04AF": {
    "ts": 1730000000200,
    "type": "SV230",
    "name": "Siren-04AF",
    "groups": [
      0,
      1
    ],
    "psuBackupDisabled": false
  },
  "10B2": {
    "ts": 1730000000210,
    "type": "SR",
    "name": "SR-10B2",
    "groups": [],
    "keypadVersion": "4-buttons"
  }
}

SEND v1/gateway/telemetry

Batched SmartVOX device telemetry (connectivity, faults, status indicators).

Publishes batched telemetry for SmartVOX devices (connection state, keepalive, network quality, faults, status). Payload is keyed by radio device ID.

Operation IDnetworkDevicesTelemetry

Available only on servers:

thingsboard

object

Accepts the following message:

application/json

Message IDmessage

Batched SmartVOX network device telemetry keyed by radio device ID. Each entry provides operational state (connectivity, keepalive, faults, status values).

object [Network Devices Telemetry (ThingsBoard MQTT v1/gateway/telemetry)]

Examples

#1 Example - SR telemetry example

{
  "04AF": [
    {
      "ts": 1730000000450,
      "values": {
        "connectionState": "online",
        "keepAlive": {
          "intervalSec": 30,
          "elapsedSinceLastRxSec": 5,
          "timeUntilNextRxSec": 25
        },
        "network": {
          "hopCount": 1,
          "nearbySrc": "00A1",
          "nearbyLqi": 210,
          "worstSrc": "00B2",
          "worstLqi": 180
        },
        "faults": {
          "systemFault": false,
          "batteryFault": false,
          "keypadFault": false
        },
        "status": {
          "batteryLevel": 97
        }
      }
    }
  ]
}

#2 Example - SLG telemetry example

{
  "1AB5": [
    {
      "ts": 1730000000460,
      "values": {
        "connectionState": "online",
        "keepAlive": {
          "intervalSec": 30,
          "elapsedSinceLastRxSec": 4,
          "timeUntilNextRxSec": 26
        },
        "network": {
          "hopCount": 1,
          "nearbySrc": "00A1",
          "nearbyLqi": 205,
          "worstSrc": "00C3",
          "worstLqi": 170
        },
        "faults": {
          "systemFault": false,
          "hostCommLost": false,
          "psuCommLost": false,
          "psuMainsFault": false,
          "psuBatteryFault": false,
          "psuInternalFault": false,
          "uplinkFault": false
        },
        "status": {
          "uplinkConnected": true
        }
      }
    }
  ]
}

RECEIVE v1/devices/me/rpc/request/$request_id
RPC request topic used for both server-side RPC (ThingsBoard -> gateway) and client-side RPC (gateway -> ThingsBoard).
Receives RPC requests from ThingsBoard to execute gateway/network actions. Main use cases:

trigger alerts on SmartVOX devices/groups,

stop active alerts,

refresh known device states.
Operation IDserverSideRpcRequest
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDmessage
Server-side RPC request consumed by the gateway. Used by ThingsBoard to trigger alerts and request state refresh on the SmartVOX network.

object allOf
RPC request consumed by the gateway when ThingsBoard initiates server-side RPC.

Examples
#1 Example
{ "method": "refreshDevices", "params": {} }

#2 Example
{ "method": "trigAlertOnce", "params": { "source": { "kind": "device", "id": "1A2B" }, "scope": { "type": "group", "groupId": 0 }, "priority": "high", "signaling": "combined", "audible": { "sounds": [ { "bank": "standard", "fileId": 0, "attenuationInDB": 0, "repeats": 1 } ], "sequenceRepeats": 1 } } }
SEND v1/devices/me/rpc/response/+
RPC response topic for gateway responses to server-side RPC requests.

Returns execution result for a server-side RPC request. Response includes result code and an optional message for troubleshooting.

Operation IDserverSideRpcResponse
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDmessage
Server-side RPC execution response. result indicates whether the action succeeded, and msg provides contextual details on errors.

object [RPC Server-side Response (ThingsBoard MQTT v1/devices/me/rpc/response/+)]
RPC response published by the gateway to answer ThingsBoard server-side RPC requests.

Examples
#1 Example
{ "result": "success", "msg": "" }

#2 Example
{ "result": "invalidParams", "msg": "missing key: scope" }
SEND v1/devices/me/rpc/request/$request_id
RPC request topic used for both server-side RPC (ThingsBoard -> gateway) and client-side RPC (gateway -> ThingsBoard).

Publishes client-side RPC requests from the gateway to ThingsBoard when an alert event originates from the radio network. This is used for alert method propagation and traceability in ThingsBoard.

Operation IDclientSideRpcRequest
Available only on servers:
- thingsboard
object
Accepts the following message:
application/json
Message IDclientMessage
Client-side RPC request published by the gateway to ThingsBoard (alert methods only). Used when a radio-originated alert must be propagated and traced in the platform.

object allOf
RPC request emitted by the gateway to ThingsBoard (client-side RPC). Only alert-related methods are allowed.

Examples
#1 Example
{ "method": "trigAlertOnce", "params": { "source": { "kind": "device", "id": "1A2B" }, "scope": { "type": "group", "groupId": 0 }, "priority": "high", "signaling": "combined", "audible": { "sounds": [ { "bank": "standard", "fileId": 0, "attenuationInDB": 0, "repeats": 1 } ], "sequenceRepeats": 1 } } }

#2 Example
{ "method": "stopAlertAll", "params": { "source": { "kind": "device", "id": "1A2B" }, "scope": { "type": "global" }, "signaling": "combined" } }

Messages

#1
- application/json
Message IDGatewayAttributesMessage
Gateway identity/configuration payload. Includes SmartVOX Gateway app version and SLG modem metadata (when available).

object [Gateway Attributes (ThingsBoard MQTT v1/devices/me/attributes)]
Payload published by the SmartVOX Gateway to ThingsBoard under v1/devices/me/attributes.
#2
- application/json
Message IDGatewayTelemetryMessage
Gateway runtime telemetry payload. Exposes connectivity state and radio modem operational status for monitoring dashboards/alarms.

object [Gateway Telemetry (ThingsBoard MQTT v1/devices/me/telemetry)]
#3
- application/json
Message IDNetworkConnectMessage
Notification that a SmartVOX device became reachable on the radio network.

object [Network Connect (ThingsBoard MQTT v1/gateway/connect)]
#4
- application/json
Message IDNetworkDisconnectMessage
Notification that a SmartVOX device became unreachable on the radio network.

object [Network Disconnect (ThingsBoard MQTT v1/gateway/disconnect)]
#5
- application/json
Message IDNetworkAttributesBatchMessage
Batched SmartVOX network device attributes keyed by radio device ID. Each entry describes static/slow-changing metadata used to classify and configure UI behavior.

object [Network Devices Attributes (ThingsBoard MQTT v1/gateway/attributes)]
#6
- application/json
Message IDNetworkTelemetryBatchMessage
Batched SmartVOX network device telemetry keyed by radio device ID. Each entry provides operational state (connectivity, keepalive, faults, status values).

object [Network Devices Telemetry (ThingsBoard MQTT v1/gateway/telemetry)]
#7
- application/json
Message IDRpcRequestMessage
Server-side RPC request consumed by the gateway. Used by ThingsBoard to trigger alerts and request state refresh on the SmartVOX network.

object allOf
RPC request consumed by the gateway when ThingsBoard initiates server-side RPC.
#8
- application/json
Message IDRpcClientRequestMessage
Client-side RPC request published by the gateway to ThingsBoard (alert methods only). Used when a radio-originated alert must be propagated and traced in the platform.

object allOf
RPC request emitted by the gateway to ThingsBoard (client-side RPC). Only alert-related methods are allowed.
#9
- application/json
Message IDRpcResponseMessage
Server-side RPC execution response. result indicates whether the action succeeded, and msg provides contextual details on errors.

object [RPC Server-side Response (ThingsBoard MQTT v1/devices/me/rpc/response/+)]
RPC response published by the gateway to answer ThingsBoard server-side RPC requests.

SmartVOX Gateway ThingsBoard MQTT API 0.2.0

What this API is for

System overview

Product references

Devices summary

Data sent to ThingsBoard

1) Gateway states

2) Network device states

3) RPC requests

Server-side RPC (ThingsBoard -> Gateway -> ThingsBoard)

Client-side RPC (Gateway -> ThingsBoard)

Servers

Security:

Operations

SEND v1/devices/me/attributes

Examples

#1 Example

#2 Example

SEND v1/devices/me/telemetry

Examples

#1 Example

#2 Example

SEND v1/gateway/connect

Examples

#1 Example

SEND v1/gateway/disconnect

Examples

#1 Example

SEND v1/gateway/attributes

Examples

#1 Example - SR attributes example

#2 Example - SV230 attributes example

#3 Example - SLG attributes example

#4 Example

SEND v1/gateway/telemetry

Examples

#1 Example - SR telemetry example

#2 Example - SLG telemetry example

RECEIVE v1/devices/me/rpc/request/$request_id

Examples

#1 Example

#2 Example

SEND v1/devices/me/rpc/response/+

Examples

#1 Example

#2 Example

SEND v1/devices/me/rpc/request/$request_id

Examples

#1 Example

#2 Example

Messages