terafin/mqtt-tesla-bridge

mqtt-tesla-bridge

镜像概述

mqtt-tesla-bridge 是一个轻量级的 Docker 镜像，旨在通过 MQTT 协议桥接和控制 Tesla 能源系统（如 Powerwall 电池、太阳能面板等）。它允许用户通过 MQTT 主题下发控制指令，并实时轮询发布系统的运行状态和统计数据，非常适合集成到 Home Assistant 等智能家居或物联网系统中。

核心功能和特性

• MQTT 远程控制：支持通过 MQTT 消息动态调整 Tesla 能源系统的电池备用百分比和运行模式。
• 实时状态监控：每 5 秒自动轮询并发布系统状态，包括太阳能发电量、电网使用情况、电池充放电状态及系统硬件信息。
• 易于集成：基于标准的 MQTT 协议，可无缝对接各类支持 MQTT 的物联网平台。

环境变量配置

在运行容器时，必须配置以下环境变量以连接到您的 MQTT 代理和 Tesla 账户：

使用方法

Docker CLI 部署

注：已修正原文档中 docker run 命令的参数顺序错误。

bash
docker run -d \
  --name mqtt-tesla-bridge \
  -e MQTT_HOST="mqtt://192.168.1.100" \
  -e TESLA_USERNAME="user@example.com" \
  -e TESLA_PASSWORD="your_password" \
  -e TOPIC_PREFIX="/tesla" \
  docker.xuanyuan.run/terafin/mqtt-tesla-bridge

Docker Compose 部署

推荐使用 Docker Compose 进行部署，创建 docker-compose.yml 文件：

yaml
version: '3.8'
services:
  mqtt-tesla-bridge:
    image: docker.xuanyuan.run/terafin/mqtt-tesla-bridge
    container_name: mqtt-tesla-bridge
    restart: unless-stopped
    environment:
      - MQTT_HOST=mqtt://192.168.1.100
      - TESLA_USERNAME=user@example.com
      - TESLA_PASSWORD=your_password
      - TOPIC_PREFIX=/tesla

启动服务：

bash
docker-compose up -d

控制指令 (MQTT Publish)

您可以向以下 MQTT 主题发布消息来控制 Tesla 能源系统（假设 TOPIC_PREFIX 为 /tesla，MQTT 服务器 IP 为 192.168.1.100）：

1. 设置电池备用百分比

将电池备用电量阈值设置为 90%：

bash
mosquitto_pub -h 192.168.1.100 -t "/tesla/reserve/percent/set" -m "90"

2. 设置电池备用模式

将系统模式设置为“电池备份”（Battery Backup）：

bash
mosquitto_pub -h 192.168.1.100 -t "/tesla/reserve/mode/set" -m "backup"

将系统模式设置为“自用”（Self-Consumption，优先使用电池直到达到备用百分比）：

bash
mosquitto_pub -h 192.168.1.100 -t "/tesla/reserve/mode/set" -m "self_consumption"

状态数据 (MQTT Subscribe)

该镜像每 5 秒 轮询一次 Tesla 系统，并将以下状态数据发布到对应的 MQTT 主题：

系统与硬件信息

• /tesla/system/version: 系统固件版本 (例: 1.10.2)
• /tesla/system/battery_count: 电池数量 (例: 3)
• /tesla/system/has_batteries: 是否包含电池 (例: true)
• /tesla/system/has_solar: 是否包含太阳能 (例: true)
• /tesla/system/has_grid: 是否连接电网 (例: true)

实时能源统计 (单位: 瓦特 W)

• /tesla/stats/solar_generation: 太阳能发电量 (例: 400.07)
• /tesla/stats/grid_usage: 电网使用量 (例: 753.72)
• /tesla/stats/battery_usage: 电池使用量（负数表示放电，正数表示充电） (例: -400.00)
• /tesla/stats/home_load: 家庭总负载 (例: 753.79)
• /tesla/stats/grid_active: 电网活动状态 (例: Active)

电池与备用状态

• /tesla/reserve/mode: 当前备用模式 (例: self_consumption)
• /tesla/reserve/percent: 设定的备用百分比 (例: 95)
• /tesla/reserve/battery/percent: 当前电池电量百分比 (例: 80.6)
• /tesla/reserve/battery/remaining: 电池剩余电量 (Wh) (例: 33599)
• /tesla/reserve/battery/capacity: 电池总容量 (Wh) (例: 41675)
• /tesla/reserve/battery/charging: 电池是否正在充电 (1 为是，0 为否)
• /tesla/reserve/battery/discharging: 电池是否正在放电 (1 为是，0 为否)