fronius

Files (2)

• SKILL.md
• fronius.cjs

SKILL.md (first lines)

# Fronius

Use this skill for operator-approved Fronius photovoltaic monitoring: local
inverter reads through Fronius Solar API V1 and cloud reads through Solar.web
Query API. This v1 skill covers read-only monitoring for inverters, meters,
storage, OhmPilot, and Solar.web account data.

## Core Contract

- Run supported operations through `skills/fronius/fronius.cjs`; the helper is
  the source of truth for Fronius URLs, Solar.web headers, endpoint bounds, and
  response-shape metadata.
- For the common "what is my solar doing now?" local LAN query, use the helper
  `local-summary` command. It performs the bounded local Solar API reads and
  returns normalized live production, consumption, grid, battery, meter, and
  storage fields.
- For live API calls, run the helper to build the request, then pass the
  emitted `httpRequest` object unchanged to the built-in `http_request` tool.
- Use `local-health` through the helper and `http_request` for local
  reachability checks.
- The helper emits only allowlisted endpoint shapes. It rejects arbitrary path
  passthrough and command-line secret values.
- Treat the inverter LAN base URL as plain local configuration. Use
  `--local-host http://<fronius-ip>` when the operator provides it, or use the
  configured `FRONIUS_LOCAL_HOST` environment value.
- Solar.web Query API authentication uses `AccessKeyId` and `AccessKeyValue`
  HTTP headers per Fronius' interface documentation. The helper emits those as
  `secretHeaders` so the gateway injects them server-side.
- Treat the first 401 or 403 live response as final for that attempt. For 429,
  report the rate-limit condition and any retry-after guidance.
- Treat local host reachability, gateway host policy, and macOS Local Network
  permission as separate failure modes.

## Setup

Local inverter path:

```bash
hybridclaw env set FRONIUS_LOCAL_HOST "http://<fronius-ip>"
```

The inverter LAN URL is configuration, not credential material. It can also be
passed per request with `--local-host http://<fronius-ip>` or exported as
`FRONIUS_LOCAL_HOST`.

Solar.web cloud path setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set
   `FRONIUS_SOLARWEB_ACCESS_KEY_ID` and
   `FRONIUS_SOLARWEB_ACCESS_KEY_VALUE`.
2. Browser `/chat` or TUI fallback:
   `/secret set FRONIUS_SOLARWEB_ACCESS_KEY_ID "<access-key-id>"` and
   `/secret set FRONIUS_SOLARWEB_ACCESS_KEY_VALUE "<access-key-value>"`.
3. Local console fallback:

```bash
hybridclaw secret set FRONIUS_SOLARWEB_ACCESS_KEY_ID "<access-key-id>"
hybridclaw secret set FRONIUS_SOLARWEB_ACCESS_KEY_VALUE "<access-key-value>"
```

Solar.web Query API access is requested from Solar.web. Create and store the
AccessKeyId and AccessKeyValue in HybridClaw secrets as soon as Solar.web shows
them. Solar.web Premium or a paid Query API package may be required for some
system, historical, and aggregate endpoints.

The cloud helper emits:

```json
{
  "secretHeaders": [
    { "name": "AccessKeyId", "secretName": "FRONIUS_SOLARWEB_ACCESS_KEY_ID", "prefix": "none" },
    { "name": "AccessKeyValue", "secretName": "FRONIUS_SOLARWEB_ACCESS_KEY_VALUE", "prefix": "none" }
  ]
}
```

The gateway injects the real access-key values server-side. Model-visible
helper output, prose, logs, and tests should contain only SecretRef names.

## Command Contract

Show helper usage:

```bash
node skills/fronius/fronius.cjs --help
```

Local reads:

```bash
node skills/fronius/fronius.cjs --format json --local-host http://<fronius-ip> local-summary
node skills/fronius/fronius.cjs --format json http-request local-api-version
node skills/fronius/fronius.cjs --format json http-request local-health
node skills/fronius/fronius.cjs --format json http-request local-power-flow
node skills/fronius/fronius.cjs --format json http-request local-inverter-realtime --scope System
node skills/fronius/fronius.cjs --format json http-request local-meter-realtime --scope System
node skills/fronius/fronius.cjs --format json http-request local-storage-realtime --scope System
node skills/fronius/fronius.cjs --format json http-request local-ohmpilot-realtime --scope System
node skills/fronius/fronius.cjs --format json http-request local-archive \
  --start 2026-05-26 \
  --end 2026-05-27 \
  --channel EnergyReal_WAC_Sum_Produced
node skills/fronius/fronius.cjs --format json http-request local-logger-info
node skills/fronius/fronius.cjs --format json http-request local-active-device-info --device-class Inverter
```

Cloud reads:

```bash
node skills/fronius/fronius.cjs --format json http-request cloud-pvsystems
node skills/fronius/fronius.cjs --format json http-request cloud-auth-check
node skills/fronius/fronius.cjs --format json http-request cloud-pvsystem --pv-system <id>
node skills/fronius/fronius.cjs --format json http-request cloud-flowdata --pv-system <id>
node skills/fronius/fronius.cjs --format json http-request cloud-aggrdata \
  --pv-system <id> \
  --period day \
  --from 2026-05-26
node skills/fronius/fronius.cjs --format json http-request cloud-histdata \
  --pv-system <id> \

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw