### Task Setup and Run

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Commands to set up the development environment using Go-Task and to run the main task.

```shell
task setup
task
```

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

### Install hubitatcontrol from source

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Install the hubitatcontrol library directly from its GitHub repository. Use this if you need the latest development version.

```shell
pip install git+https://github.com/Jelloeater/hubitatcontrol.git
```

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

### Install Hubitat Control

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Install the library from PyPI or directly from its source repository.

```bash
pip install hubitatcontrol
```

```bash
pip install git+https://github.com/Jelloeater/hubitatcontrol.git
```

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

### Get and control a specific device

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Retrieve a specific device by its name and send a command to turn it on. This example assumes the device is a switch or light.

```python
TEST_DEVICE = '1RGB'

device = hc.GetSingleDevice(hub).name(TEST_DEVICE)

device.turn_on() # Send command to device

print(device.switch)
```

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

### Install hubitatcontrol using pip

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Install the hubitatcontrol library using pip. This is the standard method for installing Python packages.

```shell
pip install hubitatcontrol
```

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

### Control a Device (Turn On)

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/README.md

Get a specific device by name and send a 'turn_on' command. The current state of the device is then printed.

```python
TEST_DEVICE = '1RGB'

device = hc.GetSingleDevice(hub).name(TEST_DEVICE)

# Turn on all the switches (includes lights)
device.turn_on() # Send command to device
print(device.switch)
```

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

### Control RGBW Bulbs: Full Color

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Provides examples for controlling RGBW smart bulbs, including reading and setting hue, saturation, and color mode. It also shows how to set individual components or all color parameters atomically.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
bulb = hc.GetSingleDevice(hub).name('Bedroom RGBW Bulb')
# type(bulb) -> <class 'hubitatcontrol.lights.RGBWBulb'>

# Read current color state
print(bulb.hue)          # 0–100
print(bulb.saturation)   # 0–100
print(bulb.color_mode)   # 'RGB' or 'CT'
print(bulb.color_name)   # 'Red', 'Blue', etc.
print(bulb.color)        # Raw color value string

# Set individual color components
bulb.set_hue(10)          # Warm red hue (waits 2s)
bulb.set_saturation(80)   # High saturation (waits 2s)

# Set hue, saturation, and level atomically
bulb.set_color(hue=66, saturation=100, level=75)
# Sends: setColor/{"hue": 66, "saturation": 100, "level": 75}

# Full scene: turn on, warm white dim
bulb.turn_on()
bulb.set_color_temp(3000)
bulb.set_level(40)
```

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

### Connect to Hubitat Hub

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Initialize the Hub object to establish a connection. Supports both local network and cloud-based API endpoints. Use the `devices` attribute to get a list of all devices, or `get_device` and `get_device_id` to retrieve specific devices.

```python
import hubitatcontrol as hc

# Local network connection
hub = hc.Hub(
    host='http://192.168.1.100',
    token='your-maker-api-token',
    app_id='1'
)

# Cloud connection (requires an additional cloud token)
hub_cloud = hc.Hub(
    host='https://cloud.hubitat.com',
    token='your-maker-api-token',
    app_id='1',
    cloud_token='your-cloud-api-token'
)

# List all devices registered on the hub
all_devices = hub.devices  # Returns raw list of device dicts
for d in all_devices:
    print(d['id'], d['name'], d['type'])
# Output:
# 42  Living Room Light  Inovelli LZW31-SN Red Series Dimmer
# 55  Front Door Sensor  Generic Zigbee Contact Sensor
# ...

# Look up a device by label
raw = hub.get_device('Living Room Light')
print(raw['capabilities'])  # ['Switch', 'SwitchLevel', ...]

# Look up a device by numeric ID
raw_by_id = hub.get_device_id(42)
print(raw_by_id['type'])
```

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

### Read Environmental Sensors: Temperature and Humidity

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Demonstrates how to read both temperature and humidity from environmental sensors. Includes an example of triggering an alert for high humidity levels.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')

for sensor in hc.GetDevices(hub).EnvironmentalSensor():
    print(f"{sensor.name}: {sensor.temperature}°F, {sensor.humidity}% RH")
    if sensor.humidity > 70:
        print(f"  High humidity alert: {sensor.name}")
# Output:
# Bathroom Sensor: 74°F, 78% RH
#   High humidity alert: Bathroom Sensor
# Basement Sensor: 65°F, 55% RH
```

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

### Control Zigbee Outlets: Power Metering

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Demonstrates how to use the ZigbeeOutlet class to read the on/off status and current power consumption (in watts) of smart outlets. Includes an example of turning off outlets with high power draw.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
outlets = hc.GetDevices(hub).Outlet()

