WiCAN Pro to Home Assistant: The Ultimate MQTT Best Practices Guide

[wambs]

WiCAN Pro to Home Assistant: The Ultimate MQTT Best Practices Guide

Integrating the WiCAN Pro with Home Assistant over MQTT unlocks incredible potential for vehicle monitoring. However, because CAN bus data is highly complex and transmits at lightning speed, a poorly planned setup will quickly result in messy configuration files and broken data.

Follow these best practices to build a bulletproof, highly optimized integration from the ground up.

Import Note: The Expression Hex type is only available on the WiCAN Pro forked releases: https://github.com/wambs/wican-fw/releases?page=1

---

📡 Why MQTT? The Advantages for Vehicle Telemetry

Before diving into the configuration, it is helpful to understand why MQTT (Message Queuing Telemetry Transport) is the gold standard for bridging your vehicle's CAN bus to your smart home:

• Extremely Lightweight: MQTT has incredibly small packet headers. This means it can transmit massive amounts of high-frequency data (like Engine RPM) without bogging down your Wi-Fi network or Home Assistant server.
• Lightning Fast: It operates on a publish/subscribe model, allowing for near real-time data streaming from your truck straight to your dashboard with virtually zero latency.
• Low Bandwidth: By only sending tiny text or hex payloads, it uses a fraction of the bandwidth compared to standard HTTP API requests.
• Reliability: It is specifically designed for environments where network connections might drop or fluctuate (like a vehicle pulling into or out of a garage).
• Rich Entity Customization: When defining MQTT sensors manually in Home Assistant, you have total control over the metadata. You can explicitly set the unit_of_measurement (like PSI or °C), define the state_class (like measurement for long-term statistics graphing), assign a unique_id to allow UI editing, and explicitly define the exact backend name using default_entity_id.

🛠️ The Ultimate Debugging Tool: MQTT Explorer

Before you write a single line of YAML code in Home Assistant, download a free desktop program called MQTT Explorer.

When you connect MQTT Explorer to your Home Assistant broker, you get a live, visual tree of every single message the WiCAN broadcasts. It is invaluable for troubleshooting because it allows you to:

• View all WiCAN activity in real-time with precise timestamps.
• Monitor the online / offline availability topics to confirm connection stability.
• See built-in WiCAN hardware metrics, such as the internal device battery level and signal strength.
• Copy the exact JSON or Hex payloads to reference while building your Home Assistant templates.

Tip

Mocking Data: You can manually inject/publish custom MQTT payloads directly to your broker using MQTT Explorer. This allows you to instantly test and debug your Home Assistant entity decoding logic without needing the truck running or the WiCAN device connected!

---

Phase 1: Initial MQTT Broker Connection (Settings Page)

Before you can start routing vehicle data, you must connect the WiCAN Pro to your Home Assistant MQTT broker (typically the Mosquitto Broker add-on).

Navigate to the Settings tab in the WiCAN Pro web interface and locate the MQTT section. Configure the fields as follows:

• Enable MQTT: Toggle this to ON.
• Broker Address: Enter the local IP address of your Home Assistant instance (e.g., 192.168.1.100). Do not add http:// or port numbers here.
• Port: Enter 1883 (the standard unencrypted MQTT port).
• Client ID: Give the WiCAN a unique name so your broker can identify it (e.g., wican_f350).
• Username & Password: Enter the credentials for the specific Home Assistant user you created for MQTT access.
• Keep Alive: 60 seconds is the standard default and works perfectly.

Once entered, save your settings. The WiCAN Pro will now maintain a persistent connection to Home Assistant whenever it is powered on and connected to your network.

---

Phase 2: MQTT Topic Naming & Payload Format

How you name your MQTT topics dictates how easily you can organize them in Home Assistant. Never dump raw PIDs into the root of your MQTT broker.

1. Use a Strict, Hierarchical MQTT Topic Prefix

Use a logical, nested structure that identifies the system, the vehicle, the module, and the specific data point.

• Format: <system>/<device>/<vehicle>/<module>_<data_name>
• Good Example: homeassistant/wican/f350/pcm_engine_rpm
• Good Example: homeassistant/wican/f350/bcm_remote_start_failures

2. Choose the Right Payload Format

