Alert Request Specification

This document defines the JSON contract for alert RPC requests (trigAlertOnce, trigAlertContinuous, stopAlertAll, stopAlertContinuous).

Scope: Alert methods only. The refreshDevices server-side RPC method is documented in the SmartVOX Gateway MQTT API.

JSON Schemas

Alert params rules are defined in this document. The machine-readable schemas below validate the full MQTT RPC payload ({ method, params }). Paths match the published HTML documentation (out/ after running script/generate-mqtt-api-doc.sh).

Direction	Download	Validate
Server-side RPC request (backend → gateway)	rpc-server-side-request.bundled.schema.json	Open validator
Client-side RPC request (gateway → backend)	rpc-client-side-request.bundled.schema.json	Open validator
Server-side RPC response	rpc-server-side-response.schema.json	Open validator

RPC directions

Alert requests use topic v1/devices/me/rpc/request/$request_id, shared with other RPC methods. The direction depends on who initiates the exchange:

Direction	Initiator	Consumer	Role
Server-side RPC	MQTT backend	SmartVOX Gateway	Backend publishes the request; gateway executes alert actions on the radio network
Client-side RPC	SmartVOX Gateway	MQTT backend	Gateway publishes when an alert originates from the radio network (propagation and traceability)

Both directions support the four alert methods listed below. Client-side RPC is limited to alert methods; other RPC such as refreshDevices is server-side only and documented in the main MQTT API.

Request Types

trigAlertOnce: trigger one alert cycle
trigAlertContinuous: trigger a continuous alert
stopAlertAll: stop all alerts in scope
stopAlertContinuous: stop one continuous alert by alertId

RPC Envelope

Alert requests are sent as MQTT RPC messages on v1/devices/me/rpc/request/$request_id. The payload is a JSON object with a top-level method and params key, following ThingsBoard MQTT RPC conventions and compatible with any broker that routes these topics.

The top-level method selects which request type the gateway will parse and handle; the alert contract itself lives under params.

Example:

{
  "method": "stopAlertAll",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "signaling": "visual"
  }
}

Params Core Contract

Scope

scope is a required object with:

type (required): global or group
groupId (required only when type = "group"): integer 0..15

Business meaning: - scope defines where the alert applies. - global means the alert targets all devices. - group means the alert targets one logical group of devices identified by groupId.

Examples:

{
  "scope": {
    "type": "global"
  }
}

{
  "scope": {
    "type": "group",
    "groupId": 5
  }
}

Signaling

Allowed values:

combined
audible
visual

Business meaning: - audible: play sound only. - visual: activate the visual beacon only. - combined: audible + visual behavior in the same request.

Priority

Allowed values:

highest
high
medium
low
lowest

Business meaning: - priority defines the alert urgency used by the application when multiple alerts compete.

Alert ID

Key: alertId
Required for trigAlertContinuous and stopAlertContinuous
Ignored (optional) for trigAlertOnce and stopAlertAll
Range: 0..255

Business meaning: - alertId identifies the continuous alert instance to start or stop. - The same alertId is used later by stopAlertContinuous to stop a previously started continuous alert. - For other methods, alertId is ignored by the application.

Alert Relay Activation

Key: alertRelayActivation
Allowed values: on, off
Optional for trigAlertOnce and trigAlertContinuous
Default value when omitted: on

Business meaning: - alertRelayActivation controls whether the siren alert relay is enabled while an alert is active.

Timestamp (`ts`)

Key: ts
Optional for all request types
Type: unsigned 64-bit integer (uint64)
Unit: milliseconds (msec)
Range: 0..18446744073709551615

Business meaning: - ts is the request timestamp expressed in milliseconds. - It can be used for ordering, traceability, and correlation across systems.

Example:

{
  "ts": 1774961285037
}

Source

Key: source
Required for all request types
Type: object
Required fields:
kind: device, user, service, or system
id: non-empty string, max 63 characters

Business meaning: - source identifies who originated the alert request. - source.kind provides the origin category. - source.id provides the origin identifier.

Example:

{
  "source": {
    "kind": "device",
    "id": "1A2B"
  }
}

Required / Optional Matrix

