MQTT Publisher
Relevant source files
The following files were used as context for generating this wiki page:
The MqttPublisher is a dedicated class within the Pulsar Dome Driver responsible for handling all communications with an MQTT broker. It encapsulates the logic for connecting, publishing messages, and subscribing to topics, providing a clean interface for other parts of the application to interact with the MQTT system. This allows the driver to report its status, dome movements, and potential alarms to external monitoring systems in real-time.
The functionality is enabled or disabled via a setting in the driver's configuration, which can be controlled from the settings UI. The MqttPublisher is primarily utilized by the main DomeDriver class for general status updates and by the ActionWatchdog helper to report the success or failure of long-running dome operations.
Sources: MQTT/MqttPublisher.cs, Driver/Pulsar_DomeDriver.cs:192-198, Helper/ActionWatchdog.cs:13-20
Architecture and Dependencies
The MqttPublisher class relies on the MQTTnet library to handle the low-level MQTT protocol details. It is designed with two key dependencies, which are injected via its constructor: FileLogger for logging its internal operations and ConfigManager to access configuration settings, such as the Rebooting state.
Sources: MQTT/MqttPublisher.cs:17-23
Class Diagram
This diagram illustrates the structure of the MqttPublisher class and its relationship with its dependencies.
Core Functionality
Initialization and Connection
Connection to the MQTT broker is managed by the InitializeAsync method. This method is responsible for setting up the MQTT client, defining connection options, and establishing the connection. It is designed to be called only once, preventing multiple initializations.
The process involves:
- Creating an
MqttFactoryand anIMqttClientinstance. - Building
MqttClientOptionswith aClientIdof "DomeDriver" and the server address. - Assigning handlers for
ConnectedandDisconnectedevents to log connection status changes. - Calling
ConnectAsyncto establish the connection with the broker.
Sources: MQTT/MqttPublisher.cs:29-81
The following sequence diagram shows the initialization flow.
Publishing Messages
The PublishAsync method sends a message to a specified topic on the MQTT broker. Before publishing, it performs several checks:
- It ensures the MQTT client is initialized and connected.
- It checks the
_config.Rebootingflag; if true, it aborts the publish operation or overrides the payload to "REBOOTING".
Messages are constructed using MqttApplicationMessageBuilder with the following properties:
- Quality of Service (QoS):
WithExactlyOnceQoS()ensures the message is delivered exactly once. - Retain Flag:
WithRetainFlag()makes the broker hold on to the message so that new subscribers to the topic receive it immediately.
Sources: MQTT/MqttPublisher.cs:83-126
This flowchart illustrates the logic of the PublishAsync method.
Sources: MQTT/MqttPublisher.cs:83-126
Subscribing to Topics
The SubscribeAsync method allows the driver to listen for incoming messages on a specific topic. It configures an ApplicationMessageReceivedHandler to process messages. When a message is received, its payload is decoded from UTF-8 and passed to a callback Action<string>.
Subscriptions are configured with WithExactlyOnceQoS() to match the publishing QoS level.
Sources: MQTT/MqttPublisher.cs:128-179
Integration and Usage
The MQTT feature is controlled by a boolean flag in the configuration.
| Configuration | Type | Description | Source File |
|---|---|---|---|
UseMQTT | bool | If true, the driver will initialize the MqttPublisher and send/receive messages. | Config/ConfigManager.cs:238-248 |
This setting is exposed in the driver's setup dialog via a checkbox.
Sources: UI/SettingsForm.Designer.cs:56, 422-431
DomeDriver Integration
The main DomeDriver class initializes and manages the MqttPublisher instance.
- Initialization: In
Connectedproperty setter, if MQTT is enabled,StartMQTTAsyncis called to create theMqttPublisherinstance and connect to the broker. - Publishing: A helper method,
TryMQTTPublish, provides a null-safe, non-blocking way to publish messages. This is used throughout the driver to report status changes, watchdog heartbeats, and alarms. - Topics: The driver defines several topics for different types of messages.
Sources: Driver/Pulsar_DomeDriver.cs:192-198, 1512-1533, 1536-1543
The following table lists the MQTT topics used by the driver.
| Topic | Description | Source File |
|---|---|---|
Dome/DriverStatus | General status of the ASCOM driver (e.g., "Driver connected", "Driver disconnected"). | Driver/Pulsar_DomeDriver.cs:101 |
Dome/Dome/Status | Status of dome rotation actions (e.g., slew success/failure, home/park status). | Driver/Pulsar_DomeDriver.cs:102 |
Dome/Shutter/Status | Status of shutter actions (e.g., "Shutter is open.", "Shutter failed to close."). | Driver/Pulsar_DomeDriver.cs:103 |
Dome/Alarm | Used for publishing critical errors and unrecoverable failures. | Driver/Pulsar_DomeDriver.cs:104 |
Dome/Watchdog | Publishes a periodic heartbeat message to indicate the driver is alive. | Driver/Pulsar_DomeDriver.cs:105 |
ActionWatchdog Integration
The ActionWatchdog class, which monitors long-running commands like OpenShutter or FindHome, uses the MqttPublisher to report the final status of these actions. It publishes a "success" or "fail" message to the appropriate topic (_mqttDomeStatus or _mqttShutterStatus) when the action completes or times out.
Sources: Helper/ActionWatchdog.cs:38-44, 91-100
Summary
The MqttPublisher class provides a robust and centralized mechanism for integrating the Pulsar Dome Driver with an MQTT-based ecosystem. By encapsulating connection management, publishing, and subscribing logic, it allows other components like DomeDriver and ActionWatchdog to easily report status and receive commands without being burdened by the details of the MQTT protocol. This feature is critical for remote monitoring, automation, and integration with larger observatory control systems.