mqtt-development

What problem does it solve?

Ensures consistent MQTT topic, QoS, and handler implementations across ESP32 firmware and the Python server to prevent protocol drift, message loss, duplicate commands, and synchronization errors between devices and backend services.

Core Features & Use Cases

• Topic Schema Enforcement: Centralized guidance to add and sync topics between El Trabajante (ESP32) and El Servador (server) so both sides use the exact kaiser/{kaiser_id}/esp/{esp_id}/... format.
• QoS Strategy & Safety: Clear QoS assignment rules (QoS 2 for commands, QoS 1 for sensor data, QoS 0 for heartbeats) to avoid dangerous duplicates and ensure reliable command delivery.
• Handler & Publisher Patterns: Standardized handler registration, publisher retry with exponential backoff, and correlation_id usage for traceability.
• Resilience Patterns: Circuit breaker behavior on ESP32, offline buffers on device and server, last-will handling, and Mosquitto broker configuration for persistence and websockets.
• Operational References: Concrete file paths and error-code ranges for rapid implementation and debugging (topic builder, mqtt_client, publisher, offline_buffer, constants).
• Use case: Add a new actuator command topic and guarantee safe delivery by implementing the topic on ESP32 topic_builder.cpp, adding the server constant and TopicBuilder, registering a handler, and using QoS 2 with offline buffering.

Quick Start

Add a new actuator command by defining the server topic constant, extending the server TopicBuilder, adding the corresponding ESP32 topic_builder method, and registering the handler with QoS 2.