Skip to main content

MQTT API Reference

This page describes the full MQTT topic namespace, authentication model, payload conventions, and QoS guidance for Vwire devices.

Two separate credentials​

Vwire uses two distinct device credentials — each serves a different purpose:

CredentialWhere to find itPurpose
Auth TokenDevice detail page → Auth TokenMQTT password for authentication only
Device IDDevice detail page → Device ID (e.g. VW-ABC123)Used in every MQTT topic for message routing

The auth token proves who you are. The device ID identifies which MQTT topics belong to your device. Never use the auth token in topic paths — use the Device ID.

Connection details​

FieldValue
Brokermqtt.vwire.io
Port (TLS)8883 (recommended)
Port (plain TCP)1883
TLSRequired for port 8883
ProtocolMQTT 3.1.1

Authentication fields​

FieldValue
clientIdAny unique string — the library uses the Device ID
usernameDevice ID (e.g. VW-ABC123)
passwordAuth Token (e.g. at_xxxxxxxxxxxxxxxx)

Topic tree​

vwire/
  {deviceId}/                       ← Device ID (VW-XXXXXX or VU-XXXXXX), NOT the auth token
    pin/{pin}                       ← Device PUBLISHES sensor value  (e.g. pin/V0)
    cmd/{pin}                       ← Server PUBLISHES command to device  (e.g. cmd/V1)
    status                          ← Device PUBLISHES online/offline  (LWT)
    heartbeat                       ← Device PUBLISHES health info
    sync/{pin}                      ← Device PUBLISHES sync request for a pin
    notify                          ← Device PUBLISHES push notification
    alarm                           ← Device PUBLISHES persistent alarm
    alarm_ack                       ← Server PUBLISHES alarm acknowledgment back to device
    email                           ← Device PUBLISHES email request
    ack/{msgId}                     ← Device PUBLISHES reliable delivery acknowledgment
    ota                             ← Server PUBLISHES OTA firmware command
    ota_status                      ← Device PUBLISHES OTA progress/result
    log                             ← Device PUBLISHES debug log message

Device → Server topics​

Sensor / virtual pin value​

vwire/{deviceId}/pin/{pin}

Published by the device when calling Vwire.virtualSend().

Payload — single value:

["23.5"]

Payload — multiple values (multi-param):

["val1", "val2", "val3"]

QoS: 0 for frequent sensor readings, 1 for important state changes

Device status (LWT)​

vwire/{deviceId}/status

Online payload (published by device after connect):

{"status": "online"}

Offline payload (LWT — published by broker when device disconnects):

{"status": "offline"}

QoS: 1, Retain: true

Heartbeat​

vwire/{deviceId}/heartbeat

Published periodically by the device. Updates lastSeenAt, IP address, and firmware version in the dashboard.

{
  "uptime": 12345,
  "heap": 32000,
  "rssi": -65,
  "ip": "192.168.1.100",
  "fw": "3.1.0"
}

Push notification​

vwire/{deviceId}/notify

Published when the device calls Vwire.notify(message). The server delivers this as a push notification and bell notification to the user.

Payload: raw UTF-8 string message (not JSON)

Temperature exceeded 85°C!

Persistent alarm​

vwire/{deviceId}/alarm

Published when the device calls Vwire.alarm(). Delivers a persistent alarm to the mobile app requiring user acknowledgment.

{
  "type": "alarm",
  "message": "🚨 Critical: Pressure too high!",
  "alarmId": "alarm_1234567890",
  "sound": "alarm",
  "priority": 3,
  "timestamp": 1708000000000
}

Email notification​

vwire/{deviceId}/email

Published when the device calls Vwire.email(subject, body). Requires a PRO plan or higher.

{
  "subject": "Daily Status Report",
  "body": "All sensors nominal at 09:00 AM."
}

Reliable delivery acknowledgment​

vwire/{deviceId}/ack/{msgId}

Published by the device to acknowledge receipt of a reliable delivery command. The server removes the message from its retry queue.

Payload: "ok" or "error:<reason>"

OTA progress / result​

vwire/{deviceId}/ota_status

