luxos 0.0.0__py3-none-any.whl

luxos/__main__.py

@@ -0,0 +1,4 @@
+from luxos.scripts.luxos import main
+
+if __name__ == "__main__":
+    main()

luxos/api.json

@@ -0,0 +1,215 @@
+{
+  "addgroup": {
+    "logon_required": false
+  },
+  "addpool": {
+    "logon_required": false
+  },
+  "asc": {
+    "logon_required": false
+  },
+  "asccount": {
+    "logon_required": false
+  },
+  "atm": {
+    "logon_required": false
+  },
+  "atmset": {
+    "logon_required": true
+  },
+  "autotunerget": {
+    "logon_required": false
+  },
+  "autotunerset": {
+    "logon_required": true
+  },
+  "check": {
+    "logon_required": false
+  },
+  "coin": {
+    "logon_required": false
+  },
+  "config": {
+    "logon_required": false
+  },
+  "curtail": {
+    "logon_required": true
+  },
+  "devdetails": {
+    "logon_required": false
+  },
+  "devs": {
+    "logon_required": false
+  },
+  "disableboard": {
+    "logon_required": true
+  },
+  "disablepool": {
+    "logon_required": false
+  },
+  "edevs": {
+    "logon_required": false
+  },
+  "enableboard": {
+    "logon_required": true
+  },
+  "enablepool": {
+    "logon_required": false
+  },
+  "estats": {
+    "logon_required": false
+  },
+  "fans": {
+    "logon_required": false
+  },
+  "fanset": {
+    "logon_required": true
+  },
+  "frequencyget": {
+    "logon_required": false
+  },
+  "frequencyset": {
+    "logon_required": true
+  },
+  "frequencystop": {
+    "logon_required": true
+  },
+  "groupquota": {
+    "logon_required": false
+  },
+  "healthchipget": {
+    "logon_required": false
+  },
+  "healthchipset": {
+    "logon_required": true
+  },
+  "healthctrl": {
+    "logon_required": false
+  },
+  "healthctrlset": {
+    "logon_required": true
+  },
+  "immersionswitch": {
+    "logon_required": true
+  },
+  "kill": {
+    "logon_required": false
+  },
+  "lcd": {
+    "logon_required": false
+  },
+  "limits": {
+    "logon_required": false
+  },
+  "logoff": {
+    "logon_required": true
+  },
+  "logon": {
+    "logon_required": false
+  },
+  "logset": {
+    "logon_required": false
+  },
+  "netset": {
+    "logon_required": true
+  },
+  "poolopts": {
+    "logon_required": false
+  },
+  "pooloptsset": {
+    "logon_required": false
+  },
+  "pools": {
+    "logon_required": false
+  },
+  "power": {
+    "logon_required": false
+  },
+  "profileget": {
+    "logon_required": false
+  },
+  "profilenew": {
+    "logon_required": true
+  },
+  "profilerem": {
+    "logon_required": true
+  },
+  "profiles": {
+    "logon_required": false
+  },
+  "profilerestore": {
+    "logon_required": true
+  },
+  "profileset": {
+    "logon_required": true
+  },
+  "reboot": {
+    "logon_required": true
+  },
+  "rebootdevice": {
+    "logon_required": true
+  },
+  "removegroup": {
+    "logon_required": false
+  },
+  "resetminer": {
+    "logon_required": true
+  },
+  "resetconfig": {
+    "logon_required": true
+  },
+  "removepool": {
+    "logon_required": false
+  },
+  "session": {
+    "logon_required": false
+  },
+  "stats": {
+    "logon_required": false
+  },
+  "summary": {
+    "logon_required": false
+  },
+  "switchpool": {
+    "logon_required": false
+  },
+  "tempctrl": {
+    "logon_required": false
+  },
+  "tempctrlset": {
+    "logon_required": true
+  },
+  "temps": {
+    "logon_required": false
+  },
+  "tempsensor": {
+    "logon_required": false
+  },
+  "tempsensorset": {
+    "logon_required": true
+  },
+  "tunerstatus": {
+    "logon_required": false
+  },
+  "tunerswitch": {
+    "logon_required": true
+  },
+  "uninstallluxos": {
+    "logon_required": true
+  },
+  "updaterun": {
+    "logon_required": true
+  },
+  "updateset": {
+    "logon_required": true
+  },
+  "version": {
+    "logon_required": false
+  },
+  "voltageget": {
+    "logon_required": false
+  },
+  "voltageset": {
+    "logon_required": true
+  }
+}

