` with correct corresponding values.
```
/* Detailed source-code truncated for AI context efficiency. */
```
### ui-lovelace.yaml
The below is the Lovelace UI configuration used to make the example screenshot above. You will obviously want to configure this to your liking, however the example contains all of the sensors and values presented via MQTT and could be used as the basis of UI configuration.
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Useful Automations
The below automations leverage TeslaMate MQTT topics to provide some useful automations
### Garage Door Automation based on Tesla location
This automation triggers when the Tesla transitions from not_home to home. This means that the vehicle would have had to have been outside of the home zone previously, and returned home. You may want to add conditions here to improve accuracy, such as time of day.
```yml title="automation.yaml"
- alias: Open garage if car returns home
initial_state: on
trigger:
- platform: state
entity_id: device_tracker.tesla_location
from: "not_home"
to: "home"
action:
- service: switch.turn_on
entity_id: switch.garage_door_switch
```
### Notification for Doors and Windows left open
The following set of automations and scripts will detect when a Tesla door, frunk, trunk or window is left open. The script will notify you after the defined time period (by default, 5 minutes). If you would like to customize how the notification is performed, you can edit the `notify_tesla_open` script which is called by all of the four notifications.
By default, the script will repeatedly notify every 5 minutes. Remove the recursive `script.turn_on` sequence in the `notify_tesla_open` script if you'd only like to be informed once.
We add the random 30 second interval after each notification to avoid clobbering the notification script when we have multiple things open at once.
For example, opening the door will open the door and the window. If we don't delay the calls, we will only get a message about the window (as it is the last call to the script) and if we then close the window, we won't get notifications about other things left open. This results in more notifications but less chance on missing out on knowing something was left open.
#### automation.yaml
```yml title="automation.yaml"
- alias: Set timer if TeslaMate reports something is open to alert us
initial_state: on
trigger:
- platform: mqtt
topic: teslamate/cars/1/windows_open
payload: "true"
- platform: mqtt
topic: teslamate/cars/1/doors_open
payload: "true"
- platform: mqtt
topic: teslamate/cars/1/trunk_open
payload: "true"
- platform: mqtt
topic: teslamate/cars/1/frunk_open
payload: "true"
action:
- service: script.turn_on
data_template:
entity_id: script.notify_tesla_{{trigger.topic.split('/')[3]}}
- alias: Cancel notification if said door/window is closed
initial_state: on
trigger:
- platform: mqtt
topic: teslamate/cars/1/windows_open
payload: "false"
- platform: mqtt
topic: teslamate/cars/1/doors_open
payload: "false"
- platform: mqtt
topic: teslamate/cars/1/trunk_open
payload: "false"
- platform: mqtt
topic: teslamate/cars/1/frunk_open
payload: "false"
action:
- service: script.turn_off
data_template:
entity_id: script.notify_tesla_{{trigger.topic.split('/')[3]}}
```
#### script.yaml
```
/* Detailed source-code truncated for AI context efficiency. */
```
---
### Integrations Mqtt (`website/docs/integrations/mqtt.md`)
---
title: MQTT Integration
sidebar_label: MQTT
---
The MQTT function within TeslaMate allows useful values to be published to an MQTT broker. This is useful in allowing other automation platforms to consume data from TeslaMate.
## MQTT Topics
Vehicle data will be published to the following topics:
| Topic | Example | Description |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `teslamate/cars/$car_id/display_name` | Blue Thunder | Vehicle Name |
| `teslamate/cars/$car_id/state` | asleep | Status of the vehicle (e.g. `online`, `asleep`, `charging`) |
| `teslamate/cars/$car_id/since` | 2019-02-29T23:00:07Z | Date of the last status change |
| `teslamate/cars/$car_id/healthy` | true | Health status of the logger for that vehicle |
| `teslamate/cars/$car_id/version` | 2019.32.12.2 | Software Version |
| `teslamate/cars/$car_id/update_available` | false | Indicates if a software update is available |
| `teslamate/cars/$car_id/update_version` | 2019.32.12.3 | Software version of the available update |
| `teslamate/cars/$car_id/download_perc` | 100 | Download progress of the available update in percent |
| `teslamate/cars/$car_id/install_perc` | 42 | Installation progress of the update in percent |
| | | |
| `teslamate/cars/$car_id/model` | 3 | Either "S", "3", "X" or "Y" |
| `teslamate/cars/$car_id/trim_badging` | P100D | Trim badging |
| `teslamate/cars/$car_id/exterior_color` | DeepBlue | The exterior color |
| `teslamate/cars/$car_id/wheel_type` | Pinwheel18 | The wheel type |
| `teslamate/cars/$car_id/spoiler_type` | None | The spoiler type |
| | | |
| `teslamate/cars/$car_id/geofence` | 🏡 Home | The name of the Geo-fence, if one exists at the current position |
| | | |
| `teslamate/cars/$car_id/latitude` | 35.278131 | DEPRECATED: Last reported car latitude |
| `teslamate/cars/$car_id/longitude` | 29.744801 | DEPRECATED: Last reported car longitude |
| `teslamate/cars/$car_id/location` | \{
"latitude": 35.278131,
"longitude": 29.744801
\} | Last reported car location (json blob) |
| `teslamate/cars/$car_id/shift_state` | D | Current/Last Shift State (D/N/R/P) |
| `teslamate/cars/$car_id/power` | -9 | Current battery power in watts. Positive value on discharge, negative value on charge |
| `teslamate/cars/$car_id/speed` | 12 | Current Speed in km/h |
| `teslamate/cars/$car_id/heading` | 340 | Last reported car direction |
| `teslamate/cars/$car_id/elevation` | 70 | Current elevation above sea level in meters |
| | | |
| `teslamate/cars/$car_id/locked` | true | Indicates if the car is locked |
| `teslamate/cars/$car_id/sentry_mode` | false | Indicates if Sentry Mode is active |
| `teslamate/cars/$car_id/windows_open` | false | Indicates if any of the windows are open |
| `teslamate/cars/$car_id/driver_front_window_open` | false | Indicates if the driver-side front window is open |
| `teslamate/cars/$car_id/driver_rear_window_open` | false | Indicates if the driver-side rear window is open |
| `teslamate/cars/$car_id/passenger_front_window_open` | false | Indicates if the passenger-side front window is open |
| `teslamate/cars/$car_id/passenger_rear_window_open` | false | Indicates if the passenger-side rear window is open |
| `teslamate/cars/$car_id/doors_open` | false | Indicates if any of the doors are open |
| `teslamate/cars/$car_id/driver_front_door_open` | false | Indicates if the driver-side front door is open |
| `teslamate/cars/$car_id/driver_rear_door_open` | false | Indicates if the driver-side rear door is open |
| `teslamate/cars/$car_id/passenger_front_door_open` | false | Indicates if the passenger-side front door is open |
| `teslamate/cars/$car_id/passenger_rear_door_open` | false | Indicates if the passenger-side rear door is open |
| `teslamate/cars/$car_id/sun_roof_state` | open | Current sunroof state |
| `teslamate/cars/$car_id/sun_roof_installed` | true | Indicates if the vehicle has a sunroof |
| `teslamate/cars/$car_id/sun_roof_percent_open` | 80 | Current sunroof open percentage |
| `teslamate/cars/$car_id/trunk_open` | false | Indicates if the trunk is open |
| `teslamate/cars/$car_id/frunk_open` | false | Indicates if the frunk is open |
| `teslamate/cars/$car_id/is_user_present` | false | Indicates if a user is present in the vehicle |
| | | |
| `teslamate/cars/$car_id/is_climate_on` | true | Indicates if the climate control is on |
| `teslamate/cars/$car_id/inside_temp` | 20.8 | Inside Temperature in °C |
| `teslamate/cars/$car_id/outside_temp` | 18.4 | Temperature in °C |
| `teslamate/cars/$car_id/is_preconditioning` | false | Indicates if the vehicle is being preconditioned |
| | | |
| `teslamate/cars/$car_id/odometer` | 1653 | Car odometer in km |
| `teslamate/cars/$car_id/est_battery_range_km` | 372.5 | Estimated Range in km |
| `teslamate/cars/$car_id/rated_battery_range_km` | 401.63 | Rated Range in km |
| `teslamate/cars/$car_id/ideal_battery_range_km` | 335.79 | Ideal Range in km |
| | | |
| `teslamate/cars/$car_id/battery_level` | 88 | Battery Level Percentage |
| `teslamate/cars/$car_id/usable_battery_level` | 85 | Usable battery level percentage |
| `teslamate/cars/$car_id/plugged_in` | true | If car is currently plugged into a charger |
| `teslamate/cars/$car_id/charging_state` | Charging | The cars charging state (Charging, Disconnected, Stopped, NoPower, Complete) |
| `teslamate/cars/$car_id/charge_energy_added` | 5.06 | Last added energy in kWh |
| `teslamate/cars/$car_id/charge_limit_soc` | 90 | Charge Limit Configured in Percentage |
| `teslamate/cars/$car_id/charge_port_door_open` | true | Indicates if the charger door is open |
| `teslamate/cars/$car_id/charger_actual_current` | 2.05 | Current amperage supplied by charger |
| `teslamate/cars/$car_id/charger_phases` | 3 | Number of charger power phases (1-3) |
| `teslamate/cars/$car_id/charger_power` | 48.9 | Charger Power |
| `teslamate/cars/$car_id/charger_voltage` | 240 | Charger Voltage |
| `teslamate/cars/$car_id/charge_current_request` | 40 | How many amps the car wants |
| `teslamate/cars/$car_id/charge_current_request_max` | 40 | How many amps the car can have |
| `teslamate/cars/$car_id/scheduled_charging_start_time` | 2019-02-29T23:00:07Z | Start time of the scheduled charge |
| `teslamate/cars/$car_id/time_to_full_charge` | 1.83 | Hours remaining to full charge |
| `teslamate/cars/$car_id/tpms_pressure_fl` | 2.9 | Tire pressure measure in BAR, front left tire |
| `teslamate/cars/$car_id/tpms_pressure_fr` | 2.8 | Tire pressure measure in BAR, front right tire |
| `teslamate/cars/$car_id/tpms_pressure_rl` | 2.9 | Tire pressure measure in BAR, rear left tire |
| `teslamate/cars/$car_id/tpms_pressure_rr` | 2.8 | Tire pressure measure in BAR, rear right tire |
| `teslamate/cars/$car_id/tpms_soft_warning_fl` | true | Indicates if the Tire pressure measure is soft warning, front left tire |
| `teslamate/cars/$car_id/tpms_soft_warning_fr` | false | Indicates if the Tire pressure measure is soft warning, front right tire |
| `teslamate/cars/$car_id/tpms_soft_warning_rl` | false | Indicates if the Tire pressure measure is soft warning, rear left tire |
| `teslamate/cars/$car_id/tpms_soft_warning_rr` | false | Indicates if the Tire pressure measure is soft warning, rear right tire |
| `teslamate/cars/$car_id/active_route_destination` | Home | DEPRECATED: Navigation destination name (or "nil") |
| `teslamate/cars/$car_id/active_route_latitude` | 35.278131 | DEPRECATED: Navigation destination latitude (or "nil") |
| `teslamate/cars/$car_id/active_route_longitude` | 29.744801 | DEPRECATED: Navigation destination longitude (or "nil") |
| `teslamate/cars/$car_id/active_route` | _See below_ | Navigation details (json blob) |
| `teslamate/cars/$car_id/center_display_state` | 0 | Center Display State |
| `teslamate/cars/$car_id/service_mode` | false | Whether Service Mode is active or not |
:::note
`$car_id` usually starts at 1
:::
:::note
A topic is published empty when the car reports no value for it, e.g. `speed` and `shift_state` while the car is switched off; `location` is never published empty. A topic the car has not reported since TeslaMate started is not published, so its retained value stays. While TeslaMate runs, the `odometer` never decreases and is never published empty.
:::
### `active_route` payload examples
Routing to a destination.
```json
{
"destination": "Home",
"energy_at_arrival": 73,
"miles_to_arrival": 6.485299,
"minutes_to_arrival": 23.466667,
"traffic_minutes_delay": 0.0,
"location": {
"latitude": 35.278131,
"longitude": 29.744801
},
"error": null
}
```
Not routing to a destination.
```json
{
"error": "No active route available"
}
```
---
### Maintenance Backup (`website/docs/maintenance/backup.mdx`)
---
title: Backup
sidebar_label: Backup
---
:::warning
**For better protection, the created backup should be transferred off the host to an independent storage location, ensuring it cannot be overwritten or lost in the event of a host failure.**
:::
:::note
If you are using `docker-compose`, you are using Docker Compose v1, which has been deprecated. Docker Compose commands refer to Docker Compose v2. Consider upgrading your docker setup, see [Migrate to Compose V2](https://docs.docker.com/compose/migrate/)
:::
## Backup
Create backup file `teslamate.bck`:
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
```bash
docker compose exec -T database pg_dump -U teslamate teslamate > ./teslamate.bck
```
:::note
`-T` is important if you add this line a crontab or the backup will not work because docker will generate this error `the input device is not a TTY`
:::
:::note
Be absolutely certain to move the `teslamate.bck` file to another safe location, as you may lose that backup file if you use a docker-compose GUI to upgrade your teslamate configuration. Some GUIs delete the folder that holds the `docker-compose.yml` when updating.
:::
:::note
If you get the error `No such service: database`, update your _docker-compose.yml_ or use `db` instead of `database` in the above command.
:::
:::note
If you changed `TM_DB_USER` in the .env file from one of the advanced guides, make sure to replace the first instance of `teslamate` to the value of `TM_DB_USER` in the above command.
:::
You can use the idiomatic backup script:
```bash
teslamate-backup teslamate_$(date +%Y%m%d-%H%M).bck
```
---
### Maintenance Manually Fixing Data (`website/docs/maintenance/manually_fixing_data.mdx`)
---
title: Manually fixing data
---
:::note
If you are using `docker-compose`, you are using Docker Compose v1, which has been deprecated. Docker Compose commands refer to Docker Compose v2. Consider upgrading your docker setup, see [Migrate to Compose V2](https://docs.docker.com/compose/migrate/)
:::
## Get the ID
First you need to find out the ID of the drive or charge:
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
- Open the `Drives` dashboard and click on the start date of the drive.
- The URL will contain the drive ID, for example `&var-drive_id=9999`.
- Open the `Charges` dashboard and click on the start date of the charge.
- The URL will contain the charge id, for example `&var-charging_process_id=9999`.
## Terminate a drive or charge
If for some reason a drive or charge hasn't been fully recorded, for example due to a bug or an unexpected restart, you can terminate it manually. Among other things, this assigns an end date to the drive/charge.
Replace `9999` with the actual ID then run the command while the TeslaMate container is running:
```bash
docker compose exec teslamate bin/teslamate rpc \
"TeslaMate.Repo.get!(TeslaMate.Log.Drive, 9999) |> TeslaMate.Log.close_drive()"
```
```bash
docker compose exec teslamate bin/teslamate rpc \
"TeslaMate.Repo.get!(TeslaMate.Log.ChargingProcess, 9999) |> TeslaMate.Log.complete_charging_process()"
```
```bash
teslamate-close-drive 9999
```
```bash
teslamate-close-charge 9999
```
## Delete a drive or charge
If for some reason a drive or charge was recorded incorrectly, you can delete it.
1. Attach to the **running** database container:
```bash
docker compose exec database psql teslamate teslamate
```
:::note
If you get the error `No such service: database`, update your _docker-compose.yml_ or use `db` instead of `database` in the above command.
:::
2. Afterwards replace `9999` with the actual ID then run the query:
```sql
DELETE FROM drives WHERE id = 9999;
```
1. Attach to the **running** database container:
```bash
docker compose exec database psql teslamate teslamate
```
:::note
If you get the error `No such service: database`, update your _docker-compose.yml_ or use `db` instead of `database` in the above command.
:::
2. Afterwards replace `9999` with the actual ID then run the query:
```sql
DELETE FROM charging_processes WHERE id = 9999;
```
You can use the idiomatic maintenance script:
```bash
teslamate-delete-drive 9999
```
You can use the idiomatic maintenance script:
```bash
teslamate-delete-charge 9999
```
## Remove a vehicle from the database
**NOTE:** Always [backup](backup.mdx) your data before performing any database changes.
1. Connect to your running TeslaMate database
```bash
docker compose exec database psql teslamate teslamate
```
:::note
If you get the error `No such service: database`, update your _docker-compose.yml_ or use `db` instead of `database` in the above command.
:::
2. Identify the right car ID in the database to remove
```sql
SELECT id, vin FROM cars;
```
3. Based upon the output, run the following command replacing `num` with the ID from the previous command.
```sql
DELETE FROM cars WHERE id = num;
DELETE FROM car_settings WHERE id = num;
DELETE FROM charging_processes WHERE car_id = num;
DELETE from charges WHERE charging_process_id in (select id from charging_processes where car_id = num);
DELETE FROM drives WHERE car_id = num;
DELETE FROM positions WHERE car_id = num;
DELETE FROM states WHERE car_id = num;
DELETE FROM updates WHERE car_id = num;
```
## Reindex Database
**NOTE:** If your database experiences a lot of updates or deletions, like importing data from other sources or deleting a loaner car or some other similar situation, you might encounter index bloat, which can degrade performance. In such cases, reindexing could be beneficial.
In summary, you don't necessarily need to run REINDEX periodically unless your database workload involves significant amounts of updates and deletions, if so, you may you may proceed as indicated in the following steps:
1. Connect to your running TeslaMate database
```bash
docker compose exec -T database psql teslamate teslamate
```
:::note
If you get the error `No such service: database`, update your _docker-compose.yml_ or use `db` instead of `database` in the above command.
:::
2. Run the following script (copy and paste)
```sql
REINDEX DATABASE teslamate
```
3. Exit the prompt by typing:
```bash
\q (or press CTRL + C)
```
---
### Maintenance Restore (`website/docs/maintenance/restore.mdx`)
---
title: Restore
sidebar_label: Restore data from Backup
---
:::note
If you are using `docker-compose`, you are using Docker Compose v1, which has been deprecated. Docker Compose commands refer to Docker Compose v2. Consider upgrading your docker setup, see [Migrate to Compose V2](https://docs.docker.com/compose/migrate/)
:::
## Restore
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
:::note
Replace the default `teslamate` value below with the value defined in the .env file if you have one (TM_DB_USER and TM_DB_NAME)
:::
```bash
# Stop the teslamate container to avoid write conflicts
docker compose stop teslamate
# Drop existing data and reinitialize (Don't forget to replace first teslamate if using different TM_DB_USER)
docker compose exec -T database psql -U teslamate teslamate << .
DROP SCHEMA IF EXISTS public CASCADE;
DROP SCHEMA IF EXISTS private CASCADE;
CREATE SCHEMA public;
CREATE EXTENSION cube WITH SCHEMA public;
CREATE EXTENSION earthdistance WITH SCHEMA public;
.
# Restore
docker compose exec -T database psql -U teslamate -d teslamate < teslamate.bck
# Restart the teslamate container
docker compose start teslamate
```
You can use the idiomatic restore script, for example:
```bash
teslamate-restore teslamate_20250805-1622.bck
```
---
### Maintenance Upgrading Postgres (`website/docs/maintenance/upgrading_postgres.md`)
---
title: Upgrading PostgreSQL to a new major version
sidebar_label: Upgrading PostgreSQL
---
1. Create a [backup](backup.mdx)
2. Stop all TeslaMate containers
```bash
docker compose down
```
3. Delete the database volume. **Be careful**, this will delete all your previously recorded data! Make sure that your backup can be restored before you start.
```bash
docker volume rm "$(basename "$PWD")_teslamate-db"
```
4. Change the postgres version and ensure your volume mount is [configured correctly](https://hub.docker.com/_/postgres#pgdata) in docker-compose.yml and start the container
```yml {2}
database:
image: postgres:18-trixie
...
volumes:
- teslamate-db:/var/lib/postgresql
```
```bash
docker compose up -d database
```
5. [Restore](restore.mdx) the backup
---
### Installation Unsupported Debian (`website/docs/installation/unsupported/debian.md`)
---
title: Manual install - Debian (no support)
sidebar_label: Manual - Debian (no support)
---
This document provides the necessary steps for installation of TeslaMate on a vanilla Debian or Ubuntu system. The **recommended and most straightforward installation approach is through the use of [Docker](../docker.md)**, however this walkthrough provides the necessary steps for manual installation in an aptitude (Debian/Ubuntu) environment.
## Requirements
Click on the following items to view detailed installation steps.
Note that in very recent distributions, you might have the required versions already packaged. However, the contents or naming of the Debian/Ubuntu packages might slightly differ than the ones from upstream, so you might need to install extra packages or do other tweaks.
Postgres (v16.7+, v17.3+ or v18.0+)
Either upstream:
```bash
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get install -y postgresql-18 postgresql-client-18
```
Source: [postgresql.org/download](https://www.postgresql.org/download/)
Or if you run a recent enough distribution (e.g. Debian Trixie:):
```bash
sudo apt install postgresql-17 postgresql-client-17
```
Elixir (v1.19+ on Erlang/OTP 28+)
The Erlang and Elixir packages of Debian stable are too old, so install both with [mise](https://mise.jdx.dev/). On Ubuntu 22.04 and 24.04 mise downloads a precompiled Erlang/OTP; on Debian it compiles Erlang/OTP from source, which takes a while.
```bash
sudo apt install -y extrepo
sudo extrepo enable mise
sudo apt update
sudo apt install -y mise build-essential libncurses-dev libssl-dev openssl curl
echo 'eval "$(mise activate bash)"' >> ~/.bashrc && source ~/.bashrc
mise use --global erlang@29 elixir@1.20.3-otp-29
```
Run the [compile steps](#compile-elixir-project) as the same user, so `mix` is on the `PATH`.
Source: [mise.jdx.dev/lang/elixir](https://mise.jdx.dev/lang/elixir.html)
Grafana (v13.2.3+)
```bash
sudo apt-get install -y apt-transport-https software-properties-common
sudo add-apt-repository "deb https://apt.grafana.com stable main"
wget -q -O - https://apt.grafana.com/gpg-full.key | sudo apt-key add -
sudo apt-get update
sudo apt-get install -y grafana
sudo systemctl start grafana-server
sudo systemctl enable grafana-server.service # to start Grafana at boot time
```
Source: [grafana.com/docs/installation](https://grafana.com/docs/grafana/latest/installation/)
[Import the Grafana dashboards](#import-grafana-dashboards) after [cloning the TeslaMate git repository](#clone-teslamate-git-repository).
An MQTT Broker (e.g. Mosquitto)
```bash
sudo apt-get install -y mosquitto
```
Source: [mosquitto.org/download](https://mosquitto.org/download/)
Node.js (v22+)
Either from upstream:
```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs
```
Source: [nodejs.org/en/download/package-manager](https://nodejs.org/en/download/package-manager/all#debian-and-ubuntu-based-linux-distributions)
Or if you run a recent enough distribution (e.g. Debian Trixie:):
```bash
sudo apt install nodejs npm
```
## Clone TeslaMate git repository
The following command will clone the source files for the TeslaMate project. This should be run in an appropriate directory within which you would like to install TeslaMate. You should also record this path and provide them to the startup scripts proposed at the end of this guide.
```bash
cd /usr/src
git clone https://github.com/teslamate-org/teslamate.git
cd teslamate
git checkout $(git describe --tags `git rev-list --tags --max-count=1`) # Checkout the latest stable version
```
## Create PostgreSQL database
The following commands will create a database called `teslamate` on the PostgreSQL database server, and a user called `teslamate`. When creating the `teslamate` user, you will be prompted to enter a password for the user interactively. This password should be recorded and provided as an environment variable in the startup script at the end of this guide.
```console
sudo -u postgres psql
postgres=# create database teslamate;
postgres=# create user teslamate with encrypted password 'your_secure_password_here';
postgres=# grant all privileges on database teslamate to teslamate;
postgres=# ALTER USER teslamate WITH SUPERUSER;
postgres=# \q
```
_Note: The superuser privileges can be revoked after running the initial database migrations._
## Compile Elixir Project
```bash
cd elixir
mix local.hex --force; mix local.rebar --force
mix deps.get --only prod
npm install --prefix ./assets && npm run deploy --prefix ./assets
MIX_ENV=prod mix do phx.digest, release --overwrite
```
### Set your system locale
You may need to set your system locale. If you get an error when running the TeslaMate service which indicates that you don't have a UTF-8 capable system locale set, run the following commands to set the locale on your system:
```bash
sudo locale-gen en_US.UTF-8
sudo localectl set-locale LANG=en_US.UTF-8
```
## Starting TeslaMate at boot time
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
Create a systemd service at `/etc/systemd/system/teslamate.service`:
```ini
[Unit]
Description=TeslaMate
After=network.target
After=postgresql.service
[Service]
Type=simple
# User=username
# Group=groupname
Restart=on-failure
RestartSec=5
Environment="HOME=/usr/src/teslamate"
Environment="LANG=en_US.UTF-8"
Environment="LC_CTYPE=en_US.UTF-8"
Environment="TZ=Europe/Berlin"
Environment="PORT=4000"
Environment="ENCRYPTION_KEY=your_secure_encryption_key_here"
Environment="DATABASE_USER=teslamate"
Environment="DATABASE_PASS=#your secure password!
Environment="DATABASE_NAME=teslamate"
Environment="DATABASE_HOST=127.0.0.1"
Environment="MQTT_HOST=127.0.0.1"
WorkingDirectory=/usr/src/teslamate
ExecStartPre=/usr/src/teslamate/elixir/_build/prod/rel/teslamate/bin/teslamate eval "TeslaMate.Release.migrate"
ExecStart=/usr/src/teslamate/elixir/_build/prod/rel/teslamate/bin/teslamate start
ExecStop=/usr/src/teslamate/elixir/_build/prod/rel/teslamate/bin/teslamate stop
[Install]
WantedBy=multi-user.target
```
- `MQTT_HOST` should be the IP address of your MQTT broker. If you do not have one installed, the MQTT functionality can be disabled with `DISABLE_MQTT=true`.
- `TZ` should be your local timezone. Work out your timezone name using the [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) in the linked Wikipedia page.
Start the service:
```bash
sudo systemctl start teslamate
```
And automatically get it to start on boot:
```bash
sudo systemctl enable teslamate
```
Create the following file: `/usr/local/bin/teslamate-start.sh`
You should at least substitute the following details:
- `MQTT_HOST` should be the IP address of your MQTT broker. If you do not have one installed, the MQTT functionality can be disabled with 'DISABLE_MQTT=true'.
- `TZ` should be your local timezone. Work out your timezone name using the [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) in the linked Wikipedia page.
- `TESLAMATEPATH` should be the path that you ran the `git clone` within.
```bash
export ENCRYPTION_KEY="your_secure_encryption_key_here"
export DATABASE_USER="teslamate"
export DATABASE_PASS="your_secure_password_here"
export DATABASE_HOST="127.0.0.1"
export DATABASE_NAME="teslamate"
export MQTT_HOST="127.0.0.1"
export MQTT_USERNAME="teslamate"
export MQTT_PASSWORD="teslamate"
export MQTT_TLS="false"
export TZ="Europe/Berlin"
export TESLAMATEPATH=/usr/src/teslamate
$TESLAMATEPATH/elixir/_build/prod/rel/teslamate/bin/teslamate start
```
The following command needs to be run once during the installation process in order to create the database schema for the TeslaMate installation:
```bash
export ENCRYPTION_KEY="your_secure_encryption_key_here"
export DATABASE_USER="teslamate"
export DATABASE_PASS="your_secure_password_here"
export DATABASE_HOST="127.0.0.1"
export DATABASE_NAME="teslamate"
_build/prod/rel/teslamate/bin/teslamate eval "TeslaMate.Release.migrate"
```
Add the following to /etc/rc.local, to start a screen session at boot time and run the TeslaMate server within a screen session. This lets you interactively connect to the session if needed.
```bash
# Start TeslaMate
cd /usr/src/teslamate
screen -S teslamate -L -dm bash -c "cd /usr/src/teslamate; ./start.sh; exec sh"
```
## Import Grafana Dashboards
1. Visit [localhost:3000](http://localhost:3000) and log in. The default credentials are: `admin:admin`.
2. Create a data source with the name "TeslaMate":
```grafana
Type: PostgreSQL
Default: YES
Name: TeslaMate
Host: localhost
Database: teslamate
User: teslamate Password: your_secure_password_here
SSL-Mode: disable
Version: 10
```
3. Install `jq`:
```bash
sudo apt install jq
```
4. [Manually import](https://grafana.com/docs/reference/export_import/#importing-a-dashboard) the dashboard [files](https://github.com/teslamate-org/teslamate/tree/main/grafana/dashboards) or use the `dashboards.sh` script. First create a "Service Account" called `TeslaMate` under Grafana's Administration > User and access menu. Then create an API token for this service account (in place of `` below) and run the script:
```bash
$ env GRAFANA_API_TOKEN= ./grafana/dashboards.sh restore
URL: http://localhost:3000
GRAFANA_API_TOKEN: mytoken
DASHBOARDS_DIRECTORY: ./grafana/dashboards
GRAFANA_ORG_NAMESPACE: default
RESTORED locations.json into Grafana folder 'TeslaMate' ...
RESTORED drive-stats.json into Grafana folder 'TeslaMate' ...
...
```
:::tip
To point to a different Grafana instance use the URL variable:
```bash
env URL=https://mygrafana.example.net GRAFANA_API_TOKEN= ./grafana/dashboards.sh restore
```
:::
:::tip
In case you use a Grafana installation that runs on a separate server (for
example, an already existing Grafana install), set the `URL` variable to
point to it (the default points to `http://localhost:3000`, use a full URL,
including protocol, host and port):
```bash
URL= ./grafana/dashboards.sh restore
```
:::
## Usage
1. [Generate an access and refresh token](../tokens.md)
2. Open the web interface [http://your-ip-address:4000](http://localhost:4000)
3. Enter the access and refresh token on the sign-in page
4. The Grafana dashboards are available at [http://your-ip-address:3000](http://localhost:3000). Log in with the default user `admin` (initial password `admin`) and enter a secure password.
5. In the TeslaMate web interface, go to _Settings → URLs_ and set the _Web App_ and _Dashboards_ URLs, so the links between TeslaMate and Grafana work in both directions.
## Update
To update the running TeslaMate configuration to the latest version, follow: [Upgrading to a new version](../../upgrading.mdx)
---
### Installation Unsupported Freebsd (`website/docs/installation/unsupported/freebsd.md`)
---
title: Manual install - FreeBSD (no support)
sidebar_label: Manual - FreeBSD (no support)
---
This document provides the necessary steps for installation of TeslaMate in a FreeBSD jail. The **recommended and most straightforward installation approach is through the use of [Docker](../docker.md)**, however this walkthrough provides the necessary steps for manual installation in a FreeBSD 13.0 environment.
It assumes that pre-requisites are met and only basic instructions are provided and should also work in FreeBSD before 13.0.
## Requirements
Click on the following items to view detailed installation steps.
bash & jq
```bash
pkg install bash jq
bash
```
For simplicity reasons, follow the rest of the tutorial in bash rather the csh.
git
```bash
pkg install git
```
Erlang (v26+)
```bash
pkg install erlang
```
Elixir (v1.19+ on Erlang/OTP 28+)
```bash
pkg install elixir
```
Postgres (v16.7+, v17.3+ or v18.0+)
```bash
pkg install postgresql18-server
pkg install postgresql18-contrib
echo postgres_enable="yes" >> /etc/rc.conf
```
Initialize the database
```bash
service postgresql initdb
```
Grafana (v13.1.1+)
```bash
pkg install grafana
echo grafana_enable="yes" >> /etc/rc.conf
```
An MQTT Broker (e.g. Mosquitto)
```bash
pkg install mosquitto
echo mosquitto_enable="yes" >> /etc/rc.conf
```
Node.js (v22+)
```bash
pkg install node22
pkg install npm-node22
```
## Clone TeslaMate git repository
The following command will clone the source files for the TeslaMate project. This should be run in an appropriate directory within which you would like to install TeslaMate. You should also record this path and provide them to the startup scripts proposed at the end of this guide.
```bash
cd /usr/local/src
git clone https://github.com/teslamate-org/teslamate.git
cd teslamate
git checkout $(git describe --tags `git rev-list --tags --max-count=1`) # Checkout the latest stable version
```
## Create PostgreSQL database
The following commands will create a database called `teslamate` on the PostgreSQL database server, and a user called `teslamate`. When creating the `teslamate` user, you will be prompted to enter a password for the user interactively. This password should be recorded and provided as an environment variable in the startup script at the end of this guide. Use 'su - postgres' if unable to enter psql console from current user.
```console
psql
postgres=# create database teslamate;
postgres=# create user teslamate with encrypted password 'your_secure_password_here';
postgres=# grant all privileges on database teslamate to teslamate;
postgres=# ALTER USER teslamate WITH SUPERUSER;
postgres=# \q
```
_Note: The superuser privileges can be revoked after running the initial database migrations._
## Compile Elixir Project
```bash
cd elixir
mix local.hex --force; mix local.rebar --force
mix deps.get --only prod
npm install --prefix ./assets && npm run deploy --prefix ./assets
export MIX_ENV=prod
mix do phx.digest, release --overwrite
```
## Starting TeslaMate at boot time
### Create FreeBSD service definition _/usr/local/etc/rc.d/teslamate_
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Update _/etc/rc.conf_
```bash
echo teslamate_enable="YES" >> /etc/rc.conf
echo teslamate_db_host="localhost" >> /etc/rc.conf
echo teslamate_db_port="5432" >> /etc/rc.conf
echo teslamate_db_pass="" >> /etc/rc.conf
echo teslamate_encryption_key="" >> /etc/rc.conf
echo teslamate_disable_mqtt="true" >> /etc/rc.conf
echo teslamate_timezone="" >> /etc/rc.conf #i.e. Europe/Berlin, America/Los_Angeles
```
### Start service
```bash
chmod +x /usr/local/etc/rc.d/teslamate
service teslamate start
```
## Import Grafana Dashboards
1. Visit [localhost:3000](http://localhost:3000) and log in (don't forget to start the service: service grafana start). The default credentials are: `admin:admin`.
2. Create a data source with the name "TeslaMate":
```grafana
Type: PostgreSQL
Default: YES
Name: TeslaMate
Host: localhost
Database: teslamate
User: teslamate Password: your_secure_password_here
SSL-Mode: disable
Version: 10
```
3. [Manually import](https://grafana.com/docs/reference/export_import/#importing-a-dashboard) the dashboard [files](https://github.com/teslamate-org/teslamate/tree/main/grafana/dashboards) or use the `dashboards.sh` script. First create a "Service Account" called `TeslaMate` under Grafana's Administration > User and access menu. Then create an API token for this service account (in place of `` below) and run the script:
```bash
$ env GRAFANA_API_TOKEN= ./grafana/dashboards.sh restore
URL: http://localhost:3000
GRAFANA_API_TOKEN: mytoken
DASHBOARDS_DIRECTORY: ./grafana/dashboards
GRAFANA_ORG_NAMESPACE: default
RESTORED locations.json into Grafana folder 'TeslaMate' ...
RESTORED drive-stats.json into Grafana folder 'TeslaMate' ...
...
```
:::tip
To point to a different Grafana instance use the URL variable:
```bash
env URL=https://mygrafana.example.net GRAFANA_API_TOKEN= ./grafana/dashboards.sh restore
```
:::
## Usage
1. [Generate an access and refresh token](../tokens.md)
2. Open the web interface [http://your-ip-address:4000](http://localhost:4000)
3. Enter the access and refresh token on the sign-in page
4. The Grafana dashboards are available at [http://your-ip-address:3000](http://localhost:3000). Log in with the default user `admin` (initial password `admin`) and enter a secure password.
5. In the TeslaMate web interface, go to _Settings → URLs_ and set the _Web App_ and _Dashboards_ URLs, so the links between TeslaMate and Grafana work in both directions.
## Update
To update the running TeslaMate configuration to the latest version, follow: [Upgrading to a new version](../../upgrading.mdx)
---
### Installation Unsupported Unraid (`website/docs/installation/unsupported/unraid.md`)
---
title: Unraid install (no support)
sidebar_label: Unraid (no support)
---
This document provides the necessary steps for installation of TeslaMate on Unraid. You can either:
- use [Docker Compose for Unraid](https://docs.ibracorp.io/docker-compose/docker-compose-for-unraid) and follow the [Docker Compose installation guide](installation/docker.md) to set up TeslaMate, which is the recommended method and is supported,
- or install the containers individually using the Unraid Community Apps store, without any support.
## Requirements
- Existing Unraid install on v6 or higher with Docker service enabled
- Community Apps store installed
- appdata share configured
- External internet access, to talk to tesla.com
## Installation
Unlike the Compose installation which sets up the following containers in one go, you can install and configure each container individually from Community Apps.
### Postgres
1. Go to the Apps tab for the Community Apps and search for postgresql17 (current version supported) and click install.
2. Verify that no other applications are running on port `5432`
3. Pick a password of your choosing for the database
4. Set `POSTGRES_USER` to `teslamate`
5. Set `POSTGRES_DB` to `teslamate`
6. Click apply and set the container to autostart.
### Mosquitto
1. Go to the Apps tab for the Community Apps and search for mosquitto (for example cmccambridge repository) and click install.
2. Verify that no other applications are running on port `1883`
3. Default template options are mostly fine.
4. Click apply and set the container to autostart.
### TeslaMate
1. Go to the Apps tab for the Community Apps and search for TeslaMate and click install.
2. Verify that no other applications are running on port `4000`
3. **Choose a secure encryption key** that will be used to encrypt your Tesla API tokens (insert as `ENCRYPTION_KEY`).
4. Set the postgres user to `teslamate` and the postgres password to your password from the postgres setup
5. Set the database `teslamate` to match the previous config
6. Set the MQTT host to the IP address of your Unraid server
7. Create an MQTT user and password (required since the default setup is secure)
8. Click apply and optionally set the container to autostart
### TeslaMate-Grafana
1. Go to the Apps tab for the Community Apps and search for TeslaMate Grafana and click install.
2. Verify that no other applications are running on port `3000` (such as another Grafana instance). If so, specify a different port like 3333
3. Specify the TeslaMate database name, username, and password
4. Set the IP of your Unraid server for the host.
5. Click apply and optionally set the container to autostart
## Usage
1. [Generate an access and refresh token](../tokens.md)
2. Open the web interface [http://your-ip-address:4000](http://localhost:4000) or click on the TeslaMate icon and select WebUI.
3. Enter the access and refresh token on the sign-in page
4. The Grafana dashboards are available at [http://your-ip-address:3000](http://localhost:3000). Log in with the default user `admin` (initial password `admin`) and enter a secure password.
5. In the TeslaMate web interface, go to _Settings → URLs_ and set the _Web App_ and _Dashboards_ URLs, so the links between TeslaMate and Grafana work in both directions.
## Update
Check out the [release notes](https://github.com/teslamate-org/teslamate/releases) before upgrading!
To update the running TeslaMate configuration to the latest version, go back to the Apps tab and wait for the Action Center to notify of new updates. Under no circumstances use the Auto Update Applications plugin, as it can easily break your setup, and you won't get any support.
## Unraid Backup and Restore when choosing the individual installation method
### User Scripts Plugin
Go to the Apps tab and search for the User Scripts plugin and install. The plugin can then be accessed from the Settings menu.
### Backup
In the User Scripts plugin, click the Add New Script button. Give the script a name such as `TeslaMate Backup`
Click the gear icon next to the name and Edit Script.
Copy and paste in the following script:
```bash
#!/bin/bash
# Check if array is started
ls /mnt/disk[1-9]* 1>/dev/null 2>/dev/null
if [ $? -ne 0 ]
then
echo "ERROR: Array must be started before using this script"
exit
fi
BACKUP_DIR="/mnt/user/backups/SQL/postgres17"
databases=`docker exec postgresql17 psql -U teslamate teslamate -l -t | cut -d'|' -f1 | sed -e 's/ //g' -e '/^$/d'`
for db in $databases; do if [ "$db" != "postgres" ] && [ "$db" != "template0" ] && [ "$db" != "template1" ] && [ "$db" != "template_postgis" ]; then
FOLDER=$BACKUP_DIR/$db
echo "Backing up $db"
mkdir -p "$FOLDER"
FILENAME=${db}_$(date +%A).sql
FILEPATH=$FOLDER/$FILENAME
docker exec postgresql17 pg_dump --clean -h 127.0.0.1 -U teslamate -d $db > $FILEPATH
tar czf $FILEPATH.tgz -C $FOLDER $FILENAME
rm $FILEPATH
fi
done
find $BACKUP_DIR/ -type f -name '*.tgz' -mtime +7 -exec rm {} \;
```
:::note
Change the `BACKUP_DIR` path to a share on your server where you want to save backups. Make sure you have the mover settings configured correctly on your share or also have some other backup process for these files since they are still on your server.
:::
:::note
If you changed `DB_USER` in the template from one of the advanced guides, make sure to replace the first instance of `teslamate` and again after the -U in in the above command.
:::
Click **RUN SCRIPT** to test and verify that it works. If you are satisfied, you can select Scheduled Daily from the drop-down to run the cron job every day and create a backup file every day with the day of the week in the file name. Make sure to the click **Run in Background**
### Restore
1. Manually stop all TeslaMate docker containers (TeslaMate-Grafana, TeslaMate).
2. In the User Scripts plugin, click the Add New Script button. Give the script a name such as `TeslaMate Restore`
3. Click the gear icon next to the name and Edit Script.
4. Copy and paste the following script and then Click **RUN SCRIPT**
```
/* Detailed source-code truncated for AI context efficiency. */
```
:::note
Replace the `BACKUP_DIR` value with the value defined in the previous backup file.
:::
:::note
Replace the `DB_CONTAINER` value with the name of the container you want the restore to go **to**.
:::
:::note
Replace the default `teslamate` value below with the value defined in the template if you have one (DB_USER and DB_NAME)
:::
### Postgres Upgrade
1. Run the Backup script
2. Go to the Apps tab and search for the latest recommended postgres version and install a new container instance. Then shut it down.
3. Edit the Restore script `DB_CONTAINER` with the name of the new postgres container you just installed and specify the `BACKUP_DIR`
4. Click RUN SCRIPT
5. Select the backup file you want to restore.
6. Start the new postgres, TeslaMate, and TeslaMate-Grafana containers and verify that your data is correct.
7. When you are certain everything is working as expected, you can delete the old postgres container and image (optional)
---
--- METRICS ---
- Files Extracted: 28
- Estimated Token Budget: ~49041 tokens
- Canonical Reference: https://codewiki.google/github.com/teslamate-org/teslamate
![Web Interface]({useBaseUrl("screenshots/web_interface.png")})
## Battery Health
![Visited addresses]({useBaseUrl("screenshots/battery-health.png")})
## Charge Level
![Charge Level]({useBaseUrl("screenshots/charge-level.png")})
## Charges
![Charges]({useBaseUrl("screenshots/charging-history.png")})
## Charge Details
![Charge Details]({useBaseUrl("screenshots/charging.png")})
## Charging Stats
![Charge Stats]({useBaseUrl("screenshots/charging-stats.png")})
## Database Information
![Database Information]({useBaseUrl("screenshots/db-info.png")})
## Drive Stats
![Drive Stats]({useBaseUrl("screenshots/drive-stats.png")})
## Drives
![Drives]({useBaseUrl("screenshots/drives.png")})
## Drive Details
![Drive Details]({useBaseUrl("screenshots/drive.png")})
## Efficiency
![Efficiency]({useBaseUrl("screenshots/efficiency.png")})
## Location (addresses)
![Location (addresses)]({useBaseUrl("screenshots/locations.png")})
## Mileage
![Mileage]({useBaseUrl("screenshots/mileage.png")})
## Overview
![Overview]({useBaseUrl("screenshots/overview.png")})
## Projected Range
![Projected Range]({useBaseUrl("screenshots/projected-range.png")})
## States
![States]({useBaseUrl("screenshots/states.png")})
## Statistics
![Statistics]({useBaseUrl("screenshots/statistics.png")})
## Temperatures
![Temperatures]({useBaseUrl("screenshots/temperatures.png")})
## Timeline
![Timeline]({useBaseUrl("screenshots/timeline.png")})
## Trip
![Trip]({useBaseUrl("screenshots/trip.png")})
## Updates
![Updates]({useBaseUrl("screenshots/updates.png")})
## Vampire Drain
![Vampire Drain]({useBaseUrl("screenshots/vampire_drain.png")})
## Visited (Lifetime driving map)
![Lifetime driving map]({useBaseUrl("screenshots/lifetime_driving_map.png")})
---
### Upgrading (`website/docs/upgrading.mdx`)
---
id: upgrading
title: Upgrading to a new version
sidebar_label: Upgrading to a new version
---
:::warning
**Create a [backup](maintenance/backup.mdx) before updating!**
:::
:::info
**Check the [Release Notes](https://github.com/teslamate-org/teslamate/releases) for major version jumps** - some versions may require intermediate upgrades or database migrations in a specific order
:::
:::note
If you are using `docker-compose`, you are using Docker Compose v1, which has been deprecated. Docker Compose commands refer to Docker Compose v2. Consider upgrading your docker setup, see [Migrate to Compose V2](https://docs.docker.com/compose/migrate/)
:::
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
})
### Current Status
- Sensors: All sensors exposed by the Tesla component are available
- Locks: Not implemented
- Climate: Not implemented
## MQTT Discovery (automatic configuration)
TeslaMate can publish [Home Assistant MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) payloads, so the entities below are created automatically and you no longer need to maintain `mqtt_sensors.yaml`.
Enable it with the following environment variables (see [Environment variables](../configuration/environment_variables.md)):
| Variable | Description | Default |
| -------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------- |
| `MQTT_HOME_ASSISTANT_DISCOVERY` | Set to `true` to enable discovery. | `false` |
| `MQTT_HOME_ASSISTANT_DISCOVERY_URL` | TeslaMate URL surfaced in the discovered device panel (e.g. `https://teslamate.example.com/`). | _none_ |
| `MQTT_HOME_ASSISTANT_DISCOVERY_PREFIX` | Discovery topic prefix. Must match Home Assistant's `discovery_prefix` setting. | `homeassistant` |
When enabled, TeslaMate publishes one retained device discovery payload per
vehicle to `