feat: mqtt (#4841)

conductor/product.md

@@ -12,7 +12,7 @@ Meshtastic-Android is a Kotlin Multiplatform (KMP) application designed to facil
 - Emergency response and disaster relief teams
 
 ## Core Features
-- Direct communication with Meshtastic hardware (via BLE, USB, TCP)
+- Direct communication with Meshtastic hardware (via BLE, USB, TCP, MQTT)
 - Decentralized text messaging across the mesh network
 - Unified cross-platform notifications for messages and node events
 - Adaptive node and contact management

conductor/tech-stack.md

@@ -25,6 +25,7 @@
 - **Ktor:** Multiplatform HTTP client for web services and TCP streaming.
 - **Kable:** Multiplatform BLE library used as the primary BLE transport for all targets (Android, Desktop, and future iOS).
 - **jSerialComm:** Cross-platform Java library used for direct Serial/USB communication with Meshtastic devices on the Desktop (JVM) target.
+- **KMQTT:** Kotlin Multiplatform MQTT client and broker used for MQTT transport, replacing the Android-only Paho library.
 - **Coroutines & Flows:** For asynchronous programming and state management.
 
 ## Testing (KMP)

conductor/tracks.md

@@ -1,3 +1,8 @@
 # Project Tracks
 
 This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
+
+---
+
+- [x] **Track: MQTT transport**
+*Link: [./tracks/mqtt_transport_20260318/](./tracks/mqtt_transport_20260318/)*

conductor/tracks/mqtt_transport_20260318/index.md

@@ -0,0 +1,5 @@
+# Track mqtt_transport_20260318 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/tracks/mqtt_transport_20260318/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "mqtt_transport_20260318",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-03-18T00:00:00Z",
+  "updated_at": "2026-03-18T00:00:00Z",
+  "description": "MQTT transport"
+}

conductor/tracks/mqtt_transport_20260318/plan.md

@@ -0,0 +1,32 @@
+# Implementation Plan: MQTT Transport
+
+## Phase 1: Core Networking & Library Integration
+- [x] Task: Evaluate and add KMP MQTT library dependency (e.g. Kmqtt) to `core:network` or `libs.versions.toml`. [2a4aa35]
+    - [x] Add dependency to `libs.versions.toml`.
+    - [x] Apply dependency in `core:network/build.gradle.kts`.
+- [x] Task: Implement `MqttTransport` class in `commonMain` of `core:network`. [99d35b3]
+    - [x] Create failing tests in `commonTest` for MqttTransport initialization and configuration parsing.
+    - [x] Implement MqttTransport to parse URL (mqtt://, mqtts://), credentials, and configure the underlying MQTT client.
+    - [x] Write failing tests for connection state flows.
+    - [x] Implement connection lifecycle handling (connect, disconnect, reconnect).
+- [x] Task: Conductor - User Manual Verification 'Phase 1: Core Networking & Library Integration' (Protocol in workflow.md) [93d9a50]
+
+## Phase 2: Publishing & Subscribing
+- [x] Task: Implement message subscription and payload parsing. [4900f69]
+    - [x] Create failing tests for receiving and mapping standard Meshtastic JSON payloads from subscribed topics.
+    - [x] Implement topic subscription management in `MqttTransport`.
+    - [x] Implement payload parsing and integration with `core:model` definitions.
+- [x] Task: Implement publishing mechanism. [0991210]
+    - [x] Create failing tests for formatting and publishing node information/messages to custom topics.
+    - [x] Implement publish functionality in `MqttTransport`.
+- [x] Task: Conductor - User Manual Verification 'Phase 2: Publishing & Subscribing' (Protocol in workflow.md) [7418e53]
+
+## Phase 3: Service & UI Integration
+- [x] Task: Integrate `MqttTransport` into `core:service` and `core:data`. [d414556, e172f53]
+    - [x] Create failing tests for orchestrating MQTT connection based on user preferences.
+    - [x] Implement service-level bindings to maintain background connection.
+- [x] Task: Implement MQTT UI Configuration Settings. (Verified existing implementation)
+    - [x] Verified existing `MQTTConfigItemList.kt` correctly manages UI inputs.
+    - [x] Verified MQTT broker URL, username, password, and custom topic inputs exist in UI.
+    - [x] Verified UI inputs correctly wire to `ModuleConfig.MQTTConfig` used by `MQTTRepositoryImpl`.
+- [x] Task: Conductor - User Manual Verification 'Phase 3: Service & UI Integration' (Protocol in workflow.md) [deaa324]

conductor/tracks/mqtt_transport_20260318/spec.md

@@ -0,0 +1,33 @@
+# Specification: MQTT Transport
+
+## Overview
+Implement an MQTT transport layer for the Meshtastic-Android Kotlin Multiplatform (KMP) application to enable communication with Meshtastic devices over MQTT. This will support Android, Desktop, iOS, and potentially Web platforms in the future.
+
+## Functional Requirements
+- **Platforms:** Ensure the MQTT transport operates correctly across Android, Desktop, and iOS platforms, using KMP best practices (with considerations for Web compatibility if technically feasible).
+- **Core Library:** Utilize a dedicated Kotlin Multiplatform MQTT client library (e.g., Kmqtt) within the `core:network` module.
+- **Connection Features:**
+  - Support for both standard (`mqtt://`) and secure TLS/SSL (`mqtts://`) connections.
+  - Support for username and password authentication.
+- **Messaging Features:**
+  - Subscribe to and publish on user-defined custom topics.
+  - Parse and serialize standard Meshtastic JSON payloads.
+- **UI Integration:**
+  - Follow the existing Android UX patterns for network/device connections.
+  - Integrate MQTT configuration seamlessly into the connection or advanced settings menus.
+
+## Non-Functional Requirements
+- **Architecture:** Business logic for MQTT communication must reside in the `core:network` (or a new `core:mqtt`) `commonMain` source set.
+- **Testability:** Implement shared tests in `commonTest` to verify connection states, topic parsing, and payload serialization without relying on JVM-specific mocks.
+- **Performance:** Ensure background execution and resource management align with the `core:service` architecture.
+
+## Acceptance Criteria
+- [ ] Users can enter an MQTT broker URL (including TLS), username, and password in the UI.
+- [ ] The app successfully connects to the specified MQTT broker and maintains the connection in the background.
+- [ ] The app can publish Meshtastic node information/messages to the broker.
+- [ ] The app can receive and process incoming Meshtastic payloads from subscribed topics.
+- [ ] Unit tests cover at least 80% of the new MQTT client logic.
+
+## Out of Scope
+- Direct firmware updates via MQTT (if not natively supported by the standard payload).
+- Implementing a full local MQTT broker on the device.