Vwire IoT Python Library

Official Python client library for the Vwire IoT Platform - enabling seamless communication between your Python applications and IoT devices.

The API is designed to be consistent with the Arduino Vwire library, making it easy to port code between platforms and maintain a unified development experience.

Arduino ↔ Python Method Mapping

Arduino	Python	Description
`Vwire.config(token)`	`Vwire(token, device_id)`	Initialize client
`Vwire.setDeviceId(id)`	(built into constructor)	Set device ID
`Vwire.begin(ssid, pass)`	`connect()`	Connect to server
`Vwire.run()`	`run()`	Block and process messages
`Vwire.connected()`	`connected`	Check connection
`Vwire.virtualSend(pin, v)`	`virtual_send(pin, v)`	Send data
`VWIRE_RECEIVE(pin)`	`@on_virtual_receive(pin)`	Receive data
`Vwire.syncVirtual(pin)`	`sync_virtual(pin)`	Sync pin value
`Vwire.syncAll()`	`sync_all()`	Sync all pins
`Vwire.notify(msg)`	`notify(msg)`	Push notification
`Vwire.alarm(msg[,sound][,pri])`	`alarm(msg[,sound][,pri])`	Persistent alarm
`Vwire.email(s, b)`	`email(s, b)`	Send email
`Vwire.log(msg)`	`log(msg)`	Send log message

Note: Unlike Arduino, the Python library uses a background thread for MQTT operations. Messages are sent immediately when you call virtual_send() - no manual loop() or run() call is required after each send.

Features

Secure by Default - MQTT over TLS (port 8883) for encrypted communication
Real-time Communication - Bidirectional data flow with MQTT
Built-in Timer - Schedule tasks
Multiple Transports - MQTT, MQTT over WebSocket, HTTP fallback
Pythonic API - Clean, decorator-based event handling
Cross-Platform - Works on Raspberry Pi, Linux, Windows, macOS
Minimal Dependencies - Only requires paho-mqtt and requests

Installation

From PyPI (Recommended)

pip install vwire-iot

From Source

git clone https://github.com/vwireiot/vwire-python.git
cd vwire-python
pip install -e .

Dependencies

pip install paho-mqtt>=2.0.0 requests>=2.28.0

Quick Start

1. Get Your Auth Token

Create an account at vwire.io
Create a new project
Add a device and copy the Auth Token

2. Basic Usage

from vwire import Vwire

# Create client with your auth token and device ID
device = Vwire("your-auth-token-here", "VW-ABC123")  # Device ID is required

# Connect to server (uses secure TLS by default)
device.connect()

# Send data to virtual pins
device.virtual_send(0, 25.5)  # Temperature
device.virtual_send(1, 60)    # Humidity

# Disconnect when done
device.disconnect()

2. Device ID Configuration

Device ID is required and should be obtained from the Vwire dashboard. It follows the format VW-XXXXXX (OEM devices) or VU-XXXXXX (user-created devices).

from vwire import Vwire

# Device ID is required (system-generated from dashboard)
device = Vwire("your-auth-token-here", "VW-ABC123")

# Device ID is used for MQTT topics instead of auth token
# Topics become: vwire/VW-ABC123/pin/V0, etc.
device.connect()
device.virtual_send(0, 25.5)

Why Device ID is Required:

All MQTT topics now use device ID for pub/sub routing
Better organization and scalability
Auth token remains private (authentication only)
Consistent with Arduino library implementation

3. Receiving Commands

from vwire import Vwire

device = Vwire("your-auth-token-here")

# Handle commands from dashboard widgets
@device.on_virtual_receive(0)
def handle_slider(value):
    print(f"Slider value: {value}")
    # Control your hardware here

@device.on_virtual_receive(1)
def handle_button(value):
    if value == "1":
        print("Button pressed!")

# Connect and run event loop
device.connect()
device.run()

4. Using Timers

from vwire import Vwire

device = Vwire("your-auth-token-here")

def send_sensor_data():
    temp = read_temperature()  # Your sensor reading
    device.virtual_send(0, temp)

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

device.connect()
device.run()

API Reference

Vwire Class

The main client class for IoT communication.

Constructor

Vwire(auth_token, config=None, server=None, port=None)