for outlet in outlets:
    status = outlet.switch         # 'on' or 'off'
    watts = outlet.power           # current power draw in watts
    print(f"{outlet.name}: {status}, {watts}W")
    if watts > 1500:
        print(f"  WARNING: High power draw on {outlet.name}")
        outlet.turn_off()
```

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

### Mermaid Class Diagram

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/README.md

Visual representation of the project's class hierarchy. No specific setup required to view.

```mermaid
flowchart LR
Specific_Device --> Abstract_Device_Class --> Device--> Hub
```

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

### Get temperature from all sensors

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Iterate through all devices identified as TemperatureSensors and print their names and current temperature readings.

```python
for i in hc.GetDevices(hub).TemperatureSensor():

	i print(f"{i.name} \- {i.temperature}")
```

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

### Control Dimmers: Brightness Level

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Shows how to control the brightness level of dimmer devices from 0 to 100. Includes an example of handling invalid range exceptions.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
dimmer = hc.GetSingleDevice(hub).name('Living Room Dimmer')

print(dimmer.level)      # 75

dimmer.set_level(50)     # Set to 50% brightness (waits 2.5s for device to respond)
print(dimmer.level)      # 50

try:
    dimmer.set_level(150)  # Raises Exception: Invalid range
except Exception as e:
    print(e)
```

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

### Hubitat Control CLI Help

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Run this command to see the general help information for the Hubitat Control CLI.

```bash
hubitatcontrol --help
```

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

### Control Switches: On/Off

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Demonstrates how to list all switches, read their current state, and send on/off commands. Also shows how to inspect device metadata like commands, capabilities, history, and attributes.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
switches = hc.GetDevices(hub).Switch()

for sw in switches:
    print(f"{sw.name} is currently {sw.switch}")  # 'on' or 'off'

# Turn on a specific switch
sw = hc.GetSingleDevice(hub).name('Porch Light')
sw.turn_on()
print(sw.switch)   # 'on'

sw.turn_off()
print(sw.switch)   # 'off'

# Inspect raw device metadata
print(sw.commands)      # List of available commands
print(sw.capabilities)  # List of capability strings
print(sw.history)       # List of recent event dicts
print(sw.attributes)    # List of attribute dicts with currentValue
```

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

### Initialize Hubitat Hub Object (Local)

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/README.md

Create a Hub object for local API access. Ensure you have your Hubitat host IP address, Maker API token, and App ID.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='Maker_Token', app_id='Maker_App_ID') # Get Hub object to auth and poll against
```

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

### List Devices from Keyring

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

This command lists the devices currently recognized from the system keyring.

```bash
hubitatcontrol ls
```

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

### Hubitat Control CLI Usage Overview

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/README.md

Provides a detailed overview of the Hubitat Control CLI, including its purpose, options, and available commands.

```text
❯ hubitatcontrol

 Usage: hubitatcontrol [OPTIONS] COMMAND [ARGS]...

 Hubitat Control CLI Interface

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion        [bash|zsh|fish|powershell|pwsh]  Install completion for the specified shell. │
│                                                              [default: None]                             │
│ --show-completion           [bash|zsh|fish|powershell|pwsh]  Show completion for the specified shell, to │
│                                                              copy it or customize the installation.      │
│                                                              [default: None]                             │
│ --help                                                       Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────╮
│ clear-keyring                      Clear Keyring passwords                                               │
│ level                              Turn on a device via it's Device ID                                   │
│ load-env-to-keyring                Load .env file at exec location to keyring                            │
│ ls                                 Prints current devices from system keyring                            │
│ off                                Turn on a device via it's Device ID                                   │
│ on                                 Turn on a device via it's Device ID                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Version: 1.1.2   Project: https://github.com/Jelloeater/hubitatcontrol
```

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

### CLI Commands

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Command-line interface for quick device inspection and basic control.

```APIDOC
## CLI — `hubitatcontrol`

The CLI provides quick device inspection and basic control from the terminal, reading credentials from the OS keyring.

### Setup
```bash
# First-time setup: store .env credentials in the OS keyring
hubitatcontrol load-env-to-keyring
```

### Device Listing
```bash
# List all devices in a table
hubitatcontrol ls
# Output:
# +----+----------------------+--------------------------+
# | id | name                 | type                     |
# +----+----------------------+--------------------------+
# | 42 | Living Room Dimmer   | Inovelli LZW31-SN Dimmer |
# | 55 | Bedroom Sensor       | Generic Zigbee Sensor    |
# +----+----------------------+--------------------------+
```

### Device Control
```bash
# Turn a device on by ID
hubitatcontrol on 42

# Turn a device off by ID
hubitatcontrol off 42

