OBD2 MQTT: Connect Your Car to Home Assistant

Harness the power of your car’s onboard diagnostics with Obd2 Mqtt, and seamlessly integrate real-time vehicle data into your Home Assistant smart home system. This guide will walk you through setting up an OBD2 to MQTT bridge, allowing you to monitor everything from engine temperature to fuel consumption directly within your home automation dashboard.

What You’ll Need for OBD2 MQTT Integration

To embark on this exciting project, gather the following components. These are essential to establish a robust OBD2 MQTT connection for your Home Assistant setup:

Home Assistant with Mosquitto Broker: Ensure you have Home Assistant installed and the Mosquitto Broker MQTT add-on configured and running. This is the central hub for receiving and processing your car’s data.
ESP32 with SIM800L or A7670 Module: An ESP32 microcontroller paired with a SIM800L or A7670 GSM module provides the processing power and cellular connectivity needed for OBD2 MQTT data transmission.
ELM327 OBD2 Bluetooth Adapter: A reliable ELM327 Bluetooth adapter is crucial for interfacing with your car’s OBD2 port and retrieving diagnostic data.
SIM Card: A SIM card with a data plan is required for cellular communication, enabling your ESP32 to send OBD2 MQTT data to your Home Assistant server remotely. Consider providers like fraenk for affordable data options.
A Car: Of course, you’ll need a car with an OBD2 port to connect to and extract data from!
(Optional) PlatformIO IDE: If you prefer compiling the firmware yourself, PlatformIO is a powerful open-source ecosystem for embedded development.
(Optional) Node.js and NPM: These are needed if you intend to customize or build upon the web-based tools for firmware management.

Supported Hardware for OBD2 MQTT

Choosing the right hardware is crucial for a smooth OBD2 MQTT experience. Here’s a compatibility overview of recommended devices, focusing on factors like SSL/TLS support and available enclosures:

Product	Environment	SSL/TLS Support	Enclosure Options
T-Call SIM800L	SIM800L_IP5306_VERSION_20190610 SIM800L_IP5306_VERSION_20200811	❌ (SSL 2/3, TLS 1.0/1.2 only)	Enclosure for SIM800L Boards
T-Call SIM800C	SIM800L_AXP192_VERSION_20200327 SIM800C_AXP192_VERSION_20200609	❌ (SSL 2/3, TLS 1.0/1.2 only)	Enclosure for SIM800L Boards
T-Call A7670	T-Call-A7670X-V1-0 T-Call-A7670X-V1-1	✅	Enclosure with Internal GPS/LTE Enclosure with External GPS/LTE
T-A7670E/G/SA R2	T-A7670X	✅	Enclosure with Internal GPS/LTE Enclosure with External GPS/LTE
T-A7670E/G/SA R2 without GPS	T-A7670X-NO-GPS	✅	Enclosure for A7670 Boards
T-A7670G with GPS Shield	T-A7670X-GPS-SHIELD	✅	Enclosure with Internal GPS/LTE Enclosure with External GPS/LTE

This table highlights devices suitable for your OBD2 MQTT project, considering SSL/TLS for secure communication and practical enclosure solutions for different board configurations.

Getting Started with Your OBD2 MQTT Bridge

Let’s dive into setting up your OBD2 MQTT bridge. The easiest way to get started is using the web installer:

Web Installation (ESP Web Tools) for OBD2 MQTT

For users who prefer a straightforward setup without compiling firmware, the Web Installer provides a hassle-free method to flash your ESP32 device with the necessary OBD2 MQTT firmware. Simply connect your ESP32 to your computer and follow the intuitive steps on the website.

Updating Firmware and Settings for OBD2 MQTT

Once your OBD2 MQTT device is flashed, you can easily update settings or the firmware itself through a web interface:

