Skip to main content

Using OpenEMS with Claude

Claude, our AI assistant, can now work with OpenEMS, NFE's SCADA. It can tell you how a site is doing, pull history and energy figures, read component settings, and prepare setting changes. It does this through the "nfe-openems" skill, signed in with your own OpenEMS (Keycloak) login. This page explains what it can do, the one-time setup, and the limits to know about.

What Claude can do in OpenEMS

  • Check on sites. "Is the Sezibwa gateway online?", "How is the Sezibwa battery doing right now?" Claude lists the edges with their last message, and reads live values such as SoC, battery, grid and load power, and phase voltages. It spells out what the signs mean (charging or discharging, buying or selling).
  • Pull history. "What was the lowest SoC yesterday, and when?", "Give me the evening L3 voltage for last week as a CSV." Times are in Kampala time.
  • Work out energy. "How much did the battery discharge each day this week?" At our sites the battery's energy counters are empty, so Claude works the kWh out from power history. For 30 Oct to 1 Nov 2026 it agreed with the daily brief to within 1.5%. For site consumption it uses the main meter's counter.
  • Read settings. "What are the SRNE charge and discharge windows at Sezibwa?" Claude shows each component's settings, and turns the SRNE's encoded schedule times into clock times.
  • Export the same Excel file the OpenEMS UI gives you.
  • Prepare a change. "What would it take to start the evening discharge at 17:30?" Claude shows the exact change, current → new, and changes nothing until you say yes. See the limits below: today changes can't be sent through the Backend.

Two things to know first

1. Changes can't reach the gateways through the Backend yet. Our gateways connect straight to the Backend's Edge Manager. OpenEMS 2026 expects them to come in through its BackendEdge relay, so anything the Backend sends down to a gateway fails. That covers setting changes, channel writes and the live system log, in Claude and in the OpenEMS UI alike. Reading works: status, live values, history, energy, exports and the Backend's copy of each configuration. Until the deployment is fixed, changes are made on the gateway itself (its local UI or REST API over ZeroTier) by the engineer responsible, and recorded here in the Library. When asked for a change, Claude shows the exact plan and says this.

2. Inside OpenEMS, everyone is the same user. You sign in with your own Keycloak account, so access can be given and taken away person by person. But the Backend keeps its gateway list in a simple file (Metadata.File), and every login becomes one built-in user, admin, with full rights on every gateway. OpenEMS therefore can't tell who changed what. Claude keeps a log of every change it makes on your computer (~/.config/nfe-openems/changes.log), and you should post a short note in the site's Element thread or Library page: who, what, why, and before → after.

One-time setup

You need three things:

  1. Claude on your own computer. The skill works in the Claude desktop app (Code tab) or in Claude Code, on macOS, Linux or Windows (with WSL). Your login stays on your computer.
  2. The skill. It's already set up for everyone in our Claude organisation, so there's nothing to install. If it doesn't show up for you, download nfe-openems.skill from the attachments on this page (paperclip icon, top right). Open it and click Save skill, or unzip it into ~/.claude/skills/.
  3. Your own OpenEMS login. It's the one you use at https://openems.nearlyfreeenergy.com. If you don't have one, ask a Keycloak admin to create a user for you in the openems realm. Please don't use the shared admin login for day-to-day work: then nobody can tell who did what.

Then sign in:

  1. In a Claude chat, ask something like "Using OpenEMS, is Sezibwa online?" The first time, Claude creates ~/.config/nfe-openems/credentials.env, with the username and password left blank.
  2. Choose how you want to sign in:
    • Type your password each day (more private). Claude opens a sign-in prompt in its Terminal panel, or asks you to run one in your own terminal. You type your username and password there; Claude never sees them. The sign-in lasts 12 hours.
    • Save your password in the file (more convenient). Open the file (on a Mac: Finder → Go → Go to Folder… → ~/.config/nfe-openems, then open credentials.env with TextEdit). Paste your username after OPENEMS_USERNAME= and your password after OPENEMS_PASSWORD=, with no spaces or quotes, and save. Claude then signs in again by itself when the 12 hours are up.
  3. Tell Claude "done". It confirms who you're signed in as, and until when.