Published by the device during an OTA update.

{"progress": 42}
{"result": "ok", "version": "1.3.0"}
{"result": "error", "reason": "invalid hash"}

Sync request​

vwire/{deviceId}/sync/{pin}

Published by the device when calling Vwire.syncVirtual(V0). The server responds by publishing the last stored value for that pin on the command topic.

Debug log​

vwire/{deviceId}/log

Published when the device calls Vwire.debug(). Raw UTF-8 string. Visible in server logs; not stored.

Server → Device topics​

Command / write virtual pin​

vwire/{deviceId}/cmd/{pin}

Published by the server when a dashboard widget sends a value to the device. The device receives this as a VWIRE_RECEIVE(Vn){} callback.

Payload — single value:

["1"]

Payload — multi-param:

["255", "128", "0"]

OTA firmware command​

vwire/{deviceId}/ota

Published by the server when the user clicks "Upload & Deploy" in the dashboard.

{
  "url": "https://app.vwire.io/api/v1/ota/firmware/uuid.bin",
  "sha256": "abc123def456...",
  "version": "1.3.0",
  "size": 712432
}

Alarm acknowledgment​

vwire/{deviceId}/alarm_ack

Published by the server when the user dismisses or snoozes an alarm in the app.

{
  "alarmId": "alarm_1234567890",
  "action": "stopped",
  "snoozeMinutes": 0,
  "timestamp": 1708000000000
}

Payload conventions​

TypeExampleMQTT payload
Integer42["42"]
Float23.5["23.5"]
String"hello"["hello"]
GPSlat/lng["48.858,2.294"]
Multi-paramR,G,B["255","128","0"]

QoS reference​

Traffic typeQoSRetain
Frequent sensor data0No
Important events1No
Control commands1No
Device status (LWT)1Yes
OTA commands1No
Alarms / notifications1No

Connection details​

FieldValue
Brokerapp.vwire.io
Port (TLS)8883
Port (WebSocket TLS)443
TLS requirementRequired
AuthenticationToken as clientId, username, password
ProtocolMQTT 3.1.1

Topic tree​

vwire/
  {deviceToken}/
    data/
      v/{pin}           ← device publishes sensor value
    cmd/
      v/{pin}           ← server/dashboard publishes command
    status              ← device ONLINE/OFFLINE (LWT)
    info                ← device metadata
    ota                 ← OTA update URL
    sync                ← pin sync on reconnect

Data topics (device → server)​

Virtual pin value​

vwire/{token}/data/v/{pin}

Payload:

["value"]

Multiple values (multi-param):

["val1", "val2", "val3"]

QoS: 0 (for frequent sensor readings) or 1 (for important events)

Device status​

vwire/{token}/status

Online payload:

{"status": "online", "ip": "192.168.1.105", "ver": "1.2.3"}

Offline (LWT) payload:

{"status": "offline"}

QoS: 1, Retain: true

Device info​

vwire/{token}/info
{
  "firmware": "1.2.3",
  "hardware": "ESP32",
  "mac": "A4:CF:12:34:56:78"
}

Command topics (server → device)​

Write virtual pin​

vwire/{token}/cmd/v/{pin}

Payload:

["value"]

Device receives this as a VWIRE_RECEIVE(Vn) callback.

OTA update​

vwire/{token}/ota
{
  "url": "https://app.vwire.io/api/v1/ota/firmware/uuid.bin",
  "sha256": "abc123...",
  "version": "1.3.0",
  "size": 712432
}

Sync pins​

vwire/{token}/sync
{"pins": [0, 1, 5]}

Server sends this after a device reconnects; the device should call Vwire.syncVirtual() for listed pins.

Payload conventions​

TypeJavaScriptMQTT payload
Integer42["42"]
Float23.5["23.5"]
String"hello"["hello"]
GPSlat/lng pair["48.858,2.294"]
JSON object{a:1}["{\"a\":1}"] (escaped)
Array[1,2,3]["1","2","3"]

QoS reference​

Traffic typeQoSRetain
Frequent sensor data0No
Control commands1No
Device status1Yes
OTA messages1No
LWT1Yes