pyControl4

https://lawtancool.github.io/pyControl4
Admin
pyControl4 is a Python library that provides programmatic control and monitoring of Control4 smart...
Tokens:61,458
Snippets:602
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Item Setup Information - Python

Source: https://lawtancool.github.io/pyControl4/director.html

Fetches the setup information for a given Control4 item ID. This method uses a POST request to send a 'GET_SETUP' command.

```python
async def get_item_setup(self, item_id: int) -> dict[str, Any]:
    """Returns the setup info of the specified item.

    Parameters:
        `item_id` - The Control4 item ID.
    """
    data = await self.send_post_request(
        f"/api/v1/items/{item_id}/commands", "GET_SETUP", {}, False
    )
    result: dict[str, Any] = json.loads(data)
    return result
```

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

### Get Item Setup Info

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the setup information for a specified Control4 item.

```APIDOC
## GET /api/v1/items/{item_id}/commands

### Description
Returns the setup info of the specified item.

### Method
GET

### Endpoint
/api/v1/items/{item_id}/commands

### Parameters
#### Path Parameters
- **item_id** (int) - Required - The Control4 item ID.

### Response
#### Success Response (200)
- **data** (dict[str, Any]) - The setup information for the item.
```

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

### Get Item Setup Information

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the setup details for a specific Control4 item using its item ID. This method is intended for fetching configuration data related to an item.

```python
    async def get_item_setup(self, item_id: int) -> dict[str, Any]:
```

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

### get_item_setup

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the setup information for a specified Control4 item.

```APIDOC
## POST /api/v1/items/{item_id}/commands

### Description
Returns the setup info of the specified item.

### Method
POST

### Endpoint
/api/v1/items/{item_id}/commands

### Parameters
#### Path Parameters
- **item_id** (int) - Required - The Control4 item ID.
#### Request Body
- **command** (str) - Required - The command to execute, should be "GET_SETUP".
- **parameters** (dict) - Optional - Empty dictionary.
- **send_to_director** (bool) - Optional - False.

### Response
#### Success Response (200)
- **dict[str, typing.Any]** - A dictionary containing the setup information.
```

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

### set_play

Source: https://lawtancool.github.io/pyControl4/room.html

Starts or resumes playback in the room.

```APIDOC
## set_play

### Description
Starts or resumes playback in the room.

### Method
POST

### Endpoint
/api/v1/items/{item_id}/commands

### Parameters
#### Request Body
- **command** (string) - Required - "PLAY"
- **data** (object) - Required - {}

### Response
#### Success Response (200)
(No specific response fields documented)
```

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

### get_audio_devices

Source: https://lawtancool.github.io/pyControl4/room.html

Get the audio devices located in the room.

```APIDOC
## GET /api/v1/locations/rooms/{room_id}/audio_devices

### Description
Retrieves a list of audio devices associated with a specific room.

### Method
GET

### Endpoint
/api/v1/locations/rooms/{room_id}/audio_devices

### Parameters
#### Path Parameters
- **room_id** (string) - Required - The ID of the room to retrieve audio devices from.
```

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

### Create Control4 Object

Source: https://lawtancool.github.io/pyControl4/blind.html

Instantiates a Control4 object. This is a basic setup step for interacting with the Control4 system.

```python
Creates a Control4 object.
```

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

### Get UI Configuration

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the Control4 App UI Configuration, enumerating rooms and capabilities.

```APIDOC
## GET /api/v1/ui-configuration

### Description
Returns a dictionary of the Control4 App UI Configuration enumerating rooms and capabilities.

### Method
GET

### Endpoint
/api/v1/ui-configuration

### Response
#### Success Response (200)
- **experiences** (list[dict[str, Any]]) - A list of experiences, each containing sources.
```

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

### Get Account Controllers

Source: https://lawtancool.github.io/pyControl4/account.html

Retrieves a dictionary of all controllers registered to an account. Use this to get controller details like 'controllerCommonName' and 'href'.

```python
async def get_account_controllers(self) -> dict[str, Any]:
        """Returns a dictionary of the information for all controllers registered
        to an account.

        Returns:
            ```
            {
                "controllerCommonName": "control4_MODEL_MACADDRESS",
                "href": "https://apis.control4.com/account/v3/rest/accounts/000000",
                "name": "Name"
            }
            ```
        """
        data = await self._send_account_get_request(GET_CONTROLLERS_ENDPOINT)
        json_dict = json.loads(data)
        try:
            result: dict[str, Any] = json_dict["account"]
            return result
        except KeyError:
            msg = "Did not receive account information from the Control4 API."
            _LOGGER.error(msg + " Response: " + data)
            raise
```

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

### Get All Item Info - Python

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves a list of all items present on the Control4 Director. This is useful for an overview of all connected devices.

```python
async def get_all_item_info(self) -> list[dict[str, Any]]:
    """Returns a list of all the items on the Director."""
    data = await self.send_get_request("/api/v1/items")
    result: list[dict[str, Any]] = json.loads(data)
    return result
```

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

### get_video_devices

Source: https://lawtancool.github.io/pyControl4/room.html

Get the video devices located in the room. Note that this is literally the devices in the room, not necessarily all devices _playable_ in the room. See `pyControl4.director.C4Director.get_ui_configuration` for a more accurate list.

