Homebridge-ping-powerwalls NPM

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:

Complete Independence: Operates entirely outside Tesla's ecosystem using standard network protocols, with no reliance on Tesla's servers, APIs, or software
Reliable Network Monitoring: Performs connectivity checks as frequently as every 5 seconds to quickly detect outages
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
HomeKit Integration: Appears as sensors in the Apple Home app, enabling HomeKit automations, Siri control, and notification options through the entire Apple ecosystem
Recovery Confirmation: Verifies stability when units come back online before sending recovery notifications
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.

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:

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

Components

The solution is a single package containing:

Homebridge Plugin: Modified version of homebridge-ping-hosts optimized for Powerwall monitoring
Alert Monitor: Integrated monitoring component that sends email notifications
Status Dashboard: Enhanced dashboard with reporting capabilities and visualizations
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:

Open your Homebridge UI in a web browser
Navigate to the "Plugins" tab
Search for "homebridge-ping-powerwalls"
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:

Access the Homebridge shell:

sudo hb-service shell

Create the configuration file:

nano /var/lib/homebridge/powerwall_alert_config.json

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
  }
}

Save the file (Ctrl+O, then Enter, then Ctrl+X)
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:

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

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

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
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
JSON parsing errors
- Ensure your configuration file is valid JSON with no syntax errors
- Use a JSON validator if needed: https://jsonlint.com/
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
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
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
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:

Backend Components:
- API server for data retrieval and processing
- Statistical analysis module for metrics calculations
- Static file server for frontend assets
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.

homebridge-plugin tesla powerwall monitoring ping alerts

ping @network-utils/arp-lookup nodemailer q underscore

4 months ago

4 months ago

4 months ago

4 months ago

4 months ago

4 months ago

4 months ago

4 months ago