OBD2 to MQTT for Home Assistant

What you need?

• an installed Home Assistant with Mosquitto Broker
• (optional) an installed PlatformIO
• (optional) an installed Node.js and NPM
• a ESP32 with SIM800L or A7670
  • (optional) RP-SMA to IPX cable
  • (optional) Antenna (work's for me) or other
  • (optional) a 3D Printer for the case
• a ELM327 OBD Bluetooth Adapter or any other
  • if you want to use this cheap adapter, you should set the right connection protocol or have patience
• a SIM Card - I use one from fraenk
• and the most important thing, a car

Supported Devices

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

Getting started

Upload via Web Installer (ESP Web Tools)

If you don't want to install PlatformIO and compile by your own, use the Web Installer.

Update Settings or Firmware & Filesystem

• connect to Wi-Fi Access Point starts with name OBD2-MQTT- followed from device MAC
• open Browser and navigate to http://192.168.4.1
• change settings to your needs and reboot afterward OR update to new firmware and filesystem

Build

Build firmware.bin

pio run [-e OPTIONAL ENV]

Build littlefs.bin

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

Upload

Build and upload firmware.bin to device

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

Build and upload littlefs.bin to device

# connect to AP and save current settings
curl http://192.168.4.1/api/settings -o settings.json

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

# after reboot connect to AP
curl -X PUT -H "Content-Type: application/json" -d @settings.json http://192.168.4.1/api/settings

Settings

Configure Wi-Fi, Mobile settings according to your needs. Set the detected ELM327 device and optionally select the protocol for faster initialization.
Set up the MQTT configuration with your data. If you want to use TLS/SSL on a SIM800 device, you need to know that only SSL 2/3 and TLS 1.0 are supported. For devices with a battery, you can set the automatic sleep timeout (no data/ignition off) and the sleep duration.

Configure Sensors

The following sensors are included in the supplied standard profile:

• Ambient Temperature
• Battery Voltage
• Calculated average speed
• Calculated consumption
• Calculated consumption per 100km
• Calculated driven distance
• Check Engine Light
• Engine Coolant Temperature
• Engine Load
• Engine Running
• Fuel Level
• Fuel Rate
• Intake Air Temperature
• Kilometer per Hour
• Mass Air Flow
• Odometer
• Oil Temperature
• Pedal Position
• Rounds per minute
• Throttle
• Top Speed ;-)

Diagnostic Output on all profiles:

• CPU Temperature (ESP)
• Free Memory (ESP)
• GPS Location (only for A76xx)
• GSM Location
• Signal Quality
• Uptime

More profiles can be found here.

Custom OBD States

On the OBD tab you can adjust the required states and upload and/or download the current profile. There two types of states, READ and CALC, both can be a value type of BOOL, FLOAT or INT.

Options:

• enabled

  the state is enabled

• visible

  the state is visible

• Measurement

  if the state is a measurement

• Diagnostic

  the state should be displayed as a diagnostic field

• Interval

  the update interval or -1 for onetime update

• Name

  the state name, only letters, numbers and underscore are allowed

• Description

  the state description, is shown in Home Assistant as field description

• Icon

  the state icon name without leading mdi:

• Sensor Device Class

  the sensor device class, see

• Unit

  the unit for device class or custom one

READ

The READ state is used to read PIDs, either using an internal function or by setting the PID codes, response, and value changes. The PID codes must be entered in decimal NOT hexadecimal.
Option scale factor can be a mathematical expression.

Example

with internal function:

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

or with PID codes and value changes:

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

CALC

The CALC state can be used to calculate a value based on other states.

Example

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

Expression

Within an expression, all mathematical operators are allowed as well as binary operator & (and) and | (or), other states can be used to calculate the value. To do this use the state name with a leading $.
It is also possible to use previous values and stored timestamps for this purpose.

Variables and it's substates:

• $millis
  predefined

  the current timestamp

• $var
  

  the current value

• $var.ov
  

  the previous value

• $var.pu
  

  the previous updated timestamp

• $var.lu
  

  the last updated timestamp

• $var.a
  only for INT states

  the first byte

• $var.b
  only for INT states

  the second byte

• $var.c
  only for INT states

  the third byte

• $var.d
  only for INT states

  the fourth byte

There are also some internal mathematical functions like:

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

as well as internal functions:

• afRatio - air flow ratio by fuel type
• density - density by fuel type
• numDTCs - number of DTCs, is required to call monitor status first. see default profile

Value Format

Can be used with simple printf compatible expression, such as %d for int or %.2f for float output. If you leave this field blank, the default values are used.
Or you can use the format expression to perform some calculations. Within this expression, only $value (for the current value) is allowed. There are also some built-in functions for formatting values.

• toBitStr
  

  Format as Bit String

• toMiles
  

  Convert km to mi

• toGallons
  

  Convert L to gal

• toMPG
  

  Convert L/100km to MPG