### Install and View Help for AIOSomecomfort

Source: https://github.com/mkmer/aiosomecomfort/blob/main/README.rst

Install the package via pip and display the command-line interface help menu.

```bash
$ pip install AIOSomecomfort
$ test.py -h
usage: test.py [-h] [--get_fan_mode] [--set_fan_mode SET_FAN_MODE]
                   [--get_system_mode] [--set_system_mode SET_SYSTEM_MODE]
                   [--get_setpoint_cool]
                   [--set_setpoint_cool SET_SETPOINT_COOL]
                   [--get_setpoint_heat]
                   [--set_setpoint_heat SET_SETPOINT_HEAT]
                   [--get_current_temperature] [--get_current_humidity]
                   [--get_outdoor_temperature] [--get_outdoor_humidity]
                   [--get_equipment_output_status] [--cancel_hold]
                   [--permanent_hold] [--hold_until HOLD_UNTIL] [--get_hold]
                   [--username USERNAME] [--password PASSWORD]
                   [--device DEVICE] [--login] [--devices]

optional arguments:
  -h, --help            show this help message and exit
  --get_fan_mode        Get fan_mode
  --set_fan_mode SET_FAN_MODE
                        Set fan_mode
  --get_system_mode     Get system_mode
  --set_system_mode SET_SYSTEM_MODE
                        Set system_mode
  --get_setpoint_cool   Get setpoint_cool
  --set_setpoint_cool SET_SETPOINT_COOL
                        Set setpoint_cool
  --get_setpoint_heat   Get setpoint_heat
  --set_setpoint_heat SET_SETPOINT_HEAT
                        Set setpoint_heat
  --get_current_temperature
                        Get current_temperature
  --get_current_humidity
                        Get current_humidity
  --get_outdoor_temperature
                        Get outdoor_temperature
  --get_outdoor_humidity
                        Get outdoor_humidity
  --get_equipment_output_status
                        Get equipment_output_status
  --set_humidity HUMIDITY_VALUE
                        Set humidity setpoint.
  --cancel_hold         Set cancel_hold
  --permanent_hold      Set permanent_hold
  --hold_until HOLD_UNTIL
                        Hold until time (HH:MM)
  --get_hold            Get the current hold mode
  --username USERNAME   username
  --password PASSWORD   password
  --device DEVICE       device
  --login               Just try to login
  --devices             List available devices
  --loop                Loop on temperature and operating mode
```

--------------------------------

### Execute CLI Commands for Thermostat Control

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Provides command-line examples for installing the package and performing various thermostat operations like reading sensors and setting modes.

```bash
# Install the package
pip install AIOSomecomfort

# Test login credentials
python test.py --username your_email@example.com --password your_password --login
# Output: Success

# List all devices on the account
python test.py --username your_email@example.com --password your_password --devices
# Output:
# Location 0123456:
#   Device 1177223: My Thermostat

# Read current temperature
python test.py --username your_email@example.com --password your_password --get_current_temperature
# Output: 72.0

# Read current humidity
python test.py --username your_email@example.com --password your_password --get_current_humidity
# Output: 45

# Read heat setpoint
python test.py --username your_email@example.com --password your_password --get_setpoint_heat
# Output: 68.0

# Set heat setpoint
python test.py --username your_email@example.com --password your_password --set_setpoint_heat 70
# (no output on success)

# Read cool setpoint
python test.py --username your_email@example.com --password your_password --get_setpoint_cool
# Output: 76.0

# Set cool setpoint
python test.py --username your_email@example.com --password your_password --set_setpoint_cool 74

# Read/set fan mode
python test.py --username your_email@example.com --password your_password --get_fan_mode
# Output: auto
python test.py --username your_email@example.com --password your_password --set_fan_mode on

# Read/set system mode
python test.py --username your_email@example.com --password your_password --get_system_mode
# Output: heat
python test.py --username your_email@example.com --password your_password --set_system_mode cool

# Read outdoor temperature and humidity
python test.py --username your_email@example.com --password your_password --get_outdoor_temperature
python test.py --username your_email@example.com --password your_password --get_outdoor_humidity

# Get equipment status (what's currently running)
python test.py --username your_email@example.com --password your_password --get_equipment_output_status
# Output: heat

# Get current hold status
python test.py --username your_email@example.com --password your_password --get_hold
# Output: heat:permanent cool:permanent

# Cancel all holds (return to schedule)
python test.py --username your_email@example.com --password your_password --cancel_hold
```

