HA 调试日志

第一章 Debian 系统安装

准备工作

用户名：homeassistant 密码：12345678

备用ssh工具

ssh 工具 ssh工具

U盘烧录工具 rufus-4.11_x86.exe

debian 系统 debian_13-AMD64

debian 系统 debian_13-ARM64

需要设置BIOS 从U盘启动

串口调试助手

网络调试助手

手机端APP

编辑软件32位

编辑软件64位

1.1 系统更新与升级
首先，更新系统软件包列表并升级所有已安装的软件包，以确保系统处于最新状态。

1
2
3
<BASH>
sudo apt update
sudo apt upgrade -y

注意：如果在升级过程中提示“y/n”确认，输入 y。

1.2 网络配置
为了 Home Assistant 的稳定运行，建议配置静态 IP 地址。

1.2.1 识别网络接口
使用 ip a 命令查看当前系统的网络接口名称（例如：enp0s3、eth0 等）。

1
2
<BASH>
ip a

1.2.2 配置静态 IP
使用 nano 编辑 /etc/network/interfaces 文件。

1
2
<BASH>
sudo nano /etc/network/interfaces

将以下内容添加到文件末尾，根据您的网络环境修改 enp0s3、address、netmask 和 gateway。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<INI>
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).
source /etc/network/interfaces.d/*
# The loopback network interface
auto lo
iface lo inet loopback
# Primary network interface - STATIC IP configuration
auto enp0s3                                # 替换为你的实际网卡接口名
iface enp0s3 inet static
    address 192.168.1.100                  # 你希望分配的 IP 地址
    netmask 255.255.255.0                  # 子网掩码
    gateway 192.168.1.1                    # 默认网关（通常是路由器的 IP）
    dns-nameservers 8.8.8.8 114.114.114.114 # DNS 服务器地址，多个可以用空格隔开

保存并退出：按下 Ctrl + X，然后按 Y 确认保存，最后按 Enter。

1.2.3 应用网络配置
重启网络服务使配置生效：

1
2
<BASH>
sudo systemctl restart networking

1.2.4 检查 IP 地址
验证新的静态 IP 地址是否已成功应用：

1
2
3
4
<BASH>
ip a show enp0s3 # 将 enp0s3 替换为你的网卡接口名
1.2.5 配置 DNS (可选，如果上述配置未生效或需要额外配置)
有时 dns-nameservers 可能不会立即生效。您可以手动编辑 /etc/resolv.conf。
1
2
<BASH>
sudo nano /etc/resolv.conf

添加或修改 DNS 服务器地址：

1
2
3
<INI>
nameserver 8.8.8.8
nameserver 8.8.4.4

保存并退出。

1.3 SSH 服务安装与检查
通过 SSH 远程管理服务器会非常方便。

1.3.1 检查 SSH 服务是否已安装

1
2
<BASH>
dpkg -l | grep openssh-server

1.3.2 安装 SSH 服务
如果未安装，执行安装命令：

1
2
<BASH>
sudo apt install openssh-server

1.3.3 检查 SSH 服务运行状态

1
2
<BASH>
systemctl status ssh

1.3.4 检查 SSH 默认端口 (22)

1
2
<BASH>
ss -tuln | grep 22

1.4 Sudo 权限配置
如果您当前用户没有 sudo 权限，或者想为其他用户配置 sudo 权限，请按照以下步骤操作。

切换到 root 用户：

1
2
<BASH>
su - root

安装 sudo (如果未安装)：

1
2
<BASH>
apt install sudo

将用户添加到 sudo 组 (例如，将名为 ha 的用户添加到 sudo 组)：

1
2
<BASH>
sudo usermod -aG sudo ha

注意：这里的 ha 应该替换为您实际的用户名。如果 Home Assistant 将运行在一个独立的用户下，通常无需将其添加到 sudo 组，除非特定操作需要。我们将在后面创建 homeassistant 用户。

检查是否成功：

1
2
<BASH>
grep sudo /etc/group

1.5 更换软件源 (可选，推荐国内用户使用)
为了加快软件包的下载速度，您可以更换为国内的软件源。

备份原有源文件 (可选，但推荐)：

1
2
<BASH>
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

编辑软件源文件：

1
2
<BASH>
sudo nano /etc/apt/sources.list

清华 TUNA 镜像源示例 (Debian Trixie - Debian 12)：

清空原有内容，或将原有内容注释掉（在行首添加 #），然后粘贴以下内容。

1
2
3
4
5
6
7
8
9
10
<INI>
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie main contrib non-free
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie main contrib non-free
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-updates main contrib non-free
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-updates main contrib non-free
deb https://mirrors.tuna.tsinghua.edu.cn/debian-security trixie-security main contrib non-free
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian-security trixie-security main contrib non-free
# 对于 Debian Testing (trixie)，不推荐 backports。如果你的确有额外需要，可以自行添加。
# deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-backports main contrib non-free
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-backports main contrib non-free

阿里云镜像源示例 (Debian Trixie - Debian 12)：

如果清华源不稳定，您可以尝试阿里云。

1
2
3
4
5
6
7
8
9
10
<INI>
deb http://mirrors.aliyun.com/debian/ trixie main contrib non-free
# deb-src http://mirrors.aliyun.com/debian/ trixie main contrib non-free
deb http://mirrors.aliyun.com/debian/ trixie-updates main contrib non-free
# deb-src http://mirrors.aliyun.com/debian/ trixie-updates main contrib non-free
deb http://mirrors.aliyun.com/debian-security/ trixie-security main contrib non-free
# deb-src http://mirrors.aliyun.com/debian-security/ trixie-security main contrib non-free
# 对于 Debian Testing (trixie)，不推荐 backports。
# deb http://mirrors.aliyun.com/debian/ trixie-backports main contrib non-free
# deb-src http://mirrors.aliyun.com/debian/ trixie-backports main contrib non-free

保存并退出。

更新软件系统：更换源后务必更新。

1
2
<BASH>
sudo apt update

1.6 安装 Python3 及 Pip
Home Assistant Core 基于 Python 运行，需要安装 Python 3 及其包管理工具 Pip。

安装 Python 3：

1
2
<BASH>
sudo apt install python3

安装 pip (Python 3 的 pip 通常是 pip3)：

1
2
<BASH>
sudo apt install python3-pip
  1. Home Assistant Core 安装
    2.1 安装必要依赖
    在安装 Home Assistant 之前，需要安装一些必要的系统依赖。
1
2
3
<BASH>
sudo apt update
sudo apt install -y python3 python3-dev python3-venv python3-pip build-essential libssl-dev libffi-dev

2.2 创建 Home Assistant 专用用户
为了安全和管理方便，Home Assistant 应该运行在一个专用的低权限用户下。

1
2
<BASH>
sudo adduser homeassistant

按照提示设置密码并填写其他信息（可以直接回车跳过）。

2.3 创建并激活 Python 虚拟环境
虚拟环境可以隔离 Home Assistant 及其依赖，避免与系统其他 Python 项目产生冲突。

通常，虚拟环境会存在于 /srv/homeassistant 这样的用户主目录之外的一个公共可写目录中，这符合服务器安装的约定。

创建虚拟环境目录并设置权限：

1
2
3
<BASH>
sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant

切换到 Home Assistant 用户并创建虚拟环境：

1
2
3
<BASH>
sudo su - homeassistant
python3 -m venv /srv/homeassistant

激活虚拟环境：
在 homeassistant 用户下，激活刚刚创建的虚拟环境。

1
2
<BASH>
source /srv/homeassistant/bin/activate

激活后，您的命令行提示符前会显示 (homeassistant)，表示您已进入虚拟环境。

2.4 安装 Home Assistant Core
在激活的虚拟环境中，安装 Home Assistant Core。

1
2
<BASH>
pip install homeassistant

注意：这个过程可能需要一些时间，因为它会下载并安装 Home Assistant Core 及所有依赖。请耐心等待。

2.5 首次启动 Home Assistant
首次安装完毕后，可以尝试启动 Home Assistant 来生成初始配置文件。

1
2
<BASH>
hass

Home Assistant 将会启动并提示您访问 Web 界面进行配置。首次启动可能较慢，因为它需要下载一些必要组件。当您看到类似 Home Assistant has started! 的消息时，表示启动成功。

您可以通过浏览器访问 http://<你的Debian IP地址>:8123 来进行初始设置。

在完成首次设置后，按下 Ctrl + C 停止 Home Assistant 进程。

  1. 配置 Systemd 服务
    为了让 Home Assistant 在系统启动时自动运行，并能通过 systemctl 进行管理，需要配置一个 Systemd 服务。

3.1 创建 Systemd 服务文件
切换回您的管理员用户 (例如，原来的用户或 root)。如果您仍在 homeassistant 用户下，请先执行 exit。

1
2
<BASH>
exit # 如果您是 homeassistant 用户，执行此命令退出

然后创建服务文件：

1
2
<BASH>
sudo nano /etc/systemd/system/homeassistant.service

粘贴以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
<INI>
[Unit]
Description=Home Assistant
After=network-online.target
[Service]
Type=simple
User=homeassistant
Group=homeassistant
ExecStart=/srv/homeassistant/bin/hass -c /home/homeassistant/.homeassistant
RestartForceExitStatus=100
Restart=always
[Install]
WantedBy=multi-user.target

注意：

User 和 Group 确保 Home Assistant 进程以 homeassistant 用户身份运行。
ExecStart 指向虚拟环境中的 hass 可执行文件，并指定配置文件目录为 /home/homeassistant/.homeassistant (Home Assistant 会在这个目录创建 configuration.yaml 等文件)。
保存并退出。

3.2 启动并启用 Home Assistant 服务
重新加载 Systemd 配置：

1
2
<BASH>
sudo systemctl daemon-reload

启动 Home Assistant 服务：

1
2
<BASH>
sudo systemctl start homeassistant.service

设置 Home Assistant 服务开机自启动：

1
2
<BASH>
sudo systemctl enable homeassistant.service

3.3 检查服务状态与日志
检查 Home Assistant 服务状态：

1
2
<BASH>
sudo systemctl status homeassistant.service

实时查看 Home Assistant 日志：
这对于调试问题非常有用。

1
2
<BASH>
sudo journalctl -f -u homeassistant.service

现在，Home Assistant 应该已在后台运行，并会在系统启动时自动启动。您可以通过浏览器访问 http://<你的Debian IP地址>:8123 来管理您的智能家居。

  1. 调试与权限
    4.1 使用 PyPI 镜像源加速安装 (如果之前安装缓慢或失败)
    如果在 pip install homeassistant 步骤遇到下载缓慢或安装失败的问题，可以配置 PyPI 镜像源。

创建 pip 配置目录：

1
2
<BASH>
mkdir -p ~/.pip

创建或编辑 pip 配置文件：

1
2
<BASH>
nano ~/.pip/pip.conf

添加镜像源配置 (以清华源为例)：

1
2
3
<INI>
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

保存并退出。

重新安装 Home Assistant (如果之前安装失败)：

如果仍然遇到 SSL 证书问题，可以尝试添加 –trusted-host 参数。
请注意，使用 –trusted-host 可能会降低安全性，只在信任的源上使用。

1
2
<BASH>
pip install homeassistant -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

安装特定版本的 Home Assistant Frontend (如果需要)：

1
2
<BASH>
pip install home-assistant-frontend==20260107.2 -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

4.2 权限配置
错误的权限配置是常见的问题。

临时宽松权限 (仅用于临时排查问题，不建议长期使用)：
如果您在调试 Home Assistant 访问文件或目录时遇到权限问题，可以临时赋予 /home/homeassistant 目录及其内容所有用户所有权限。

1
2
<BASH>
sudo chmod -R 777 /home/homeassistant

警告：这会赋予所有用户对该目录的完全读写执行权限，存在安全风险。仅用于临时故障排除。

恢复正常权限 (推荐)：
调试完毕后，应恢复为更安全的权限设置。例如，让 homeassistant 用户可读写执行，其他用户只读执行。

1
2
<BASH>
sudo chmod -R 755 /home/homeassistant

确保所有者和组正确：
确保 Home Assistant 配置文件和数据目录的所有者和组是 homeassistant。

1
2
<BASH>
sudo chown -R homeassistant:homeassistant /home/homeassistant

4.3 检查串口设备权限
如果您的 Home Assistant 需要与串口设备 (如 Zigbee 或 Z-Wave 棒) 交互，您可能需要检查并配置这些设备的权限。

查看串口设备列表：

1
2
<BASH>
ls -l /dev/ttyS* /dev/ttyUSB*

如果 homeassistant 用户没有访问这些设备的权限，您需要将其添加到相应的组（通常是 dialout 或 tty 组）。例如，将 homeassistant 用户添加到 dialout 组：

1
2
<BASH>
sudo usermod -aG dialout homeassistant

添加后，需要重启 Home Assistant 服务或重启系统才能使更改生效。

  • TCP单独按钮源码
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
type: button                 # 按钮的类型，此处指定为标准按钮
name: 客厅空调 - 开         # 按钮上显示的名称或文本
icon: file:jz              # 按钮上显示的图标。
                             # "file:jz" 可能表示一个自定义图标，通常存储在Home Assistant的www目录下。
                             # 标准的MDI (Material Design Icons) 图标格式通常是 "mdi:lightbulb" 等。
show_state: false          # 是否在按钮上显示实体（如果按钮关联了实体）的当前状态。
                             # 此处设置为 false，表示不显示状态。
show_icon: true            # 是否在按钮上显示图标。
                             # 此处设置为 true，表示显示图标。
tap_action:                # 定义单击（轻触）按钮时触发的动作
  action: call-service     # 动作类型为调用一个Home Assistant服务
  service: script.send_tcp_command_script # 要调用的服务的名称，这里是一个名为 'send_tcp_command_script' 的自定义脚本。
                                         # 这个脚本可能是用来通过TCP向设备发送命令的。
  data:                    # 传递给上述服务的数据
    ip_address: 192.168.3.116 # 目标设备的IP地址，用于TCP连接
    port_number: 4001        # 目标设备的端口号，用于TCP连接
    command_string: yyyyyyy  # 要通过TCP发送到设备的命令字符串
hold_action:               # 定义长按按钮时触发的动作
  action: more-info        # 动作类型为显示更多信息弹窗。
                             # 如果按钮关联了实体，长按会显示该实体的详细信息和历史记录。


  • RS232单独按钮源码
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
send_rs232_data_script: # 脚本的唯一标识符。通过 service: script.send_rs232_data_script 调用。
  alias: "发送 RS232 数据" # 在 Home Assistant UI 中显示的脚本友好名称。
  description: "一个用于通过串口发送数据并可选读取响应的通用脚本。" # 脚本的描述，方便理解其功能。
  fields: # 定义脚本运行时可以接受的输入参数。这些参数将作为服务数据传递。
    data: # 参数的内部名称，用于在脚本序列中引用。
      name: "要发送的数据" # 在 UI 中显示给用户的参数名称。
      description: "要通过串口发送的字符串或十六进制数据。" # 参数的详细说明。
      required: true # 指示此参数是否为必需。true 表示调用脚本时必须提供。
      example: "PowerOn" # 在 UI 中显示的示例值，帮助用户理解输入格式。
      selector: # 定义在 UI 中此参数的输入控件类型。
        text: # 指定为文本输入类型。
          type: text # 具体的文本输入控件类型。
          multiline: false # 文本输入框是否支持多行。false 表示单行输入。
    port: # 串口路径参数。
      name: "串口路径" # 在 UI 中显示的参数名称。
      description: "串口设备的路径 (例如 /dev/ttyS1 或 /dev/ttyUSB0)。" # 参数说明。
      required: true # 必需参数。
      example: "/dev/ttyS1" # 示例值。
      default: "/dev/ttyS1" # 默认值，如果用户未提供则使用此值。
      selector:
        text: # 文本输入类型。
          type: text
    baudrate: # 波特率参数。
      name: "波特率" # 在 UI 中显示的参数名称。
      description: "串口连接的波特率。" # 参数说明。
      required: true # 必需参数。
      example: 9600 # 示例值。
      default: 9600 # 默认值。
      selector: # 定义数字输入控件。
        number: # 指定为数字输入类型。
          min: 300 # 允许的最小值。
          max: 115200 # 允许的最大值。
          step: 1 # 每次增减的步长。
          mode: box # 数字输入框的显示模式（box 为标准文本框）。
          unit_of_measurement: "bps" # 数字的单位。
    bytesize: # 数据位参数。
      name: "数据位" # 在 UI 中显示的参数名称。
      description: "每个字符的数据位数 (5, 6, 7 或 8)。" # 参数说明。
      required: true # 必需参数。
      default: 8 # 默认值。
      selector: # 定义选择框控件。
        select: # 指定为选择类型。
          options: # 下拉菜单的选项列表。
            - "5"
            - "6"
            - "7"
            - "8"
          mode: dropdown # 选择框的显示模式（dropdown 为下拉菜单）。
    parity: # 校验位参数。
      name: "校验位" # 在 UI 中显示的参数名称。
      description: "奇偶校验设置 ('N' 为无, 'E' 为偶, 'O' 为奇)。" # 参数说明。
      required: true # 必需参数。
      default: "N" # 默认值。
      selector:
        select: # 指定为选择类型。
          options: # 下拉菜单的选项列表，包含标签和实际值。
            - label: "无 (None)" # 在 UI 中显示的选项文本。
              value: "N" # 实际传递的值。
            - label: "偶 (Even)"
              value: "E"
            - label: "奇 (Odd)"
              value: "O"
            - label: "标记 (Mark)"
              value: "M"
            - label: "空格 (Space)"
              value: "S"
          mode: dropdown # 下拉菜单模式。
    stopbits: # 停止位参数。
      name: "停止位" # 在 UI 中显示的参数名称。
      description: "停止位数 (1.0, 1.5 或 2.0)。" # 参数说明。
      required: true # 必需参数。
      default: 1.0 # 默认值。
      selector:
        select: # 指定为选择类型。
          options: # 下拉菜单的选项列表。
            - "1.0"
            - "1.5"
            - "2.0"
          mode: dropdown # 下拉菜单模式。
    timeout: # 读取超时参数。
      name: "读取超时 (秒)" # 在 UI 中显示的参数名称。
      description: "读取响应时的超时时间（秒）。" # 参数说明。
      required: true # 必需参数。
      default: 1.0 # 默认值。
      selector:
        number: # 指定为数字输入类型。
          min: 0.0 # 允许的最小值。
          max: 60.0 # 允许的最大值。
          step: 0.1 # 每次增减的步长。
          mode: slider # 数字输入框的显示模式（slider 为滑块）。
          unit_of_measurement: "s" # 单位。
    is_hex: # 数据是否为十六进制参数。
      name: "数据是十六进制" # 在 UI 中显示的参数名称。
      description: "勾选此项表示要发送的数据应被解释为十六进制字符串。" # 参数说明。
      required: true # 必需参数。
      default: false # 默认值。
      selector:
        boolean: {} # 指定为布尔（开关）类型。
    read_response: # 是否读取响应参数。
      name: "读取响应" # 在 UI 中显示的参数名称。
      description: "勾选此项表示脚本应尝试读取串口的响应数据。" # 参数说明。
      required: true # 必需参数。
      default: false # 默认值。
      selector:
        boolean: {} # 指定为布尔（开关）类型。
    encoding: # 编码方式参数。
      name: "编码方式" # 在 UI 中显示的参数名称。
      description: "当发送数据为字符串时使用的字符编码。" # 参数说明。
      required: true # 必需参数。
      example: "ascii" # 示例值。
      default: "ascii" # 默认值。
      selector:
        select: # 指定为选择类型。
          options: # 下拉菜单的选项列表。
            - "ascii"
            - "utf-8"
            - "latin-1"
            - "gbk"
            - "gb2312"
          mode: dropdown # 下拉菜单模式。

  sequence: # 脚本执行的步骤序列。
    - service: shell_command.send_rs232_command # 调用名为 "send_rs232_command" 的 shell_command 服务。
      data: # 传递给 shell_command 服务的数据。
        # 以下所有参数都使用 Jinja2 模板语法 `{{ parameter_name }}` 来引用 script.fields 中定义的同名参数。
        data: "{{ data }}" # 将脚本接收到的 `data` 参数值传递给 shell_command 的 `data` 参数。
        port: "{{ port }}" # 将脚本接收到的 `port` 参数值传递给 shell_command 的 `port` 参数。
        baudrate: "{{ baudrate }}" # 将脚本接收到的 `baudrate` 参数值传递给 shell_command 的 `baudrate` 参数。
        bytesize: "{{ bytesize }}" # 将脚本接收到的 `bytesize` 参数值传递给 shell_command 的 `bytesize` 参数。
        parity: "{{ parity }}" # 将脚本接收到的 `parity` 参数值传递给 shell_command 的 `parity` 参数。
        stopbits: "{{ stopbits }}" # 将脚本接收到的 `stopbits` 参数值传递给 shell_command 的 `stopbits` 参数。
        timeout: "{{ timeout }}" # 将脚本接收到的 `timeout` 参数值传递给 shell_command 的 `timeout` 参数。
        is_hex: "{{ is_hex | default(false) }}" # 将脚本接收到的 `is_hex` 参数值传递给 shell_command 的 `is_hex` 参数。
                                               # `| default(false)` 表示如果 `is_hex` 未提供，则默认为 `false`。
        read_response: "{{ read_response | default(false) }}" # 将脚本接收到的 `read_response` 参数值传递给 shell_command 的 `read_response` 参数。
                                                              # `| default(false)` 表示如果 `read_response` 未提供，则默认为 `false`。
        encoding: "{{ encoding }}" # 将脚本接收到的 `encoding` 参数值传递给 shell_command 的 `encoding` 参数。


  • 多实体 卡片配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# 这是一个 Lovelace UI 视图或卡片配置的片段。

type: entities # 卡片的类型，这里指定为 "实体卡片"。实体卡片用于显示一个实体列表，每个实体都可以是一个按钮、传感器等。
title: 客厅电视 (输出 1) # 卡片的标题，显示在卡片的顶部。
entities: # 定义卡片中包含的实体列表。
  - type: button # 列表中的第一个实体是一个按钮。
    name: 输入 1 (机顶盒) # 按钮上显示的文本。
    icon: mdi:alarm-light # 按钮上显示的图标。mdi: 前缀表示这是一个 Material Design Icon。
    tap_action: # 定义单击（轻触）按钮时触发的动作。
      action: call-service # 动作类型为调用一个 Home Assistant 服务。
      service: script.send_tcp_command_script # 要调用的服务的名称，这里是一个名为 'send_tcp_command_script' 的自定义脚本。
      data: # 传递给上述服务的数据。
        ip_address: 192.168.3.116 # 目标设备的IP地址，用于TCP连接（可能是一个电视矩阵切换器或IP控制设备）。
        port_number: 4001 # 目标设备的端口号，用于TCP连接。
        command_string: kaixin001 # 要通过TCP发送到设备的命令字符串（可能用于切换到输入1）。
  - type: button # 列表中的第二个实体，也是一个按钮。
    name: 输入 2 (游戏机) # 按钮上显示的文本。
    icon: mdi:gamepad-variant # 按钮图标，表示游戏手柄。
    tap_action: # 单击动作。
      action: call-service # 调用服务。
      service: script.send_tcp_command_script # 调用自定义脚本。
      data: # 传递给服务的数据。
        ip_address: 192.168.3.116 # 目标设备IP地址。
        port_number: 4001 # 目标设备端口号。
        command_string: kaixin002 # 命令字符串，用于切换到输入2。
  - type: button # 列表中的第三个实体，一个按钮。
    name: 输入 3 (蓝光播放器) # 按钮上显示的文本。
    icon: mdi:disc-player # 按钮图标，表示光盘播放器。
    tap_action: # 单击动作。
      action: call-service # 调用服务。
      service: script.send_tcp_command_script # 调用自定义脚本。
      data: # 传递给服务的数据。
        ip_address: 192.168.3.116 # 目标设备IP地址。
        port_number: 4001 # 目标设备端口号。
        command_string: kaixin003 # 命令字符串，用于切换到输入3。
  - type: button # 列表中的第四个实体，一个按钮。
    name: 输入 4 (PC) # 按钮上显示的文本。
    icon: mdi:desktop-tower # 按钮图标，表示台式电脑。
    tap_action: # 单击动作。
      action: call-service # 调用服务。
      service: script.send_tcp_command_script # 调用自定义脚本。
      data: # 传递给服务的数据。
        ip_address: 192.168.3.116 # 目标设备IP地址。
        port_number: 4001 # 目标设备端口号。
        command_string: kaixin004 # 命令字符串，用于切换到输入4。
grid_options: # 这是一个非标准参数，看起来像是在尝试控制卡片内部实体或内容的布局。
              # 在标准的 Home Assistant Entities 卡片中，通常没有 `grid_options` 这个顶级参数。
              # 如果你想控制布局，你可能需要使用 'Grid' 卡片或其他布局卡片（如 'Custom:button-card' 等）
              # 或者将 'entities' 列表放在一个 'Custom:vertical-stack' 或 'Custom:horizontal-stack' 中。
              # 因此，下面的注释是基于猜测其预期功能的。
  columns: 6 # 期望的列数。如果在一个支持网格布局的自定义卡片中使用，表示将内容分成6列。
  rows: auto # 期望的行数。如果在一个支持网格布局的自定义卡片中使用，表示行数自动调整。

  • 多实体 卡片配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 这是一个 Lovelace UI 视图或卡片配置的片段。

type: entities # 卡片的类型，这里指定为 "实体卡片"。实体卡片用于显示一个或多个实体及其状态和/或控件。
entities: # 定义卡片中包含的实体列表。
  - entity: input_select.matrix_source_selector # 列表中的第一个实体。
                                               # `input_select` 是 Home Assistant 中的一个“输入选择器”辅助功能，
                                               # 允许用户从预定义的列表中选择一个值。
                                               # 这里可能用于选择视频矩阵的输入源。
  - entity: input_select.matrix_destination_selector # 列表中的第二个实体。
                                                    # 另一个 `input_select`，可能用于选择视频矩阵的输出目标。
  - entity: script.execute_matrix_switch # 列表中的第三个实体。
                                        # 这是一个脚本实体，通常在 UI 中显示为一个按钮。
                                        # 用户点击这个按钮时，会触发名为 `execute_matrix_switch` 的脚本，
                                        # 该脚本可能会根据上面两个 `input_select` 的当前值来执行矩阵切换操作。
grid_options: # 这是一个非标准参数，通常不会在标准的 Home Assistant Entities 卡片中直接使用。
              # 如果你想控制布局，你可能需要使用 'Grid' 卡片或其他自定义布局卡片（如 'Custom:button-card' 等）
              # 或者将 'entities' 列表放在一个 'Custom:vertical-stack' 或 'Custom:horizontal-stack' 中。
              # 因此，下面的注释是基于猜测其预期功能的。
  columns: 6 # 期望的列数。如果在一个支持网格布局的自定义卡片中使用，表示将内容分成6列。
  rows: auto # 期望的行数。如果在一个支持网格布局的自定义卡片中使用，表示行数自动调整。
  • 复位自动化的实现方法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 示例：放在 automations.yaml 文件中
# 或在 configuration.yaml 文件中的 automation: 部分
- id: '1678901234568' # 这是一个唯一的ID，每个自动化都必须有唯一ID。
                      # 建议使用时间戳或其他确保唯一性的方式。
  alias: '复位测试开关' # 这个自动化的名称，方便你在界面上识别。
  description: '当 input_boolean.test_toggle 打开后立即将其关闭，模拟瞬时按钮行为。'
  trigger:
    - platform: state # 触发平台是“状态变化”
      entity_id: input_boolean.test_toggle # 监听的实体是你的 input_boolean
      from: 'off' # 状态从 'off'
      to: 'on'    # 变为 'on' 时触发
  condition: [] # 复位自动化通常不需要条件，因为无论如何都要复位。
                # 如果有特殊需求，可以在这里添加条件。
  action:
    - service: input_boolean.turn_off # 调用的服务是 input_boolean 域下的 turn_off
      target:
        entity_id: input_boolean.test_toggle # 指定要关闭的 input_boolean 实体
  mode: single # 运行模式：确保自动化在处理完当前触发后，才能再次被触发。
               # 对于复位操作，这个模式足够了，可以防止因快速连续点击导致意外行为。
  • 自动化示例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# automations.yaml (自动化配置文件，通常通过 `configuration.yaml` 引用)

- id: '1678901234567' # 自动化唯一标识符。每个自动化都必须拥有一个不重复的ID。
                      # 建议使用时间戳或其他确保唯一性的字符串。
  alias: '当测试开关打开时执行动作' # 自动化在 Home Assistant 用户界面中显示的友好名称。
  description: '当 input_boolean.test_toggle 从 off 变为 on 时触发' # 自动化的详细描述，说明其主要功能或触发条件。
                                                                    # 方便理解和管理。

  trigger: # 定义触发此自动化的事件或状态变化。可以是一个或多个触发器。
    - platform: state # 触发器平台类型。'state' 意味着当某个实体的状态发生变化时触发。
      entity_id: input_boolean.test_toggle # 监听状态变化的实体ID。这里是之前创建的 `input_boolean`。
      from: 'off' # 实体的旧状态。此自动化只在实体状态从 'off' 变为 'on' 时触发。
                  # 如果省略 'from'，则从任意状态变为 'to' 都会触发。
      to: 'on'    # 实体的新状态。此自动化只在实体状态从 'off' 变为 'on' 时触发。
                  # 如果省略 'to'，则从 'from' 变为任意其他状态都会触发。

  condition: [] # 可选。定义在触发器满足后，动作执行前的附加条件。
                # 只有当所有条件都满足时，自动化才会执行其动作。
                # 此处为空列表 `[]` 表示没有额外条件，只要触发器满足即执行动作。

  action: # 定义当触发器满足且所有条件通过后，自动化将执行的任务列表。
          # 动作可以是一个或多个服务调用、事件发送、场景激活等。
    - service: light.toggle # 示例动作1：调用 Home Assistant 中的一个服务。
                            # 'light.toggle' 服务会切换目标灯光的开关状态（开变关，关变开）。
      data: {} # 传递给服务的数据参数。对于 light.toggle，如果不需要额外的亮度、颜色等参数，可以为空。
      target: # 指定服务操作的目标实体。
        entity_id: light.your_light_id # 目标灯光实体的ID。请将 'light.your_light_id' 替换为
                                       # 你实际 Home Assistant 中灯光实体的ID，例如 `light.living_room_light`。

    - service: persistent_notification.create # 示例动作2：调用 Home Assistant 的通知服务，
                                             # 在 Home Assistant UI 中创建一个持久通知。
      data: # 传递给通知服务的数据。
        message: "测试开关被按下，自动化已触发！" # 通知显示的主要内容。
        title: "自动化通知" # 通知的标题。

  mode: single # 自动化运行模式。定义当自动化被多次快速触发时如何处理。
               # 'single' (默认): 自动化一次只能运行一个实例。如果正在运行中再次被触发，则新的触发会被忽略。
               # 'queued': 新的触发会排队等待当前实例运行完毕。
               # 'restart': 新的触发会中止当前正在运行的实例，并重新开始执行自动化。
               # 'parallel': 允许多个自动化实例同时运行。
               # 对于按钮复位场景，'single' 通常是合适的，以避免同一动作被快速重复执行。

  • 创建脚本实体ID
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# scripts.yaml (这是脚本定义的独立文件，或者，如果直接在 configuration.yaml 中定义，
# 则这些内容将位于 'script:' 键下方)

my_action_script: # 这是脚本的唯一标识符，也作为其实体ID的一部分 (例如：`script.my_action_script`)。
                   # 这个名称必须是唯一的，且遵循 Home Assistant 的实体ID命名规范（小写、无空格、使用下划线）。
  alias: "执行我的动作" # 脚本在 Home Assistant 用户界面中显示的友好名称。
                       # 用户在 Lovelace 界面或服务调用中会看到这个名称。

  sequence: # 定义脚本将按顺序执行的一系列动作。
            # 动作可以是服务调用、事件触发、其他脚本的调用等。
            # 这里的每个 `-` 开头的项都代表一个独立的动作。

    - service: light.toggle # 序列中的第一个动作：调用 Home Assistant 中的一个服务。
                            # `light.toggle` 是一个内置服务，用于切换灯光的开/关状态。
      target: # 指定此服务操作的目标实体。
        entity_id: light.your_light_id # 目标灯光实体的ID。
                                       # 请将 'light.your_light_id' 替换为你实际 Home Assistant 中灯光设备的实体ID。
                                       # 例如：`light.living_room_lamp`。

    - service: persistent_notification.create # 序列中的第二个动作：调用另一个 Home Assistant 服务。
                                             # `persistent_notification.create` 服务会在 Home Assistant 界面中创建一个持久性通知。
      data: # 传递给 `persistent_notification.create` 服务的数据参数。
        message: "脚本被执行，自动化已触发！" # 通知的主体内容，即用户将看到的文本。
        title: "脚本通知" # 通知的标题，会在通知内容的上方显示。

  mode: single # 脚本的运行模式。定义当脚本被多次快速调用时如何处理。
               # `single` (默认): 脚本一次只能运行一个实例。如果正在运行中再次被触发，则新的调用会被忽略。
               # `queued`: 新的调用会排队等待当前实例运行完毕。
               # `restart`: 新的调用会中止当前正在运行的实例，并重新开始执行脚本。
               # `parallel`: 允许多个脚本实例同时运行。
               # 对于通常的按钮或手动触发的动作，`single` 是一个安全且常见的选择，以避免重复执行。
  • 配置文件注释
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
default_config:

homeassistant: # <-- 请确保这一行从文件的最左边开始，前面没有任何空格
  name: 智能会议室
  latitude: 31.230416 # 请替换为你的实际纬度
  longitude: 121.473701 # 请替换为你的实际经度
  elevation: 50 # 请替换为你的海拔高度 (单位：米)
  unit_system: metric
  time_zone: Asia/Shanghai # 请替换为你的实际时区

shell_command:
  send_cmd: "/var/packages/HomeAssistant/target/bin/python3.13 /volume1/@apphome/HomeAssistant/.homeassistant/scripts/send_tcp_command.py \"{{ ip }}\" \"{{ port }}\" \"{{ command }}\""

python_script:     #python_script脚本组件


# 从主题文件夹加载前端主题
frontend:
  themes: !include_dir_merge_named themes
input_number: !include input_numbers.yaml        #专门设计用于表示和允许用户输入一个数值，通常以滑块或步进器形式出现在 UI 中
input_select: !include inputs.yaml               #从预设列表中选择一个选项
input_boolean: !include input_booleans.yaml      #简单的开/关（true/false）开关
automation: !include automations.yaml            #自动化脚本实现
script: !include scripts.yaml                    #脚本执行器
scene: !include scenes.yaml                      #场景

  • HACS集成方法
    首先要先创建一个文件名为custom_components的文件夹给上755的权限
    下载HACS.ZIP
    将下载的文件解压上传至custom_components文件夹下
    文件结果例如 ../custom_components/hacs/ (记得给权限)
    然后就可以在集成中进行添加了。（补充他使用的github的仓库是需要科学访问的，博客中有加速地址可以使用）

  • 自定义图标的集成方法
    首先下载JavaScript脚本file-loader.js
    这里注意了：脚本中定义了路径是在../.homeassistant/www/下面包括存储文件夹svg （注意分配权限）
    在仪表盘中的资源中引入脚本，这里说明资源引入是有默认路径的/local/file-loader.js（文件路径www以前的都使用local来替换）
    引入脚本是需要重新启动的。

  • 隐藏侧边栏和页眉
    使用的是kiosk_mode插件 下载地址
    从最新版本下载kiosk-mode.js 文件www并将其放置在您的文件夹中
    添加资源

  1. 前往“设置 > 控制面板”
  2. 点击右上角的三个点，然后点击“资源”
  3. 点击屏幕右下角的“添加资源”
  4. 添加您之前下载的文件的 URL（例如 /local/kiosk-mode.js?v=1.0.0）
  5. 请确保在 URL 末尾添加正确的版本号（例如 ?v=1.0.0），这样 Home Assistant 才会加载最新版本，而不是缓存中的版本。
1
2
3
4
5
6
7
8
kiosk_mode:
  hide_header: true
  hide_sidebar: true
  user_settings:
    - users:
        - yz029
      hide_header: true
      hide_sidebar: true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
?edit=1直接编辑
?kiosk隐藏页眉和侧边栏
?hide_header仅隐藏标题
?hide_sidebar仅隐藏侧边栏
?hide_menubutton隐藏侧边栏菜单按钮
?hide_notifications隐藏通知入口点
?hide_account隐藏帐户图标
?hide_add_to_home_assistant隐藏“添加到 Home Assistant”溢出
?hide_search隐藏搜索图标
?hide_assistant隐藏助手图标
?hide_overflow隐藏右上角菜单
?block_overflow阻止右上角溢出菜单的鼠标交互
?hide_refresh在 Lovelace YAML 模式下隐藏右上角菜单中的“刷新”按钮
?hide_unused_entities在 Lovelace YAML 模式下隐藏右上角菜单中的“未使用实体”按钮
?hide_reload_resources在 Lovelace YAML 模式下隐藏右上角菜单中的“重新加载资源”按钮
?hide_edit_dashboard隐藏右上角菜单中的“编辑仪表盘”按钮
?block_mouse完全阻挡鼠标
?block_context_menu防止打开右键菜单
?hide_dialog_header_breadcrumb_navigation隐藏更多信息对话框标题上方的面包屑导航
?hide_dialog_header_history隐藏“更多信息”对话框标题中的“历史记录”图标
?hide_dialog_header_settings隐藏“更多信息”对话框标题中的“设置”图标
?hide_dialog_header_overflow隐藏更多信息对话框标题栏右上角的溢出菜单
?hide_dialog_header_action_items隐藏更多信息对话框标题中的所有操作项。
?hide_dialog_history隐藏“更多信息”对话框中的“历史记录”部分
?hide_dialog_history_show_more隐藏“更多信息”对话框“历史记录”部分中的“显示更多”链接
?hide_dialog_logbook在更多信息对话框中隐藏“日志”部分
?hide_dialog_logbook_show_more隐藏“日志”部分中“显示更多”链接（位于“更多信息”对话框的“日志”部分）
?hide_dialog_attributes隐藏“更多信息”对话框中的“属性”部分
?hide_dialog_media_actions隐藏媒体播放器实体“更多信息”对话框中的操作块
?hide_dialog_update_actions隐藏更新实体的“更多信息”对话框中的操作块
?hide_dialog_camera_actions隐藏相机实体更多信息对话框中的操作模块
?hide_dialog_timer_actions隐藏计时器实体“更多信息”对话框中的操作块
?hide_dialog_climate_actions隐藏气候实体“更多信息”对话框中的所有操作
?hide_dialog_climate_temperature_actions在气候实体的“更多信息”对话框中隐藏温度控制操作
?hide_dialog_climate_settings_actions隐藏气候实体“更多信息”对话框中的模式和预设操作
?hide_dialog_light_actions隐藏轻型实体更多信息对话框中的所有操作
?hide_dialog_light_control_actions隐藏轻型实体更多信息对话框中的控制操作
?hide_dialog_light_color_actions隐藏灯光实体更多信息对话框中的收藏颜色操作
?hide_dialog_light_settings_actions隐藏轻型实体更多信息对话框中的设置操作
  • 配置Nginx做反向代理
  1. 更新系统包列表和升级已安装的包
1
2
sudo apt update
sudo apt upgrade -y
  1. 安装 Nginx
1
sudo apt install nginx -y
  1. 检查 Nginx 状态（可选）
1
2
sudo systemctl status nginx

你应该看到 active (running)。

  1. 配置 Nginx 的反向代理
    现在我们需要创建 Nginx 配置文件来指向

  2. 禁用默认的 Nginx 站点（可选，但推荐）

1
sudo rm /etc/nginx/sites-enabled/default

如果你的 Nginx 还需要服务其他网站，则跳过此步骤。
5. 创建新的 Nginx 配置文件

1
sudo nano /etc/nginx/sites-available/homeassistant
  1. 将以下内容粘贴到文件中
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# HTTP 配置（推荐作为 HTTPS 的重定向）
server {
    listen 80;
    server_name 192.168.3.200; # 替换为你的域名和/或服务器IP
    
    # 如果你计划使用 HTTPS，可以取消注释下面两行进行强制重定向
    # return 301 https://$host$request_uri; 
    
    location / {
        # 代理到你的  实例
        proxy_pass http://192.168.3.200:8123; # 替换为你的  的内部 IP 和端口

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 设置一些重要的头部信息，让 Home Assistant 知道真实的客户端 IP 等
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 避免 Nginx 缓存代理响应
        proxy_cache_bypass $http_upgrade;
        proxy_no_cache $http_upgrade;

        # 调整超时设置
        proxy_connect_timeout 75s;
        proxy_send_timeout 75s;
        proxy_read_timeout 75s;
    }
}
  1. 激活新的 Nginx 配置
1
sudo ln -s /etc/nginx/sites-available/homeassistant /etc/nginx/sites-enabled/
  1. 测试 Nginx 配置语法
1
sudo nginx -t

如果显示 syntax is ok 和 test is successful，则表示没有语法错误
9. 重新加载 Nginx 服务

1
2
3
sudo systemctl reload nginx
# 或者如果 reload 失败，使用 restart
# sudo systemctl restart nginx
  1. 配置 信任代理
1
2
3
4
5
6
7
8
9
10
11
12
# 在 configuration.yaml
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1       # Nginx 和 HA 在同一台机器上时
    - 192.168.3.200   # 假设 Nginx 服务器的 IP 是这个（如果是另一台机器）
    # - 172.30.33.0/24  # HassOS/Supervised 可能需要这个，或者 Docker 桥接网络
    # - 10.0.0.0/8      # 如果你使用更大的内部网络段
  # 如果你希望限制只有 Nginx 可以访问 HA，可以启用 ip_filter
  # ip_filter:
  #   - 127.0.0.1
  #   - 192.168.3.200 # Nginx 服务器的 IP
  1. 测试 Nginx 配置并重新加载
1
2
sudo nginx -t
sudo systemctl reload nginx
  1. 检查是否已启用
1
2
3
4
5
6
7
sudo systemctl is-enabled nginx
#如果输出 enabled，则表示 Nginx 已经设置为开机自启动，你无需做任何事情
#如果输出 disabled，则表示它未设置开机自启动
#开机自启动 sudo systemctl enable nginx

#查看服务状态（会显示更多信息，包括是否开机自启动）
sudo systemctl status nginx

仪表盘背景设定（单独设定不跟主题）

  1. 创建存储背景照片的文件夹 例如：ing (给权限)
  2. 将背景图片上传至文件夹 （文件夹都是在www/ing 这种结果）
  3. 在仪表盘进行原始yaml编辑，头部位置插入
1
2
3
4
5
6
7
background: center / cover no-repeat url('/local/images/my_background.jpg') fixed

#center: 图片居中显示。
#/ cover: 图片会覆盖整个背景区域，可能会裁剪部分图片。
#no-repeat: 图片不重复。
#url('/local/images/my_background.jpg'): 指定图片的路径。images/my_background.jpg 是你放置在 /config/www/ 目录下的图片。
#fixed: 背景图片在滚动时保持固定。你可以将其删除以让背景随内容滚动

按钮样式编辑

安装可编辑的插件：card-mod 这对于你想对特定按钮或卡片进行精确样式控制非常有用

  • 安装好插件找不到路径的使用
1
find /home/homeassistant/.homeassistant -name "文件名称"

请将以下内容添加到您的configuration.yaml文件中并重启

添加仪表盘资源里：

1
2
3
4
5
6
7
frontend:
  extra_module_url:
    - /[card_mod resource URL]
#示例：
frontend:
  extra_module_url:
    - /hacsfiles/lovelace-card-mod/card-mod.js?hacstag=12345678901

可以在任何卡片或实体中添加 style 属性来注入 CSS

示例：修改一个实体按钮的背景和圆角

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
type: entities
entities:
  - entity: light.living_room_lights
    name: 客厅灯
    # 使用 card-mod 注入 CSS
    card_mod:
      style: |
        :host { # 针对当前实体行
          --paper-item-icon-color: #f7d23d; /* 未激活图标颜色 */
          --paper-item-icon-active-color: #FFC107; /* 激活图标颜色 */
          --mdc-ripple-color: rgba(255, 193, 7, 0.4); /* 点击波纹颜色 */
          background: linear-gradient(to right, #444, #222); /* 按钮背景渐变 */
          border-radius: 10px; /* 边框圆角 */
          box-shadow: 0px 2px 5px rgba(0,0,0,0.3); /* 默认阴影 */
        }
        :host(:hover) { /* 悬停时的效果 */
          box-shadow: 0px 4px 8px rgba(0,0,0,0.5); /* 悬停时阴影加深 */
          transform: translateY(-2px); /* 悬停时轻微上浮 */
          transition: all 0.2s ease-in-out; /* 过渡动画 */
        }
        :host(.paper-item.ha-paper-item.style-scope.hui-entity-row) { /* 更具体的选择器 */
          margin: 5px; /* 增加行之间的间距 */
        }