```APIDOC
## GET /api/v1/locations/rooms/{room_id}/video_devices

### Description
Retrieves a list of video devices associated with a specific room. This may not include all playable devices.

### Method
GET

### Endpoint
/api/v1/locations/rooms/{room_id}/video_devices

### Parameters
#### Path Parameters
- **room_id** (string) - Required - The ID of the room to retrieve video devices from.
```

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

### Get Controller OS Version

Source: https://lawtancool.github.io/pyControl4/account.html

Retrieves the OS version of a specific controller.

```APIDOC
## GET /accounts/{accountId}/controllers/{controllerId}/osVersion

### Description
Returns the OS version of a controller as a string.

### Method
GET

### Endpoint
/accounts/{accountId}/controllers/{controllerId}/osVersion

### Parameters
#### Path Parameters
- **controller_href** (str) - Required - The API `href` of the controller (get this from the output of `get_account_controllers()`)

### Response
#### Success Response (200)
- **osVersion** (str) - The OS version of the controller.

#### Response Example
```json
{
    "osVersion": "5.10.4"
}
```
```

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

### Get Supported HVAC Modes

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves a list of all supported HVAC modes for the device.

```APIDOC
## get_hvac_modes

### Description
Returns a list of supported HVAC modes.

### Method
async def get_hvac_modes(self) -> list[str] | None:
    """Returns a list of supported HVAC modes."""
    value = await self.director.get_item_variable_value(
        self.item_id, "HVAC_MODES_LIST"
    )
    if value is None:
        return None
    return [m.strip() for m in value.split(",") if m.strip()]
```

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

### Get Controller Info

Source: https://lawtancool.github.io/pyControl4/account.html

Retrieves detailed information about a specific controller using its href.

```APIDOC
## GET /accounts/{accountId}/controllers/{controllerId}

### Description
Returns a dictionary of the information of a specific controller.

### Method
GET

### Endpoint
/accounts/{accountId}/controllers/{controllerId}

### Parameters
#### Path Parameters
- **controller_href** (str) - Required - The API `href` of the controller (get this from the output of `get_account_controllers()`)

### Response
#### Success Response (200)
- **allowsPatching** (bool) - Indicates if patching is allowed.
- **allowsSupport** (bool) - Indicates if support is allowed.
- **blockNotifications** (bool) - Indicates if notifications are blocked.
- **controllerCommonName** (str) - The common name of the controller.
- **created** (str) - The creation date of the controller.
- **dealer** (dict) - Information about the dealer.
- **enabled** (bool) - Indicates if the controller is enabled.
- **hasLoggedIn** (bool) - Indicates if the controller has logged in.
- **href** (str) - The API href of the controller.
- **id** (int) - The ID of the controller.
- **lastCheckIn** (str) - The last check-in time of the controller.
- **licenses** (dict) - Information about the controller's licenses.
- **modified** (str) - The last modified date of the controller.
- **name** (str) - The name of the controller.
- **provisionDate** (str) - The provision date of the controller.
- **storage** (dict) - Information about the controller's storage.
- **type** (str) - The type of the controller.
- **users** (dict) - Information about the controller's users.

#### Response Example
```json
{
    "allowsPatching": True,
    "allowsSupport": False,
    "blockNotifications": False,
    "controllerCommonName": "control4_MODEL_MACADDRESS",
    "controller": {
        "href": "https://apis.control4.com/account/v3/rest/accounts/000000/controller"
    },
    "created": "2017-08-26T18:33:31Z",
    "dealer": {
        "href": "https://apis.control4.com/account/v3/rest/dealers/12345"
    },
    "enabled": True,
    "hasLoggedIn": True,
    "href": "https://apis.control4.com/account/v3/rest/accounts/000000",
    "id": 000000,
    "lastCheckIn": "2020-06-13T21:52:34Z",
    "licenses": {
        "href": "https://apis.control4.com/account/v3/rest/accounts/000000/licenses"
    },
    "modified": "2020-06-13T21:52:34Z",
    "name": "Name",
    "provisionDate": "2017-08-26T18:35:11Z",
    "storage": {
        "href": "https://apis.control4.com/storage/v1/rest/accounts/000000"
    },
    "type": "Consumer",
    "users": {
        "href": "https://apis.control4.com/account/v3/rest/accounts/000000/users"
    }
}
```
```

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

### Get Controller OS Version

Source: https://lawtancool.github.io/pyControl4/account.html

Retrieves the operating system version of a specific controller. Requires the controller's href.

```python
async def get_controller_os_version(self, controller_href: str) -> str:
        """Returns the OS version of a controller as a string.

        Parameters:
            `controller_href` - The API `href` of the controller (get this from
                the output of `get_account_controllers()`)
        """
        data = await self._send_account_get_request(controller_href + "/controller")
        json_dict = json.loads(data)
        try:
            version: str = json_dict["osVersion"]
            return version
        except KeyError:
            msg = "Did not receive OS version from the Control4 API."
            _LOGGER.error(msg + " Response: " + data)
            raise
```

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

### Get Security Panel Display Text

Source: https://lawtancool.github.io/pyControl4/alarm.html

Retrieves the display text of the security panel. Returns `None` if the text cannot be determined.

```python
async def get_display_text(self) -> str | None:
    """Returns the display text of the security panel."""
    display_text = await self.director.get_item_variable_value(
        self.item_id, "DISPLAY_TEXT"
    )
    return display_text
```

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