--------------------------------

### Run continuous monitoring loop

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Starts a polling loop that checks the thermostat status every 15 seconds.

```bash
python test.py --username your_email@example.com --password your_password --loop
# Output:
# 72.0
# heat
# 72.0
# off
# ...
```

--------------------------------

### Interact with Thermostat via CLI

Source: https://github.com/mkmer/aiosomecomfort/blob/main/README.rst

Perform authentication, list devices, and manage thermostat settings using the test script.

```bash
$ test.py --username foo --password bar --login
Success
$ test.py --devices
+----------+---------+---------------+
| Location |  Device |      Name     |
+----------+---------+---------------+
| 0123456  | 1177223 | My Thermostat |
+----------+---------+---------------+
$ test.py --get_current_temperature
58.0
$ test.py --get_setpoint_heat
58.0
$ test.py --set_setpoint_heat 56
$ test.py --get_setpoint_heat
56.0
$ test.py --loop
56.0
off
56.0
heat
```

--------------------------------

### Initialize AIOSomeComfort Client

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Initializes the AIOSomeComfort client with credentials and an aiohttp session. Handles authentication, device discovery, and provides access to thermostat data. Catches authentication and connection errors.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import AuthError, ConnectionError

async def initialize_client():
    async with aiohttp.ClientSession() as session:
        # Create client with credentials and session
        client = AIOSomeComfort(
            username="your_email@example.com",
            password="your_password",
            timeout=30,  # Optional: request timeout in seconds
            session=session
        )

        try:
            # Authenticate with Honeywell servers
            await client.login()
            print("Login successful")

            # Discover all locations and devices
            await client.discover()

            # Access discovered locations
            for loc_id, location in client.locations_by_id.items():
                print(f"Location: {loc_id}")
                for dev_id, device in location.devices_by_id.items():
                    print(f"  Device: {device.name} (ID: {dev_id})")

            # Get the default device (first device found)
            device = client.default_device
            if device:
                print(f"Default device: {device.name}")

            # Get a specific device by ID
            specific_device = client.get_device(1234567)

        except AuthError as e:
            print(f"Authentication failed: {e}")
        except ConnectionError as e:
            print(f"Connection error: {e}")

asyncio.run(initialize_client())
```

--------------------------------

### Handle Thermostat Exceptions in Python

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Demonstrates how to catch and handle specific library exceptions during login, data refresh, and setpoint updates. Requires an active aiohttp session.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import (
    SomeComfortError,      # Base exception class
    AuthError,             # Authentication failures
    ConnectionError,       # Network connectivity issues
    ConnectionTimeout,     # Request timeout
    APIError,              # General API errors
    APIRateLimited,        # Rate limiting triggered
    SessionTimedOut,       # Session expired
    ServiceUnavailable,    # Honeywell service down
    UnexpectedResponse,    # Invalid API response
    UnauthorizedError,     # 401/403 responses
)

async def robust_thermostat_control():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)

        try:
            await client.login()
            await client.discover()

        except AuthError as e:
            print(f"Login failed - check credentials: {e}")
            return
        except ConnectionTimeout:
            print("Connection timed out - check network")
            return
        except ConnectionError as e:
            print(f"Connection failed: {e}")
            return

        device = client.default_device
        if not device:
            print("No devices found on account")
            return

        try:
            # Attempt to refresh device data
            await device.refresh()

        except APIRateLimited as e:
            # Honeywell limits requests - wait before retrying
            print(f"Rate limited: {e}")
            print(f"Next login allowed at: {client.next_login}")
            return
        except UnauthorizedError:
            print("Session expired - need to re-login")
            await client.login()
            return
        except ServiceUnavailable:
            print("Honeywell service is unavailable - try again later")
            return
        except UnexpectedResponse as e:
            print(f"Unexpected API response: {e}")
            return

        try:
            # Attempt to change temperature
            await device.set_setpoint_heat(72)

        except SomeComfortError as e:
            # Catch-all for any library-specific errors
            print(f"Operation failed: {e}")
        except APIError as e:
            print(f"API rejected the request: {e}")

asyncio.run(robust_thermostat_control())
```