示例 2：修改一个自定义 button-card 的样式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
type: custom:button-card
entity: switch.fan
name: 风扇
icon: mdi:fan
color: auto
# button-card 自身提供的样式选项
show_state: true
styles:
  card:
    - background-color: '#282C34' # 背景色
    - border-radius: 12px # 圆角
    - box-shadow: "0px 2px 4px rgba(0,0,0,0.3)" # 默认阴影
  name:
    - font-size: 14px
  state:
    - font-size: 12px
# 使用 card-mod 针对更复杂的悬停/激活效果或内部元素
card_mod:
  style: |
    .card-content { /* button-card 的内容区域 */
      padding: 10px;
    }
    ha-icon { /* 图标 */
      --mdc-icon-size: 28px;
    }
    :host(:hover) { /* 悬停效果 */
      box-shadow: 0px 6px 12px rgba(0,0,0,0.5);
      transform: translateY(-3px);
      transition: all 0.3s ease-in-out;
    }
    :host(.active) { /* 激活状态的额外样式，如果 button-card 不够用 */
      border: 2px solid var(--mdc-theme-primary);
    }

扩展内容（制作卡片模板使用decluttering-card插件灵活性高）

针对重复性高的按钮卡片非常实用

优点：

  • 非常灵活： 可以定义任意数量的变量，替换卡片配置中的任何部分。
  • 易于阅读和维护： 模板集中定义，实例化时参数清晰。
  • 适用于任何卡片类型： 不仅仅是按钮，任何 Lovelace 卡片配置都可以模板化。

