systemair-api-promises 0.1.0__py3-none-any.whl

systemair_api/__init__.py

@@ -0,0 +1,10 @@
+"""Systemair API - Python library for communicating with and controlling Systemair ventilation units."""
+
+from systemair_api.__version__ import __version__
+
+from systemair_api.models.ventilation_unit import VentilationUnit
+from systemair_api.api.systemair_api import SystemairAPI
+from systemair_api.auth.authenticator import SystemairAuthenticator
+from systemair_api.api.websocket_client import SystemairWebSocket
+from systemair_api.utils.constants import UserModes
+from systemair_api.utils.register_constants import RegisterConstants

systemair_api/__main__.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python
+"""Main entry point for the systemair_api package."""
+
+import os
+import time
+import threading
+from dotenv import load_dotenv
+
+from systemair_api.auth.authenticator import SystemairAuthenticator
+from systemair_api.api.systemair_api import SystemairAPI
+from systemair_api.api.websocket_client import SystemairWebSocket
+from systemair_api.models.ventilation_unit import VentilationUnit
+from systemair_api.utils.constants import UserModes
+
+def on_message(message: dict) -> None:
+    """Handle incoming WebSocket messages.
+    
+    Args:
+        message: The message received from the WebSocket
+    """
+    print("Received WebSocket message:", message)
+
+def main() -> None:
+    """Run the example application demonstrating the SystemAIR API."""
+    # Load environment variables from .env file if it exists
+    load_dotenv()
+    
+    # Get credentials from environment variables
+    email = os.getenv("EMAIL")
+    password = os.getenv("PASSWORD")
+    
+    if not email or not password:
+        print("Please set EMAIL and PASSWORD environment variables")
+        print("You can create a .env file with these variables")
+        return
+    
+    # Authenticate
+    authenticator = SystemairAuthenticator(email, password)
+    access_token = authenticator.authenticate()
+    
+    if not access_token:
+        print("Authentication failed")
+        return
+    
+    print("Authentication successful, access token obtained")
+    
+    # Create API client
+    api = SystemairAPI(access_token)
+    
+    # Get account devices
+    devices_response = api.get_account_devices()
+    if not devices_response or "data" not in devices_response:
+        print("Failed to get devices")
+        return
+    
+    devices = devices_response["data"]["GetAccountDevices"]
+    if not devices:
+        print("No devices found")
+        return
+    
+    print(f"Found {len(devices)} devices:")
+    ventilation_units = []
+    
+    for device in devices:
+        print(f" - {device['name']} (ID: {device['identifier']})")
+        ventilation_unit = VentilationUnit(device['identifier'], device['name'])
+        ventilation_units.append(ventilation_unit)
+    
+    # Set up WebSocket client
+    ws_client = SystemairWebSocket(access_token, on_message)
+    ws_client.connect()
+    
+    try:
+        # Get status for the first device
+        if ventilation_units:
+            unit = ventilation_units[0]
+            
+            # Get device status
+            status_response = api.fetch_device_status(unit.identifier)
+            if status_response:
+                unit.update_from_api(status_response)
+                print(f"\nCurrent Status for {unit.name}:")
+                unit.print_status()
+                
+                # Broadcast to get updates via WebSocket
+                api.broadcast_device_statuses([unit.identifier])
+                
+                # Example: Change user mode to Away
+                print("\nChanging user mode to Away...")
+                unit.set_user_mode(api, UserModes.AWAY)
+                
+                # Wait for a moment to receive WebSocket updates
+                time.sleep(5)
+                
+                # Change user mode back to Auto
+                print("\nChanging user mode back to Auto...")
+                unit.set_user_mode(api, UserModes.AUTO)
+                
+                # Get updated status
+                status_response = api.fetch_device_status(unit.identifier)
+                if status_response:
+                    unit.update_from_api(status_response)
+                    print("\nUpdated Status:")
+                    unit.print_status()
+        
+        # Keep the main thread alive for WebSocket messages
+        print("\nListening for WebSocket messages. Press Ctrl+C to exit.")
+        while True:
+            time.sleep(1)
+            
+    except KeyboardInterrupt:
+        print("\nExiting...")
+    finally:
+        # Disconnect WebSocket
+        ws_client.disconnect()
+
+if __name__ == "__main__":
+    main()

systemair_api/__version__.py

@@ -0,0 +1,3 @@
+"""Version information."""
+
+__version__ = "0.1.0"

systemair_api/api/__init__.py