--------------------------------

### Set Temperature Setpoints in Python

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Adjusts heating and cooling targets while respecting device-specific deadband constraints and temperature limits.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import SomeComfortError

async def set_temperature_setpoints():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Read current setpoints
        current_heat_setpoint = device.setpoint_heat
        current_cool_setpoint = device.setpoint_cool
        print(f"Current heat setpoint: {current_heat_setpoint}")  # Output: 68.0
        print(f"Current cool setpoint: {current_cool_setpoint}")  # Output: 74.0

        try:
            # Set heating setpoint (must be within device limits)
            await device.set_setpoint_heat(70)
            print("Heat setpoint changed to 70")

            # Set cooling setpoint (must be within device limits)
            await device.set_setpoint_cool(76)
            print("Cool setpoint changed to 76")

        except SomeComfortError as e:
            # Raised if setpoint is outside valid range
            print(f"Failed to set temperature: {e}")
            # Example: "Setpoint outside range 50-90"

asyncio.run(set_temperature_setpoints())
```

--------------------------------

### Manage Temperature Hold Modes

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Shows how to check hold status, cancel holds, and set permanent or temporary temperature holds with optional setpoints.

```python
import asyncio
import datetime
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import SomeComfortError

async def manage_hold_modes():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Get current hold status for heat and cool
        # Returns: False (schedule), True (permanent), or datetime.time (temporary)
        heat_hold = device.hold_heat
        cool_hold = device.hold_cool

        if heat_hold is False:
            print("Heat: Following schedule")
        elif heat_hold is True:
            print("Heat: Permanent hold")
        else:
            print(f"Heat: Temporary hold until {heat_hold}")

        # Cancel all holds - return to schedule
        await device.set_hold_heat(False)
        await device.set_hold_cool(False)
        print("Holds cancelled, following schedule")

        # Set permanent hold (maintains setpoint indefinitely)
        await device.set_hold_heat(True)
        await device.set_hold_cool(True)
        print("Permanent hold enabled")

        # Set temporary hold until specific time (must be 15-minute boundary)
        hold_until = datetime.time(hour=18, minute=30)  # 6:30 PM
        try:
            await device.set_hold_heat(hold_until)
            await device.set_hold_cool(hold_until)
            print(f"Temporary hold set until {hold_until}")
        except SomeComfortError as e:
            print(f"Failed to set hold: {e}")
            # Example: "Invalid time: must be on a 15-minute boundary"

        # Set hold with a specific temperature
        await device.set_hold_heat(True, temperature=72)
        await device.set_hold_cool(True, temperature=76)
        print("Permanent hold with specific temperatures set")

asyncio.run(manage_hold_modes())
```

--------------------------------

### Initialize Fan Mode Control in Python

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Boilerplate code for configuring fan operation modes like auto, on, or circulate.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import SomeComfortError
```

--------------------------------

### Control Fan Modes

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Demonstrates how to retrieve current fan status and update the fan mode to auto, on, circulate, or follow schedule.

```python
async def control_fan_mode():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Get current fan mode setting
        fan_mode = device.fan_mode
        print(f"Current fan mode: {fan_mode}")  # Output: auto

        # Check if fan is currently running
        fan_running = device.fan_running
        print(f"Fan is running: {fan_running}")  # Output: True

        try:
            # Set fan to auto mode
            await device.set_fan_mode("auto")
            print("Fan set to auto")

            # Set fan to run continuously
            await device.set_fan_mode("on")
            print("Fan set to on")

            # Set fan to circulate mode
            await device.set_fan_mode("circulate")
            print("Fan set to circulate")

            # Set fan to follow schedule
            await device.set_fan_mode("follow schedule")
            print("Fan set to follow schedule")

        except SomeComfortError as e:
            print(f"Failed to set fan mode: {e}")
            # Example: "Device does not support circulate"

asyncio.run(control_fan_mode())
```