步骤 A: 定义模板 (通常在 ui-lovelace.yaml 或一个单独的 lovelace/templates.yaml 文件中)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# ui-lovelace.yaml (或你用 !include 包含的某个文件)
decluttering_templates:
  # 定义一个名为 'my_icon_button_template' 的模板
  my_icon_button_template:
    card:
      type: button
      entity: "[[entity]]"        # 这是一个变量，实例化时会被替换
      icon: "[[icon]]"            # 这是一个变量
      name: "[[name]]"            # 这是一个变量
      show_name: true
      show_state: false
      tap_action:
        action: toggle
      hold_action:
        action: more-info
      # 如果你希望按钮紧凑，可以像之前那样添加 card_mod 样式
      card_mod:
        style:
          ha-card$:
            mwc-button:
              padding: 0px !important;
              margin: 0px !important;
              min-width: 0px !important;
              min-height: 0px !important;
              background: transparent !important;
              box-shadow: none !important;
              --mdc-button-horizontal-padding: 0;
              --mdc-button-height: auto;
              --mdc-button-min-width: 0;
            ha-icon:
              width: 36px !important; # 设置图标的实际大小
              height: 36px !important;
              --mdc-icon-size: 36px;
          .: |
            ha-card {
              padding: 0 !important;
              margin: 0 !important;
              background: transparent !important;
              box-shadow: none !important;
              border-radius: 0 !important;
              width: fit-content;
              height: fit-content;
              display: flex;
              justify-content: center;
              align-items: center;
              overflow: visible !important;
            }

  # 你可以定义另一个模板，例如只显示图标的更小按钮
  my_mini_icon_button_template:
    card:
      type: button
      entity: "[[entity]]"
      icon: "[[icon]]"
      name: "" # 不显示名称
      show_name: false
      show_state: false
      tap_action:
        action: toggle
      # 这里的 card_mod 样式可能需要调整以适应更小的图标
      card_mod:
        style:
          ha-card$:
            mwc-button:
              padding: 0px !important;
              margin: 0px !important;
              min-width: 0px !important;
              min-height: 0px !important;
              background: transparent !important;
              box-shadow: none !important;
              --mdc-button-horizontal-padding: 0;
              --mdc-button-height: auto;
              --mdc-button-min-width: 0;
            ha-icon:
              width: 24px !important; # 更小的图标
              height: 24px !important;
              --mdc-icon-size: 24px;
          .: |
            ha-card {
              padding: 0 !important;
              margin: 0 !important;
              background: transparent !important;
              box-shadow: none !important;
              border-radius: 0 !important;
              width: fit-content;
              height: fit-content;
              display: flex;
              justify-content: center;
              align-items: center;
              overflow: visible !important;
            }

