Install HelioPulse your way.

Install HelioPulse OS on a Raspberry Pi.

HelioPulse OS is a ready-to-use Linux image for Raspberry Pi: system, panel and updates in a single installation designed for local energy monitoring.

1. 1

   Download the stable release

   Get the image and review the release notes from the public releases repository.

   Download latest image · 2.0 GBView all releases
2. 2

   Flash the image

   Use Raspberry Pi Imager or an equivalent tool. Select the downloaded file and the destination SSD or microSD.

3. 3

   Connect and power on

   Connect storage, network, USB–RS485 adapter and the official power supply suitable for your Raspberry Pi.

Configure from your browser.

On first boot the appliance opens a captive portal from your browser: connect Wi-Fi, create your administrator and finish. No SSH, no cables to your computer.

1. 1

   Insert the card and power on

   Put the flashed microSD into the Raspberry Pi and connect the power. The first boot expands the system and starts HelioPulse; give it a minute.

2. 2

   Join the HelioPulse network

   From your phone or laptop, connect to the open HelioPulse-XXXX Wi-Fi network (no password) the device creates. Then open your browser and go to http://heliopulse.setup:8090 to reach the setup portal. On some phones the portal opens automatically; if not, just type that address.

3. 3

   Connect to the Internet

   Pick your home Wi-Fi and enter its password, or choose to continue with a network cable. The signal strength helps you find the right network.

4. 4

   Create your administrator

   Set the username and password (at least 8 characters) you will use to sign in to the panel. Keep them safe: this is your administrator account.

5. 5

   Optional: enable remote access

   If your device supports it, pick a name to reach the panel securely over the Internet. Local access always keeps working, so you can skip this step.

6. 6

   Ready to use

   The portal confirms setup is complete. The device is now on your Wi-Fi: reconnect to your usual network and open the panel at http://heliopulse.local:8080 with the account you created. The HelioPulse-XXXX network disappears since it is no longer needed.

Run HelioPulse in Docker.

Instead of flashing an image, pull the container on a mini-PC, NAS or server. The same core, no Raspberry required: ESP32 collectors connect over the network, and USB-RS485 adapters and remote access work just like on HelioPulse OS.

1. 1

   Start the container

   Use docker run for a quick try, or Docker Compose for a permanent installation. The image picks your architecture automatically.

   Docker Composedocker run

   Copy

   # compose.yml — permanent installation (recommended)
   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

   Open the panel

   Go to http://<host-IP>:8080 from any device on your network and create your administrator account in the setup wizard.

   From outside your local network (for example, a port published to the Internet), the wizard asks for a one-time setup code; read it with docker exec heliopulse cat /data/config/bootstrap-token. Then set System › General › Site location: daily totals, reports and schedules use its time zone.

3. 3

   Keep it up to date

   Updates replace the image: pull the new version and recreate the container. Your data stays in the volume.

   Keep it up to dateCopy

   # Update to a new version (image replacement):
   docker compose pull && docker compose up -d

Install the Home Assistant App.

Run HelioPulse as an App inside Home Assistant OS, with sidebar access, administrator sign-in and MQTT sensors.

1. 1

   Add the repository

   Open Settings → Apps → App store → ⋮ → Repositories and add the public repository below.

   Add the repositoryCopy

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

   Add to my Home Assistant
2. 2

   Install and open HelioPulse

   Find HelioPulse, install it and start it. Enable Show in sidebar, then open HelioPulse using your Home Assistant administrator session.

3. 3

   Connect sensors (optional)

   For sensors, configure Mosquitto and the MQTT integration in Home Assistant. Keep mqtt_mode set to auto and configure your devices in HelioPulse. Use a distinct topic_prefix for each instance.

4. 4

   Update safely

   Install App updates from Home Assistant and create a backup first. App versions are independent of HelioPulse OS and its OTA updates.

A local, modular platform.

Each device has an independent collector. A failure or restart in one inverter does not interrupt telemetry from the others.

The translator between your device and HelioPulse.

A driver is a declarative JSON file. It defines how to communicate over Modbus RTU and convert manufacturer registers into common HelioPulse metrics.

Start with the Modbus map.

You need the manufacturer's protocol manual and verified readings from a real device. The minimum schema requires an identifier, modbus_rtu protocol and at least one group with one register.

{
  "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
    }]
  }]
}

Activate it without SSH.