2025.3.4
首页 ▸ Installation ▸

ODROID

安装 Home Assistant 操作系统

如果您想轻松开始使用 Home Assistant 或者几乎没有 Linux 经验，请遵循本指南。

建议的硬件

您需要一些东西来开始安装 Home Assistant。以下链接指向 Ameridroid。如果您不在美国，应该可以在您所在国家的网店找到这些商品。

要开始使用，我们建议使用 ODROID-N2+，这是为我们的 Home Assistant Blue 提供动力的主板，或者 ODROID-M1。

如果不可用，我们也推荐 ODROID-C4。

Home Assistant 套装（美国市场）：

这些套装预装了 Home Assistant。

未预装 Home Assistant 的版本：

这些是联盟链接。我们通过本文中的链接获得购买佣金。

将映像写入您的启动介质

  1. 注意：此过程将把 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 写入您的设备。

    • 这意味着您将丢失所有数据以及之前安装的操作系统。
    • 在执行下一步之前备份您的数据。

  2. 将 Home Assistant 启动介质（eMMC module or SD card）连接到您的计算机。

    如果您使用的是 ODROID-M1，请注意不支持从 NVMe 启动。如果您想从 eMMC 启动，请在安装映像之前更新固件。

    如果您使用的是 Home Assistant Blue 或 ODROID-N2+，您可以直接连接您的设备。

    如果您使用的是 ODROID-M1S，您需要按照本指南将您的设备启动到 UMS 模式。

  3. 下载并启动 Balena Etcher。在 Windows 上，您可能需要以管理员权限运行它。

  4. 将映像下载到您的计算机。

    • 复制映像的 URL。
    • 如果下面有多个链接，请确保选择适合您 ODROID 版本的正确链接。
https://github.com/home-assistant/operating-system/releases/download//haos_odroid-n2-.img.xz

指南：使用 OTG-USB 刷写 ODROID-N2

https://github.com/home-assistant/operating-system/releases/download//haos_odroid-n2-.img.xz

指南：使用 OTG-USB 刷写 ODROID-N2

https://github.com/home-assistant/operating-system/releases/download//haos_odroid-c2-.img.xz

https://github.com/home-assistant/operating-system/releases/download//haos_odroid-c4-.img.xz

https://github.com/home-assistant/operating-system/releases/download//haos_odroid-m1-.img.xz

https://github.com/home-assistant/operating-system/releases/download//haos_odroid-m1s-.img.xz

指南：使用 OTG-USB 刷写 ODROID-M1S

选择并复制 URL 或使用悬停时出现的“复制”按钮。

  1. 将 URL 粘贴到浏览器中开始下载。
  2. 解压刚刚下载的文件。
  3. 选择 从文件刷写 并选择刚刚解压的镜像。
    • 不要使用 从 URL 刷写。在某些系统上无法正常工作。

Etcher 软件截图，显示从 URL 刷写已选择。 8. 选择目标。 Etcher 软件截图，显示选择目标按钮高亮。 9. 选择要用于安装的启动介质 (eMMC module or SD card)。 Etcher 软件截图，显示可用的目标。 10. 选择 刷写！ 开始写入镜像。

  • 如果操作失败，请解压 .xz 文件并重试。 Etcher 软件截图，显示刷写按钮高亮。
  • 当 Balena Etcher 完成镜像写入后，您将看到确认信息。 Etcher 软件截图，显示安装已完成。

启动您的 ODROID

  1. 插入刚刚创建的启动介质 (eMMC module or SD card)。

  2. 插入连接到网络和互联网的以太网电缆并启动系统。

    • 注意：需要互联网连接，因为新安装的 Home Assistant OS 尚未包含所有 Home Assistant 组件。它会在首次启动时下载最新版本的 Home Assistant Core。

  3. 在桌面系统的浏览器中，几分钟后您就可以通过 homeassistant.local:8123 访问您的新 Home Assistant。

Note

如果您运行的是较旧的 Windows 版本或具有更严格的网络配置，您可能需要通过 homeassistant:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您的 ODROID 的 IP 地址）访问 Home Assistant。

帮助我们改进 Home Assistant

您刚刚安装了 Home Assistant 吗？Home Assistant 团队希望与您交流，了解安装过程的情况。

立即帮助

安装并可以访问 Home Assistant 操作系统后，您可以继续完成入门设置。

  Onboarding

刷写 ODROID-N2+

可以通过将设备直接通过主板前面的 USB-OTG 连接到计算机，来将 Home Assistant 刷写到 ODROID-N2+。该设备包含 Petitboot 引导加载程序，使 ODROID-N2+ 的存储可以显示为 USB 驱动器。

