mx-remote 2.0.0__py3-none-any.whl

mx_remote/proto/FrameHeader.py

@@ -0,0 +1,92 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from ..Uid import MxrDeviceUid
+from ..Interface import DeviceRegistry
+
+class FrameHeader:
+    ''' Header of an mx_remote frame '''
+    def __init__(self, mxr:DeviceRegistry, data: bytes, addr: tuple[str, int]):
+        self._mxr = mxr
+        self.data = data
+        self.addr = addr
+        if len(data) < 24:
+            raise Exception(f'invalid mx_remote frame (length = {len(data)})')
+        if (data[0] != 80) or (data[1] != 56):
+            raise Exception(f'invalid mx_remote frame (header = {int(data[0])}:{int(data[1])})')
+
+    def construct(mxr:DeviceRegistry, opcode:int, protocol:int=1) -> 'FrameHeader':
+        # create a new mx_remote frame for transmission
+        pkt = [80, 56, protocol, 0 ]
+        pkt.extend(mxr.uid_raw)
+        pkt.extend([(opcode & 0xFF), ((opcode >> 8) & 0xFF)])
+        pkt.extend([0, 0])
+        return FrameHeader(mxr, bytes(pkt), ("", 0))
+
+    @property
+    def mxr(self) -> DeviceRegistry:
+        return self._mxr
+
+    @property
+    def protocol(self) -> int:
+        # frame protocol version
+        if len(self) < 4:
+            return 255
+        return (int(self.data[3]) << 8) | int(self.data[2])
+
+    @property
+    def remote_id(self) -> MxrDeviceUid:
+        # unique id of the device that sent this frame
+        return MxrDeviceUid(self.data[4:20])
+
+    @property
+    def remote_id_raw(self) -> bytes:
+        # unique id of the device that sent this frame
+        if len(self) < 20:
+            return None
+        return self.data[4:20]
+
+    @property
+    def opcode(self) -> int:
+        # command opcode
+        if len(self) < 22:
+            return -1
+        return (int(self.data[21]) << 8) | int(self.data[20])
+
+    @property
+    def payload_len(self) -> int:
+        # number of payload bytes
+        if len(self) < 24:
+            return 0
+        return (int(self.data[23]) << 8) | int(self.data[22])
+
+    @property
+    def payload(self) -> bytes:
+        # frame payload bytes
+        if len(self) < 25:
+            return None
+        return self.data[24:]
+
+    @payload.setter
+    def payload(self, val:bytes) -> None:
+        data = list(self.data[0:24])
+        if (val is None) or (len(val) == 0):
+            data[22] = 0
+            data[23] = 0
+        else:
+            l = len(val)
+            data[22] = (l & 0xFF)
+            data[23] = ((l >> 8) & 0xFF)
+            data += val
+        self.data = bytes(data)
+
+    def __len__(self) -> int:
+        # number of bytes in this frame
+        return len(self.data)
+
+    def __str__(self) -> str:
+        return f"proto: {self.protocol} op: {self.opcode} len: {self.payload_len}"

mx_remote/proto/FrameHello.py

