fix(config): one name per thing - api_token and url (#451)

config/batcontrol_config_dummy.yaml

@@ -117,7 +117,7 @@ utility:
   vat: 0.19 # awattar and energyforecast only
   fees: 0.015 # awattar and energyforecast only
   markup: 0.03 # awattar and energyforecast only
-  # apikey: YOUR_API_KEY # mandatory for tibber, energyforecast and energyforecast_total_price
+  # api_token: YOUR_API_KEY # mandatory for tibber, energyforecast and energyforecast_total_price (old name: apikey)
   # market_zone: DE # both energyforecast providers: DE/LU, AT, FR, NL, BE, PL, DK1, DK2. Default: DE
   #
   # energyforecast_total_price: the API returns the full price incl. dynamic network
@@ -188,18 +188,21 @@ pvinstallations:
     # horizon: # leave empty for the default PVGIS horizon
 
   # homeassistant-solar-forecast-ml (HACS integration)
+  # Keep only the entries of the provider you selected above: fcsolarapi and
+  # solcast read every entry, so a leftover entry of another provider fails.
   # - name: HA Solar ML Forecast
-  #   base_url: ws://homeassistant.local:8123
-  #   api_token: eyJ... # long-lived access token from the HA profile
+  #   type: homeassistant-solar-forecast-ml # optional, explicit provider type
+  #   url: ws://homeassistant.local:8123 # old name: base_url
+  #   api_token: eyJ... # long-lived access token from the HA profile (old name: apikey)
   #   entity_id: sensor.solar_forecast_ml_evcc_solar_prognose
   #   sensor_unit: auto # auto (detect), Wh or kWh
-  #   cache_ttl_hours: 24.0
+  #   cache_ttl_hours: 24.0 # how long a fetched forecast stays usable. Default: 12.0
 
   # solcast - free hobbyist account, 10 requests/day. Site geometry is configured
   # in the Solcast web toolkit, not here.
   # - name: Haus
   #   resource_id: xxxx-xxxx-xxxx-xxxx
-  #   apikey: your-solcast-api-key
+  #   api_token: your-solcast-api-key # old name: apikey
   #   percentile: 50 # 10 pessimistic, 50 default, 90 optimistic
 
 #--------------------------
@@ -213,8 +216,8 @@ consumption_forecast:
     load_profile: load_profile.csv # file inside the config folder
 
   # homeassistant_api:
-  #   base_url: ws://homeassistant:8123
-  #   apitoken: YOUR_LONG_LIVED_ACCESS_TOKEN
+  #   url: ws://homeassistant:8123 # old name: base_url
+  #   api_token: YOUR_LONG_LIVED_ACCESS_TOKEN # old name: apitoken
   #   entity_id: sensor.energy_consumption # consumption data in Wh or kWh
   #   sensor_unit: auto # auto (default), Wh or kWh. Fixed values skip detection
   #   history_days: [-7, -14, -21] # days to look back

docs/configuration/consumption-forecast.md

@@ -114,12 +114,19 @@ The HomeAssistant API method provides **dynamic consumption forecasting** based
 
 ### Configuration
 
+!!! info "Key names"
+    The credential is `api_token` and the endpoint is `url`, consistently across all
+    configuration sections. The older spellings `apitoken`, `apikey` and `base_url` are still
+    read, but log a deprecation warning at startup. The Home Assistant add-on offers only
+    `url` and `api_token` from version 0.10.0 on - rename them there in the same step as the
+    update.
+
 ```yaml
 consumption_forecast:
   type: homeassistant-api
   homeassistant_api:
-    base_url: ws://homeassistant.local:8123   # Your HomeAssistant URL
-    apitoken: YOUR_LONG_LIVED_ACCESS_TOKEN     # Long-Lived Access Token
+    url: ws://homeassistant.local:8123        # Your HomeAssistant URL
+    api_token: YOUR_LONG_LIVED_ACCESS_TOKEN   # Long-Lived Access Token
     entity_id: sensor.energy_consumption        # Entity ID with consumption data
     sensor_unit: auto                           # Options: 'auto', 'Wh', or 'kWh' (since 0.5.7)
     history_days: "-7;-14;-21"               # Days to look back (negative values)
@@ -134,8 +141,8 @@ consumption_forecast:
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
-| `base_url` | HomeAssistant URL (ws is correct)  | `ws://homeassistant.local:8123` |
-| `apitoken` | Long-Lived Access Token from HomeAssistant | `eyJ0eXAiOiJKV1Qi...` |
+| `url` | HomeAssistant URL (ws is correct)  | `ws://homeassistant.local:8123` |
+| `api_token` | Long-Lived Access Token from HomeAssistant | `eyJ0eXAiOiJKV1Qi...` |
 | `entity_id` | Entity ID tracking consumption (must have long-term statistics) | `sensor.energy_consumption` |
 
 #### Optional Parameters
@@ -182,8 +189,8 @@ The `sensor_unit` parameter controls how batcontrol detects the unit of measurem
 consumption_forecast:
   type: homeassistant-api
   homeassistant_api:
-    base_url: ws://homeassistant.local:8123
-    apitoken: YOUR_TOKEN
+    url: ws://homeassistant.local:8123
+    api_token: YOUR_TOKEN
     entity_id: sensor.energy_consumption
     sensor_unit: kWh  # Explicit configuration - faster startup!
 ```
@@ -349,9 +356,12 @@ The script will:
 
 ### HomeAssistant API Method
 
-**Problem:** "Authentication failed"
+**Problem:** "Authentication failed" or "expected str at 'access_token'. Got None"
 
 **Solution:**
+- `Got None` means no token reached the provider: the credential key is `api_token`
+  (`apitoken` still works but is deprecated), and it belongs in the same block as
+  `entity_id` and `url`
 - Verify your access token is correct
 - Check if the token has been revoked in HomeAssistant
 - Create a new Long-Lived Access Token
@@ -366,8 +376,8 @@ This error occurs when your HomeAssistant instance has many entities (sensors, l
 consumption_forecast:
   type: homeassistant-api
   homeassistant_api:
-    base_url: ws://homeassistant.local:8123
-    apitoken: YOUR_TOKEN
+    url: ws://homeassistant.local:8123
+    api_token: YOUR_TOKEN
     entity_id: sensor.energy_consumption
     sensor_unit: kWh  # or 'Wh' depending on your sensor
 ```
@@ -391,7 +401,7 @@ consumption_forecast:
 **Problem:** "Connection refused"
 
 **Solution:**
-- Verify `base_url` is correct and accessible from batcontrol
+- Verify `url` is correct and accessible from batcontrol
 - Check if HomeAssistant is running
 - Verify network connectivity
 - Check firewall rules
@@ -512,8 +522,8 @@ consumption_forecast:
 consumption_forecast:
   type: homeassistant-api
   homeassistant_api:
-    base_url: ws://192.168.1.100:8123
-    apitoken: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+    url: ws://192.168.1.100:8123
+    api_token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
     entity_id: sensor.house_energy_total
     sensor_unit: auto  # Auto-detect (default)
     history_days: "-7;-14;-21"
@@ -528,8 +538,8 @@ consumption_forecast:
 consumption_forecast:
   type: homeassistant-api
   homeassistant_api:
-    base_url: ws://homeassistant.local:8123
-    apitoken: your_token_here
+    url: ws://homeassistant.local:8123
+    api_token: your_token_here
     entity_id: sensor.energy_consumption
     sensor_unit: kWh  # Explicit unit - faster startup, no auto-detection needed
     history_days: "-7;-14;-21"
@@ -544,8 +554,8 @@ consumption_forecast:
 consumption_forecast:
   type: homeassistant-api
   homeassistant_api:
-    base_url: ws://homeassistant.local:8123
-    apitoken: your_token_here
+    url: ws://homeassistant.local:8123
+    api_token: your_token_here
     entity_id: sensor.energy_consumption
     sensor_unit: Wh  # Explicit unit for optimal performance
     history_days: "-1;-2;-3"  # Only last 3 days

docs/configuration/dynamic-tariff-provider.md

@@ -9,13 +9,20 @@ Currently following data providers are available:
 
 You can chose one and need to adjust the configuration.
 
+!!! info "Key names"
+    The credential is `api_token` and the endpoint is `url`, consistently across all
+    configuration sections. The older spellings `apikey`, `apitoken` and `base_url` are still
+    read, but log a deprecation warning at startup. The Home Assistant add-on offers only
+    `url` and `api_token` from version 0.10.0 on - rename them there in the same step as the
+    update.
+
 ## tibber
 You need to get an API Key from https://developer.tibber.com/ , which looks like `Zz-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx`. After obtaining this key, use the following configuration:
 
 ```
 utility:
   type: tibber 
-  apikey: YOUR-PASSWORD
+  api_token: YOUR-PASSWORD
 ```
 
 
@@ -178,7 +185,7 @@ to obtain an API key.
 ```yaml
 utility:
   type: energyforecast
-  apikey: xxxxxxxxx
+  api_token: xxxxxxxxx
   vat: 0.19     # 19% VAT
   fees: 0.15    # Your network fees (Netzentgelt), EUR/kWh excl. VAT
   markup: 0.00  # Optional markup, e.g. supplier margin
@@ -205,7 +212,7 @@ This is useful if:
 ```yaml
 utility:
   type: energyforecast_total_price
-  apikey: xxxxxxxxx
+  api_token: xxxxxxxxx
   # market_zone: DE  # optional: DE/LU (default, both map to DE-LU market zone), AT, FR, NL, BE, PL, DK1, DK2
 ```
 

docs/configuration/solar-forecast.md

@@ -93,12 +93,26 @@ The minimum configuration is:
 solar_forecast_provider: homeassistant-solar-forecast-ml
 pvinstallations:
   - name: HA Solar ML Forecast
-    base_url: ws://homeassistant.local:8123  # Your HomeAssistant URL
+    url: ws://homeassistant.local:8123       # Your HomeAssistant URL
     api_token: eyJ...                        # Long-lived access token from HA Profile
     entity_id: sensor.solar_forecast_ml_evcc_solar_prognose  # Forecast sensor entity
 ```
 
-If you're running batcontrol in a HomeAssistant addon, use `ws://homeassistant:8123` as the base_url. For standalone installations, use your HomeAssistant IP or hostname.
+If you're running batcontrol in a HomeAssistant addon, use `ws://homeassistant:8123` as the url. For standalone installations, use your HomeAssistant IP or hostname.
+
+!!! note "List only the entries of the provider you selected"
+    This provider uses a single `pvinstallations` entry: the one with a matching `type:`, or
+    the one carrying `entity_id`. Entries of *other* providers have to be removed, because
+    `fcsolarapi` and `solcast` read every entry in the list and fail on an entry that does not
+    carry their keys. With several entries and no way to tell which one is meant, batcontrol
+    stops at startup and asks you to add `type: homeassistant-solar-forecast-ml`.
+
+!!! info "Key names"
+    The credential is `api_token` and the endpoint is `url`, consistently across all
+    configuration sections. The older spellings `base_url`, `apikey` and `apitoken` are still
+    read, but log a deprecation warning at startup. The Home Assistant add-on offers only
+    `url` and `api_token` from version 0.10.0 on - rename them there in the same step as the
+    update.
 
 ### Optional Parameters
 
@@ -107,11 +121,11 @@ You can customize the behavior with additional parameters:
 ```yaml
 pvinstallations:
   - name: HA Solar ML Forecast
-    base_url: ws://homeassistant:8123
+    url: ws://homeassistant:8123
     api_token: eyJ...
     entity_id: sensor.solar_forecast_ml_prognose_nachste_stunde
     sensor_unit: auto  # Options: 'auto' (default, auto-detect), 'Wh', or 'kWh'
-    cache_ttl_hours: 24.0  # Cache duration in hours (default: 24.0)
+    cache_ttl_hours: 24.0  # Cache duration in hours (default: 12.0)
 ```
 
 The `sensor_unit` parameter:
@@ -121,6 +135,30 @@ The `sensor_unit` parameter:
 
 Setting the explicit unit (`Wh` or `kWh`) can speed up startup by skipping auto-detection.
 
+The `cache_ttl_hours` parameter controls how long an already fetched forecast stays usable as a
+fallback when HomeAssistant cannot be reached (default: 12 hours). It does not control how often
+batcontrol asks for a new forecast — that is the refresh interval of the provider.
+
+### Troubleshooting
+
+**Problem:** batcontrol stops at startup with
+`Auth message incorrectly formatted: expected str at 'access_token'. Got None`
+
+**Solution:** the access token never reached the provider. Check that
+
+- the token is configured as `api_token` — `apikey` is the key name of the fcsolarapi and
+  Solcast providers and was a common mix-up ([issue #451](https://github.com/MaStr/batcontrol/issues/451))
+- the token sits in the same `pvinstallations` entry as `entity_id` and `url`
+- the entry belongs to the selected provider (see the note above about `type:`)
+
+Since batcontrol 0.10.0 a missing token is reported as a configuration error naming the key,
+before any connection to HomeAssistant is attempted.
+
+**Problem:** `No "url" configured for installation <name>, falling back to ws://homeassistant.local:8123`
+
+**Solution:** your URL is not in the entry batcontrol selected. Use the key `url` (or the
+deprecated `base_url`) in the entry that also holds `entity_id`.
+
 ## Solcast
 
 [Solcast](https://solcast.com/) provides satellite-based solar forecasts in native 30-minute resolution. batcontrol interpolates the values to 15-minute intervals (linear power interpolation) or aggregates them to hourly values, depending on your `time_resolution_minutes` setting.
@@ -134,7 +172,7 @@ Solcast offers a free "Home User" (hobbyist) account which is sufficient for bat
 1. Register at [solcast.com](https://solcast.com/free-rooftop-solar-forecasting) and choose the free **Home User** (hobbyist) plan.
 2. In the Solcast toolkit, create a **Rooftop Site**. Enter your location (latitude/longitude), panel tilt, azimuth and capacity (kWp) there — the site geometry lives in your Solcast account, **not** in the batcontrol configuration.
 3. Copy the site's **resource id** (shown in the site details, format `xxxx-xxxx-xxxx-xxxx`).
-4. Copy your **API key** from the Solcast account settings.
+4. Copy your **API key** from the Solcast account settings (configured as `api_token`).
 
 The free account is limited to **one location with up to two rooftop sites** (e.g. an east/west split) and **10 API requests per day**.
 
@@ -147,7 +185,7 @@ solar_forecast_provider: solcast
 pvinstallations:
   - name: Haus #name
     resource_id: xxxx-xxxx-xxxx-xxxx  # from your Solcast rooftop site
-    apikey: your-solcast-api-key      # from your Solcast account settings
+    api_token: your-solcast-api-key   # from your Solcast account settings
 ```
 
 For two rooftop sites (e.g. east/west arrays) use one entry per site. The API key is the same for both, each site has its own resource id:
@@ -157,10 +195,10 @@ solar_forecast_provider: solcast
 pvinstallations:
   - name: Dach Ost
     resource_id: xxxx-xxxx-xxxx-aaaa
-    apikey: your-solcast-api-key
+    api_token: your-solcast-api-key
   - name: Dach West
     resource_id: xxxx-xxxx-xxxx-bbbb
-    apikey: your-solcast-api-key
+    api_token: your-solcast-api-key
 ```
 
 ### Optional percentile parameter
@@ -171,7 +209,7 @@ You can select which estimate batcontrol uses per installation:
 pvinstallations:
   - name: Haus
     resource_id: xxxx-xxxx-xxxx-xxxx
-    apikey: your-solcast-api-key
+    api_token: your-solcast-api-key
     percentile: 10  # 10 (pessimistic), 50 (default, most likely), 90 (optimistic)
 ```
 

scripts/test_homeassistant_forecast.py

@@ -133,8 +133,8 @@ def main():
         # Build configuration dict for factory
         config = {
             'type': 'homeassistant-api',
-            'base_url': HOMEASSISTANT_URL,
-            'apitoken': HOMEASSISTANT_TOKEN,
+            'url': HOMEASSISTANT_URL,
+            'api_token': HOMEASSISTANT_TOKEN,
             'entity_id': ENTITY_ID,
             'history_days': HISTORY_DAYS,
             'history_weights': HISTORY_WEIGHTS,