--------------------------------

### Control humidity via CLI

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Adjusts the thermostat humidity setting if the device supports it.

```bash
python test.py --username your_email@example.com --password your_password --set_humidity 45
```

--------------------------------

### Set permanent hold via CLI

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Sets a permanent hold on the thermostat using the specified credentials.

```bash
python test.py --username your_email@example.com --password your_password --permanent_hold
```

--------------------------------

### Target specific device via CLI

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Targets a specific thermostat device by its ID to retrieve the current temperature.

```bash
python test.py --username your_email@example.com --password your_password --device 1177223 --get_current_temperature
```

--------------------------------

### Control Humidifier and Dehumidifier Devices

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Use this snippet to control integrated humidifier and dehumidifier systems. It checks for device availability, reads current settings, and demonstrates setting humidity setpoints and modes (auto/off). Requires aiohttp and AIOSomeComfort libraries.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import APIError

async def control_humidity_devices():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Humidifier control
        if device.has_humidifier:
            print("Humidifier is available")

            # Read humidifier settings
            humidifier_setpoint = device.humidifier_setpoint
            humidifier_mode = device.humidifier_mode  # 1=auto, 0=off
            lower_limit = device.humidifier_lower_limit
            upper_limit = device.humidifier_upper_limit

            print(f"Humidifier setpoint: {humidifier_setpoint}%")
            print(f"Humidifier mode: {'auto' if humidifier_mode == 1 else 'off'}")
            print(f"Limits: {lower_limit}% - {upper_limit}%")

            try:
                # Set humidifier setpoint (rounded to nearest 5%)
                await device.set_humidifier_setpoint(45)
                print("Humidifier setpoint set to 45%")

                # Enable humidifier auto mode
                await device.set_humidifier_auto()
                print("Humidifier set to auto mode")

                # Turn off humidifier
                await device.set_humidifier_off()
                print("Humidifier turned off")

            except APIError as e:
                print(f"Humidifier control failed: {e}")
        else:
            print("No humidifier available")

        # Dehumidifier control
        if device.has_dehumidifier:
            print("Dehumidifier is available")

            # Read dehumidifier settings
            dehumidifier_setpoint = device.dehumidifier_setpoint
            dehumidifier_mode = device.dehumidifier_mode  # 1=auto, 0=off
            lower_limit = device.dehumidifier_lower_limit
            upper_limit = device.dehumidifier_upper_limit

            print(f"Dehumidifier setpoint: {dehumidifier_setpoint}%")
            print(f"Dehumidifier mode: {'auto' if dehumidifier_mode == 1 else 'off'}")

            try:
                # Set dehumidifier setpoint (rounded to nearest 5%)
                await device.set_dehumidifier_setpoint(50)
                print("Dehumidifier setpoint set to 50%")

                # Enable dehumidifier auto mode
                await device.set_dehumidifier_auto()
                print("Dehumidifier set to auto mode")

                # Turn off dehumidifier
                await device.set_dehumidifier_off()
                print("Dehumidifier turned off")

            except APIError as e:
                print(f"Dehumidifier control failed: {e}")
        else:
            print("No dehumidifier available")

asyncio.run(control_humidity_devices())

```

--------------------------------

### Access Raw API Data from Honeywell Thermostat

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Retrieve and inspect raw data structures from the Honeywell API for debugging or advanced analysis. This includes UI, fan, and demand response data. Requires aiohttp and AIOSomeComfort libraries.

```python
import asyncio
import aiohttp
import json
from aiosomecomfort import AIOSomeComfort

