MQTT 5 & Mosquitto Broker Technical Reference

This technical guide defines the network architecture, endpoint definitions, security configurations, and messaging topic topology enforced across the Virtuino Cloud MQTT broker backend layers.

1. Broker Connection Endpoints

Standard Encrypted Port (MQTTS) Host: broker.virtuino.com
Port: 8883 (TLS Encrypted)

Encrypted WebSockets Port (WSS) Host: broker.virtuino.com/mqtt
Port: 443 (Secure WebSockets)

2. Authentication & Guard Verification

The Mosquitto access layers demand explicit plain-text credential tokens sent during the initial MQTT CONNECT negotiation sequence.

Username Parameter Your registered account email address (e.g., engineer@domain.com)

Password Parameter Your private alphanumeric cloud system API Key token.

3. Encryption and Transport Layer Security (TLS)

To eliminate eavesdropping risks, port 8883 runs standard TLS 1.3 encryption mechanisms. If your physical client library demands an explicit Root Certificate Authority profile to establish a secure handshake, supply the official ISRG Root X1 certificate authority parameters.

4. QoS (Quality of Service) Support Matrix

QoS 0 (At most once): Lowest latency transmission option. Highly optimized for non-critical periodic sensor updates like ambient air temperature streams.
QoS 1 (At least once): Enforces delivery confirmations via broker acknowledgments. Highly recommended for control feedback triggers, alarm alerts, and relay actuator operations.
QoS 2 (Exactly once): Not supported globally on basic application server channels to maintain maximum runtime scalability thresholds.

5. Messaging Topic Topology

The platform restricts message isolation to prevent accidental namespace cross-contamination. Topics must adhere strictly to the following directory template layout:

Base Topic Structural Format [user_broker_hash_prefix]/device/[device_id]/[channel_or_property]

Example Active Topic String: Given a unique system broker identification string prefix of vr_f687sjdd and an explicit peripheral controller labeled Pump_Controller, the matching topics appear as follows:

5a. Publishing Sensor Data Metrics

// Post raw metric floats to sync data visualization dashboards. Target Topic vr_f687sjdd/device/Pump_Controller/V1 Payload Packet String "45.20"

5b. Subscribing to Actuator Triggers

// Listen for incoming toggle adjustments issued from cloud UI panels. Target Topic vr_f687sjdd/device/Pump_Controller/V2 Expected Payload String "1"

5c. Multi-Level Wildcard Topic Subscriptions (#)

// Replaces all subsequent trailing directory branches recursively. Subscribe Topic vr_f687sjdd/device/#

Enables monitoring all published telemetry packets flowing from all local system nodes belonging to this profile token.

5d. Single-Level Wildcard (+)

// Replaces exactly one level in the topic path. Subscribe Topic vr_f687sjdd/device/+/status

Receives the status from all devices (e.g., DeviceA/status, DeviceB/status) but ignore other fields like temperature.

6. Connectivity (LWT & Retain)

Last Will and Testament (LWT)

// Server publishes this if the device disconnects unexpectedly.

Topic: vr_f687sjdd/device/Pump_Controller/status
Payload: "connection_lost"

State Persistence (Retain): Messages published with the Retain flag are delivered to subscribers immediately upon connection, synchronizing the device's physical state with the cloud.

7. Diagnostics

Debug Stream vr_f687sjdd/debug // Essential for debugging permission issues or malformed payloads.