Vwire Arduino Library

Version 3.1.0 — connects ESP32, ESP8266, and compatible boards to the VwireIOT cloud via secure MQTT.

Source: github.com/vwireiot/vwire-arduino

---

Supported boards

Board	TCP	TLS (recommended)	Cloud OTA
ESP32	✅	✅	✅
ESP8266	✅	✅	✅
RP2040 (Pico W)	✅	⚠️ Limited	❌
Arduino (WiFiNINA / Ethernet)	✅	❌	❌
SAMD	✅	❌	❌

---

Installation

Arduino Library Manager

1. Sketch → Include Library → Manage Libraries
2. Search Vwire and click Install
3. Also install the dependencies: PubSubClient and ArduinoJson

PlatformIO

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
    parvaizahmad/VWire
    knolleary/PubSubClient
    bblanchon/ArduinoJson

Manual

Download the ZIP from GitHub and install via Sketch → Include Library → Add .ZIP Library.

---

Minimal sketch

#include <Vwire.h>

const char* WIFI_SSID     = "YOUR_WIFI_SSID";
const char* WIFI_PASSWORD = "YOUR_WIFI_PASSWORD";

// Both values from device settings in the dashboard
const char* AUTH_TOKEN = "YOUR_AUTH_TOKEN";
const char* DEVICE_ID  = "YOUR_DEVICE_ID";   // e.g. VU-ABC123

VWIRE_CONNECTED() {
  Serial.println("Connected!");
  Vwire.syncVirtual(V0);   // request last stored value
}

void setup() {
  Serial.begin(115200);

  Vwire.config(AUTH_TOKEN);
  Vwire.setDeviceId(DEVICE_ID);
  Vwire.begin(WIFI_SSID, WIFI_PASSWORD);
}

void loop() {
  Vwire.run();

  static unsigned long last = 0;
  if (Vwire.connected() && millis() - last >= 2000) {
    last = millis();
    Vwire.virtualSend(V0, analogRead(A0));
  }
}

---

API reference

Configuration

Vwire.config(authToken)

Configure using only the auth token. Connects to mqtt.vwire.io:8883 over TLS by default.

Vwire.config("YOUR_AUTH_TOKEN");

Vwire.config(authToken, server, port)

Configure with a custom server and port.

Vwire.config("YOUR_AUTH_TOKEN", "mqtt.vwire.io", 8883);

Vwire.setDeviceId(deviceId)

Set the device ID (shown in the dashboard device settings, e.g. VU-ABC123). Call after config() and before begin().

Vwire.setDeviceId("VU-ABC123");

Vwire.setTransport(transport)

Override the transport protocol. Default is TLS.

Vwire.setTransport(VWIRE_TRANSPORT_TCP_SSL);  // TLS port 8883 (default, recommended)
Vwire.setTransport(VWIRE_TRANSPORT_TCP);      // Plain TCP port 1883

Use plain TCP only on boards that don't support TLS (RP2040, SAMD, some Arduino models).

---

Connection

Vwire.begin(ssid, password)

Connect to WiFi and the Vwire cloud. Blocks until connected or times out.

bool ok = Vwire.begin(WIFI_SSID, WIFI_PASSWORD);
if (!ok) {
  Serial.printf("Error: %d\n", Vwire.getLastError());
}

Vwire.run()

Process MQTT messages and maintain the connection. Must be called on every loop() iteration.

void loop() {
  Vwire.run();
  // your code here
}

Vwire.connected()

Returns true if currently connected to the MQTT broker.

Vwire.disconnect()

Cleanly disconnect from the MQTT broker.

---

Sending data (device → cloud)

Vwire.virtualSend(pin, value)

Send a value to a virtual pin. Supported types: int, float, bool, String, const char*.

Vwire.virtualSend(V0, 23.5);        // float
Vwire.virtualSend(V1, 42);          // int
Vwire.virtualSend(V2, true);        // bool (sends "1" or "0")
Vwire.virtualSend(V3, "hello");     // string
Vwire.virtualSend(100, sensorVal);  // pin 100 (beyond V31 macro range)

Vwire.virtualSendArray(pin, values, count)

Send multiple values to one pin as a comma-separated payload.

float readings[3] = { 1.1, 2.2, 3.3 };
Vwire.virtualSendArray(V5, readings, 3);

int data[2] = { 100, 200 };
Vwire.virtualSendArray(V6, data, 2);

Vwire.virtualSendf(pin, format, ...)

Send a formatted string to a pin (printf-style).

