MQTT Protocol Reference

Vwire uses a structured MQTT topic hierarchy for all device communication. This page covers the broker details, how authentication works, the topic schema, payload format, and keep-alive behaviour.

For the complete topic reference including notification and OTA topics, see the MQTT API Reference.

---

Broker endpoints

Field	Value
Host	mqtt.vwire.io
Port (TLS)	8883 (recommended)
Port (plain TCP)	1883
TLS	Required on port 8883
Protocol	MQTT 3.1.1

---

Authentication — two credentials

Every Vwire device has two separate credentials:

Credential	MQTT field	Purpose
Auth Token	password	Authenticates the connection
Device ID (e.g. VW-ABC123)	clientId and username	Identifies which MQTT topics belong to this device

Both are available on the device detail page in the dashboard. The library sets them automatically when you call Vwire.config(AUTH_TOKEN) and Vwire.setDeviceId(DEVICE_ID).

---

Topic schema

All topics use the Device ID (never the auth token) as the identifier:

Device → Server

Topic	Purpose
vwire/{deviceId}/pin/{pin}	Publish virtual pin value (e.g. pin/V0)
vwire/{deviceId}/status	Device online / offline (LWT)
vwire/{deviceId}/heartbeat	Device health (uptime, heap, RSSI, IP, firmware)
vwire/{deviceId}/sync/{pin}	Request server to resend last stored value for pin
vwire/{deviceId}/notify	Push notification to user
vwire/{deviceId}/alarm	Persistent alarm requiring acknowledgment
vwire/{deviceId}/email	Email notification to user
vwire/{deviceId}/ack/{msgId}	Reliable delivery acknowledgment
vwire/{deviceId}/ota_status	OTA progress / result report
vwire/{deviceId}/log	Debug log message

Server → Device

Topic	Purpose
vwire/{deviceId}/cmd/{pin}	Dashboard writes a value to a pin (e.g. cmd/V1)
vwire/{deviceId}/ota	OTA firmware command (URL, hash, version)
vwire/{deviceId}/alarm_ack	Alarm acknowledgment from mobile app

---

Payload format

All pin values are wrapped in a JSON array:

["value"]

For multiple values at once (multi-param):

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

Examples:

["23.5"]                   ← temperature
["255"]                    ← integer
["48.858844,2.294351"]     ← GPS as string
["255","128","0"]          ← R, G, B

The Vwire library handles JSON wrapping automatically via Vwire.virtualSend(). If you publish raw MQTT, wrap values in a JSON array.

---

QoS levels

Message type	QoS	Rationale
Sensor data (frequent)	0	Best-effort; occasional loss acceptable
Commands (control)	1	At-least-once; duplicates handled on device
OTA trigger	1	Must not be lost
LWT	1	Must be delivered on disconnect

---

Last Will Testament (LWT)

The library configures LWT automatically during Vwire.begin():

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

---

Keep-alive

The library sets the MQTT keep-alive to 60 seconds.
After 30 seconds without a PUBLISH, the client sends a PINGREQ.
If the broker receives no traffic for 60 seconds, it publishes the LWT and disconnects the client.

---

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"

---

Broker endpoints

Field	Value
Host	app.vwire.io
Port (MQTTS)	8883
Port (WebSocket TLS)	443
TLS	Required
Authentication	Device Token

---

Topic schema

All topics follow the pattern:

vwire/{deviceToken}/{direction}/{pinType}/{pinNumber}

Publish (device → server)

Topic	Purpose
vwire/{token}/data/v/{pin}	Push virtual pin value
vwire/{token}/status	Device status / heartbeat
vwire/{token}/info	Device metadata (firmware version, etc.)

Subscribe (server → device)

Topic	Purpose
vwire/{token}/cmd/v/{pin}	Receive value written to virtual pin
vwire/{token}/ota	OTA firmware update trigger
vwire/{token}/sync	Sync pin values on reconnect

---

Payload format

Virtual pin value

["value"]

or for multiple values at once:

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

Examples:

["23.5"]                      ← temperature
["255"]                       ← integer
["48.858844,2.294351"]        ← GPS as string
["{\"a\":1,\"b\":2}"]         ← JSON string escaped

The VWire library handles JSON wrapping automatically via virtualSend(). If you publish raw MQTT, wrap values in a JSON array.

---

QoS levels

Message type	QoS	Rationale
Sensor data (frequent)	0	Best-effort; occasional loss acceptable
Commands (control)	1	At-least-once; duplicates handled on device
OTA trigger	1	Must not be lost
LWT	1	Must be delivered on disconnect

---

Last Will Testament (LWT)

The library configures LWT automatically during Vwire.begin():

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

When the device disconnects cleanly or drops, the broker publishes this automatically.

---

Keep-alive

The library sets the MQTT keep-alive to 60 seconds by default.
After keepAlive / 2 seconds without a PUBLISH (30 s), the client sends a PINGREQ.
If the broker receives no PINGREQ for keepAlive seconds, it considers the client disconnected and publishes the LWT.

---

Example raw MQTT session

# Using mosquitto_pub to publish temperature
mosquitto_pub \
  -h app.vwire.io -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -u "dt_your-device-token" \
  -P "dt_your-device-token" \
  -i "dt_your-device-token" \
  -t "vwire/dt_your-device-token/data/v/0" \
  -m '["23.5"]'

# Subscribe to commands on V1
mosquitto_sub \
  -h app.vwire.io -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -u "dt_your-device-token" \
  -P "dt_your-device-token" \
  -i "dt_your-device-token" \
  -t "vwire/dt_your-device-token/cmd/v/1"