async def access_raw_data():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Get device identifiers
        device_id = device.deviceid
        mac_address = device.mac_address
        device_name = device.name

        print(f"Device ID: {device_id}")
        print(f"MAC Address: {mac_address}")
        print(f"Device Name: {device_name}")

        # Access raw API response data (read-only deep copies)
        raw_ui_data = device.raw_ui_data
        raw_fan_data = device.raw_fan_data
        raw_dr_data = device.raw_dr_data  # Demand response data
        raw_data = device.raw_data  # Full raw data structure

        # Example: Print all available UI data keys
        print("UI Data keys:", list(raw_ui_data.keys()))

        # Example: Access specific raw values
        print(f"Heat lower limit: {raw_ui_data.get('HeatLowerSetptLimit')}")
        print(f"Heat upper limit: {raw_ui_data.get('HeatUpperSetptLimit')}")
        print(f"Cool lower limit: {raw_ui_data.get('CoolLowerSetptLimit')}")
        print(f"Cool upper limit: {raw_ui_data.get('CoolUpperSetptLimit')}")
        print(f"Deadband: {raw_ui_data.get('Deadband')}")

        # Export raw data to JSON for analysis
        with open("thermostat_data.json", "w") as f:
            json.dump(raw_data, f, indent=2, default=str)
            print("Raw data exported to thermostat_data.json")

asyncio.run(access_raw_data())

```

--------------------------------

### Manage System Mode in Python

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Updates the thermostat operating mode, such as heat, cool, or off, after validating device support.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort
from aiosomecomfort.exceptions import SomeComfortError

# Available system modes: "emheat", "heat", "off", "cool", "auto"

async def manage_system_mode():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Get current system mode
        current_mode = device.system_mode
        print(f"Current system mode: {current_mode}")  # Output: heat

        # Get equipment output status (what's currently running)
        equipment_status = device.equipment_output_status
        print(f"Equipment status: {equipment_status}")  # Output: heat, cool, fan, or off

        try:
            # Set to cooling mode
            await device.set_system_mode("cool")
            print("System mode set to cool")

            # Set to heating mode
            await device.set_system_mode("heat")
            print("System mode set to heat")

            # Set to auto mode (automatic heat/cool switching)
            await device.set_system_mode("auto")
            print("System mode set to auto")

            # Turn system off
            await device.set_system_mode("off")
            print("System turned off")

            # Set emergency heat (if supported)
            await device.set_system_mode("emheat")
            print("Emergency heat activated")

        except SomeComfortError as e:
            print(f"Failed to set system mode: {e}")
            # Example: "Device does not support cool"

asyncio.run(manage_system_mode())
```

--------------------------------

### Set temporary hold via CLI

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Sets a temporary hold until a specific time using the --hold_until flag.

```bash
python test.py --username your_email@example.com --password your_password --hold_until 18:30
```

--------------------------------

### Read Thermostat Sensor Data

Source: https://context7.com/mkmer/aiosomecomfort/llms.txt

Reads current temperature, humidity, and outdoor conditions from a thermostat device. Also retrieves the temperature unit (F/C) and checks device responsiveness. Refreshes data from the API.

```python
import asyncio
import aiohttp
from aiosomecomfort import AIOSomeComfort

async def read_sensor_data():
    async with aiohttp.ClientSession() as session:
        client = AIOSomeComfort("email@example.com", "password", session=session)
        await client.login()
        await client.discover()

        device = client.default_device

        # Get current indoor temperature
        current_temp = device.current_temperature
        print(f"Current temperature: {current_temp}")  # Output: 72.0

        # Get temperature unit (F or C)
        temp_unit = device.temperature_unit
        print(f"Temperature unit: {temp_unit}")  # Output: F

        # Get current indoor humidity (if sensor available)
        humidity = device.current_humidity
        if humidity is not None:
            print(f"Indoor humidity: {humidity}%")  # Output: 45

        # Get outdoor temperature (if available)
        outdoor_temp = device.outdoor_temperature
        if outdoor_temp is not None:
            print(f"Outdoor temperature: {outdoor_temp}")  # Output: 65.0

        # Get outdoor humidity (if available)
        outdoor_humidity = device.outdoor_humidity
        if outdoor_humidity is not None:
            print(f"Outdoor humidity: {outdoor_humidity}%")  # Output: 60

        # Check if device is connected and responsive
        is_alive = device.is_alive
        print(f"Device is alive: {is_alive}")  # Output: True

        # Refresh device data from the API
        await device.refresh()

asyncio.run(read_sensor_data())
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.