OpenEMS Edge ↔ Backend Connection

Overview

This page describes how an OpenEMS Edge connects to an OpenEMS Backend through a reverse proxy.

The intended setup is:

OpenEMS Backend runs on a VPS in Docker
Nginx terminates TLS and handles WebSocket proxying
Edge connects to the Backend via secure WebSocket (wss)
Backend authenticates the Edge using an API key from the metadata configuration

Architecture

OpenEMS Edge
   ↓
wss://ems.zevplus.ch/edge-to-backend/
   ↓
Nginx reverse proxy (443)
   ↓
openems-backend:8081
   ↓
OpenEMS Backend Edge-WebSocket

Relevant Backend Ports

Port	Purpose	Public Access
8079	Apache Felix Web Console	Optional / temporary only
8081	Edge → Backend WebSocket	No direct public access
8082	UI → Backend WebSocket	No direct public access

Critical Rule:

Ports 8081 and 8082 must not be exposed directly to the internet.

External access must go through HTTPS on port 443 via the reverse proxy.

Backend Reverse Proxy Endpoint

The Edge connects to this external URL:

wss://ems.zevplus.ch/edge-to-backend/

Nginx routes this path internally to:

http://openems-backend:8081

Example Nginx location:

location /edge-to-backend {
    proxy_pass http://openems-backend:8081;

    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_set_header Host $host;

    proxy_read_timeout 3600;
    proxy_send_timeout 3600;
}

Required WebSocket mapping:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Backend Metadata

The Backend needs to know which Edges are allowed to connect.

For a simple multi-edge setup, use Metadata.File instead of Metadata.Dummy.

Example metadata file:

{
  "edges": {
    "c0001-e0001": {
      "comment": "Customer 1 Edge 1",
      "apikey": "REPLACE_WITH_SECRET_API_KEY"
    },
    "c0001-e0002": {
      "comment": "Customer 1 Edge 2",
      "apikey": "REPLACE_WITH_SECRET_API_KEY"
    }
  }
}

Typical location inside the Backend container:

/var/opt/openems/config/metadata.json

Typical Docker volume mapping:

volumes:
  - openems-backend-conf:/var/opt/openems/config:rw
  - openems-backend-data:/var/opt/openems/data:rw

Edge ID Convention

Use a stable and structured Edge ID.

Recommended pattern:

c0001-e0001

Meaning:

c0001 = customer/project/site identifier
e0001 = edge identifier

Examples:

c0001-e0001
c0001-e0002
c0002-e0001

Avoid generic names such as:

edge1
test-edge
raspi

They become hard to manage once multiple customers, buildings, or test systems exist.

Edge Configuration

On the Edge, configure the component:

Controller.Api.Backend

Typical settings:

Field	Value
Component ID	`ctrlBackend0`
URI	`wss://ems.zevplus.ch/edge-to-backend/`
API Key	API key from Backend `metadata.json`
Edge ID	Matching Edge ID from Backend metadata

The API key entered on the Edge must match the corresponding API key in the Backend metadata.

Important Matching Rules

The following values must match exactly:

Edge Configuration	Backend Configuration
Edge ID	Key in `metadata.json`
API Key	`apikey` value in `metadata.json`
URI path	Nginx route to Backend port `8081`

Example:

Backend metadata:

{
  "edges": {
    "c0001-e0001": {
      "comment": "Customer 1 Edge 1",
      "apikey": "abc123"
    }
  }
}

Edge configuration:

Edge ID: c0001-e0001
API Key: abc123
URI: wss://ems.zevplus.ch/edge-to-backend/

Metadata.Dummy vs Metadata.File

Metadata.Dummy

Metadata.Dummy is useful for quick tests and simulations.

Typical limitation:

Uses a template-based Edge ID model
Not ideal for managing multiple real Edges
Not suitable for structured customer/project setups

Example template:

edge%d

Metadata.File

Metadata.File is better for real deployments.

Advantages:

Explicit Edge IDs
Explicit API keys
Easier multi-edge management
Better fit for customer/site naming conventions

Recommended for this project:

Metadata.File

Restart / Reload Notes

After changing Backend metadata or OSGi configuration, restart the Backend if required:

docker compose restart openems-backend

Check logs:

docker logs -f openems_backend

If only Nginx config changed:

docker compose exec nginx nginx -s reload

Verification

1. Check Backend Container

docker ps

Expected:

openems_backend
nginx
openems-ui

2. Check Backend Logs

docker logs -f openems_backend

Useful log patterns:

Edge.Websocket
Ui.Websocket
Controller.Api.Backend

3. Check Nginx Reachability

From outside:

curl -Iv https://ems.zevplus.ch

For ACME / port 80 checks:

curl -I http://ems.zevplus.ch/.well-known/acme-challenge/test

4. Check Internal Docker Networking

From inside the Nginx container:

docker exec -it nginx sh

Then:

nc -vz openems-backend 8081
nc -vz openems-backend 8082

Expected:

openems-backend (x.x.x.x:8081) open
openems-backend (x.x.x.x:8082) open

Common Issues

Edge does not appear in Backend UI

Possible causes:

Wrong Edge ID
Wrong API key
Metadata.Dummy still active instead of Metadata.File
Backend was not restarted after metadata change
Reverse proxy path does not point to Backend port 8081

WebSocket closes immediately

Possible causes:

API key mismatch
Edge ID not known to Backend
URI typo
Missing WebSocket upgrade headers in Nginx

Typical Edge-side symptom:

Websocket closed

Backend UI works, but Edge does not connect

Possible cause:

The UI and Edge use different Backend WebSocket ports:

Connection	Backend Port
Edge → Backend	8081
UI → Backend	8082

The Edge must be routed to 8081, not 8082.

UI shows Edge but no history

The Edge connection may be working, but historical data needs a working Timedata backend, for example InfluxDB.

This is a separate issue from the Edge ↔ Backend WebSocket connection.

Security Notes

Treat API keys as secrets
Do not commit real API keys into a public repository
Do not expose Backend WebSocket ports directly
Use HTTPS / WSS only for external connections
Restrict Felix console access as much as possible

Recommended practice for public documentation:

apikey: "REPLACE_WITH_SECRET_API_KEY"

Never document production API keys.

Recommended Operational Checklist

When adding a new Edge:

Choose a stable Edge ID
Add the Edge ID and API key to Backend metadata
Restart the Backend if required
Configure Controller.Api.Backend on the Edge
Set the URI to wss://ems.zevplus.ch/edge-to-backend/
Enter the matching API key
Check Backend logs
Verify that the Edge appears in the Backend UI
Verify live data
Verify historical data separately

Summary

Edge connects to Backend via wss://ems.zevplus.ch/edge-to-backend/
Nginx proxies this path to openems-backend:8081
Backend authenticates the Edge via metadata and API key
Metadata.File is recommended for structured multi-edge setups
Direct public exposure of ports 8081 and 8082 must be avoided