Skip to main content

Running OpenEMS Edge on a Raspberry PI

Release 2025.11.0

This guide walks through running OpenEMS Edge on a Raspberry Pi and connecting it to an OpenEMS UI running as a Docker container on a separate machine over a local network.

The goal is a simple, reproducible local Edge + local UI setup suitable for development, simulation, and early deployments.

Architecture Overview

This setup consists of two main components connected over the internet:

  • Edge (Raspberry Pi)
    Runs OpenEMS Edge as a systemd service and connects to the internet via Wi‑Fi.

  • Client (Laptop / Desktop)
    Runs the OpenEMS UI inside a Docker container. The UI may run on a different network (home, office, cloud VM).

Communication:

  • The UI communicates with the Edge via a WebSocket connection (default port 8085) over the public internet.

This means the Edge must be reachable via a public IP, port forwarding, or a secure tunnel.

Assumptions & Prerequisites

Before starting, ensure:

  • Raspberry Pi has working Wi‑Fi internet access

  • You have one of the following for remote access to the Pi:

    • Public IPv4 address with port forwarding, or

    • A static public IP, or

    • A secure tunnel (e.g. WireGuard, Tailscale, Cloudflare Tunnel)

  • Ports 80, 443, and 8085 are reachable from the Client

  • You have sudo access on the Raspberry Pi

  • Raspberry Pi OS is 64‑bit (ARM64)

Strong recommendation: For production or long‑running setups, use a VPN or tunnel instead of exposing ports directly.

Requirements

Hardware

  • Raspberry Pi–based Edge device
    (e.g. SL-RP4 with embedded Raspberry Pi 4B)

  • 2 GB RAM (minimum)

  • 16 GB micro-SD card + reader

Software / Dependencies

  • SSH

  • Rsync or WinSCP (Windows)

  • Raspberry Pi Imager

  • Docker Desktop

  • OpenEMS source code (release 2025.11.0)

  • Adoptium OpenJDK Temurin 21 (ARM64)

Fresh Device Deployment

This guide uses headless setup only. No monitor or keyboard is required for the Raspberry Pi.

Format SD Card (Client)

Install and launch Raspberry Pi Imager, then select:

  • Device: Raspberry Pi 4

  • Operating System: Raspberry Pi OS Lite (64-bit)
    (Debian Trixie – 2025-10-01)

  • Storage: Target SD card

Click Next → Edit Settings.

These settings are written to the SD card and applied on the first boot.

OS Customisation — General

Mandatory:

  • Hostname

  • Username and password

  • Enable SSH

Required for this setup:

  • Configure Wi‑Fi SSID, password, and country

Also configure:

  • Timezone

  • Keyboard layout

OS Customisation — Services

Enable the following:

  • ✅ Enable SSH (key-based auth recommended)

  • ✅ Enable Raspberry Pi Connect

Raspberry Pi Connect allows secure remote access to the Pi over the internet, even behind NAT, without port forwarding.

Proceed to format the SD card.

Raspberry Pi Connect (Remote Access)

Raspberry Pi Connect provides a secure, browser-based and SSH-like remote access method for headless Raspberry Pi devices without exposing ports or requiring a VPN.

Why Use Raspberry Pi Connect

  • No monitor or keyboard required

  • Works behind NAT and firewalls

  • Secure, encrypted connection

  • Accessible from anywhere via a browser

Requirements

  • Raspberry Pi OS (64-bit)

  • Internet access via Wi-Fi

  • Raspberry Pi ID account

First Login via Raspberry Pi Connect

  1. During first boot, ensure the Pi is connected to Wi-Fi

  2. Sign in to Raspberry Pi Connect from another device:

https://connect.raspberrypi.com

  1. Log in with your Raspberry Pi ID

  2. Select your Pi from the device list

  3. Open a remote shell or desktop session (if enabled)

Once Raspberry Pi Connect is active, SSH is optional but still recommended for automation.

Install & Run OpenEMS UI on macOS (Client Machine)

In this setup, the OpenEMS UI runs on your macOS machine, not on the Raspberry Pi.