# Set brightness level (0-100) by device ID
hubitatcontrol level 42 75
```

### Cleanup
```bash
# Remove stored credentials from keyring
hubitatcontrol clear-keyring
```
```

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

### get_hub_envs() - Create Hub from Environment Variables

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

This function simplifies the connection process by automatically loading Hubitat credentials from environment variables or a `.env` file, returning a configured `Hub` object.

```APIDOC
## get_hub_envs()

Create Hub from Environment Variables

### Description
Loads credentials from a `.env` file (or existing environment variables) and returns a ready-to-use `Hub` object.

### Usage
```python
import hubitatcontrol as hc

# Reads HUBITAT_HOST, HUBITAT_API_TOKEN, HUBITAT_API_APP_ID,
# and optionally HUBITAT_CLOUD_TOKEN from the environment / .env file
hub = hc.get_hub_envs()

print(len(hub.devices), "devices found")
```
```

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

### Load Environment Variables to OS Keyring with hubitatcontrol CLI

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Use `hubitatcontrol load-env-to-keyring` to securely store your Hubitat Maker API credentials from a .env file into the operating system's keyring for use with the CLI.

```bash
# First-time setup: store .env credentials in the OS keyring
hubitatcontrol load-env-to-keyring
```

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

### Load Environment Variables to Keyring

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Use this command to load API keys from your .env file into the system keyring for use by the CLI.

```bash
hubitatcontrol load-env-to-keyring
```

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

### Create Hub from Environment Variables

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

The `get_hub_envs()` function simplifies connecting to the Hubitat hub by automatically loading credentials from environment variables or a .env file. It returns a configured `Hub` object.

```python
import hubitatcontrol as hc

# Reads HUBITAT_HOST, HUBITAT_API_TOKEN, HUBITAT_API_APP_ID,
# and optionally HUBITAT_CLOUD_TOKEN from the environment / .env file
hub = hc.get_hub_envs()

print(len(hub.devices), "devices found")
# Output: 24 devices found
```

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

### Initialize Hubitat Hub Object (Cloud)

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/README.md

Create a Hub object for cloud API access. This requires the additional 'cloud_token' parameter.

```python
# If you have a cloud based maker API, you can include the cloud token
# hub = hc.get_hub(host='https://cloud.hubitat.com', token='Maker_Token',
#                  app_id='Maker_App_ID', cloud_token='Cloud_API_token')
```

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

### Control Color Temperature Bulbs

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Demonstrates how to adjust the color temperature of smart bulbs in Kelvin, set brightness, and turn them on. Assumes the bulb extends the Dimmer class.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
bulb = hc.GetSingleDevice(hub).name('Office Bulb')
# type(bulb) -> <class 'hubitatcontrol.lights.ColorTempBulb'>

print(bulb.color_temp)      # 4000 (Kelvin)
bulb.set_color_temp(2700)   # Warm white (waits 2s)
bulb.set_level(80)          # 80% brightness
bulb.turn_on()
```

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

### Hubitat Control CLI Usage

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Displays the overall usage instructions, options, and available commands for the Hubitat Control CLI.

```text
❯ hubitatcontrol

 Usage: hubitatcontrol [OPTIONS] COMMAND [ARGS]...

 Hubitat Control CLI Interface

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮

│ --install-completion        [bash|zsh|fish|powershell|pwsh]  Install completion for the specified shell. │
│                                                              [default: None]                             │
│ --show-completion           [bash|zsh|fish|powershell|pwsh]  Show completion for the specified shell, to │
│                                                              copy it or customize the installation.      │
│                                                              [default: None]                             │
│ --help                                                       Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────╮

│ clear-keyring                      Clear Keyring passwords                                               │
│ level                              Turn on a device via it's Device ID                                   │
│ load-env-to-keyring                Load .env file at exec location to keyring                            │
│ ls                                 Prints current devices from system keyring                            │
│ off                                Turn on a device via it's Device ID                                   │
│ on                                 Turn on a device via it's Device ID                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Version: 1.1.2   Project: https://github.com/Jelloeater/hubitatcontrol
```

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

### List All Devices with hubitatcontrol CLI

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Use `hubitatcontrol ls` to display a table of all connected Hubitat devices, including their ID, name, and type. This is useful for quick inspection and identifying device IDs for control commands.

```bash
# List all devices in a table
hubitatcontrol ls
# Output:
# +----+----------------------+--------------------------+
# | id | name                 | type                     |
# +----+----------------------+--------------------------+
# | 42 | Living Room Dimmer   | Inovelli LZW31-SN Dimmer |
# | 55 | Bedroom Sensor       | Generic Zigbee Sensor    |
# +----+----------------------+--------------------------+
```

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

### DeviceInit.cast_device

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/index.md

Dynamically casts a device to its appropriate type based on its capabilities.

```APIDOC
## cast_device()

