⚠️ AI-Generated Code Warning: This project was "vibe coded" using generative AI and should be thoroughly reviewed before use. It comes with no warranty or guarantee of functionality, security, or reliability.

Pentameter is a Prometheus exporter for Pentair IntelliCenter pool controllers that connects via WebSocket and exposes pool equipment data as Prometheus metrics with pre-configured Grafana dashboards for visualization.

• Temperature Monitoring: Pool, spa, and outdoor air sensors
• Pump Monitoring: Variable speed RPM and flow rates
• Equipment Status: Circuit and feature on/off states
• Connection Health: Automatic failure detection and recovery
• Auto-Discovery: Finds IntelliCenter automatically via mDNS (multicast DNS)

• Prometheus Metrics: Standard format compatible with any monitoring tool
• Pre-configured Dashboards: Grafana dashboards with automatic provisioning
• Kiosk Mode: Clean displays for dedicated monitoring screens
• Historical Trends: Long-term data visualization and analysis

• Intelligent Filtering: Focus on meaningful equipment vs virtual controls
• User-Controlled Feature Visibility: Respects IntelliCenter's "Show as Feature" settings
• Graceful Degradation: Handle missing sensors without errors
• Browser Compatibility: Standard metrics endpoint works everywhere

• WebSocket connection to IntelliCenter controllers
• Automatic IntelliCenter discovery via mDNS (finds pentair.local on network)
• Listen mode for real-time equipment change monitoring and debugging
• Robust connection management with exponential backoff retry logic
• Health checks with automatic reconnection on failures
• Configurable via command line flags or environment variables
• Health check endpoint

Pentameter connects to IntelliCenter controllers via WebSocket and transforms pool data into standard Prometheus metrics for monitoring and alerting.

1. Go Service - Core monitoring service

   • WebSocket client for IntelliCenter communication
   • Prometheus metrics endpoint (/metrics)
   • Health checks and connection management

2. IntelliCenter Interface

   • WebSocket connection (default port 6680)
   • JSON message protocol using GetParamList API
   • Exponential backoff retry with health checks
   • Request/response polling - API does not support push notifications (verified 2025-11-08)
   • Persistent connection with configurable poll intervals (2s for listen mode, 60s default)

3. Metrics Export

   • HTTP server (default port 8080)
   • Standard Prometheus format
   • Compatible with any monitoring tool

4. Docker Deployment

   • Multi-stage builds with scratch base images (~12MB)
   • Docker Compose orchestration
   • Prometheus and Grafana included

• Language: Go with standard library HTTP server
• WebSocket: github.com/gorilla/websocket
• Metrics: github.com/prometheus/client_golang
• Build: Makefile with Docker integration
• Deployment: Docker Compose with restart policies

Pentameter offers multiple installation methods to suit different deployment preferences:

Recommended for macOS users who want just the metrics exporter:

# One-line install (automatically adds tap)
brew install astrostl/pentameter/pentameter

# Start the exporter (auto-discovers IntelliCenter)
pentameter

# Or manually specify IP address if needed
export PENTAMETER_IC_IP=192.168.1.100
pentameter

Alternative two-step install:

# Add the tap (one time setup)
brew tap astrostl/pentameter https://github.com/astrostl/pentameter
brew install pentameter

✅ Instant installation - No build time, no dependencies
✅ Pre-built binaries - Intel and Apple Silicon supported
✅ Automatic updates - brew upgrade pentameter

Metrics are available at http://localhost:8080/metrics

For complete monitoring with Grafana dashboards, use the Docker Compose option below.

Recommended for Go developers who want to build from source:

# Install latest version
go install github.com/astrostl/pentameter@latest

# Or install specific version
go install github.com/astrostl/pentameter@v0.2.2

# Start the exporter (auto-discovers IntelliCenter)
pentameter

# Or manually specify IP address if needed
export PENTAMETER_IC_IP=192.168.1.100
pentameter

✅ Latest source - Always up-to-date with repository
✅ Go toolchain integration - Uses your existing Go installation
✅ All platforms - Works wherever Go runs

Note: Version information (pentameter --version) will show as "dev" since go install doesn't include build-time version injection.

