homebridge-ping-powerwalls v1.0.0

Tesla Powerwall 3 Monitoring Solution

A comprehensive monitoring solution for Tesla Powerwall 3 units that detects network connectivity issues and sends alerts.

Problem Statement

Silent Network Failures of Tesla Powerwall 3

Tesla Powerwall 3 units can silently drop off the network without any notification in the official Tesla app. This critical issue means your Powerwall system can be completely offline for days without your knowledge, leading to several serious consequences:

• Lost Solar Production: When Powerwalls disconnect from the network, solar panel systems that rely on the Powerwall's built-in inverter stop producing energy completely, resulting in unexpected electricity costs and lost renewable energy generation.

• Failed Backup Readiness: During an outage, you might discover your backup power system isn't operational when you need it most.

• Delayed Troubleshooting: Without timely notifications, minor issues can escalate into more significant problems that take longer to resolve.

• Monitoring Gap: The Tesla app provides no alerts or notifications when Powerwalls go offline, leaving a critical gap in system monitoring.

This monitoring solution addresses these problems by providing:

1. Complete Independence: Operates entirely outside Tesla's ecosystem using standard network protocols, with no reliance on Tesla's servers, APIs, or software
2. Reliable Network Monitoring: Performs connectivity checks as frequently as every 5 seconds to quickly detect outages
3. Immediate Notifications: Delivers email alerts promptly when a unit has been offline for your specified duration, plus seamless integration with Apple HomeKit for additional notification options through the iOS/macOS ecosystem
4. HomeKit Integration: Appears as sensors in the Apple Home app, enabling HomeKit automations, Siri control, and notification options through the entire Apple ecosystem
5. Recovery Confirmation: Verifies stability when units come back online before sending recovery notifications
6. Historical Analysis: Tracks comprehensive connectivity data with powerful reporting tools to identify patterns and recurring issues

Whether you're relying on your Powerwall system for daily solar integration or emergency backup, knowing immediately when connectivity issues arise is essential for maintaining optimal system performance.

Prerequisites

Hardware Requirements

• Raspberry Pi (Zero W, 3, or 4) or any always-on computer capable of running Node.js
• Reliable network connection to the same local network as your Powerwall units
• Internet connection for sending email notifications

Required Software

• Node.js 12.0.0 or higher
• Homebridge 1.1.0 or higher

Homebridge Installation

Before installing this plugin, you'll need a working Homebridge installation.

1. Install Homebridge:

   • https://github.com/homebridge/homebridge#installation

Solution Overview

This monitoring solution provides reliable network connectivity monitoring for Tesla Powerwall 3 units with these key features:

1. Regular Ping Monitoring: Checks Powerwall connectivity as frequently as every 5 seconds
2. Intelligent Alerting: Sends email notifications when a unit has been offline for a configurable period
3. Recovery Detection: Recognizes when units come back online and confirms stability before sending recovery alerts
4. Historical Logging: Maintains detailed logs of connectivity events with automatic pruning
5. HomeKit Integration: Shows Powerwall status in the Home app
6. Enhanced Web Dashboard: Provides a comprehensive web interface with advanced reporting and analytics
7. Low Resource Usage: Optimized for Raspberry Pi Zero
8. Rich HTML Email Alerts: Visual status information with color coding

Components

The solution is a single package containing:

1. Homebridge Plugin: Modified version of homebridge-ping-hosts optimized for Powerwall monitoring
2. Alert Monitor: Integrated monitoring component that sends email notifications
3. Status Dashboard: Enhanced dashboard with reporting capabilities and visualizations
4. Command-Line Tools: CLI utilities for management and testing

Installation Instructions

1. Installation from NPM

The plugin is now available on the NPM registry for simplified installation.

Install via Homebridge UI

The easiest way to install the plugin is through the Homebridge UI:

1. Open your Homebridge UI in a web browser
2. Navigate to the "Plugins" tab
3. Search for "homebridge-ping-powerwalls"
4. Click "Install" next to the plugin

Install via Command Line

Alternatively, you can install the plugin using npm:

# For Homebridge on Raspberry Pi (with hb-service)
sudo hb-service add homebridge-ping-powerwalls

# OR if using regular Homebridge with npm
npm install -g homebridge-ping-powerwalls

Once installed, proceed to the "Configure Homebridge" section below to set up the plugin.

1. Install the Plugin from GitHub

If you have issues finding or installing this plugin from npm, you can install this plugin directly from a GitHub repository using these steps:

# For Homebridge on Raspberry Pi (with hb-service)
sudo hb-service add github:yourusername/homebridge-ping-powerwalls

# OR if using regular Homebridge with npm
npm install -g github:yourusername/homebridge-ping-powerwalls

Replace yourusername with the actual GitHub username where you've hosted the repository.

Example:

# For Homebridge on Raspberry Pi (with hb-service)
sudo hb-service add github:bullishpip/homebridge-ping-powerwalls

# OR if using regular Homebridge with npm
npm install -g github:bullishpip/homebridge-ping-powerwalls