@@ -0,0 +1,77 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from ..const import __version__
+from .Constants import MXR_PROTOCOL_VERSION, MXR_DEVICE_FEATURE_MANAGER
+from .FrameBase import FrameBase, append_payload_str
+from .FrameHeader import FrameHeader
+from ..Interface import DeviceRegistry, DeviceFeatures
+import struct
+from typing import Any
+
+class FrameHello(FrameBase):
+    ''' Hello frame, sent by devices to advertise themselves on the network '''
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    def construct(mxr:DeviceRegistry) -> FrameBase:
+        payload = [ (MXR_PROTOCOL_VERSION & 0xFF), ((MXR_PROTOCOL_VERSION >> 8) & 0xFF) ]
+        payload = append_payload_str(payload=payload, value=mxr.name, sz=16)
+        payload = append_payload_str(payload=payload, value="P9SN00000000", sz=16)
+        payload = append_payload_str(payload=payload, value=__version__, sz=16)
+        features = MXR_DEVICE_FEATURE_MANAGER
+        payload += [ (features >> 0) & 0xFF, (features >> 8) & 0xFF, (features >> 16) & 0xFF, (features >> 24) & 0xFF ]
+        return FrameBase.construct_frame(mxr=mxr, opcode=0, payload=payload)
+
+    @property
+    def supported_protocol(self) -> int:
+        # supported protocol version, which may be higher than this frame's protocol version
+        return (int(self.payload[1]) << 8) | int(self.payload[0])
+
+    @property
+    def device_name(self) -> str:
+        # device name
+        return self.payload[2:18].split(b'\0',1)[0].decode('ascii')
+
+    @property
+    def serial(self) -> str:
+        # device serial
+        return self.payload[18:34].split(b'\0',1)[0].decode('ascii')
+
+    @property
+    def version(self) -> str:
+        # firmware version
+        return self.payload[34:50].split(b'\0',1)[0].decode('ascii')
+
+    @property
+    def features(self) -> DeviceFeatures:
+        # supported features bitmask
+        return DeviceFeatures(struct.unpack('<L', self.payload[50:54])[0])
+
+    def process(self) -> None:
+        # register or update this device in the local cache
+        self.mxr.on_mxr_hello(self)
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, FrameHello) and \
+                (self.protocol == other.protocol) and \
+                (self.device_name == other.device_name) and \
+                (self.serial == other.serial) and \
+                (self.version == other.version) and \
+                (self.features == other.features)
+
+    def __ne__(self, other: Any) -> bool:
+        return not isinstance(other, FrameHello) or \
+                (self.protocol != other.protocol) or \
+                (self.device_name != other.device_name) or \
+                (self.serial != other.serial) or \
+                (self.version != other.version) or \
+                (self.features != other.features)
+
+    def __str__(self) -> str:
+        return f"hello name:{self.device_name} serial:{self.serial} version:{self.version} features/status: {self.features} uid: {self.header.remote_id}"
+

mx_remote/proto/FrameLinks.py

@@ -0,0 +1,45 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .LinkConfig import LinkConfig
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+import logging
+
+class FrameLinks(FrameBase):
+    ''' All configured links for the device that sent this frame '''
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    @property
+    def nb_links(self) -> int:
+        # number of links defined in this frame
+        return len(self) / 38
+
+    @property
+    def links(self) -> list[LinkConfig]:
+        # list of all links defined in this frame
+        rv = []
+        linknum = 0
+        while linknum < self.nb_links:
+            link = LinkConfig(self, self.payload[(linknum*38):((linknum+1)*38)])
+            rv.append(link)
+            linknum += 1
+        return rv
+
+    def process(self) -> None:
+        # update the cached link status
+        dev = self.remote_device
+        if dev is None:
+            logging.debug("not processing link config - hello not received")
+            return
+        for link in self.links:
+            link.process()
+        dev.on_link_config_received()
+
+    def __str__(self) -> str:
+        return f"{self.remote_device} links config"

mx_remote/proto/FrameMeshOperation.py

