AI Disclosure: This project is developed with the assistance of AI tools, primarily Claude (Anthropic) as well as other AI-based coding assistants. AI is used for code generation, code review, bug analysis, and documentation. All AI-generated output is reviewed by the project maintainer before being committed. I am not a professional programmer — please keep this in mind when using the plugin or reviewing the code.
A powerful and flexible SimHub plugin that publishes granular racing telemetry data to an MQTT broker in real-time. Perfect for building custom dashboards, data analysis tools, streaming overlays, and IoT integrations.
Development & Testing: This plugin is primarily developed and tested with Le Mans Ultimate (LMU). It is designed to work with all SimHub-supported simulators, but LMU is the reference platform for feature validation and bug testing.
Forked from and enhanced: SimenAsphaug/SimHub-MQTT-Publisher who forked from: SHWotever/SimHub-MQTT-Publisher
- 80+ Granular Telemetry Properties - Select exactly what data you need
- Organized Tab Interface - Clean UI with Connection, Presets, Telemetry, and Settings tabs
- Configurable Update Rate - Set the MQTT publish interval in milliseconds (default: 100 ms ≈ 10 Hz)
- Publish on Change Only - Optionally skip publishing when no selected values have changed
- Root-Level Property Control - Choose to include/exclude timestamp, userId, and gameName
- Dynamic Topic Placeholders - Use {gameName}, {sessionType}, {trackName}, {carName} for flexible routing
- Real-time MQTT Publishing - Non-blocking, fire-and-forget data streaming to any MQTT broker
- Quick Preset Configurations - Basic, Racing, Strategy, and Analysis presets
- Export/Import Settings - Share configurations between installations
- Connection Testing - Built-in MQTT broker connectivity verification
- Password Protection - Secure credential management with show/hide toggle
- Debug Mode - Complete raw telemetry data for discovery and troubleshooting
- Correct Lap Time Handling - Proper TimeSpan-to-millisecond conversion for BestLapTime, LastLapTime, sector times, etc.
- Multi-Game Support - Works with any simulator supported by SimHub (Le Mans Ultimate, iRacing, ACC, and more)
- Installation
- Configuration
- Usage
- Data Structure
- Use Cases
- Documentation
- Troubleshooting
- Contributing
- License
- SimHub (version 8.0 or later recommended)
- MQTT Broker (Mosquitto, EMQX, HiveMQ, AWS IoT Core, Azure IoT Hub, etc.)
- .NET Framework 4.8 (usually included with SimHub)
-
Download the latest release from the Releases page
-
Extract the release archive - You'll find these DLL files:
SimHub.MQTTPublisher.dll(required)MQTTnet.dll(required)
-
Copy both DLL files to your SimHub installation directory (typically
C:\Program Files (x86)\SimHub\)Note:
Newtonsoft.Json.dllis not included in the release — the plugin uses the copy already shipped with SimHub. -
Restart SimHub - The plugin will be automatically detected and loaded
-
Verify installation:
- Open SimHub
- Navigate to Settings → Plugins
- Look for "MQTT Publisher Enhanced" in the plugin list
-
Open SimHub and navigate to the MQTT Publisher Enhanced plugin settings
-
Configure MQTT Connection (Connection Settings Tab):
MQTT Server: mqtt://your-broker-address:1883 Login: your_username (if authentication enabled) Password: your_password (if authentication enabled) Topic: simhub/telemetry (or your preferred topic)Topic Placeholders:
You can use dynamic placeholders in your MQTT topic that will be replaced with real-time values:
{gameName}- Current simulator (e.g., "IRacing", "Assetto_Corsa_Competizione"){sessionType}- Session type (e.g., "Practice", "Qualifying", "Race"){trackName}- Current track/circuit (e.g., "Spa-Francorchamps", "Monza"){carName}- Current vehicle (e.g., "Porsche_911_GT3_R", "Ferrari_488_GT3")
All placeholders are automatically sanitized (spaces → underscores, special chars removed)
Examples:
simhub/{gameName}/telemetry→simhub/IRacing/telemetryracing/{trackName}/{carName}→racing/Spa-Francorchamps/Porsche_911_GT3_Rtelemetry/{gameName}/{sessionType}→telemetry/IRacing/Race
-
Test Connection:
- Click the "Test Connection" button
- Wait for the status message (green = success, red = failure)
- Troubleshoot any connection issues before proceeding
-
Select Telemetry Data:
Option A - Use Quick Presets (Quick Presets Tab):
- Basic: Essential telemetry (speed, RPM, gear, throttle, brake)
- Racing: Racing-focused data (position, gaps, lap times, flags)
- Strategy: Strategy management (fuel, tire wear, pit stops)
- Analysis: Everything enabled (except debug options)
Option B - Manual Selection (Telemetry Configuration Tab):
- Review the Performance Notice at the top
- Configure Root Level Properties (timestamp, userId, gameName)
- Expand categories and check individual properties you need
- Debug options available in Advanced Debugging section
-
Apply Settings - Click the global "Apply Settings" button at the bottom to save and activate
Go to the Settings Management Tab:
Export your configuration:
- Click "Export Settings" button
- Choose a location and filename (e.g.,
my-racing-config.json) - Settings are saved as JSON (password excluded for security)
Import a configuration:
- Click "Import Settings" button
- Select a previously exported JSON file
- Review the imported settings
- Click "Apply Settings" to activate
Available in the Advanced Debugging section of the Telemetry Configuration tab:
Debug Flag Details:
- Shows individual flag breakdown (Green, Yellow, Red, Blue, etc.)
- Useful for understanding flag system behavior
Debug Mode:
- Sends ALL raw telemetry data from the simulator
- Includes complete GameData object with hundreds of properties
- Warning: Significantly increases payload size and CPU usage
- Use only for:
- Discovering available properties for your simulator
- Troubleshooting data issues
- Custom integration development
The plugin provides two mechanisms to control MQTT traffic:
- Update Interval (ms) — Configurable in Connection Settings. Sets the minimum time between publishes. Default: 100 ms (≈ 10 Hz). Minimum: 10 ms.
- Publish on Change Only — When enabled, messages are only sent if at least one selected telemetry value has changed since the last publish. Ideal for slow-changing data like lap times or position.
Additional performance tips:
- Enable only the properties you actually need
- Disable entire categories you don't use
- Avoid Debug Mode unless specifically needed for troubleshooting
- More properties = Larger payloads = Higher CPU usage
Once configured, the plugin automatically publishes telemetry data when:
- SimHub is running
- A supported racing simulator is running
- You're in an active session (practice, qualifying, race)
Data is published to your configured MQTT topic in JSON format.
Use any MQTT client to subscribe and view the data:
Using mosquitto_sub (command line):
mosquitto_sub -h your-broker-address -t simhub/telemetry -u username -P passwordUsing MQTT Explorer (GUI):
- Connect to your broker
- Subscribe to your topic (e.g.,
simhub/telemetry) - View real-time JSON payloads
Using Node-RED:
- Add an MQTT Input node
- Configure broker connection
- Set topic to match your configuration
- Process the JSON data with function nodes
The plugin publishes data as JSON with the following top-level structure:
{
"time": 1704067200000,
"userId": "unique-user-id",
"gameName": "Assetto Corsa Competizione",
"carState": { ... },
"flagState": { ... },
"positionData": { ... },
"tireData": { ... },
"fuelData": { ... },
"weatherData": { ... },
"damageData": { ... },
"inputData": { ... },
"safetyData": { ... },
"trackInformation": { ... },
"vehicleInformation": { ... },
"sessionInfo": { ... }
}Root-Level Properties:
time- Unix timestamp in milliseconds (enabled by default)userId- Unique identifier for the user (disabled by default)gameName- Name of the racing simulator (enabled by default)
Note: Only enabled data categories and properties appear in the payload. Null values are automatically excluded to minimize bandwidth.
{
"time": 1704067200000,
"gameName": "Assetto Corsa Competizione",
"carState": {
"SpeedKmh": 245.7,
"Rpms": 8450,
"Gear": "5",
"Throttle": 0.95,
"Brake": 0.0,
"CurrentLapTime": 94536.2
},
"flagState": {
"Flags": 4
}
}For detailed documentation of all data fields, see the Documentation section.
Build custom web dashboards using:
- MQTT.js (JavaScript MQTT client)
- WebSockets (with MQTT broker WebSocket support)
- Chart.js / D3.js for data visualization
- React / Vue / Angular for UI framework
Collect telemetry for post-race analysis:
- Subscribe to MQTT topic with Python, Node.js, or any language
- Store data in database (InfluxDB, MongoDB, PostgreSQL)
- Analyze lap times, tire degradation, fuel consumption
- Generate reports and insights
Enhance your live streams:
- OBS Browser Source with MQTT WebSocket connection
- Display real-time telemetry on stream
- Custom graphics and animations based on race events
- Flag status indicators and position updates
Connect physical devices:
- LED strips for flag status (green = racing, yellow = caution)
- Vibration motors for tire wear warnings
- Physical gauges for RPM, speed, fuel
- Smart home integration (change room lighting based on race status)
Create race notifications:
- Subscribe to MQTT with bot
- Send alerts for race start, finish, incidents
- Post lap time updates to channels
- Team race coordination
Comprehensive documentation is available in the /docs folder:
- Data Categories Overview - Complete list of all available data
- Car State Data - Speed, RPM, gear, pedal inputs, engine status
- Flag System - Understanding flag states and bitwise values
- Position & Timing - Race position, lap times, sector times, gaps
- Tire Data - Temperature, pressure, wear, grip, compound
- Fuel & Energy - Fuel levels, consumption, ERS, DRS, battery
- Weather & Track Conditions - Temperature, rain, wind, grip
- Damage & Mechanical - Car damage, temperatures, wear indicators
- Driver Input - Steering, pedals, assists, electronic systems
- Safety & Race Control - Safety car, pit status, penalties, formation laps
- Integration Examples - Code samples for common use cases
"Connection timeout" error:
- Verify broker address and port (default MQTT port is 1883)
- Check firewall rules allow outbound connections on port 1883
- Ensure MQTT broker is running and accessible
- Try connecting with mosquitto_sub to verify broker availability
"Connection failed" error:
- Check username and password if authentication is enabled
- Verify broker supports MQTT 3.1.1 protocol
- Check broker logs for connection rejection reasons
- Ensure SSL/TLS settings match broker configuration (this plugin uses non-SSL by default)
Subscribed to topic but receiving no messages:
- Confirm a racing simulator is running and in an active session
- Verify at least one telemetry option is enabled
- Check topic name matches exactly (MQTT is case-sensitive)
- Ensure "Apply Settings" was clicked after configuration
- Look for errors in SimHub logs
Data is missing expected fields:
- Not all simulators provide all telemetry properties
- Enable Debug Mode temporarily to see all available properties for your sim
- Some properties are only available during specific conditions (e.g., DRS in F1 games)
SimHub or game stuttering:
- Reduce the number of enabled telemetry properties
- Check MQTT broker can handle the message rate
- Consider using MQTT QoS level 0 for better performance
- Verify network connection is stable
High bandwidth usage:
- Disable unnecessary telemetry categories
- Avoid Debug Mode unless needed
- Consider implementing message throttling in your client application
Parsing JSON fails:
- Ensure your client expects null values may be omitted
- Check for partial messages (unlikely but possible with network issues)
- Validate JSON structure with online JSON validator
- Some fields may return unexpected types depending on simulator
Contributions are welcome! Please feel free to:
- Report bugs via GitHub Issues
- Suggest features or enhancements
- Submit pull requests with improvements
- Share your use cases and integrations
- Improve documentation
- TelemetryHelper with PropertyInfo Cache: All reflection-based property lookups are now cached, eliminating repeated
GetProperty()calls (~300/s at 10 Hz). TimeSpan-to-milliseconds conversion is now consistent across all payload classes. - MQTT Auto-Reconnect: The plugin now automatically reconnects when the broker connection drops. The reconnect loop is cleanly cancelled when settings are reapplied or SimHub shuts down.
- Publish Error Logging: MQTT publish failures are now logged to the SimHub log instead of being silently discarded.
- Concurrent Guard: Rapid "Apply Settings" clicks no longer create multiple simultaneous MQTT connections.
- Fixed TestConnection: Connection errors are now correctly surfaced in the UI; the test client is always properly disposed.
- Fixed CarCoordinates Null Crash: Added null check before calling
.ToList()on coordinates. - Fixed Include_GameName Default: ViewModel default now matches the Settings class default (
true). - SessionInfo as Typed Class: Replaced anonymous object with a proper
SessionInfoclass including correct TimeSpan handling forSessionTimeLeft. - LMU as Primary Test Platform: Development and testing now done with Le Mans Ultimate.
- Simplified Installation:
Newtonsoft.Json.dllno longer needs to be copied — SimHub already ships with it. Only copy it if you encounter runtime errors. - Fixed AssemblyVersion: Assembly version now correctly matches the release version
- Configurable Update Rate: Set MQTT publish interval in milliseconds via Connection Settings (default 100 ms ≈ 10 Hz)
- Publish on Change Only: New option to skip publishing when no telemetry values have changed — greatly reduces MQTT traffic
- Non-blocking Publishing: Replaced synchronous
.Wait()with fire-and-forget to avoid blocking SimHub's critical DataUpdate path - Fixed Lap Time Data: BestLapTime, LastLapTime, PersonalBestLapTime, SessionBestLapTime, and all sector times now correctly convert from TimeSpan to milliseconds (previously always returned null)
- Organized Tab Interface: Separated UI into Connection, Presets, Telemetry, and Settings tabs
- Root-Level Property Control: Choose which root properties to include (time, userId, gameName)
- Dynamic Topic Placeholders: Support for {gameName}, {sessionType}, {trackName}, {carName} placeholders in MQTT topics
- iRacing Property Mappings: Fixed all property names to match iRacing telemetry (tire temps, fuel, lap times, sectors)
- Enhanced Debug Mode: Shows clean list of all available properties with values for property discovery
- Performance Warnings: Added clear warnings about payload size and CPU usage
- Debug Flag Details: Moved to Advanced Debugging section with dedicated checkbox
- Improved Presets: "Enable All" now excludes debug options for safety
- Better UX: Global Apply Settings button, clearer organization, helpful tooltips, collapsed expanders by default
- Complete rewrite with 80+ granular telemetry properties
- Quick preset configurations (Basic, Racing, Strategy, Analysis)
- Export/Import settings functionality
- Connection testing
- Password visibility toggle
- Debug mode for raw telemetry discovery
- Comprehensive documentation
- Multi-simulator support improvements
MIT License
Original project by SHWotever - Enhanced by Simen Asphaug (v1.1.0) - and further enhanced by Torsten Schuchort
- SHWotever for creating the original SimHub MQTT Publisher
- SimHub team for the excellent racing telemetry platform
- MQTT.NET for the robust MQTT client library
- All contributors and users of this enhanced version
For issues, questions, or suggestions:
- Open an issue on GitHub
- Check existing documentation in the
/docsfolder - Review closed issues for similar problems
Happy Racing! 🏁