Key	trigAlertOnce	trigAlertContinuous	stopAlertAll	stopAlertContinuous
`ts`	optional	optional	optional	optional
`source`	required	required	required	required
`scope`	required	required	required	required
`priority`	required	required	n/a	n/a
`alertId`	optional (ignored)	required	optional (ignored)	required
`signaling`	required	required	required	required
`audible`	required when `signaling` is `combined` or `audible`	required when `signaling` is `combined` or `audible`; not required when `signaling` is `visual`	n/a	n/a
`visual`	required when `signaling` is `visual`	optional; ignored if present (any `signaling` value)	n/a	n/a
`alertRelayActivation`	optional (default `on`)	optional (default `on`)	n/a	n/a

Audible Object

audible contains:

sounds (required): array of sound objects
sequenceRepeats (0..65535):
required for trigAlertOnce
ignored for trigAlertContinuous

Business meaning: - audible defines the full sound playback pattern. - sounds contains one or two sound definitions. - sequenceRepeats controls how many times the full sounds sequence is replayed (for trigAlertOnce).

Sounds Array Rules

sounds.length must be 1 or 2
if sounds.length = 1:
sounds[0] must exist
in trigAlertOnce, sounds[0].repeats and sequenceRepeats are required and used
in trigAlertContinuous, sounds[0].repeats may be present but is ignored
if sounds.length = 2:
sounds[0] and sounds[1] must exist
in trigAlertOnce, sounds[0].repeats and sounds[1].repeats are required and used
in trigAlertContinuous, sounds[0].repeats and sounds[1].repeats MUST be present (schema-level requirement)

Sound Object

Each item in sounds:

{
  "bank": "standard",
  "fileId": 0,
  "attenuationInDB": 0,
  "repeats": 1
}

Field constraints:

bank: standard or custom
fileId: 0..127
attenuationInDB: 0..40
repeats: 0..255

Business meaning: - bank selects the sound library. - fileId selects the sound inside the selected bank. - attenuationInDB sets volume attenuation for this sound. - repeats defines how many times this sound is repeated before moving to the next sound in the sequence.

Visual Object

visual:

{
  "visual": {
    "durationInSec": 10
  }
}

Constraints:

durationInSec: 1..65534
required for trigAlertOnce when signaling = "visual"
for trigAlertContinuous, visual is optional and ignored if present (including when signaling = "visual")

Business meaning: - visual.durationInSec is the visual beacon activation time in seconds. - For continuous trigger requests, visual-specific timing is managed elsewhere, so this object is ignored. - A trigAlertContinuous request with signaling = "visual" needs only the core fields (source, scope, priority, alertId, signaling); neither audible nor visual is required.

Normative Rules (MUST / MAY / IGNORED)

ts MAY be present and, when present, MUST be an integer in 0..18446744073709551615 (milliseconds).
source MUST be present and MUST be an object with kind and id.
source.kind MUST be one of device, user, service, system.
source.id MUST be a non-empty string of max 63 characters.
scope MUST be present and MUST be an object containing type.
scope.type MUST be global or group.
If scope.type = "group", scope.groupId MUST be present.
If scope.type = "global", scope.groupId MAY be omitted.
If signaling is combined or audible, audible MUST be present.
For trigAlertOnce when signaling = "visual", visual MUST be present.
For trigAlertContinuous when signaling = "visual", audible MAY be omitted (not required).
For trigAlertContinuous when signaling = "visual", visual MAY be omitted; if present it is IGNORED.
sounds.length MUST be 1 or 2.
For trigAlertContinuous, visual is IGNORED (any signaling value).
For trigAlertContinuous, sequenceRepeats is IGNORED.
For trigAlertContinuous with sounds.length = 1, repeats MAY be present but is IGNORED.
For trigAlertContinuous with sounds.length = 2, each sound repeats MUST be present.

Canonical Examples

trigAlertOnce - combined, 2 sounds

{
  "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 },
        { "bank": "standard", "fileId": 1, "attenuationInDB": 0, "repeats": 2 }
      ],
      "sequenceRepeats": 1
    },
    "alertRelayActivation": "on"
  }
}

trigAlertOnce - visual