@@ -0,0 +1,66 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+from ..Interface import DeviceRegistry, DeviceBase, MxrDeviceUid
+from enum import Enum
+
+class MeshOperation(Enum):
+    REGISTER = 0
+    UNREGISTER = 1
+    REPLACE = 2
+    REGENERATE_ADDRESSES = 3
+    PROMOTE_MASTER = 4
+    REPORT_MEMBERSHIP = 0xFF
+
+    def __str__(self) -> str:
+        if self.value == MeshOperation.REGISTER.value:
+            return "register"
+        if self.value == MeshOperation.UNREGISTER.value:
+            return "unregister"
+        if self.value == MeshOperation.REPLACE.value:
+            return "replace"
+        if self.value == MeshOperation.REGENERATE_ADDRESSES.value:
+            return "regenerate addresses"
+        if self.value == MeshOperation.PROMOTE_MASTER.value:
+            return "promote master"
+        if self.value == MeshOperation.REPORT_MEMBERSHIP.value:
+            return "report membership"
+        return "unknown"
+
+class FrameMeshOperation(FrameBase):
+    ''' Mesh operation '''
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    def construct(mxr:DeviceRegistry, operation:MeshOperation, target:DeviceBase, option:DeviceBase|None) -> FrameBase:
+        payload = bytes([operation.value, 0, 0, 0]) + target.remote_id.byte_value
+        if option is not None:
+            payload += option.remote_id.byte_value
+        else:
+            payload += bytes([0 for _ in range(16)])
+        return FrameBase.construct_frame(mxr=mxr, opcode=0x3B, payload=payload)
+
+    @property
+    def operation(self) -> MeshOperation:
+        return MeshOperation(self.payload[0])
+
+    @property
+    def target_uid(self) -> MxrDeviceUid:
+        return MxrDeviceUid(value=self.payload[4:20])
+
+    @property
+    def parameter(self) -> MxrDeviceUid:
+        return MxrDeviceUid(value=self.payload[20:36])
+
+    def process(self) -> None:
+        if (self.operation == MeshOperation.REPORT_MEMBERSHIP):
+            self.remote_device.mesh_master = self.target_uid
+
+    def __str__(self) -> str:
+        return f"Mesh operation: {str(self.operation)}"

mx_remote/proto/FrameMirrorStatus.py

@@ -0,0 +1,49 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+from ..Interface import DeviceBase
+from ..Uid import MxrDeviceUid
+
+class FrameMirrorStatus(FrameBase):
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    @property
+    def target(self) -> MxrDeviceUid:
+        if len(self.payload) < 16:
+            return None
+        return MxrDeviceUid(self.payload[0:16])
+
+    @property
+    def is_own(self) -> bool:
+        dev = self.remote_device
+        if dev is None:
+            return False
+        return (dev.remote_id == self.target)
+
+    @property
+    def master(self) -> MxrDeviceUid:
+        if len(self.payload) < 32:
+            return None
+        return MxrDeviceUid(self.payload[16:32])
+
+    @property
+    def master_dev(self) -> DeviceBase:
+        return self.mxr.get_by_uid(self.master)
+
+    def process(self) -> None:
+        dev = self.remote_device
+        if dev is None:
+            return False
+        if self.is_own and len(dev.outputs) > 0:
+            first_out = dev.outputs[list(dev.outputs.keys())[0]]
+            first_out.mirroring = self.master_dev
+
+    def __str__(self) -> str:
+        return f"{self.remote_device} mirroring status: {self.master_dev}"

mx_remote/proto/FrameNetworkStatus.py

