⚠️ Work in Progress: This project is under active development and not ready for production use. Features may be incomplete, APIs may change, and bugs are expected.

launchbox2mqtt

A LaunchBox plugin that bridges LaunchBox events to MQTT, enabling real-time monitoring and automation of retro gaming sessions. Companion to retro2mqtt for complete frontend-to-emulator observability.

Features

• Game Lifecycle Events: Publishes MQTT messages when games are launched, running, and exited
• Emulator Events: Tracks emulator loading and execution state
• System Events: Monitors LaunchBox and BigBox state changes
• Game Metadata: Publishes detailed game and emulator information as JSON
• Configuration UI: Easy-to-use dialog for MQTT broker settings
• Secure Credentials: Password encryption using Windows DPAPI
• Debug Logging: File-based logging to <LaunchBox>/Logs/launchbox-mqtt-debug.log

Related Projects

retro2mqtt Integration

This plugin is a companion to retro2mqtt, which monitors RetroArch emulator internals and provides Home Assistant integration via MQTT Discovery.

Why use both together?

• launchbox2mqtt tracks frontend events: game launches, LaunchBox state, and game metadata
• retro2mqtt monitors emulator internals: RetroArch core activity, savestate events, and real-time gameplay
• Together they provide complete visibility into your gaming sessions from frontend to emulator

Benefits of combining:

1. Home Assistant Integration: retro2mqtt provides MQTT Discovery for automatic entity creation in Home Assistant
2. Advanced Automations: Trigger actions based on both frontend (LaunchBox) and emulator (RetroArch) events
3. Complete Session Tracking: Track which frontend launched what game using which emulator core
4. Rich Automation Scenarios:
   • LaunchBox launches game → retro2mqtt detects RetroArch core → Home Assistant dims room lights
   • Track total play time across frontend and emulator
   • Discord rich presence showing game from LaunchBox + core from RetroArch
   • Separate metrics for frontend usage vs actual gameplay time

Architecture:

LaunchBox → launchbox2mqtt → MQTT Broker ← retro2mqtt ← RetroArch
                                    ↓
                            Home Assistant

Both projects can be used independently, but combining them unlocks powerful automation possibilities.

MQTT Topics

The plugin publishes to the following topics:

Game/Content Events

Topic	Payload	Retained	Description
launchbox/details	JSON	Yes	LaunchBox details like version and id.
launchbox/content/loaded	on/off	No	Content (game) is loaded
launchbox/content/running	on/off	No	Content is currently running
launchbox/content	Game title	No	Currently loaded game title
launchbox/content/last_played	Game title	Yes	Last played game title (retained)
launchbox/content/details	JSON	Yes	Full game metadata (retained)

Emulator Events

Topic	Payload	Retained	Description
launchbox/emulator/loaded	on/off	No	Emulator is loaded
launchbox/emulator/running	on/off	No	Emulator is currently running
launchbox/emulator	Emulator title	No	Currently loaded emulator
launchbox/emulator/last_loaded	Emulator title	Yes	Last loaded emulator (retained)
launchbox/emulator/details	JSON	Yes	Emulator configuration details (retained)

System Events

Topic	Payload	Retained	Description
launchbox/running	on/off	No	LaunchBox application state
launchbox/bigbox/running	on/off	No	BigBox mode state
launchbox/bigbox/locked	on/off	No	BigBox locked state
launchbox/system/event	Event name	No	Other system events (fallback)

Installation

1. Download the latest launchbox2mqtt-*.zip from GitHub Releases
2. Extract the contents to <LaunchBox Installation>/Plugins/MQTTPlugin/
3. Restart LaunchBox

For building from source, see Development Guide.

Configuration

MQTT Broker Settings

Configure your MQTT broker connection via the LaunchBox GUI:

1. Open LaunchBox
2. Navigate to Tools > MQTT Configuration menu item
3. Click to open the configuration dialog
4. Enter your MQTT broker details:
   • Host: MQTT broker hostname or IP address (default: localhost)
   • Port: MQTT broker port (default: 1883)
   • Username: Optional authentication username
   • Password: Optional authentication password
5. Click Test Connection to verify settings
6. Click Save to apply changes

Security:

• Passwords are encrypted using Windows DPAPI (Data Protection API)
• Encryption is user-scoped and machine-scoped
• Config stored in <LaunchBox>/Plugins/MQTTPlugin/config.json
• The MQTT connection automatically reconnects after saving new settings

Default Configuration:

If no configuration file exists, the plugin uses these defaults:

• Host: localhost
• Port: 1883
• No authentication

First Run

On first run without a config file, the plugin will log a warning and use default settings. Access the configuration dialog to set up your broker connection.

📃 License

MIT License - see LICENSE file for details.