Keeping your login safe

  • Never paste your password into a chat, an email, Element, a Library page or a shared document. It only goes into the sign-in prompt or the file on your computer.
  • Claude is set up never to show or print your password or the sign-in token. It sends them only to openems.nearlyfreeenergy.com.
  • Claude hides passwords and API keys that appear in gateway settings, and it refuses to set them. Set those yourself in the OpenEMS UI.
  • If you think your password has been exposed, change it in Keycloak.

How Claude handles changes

  • Reading is free. Status, values, history, energy, settings and exports happen straight away.
  • Changes need your yes. Claude first shows a dry run: the gateway, the component, each value's current → new, and what it will do at the site. It changes nothing until you agree to exactly that.
  • Some things are never done through Claude: shell commands, software updates and restarts on the gateway, network settings, and passwords or API keys. Those belong to the engineer responsible, over SSH or in the UI.
  • SRNE settings follow the Library's SRNE ASP48120SH3 Safe Settings Write design. Claude takes schedule times as clock times (17:30) and encodes them for the inverter, and it won't guess raw register values.

Tips for good results

  • Name the site and the period: "Sezibwa, yesterday", "last week, per day". Dates are whole days in Kampala time.
  • Ask Claude to say its source. Battery figures can come from the SRNE's own readings (ess0) or the site totals (_sum), and energy from a counter or worked out from power. Good answers say which.
  • Gaps are reported, not hidden. If a period has missing data, Claude says how much and marks figures as estimates.
  • Customers' names. The household meters at Sezibwa are named after the customers. In shared notes, refer to meters by house or meter id unless the names are needed.
  • History for old test rigs can be mixed. The Backend files history by the number at the end of the gateway id, so aaron-pi-1 also holds what hillary-test-pi-1 sent before it was renamed hillary-test-pi-99. See OpenEMS Backend InfluxDB Data Model and Edge-ID Collision.
  • When you learn something about a site's setup or OpenEMS, add it to the Product book's OpenEMS chapter so others can use it too.

Troubleshooting

What you see What to do
"not signed in" (exit 2) The 12-hour sign-in ran out and no password is saved. Sign in again in the terminal, or save your password in the file.
"sign-in refused" Wrong username or password, or your Keycloak user is disabled. Try them at https://openems.nearlyfreeenergy.com.
"this Backend cannot pass requests down to its Edges" The known limit described above. Make the change on the gateway itself and record it.
A value shows null The gateway is offline, the value isn't sent to the Backend, or there's no such channel. Ask Claude to find the right channel.
Energy totals come back empty Expected for the _sum and battery counters at our sites. Ask for the energy worked out from power instead.
"no stored history" Nothing was recorded for that gateway or period, for example an old test rig that hasn't connected since.

For admins

  • Skill: "nfe-openems", set up for everyone in Claude under Organization settings → Plugins & skills (Organization library, installed by default). Updates are made by uploading a new version there. When you do, also replace the attachment on this page, which is kept for manual installs.
  • Backend: https://openems.nearlyfreeenergy.com (OpenEMS 2026.10, the Nearly-Free-Energy/openems fork, deployed from openems-deployment). The skill uses the UI websocket /openems-backend; /rest/jsonrpc is the Backend-to-Backend REST route.
  • Users: Keycloak at https://keycloak.openems.nearlyfreeenergy.com/admin/, realm openems. Each person needs their own user.
  • Known deployment issues (November 2026):
    • The gateways connect straight to the Edge Manager without the BackendEdge relay, so requests from the Backend to a gateway fail with Endpoint with method "edgeRpc" is not defined. The fix is to run the BackendEdge app between the gateways and the Edge Manager.
    • Metadata.File maps every login to the one admin user, with full rights on every gateway.
    • At Sezibwa the _sum and SRNE battery energy counters are empty, _sum/GridMode reads Undefined, and there is no solar meter.
  • Tested on 2 November 2026 with Aaron's login. Sign-in, gateway list, live values, live watch, history, energy (counters and worked out from power), the Excel export, settings and a dry-run change all worked as described here. Nothing was changed on any gateway.

Last reviewed: 2 November 2026 by Aaron Tushabe (skill set up for the whole organisation)

No comments to display

Back to top