### Get Supported Hold Modes

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves a list of all supported hold modes for the device.

```APIDOC
## get_hold_modes

### Description
Returns a list of supported hold modes.

### Method
async def get_hold_modes(self) -> list[str] | None:
    """Returns a list of supported hold modes."""
    value = await self.director.get_item_variable_value(
        self.item_id, "HOLD_MODES_LIST"
    )
    if value is None:
        return None
    return [m.strip() for m in value.split(",") if m.strip()]
```

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

### Account Controller Information

Source: https://lawtancool.github.io/pyControl4/account.html

Example of the JSON response structure when retrieving account controller details. This includes properties like 'allowsPatching', 'controllerCommonName', and 'created' timestamp.

```json
{
    'allowsPatching': True,
    'allowsSupport': False,
    'blockNotifications': False,
    'controllerCommonName': 'control4_MODEL_MACADDRESS',
    'controller': {
        'href': 'https://apis.control4.com/account/v3/rest/accounts/000000/controller'  # noqa: E501
    },
    'created': '2017-08-26T18:33:31Z',
    'dealer': {
        'href': 'https://apis.control4.com/account/v3/rest/dealers/12345'
    },
    'enabled': True,
    'hasLoggedIn': True,
    'href': 'https://apis.control4.com/account/v3/rest/accounts/000000',
    'id': 000000,
    'lastCheckIn': '2020-06-13T21:52:34Z',
    'licenses': {
        'href': 'https://apis.control4.com/account/v3/rest/accounts/000000/licenses'  # noqa: E501
    },
    'modified': '2020-06-13T21:52:34Z',
    'name': 'Name',
    'provisionDate': '2017-08-26T18:35:11Z',
    'storage': {
        'href': 'https://apis.control4.com/storage/v1/rest/accounts/000000'
    },
    'type': 'Consumer',
    'users': {
        'href': 'https://apis.control4.com/account/v3/rest/accounts/000000/users'  # noqa: E501
    }
}
```

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

### Get Account Controllers

Source: https://lawtancool.github.io/pyControl4/account.html

Retrieves a dictionary of information for all controllers registered to an account.

```APIDOC
## GET /accounts/{accountId}/controllers

### Description
Returns a dictionary of the information for all controllers registered to an account.

### Method
GET

### Endpoint
/accounts/{accountId}/controllers

### Response
#### Success Response (200)
- **controllerCommonName** (str) - The common name of the controller.
- **href** (str) - The API href of the controller.
- **name** (str) - The name of the controller.

#### Response Example
```json
{
    "controllerCommonName": "control4_MODEL_MACADDRESS",
    "href": "https://apis.control4.com/account/v3/rest/accounts/000000",
    "name": "Name"
}
```
```

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

### Get UI Configuration

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the UI configuration for the Control4 Director. This includes details about available devices, rooms, and media sources.

```APIDOC
## GET /api/v1/agents/ui_configuration

### Description
Retrieves the UI configuration for the Control4 Director, providing details about available devices, rooms, and media sources.

### Method
GET

### Endpoint
/api/v1/agents/ui_configuration

### Response
#### Success Response (200)
- **data** (dict) - A dictionary containing the UI configuration details.

### Response Example
```json
{
    "agents": [
        {
            "type": "listen",
            "sources": {
                "source": [
                    {
                        "id": 298,
                        "type": "DIGITAL_AUDIO_SERVER",
                        "name": "My Music"
                    },
                    {
                        "id": 302,
                        "type": "AUDIO_SELECTION",
                        "name": "Stations"
                    },
                    {
                        "id": 306,
                        "type": "DIGITAL_AUDIO_SERVER",
                        "name": "ShairBridge"
                    },
                    {
                        "id": 937,
                        "type": "DIGITAL_AUDIO_SERVER",
                        "name": "Spotify Connect"
                    },
                    {
                        "id": 100002,
                        "type": "DIGITAL_AUDIO_CLIENT",
                        "name": "Digital Media"
                    }
                ]
            },
            "active": false,
            "room_id": 9,
            "username": "primaryuser"
        },
        {
            "type": "cameras",
            "sources": {
                "source": [
                    {
                        "id": 877,
                        "type": "Camera"
                    },
                    ...
                ]
            }
        }
        ...
    ]
}
```
```

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

### Get Available Arm Types

Source: https://lawtancool.github.io/pyControl4/alarm.html

Retrieves a comma-separated string of supported arming types from the panel's capabilities and returns them as a list.

```python
async def get_arm_types(self) -> list[str]:
        """Returns the available arm types as a list."""
        data = await self.director.get_item_info(self.item_id)
        if not data or not isinstance(data, list) or len(data) == 0:
            return []

        capabilities = data[0].get("capabilities", {})
        arm_types_str = capabilities.get("arm_types", "")
        if not arm_types_str:
            return []
        return [t.strip() for t in arm_types_str.split(",") if t.strip()]
```

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

### Get Item Commands - Python

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves a list of all available commands for a given Control4 item, specified by its item ID. This helps in understanding what actions can be performed on the item.

```python
async def get_item_commands(self, item_id: int) -> list[dict[str, Any]]:
    """Returns the commands available for the specified item.

    Parameters:
        `item_id` - The Control4 item ID.
    """
    data = await self.send_get_request(f"/api/v1/items/{item_id}/commands")
    result: list[dict[str, Any]] = json.loads(data)
    return result
```

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

