Skip to main content

Vwire Python Library

The Vwire Python library connects Raspberry Pi, Linux SBCs, and any Python 3 environment to the Vwire IoT platform over MQTT/TLS.

Repository: github.com/vwireiot/vwire-python
Version: 2.0+ — API is consistent with the Arduino Vwire library.

Python 3.14+ note: There is a known incompatibility with paho-mqtt. Use Python 3.8–3.13.

Installation​

The library is not available on PyPI. Install directly from the GitHub repository:

# Clone the repository
git clone https://github.com/vwireiot/vwire-python.git

# Install in editable mode
cd vwire-python
pip install -e .

Verify installation​

python -c "from vwire import Vwire; print('Vwire installed successfully')"

Dependencies​

Installed automatically by pip:

  • paho-mqtt >= 2.0.0
  • requests >= 2.28.0

Minimum example​

import time
from vwire import Vwire

AUTH_TOKEN = "your-auth-token"
DEVICE_ID  = "VW-XXXXXX"        # Found in the Vwire dashboard

device = Vwire(AUTH_TOKEN, DEVICE_ID)

if not device.connect():
    raise SystemExit("Connection failed")

while True:
    device.virtual_send(0, 23.5)   # V0 = 23.5°C
    time.sleep(5)

Configuration​

from vwire import Vwire, VwireConfig

# Default: mqtt.vwire.io:8883 with TLS (recommended for production)
config = VwireConfig()

# Custom server endpoint
config = VwireConfig(broker="custom.mqtt.server", port=8883, use_tls=True)

device = Vwire(AUTH_TOKEN, DEVICE_ID, config=config)

API reference​

Vwire(auth_token, device_id, config=None)​

Create a Vwire client instance.

ParameterTypeDescription
auth_tokenstrDevice auth token from the dashboard
device_idstrDevice ID, e.g. "VW-ABC123"
configVwireConfigOptional — defaults to production TLS server

device.connect()​

Connect to the Vwire MQTT broker. Returns True on success, False on failure.

if not device.connect():
    print("Failed to connect!")

device.virtual_send(pin, value)​

Send a value to a virtual pin. Mirrors Vwire.virtualSend() in the Arduino library.

device.virtual_send(0, 23.5)         # float
device.virtual_send(1, 42)           # int
device.virtual_send(2, "message")    # string
device.virtual_send(3, "lat,lng")    # GPS coordinates

@device.on_virtual_receive(pin)​

Decorator to register a handler for incoming dashboard commands on a pin. Mirrors VWIRE_RECEIVE(Vn){} in Arduino.

@device.on_virtual_receive(0)
def handle_switch(value):
    # value is always a string — parse as needed
    state = int(value)
    print(f"Switch: {'ON' if state else 'OFF'}")

@device.on_virtual_receive(1)
def handle_slider(value):
    speed = float(value)
    print(f"Speed: {speed}")

device.sync_virtual(pin)​

Request the server to resend the last stored value for a pin. Use during initialization to restore state after a restart.

device.sync_virtual(1)   # triggers on_virtual_receive(1) with last saved value

device.disconnect()​

Gracefully disconnect from the MQTT broker.

Context manager​

with Vwire(AUTH_TOKEN, DEVICE_ID) as device:
    device.virtual_send(0, 25.0)
    time.sleep(1)
# Automatically disconnects

Timers​

Send data on a schedule without blocking your main loop:

from vwire import Vwire

device = Vwire(AUTH_TOKEN, DEVICE_ID)

def read_and_send():
    temperature = read_temperature()   # your sensor function
    device.virtual_send(0, temperature)

# Send every 5 seconds
device.timer.set_interval(5000, read_and_send)

device.connect()
device.run()   # blocks — processes events and timers

Notifications​

Send push notifications, persistent alarms, and emails from your Python device. Mirrors the Arduino library's notification methods. Requires a PRO plan or higher.

# Push notification — appears in app and bell notification
device.notify("Temperature exceeded 85°C")

# Persistent alarm — requires user acknowledgment in the app
device.alarm("🚨 Critical: Sensor failure detected!")

# Email notification
device.email(
    subject="Daily Report",
    body="All sensors nominal at 10:00 AM."
)

Full Raspberry Pi example​

#!/usr/bin/env python3
"""
Raspberry Pi sensor monitor with threshold alerts.
Clones and installs: pip install -e vwire-python/
"""

import time
from vwire import Vwire

AUTH_TOKEN = "your-auth-token"
DEVICE_ID  = "VW-XXXXXX"

device = Vwire(AUTH_TOKEN, DEVICE_ID)

# Handle LED control command from dashboard (V0 = Switch widget)
@device.on_virtual_receive(0)
def on_led_control(value):
    try:
        import RPi.GPIO as GPIO
        GPIO.setmode(GPIO.BCM)
        GPIO.setup(17, GPIO.OUT)
        GPIO.output(17, int(value))
    except Exception as e:
        print(f"GPIO error: {e}")

if not device.connect():
    raise SystemExit("Connection failed")

print("Connected to Vwire!")

last_alert = 0
ALERT_COOLDOWN = 60  # seconds between repeated alerts

while True:
    # Replace with real sensor reads
    temperature = read_temperature()
    humidity    = read_humidity()

    device.virtual_send(0, round(temperature, 1))
    device.virtual_send(1, round(humidity, 1))

    # Send alert if temperature exceeds threshold
    current_time = time.time()
    if temperature > 80 and (current_time - last_alert) > ALERT_COOLDOWN:
        last_alert = current_time
        device.notify(f"High temperature: {temperature}°C")

    time.sleep(10)

Run as a systemd service​

# /etc/systemd/system/vwire-monitor.service
[Unit]
Description=Vwire IoT Monitor
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/vwire-monitor
ExecStart=/usr/bin/python3 main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
sudo systemctl enable vwire-monitor
sudo systemctl start  vwire-monitor
sudo journalctl -u vwire-monitor -f  # live logs