### Description
The order here is very important that we cast the device properly based on increasing complexity / functionality.

### Method
This is a method of the DeviceInit class.
```

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

### Configure Hubitat Credentials

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Store Hubitat API credentials in a .env file for the Python API or use the OS keyring for the CLI. The .env file should contain the host, API token, and app ID. Cloud connections require an additional cloud token.

```ini
# .env
HUBITAT_HOST=http://192.168.1.100
HUBITAT_API_TOKEN=00000000-0000-0000-0000-000000000000
HUBITAT_API_APP_ID=1
HUBITAT_CLOUD_TOKEN=          # Leave blank for local API access
```

```bash
# Load .env into the OS keyring for CLI use
hubitatcontrol load-env-to-keyring
```

```bash
# Clear stored keyring credentials
hubitatcontrol clear-keyring
```

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

### Retrieve and Auto-Cast a Single Device

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

The `GetSingleDevice` class retrieves a single device by its name or ID and automatically casts it to its most specific Python class (e.g., `Dimmer`, `TemperatureSensor`). This allows direct access to device attributes like `switch`, `level`, or `temperature`.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')

# Look up by device name (matches the "name" field, not "label")
device = hc.GetSingleDevice(hub).name('Living Room Dimmer')
print(type(device))           # <class 'hubitatcontrol.lights.Dimmer'>
print(device.switch)          # 'on'
print(device.level)           # 75

# Look up by numeric device ID
sensor = hc.GetSingleDevice(hub).id(55)
print(type(sensor))           # <class 'hubitatcontrol.sensors.TemperatureSensor'>
print(sensor.temperature)     # 72
```

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

### Turn Device On/Off by ID with hubitatcontrol CLI

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Control devices using their ID with the `hubitatcontrol on <id>` and `hubitatcontrol off <id>` commands. These commands send basic on/off signals to the specified device.

```bash
# Turn a device on by ID
hubitatcontrol on 42

# Turn a device off by ID
hubitatcontrol off 42
```

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

### GetDevices

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/index.md

Retrieves a list of pre-casted devices that can be searched through.

```APIDOC
## GetDevices

### Description
Get a list of pre-casted devices you can search though.

### Methods
- Bulb() -> list[hubitatcontrol.lights.Bulb]
- ColorTempBulb() -> list[hubitatcontrol.lights.ColorTempBulb]
- Dimmer() -> list[hubitatcontrol.lights.Dimmer]
- EnvironmentalSensor() -> list[hubitatcontrol.sensors.EnvironmentalSensor]
- Outlet() -> list[hubitatcontrol.generic.ZigbeeOutlet]
- RGBWBulb() -> list[hubitatcontrol.lights.RGBWBulb]
- Switch() -> list[hubitatcontrol.generic.Switch]
- TemperatureSensor() -> list[hubitatcontrol.sensors.TemperatureSensor]
```

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

### Device.send_device_command()

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Sends an arbitrary command string and an optional secondary argument directly to a device via the Maker API.

```APIDOC
## `Device.send_device_command()` — Raw Command Dispatch

Sends an arbitrary command string (and optional secondary argument) directly to any device via the Maker API.

### Method Signature
`send_device_command(command: str, secondary_command: Optional[str] = None)`

### Parameters
- **command** (str) - Required - The command to send to the device.
- **secondary_command** (str, optional) - The secondary argument for the command. Defaults to None.

### Request Example
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
device = hc.GetSingleDevice(hub).name('Living Room Dimmer')

# Simple command
response = device.send_device_command(command='on')
print(response)

# Command with argument
response = device.send_device_command(command='setLevel', secondary_command='65')
print(response)
```

### Response Example
```json
{
  "API response JSON": "..."
}
```

### Inspect Available Commands
```python
print(device.commands)
# Example Output:
# [{'command': 'on', 'type': 'COMMAND'}, {'command': 'setLevel', 'type': 'COMMAND'}, ...]
```
```

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

### GetDevices - Retrieve All Devices of a Given Type

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Fetches all devices of a specified type from the Hubitat hub, returning them as a list of objects cast to their corresponding Python classes. This allows for easy iteration and control over groups of devices.

```APIDOC
## GetDevices

Retrieve All Devices of a Given Type

### Description
Returns a list of all hub devices cast to a specific device class, filtered by their capabilities.

### Usage
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
gd = hc.GetDevices(hub)

# All temperature sensors
for sensor in gd.TemperatureSensor():
    print(f"{sensor.name}: {sensor.temperature}°F")

