MQTT Protocol Reference

VWire uses MQTT 3.1.1 for device connectivity. This page covers the broker details, authentication model, topic schema, payload format, and special topics used by advanced integrations.

---

Broker endpoints

Field	Value
Host	mqtt.vwire.io
Port (TLS)	8883
Port (plain TCP)	1883
TLS	Recommended and expected for production
Protocol	MQTT 3.1.1

---

Authentication

Every VWire device has two credentials:

Credential	MQTT field	Purpose
Auth Token	password	Authenticates the connection
Device ID	clientId and username	Identifies the device and names its topics

The Arduino and Python libraries handle this automatically when you call Vwire.config(AUTH_TOKEN) and Vwire.setDeviceId(DEVICE_ID).

---

Topic schema

All topics use the Device ID in the topic path.

Device → Server

Topic	Purpose
vwire/{deviceId}/pin/{pin}	Publish a pin value such as V0, D2, or A0
vwire/{deviceId}/status	Online/offline status (including LWT)
vwire/{deviceId}/heartbeat	Uptime, heap, RSSI, IP, firmware, and other health data
vwire/{deviceId}/sync/{pin}	Request the last stored value for one pin
vwire/{deviceId}/sync	Request sync for all stored pin values
vwire/{deviceId}/notify	Send a standard notification
vwire/{deviceId}/alarm	Send a persistent alarm
vwire/{deviceId}/email	Send an email notification
vwire/{deviceId}/ack/{msgId}	Reliable-delivery acknowledgment
vwire/{deviceId}/ota_status	OTA progress or result
vwire/{deviceId}/log	Debug log message

Server → Device

Topic	Purpose
vwire/{deviceId}/cmd/{pin}	Write a value to a virtual, digital, or analog pin
vwire/{deviceId}/pinconfig	Send GPIO configuration to the Arduino GPIO Pin Manager
vwire/{deviceId}/ota	Start an OTA firmware update
vwire/{deviceId}/alarm_ack	Forward the user's alarm stop/snooze action

---

Payload format

Payload size limits

Each pin type has a maximum value size (UTF-8 bytes). Messages that exceed the limit are silently dropped by the server.

Pin type	Max payload
Virtual (V0–V255)	1 024 bytes
Digital (D0–D99)	16 bytes
Analog (A0–A15)	16 bytes

The broker also enforces a 64 KB maximum MQTT packet size (topic + headers + payload). See Pins & Data Limits for full details.

Pin values

Pin values are wrapped in a JSON array.

["value"]

For multiple values at once:

["value1", "value2", "value3"]

Examples:

["23.5"]
["255"]
["48.858844,2.294351"]
["255","128","0"]

If you use the Arduino or Python library, the JSON wrapping is handled automatically. Raw MQTT clients must wrap values themselves.

Alarm payload

Custom clients sending alarms should publish JSON like this:

{
  "type": "alarm",
  "message": "Pump failure",
  "sound": "urgent",
  "priority": 3,
  "volume": 90,
  "timestamp": 1740000000000
}

Field	Required	Notes
type	Yes	Must be "alarm"
message	Yes	Alarm text shown to the user
sound	No	default, warning, or urgent
priority	No	1, 2, or 3
volume	No	0-100, defaults to 50
timestamp	No	Unix timestamp in milliseconds

Alarm acknowledgment payload

Custom MQTT clients that subscribe to vwire/{deviceId}/alarm_ack receive JSON like this when the user acts on an alarm:

{
  "alarmId": "alarm_1740000000000",
  "action": "snoozed",
  "snoozeMinutes": 5,
  "timestamp": 1740000123456
}

---

QoS levels

Message type	QoS	Rationale
Sensor data	0	Best-effort; occasional loss is acceptable
Commands	1	At-least-once delivery
OTA trigger	1	Must not be lost
LWT	1	Must be delivered on disconnect

---

Last Will Testament

The libraries configure LWT automatically during Vwire.begin():

Field	Value
LWT Topic	vwire/{deviceId}/status
LWT Payload	{"status":"offline"}
QoS	1
Retain	true

---

Keep-alive

The default keep-alive is 60 seconds.

• After roughly 30 seconds without traffic, the client sends a PINGREQ.
• If the broker receives no traffic for the keep-alive window, it considers the client disconnected and publishes the LWT.

---

Example raw MQTT session

# Publish temperature on V0
mosquitto_pub \
  -h mqtt.vwire.io -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -i "VW-ABC123" \
  -u "VW-ABC123" \
  -P "at_your-auth-token" \
  -t "vwire/VW-ABC123/pin/V0" \
  -m '["23.5"]'

# Subscribe to commands on V1
mosquitto_sub \
  -h mqtt.vwire.io -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -i "VW-ABC123" \
  -u "VW-ABC123" \
  -P "at_your-auth-token" \
  -t "vwire/VW-ABC123/cmd/V1"

# Subscribe to alarm acknowledgments in a custom client
mosquitto_sub \
  -h mqtt.vwire.io -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -i "VW-ABC123-listener" \
  -u "VW-ABC123" \
  -P "at_your-auth-token" \
  -t "vwire/VW-ABC123/alarm_ack"