PyNetioConf 0.3.0b1__py3-none-any.whl

PyNetioConf/ESPCore/ws_api.py

@@ -0,0 +1,391 @@
+import base64
+import hashlib
+import json
+import logging
+import math
+import random
+from collections.abc import Generator
+from io import BufferedIOBase
+from time import sleep
+from typing import Any, BinaryIO, NamedTuple, Tuple
+
+from websocket import WebSocket, WebSocketConnectionClosedException
+
+from PyNetioConf.constants import WS_EXECUTION_DELAY
+
+from ..exceptions import CommunicationError
+from ..netio_device import NETIODevice
+
+logger = logging.getLogger(__name__)
+
+
+class _FileChunk(NamedTuple):
+    base64: str
+    original_len: int
+    index: int
+    bytes_from: int
+    bytes_to: int
+
+
+def send_request(
+    device: NETIODevice,
+    type: str,
+    topic: str | None = None,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Send a request to the device's websocket API and return the response.
+    Parameters
+    ----------
+    device : ESPDevice
+        The ESPDevice object of the device.
+    type : str
+        The type of the request. Can be one of the following: "HELO", "AUTH", "SET", "SUBSCRIBE", "UNSUBSCRIBE".
+    topic : str
+        The target of the request if applicable.
+    data : Dict
+        The data to send with the request if applicable.
+
+    Returns
+    -------
+        Upon successful communication returns the direct API response from the device to be further parsed.
+    """
+    if device.ws is None:
+        device.login(device.username, device.password)
+
+    request: dict[str, Any] = {"type": type, "reqId": device.ws_req_id}
+    unsubscribe_needed = False
+    expected_reqest_id = device.ws_req_id
+    if type == "SUBSCRIBE":
+        unsubscribe_needed = True
+    if topic:
+        request["topic"] = topic
+    if data:
+        request["data"] = data
+    logger.debug(f"Sending request to {device.host} with payload {request}")
+    while True:
+        try:
+            if device.ws is None:
+                raise CommunicationError(
+                    "No websocket connection associated with the device"
+                )
+            device.ws.send(json.dumps(request, ensure_ascii=False))
+            sleep(
+                WS_EXECUTION_DELAY  # TODO: Tie to device/NM
+            )  # Due to internal timers it is safer to wait after sending to not overwhelm the device
+            device.ws_req_id += 1
+
+            # Since we do not look for events we should not leave a hanging SUBSCRIBE on the websocket
+            # This is best done right after the SUBSCRIBE, so as little EVENT data gets transmitted
+            if unsubscribe_needed:
+                unsubscribe_request: dict[str, Any] = {
+                    "type": "UNSUBSCRIBE",
+                    "reqId": device.ws_req_id,
+                }
+                if topic:
+                    unsubscribe_request["topic"] = topic
+                logger.debug(
+                    f"Sending request to {device.host} with payload {unsubscribe_request}"
+                )
+                device.ws.send(json.dumps(unsubscribe_request, ensure_ascii=False))
+                sleep(
+                    WS_EXECUTION_DELAY
+                )  # Due to internal timers it is safer to wait after sending to not overwhelm the device
+                device.ws_req_id += 1
+
+            # Create a more proper message filtering
+            waiting_for_reply = True
+            while waiting_for_reply:
+                message = device.ws.recv()
+                logger.debug(f"Received response {message}")
+                message_data = json.loads(message)
+                if message_data["type"] != "EVENT":
+                    if message_data["type"] == "PONG":
+                        device._pong_queue.append(message_data)
+                    else:
+                        device._request_queue.append(message_data)
+                    try:
+                        if message_data["reqId"] == expected_reqest_id:
+                            waiting_for_reply = False
+                            logger.debug(
+                                f"Processing correct request {message_data['reqId']}"
+                            )
+                            break
+                        elif message_data["reqId"] > expected_reqest_id:
+                            if message_data["type"] == "PONG":
+                                match = next(
+                                    (
+                                        dq_req_id
+                                        for dq_req_id in device._pong_queue
+                                        if dq_req_id.get("reqId") == expected_reqest_id
+                                    ),
+                                    None,
+                                )
+                            else:
+                                match = next(
+                                    (
+                                        dq_req_id
+                                        for dq_req_id in device._request_queue
+                                        if dq_req_id.get("reqId") == expected_reqest_id
+                                    ),
+                                    None,
+                                )
+                            if match:
+                                logger.debug(
+                                    f"Processing correct request {message_data['reqId']}"
+                                )
+                                break
+                            else:
+                                raise NotImplementedError
+
+                        else:
+                            logger.debug(
+                                f"Processing wrong message: [{message_data['reqId']}], continuing to next one."
+                            )
+                    except KeyError:
+                        # We shouldn't be able to get here with queuing since we filter EVENTs completely now
+                        logger.debug(f"Throwing away websocket message: {message}")
+                        continue
+
+            if message_data:
+                return message_data
+            else:
+                return json.loads(message)
+        except (BrokenPipeError, WebSocketConnectionClosedException):
+            # This most likely means that the device has rebooted, or just lost connection for other reasons.
+            # Try to reconnect first, then consider the connection lost.
+            device.login(device.username, device.password, logout=True)
+            continue
+        except Exception as e:
+            raise CommunicationError(f"Failed to send request to {device.host}", str(e))
+
+
+def _gen_file_chunks(
+    file_obj: BufferedIOBase, chunk_size: int = 2048
+) -> Generator[_FileChunk, None, None]:
+    """Reads a binary file in chunks.
+
+    Yields:
+        Tuple[str, int, int, int, int]:
+            (base64_string, original_chunk_len, chunk_index, bytes_from, bytes_to)
+    """
+    chunk_iterator = iter(lambda: file_obj.read(chunk_size), b"")
+    current_byte = 0
+
+    for index, chunk in enumerate(chunk_iterator, start=0):
+        chunk_len = len(chunk)
+        b64_string = base64.b64encode(chunk).decode("utf-8")
+
+        bytes_from = current_byte
+        bytes_to = current_byte + chunk_len  # Inclusive boundary
+
+        yield _FileChunk(
+            base64=b64_string,
+            original_len=chunk_len,
+            index=index,
+            bytes_from=bytes_from,
+            bytes_to=bytes_to,
+        )
+
+        current_byte += chunk_len
+
+
+def upload_file(device: NETIODevice, file: BufferedIOBase, upload_id: str):
+    CHUNK_SIZE = 2048
+    file_chunks = list(_gen_file_chunks(file, CHUNK_SIZE))
+    chunks_total = len(file_chunks)
+    total_size = sum(chunk.original_len for chunk in file_chunks)
+    for chunk in file_chunks:
+        uploaded_chunk = chunk_file_upload(
+            device,
+            chunk.base64,
+            chunk.bytes_from,
+            chunk.bytes_to,
+            total_size,
+            upload_id,
+            chunk.index,
+            chunks_total,
+            False if chunk.index < (chunks_total - 1) else True,
+        )
+        sleep(0.3)
+
+
+def chunk_file_upload(
+    device: NETIODevice,
+    byte_data: str,
+    bytes_from: int,
+    bytes_to: int,
+    bytes_total: int,
+    upload_id: str,
+    chunk_index: int = 0,
+    chunk_total: int = 1,
+    complete: bool = True,
+) -> dict[str, Any]:
+    chunk_topic = "upload/chunk"
+    ws_type = "SET"
+    chunk_data = {
+        "b64Data": byte_data,
+        "bytesFrom": bytes_from,
+        "bytesTo": bytes_to,
+        "bytesTotal": bytes_total,
+        "chunkIndex": chunk_index,
+        "chunksTotal": chunk_total,
+        "complete": complete,
+        "uploadId": upload_id,
+    }
+    ws_request = {
+        "data": chunk_data,
+        "reqId": device.ws_req_id,
+        "topic": chunk_topic,
+        "type": ws_type,
+    }
+    import copy
+
+    _debug_request = {
+        **ws_request,
+        "data": {
+            **chunk_data,
+            "b64Data": f"... [{len(byte_data)} bytes] ...",
+        },
+    }
+    if device.ws is None:
+        raise CommunicationError("No websocket connection associated with the device")
+    logger.debug(f"Sending request to {device.host} with payload {_debug_request}")
+    device.ws.send(json.dumps(ws_request, ensure_ascii=False))
+    device.ws_req_id += 1
+    chunk_reply = device.ws.recv()
+    logger.debug(f"Received response from {device.host} with payload {chunk_reply}")
+    return json.loads(chunk_reply)
+
+
+def generate_salt() -> str:
+    base = random.randint(0, 2**32)
+    # create a sha256 hash of the base
+    return hashlib.sha256(str(base).encode()).hexdigest()
+
+
+def generate_password_hash(username: str, password: str, public_key: str) -> str:
+    salted_hash = hashlib.sha256(f"{username}{public_key}{password}".encode()).digest()
+    # convert the salted hash to base64
+    return base64.b64encode(salted_hash).decode()
+
+
+def generate_password_token(salt: str, password_hash: str) -> tuple[str, str]:
+    # create a sha256 hash of the salt and password hash
+    pwd_hash = hashlib.sha256(f"{salt}{password_hash}".encode()).hexdigest()
+    return salt, pwd_hash
+
+
+def generate_auth_token(password_token: tuple[str, str], local_timestamp: int) -> str:
+    time_mark = str(math.floor(local_timestamp / 10))
+    token_hash = hashlib.sha256(f"{time_mark}{password_token[1]}".encode()).hexdigest()
+    return f"{password_token[0]}.{token_hash}"
+
+
+def login(
+    device: NETIODevice, timestamp: int, public_key: str, username: str, password: str
+) -> dict[str, Any]:
+    salt = generate_salt()
+    password_hash = generate_password_hash(username, password, public_key)
+    password_token = generate_password_token(salt, password_hash)
+    auth_token = generate_auth_token(password_token, timestamp)
+    request = {
+        "type": "AUTH",
+        "reqId": device.ws_req_id,
+        "username": username,
+        "token": auth_token,
+    }
+    if device.ws is None:
+        raise CommunicationError("No websocket connection associated with the device")
+    device.ws.send(json.dumps(request, ensure_ascii=False))
+    logger.debug(f"Sending authentication request to {device.host}, payload: {request}")
+    device.ws_req_id += 1
+    message = device.ws.recv()
+    logger.debug(
+        f"Received authentication response from {device.host}, payload: {message}"
+    )
+    return json.loads(message)
+
+
+def device_init_login(
+    ws: WebSocket,
+    ws_req_id: int,
+    timestamp: int,
+    public_key: str,
+    username: str,
+    password: str,
+    host: str,
+) -> dict[str, Any]:
+    salt = generate_salt()
+    password_hash = generate_password_hash(username, password, public_key)
+    password_token = generate_password_token(salt, password_hash)
+    auth_token = generate_auth_token(password_token, timestamp)
+    request = {
+        "type": "AUTH",
+        "reqId": ws_req_id,
+        "username": username,
+        "token": auth_token,
+    }
+    ws.send(json.dumps(request, ensure_ascii=False))
+    logger.debug(f"Sending authentication request to {host}, payload: {request}")
+    ws_req_id += 1
+    message = ws.recv()
+    logger.debug(f"Received authentication response from {host}, payload: {message}")
+    return json.loads(message)
+
+
+def device_init_request(
+    ws: WebSocket,
+    ws_req_id: int,
+    type: str,
+    host: str,
+    topic: str | None = None,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    This is a simplified version of the send_request() function used for communication between PyNetioConf and a device which is yet to initialize.
+    """
+    request: dict[str, Any] = {"type": type, "reqId": ws_req_id}
+    unsubscribe_needed = False
+    expected_reqest_id = ws_req_id
+    if type == "SUBSCRIBE":
+        unsubscribe_needed = True
+    if topic:
+        request["topic"] = topic
+    if data:
+        request["data"] = data
+    logger.debug(f"Sending request to {host} with payload {request}")
+    try:
+        ws.send(json.dumps(request, ensure_ascii=False))
+
+        # Since we do not look for events we should not leave a hanging SUBSCRIBE on the websocket
+        if unsubscribe_needed:
+            ws_req_id += 1
+            unsubscribe_request: dict[str, Any] = {
+                "type": "UNSUBSCRIBE",
+                "reqId": ws_req_id,
+            }
+            if topic:
+                unsubscribe_request["topic"] = topic
+            logger.debug(
+                f"Sending request to {host} with payload {unsubscribe_request}"
+            )
+            ws.send(json.dumps(unsubscribe_request, ensure_ascii=False))
+        ws_req_id += 1
+        message = ws.recv()
+        # Create a more proper message filtering
+        waiting_for_reply = True
+        while waiting_for_reply:
+            try:
+                if json.loads(message)["reqId"] == expected_reqest_id:
+                    waiting_for_reply = False
+                else:
+                    logger.debug(f"Throwing away websocket message: {message}")
+                    message = ws.recv()
+            except KeyError:
+                logger.debug(f"Throwing away websocket message: {message}")
+                message = ws.recv()
+        logger.debug(f"Received response from {host} with payload {message}")
+        return json.loads(message)
+    except Exception as e:
+        raise CommunicationError(f"Failed to send request to {host}", str(e))

PyNetioConf/NetioManager.py

@@ -0,0 +1,183 @@
+"""
+Module for managing NETIO devices across a session without creating multiple connections to the same device.
+"""
+
+import atexit
+import re
+from typing import Any, Dict, List, Tuple
+
+import requests
+
+from PyNetioConf.exceptions import CommunicationError, FirmwareVersionNotSupported
+
+from .ESPCore import esp_device_init
+from .netio_device import NETIODevice
+
+
+class NetioManager:
+    """
+    A class to create and manage NETIO devices across a session.
+    """
+
+    def __init__(self) -> None:
+        self._connected_devices: list[NETIODevice] = list()
+        atexit.register(self.logout_all)
+
+    def logout_all(self) -> None:
+        """
+        Logs out of all connected devices, keeps the device list, but invalidates the sessions, if a request will be
+        sent to any of the devices, a new session will be created.
+        """
+        for device in self._connected_devices:
+            if device.session_id != "" or device.ws is not None:
+                device.logout()
+
+    def init_device(
+        self,
+        host: str,
+        username: str,
+        password: str,
+        keep_alive: bool = True,
+        use_https: bool = False,
+        **kwargs: dict[str, Any],
+    ) -> NETIODevice:
+        """
+        Initialize a Netio device object, create a connection to the device, get its platform type and return
+        an object based on that platform.
+
+        Parameters
+        ----------
+        host: str
+            Device IP address (just the IP address, without any URL parts such as 'http://')
+        username: str
+            Username that will be used to log in to the device. (Note many actions require administrator privileges)
+        password: str
+            Password for the user.
+        keep_alive: bool
+            If True, the connection will be kept alive by sending a keep alive packet every 30 seconds.
+        use_https: bool
+            Makes the communication with the device based on HTTPs, the protocol must be enabled on the device
+            in the security settings.
+        kwargs: dict[str, Any]
+            Used mainly for setting up custom SSL options while using HTTPS
+
+        Returns
+        -------
+            NETIODevice compatible object based on the platform of the connected device.
+        """
+        try:
+            netio_device = esp_device_init.initialize_esp(
+                host, username, password, keep_alive, self, use_https, **kwargs
+            )  # pyright: ignore[reportUnknownMemberType]
+        except requests.exceptions.ConnectionError:
+            raise NotImplementedError
+        self._connected_devices.append(netio_device)
+        return netio_device
+
+    def update_device(self, netio_device: NETIODevice, **kwargs) -> NETIODevice:
+        """
+        Update the device object in the device list and return its new instance,
+        main use for updating firmware between major versions.
+
+        Parameters
+        ----------
+        netio_device: NETIODevice
+            The device object to update.
+
+        Returns
+        -------
+            The updated device object.
+        """
+        for index, device in enumerate(self._connected_devices):
+            if netio_device.sn_number == device.sn_number:
+                updated_device = esp_device_init.initialize_esp(
+                    device.host,
+                    device.username,
+                    device.password,
+                    device._keep_alive_flag,
+                    self,
+                    device.use_https,
+                    **kwargs,
+                )
+                self._connected_devices[index] = updated_device
+                return updated_device
+        raise CommunicationError("Device could not be reinstated after update.")
+
+    @staticmethod
+    def parse_fw_version(host: str) -> tuple[int, int, int]:
+        """
+        Parse the firmware info string and return the version numbers.
+
+        Parameters
+        ----------
+        host: str
+            The URL of the device.
+
+        Returns
+        -------
+            A tuple containing the major, minor and bugfix version numbers.
+        """
+        fw_info = NetioManager.get_info(host)["data"]["version"]
+        fw_version = fw_info.split("-")[0]
+        version_info = re.search(r"(\d+)\.(\d+)\.(\d+)", fw_version)
+
+        if version_info:
+            return (
+                int(version_info.group(1)),
+                int(version_info.group(2)),
+                int(version_info.group(3)),
+            )
+        else:
+            raise ValueError("Invalid firmware version string")
+
+    @staticmethod
+    def get_info(host: str) -> dict:
+        """
+        Get version information from the device.
+
+        Parameters
+        ----------
+        host: str
+            IP address of the device.
+        Returns
+        -------
+            Dictionary containing the version info from the device
+        """
+        session = requests.Session()
+        json_payload = {"sessionId": "", "action": "getVersion"}
+        from urllib3.exceptions import MaxRetryError
+
+        try:
+            response = session.post(
+                f"http://{host}/api", json=json_payload, timeout=300
+            )  # noqa
+        except MaxRetryError:
+            from time import sleep
+
+            sleep(5)
+            response = session.get(f"http://{host}/api", json=json_payload, timeout=300)
+
+        if "data" not in response.json():
+            raise ConnectionError("Invalid response from device")
+        return response.json()
+
+    @staticmethod
+    def esp_get_platform(host) -> tuple[str, str]:
+        """
+        Get platform information from the device, as well as the serial number.
+
+        Parameters
+        ----------
+        host: str
+            URL of the device.
+
+        Returns
+        -------
+            A tuple containing the platform type and the serial number.
+        """
+        json_response = NetioManager.get_info(host)
+
+        if "platform" not in json_response["data"]:
+            raise ValueError("Invalid response from device")  # todo custom exception
+
+        return json_response["data"]["platform"], json_response["data"]["deviceSN"]

PyNetioConf/__init__.py

@@ -0,0 +1 @@
+from .NetioManager import NetioManager

PyNetioConf/constants.py

@@ -0,0 +1,12 @@
+# Timings and timeouts
+WS_EXECUTION_DELAY = 0.035  # Serves to give breathing room to the internal device timers and reduce unwanted restarts
+WS_DEFAULT_TIMEOUT = 60
+
+CLOUD_DEFAULT_CONNECTION_WAIT = 10
+CLOUD_ACTION_COMMUNICATION_DELAY = 3
+
+DEVICE_RESET_GRACE_PERIOD = 5
+
+# WebSocket 5.0.0+ communication constants
+DEFAULT_REQUEST_QUEUE_LEN = 256
+DEFAULT_KEEP_ALIVE_QUEUE_LEN = 64

PyNetioConf/exceptions.py

@@ -0,0 +1,56 @@
+class NetioException(Exception):
+    """Base class for all exceptions raised by this module"""
+    pass
+
+
+class ElementAlreadyExists(NetioException):
+    """Raised when trying to create an element that already exists"""
+    pass
+
+
+class ProtocolNotEnabled(NetioException):
+    """Raised when the protocol is not enabled on the device"""
+    pass
+
+
+class CommunicationError(NetioException):
+    """Raised when the connection to the Netio device fails"""
+
+    def __init__(self, message: str, error: str = ""):
+        super().__init__(message)
+        self.error = error
+
+
+class AuthError(NetioException):
+    """Raised when the authentication with the Netio device fails"""
+    pass
+
+
+class FeatureNotSupported(NetioException):
+    """Raised when the device type is not supported"""
+    pass
+
+
+class FirmwareVersionNotSupported(NetioException):
+    """Raised when the firmware version is not supported"""
+    pass
+
+
+class DeviceNotYetSupported(NetioException):
+    """Raised when the device is not yet supported"""
+    pass
+
+
+class InvalidSocketIndex(NetioException):
+    """Raised when the socket index is invalid"""
+    pass
+
+
+class ElementNotFound(NetioException):
+    """Raised when looking for an element that doesn't exist on the device."""
+    pass
+
+
+class InvalidParameterValueError(NetioException):
+    """Raised when trying to set an invalid paremeter in protocol or configuration methods"""
+    pass