# All environmental sensors (temp + humidity)
for sensor in gd.EnvironmentalSensor():
    print(f"{sensor.name}: {sensor.temperature}°F, {sensor.humidity}% RH")

# All dimmable switches
for dimmer in gd.Dimmer():
    print(f"{dimmer.name} level: {dimmer.level}%")

# All smart outlets with power metering
for outlet in gd.Outlet():
    print(f"{outlet.name}: {outlet.power}W")

# Available typed getters:
# gd.Switch()          -> list[generic.Switch]
# gd.Outlet()          -> list[generic.ZigbeeOutlet]
# gd.Dimmer()          -> list[lights.Dimmer]
```
```

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

### Device Class Methods

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/hub.md

Methods available on the Device class for interacting with a specific device.

```APIDOC
## Device Class

### Methods

`send_device_command(self, command: str, secondary_command: str = None) -> requests.models.Response`
: Sends a command to the device. Supports an optional secondary command.
```

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

### Read Temperature Sensors

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Shows how to retrieve temperature readings from individual sensors using their ID or by listing all temperature sensors available in the Hubitat system.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')

# Single sensor lookup
sensor = hc.GetSingleDevice(hub).id(55)
print(f"Temperature: {sensor.temperature}°F")
# Output: Temperature: 72°F

# All temperature sensors
for s in hc.GetDevices(hub).TemperatureSensor():
    print(f"{s.name}: {s.temperature}°F")
```

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

### GetSingleDevice.name

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/index.md

Retrieves a single device by its name and casts it to the matched specification.

```APIDOC
## name(device_name: str)

### Description
Get a device by name and cast to the matched spec.

### Parameters
#### Path Parameters
- **device_name** (str) - Required - The name of the device.
```

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

### get_hub_envs

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/index.md

Generates a Hub object from local environmental variables.

```APIDOC
## get_hub_envs()

### Description
Generates a Hub object from local environmental variables.

### Returns
- hubitatcontrol.hub.Hub: A Hub object representing the local Hubitat environment.
```

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

### Initialize Hub object for cloud API access

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Create a Hub object for accessing the Hubitat Elevation controller via its cloud Maker API endpoint. This requires the cloud token in addition to the standard host, token, and app ID.

```python
hub = hc.get*hub(host='https://cloud.hubitat.com', token='Maker*Token',
=======================================================================
app*id='Maker*App*ID', cloud*token='Cloud*API*token')
=====================================================
```

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

### Initialize Hub object for local API access

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

Create a Hub object to authenticate and poll data from a Hubitat Elevation controller using its local Maker API endpoint. Ensure you have your Hub's IP address, Maker API token, and App ID.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='Maker_Token',

app*id='Maker*App_ID') # Get Hub object to auth and poll against
```

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

### RGBWBulb - Full Color Control

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Extends `ColorTempBulb` with hue, saturation, and combined color control for RGBW smart bulbs.

```APIDOC
## RGBWBulb - Full Color Control

### Description
Extends `ColorTempBulb` with hue, saturation, and combined color control for RGBW smart bulbs.

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
bulb = hc.GetSingleDevice(hub).name('Bedroom RGBW Bulb')
# type(bulb) -> <class 'hubitatcontrol.lights.RGBWBulb'>

# Read current color state
print(bulb.hue)          # 0–100
print(bulb.saturation)   # 0–100
print(bulb.color_mode)   # 'RGB' or 'CT'
print(bulb.color_name)   # 'Red', 'Blue', etc.
print(bulb.color)        # Raw color value string

# Set individual color components
bulb.set_hue(10)          # Warm red hue (waits 2s)
bulb.set_saturation(80)   # High saturation (waits 2s)

# Set hue, saturation, and level atomically
bulb.set_color(hue=66, saturation=100, level=75)
# Sends: setColor/{"hue": 66, "saturation": 100, "level": 75}

# Full scene: turn on, warm white dim
bulb.turn_on()
bulb.set_color_temp(3000)
bulb.set_level(40)
```

### Attributes
- **hue** (int): The current hue (0-100).
- **saturation** (int): The current saturation (0-100).
- **color_mode** (str): The current color mode ('RGB' or 'CT').
- **color_name** (str): The name of the current color.
- **color** (str): The raw color value string.