步骤 B: 在你的 Lovelace 视图中使用模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Lovelace UI 视图中的使用
- type: custom:decluttering-card
  template: my_icon_button_template # 引用上面定义的模板
  variables:
    entity: light.kitchen_light    # 为 [[entity]] 变量赋值
    icon: mdi:lightbulb-on         # 为 [[icon]] 变量赋值
    name: 厨房灯

- type: custom:decluttering-card
  template: my_icon_button_template
  variables:
    entity: switch.fan             # 更换实例
    icon: mdi:fan
    name: 风扇

- type: custom:decluttering-card
  template: my_mini_icon_button_template # 使用另一个模板
  variables:
    entity: cover.garage_door
    icon: mdi:garage

卡片GUI效果

  • 使用 custom:button-card 和 card-mod 实现立体感和动态效果

你的 PNG 图片本身就需要带有一定的立体感。这意味着：

光影效果： 在设计软件（如 Photoshop, Figma, Sketch, Blender 等）中，为你的按钮元素添加光源，模拟出高光和阴影。这比纯平的颜色更能产生三维感。
透明背景： 确保图片背景是透明的（.png 格式支持），这样按钮的边缘就不会有生硬的方块背景。
不同状态的图片：
默认状态 (Off/Inactive): 例如，一个不发光的灯泡图标。
激活状态 (On/Active): 例如，一个发光的灯泡图标。
按压状态 (Pressed): 可选，但如果你想追求极致，可以制作一个略微“凹陷”或“被压扁”的图片。

  • 图片存储位置： 将你的 PNG 图片存放在 /local/images/light_off.png （没有就自建）

