AsyncAccount

pybticino.account.AsyncAccount

Represents a BTicino user account and provides methods to interact with the API.

This class is the main entry point for interacting with the user's homes and modules after successful authentication. It uses an AuthHandler instance to manage authentication tokens and an aiohttp.ClientSession (obtained from the AuthHandler) to make API requests.

Attributes:

Name	Type	Description
auth_handler	AuthHandler	The authentication handler instance used for managing tokens and the HTTP session.
user	Optional[str]	The email address of the authenticated user, populated after calling async_update_topology.
homes	dict[str, Home]	A dictionary mapping home IDs to Home objects, populated after calling async_update_topology.
raw_data	dict[str, Any]	The last raw response received from the /homesdata endpoint.

__init__

__init__(auth_handler: AuthHandler, app_version: str = DEFAULT_APP_VERSION, build_number: str = DEFAULT_BUILD_NUMBER, android_version: str = DEFAULT_ANDROID_VERSION, device_info: str = DEFAULT_DEVICE_INFO) -> None

Initialize the AsyncAccount.

Parameters:

Name	Type	Description	Default
auth_handler	AuthHandler	An initialized and authenticated AuthHandler instance.	required
app_version	str	The application version string to use in User-Agent. Defaults to DEFAULT_APP_VERSION.	DEFAULT_APP_VERSION
build_number	str	The build number string to use in User-Agent. Defaults to DEFAULT_BUILD_NUMBER.	DEFAULT_BUILD_NUMBER
android_version	str	The Android version string to use in User-Agent. Defaults to DEFAULT_ANDROID_VERSION.	DEFAULT_ANDROID_VERSION
device_info	str	The device info string to use in User-Agent. Defaults to DEFAULT_DEVICE_INFO.	DEFAULT_DEVICE_INFO

Raises:

Type	Description
TypeError	If auth_handler is not an instance of AuthHandler.

async_update_topology async

async_update_topology(device_types: list[str] | None = None) -> None

Fetch the user's home topology (homes and modules) from the API.

This method calls the /api/homesdata endpoint to retrieve information about the user's homes and the modules within them. It populates the self.homes dictionary with Home objects and self.user with the user's email address. It also stores the raw response in self.raw_data.

Parameters:

Name	Type	Description	Default
device_types	Optional[list[str]]	A list of device type strings to filter the results. Defaults to DEFAULT_DEVICE_TYPES.	None

Raises:

Type	Description
AuthError	If obtaining an access token fails.
ApiError	If the API call fails.

async_get_home_status async

async_get_home_status(home_id: str, device_types: list[str] | None = None) -> dict[str, Any]

Retrieve the current status of modules for a specific home.

Calls the /syncapi/v1/homestatus endpoint. Note that this method currently returns the raw API response dictionary. Further processing to update Module objects might be added in the future.

Parameters:

Name	Type	Description	Default
home_id	str	The ID of the home for which to retrieve the status. Must exist in self.homes.	required
device_types	Optional[list[str]]	A list of device type strings to filter the results. Defaults to DEFAULT_DEVICE_TYPES.	None

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The raw JSON response from the API containing the home status, or an empty dictionary if the home_id is not found (an error is logged).

Raises:

Type	Description
AuthError	If obtaining an access token fails.
ApiError	If the API call fails.

async_set_module_state async

async_set_module_state(home_id: str, module_id: str, state: dict, timezone: str | None = None, bridge_id: str | None = None) -> dict[str, Any]

Set the state of a specific module.

Calls the /syncapi/v1/setstate endpoint to change the state of a module (e.g., unlock a door lock, turn on a light).

Parameters:

Name	Type	Description	Default
home_id	str	The ID of the home containing the module.	required
module_id	str	The ID of the module to control.	required
state	dict	A dictionary representing the desired state change. The keys and values depend on the module type (e.g., {'lock': False} for unlocking).	required
timezone	Optional[str]	The timezone string (e.g., 'Europe/Rome'). Recommended to include based on API logs.	None
bridge_id	Optional[str]	The ID of the bridge module, if the target module is connected via a bridge.	None

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The raw JSON response from the API, typically indicating the status of the operation.

Raises:

Type	Description
ValueError	If the provided home_id is not found in self.homes.
AuthError	If obtaining an access token fails.
ApiError	If the API call fails.

async_get_events async

async_get_events(home_id: str, size: int = 30) -> dict[str, Any]

Retrieve the event history for a specific home.

Calls the /api/getevents endpoint to fetch recent events for the home. Note that this method currently returns the raw API response dictionary. Further processing into Event objects might be added later.

Parameters:

Name	Type	Description	Default
home_id	str	The ID of the home for which to retrieve events. Must exist in self.homes.	required
size	int	The maximum number of events to retrieve. Defaults to 30.	30

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The raw JSON response from the API containing the events, or an empty dictionary if the home_id is not found (an error is logged).

Raises:

Type	Description
AuthError	If obtaining an access token fails.
ApiError	If the API call fails.

async_get_turn_servers async

async_get_turn_servers() -> list[dict[str, Any]]

Fetch TURN/STUN server credentials for WebRTC.

Makes a POST request to the /turn endpoint using the same headers and format as all other API calls (User-Agent, JSON content type).

Returns:

Type	Description
list[dict[str, Any]]	A list of ICE server dicts, each containing:
list[dict[str, Any]]	urls: list of TURN/STUN URLs
list[dict[str, Any]]	username: TURN username
list[dict[str, Any]]	credential: TURN password
list[dict[str, Any]]	credentialType: usually "password"

Raises:

Type	Description
AuthError	If authentication fails.
ApiError	If the API request fails.