espectre::IMqttTransport Class Reference

The MQTT client seam. More...

#include <mqtt_transport.h>

Public Types
using	CommandCallback = std::function<void(const std::string &)>
	Payload of a message on the device command topic.
using	ConnectionCallback = std::function<void(bool connected)>
	Broker connection state changed; the argument is the new state.
using	MessageCallback = std::function<void(const std::string &, const std::string &)>
	Message on a topic registered through subscribe(): (topic, payload).

Public Member Functions
virtual	~IMqttTransport ()=default
virtual bool	setup (const EspectreDeviceConfig &config)=0
	Configure and start connecting.
virtual void	loop ()=0
	Pump the client and dispatch callbacks.
virtual void	shutdown ()=0
	Disconnect and release resources.
virtual bool	connected () const =0
	True while the broker connection is established.
virtual bool	publish (const std::string &topic, const std::string &payload, bool retain)=0
	Publish to an absolute topic.
virtual bool	publish_suffix (const char *suffix, const std::string &payload, bool retain)=0
	Publish under this device's protocol topic prefix.
virtual bool	subscribe (const std::string &topic, MessageCallback callback)=0
	Register a topic and its handler.
virtual void	set_command_callback (CommandCallback callback)=0
	Handler for the device command topic, which the transport subscribes itself.
virtual void	set_connection_callback (ConnectionCallback callback)=0
	Handler for connection state changes, including reconnects.
virtual MqttTransportDiagnostics	diagnostics () const
	Bounded outbound queue, drop, failure, and reconnect counters.

Detailed Description

The MQTT client seam.

Implement it to carry ESPectre Protocol messages over an MQTT stack you already own, then hand the instance to a frontend. EspIdfMqttTransport (mqtt_transport_esp_idf.h) is the shipped implementation over esp-mqtt, and test/cpp/support/mqtt_transport_mock.h is the host double.

Topic layout and payload schemas live in docs/ESPECTRE_PROTOCOL.md, and espectre_protocol.h builds the payloads, so an implementation only has to move bytes.

Contract for implementers

• The transport is driven from the frontend's task: loop() is where you pump your client and deliver queued callbacks.
• Publishing while disconnected must fail cleanly rather than block.
• Registered subscriptions must survive a reconnect. Callers subscribe once and expect the broker subscription to be reissued on the next connect.

Definition at line 49 of file mqtt_transport.h.

Member Typedef Documentation

CommandCallback

using espectre::IMqttTransport::CommandCallback = std::function<void(const std::string &)>

Payload of a message on the device command topic.

Definition at line 52 of file mqtt_transport.h.

ConnectionCallback

using espectre::IMqttTransport::ConnectionCallback = std::function<void(bool connected)>

Broker connection state changed; the argument is the new state.

Definition at line 54 of file mqtt_transport.h.

MessageCallback

using espectre::IMqttTransport::MessageCallback = std::function<void(const std::string &, const std::string &)>

Message on a topic registered through subscribe(): (topic, payload).

Definition at line 56 of file mqtt_transport.h.

Constructor & Destructor Documentation

~IMqttTransport()

virtual espectre::IMqttTransport::~IMqttTransport ( )

virtualdefault

Member Function Documentation

setup()

virtual bool espectre::IMqttTransport::setup ( const EspectreDeviceConfig & config )

pure virtual

Configure and start connecting.

Asynchronous: true means the client started, not that it reached the broker. Wait for the connection callback before expecting publishes to land. Calling it again reconfigures and tears down the previous client.

Returns

false when the configuration cannot produce a client, such as an empty EspectreDeviceConfig::mqtt_host.

loop()

virtual void espectre::IMqttTransport::loop ( )

pure virtual

Pump the client and dispatch callbacks.

Called from the frontend loop.

shutdown()

virtual void espectre::IMqttTransport::shutdown ( )

pure virtual

Disconnect and release resources.

Safe to repeat.

connected()

virtual bool espectre::IMqttTransport::connected ( ) const

pure virtual

True while the broker connection is established.

publish()

virtual bool espectre::IMqttTransport::publish ( const std::string & topic, const std::string & payload, bool retain )

pure virtual

Publish to an absolute topic.

Parameters

topic	Full topic name, not a suffix.
payload	Message body, copied before returning.
retain	Ask the broker to retain the message, for state a late subscriber must still see, such as availability.

Returns

false when disconnected or the bounded publish queue rejects the message. Published at QoS 0, so true means queued locally, not delivered to the broker.

publish_suffix()

virtual bool espectre::IMqttTransport::publish_suffix ( const char * suffix, const std::string & payload, bool retain )

pure virtual

Publish under this device's protocol topic prefix.

The prefix comes from the EspectreDeviceConfig passed to setup(), so callers pass only the trailing segment, for example "/telemetry".

subscribe()

virtual bool espectre::IMqttTransport::subscribe ( const std::string & topic, MessageCallback callback )

pure virtual

Register a topic and its handler.

Idempotent per topic: subscribing again replaces the handler. May be called before the connection is up; the subscription is issued on connect.

Returns

false for an empty topic or an empty callback.

set_command_callback()

virtual void espectre::IMqttTransport::set_command_callback ( CommandCallback callback )

pure virtual

Handler for the device command topic, which the transport subscribes itself.

set_connection_callback()

virtual void espectre::IMqttTransport::set_connection_callback ( ConnectionCallback callback )

pure virtual

Handler for connection state changes, including reconnects.

diagnostics()

virtual MqttTransportDiagnostics espectre::IMqttTransport::diagnostics ( ) const

inlinevirtual

Bounded outbound queue, drop, failure, and reconnect counters.

Definition at line 110 of file mqtt_transport.h.

---

The documentation for this class was generated from the following file:

• src/cpp/runtime/mqtt_transport.h