• For simple, single-byte values (like RPM or Engine Temp): Let WiCAN handle the math and send the parsed Decimal/Integer over MQTT.
• For complex, multi-byte values (like TPMS packets or Bitmaps): Configure WiCAN to send the RAW HEX string. Sending raw hex bypasses JSON formatting quirks and integer overflow limits, allowing Home Assistant's template engine to perfectly slice and decode the data.

---

Phase 3: Configuring the WiCAN "Automate -> Vehicle" Rules

To actually tell the WiCAN Pro to start pulling data and pushing it to Home Assistant, you need to set up rules in the WiCAN web interface under Automate -> Vehicle. This is where you define exactly how the WiCAN interacts with the vehicle's CAN bus.

There are two primary ways to set these up: Active Polling and Passive Listening.

1. Setting up an Active Request (Polling)

Use this for data the truck doesn't broadcast on its own, requiring the WiCAN to specifically ask for it (e.g., Engine RPM, Transmission Temp, Gear Position).

When creating a new Vehicle Automation, configure the fields as follows:

• Name: A clean, recognizable name (e.g., F350 Gear Position).
• Trigger / Interval: Set how often you want WiCAN to ask for this data (e.g., 1000 ms for fast data like RPM, or 5000 ms for slow data like Coolant Temp).
• TX ID (Header): The physical address of the module you are querying (e.g., 7E2 for the TCM).
• TX Data (Request): The specific PID request hex (e.g., 22 1E 12).
• MQTT Topic: Paste your structured topic here (e.g., homeassistant/wican/f350/tcm_gear_raw).
• Expression / Output: Choose how WiCAN formats the reply. Choose standard math expressions if WiCAN is doing the math for you, or select Raw (Hex) to pass the raw string directly to HA.

Important

Don't Over-Poll: Do not poll modules faster than necessary, or you risk flooding the vehicle's CAN bus and causing network collisions.

2. Setting up a Passive Listener (Sniffing)

Use this for high-frequency data the truck broadcasts automatically, or for event-based data (e.g., TPMS tire pressure bursts, Door Locks, or Remote Start Failures). You do not want to actively poll for these.

• Trigger / Interval: Leave the polling interval blank or disabled.
• RX ID (Listen Address): Enter the specific CAN ID that broadcasts the data (e.g., 18FEF433 for TPMS events).
• TX ID / TX Data: Leave these completely blank! You are only listening, not asking.
• MQTT Topic: Enter your topic (e.g., homeassistant/wican/f350/bcm_slow_evnt1_all).
• Expression / Output: Set this to Raw (Hex). Because broadcast packets are often massive (like a 19-byte TPMS message), forcing it to raw hex prevents WiCAN from trying to format it as JSON and accidentally truncating the data.

Tip

Data Starts At: If you are using Raw (Hex) output, pay attention to where the actual data begins. If WiCAN includes the header in the output (e.g., 07 62 41 B8 08 08 08 08), you can either tell WiCAN to strip it by adjusting the starting byte, or just pass the whole string to Home Assistant and let Jinja2 slice it up using regex_findall. Passing the whole string is usually the safest method!

---

Phase 4: Home Assistant Configuration Best Practices

Because you will be creating dozens (or hundreds) of sensors, keeping your configuration.yaml clean is critical.

1. Group Entities Using a Device Anchor

Instead of having 50 loose sensors floating in Home Assistant, assign them all to a single "Vehicle" device page. Define a YAML anchor (&device_name) once, and inject it into every sensor.

.wican_vehicle_def: &f350_device
  identifiers:
    - "wican_pro_f350"
  name: "Ford F-350"
  model: "Super Duty"
  manufacturer: "Ford"

mqtt:
  sensor:
    - name: "Engine RPM"
      state_topic: "homeassistant/wican/f350/pcm_engine_rpm"
      device: *f350_device  # <--- Automatically groups this sensor to the truck

2.Defining Rich Metadata for Binary Sensors

Take full advantage of Home Assistant's built-in entity customization. By defining specific metadata—like setting a binary_sensor's device_class to problem—Home Assistant will automatically colorize the icon in your dashboard and log it appropriately without you writing any custom dashboard code.

You can also firmly lock in the backend name using default_entity_id.

