Pins & Data Limits

VWire devices exchange data through pins — named channels identified by a letter prefix and a number. Every pin value is stored as a UTF-8 string regardless of the declared data type. The platform enforces strict payload size limits per pin type to protect bandwidth, storage, and memory on constrained microcontrollers.

---

Pin types

Prefix	Range	Typical use	Max payload
V (Virtual)	V0 – V255	Application data — strings, JSON, sensor arrays, display text	1 024 bytes
D (Digital)	D0 – D99	GPIO read/write — 0 or 1	16 bytes
A (Analog)	A0 – A15	ADC readings — numeric values	16 bytes

Bare numbers are virtual

If you publish to pin 0 (no prefix), VWire automatically treats it as V0.

---

Payload size limits

Limits are measured in bytes (UTF-8 encoded). They apply uniformly across every ingress path:

Entry point	Enforcement
MQTT publish (vwire/{deviceId}/pin/{pin})	Value silently dropped
REST API (PUT /api/v1/devices/:id/pins/:pin)	400 VALUE_TOO_LARGE
WebSocket (pin:write)	Error event emitted to sender
Simple API (GET /external/api/update)	400 VALUE_TOO_LARGE
Batch update (POST /external/api/batch-update)	Oversized pin skipped (delivered: false)

Why these numbers?

Pin type	Limit	Rationale
Virtual	1 024 B (1 KB)	Generous for JSON payloads, GPS coordinates, display strings, and multi-value arrays while still fitting comfortably in a single MQTT packet.
Digital	16 B	Digital pins represent binary GPIO state. Values beyond a short number are invalid.
Analog	16 B	ADC values and numeric readings. A 16-byte string covers any floating-point representation.

Data beyond the limit is rejected

Oversized payloads are rejected entirely — they are not truncated. Make sure your firmware stays within limits before publishing.

---

Data types

When you create a widget bound to a pin, VWire associates a data type with that pin for display and charting purposes. Regardless of data type, the value is always transmitted and stored as a string. The payload size limit of the pin type still applies.

Data type	Example values	Notes
INTEGER	0, 1, 255, -10	Whole numbers
FLOAT	23.5, -0.01, 3.14159	Decimal numbers
STRING	Hello, ON, {"lat":48.8,"lon":2.3}	Arbitrary text or JSON
BOOLEAN	0 / 1, true / false	Binary state
JSON	{"temp":23,"hum":60}	Structured data — must still fit within the pin's byte limit

---

Best practices

1. Keep payloads small. Embedded devices have limited RAM. Sending 1 KB per pin update at high frequency will exhaust heap on ESP8266.
2. Use virtual pins for complex data. Digital and analog pins are designed for simple numeric values. If you need to send JSON or strings, use a virtual pin.
3. Batch when possible. The /batch-update API endpoint and the Arduino library's Vwire.virtualWrite() inside VWIRE_WRITE() handlers avoid per-message overhead.
4. Validate on the device side. Check strlen() or sizeof() before publishing to avoid silent drops on the MQTT path.