2. Configure Homebridge

Edit your Homebridge configuration file to add the Powerwall platform. You can do this through the Homebridge UI or by editing the config.json file directly:

"platforms": [
  {
    "platform": "PowerwallPing",
    "powerwalls": [
      {
        "name": "Powerwall 1",
        "ipv4_address": "192.168.1.100", 
        "interval": 5,          // Check every 5 seconds
        "timeout": 5,           // 5 seconds timeout 
        "retries": 2,           // Retry twice before considering offline
        "alert_after": 3,       // Alert after 3 minutes of being offline
        "alert_recovery_after": 1, // Consider recovered after 1 minute of stability
        "startup_as_failed": false,
        "closed_on_success": true,
        "type": "ContactSensor"
      },
      {
        "name": "Powerwall 2", 
        "ipv4_address": "192.168.1.101",
        "interval": 5,
        "timeout": 5,
        "retries": 2,
        "alert_after": 3,
        "alert_recovery_after": 1,
        "startup_as_failed": false,
        "closed_on_success": true,
        "type": "ContactSensor"
      }
    ],
    "history_size": 1000,
    "enable_monitor": true      // Enable integrated monitor
  }
]

3. Configure Email Notifications

IMPORTANT: Manual Configuration Required

The plugin should automatically create a configuration file, but due to permission issues, you may need to create it manually. Here's how:

1. Access the Homebridge shell:

sudo hb-service shell

2. Create the configuration file:

nano /var/lib/homebridge/powerwall_alert_config.json

3. Paste the following JSON content and edit the email settings:

{
  "email": {
    "enabled": true,
    "fromAddress": "your-email@gmail.com",
    "toAddress": "your-email@gmail.com",
    "host": "smtp.gmail.com",
    "port": 465,
    "secure": true,
    "auth": {
      "user": "your-email@gmail.com",
      "pass": "your-app-password"
    }
  },
  "notifications": {
    "offline": {
      "subject": "⚠️ ALERT: Tesla Powerwall Offline",
      "template": "<html><body style='font-family: Arial, sans-serif;'><h2 style='color: #d9534f;'>Powerwall Alert: Device Offline</h2><p>Powerwall <strong>{name}</strong> at <code>{address}</code> has gone offline.</p><div style='background-color: #f2dede; border: 1px solid #ebccd1; padding: 15px; border-radius: 4px; margin: 20px 0;'><p style='color: #a94442; margin: 0;'><strong>Time of alert:</strong> {time}<br><strong>Offline since:</strong> {offlineSince}</p></div><p>Please check your Powerwall system as soon as possible.</p></body></html>",
      "html": true
    },
    "recovery": {
      "subject": "✅ RESOLVED: Tesla Powerwall Back Online",
      "template": "<html><body style='font-family: Arial, sans-serif;'><h2 style='color: #5cb85c;'>Powerwall Recovered: Device Online</h2><p>Powerwall <strong>{name}</strong> at <code>{address}</code> is back online and stable.</p><div style='background-color: #dff0d8; border: 1px solid #d6e9c6; padding: 15px; border-radius: 4px; margin: 20px 0;'><p style='color: #3c763d; margin: 0;'><strong>Time of recovery:</strong> {time}<br><strong>Total downtime:</strong> {downtime} minutes</p></div><p>The system appears to be functioning normally again.</p></body></html>",
      "html": true
    }
  },
  "logPath": "/var/lib/homebridge/powerwall_logs",
  "alertLogFile": "powerwall_alerts.json",
  "maxAlertHistory": 100,
  "logPruning": {
    "enabled": true,
    "maxAgeDays": 30,         // Keep logs for 30 days
    "maxSizeMB": 50,          // Limit total log size to 50MB
    "pruneInterval": 86400,   // Check daily (in seconds)
    "keepMinEntries": 100     // Always keep at least 100 entries per log file
  }
}

4. Save the file (Ctrl+O, then Enter, then Ctrl+X)

5. Restart Homebridge:

sudo hb-service restart

Note on Gmail App Passwords: 1. Visit your Google Account > Security 2. Enable 2-Step Verification if not already enabled 3. Go to App passwords 4. Select "Mail" and "Other (Custom name)" 5. Name it "Powerwall Monitor" and copy the generated password

4. Test Email Notifications

To verify your email configuration is working correctly, use the Homebridge shell:

# Enter Homebridge shell
sudo hb-service shell

# Send a test email
node /var/lib/homebridge/node_modules/homebridge-ping-powerwalls/bin/monitor.js --test

If successful, you should receive a test email alert.

5. Set Up Web Dashboard

Start the dashboard manually from the Homebridge shell:

# Access the Homebridge shell
sudo hb-service shell

# Start the web dashboard on port 8080
node /var/lib/homebridge/node_modules/homebridge-ping-powerwalls/bin/dashboard.js 8080

Or set it up as a service for automatic startup:

sudo bash -c 'cat > /etc/systemd/system/powerwall-dashboard.service << EOF
[Unit]
Description=Tesla Powerwall Status Dashboard
After=homebridge.service
Requires=homebridge.service