mqtt:
  binary_sensor:
    - name: "F-350 SS Inhibit: Batt Volts Low"
      default_entity_id: "binary_sensor.f350_ss_inhibit_batt_volts_low"
      unique_id: "f350_ss_inhibit_batt_volts_low"
      state_topic: "homeassistant/wican/f350/bcm_slow_start_stop_inhibit"
      icon: "mdi:battery-outline"
      device_class: problem        
      value_template: >
        {% set raw_val = value_json["Start Stop Inhibit Bitmap"] if value_json is defined else value %}
        {{ 'ON' if (raw_val | int(0) | bitwise_and(8)) > 0 else 'OFF' }}
      device: *f350_device

3. Decoding Bitmaps (Multiple States in One Message)

Vehicle modules often use Bitmaps to send multiple true/false statuses in a single byte (e.g., Remote Start Failure reasons, where Bit 0 is "Hood Open" and Bit 1 is "Not in Park").

Use Jinja2's bitwise_and filter to extract multiple active states and combine them into a clean, comma-separated list.

- name: "Remote Start Failure Reasons"
      state_topic: "homeassistant/wican/f350/bcm_remote_start_failures"
      value_template: >
        {% set raw_val = value | int %}
        {% set result = namespace(reasons=[]) %}
        {% set bitmask = {
          128: 'Alarm Triggered',
          32: 'Hood Open',
          16: 'Ignition Not Off',
          1: 'Vehicle Not In Park'
        } %}
        {% for mask, text in bitmask.items() %}
          {% if raw_val | bitwise_and(mask) %}
            {% set result.reasons = result.reasons + [text] %}
          {% endif %}
        {% endfor %}
        {{ result.reasons | join(', ') if result.reasons else 'None' }}

4. Bulletproof Raw Hex Parsing

If WiCAN sends a long string of Hex data (like 07 62 41 B8 08), spaces and formatting can easily break standard text slicing. Use regex_findall to cleanly extract the hex pairs into a perfect array.

