pymp305 0.1.0__py3-none-any.whl

pymp305/__init__.py

@@ -0,0 +1,38 @@
+"""pymp305 — Python driver for the ISDT MP305 line (MP305A / MP305B) over USB-HID.
+
+Both models share one controller and protocol; the model is auto-detected for error
+decoding. Reverse-engineered from the official ISDT WebLink web app; see ../PROTOCOL.md.
+"""
+from .device import (
+    MP305,
+    MP305A,
+    MP305B,
+    MP305Error,
+    MP305BError,
+    ControlCommand,
+    ChargeCommand,
+    SystemSetCommand,
+)
+from .responses import (
+    State,
+    SystemSettings,
+    HardwareInfo,
+    decode_errors,
+    BATTERY_TYPES,
+    ERROR_LIST,
+    MODEL_DC,
+    MODEL_PROGRAMMABLE,
+    MODEL_USB_PD,
+    MODEL_CHARGE,
+)
+from . import protocol
+
+__all__ = [
+    "MP305", "MP305A", "MP305B", "MP305Error", "MP305BError",
+    "ControlCommand", "ChargeCommand", "SystemSetCommand",
+    "State", "SystemSettings", "HardwareInfo", "decode_errors",
+    "BATTERY_TYPES", "ERROR_LIST",
+    "MODEL_DC", "MODEL_PROGRAMMABLE", "MODEL_USB_PD", "MODEL_CHARGE",
+    "protocol",
+]
+__version__ = "0.1.0"

pymp305/device.py