[Service]
Type=simple
User=homebridge
ExecStart=/usr/bin/node /var/lib/homebridge/node_modules/homebridge-ping-powerwalls/bin/dashboard.js 8080 /var/lib/homebridge/powerwall_logs
Restart=always
RestartSec=10
StandardOutput=append:/var/lib/homebridge/powerwall_logs/dashboard.log
StandardError=append:/var/lib/homebridge/powerwall_logs/dashboard.log

[Install]
WantedBy=multi-user.target
EOF'

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable powerwall-dashboard
sudo systemctl start powerwall-dashboard

Then access the dashboard at http://your-raspberry-pi-ip:8080

Enhanced Dashboard Features

The refactored dashboard provides a comprehensive monitoring solution with the following enhancements:

1. Modern User Interface

• Responsive Design: Works on mobile, tablet, and desktop
• Tab-Based Navigation: Easy access to different dashboard sections
• Light & Dark Themes: Adjusts to your preference or system settings
• Configurable Settings: Customize refresh rates and default views

2. Advanced Reporting Capabilities

The dashboard now includes four specialized report types:

• Uptime Analysis:

  • Overall uptime percentage with visual meter
  • Daily uptime percentage line chart
  • Outage time-of-day distribution
  • Outage day-of-week distribution
  • Outage duration distribution

• Outage Patterns:

  • Outage frequency statistics
  • Duration statistics (total, average, max, min)
  • Time-of-day patterns visualization
  • Hourly distribution chart
  • Day-of-week bar chart
  • Detailed outage table with timestamps

• Powerwall Comparison:

  • Side-by-side comparison table
  • Uptime percentage comparison chart
  • Outage frequency comparison chart
  • Average outage duration comparison chart

• Alert Analysis:

  • Alert summary statistics
  • Alerts by Powerwall breakdown
  • Daily alerts chart
  • Hourly distribution chart
  • Day-of-week pattern chart

3. Customizable Time Ranges

Generate reports for different time periods:

• Last 7 days
• Last 14 days
• Last 30 days
• Last 60 days
• Last 90 days

4. Real-Time Data Updates

• Manual refresh button
• Configurable auto-refresh intervals
• Server-side data processing for efficiency

5. Data Persistence

• Persistent user settings saved in browser local storage
• Automatic session restoration between visits

Command-Line Utilities

The package includes command-line utilities, but they must be accessed through the Homebridge shell:

1. Monitor Tool (for email alerts and testing):

   sudo hb-service shell
   node /var/lib/homebridge/node_modules/homebridge-ping-powerwalls/bin/monitor.js [options]

   Options:

   • --test: Send a test email alert
   • --prune: Manually run log pruning

2. Dashboard Tool (web interface):

   sudo hb-service shell
   node /var/lib/homebridge/node_modules/homebridge-ping-powerwalls/bin/dashboard.js [port] [logDir]

Troubleshooting Guide

Common Issues and Solutions

1. Configuration file not being created automatically

   • Create it manually as described in Step 3 above
   • Make sure to use the correct path: /var/lib/homebridge/powerwall_alert_config.json

2. Command not found errors when trying to use CLI tools

   • Always use the Homebridge shell: sudo hb-service shell
   • Run scripts directly with Node.js: node /var/lib/homebridge/node_modules/homebridge-ping-powerwalls/bin/monitor.js

3. JSON parsing errors

   • Ensure your configuration file is valid JSON with no syntax errors
   • Use a JSON validator if needed: https://jsonlint.com/

4. Logs showing but no email alerts

   • Check your email configuration in the powerwall_alert_config.json file
   • Run a test email from the Homebridge shell to verify settings

5. Dashboard not working

   • Make sure to start it from the Homebridge shell
   • Check if the port is already in use
   • Verify the log directory exists and is accessible

6. Charts not displaying in dashboard

   • Ensure you have an active internet connection (Chart.js is loaded from CDN)
   • Check your browser console for any JavaScript errors
   • Try clearing your browser cache

7. Dashboard showing "No data available"

   • Verify that your Powerwalls are properly configured
   • Check that the log files exist in the log directory
   • Ensure the dashboard has read access to the log files

Technical Architecture

The monitoring dashboard has been refactored with a clean separation of concerns:

1. Backend Components:

   • API server for data retrieval and processing
   • Statistical analysis module for metrics calculations
   • Static file server for frontend assets

2. Frontend Components:

   • HTML structure (index.html)
   • CSS styling (styles.css)
   • Core dashboard functionality (dashboard.js)
   • Enhanced reporting features (reporting.js)
   • Chart visualizations (charts.js)

This modular architecture makes the codebase more maintainable and easier to extend.

Summary

By following this updated guide, you'll have a robust monitoring solution that will keep you informed about the network connectivity of your Tesla Powerwall 3 units, allowing you to quickly respond to any issues. The enhanced dashboard provides advanced reporting and visualization capabilities for better insights into your Powerwall performance.