Skip to content

INTEGRATIONS.md

Latest commit

 

History

History
104 lines (77 loc) · 3.15 KB

INTEGRATIONS.md

File metadata and controls

104 lines (77 loc) · 3.15 KB

Integrations

This document summarizes each integration, required configuration, and operational notes.

HomeWizard P1

Purpose: live net grid import/export.

HOMEWIZARD_HOST=homewizard.local

The adapter reads the P1 meter over the local LAN. This is the most important data source because it gives live net power at the meter.

Huawei FusionSolar

Purpose: solar production.

HUAWEI_SOURCE=fusionsolar
FUSIONSOLAR_BASE_URL=https://eu5.fusionsolar.huawei.com
FUSIONSOLAR_USERNAME=your_openapi_username
FUSIONSOLAR_SYSTEM_CODE=your_openapi_system_code
FUSIONSOLAR_STATION_CODE=
FUSIONSOLAR_VERIFY_TLS=true
FUSIONSOLAR_MIN_POLL_SECONDS=360

Operational notes:

  • Requires a FusionSolar Northbound/OpenAPI account.
  • Station codes can be supplied directly or discovered where supported.
  • The API is rate-limited. Polling too often can return throttling responses.
  • The adapter uses cached values and backs off after throttling.
  • If solar is unavailable, the backend does not infer true home load from net grid flow alone.

Panasonic Aquarea

Purpose: heat-pump telemetry and guarded commands.

PANASONIC_ENABLED=true
PANASONIC_SOURCE=aquarea
PANASONIC_USERNAME=your_panasonic_account_email
PANASONIC_PASSWORD=your_panasonic_account_password
PANASONIC_AQUAREA_ENVIRONMENT=production
PANASONIC_VERIFY_TLS=true
PANASONIC_MIN_POLL_SECONDS=60
PANASONIC_SETPOINT_MIN_C=18
PANASONIC_SETPOINT_MAX_C=30
PANASONIC_APP_VERSION=4.1.0

Operational notes:

  • The adapter follows Panasonic Aquarea cloud behavior through an unofficial client path.
  • The backend exposes power, mode, and setpoint command endpoints.
  • Setpoint commands are bounded by configured safety limits.
  • If Panasonic throttles or returns limited data, the dashboard shows degraded connection health.

Samsung SmartThings

Purpose: read-only appliance discovery and state.

SMARTTHINGS_ENABLED=true
SMARTTHINGS_TOKEN=your_smartthings_token
SMARTTHINGS_MIN_POLL_SECONDS=60
SMARTTHINGS_DEVICE_IDS=

Operational notes:

  • Leave SMARTTHINGS_DEVICE_IDS empty to auto-detect likely Samsung appliances.
  • Some appliances expose live power, while others expose only state or cycle details.
  • The adapter uses conservative load estimates when a running appliance does not expose direct watts.
  • The app does not send appliance control commands.

Open-Meteo

Purpose: local weather context.

WEATHER_ENABLED=true
WEATHER_LATITUDE=your_latitude
WEATHER_LONGITUDE=your_longitude
WEATHER_LOCATION_LABEL=Home
WEATHER_MIN_POLL_SECONDS=900

Operational notes:

  • No API key is required.
  • The dashboard shows temperature, apparent temperature, cloud cover, wind, rain, condition, and observation time.
  • Coordinates should be approximate enough for useful weather without over-sharing exact home location in public examples.

Adding a New Integration

  1. Add a typed adapter in app/adapters/.
  2. Add config values in app/config.py.
  3. Add response models in app/models.py if the API shape changes.
  4. Update app/main.py to read the adapter, report connection health, and degrade cleanly on failure.
  5. Keep polling and backoff behavior explicit.
  6. Update the React dashboard and this document.