MQTT Configuration
Relevant source files
The following files were used as context for generating this wiki page:The Pulsar Dome Driver integrates an MQTT (Message Queuing Telemetry Transport) client to publish real-time status updates, command outcomes, and critical alerts. This functionality allows external systems to monitor the dome's state and driver health without directly polling the ASCOM driver. The feature is optional and can be enabled through the driver's settings dialog.
When enabled, the driver connects to a local MQTT broker and publishes messages to predefined topics. This includes driver connection status, dome and shutter movements, action success or failure, and periodic heartbeats. The implementation is primarily handled by the MqttPublisher class, which is instantiated and controlled by the main DomeDriver class.
Enabling MQTT
MQTT functionality is disabled by default and must be enabled in the driver's setup dialog.
The following diagram shows the configuration flow, from the user interface to the driver's runtime behavior.
Configuration Steps
- Open the ASCOM driver's
SetupDialog. - In the
SettingsForm, check the "MQTT" checkbox (chkBoxMQTT). - Click "OK" to save the setting.
This action sets the UseMQTT property in the ConfigManager to true, which is persisted in the ASCOM profile. When the DomeDriver establishes a connection, it checks this flag and initializes the MQTT client if it is set.
Sources: UI/SettingsForm.cs:90, UI/SettingsForm.Designer.cs:302-309, Config/ConfigManager.cs:238-248
Configuration Property
| Property | Class | Storage | Description |
|---|---|---|---|
UseMQTT | ConfigManager | ASCOM Profile ("MQTT") | A boolean flag that determines if the MQTT client should be initialized on driver connection. |
Sources: Config/ConfigManager.cs:238-248
Architecture
The MQTT system is composed of several key classes that interact to provide the publishing functionality. The DomeDriver is the central orchestrator, using ConfigManager to check if the feature is enabled and MqttPublisher to handle the communication. The ActionWatchdog also uses the MqttPublisher instance to report on long-running command states.
This class diagram illustrates the relationships between the main components of the MQTT feature.
Core Component: MqttPublisher
The MqttPublisher class is a wrapper around the MQTTnet library, providing a simplified interface for connecting, publishing, and subscribing.
Sources: MQTT/MqttPublisher.cs
Initialization
Connection to the MQTT broker is handled by the InitializeAsync method.
// File: MQTT/MqttPublisher.cs:28-31
public async Task InitializeAsync(string brokerIp, int port = 1883)
{
// ...
}
Key characteristics of the initialization process:
- Broker Address: The broker IP is passed as an argument. The
DomeDrivercurrently hardcodes this to"localhost". - Client ID: The client identifies itself to the broker with the
ClientId"DomeDriver". - Connection Handlers: It sets up handlers to log connection and disconnection events.
- Singleton Initialization: An internal flag
_initializedprevents multiple initializations.
Sources: MQTT/MqttPublisher.cs:28-68, Driver/Pulsar_DomeDriver.cs:1571
The following sequence diagram shows the MQTT client initialization when the dome driver connects.
Publishing Messages
The PublishAsync method is used to send messages to the broker.
// File: MQTT/MqttPublisher.cs:91-94
public async Task PublishAsync(string topic, string payload)
{
// ...
}
- Message Construction: Messages are built with a topic, a string payload (encoded to UTF-8), and two important flags:
WithExactlyOnceQoS(): Sets the Quality of Service level to 2, ensuring the message is received exactly once.WithRetainFlag(): The broker will retain the last message on this topic and send it to any new subscribers.
- Connection Check: Publishing is skipped if the client is not connected.
- Reboot State: If the driver is in a rebooting state (
_config.Rebooting), the payload is overridden to"REBOOTING".
To simplify publishing, the DomeDriver uses a helper method TryMQTTPublish which performs a null-check and fires the publish call without awaiting it.
// File: Driver/Pulsar_DomeDriver.cs:1584-1590
private void TryMQTTPublish(string topic, string message)
{
if (_mqttPublisher != null && _mqttPublisher.IsConnected && !string.IsNullOrWhiteSpace(topic))
{
_ = _mqttPublisher.PublishAsync(topic, message);
}
}
Sources: MQTT/MqttPublisher.cs:91-125, Driver/Pulsar_DomeDriver.cs:1584-1590
MQTT Topics
The driver publishes information to a set of predefined topics.
| Topic | Description | Example Payload | Source |
|---|---|---|---|
Dome/DriverStatus | Reports the connection state of the ASCOM driver. | Driver connected | DomeDriver.cs:204 |
Dome/Dome/Status | Published when a dome action (slew, home, park) succeeds or fails. | Dome is at home. | DomeDriver.cs:1898 |
Dome/Shutter/Status | Published when a shutter action (open, close) succeeds or fails. | Shutter is closed. | DomeDriver.cs:1858 |
Dome/Alarm | Published when an unrecoverable error occurs, often triggering a reset. | Abort failed (no ACK). Resetting controller. | DomeDriver.cs:1924 |
Dome/Watchdog | A periodic heartbeat message containing the UTC time and dome status string. | 2023-10-27T10:30:00 :0,0,0,180.0,180.0,0,1 | DomeDriver.cs:704 |
Dome/Debug | Used for publishing internal debug state information. | in reset | DomeDriver.cs:1107 |
Sources: Driver/Pulsar_DomeDriver.cs:100-105, 704, 1107, 1858, 1898, 1924
Integration with Dome Operations
MQTT publishing is deeply integrated into the driver's operational logic, especially for monitoring long-running actions and system health.
Action Watchdog
The ActionWatchdog class is responsible for monitoring commands like OpenShutter, FindHome, etc. It uses the MqttPublisher instance to report the start, success, or failure of these actions.
This sequence diagram shows how the ActionWatchdog reports the status of an OpenShutter command via MQTT.
System Watchdog (Heartbeat)
The DomeDriver runs a system watchdog in a background task. This watchdog performs two key MQTT-related functions:
- Publishes a periodic heartbeat message to the
Dome/Watchdogtopic. - Checks if the MQTT client is connected and logs a warning if it is not.
This ensures that external systems can monitor not only the dome's state but also the health and responsiveness of the driver itself.
Sources: Driver/Pulsar_DomeDriver.cs:697-709