MQTT Integration Overview
Relevant source files
The following files were used as context for generating this wiki page:The Pulsar Dome Driver incorporates an MQTT (Message Queuing Telemetry Transport) integration to publish real-time status updates, alarms, and operational messages to an MQTT broker. This allows external systems to monitor the dome's activity, state, and health without directly polling the ASCOM driver. The feature is optional and can be enabled through the driver's settings.
The integration is primarily managed by the MqttPublisher class, which handles the connection to the broker and the publishing of messages. The main DomeDriver class and the ActionWatchdog helper class utilize this publisher to send updates during various operations, such as connection changes, status polling, command execution, and error handling.
Configuration
MQTT functionality is disabled by default and must be enabled in the driver's setup dialog.
Sources: UI/SettingsForm.cs:38, Config/ConfigManager.cs:228-237
| Setting | UI Control | Description |
|---|---|---|
UseMQTT | chkBoxMQTT (CheckBox) | Enables or disables the MQTT integration. When checked, the driver will attempt to connect to the MQTT broker upon connection. |
The UI control for this setting is defined in SettingsForm.Designer.cs. The value is read from and saved to the ASCOM profile via the ConfigManager.
Sources: UI/SettingsForm.Designer.cs:56, UI/SettingsForm.cs:88, Config/ConfigManager.cs:228-237
Core Component: MqttPublisher
The MqttPublisher class is a wrapper around the MQTTnet library, providing a simplified interface for connecting, publishing, subscribing, and disconnecting from an MQTT broker.
Sources: MQTT/MqttPublisher.cs
Class Structure
The MqttPublisher class depends on FileLogger for logging its operations and ConfigManager to check for system states like rebooting.
This diagram shows the relationships between MqttPublisher and other key classes that use it.
Sources: MQTT/MqttPublisher.cs:12, Driver/Pulsar_DomeDriver.cs:89, Helper/ActionWatchdog.cs:15
Key Methods
InitializeAsync(string brokerIp, int port = 1883): Creates an MQTT client, builds connection options with a hardcodedClientIdof "DomeDriver", and connects to the specified broker. It also sets up handlers for connection and disconnection events.
Sources: MQTT/MqttPublisher.cs:33-72PublishAsync(string topic, string payload): Publishes a message to a given topic. It checks if the client is connected and if the system is in aRebootingstate. Messages are sent with "Exactly Once" QoS and the retain flag set.
Sources: MQTT/MqttPublisher.cs:89-122SubscribeAsync(string topic, Action<string> onMessage): Subscribes to a topic and registers a callback action to be invoked when a message is received.
Sources: MQTT/MqttPublisher.cs:124-167DisconnectAsync(): Cleanly disconnects from the MQTT broker.
Sources: MQTT/MqttPublisher.cs:169-191
Integration with DomeDriver
The main DomeDriver class is the primary consumer of the MqttPublisher.
Sources: Driver/Pulsar_DomeDriver.cs
Initialization and Teardown
When the dome driver connects (Connected = true), it checks if _config.UseMQTT is true. If so, it launches the StartMQTTAsync method in a background task. This method instantiates and initializes the MqttPublisher.
The following sequence diagram illustrates the MQTT startup process.
When the driver disconnects, it publishes a "Driver disconnected" message and then calls _mqttPublisher.DisconnectAsync().
Sources: Driver/Pulsar_DomeDriver.cs:240-244
Publishing Messages
The driver publishes messages to various topics in response to different events. A helper method, TryMQTTPublish, is used to safely publish messages without blocking the main thread and to avoid errors if the MQTT client is not connected.
// Driver/Pulsar_DomeDriver.cs:1490-1497
private void TryMQTTPublish(string topic, string message)
{
if (_mqttPublisher != null && _mqttPublisher.IsConnected && !string.IsNullOrWhiteSpace(topic))
{
_ = _mqttPublisher.PublishAsync(topic, message);
}
}
This method is called from various places:
- System Watchdog: A heartbeat message is published every 5 seconds to the
Dome/Watchdogtopic.
Sources: Driver/Pulsar_DomeDriver.cs:646-648 - Reset Routine: Messages are published to
Dome/DebugandDome/Alarmduring the reset process.
Sources: Driver/Pulsar_DomeDriver.cs:1017, Driver/Pulsar_DomeDriver.cs:1134 - Abort Slew: The result of an abort command is published to
Dome/Dome/StatusorDome/Alarm.
Sources: Driver/Pulsar_DomeDriver.cs:1882, Driver/Pulsar_DomeDriver.cs:1888
MQTT Topics
The driver defines several topics for publishing different kinds of information.
| Topic | Example Payload | Context | Source File |
|---|---|---|---|
Dome/DriverStatus | Driver connected / Driver disconnected | Published when the ASCOM driver connects or disconnects. | Driver/Pulsar_DomeDriver.cs:90, 210, 241 |
Dome/Dome/Status | Dome is at home. / Abort succeeded | Status of dome rotation, homing, and parking commands. | Driver/Pulsar_DomeDriver.cs:91, 1882 |
Dome/Shutter/Status | Shutter is open. / Shutter failed to open. | Status of shutter open/close commands. | Driver/Pulsar_DomeDriver.cs:92 |
Dome/Alarm | Unrecoverable failure after hard reset... | Published when a critical, unrecoverable error occurs. | Driver/Pulsar_DomeDriver.cs:93, 1134 |
Dome/Watchdog | Alive at 2023-10-27T10:00:00 | A periodic heartbeat message sent by the system watchdog. | Driver/Pulsar_DomeDriver.cs:94, 648 |
Integration with ActionWatchdog
The ActionWatchdog class monitors long-running dome actions (e.g., slewing, opening shutter). It accepts an MqttPublisher instance to report the final status of these actions.
Sources: Helper/ActionWatchdog.cs
When an action completes, the watchdog publishes a message indicating success, failure, or timeout.
- On Success: Publishes a success message (e.g., "Shutter is open.") to the action-specific topic (
_mqttTopic). - On Timeout/Failure: Publishes a failure message (e.g., "Shutter opening... timed out.") to the alarm topic (
_mqttFailTopic, which defaults to "Alarm").
The diagram below shows the flow when an action monitored by the watchdog completes successfully.
This flow shows the watchdog triggering an MQTT publish on success.
Sources: Helper/ActionWatchdog.cs:94-96, Helper/ActionWatchdog.cs:99-105
Summary
The MQTT integration provides a robust, one-way communication channel for the Pulsar Dome Driver to broadcast its status and critical events. By leveraging the MqttPublisher class, both the main driver logic and helper components like ActionWatchdog can report information to external monitoring systems in real-time. This feature enhances the driver's observability, making it suitable for automated and remotely managed observatory environments.