FLUX-HOC

A Home Operations Center built in Rust. Collects real-time data from solar inverters, geothermal HVAC, electric vehicles, whole-home energy monitoring, weather, and utility billing — stores everything in InfluxDB and PostgreSQL, exposes it through a REST API and a retro phosphor-aesthetic web dashboard, and delivers operational intelligence via Claude AI analysis.

Designed to run on a local server via Docker Compose. No cloud subscriptions required for core functionality.

WebUI

Main Tab - 1 Day view

Geothermal Tab - 1 Day view

Terminal

---

Features

• Real-time solar production monitoring across multiple inverters (SMA Sunny Boy)
• Geothermal HVAC performance tracking — COP calculation, loop temperatures, per-component energy use
• EV charging session history and cost attribution (Tesla Wall Connector Gen 3 local API)
• Whole-home energy monitoring via Sense real-time WebSocket feed
• Weather correlation — temperature, irradiance, heating/cooling degree days (Open-Meteo, no API key)
• Utility billing import and cost attribution per system (National Grid Green Button)
• IoT sensor ingestion via MQTT
• Month-over-month and year-over-year comparisons at the monthly summary level
• Claude AI analysis — scheduled daily/weekly/monthly briefings and on-demand queries
• Prometheus metrics + Grafana dashboards
• htop-style terminal dashboard (flux-tui)

---

Project Rationale

I wanted a single pane of glass for understanding how my home generates, consumes, and exchanges electricity — and to answer questions like: does my geothermal COP degrade in extreme cold? Does solar production offset EV charging costs month-over-month? Existing tools answered these questions in isolation. FLUX-HOC connects them.

---

Supported Connectors

Connector	Device	Protocol	Status
sma	SMA Sunny Boy 5.0-US (×2)	HTTPS REST (WebConnect)	Implemented
sense	Sense energy monitor	WebSocket (real-time feed)	Implemented
waterfurnace	WaterFurnace 7-Series + 5-Series geothermal	Symphony WSS (interim) / RS-485 Modbus via Pi	Implemented
tesla	Tesla Model Y	Tessie API	Roadmap (associated cost)
wall-connector	Tesla Wall Connector Gen 3	Local HTTP (unauthenticated)	Implemented
nationalgrid	National Grid utility	Green Button CMD (ESPI XML)	Roadmap (using manual pdf process for now)
weather	Open-Meteo	REST (no API key)	Implemented
mqtt	Generic IoT sensors	MQTT subscribe	Roadmap
modbus	RS-485 bridge via Raspberry Pi	HTTP → Modbus RTU	Roadmap

Adding a new connector (different EV brand, HVAC system, inverter manufacturer) requires only a new crate implementing the Connector trait — no UI or schema changes. See CONTRIBUTING.md.

---

Quick Start

Note: Designed for homeowners with solar + geothermal + EV setups. Tested on a home network in the Greater Boston area.

Prerequisites: Docker Desktop, git, a .env file (copy from .env.example).

git clone https://github.com/tim-ireland/flux-rs
cd flux-rs
cp .env.example .env
# Edit .env — fill in inverter URLs, API tokens, passwords

Start the infrastructure services:

docker compose -f docker/docker-compose.yml up -d

Run the daemon locally (during development):

cargo run --bin fluxd

Open the dashboard:

• Web UI: http://localhost:8080
• Grafana: http://localhost:3000
• InfluxDB: http://localhost:8086

---

Configuration

All configuration lives in two places:

config/flux.toml — structural config (connector names, poll intervals, measurement definitions). No secrets, safe to commit.

[site]
name = "Home"
latitude = 42.36
longitude = -71.06
timezone = "America/New_York"

[[connectors]]
type = "sma"
name = "sb-north"
poll_interval_secs = 10

[[connectors]]
type = "sma"
name = "sb-south"
poll_interval_secs = 10

Environment variables (in .env, never committed) — all URLs, credentials, and tokens:

Variable	Description
SMA_SB_NORTH_URL	SMA inverter LAN URL, e.g. https://192.168.1.51
SMA_SB_NORTH_PASSWORD	Inverter password (max 12 chars, User group)
SENSE_PASSWORD	Sense account password
TESSIE_TOKEN	Tessie API token for Tesla data
WATERFURNACE_PASSWORD	Symphony account password
INFLUXDB_URL	InfluxDB v2 URL, e.g. http://localhost:8086
INFLUX_TOKEN	InfluxDB write token
POSTGRES_URL	PostgreSQL connection string
ANTHROPIC_API_KEY	Claude API key for AI analysis

See .env.example for the full list.

---

Architecture

FLUX-HOC is a Cargo workspace. Connectors run as independent Tokio tasks and publish MetricEvent structs onto a broadcast channel. Sinks (InfluxDB, PostgreSQL, Prometheus) fan out from the channel and write concurrently.

graph LR
    SMA --> Bus[broadcast channel]
    Sense --> Bus
    WF[WaterFurnace] --> Bus
    Tesla --> Bus
    WC[Wall Connector] --> Bus
    Bus --> InfluxDB
    Bus --> Postgres
    Bus --> Prometheus

Loading

For full architecture documentation see docs/architecture.md. Key design decisions are captured as Architecture Decision Records in docs/adr/.

---

Adding a Connector

See CONTRIBUTING.md for the full connector contract. The short version:

1. Create crates/connectors/flux-connector-{type}/
2. Implement the Connector trait (name, category, capabilities, poll/run)
3. Register in bins/fluxd/src/registry.rs
4. Add example config to config/examples/{type}.toml

The UI renders by DeviceCategory, not by connector type — a new EV brand appears in the VEHICLES panel automatically.

---

Safety

SMA and WaterFurnace connectors are read-only by design. The SmaReadClient and ReadOnlyModbus types have no write methods — incorrect write calls are a compile error, not a runtime error. See docs/connectors/sma.md and docs/connectors/waterfurnace.md.

---

Development

just test       # run all tests
just lint       # cargo fmt check + clippy -D warnings
just fmt        # format all code
just up         # start Docker infrastructure
just run        # run fluxd locally

Requires: Rust (via rustup, toolchain pinned in rust-toolchain.toml), just, Docker Desktop.

---

License

MIT