### Methods
- **set_hue(hue: int)**: Sets the hue.
- **set_saturation(saturation: int)**: Sets the saturation.
- **set_color(hue: int, saturation: int, level: int)**: Sets hue, saturation, and level atomically.
- **set_color_temp(kelvin: int)**: Sets the color temperature (inherited from ColorTempBulb).
- **set_level(level: int)**: Sets the brightness level (inherited from Dimmer).
- **turn_on()**: Turns the bulb on (inherited from Switch).
```

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

### Send Raw Device Command with hubitatcontrol

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Use `send_device_command` to send arbitrary commands to a device. This method supports commands with or without secondary arguments. Inspect `device.commands` to see available commands.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
device = hc.GetSingleDevice(hub).name('Living Room Dimmer')

# Simple command
response = device.send_device_command(command='on')
print(response)   # API response JSON

# Command with argument
response = device.send_device_command(command='setLevel', secondary_command='65')
print(response)

# Inspect all available commands before sending
print(device.commands)
# [{'command': 'on', 'type': 'COMMAND'}, {'command': 'setLevel', 'type': 'COMMAND'}, ...]
```

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

### Hub Class Methods

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/hub.md

Methods available on the Hub class for managing devices.

```APIDOC
## Hub Class

### Methods

`get_device(self, name: str)`
: Retrieves a device by its name.

`get_device_id(self, dev_id: int)`
: Retrieves a device by its ID.
```

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

### Mermaid Class Diagram

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/index.rst

A visual representation of the class model for Hubitat Control, showing the relationships between different device classes.

```mermaid
flowchart LR

Specific*Device --> Abstract*Device_Class --> Device--> Hub
```

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

### Hub - Connect to the Hubitat Elevation Controller

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

The `Hub` class is the primary entry point for API communication. It allows you to establish a connection to your Hubitat controller, either locally or via the cloud, and provides access to device information.

```APIDOC
## Hub

Connect to the Hubitat Elevation Controller

### Description
`Hub` is the entry point for all API communication. It builds the correct base URL for either a local or cloud endpoint and exposes the device list.

### Usage
```python
import hubitatcontrol as hc

# Local network connection
hub = hc.Hub(
    host='http://192.168.1.100',
    token='your-maker-api-token',
    app_id='1'
)

# Cloud connection (requires an additional cloud token)
hub_cloud = hc.Hub(
    host='https://cloud.hubitat.com',
    token='your-maker-api-token',
    app_id='1',
    cloud_token='your-cloud-api-token'
)

# List all devices registered on the hub
all_devices = hub.devices  # Returns raw list of device dicts
for d in all_devices:
    print(d['id'], d['name'], d['type'])

# Look up a device by label
raw = hub.get_device('Living Room Light')
print(raw['capabilities'])

# Look up a device by numeric ID
raw_by_id = hub.get_device_id(42)
print(raw_by_id['type'])
```
```

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

### Set Device Brightness Level with hubitatcontrol CLI

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Adjust the brightness of a dimmable device using the `hubitatcontrol level <id> <level>` command. The level should be an integer between 0 and 100.

```bash
# Set brightness level (0-100) by device ID
hubitatcontrol level 42 75
```

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

### ZigbeeOutlet - Smart Outlet with Power Metering

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Extends `Switch` with real-time power consumption reading (watts).

```APIDOC
## ZigbeeOutlet - Smart Outlet with Power Metering

### Description
Extends `Switch` with real-time power consumption reading (watts).

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
outlets = hc.GetDevices(hub).Outlet()

for outlet in outlets:
    status = outlet.switch         # 'on' or 'off'
    watts = outlet.power           # current power draw in watts
    print(f"{outlet.name}: {status}, {watts}W")
    if watts > 1500:
        print(f"  WARNING: High power draw on {outlet.name}")
        outlet.turn_off()
```

### Attributes
- **switch** (str): The current state of the outlet ('on' or 'off').
- **power** (float): The current power draw in watts.

### Methods
- **turn_on()**: Turns the outlet on (inherited from Switch).
- **turn_off()**: Turns the outlet off (inherited from Switch).
```

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

### EnvironmentalSensor - Temperature and Humidity Reading

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Extends `TemperatureSensor` with humidity measurement.

```APIDOC
## EnvironmentalSensor - Temperature and Humidity Reading

### Description
Extends `TemperatureSensor` with humidity measurement, matching devices that report both `TemperatureMeasurement` and `RelativeHumidityMeasurement` capabilities.

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')

for sensor in hc.GetDevices(hub).EnvironmentalSensor():
    print(f"{sensor.name}: {sensor.temperature}°F, {sensor.humidity}% RH")
    if sensor.humidity > 70:
        print(f"  High humidity alert: {sensor.name}")
# Output:
# Bathroom Sensor: 74°F, 78% RH
#   High humidity alert: Bathroom Sensor
# Basement Sensor: 65°F, 55% RH
```

### Attributes
- **temperature** (float): The current temperature reading (e.g., in °F) (inherited from TemperatureSensor).
- **humidity** (float): The current relative humidity percentage.
```

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

### Thermostat

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/generic.md

Represents a generic thermostat device. Provides methods to set the temperature.