所有这些说明在 ODROID-N2（非加版）上也同样适用。

你将需要的工具

要使用 Petitboot 和 OTG-USB 刷写你的 eMMC，你需要以下物品：

  • HDMI 电缆和显示器
  • USB 键盘
  • USB 2.0 到 micro-USB 电缆
  • 如果你的主板是 Home Assistant Blue：No.2 内六角工具以打开机箱

启用 SPI 引导模式

要启用 SPI 引导模式：

  1. 拔掉电源线，关闭 ODROID-N2+。

  2. 拆下机壳。

    拆下机壳的照片

  3. 找到引导模式的切换开关，并将其从 MMC 切换到 SPI。

    SPI 切换开关的照片

  4. 通过位于主板前面的 USB-OTG 端口将 ODROID-N2+ 直接连接到你的计算机。

  5. 将 USB 键盘和显示器（使用 HDMI）连接到你的 ODROID-N2+。

  6. 插上电源线以打开 ODROID-N2+。

启用 USB 驱动器模式

在 ODROID-N2+ 设置为 SPI 引导模式并开机后，它将引导进入一个终端。要启用 USB 驱动器模式：

  1. 从菜单中选择 Exit to shell。

    退出到 shell

Note

使用命令行时，可能会返回以下消息： can't access tty; job control turned off. 您可以安全地忽略此消息并继续安装。

  1. 在控制台使用以下命令确认存储设备节点：

    ls /dev/mmc*

  2. 使用 ums 命令（USB 大容量存储模式）将 ODROID-N2+ 的存储设备设置为大容量存储设备。 这将配置 ODROID-N2+ 和 OTG 作为读卡器：

    ums /dev/mmcblk0

刷写 Home Assistant

  1. 通过 ODROID-N2+ 前面的 micro-USB 端口将 ODROID-N2+ 连接到你的 PC。

  2. 当 ODROID-N2 被识别为 USB 连接的存储设备时，你可以使用 Etcher 刷写 eMMC。

    • 使用最新稳定版本的 Home Assistant OS，适用于 ODROID-N2+ (haos_odroid-n2-.img.xz)。
    • 在 Balena 中，使用 Flash from file。 Flash from URL 在所有系统上都无法正常工作。

  3. 刷写过程完成后，从 PC 上断开 ODROID-N2+。

    • 拔掉电源线。
    • 拔掉 USB 和 HDMI 电缆。
    • 确保将引导模式开关切换回 MMC。

  4. 将 ODROID 放回其机壳中。

  5. 通过以太网线将 ODROID-N2+ 连接到网络，确保有互联网访问，并插上电源。

  6. 如果你的路由器支持 mDNS，你可以通过 http://homeassistant.local:8123 访问你的安装。

    • 如果你的网络不支持 mDNS，你必须使用 ODROID-N2+ 的 IP 地址，而不是 homeassistant.local。例如， http://192.168.0.9:8123。
    • 你应该能够从路由器的管理员界面找到 ODROID-N2+ 的 IP 地址。

  7. 继续进行 入门。

刷写 ODROID-M1S

Home Assistant 可以通过将设备直接连接到计算机的主板前面的 USB-OTG 端口来刷写到 ODROID-M1S。 与其他 ODROID 板不同，M1S 没有可选的 eMMC 模块插槽。它也没有单独的闪存芯片来存储专用的引导加载程序。 相反，M1S 拥有一个内置的 64GB eMMC，直接焊接在主板上，默认存储一个引导加载程序。本指南将向您展示如何将 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more] 安装到内置的 eMMC。

警告： 安装 Home Assistant OS 会将 eMMC 上的固件和 SPL 替换为 Home Assistant OS 提供的主线版本。因此，无法再使用带有 EMMC2UMS 镜像的 SD 卡，因为当前（2024年2月）主线 SPL 与 EMMC2UMS 镜像中的 U-Boot 不兼容。这对标准使用没有问题，只是在您想返回 Hardkernel 提供的操作系统时会变得更加复杂（请参见 HK Recovery）。**

您将需要的东西

要通过 USB-OTG 刷写您的 eMMC，您将需要以下物品：

  • 一张小 SD 卡
  • 另一台计算机
  • USB 2.0 至 micro-USB 线缆
  • 特别的 Hardkernel eMMC 转 USB 大容量存储镜像

启动到大容量存储模式

