Key Concepts

Understanding these building blocks makes the rest of VWire much easier to navigate.

---

Pins

VWire supports three pin types, and a single device can use all of them at once.

Pin type	Range	What it represents	Common use
Virtual pins	V0-V255	Software-defined data channels	Sensor values, commands, text, GPS, RGB tuples
Digital pins	D0-D99	Physical digital I/O lines	Relays, switches, buttons, LEDs
Analog pins	A0-A15	Physical analog input channels	Potentiometers, analog sensors, raw ADC values

Virtual pins

Virtual pins do not map to a specific hardware pin. Your firmware decides what each pin means, and widgets simply read or write that named channel.

Device publishes:   V0 = "23.5"
Widget reads:       23.5 C
Widget writes:      V5 = "1"
Device receives:    command on V5

Use virtual pins when you want full control over serialization, scaling, and device-side behavior.

Digital and analog pins

Digital and analog pins refer to real hardware pins on the board. They are especially useful with the Arduino GPIO Pin Manager, which lets the dashboard talk directly to D and A pins.

Important: VWire uses board-label pin names, not one universal raw GPIO numbering scheme.

• On ESP8266/NodeMCU, D4 maps to GPIO2.
• On ESP32 and most other boards, D4 maps directly to GPIO4.
• Analog pins follow the board's own A0, A1, and similar mapping.

Choose the label printed on your board or the official board pin map when binding widgets to physical pins.

Arduino GPIO Pin Manager

The Arduino library includes a GPIO Pin Manager that can configure, poll, and write physical pins automatically.

• Call Vwire.enableGPIO() before Vwire.begin().
• Configure pin modes from the dashboard.
• Bind widgets directly to D and A pins without writing a separate VWIRE_RECEIVE handler for each one.

See GPIO Pin Manager for supported modes, mappings, and examples.

---

Devices

A device is any MQTT-capable hardware that authenticates with its Auth Token and Device ID.

Field	Details
Auth Token	Private secret used to authenticate the MQTT connection
Device ID	Public identifier used in MQTT topics and external APIs
Status	Online / Offline state tracked from MQTT activity
Last Seen	Timestamp of the most recent device activity
Heartbeat	Optional periodic payload with uptime, RSSI, heap, IP, and firmware info

---

Projects

A project is a dashboard that groups widgets, notification rules, and sharing settings around a use case.

Projects can be shared with other VWire users at different permission levels such as Viewer, Operator, Editor, and Admin.

---

Widgets

Widgets are the visible controls and displays inside a project. Each widget binds to a device + pin pair, and that pin can be virtual, digital, or analog depending on the workflow.

There are 29 widget types. See Widget Overview for the full catalog.

---

Notifications

VWire can deliver notifications through three channels:

Channel	How it works
In-app bell	Stored in notification history inside the dashboard
Mobile push	Sent to registered mobile app devices with notification permission
Email	Controlled by plan availability and the user's email preferences

To reduce spam, VWire applies a short device-boot quiet window, caps general notifications at 60 per minute per device, and rate-limits alarms separately.