### Get Room Volume - Python

Source: https://lawtancool.github.io/pyControl4/room.html

Retrieves the current volume level for the room, ranging from 0 to 100. Returns None if the volume cannot be determined.

```python
async def get_volume(self) -> int | None:
    """Returns the current volume for the room from 0-100"""
    value = await self.director.get_item_variable_value(
        self.item_id, "CURRENT_VOLUME"
    )
    if value is None:
        return None
    return int(value)
```

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

### Initialize and Connect AsyncClient

Source: https://lawtancool.github.io/pyControl4/websocket.html

Initializes the AsyncClient with optional SSL verification and an HTTP session. Connects to the specified WSS URL with JWT authentication and WebSocket transport.

```python
http_session = aiohttp.ClientSession(
                connector=self.session.connector, connector_owner=False
            )
            self._sio = socketio.AsyncClient(ssl_verify=True, http_session=http_session)
        else:
            self._sio = socketio.AsyncClient(ssl_verify=False)
        self._sio.register_namespace(
            _C4DirectorNamespace(
                token=director_bearer_token,
                url=self.base_url,
                callback=self._callback,
                session=self.session,
                connect_callback=self.connect_callback,
                disconnect_callback=self.disconnect_callback,
            )
        )
        await self._sio.connect(
            self.wss_url,
            transports=["websocket"],
            headers={"JWT": director_bearer_token},
        )
```

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

### Send Account GET Request

Source: https://lawtancool.github.io/pyControl4/account.html

Internal method to send authenticated GET requests to the Control4 API using the account bearer token.

```python
async def _send_account_get_request(self, uri: str) -> str:
    """Used internally to send GET requests to the Control4 API,
    authenticated with the account bearer token. Returns the entire JSON
    response from the Control4 auth API.

    Parameters:
        `uri` - Full URI to send GET request to.
    """
    try:
        headers = {"Authorization": f"Bearer {self.account_bearer_token}"}
    except AttributeError:
        msg = (
            "The account bearer token is missing. "
            "Is your username/password correct?"
        )
        _LOGGER.error(msg)
        raise
    async with self._get_session() as session:
        async with asyncio.timeout(10):
            async with session.get(uri, headers=headers) as resp:
                text = await resp.text()
                check_response_for_error(text)
                return text
```

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

### Get Cooling Setpoint (Fahrenheit)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the cooling setpoint temperature in Fahrenheit. The value is converted to a float.

```python
async def get_cool_setpoint_f(self) -> float | None:
    """Returns the cooling setpoint temperature in Fahrenheit."""
    value = await self.director.get_item_variable_value(
        self.item_id, "COOL_SETPOINT_F"
    )
    if value is None:
        return None
    return float(value)
```

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

### Initialize C4Account

Source: https://lawtancool.github.io/pyControl4/account.html

Creates a Control4 account object with username, password, and an optional aiohttp.ClientSession.

```python
class C4Account:
    def __init__(
        self,
        username: str,
        password: str,
        session: aioiohttp.ClientSession | None = None,
    ):
        """Creates a Control4 account object.

        Parameters:
            `username` - Control4 account username/email.

            `password` - Control4 account password.

            `session` - (Optional) Allows the use of an `aiohttp.ClientSession`
                object for all network requests. This session will not be closed
                by the library. If not provided, the library will open and close
                its own `ClientSession`s as needed.
        """
        self.username = username
        self.password = password
        self.session = session
```

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

### Get All Item Information

Source: https://lawtancool.github.io/pyControl4/director.html

Fetches a comprehensive list of all items present on the Control4 Director. This method performs a GET request to the '/api/v1/items' endpoint and parses the JSON response.

```python
    async def get_all_item_info(self) -> list[dict[str, Any]]:
        """Returns a list of all the items on the Director."""
        data = await self.send_get_request("/api/v1/items")
        result: list[dict[str, Any]] = json.loads(data)
        return result
```

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

### Get Specific Item Information

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves detailed information for a single Control4 item, identified by its unique item ID. The method sends a GET request to the '/api/v1/items/{item_id}' endpoint and returns the parsed JSON response.

```python
    async def get_item_info(self, item_id: int) -> list[dict[str, Any]]:
        """Returns a list of the details of the specified item.

        Parameters:
            `item_id` - The Control4 item ID.
        """
        data = await self.send_get_request(f"/api/v1/items/{item_id}")
        result: list[dict[str, Any]] = json.loads(data)
        return result
```

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

### Set Video and Audio Source

Source: https://lawtancool.github.io/pyControl4/room.html

Sets the current audio and video source for the room using the provided source ID.

```python
async def set_video_and_audio_source(self, source_id: int) -> None:
    """Sets the current audio and video source for the room"""
    await self._set_source(source_id, audio_only=False)
```

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

### Get Supported HVAC Modes

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves a list of supported HVAC modes. The modes are returned as a comma-separated string and parsed into a list.

```python
async def get_hvac_modes(self) -> list[str] | None:
    """Returns a list of supported HVAC modes."""
    value = await self.director.get_item_variable_value(
        self.item_id, "HVAC_MODES_LIST"
    )
    if value is None:
        return None
    return [m.strip() for m in value.split(",") if m.strip()]
```

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