（这些步骤与官方 Hardkernel wiki 页面相同。）

  1. 下载 ODROID-M1S_EMMC2UMS.img。
  2. 使用 balena Etcher 或其他工具将 UMS 实用程序刷写到 SD 卡上。
    • 使用 从文件刷写。从 URL 刷写 在所有系统上并不适用。 （balena Etcher 会抱怨刷写过程中出现了问题。您可以忽略此消息）
  3. 将 SD 卡插入到您的 ODROID-M1S 中并启动。

刷写 Home Assistant M1S

  1. 下载用于 ODROID-M1S 的最新稳定版本的 Home Assistant OS。
  2. 除了要刷写的 HAOS 镜像（M1S 而非 N2+ 版本），您可以按照 N2+ 的逐步刷写指南 这里。

HK Recovery

如果您想将 M1S 恢复到 Hardkernel 的初始状态，您将需要恢复 HK 的引导加载程序。 重新刷写 eMMC 以安装您选择的操作系统的可靠方法是使用 Home Assistant OS 刷写 EMMC2UMS 镜像，这将 ODROID-M1S 转换为 USB 大容量存储设备。刷写完 EMMC2UMS 镜像后，您可以再次刷写任何操作系统。您需要一个 micro USB 线缆将 ODROID-M1S 连接到计算机。

注意：这些命令将使您当前的 Home Assistant OS 安装无法启动！

使用本地终端（HDMI/键盘）访问系统控制台。在 Home Assistant CLI（命令行）中，输入 login 进入根 shell，并使用 curl 下载一个镜像并将其 dd 到 eMMC 块设备中：

curl https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img | dd of=/dev/mmcblk0

这样，设备将在下次启动时以 UMS 模式启动，SD 卡被移除。请按照 从 PC 通过 USB 安装 来安装不同的操作系统。

安装 Home Assistant Container

以下说明适用于在您自己管理的容器环境中安装 Home Assistant ContainerHome Assistant Container 是 Home Assistant Core 的独立容器化安装。任何 OCI 兼容的运行时都可以使用，但文档重点是 Docker。 [Learn more]。可以使用任何 OCI 兼容的运行时，但本指南将重点介绍使用 Docker 进行安装。

Note

此安装方法无法使用附加组件。如果您想使用附加组件，则需要使用其他安装方法。推荐的方法是 Home Assistant Operating SystemHome Assistant OS，即 Home Assistant 操作系统，是一个嵌入式、简约的操作系统，旨在运行 Home Assistant 生态系统。它是大多数用户推荐的安装方法。 [Learn more]。请查看安装类型概述表以了解差异。

Important

先决条件 本指南假设您已经设置了操作系统并安装了容器运行时（如 Docker）。

如果您使用 Docker，则需要至少版本 19.03.9，理想情况下使用更高版本，以及 libseccomp 2.4.2 或更新版本。Docker Desktop 无法使用，您必须使用 Docker Engine。

平台安装

使用 Docker 安装非常简单。调整以下命令，使：

  • /PATH_TO_YOUR_CONFIG 指向您要存储配置并运行它的文件夹。请确保保留 :/config 部分。

  • MY_TIME_ZONE 是 tz 数据库名称，例如 TZ=America/Los_Angeles。

  • D-Bus 是可选的，但如果您计划使用 Bluetooth 集成则是必需的。

    docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=MY_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

    # if this returns "Image is up to date" then you can stop here
docker pull ghcr.io/home-assistant/home-assistant:stable

    # stop the running container
docker stop homeassistant

    # remove it from Docker's list of containers
docker rm homeassistant

    # finally, start a new one