@@ -0,0 +1,4 @@
+"""API communication modules for Systemair ventilation units."""
+
+from systemair_api.api.systemair_api import SystemairAPI
+from systemair_api.api.websocket_client import SystemairWebSocket

systemair_api/api/systemair_api.py

@@ -0,0 +1,281 @@
+"""SystemairAPI - Core API communication module for Systemair ventilation units."""
+
+from typing import Dict, List, Optional, Any, Union, cast
+import requests
+from systemair_api.utils.constants import APIEndpoints
+from systemair_api.utils.exceptions import APIError, DeviceNotFoundError, RateLimitError
+
+class SystemairAPI:
+    """Core API interface for communicating with Systemair Home Solutions API.
+    
+    Provides methods for discovering devices, fetching device status,
+    and sending control commands to ventilation units.
+    """
+    
+    def __init__(self, access_token: str) -> None:
+        """Initialize the SystemairAPI with an access token.
+        
+        Args:
+            access_token: A valid JWT access token from authentication
+        """
+        self.access_token: str = access_token
+        self.headers: Dict[str, str] = {
+            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:128.0) Gecko/20100101 Firefox/128.0',
+            'Accept': '*/*',
+            'Accept-Language': 'en-US,en;q=0.5',
+            'Accept-Encoding': 'gzip, deflate, br, zstd',
+            'Referer': 'https://homesolutions.systemair.com/device/home',
+            'content-type': 'application/json',
+            'x-access-token': self.access_token,
+            'Origin': 'https://homesolutions.systemair.com',
+            'Connection': 'keep-alive',
+            'Sec-Fetch-Dest': 'empty',
+            'Sec-Fetch-Mode': 'cors',
+            'Sec-Fetch-Site': 'same-origin',
+        }
+        
+    def update_token(self, access_token: str) -> None:
+        """Update the access token used for API requests.
+        
+        This method should be called when the token is refreshed.
+        
+        Args:
+            access_token: The new access token
+        """
+        self.access_token = access_token
+        self.headers['x-access-token'] = access_token
+
+    def broadcast_device_statuses(self, device_ids: List[str]) -> Dict[str, Any]:
+        """Broadcast requests for device statuses to trigger WebSocket updates.
+        
+        Args:
+            device_ids: List of device identifiers to request updates for
+            
+        Returns:
+            dict: API response
+            
+        Raises:
+            APIError: If the API request fails
+            DeviceNotFoundError: If one or more devices are not found
+            RateLimitError: If rate limit is exceeded
+        """
+        data = {
+            "variables": {"deviceIds": device_ids},
+            "query": """
+            query ($deviceIds: [String]!) {
+                BroadcastDeviceStatuses(deviceIds: $deviceIds)
+            }
+            """
+        }
+
+        try:
+            response = requests.post(APIEndpoints.GATEWAY, headers=self.headers, json=data)
+            
+            if response.status_code == 429:
+                retry_after = response.headers.get('Retry-After')
+                retry_seconds = int(retry_after) if retry_after and retry_after.isdigit() else None
+                raise RateLimitError(retry_after=retry_seconds)
+                
+            response.raise_for_status()
+            result = cast(Dict[str, Any], response.json())
+            
+            # Check for error in response data
+            if 'errors' in result:
+                errors = result['errors']
+                for error in errors:
+                    if 'message' in error and any(device_id in error.get('message', '') for device_id in device_ids):
+                        raise DeviceNotFoundError(device_ids[0], error.get('message'))
+                raise APIError(message=errors[0].get('message', 'Unknown API error'), 
+                              response_data=result)
+                              
+            return result
+        except requests.exceptions.RequestException as e:
+            raise APIError(f"Failed to broadcast device statuses: {str(e)}", 
+                          getattr(e, 'response', None) and getattr(e.response, 'status_code', None))
+
+    def fetch_device_status(self, device_id: str) -> Dict[str, Any]:
+        """Fetch detailed status for a specific device.
+        
+        Args:
+            device_id: The unique identifier of the device
+            
+        Returns:
+            dict: API response with detailed device status
+            
+        Raises:
+            APIError: If the API request fails
+            DeviceNotFoundError: If the device is not found
+            RateLimitError: If rate limit is exceeded
+        """
+        headers = self.headers.copy()
+        headers['device-id'] = device_id
+        headers['device-type'] = 'LEGACY'
+
+        data = {
+            "variables": {"input": {"route": "/home", "viewId": ""}},
+            "query": """
+            query ($input: GetViewInputType!) {
+                GetView(input: $input) {
+                    children {
+                        type
+                        properties
+                    }
+                }
+            }
+            """
+        }
+
+        try:
+            response = requests.post(APIEndpoints.REMOTE, headers=headers, json=data)
+            
+            if response.status_code == 404:
+                raise DeviceNotFoundError(device_id)
+                
+            if response.status_code == 429:
+                retry_after = response.headers.get('Retry-After')
+                retry_seconds = int(retry_after) if retry_after and retry_after.isdigit() else None
+                raise RateLimitError(retry_after=retry_seconds)
+                
+            response.raise_for_status()
+            result = cast(Dict[str, Any], response.json())
+            
+            # Check for error in response data
+            if 'errors' in result:
+                errors = result['errors']
+                for error in errors:
+                    if 'message' in error and device_id in error.get('message', ''):
+                        raise DeviceNotFoundError(device_id, error.get('message'))
+                raise APIError(message=errors[0].get('message', 'Unknown API error'), 
+                              response_data=result)
+                              
+            return result
+        except requests.exceptions.RequestException as e:
+            if getattr(e, 'response', None) and getattr(e.response, 'status_code', None) == 404:
+                raise DeviceNotFoundError(device_id, str(e))
+            raise APIError(f"Failed to fetch device status: {str(e)}", 
+                          getattr(e, 'response', None) and getattr(e.response, 'status_code', None))
+
+    def get_account_devices(self) -> Dict[str, Any]:
+        """Get all devices associated with the current account.
+        
+        Returns:
+            dict: API response with devices list
+            
+        Raises:
+            APIError: If the API request fails
+            RateLimitError: If rate limit is exceeded
+        """
+        data = {
+            "operationName": "GetLoggedInAccount",
+            "variables": {},
+            "query": """
+            query GetLoggedInAccount {
+              GetAccountDevices {
+                identifier
+                name
+                street
+                zipcode
+                city
+                country
+                deviceType {
+                  entry
+                  module
+                  scope
+                  type
+                }
+              }
+            }
+            """
+        }
+
+        try:
+            response = requests.post(APIEndpoints.GATEWAY, headers=self.headers, json=data)
+            
+            if response.status_code == 429:
+                retry_after = response.headers.get('Retry-After')
+                retry_seconds = int(retry_after) if retry_after and retry_after.isdigit() else None
+                raise RateLimitError(retry_after=retry_seconds)
+                
+            response.raise_for_status()
+            result = cast(Dict[str, Any], response.json())
+            
+            # Check for error in response data
+            if 'errors' in result:
+                errors = result['errors']
+                raise APIError(message=errors[0].get('message', 'Unknown API error'), 
+                              response_data=result, 
+                              status_code=response.status_code)
+                              
+            return result
+        except requests.exceptions.RequestException as e:
+            raise APIError(f"Failed to fetch account devices: {str(e)}", 
+                          getattr(e, 'response', None) and getattr(e.response, 'status_code', None))
+
+
+    def write_data_item(self, device_id: str, register_id: int, value: Union[int, float, str]) -> Dict[str, Any]:
+        """Write a value to a specific register on a device.
+        
+        Args:
+            device_id: The unique identifier of the device
+            register_id: The register ID to write to
+            value: The value to write
+            
+        Returns:
+            dict: API response indicating success
+            
+        Raises:
+            APIError: If the API request fails
+            DeviceNotFoundError: If the device is not found
+            RateLimitError: If rate limit is exceeded
+            ValidationError: If the provided value is invalid
+        """
+        headers = self.headers.copy()
+        headers['device-id'] = device_id
+        headers['device-type'] = 'LEGACY'
+
+        data = {
+            "variables": {
+                "input": {
+                    "dataPoints": [{"id": register_id, "value": str(value)}]
+                }
+            },
+            "query": """
+            mutation ($input: WriteDataItemsInput!) {
+                WriteDataItems(input: $input)
+            }
+            """
+        }
+
+        try:
+            response = requests.post(APIEndpoints.REMOTE, headers=headers, json=data)
+            
+            if response.status_code == 404:
+                raise DeviceNotFoundError(device_id)
+                
+            if response.status_code == 429:
+                retry_after = response.headers.get('Retry-After')
+                retry_seconds = int(retry_after) if retry_after and retry_after.isdigit() else None
+                raise RateLimitError(retry_after=retry_seconds)
+                
+            response.raise_for_status()
+            result = cast(Dict[str, Any], response.json())
+            
+            # Check for error in response data
+            if 'errors' in result:
+                errors = result['errors']
+                for error in errors:
+                    msg = error.get('message', '')
+                    if 'device' in msg.lower() and 'not found' in msg.lower():
+                        raise DeviceNotFoundError(device_id, msg)
+                    if 'invalid' in msg.lower() or 'validation' in msg.lower():
+                        from systemair_api.utils.exceptions import ValidationError
+                        raise ValidationError(message=msg, field=f"register_{register_id}", value=value)
+                raise APIError(message=errors[0].get('message', 'Unknown API error'), 
+                              response_data=result)
+                              
+            return result
+        except requests.exceptions.RequestException as e:
+            if getattr(e, 'response', None) and getattr(e.response, 'status_code', None) == 404:
+                raise DeviceNotFoundError(device_id, str(e))
+            raise APIError(f"Failed to write data to device: {str(e)}", 
+                          getattr(e, 'response', None) and getattr(e.response, 'status_code', None))