### Send GET Request to Control4 API

Source: https://lawtancool.github.io/pyControl4/director.html

Sends a GET request to a specified Control4 API URI. It handles session management, timeouts, and basic error checking for the response. The URI should not include the Director's IP address.

```python
async def send_get_request(self, uri: str) -> str:
    """Sends a GET request to the specified API URI.
    Returns the Director's JSON response as a string.

    Parameters:
        `uri` - The API URI to send the request to. Do not include the IP
                address of the Director.
    """
    async with self._get_session() as session:
        async with asyncio.timeout(10):
            async with session.get(
                self.base_url + uri, headers=self.headers
            ) as resp:
                text = await resp.text()
                check_response_for_error(text)
                return text
```

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

### Send GET Request to Director API

Source: https://lawtancool.github.io/pyControl4/director.html

Sends a GET request to a specified API URI on the Control4 Director. It handles session management and response parsing, returning the Director's JSON response as a string. Includes a 10-second timeout.

```python
    async def send_get_request(self, uri: str) -> str:
        """Sends a GET request to the specified API URI.
        Returns the Director's JSON response as a string.

        Parameters:
            `uri` - The API URI to send the request to. Do not include the IP
                    address of the Director.
        """
        async with self._get_session() as session:
            async with asyncio.timeout(10):
                async with session.get(
                    self.base_url + uri, headers=self.headers
                ) as resp:
                    text = await resp.text()
                    check_response_for_error(text)
                    return text
```

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

### Open Blind - Python

Source: https://lawtancool.github.io/pyControl4/blind.html

Command to fully open the blind. Ensure the blind is initialized and accessible before calling this method.

```python
async def open(self) -> None:
    """Opens the blind completely."""
    await self.director.send_post_request(
        f"/api/v1/items/{self.item_id}/commands",
        "SET_LEVEL_TARGET:LEVEL_TARGET_OPEN",
        {},
    )
```

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

### set_video_and_audio_source

Source: https://lawtancool.github.io/pyControl4/room.html

Sets the current audio and video source for the room.

```APIDOC
## set_video_and_audio_source

### Description
Sets the current audio and video source for the room.

### Method
POST

### Endpoint
/api/v1/items/{item_id}/commands

### Parameters
#### Request Body
- **command** (string) - Required - "SELECT_VIDEO_DEVICE"
- **data** (object) - Required - {
  "deviceid": (int) - Required - The ID of the video/audio device to select.
}

### Response
#### Success Response (200)
(No specific response fields documented)
```

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

### get_ui_configuration

Source: https://lawtancool.github.io/pyControl4/director.html

Returns a dictionary of the Control4 App UI Configuration enumerating rooms and capabilities.

```APIDOC
## get_ui_configuration

### Description
Returns a dictionary of the Control4 App UI Configuration enumerating rooms and capabilities.

### Method
GET

### Endpoint
/api/v1/agents/ui_configuration

### Response
#### Success Response (200)
- **experiences** (list) - A list of UI experiences available in the Control4 system.
  - **type** (string) - The type of experience (e.g., "watch", "listen", "cameras").
  - **sources** (dict) - Contains information about available sources for the experience.
    - **source** (list) - A list of source objects.
      - **id** (integer) - The unique identifier for the source.
      - **type** (string) - The type of the source (e.g., "HDMI", "DIGITAL_AUDIO_SERVER").
      - **name** (string, optional) - The name of the source.
  - **active** (boolean) - Indicates if the experience is currently active.
  - **room_id** (integer) - The ID of the room associated with the experience.
  - **username** (string) - The username associated with the experience.
```

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

### Get Humidity

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the current ambient humidity percentage.

```APIDOC
## get_humidity

### Description
Returns the current humidity percentage.

### Method
async def get_humidity(self) -> float | None:
    """Returns the current humidity percentage."""
    value = await self.director.get_item_variable_value(self.item_id, "HUMIDITY")
    if value is None:
        return None
    return float(value)
```

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

### Set Audio Source - Python

Source: https://lawtancool.github.io/pyControl4/room.html

Sets the current audio source for the room using the provided source ID.

```python
async def set_audio_source(self, source_id: int) -> None:
    """Sets the current audio source for the room"""
    await self._set_source(source_id, audio_only=True)
```

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

### Get Hold Mode

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the currently active hold mode.

```APIDOC
## get_hold_mode

### Description
Returns the currently active hold mode.

### Method
async def get_hold_mode(self) -> str | None:
    """Returns the currently active hold mode."""
    return await self.director.get_item_variable_value(self.item_id, "HOLD_MODE")
```

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

### Get Fan Mode

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the currently active fan mode.

```APIDOC
## get_fan_mode

### Description
Returns the currently active fan mode.

### Method
async def get_fan_mode(self) -> str | None:
    """Returns the currently active fan mode."""
    return await self.director.get_item_variable_value(self.item_id, "FAN_MODE")
```

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

### Manage Session

Source: https://lawtancool.github.io/pyControl4/account.html

Returns the configured session or creates and closes a temporary one if none is provided.

```python
@asynccontextmanager
async def _get_session(self) -> AsyncGenerator[aiohttp.ClientSession, None]:
    """Returns the configured session or creates a temporary one.

    If self.session is set, yields it without closing.
    Otherwise, creates and closes a temporary session.
    """
    if self.session is not None:
        yield self.session
    else:
        async with aiohttp.ClientSession() as session:
            yield session
```

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