docker run -d \
  --name homeassistant \
  --restart=unless-stopped \
  --privileged \
  -e TZ=MY_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

    一旦 Home Assistant Container 运行，您应该可以使用 http://<host>:8123 访问 Home Assistant（将 替换为系统的主机名或 IP）。您可以继续 onboarding。

      Onboarding

    重启 Home Assistant

    如果您更改了配置，则必须重启服务器。为此，您有 3 个选项。

    1. 在 Home Assistant UI 中，转到 设置 > 系统 并点击 重启 按钮。
    2. 您可以转到 开发者工具 > 操作，选择 homeassistant.restart 并选择 执行操作。
    3. 从终端重启。
    docker restart homeassistant

    docker compose restart

    Docker compose

    Tip

    docker compose 应该已经安装在您的系统上。如果没有，您可以手动安装它。

    随着 Docker 命令变得越来越复杂，切换到 docker compose 可能更可取，并支持在失败或系统重启时自动重启。创建一个 compose.yml 文件：

      services:
    homeassistant:
      container_name: homeassistant
      image: "ghcr.io/home-assistant/home-assistant:stable"
      volumes:
        - /PATH_TO_YOUR_CONFIG:/config
        - /etc/localtime:/etc/localtime:ro
        - /run/dbus:/run/dbus:ro
      restart: unless-stopped
      privileged: true
      network_mode: host

    通过以下命令启动:

    docker compose up -d

    一旦 Home Assistant Container 运行，您应该可以使用 http://<host>:8123 访问 Home Assistant（将 替换为系统的主机名或 IP）。您可以继续 onboarding。

      Onboarding

    暴露设备

    为了使用 Zigbee 或其他需要访问设备的集成，您需要将适当的设备映射到容器中。确保运行容器的用户具有访问 /dev/tty* 文件的正确权限，然后将设备映射添加到您的容器指令中：

    docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ...

    services:
  homeassistant:
    ...
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

    优化

    Home Assistant Container 使用替代的内存分配库 jemalloc 来实现更好的内存管理和 Python 运行时加速。

    由于使用的 jemalloc 配置可能会在某些具有大于 4K 页面大小的硬件（如某些特定的 ARM64 架构 SoC）上导致问题，可以通过传递环境变量 DISABLE_JEMALLOC 来禁用它，例如：

    docker run ... -e "DISABLE_JEMALLOC=true" ...

    services:
  homeassistant:
  ...
    environment:
      DISABLE_JEMALLOC: true

    错误信息 <jemalloc>: Unsupported system page size 是一个已知的指示器。

    安装 Home Assistant Core

    Caution

    这是一个高级安装过程，某些步骤可能因系统而异。考虑到这种安装类型的性质，我们假设您可以处理本文档与您使用的系统配置之间的细微差异。如有疑问，请考虑使用 其他安装方法，因为它们可能更适合您。

    先决条件

    本指南假设您已经设置好操作系统并安装了 Python 3.13（包括 python3-dev 包）或更新版本。

    安装依赖项

    在开始之前，请确保您的系统已完全更新，本指南中的所有软件包都使用 apt 安装，如果您的操作系统没有 apt，请寻找替代方案。

    sudo apt-get update
sudo apt-get upgrade -y

    安装依赖:

    sudo apt-get install -y python3 python3-dev python3-venv python3-pip bluez libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff6 libturbojpeg0-dev tzdata ffmpeg liblapack3 liblapack-dev libatlas-base-dev

    上述列出的依赖项可能会有所不同或缺失，具体取决于您的系统或个人使用 Home Assistant 的情况。

    创建账户

    为 Home Assistant Core 添加一个名为 homeassistant 的账户。 由于此账户仅用于运行 Home Assistant Core，因此添加了额外的参数 -rm 来创建一个系统账户并创建主目录。 参数 -G dialout,gpio,i2c 将用户添加到 dialout、gpio 和 i2c 组。第一个组是使用 Z-Wave 和 Zigbee 控制器所必需的，而第二个组是与 GPIO 通信所必需的。

    sudo useradd -rm homeassistant -G dialout,gpio,i2c

    创建虚拟环境

    首先，我们将为 Home Assistant Core 的安装创建一个目录，并将所有者更改为 homeassistant 账户。

    sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant

    接下来是为 Home Assistant Core 创建并切换到虚拟环境。这将使用 homeassistant 账户来完成。

    sudo -u homeassistant -H -s
cd /srv/homeassistant
python3 -m venv .
source bin/activate

    激活虚拟环境后（注意提示符会变为 (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $），您需要运行以下命令来安装所需的 Python 包。

    python3 -m pip install wheel

    安装完所需的 Python 包后，现在可以安装 Home Assistant Core 了！

    pip3 install homeassistant==2025.3.4

    故障排除：如果您在环境中没有看到上述版本的 Home Assistant 包，请确保您已安装正确的 Python 版本，如先决条件中所述。

    首次启动 Home Assistant Core。这将为您完成安装，自动在 /home/homeassistant 目录中创建 .homeassistant 配置目录，并安装任何基本依赖项。

    hass

    您现在可以通过 Web 界面访问您的安装，地址为 http://homeassistant.local:8123。

    如果此地址无法访问，您也可以尝试 http://localhost:8123 或 http://X.X.X.X:8123（将 X.X.X.X 替换为您机器的 IP 地址）。

    Note

    当您第一次运行 hass 命令时，它将下载、安装并缓存必要的库/依赖项。此过程可能需要 5 到 10 分钟。在此期间，当您访问 Web 界面时，可能会遇到 无法访问此网站 的错误。这种情况只会发生在第一次。后续的重启会快得多。

    我们通过本文中的链接进行的购买会获得佣金.