🔭 AetherLens Home Edition

See Through Your Digital Energy Cloud - Open-source cost and usage monitoring for smart homes, IoT devices, and personal cloud services.

🏠 What is AetherLens?

AetherLens brings enterprise-grade cost monitoring and optimization to your home lab. Track every watt, every API call, and every penny across your entire digital footprint - from smart plugs to cloud services. Built by the home lab community, for the home lab community.

🎯 Perfect For

• Home Lab Enthusiasts running Proxmox, TrueNAS, or Kubernetes clusters
• Smart Home Users with complex Home Assistant, Node-RED, or IoT setups
• Self-Hosters managing their own services and infrastructure
• Crypto Miners tracking profitability and power costs across mining rigs
• Solar Power Owners optimizing self-consumption vs. grid export/import
• Remote Workers managing home office expenses and energy efficiency
• AWS/Azure Personal Users tracking cloud spending on personal projects

✨ Key Features

📊 Unified Cost Dashboard

• Real-time monitoring of power consumption across all devices
• Historical trends and usage patterns with customizable time ranges
• Cost breakdowns by device, room, category, or cloud service
• Time-of-use optimization suggestions to reduce peak-hour costs
• Budget tracking with alerts when approaching spending limits

🔌 Extensive Integrations

Smart Home Devices:

• Smart Plugs: TP-Link Kasa, Shelly, Tasmota, Zigbee devices
• Energy Monitors: Emporia Vue, Sense, IoTaWatt, CurrentCost
• Home Automation: Home Assistant, Hubitat, SmartThings, openHAB

Solar & Battery Systems:

• Inverters: Tesla Powerwall, Enphase, SolarEdge, Fronius, SMA
• Battery Management: LG Chem, Sonnen, BYD

Cloud Services:

• AWS Cost Explorer API (personal accounts)
• Azure Cost Management API
• Google Cloud Billing API

Crypto Mining:

• Mining Pools: NiceHash, Ethermine, F2Pool
• Mining Management: HiveOS, Awesome Miner

💡 Smart Analysis Features

• Anomaly Detection - Identify unusual consumption patterns automatically
• Cost Predictions - Estimate monthly bills before they arrive
• Optimization Recommendations - AI-driven suggestions to reduce costs
• Carbon Footprint Tracking - Monitor your environmental impact
• Bill Verification - Compare actual vs. utility company bills
• Peak Shaving - Recommendations to reduce demand charges

🔒 Privacy First

• 100% Local Processing - All data stays on your hardware
• No Cloud Required - Functions completely offline
• Optional Encryption - Encrypt data at rest for extra security
• Data Ownership - Export anytime in standard formats (CSV, JSON, Parquet)
• No Telemetry - Zero data collection, zero analytics, zero tracking

🚀 Quick Start

Docker Compose (Recommended)

version: '3.8'
services:
  aetherlens:
    image: aetherlens/home:latest
    container_name: aetherlens
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
      - ./config:/config
    environment:
      - TZ=America/New_York
      - TIMESCALEDB_URL=postgresql://postgres:password@timescaledb:5432/aetherlens
    restart: unless-stopped

  timescaledb:
    image: timescale/timescaledb:latest-pg15
    container_name: aetherlens-db
    volumes:
      - ./timescaledb:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=aetherlens
    restart: unless-stopped

# Start the stack
docker-compose up -d

# Access the web UI
open http://localhost:8080

# Check logs
docker-compose logs -f aetherlens

Standalone Installation

# Download the latest release
curl -L https://github.com/aetherlens/home/releases/latest/download/aetherlens-linux-amd64 -o aetherlens
chmod +x aetherlens

# Initialize configuration
./aetherlens init

# Edit configuration
nano ~/.aetherlens/config.yaml

# Start the service
./aetherlens start

# Access web UI
open http://localhost:8080

Home Assistant Add-on

1. Add the AetherLens repository to your Home Assistant:

   https://github.com/aetherlens/home-assistant-addon
   

2. Navigate to Settings → Add-ons → Add-on Store

3. Search for AetherLens and click Install

4. Configure the add-on and click Start

5. Access via the Home Assistant sidebar

📖 Configuration Example

# ~/.aetherlens/config.yaml
general:
  currency: USD
  timezone: America/New_York
  data_retention_days: 90
  
energy_rates:
  provider: "Pacific Gas & Electric"
  plan: "Time-of-Use (TOU)"
  time_of_use:
    peak:
      rate: 0.42
      hours: "16:00-21:00"
      days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
    off_peak:
      rate: 0.24
      hours: "00:00-15:59,21:01-23:59"
      days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
    super_off_peak:
      rate: 0.12
      hours: "00:00-23:59"
      days: ["saturday", "sunday"]
  fixed_charges:
    monthly_service_fee: 10.00
    demand_charge_per_kw: 15.00

plugins:
  - name: shelly
    enabled: true
    poll_interval: 30
    devices:
      - ip: 192.168.1.100
        name: "Office Desk"
        room: "Office"
        device_id: "shelly-office-desk"
      - ip: 192.168.1.101
        name: "Server Rack"
        room: "Lab"
        device_id: "shelly-server-rack"
        
  - name: home_assistant
    enabled: true
    url: "http://homeassistant.local:8123"
    token: "${HA_TOKEN}"
    entities:
      - entity_id: "sensor.washing_machine_power"
        device_name: "Washing Machine"
        room: "Laundry"
    
  - name: aws_cost
    enabled: true
    profile: "personal"
    regions: ["us-east-1", "us-west-2"]
    poll_interval: 3600  # Check hourly
    
  - name: emporia_vue
    enabled: true
    username: "${EMPORIA_USERNAME}"
    password: "${EMPORIA_PASSWORD}"
    devices:
      - device_id: "12345"
        name: "Main Panel"

alerts:
  - name: "High Office Consumption"
    device_id: "shelly-office-desk"
    condition: "power > 500"  # Watts
    duration: 300  # Seconds
    actions:
      - type: notification
        channels: ["email", "pushover"]
        message: "Office desk using over 500W for 5 minutes"
      - type: automation
        action: "send_webhook"
        url: "http://home-assistant.local:8123/api/webhook/high_power_alert"

🔌 Plugin Development

Create custom plugins to monitor any device or service:

# plugins/my_device_plugin.py
from aetherlens_sdk import BasePlugin, Metric
import aiohttp
import time

class MyDevicePlugin(BasePlugin):
    """Plugin for monitoring custom devices"""
    
    def __init__(self, config: dict):
        super().__init__(config)
        self.device_ip = config['device_ip']
        self.poll_interval = config.get('poll_interval', 30)
    
    async def collect_metrics(self) -> list[Metric]:
        """Collect power metrics from device"""
        async with aiohttp.ClientSession() as session:
            async with session.get(f"http://{self.device_ip}/status") as resp:
                data = await resp.json()
        
        return [
            Metric(
                device_id=self.config['device_id'],
                metric_type='power',
                value=data['power_watts'],
                unit='watts',
                timestamp=time.time(),
                tags={'room': self.config.get('room', 'unknown')}
            ),
            Metric(
                device_id=self.config['device_id'],
                metric_type='energy',
                value=data['total_kwh'],
                unit='kWh',
                timestamp=time.time()
            )
        ]
    
    async def discover_devices(self) -> list:
        """Optional: Implement device discovery"""
        return []
    
    def get_capabilities(self) -> list[str]:
        return ['power', 'energy']

# Register plugin
PLUGIN_CLASS = MyDevicePlugin

📚 Full Plugin Development Guide →

📈 Visualization & Export

Built-in Dashboards

• Overview Dashboard - Real-time consumption, current costs, top consumers
• Device Details - Individual device history, statistics, cost breakdown
• Room/Zone View - Consumption grouped by physical location
• Cost Analysis - Daily, weekly, monthly trends with forecasting
• Time-of-Use Optimizer - Recommendations for shifting loads
• Carbon Dashboard - CO₂ emissions tracking and reduction tips

Grafana Integration

# Import pre-built dashboards
./aetherlens grafana export --output ./dashboards

# Or use Prometheus endpoint directly
# Add data source in Grafana:
# Type: Prometheus
# URL: http://aetherlens:8080/metrics

Data Export

# Export to CSV
./aetherlens export csv --start 2024-01-01 --end 2024-12-31 --output energy_data.csv

# Export to JSON
./aetherlens export json --device shelly-office-desk --days 30 --output office_data.json

# Stream to external InfluxDB
./aetherlens export influx --url http://influxdb:8086 --bucket home_metrics --continuous

# Backup entire database
./aetherlens backup --output ./backups/aetherlens-$(date +%Y%m%d).tar.gz

🛣️ Roadmap

Phase 1 - Foundation ✅ COMPLETE (October 2025)

Status: ✅ Complete - View Summary

• Project structure and development tooling (ruff, black, isort, mypy)
• CI/CD pipeline (GitHub Actions with 6 jobs)
• Git hooks preventing CI failures (pre-push validation)
• Test infrastructure (unit, integration, security tests - 47.82% coverage)
• Windows development environment (full batch script support)
• Documentation (WINDOWS-SETUP.md, DEVELOPMENT-WORKFLOW.md, CONTRIBUTING.md)
• Security scanning and validation

Key Achievement: Perfect local/CI parity - errors caught before GitHub!

Phase 2 - Core Implementation 📋 READY (TBD)

Status: 📋 Ready to Start - View Kickoff Plan

Objectives:

• Fix 41 mypy type errors, make type checking blocking
• Implement API endpoints (auth, devices CRUD, metrics)
• Increase test coverage from 47.82% to ≥70%
• Complete database layer and migrations
• Create quality test suite

Phase 3 - Intelligence 📋 (Future)

• Machine learning cost predictions
• Automated optimization recommendations
• Anomaly detection algorithms
• Mobile app (iOS/Android) with push notifications
• 25+ plugin integrations
• Advanced rate structures (tiered, demand charges)
• Solar production and net metering support

Phase 3 - Ecosystem 📋 (Q3 2025)

• Plugin marketplace and registry
• Optional cloud sync (E2E encrypted)
• Multi-home/site support
• Small business features (multiple accounts, reporting)
• Energy arbitrage automation (grid export optimization)
• Integration with smart thermostats and EV chargers
• Advanced carbon footprint calculations

Phase 4 - Advanced Features 📋 (Q4 2025)

• Distributed deployment for large installations
• Neo4j integration for complex relationship queries
• Custom alert scripting (Python/Lua)
• Home energy audit recommendations
• Utility bill parsing and reconciliation
• Peer-to-peer energy trading (blockchain integration)

View Full Roadmap →

🤝 Contributing

We love contributions! Whether it's:

• 🐛 Bug reports and feature requests
• 🔌 New device plugins
• 📖 Documentation improvements
• 💻 Code contributions
• 🌍 Translations
• 🎨 UI/UX enhancements

Please see our Contributing Guide for details.

Development Setup

Quick Start:

# Clone and setup
git clone https://github.com/aetherlens/home.git
cd aetherlens
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\activate

# Install dependencies
pip install -r requirements-dev.txt
pip install -e .

# Install pre-commit hooks (prevents CI failures)
pip install pre-commit
pre-commit install

# Verify setup
./venv/Scripts/ruff check src/ tests/
./venv/Scripts/black --check src/ tests/
./venv/Scripts/pytest tests/unit/ -v

Before Every Commit/Push:

# Run linting (matches GitHub Actions CI exactly)
./venv/Scripts/ruff check src/ tests/
./venv/Scripts/black --check src/ tests/
./venv/Scripts/isort --check-only src/ tests/
./venv/Scripts/mypy src/

# Or use Make (Linux/Mac):
make lint

# Auto-fix formatting issues:
./venv/Scripts/black src/ tests/
./venv/Scripts/isort src/ tests/
# Or: make format

📚 Full Documentation:

• QUICKSTART.md - Get started in 5 minutes
• docs/DEVELOPMENT.md - Complete development guide
• docs/TESTING.md - Testing documentation
• docs/API.md - API reference
• CLAUDE.md - AI-assisted development guidelines

Top Contributors

💬 Community

• Discord: Join our Discord - Active community, real-time help
• Forum: community.aetherlens.io - Long-form discussions
• Reddit: r/aetherlens - News and showcases
• Twitter/X: @aetherlens - Updates and tips
• GitHub Discussions: Ask questions and share ideas

🏆 Success Stories

"Cut my electricity bill by 30% after identifying vampire loads I never knew existed. The time-of-use optimizer alone saved me $40/month!" - @homelab_hero

"Finally understand what my solar panels are actually saving me. The production vs. consumption dashboard is exactly what I needed." - @solar_saver

"The Home Assistant integration is flawless. Seeing all my device costs in one place changed how I think about my smart home." - @smart_home_sam

"Discovered my crypto mining rig was costing more in electricity than it was earning. Made the decision to shut it down based on real data." - @crypto_realist

📊 Community Stats

🛡️ Security

Security is our top priority:

• All credentials stored encrypted using platform keyring
• Optional encryption at rest for time-series data
• Regular dependency scanning with Dependabot
• Security audit reports published quarterly

Please report vulnerabilities to security@aetherlens.io

See SECURITY.md for our complete security policy.

📝 License

AetherLens Home Edition is licensed under the MIT License. See LICENSE for details.

This means you can:

• ✅ Use commercially
• ✅ Modify and distribute
• ✅ Use privately
• ✅ Sublicense

You must:

• 📄 Include the license and copyright notice

🙏 Acknowledgments

Built with amazing open-source projects:

• TimescaleDB - Time-series data storage
• FastAPI - High-performance API framework
• React - UI framework
• Home Assistant - Inspiration and integration
• Grafana - Visualization capabilities

Special thanks to all our plugin contributors!

🔗 Related Projects

• Home Assistant - Open source home automation
• Sense - Whole-home energy monitor
• Emporia Vue - Circuit-level monitoring
• Solar-Log - Solar monitoring system
• CloudHealth - Cloud cost management (enterprise)

🚦 Project Status

---

⚡ Every Watt Counts - From Home to Cloud ⚡

_{Built with ❤️ by the home lab community, for the home lab community}

⭐ Star us on GitHub • 💬 Join Discord • 🔌 Write a Plugin