TeslaMate User Guide

version: '3'

services:
  teslamate:
    image: teslamate/teslamate:latest
    restart: always
    environment:
      - ENCRYPTION_KEY= #设置 TeslaMate API 加密密码，注意等号后面不要有空格
      - DATABASE_USER=teslamate
      - DATABASE_PASS= #设置安全数据库密码，注意等号后面不要有空格
      - DATABASE_NAME=teslamate
      - DATABASE_HOST=database
      - MQTT_HOST=mosquitto
    ports:
      - 4000:4000
    volumes:
      - ./import:/opt/app/import
    cap_drop:
      - all

  database:
    image: postgres:15
    restart: always
    environment:
      - POSTGRES_USER=teslamate
      - POSTGRES_PASSWORD= #设置数据库密码，注意等号后面不要有空格
      - POSTGRES_DB=teslamate
    volumes:
      - teslamate-db:/var/lib/postgresql/data

  grafana:
    image: teslamate/grafana:latest
    restart: always
    environment:
      - DATABASE_USER=teslamate
      - DATABASE_PASS= #设置 grafana 的数据库密码，注意等号后面不要有空格
      - DATABASE_NAME=teslamate
      - DATABASE_HOST=database
    ports:
      - 3000:3000
    volumes:
      - teslamate-grafana-data:/var/lib/grafana

  mosquitto:
    image: eclipse-mosquitto:2
    restart: always
    command: mosquitto -c /mosquitto-no-auth.conf
    # ports:
    #   - 1883:1883
    volumes:
      - mosquitto-conf:/mosquitto/config
      - mosquitto-data:/mosquitto/data

volumes:
  teslamate-db:
  teslamate-grafana-data:
  mosquitto-conf:
  mosquitto-data:
```  

Note that some services require matching passwords, so I recommend setting all passwords above to the same value for simplicity. Also, pay special attention to ensure `=` has no trailing spaces. Next, open a terminal and execute the following (copy each line and press Enter):  

```bash
# 假设你放上述文件的目录为 ~/Developer/Docker/TeslaMate
cd ~/Developer/Docker/TeslaMate
docker compose up -d
```  

Once completed, Docker Desktop should look like this:  

{% render_caption caption="安装完成后截图" img="https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/cd39c66f-60b7-4d3d-81bd-f5ac50260d28.webp" %}  
![安装完成后截图](https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/cd39c66f-60b7-4d3d-81bd-f5ac50260d28.webp)  
{% endrender_caption %}  

## 2. Logging in and Authorizing Your Tesla Account  

After ensuring no errors in the previous step and confirming all services are in the "Running" state (you can check logs by clicking each service name in the screenshot above for any errors), open `localhost:4000` in your browser. You’ll be prompted to enter an API Token and Refresh Token. The official documentation explains how to obtain these here:  

{% render_bookmark url="https://docs.teslamate.org/docs/faq/#how-to-generate-your-own-tokens" title="Frequently Asked Questions | TeslaMate" img="" yid="" bid="" %}  
How to generate your own tokens  
{% endrender_bookmark %}  

Here, I’ll use the third method: "Tesla Auth (macOS, Linux, Windows)." Click the link below to find the version for your system and download the corresponding file (an executable):

{% render_bookmark url="https://github.com/adriankumpf/tesla_auth#download" title="GitHub - adriankumpf/tesla_auth: Securely generate API tokens for third-party access to your Tesla." img="https://opengraph.githubassets.com/14ed85d2b3ddb9d5945d743bce95d70195e338a20492ab583d95d8c0d4f14ebd/adriankumpf/tesla_auth" yid="" bid="" %}
Securely generate API tokens for third-party access to your Tesla. - GitHub - adriankumpf/tesla_auth: Securely generate API tokens for third-party access to your Tesla.
{% endrender_bookmark %}

If you directly double-click to open (or open via terminal), macOS may warn you that the executable file could be dangerous. Go to `系统设置-隐私与安全性` and click "Open Anyway". After opening, a window will pop up prompting you to log in to your Tesla account. Once logged in, the page will display your Tesla API Token and Refresh Token (I won't include screenshots here). Copy these to the corresponding fields on the `localhost:4000` page to successfully log in. The interface after successful login looks like this:

{% render_caption caption="TeslaMate 授权成功界面" img="https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/8d41bc35-475f-499d-b2d3-c4812e9a72e9.webp" %}
![TeslaMate 授权成功界面](https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/8d41bc35-475f-499d-b2d3-c4812e9a72e9.webp)
{% endrender_caption %}

At this point, authentication is complete. Next, configure Grafana.

## 3. Basic Concepts of Grafana

Grafana is a powerful web-based data visualization dashboard tool, which is relatively complex to use. I haven't explored how to localize it into Chinese. Fortunately, Tesla's data fields are simple enough that localization isn't necessary. Here’s a brief introduction to the relevant concepts for easier customization later.

### Dashboard and Panel

A Dashboard is an interface that displays various data, showing different Panels. A Panel is a module that queries the database for data and visualizes it. Each red box in the image below represents a Panel:

{% render_caption caption="N 个 Panel 组成了一个 Dashboard" img="https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/6b5bfe32-8214-4994-a6ce-9b3a1874e11e.webp" %}
![N 个 Panel 组成了一个 Dashboard](https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/6b5bfe32-8214-4994-a6ce-9b3a1874e11e.webp)
{% endrender_caption %}

Panels can be copied between different Dashboards as shown below:

{% render_caption caption="Panel 复制" img="https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/2522b63e-34e9-44e2-a0ba-2d74901ea53b.webp" %}
![Panel 复制](https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/2522b63e-34e9-44e2-a0ba-2d74901ea53b.webp)
{% endrender_caption %}

After clicking "Copy," you can paste it into another Dashboard. Click the "Add Panel" button in the upper right corner of the Dashboard (or when creating a new Dashboard for the first time). If you didn’t click "Copy" in the previous step, the fourth option, "Paste from Clipboard," won’t appear. The new Panel creation interface will look like this:

{% render_caption caption="粘贴刚刚复制的 Panel" img="https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/37d13b9a-d6b0-4e19-9bd9-b41712ea5e05.webp" %}
![粘贴刚刚复制的 Panel](https://static.xheldon.cn/img/in-post/2023/the-use-of-teslamate/37d13b9a-d6b0-4e19-9bd9-b41712ea5e05.webp)
{% endrender_caption %}

### Variable and JSON Model

**Variable**

Each Dashboard can set Variables for Panels to use. How do Panels use Variables? Panel data is retrieved via SQL queries, and part of the SQL syntax uses Grafana's SQL template syntax. Below is the SQL query for altitude data:

```sql
SELECT
 $__time(date),
 ROUND(convert_m(elevation, '$alternative_length_unit')) AS elevation_[[alternative_length_unit]]
FROM
 positions
WHERE
 car_id = $car_id AND
 $__timeFilter(date)
ORDER BY
 date ASC