Fronius

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:

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:

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:

{
  "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:

node skills/fronius/fronius.cjs --help

Local reads:

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:

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 2026-05-20 \
  --to 2026-05-27 \
  --channel EnergyReal_WAC_Sum_Produced
node skills/fronius/fronius.cjs --format json http-request cloud-messages --pv-system <id> --since 2026-05-20
node skills/fronius/fronius.cjs --format json http-request cloud-devices-list --pv-system <id>
node skills/fronius/fronius.cjs --format json http-request cloud-errors --pv-system <id> --since 2026-05-20

Run one gateway-proxied smoke request:

node skills/fronius/fronius.cjs --live --format json http-request cloud-flowdata --pv-system <id>

Health Checks

• local-health verifies local-host reachability by reading the local API version endpoint.
• cloud-auth-check verifies Solar.web key validity by reading the bounded PV systems list endpoint. A 401 or 403 from Solar.web means the upstream API rejected the injected key pair or the key lacks access. Gateway errors that name FRONIUS_SOLARWEB_ACCESS_KEY_ID or FRONIUS_SOLARWEB_ACCESS_KEY_VALUE indicate missing, unavailable, or blocked SecretRefs. A 429 means the account hit Solar.web rate limits.

Error Interpretation

• For local DNS, connection refused, timeout, no route to host, or gateway network-policy denial, report the exact gateway/local failure and ask for the actual inverter host when no operator-supplied host is available.
• For helper errors naming FRONIUS_LOCAL_HOST, ask the operator for the inverter LAN base URL or a configured environment value.
• For gateway errors naming FRONIUS_SOLARWEB_ACCESS_KEY_ID or FRONIUS_SOLARWEB_ACCESS_KEY_VALUE, ask the operator to set or unblock that specific secret.
• For Solar.web 401 or 403, report that the configured Solar.web key pair was rejected or lacks access.
• When both local and cloud paths fail, give a concise status for each path and one next action for each.