@@ -0,0 +1,271 @@
+"""High-level driver for the ISDT MP305 (MP305A / MP305B) over USB-HID.
+
+Both models share the same controller and protocol; the only model-specific behaviour is
+error-bit decoding, handled automatically once the device name is read.
+
+Requires the `hid` package (cython-hidapi):  pip install hidapi
+
+Example
+-------
+    from pymp305 import MP305
+    with MP305.open() as psu:
+        print(psu.hardware_info())
+        psu.set_output(voltage=5.0, current=1.0, on=True)
+        print(psu.read_state())
+"""
+from __future__ import annotations
+
+import struct
+import time
+from dataclasses import dataclass
+
+from . import protocol as P
+from .responses import HardwareInfo, State, SystemSettings
+
+try:
+    import hid  # cython-hidapi
+except ImportError:  # pragma: no cover
+    hid = None
+
+
+class MP305Error(Exception):
+    pass
+
+
+@dataclass
+class ControlCommand:
+    """Fields for the 0xC8 control command (DPConnectModel)."""
+    remote_con: int = 1          # 1 = take remote control (required to change anything)
+    set_voltage: float = 0.0     # volts
+    set_current: float = 0.0     # amps
+    real_change: int = 3         # live-apply: 1=V, 2=I, 3=both
+    voltage_slow: int = 0
+    current_over: int = 0
+    output: int = 0              # 1 = output ON
+    model: int = 0               # 0 = DC PSU
+    refresh: int = 0
+
+    def payload(self) -> bytes:
+        return struct.pack(
+            "<BHHBBBBBB",
+            self.remote_con & 0xFF,
+            int(round(self.set_voltage * 100)) & 0xFFFF,   # 10 mV units
+            int(round(self.set_current * 1000)) & 0xFFFF,  # 1 mA units
+            self.real_change & 0xFF,
+            self.voltage_slow & 0xFF,
+            self.current_over & 0xFF,
+            self.output & 0xFF,
+            self.model & 0xFF,
+            self.refresh & 0xFF,
+        )
+
+
+@dataclass
+class ChargeCommand:
+    """Fields for the 0xEE charge command (chargeConnectCmd)."""
+    remote_con: int = 1
+    battery_type: int = 0        # index into responses.BATTERY_TYPES
+    capacity_voltage: float = 0  # per-cell V (×1000); raw cell count for NiMH/Cd
+    cells: int = 1
+    current: float = 0.0         # amps
+    output: int = 0
+    model: int = 3               # charge
+
+    def payload(self) -> bytes:
+        cap = (int(round(self.capacity_voltage * 1000))
+               if self.battery_type != 5 else int(self.capacity_voltage))
+        return struct.pack(
+            "<BBHBHBB",
+            self.remote_con & 0xFF,
+            self.battery_type & 0xFF,
+            cap & 0xFFFF,
+            self.cells & 0xFF,
+            int(round(self.current * 1000)) & 0xFFFF,
+            self.output & 0xFF,
+            self.model & 0xFF,
+        )
+
+
+@dataclass
+class SystemSetCommand:
+    """Fields for the 0xC6 system-settings command (systemSetCmd)."""
+    per_limit: int = 90
+    volume: int = 3
+    screen_off: int = 0
+    shutdown: int = 0
+    screen_direction: int = 0
+    slope_steps: int = 0
+    current_over: int = 0
+    system_check: int = 0
+    recover: int = 0
+    usb_line: int | None = None
+
+    def payload(self) -> bytes:
+        buf = struct.pack(
+            "<BBBBBHHBB",
+            self.per_limit & 0xFF, self.volume & 0xFF, self.screen_off & 0xFF,
+            self.shutdown & 0xFF, self.screen_direction & 0xFF,
+            self.slope_steps & 0xFFFF, self.current_over & 0xFFFF,
+            self.system_check & 0xFF, self.recover & 0xFF,
+        )
+        if self.usb_line is not None:
+            buf += struct.pack("<H", self.usb_line & 0xFFFF)
+        return buf
+
+
+class MP305:
+    """Driver for an ISDT MP305A or MP305B. The concrete model is auto-detected from the
+    device name on the first `hardware_info()` call and used for error decoding."""
+
+    def __init__(self, device, report_size: int = P.REPORT_SIZE):
+        self._dev = device
+        self._report_size = report_size
+        self.device_name: str | None = None   # "MP305A" / "MP305B", set by hardware_info()
+
+    # ---- connection ------------------------------------------------------
+    @staticmethod
+    def list_devices() -> list[dict]:
+        if hid is None:
+            raise MP305Error("the 'hidapi' package is not installed (pip install hidapi)")
+        return [d for d in hid.enumerate() if d["vendor_id"] == P.VENDOR_ID]
+
+    @classmethod
+    def open(cls, path: bytes | None = None, serial: str | None = None) -> "MP305":
+        """Open the MP305. Picks the HID interface with usage_page 0x01 / usage 0x04
+        when several interfaces from VID 0x28E9 are present."""
+        if hid is None:
+            raise MP305Error("the 'hidapi' package is not installed (pip install hidapi)")
+        dev = hid.device()
+        if path is not None:
+            dev.open_path(path)
+        else:
+            candidates = cls.list_devices()
+            if not candidates:
+                raise MP305Error(f"no device with VID 0x{P.VENDOR_ID:04X} found")
+            preferred = [c for c in candidates
+                         if c.get("usage_page") == P.HID_USAGE_PAGE
+                         and c.get("usage") == P.HID_USAGE]
+            chosen = (preferred or candidates)[0]
+            dev.open_path(chosen["path"])
+        try:
+            dev.set_nonblocking(0)
+        except Exception:
+            pass
+        return cls(dev)
+
+    def close(self):
+        self._dev.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ---- raw transport ---------------------------------------------------
+    def send(self, cmd: int, payload: bytes = b"") -> None:
+        report = P.build_report(cmd, payload, self._report_size)
+        n = self._dev.write(report)
+        if n < 0:
+            raise MP305Error("HID write failed")
+
+    def send_raw_payload(self, payload: bytes) -> None:
+        """Send a payload whose first byte is the command byte (e.g. BOOT/REBOOT)."""
+        self.send(payload[0], payload[1:])
+
+    def read_frame(self, timeout_ms: int = 1000) -> P.Frame | None:
+        raw = self._dev.read(self._report_size + 1, timeout_ms)
+        if not raw:
+            return None
+        return P.parse_report(bytes(raw))
+
+    def request(self, cmd: int, expect: int, payload: bytes = b"",
+                timeout_ms: int = 1500) -> P.Frame:
+        """Send `cmd` and wait until a frame with command byte `expect` arrives."""
+        self.send(cmd, payload)
+        deadline = time.monotonic() + timeout_ms / 1000.0
+        while time.monotonic() < deadline:
+            frame = self.read_frame(timeout_ms=max(1, int((deadline - time.monotonic()) * 1000)))
+            if frame is None:
+                continue
+            if frame.cmd == expect:
+                return frame
+        raise MP305Error(f"timed out waiting for response 0x{expect:02X} to 0x{cmd:02X}")
+
+    # ---- high-level reads ------------------------------------------------
+    def hardware_info(self, timeout_ms: int = 1500) -> HardwareInfo:
+        f = self.request(P.CMD_HW_INFO, P.RESP_HW_INFO, timeout_ms=timeout_ms)
+        info = HardwareInfo.parse(f.values)
+        if info.device_name:
+            self.device_name = info.device_name   # cache for model-aware error decoding
+        return info
+
+    def read_state(self, realtime: bool = True, timeout_ms: int = 1500) -> State:
+        """Read the live measurement/state frame (0xC3)."""
+        cmd = P.CMD_REALTIME if realtime else P.CMD_STATE_INFO
+        f = self.request(cmd, P.RESP_STATE, timeout_ms=timeout_ms)
+        return State.parse(f.values, device_name=self.device_name)
+
+    def read_system_settings(self, timeout_ms: int = 1500) -> SystemSettings:
+        f = self.request(P.CMD_SYS_GET, P.RESP_SYS, timeout_ms=timeout_ms)
+        return SystemSettings.parse(f.values)
+
+    # ---- high-level control ---------------------------------------------
+    def control(self, cmd: ControlCommand, timeout_ms: int = 1500) -> P.Frame:
+        return self.request(P.CMD_CONTROL, P.RESP_CONTROL, cmd.payload(), timeout_ms)
+
+    def set_output(self, voltage: float | None = None, current: float | None = None,
+                   on: bool | None = None, *, model: int = 0,
+                   real_change: int = 3, timeout_ms: int = 1500) -> State:
+        """Convenience: take remote control and set V / I / output in one call.
+
+        Unspecified values are read from the current state so they are preserved.
+        Returns the fresh state after the change.
+        """
+        st = self.read_state(timeout_ms=timeout_ms)
+        cmd = ControlCommand(
+            remote_con=1,
+            set_voltage=st.set_voltage if voltage is None else voltage,
+            set_current=st.set_current if current is None else current,
+            real_change=real_change,
+            voltage_slow=st.voltage_slow,
+            current_over=st.current_over,
+            output=st.output if on is None else (1 if on else 0),
+            model=model,
+            refresh=0,
+        )
+        self.control(cmd, timeout_ms=timeout_ms)
+        return self.read_state(timeout_ms=timeout_ms)
+
+    def output_on(self, **kw) -> State:
+        return self.set_output(on=True, **kw)
+
+    def output_off(self, **kw) -> State:
+        return self.set_output(on=False, **kw)
+
+    def release_remote(self, timeout_ms: int = 1500) -> P.Frame:
+        """Hand control back to the device's front panel (remoteCon = 0)."""
+        return self.control(ControlCommand(remote_con=0), timeout_ms=timeout_ms)
+
+    def set_system_settings(self, cmd: SystemSetCommand, timeout_ms: int = 1500) -> P.Frame:
+        return self.request(P.CMD_SYS_SET, P.RESP_SYS_SET, cmd.payload(), timeout_ms)
+
+    def charge(self, cmd: ChargeCommand, timeout_ms: int = 1500) -> P.Frame:
+        return self.request(P.CMD_CHARGE_CONTROL, P.RESP_CHARGE, cmd.payload(), timeout_ms)
+
+    def set_language(self, index: int, timeout_ms: int = 1500) -> P.Frame:
+        return self.request(P.CMD_SET_LANGUAGE, 0xA3, bytes([index & 0xFF]), timeout_ms)
+
+    # ---- danger zone -----------------------------------------------------
+    def reboot(self) -> None:
+        self.send_raw_payload(P.REBOOT_PAYLOAD)
+
+    def enter_bootloader(self) -> None:
+        self.send_raw_payload(P.BOOT_PAYLOAD)
+
+
+# Both models share this driver; aliases for discoverability / explicit intent.
+MP305A = MP305
+MP305B = MP305
+# Backwards-compatible error alias.
+MP305BError = MP305Error