Connect to the OBD2-MQTT Wi-Fi Access Point: Your ESP32 will create a Wi-Fi network named “OBD2-MQTT-” followed by its MAC address. Connect your computer or phone to this network.
Access the Configuration Portal: Open a web browser and navigate to http://192.168.4.1.
Adjust Settings or Update Firmware: Within the web portal, you can modify your OBD2 MQTT settings to match your Wi-Fi, MQTT broker, and car specifics. You can also upload new firmware and filesystem images for updates.

Screenshot of the OBD2 MQTT settings page, showing options for Wi-Fi, MQTT, and OBD2 adapter configuration.

Screenshot of the Over-The-Air (OTA) update interface, allowing users to easily update the OBD2 MQTT firmware and filesystem.

Building Firmware for Advanced OBD2 MQTT Users

For those who prefer a more hands-on approach or need to customize the OBD2 MQTT firmware, compiling from source using PlatformIO is the way to go:

Build firmware.bin:

pio run [-e OPTIONAL ENV]

Build littlefs.bin (filesystem):

pio run --target buildfs [-e OPTIONAL ENV]

Uploading Firmware to Your OBD2 MQTT Device

After building the firmware and filesystem images, you can upload them to your ESP32 device using PlatformIO:

Upload firmware.bin:

pio run --target upload -e T-Call-A7670X-V1-0

Upload littlefs.bin (filesystem) while preserving settings:

<span><span>#</span> connect to AP and save current settings</span> curl http://192.168.4.1/api/settings -o settings.json pio run --target uploadfs -e T-Call-A7670X-V1-0 <span><span>#</span> after reboot connect to AP</span> curl -X PUT -H <span><span>"</span>Content-Type: application/json<span>"</span></span> -d @settings.json http://192.168.4.1/api/settings

This advanced upload method ensures your OBD2 MQTT device retains its configuration even after a filesystem update.

Configuring Your OBD2 MQTT Settings

The settings page is where you tailor your OBD2 MQTT bridge to your specific needs. Navigate to the settings portal as described earlier and configure the following:

Wi-Fi: Enter your home Wi-Fi credentials for internet connectivity.
Mobile Settings: Configure APN and other mobile network settings relevant to your SIM card provider.
ELM327 Device: Specify the Bluetooth name or address of your ELM327 OBD2 adapter.
OBD2 Protocol (Optional): Select a specific OBD2 protocol for faster initialization if you know your car’s protocol. Otherwise, leave it on auto-detect.
MQTT Configuration: Input your Mosquitto Broker details, including broker address, port, username, and password. For SIM800 devices, note that OBD2 MQTT supports SSL 2/3 and TLS 1.0 for secure MQTT communication.
Sleep Settings (Battery Devices): If using a battery-powered ESP32, configure sleep timeout (idle time before sleep) and sleep duration to optimize power consumption when the car is off or inactive. This is crucial for efficient OBD2 MQTT operation in battery-powered setups.

Pre-Configured Sensors for OBD2 MQTT and Home Assistant

The standard OBD2 MQTT profile comes loaded with a comprehensive set of sensors, ready to be integrated into your Home Assistant dashboard. These sensors provide a wide range of vehicle data points:

Ambient Temperature
Battery Voltage
Calculated Average Speed
Calculated Fuel Consumption
Calculated Fuel Consumption per 100km/Miles
Calculated Driven Distance
Check Engine Light Status
Engine Coolant Temperature
Engine Load
Engine Running Status
Fuel Level
Fuel Rate
Intake Air Temperature
Speed (Kilometer per Hour)
Mass Air Flow
Odometer
Oil Temperature
Pedal Position
Engine Revolutions Per Minute (RPM)
Throttle Position
Top Speed Achieved

In addition to these car-specific sensors, OBD2 MQTT also provides diagnostic data about the ESP32 device itself:

ESP32 CPU Temperature
ESP32 Free Memory
GPS Location (for A76xx modules)
GSM Location
Signal Quality (GSM)
Uptime

Screenshot from Home Assistant showcasing the integrated OBD2 MQTT sensors, displaying real-time vehicle data within the smart home dashboard.