systemair_api/api/websocket_client.py

@@ -0,0 +1,100 @@
+"""SystemairWebSocket - WebSocket client for real-time updates from Systemair ventilation units."""
+
+import websocket
+import json
+import threading
+import ssl
+from typing import Any, Callable, Dict, Optional, Union, cast
+from websocket import WebSocket, WebSocketApp
+
+class SystemairWebSocket:
+    """WebSocket client for real-time updates from Systemair Home Solutions API.
+    
+    Establishes a persistent connection to the Systemair WebSocket server
+    and processes incoming messages through a callback function.
+    """
+    
+    def __init__(self, access_token: str, on_message_callback: Callable[[Dict[str, Any]], None]) -> None:
+        """Initialize the WebSocket client.
+        
+        Args:
+            access_token: A valid JWT access token from authentication
+            on_message_callback: Callback function that will be called with message data
+        """
+        self.access_token: str = access_token
+        self.on_message_callback: Callable[[Dict[str, Any]], None] = on_message_callback
+        self.ws: Optional[WebSocketApp] = None
+        self.thread: Optional[threading.Thread] = None
+
+    def on_message(self, ws: WebSocket, message: Any) -> None:
+        """Handle incoming WebSocket messages.
+        
+        Args:
+            ws: WebSocket connection
+            message: Raw message data
+        """
+        data = json.loads(message)
+        self.on_message_callback(data)
+
+    def on_error(self, ws: WebSocket, error: Any) -> None:
+        """Handle WebSocket errors.
+        
+        Args:
+            ws: WebSocket connection
+            error: Error information
+        """
+        # Log to stdout for diagnostic purposes, but keep it minimal
+        print(f"WebSocket error: {error}")
+
+    def on_close(self, ws: WebSocket, close_status_code: Any, close_msg: Any) -> None:
+        """Handle WebSocket connection closure.
+        
+        Args:
+            ws: WebSocket connection
+            close_status_code: Status code for the closure
+            close_msg: Closure message
+        """
+        # Important status messages are kept to help diagnose issues
+        if close_status_code:
+            print(f"WebSocket connection closed with code: {close_status_code}")
+        else:
+            print("WebSocket connection closed")
+
+    def on_open(self, ws: WebSocket) -> None:
+        """Handle WebSocket connection opening.
+        
+        Args:
+            ws: WebSocket connection
+        """
+        # Connection established notification is useful for debugging
+        print("WebSocket connection opened")
+
+    def connect(self) -> None:
+        """Establish a WebSocket connection in a separate thread.
+        
+        The connection is opened in a daemon thread to allow the main program
+        to continue execution.
+        """
+        # Disable WebSocket trace output to keep logs cleaner
+        websocket.enableTrace(False)
+        self.ws = websocket.WebSocketApp(
+            f"wss://homesolutions.systemair.com/streaming/",
+            header=[
+                f"Sec-WebSocket-Protocol: accessToken, {self.access_token}",
+                "Origin: https://homesolutions.systemair.com",
+            ],
+            on_open=self.on_open,
+            on_message=self.on_message,
+            on_error=self.on_error,
+            on_close=self.on_close,
+        )
+        self.thread = threading.Thread(target=self.ws.run_forever, kwargs={"sslopt": {"cert_reqs": ssl.CERT_NONE}})
+        self.thread.daemon = True
+        self.thread.start()
+
+    def disconnect(self) -> None:
+        """Close the WebSocket connection and clean up resources."""
+        if self.ws:
+            self.ws.close()
+        if self.thread:
+            self.thread.join()

systemair_api/auth/__init__.py

@@ -0,0 +1,3 @@
+"""Authentication modules for Systemair Home Solutions cloud."""
+
+from systemair_api.auth.authenticator import SystemairAuthenticator