petoss/fveread repository overview

⁠⚡ FVE Control (fvctl)

Lightweight Python-based controller for optimizing surplus energy usage (e.g. from photovoltaic systems) using Home Assistant.

The container periodically evaluates available power and dynamically switches configured devices (e.g. boilers) based on temperature thresholds, tariff conditions, and system state.

⁠🚀 Features

• Smart distribution of surplus energy
• Integration with Home Assistant API
• Temperature-driven device control
• Low-tariff support
• Fail-fast configuration validation
• Minimal resource footprint

⁠📦 Usage

⁠Docker Compose (example)

version: "3.8"

services:
  fvctl:
    image: petoss/fveread:latest
    container_name: fvctl
    restart: unless-stopped

    environment:
      TZ: Europe/Prague

    volumes:
      - ./config:/opt/fve/config:ro

⁠⚙️ Configuration

The container expects configuration files mounted into:

/opt/fve/config/

Required files:

• fveconfig.yaml – main configuration (Home Assistant, entities)
• devices.yaml – controlled devices definition

⁠▶️ Runtime

The container runs a simple loop:

• Fetch Home Assistant states
• Evaluate available energy
• Decide which devices to enable
• Apply state changes via API

Execution interval: 10 seconds

⁠🐳 Entrypoint

The container runs:

python3 /opt/fve/scripts/FVctl.py

with proper signal handling for graceful shutdown.

⁠🔧 Notes

• Requires a valid Home Assistant long-lived access token
• Designed for continuous operation
• Stateless container (configuration via mounted volume)

⁠📌 Use Case

Ideal for:

• photovoltaic surplus optimization
• boiler / heating control
• simple home energy automation without heavy dependencies

⁠🧠 Philosophy

• Keep it simple
• Fail early on bad config
• Let Home Assistant handle state, this handles logic