1. Install Docker Desktop (macOS)

If not already installed:

brew install --cask docker
open -a Docker

Wait until the Docker whale icon shows "Docker is running".

Verify:

docker version

You must see both Client and Server sections.

2. Clone OpenEMS Source Code (on macOS)

git clone -b 2025.11.0 https://github.com/OpenEMS/openems
cd openems

3. Build the OpenEMS UI Docker Image

docker build . \
  -t openems_ui \
  -f tools/docker/ui/Dockerfile.edge

Verify image exists:

docker images | grep openems_ui

4. Run the OpenEMS UI Container

Replace YOUR_PI_IP with:

  • Public IP address of your Raspberry Pi

  • OR VPN IP (recommended)

  • OR Public DNS name

Example:

docker container run \
  -e WEBSOCKET_HOST=YOUR_PI_IP \
  -p 80:80 \
  -p 443:443 \
  --restart unless-stopped \
  --name openems_ui_container \
  openems_ui

Do not include http:// or ports in WEBSOCKET_HOST.

OpenEMS UI Login (macOS)

Open your browser on the same Mac where Docker is running:

http://localhost/login

Default login:

  • Username: admin

  • Password: admin

If the dashboard loads but shows "disconnected", verify that the Raspberry Pi is listening on port 8085:

sudo ss -lntp | grep 8085

And confirm that Controller.Api.Websocket is configured in the OpenEMS Config Manager on the Pi.

Create & Launch the UI Docker Container (Client)

Start the UI by accessing:

http://localhost/login

Default password: admin

  • Change language via:
    Top-left menu → Admin icon → “Sprache wählen”

  • Refresh or use the back arrow to return to the overview

Create & Launch the UI Docker Container (Client)

Set WEBSOCKET_HOST to one of the following:

  • Public IP address of the Raspberry Pi

  • Public DNS name (recommended)

  • VPN / tunnel IP or hostname

Example using a public hostname:

docker container run \
  -e WEBSOCKET_HOST=edge.example.com \
  -p 443:443 -p 80:80 \
  --restart unless-stopped \
  --name openems_ui_container \
  openems_ui

Why UI is Containerized but Edge Runs as a Service

In this guide, the OpenEMS UI runs in Docker while OpenEMS Edge runs as a native systemd service on the Raspberry Pi.

Why containerize the UI

  • The UI behaves like a web application: it’s comparatively portable and easier to run consistently across machines.

  • Docker makes it simple to package dependencies, run upgrades/rollbacks, and expose the UI via standard ports.

  • The UI typically needs only a small set of runtime settings (e.g., WEBSOCKET_HOST).

Why run Edge as a system service

OpenEMS Edge is closer to an appliance / gateway and is often more reliable when managed directly by the host OS:

  • Boot reliability: systemd starts Edge on boot and restarts it if it crashes.

  • Hardware & networking access: Edge may need stable access to devices and networking (serial/USB/Modbus/etc.). Running directly on the OS avoids Docker-specific device mapping and networking edge cases.

  • Persistent configuration: Externalized configs in /etc/openems.d are straightforward to manage and back up.

  • Simpler troubleshooting: Standard Linux tooling works immediately (systemctl status, journalctl).

When running Edge in Docker can make sense

  • You are running simulation only (no direct hardware I/O)

  • You already use container fleet management (e.g., docker-compose, k3s, balena)

  • You can standardize volumes, device mappings, and networking mode

Troubleshooting

  • UI loads but no Edge connection
    → Check public reachability of port 8085

  • Works on LAN but not remotely
    → Router port forwarding or firewall missing

  • Public IP keeps changing
    → Use Dynamic DNS or a tunnel

  • Connection drops frequently
    → Use VPN/tunnel instead of raw port forwarding

Security Notes (Important)

When exposing OpenEMS Edge over the internet:

  • Avoid running long‑term setups with raw port forwarding

  • Prefer WireGuard, Tailscale, or Cloudflare Tunnel

  • Consider TLS termination and authentication

  • Restrict SSH access (key‑based auth only)

This setup is suitable for remote development, pilots, and managed deployments.

Back to top