/fronius

name: fronius
description: "Read Fronius photovoltaic inverter data through the local Fronius Solar API V1 or Solar.web Query API cloud, without exposing access-key material."
user-invocable: true
requires:
  bins:
    - node
config_variables:
  - id: fronius-local-host
    env: FRONIUS_LOCAL_HOST
    required: false
    scope: "Local Fronius inverter base URL used in gateway http_request URLs"
    how_to_obtain: "Find the inverter LAN address in the router, Fronius app, or installer documentation and store it with `hybridclaw env set FRONIUS_LOCAL_HOST \"http://<fronius-ip>\"`."
credentials:
  - id: fronius-solarweb-access-key-id
    kind: api_key
    required: false
    secret_ref:
      source: store
      id: FRONIUS_SOLARWEB_ACCESS_KEY_ID
    scope: "Solar.web Query API AccessKeyId header"
    how_to_obtain: "Apply for Solar.web Query API access in Solar.web and create an API key. Set `FRONIUS_SOLARWEB_ACCESS_KEY_ID` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set FRONIUS_SOLARWEB_ACCESS_KEY_ID \"<access-key-id>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set FRONIUS_SOLARWEB_ACCESS_KEY_ID \"<access-key-id>\"`."
  - id: fronius-solarweb-access-key-value
    kind: api_key
    required: false
    secret_ref:
      source: store
      id: FRONIUS_SOLARWEB_ACCESS_KEY_VALUE
    scope: "Solar.web Query API AccessKeyValue header"
    how_to_obtain: "Save the API key value when Solar.web shows it. Set `FRONIUS_SOLARWEB_ACCESS_KEY_VALUE` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set FRONIUS_SOLARWEB_ACCESS_KEY_VALUE \"<access-key-value>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set FRONIUS_SOLARWEB_ACCESS_KEY_VALUE \"<access-key-value>\"`."
metadata:
  hybridclaw:
    category: home-automation
    short_description: "Fronius local inverter and Solar.web monitoring reads."
    tags:
      - fronius
      - solar
      - photovoltaic
      - energy
      - monitoring
      - r21
    related_roadmap:
      - R21.111
      - R5
      - R29
    issue: 1114
    stakes_tiers:
      green:
        - local-api-version
        - local-health
        - local-inverter-info
        - local-inverter-realtime
        - local-power-flow
        - local-meter-realtime
        - local-storage-realtime
        - local-ohmpilot-realtime
        - local-archive
        - local-logger-info
        - local-active-device-info
        - cloud-pvsystems
        - cloud-auth-check
        - cloud-pvsystem
        - cloud-flowdata
        - cloud-aggrdata
        - cloud-histdata
        - cloud-messages
        - cloud-devices-list
        - cloud-errors
      amber: []
      red: []
    escalation:
      writes: unsupported
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: 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": "no