Control4 HVAC BMS Data Exporter

Export historical data from Control4 HVAC Generic BMS Monitor systems via WebSocket API.

Overview

This tool allows you to extract years of historical temperature, humidity, and HVAC data from Control4 systems running the hvac_generic_bms_monitor_dc driver. Perfect for migrating to a new platform or analyzing your HVAC system's performance.

Features

• ✅ Export all historical data via WebSocket API
• ✅ Automatic device and variable name mapping
• ✅ CSV output format for easy import
• ✅ Comprehensive data analysis tools
• ✅ Support for 132+ sensor types
• ✅ No proprietary format decoding required

Quick Start

Prerequisites

• Python 3.7+
• Access to your Control4 controller's IP address
• Control4 system with HVAC BMS Monitor driver

Installation

# Clone the repository
git clone https://github.com/yourusername/control4-hvac-data-exporter.git
cd control4-hvac-data-exporter

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Basic Usage

1. Update the controller IP address in scripts/export_data.py:

   WS_URL = "ws://YOUR_CONTROLLER_IP:13005/"

2. Create your device list (see Device Discovery)

3. Run the export:

   python scripts/export_data.py

4. Analyze the data:

   python scripts/analyze_data.py
   python scripts/check_export.py

What Gets Exported

• Temperature sensors (°F and °C)
• Humidity sensors (%)
• HVAC states and modes
• Setpoints (heating/cooling)
• Outdoor weather data
• System memory and usage stats

Example Export Stats

• Data Points: 786,027 readings
• Sensors: 132 active sensors
• Date Range: ~414 days of history
• Format: CSV with timestamps, device names, and values

System Architecture

WebSocket API

The Control4 HVAC BMS Monitor exposes a WebSocket API on port 13005:

ws://CONTROLLER_IP:13005/

Request Format

{
  "method": "GET_DATA",
  "from": 1234567890000,
  "to": 1234567890000,
  "utcOffset": -21600,
  "windowSize": "NONE",
  "scale": "MS",
  "vars": "device_id.variable_id,device_id.variable_id,...",
  "maximumElements": 100000,
  "uuid": "unique-request-id"
}

Response Format

{
  "type": "DEVICE_DATA",
  "uuid": "unique-request-id",
  "values": {
    "device_id.variable_id": {
      "values": [[timestamp, value], [timestamp, value], ...]
    }
  }
}

Scripts

Core Scripts

• export_data.py - Main export script to download all historical data
• check_export.py - Verify exported data and show statistics
• analyze_data.py - Comprehensive data analysis (frequency, gaps, ranges, correlations)
• analyze_devices.py - Per-device/sensor statistics
• missing_sensors.py - Identify sensors without historical data

Utility Scripts

• test_window_sizes.py - Test different windowSize parameters
• add_names.py - Add human-readable names to exported data

Device Discovery

To create your device_variable_list.json:

1. Open Chrome DevTools (F12) on the Control4 web interface
2. Go to Network tab → WS (WebSocket)
3. Click on the WebSocket connection
4. Look for USER_SCREENS or WATCHED_DEVICES messages
5. Extract device IDs and variable IDs
6. Create JSON mapping (see examples/device_variable_list_sample.json)

Configuration

Key Parameters

• windowSize: Data aggregation level

  • "NONE" - All raw data points (recommended)
  • "HOUR_1" - Hourly aggregation
  • "DAY_1" - Daily aggregation
  • "WEEK_1" - Weekly aggregation
  • "MONTH_1" - Monthly aggregation

• maximumElements: Max data points per sensor (default: 100000)

• utcOffset: Timezone offset in seconds (e.g., -21600 for Central Time)

Data Analysis Features

1. Frequency Analysis

Understand sampling rates for each sensor (seconds, minutes, hours, or days between readings).

2. Gap Detection

Find periods with missing data (gaps > 24 hours).

3. Value Range Analysis

Min/max/average values for all numeric sensors.

4. Temperature Correlation

Compare temperature readings across different rooms.

5. Time-of-Day Patterns

Identify continuous vs event-driven sensors.

6. Data Completeness

Calculate percentage of expected data points present.

Output Format

CSV file with columns:

• sensor_id - Device and variable ID (e.g., "788.1130")
• sensor_name - Human-readable name (e.g., "Theater - TEMPERATURE_F")
• timestamp - Unix timestamp (seconds)
• datetime - ISO 8601 formatted datetime
• value - Sensor reading (numeric or string)

Limitations

• System stores approximately 13-14 months of historical data
• Some sensors (SCALE, HVAC_MODE) may not have historical data
• Configuration values and setpoints only record when changed
• Maximum data points per request: 100,000

Troubleshooting

No Data Received

1. Verify controller IP address and port 13005
2. Check that WebSocket connection is established
3. Ensure device IDs and variable IDs are correct
4. Try requesting a single sensor first

Missing Sensors

Some sensors won't have historical data:

• SCALE - Configuration value (rarely changes)
• HVAC_MODE - Configuration value (rarely changes)
• Setpoints - Only logged when manually adjusted
• New devices - Recently added sensors

Connection Issues

• Ensure you're on the same network as the Control4 controller
• Check firewall settings for port 13005
• Verify the HVAC BMS Monitor driver is installed and running

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• Control4 for the HVAC BMS Monitor driver
• Community members who helped reverse-engineer the WebSocket API

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Disclaimer

This tool is not affiliated with or endorsed by Control4. Use at your own risk. Always backup your data before making system changes.