pymp305/protocol.py

@@ -0,0 +1,134 @@
+"""Wire-protocol framing for the ISDT MP305 (MP305A / MP305B) over USB-HID.
+
+Transcribed from the official WebLink web app (see ../../PROTOCOL.md). All framing
+quirks (length byte, 0xAA stuffing, checksum) are reproduced exactly so the
+checksums match what the firmware expects.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# USB-HID identity (from HIDDeviceManager.connect)
+VENDOR_ID = 0x28E9          # GigaDevice
+HID_USAGE_PAGE = 0x01
+HID_USAGE = 0x04
+REPORT_ID = 0x01
+REPORT_SIZE = 64            # output report payload size (zero padded)
+
+FRAME_START = 0xAA
+GROUP_ID = 0x12
+
+# ---- command bytes -------------------------------------------------------
+CMD_HW_INFO        = 0xE0   # -> 0xE1
+CMD_STATE_INFO     = 0xC2   # -> 0xC3
+CMD_REALTIME       = 0xBD   # -> 0xC3
+CMD_SYS_GET        = 0xC4   # -> 0xC5
+CMD_SYS_SET        = 0xC6   # -> 0xC7
+CMD_CONTROL        = 0xC8   # -> 0xC9
+CMD_CHARGE_INFO    = 0xEC   # -> 0xED
+CMD_CHARGE_SEARCH  = 0xEA   # -> 0xEB
+CMD_CHARGE_CONTROL = 0xEE   # -> 0xEF
+CMD_SET_LANGUAGE   = 0xA2   # -> 0xA3
+
+# response command bytes
+RESP_HW_INFO   = 0xE1
+RESP_STATE     = 0xC3
+RESP_SYS       = 0xC5
+RESP_SYS_SET   = 0xC7
+RESP_CONTROL   = 0xC9
+RESP_CHARGE    = 0xED
+
+# raw multi-byte payloads for boot/reboot (cmd byte + extra data bytes)
+BOOT_PAYLOAD   = bytes([0xF0, 0xAC])   # jump to bootloader
+REBOOT_PAYLOAD = bytes([0xFC, 0xCA])   # reboot device
+
+
+def _add_0xAA(data: list[int]) -> list[int]:
+    """Double every 0xAA in the DATA region (index > 5), matching Cmd.add0xAA."""
+    out: list[int] = []
+    for i, b in enumerate(data):
+        out.append(b)
+        if b == FRAME_START and i > 5:
+            out.append(FRAME_START)
+    return out
+
+
+def _process_hex_array(arr: list[int]) -> list[int]:
+    """Set the length byte [0] and checksum byte [last]; matches Cmd.processHexArray."""
+    a = list(arr)
+    a[0] = (len(a) - 1) & 0xFF
+
+    total = 0
+    prev_is_aa = False
+    for i in range(2, len(a) - 1):          # index 2 .. second-to-last
+        v = a[i]
+        cur_is_aa = v == FRAME_START
+        if cur_is_aa and prev_is_aa:        # consecutive 0xAA counted once
+            prev_is_aa = False
+            continue
+        total += v
+        prev_is_aa = cur_is_aa
+    a[-1] = total & 0xFF
+
+    if a[-1] == FRAME_START:                # avoid a checksum that looks like a marker
+        a.append(FRAME_START)
+        a[0] = (a[0] + 1) & 0xFF
+    return a
+
+
+def build_frame(cmd: int, payload: bytes = b"") -> bytes:
+    """Build a complete HID frame (without the report-ID byte) for `cmd`+`payload`."""
+    body = [0x00, FRAME_START, GROUP_ID, (1 + len(payload)) & 0xFF, cmd, *payload, 0x00]
+    body = _add_0xAA(body)
+    return bytes(_process_hex_array(body))
+
+
+def build_report(cmd: int, payload: bytes = b"", report_size: int = REPORT_SIZE) -> bytes:
+    """Build the full bytes to hand to a hidapi `write()`:  report-id + frame + padding."""
+    frame = build_frame(cmd, payload)
+    buf = bytes([REPORT_ID]) + frame
+    if report_size and len(buf) < report_size + 1:
+        buf += b"\x00" * (report_size + 1 - len(buf))
+    return buf
+
+
+@dataclass
+class Frame:
+    cmd: int
+    payload: bytes      # bytes after the cmd byte, de-stuffed
+    values: bytes       # full de-stuffed frame: [N, 0xAA, 0x12, L, cmd, ...]
+
+
+def parse_report(raw: bytes) -> Frame | None:
+    """De-stuff and parse a raw HID input report (may or may not include the report-ID).
+
+    Returns None if no valid [0xAA, 0x12] header is found.
+    """
+    buf = bytes(raw)
+    # Locate the 0xAA,0x12 header; the byte before it is the length byte N.
+    start = -1
+    for i in range(len(buf) - 1):
+        if buf[i] == FRAME_START and buf[i + 1] == GROUP_ID:
+            start = i - 1
+            break
+    if start < 0:
+        return None
+    frame = list(buf[start:])
+
+    # De-stuff consecutive 0xAA (keep first), decrement N for each dropped byte.
+    values: list[int] = []
+    prev_is_aa = False
+    for b in frame:
+        cur_is_aa = b == FRAME_START
+        if cur_is_aa and prev_is_aa:
+            if values:
+                values[0] = (values[0] - 1) & 0xFF
+        else:
+            values.append(b)
+        prev_is_aa = cur_is_aa
+
+    if len(values) < 6:
+        return None
+    cmd = values[4]
+    payload = bytes(values[5:-1])   # exclude the trailing checksum byte
+    return Frame(cmd=cmd, payload=payload, values=bytes(values))

pymp305/responses.py

@@ -0,0 +1,171 @@
+"""Parsers for ISDT MP305 (MP305A / MP305B) response frames. Offsets/units transcribed
+from the WebLink source (DP3005Resp.js, dpstateResp.js, hardwareInfoResp.js, constant.js)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# bit-index -> error name, from constant.js `errorLists`
+ERROR_LIST = [
+    "errorOutRev", "errorBattVolt", "errorBattTemp_L", "errorBattTemp_H",
+    "errorBoardTemp_H", "errorDcOutOCP", "errorDcOutOVP", "errorDICInitFail",
+    "errorDcOutVol", "errorTimeOut", "errorConnectionBroken", "errorBatteryOver",
+    "errorBatteryLow", "errorCellsNode", "errorNoBattery", "errorCapacity",
+    "errorUnknown",
+]
+
+# control/model enums
+MODEL_DC = 0          # plain DC power supply (CV/CC)
+MODEL_PROGRAMMABLE = 1
+MODEL_USB_PD = 2
+MODEL_CHARGE = 3
+
+BATTERY_TYPES = ["LiHv", "LiPo", "Lilon", "LiFe", "Pb", "NiMH/Cd"]
+
+
+def _u8(b, i):  return b[i]
+def _u16(b, i): return b[i] | (b[i + 1] << 8)
+def _u32(b, i): return b[i] | (b[i + 1] << 8) | (b[i + 2] << 16) | (b[i + 3] << 24)
+
+
+# Non-MP305B devices (e.g. MP305A) remap a few low error bits — from constant.js getByteType.
+SPECIAL_ERRORS = {1: "errorUnknown", 2: "errorUnknown", 3: "errorBattTemp_H_A"}
+
+
+def decode_errors(mask: int, device_name: str | None = None,
+                  charge_mode: bool = False) -> list[str]:
+    """Decode a charge-error bitmask to error names, MP305A/MP305B-aware.
+
+    Mirrors WebLink's `getByteType`: the meaningful bit-width is 17 in charge mode
+    (model 3) and 9 otherwise; MP305B maps bits straight to `ERROR_LIST` while other
+    models remap bits 1-3 via `SPECIAL_ERRORS`.
+    """
+    if not mask:
+        return []
+    width = 17 if charge_mode else 9
+    names: list[str] = []
+    for i in range(min(width, len(ERROR_LIST))):
+        if not (mask & (1 << i)):
+            continue
+        name = ERROR_LIST[i] if device_name == "MP305B" else (SPECIAL_ERRORS.get(i) or ERROR_LIST[i])
+        if name:
+            names.append(name)
+    return names
+
+
+@dataclass
+class State:
+    """Decoded 0xC3 state frame (DP3005Resp), with physical units applied."""
+    out_state: int = 0
+    battery_state: int = 0
+    percentage: int = 0
+    voltage: float = 0.0        # V  (measured output)
+    set_voltage: float = 0.0    # V
+    current: float = 0.0        # A  (measured output)
+    set_current: float = 0.0    # A
+    working_time: int = 0       # s
+    energy: float = 0.0         # Wh
+    power: float = 0.0          # W
+    current_over: int = 0
+    real_change: int = 0
+    voltage_slow: int = 0
+    output: int = 0             # 1 = output on
+    model: int = 0
+    voltage_board: int = 0
+    current_board: int = 0
+    temperature: int = 0        # °C
+    charge_error: int = 0
+    errors: list[str] = field(default_factory=list)
+    wave_pause: int = 0
+    wave_time: int = 0
+    raw: bytes = b""
+
+    @classmethod
+    def parse(cls, frame_values: bytes, index: int = 5,
+              device_name: str | None = None) -> "State":
+        v = frame_values
+        i = index
+        s = cls(raw=bytes(v))
+        s.out_state = _u8(v, i); i += 1
+        s.battery_state = _u8(v, i); i += 1
+        s.percentage = _u8(v, i); i += 1
+        s.voltage = _u16(v, i) / 100.0; i += 2
+        s.set_voltage = _u16(v, i) / 100.0; i += 2
+        s.current = _u16(v, i) / 1000.0; i += 2
+        s.set_current = _u16(v, i) / 1000.0; i += 2
+        s.working_time = _u32(v, i); i += 4
+        s.energy = _u32(v, i) / 1000.0; i += 4
+        s.power = _u16(v, i) / 100.0; i += 2
+        s.current_over = _u8(v, i); i += 1
+        s.real_change = _u8(v, i); i += 1
+        s.voltage_slow = _u8(v, i); i += 1
+        s.output = _u8(v, i); i += 1
+        s.model = _u8(v, i); i += 1
+        s.voltage_board = _u8(v, i); i += 1
+        s.current_board = _u8(v, i); i += 1
+        s.temperature = _u8(v, i); i += 1
+        # optional trailing fields, gated on the length byte (values[0]) like the JS
+        if v[0] > 34 and i + 1 < len(v):
+            s.charge_error = _u16(v, i); i += 2
+            s.errors = decode_errors(s.charge_error, device_name,
+                                     charge_mode=(s.model == MODEL_CHARGE))
+        if v[0] > 36 and i + 4 < len(v):
+            s.wave_pause = _u8(v, i); i += 1
+            s.wave_time = _u32(v, i); i += 4
+        return s
+
+
+@dataclass
+class SystemSettings:
+    """Decoded 0xC5 frame (DPStateResp)."""
+    per_limit: int = 0
+    volume: int = 0
+    screen_off: int = 0
+    shutdown: int = 0
+    screen_direction: int = 0
+    slope_steps: int = 0
+    current_over: int = 0
+    usb_line: int | None = None
+    raw: bytes = b""
+
+    @classmethod
+    def parse(cls, frame_values: bytes, index: int = 5) -> "SystemSettings":
+        v = frame_values
+        i = index
+        s = cls(raw=bytes(v))
+        s.per_limit = _u8(v, i); i += 1
+        s.volume = _u8(v, i); i += 1
+        s.screen_off = _u8(v, i); i += 1
+        s.shutdown = _u8(v, i); i += 1
+        s.screen_direction = _u8(v, i); i += 1
+        s.slope_steps = _u16(v, i); i += 2
+        s.current_over = _u16(v, i); i += 2
+        if v[0] > 14 and i + 1 < len(v):
+            s.usb_line = _u16(v, i); i += 2
+        return s
+
+
+@dataclass
+class HardwareInfo:
+    """Decoded 0xE1 frame (HardwareInfoResp, HID layout: index=5)."""
+    device_id: list[int] = field(default_factory=list)
+    hardware_version: str = ""
+    boot_version: str = ""
+    app_version: str = ""
+    device_name: str = ""
+    raw: bytes = b""
+
+    @classmethod
+    def parse(cls, frame_values: bytes, index: int = 5) -> "HardwareInfo":
+        v = frame_values
+        i = index
+        info = cls(raw=bytes(v))
+        info.device_id = [v[i + k] for k in range(8)]; i += 8
+        hw = [v[i + k] for k in range(4)]; i += 4
+        bt = [v[i + k] for k in range(4)]; i += 4
+        ap = [v[i + k] for k in range(4)]; i += 4
+        name = bytes(v[i:i + 10]); i += 10
+        info.hardware_version = "V{}.{}.{}.{}".format(*hw)
+        info.boot_version = "V{}.{}.{}.{}".format(*bt)
+        info.app_version = "V{}.{}.{}.{}".format(*ap)
+        info.device_name = name.split(b"\x00")[0].decode("ascii", "replace").strip()
+        return info