@@ -0,0 +1,163 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+from ..Interface import NetworkPortStatus, UtpLinkErrorStatus, UtpLinkSpeed, UtpCableStatus
+import socket
+import struct
+
+class UtpCableStatusImpl(UtpCableStatus):
+    def __init__(self, data):
+        self._data = data
+
+    @property
+    def polarity(self) -> bool:
+        return (self._data[0] == 1)
+
+    @property
+    def pair(self) -> int:
+        return (self._data[1])
+
+    @property
+    def skew(self) -> int:
+        return struct.unpack('<L', self._data[4:8])[0]
+
+    @property
+    def length(self) -> int:
+        return struct.unpack('<L', self._data[8:12])[0]
+
+    def __str__(self):
+        return f"pair {self.pair} polarity {self.polarity} skew {self.skew}"
+
+    def __repr__(self):
+        return str(self)
+
+class UtpLinkErrorStatusImpl(UtpLinkErrorStatus):
+    def __init__(self, data):
+        self._data = data
+
+    @property
+    def in_error(self) -> bool:
+        return ((self._data & (1 << 0)) != 0)
+
+    @property
+    def in_fcs_error(self) -> bool:
+        return ((self._data & (1 << 1)) != 0)
+
+    @property
+    def in_collision(self) -> bool:
+        return ((self._data & (1 << 2)) != 0)
+
+    @property
+    def out_deferred(self) -> bool:
+        return ((self._data & (1 << 3)) != 0)
+
+    @property
+    def out_excessive(self) -> bool:
+        return ((self._data & (1 << 4)) != 0)
+
+    @property
+    def polarity_error(self) -> bool:
+        return ((self._data & (1 << 5)) != 0)
+
+    @property
+    def skew_warning(self) -> bool:
+        return ((self._data & (1 << 6)) != 0)
+
+    @property
+    def length_warning(self) -> bool:
+        return ((self._data & (1 << 7)) != 0)
+
+    def __str__(self) -> str:
+        errs = ""
+        if self.in_error:
+            errs += "[rx errors]"
+        if self.in_fcs_error:
+            errs += "[rx fcs]"
+        if self.in_collision:
+            errs += "[rx collision]"
+        if self.out_deferred:
+            errs += "[tx deferred]"
+        if self.out_excessive:
+            errs += "[tx excessive]"
+        if self.polarity_error:
+            errs += "[polarity]"
+        if self.skew_warning:
+            errs += "[skew]"
+        if self.length_warning:
+            errs += "[length warning]"
+        if errs == "":
+            errs = "healthy"
+        return errs
+
+class NetworkPortStatusImpl(NetworkPortStatus):
+    def __init__(self, data:bytes) -> None:
+        self.data = data
+
+    @property
+    def port(self) -> int:
+        return int(self.data[0])
+
+    @property
+    def errors(self) -> UtpLinkErrorStatus:
+        return UtpLinkErrorStatusImpl(self.data[1])
+
+    @property
+    def vct_status(self) -> list[str]:
+        rv = []
+        for x in range(4):
+            if (self.data[2] & (1 << x) != 0):
+                rv.append("WARNING")
+            else:
+                rv.append("healthy")
+        return rv
+
+    @property
+    def link_speed(self) -> UtpLinkSpeed:
+        return UtpLinkSpeed(self.data[3] & 0x7)
+
+    @property
+    def link_full_duplex(self) -> bool:
+        return ((self.data[3] & (1 << 3)) != 0)
+
+    @property
+    def name(self) -> str:
+        return self.data[112:128].split(b'\0',1)[0].decode('ascii')
+
+    @property
+    def ip(self) -> str:
+        ip = int.from_bytes(self.data[132:136], "big")
+        return socket.inet_ntoa(struct.pack('!L', ip))
+
+    @property
+    def querier(self) -> str:
+        ip = int.from_bytes(self.data[136:140], "big")
+        return socket.inet_ntoa(struct.pack('!L', ip))
+
+    @property
+    def cable_status(self) -> list[UtpCableStatus]:
+        return [UtpCableStatusImpl(self.data[8:20]), UtpCableStatusImpl(self.data[20:32]), UtpCableStatusImpl(self.data[32:44]), UtpCableStatusImpl(self.data[44:56])]
+
+    def __str__(self) -> str:
+        return f"network status port {self.name} status: {self.errors} ip: {self.ip} vct: {self.vct_status} speed: {self.link_speed} full duplex: {self.link_full_duplex} cable: {str(self.cable_status)}"
+
+class FrameNetworkStatus(FrameBase):
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    @property
+    def status(self) -> NetworkPortStatus:
+        return NetworkPortStatusImpl(data=self.payload)
+
+    def process(self) -> None:
+        dev = self.remote_device
+        if dev is not None:
+            dev.update_network_status(self.status)
+
+    def __str__(self) -> str:
+        return str(self.status)

mx_remote/proto/FramePDUState.py