### Get HVAC Mode

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the currently active HVAC mode.

```APIDOC
## get_hvac_mode

### Description
Returns the currently active HVAC mode.

### Method
async def get_hvac_mode(self) -> str | None:
    """Returns the currently active HVAC mode."""
    return await self.director.get_item_variable_value(self.item_id, "HVAC_MODE")
```

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

### Initialize C4Director

Source: https://lawtancool.github.io/pyControl4/director.html

Creates a Control4 Director object. Requires the Director's IP address and a bearer token for authentication. Optionally accepts an aiohttp.ClientSession for network requests.

```python
class C4Director:
    def __init__(
        self,
        ip: str,
        director_bearer_token: str,
        session_no_verify_ssl: aiohttp.ClientSession | None = None,
    ):
        """Creates a Control4 Director object.

        Parameters:
            `ip` - The IP address of the Control4 Director/Controller.

            `director_bearer_token` - The bearer token used to authenticate
                                      with the Director.
                See `pyControl4.account.C4Account.get_director_bearer_token`
                for how to get this.

            `session` - (Optional) Allows the use of an
                        `aiohttp.ClientSession` object
                        for all network requests. This
                        session will not be closed by the library.
                        If not provided, the library will open and
                        close its own `ClientSession`s as needed.
        """
        self.base_url = f"https://{ip}"
        self.headers = {"Authorization": f"Bearer {director_bearer_token}"}
        self.director_bearer_token = director_bearer_token
        self.session = session_no_verify_ssl
```

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

### Initialize C4Entity Object

Source: https://lawtancool.github.io/pyControl4/index.html

Creates a Control4 object by initializing with a C4Director and the item ID. This is the base class for various Control4 device types.

```python
class C4Entity:
    def __init__(self, director: C4Director, item_id: int):
        """Creates a Control4 object.

        Parameters:
            `director` - A `pyControl4.director.C4Director` object that corresponds
                to the Control4 Director that the device is connected to.

            `item_id` - The Control4 item ID.
        """
        self.director = director
        self.item_id = int(item_id)
```

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

### Get Fan State

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the current power state of the fan (on or off).

```APIDOC
## get_fan_state

### Description
Returns the current power state of the fan (on, off).

### Method
async def get_fan_state(self) -> str | None:
    """Returns the current power state of the fan (on, off)."""
    return await self.director.get_item_variable_value(self.item_id, "FAN_STATE")
```

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

### Get Hold Mode

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the currently active hold mode.

```python
async def get_hold_mode(self) -> str | None:
    """Returns the currently active hold mode."""
    return await self.director.get_item_variable_value(self.item_id, "HOLD_MODE")
```

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

### get_video_devices

Source: https://lawtancool.github.io/pyControl4/room.html

Get the video devices located in the room. Note that this is literally the devices in the room, not necessarily all devices _playable_ in the room. This method may not work in OS 3.2.3 but might work in previous versions.

```APIDOC
## get_video_devices

### Description
Get the video devices located in the room. Note that this is literally the devices in the room, not necessarily all devices _playable_ in the room. See `C4Director.get_ui_configuration()` for a more accurate list. This method may not work in OS 3.2.3 but might work in previous versions.

### Method
GET

### Endpoint
/api/v1/locations/rooms/{self.item_id}/video_devices

### Response
#### Success Response (200)
- **devices** (dict[str, typing.Any]) - A dictionary containing video devices.
```

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

### Get Fan Mode

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the currently active fan mode.

```python
async def get_fan_mode(self) -> str | None:
    """Returns the currently active fan mode."""
    return await self.director.get_item_variable_value(self.item_id, "FAN_MODE")
```

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

### Get HVAC Mode

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the currently active HVAC mode.

```python
async def get_hvac_mode(self) -> str | None:
    """Returns the currently active HVAC mode."""
    return await self.director.get_item_variable_value(self.item_id, "HVAC_MODE")
```

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

### Set Play

Source: https://lawtancool.github.io/pyControl4/room.html

Resumes media playback in the room. This method sends a PLAY command to the room.

```python
async def set_play(self) -> None:
    await self.director.send_post_request(
        f"/api/v1/items/{self.item_id}/commands",
        "PLAY",
        {},
    )
```

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

### Get Fan State

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the current power state of the fan (on, off).

```python
async def get_fan_state(self) -> str | None:
    """Returns the current power state of the fan (on, off)."""
    return await self.director.get_item_variable_value(self.item_id, "FAN_STATE")
```

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

### Get Item Bindings

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the bindings information for a specified Control4 item.

```APIDOC
## GET /api/v1/items/{item_id}/bindings

### Description
Returns the bindings information for the specified item.

### Method
GET

### Endpoint
/api/v1/items/{item_id}/bindings

### Parameters
#### Path Parameters
- **item_id** (int) - Required - The Control4 item ID.

### Response
#### Success Response (200)
- **result** (list[dict[str, Any]]) - A list of dictionaries containing binding information.
```

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

### Set Light Color Temperature - Python

Source: https://lawtancool.github.io/pyControl4/light.html

Use this function to set the color temperature of a light. The `rate` parameter controls the transition speed.

