Automate

Introduction to OBD PIDs

OBD (On-Board Diagnostics) PIDs (Parameter IDs) are codes used to request specific data from a vehicle's computer system. These standardized codes allow diagnostic tools to communicate with vehicles and retrieve real-time information about engine performance, emissions, speed, temperature, and many other parameters.

PIDs are typically represented in hexadecimal format and are organized into different modes (also called services). For example, Mode 01 (real-time data) contains PIDs for current engine parameters, while Mode 09 contains vehicle information like VIN number.

The WiCAN device uses these PIDs to periodically poll your vehicle for specific information, allowing you to monitor various aspects of your vehicle's operation in real-time through MQTT or HTTP interfaces.

Overview

The "Automate" feature enables you to periodically request one or more PIDs from your vehicle's ECU. This allows for continuous monitoring of vehicle parameters without manual intervention.

Before using the Automate feature, ensure that the Protocol in the CAN section on the "Settings" tab is set to AutoPID.

Configuration of "Automate" itself is done on the "Automate" tab.

Responses can be monitored:

Automate Settings

  • MQTT HA Discovery: This option is currently disabled. Instead use Home Assistant integration which will automatically detect the parameters.
  • Grouping: When enabled, groups related PIDs together in the output. This helps organize data in a more logical structure for MQTT.
  • Destination Type: Determines where the data is sent. The default option makes the data available through the HTTP endpoint, the 'MQTT Topic' will send to the destination topics specified in the Destination field.
  • Destination: Specify a custom destination for your data if needed (such as a specific MQTT topic).
  • Cycle Time(ms): The interval in milliseconds at which the system will request the configured PIDs. In the example, it's set to 5000ms (5 seconds).

Standard PIDs

  • Standard PIDs: Enable this option to use the standardized OBD-II PIDs defined in the SAE J1979 standard. A list of standard PIDs is available on https://en.wikipedia.org/wiki/OBD-II_PIDs#Standard_PIDs. Most vehicles support a number of these standard PIDs; however, not all car manufacturers expose all of these PIDs. For example, some vehicles might not support Odometer reading or Fuel level through standard PIDs, instead making them available through vehicle-specific PIDs.
  • ECU Protocol: Select the communication protocol used by your vehicle. The protocols include:
    • ISO 15765-4 CAN (11-bit ID, 500 kbaud) - Most common in modern vehicles
    • ISO 15765-4 CAN (29-bit ID, 500 kbaud)
    • ISO 15765-4 CAN (11-bit ID, 250 kbaud)
    • ISO 15765-4 CAN (29-bit ID, 250 kbaud)+
  • Available PIDs: Shows a list of available standard PIDs that can be requested. Use the "Add PID" button to add a specific PID or "Scan PIDs" to automatically detect supported PIDs in your vehicle.

Vehicle Specific

  • Vehicle Specific: Enable this option to use pre-configured settings specific to your vehicle model. Some parameters might not be available through the Standard PIDs, like battery State of Charge, so car manufacturers create their own specific PIDs.
  • Vehicle Model: Select your specific vehicle model from the dropdown list. Use the "Get Latest" button to download the most up-to-date vehicle profiles.
  • Vehicle Profiles: Alternatively, you can manually upload a vehicle profile file if your internet connection is limited or if you have custom profiles.
  • Specific Initialisation: Contains initialization commands that need to be sent to the vehicle before requesting specific PIDs.

Custom PIDs

Custom PIDs offer advanced flexibility and can be used for testing new PID requests, if you need a PID to be sent to specific topics, or to Wallbox MQTT.

  • Custom Initialisation: Will be sent by WiCAN prior to requesting particular PIDs.
  • Name: The attribute name containing the result of the PID request.
  • Init: Will be sent by WiCAN prior to requesting this particular PID.
  • Expression: Is used to calculate the attribute value from the bytes returned for this PID.
  • Min Value: The minimum value calculated by expression.
  • Max Value: The maximum value calculated by expression.
  • Period: The interval after which this PID is requested again.
  • Destination Type: The default option makes the data available through the HTTP endpoint. The 'MQTT Topic' will send to the destination topics specified in the Destination field, and Wallbox will send it in Wallbox format.
  • Send_to: The MQTT topic the result should be sent to.

In order to add more PIDs, the New button can be used. The Delete button deletes the configuration of the corresponding PID.

Expression Format for Automate

The Expression field in Automate allows you to process the raw data received from your vehicle and convert it into meaningful values. Understanding how to write these expressions is essential for creating custom PIDs or interpreting vehicle data correctly.

Basic Syntax

Expressions are mathematical formulas that can reference specific bytes from the vehicle's response data and perform calculations with them.

Data Access Methods

  • Raw Bytes (Unsigned): B0, B1, B2, etc.
    • References the byte at the specified index (zero-based)
    • Example: B0 refers to the first byte in the response
  • Bit Access: B0:3
    • References a specific bit within a byte
    • Format: Bx:y where x is the byte index and y is the bit position
    • Example: B0:3 refers to the 4th bit (position 3) of the first byte
  • Signed Bytes: S0, S1, S2, etc.
    • References the byte at the specified index as a signed value
    • Example: S0 treats the first byte as a signed 8-bit value
  • Byte Ranges (Unsigned): [B0:B1]
    • Combines multiple consecutive bytes into one value (big-endian)
    • Example: [B0:B1] combines the first two bytes as a 16-bit unsigned value
  • Byte Ranges (Signed): [S0:S1]
    • Combines multiple consecutive bytes into one signed value (big-endian)
    • Example: [S0:S1] combines the first two bytes as a 16-bit signed value
    • Properly handles sign extension based on the size of the range

Supported Operations

  • Arithmetic: +, -, *, /
    • Example: B0 + B1, [B0:B1] / 4
  • Bitwise: & (AND), | (OR), ^ (XOR)
    • Example: B0 & 0xFF, B1 | B2
  • Bit Shifting: <<, >>
    • Example: B0 << 8, [B0:B3] >> 2
  • Grouping: (, )
    • Example: (B0 + B1) * 4

Common Expression Patterns

  1. Simple Value Extraction:
    • B0 - Return the raw value of the first byte
  2. Temperature Conversion:
    • B0 - 40 - Common formula for engine temperature (°C)
  3. Multi-Byte Values:
    • [B0:B1] - 16-bit value from two bytes
    • [B0:B3] - 32-bit value from four bytes
  4. Scaling Factors:
    • [B0:B1] / 4 - Scaled 16-bit value (divides by 4)
    • B0 * 0.5 - Scaled 8-bit value (multiplies by 0.5)
  5. Bit Masking and Extraction:
    • (B0 & 0xF0) >> 4 - Extract the upper 4 bits of a byte
    • B0 & 0x0F - Extract the lower 4 bits of a byte
  6. Percentage Calculations:
    • B0 * 100 / 255 - Convert 8-bit value to percentage

Example Expressions

  • Battery voltage: [B0:B1] / 1000
  • Engine RPM: [B0:B1] / 4
  • Vehicle speed: B0
  • Engine load: B0 * 100 / 255
  • Fuel level: B0 * 100 / 255
  • Engine coolant temperature: B0 - 40
  • Battery State of Charge: [B0:B1] / 10

Notes

  • Bytes are zero-indexed (B0 is the first byte)
  • Expressions are evaluated from left to right following standard operator precedence
  • Use parentheses () to control the order of operations
  • Maximum range for byte combinations is 8 bytes
  • Expressions support both integer and floating-point calculations
Table of Contents