implement econet exporter

README.md

@@ -1,74 +1,73 @@
-# go-server-with-otel 🚀
+# econet-exporter 🔥💧
 
-A powerful and flexible template for building Go HTTP + GRPC servers with full OpenTelemetry (OTEL) support.
-Bootstrapped with the go-app framework to provide all the bells and whistles right out of the box.
-Ideal for rapidly creating production-ready microservices.
+An exporter for **Rheem EcoNet / Rheemcloud** water-heater data. It keeps a
+long-lived connection to the Rheem cloud (via
+[`rheemcloud-go`](https://github.com/kevinburke/rheemcloud-go)) and exposes device
+state and usage three ways:
 
-Check out the [go-app framework](https://gitea.libretechconsulting.com/rmcguire/go-app) for more detail there.
+- **OTEL metrics** served for Prometheus scraping at `/metrics` (live state +
+  energy/water usage, including a dollar-cost metric).
+- A simple **gRPC API** (`ListDevices`, `GetDevice`) with a grpc-gateway REST
+  frontend under `/api`.
+- An **MCP tool** (`list_water_heaters`) at `/api/mcp` that wraps the gRPC API.
 
-## 🌟 Features
+Built on the [go-app framework](https://gitea.libretechconsulting.com/rmcguire/go-app),
+which provides OTEL, the Prometheus endpoint, gRPC + gateway, health checks,
+config/env loading, and graceful shutdown.
 
-- **📈 OpenTelemetry (OTEL) Metrics & Traces** – Comprehensive observability with built-in support for metrics and traces.
-- 📝 Logging with Zerolog – High-performance structured logging with zerolog for ultra-fast, leveled logging.
-- 💻 Local dev with air pre-configured (just run `air`)
-- **💬 GRPC + GRPC-Gateway** – Supports RESTful JSON APIs alongside gRPC with auto-generated Swagger (OpenAPI2) specs.
-- 🌐 HTTP and GRPC Middleware – Flexible middleware support for HTTP and GRPC to enhance request handling, authentication, and observability.
-- **📦 Multi-Arch Builds** – Robust Makefile that supports building for multiple architectures (amd64, arm64, etc.).
-- **🐳 Docker Image Generation** – Easily build Docker images using `make docker`.
-- **📜 Config Schema Generation** – Automatically generate JSON schemas for configuration validation.
-- **📝 Proto Compilation** – Seamlessly compile .proto files with `make proto`.
-- **🔄 Project Renaming** – Easily rename your project using `make rename NAME=your.gitremote.com/pathto/repo`.
-- **📦 Helm Chart** – Deploy your application with Kubernetes using the provided Helm chart.
-- **🤖 Gitea CI Integration** – Out-of-the-box Gitea CI pipeline configuration with `.gitea/workflows/ci.yaml`.
-- **⚙️ Expandable Configuration** – Extend your app-specific configuration with go-app's built-in logging, HTTP, and GRPC config support.
+## ⚙️ Configuration
 
----
+Config merges a YAML file (`-config config.yaml`), environment variables, and
+go-app defaults. Custom fields (see `pkg/config/custom.go`):
 
-## 📚 Getting Started
+| Field | Env var | Notes |
+|-------|---------|-------|
+| `econetEmail` | `ECONET_EMAIL` | Rheem account email |
+| `econetPassword` | `ECONET_PASSWORD` | Prefer the env var; keep out of config.yaml |
+| `costPerKWH` | `ECONET_COST_PER_KWH` | **US dollars per kWh** (e.g. `0.18` = 18¢), not cents |
+| `usageInterval` | `ECONET_USAGE_INTERVAL` | Energy/water poll interval (default `5m`) |
 
-1. Install tools:
-   - Install make, protoc, and go using brew, apt, etc..
-   - Install protoc plugins (provided in go.mod tool()):
-      - `go get -v tool && go install -v tool`
+Everything under the go-app `AppConfig` (logging, otel, http, grpc) is also
+env-overridable with `APP_*` variables — see `env-sample`.
 
-1. **Rename your package:**
-   ```sh
-   make rename NAME=my.gitremote.com/pathto/repo
-   ```
+## 🚀 Running
 
-1. **Review the config struct:**
-   Update and customize your app-specific configuration. This merges with go-app's configuration, providing logging, HTTP, and GRPC config for free.
+```sh
+export ECONET_EMAIL=you@example.com ECONET_PASSWORD=... ECONET_COST_PER_KWH=0.14
+go run . -config config.yaml
+```
 
-1. **Generate a new JSON schema:**
-   ```sh
-   make schema
-   ```
-   - Ensure your structs have `yaml` and `json` tags.
-   - With the `yaml-language-server` LSP plugin, the schema will be auto-detected in your `config.yaml`.
+Then:
+- `curl localhost:8080/metrics | grep econet_`
+- `curl localhost:8080/api/v1alpha1/devices` (REST via grpc-gateway)
+- `grpcurl -plaintext localhost:8081 econet.v1alpha1.EconetService/ListDevices`
+- MCP: point a client at `http://localhost:8080/api/mcp`
 
-1. **Compile proto files:**
-   ```sh
-   make proto
-   ```
-   - Add paths under `proto/` as necessary.
+## 📊 Metrics
 
-1. **Implement your application logic.**
-
-1. **Update Gitea CI configuration:**
-   Modify parameters in `.gitea/workflows/ci.yaml` as needed.
-
-1. Tag your release: `git tag v0.1.0` and push `git push --tags`
-
----
+Per-device gauges labeled `econet.serial`, `econet.device_id`,
+`econet.friendly_name`: `econet_setpoint_fahrenheit`, `econet_connected`,
+`econet_running`, `econet_enabled`, `econet_away`,
+`econet_hot_water_availability_percent`, `econet_alert_count`,
+`econet_wifi_signal_db`, `econet_device_info` (adds `type`/`generic_type`/`mode`).
+Polled usage: `econet_energy_usage_kwh`, `econet_water_usage_gallons`,
+`econet_energy_cost_dollars`.
 
 ## 📂 Project Structure
-- `proto/` - Protobuf definitions and generated files.
-- `api/` - Auto-generated code for proto, grpc-gateway, and OpenAPI2 spec
-- `pkg/config/` - Custom config, merged with go-app configuration
-- `pkg/demo(http|grpc)/` - HTTP and GRPC server implementations
-- `helm/` - Helm chart for deploying your application to Kubernetes.
-- `.gitea/workflows/` - CI pipelines for automated builds and tests.
+- `proto/econet/v1alpha1/` - Protobuf definitions (source).
+- `api/econet/v1alpha1/` - Generated proto, grpc, grpc-gateway code.
+- `pkg/config/` - Custom config merged with go-app configuration.
+- `pkg/econet/` - `EconetService` (owns the rheemcloud client) plus:
+  - `econetgrpc/` - gRPC `EconetService` implementation.
+  - `econetmcp/` - MCP server + tools.
+  - `econetmetrics/` - OTEL observable gauges + usage poller.
+- `helm/` - Helm chart for Kubernetes deployment.
+- `.gitea/workflows/` - CI pipelines.
 
----
+## 🛠️ Development
 
-## 🔥 Ready to build something awesome? Let's go! 🎉
+- `make proto` - regenerate code from `proto/`.
+- `make schema` - regenerate `contrib/schema.json` from the config struct.
+- `make build` / `make docker` - multi-arch build / image.
+
+See `AGENTS.md` for agent-oriented development notes.