Explore additional sensor profiles here to customize your OBD2 MQTT setup further.

Customizing OBD2 Sensors in Your MQTT Bridge

For advanced users, OBD2 MQTT offers the flexibility to define custom OBD2 states and tailor the data collection to specific needs. Navigate to the “OBD” tab in the web configuration portal to manage these custom sensors.

Screenshot of the OBD2 sensor configuration tab in the web interface, showing options for customizing OBD2 states, including READ and CALC types.

Sensor State Types:

OBD2 MQTT supports two main types of custom states:

READ States: These directly read OBD2 PIDs (Parameter IDs) from your car.
CALC States: These calculate values based on other sensor states, allowing for derived metrics and complex data analysis within your OBD2 MQTT bridge.

Both READ and CALC states can be configured with the following value types:

BOOL: Boolean (true/false) values
FLOAT: Floating-point numbers (decimal values)
INT: Integers (whole numbers)

Common Sensor Options:

Enabled: Toggles the sensor state on or off.
Visible: Determines if the sensor is displayed in the user interface and published via OBD2 MQTT.
Measurement: Indicates if the state represents a physical measurement for Home Assistant’s sensor device class handling.
Diagnostic: Flags the state as diagnostic information.
Interval: Sets the data update interval in milliseconds (-1 for one-time updates).
Name: The unique name of the state (alphanumeric and underscores only).
Description: A user-friendly description displayed in Home Assistant.
Icon: A Home Assistant Material Design Icons (MDI) name (without “mdi:”).
Sensor Device Class: A Home Assistant sensor device class for proper categorization and unit handling (refer to Home Assistant Sensor Device Classes).
Unit: The unit of measurement for the sensor (if applicable or for custom units).

READ State Configuration for OBD2 MQTT

READ states are the foundation of OBD2 MQTT, enabling direct access to your car’s diagnostic parameters. You can configure READ states using either pre-defined internal functions or by manually specifying PID codes and data interpretation rules.

Example 1: READ State with Internal Function (Battery Voltage)

{ <span>"type"</span>: <span>0</span>, <span>"valueType"</span>: <span><span>"</span>float<span>"</span></span>, <span>"enabled"</span>: <span>true</span>, <span>"visible"</span>: <span>true</span>, <span>"interval"</span>: <span>30000</span>, <span>"name"</span>: <span><span>"</span>batteryVoltage<span>"</span></span>, <span>"description"</span>: <span><span>"</span>Battery Voltage<span>"</span></span>, <span>"icon"</span>: <span><span>"</span>battery<span>"</span></span>, <span>"unit"</span>: <span><span>"</span>V<span>"</span></span>, <span>"deviceClass"</span>: <span><span>"</span>voltage<span>"</span></span>, <span>"measurement"</span>: <span>true</span>, <span>"diagnostic"</span>: <span>false</span>, <span>"readFunc"</span>: <span><span>"</span>batteryVoltage<span>"</span></span> }

This JSON configuration defines a READ state for battery voltage, utilizing the internal “batteryVoltage” function for simplified setup.

Example 2: READ State with Custom PID Codes (Engine RPM)

{ <span>"type"</span>: <span>0</span>, <span>"valueType"</span>: <span><span>"</span>int<span>"</span></span>, <span>"enabled"</span>: <span>true</span>, <span>"visible"</span>: <span>true</span>, <span>"interval"</span>: <span>100</span>, <span>"name"</span>: <span><span>"</span>rpm<span>"</span></span>, <span>"description"</span>: <span><span>"</span>Rounds per minute<span>"</span></span>, <span>"icon"</span>: <span><span>"</span>engine<span>"</span></span>, <span>"measurement"</span>: <span>true</span>, <span>"diagnostic"</span>: <span>false</span>, <span>"pid"</span>: { <span>"service"</span>: <span>1</span>, <span>"pid"</span>: <span>12</span>, <span>"numResponses"</span>: <span>1</span>, <span>"numExpectedBytes"</span>: <span>2</span>, <span>"scaleFactor"</span>: <span><span>"</span>1.0 / 4.0<span>"</span></span>, <span>"bias"</span>: <span>0</span> } }