@@ -0,0 +1,71 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+from .PDUState import PDUState
+import struct
+from typing import Any
+
+class FramePDUState(FrameBase):
+    ''' pdu state frame, sent every minute by devices on the network '''
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+        self._state = PDUState(self)
+
+    @property
+    def state(self) -> PDUState:
+        return self._state
+
+    @property
+    def current(self) -> float:
+        # current (A)
+        return round(struct.unpack('f', self.payload[0:4])[0], 2)
+
+    @property
+    def voltage(self) -> float:
+        # voltage (V)
+        return round(struct.unpack('f', self.payload[4:8])[0], 2)
+
+    @property
+    def power(self) -> float:
+        # power consumption (W)
+        return round(struct.unpack('f', self.payload[8:12])[0], 2)
+
+    @property
+    def dissipation(self) -> float:
+        # power dissipation (W)
+        return round(struct.unpack('f', self.payload[12:16])[0], 2)
+
+    #@property
+    #def power_factor(self) -> float:
+    #    # power factor (NOT SUPPORTED)
+    #    return round(struct.unpack('f', self.payload[16:20])[0], 2)
+
+    @property
+    def frequency(self) -> float:
+        # AC frequency
+        return round(struct.unpack('f', self.payload[20:24])[0], 2)
+
+    def outlet_state(self, outlet):
+        return self.payload[24 + outlet] if outlet < 8 else 0
+
+    def process(self) -> None:
+        # update the local cached state
+        dev = self.mxr.get(self.remote_id)
+        if dev is not None:
+            dev.on_mxr_update_pdu(self.state)
+
+    def __eq__(self, other:Any) -> bool:
+        if not isinstance(other, FramePDUState):
+            return False
+        return (self.payload[0:16].append(self.payload[24:32])) == \
+            (other.payload[0:16].append(other.payload[24:32]))
+
+    def __ne__(self, other:Any) -> bool:
+        return not self.__eq__(other)
+

mx_remote/proto/FramePowerChange.py

@@ -0,0 +1,38 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+from ..Interface import BayBase
+
+class FramePowerChange(FrameBase):
+    ''' power status changed of a device connected to a bay '''
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+        self.dev = None
+
+    @property
+    def bay(self) -> BayBase:
+        # bay that changed
+        portnum = self.payload[0]
+        dev = self.remote_device
+        if dev is None:
+            return
+        return dev.get_by_portnum(portnum)
+
+    @property
+    def power(self) -> bool:
+        # new power status
+        return (self.payload[1] == 1)
+
+    def process(self) -> None:
+        bay = self.bay
+        if bay is not None:
+            bay.power_status = 'on' if self.power else 'off'
+
+    def __str__(self):
+        return f"{self.bay} power status: {self.power}"

mx_remote/proto/FrameRCAction.py

@@ -0,0 +1,50 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+from .Constants import RCAction
+from ..Interface import BayBase, DeviceBase, DeviceRegistry
+from ..Uid import MxrDeviceUid
+import logging
+
+_LOGGER = logging.getLogger(__name__)
+
+class FrameRCAction(FrameBase):
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    def construct(mxr:DeviceRegistry, target:BayBase, action:RCAction) -> FrameBase:
+        payload = target.device.remote_id.byte_value
+        payload += bytes([(target.port & 0xFF), ((target.port >> 8) & 0xFF), (int(action.value) & 0xFF), ((int(action.value) >> 8) & 0xFF)])
+        frame:FrameBase = FrameBase.construct_frame(mxr=mxr, opcode=0x0E)
+        frame.payload = payload
+        return frame
+
+    @property
+    def bay(self) -> BayBase:
+        # bay that received the key press
+        dev = self.remote_device
+        if dev is None:
+            return None
+        portnum = ((int(self.payload[1]) << 8) | int(self.payload[0])) if (dev.protocol >= 6) else self.payload[0]
+        return dev.get_by_portnum(portnum)
+
+    @property
+    def action(self) -> RCAction:
+        dev = self.remote_device
+        if dev is None:
+            return None
+        return RCAction(int(self.payload[2]))
+
+    def process(self) -> None:
+        bay = self.bay
+        if bay is not None:
+            bay.on_action_received(self.action)
+
+    def __str__(self) -> str:
+        return f"{self.bay} action receive: {self.action}"

mx_remote/proto/FrameRCIr.py

@@ -0,0 +1,17 @@
+##################################################
+##         MX Remote Python Interface           ##
+##                                              ##
+## author: Lars Op den Kamp (lars@opdenkamp.eu) ##
+## copyright (c) 2024 Op den Kamp IT Solutions  ##
+##################################################
+
+from .FrameBase import FrameBase
+from .FrameHeader import FrameHeader
+
+class FrameRCIr(FrameBase):
+    ''' IR key press '''
+    def __init__(self, header:FrameHeader):
+        super().__init__(header)
+
+    def __str__(self) -> str:
+        return f"IR key press"