Parameter	Type	Description
`auth_token`	str	Device authentication token from dashboard
`config`	VwireConfig	Optional configuration object
`server`	str	Override server hostname
`port`	int	Override MQTT port

Connection Methods

Method	Description
`connect(timeout=30)`	Connect to server. Returns `True` if successful.
`disconnect()`	Disconnect from server.
`run(blocking=True)`	Run event loop. Set `blocking=False` for background mode.
`connected`	Property: `True` if connected.

Virtual Pin Operations

Method	Description
`virtual_send(pin, value)`	Send value to virtual pin V0-V255.
`virtual_send(pin, v1, v2, ...)`	Send multiple values (for arrays).
`virtual_read(pin)`	Read last known value of virtual pin.
`sync_virtual(pin)`	Request sync of specific pin from server.
`sync_all()`	Request sync of all pins from server.

Event Handlers

# Decorator syntax (matches Arduino VWIRE_RECEIVE macro)
@device.on_virtual_receive(pin)
def handler(value):
    pass

# Generic syntax
@device.on(Vwire.VIRTUAL_RECEIVE, pin)
def handler(value):
    pass

Notifications & Logging

These methods match the Arduino library API. Note: notify(), alarm(), and email() are only available for paid plans (PRO, PRO+, ENTERPRISE).

Method	Arduino Equivalent	Description
`notify(message)`	`Vwire.notify(msg)`	Send push notification to device owner
`alarm(message[, sound][, priority])`	`Vwire.alarm(msg[,sound][,pri])`	Send persistent alarm to mobile device
`email(subject, body)`	`Vwire.email(s, b)`	Send email to device owner
`log(message)`	`Vwire.log(msg)`	Send log message to server

# Send notifications (paid plans only)
device.notify("Temperature alert: exceeded 30°C!")

# Send persistent alarm (paid plans only)
device.alarm("Critical temperature alert!", "urgent", 5)

# Send email (paid plans only)
device.email(
    "Sensor Alert", 
    "Temperature has exceeded the configured threshold of 30°C."
)

# Send log message for debugging
device.log("Sensor initialized successfully")

`alarm(message[, sound][, priority])`

Triggers a persistent alarm on the mobile device that plays a ringtone and requires user interaction to stop. Unlike notify(), alarms cannot be dismissed by tapping - they require explicit STOP or SNOOZE action.

Parameters:

message (str): Alarm message to display
sound (str, optional): Sound type ("default", "urgent", "warning"). Default: "default"
priority (int, optional): Priority level 1-5 (5 being highest). Default: 1

Example:

# Basic alarm
device.alarm("Temperature critical!")

# Alarm with custom sound and high priority
device.alarm("Security breach detected!", "urgent", 5)

Note: Alarms are deduplicated within 10-second windows to prevent spam. Only available for paid plans.

VwireConfig Class

Configuration for the Vwire client.

from vwire import VwireConfig

# Default (secure TLS connection)
config = VwireConfig()

# Development mode (for local testing)
config = VwireConfig.development("localhost", 1883)

# WebSocket mode (when MQTT ports are blocked)
config = VwireConfig.websocket()

# Custom configuration
config = VwireConfig.custom(
    server="iot.mycompany.com",
    mqtt_port=8883,
    use_tls=True
)

VwireTimer Class

Timer for scheduling periodic tasks.

from vwire import VwireTimer

timer = VwireTimer()

# Run every 5 seconds
timer_id = timer.set_interval(5000, my_function)

# Run once after 10 seconds
timer.set_timeout(10000, one_time_function)

# Control timers
timer.enable_timer(timer_id)
timer.disable_timer(timer_id)
timer.delete_timer(timer_id)
timer.change_interval(timer_id, 3000)  # Change to 3 seconds

# In manual loop
while True:
    timer.run()
    time.sleep(0.01)

# Or start background thread
timer.start()

VwireHTTP Class

HTTP client for simple operations without persistent connection.

from vwire import VwireHTTP

client = VwireHTTP("your-auth-token")

# Send to pins
client.virtual_send(0, 25.5)
client.virtual_send(1, 60)

# Batch send
client.write_batch({
    "V0": 25.5,
    "V1": 60,
    "V2": 1013
})

# Read from server
value = client.virtual_read(0)