```APIDOC
## Thermostat

### Description
Represents a generic thermostat device. Provides methods to set the temperature.

### Methods

#### `set_temperature()`
Sets the thermostat temperature.
```

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

### GetSingleDevice - Retrieve and Auto-Cast One Device

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Retrieves a single device from the Hubitat hub, automatically casting it to its most specific Python class based on its capabilities. Devices can be looked up by name or ID.

```APIDOC
## GetSingleDevice

Retrieve and Auto-Cast One Device

### Description
Looks up a single device by name or ID and returns it cast to its most specific Python class.

### Usage
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')

# Look up by device name (matches the "name" field, not "label")
device = hc.GetSingleDevice(hub).name('Living Room Dimmer')
print(type(device))           # <class 'hubitatcontrol.lights.Dimmer'>
print(device.switch)          # 'on'
print(device.level)           # 75

# Look up by numeric device ID
sensor = hc.GetSingleDevice(hub).id(55)
print(type(sensor))           # <class 'hubitatcontrol.sensors.TemperatureSensor'>
print(sensor.temperature)     # 72
```
```

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

### Retrieve Temperature Sensor Data

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/README.md

Iterate through all devices identified as Temperature Sensors and print their name and current temperature.

```python
# Get temprature from all sensors
for i in hc.GetDevices(hub).TemperatureSensor():
    print(f"{i.name} - {i.temperature}")
```

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

### Retrieve All Devices of a Specific Type

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

The `GetDevices` class allows you to retrieve a list of all devices on the hub that match a specific capability or type. The returned devices are cast to their corresponding Python classes, enabling easy access to their attributes and methods.

```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
gd = hc.GetDevices(hub)

# All temperature sensors
for sensor in gd.TemperatureSensor():
    print(f"{sensor.name}: {sensor.temperature}°F")
# Output:
# Bedroom Sensor: 68°F
# Office Sensor: 71°F

# All environmental sensors (temp + humidity)
for sensor in gd.EnvironmentalSensor():
    print(f"{sensor.name}: {sensor.temperature}°F, {sensor.humidity}% RH")

# All dimmable switches
for dimmer in gd.Dimmer():
    print(f"{dimmer.name} level: {dimmer.level}%")

# All smart outlets with power metering
for outlet in gd.Outlet():
    print(f"{outlet.name}: {outlet.power}W")

# Available typed getters:
# gd.Switch()          -> list[generic.Switch]
# gd.Outlet()          -> list[generic.ZigbeeOutlet]
# gd.Dimmer()          -> list[lights.Dimmer]
```

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

### ColorTempBulb - Color Temperature Control

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Extends `Dimmer` with color temperature adjustment in degrees Kelvin.

```APIDOC
## ColorTempBulb - Color Temperature Control

### Description
Extends `Dimmer` with color temperature adjustment in degrees Kelvin.

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
bulb = hc.GetSingleDevice(hub).name('Office Bulb')
# type(bulb) -> <class 'hubitatcontrol.lights.ColorTempBulb'>

print(bulb.color_temp)      # 4000 (Kelvin)
bulb.set_color_temp(2700)   # Warm white (waits 2s)
bulb.set_level(80)          # 80% brightness
bulb.turn_on()
```

### Attributes
- **color_temp** (int): The current color temperature in Kelvin.

### Methods
- **set_color_temp(kelvin: int)**: Sets the color temperature in Kelvin.
- **set_level(level: int)**: Sets the brightness level (inherited from Dimmer).
- **turn_on()**: Turns the bulb on (inherited from Switch).
```

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

### Switch - On/Off Control

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Base class for controllable devices. Supports reading switch state and sending on/off commands.

```APIDOC
## Switch - On/Off Control

### Description
Base controllable device class. Supports reading switch state and sending on/off commands.

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
switches = hc.GetDevices(hub).Switch()

for sw in switches:
    print(f"{sw.name} is currently {sw.switch}")  # 'on' or 'off'

# Turn on a specific switch
sw = hc.GetSingleDevice(hub).name('Porch Light')
sw.turn_on()
print(sw.switch)   # 'on'

sw.turn_off()
print(sw.switch)   # 'off'

# Inspect raw device metadata
print(sw.commands)      # List of available commands
print(sw.capabilities)  # List of capability strings
print(sw.history)       # List of recent event dicts
print(sw.attributes)    # List of attribute dicts with currentValue
```

### Attributes
- **name** (str): The name of the switch.
- **switch** (str): The current state of the switch ('on' or 'off').
- **commands** (list): List of available commands for the device.
- **capabilities** (list): List of capability strings for the device.
- **history** (list): List of recent event dictionaries.
- **attributes** (list): List of attribute dictionaries, including `currentValue`.
```

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

### Switch

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/generic.md

Represents a generic switch device. Provides methods to turn the device on or off.

```APIDOC
## Switch