Here, a READ state for engine RPM is configured by directly specifying the OBD2 PID codes (service 1, PID 12), response details, and a scaling factor to convert the raw data into RPM values. Remember to use decimal PID values, not hexadecimal.

CALC State Configuration for Advanced OBD2 MQTT Sensors

CALC states in OBD2 MQTT empower you to create sophisticated sensors by performing calculations on data from other states. This opens up possibilities for fuel economy metrics, trip statistics, and more.

Example: CALC State for Distance Driven

{ <span>"type"</span>: <span>1</span>, <span>"valueType"</span>: <span><span>"</span>float<span>"</span></span>, <span>"enabled"</span>: <span>true</span>, <span>"visible"</span>: <span>true</span>, <span>"interval"</span>: <span>100</span>, <span>"name"</span>: <span><span>"</span>distanceDriven<span>"</span></span>, <span>"description"</span>: <span><span>"</span>Calculated driven distance<span>"</span></span>, <span>"icon"</span>: <span><span>"</span>map-marker-distance<span>"</span></span>, <span>"unit"</span>: <span><span>"</span>mi<span>"</span></span>, <span>"deviceClass"</span>: <span><span>"</span>distance<span>"</span></span>, <span>"measurement"</span>: <span>true</span>, <span>"diagnostic"</span>: <span>false</span>, <span>"expr"</span>: <span><span>"</span>$distanceDriven + ($speed.ov + $speed) / 2 / 3600 * ($millis - $distanceDriven.lu) / 1000<span>"</span></span>, <span>"value"</span>: { <span>"func"</span>: <span><span>"</span>toMiles<span>"</span></span> } }

This CALC state calculates the distance driven by integrating speed data over time. It utilizes an expression to combine current speed ($speed), previous speed ($speed.ov), timestamps, and the previous distance driven value ($distanceDriven.ov) to incrementally update the driven distance. The toMiles function in the value format section converts the calculated distance from kilometers to miles.

Expressions in OBD2 MQTT CALC States

OBD2 MQTT CALC state expressions are powerful tools for data manipulation. They support standard mathematical operators (+, -, *, /, ^), binary operators (& (AND), | (OR)), and references to other sensor states using a leading $ symbol.

Available Variables and Substates:

$millis: Current timestamp in milliseconds (predefined).
$var: Current value of the state named var.
$var.ov: Previous value of the state var.
$var.pu: Timestamp of the previous update for state var.
$var.lu: Timestamp of the last update for state var.
$var.a, $var.b, $var.c, $var.d: Individual bytes of an INT state var (byte access).

Built-in Mathematical Functions:

Single Parameter Functions:

sin, cos, tan
asin, acos, atan
sinh, cosh, tanh
asinh, acosh, atanh
ln, log, exp
sqrt, sqr
round, int

Two Parameter Functions:

min, max

OBD2 Specific Functions:

afRatio: Air-fuel ratio calculation based on fuel type.
density: Fuel density based on fuel type.
numDTCs: Number of Diagnostic Trouble Codes (DTCs) – requires calling monitor status first (see default profile for example).

Value Formatting in OBD2 MQTT

The “Value Format” option in OBD2 MQTT allows you to customize the output format of your sensor values. You can use simple printf-style formatting expressions (e.g., %d for integers, %.2f for floats). If left blank, default formatting is applied.

Built-in Value Formatting Functions:

toBitStr: Formats an integer value as a bit string.
toMiles: Converts kilometers to miles.
toGallons: Converts liters to gallons.
toMPG: Converts liters per 100km to miles per gallon.

By leveraging these features, you can create a highly customized and informative OBD2 MQTT system, bringing rich vehicle data into your Home Assistant smart home environment.