HidOverI2C 0.2.4__py3-none-any.whl

hidoveri2c/__init__.py

@@ -0,0 +1,386 @@
+import struct
+import time
+from dataclasses import dataclass
+from enum import Enum, Flag
+from typing import Type
+
+from .i2c_msg import i2c_msg as _i2c_msg
+from .protocols import I2CMessageClass
+
+class HidOverI2c:
+    @dataclass
+    class HidOverI2cDescriptorHeader:
+        wHIDDescLength: int
+        bcdVersion: int
+
+        STRUCT = struct.Struct("<HH")
+
+        @classmethod
+        def unpack(cls, data: bytes):
+            values = cls.STRUCT.unpack(data)
+            return cls(*values)
+
+    @dataclass
+    class HidOverI2cDescriptor:
+        wHIDDescLength: int
+        bcdVersion: int
+        wReportDescLength: int
+        wReportDescRegister: int
+        wInputRegister: int
+        wMaxInputLength: int
+        wOutputRegister: int
+        wMaxOutputLength: int
+        wCommandRegister: int
+        wDataRegister: int
+        wVendorID: int
+        wProductID: int
+        wVersionID: int
+        RESERVED: int
+
+        STRUCT = struct.Struct("<HHHHHHHHHHHHHI")
+
+        @classmethod
+        def unpack(cls, data: bytes):
+            values = cls.STRUCT.unpack(data)
+            return cls(*values)
+        
+        def pack(self) -> bytes:
+            return self.STRUCT.pack(
+                self.wHIDDescLength,
+                self.bcdVersion,
+                self.wReportDescLength,
+                self.wReportDescRegister,
+                self.wInputRegister,
+                self.wMaxInputLength,
+                self.wOutputRegister,
+                self.wMaxOutputLength,
+                self.wCommandRegister,
+                self.wDataRegister,
+                self.wVendorID,
+                self.wProductID,
+                self.wVersionID,
+                self.RESERVED
+            )
+        
+    class RequestOpcode(Enum):
+        RESERVED_0 = 0b0000
+        RESET = 0b0001
+        GET_REPORT   = 0b0010
+        SET_REPORT   = 0b0011
+        GET_IDLE     = 0b0100
+        SET_IDLE     = 0b0101
+        GET_PROTOCOL = 0b0110
+        SET_PROTOCOL = 0b0111
+        SET_POWER    = 0b1000
+        RESERVED_9  = 0b1001
+        RESERVED_A  = 0b1010
+        RESERVED_B  = 0b1011
+        RESERVED_C  = 0b1100
+        RESERVED_D  = 0b1101
+        VENDOR       = 0b1110
+        RESERVED_F  = 0b1111
+
+    class Flags(Flag):
+        ALLOW_INVALID = 0
+
+    class ReportType(Enum):
+        RESERVED = 0b00
+        Input    = 0b01
+        Output   = 0b10
+        Feature  = 0b11
+
+    class Version:
+        def __init__(self, version_id):
+            self.major = version_id >> 8
+            self.minor = (version_id & 0xFF) >> 4
+            self.patch = (version_id & 0x0F)
+
+
+    """
+    Public Methods
+    """
+
+    def __init__(self, bus, addr, descriptor_reg, msg_type: Type[I2CMessageClass] = _i2c_msg):
+        self._bus = bus
+        self._msg = msg_type
+        self._addr = addr
+        self._descriptor_reg = descriptor_reg
+
+        read_msgs = self._prepare_register_read(self._descriptor_reg, 4)
+        self._bus.i2c_rdwr(*read_msgs)
+        descriptor_header = self.HidOverI2cDescriptorHeader.unpack(bytes(read_msgs[-1]))
+        
+        read_msgs = self._prepare_register_read(self._descriptor_reg, descriptor_header.wHIDDescLength)
+        self._bus.i2c_rdwr(*read_msgs)
+        self._descriptor = self.HidOverI2cDescriptor.unpack(bytes(read_msgs[-1]))
+
+    def read(self, size: int, timeout_ms=0):
+        return self._input_read(size, timeout_ms)
+
+    def write(self, data) -> None:
+        self._output_write(data)
+
+    def get_report(self, report_type, report_id, size) -> bytes:
+        assert report_type in (self.ReportType.Input, self.ReportType.Feature)
+        if report_type == self.ReportType.Input:
+            return self.get_input_report(report_id, size)
+        elif report_type == self.ReportType.Feature:
+            return self.get_feature_report(report_id, size)
+
+    def set_report(self, report_type, report_id, data) -> None:
+        if report_type == self.ReportType.Output:
+            self._set_output_report(report_id, data)
+        elif report_type == self.ReportType.Feature:
+            self._set_feature_report(report_id, data)
+    
+    def get_input_report(self, report_id, size) -> bytes:
+        raw_data = self._get_request(self.RequestOpcode.GET_REPORT, report_type=self.ReportType.Input, report_id=report_id, size=size)[2:]
+        length, data = struct.unpack("<H", raw_data[:2])[0], raw_data[2:]
+        assert length == (len(data)+2)
+        return data
+    
+    def get_feature_report(self, report_id, size) -> bytes:
+        raw_data = self._get_request(self.RequestOpcode.GET_REPORT, report_type=self.ReportType.Feature, report_id=report_id, size=size)
+        length, data = struct.unpack("<H", raw_data[:2])[0], raw_data[2:]
+        assert length == (len(data)+2)
+        return data
+
+    def get_report_descriptor(self, size = 4096):
+        i2c_msgs = self._prepare_register_read(self._report_descriptor_register, size)
+        self._bus.i2c_rdwr(*i2c_msgs)
+        return bytes(i2c_msgs[-1])
+
+    def get_idle(self, report_id=0):
+        raw_data = self._get_request(self.RequestOpcode.GET_IDLE, report_type=self.ReportType.Feature, report_id=report_id, size=2)
+        length, idle = struct.unpack("<HH", raw_data)
+        assert length == (2 + 2)
+        return idle
+    
+    def set_idle(self, duration, report_id=0):
+        _bytes = struct.pack("<H", duration)
+        self._set_request(self.RequestOpcode.SET_IDLE, data=_bytes, report_id=report_id)
+
+    def get_protocol(self):
+        raw_data = self._get_request(self.RequestOpcode.GET_PROTOCOL, size=2)
+        length, protocol = struct.unpack("<HH", raw_data)
+        assert length == (2 + 2)
+        return protocol
+
+    def set_protocol(self, protocol: int):
+        assert 0 <= protocol <= 1
+        _bytes = struct.pack("<H", protocol)
+        self._set_request(self.RequestOpcode.SET_PROTOCOL, data=_bytes)
+
+    def reset(self):
+        self._set_request(self.RequestOpcode.RESET)
+
+    def set_power(self, power) -> None:
+        assert 0 <= power <= 1
+        self._set_request(self.RequestOpcode.SET_POWER, report_id=power)
+
+    """
+    Private Methods
+    """
+    def _read(self, size: int) -> bytes:
+        """
+        Perform an immediate, unsolicited read from HidOverI2c device
+
+        """
+        read = self._msg.read(self._addr, size)
+        self._bus.i2c_rdwr(read)
+        return bytes(read)
+
+    def _input_read(self, size, timeout_ms=0):
+        """
+        Perform a read from the input register.
+        """
+        # TODO: check if we're non blocking and whether we have IRQ signal
+        start_time = time.time()
+        while True:
+            if timeout_ms > 0:
+                elapsed = (time.time() - start_time)*1000 # ms
+                remaining = timeout_ms - elapsed
+                if remaining <= 0:
+                    return None
+
+            # wMaxInputLength includes the 2 byte length prefix, so we read that many bytes to ensure we get a full report.
+            data = self._read(self._descriptor.wMaxInputLength)
+            if len(data) <= 2:
+                continue # device initiated reset?
+            data_len = struct.unpack("<H", data[:2])[0]
+            if data_len <= 2:
+                continue # null report?
+
+            report = data[2:data_len]
+            return report
+
+    def _output_write(self, data) -> bytes:
+        i2c_msgs = self._prepare_register_write(self._output_register, data)
+        self._bus.i2c_rdwr(*i2c_msgs)
+        return bytes(i2c_msgs[-1]) # final read operation
+
+    def _set_output_report(self, report_id, data) -> None:
+        self._set_request(self.RequestOpcode.SET_REPORT, self.ReportType.Output, report_id, data)
+
+    def _set_feature_report(self, report_id, data) -> None:
+        self._set_request(self.RequestOpcode.SET_REPORT, self.ReportType.Feature, report_id=report_id, data=data)
+
+    def _get_request(self, opcode: RequestOpcode, *, report_type = ReportType.RESERVED, report_id = 0, size) -> bytes:
+        """
+        Perform a request which will Read from the data-register.
+        This function returns the data read INCLUDING the 2-byte length prefix.
+        """
+        _command_bytes = self._register_bytes(self._command_register) + self._pack_request(opcode, report_type, report_id)
+        _data_bytes = self._register_bytes(self._data_register)
+        write = self._msg.write(self._addr, _command_bytes + _data_bytes)
+        read = self._msg.read(self._addr, size+2) # +2 for length prefix
+        self._bus.i2c_rdwr(write, read)
+        return bytes(read)
+
+    def _set_request(self, opcode: RequestOpcode, report_type = ReportType.RESERVED, report_id = 0, data: bytes|None = None) -> None:
+        """
+        Perform a request which will Write to the data-register.
+        """
+        _command_bytes = self._register_bytes(self._command_register) + self._pack_request(opcode, report_type, report_id)
+        if data is not None:
+            _data_bytes = self._register_bytes(self._data_register) + struct.pack("<H", len(data)+2) + data
+            write = self._msg.write(self._addr, _command_bytes + _data_bytes)
+        else:
+            write = self._msg.write(self._addr, _command_bytes)
+        self._bus.i2c_rdwr(write)
+
+    def _read_register(self, register, size) -> bytes:
+        i2c_msgs = self._prepare_register_read(register, size)
+        self._bus.i2c_rdwr(*i2c_msgs)
+        return bytes(i2c_msgs[-1])
+    
+    def _write_register(self, register, data) -> None:
+        i2c_msgs = self._prepare_register_write(register, data)
+        self._bus.i2c_rdwr(*i2c_msgs)
+
+    def _write_read_register(self, register, wr_data, rd_data):
+        i2c_msgs = self._prepare_register_write(register, wr_data)
+        i2c_msgs += self._prepare_register_read(register, rd_data)
+        self._bus.i2c_rdwr(*i2c_msgs)
+        return bytes(i2c_msgs[-1])
+
+    def _prepare_register_write(self, register, data) -> tuple[I2CMessageClass]:
+        _data = self._register_bytes(register) + struct.pack("<H", len(data)+2) + data
+        write = self._msg.write(self._addr, _data)
+        return (write,)
+
+    def _prepare_register_read(self, register, size) -> tuple[I2CMessageClass, I2CMessageClass]:
+        """
+        Prepares a Write (regnum)+Read (regdata) I2C messages for a single transaction.
+        """
+
+        write = self._msg.write(self._addr, self._register_bytes(register))
+        read = self._msg.read(self._addr, size)
+        return (write, read)
+
+    """
+    Static methods
+    """
+
+    @staticmethod
+    def _pack_request(opcode: RequestOpcode, report_type: ReportType, report_id) -> bytes:
+        """
+        Packs an opcode+report_type+report_id into 2 or 3 bytes, as required for the command register.
+        #7.1.1
+        """
+        assert 0 <= report_id <= 255
+        if report_id < 15:
+            _bytes = [report_id | (report_type.value << 4), opcode.value]
+        else:
+            _bytes = [15 | (report_type.value << 4), opcode.value, report_id]
+
+        return bytes(_bytes)
+
+    @staticmethod
+    def _register_bytes(register) -> bytes:
+        """
+        Returns the specified 16-bit value as bytes(2) as required for an i2c write register.
+        """
+        return struct.pack("<H", register)
+
+    """
+    Properties
+    """
+
+    @property
+    def manufacturer(self):
+        return "Microsoft"
+
+    @property
+    def product(self):
+        return "HID I2C Devic"
+
+    @property
+    def serial(self):
+        return None
+
+    @property
+    def vid(self):
+        return self._descriptor.wVendorID
+
+    @property
+    def pid(self):
+        return self._descriptor.wProductID
+
+    @property
+    def version(self):
+        return self.Version(self._descriptor.bcdVersion)
+
+    @property
+    def _output_register(self):
+        return self._descriptor.wOutputRegister
+    
+    @property
+    def _input_register(self):
+        return self._descriptor.wInputRegister
+    
+    @property
+    def _report_descriptor_register(self):
+        return self._descriptor.wReportDescRegister
+    
+    @property
+    def _command_register(self):
+        return self._descriptor.wCommandRegister
+    
+    @property
+    def _data_register(self):
+        return self._descriptor.wDataRegister
+    
+    @property
+    def report_descriptor_length(self):
+        return self._descriptor.wReportDescLength
+
+class HIDAPI_HidOverI2c(HidOverI2c):
+
+    def set_feature_report(self, report, *args, **kwargs):
+        report_id = report[0]
+        return super()._set_feature_report(report_id, report, *args, **kwargs)
+
+    def set_output_report(self, report, *args, **kwargs):
+        report_id = report[0]
+        return super()._set_output_report(report_id, report, *args, **kwargs)
+
+    send_feature_report = set_feature_report # provided for compatibility.
+    send_output_report  = set_output_report  # provided for compatibility.
+
+    def get_manufacturer_string(self) -> str|None:
+        return self.manufacturer
+    
+    def get_product_string(self) -> str|None:
+        return None
+    
+    def get_serial_number_string(self):
+        return None
+    
+    def get_indexed_string(self, index):
+        return None
+
+__all__ = [
+    'HidOverI2c',
+    'HIDAPI_HidOverI2c',
+]

