# Zigbee2MQTT Climate Mappings
# Handles thermostats and HVAC devices
#
# Thermostat device structure (from spec):
# - temperature channel (required): current temperature reading
# - thermostat channel (required): locked state
# - heater channel (optional): heating setpoint and status
# - cooler channel (optional): cooling setpoint and status
# - humidity channel (optional): humidity reading

version: "1.0"

mappings:
  # Zigbee thermostat/climate device
  - name: climate
    description: "Zigbee thermostat or HVAC controller"
    priority: 100
    match:
      expose_type: climate
    device_category: THERMOSTAT
    channels:
      # Temperature channel - current/local temperature (required)
      - identifier: temperature
        name: Temperature
        category: TEMPERATURE
        features:
          - z2m_feature: local_temperature
            direction: read_only
            panel:
              identifier: TEMPERATURE
              name: Current Temperature
              data_type: FLOAT
              unit: "°C"
              settable: false

      # Thermostat channel - locked state and internal climate properties
      - identifier: thermostat
        name: Thermostat
        category: THERMOSTAT
        features:
          # Preset mode (away, boost, comfort, eco, etc.)
          # Internal property: Z2M climate devices expose preset modes
          # Stored as MODE property on thermostat channel
          - z2m_feature: preset
            panel:
              identifier: MODE
              name: Preset Mode
              data_type: ENUM
              # format derived from device's actual preset values

          # Fan mode (auto, low, medium, high, etc.)
          # Internal property: Z2M climate devices expose fan control modes
          # Stored as SPEED property on thermostat channel
          - z2m_feature: fan_mode
            panel:
              identifier: SPEED
              name: Fan Mode
              data_type: ENUM
              # format derived from device's actual fan mode values

      # Heater channel - heating setpoint and valve control (optional)
      - identifier: heater
        name: Heater
        category: HEATER
        features:
          # System mode -> heater ON state (true when mode includes heating)
          - z2m_feature: system_mode
            panel:
              identifier: ON
              name: Heater On
              data_type: BOOL
            transform:
              type: map
              read:
                "off": false
                "heat": true
                "cool": false
                "auto": true
                "heat_cool": true
                "fan_only": false
              write:
                true: "heat"
                false: "off"

          # Running state -> heater status (true when heating)
          - z2m_feature: running_state
            direction: read_only
            panel:
              identifier: STATUS
              name: Heating Status
              data_type: BOOL
              settable: false
            transform:
              type: map
              read:
                "idle": false
                "heat": true
                "cool": false
                "fan_only": false

          # Heating setpoint temperature
          - z2m_feature: occupied_heating_setpoint
            panel:
              identifier: TEMPERATURE
              name: Heating Setpoint
              data_type: FLOAT
              unit: "°C"

          # Alternative heating setpoint name
          - z2m_feature: current_heating_setpoint
            panel:
              identifier: TEMPERATURE
              name: Heating Setpoint
              data_type: FLOAT
              unit: "°C"

          # PI heating demand (percentage) -> valve position
          - z2m_feature: pi_heating_demand
            direction: read_only
            panel:
              identifier: POSITION
              name: Heating Demand
              data_type: UCHAR
              format: [0, 100]
              unit: "%"
              settable: false

          # Valve position (percentage)
          - z2m_feature: valve_position
            direction: read_only
            panel:
              identifier: POSITION
              name: Valve Position
              data_type: UCHAR
              format: [0, 100]
              unit: "%"
              settable: false

      # Cooler channel - cooling setpoint (optional)
      - identifier: cooler
        name: Cooler
        category: COOLER
        features:
          # System mode -> cooler ON state (true when mode includes cooling)
          # Write order strategy: Flutter writes heater first, cooler last for COOL/AUTO modes.
          # This ensures cooler's write is the final mode sent to Z2M.
          # - COOL mode: heater→"off", cooler→"cool" → final "cool" ✓
          # - AUTO mode: heater→"heat", cooler→"cool" → final "cool" (limitation: no true heat_cool)
          # Trade-off: COOL mode works correctly, AUTO mode enables cooling only.
          # For true heat_cool support, users should configure via Z2M interface directly.
          - z2m_feature: system_mode
            panel:
              identifier: ON
              name: Cooler On
              data_type: BOOL
            transform:
              type: map
              read:
                "off": false
                "heat": false
                "cool": true
                "auto": true
                "heat_cool": true
                "fan_only": false
              write:
                true: "cool"

          # Running state -> cooler status (true when cooling)
          - z2m_feature: running_state
            direction: read_only
            panel:
              identifier: STATUS
              name: Cooling Status
              data_type: BOOL
              settable: false
            transform:
              type: map
              read:
                "idle": false
                "heat": false
                "cool": true
                "fan_only": false

          # Cooling setpoint temperature
          - z2m_feature: occupied_cooling_setpoint
            panel:
              identifier: TEMPERATURE
              name: Cooling Setpoint
              data_type: FLOAT
              unit: "°C"

      # Humidity channel (optional, if device has humidity sensor)
      - identifier: humidity
        name: Humidity
        category: HUMIDITY
        features:
          - z2m_feature: humidity
            direction: read_only
            panel:
              identifier: HUMIDITY
              name: Humidity
              data_type: UCHAR
              format: [0, 100]
              unit: "%"
              settable: false

# The following Z2M features are mapped as internal properties:
# - preset (away, boost, comfort, eco, etc.) - stored as MODE on thermostat channel
# - fan_mode - stored as SPEED on thermostat channel
#
# NOT mapped:
# - local_temperature_calibration - no calibration property in spec