# Running OpenEMS Edge on a Raspberry PI This guide explains how to: 1. Install and run **OpenEMS Edge on a Raspberry Pi** 2. Configure WebSocket + simulation 3. Run **OpenEMS UI on a macOS machine (not on the Pi)** 4. Connect the UI to the Edge over the internet The structure is intentionally split into two clear parts: - **PART A — Raspberry Pi (Edge)** - **PART B — macOS Machine (OpenEMS UI)** --- # ============================ # PART A — Raspberry Pi (Edge) # ============================ ## 1. Raspberry Pi OS Setup (Headless) Use Raspberry Pi Imager: - Device: Raspberry Pi 4 - OS: Raspberry Pi OS Lite (64‑bit) - Configure: - Hostname - Username & password - Enable SSH - Configure Wi‑Fi - Enable Raspberry Pi Connect Boot the Pi and connect via: - SSH - OR Raspberry Pi Connect --- ## 2. Install Java 21 (Temurin ARM64) On the Pi: ```bash sudo apt update sudo apt install -y wget apt-transport-https gpg wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public \ | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/adoptium.gpg > /dev/null echo "deb https://packages.adoptium.net/artifactory/deb \ $(awk -F= '/^VERSION_CODENAME/{print $2}' /etc/os-release) main" \ | sudo tee /etc/apt/sources.list.d/adoptium.list sudo apt update sudo apt install -y temurin-21-jdk ``` Verify: ```bash java -version ``` --- ## 3. Install OpenEMS Edge ```bash mkdir -p ~/downloads cd ~/downloads wget https://github.com/OpenEMS/openems/releases/download/2025.11.0/openems-edge.jar sudo chmod +x openems-edge.jar sudo mkdir -p /usr/lib/openems sudo mv openems-edge.jar /usr/lib/openems/ sudo mkdir -p /etc/openems.d ``` --- ## 4. Configure systemd Service Create: ```bash sudo nano /etc/systemd/system/openems.service ``` Paste: ```ini [Unit] Description=OpenEMS Edge After=network.target [Service] User=root Group=root Type=notify WorkingDirectory=/usr/lib/openems ExecStart=/usr/bin/java -Dfelix.cm.dir=/etc/openems.d/ \ -jar /usr/lib/openems/openems-edge.jar SuccessExitStatus=143 Restart=always RestartSec=10 WatchdogSec=60 [Install] WantedBy=multi-user.target ``` Enable & start: ```bash sudo systemctl daemon-reload sudo systemctl enable openems sudo systemctl start openems ``` Check: ```bash systemctl status openems ``` --- ## 5. Access OpenEMS Config Manager On the Pi, open: ``` http://localhost:8080/system/console/configMgr ``` --- ## 6. Add Required Components In Config Manager: 1. Add a **Scheduler** (any default scheduler) 2. Add **Controller.Api.Websocket** - Port: 8085 - Enabled: true Restart Edge: ```bash sudo systemctl restart openems ``` Verify WebSocket is listening: ```bash sudo ss -lntp | grep 8085 ``` You should see Java listening on port 8085. --- ## 7. (Optional) Add Simulation Components In Config Manager, add: - Simulator ESS - Simulator Grid Meter - Simulator PV Save and restart OpenEMS. --- # ===================================== # PART B — macOS Machine (OpenEMS UI) # ===================================== ## 1. Install Docker Desktop ```bash brew install --cask docker open -a Docker ``` Wait until Docker reports "Docker is running". Verify: ```bash docker version ``` You must see both Client and Server. --- ## 2. Clone OpenEMS Source ```bash git clone -b 2025.11.0 https://github.com/OpenEMS/openems cd openems ``` --- ## 3. Build OpenEMS UI Image ```bash docker build . \ -t openems_ui \ -f tools/docker/ui/Dockerfile.edge ``` --- ## 4. Run OpenEMS UI Replace YOUR\_PI\_IP with: - Public IP - OR VPN IP - OR Public DNS Example: ```bash docker container run \ -e WEBSOCKET_HOST=YOUR_PI_IP \ -p 80:80 \ -p 443:443 \ --restart unless-stopped \ --name openems_ui_container \ openems_ui ``` --- ## 5. Open the UI On your Mac: ``` http://localhost/login ``` Default login: - Username: admin - Password: admin If UI shows "disconnected": - Confirm port 8085 is listening on the Pi - Confirm WebSocket controller exists - Confirm WEBSOCKET\_HOST is correct --- # Why UI Runs on macOS and Edge Runs on Pi - Edge interacts with hardware and benefits from native systemd management - UI behaves like a stateless web application and is ideal for containerization - Separating them improves stability and flexibility --- # Troubleshooting - UI loads but no connection → check port 8085 - Nothing listening on 8085 → WebSocket not configured - Docker errors on Mac → ensure Docker Desktop is running --- # Security Notes - Prefer VPN/tunnel (Tailscale/WireGuard) over port forwarding - Use SSH key-based authentication - Do not expose ConfigMgr (8080) publicly --- You now have: - OpenEMS Edge running on Raspberry Pi - WebSocket enabled - Optional simulation components - OpenEMS UI running on macOS - UI connected over internet