```python
async def set_color_temperature(
    self, kelvin: int, *, rate: int | None = None
) -> None:
    params = {
        "LIGHT_COLOR_TARGET_COLOR_CORRELATED_TEMPERATURE": int(kelvin),
        "LIGHT_COLOR_TARGET_MODE": 1,
    }
    if rate is not None:
        params["RATE"] = int(rate)

    await self.director.send_post_request(
        f"/api/v1/items/{self.item_id}/commands",
        "SET_COLOR_TARGET",
        params,
    )
```

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

### Get Item Commands

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the commands available for a specified Control4 item.

```APIDOC
## GET /api/v1/items/{item_id}/commands

### Description
Returns the commands available for the specified item.

### Method
GET

### Endpoint
/api/v1/items/{item_id}/commands

### Parameters
#### Path Parameters
- **item_id** (int) - Required - The Control4 item ID.

### Response
#### Success Response (200)
- **result** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents a command.
```

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

### sio_connect

Source: https://lawtancool.github.io/pyControl4/websocket.html

Starts the WebSocket connection and listens for messages, using a provided bearer token for authentication. It handles existing connections by disconnecting them before establishing a new one. This method should be called periodically with a fresh token to maintain the connection.

```APIDOC
## sio_connect

### Description
Start WebSockets connection and listen, using the provided director_bearer_token to authenticate with the Control4 Director. If a connection already exists, it will be disconnected and a new connection will be created.

This function should be called using a new token every 86400 seconds (the expiry time of the director tokens), otherwise the Control4 Director will stop sending WebSocket messages.

### Parameters
- `director_bearer_token` (str) - The bearer token used to authenticate with the Director. See `pyControl4.account.C4Account.get_director_bearer_token` for how to get this.
```

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

### Get Current Temperature (Celsius)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the current ambient temperature in Celsius.

```APIDOC
## get_current_temperature_c

### Description
Returns the current ambient temperature in Celsius.

### Method
async def get_current_temperature_c(self) -> float | None:
    """Returns the current ambient temperature in Celsius."""
    value = await self.director.get_item_variable_value(
        self.item_id, "TEMPERATURE_C"
    )
    if value is None:
        return None
    return float(value)
```

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

### Get Current Temperature (Fahrenheit)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the current ambient temperature in Fahrenheit.

```APIDOC
## get_current_temperature_f

### Description
Returns the current ambient temperature in Fahrenheit.

### Method
async def get_current_temperature_f(self) -> float | None:
    """Returns the current ambient temperature in Fahrenheit."""
    value = await self.director.get_item_variable_value(
        self.item_id, "TEMPERATURE_F"
    )
    if value is None:
        return None
    return float(value)
```

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

### C4Director Initialization

Source: https://lawtancool.github.io/pyControl4/director.html

Initializes the C4Director object with the Director's IP address and bearer token for authentication. An optional aiohttp.ClientSession can be provided.

```APIDOC
## class C4Director(ip: str, director_bearer_token: str, session_no_verify_ssl: aiohttp.ClientSession | None = None)

### Description
Creates a Control4 Director object.

### Parameters
- **ip** (str) - The IP address of the Control4 Director/Controller.
- **director_bearer_token** (str) - The bearer token used to authenticate with the Director.
- **session_no_verify_ssl** (aiohttp.ClientSession | None, optional) - Allows the use of an aiohttp.ClientSession object for all network requests. If not provided, the library will open and close its own ClientSessions as needed.
```

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

### Get Video Devices in Room - Python

Source: https://lawtancool.github.io/pyControl4/room.html

Retrieves video devices physically located in the room. Note: This method may not function correctly in OS 3.2.3 and later. It lists devices present, not necessarily all playable devices.

```python
async def get_video_devices(self) -> dict[str, Any]:
    """
    Note: As tested in OS 3.2.3 this doesn't work, but may work in previous versions

    Get the video devices located in the room.
    Note that this is literally the devices in the room,
    not necessarily all devices _playable_ in the room.
    See `pyControl4.director.C4Director.get_ui_configuration`
    for a more accurate list
    """
    data = await self.director.send_get_request(
        f"/api/v1/locations/rooms/{self.item_id}/video_devices"
    )
    result: dict[str, Any] = json.loads(data)
    return result
```

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

### Get Heating Setpoint (Celsius)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the heating setpoint temperature in Celsius.

```APIDOC
## get_heat_setpoint_c

### Description
Returns the heating setpoint temperature in Celsius.

### Method
async def get_heat_setpoint_c(self) -> float | None:
    """Returns the heating setpoint temperature in Celsius."""
    value = await self.director.get_item_variable_value(
        self.item_id, "HEAT_SETPOINT_C"
    )
    if value is None:
        return None
    return float(value)
```

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

### is_on

Source: https://lawtancool.github.io/pyControl4/room.html

Checks if the room is currently powered on.

```APIDOC
## is_on

### Description
Returns True/False if the room is "ON" from the director's perspective.

### Method
GET (Implicit)

### Endpoint
(Internal method, not a direct HTTP endpoint)

### Response
#### Success Response
- **bool | None**: True if the room is on, False otherwise, or None if the state cannot be determined.
```

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

### Get Heating Setpoint (Fahrenheit)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the heating setpoint temperature in Fahrenheit.