hidoveri2c/i2c_msg.py

@@ -0,0 +1,48 @@
+
+class i2c_msg:
+    READ = 0x01
+    WRITE = 0x00
+    buf: list[int]
+    len: int
+    addr: int
+    flags: int
+
+    def __init__(self, addr, buf, len, flags):
+        self.addr = addr
+        self.buf = buf
+        self.len = len
+        self.flags = flags
+
+    @staticmethod
+    def read(addr, size):
+        return i2c_msg(addr, [0]*size, size, i2c_msg.READ)
+    
+    @staticmethod
+    def write(addr, data):
+        return i2c_msg(addr, data, len(data), i2c_msg.WRITE)
+
+    def __iter__(self):
+        """ Iterator / Generator
+
+        :return: iterates over :py:attr:`buf`
+        :rtype: :py:class:`generator` which returns int values
+        """
+        idx = 0
+        while idx < self.len:
+            yield self.buf[idx]
+            idx += 1
+
+    def __len__(self):
+        return self.len
+
+    def __bytes__(self):
+        return bytes(self.buf[:self.len])
+
+    def __repr__(self):
+        return 'i2c_msg(%d,%d,%r)' % (self.addr, self.flags, self.__bytes__())
+
+    def __str__(self):
+        s = self.__bytes__()
+        # Throw away non-decodable bytes
+        s = s.decode(errors="ignore")
+        return s

hidoveri2c/protocols/__init__.py

@@ -0,0 +1,5 @@
+from .i2c_msg import I2CMessageClass
+
+__all__ = [
+    'I2CMessageClass'
+]

hidoveri2c/protocols/i2c_msg.py

@@ -0,0 +1,21 @@
+from typing import Protocol, runtime_checkable, Iterator
+
+@runtime_checkable
+class I2CMessageClass(Protocol):
+    """
+    Using flexible signatures to match both smbus2 and alternatives
+    """
+    addr: int
+    flags: int
+    len: int
+    def __bytes__(self) -> bytes: ...
+
+    def __iter__(self) -> Iterator[int]: ...
+
+    def __len__(self) -> int: ...
+
+    @staticmethod
+    def read(address: int, length: int) -> 'I2CMessageClass': ...
+    
+    @staticmethod
+    def write(address: int, buf: bytes|str|list[int]) -> 'I2CMessageClass': ...