The Open Vehicle Monitoring System (OVMS) integration for Home Assistant. Connect your electric vehicle with Home Assistant via MQTT, automatically creating sensors for all vehicle metrics.
The OVMS integration discovers and creates Home Assistant entities from MQTT topics published by your OVMS module. The integration automatically:
- Identifies vehicle data and creates appropriate entity types (sensors, binary sensors, device trackers, switches)
- Categorizes entities by data type (battery, climate, location, etc.)
- Maintains entity state based on real-time MQTT updates
- Processes data for comprehensive metrics including statistics
- Provides services to send commands to your vehicle
- Automatic Discovery: Detects all metrics published by your OVMS module without manual configuration
- Entity Creation: Creates appropriate Home Assistant entities based on data type with intelligent state parsing
- Smart Categorization: Organizes entities into logical groups (battery, climate, location, etc.)
- Real-time Updates: Entities update as new data is published through MQTT
- Command Interface: Send commands to your vehicle through services with proper rate limiting
- Vehicle Status: Track online/offline status of your vehicle automatically
- Secure Communication: Supports TLS/SSL connections to MQTT brokers with certificate verification
- Vehicle-Specific Metrics: Special support for VW e-UP!, Smart ForTwo, and MG ZS-EV - with additional vehicle models planned
- Diagnostics Support: Provides detailed diagnostics for troubleshooting
- Flexible Topic Structure: Supports various MQTT topic structures including custom formats
- Multi-language Support: Includes translations for English, French, German, Spanish, and Swedish
- GPS Tracking: Advanced location tracking with accuracy estimation from signal quality
- Cell-level Battery Data: Processes and displays individual cell data with statistical analysis
- Command Rate Limiting: Prevents overwhelming the vehicle with too many commands
- Code Structure: Well-organized codebase with proper separation of concerns
- Error Handling: Comprehensive error handling with detailed logging
- Type Hints: Full Python type hinting for better code maintainability
- Security: SSL/TLS support, credential protection, and input validation
- Standards Compliance: Follows Home Assistant development guidelines
- Performance: Efficient MQTT message processing with minimal overhead
- Reliability: Connection recovery mechanisms with backoff strategy
- Testing: Automated validations via HACS and Hassfest
- Maintenance: Structured release process with version control
- Home Assistant (2025.2.5 or newer) according to HACS specification
- MQTT integration configured in Home Assistant
- OVMS module publishing to the same MQTT broker
- OVMS firmware 3.3.001 or newer recommended
- Python package: paho-mqtt>=1.6.1 (installed automatically)
Integration overview 1
Integration overview 2
All topics with a lot of metrics are stored in attributes instead, where the average and median are calculated and presented
Compared to using the OVMS V2 server, this integration will use more data since it's using the V3 server over MQTT. If you are concerned about data usage, this integration might not be for you. Below are real-life cellular data usage from a car with both V2 and V3 OVMS server activated.
Specifications of the car in the example:
- While parked at home: WIFI
- While parked at work: 4G
- Traveled to work: 22 times
- Duration of travel to work: 40 minutes per trip
The grah above are showing the usage over one month.
-
In Home Assistant go to HACS -> Integrations. Click on "+ Explore & Download Repositories" and search for "OVMS Home Assistant".
-
In Home Assistant go to Settings -> Devices & Services -> Integrations. Click on "+ Add integration" and search for "OVMS".
- Download the repository as a ZIP file and extract it
- Copy the
custom_components/ovmsfolder to your Home Assistant'scustom_componentsdirectory - Restart Home Assistant
Before using this integration, you need to configure your MQTT broker with the correct permissions:
The OVMS integration needs the following MQTT permissions:
Subscribe Permissions:
ovms/#- For all OVMS topics (replaceovmswith your chosen prefix if different)homeassistant/#- For testing connection during setup
Publish Permissions:
ovms/+/+/client/rr/command/#- For sending commands to the OVMS moduleovms/+/+/status- For publishing online/offline status
If you're using a broker with restrictive ACLs (like Mosquitto, EMQX, etc.), ensure your MQTT user has these permissions.
user ovms_user
topic read ovms/#
topic write ovms/+/+/client/rr/command/#
topic write ovms/+/+/status
Configure your OVMS module to publish data to your MQTT broker:
- In the OVMS web UI, go to Config → Server V3 (MQTT)
- Configure the following settings:
- Server: Your MQTT broker address
- Port:
- TCP Port: 1883 (mqtt://)
- WebSocket Port: 8083 (ws://)
- SSL/TLS Port: 8883 (mqtts://)
- Secure WebSocket Port: 8084 (wss://)
- Username/Password: If required by your broker
- Topic Prefix:
ovms(default, can be customized) - Enable Auto-Start: YES
- Go to Settings → Devices & Services → Add Integration
- Search for "OVMS" and select it
- Enter the MQTT broker details:
- MQTT Broker: Your broker address
- Port:
- TCP Port: 1883 (mqtt://)
- WebSocket Port: 8083 (ws://) - default
- SSL/TLS Port: 8883 (mqtts://)
- Secure WebSocket Port: 8084 (wss://)
- Username/Password: If required by your broker
- Configure topic structure:
- Topic Prefix: Should match your OVMS setting (default:
ovms) - MQTT Username: Username that OVMS uses in its topics
- Topic Prefix: Should match your OVMS setting (default:
- The integration will scan for available OVMS vehicles
- Select your vehicle ID when prompted
For testing purposes, you can:
-
Enable debug logging by adding to your
configuration.yaml:logger: default: info logs: custom_components.ovms: debug
-
Monitor MQTT messages using an external tool like MQTT Explorer to verify what your OVMS is publishing
-
Check the Home Assistant logs for detailed information about discovered topics and created entities
After setup, entities will be created for your vehicle metrics. These include:
- Battery: State of charge, range, power, voltage, etc.
- Climate: Temperature readings from various vehicle sensors
- Location: GPS position of the vehicle
- Status: Connection state, operational parameters
- Vehicle-specific: Other metrics specific to your vehicle model
Entities are grouped under a device representing your vehicle, identified by the vehicle ID.
The integration provides several services to interact with your vehicle:
Send any command to the OVMS module.
service: ovms.send_command
data:
vehicle_id: your_vehicle_id
command: stat
parameters: range
timeout: 10 # Optional timeout in secondsCould be done as a button in HA:
show_name: true
show_icon: true
type: button
tap_action:
action: perform-action
perform_action: ovms.send_command
target: {}
data:
timeout: 10
vehicle_id: REG123
command: server v3 update all
entity: input_button.ovms_update_all
hold_action:
action: none
name: "REG123: update all"
Example of how a command button could look like in the Lovelace UI
Set an OVMS configuration feature.
service: ovms.set_feature
data:
vehicle_id: your_vehicle_id
feature: feature_name
value: feature_valueControl the vehicle's climate system.
service: ovms.control_climate
data:
vehicle_id: your_vehicle_id
temperature: 21.5
hvac_mode: heat # Options: off, heat, cool, auto
duration: 30 # Duration in minutesControl the vehicle's charging functions.
service: ovms.control_charging
data:
vehicle_id: your_vehicle_id
action: start # Options: start, stop, status
mode: range # Options: standard, storage, range, performance
limit: 80 # Percentage limit for chargingThe integration provides a Homelink service that can trigger vehicle functions associated with Homelink buttons:
Activate a Homelink button on the OVMS module.
service: ovms.homelink
data:
vehicle_id: your_vehicle_id
button: 1 # Options: 1, 2, or 3Smart ForTwo-specific functionality: For Smart ForTwo vehicles, these buttons control climate functions:
- Button 1: 5 minute climate boost
- Button 2: 10 minute climate boost
- Button 3: 15 minute climate boost or 12V battery charging
This feature requires a battery State of Charge (SoC) greater than 30%.
Example Lovelace button configuration:
type: button
name: "5min Climate Boost"
icon: mdi:car-seat-heater
tap_action:
action: call-service
service: ovms.homelink
service_data:
vehicle_id: your_vehicle_id
button: 1Notification topics in Home Assistant are inherently transient, representing momentary events rather than persistent states. As a result, the associated sensors typically remain active for a limited period before transitioning to an unavailable status—this behavior is by design.
To maintain the state of notification topics and their corresponding sensors permanently, you can implement a template-based solution in Home Assistant. The following approach allows you to preserve the most recent state information:
template:
- sensor:
- name: "Preserved Notification State"
state: >
{% if is_state('sensor.original_notification_topic', 'unavailable') %}
{{ states('sensor.preserved_notification_state') }}
{% else %}
{{ states('sensor.original_notification_topic') }}
{% endif %}
availability: trueThis template creates a persistent sensor that:
- Retains the previous value when the original notification sensor becomes unavailable
- Updates with new information when the original notification sensor is active
- Remains continuously available regardless of the source sensor's status
When implementing this solution, you should:
- Replace
sensor.original_notification_topicwith the actual entity ID of your notification sensor - Consider adding appropriate attributes to preserve additional contextual information
- Potentially include timestamp information to track when the last valid notification occurred
This approach provides a robust mechanism for maintaining notification states beyond their typical lifecycle, enabling more consistent automation and reporting capabilities.
The integration supports these MQTT topic structures:
- Default:
ovms/username/vehicle_id/metric/... - Alternative:
ovms/client/vehicle_id/... - Simple:
ovms/vehicle_id/... - Custom: Define your own structure with placeholders
- OVMS module publishes metrics to MQTT broker
- Integration subscribes to all topics under the configured prefix
- Received messages are parsed to determine entity type and attributes
- Entities are created or updated based on the incoming data
- Commands are sent via MQTT and responses are tracked
The integration uses pattern matching and metric definitions to determine entity types:
- Metrics with temperature data become temperature sensors
- Location data becomes device trackers
- Binary states (on/off, connected/disconnected) become binary sensors
- Numeric values become standard sensors
- Array data (like cell voltages) is processed with statistical analysis
Commands use a request-response pattern:
- Command is published to:
{prefix}/{username}/{vehicle_id}/client/rr/command/{command_id} - Response is received on:
{prefix}/{username}/{vehicle_id}/client/rr/response/{command_id} - Unique command IDs ensure responses are matched to requests
You can for example use the developer tool in Home Assistant to update all the metrics at once with this command:
The integration includes sophisticated data processing:
- Auto-detection of data types and units
- Extraction of statistics from array data (min, max, average, median)
- Conversion between different units based on user preferences
- JSON payload parsing for complex data structures
- GPS accuracy calculation from quality metrics
- TLS/SSL Support: Secure encrypted connections to MQTT broker
- Certificate Verification: Option to verify SSL certificates (enabled by default)
- Rate Limiting: Command limiting to prevent overwhelming the vehicle (5 per minute by default)
- Input Validation: Comprehensive validation of all inputs
- MQTT ACL: Detailed guidance for restrictive MQTT permissions
Warning! The debug output is substantial. It may fill your disk if you are not careful, don't leave it turned on.
- Check if your OVMS module is publishing to the MQTT broker
- Verify the topic structure matches what's configured in the integration
- Enable debug logging and check for errors in the Home Assistant logs
- Ensure your MQTT broker allows wildcard subscriptions (#)
- Verify ACL permissions in your MQTT broker for the topics listed above
- Verify MQTT broker credentials are correct
- Check if TLS/SSL settings match between OVMS, Home Assistant, and the broker
- Test connection using an external MQTT client
- Check firewall rules if using different networks
- Ensure the OVMS module is online
- Check if the command syntax is correct for your vehicle
- Verify MQTT QoS settings allow reliable message delivery
- Look for command responses in the logs
If your OVMS uses a non-standard topic structure, you can define a custom pattern during setup using these placeholders:
{prefix}: The base MQTT topic prefix{mqtt_username}: The username portion of the topic{vehicle_id}: The vehicle identifier
Here's an example card configuration for a vehicle dashboard:
type: vertical-stack
cards:
- type: entities
title: Vehicle Status
entities:
- entity: sensor.ovms_v_b_soc
name: Battery
- entity: sensor.ovms_v_b_range_est
name: Range
- entity: sensor.ovms_v_c_charging
name: Charging
- entity: sensor.ovms_v_p_odometer
name: Odometer
- type: map
entities:
- entity: device_tracker.ovms_locationThe OVMS integration follows these development principles:
- Modular Architecture: Separation of concerns with dedicated modules for specific functions
- Comprehensive Logging: Detailed logging for troubleshooting at various levels
- Consistent Formatting: Code formatted with Black and checked with Pylint
- Automated Testing: CI/CD pipeline with GitHub Actions for validation
- Release Management: Structured release process with semantic versioning
- Documentation: Extensive inline documentation and comments
This integration undergoes regular validation through:
- HACS compatibility checking
- Hassfest validation for Home Assistant standards
- Python code validation and linting
- Version checking and dependency management
Q: Can I use multiple vehicles with this integration?
A: Yes, you can set up multiple instances of the integration, one for each vehicle.
Q: Does this work with all OVMS-supported vehicles?
A: Yes, the integration is vehicle-agnostic and works with any vehicle supported by OVMS. Vehicle-specific enhancements are provided for some models like VW e-UP!, Smart ForTwo, and MG ZS-EV.
Q: Can I use this without internet access?
A: Yes, as long as your OVMS module, MQTT broker, and Home Assistant can communicate on the same network.
Q: How frequent are the updates?
A: Updates happen in real-time as the OVMS module publishes new data, typically every few seconds while the vehicle is active.
Q: How does the integration handle connectivity issues?
A: The integration includes automatic reconnection with exponential backoff, online/offline status tracking, and will resume normal operation when connection is restored.
Q: Is my data secure?
A: Yes, the integration supports TLS/SSL encryption for MQTT connections and follows secure coding practices for handling sensitive data.
Contributions to the OVMS Home Assistant integration are welcome! Whether it's bug reports, feature requests, documentation improvements, or code contributions.
To contribute:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
Please ensure your code follows the existing style conventions and includes appropriate tests and documentation.
MIT License - see LICENSE file
This integration is not officially affiliated with the Open Vehicles project, yet.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
![@github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=64&v=4){kind=small}