```APIDOC
## get_heat_setpoint_f

### Description
Returns the heating setpoint temperature in Fahrenheit.

### Method
async def get_heat_setpoint_f(self) -> float | None:
    """Returns the heating setpoint temperature in Fahrenheit."""
    value = await self.director.get_item_variable_value(
        self.item_id, "HEAT_SETPOINT_F"
    )
    if value is None:
        return None
    return float(value)
```

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

### open

Source: https://lawtancool.github.io/pyControl4/blind.html

Opens the blind completely.

```APIDOC
async def open(self) -> None:
    """Opens the blind completely."""
    await self.director.send_post_request(
        f"/api/v1/items/{self.item_id}/commands",
        "SET_LEVEL_TARGET:LEVEL_TARGET_OPEN",
        {{}},
    )
```

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

### Get Cooling Setpoint (Celsius)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the cooling setpoint temperature in Celsius.

```APIDOC
## get_cool_setpoint_c

### Description
Returns the cooling setpoint temperature in Celsius.

### Method
async def get_cool_setpoint_c(self) -> float | None:
    """Returns the cooling setpoint temperature in Celsius."""
    value = await self.director.get_item_variable_value(
        self.item_id, "COOL_SETPOINT_C"
    )
    if value is None:
        return None
    return float(value)
```

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

### Get Cooling Setpoint (Fahrenheit)

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the cooling setpoint temperature in Fahrenheit.

```APIDOC
## get_cool_setpoint_f

### Description
Returns the cooling setpoint temperature in Fahrenheit.

### Method
async def get_cool_setpoint_f(self) -> float | None:
    """Returns the cooling setpoint temperature in Fahrenheit."""
    value = await self.director.get_item_variable_value(
        self.item_id, "COOL_SETPOINT_F"
    )
    if value is None:
        return None
    return float(value)
```

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

### Set Light Color Temperature

Source: https://lawtancool.github.io/pyControl4/light.html

Sets the color temperature of a light in Kelvin. Optionally specify a transition rate.

```python
async def set_color_temperature(self, kelvin: int, *, rate: int | None = None) -> None:
    params = {
        "LIGHT_COLOR_TARGET_COLOR_CORRELATED_TEMPERATURE": int(kelvin),
        "LIGHT_COLOR_TARGET_MODE": 1,
    }
    if rate is not None:
        params["RATE"] = int(rate)

    await self.director.send_post_request(
        f"/api/v1/items/{self.item_id}/commands",
        "SET_COLOR_TARGET",
        params,
    )
```

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

### Get Humidity

Source: https://lawtancool.github.io/pyControl4/climate.html

Retrieves the current humidity percentage. The value is converted to a float.

```python
async def get_humidity(self) -> float | None:
    """Returns the current humidity percentage."""
    value = await self.director.get_item_variable_value(self.item_id, "HUMIDITY")
    if value is None:
        return None
    return float(value)
```

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

### get_opening

Source: https://lawtancool.github.io/pyControl4/blind.html

Returns an indication of whether the blind is moving in the open direction.

```APIDOC
## get_opening

### Description
Returns an indication of whether the blind is moving in the open direction as a boolean (True=opening, False=closing). If the blind is stopped, reports the direction it last moved.

### Method
Asynchronous function call

### Parameters
None

### Request Example
```python
is_opening = await blind.get_opening()
```

### Response
#### Success Response
- **is_opening** (bool | None) - True if the blind is opening, False if closing, or None if unavailable.
```

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

### Set Cooling Setpoint (Fahrenheit)

Source: https://lawtancool.github.io/pyControl4/climate.html

Sets the desired cooling temperature in Fahrenheit. Uses the Control4 director to send a POST request.

```python
async def set_cool_setpoint_f(self, temp: float) -> None:
    """Sets the cooling setpoint temperature in Fahrenheit."""
    await self.director.send_post_request(
        f"/api/v1/items/{self.item_id}/commands",
        "SET_SETPOINT_COOL",
        {"FAHRENHEIT": temp},
    )
```

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

### Get Item Network Information

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves the network information for a specified Control4 item.

```APIDOC
## GET /api/v1/items/{item_id}/network

### Description
Returns the network information for the specified item.

### Method
GET

### Endpoint
/api/v1/items/{item_id}/network

### Parameters
#### Path Parameters
- **item_id** (int) - Required - The Control4 item ID.

### Response
#### Success Response (200)
- **result** (list[dict[str, Any]]) - A list of dictionaries containing network information.
```

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

### Open Blind Completely

Source: https://lawtancool.github.io/pyControl4/blind.html

Sends a command to open the blind to its fully open position.

```python
async def open(self) -> None:
        """Opens the blind completely."""
        await self.director.send_post_request(
            f"/api/v1/items/{self.item_id}/commands",
            "SET_LEVEL_TARGET:LEVEL_TARGET_OPEN",
            {},
        )
```

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

### Get Item Variables

Source: https://lawtancool.github.io/pyControl4/director.html

Retrieves a list of variables available for a specified Control4 item.

```APIDOC
## GET /api/v1/items/{item_id}/variables

### Description
Returns a list of the variables available for the specified item.

### Method
GET

### Endpoint
/api/v1/items/{item_id}/variables

### Parameters
#### Path Parameters
- **item_id** (int) - Required - The Control4 item ID.

### Response
#### Success Response (200)
- **result** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents a variable.
```
Tokens:
Raw