Skip to main content

​
Heat Pump State

Heat pump state parameters provide real-time operational data, sensor readings, and consumption metrics. These fields are read-only and automatically updated from the manufacturer’s API.
State data refresh frequency depends on the manufacturer’s API. Most values update every 5-15 minutes.

​
Operational Status

​
operational_mode
enum
Current operational mode of the heat pump.Options:
  • Hot Water - Heating domestic hot water only
  • Heating - Space heating active
  • Pool Heating - Pool heating mode (if applicable)
  • Standby - Device is on but not actively heating
  • Off - Device is powered off
Example: Hot Water
​
current_power_consumption_w
float
Current power consumption in Watts.Example: 2341.0
​
current_state_last_updated_at
datetime
Timestamp when the device state was last updated from the manufacturer’s API.Use this to determine data freshness.Example: 2023-03-22T13:54:34.000Z

​
Temperature Readings

​
outdoor_temperature
float
Current outdoor temperature in °C measured by the heat pump.Example: 9.3
​
indoor_actual_temperature
float
Current indoor temperature in °C (if indoor sensor is available).May be null if the device doesn’t have an indoor temperature sensor.Example: 21.2
​
dhw_actual_temperature
float
Current temperature of domestic hot water in °C.Example: 51.1

​
Energy Consumption

​
consumption_last_day_kwh
float
Energy consumption for the previous day in kWh.Example: 9.4
​
consumption_last_week_kwh
float
Energy consumption for the previous week in kWh.Example: 72.5
​
consumption_last_month_kwh
float
Energy consumption for the previous month in kWh.Example: 351.3
​
consumption_last_updated_at
datetime
Timestamp when consumption data was last calculated.Example: 2023-03-22T13:54:34.000Z

​
Usage Examples

​
Get Device State

curl -X GET \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/heat-pumps/{device_id}' \
  -H 'Authorization: Bearer {auth_token}' \
  -H 'Accept: application/json'

​
Display Current Status

def format_heat_pump_status(device):
    """
    Format heat pump state for dashboard display
    """
    return {
        'mode': device['operational_mode'],
        'power': f"{device['current_power_consumption_w']} W",
        'indoor_temp': f"{device['indoor_actual_temperature']}°C" if device['indoor_actual_temperature'] else "N/A",
        'outdoor_temp': f"{device['outdoor_temperature']}°C",
        'dhw_temp': f"{device['dhw_actual_temperature']}°C",
        'consumption_today': f"{device['consumption_last_day_kwh']} kWh",
        'last_updated': device['current_state_last_updated_at']
    }

# Example usage
heat_pump = get_heat_pump(org_id, user_id, device_id)
status = format_heat_pump_status(heat_pump)

print(f"Mode: {status['mode']}")
print(f"Current Power: {status['power']}")
print(f"Indoor: {status['indoor_temp']}, Outdoor: {status['outdoor_temp']}")
print(f"DHW: {status['dhw_temp']}")
print(f"Today's Consumption: {status['consumption_today']}")

def analyze_consumption_trend(device):
    """
    Analyze energy consumption patterns
    """
    daily = device['consumption_last_day_kwh']
    weekly = device['consumption_last_week_kwh']
    monthly = device['consumption_last_month_kwh']

    # Calculate averages
    avg_daily = weekly / 7
    avg_daily_from_month = monthly / 30

    return {
        'yesterday': daily,
        'avg_per_day_this_week': round(avg_daily, 2),
        'avg_per_day_this_month': round(avg_daily_from_month, 2),
        'total_this_week': weekly,
        'total_this_month': monthly,
        'trend': 'increasing' if daily > avg_daily else 'decreasing'
    }

# Example usage
trends = analyze_consumption_trend(heat_pump)
print(f"Yesterday: {trends['yesterday']} kWh")
print(f"Weekly average: {trends['avg_per_day_this_week']} kWh/day")
print(f"Monthly average: {trends['avg_per_day_this_month']} kWh/day")
print(f"Trend: {trends['trend']}")

​
Check Data Freshness

from datetime import datetime, timedelta

def check_data_freshness(device):
    """
    Verify that device data is recent
    """
    last_update = datetime.fromisoformat(device['current_state_last_updated_at'].replace('Z', '+00:00'))
    now = datetime.now(last_update.tzinfo)
    age_minutes = (now - last_update).total_seconds() / 60

    if age_minutes < 15:
        status = 'fresh'
    elif age_minutes < 60:
        status = 'slightly_stale'
    else:
        status = 'stale'

    return {
        'status': status,
        'age_minutes': round(age_minutes, 1),
        'last_updated': last_update.isoformat(),
        'message': f"Data is {round(age_minutes)} minutes old"
    }

# Example usage
freshness = check_data_freshness(heat_pump)
if freshness['status'] == 'stale':
    print(f"Warning: {freshness['message']}")

​
Dashboard Integration

​
Status Card Component

def create_status_card(device):
    """
    Generate data for a device status card
    """
    # Determine status color
    if not device.get('is_authenticated'):
        status_color = 'red'
        status_text = 'Disconnected'
    elif device.get('operational_mode') == 'Off':
        status_color = 'gray'
        status_text = 'Off'
    elif device.get('is_smart_optimization_active'):
        status_color = 'green'
        status_text = 'Optimizing'
    else:
        status_color = 'yellow'
        status_text = 'Connected'

    return {
        'title': f"{device['device_model']['manufacturer']} {device['device_model']['model']}",
        'status': {
            'text': status_text,
            'color': status_color
        },
        'metrics': [
            {
                'label': 'Mode',
                'value': device['operational_mode'],
                'icon': '🔄'
            },
            {
                'label': 'Indoor',
                'value': f"{device['indoor_actual_temperature']}°C",
                'icon': '🏠'
            },
            {
                'label': 'Outdoor',
                'value': f"{device['outdoor_temperature']}°C",
                'icon': '🌡️'
            },
            {
                'label': 'Power',
                'value': f"{device['current_power_consumption_w']}W",
                'icon': '⚡'
            },
            {
                'label': 'Today',
                'value': f"{device['consumption_last_day_kwh']} kWh",
                'icon': '📊'
            }
        ],
        'last_updated': device['current_state_last_updated_at']
    }

​
Understanding Operational Modes

The heat pump is actively heating domestic hot water to reach the target temperature.Typical Duration: 30-90 minutes per cyclePower Consumption: Medium to High

​
Best Practices

  • Poll device state every 5-15 minutes for dashboard updates
  • Check current_state_last_updated_at to avoid unnecessary API calls
  • Implement caching to reduce API load
  • Show last update timestamp to users for transparency
  • Compare daily consumption across similar timeframes
  • Account for outdoor temperature when analyzing trends
  • Use weekly/monthly averages for meaningful comparisons
  • Alert users to unusual consumption spikes
  • Show both indoor and outdoor temperatures for context
  • Highlight when indoor temperature is outside comfort range
  • DHW temperature should typically be 45-55°C
  • Consider outdoor temperature for heating efficiency expectations
  • Handle null values gracefully (e.g., missing indoor sensor)
  • Display user-friendly messages for stale data
  • Provide troubleshooting steps when data stops updating
  • Check is_authenticated before displaying state data

Heat Pump Attributes

Writable parameters and configuration

Dashboard Integration

Building end-user dashboards

Energy Contracts

Energy pricing parameters

Buildings

Building parameters reference