Skip to main content

Connecting a Device

This guide walks through adding a new device and connecting it to VWire using the Arduino / ESP32 library.

1. Create the device in the dashboard​

  1. Go to your Project → click + Add Device.
  2. Enter a name (e.g. "Greenhouse Sensor") and click Create.
  3. Copy two credentials from the device detail page:
CredentialExamplePurpose
Auth Tokenat_xxxxxxxxMQTT password — proves who you are
Device IDVW-ABC123Your device's address in MQTT topics

Both are required. The Auth Token authenticates the connection; the Device ID is what your firmware uses in Vwire.setDeviceId().

2. Install the Vwire library​

Manual install from GitHub​

The VWire Arduino library is not currently available in Arduino Library Manager.

  1. Download the latest VWire Arduino ZIP archive from the official VWire GitHub repository.
  2. Open Arduino IDE → Sketch → Include Library → Add .ZIP Library.
  3. Select the downloaded ZIP archive.
  4. Install PubSubClient and ArduinoJson as dependencies.

PlatformIO​

Place the VWire library in your project's local lib/VWire directory, then declare the remaining dependencies in platformio.ini:

; platformio.ini
lib_deps = 
  knolleary/PubSubClient
  bblanchon/ArduinoJson

3. Basic sketch​

#define VWIRE_PRINT_DEBUG  // remove in production
#include <Vwire.h>

// ── Configuration ──────────────────────────────────────────
const char* SSID       = "YourWiFiSSID";
const char* PASSWORD   = "YourWiFiPassword";
const char* AUTH_TOKEN = "at_your-auth-token-here";  // from dashboard
const char* DEVICE_ID  = "VW-XXXXXX";               // from dashboard

// ── Receive commands from dashboard ───────────────────────
VWIRE_RECEIVE(V1) {
  int val = param.asInt();
  digitalWrite(LED_BUILTIN, val);
}

// ── Setup ──────────────────────────────────────────────────
void setup() {
  Serial.begin(115200);
  pinMode(LED_BUILTIN, OUTPUT);

  Vwire.config(AUTH_TOKEN);     // set auth token
  Vwire.setDeviceId(DEVICE_ID); // set device ID
  Vwire.begin(SSID, PASSWORD);  // connect (uses mqtt.vwire.io:8883 by default)
}

// ── Loop ───────────────────────────────────────────────────
void loop() {
  Vwire.run();  // MUST be called in every loop iteration

  float temperature = 23.5;  // replace with real sensor read
  Vwire.virtualSend(V0, temperature);

  delay(5000);
}

4. Verify connection​

Check the Serial Monitor (115200 baud) for:

[VWire] Connecting to WiFi ...
[VWire] WiFi connected — 192.168.1.105
[VWire] Connecting to MQTT broker ...
[VWire] Connected to VWire!

The device status in the dashboard should change from Offline to Online within a few seconds.

5. Troubleshooting​

SymptomLikely causeFix
Stuck at "Connecting to WiFi"Wrong SSID/passwordDouble-check credentials
"MQTT connect failed: 5"Wrong auth tokenRe-copy Auth Token from dashboard
"MQTT connect failed: 3"Network / broker unreachableCheck WiFi and firewall on port 8883
Device shows offline in dashboardLWT published prematurelyEnsure Vwire.run() is called every loop
Values not appearingWrong pin numberMatch V-pin in firmware and widget

6. Next steps​