按你的方式安装 HelioPulse。

在树莓派上安装 HelioPulse OS。

HelioPulse OS 是一款开箱即用的树莓派 Linux 镜像：系统、面板与更新集于一体，专为本地能源监控设计。

1. 1

   下载稳定版本

   从公开 releases 仓库获取镜像并阅读版本说明。

   下载最新镜像 · 2.0 GB查看所有版本
2. 2

   写入镜像

   使用 Raspberry Pi Imager 或同类工具，选择下载的文件和目标 SSD 或 microSD。

3. 3

   连接并开机

   连接存储、网络、USB–RS485 转接器和适合 Raspberry Pi 的官方电源。

通过浏览器配置。

首次启动时，设备会在浏览器中打开一个强制门户：连接 Wi-Fi、创建管理员并完成。无需 SSH，也无需连接到你电脑的线缆。

1. 1

   插入存储卡并上电

   把烧录好的 microSD 插入树莓派并接通电源。首次启动会扩展系统并启动 HelioPulse，请稍等一分钟。

2. 2

   连接 HelioPulse 网络

   用手机或电脑连接设备创建的开放 Wi-Fi 网络 HelioPulse-XXXX（无需密码）。然后打开浏览器访问 http://heliopulse.setup:8090 进入配置门户。部分手机会自动打开门户；如果没有，请手动输入该地址。

3. 3

   连接互联网

   选择你家的 Wi-Fi 并输入密码，或选择使用网线继续。信号强度可帮助你识别正确的网络。

4. 4

   创建管理员

   设置用于登录面板的用户名和密码（至少 8 个字符）。请妥善保管：这是你的管理员账户。

5. 5

   可选：启用远程访问

   如果设备支持，选择一个名称以便通过互联网安全打开面板。本地访问始终有效，因此可以跳过此步骤。

6. 6

   可以使用

   门户会确认配置完成。此时设备已接入你的 Wi-Fi：请重新连接到你常用的网络，并在 http://heliopulse.local:8080 打开面板，使用你创建的账户登录。HelioPulse-XXXX 网络会消失，因为不再需要。

在 Docker 中运行 HelioPulse。

无需烧录镜像，在迷你主机、NAS 或服务器上拉取容器即可。同样的核心，无需树莓派：ESP32 采集器通过网络连接，USB-RS485 适配器和远程访问的用法与 HelioPulse OS 相同。

1. 1

   启动容器

   快速试用请用 docker run，长期部署请用 Docker Compose。镜像会自动匹配你的架构。

   Docker Composedocker run

   复制

   # compose.yml — 长期部署（推荐）
   services:
     heliopulse:
       image: public.ecr.aws/j7s7r2j5/heliopulse:latest
       container_name: heliopulse
       ports: ["8080:8080"]
       volumes: ["heliopulse-data:/data"]
       environment: { HP_RUNTIME: docker }
       restart: unless-stopped
       read_only: true
       tmpfs: [/tmp]
       cap_drop: [ALL]
       security_opt: ["no-new-privileges:true"]
       logging: { driver: json-file, options: { max-size: 10m, max-file: "3" } }
   volumes: { heliopulse-data: {} }

2. 2

   打开面板

   在局域网内任意设备上访问 http://<主机IP>:8080，并在设置向导中创建管理员账户。

   如果从局域网外部打开（例如已发布到互联网的端口），设置向导会要求输入一次性设置码，可通过 docker exec heliopulse cat /data/config/bootstrap-token 查看。随后在 系统 › 常规 › 站点位置 中设置位置：每日统计、报告和计划都使用该位置的时区。

3. 3

   保持更新

   更新即替换镜像：拉取新版本并重新创建容器，数据保留在卷中。

   保持更新复制

   # 更新到新版本（替换镜像）：
   docker compose pull && docker compose up -d

安装 Home Assistant 应用。

在 Home Assistant OS 中将 HelioPulse 作为 App 运行，支持侧边栏入口、管理员登录和 MQTT 传感器。

1. 1

   添加存储库

   打开设置 → Apps → App 商店 → ⋮ → 仓库，添加下方的公共仓库。

   添加存储库复制

   https://github.com/helios-pulse/heliopulse-releases

   添加到我的 Home Assistant
2. 2

   安装并打开 HelioPulse

   搜索 HelioPulse，安装并启动。启用“在侧边栏显示”，使用 Home Assistant 管理员会话打开 HelioPulse。

3. 3

   连接传感器（可选）

   如需传感器，请在 Home Assistant 中配置 Mosquitto 和 MQTT 集成。将 mqtt_mode 保持为 auto，并在 HelioPulse 中配置设备。每个实例使用不同的 topic_prefix。

4. 4

   安全更新

   先创建备份，再从 Home Assistant 安装 App 更新。App 版本独立于 HelioPulse OS 及其 OTA 更新。

本地化、模块化的平台。

每个设备都有独立的 collector。一个逆变器故障或重启不会中断其他设备的遥测。

设备与 HelioPulse 之间的翻译器。

驱动是声明式 JSON 文件，定义如何通过 Modbus RTU 通信，以及如何将制造商寄存器转换为 HelioPulse 通用指标。

从 Modbus 映射开始。

你需要制造商的协议手册和真实设备上的验证读数。最小模式要求标识符、modbus_rtu 协议，以及至少包含一个寄存器的分组。

{
  "id": "my-inverter-modbus",
  "name": "My inverter",
  "manufacturer": "Manufacturer",
  "models": ["Model A"],
  "protocol": {
    "type": "modbus_rtu",
    "baud_rate": 9600,
    "slave_id": 1
  },
  "register_groups": [{
    "name": "battery",
    "interval": "5s",
    "registers": [{
      "address": 256,
      "name": "battery_soc",
      "metric": "battery.soc_pct",
      "unit": "%",
      "scale": 1,
      "signed": false
    }]
  }]
}

无需 SSH 即可启用。