MQTT Topic and Payload Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Pulsar Dome Driver integrates an MQTT client to publish real-time status updates, command feedback, and critical alerts. This allows external systems to monitor the dome's activity and health without directly interfacing with the ASCOM driver. The implementation is centered around the MqttPublisher class, which handles connection and message publishing, and is controlled by settings in the driver's configuration.
The MQTT functionality is optional and can be enabled through the driver's setup dialog. When active, the driver connects to a local MQTT broker and begins publishing messages to predefined topics. These messages cover driver connection status, dome and shutter movements, watchdog heartbeats, and alarm conditions.
Configuration
MQTT functionality must be explicitly enabled in the driver's settings.
| Setting | UI Control | Profile Key | Description | Source File |
|---|---|---|---|---|
| Use MQTT | chkBoxMQTT | MQTT | A boolean flag that enables or disables all MQTT communications. | Config/ConfigManager.cs:250-261 |
This setting is managed by the ConfigManager and can be toggled in the SettingsForm.
Sources: Config/ConfigManager.cs:250-261, UI/SettingsForm.Designer.cs:312
Architecture
The MQTT system is composed of the MqttPublisher class, which acts as a wrapper for the MQTTnet library, and integration points within the main DomeDriver class.
MqttPublisher Class
This class encapsulates all direct interaction with the MQTT broker.
This diagram shows that DomeDriver and ActionWatchdog both utilize the MqttPublisher to send messages.
Sources: MQTT/MqttPublisher.cs:12-214, Driver/Pulsar_DomeDriver.cs:81, 1572, Helper/ActionWatchdog.cs:16, 155
Connection Management
The driver initiates the MQTT connection when the dome connects, if the UseMQTT setting is true.
- Initialization:
DomeDriver.Connectedproperty setter callsStartMQTTAsync. - Connection:
StartMQTTAsynccreates anMqttPublisherinstance and callsInitializeAsync("localhost"). - Client ID: The client connects with the hardcoded Client ID "DomeDriver".
- Initial Message: Upon successful connection, it publishes "Pulsar Ascom driver connected" to the
Dome/DriverStatustopic. - Disconnection: When the driver disconnects, it publishes "Driver disconnected" and calls
_mqttPublisher.DisconnectAsync().
Sources: Driver/Pulsar_DomeDriver.cs:202, 234, 1572-1593, MQTT/MqttPublisher.cs:49-51
MQTT Topics
The driver publishes to a set of predefined topics. All topics are prefixed with Dome/.
| Topic | Purpose | Source File |
|---|---|---|
Dome/DriverStatus | Reports the connection status of the ASCOM driver itself. | Driver/Pulsar_DomeDriver.cs:83 |
Dome/Dome/Status | Provides feedback on dome rotation commands (slew, home, park). | Driver/Pulsar_DomeDriver.cs:84 |
Dome/Shutter/Status | Provides feedback on shutter commands (open, close). | Driver/Pulsar_DomeDriver.cs:85 |
Dome/Alarm | Publishes critical failure messages, often preceding a reset routine. | Driver/Pulsar_DomeDriver.cs:86 |
Dome/Watchdog | A periodic heartbeat message to indicate the driver is alive and polling. | Driver/Pulsar_DomeDriver.cs:87 |
Sources: Driver/Pulsar_DomeDriver.cs:83-87
Payload Structure
Payloads are typically simple strings. Messages are published with "Exactly Once" QoS and the Retain flag is set.
Sources: MQTT/MqttPublisher.cs:113-115
Dome/DriverStatus
Simple string messages indicating the driver's connection state.
"Driver connected""Driver disconnected"
Sources: Driver/Pulsar_DomeDriver.cs:204, 235
Dome/Dome/Status & Dome/Shutter/Status
These topics are used by the ActionWatchdog to report the progress and final state of a command.
- Start of Action: A descriptive message is sent (e.g.,
"Shutter opening..."). - Success: A confirmation message is sent (e.g.,
"Shutter is open."). - Failure: A failure message is sent (e.g.,
"Shutter failed to open.").
Sources: Helper/ActionWatchdog.cs:100, 105, Driver/Pulsar_DomeDriver.cs:1865, 1895, 1930
Dome/Alarm
Contains string messages describing a critical error. These are often published when a command fails validation, times out, or an abort command does not receive an acknowledgement.
- Example:
"Unrecoverable failure after hard reset for GoHome" - Example:
"Abort failed (no ACK). Resetting controller."
Sources: Driver/Pulsar_DomeDriver.cs:1260, 1839, Helper/ActionWatchdog.cs:110, 119
Dome/Watchdog
The payload is a composite string published every 5 seconds by the system watchdog.
- Format:
"{utcTime} :{domeOutputStatus}" - Example:
"2023-10-27T10:30:00 :0,1,0,180.0,180.0,0,1"
The domeOutputStatus part of the payload is a comma-separated string with the following fields:
| Index | Field | Type | Description | Source |
|---|---|---|---|---|
| 0 | Dome State | int | 0=Idle, 1=Slewing, 9=Homing | Config/ConfigManager.cs:68 |
| 1 | Home Status | int | 1 if at home, 0 otherwise | Config/ConfigManager.cs:67 |
| 2 | Park Status | int | 1 if parked, 0 otherwise | Config/ConfigManager.cs:66 |
| 3 | Azimuth | double | Current dome azimuth | Config/ConfigManager.cs:64 |
| 4 | Target Azimuth | double | The target azimuth for the current slew | Config/ConfigManager.cs:70 |
| 5 | Slewing Status | int | 1 if slewing, 0 otherwise | Config/ConfigManager.cs:65 |
| 6 | Shutter Status | int | 0=Open, 1=Closed, 2=Opening, 3=Closing, 4=Error | Config/ConfigManager.cs:72 |
Sources: Driver/Pulsar_DomeDriver.cs:689, 883-891
Publishing Message Flow
Messages are published at key points in the driver's lifecycle. The TryMQTTPublish helper method provides a non-blocking, "fire-and-forget" mechanism for sending messages.
Sources: Driver/Pulsar_DomeDriver.cs:1596-1603
Successful Command Flow
This diagram shows the MQTT messages published during a successful OpenShutter command.
Command Timeout Flow
This diagram illustrates the MQTT publications when a command times out.
Sources: Helper/ActionWatchdog.cs:108-114
Summary
The MQTT integration in the Pulsar Dome Driver provides a powerful, real-time, one-way communication channel for external monitoring. By publishing status, command lifecycle, and alarm messages to a local broker, it allows other observatory software or dashboards to track the dome's state of health and operational status without needing to interface directly with the ASCOM driver. The system is robust, with specific topics for different categories of information and a watchdog heartbeat to ensure continuous monitoring.