两个插件：

custom:button-card： 强大的自定义按钮卡片。
card-mod： 允许在 Lovelace UI 中应用自定义 CSS。

下面是一个详细的 custom:button-card 配置示例，它使用了 PNG 图片、状态切换、阴影和交互动画。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
type: custom:button-card
entity: light.your_light_entity # 你的灯光实体
name: 酷炫灯泡
# 这会使整个卡片区域变得紧凑，只包含图片
show_name: true
show_state: false
show_icon: false # 我们将通过图片来显示图标，而不是ha-icon
tap_action:
  action: toggle # 点击按钮会切换灯光状态

# 定义按钮的样式
styles:
  card: # 针对整个按钮卡片容器
    - border-radius: 15px # 圆角
    - background: transparent # 背景透明，假设你的图片已经包含了背景或你想用Lovelace的背景
    - box-shadow: none # 默认没有阴影，我们会在内部元素上添加
    - width: 100px # 按钮的宽度
    - height: 100px # 按钮的高度
    - display: flex
    - justify-content: center
    - align-items: center
    - overflow: visible # 允许阴影超出卡片边界

  img_cell: # 专门针对图片容器的样式
    - justify-content: center
    - align-items: center
    - padding: 0px # 移除默认内边距

  name: # 名字的样式
    - font-size: 14px
    - color: var(--text-color, white)
    - position: absolute # 将名字定位在图片下方
    - bottom: 10px # 距离底部10px
    - z-index: 2 # 确保名字在图片上方