Metrics are available at http://localhost:8080/metrics

Recommended for full monitoring setup with Grafana dashboards:

# Clone the repository (includes all config files)
git clone https://github.com/astrostl/pentameter.git
cd pentameter

# Start the complete monitoring stack (auto-discovers IntelliCenter)
docker compose up -d

# Or manually configure IP if auto-discovery doesn't work
cp .env.example .env
# Edit .env and set your PENTAMETER_IC_IP
docker compose up -d

✅ Complete monitoring - Pentameter + Prometheus + Grafana
✅ Pre-configured dashboards - Ready-to-use Grafana setup
✅ No build time - Uses published DockerHub images
✅ All platforms - Works on macOS, Linux, Windows

Access Points:

• Grafana Dashboard: http://localhost:3000/d/pentameter/
• Metrics: http://localhost:8080/metrics
• Prometheus: http://localhost:9090

• Metrics: http://HOSTNAME:8080/metrics - Prometheus metrics
• Health: http://HOSTNAME:8080/health - Health check
• Prometheus: http://HOSTNAME:9090 - Prometheus web interface
• Grafana: http://HOSTNAME:3000/d/pentameter/ - Grafana dashboards (no login required)
• Kiosk Mode: http://HOSTNAME:3000/d/pentameter/?kiosk - Clean dashboard display

Pentameter respects IntelliCenter's "Show as Feature" settings to avoid duplicate controls and maintain clean dashboards.

IntelliCenter allows users to control whether features appear in the interface through a "Show as Feature" checkbox in the Feature Circuits configuration. Pentameter automatically detects and respects this setting.

Common Use Case: Pool heating equipment often appears as both:

• Feature: User control (e.g., "Spa Heat" - enable/disable heating)
• Thermal Equipment: Actual equipment status (e.g., "Spa Heater" - heating/idle/cooling)

This creates duplication in monitoring dashboards where both the user control and equipment status are shown.

Users can eliminate this duplication through their IntelliCenter interface:

1. Access IntelliCenter → Settings → Feature Circuits
2. Select the feature (e.g., "Spa Heat")
3. Uncheck "Show as Feature" to hide the user control
4. Keep thermal equipment monitoring for actual operational status

Pentameter uses IntelliCenter's SHOMNU parameter to detect the "Show as Feature" setting:

• Show as Feature: YES → Feature appears in feature_status metrics
• Show as Feature: NO → Feature is automatically hidden from metrics

• User-Controlled: No hardcoded logic - users decide what to show
• Universal: Works with any equipment configuration and naming
• Clean Dashboards: Eliminates duplicate controls when desired
• Flexible: Users can show both if they want different information

Scenario 1: Show Both Controls

• feature_status{name="Spa Heat"} → User enable/disable control
• thermal_status{name="Spa Heater"} → Equipment operational status
• Use Case: Monitor both user intent and equipment response

Scenario 2: Show Equipment Only

• User disables "Show as Feature" for "Spa Heat"
• Only thermal_status{name="Spa Heater"} appears
• Use Case: Focus on equipment operation, control via IntelliCenter

This approach ensures Pentameter works universally across different pool configurations while giving users full control over their monitoring interface.

All configuration options can be set via command line flags or environment variables:

The functions (--version, --discover) and modes (--metrics, --listen, --homebridge) are all mutually exclusive — pick at most one. When no function or mode is given, pentameter runs in metrics mode. The /metrics HTTP endpoint is served in all modes.

Pentameter can automatically discover your IntelliCenter on the local network using mDNS (multicast DNS). The IntelliCenter broadcasts itself as pentair.local on the network.

How it works:

• When --ic-ip is not provided, pentameter automatically searches for pentair.local via mDNS
• Discovery timeout is 60 seconds with progress indicators every 2 seconds
• Works on most home networks without additional configuration
• Docker support: Auto-discovery works in Docker using host networking (enabled by default)
• Automatic re-discovery: If the IntelliCenter's IP changes (DHCP renewal, router reboot), pentameter automatically re-discovers it after 3 failed connection attempts

Test discovery:

# Test auto-discovery and show IP address
pentameter --discover