Vwire.virtualSendf(V7, "%.1f°C / %.1f%%", temp, humidity);

---

Receiving data (cloud → device)

VWIRE_RECEIVE(pin) { ... }

Handler macro — declare outside setup() and loop(). Automatically registered; no manual call needed. The variable param (type VirtualPin&) holds the received value.

VWIRE_RECEIVE(V0) {
  int value = param.asInt();
  digitalWrite(LED_BUILTIN, value);
}

VWIRE_RECEIVE(V1) {
  float setpoint = param.asFloat();
  Serial.printf("New setpoint: %.1f\n", setpoint);
}

Vwire.onVirtualReceive(pin, handler) (manual)

Register a handler at runtime instead of using the macro.

void onLedChange(VirtualPin& p) {
  digitalWrite(LED_BUILTIN, p.asBool());
}

void setup() {
  Vwire.onVirtualReceive(V0, onLedChange);
  // ...
}

---

VirtualPin value methods

The param object inside VWIRE_RECEIVE provides:

Method	Return type	Description
param.asInt()	int	Value as integer
param.asFloat()	float	Value as float
param.asDouble()	double	Value as double
param.asBool()	bool	true for "1", "true", "on"
param.asString()	String	Raw string value
param.asCString()	const char*	Raw C-string
param.getArraySize()	int	Number of comma-separated elements
param.getArrayInt(i)	int	i-th element as int
param.getArrayFloat(i)	float	i-th element as float

---

Connection handlers

VWIRE_CONNECTED() {
  Serial.println("Connected to VwireIOT!");
  Vwire.sync(V0, V1);   // restore last values
}

VWIRE_DISCONNECTED() {
  Serial.println("Disconnected!");
}

---

Sync (restore stored values)

After a reboot the device can request the last value stored in the cloud for any pin:

Vwire.syncVirtual(V0);         // sync one pin
Vwire.sync(V0, V1, V2);       // sync multiple pins
Vwire.syncAll();               // sync all pins

Typically called inside VWIRE_CONNECTED().

---

Notifications

Vwire.notify(message)

Send a push notification to the user's mobile app.

Vwire.notify("Motion detected!");

Vwire.alarm(message)

Send a persistent alarm notification (sound + high-priority push).

Vwire.alarm("Temperature critical!");

Available sound options for Vwire.alarm(message, sound): "default", "urgent", "warning".

Vwire.alarm("Pump failure", "urgent");
Vwire.alarm("Low battery", "warning", 2);  // priority: 1=normal, 2=high, 3=critical

note

alarm() requires Pro plan or above. Calls from Free accounts are silently ignored.

Vwire.email(subject, body)

Send an email notification.

Vwire.email("Sensor alert", "Temperature exceeded 40°C");

note

email() requires Pro plan or above.

---

OTA updates (ESP32/ESP8266 only)

Local OTA (Arduino OTA)

void setup() {
  Vwire.config(AUTH_TOKEN);
  Vwire.setDeviceId(DEVICE_ID);
  Vwire.enableOTA("my-device");   // optional hostname and password
  Vwire.begin(WIFI_SSID, WIFI_PASSWORD);
}

Cloud OTA (triggered from dashboard)

Vwire.enableCloudOTA();   // call before begin()

With Cloud OTA enabled, you can push firmware updates directly from the VwireIOT dashboard without physical access.

---

Reliable delivery

Enable application-level acknowledgment for critical data:

Vwire.setReliableDelivery(true);
Vwire.setAckTimeout(5000);    // ms to wait for ACK (default 5000)
Vwire.setMaxRetries(3);       // retry count before dropping (default 3)

---

Debugging

Vwire.setDebug(true);         // print debug output to Serial
Vwire.printDebugInfo();       // print version, board, connection status, memory
Serial.println(Vwire.getVersion());    // "3.1.0"
Serial.println(Vwire.getBoardName()); // "ESP32", "ESP8266", etc.
Serial.println(Vwire.getFreeHeap());  // free RAM in bytes

---

Virtual pin numbers

Convenience macros V0–V31 are defined. For pins above V31, use the number directly:

Vwire.virtualSend(V0, val);   // pin 0
Vwire.virtualSend(50, val);   // pin 50
Vwire.virtualSend(255, val);  // pin 255 (maximum)

---

Connection settings

Method	Default	Description
Vwire.setAutoReconnect(bool)	true	Auto-reconnect on drop
Vwire.setReconnectInterval(ms)	5000	Delay between reconnect attempts
Vwire.setHeartbeatInterval(ms)	15000	Heartbeat interval