# 配置不同状态下的图片和样式
state:
  - value: "on"
    styles:
      card:
        # 当实体为 "on" 时，卡片可能有一个更亮的背景或不同的阴影
        - background: rgba(255, 255, 0, 0.1) # 激活状态下发光效果
        - box-shadow: 0px 0px 15px 5px rgba(255, 255, 0, 0.7) # 激活状态下发光阴影
        - transition: all 0.3s ease-in-out # 状态切换动画
    img_src: /local/images/light_on.png # 激活状态的 PNG 图片
  - value: "off"
    styles:
      card:
        # 默认关闭状态，较暗的阴影
        - background: transparent
        - box-shadow: 0px 5px 10px rgba(0, 0, 0, 0.5) # 默认的立体阴影
        - transition: all 0.3s ease-in-out
    img_src: /local/images/light_off.png # 关闭状态的 PNG 图片

# 使用 card_mod 注入更精细的 CSS 效果
# 这允许我们直接控制 button-card 内部的元素，实现 hover/active 效果
card_mod:
  style: |
    /* 针对 button-card 的根元素 */
    :host {
      cursor: pointer; /* 鼠标悬停时显示手型 */
    }

    /* 针对 img 元素，使其适应容器并添加交互效果 */
    .img-container img {
      width: 80px; /* 控制图片大小 */
      height: 80px;
      object-fit: contain; /* 图片在容器内完整显示 */
      transition: all 0.2s ease-out; /* 图像本身的动画过渡 */
      /* 默认的图像阴影，增加立体感 */
      filter: drop-shadow(3px 3px 5px rgba(0, 0, 0, 0.6));
    }

    /* 鼠标悬停 (hover) 效果 */
    :host button-card-template:hover .img-container img {
      transform: translateY(-3px) scale(1.05); /* 向上浮动并稍微放大 */
      filter: drop-shadow(5px 5px 8px rgba(0, 0, 0, 0.7)); /* 阴影更明显 */
    }

    /* 鼠标点击 (active/press) 效果 */
    :host button-card-template:active .img-container img {
      transform: translateY(1px) scale(0.98); /* 向下轻微按压并缩小 */
      filter: drop-shadow(1px 1px 2px rgba(0, 0, 0, 0.4)); /* 阴影变浅，模拟凹陷 */
    }

    /* 针对整个按钮容器（card_main）的 hover 效果 */
    :host button-card-template:hover .card_main {
      box-shadow: 0px 8px 15px rgba(0, 0, 0, 0.6); /* 整个卡片容器的阴影变化 */
    }

    /* 如果你需要对 name 元素也添加 hover 效果 */
    :host button-card-template:hover .name {
      color: var(--primary-color); /* 悬停时名称颜色变化 */
    }