value_template: >
        {# Strips all formatting and creates an array of 2-character hex pairs #}
        {% set h = value | regex_findall('[A-Fa-f0-9]{2}') %}
        
        {# Grabs the 5th byte, converts from hex to integer, and does the math #}
        {{ ((h[4] | int(base=16)) * 0.05) | round(1) }}

5. Use YAML Anchors for Repeating Sensors (Like TPMS)

If you have 4 tires sending identical 19-byte hex strings, do not write the decoding math 4 separate times. Write it once as an anchor (&tpms_pressure), and reuse it to keep your code DRY (Don't Repeat Yourself).

Define the template once

    - <<: &tpms_pressure
        unit_of_measurement: "PSI"
        value_template: >
          {% set h = value | regex_findall('[A-Fa-f0-9]{38,}') | first %}
          {{ ((h[16:20]|int(base=16)) * 0.05) | round(1) }}
      name: "Tire 1 Pressure"
      state_topic: "homeassistant/wican/f350/evt1_raw"

    # Reuse it infinitely 
    - <<: *tpms_pressure
      name: "Tire 2 Pressure"
      state_topic: "homeassistant/wican/f350/evt2_raw"

[Merwases]

Thanks, but sorry, I just understand less than 10%... sorry.

My problem is, the are no date shown at mqtt explorer, but the Wican integration at HA is getting close to live data as soon as car awakes.

I want to use the SOC (Ioniq5) shown by Wican integration at HA (and Wican Pro software shown too) to send SOC to Evcc (PV Charging). But without even a single data at mqtt explorer, no chance so far.

I use:
Wican Pro with newest FW 4.49.beta.03 and connected to HA by http. (see screens at the bottom).

I stuck at many points after trying hard, still getting all data shown at HA/Wican Integration sensors, but never any traffic or even listed wican thing at the mqtt explorer at HA.

I think its a problem with http webhook enabled AND someting blocking mqtt from wican integration to HA, resulting to not publishing any data through mqtt and so nothing shows up at mqtt explorer, but everything at wican integration at HA even close to live data.

I add some Screens of my wican pro setup concerning mqtt and HA connection and add it here to show what words can't explain 😘 .

For instance:
mqtt_topic destination is just ??? to me, as anything I put in there, throws just connection fails 🤷🏼‍♂️ . Even mentioned "cert"... at the small lettered info ???

A really step by step guide/manual about all this special stuff may be helpfull to any semi-noob like me.
So any help is welcome.

I want to get a lokal access to the Ioniq5 SOC, as the refresh token generation necessary to get the SOC is a pain all 180 days again now not just to me... and being "chained" by manufrakturers good will, a growing problem in future.

[wambs]

You don't need webhooks if you plan on using MQTT only. webbook sends direct http formatted PID data to home assistant. set your type: to MQTT_TOPIC for each PID. and set the dest: to your home assistant MQTT msg path, e.g., homeassistant/wican/f350/tcm_gear_raw).

[werner2000x]

can I read the sensor data from an radar or ultrasonic sensor to get the distances in my bmw ix

[GaupeLnx]

i think you mix up two different ways how to get data in to home assistant.

1. via mqtt. (which is described here by in this topic by Wambs)
   In that case an mqtt topic is sent to home assistant and in home assistant you have to creatre sensors
   to make the topics sent via mqtt visible and do everything yourself.
   Some people (like me ) prefer that method as it gives you more freedom

2 Via webhooks and the home assistant integration of jay oswald
https://github.com/[jay-oswald/ha-wican](https://github.com/jay-oswald/ha-wican)
In that case you set up a webkook and install the integration on home assistant
I cant tell you how that works but it should be explained in the link above

Anyway it one or the other, im not sure if its possible to do both but i guess you dont want that.

[WatersPaul]

I was trying to connect the WICAN to my F550 with an OBD2 splitter and the Banks gauges connected. Once I disconnected the Banks, I was able to get it to work. I connect Banks back up, and it does not work. I guess I have a conflict with Banks. I tried to put the WICAN in Silent mode, but it does not seem to help.

Any ideas how to get around this conflict?

[wambs]

I think only one device can control the bus at one time. So, either Bank passive, wican active or wican passive, banks active. If passive, it can only listen, not command for pID data.

…

On Mon, Jul 13, 2026 at 7:31 PM WatersPaul ***@***.***> wrote: I was trying to connect the WICAN to my F550 with an OBD2 splitter and the Banks gauges connected. Once I disconnected the Banks, I was able to get it to work. I connect Banks back up, and it does not work. I guess I have a conflict with Banks. I tried to put the WICAN in Silent mode, but it does not seem to help. Any ideas how to get around this conflict? — Reply to this email directly, view it on GitHub <#728?email_source=notifications&email_token=ADH3ULDLZ46HNL5VV6RGPWD5EV5OTA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZWGI4TCMBRUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-17629101>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADH3ULDYUSBQ6QFINBLN7AT5EV5OTAVCNFSNUABHKJSXA33TNF2G64TZHM2DMMJYGMZDGMJTHNCGS43DOVZXG2LPNY5TSOBRGQYTMONBOYBA> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/ADH3ULDS4Q7U5LRVUBHOPIT5EV5OTA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZWGI4TCMBRUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVJTG633UMVZF62LPOM> and Android <https://github.com/notifications/mobile/android/ADH3ULF4EVODAVRH3TREPML5EV5OTA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZWGI4TCMBRUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[WatersPaul]

I thought I had the Wican Pro in passive mode. The instructions are a little different than the setting for the Wiccan pro. The options are Normal or Silent. I have the Wican Pro set to Silent

[wambs]

These instructions are much better than the stock firmware: https://wambs.github.io/wican-fw/

…

On Wed, Jul 15, 2026 at 11:22 AM WatersPaul ***@***.***> wrote: I thought I had the Wican Pro in passive mode. The instructions are a little different than the setting for the Wiccan pro. The options are Normal or Silent. I have the Wican Pro set to Silent — Reply to this email directly, view it on GitHub <#728?email_source=notifications&email_token=ADH3ULC24AEGXJ3W4RAU6EL5E6VUVA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZWGUYTENJXUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-17651257>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADH3ULEXVLRU3REM4MIDYY35E6VUVAVCNFSNUABHKJSXA33TNF2G64TZHM2DMMJYGMZDGMJTHNCGS43DOVZXG2LPNY5TSOBRGQYTMONBOYBA> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/ADH3ULGTG5WWBHMKGW6PSA35E6VUVA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZWGUYTENJXUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVJTG633UMVZF62LPOM> and Android <https://github.com/notifications/mobile/android/ADH3ULB5OHA2Q2XVXVVDQPL5E6VUVA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZWGUYTENJXUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[WatersPaul]

Thanks for the new link, the instruction there are more what I needed. I have the Wican set to Silent like it says but it still can not read when the Banks is plugged in. Any suggestions? Do I need to use the custom PIDs setting? At this point I just want to get engine RPM