{
  "method": "trigAlertOnce",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "priority": "high",
    "signaling": "visual",
    "visual": {
      "durationInSec": 10
    }
  }
}

trigAlertContinuous - audible, 1 sound

{
  "method": "trigAlertContinuous",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "priority": "high",
    "alertId": 0,
    "signaling": "audible",
    "audible": {
      "sounds": [
        { "bank": "standard", "fileId": 0, "attenuationInDB": 0 }
      ]
    }
  }
}

trigAlertContinuous - visual

Minimal payload: no audible or visual object. Continuous visual timing is managed by the application, not by visual.durationInSec.

{
  "method": "trigAlertContinuous",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "priority": "high",
    "alertId": 3,
    "signaling": "visual"
  }
}

stopAlertAll

{
  "method": "stopAlertAll",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "group", "groupId": 5 },
    "signaling": "combined"
  }
}

stopAlertContinuous

{
  "method": "stopAlertContinuous",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "alertId": 0,
    "signaling": "combined"
  }
}

Additional Example Set

trigAlertOnce - audible, global, one sound, default relay activation

{
  "method": "trigAlertOnce",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "priority": "medium",
    "signaling": "audible",
    "audible": {
      "sounds": [
        { "bank": "custom", "fileId": 12, "attenuationInDB": 5, "repeats": 3 }
      ],
      "sequenceRepeats": 2
    }
  }
}

trigAlertOnce - combined, group scope, relay off

{
  "method": "trigAlertOnce",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "group", "groupId": 9 },
    "priority": "highest",
    "signaling": "combined",
    "audible": {
      "sounds": [
        { "bank": "standard", "fileId": 2, "attenuationInDB": 0, "repeats": 1 },
        { "bank": "custom", "fileId": 7, "attenuationInDB": 8, "repeats": 2 }
      ],
      "sequenceRepeats": 4
    },
    "alertRelayActivation": "off"
  }
}

trigAlertContinuous - combined, two sounds, visual present but ignored

{
  "method": "trigAlertContinuous",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "priority": "high",
    "alertId": 42,
    "signaling": "combined",
    "audible": {
      "sounds": [
        { "bank": "standard", "fileId": 0, "attenuationInDB": 0, "repeats": 1 },
        { "bank": "standard", "fileId": 1, "attenuationInDB": 4, "repeats": 2 }
      ]
    },
    "visual": {
      "durationInSec": 20
    }
  }
}

trigAlertContinuous - audible, one sound, repeats ignored

{
  "method": "trigAlertContinuous",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "group", "groupId": 1 },
    "priority": "low",
    "alertId": 7,
    "signaling": "audible",
    "audible": {
      "sounds": [
        { "bank": "custom", "fileId": 3, "attenuationInDB": 12, "repeats": 200 }
      ]
    },
    "alertRelayActivation": "on"
  }
}

stopAlertAll - global scope

{
  "method": "stopAlertAll",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "global" },
    "signaling": "visual"
  }
}

stopAlertContinuous - group scope, audible signaling

{
  "method": "stopAlertContinuous",
  "params": {
    "source": { "kind": "device", "id": "1A2B" },
    "scope": { "type": "group", "groupId": 4 },
    "alertId": 17,
    "signaling": "audible"
  }
}

Alert Request Specification

Related documentation

JSON Schemas

RPC directions

Request Types

RPC Envelope

Params Core Contract

Scope

Signaling

Priority

Alert ID

Alert Relay Activation

Timestamp (ts)

Source

Required / Optional Matrix

Audible Object

Sounds Array Rules

Sound Object

Visual Object

Normative Rules (MUST / MAY / IGNORED)

Canonical Examples

trigAlertOnce - combined, 2 sounds

trigAlertOnce - visual

trigAlertContinuous - audible, 1 sound

trigAlertContinuous - visual

stopAlertAll

stopAlertContinuous

Additional Example Set

trigAlertOnce - audible, global, one sound, default relay activation

trigAlertOnce - combined, group scope, relay off

trigAlertContinuous - combined, two sounds, visual present but ignored

trigAlertContinuous - audible, one sound, repeats ignored

stopAlertAll - global scope

stopAlertContinuous - group scope, audible signaling

Timestamp (`ts`)