复杂卡片模板化

  • 示例模板定义 (假设你的模板名为 my_animated_image_button)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# 文件: ui-lovelace.yaml 或 lovelace/templates.yaml
decluttering_templates:
  my_animated_image_button:
    card: # 这是模板化卡片的根，下面是你完整的卡片配置
      type: custom:button-card
      entity: "[[entity]]" # 替换为变量
      name: "[[name]]"     # 替换为变量

      show_name: true
      show_state: false
      show_icon: false
      tap_action:
        action: toggle
      hold_action:
        action: more-info # 增加长按功能

      styles:
        card:
          - border-radius: 15px
          - background: transparent
          - box-shadow: none
          - width: "[[size]]px" # 按钮宽度，可作为变量
          - height: "[[size]]px" # 按钮高度，可作为变量
          - display: flex
          - justify-content: center
          - align-items: center
          - overflow: visible
        img_cell:
          - justify-content: center
          - align-items: center
          - padding: 0px
        name:
          - font-size: 14px
          - color: var(--text-color, white)
          - position: absolute
          - bottom: 10px
          - z-index: 2

      state:
        - value: "on"
          styles:
            card:
              - background: rgba(255, 255, 0, 0.1)
              - box-shadow: 0px 0px 15px 5px rgba(255, 255, 0, 0.7)
              - transition: all 0.3s ease-in-out
          img_src: "[[image_on]]" # 激活状态图片，替换为变量
        - value: "off"
          styles:
            card:
              - background: transparent
              - box-shadow: 0px 5px 10px rgba(0, 0, 0, 0.5)
              - transition: all 0.3s ease-in-out
          img_src: "[[image_off]]" # 关闭状态图片，替换为变量

      card_mod:
        style: |
          :host {
            cursor: pointer;
          }
          .img-container img {
            width: calc([[size]]px * 0.8); /* 图片大小基于按钮尺寸变量 */
            height: calc([[size]]px * 0.8);
            object-fit: contain;
            transition: all 0.2s ease-out;
            filter: drop-shadow(3px 3px 5px rgba(0, 0, 0, 0.6));
          }
          :host button-card-template:hover .img-container img {
            transform: translateY(-3px) scale(1.05);
            filter: drop-shadow(5px 5px 8px rgba(0, 0, 0, 0.7));
          }
          :host button-card-template:active .img-container img {
            transform: translateY(1px) scale(0.98);
            filter: drop-shadow(1px 1px 2px rgba(0, 0, 0, 0.4));
          }
          :host button-card-template:hover .card_main {
            box-shadow: 0px 8px 15px rgba(0, 0, 0, 0.6);
          }
          :host button-card-template:hover .name {
            color: var(--primary-color);
          }

  • 在 Lovelace UI 中使用模板： 现在，你可以在你的 Lovelace 视图中引用这个模板，并为这些变量提供具体的值
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Lovelace UI 视图中的使用
- type: horizontal-stack
  cards:
    - type: custom:decluttering-card
      template: my_animated_image_button # 引用上面定义的模板
      variables: # 为模板中的变量赋值
        entity: light.kitchen_light
        name: 厨房灯
        size: 100
        image_on: /local/images/light_on.png
        image_off: /local/images/light_off.png

    - type: custom:decluttering-card
      template: my_animated_image_button
      variables:
        entity: switch.fan_light
        name: 风扇灯
        size: 120 # 这个按钮大一点
        image_on: /local/images/fan_on.png
        image_off: /local/images/fan_off.png

    - type: custom:decluttering-card
      template: my_animated_image_button
      variables:
        entity: switch.power_socket
        name: 插座
        size: 80 # 这个按钮小一点
        image_on: /local/images/socket_on.png
        image_off: /local/images/socket_off.png