pymp305-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: pymp305
+Version: 0.1.0
+Summary: Python driver for the ISDT MP305 (MP305A/MP305B) smart bench power supply over USB-HID
+Author-email: nemanjan00 <nemanjan00@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nemanjan00/pymp305
+Project-URL: Repository, https://github.com/nemanjan00/pymp305
+Project-URL: Issues, https://github.com/nemanjan00/pymp305/issues
+Keywords: isdt,mp305,mp305a,mp305b,power-supply,psu,usb,hid,bench
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hidapi>=0.14
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# pymp305
+
+A pure-Python driver for the **ISDT MP305** smart bench power supplies (**MP305A** and **MP305B**), talking to it
+over **USB-HID** — the same transport the official [WebLink](https://www.isdt.co/weblink/)
+web app uses. Reverse-engineered from WebLink's public source-maps; the full protocol is
+documented in [`../PROTOCOL.md`](../PROTOCOL.md). (The recovered upstream JS used during
+RE is ISDT's copyright and is kept locally under `reversing/`, which is git-ignored and
+not published.)
+
+> Status: written from the recovered firmware protocol but **not yet validated against
+> real hardware** (the device hasn't arrived). The framing layer is covered by golden-vector
+> tests (`tests/test_protocol.py`, all passing). See *Bring-up* below for first-run checks.
+
+## Install
+
+```bash
+pip install hidapi          # the only runtime dependency
+pip install -e .            # from this directory
+```
+
+On Linux you'll need permission to access the hidraw node. Either run as root for a quick
+test, or add a udev rule (recommended):
+
+```
+# /etc/udev/rules.d/99-pymp305.rules
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="28e9", MODE="0660", TAG+="uaccess"
+```
+then `sudo udevadm control --reload && sudo udevadm trigger` and replug.
+
+## Quick start
+
+```python
+from pymp305 import MP305
+
+with MP305.open() as psu:
+    print(psu.hardware_info())            # name, hw/boot/app versions
+
+    psu.set_output(voltage=5.0, current=1.0, on=True)   # takes remote control + enables output
+
+    st = psu.read_state()
+    print(f"{st.voltage:.2f} V  {st.current:.3f} A  {st.power:.2f} W  {st.temperature} C")
+
+    psu.output_off()
+    psu.release_remote()                  # hand control back to the front panel
+```
+
+See [`examples/basic.py`](./examples/basic.py) for a live-streaming example.
+
+## API surface
+
+| Method | Does |
+|--------|------|
+| `MP305.list_devices()` | enumerate VID `0x28E9` HID interfaces |
+| `MP305.open(path=None)` | open (auto-picks usage_page 0x01 / usage 0x04) |
+| `hardware_info()` | `0xE0`→`0xE1` device id, firmware versions |
+| `read_state(realtime=True)` | `0xBD`/`0xC2`→`0xC3` live V/I/W/Wh/temp/output (`State`) |
+| `read_system_settings()` | `0xC4`→`0xC5` (`SystemSettings`) |
+| `set_output(voltage, current, on, model=0)` | take control + apply, returns fresh `State` |
+| `output_on()` / `output_off()` | toggle output |
+| `release_remote()` | `remoteCon=0` — return control to the panel |
+| `control(ControlCommand)` | low-level `0xC8` |
+| `set_system_settings(SystemSetCommand)` | `0xC6` |
+| `charge(ChargeCommand)` | `0xEE` battery-charge mode |
+| `set_language(i)` | `0xA2` |
+| `reboot()` / `enter_bootloader()` | danger zone |
+| `send(cmd, payload)` / `request(cmd, expect, payload)` / `read_frame()` | raw access for PDO / programmable / OTA commands not yet wrapped |
+
+Units are converted for you: `voltage`/`set_voltage` in **V**, `current`/`set_current`
+in **A**, `power` in **W**, `energy` in **Wh**, `temperature` in **°C**, `working_time` in **s**.
+
+## Bring-up checklist (first run with hardware)
+
+1. `python -c "from pymp305 import MP305; print(MP305.list_devices())"` — confirm the
+   device shows up under VID `0x28E9` and note its `usage_page`/`usage`.
+2. `psu.hardware_info()` — if the de-stuffed name/version look right, framing is correct.
+3. If reads time out: the device may not use a fixed 64-byte report. Try
+   `MP305(dev, report_size=N)` with other sizes, or pass an explicit interface `path`.
+4. `read_state()` polls with the realtime command (`0xBD`) like the app; if that yields
+   nothing, try `read_state(realtime=False)` (`0xC2`).
+
+## Tests
+
+```bash
+python tests/test_protocol.py        # or: pytest
+```
+These validate the framing/checksum/stuffing and unit decoding without hardware.
+
+## BLE (not implemented here)
+
+The MP305 also speaks the **same command set over BLE** (used by the PolyLink phone app):
+GATT service `0000af00-…`, characteristic `af01` for command/notify, `af02` for the
+binding handshake and chunked writes, plus `fee0/fee1` for OTA. BLE frames drop the
+length/0xAA/checksum wrapper and are just `[0x12, cmd, …payload]`. Wrapping that with
+`bleak` would reuse `responses.py` directly — left as a future addition.

pymp305-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pymp305/__init__.py,sha256=3j8i7vp8BjVDCpGwJhRieLrfOxGKxqWRQM07pOjfifA,986
+pymp305/device.py,sha256=AGTjbciKgr1XWdBcx3s55bAGOHOJA9HpurzEjVACs0c,10338
+pymp305/protocol.py,sha256=RITOhQWmeHuNz3r8FTVNcD-KbncEcmgW-PVSC0Sfcjk,4403
+pymp305/responses.py,sha256=-LkXHmsVaqnA3TlPkElSOdsWetxsW5Q16ZyWFfvDt4s,6152
+pymp305-0.1.0.dist-info/METADATA,sha256=gaS-7acvEnniIxG8T14h-SfEW0kKjIJVXo3HY3J2XIM,5375
+pymp305-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pymp305-0.1.0.dist-info/top_level.txt,sha256=muKwjJV2O7m9cNWU7x-drOeOmJcXwC0ePKJJ9DqQCjY,8
+pymp305-0.1.0.dist-info/RECORD,,

pymp305-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymp305-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pymp305