Troubleshooting MQTT Issues

Relevant source files

The following files were used as context for generating this wiki page:

• MQTT/MqttPublisher.cs
• Driver/Pulsar_DomeDriver.cs
• Helper/ActionWatchdog.cs
• Config/ConfigManager.cs
• UI/SettingsForm.cs
• UI/SettingsForm.Designer.cs
• Diagnostics/FileLogger.cs
• MQTT/WatchDogLogger.cs
• GNS/GNS.cs

The Pulsar Dome Driver can optionally publish status updates and alarms to an MQTT broker. This allows for integration with other observatory management systems or dashboards. This document outlines the architecture of the MQTT feature and provides guidance for diagnosing and resolving common issues.

The core of the functionality is handled by the MqttPublisher class, which uses the MQTTnet library. The main DomeDriver class orchestrates the connection, publication of messages, and configuration. All MQTT-related activities are logged to the driver's log file, which is the primary tool for troubleshooting.

1. Configuration

The MQTT feature is disabled by default. It must be enabled through the driver's settings dialog.

Enabling MQTT

1. Open the ASCOM driver's SetupDialog.
2. Check the "MQTT" checkbox.
3. Click "OK" to save the setting.

This action sets the UseMQTT flag to true in the ASCOM profile. The driver reads this value on initialization.

Setting	Control	Property	Storage Location
Enable MQTT	chkBoxMQTT	UseMQTT	ASCOM Profile (Pulsar_DomeDriver -> MQTT)

Sources: UI/SettingsForm.cs:38, 80, UI/SettingsForm.Designer.cs:56, 400-407, Config/ConfigManager.cs:238-249

2. System Architecture

The MQTT functionality involves several key classes working together. The DomeDriver is the central component that initializes and uses the MqttPublisher based on settings from ConfigManager. The FileLogger is used throughout to record activities for debugging.

The following diagram illustrates the relationship between these components.

3. Connection Lifecycle

The MQTT connection is managed by the DomeDriver and is tied to the driver's main connection state.

Connection Sequence

1. When the driver's Connected property is set to true, it calls StartMQTTAsync() in a background task if _config.UseMQTT is true.
2. StartMQTTAsync() creates an instance of MqttPublisher.
3. It then calls _mqttPublisher.InitializeAsync("localhost"), which attempts to connect to the MQTT broker at localhost:1883.
4. The MqttPublisher sets up a MqttClient with a ClientId of "DomeDriver".
5. Upon successful connection, a log message is written, and a startup message is published to the Dome/DriverStatus topic.
6. If the connection fails, an error is logged.

The following sequence diagram shows the connection flow.

Disconnection

When the driver is disconnected (Connected is set to false), the DomeDriver publishes a "Driver disconnected" message and then calls _mqttPublisher.DisconnectAsync().

Sources: [Driver/Pulsar_DomeDriver.cs:235-238]

4. Message Publishing

Messages are published to the broker to report status changes, alarms, and heartbeats.

Standard Topics

The driver publishes to a predefined set of topics:

Topic	Purpose	Published From
Dome/DriverStatus	Reports driver connection and disconnection status.	DomeDriver.cs
Dome/Dome/Status	Reports dome movement status (e.g., homing, parking, slewing).	ActionWatchdog.cs, DomeDriver.cs
Dome/Shutter/Status	Reports shutter operation status (e.g., opening, closing).	ActionWatchdog.cs
Dome/Alarm	Reports unrecoverable errors or command failures.	DomeDriver.cs
Dome/Watchdog	Publishes a periodic heartbeat with UTC timestamp and dome status.	DomeDriver.cs (System Watchdog)

Sources: Driver/Pulsar_DomeDriver.cs:90-94, 715, 1859, [Helper/ActionWatchdog.cs:22]

Publishing Logic

The primary method for publishing is TryMQTTPublish in DomeDriver.cs, which is a null-safe, non-blocking wrapper around MqttPublisher.PublishAsync.

The PublishAsync method in MqttPublisher builds a message with the following characteristics:

• QoS: Exactly Once (QoS 2)
• Retain Flag: True

This ensures messages are delivered reliably and the last known state is available to newly connected subscribers.

The following flowchart shows the logic of the TryMQTTPublish helper.

5. Logging and Diagnostics

The most effective way to troubleshoot MQTT issues is to examine the driver's log file. The location of this file is configured in the driver's settings dialog. Ensure "Debug Log" and "Trace Log" are enabled to get maximum detail.

Sources: UI/SettingsForm.cs:34, 76-77, [Diagnostics/FileLogger.cs:41-57]

Key Log Messages

Look for log entries with the [MQTT] prefix.

Log Message Snippet	Log Level	Meaning	Troubleshooting Step
[MQTT] MqttPublisher instance created	Trace	The MQTT system is being initialized.	Normal operation.
[MQTT] Attempting ConnectAsync...	Debug	The driver is trying to connect to the broker.	If this is missing, MQTT may be disabled.
[MQTT] Connected to broker at...	Info	Successful connection.	If this is present, the connection is good.
[MQTT] Connection failed: ...	Error	The connection to the broker failed. The error message will provide details (e.g., "Connection refused").	Check if the broker is running on localhost:1883 and accessible.
[MQTT] Disconnected from broker: ...	Debug	The client has disconnected.	This is normal on shutdown. If it happens unexpectedly, the reason may indicate a network issue or broker problem.
[MQTT] Publish skipped — client not connected	Debug	A message was not sent because the client is disconnected.	Check for preceding disconnection or connection failure logs.
[MQTT] Published to '{topic}': {payload}	Info	A message was successfully published.	Verify the topic and payload are correct.
[MQTT] Publish error: ...	Error	An error occurred during publishing.	The exception message will provide details.

Sources: MQTT/MqttPublisher.cs

6. Common Problems and Solutions

Problem: No MQTT messages are being sent.

1. Is MQTT enabled?
   • Check: Open the driver settings and verify the "MQTT" checkbox is ticked.
   • Source: ConfigManager.cs property UseMQTT.
2. Is the driver connected?
   • Check: The ASCOM client must be connected to the driver. MQTT initialization only occurs after the main driver connection is established.
   • Source: DomeDriver.cs, Connected property setter.
3. Is the MQTT broker running?
   • Check: The driver attempts to connect to localhost on port 1883. Ensure a broker (like Mosquitto) is running and listening on that address.
   • Source: MqttPublisher.cs:31.
4. Check the logs for connection errors.
   • Check: Look for [MQTT] Connection failed: in the log file. The error message will indicate the cause (e.g., "Connection refused", "A connection attempt failed because the connected party did not properly respond...").
   • Source: MqttPublisher.cs:72-75.

Problem: Only some messages are appearing.

1. Check the logs for publish errors.
   • Check: Look for [MQTT] Publish error: or [MQTT] Publish skipped — client not connected. This indicates the driver tried to send a message but failed.
   • Source: MqttPublisher.cs:97, 101, 126-129.
2. Is the ActionWatchdog involved?
   • Check: Status updates for long-running actions (shutter, slew, home, park) are published by the ActionWatchdog. If these are missing, look for logs related to the watchdog itself. The watchdog publishes success or failure messages.
   • Source: Helper/ActionWatchdog.cs:91, 97, 106.

Problem: The driver logs show successful publishing, but the subscriber sees nothing.

1. Check Topic Subscription: Ensure your MQTT client is subscribed to the correct topic (e.g., Dome/DriverStatus, Dome/Dome/Status). Remember that topics are case-sensitive.
2. Check Retain Flag: The driver publishes messages with the retain flag. A new subscriber should immediately get the last published message for each topic. If not, check if your broker supports and has retained messages enabled.
   • Source: MqttPublisher.cs:122.
3. Check Broker ACLs: If your broker has Access Control Lists, ensure the "DomeDriver" client ID has permission to publish to the Dome/# topic hierarchy.
   • Source: MqttPublisher.cs:42.