### Description
Represents a generic switch device. Provides methods to turn the device on or off.

### Instance Variables

* `switch` (str): Returns either 'on' or 'off'.

### Methods

#### `turn_off()`
Turns the device off.

#### `turn_on()`
Turns the device on.
```

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

### Clear Stored Credentials with hubitatcontrol CLI

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Use `hubitatcontrol clear-keyring` to remove any Hubitat credentials that have been previously stored in the OS keyring by the `load-env-to-keyring` command.

```bash
# Remove stored credentials from keyring
hubitatcontrol clear-keyring
```

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

### Dimmer - Brightness Level Control

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Extends `Switch` with brightness level control (0-100).

```APIDOC
## Dimmer - Brightness Level Control

### Description
Extends `Switch` with a brightness level (0–100). Inherits `turn_on()` and `turn_off()`.

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')
dimmer = hc.GetSingleDevice(hub).name('Living Room Dimmer')

print(dimmer.level)      # 75

dimmer.set_level(50)     # Set to 50% brightness (waits 2.5s for device to respond)
print(dimmer.level)      # 50

try:
    dimmer.set_level(150)  # Raises Exception: Invalid range
except Exception as e:
    print(e)
```

### Attributes
- **level** (int): The current brightness level (0-100).

### Methods
- **set_level(level: int)**: Sets the brightness level. Raises an exception for invalid ranges.
```

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

### GetSingleDevice.id

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/index.md

Retrieves a single device by its unique ID and casts it to the matched specification.

```APIDOC
## id(device_id: int)

### Description
Get a device by id and cast to the matched spec.

### Parameters
#### Path Parameters
- **device_id** (int) - Required - The unique identifier of the device.
```

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

### ColorTempBulb

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/lights.md

Controls a light bulb with adjustable color temperature.

```APIDOC
## ColorTempBulb

Controls a light bulb with adjustable color temperature.

### Methods

#### set_color_temp(level: int)

Sets the color temperature of the bulb.

- **level** (int) - Degrees Kelvin
```

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

### GenericZWaveLock

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/generic.md

Represents a generic Z-Wave lock device. Provides methods to lock and unlock the device.

```APIDOC
## GenericZWaveLock

### Description
Represents a generic Z-Wave lock device. Provides methods to lock and unlock the device.

### Methods

#### `lock()`
Locks the device.

#### `unlock()`
Unlocks the device.
```

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

### RGBWBulb

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/lights.md

Controls an RGBW light bulb with additional controls for hue, saturation, and color.

```APIDOC
## RGBWBulb

Controls an RGBW light bulb with additional controls for hue, saturation, and color.

### Instance variables

- **color** (str) - Current color of the bulb.
- **color_mode** (str) - The current color mode.
- **color_name** (str) - The current color name.
- **hue** (int) - Current hue value (0-100).
- **saturation** (str) - Current saturation value (0-100).

### Methods

#### set_color(hue: int, saturation: int, level: int)

Sets the color of the bulb using hue, saturation, and level.

- **hue** (int) - The desired hue value.
- **saturation** (int) - The desired saturation value.
- **level** (int) - The desired brightness level.

#### set_hue(hue: int)

Sets the hue of the bulb.

- **hue** (int) - 0-100 valid range

#### set_saturation(saturation: int)

Sets the saturation of the bulb.

- **saturation** (int) - 0-100 valid range
```

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

### Dimmer

Source: https://github.com/jelloeater/hubitatcontrol/blob/main/docs/hubitatcontrol/lights.md

Controls a dimmable light.

```APIDOC
## Dimmer

Controls a dimmable light.

### Instance variables

- **level** (int) - Current brightness level (0-100).

### Methods

#### set_level(level: int)

Sets the brightness level of the dimmer.

- **level** (int) - 0-100 valid range
```

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

### TemperatureSensor - Temperature Reading

Source: https://context7.com/jelloeater/hubitatcontrol/llms.txt

Reads the current temperature from a sensor device.

```APIDOC
## TemperatureSensor - Temperature Reading

### Description
Reads the current temperature from a sensor device.

### Method
```python
import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='TOKEN', app_id='1')

# Single sensor lookup
sensor = hc.GetSingleDevice(hub).id(55)
print(f"Temperature: {sensor.temperature}°F")
# Output: Temperature: 72°F

# All temperature sensors
for s in hc.GetDevices(hub).TemperatureSensor():
    print(f"{s.name}: {s.temperature}°F")
```

### Attributes
- **temperature** (float): The current temperature reading (e.g., in °F).
```

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