### Get Item Setup Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the setup information for a specific 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, expected to be "GET_SETUP". - **parameters** (dict[str, Any]) - Required - An empty dictionary for this command. - **async** (bool) - Required - False for this command. ### Response #### Success Response (200) - **setup_info** (dict[str, Any]) - A dictionary containing the setup information of the item. ``` -------------------------------- ### Get Item Setup Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the setup information for a specified Control4 item. ```APIDOC ## Get Item Setup ### Description Returns the setup info of the specified item. ### Method `async def get_item_setup(self, item_id: int) -> dict[str, Any]` ### Parameters #### Path Parameters - **item_id** (int) - Required - The Control4 item ID. ### Response #### Success Response (200) - **dict[str, Any]** - A dictionary containing the setup information for the item. ``` -------------------------------- ### Get Item Setup - Python Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the setup information for a specific Control4 item. Requires the item's ID. ```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 ``` -------------------------------- ### Control4 System Interaction Example Source: https://github.com/lawtancool/pycontrol4/blob/master/README.md This example demonstrates how to authenticate with a Control4 system, retrieve controller information, and control a light. Ensure you have the necessary credentials and IP address for your Control4 system. ```python from pyControl4.account import C4Account from pyControl4.director import C4Director from pyControl4.light import C4Light import asyncio username = "" password = "" ip = "192.168.1.25" """Authenticate with Control4 account""" account = C4Account(username, password) asyncio.run(account.get_account_bearer_token()) """Get and print controller name""" account_controllers = asyncio.run(account.get_account_controllers()) print(account_controllers["controllerCommonName"]) """Get bearer token to communicate with controller locally""" director_bearer_token = asyncio.run( account.get_director_bearer_token(account_controllers["controllerCommonName"]) 쨰token") """Create new C4Director instance""" director = C4Director(ip, director_bearer_token) """Print all devices on the controller""" print(asyncio.run(director.get_all_item_info())) """Create new C4Light instance""" light = C4Light(director, 253) """Ramp light level to 10% over 10000ms""" asyncio.run(light.ramp_to_level(10, 10000)) """Print state of light""" print(asyncio.run(light.get_state())) ``` -------------------------------- ### Get Item Setup Information Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the setup configuration for a specific Control4 item. This function uses a POST request to execute 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 Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Fetches setup details for a specific item. ```APIDOC ## get_item_setup ### Description Fetches setup details for a specific item. ### Method Not specified (assumed to be a method call within the pyControl4 library). ### Parameters * **item_id** (string) - Required - The unique identifier of the item. ``` -------------------------------- ### C4Room.set_play Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/room.html Starts playing media in the room. ```APIDOC ## set_play ### Description Starts playing media 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) None ### Request Example ```json { "command": "PLAY", "data": {} } ``` ``` -------------------------------- ### Set Play Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/room.html Starts or resumes playback of media in the room. ```APIDOC ## set_play ### Description Starts or resumes playback of media in the room. ### Method POST ### Endpoint /api/v1/items/{item_id}/commands ### Request Body - **command** (string) - Required - The command to execute, which is "PLAY". - **data** (object) - Required - An empty object for this command. ### Response #### Success Response (200) - **status** (string) - Indicates the success of the operation. ``` -------------------------------- ### Play Media Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/room.html Sends the 'PLAY' command to start media playback in 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 Account Controllers Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/account.html Fetches a dictionary containing information for all controllers registered to an account. It makes a GET request to the `GET_CONTROLLERS_ENDPOINT` and parses the JSON response. A `KeyError` is raised if account information is missing from the API response. ```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 Items Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves a list of all items available on the Director. ```APIDOC ## GET /api/v1/items ### Description Returns a list of all the items on the Director. ### Method GET ### Endpoint /api/v1/items ### Response #### Success Response (200) - **items** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents an item. ``` -------------------------------- ### Get All Item Info Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves a list of all items available on the Director. ```APIDOC ## GET /api/v1/items ### Description Returns a list of all the items on the Director. ### Method GET ### Endpoint /api/v1/items ### Response #### Success Response (200) - **items** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents an item. ### Response Example ```json [ { "id": 1, "name": "Living Room Light", "type": "Light", "room": "Living Room" } ] ``` ``` -------------------------------- ### Get Item Commands Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the available commands for a specified 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) - **commands** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents a command available for the item. ### Response Example ```json [ { "id": "Play", "name": "Play" }, { "id": "Pause", "name": "Pause" } ] ``` ``` -------------------------------- ### sio_connect Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/websocket.html Start WebSockets connection and listen for updates, authenticating with the provided bearer token. ```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. ### Returns None ``` -------------------------------- ### Get Item Info Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves detailed information for a specified item. ```APIDOC ## GET /api/v1/items/{item_id} ### Description Returns a list of the details of the specified item. ### Method GET ### Endpoint /api/v1/items/{item_id} ### Parameters #### Path Parameters - **item_id** (int) - Required - The Control4 item ID. ### Response #### Success Response (200) - **item_details** (list[dict[str, Any]]) - A dictionary containing the details of the specified item. ### Response Example ```json { "id": 1, "name": "Living Room Light", "type": "Light", "room": "Living Room", "model": "XYZ-123" } ``` ``` -------------------------------- ### Get UI Configuration Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the Control4 App UI Configuration, enumerating rooms and capabilities. ```APIDOC ## GET /api/v1/agents/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 experiences available in the UI. - **type** (string) - The type of experience (e.g., "watch", "listen", "cameras"). - **sources** (object) - Contains a list of 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", "Camera"). - **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. ### Response Example ```json { "experiences": [ { "type": "watch", "sources": { "source": [ { "id": 59, "type": "HDMI" }, { "id": 946, "type": "HDMI" }, { "id": 950, "type": "HDMI" }, { "id": 33, "type": "VIDEO_SELECTION" } ] }, "active": false, "room_id": 9, "username": "primaryuser" }, { "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 UI Configuration Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves a dictionary of the Control4 App UI Configuration, enumerating rooms and capabilities. ```APIDOC ## GET /api/v1/agents/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) - **dict[str, Any]** - A dictionary containing the UI configuration, including experiences, sources, rooms, and capabilities. ``` -------------------------------- ### Get All Item Info Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Fetches comprehensive information for all items managed by the Control4 Director. ```python async def get_all_item_info(self) -> list[dict[str, Any]]: ``` -------------------------------- ### Get Item Info Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves detailed information for a specific item. ```APIDOC ## GET /api/v1/items/{item_id} ### Description Returns a list of the details of the specified item. ### Method GET ### Endpoint /api/v1/items/{item_id} ### Parameters #### Path Parameters - **item_id** (int) - Required - The Control4 item ID. ### Response #### Success Response (200) - **details** (list[dict[str, Any]]) - A list of dictionaries containing the details of the specified item. ``` -------------------------------- ### Get UI Configuration Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the UI configuration for the Control4 App, including rooms and capabilities. ```APIDOC ## Get UI Configuration ### Description Returns a dictionary of the Control4 App UI Configuration enumerating rooms and capabilities. ### Method `async def get_ui_configuration(self) -> dict[str, Any]` ### Response #### Success Response (200) - **dict[str, Any]** - A dictionary containing the UI configuration. ``` -------------------------------- ### Get Supported HVAC Modes Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves a list of all supported HVAC modes for the system. ```APIDOC ## Get Supported HVAC Modes ### Description Returns a list of supported HVAC modes. ### Method GET ### Endpoint /api/v1/items/{item_id}/variables/HVAC_MODES_LIST ### Response #### Success Response (200) - **HVAC_MODES_LIST** (list[string]) - A comma-separated string of supported HVAC modes. ``` -------------------------------- ### Get Trouble Text Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/alarm.html Retrieves the trouble display text from the security panel. Returns a string or None. ```python async def get_trouble_text(self) -> str | None: """Returns the trouble display text of the security panel.""" trouble_text = await self.director.get_item_variable_value( self.item_id, "TROUBLE_TEXT" ) return trouble_text ``` -------------------------------- ### Get Account Details Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/auth.html Retrieves detailed information about a Control4 account. Requires a controller href. ```python async def getAccount(self, controller_href): data = await self.__sendAccountGetRequest(controller_href) jsonDictionary = json.loads(data) return jsonDictionary ``` -------------------------------- ### Send GET Request Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Sends a GET request to the specified API URI and returns the Director's JSON response as a string. ```APIDOC ## GET /api/v1/{uri} ### Description Sends a GET request to the specified API URI. Returns the Director's JSON response as a string. ### Method GET ### Endpoint /api/v1/{uri} ### Parameters #### Path Parameters - **uri** (string) - Required - The API URI to send the request to. Do not include the IP address of the Director. ``` -------------------------------- ### Send Account GET Request Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/account.html Internal method to send authenticated GET requests to the Control4 API using the account bearer token. ```APIDOC ## _send_account_get_request(uri: str) ### Description Sends an authenticated GET request to a specified URI on the Control4 API using the account bearer token. This method is intended for internal use. ### Parameters - **uri** (str) - The full URI to send the GET request to. ### Returns - str: The entire JSON response from the Control4 API. ``` -------------------------------- ### Send GET Request to Director Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Sends a GET request to a specified API URI on the Director. Returns 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 ``` -------------------------------- ### Get UI Configuration - Python Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Fetches the UI configuration for the Control4 system, enumerating rooms and capabilities. Returns a dictionary. ```python async def get_ui_configuration(self) -> dict[str, Any]: """Returns a dictionary of the Control4 App UI Configuration enumerating rooms and capabilities Returns: { "experiences": [ { "type": "watch", "sources": { "source": [ { "id": 59, "type": "HDMI" }, { "id": 946, "type": "HDMI" }, { "id": 950, "type": "HDMI" }, { "id": 33, "type": "VIDEO_SELECTION" } ] }, "active": false, "room_id": 9, "username": "primaryuser" }, { "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" }, { ``` -------------------------------- ### Send GET Request to Control4 API Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Sends a GET request to a specified API URI on the Director. Use this to retrieve data from the Control4 system. Ensure the URI does not include the 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 ``` -------------------------------- ### Initialize C4Auth with Credentials Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/auth.html Initializes the C4Auth class with username and password, and immediately attempts to retrieve an account bearer token. ```python class C4Auth: def __init__(self, username, password): self.username = username self.password = password asyncio.run(self.getAccountBearerToken()) ``` -------------------------------- ### Send Account GET Request Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/account.html Used internally to send GET requests to the Control4 API, authenticated with the account bearer token. Returns the entire JSON response. Requires a valid 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 ``` -------------------------------- ### Initialize C4Auth with Credentials Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/auth.html Initializes the C4Auth class with username and password, and immediately attempts to retrieve an account bearer token. ```python class C4Auth: def __init__(self, username, password): self.username = username self.password = password asyncio.run(self.getAccountBearerToken()) ``` -------------------------------- ### Send GET Request to Control4 API Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/auth.html Internal method to send authenticated GET requests to the Control4 API using an account bearer token. It constructs the necessary headers and handles potential `AttributeError` if the token is missing. ```python async def __sendAccountGetRequest(self, uri): """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: `account_bearer_token` - Control4 account bearer token. `uri` - Full URI to send GET request to. """ try: headers = {"Authorization": "Bearer {}".format(self.account_bearer_token)} except AttributeError: msg = "The account bearer token is missing - was your username/password correct? " _LOGGER.error(msg) raise async with aiohttp.ClientSession() as session: async with asyncio.timeout(10): async with session.get(uri, headers=headers) as resp: return await resp.text() ``` -------------------------------- ### Control Room AV and Volume with C4Room Source: https://context7.com/lawtancool/pycontrol4/llms.txt Use C4Room to control room power, AV source selection, and volume. Item type must be 'room'. Requires director and item_id. ```python import asyncio from pyControl4.director import C4Director from pyControl4.room import C4Room async def main(): director = C4Director("192.168.1.25", "") room = C4Room(director, 9) # Read room state on = await room.is_on() # True / False hidden = await room.is_room_hidden() # True / False volume = await room.get_volume() # int 0–100 muted = await room.is_muted() # True / False # Power await room.set_room_off() # Source selection (get source IDs from director.get_ui_configuration()) await room.set_audio_source(298) # audio only await room.set_video_and_audio_source(59) # video + audio # Volume await room.set_volume(40) await room.set_increment_volume() # +1 await room.set_decrement_volume() # -1 # Mute await room.set_mute_on() await room.set_mute_off() await room.toggle_mute() # Media transport await room.set_play() await room.set_pause() await room.set_stop() asyncio.run(main()) ``` -------------------------------- ### Initialize C4Account Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/account.html Creates a Control4 account object. Optionally accepts an aiohttp.ClientSession for network requests. ```python class C4Account: def __init__( self, username: str, password: str, session: aiohttp.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_ui_configuration Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Fetches the UI configuration for the system. ```APIDOC ## get_ui_configuration ### Description Fetches the UI configuration for the system. ### Method Not specified (assumed to be a method call within the pyControl4 library). ``` -------------------------------- ### send_get_request Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Sends a GET request to the Control4 system. ```APIDOC ## send_get_request ### Description Sends a GET request to the Control4 system. ### Method Not specified (assumed to be a method call within the pyControl4 library). ### Parameters * **endpoint** (string) - Required - The API endpoint to send the GET request to. * **params** (dict) - Optional - Parameters to include in the GET request. ``` -------------------------------- ### Get Humidity Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves the current humidity percentage. ```APIDOC ## get_humidity ### Description Returns the current humidity percentage. ### Method Signature `async def get_humidity(self) -> float | None` ### Returns - `float` | `None`: The current humidity percentage, or None if not available. ``` -------------------------------- ### Set Room Source (Internal) Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/room.html Internal helper method to set the room's audio or video source. It handles turning the room on if necessary and distinguishes between audio-only and audio/video selection. ```python async def _set_source(self, source_id: int, audio_only: bool) -> None: """ Sets the room source, turning on the room if necessary. If audio_only, only the current audio device is changed """ await self.director.send_post_request( f"/api/v1/items/{self.item_id}/commands", "SELECT_AUDIO_DEVICE" if audio_only else "SELECT_VIDEO_DEVICE", {"deviceid": source_id}, ) ``` -------------------------------- ### Set Video and Audio Source Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/room.html Sets both the audio and video source for the room. This method calls the internal `_set_source` with `audio_only=False`. ```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 HVAC Mode Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves the current HVAC mode. ```APIDOC ## get_hvac_mode ### Description Returns the currently active HVAC mode. ### Method Signature `async def get_hvac_mode(self) -> str | None` ### Returns - `str` | `None`: The current HVAC mode, or None if not available. ``` -------------------------------- ### Set Video and Audio Source Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/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 #### Path Parameters - **item_id** (string) - Required - The ID of the room item. ### Request Body - **command** (string) - Required - The command to execute, which is related to source setting. - **data** (object) - Required - Contains the source ID and a flag for audio only. - **source_id** (int) - Required - The ID of the source to set. - **audio_only** (boolean) - Required - False to set both audio and video source. ``` -------------------------------- ### Initialize C4Websocket Class Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/websocket.html Instantiates the C4Websocket class with the Director's IP address and optional parameters for SSL verification and connection callbacks. The session_no_verify_ssl parameter allows for a pre-configured aiohttp.ClientSession. ```python class C4Websocket: def __init__( self, ip: str, session_no_verify_ssl: aiohttp.ClientSession | None = None, connect_callback: Callable[..., Any] | None = None, disconnect_callback: Callable[..., Any] | None = None, ): """Creates a Control4 Websocket object. Parameters: `ip` - The IP address of the Control4 Director/Controller. `session_no_verify_ssl` - (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. This session is also passed to the underlying socketio/engineio client to avoid blocking `ssl.create_default_context()` calls inside the event loop. `connect_callback` - (Optional) A callback to be called when the Websocket connection is opened or reconnected after a network error. `disconnect_callback` - (Optional) A callback to be called when the Websocket connection is lost due to a network error. """ self.base_url: str = f"https://{ip}" self.wss_url: str = f"wss://{ip}" self.session: aiohttp.ClientSession | None = session_no_verify_ssl self.connect_callback: Callable[..., Any] | None = connect_callback self.disconnect_callback: Callable[..., Any] | None = disconnect_callback self._item_callbacks: dict[int, list[Callable[..., Any]]] = dict() self._sio: socketio.AsyncClient | None = None ``` -------------------------------- ### C4Account Initialization Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/account.html Initializes a C4Account object with username and password. Optionally accepts an aiohttp.ClientSession for network requests. ```APIDOC ## C4Account(username: str, password: str, session: aiohttp.ClientSession | None = None) ### Description Creates a Control4 account object used for authentication and API interactions. ### Parameters - **username** (str) - Control4 account username/email. - **password** (str) - Control4 account password. - **session** (aiohttp.ClientSession | None, Optional) - An existing aiohttp.ClientSession object to be used for all network requests. If not provided, the library will manage its own session. ``` -------------------------------- ### Get Item Network Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the network information for a specified 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) - **network_info** (list[dict[str, Any]]) - A list of dictionaries containing the network information for the item. ### Response Example ```json [ { "ip_address": "192.168.1.100", "mac_address": "00:1A:2B:3C:4D:5E", "connection_type": "Wired" } ] ``` ``` -------------------------------- ### Open Blind Completely Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/blind.html Sends a command to open the blind device 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", {}, ) ``` -------------------------------- ### Connect to Control4 Director and Retrieve Item Info Source: https://context7.com/lawtancool/pycontrol4/llms.txt Establishes a connection to the Control4 Director and demonstrates how to retrieve all items, filter by category, get detailed item information, and access item variables and commands. Use this for direct interaction with the Director's API. ```python import asyncio from pyControl4.director import C4Director DIRECTOR_IP = "192.168.1.25" DIRECTOR_TOKEN = "" async def main(): director = C4Director(DIRECTOR_IP, DIRECTOR_TOKEN) # Retrieve every item on the controller all_items = await director.get_all_item_info() # [{'id': 253, 'name': 'Living Room Light', 'type': 'LIGHT', ...}] # Items filtered by category lights = await director.get_all_items_by_category("lights") # Valid categories: controllers, comfort, lights, cameras, sensors, # audio_video, motorization, thermostats, motors, # control4_remote_hub, outlet_wireless_dimmer, voice-scene # Detailed info for a single item item = await director.get_item_info(253) # Available variables for an item variables = await director.get_item_variables(253) # [{'name': 'LIGHT_LEVEL', 'value': '75'}, {'name': 'LIGHT_STATE', 'value': '1'}] # Read a single variable value level = await director.get_item_variable_value(253, "LIGHT_LEVEL") print(level) # '75' # Read multiple variable values at once (pass list/tuple/set) values = await director.get_item_variable_value(253, ["LIGHT_LEVEL", "LIGHT_STATE"]) # Variable across ALL items that have it all_levels = await director.get_all_item_variable_value("LIGHT_LEVEL") # [{'iddevice': 253, 'varName': 'LIGHT_LEVEL', 'value': '75'}, ...] # Get available commands for an item cmds = await director.get_item_commands(253) # Setup, network, and binding metadata setup = await director.get_item_setup(253) network = await director.get_item_network(253) bindings = await director.get_item_bindings(253) # Room/AV experience topology from the Control4 App UI ui_config = await director.get_ui_configuration() # {'experiences': [{'type': 'watch', 'room_id': 9, ...}, ...]}) # Low-level POST (send any raw command) await director.send_post_request( f"/api/v1/items/253/commands", "SET_LEVEL", {"LEVEL": 50}, ) asyncio.run(main()) ``` -------------------------------- ### Get Item Bindings Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the binding information for a specified 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) - **bindings** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents a binding for the item. ### Response Example ```json [ { "id": 1, "name": "Volume", "type": "Analog Output" } ] ``` ``` -------------------------------- ### Initialize C4Director Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Creates a Control4 Director object. Requires the Director's IP address and a bearer token for authentication. Optionally accepts an aiohttp.ClientSession. ```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://github.com/lawtancool/pycontrol4/blob/master/docs/index.html Initializes a Control4 object representing a device. Requires a C4Director object and the item ID of the device. ```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 Item Network Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the network information for a specific 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) - **network_info** (list[dict[str, Any]]) - A list of dictionaries containing the network information for the item. ``` -------------------------------- ### open Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/blind.html Command to fully open the blind. This action will move the blind to its maximum open position. ```APIDOC ## open ### Description Opens the blind completely. ### Method POST ### Endpoint /api/v1/items/{item_id}/commands ### Request Body - **command** (string) - Must be "SET_LEVEL_TARGET:LEVEL_TARGET_OPEN" - **payload** (object) - Empty object `{}` ``` -------------------------------- ### Get Item Commands Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves the commands available for a specific 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) - **commands** (list[dict[str, Any]]) - A list of dictionaries, where each dictionary represents an available command. ``` -------------------------------- ### C4Director Class Initialization Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Initializes a C4Director object to establish communication with a Control4 Director. ```APIDOC ## C4Director(ip: str, director_bearer_token: str, session_no_verify_ssl: aiohttp.ClientSession | None = None) ### Description Creates a Control4 Director object to manage communication. ### Parameters - **ip** (str) - The IP address of the Control4 Director/Controller. - **director_bearer_token** (str) - The bearer token for authentication. Refer to `pyControl4.account.C4Account.get_director_bearer_token` for obtaining this token. - **session** (aiohttp.ClientSession | None, optional) - Allows the use of an existing `aiohttp.ClientSession` for network requests. If not provided, the library manages its own session. ``` -------------------------------- ### Get Current Temperature Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieve the current temperature in Celsius or Fahrenheit. ```APIDOC ## Get Current Temperature ### Description Retrieves the current temperature reading from the climate system. ### Methods - `get_current_temperature_c()`: Returns temperature in Celsius. - `get_current_temperature_f()`: Returns temperature in Fahrenheit. ``` -------------------------------- ### Get HVAC Mode Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves the currently active HVAC mode. ```APIDOC ## Get HVAC Mode ### Description Returns the currently active HVAC mode. ### Method GET ### Endpoint /api/v1/items/{item_id}/variables/HVAC_MODE ### Response #### Success Response (200) - **HVAC_MODE** (string) - The current HVAC mode (e.g., 'heat', 'cool', 'auto'). ``` -------------------------------- ### C4Room.set_video_and_audio_source Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/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, turning on the room if necessary. ### Method POST ### Endpoint /api/v1/items/{item_id}/commands ### Parameters #### Path Parameters - **item_id** (int) - Required - The ID of the room item. #### Request Body - **command** (string) - Required - "SELECT_VIDEO_DEVICE" - **data** (object) - Required - { "deviceid": source_id (int) } ### Response #### Success Response (200) None ### Request Example ```json { "command": "SELECT_VIDEO_DEVICE", "data": { "deviceid": 456 } } ``` ``` -------------------------------- ### Get Hold Mode Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves the currently active hold mode. ```APIDOC ## get_hold_mode ### Description Returns the currently active hold mode. ### Method Signature `async def get_hold_mode(self) -> str | None` ### Returns - `str` | `None`: The current hold mode, or None if not available. ``` -------------------------------- ### Get Fan State Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves the current power state of the fan. ```APIDOC ## get_fan_state ### Description Returns the current power state of the fan (on, off). ### Method Signature `async def get_fan_state(self) -> str | None` ### Returns - `str` | `None`: The current fan state ('on' or 'off'), or None if not available. ``` -------------------------------- ### Get All Item Information (Python) Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Retrieves a list of all items present on the Control4 Director. Requires the Director object to be initialized. ```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 Fan Mode Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/climate.html Retrieves the currently active fan mode. ```APIDOC ## get_fan_mode ### Description Returns the currently active fan mode. ### Method Signature `async def get_fan_mode(self) -> str | None` ### Returns - `str` | `None`: The current fan mode, or None if not available. ``` -------------------------------- ### Get UI Configuration Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/director.html Fetches the Control4 App UI Configuration, which enumerates rooms and their capabilities. This is useful for understanding the available user interfaces and their associated sources. ```python async def get_ui_configuration(self) -> dict[str, Any]: """Returns a dictionary of the Control4 App UI Configuration enumerating rooms and capabilities Returns: { "experiences": [ { "type": "watch", "sources": { "source": [ { "id": 59, "type": "HDMI" }, { "id": 946, "type": "HDMI" }, { "id": 950, "type": "HDMI" }, { "id": 33, "type": "VIDEO_SELECTION" } ] }, "active": false, "room_id": 9, "username": "primaryuser" }, { "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" }, ... } ... } """ data = await self.send_get_request("/api/v1/agents/ui_configuration") result: dict[str, Any] = json.loads(data) return result ``` -------------------------------- ### Get Hold Mode Source: https://github.com/lawtancool/pycontrol4/blob/master/docs/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") ```