Configuration Options

Transport Modes

Mode	Port	Description
TCP + TLS	8883	Default. Secure MQTT connection.
TCP	1883	Insecure. Development only.
WebSocket + TLS	443	Secure. Works through most firewalls.
WebSocket	80	Insecure. Development only.

Server Configuration

from vwire import Vwire, VwireConfig

# Production (default)
device = Vwire("token")  # Uses mqtt.vwire.io:8883

# Custom server
device = Vwire("token", server="iot.mycompany.com")

# Development
config = VwireConfig.development("192.168.1.100")
device = Vwire("token", config=config)

Examples

The examples/ directory contains comprehensive examples:

Example	Description
`01_basic_send.py`	Basic data sending
`02_receive_commands.py`	Handle dashboard commands
`03_timer_example.py`	Using VwireTimer
`04_weather_station.py`	Complete weather station
`05_smart_home.py`	Bidirectional smart home
`06_raspberry_pi_gpio.py`	Real GPIO with Raspberry Pi
`07_http_api.py`	HTTP API usage
`08_data_logger.py`	Production data logger
`09_alarm_notifications.py`	Push notifications, alarms & email

Comparison with Arduino Library

The Python library mirrors the Arduino Vwire library API:

Arduino	Python
`Vwire.virtualSend(V0, value)`	`device.virtual_send(0, value)`
`Vwire.virtualRead(V0)`	`device.virtual_read(0)`
`VWIRE_RECEIVE(V0) { ... }`	`@device.on_virtual_receive(0)`
`timer.setInterval(1000, func)`	`device.timer.set_interval(1000, func)`
`Vwire.begin(auth)`	`device.connect()`
`Vwire.run()`	`device.run()`

Platform Support

Platform	Status	Notes
Raspberry Pi	Full	GPIO support with RPi.GPIO
Linux	Full	All features
Windows	Full	All features
macOS	Full	All features
Docker	Full	Great for microservices

Troubleshooting

Connection Issues

"Not authorized" error:

Verify your auth token is correct
Check that the device exists in dashboard
Ensure the token hasn't been regenerated

"Connection timeout":

Check network connectivity
Verify server address and port
Check firewall settings (port 8883 for MQTT)

On Windows with WSL/Docker: If localhost connections fail, use your machine's IP:

from vwire import get_local_ip
config = VwireConfig.development(get_local_ip())

SSL Certificate Issues

For self-signed certificates:

config = VwireConfig.custom(
    server="your-server.com",
    use_tls=True,
    verify_ssl=False  # Not recommended for production
)

Debug Logging

Enable debug output:

from vwire.utils import setup_logging
import logging

setup_logging(level=logging.DEBUG)

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Vwire IoT Python Library

Arduino ↔ Python Method Mapping

Features

Installation

From PyPI (Recommended)

From Source

Dependencies

Quick Start

1. Get Your Auth Token

2. Basic Usage

2. Device ID Configuration

3. Receiving Commands

4. Using Timers

API Reference

Vwire Class

Constructor

Connection Methods

Virtual Pin Operations

Event Handlers

Notifications & Logging

`alarm(message[, sound][, priority])`

VwireConfig Class

VwireTimer Class

VwireHTTP Class

Configuration Options

Transport Modes

Server Configuration

Examples

Comparison with Arduino Library

Platform Support

Troubleshooting

Connection Issues

SSL Certificate Issues

Debug Logging

Contributing

License

Links

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Vwire IoT Python Library

Arduino ↔ Python Method Mapping

Features

Installation

From PyPI (Recommended)

From Source

Dependencies

Quick Start

1. Get Your Auth Token

2. Basic Usage

2. Device ID Configuration

3. Receiving Commands

4. Using Timers

API Reference

Vwire Class

Constructor

Connection Methods

Virtual Pin Operations

Event Handlers

Notifications & Logging

alarm(message[, sound][, priority])

VwireConfig Class

VwireTimer Class

VwireHTTP Class

Configuration Options

Transport Modes

Server Configuration

Examples

Comparison with Arduino Library

Platform Support

Troubleshooting

Connection Issues

SSL Certificate Issues

Debug Logging

Contributing

License

Links

`alarm(message[, sound][, priority])`