luxos/api.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import logging
+import json
+import importlib.resources
+
+log = logging.getLogger(__name__)
+
+
+COMMANDS = json.loads(
+    (importlib.resources.files("luxos") / "api.json")
+    .read_text()
+)
+
+
+def logon_required(cmd: str, commands_list=COMMANDS) -> bool | None:
+    # Check if the command requires logon to LuxOS API
+
+    if cmd not in COMMANDS:
+        log.info("%s command is not supported. "
+                 "Try again with a different command.", cmd)
+        return None
+
+    return COMMANDS[cmd]["logon_required"]
+
+
+# TODO timeouts should be float | None
+def execute_command(host: str, port: int, timeout: int, cmd: str, params: list[str], verbose: bool):
+    from .scripts import luxos
+    return luxos.execute_command(host, port, timeout, cmd, params, verbose)
+
+

luxos/asyncops.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import functools
+import logging
+import asyncio
+import json
+
+from typing import Any
+
+from . import exceptions
+from . import api
+
+
+log = logging.getLogger(__name__)
+
+TIMEOUT = 3.0  # default timeout for operations
+
+
+def wrapped(function):
+    """wraps a function acting on a host and re-raise with internal exceptions
+
+    This re-raise exceptions so they all derive from MinerConnectionError, eg:
+    @wrapped
+    def somcode(host: str, port: int, ...):
+        ...
+
+    try:
+        await somecode()
+    except MinerConnectionError as e:  <- this will catch all exceptions!
+        e.address
+        raise MyNewExecption() from e  <- this will re-raise
+    """
+    @functools.wraps(function)
+    async def _function(host: str, port: int, *args, **kwargs):
+        try:
+            return await function(host, port, *args, **kwargs)
+        except asyncio.TimeoutError as e:
+            # we augment underlying TimeOuts
+            raise exceptions.MinerCommandTimeoutError(host, port) from e
+        except exceptions.MinerConnectionError:
+            raise
+        except Exception as e:
+            # we augment any other exception with (host, port) info
+            log.exception("internal error")
+            raise exceptions.MinerConnectionError(host, port, "internal error") from e
+    return _function
+
+
+async def _roundtrip(
+    host: str, port: int, cmd: bytes | str, timeout: float | None
+) -> str:
+    """simple asyncio socket based send/receive function
+
+    Example:
+        print(await _roundtrip(host, port, version))
+        -> (str) "{'STATUS': [{'Code': 22, 'Description'...."
+    """
+    reader, writer = await asyncio.wait_for(
+        asyncio.open_connection(host, port), timeout
+    )
+
+    writer.write(cmd.encode() if isinstance(cmd, str) else cmd)
+    await writer.drain()
+
+    response = bytearray()
+    while True:
+        data = await asyncio.wait_for(reader.read(1), timeout=timeout)
+        if not data:
+            break
+        null_index = data.find(b"\x00")
+        if null_index >= 0:
+            response += data[:null_index]
+            break
+        response += data
+
+    return response.decode()
+
+# TODO add annotations
+async def roundtrip(
+    host: str,
+    port: int,
+    cmd: bytes | str | dict[str, Any],
+    timeout: float | None = None,
+    asjson: bool | None = True,
+    retry: int = 0,
+    retry_delay: float | None = None,
+):
+    """utility wrapper around _roundrip
+
+    Example:
+        print(await roundtrip(host, port, {"version"}))
+        -> (json) {'STATUS': [{'Code': 22, 'Description': 'LUXminer 20 ...
+        print(await roundtrip(host, port, "version"))
+        -> (str) "{'STATUS': [{'Code': 22, 'Description': 'LUXminer 20 ..
+    """
+    timeout = TIMEOUT if timeout is None else timeout
+    count = 0
+
+    if not isinstance(cmd, (bytes, str)):
+        cmd = json.dumps(cmd, indent=2, sort_keys=True)
+        if asjson is None:
+            asjson = True
+
+    last_exception = None
+    while count <= retry:
+        try:
+            timeout = TIMEOUT if timeout is None else timeout
+            res = await _roundtrip(host, port, cmd, timeout)
+            if asjson:
+                return json.loads(res)
+            else:
+                return res
+        except (Exception, asyncio.TimeoutError) as e:
+            last_exception = e
+        if retry_delay:
+            await asyncio.sleep(retry_delay)
+        count += 1
+    if last_exception is not None:
+        raise last_exception
+
+
+def validate_message(
+    host: str,
+    port: int,
+    res: dict[str, Any],
+    extrakey: str | None = None,
+    minfields: None | int = None,
+    maxfields: None | int = None,
+) -> dict[str, Any]:
+    # all miner message comes with a STATUS
+    for key in ["STATUS", "id", *([extrakey] if extrakey else [])]:
+        if key in res:
+            continue
+        raise exceptions.MinerCommandMalformedMessageError(host, port, f"missing {key} from logon message", res)
+
+    if not extrakey or not (minfields or maxfields):
+        return res
+
+    n = len(res[extrakey])
+    msg = None
+    if minfields and (n < minfields):
+        msg = f"found {n} fields for {extrakey} invalid: " f"{n} <= {minfields}"
+    elif maxfields and (n > maxfields):
+        msg = f"found {n} fields for {extrakey} invalid: " f"{n} >= {maxfields}"
+    if msg is None:
+        return res[extrakey]
+    raise exceptions.MinerCommandMalformedMessageError(host, port, msg, res)
+
+
+@wrapped
+async def logon(host: str, port: int, timeout: float | None = 3) -> str:
+    timeout = TIMEOUT if timeout is None else timeout
+    res = await roundtrip(host, port, {"command": "logon"}, timeout)
+
+    # when we first logon, we'll receive a token (session_id)
+    #   [STATUS][SessionID]
+    # on subsequent logon, we receive a
+    #   [STATUS][Msg] == "Another session is active" ([STATUS][Code] 402)
+    if "SESSION" not in res and res.get("STATUS", [{}])[0].get("Code") == 402:
+        raise exceptions.MinerCommandSessionAlreadyActive(host, port, "connection active", res)
+    sessions = validate_message(host, port, res, "SESSION", 1, 1)
+
+    session = sessions[0]  # type: ignore
+
+    if "SessionID" not in session:
+        raise exceptions.MinerCommandSessionAlreadyActive(host, port, "no SessionID in data", res)
+    return str(session["SessionID"])
+
+
+@wrapped
+async def logoff(
+    host: str, port: int, sid: str, timeout: float | None = 3
+) -> dict[str, Any]:
+    timeout = TIMEOUT if timeout is None else timeout
+    return await roundtrip(host, port, {"command": "logoff", "parameter": sid}, timeout)
+
+
+@wrapped
+async def execute_command(
+    host: str,
+    port: int,
+    timeout_sec: float | None,
+    cmd: str,
+    parameters: list[str] | None = None,
+    verbose: bool = False,
+    asjson: bool | None = True,
+    add_address: bool = False
+) -> tuple[tuple[str, int], dict[str, Any]] | dict[str, Any]:
+    timeout = TIMEOUT if timeout_sec is None else timeout_sec
+    parameters = parameters or []
+
+    sid = None
+    if api.logon_required(cmd):
+        sid = await logon(host, port)
+        parameters = [sid, *parameters]
+        log.info("session id requested & obtained for %s:%i (%s)", host, port, sid)
+    else:
+        log.debug("no logon required for command %s on %s:%i", cmd, host, port)
+
+    try:
+        packet = {"command": cmd}
+        if parameters:
+            packet["parameter"] = ",".join(parameters)
+        ret = await roundtrip(host, port, packet, timeout, asjson=asjson)
+        return ((host, port), ret) if add_address else ret
+    finally:
+        if sid:
+            await logoff(host, port, sid)

luxos/exceptions.py

@@ -0,0 +1,24 @@
+class LuxosBaseException(Exception):
+    pass
+
+
+class MinerConnectionError(LuxosBaseException):
+    def __init__(self, host: str, port: int, *args, **kwargs):
+        super().__init__(host, port, *args, **kwargs)
+        self.address = (host, port)
+
+    def __str__(self):
+        return (f"<{self.address[0]}:{self.address[1]}>: {self.__class__.__name__}, "
+                f"{self.args[2] if self.args[2:] else 'unknown reason'}")
+
+
+class MinerCommandSessionAlreadyActive(MinerConnectionError):
+    pass
+
+
+class MinerCommandTimeoutError(MinerConnectionError):
+    pass
+
+
+class MinerCommandMalformedMessageError(MinerConnectionError):
+    pass

luxos/misc.py

@@ -0,0 +1,31 @@
+# catch-all module (find later a better place)
+from __future__ import annotations
+import sys
+import itertools
+
+
+if sys.version_info >= (3, 12):
+    batched = itertools.batched
+else:
+    def batched(iterable, n):
+        if n < 1:
+            raise ValueError("n must be at least one")
+        it = iter(iterable)
+        while batch := tuple(itertools.islice(it, n)):
+            yield batch
+
+
+def indent(txt: str, pre: str = " " * 2) -> str:
+    """simple text indentation"""
+
+    from textwrap import dedent
+
+    txt = dedent(txt)
+    if txt.endswith("\n"):
+        last_eol = "\n"
+        txt = txt[:-1]
+    else:
+        last_eol = ""
+
+    result = pre + txt.replace("\n", "\n" + pre) + last_eol
+    return result if result.strip() else result.strip()