# Example output:
# IntelliCenter discovered at: 192.168.1.100

Manual IP specification:

# Bypass auto-discovery and use specific IP
pentameter --ic-ip 192.168.1.100

# Or via environment variable
export PENTAMETER_IC_IP=192.168.1.100
pentameter

Docker auto-discovery:

# Docker Compose with auto-discovery (default behavior)
docker compose up -d

# Docker run with auto-discovery
docker run -d --name pentameter --network host astrostl/pentameter:latest

Troubleshooting:

• If auto-discovery fails, pentameter provides clear guidance on using the --ic-ip flag
• Check that your IntelliCenter is on the same network
• Some networks may block mDNS multicast traffic (port 5353/UDP)
• Firewalls may need to allow multicast traffic to 224.0.0.251:5353
• Docker: Host networking is required for mDNS (enabled by default in docker-compose.yml)
• Use --ic-ip flag to manually specify IP address if auto-discovery doesn't work

Listen mode provides real-time event logging for pool equipment changes using a hybrid push + poll architecture. Perfect for debugging, discovering equipment, and monitoring activity.

• Hybrid Push + Poll: Real-time push notifications for instant updates, plus periodic polling (default 60s) to catch equipment that doesn't push (like pump RPM changes)
• Source Identification: Events prefixed with PUSH: or POLL: to distinguish real-time vs polled updates
• Initial State Discovery: Shows all equipment and current state on startup
• Unknown Equipment Detection: Automatically discovers equipment types not specifically implemented (valves, sensors, remotes, etc.)
• Clean Output: Reports POLL: [no changes] when poll cycles find no updates

# Basic listen mode (60-second poll interval)
pentameter --ic-ip 192.168.1.100 --listen

# Custom polling interval (10 seconds)
pentameter --ic-ip 192.168.1.100 --listen --interval 10

# Via environment variable
export PENTAMETER_IC_IP=192.168.1.100
export PENTAMETER_LISTEN=true
pentameter

2025/11/28 18:51:15 Fetching initial equipment state...
2025/11/28 18:51:15 POLL: Pool temperature detected: 22.0°F
2025/11/28 18:51:15 POLL: Spa temperature detected: 95.0°F
2025/11/28 18:51:15 POLL: VS detected: 3000 RPM
2025/11/28 18:51:16 POLL: Pool detected: ON
2025/11/28 18:51:16 POLL: Spa Heater detected: heating
2025/11/28 18:51:35 Listening for real-time changes (Ctrl+C to stop)...
2025/11/28 18:52:04 PUSH: Spa temp=97°F setpoint=98°F htmode=1 status=ON
2025/11/28 18:53:35 POLL: Spa temperature changed: 95.0°F → 96.0°F
2025/11/28 18:53:35 POLL: VS changed: 3000 → 2500 RPM
2025/11/28 18:54:35 POLL: [no changes]

• Debugging: Watch equipment respond to commands in real-time via PUSH: events
• Discovery: Find all equipment in your IntelliCenter, including unknown types
• Monitoring: Track circuit activation, temperature changes, and pump speed adjustments
• Testing: Verify equipment changes are being reported correctly
• Pump Tracking: Monitor pump RPM changes (not pushed by IntelliCenter, requires polling)

Listen mode monitors all equipment types:

• Water & Air Temperatures: Bodies and sensors
• Circuits: Lights, pumps, valves, cleaners
• Features: Spa jets, fountains, automation features
• Thermal Equipment: Heaters and heat pumps with operational states
• Pumps: Variable speed RPM changes (via polling)
• Unknown Equipment: Any equipment type not specifically implemented

Homebridge mode (--homebridge) runs pentameter as a sidecar for the companion homebridge-pentair-intellicenter-ai Homebridge plugin, exposing your IntelliCenter equipment to Apple HomeKit. The sidecar speaks a small newline-delimited JSON protocol to the Node plugin over stdio, so it is normally spawned by Homebridge rather than run by hand. The Prometheus /metrics endpoint continues to be served in this mode, so a single process can drive both HomeKit and Grafana.

• Thermostats - One per body (pool/spa)