Documentation

MQTT & Home Assistant Integration Guide

Comprehensive setup, architecture, security, and automation reference for Drive Assist on Geely EX2 / Geometry E (IHU629G).

Drive Assist features an integrated MQTT engine that connects your vehicle directly to Home Assistant (or any standard MQTT broker). It streams rich vehicle telemetry, publishes Home Assistant Auto-Discovery definitions, provides remote control commands, and allows Home Assistant to push dynamic context panels directly to the car’s screen.

🏗️ Architecture & Topics Schema

Device Naming & Topic Structure

All topics follow a predictable structure based on your vehicle’s partial VIN (the last 6 characters of sys.ecarx.vin, e.g., 123456):

Base Topic: drivemem/<vin> (e.g. drivemem/123456)
Client ID: driveassist-<vin> (e.g. driveassist-123456)
Device ID in Home Assistant: drivemem_<vin> (e.g. drivemem_123456)
Device Name: Geely EX2 (<vin>)

flowchart LR
    subgraph CAR["Geely IHU (Drive Assist)"]
        PUB["Telemetry Publisher"]
        SUB["Command Subscriber"]
        PANEL["Context Panel UI"]
        GATE["Garage Gate Button"]
    end

    subgraph BROKER["MQTT Broker (Mosquitto)"]
        T_STATE["drivemem/<vin>/state"]
        T_TRACKER["drivemem/<vin>/tracker/attributes"]
        T_AVAIL["drivemem/<vin>/available (LWT)"]
        T_CMD["drivemem/<vin>/+/set"]
        T_PANEL["drivemem/<vin>/panel"]
        T_GATE_AVAIL["drivemem/<vin>/gate/available"]
        T_GATE_TOGGLE["drivemem/<vin>/gate/toggle"]
        T_GATE_STATE["drivemem/<vin>/gate/state"]
        T_GATE_REFRESH["drivemem/<vin>/gate/refresh_request"]
    end

    subgraph HA["Home Assistant"]
        CORE["HA Core Entities"]
        AUTO["Automations & Scripts"]
        DASH["Lovelace Dashboard"]
    end

    PUB -->|10s Telemetry| T_STATE
    PUB -->|GPS Coordinates| T_TRACKER
    PUB -->|Online / Offline| T_AVAIL
    T_CMD -->|Execute action| SUB

    T_STATE & T_TRACKER & T_AVAIL --> CORE
    CORE --> DASH
    AUTO -->|Remote Actions| T_CMD
    AUTO -->|Push HTML card| T_PANEL
    T_PANEL --> PANEL

    AUTO -->|Retained 'online'| T_GATE_AVAIL
    T_GATE_AVAIL --> GATE
    GATE -->|QoS 1 toggle| T_GATE_TOGGLE
    T_GATE_TOGGLE --> AUTO
    AUTO -->|Cover state label| T_GATE_STATE
    T_GATE_STATE --> GATE
    GATE -->|On every (re)connect| T_GATE_REFRESH
    T_GATE_REFRESH -->|Re-check now, answer fresh| AUTO

⚙️ Configuration in Drive Assist

Open Settings on the car’s screen and select the MQTT tab.

1. Security & Master Toggles (Top Card)

Habilitar telemetria MQTT: Master switch. When disabled, shuts down the background telemetry service, closes network sockets, and collapses the configuration UI.
Aceitar comandos do HA: Security override. When disabled, incoming MQTT commands (climate steps, charging on/off, charge current limits, parking mode) are strictly rejected. Only telemetry upload is permitted.

2. Left Column: Broker Settings & Authentication

Endereços (Hosts): Enter your MQTT broker URL(s), one per line. Multiple lines provide automatic fallback.
```
tls://homeassistant.example.com:8883
tcp://<broker-ip>:1883
```
- tls:// or ssl://: Encrypted connection (port 8883 recommended).
- tcp://: Plain unencrypted connection (port 1883, only for trusted home LAN).
Usuário & Senha: Broker credentials (e.g. your Home Assistant MQTT user).
Intervalo de Envio: Telemetry reporting interval in seconds (default: 10 seconds; minimum: 5 seconds).
Salvar Configurações: Atomically saves all fields, reconfigures the service, and reconnects in the background.

3. Right Column: Monitor, Actions & Live Console

Status Card: Displays active broker URL, client identifier, and the timestamp of the last successful transmission.
[ Testar Conexão ]: Sends an immediate on-demand telemetry sample, verifying network routing, authentication, and broker ACK.
[ Descoberta MQTT ]: Re-publishes the full set of 40+ Home Assistant auto-discovery configs.
Console de Feedback: Real-time monospace terminal displaying:
- Connection handshakes and TLS cipher details
- Topics published and PUBACK confirmations
- Incoming command executions
- Socket errors or connection refusal details

🔐 TLS & Mutual TLS (mTLS) Configuration

Drive Assist supports enterprise-grade mTLS (Mutual TLS) authentication where both the car and the broker present cryptographic certificates.

Why use mTLS?

Zero Credential Exposure: No passwords transmitted over cellular or public Wi-Fi.
Strict Identity: Only devices possessing a valid client certificate signed by your Private CA can connect.
End-to-End Encryption: Protects vehicle GPS coordinates and status from sniffing on public networks.

Certificates & TLS Card Options

Located inside the MQTT configuration tab:

Certificado Cliente (mTLS):
- Requires a PKCS#12 bundle (.p12 or .pfx) containing the client certificate, private key, and password.
- Tap Importar and select the .p12 file from storage or USB drive.
- Enter the PKCS#12 password when prompted. Drive Assist will install it into the app’s private secure keystore.
Certificado CA (Servidor):
- For self-signed certificates or private CAs (e.g. Let’s Encrypt / Step CA / OpenSSL CA).
- Import your CA certificate (.crt, .cer, or .pem).
- Tap Restaurar to return to standard Android system trust roots.
Testar Handshake TLS:
- Enter your TLS broker target in the field (e.g. ssl://homeassistant.example.com:8883).
- Tap Testar Handshake TLS to perform an immediate socket handshake with full SNI validation without changing your running config.

📡 Home Assistant Auto-Discovery Entities

When connected, Drive Assist automatically creates a device named Geely EX2 (<vin>) under Settings → Devices & Services → MQTT.

Entities Created

1. Sensors (`sensor`)

2. Binary Sensors (`binary_sensor`)

3. Switches (`switch`)

4. Numbers & Selects (`number` / `select`)

5. Buttons (`button`)

6. Device Tracker (`device_tracker`)

💡 Practical Home Assistant Automations

Here are real-world automations tailored to Drive Assist:

1. Smart Garage Door Toggle (Comfort Screen Button)

The car’s Comfort screen features a dynamic garage gate button. The button only displays when Home Assistant tells the car it is near home:

- id: 'car_gate_available_when_near'
  alias: "Car — Gate available when near home"
  triggers:
    - trigger: zone.entered
      target:
        entity_id: device_tracker.geely_ex2_123456_localizacao
      zone: zone.home
    - trigger: state
      entity_id: sensor.geely_ex2_123456_marcha
  conditions:
    - condition: zone
      entity_id: device_tracker.geely_ex2_123456_localizacao
      zone: zone.home
  actions:
    - action: mqtt.publish
      data:
        topic: drivemem/123456/gate/available
        retain: true
        payload: online

- id: 'car_gate_toggle_trigger'
  alias: "Car — Open garage on car button press"
  triggers:
    - trigger: mqtt
      topic: drivemem/123456/gate/toggle
  conditions:
    - condition: zone.in_zone
      target:
        entity_id: device_tracker.geely_ex2_123456_localizacao
      zone: zone.home
  actions:
    - action: cover.open_cover
      target:
        entity_id: cover.garage_door

- id: 'car_gate_state_mirror'
  alias: "Car — Sync garage door state label"
  triggers:
    - trigger: state
      entity_id: cover.garage_door
    - trigger: mqtt
      topic: drivemem/123456/available
  actions:
    - action: mqtt.publish
      data:
        topic: drivemem/123456/gate/state
        retain: true
        payload: ""

- id: 'car_gate_hide_when_leaving'
  alias: "Car — Hide gate button when away"
  triggers:
    - trigger: zone.left
      target:
        entity_id: device_tracker.geely_ex2_123456_localizacao
      zone: zone.home
  actions:
    - action: mqtt.publish
      data:
        topic: drivemem/123456/gate/available
        retain: true
        payload: offline

- id: 'car_gate_refresh_on_request'
  alias: "Car — Answer gate availability on request"
  # The car deliberately does NOT trust the retained value it gets from a
  # fresh subscribe (see MqttReporter's GATE_REFRESH_TOPIC comment) — it
  # will not grant itself gate access off a cached belief about its own
  # location, only an answer HA gives right now. The two automations above
  # only republish on a zone enter/leave or a gear change, so a car sitting
  # at home through a WiFi blip, an HA restart, or anything else that drops
  # the MQTT connection can stay stuck with no button showing, even though
  # the correct answer never actually changed. The car publishes to this
  # topic once, every time it (re)connects; this automation re-checks the
  # real condition right now and answers fresh, closing that gap without
  # weakening the trust rule.
  triggers:
    - trigger: mqtt
      topic: drivemem/123456/gate/refresh_request
  actions:
    - choose:
        - conditions:
            - condition: zone.in_zone
              target:
                entity_id: device_tracker.geely_ex2_123456_localizacao
              zone: zone.home
          sequence:
            - action: mqtt.publish
              data:
                topic: drivemem/123456/gate/available
                retain: true
                payload: online
      default:
        - action: mqtt.publish
          data:
            topic: drivemem/123456/gate/available
            retain: true
            payload: offline

2. Context Panel: Pushing Dynamic HTML to the Car

Drive Assist reserves a dedicated card on the main screen subscribing to drivemem/<vin>/panel. Home Assistant can push live HTML, parking info, ferry lines, or alerts:

- id: 'car_push_parking_panel'
  alias: "Car — Push parking spots on arrival"
  triggers:
    - trigger: zone.entered
      entity_id: device_tracker.geely_ex2_123456_localizacao
      zone: zone.office
  actions:
    - action: mqtt.publish
      data:
        topic: drivemem/123456/panel
        retain: true
        payload: >
          <h1>Office Parking</h1>
          <p><span class="big"></span> spots free</p>
          <p>EV Chargers: <strong></strong> available</p>

🔍 Troubleshooting

Symptom	Cause	Solution
Status says “Desligado”	Master toggle is off	Enable Habilitar telemetria MQTT at the top of the MQTT tab.
“Connection refused”	Broker port is closed or firewall blocking	Verify broker IP and port (1883 for TCP, 8883 for TLS). Confirm Mosquitto listener allows remote clients (`bind_address 0.0.0.0`).
“SSLHandshakeException”	Certificate mismatch or untrusted CA	Verify broker hostname matches the certificate Common Name / SAN. If using self-signed certs, import your CA into the Certificados & TLS card.
Commands not responding	Security lock active	Ensure Aceitar comandos do HA is turned ON at the top of the MQTT tab.
Entities not showing in HA	Auto-discovery not received	Tap [ Descoberta MQTT ] in the right column of the MQTT tab to re-send discovery packets.