luxos/scripts/async_luxos.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+import asyncio
+import json
+
+from .. import misc
+from .. import asyncops
+
+
+async def run(
+    ip_list: list[str],
+    port: int,
+    cmd: str,
+    params: list[str],
+    timeout: float,
+    delay: float | None,
+    details: bool,
+    batchsize: int = 0,
+) -> None:
+    result = {}
+    batchsize = max(batchsize, 2)
+
+    for grupid, addresses in enumerate(
+        misc.batched([(ip, port) for ip in ip_list], n=batchsize)
+    ):
+        tasks = []
+        for host, port in addresses:
+            tasks.append(
+                asyncops.execute_command(
+                    host, port, timeout, cmd, params, add_address=True
+                )
+            )
+        result[grupid] = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # runs only on batchsize, wait delay then proceed onto the next batch
+        if delay:
+            await asyncio.sleep(delay)
+
+    alltasks = [task for group in result.values() for task in group]
+    successes = [task for task in alltasks if not isinstance(task, Exception)]
+    failures = [task for task in alltasks if isinstance(task, Exception)]
+
+    # print a nice report
+    print(f"task executed sucessfully: {len(successes)}")
+    if details:
+        for (host, port), task in successes:  # type: ignore
+            print(f"  > {host}:{port}")
+            print(misc.indent(json.dumps(task, indent=2, sort_keys=True), pre="  | "))
+    print(f"task executed failures: {len(failures)}")
+    for failure in failures:
+        print(f"  {failure}")
+
+
+def main(*args, **kwargs) -> None:
+    asyncio.run(run(*args, **kwargs))