Add MQTT publish and receive bricks with broker integration (CATROID-1669)

[Paras-ydv]

Summary

This PR contains the complete MQTT feature for Catroid, implemented under the epic CATROID-1669: two new bricks that let a Catrobat program publish and receive network messages, enabling multiplayer games, IoT devices, and Home Assistant setups.

This is a draft PR opened for visibility, not for merging. It exists so the whole of the GSoC work is reviewable in one place. The individual tickets will be raised as their own PRs against develop and merged one by one; this branch will be closed once they have all landed.

Tickets already merged:

• CATROID-1670: Eclipse Paho dependencies and Android configuration
• CATROID-1672: MQTT settings UI, persistence and tests
  (Add MQTT dependencies, settings UI, and test coverage (CATROID-1670, CATROID-1672) #5220)

Tickets implemented in this branch:

• CATROID-1671: MqttManager for broker connection lifecycle (Add MqttManager for broker connection lifecycle (CATROID-1671) #5222)
• CATROID-1673: Message publishing in MqttManager (Implement MQTT Message Publishing in MqttManager (CATROID-1673) #5225)
• CATROID-1674: Subscription management in MqttManager (Implement MQTT Topic Subscription in MqttManager (CATROID-1674) #5233)
• CATROID-1676: Listener registration and callback dispatch
• CATROID-1678: Subscription registry and topic-to-listener routing
• CATROID-1679: Event queue for incoming messages

Work in this branch that has no ticket yet, listed here so it can be split out once the tickets exist: wildcard topic matching, stage lifecycle integration, event dispatch, the two bricks, variable binding, the offline publish queue, reconnect with subscription recovery, and multiplayer over MQTT. Those commits deliberately carry no ticket prefix.

---

Changes Implemented

org.catrobat.catroid.devices.mqtt

• MqttManager The central manager, a Koin single living for the lifetime of the app. Owns the connection, publishing, subscriptions, listener routing, both queues and reconnect. A session flag ends the connection for good when the stage stops, so a connect still in flight cannot revive a stage the user has left.

• MqttClientInterface, PahoMqttClient, MqttClientFactory Abstract the Paho client behind an interface so MqttManager is testable on the JVM without an Android runtime or a network. PahoMqttClient also bounds Paho's timeToWait, which otherwise waits forever for an unacknowledged publish.

• MqttConnectionConfig Groups the six broker parameters and reads them from SettingsFragment.

• MqttTopicMatcher Topic matching to MQTT 3.1.1 section 4.7, including +, # and the rule that neither matches a topic beginning with $. Also validates filters and topic names, because Paho rejects malformed ones with IllegalArgumentException rather than MqttException.

• MqttMessageQueue, MqttPublishQueue Bounded queues that drop the oldest entry when full. Incoming messages are buffered by the Paho network thread and drained on the render thread; outgoing messages wait here while the broker is unreachable and are flushed on reconnect.

• MqttListener, MqttEventDispatcher, MqttScriptRegistrar Route a received message to the listeners registered for its topic, turn it into a Catroid event, and register and subscribe every MQTT script when the stage starts.

• MqttMultiplayerTransport Carries multiplayer variables over MQTT alongside Bluetooth, under catrobat/multiplayer/<room>/<sender>/<variable>.

Bricks, scripts and actions

• PublishMqttMessageBrick, PublishMqttMessageAction Publish a formula-computed message to a formula-computed topic, with QoS and a retained flag. The send happens off the render thread so a slow broker cannot freeze the stage.

• WhenMqttMessageReceivedBrick, MqttScript, MqttEventId A script that runs when a message arrives on a topic, optionally binding the payload and the topic to user variables. Both bindings are optional and a "not set" entry keeps them unset until the user picks a variable.

Integration with existing code

Brick.MQTT_CONNECTION as a stage resource, connection setup in StageResourceHolder and teardown in StageActivity, per-frame draining in StageListener, brick registration in CategoryBricksFactory, XStream aliases in XstreamSerializer, action creation in ActionFactory, variable remapping in ScriptController, and Koin registration in CatroidKoinHelper.

Testing

51 files changed, 252 MQTT unit tests, 20 instrumented tests.

• Unit tests use hand-written fakes rather than a mocking framework, matching the existing MQTT tests. The fake client rejects malformed topics exactly as Paho does, so tests fail rather than pass when validation is missing.
• Instrumented tests cover the bricks in the IDE, serialization round trips, the encrypted password store, and an end-to-end run against a real Mosquitto broker.
• Verified by hand on a Pixel 6 Pro against Mosquitto: both bricks, wildcard routing, broker loss and recovery, leaving and re-entering the stage, and a project whose topic the broker would reject.
• Multiplayer verified across two emulators with a small race-to-100 game where the scores sync live between devices.
• The full local run is green: 4830 unit tests, and pmd, checkstyle, detekt and lint report no new findings against develop.

Known Limitations

• Multiplayer variables still require a Bluetooth connection, because Project.getRequiredResources() adds Brick.BLUETOOTH_MULTIPLAYER whenever a project contains them, with no notion of which transport the user wants. The two bricks give working multiplayer in the meantime.
• TLS works only against brokers with a publicly trusted certificate; Android rejects a self-signed local broker.
• The two bricks have no wiki help pages yet.

---

Your Checklist

• Include the name of the Jira ticket in the PR's title
• Include a summary of the changes plus the relevant context
• Choose the proper base branch (develop)
• Confirm that the changes follow the project's coding guidelines
• Verify that the changes generate no compiler or linter warnings
• Perform a self-review of the changes
• Verify to commit no other files than the intentionally changed ones
• Include reasonable and readable tests verifying the added or changed behavior
• Confirm that new and existing unit tests pass locally
• Check that the commits' message style matches the project's guideline
• Stick to the project's gitflow workflow
• Verify that your changes do not have any conflicts with the base branch
• After the PR, verify that all CI checks have passed
• Post a message in the catroid-stage or catroid-ide Slack channel and ask for a code reviewer

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud