Shelly Plug Power Logger

Inspired by Bert Hubert's presentation at Joy of Coding:

"Save the world, write more efficient code."

A repeatable measurement framework that correlates:

• Power consumption over time (via Shelly Plug S Gen3)
• User interaction events (keyboard/mouse)
• Application/process activity

Understand the energy footprint of your software and work habits.

Quick Start

1. Install

# Clone the repository
git clone https://github.com/NickAldewereld/shellyplugpowerlogger.git
cd shellyplugpowerlogger

# Install dependencies
pip install -r requirements.txt

# For input event capture (recommended)
pip install pynput

2. Configure

Set your Shelly device IP:

export SHELLY_URL="http://192.168.1.38/rpc/Switch.GetStatus?id=0"

Or edit directly in scripts/config.

3. Capture (one command)

# Capture for 60 seconds
python -m src.correlate capture --duration 60

This simultaneously:

• Polls power from Shelly device
• Captures keyboard/mouse events
• Samples top processes by CPU

4. Analyze (one command)

python -m src.correlate analyze --plot

Produces:

• data/session_summary.json - Statistics and metrics
• data/aligned_timeseries.csv - Correlated data
• data/event_costs.csv - Energy cost per event type
• data/plots/session.png - Visualization

5. View Results

SESSION SUMMARY
==================================================
Duration: 1m 0s
Readings: 60 valid / 60 total

Power:
  Average: 45.2 W
  Min/Max: 32.1 / 89.3 W
  Median:  43.5 W

Total Energy: 2712.0 J (0.753 Wh)
Baseline (idle): 35.2 W

Input Events:
  key_press: 245
  mouse_click: 42
  mouse_move: 189

Energy per Event Type (avg):
  key_press: 0.125 J
  mouse_click: 0.089 J

Features

• Power Logging: Robust polling from Shelly Plug S Gen3 with error handling
• Input Tracking: Privacy-first keyboard/mouse event capture (timestamps only, no content)
• Process Sampling: Track which applications consume CPU during measurements
• Correlation Engine: Align data sources and compute energy attribution
• Visualization: Power plots with event markers and baseline
• Extensible: Export to InfluxDB, MQTT, REST APIs

Privacy

We never capture keystroke content. Only event timestamps and types are recorded.

See docs/security.md for full privacy documentation.

Repository Structure

shellyplugpowerlogger/
├── README.md
├── LICENSE                    # MIT License
├── requirements.txt
├── pyproject.toml
│
├── scripts/
│   ├── shelly_log.sh         # Standalone bash logger
│   ├── start_session.sh      # Start measurement session
│   └── stop_session.sh       # Stop running session
│
├── src/
│   ├── common/               # Shared utilities
│   │   ├── config.py         # Configuration management
│   │   └── timeutil.py       # Timestamp utilities
│   │
│   ├── correlate/            # Core measurement modules
│   │   ├── __main__.py       # CLI entrypoint
│   │   ├── input_events.py   # Keyboard/mouse capture
│   │   ├── proc_sample.py    # Process sampling
│   │   ├── shelly_reader.py  # Shelly device communication
│   │   ├── align.py          # Correlation engine
│   │   └── export.py         # Output formatters
│   │
│   └── visualize/
│       └── plot_power.py     # Matplotlib visualizations
│
├── examples/
│   ├── api_push_example.sh   # Push data to REST API
│   ├── mqtt_forwarder.md     # MQTT integration guide
│   └── influx_write_example.py  # InfluxDB integration
│
├── docs/
│   ├── metrics.md            # Metric definitions
│   ├── experiments.md        # Experiment templates
│   ├── security.md           # Privacy & security
│   └── architecture.md       # Technical architecture
│
├── data/                     # Output directory (gitignored except .gitkeep)
│
└── [legacy files]            # Original scripts (kept for reference)
    ├── mainshellyscript      # Original bash logger
    ├── visualizeinpython     # Original matplotlib script
    └── externalconnectshelly # Original integration notes

Usage Examples

Basic Power Logging (bash only)

# Simple power logging without Python
./scripts/shelly_log.sh --url http://192.168.1.38/rpc/Switch.GetStatus?id=0 --out data/power.csv

Extended Capture Session

# 5-minute session with all features
python -m src.correlate capture \
    --duration 300 \
    --url http://192.168.1.38/rpc/Switch.GetStatus?id=0 \
    --output-dir data/session_001

# Analyze
python -m src.correlate analyze \
    --input-dir data/session_001 \
    --plot

Using xinput Backend (X11 fallback)

# If pynput doesn't work (e.g., Wayland)
python -m src.correlate capture \
    --duration 60 \
    --input-backend xinput

Disable Input/Process Capture

# Power only
python -m src.correlate capture --duration 60 --no-input --no-proc

Troubleshooting

Shelly Not Responding

1. Check Shelly is on the network: ping 192.168.1.38
2. Test the API: curl http://192.168.1.38/rpc/Switch.GetStatus?id=0
3. Ensure Shelly firmware is up to date (Gen3 required)

pynput Permission Issues

On Linux (X11):

# Usually works without special permissions
python -m src.correlate capture --duration 10

On Linux (Wayland):

# pynput has limited Wayland support
# Use xinput fallback (X11 apps only):
python -m src.correlate capture --input-backend xinput

# Or run with elevated permissions (not recommended)

xinput Not Found

# Install xinput (Debian/Ubuntu)
sudo apt install xinput

# Verify
xinput list

Process Sampling Missing IO Data

IO counters may require elevated privileges:

# Run with sudo (not recommended for regular use)
sudo python -m src.correlate capture --duration 60

Configuration

Environment variables:

Variable	Default	Description
SHELLY_URL	http://192.168.1.38/rpc/Switch.GetStatus?id=0	Shelly RPC endpoint
DATA_DIR	data	Output directory
INPUT_BACKEND	pynput	Input capture backend (pynput/xinput)
POLL_INTERVAL	1.0	Power polling interval (seconds)
PROC_INTERVAL	1.0	Process sampling interval (seconds)

External Integrations

InfluxDB

export INFLUX_URL="http://localhost:8086"
export INFLUX_TOKEN="your-token"
export INFLUX_ORG="your-org"
export INFLUX_BUCKET="power"

python examples/influx_write_example.py

MQTT

See examples/mqtt_forwarder.md for integration with:

• Home Assistant
• Node-RED
• Grafana/Telegraf

REST API

export API_ENDPOINT="https://your-api.com/power"
./examples/api_push_example.sh

Documentation

• Metrics Reference - What we measure and how
• Experiment Guide - Templates for common experiments
• Security & Privacy - Privacy guarantees and security model
• Architecture - Technical deep-dive

Why This Exists

Software efficiency matters. Most developers have no visibility into the energy impact of their code. This tool aims to:

1. Make energy visible - See real power consumption as you work
2. Enable experimentation - Compare editors, browsers, build tools
3. Build awareness - Understand what activities consume energy
4. Stay lightweight - Minimal dependencies, runs anywhere

"To measure is to know. If you cannot measure it, you cannot improve it." — Lord Kelvin

Contributing

Contributions welcome! Areas of interest:

• macOS/Windows input capture support
• Additional visualization types
• More export formats
• Hardware acceleration detection

License

MIT License - See LICENSE

Author

Nick Aldewereld

• LinkedIn
• aldewereldconsultancy.nl

---

Legacy Files

The original simple scripts are preserved for reference:

• mainshellyscript → Now at scripts/shelly_log.sh (enhanced)
• visualizeinpython → Now at src/visualize/plot_power.py (enhanced)
• externalconnectshelly → Now at examples/ directory