pmd-pycore 0.2.3__py3-none-any.whl

pmd_pycore/__init__.py

@@ -0,0 +1,15 @@
+# pmd_pycore/__init__.py
+
+from importlib.metadata import version as get_version, PackageNotFoundError
+from .version import __version__
+
+try:
+    installed_version = get_version("pmd-pycore")
+    if installed_version != __version__:
+        __version__ = installed_version
+except PackageNotFoundError:
+    pass  # Use the version from version.py
+
+from . import core
+
+__all__ = ["core", "__version__"]

pmd_pycore/core/__init__.py

@@ -0,0 +1,101 @@
+# pmd_pycore/core/__init__.py
+
+from .pmd2 import (
+    get_pmd2_ports,
+    find_pmd2_devices,
+    read_pmd2_uart,
+    read_pmd2_welcome_string,
+    read_pmd2_device,
+    read_pmd2_uid,
+    read_pmd2_sensors,
+    translate_pmd2_sensor_struct,
+    translate_pmd2_aggregate_power,
+    translate_pmd2_chip_sensors,
+    translate_pmd2x_hpwr_temperatures,
+    PMD2_CHANNELS,
+    PMD2X_CHANNELS,
+    PMD2VendorDataStruct,
+    PMD2PowerSensor,
+    PMD2SensorStruct,
+    PMD2XSensorStruct,
+    PMD2_CMD,
+    PMD2_VENDOR_ID,
+    PMD2_PRODUCT_ID,
+    PMD2X_PRODUCT_ID,
+    PMD2_PRODUCT_STRING,
+    PMD2X_PRODUCT_STRING,
+    PMD2_SENSOR_POWER_NUM,
+    PMD2X_SENSOR_POWER_NUM,
+    PMD2X_SENSOR_TS_NUM,
+    PMD2X_TS_IN,
+    PMD2X_TS_OUT,
+    PMD2X_TS_NOT_CONNECTED,
+)
+from .pmdusb import (
+    get_pmdusb_ports,
+    read_pmdusb_uart,
+    read_pmdusb_welcome_string,
+    read_pmdusb_id,
+    read_pmdusb_sensors,
+    translate_pmdusb_sensors,
+    translate_pmdusb_aggregate_power,
+    PMDUSBIdStruct,
+    PMDUSBChannelValues,
+    PMDUSBSensorStruct,
+    PMDUSB_CMD,
+    PMDUSB_VENDOR_ID,
+    PMDUSB_PRODUCT_ID,
+    PMDUSB_PRODUCT_STRING,
+    PMDUSB_CHANNEL_NUM,
+    PMDUSB_CHANNELS,
+)
+
+__all__ = [
+    # pmd2
+    "get_pmd2_ports",
+    "find_pmd2_devices",
+    "read_pmd2_uart",
+    "read_pmd2_welcome_string",
+    "read_pmd2_device",
+    "read_pmd2_uid",
+    "read_pmd2_sensors",
+    "translate_pmd2_sensor_struct",
+    "translate_pmd2_aggregate_power",
+    "translate_pmd2_chip_sensors",
+    "translate_pmd2x_hpwr_temperatures",
+    "PMD2_CHANNELS",
+    "PMD2X_CHANNELS",
+    "PMD2VendorDataStruct",
+    "PMD2PowerSensor",
+    "PMD2SensorStruct",
+    "PMD2XSensorStruct",
+    "PMD2_CMD",
+    "PMD2_VENDOR_ID",
+    "PMD2_PRODUCT_ID",
+    "PMD2X_PRODUCT_ID",
+    "PMD2_PRODUCT_STRING",
+    "PMD2X_PRODUCT_STRING",
+    "PMD2_SENSOR_POWER_NUM",
+    "PMD2X_SENSOR_POWER_NUM",
+    "PMD2X_SENSOR_TS_NUM",
+    "PMD2X_TS_IN",
+    "PMD2X_TS_OUT",
+    "PMD2X_TS_NOT_CONNECTED",
+    # pmdusb
+    "get_pmdusb_ports",
+    "read_pmdusb_uart",
+    "read_pmdusb_welcome_string",
+    "read_pmdusb_id",
+    "read_pmdusb_sensors",
+    "translate_pmdusb_sensors",
+    "translate_pmdusb_aggregate_power",
+    "PMDUSBIdStruct",
+    "PMDUSBChannelValues",
+    "PMDUSBSensorStruct",
+    "PMDUSB_CMD",
+    "PMDUSB_VENDOR_ID",
+    "PMDUSB_PRODUCT_ID",
+    "PMDUSB_PRODUCT_STRING",
+    "PMDUSB_CHANNEL_NUM",
+    "PMDUSB_CHANNELS",
+]

pmd_pycore/core/pmd2.py

@@ -0,0 +1,407 @@
+"""
+Wire-format structures, serial I/O, and sensor translation for ElmorLabs PMD2/PMD2X.
+
+Example:
+    >>> from pmd_pycore.core import get_pmd2_ports, read_pmd2_device, read_pmd2_sensors
+    >>> ports = get_pmd2_ports()
+    >>> if ports:
+    >>>     import serial
+    >>>     ser = serial.Serial(ports[0]['port'], 115200, timeout=1,
+    >>>                          rtscts=False, dsrdtr=False)
+    >>>     info = read_pmd2_device(ser)
+    >>>     sensors = read_pmd2_sensors(ser, info['ProductId'])
+    >>>     ser.close()
+"""
+
+import os
+import sys
+import time
+import logging
+import serial
+import serial.tools.list_ports
+from ctypes import LittleEndianStructure, c_uint8, c_int16, c_int32, c_uint16, sizeof
+from enum import IntEnum
+from typing import List, Dict, Optional, Union
+
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
+logger = logging.getLogger("pmd_pycore.core.pmd2")
+logger.setLevel(getattr(logging, LOG_LEVEL, logging.INFO))
+
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+
+# --- Structures ---
+
+PMD2_VENDOR_ID = 0xEE
+PMD2_PRODUCT_ID = 0x15
+PMD2X_PRODUCT_ID = 0x17
+
+PMD2_PRODUCT_STRING = "ElmorLabs PMD2"
+PMD2X_PRODUCT_STRING = "ElmorLabs PMD2X"
+
+PMD2_SENSOR_POWER_NUM = 10
+PMD2X_SENSOR_POWER_NUM = 16
+PMD2X_SENSOR_TS_NUM = 2
+
+PMD2X_TS_IN = 0   # 12VHPWR connector temperature sensor, cable side
+PMD2X_TS_OUT = 1  # 12VHPWR connector temperature sensor, PSU/device side
+PMD2X_TS_NOT_CONNECTED = 0x7FFF
+
+
+class PMD2_CMD(IntEnum):
+    """USB_CMD, per PMD2-FW's pmd2.h (private repo).
+
+    CMD_READ_DEVICE_DATA is declared there but has no case in the device's
+    CDC_Receive_FS dispatch (usbd_cdc_if.c) -- sending it is a no-op.
+    """
+
+    CMD_WELCOME = 0
+    CMD_READ_VENDOR_DATA = 1
+    CMD_READ_UID = 2
+    CMD_READ_DEVICE_DATA = 3
+    CMD_READ_SENSOR_VALUES = 4
+    CMD_WRITE_CONT_TX = 5
+    CMD_READ_CONFIG = 6
+    CMD_WRITE_CONFIG = 7
+    CMD_RESET = 0xF0
+    CMD_BOOTLOADER = 0xF1
+    CMD_MCU_CMD = 0xF2
+    CMD_NOP = 0xFF
+
+    def toByte(self) -> bytes:
+        return self.value.to_bytes(1, byteorder="little")
+
+
+class PMD2VendorDataStruct(LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("VendorId", c_uint8),
+        ("ProductId", c_uint8),
+        ("FwVersion", c_uint8),
+    ]
+
+    def __str__(self):
+        return (
+            f"VendorId: {hex(self.VendorId)}, "
+            f"ProductId: {hex(self.ProductId)}, "
+            f"FwVersion: {hex(self.FwVersion)}"
+        )
+
+
+class PMD2PowerSensor(LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("Voltage", c_int16),
+        ("Current", c_int32),
+        ("Power", c_int32),
+    ]
+
+    def __str__(self):
+        return f"Voltage: {self.Voltage}, Current: {self.Current}, Power: {self.Power}"
+
+
+class PMD2SensorStruct(LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("Vdd", c_uint16),
+        ("Tchip", c_int16),
+        ("PowerReadings", PMD2PowerSensor * PMD2_SENSOR_POWER_NUM),
+        ("EpsPower", c_uint16),
+        ("PciePower", c_uint16),
+        ("MbPower", c_uint16),
+        ("TotalPower", c_uint16),
+        ("Ocp", c_uint8 * PMD2_SENSOR_POWER_NUM),
+    ]
+
+
+class PMD2XSensorStruct(LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("Vdd", c_uint16),
+        ("Tchip", c_int16),
+        ("Ts", c_int16 * PMD2X_SENSOR_TS_NUM),
+        ("PowerReadings", PMD2PowerSensor * PMD2X_SENSOR_POWER_NUM),
+        ("EpsPower", c_uint16),
+        ("PciePower", c_uint16),
+        ("MbPower", c_uint16),
+        ("TotalPower", c_uint16),
+        ("Ocp", c_uint8 * PMD2X_SENSOR_POWER_NUM),
+    ]
+
+
+# --- Serial I/O ---
+
+# VID:PID shared by PMD2 and PMD2X (checked case-insensitively).
+_PMD2_VID_PID = "VID:PID=0483:5740"
+
+# Longest welcome string a device can push on connect.
+_WELCOME_PUSH_MAX_LEN = max(len(PMD2_PRODUCT_STRING), len(PMD2X_PRODUCT_STRING)) + 1
+
+# CMD_WELCOME replies with BuildData.ProductName truncated to 15 bytes
+# (CDC_Transmit_FS((void*)BuildData.ProductName, 15) in usbd_cdc_if.c) --
+# a fixed size independent of the unsolicited DTR-triggered push above.
+_WELCOME_REPLY_LEN = 15
+
+_UID_LEN = 12
+
+
+def get_pmd2_ports() -> List[Dict[str, str]]:
+    """Return all candidate PMD2/PMD2X COM ports without opening them.
+
+    Returns:
+        List[Dict[str, str]]: List of dicts with a 'port' key, e.g. [{'port': 'COM3'}].
+    """
+    try:
+        ports = serial.tools.list_ports.comports()
+    except serial.SerialException as e:
+        logger.error("Failed to enumerate serial ports: %s", e)
+        raise
+
+    pmd2_ports = []
+    for p in ports:
+        if _PMD2_VID_PID in p.hwid.upper():
+            pmd2_ports.append({"port": p.device})
+    return pmd2_ports
+
+
+def _drain_pmd2_welcome_push(ser: serial.Serial) -> Optional[str]:
+    """Read and decode the unsolicited welcome string a device pushes after DTR is asserted."""
+    buffer = ser.read(_WELCOME_PUSH_MAX_LEN)
+    try:
+        return buffer.decode("ascii").rstrip("\x00")
+    except UnicodeDecodeError:
+        return None
+
+
+def find_pmd2_devices() -> List[Dict[str, str]]:
+    """Scan and return all connected PMD2/PMD2X devices with identity info.
+
+    Returns:
+        List[Dict[str, str]]: List of dicts with 'port', 'product_id', 'fw' keys.
+
+    Note:
+        This opens and closes a serial connection per candidate port.
+    """
+    devices = []
+    for port_info in get_pmd2_ports():
+        port = port_info["port"]
+        product_id, fw = "?", "?"
+        try:
+            with serial.Serial(port, 115200, timeout=1, rtscts=False, dsrdtr=False) as ser:
+                ser.dtr = True
+                _drain_pmd2_welcome_push(ser)
+                device_info = read_pmd2_device(ser)
+                if device_info:
+                    product_id = device_info["ProductId"]
+                    fw = device_info["FwVersion"]
+            logger.info("Found device on %s: ProductId=%s, FW=%s", port, product_id, fw)
+        except serial.SerialException as e:
+            logger.warning("Failed to open serial port %s: %s", port, e)
+        except Exception as e:
+            logger.warning("Failed to read device on %s: %s", port, e)
+        devices.append({"port": port, "product_id": product_id, "fw": fw})
+    return devices
+
+
+def read_pmd2_uart(ser: serial.Serial, cmd: PMD2_CMD, size: int) -> Optional[bytes]:
+    """Send a command and read `size` bytes from the device.
+
+    Returns:
+        Optional[bytes]: Raw bytes read, or None if the read was incomplete.
+    """
+    ser.reset_input_buffer()
+    ser.write(cmd.toByte())
+    # Without a short gap the device occasionally hasn't queued its response
+    # yet when we read. 2ms was 0/5000 on a PMD2X but 2-3% failures on a
+    # PMD2 (different unit/firmware); 5ms was 0/5000 on both -- cheap
+    # insurance against a read that otherwise blocks for the full port
+    # timeout before coming back empty.
+    time.sleep(0.005)
+    buffer = ser.read(size)
+    if len(buffer) != size:
+        logger.warning("UART read incomplete: expected %d, got %d bytes", size, len(buffer))
+        return None
+    return buffer
+
+
+def read_pmd2_device(ser: serial.Serial) -> Optional[Dict[str, int]]:
+    """Read and validate vendor/product/firmware info from the device.
+
+    Returns:
+        Optional[Dict[str, int]]: Dict with 'VendorId', 'ProductId', 'FwVersion',
+            or None if the read failed or the vendor ID didn't match.
+    """
+    buffer = read_pmd2_uart(ser, PMD2_CMD.CMD_READ_VENDOR_DATA, sizeof(PMD2VendorDataStruct))
+    if buffer is None:
+        return None
+
+    vendor_struct = PMD2VendorDataStruct.from_buffer_copy(buffer)
+    if vendor_struct.VendorId != PMD2_VENDOR_ID or vendor_struct.ProductId not in (
+        PMD2_PRODUCT_ID,
+        PMD2X_PRODUCT_ID,
+    ):
+        logger.warning("Unexpected vendor data: %s", vendor_struct)
+        return None
+
+    return {
+        "VendorId": vendor_struct.VendorId,
+        "ProductId": vendor_struct.ProductId,
+        "FwVersion": vendor_struct.FwVersion,
+    }
+
+
+def read_pmd2_welcome_string(ser: serial.Serial) -> Optional[str]:
+    """Send CMD_WELCOME and return the device's product name.
+
+    Returns:
+        Optional[str]: Decoded product name, or None if the read failed.
+    """
+    buffer = read_pmd2_uart(ser, PMD2_CMD.CMD_WELCOME, _WELCOME_REPLY_LEN)
+    if buffer is None:
+        return None
+    try:
+        return buffer.decode("ascii").rstrip("\x00")
+    except UnicodeDecodeError:
+        logger.warning("Failed to decode welcome string: %r", buffer)
+        return None
+
+
+def read_pmd2_uid(ser: serial.Serial) -> Optional[str]:
+    """Read the device's unique ID (the STM32's hardware UID).
+
+    Returns:
+        Optional[str]: UID as an uppercase hex string, or None if the read failed.
+    """
+    buffer = read_pmd2_uart(ser, PMD2_CMD.CMD_READ_UID, _UID_LEN)
+    if buffer is None:
+        return None
+    return buffer.hex().upper()
+
+
+def read_pmd2_sensors(
+    ser: serial.Serial,
+    product_id: int,
+) -> Optional[Union[PMD2SensorStruct, PMD2XSensorStruct]]:
+    """Read all sensor values from the device.
+
+    Args:
+        ser (serial.Serial): Opened serial connection to the device.
+        product_id (int): PMD2_PRODUCT_ID or PMD2X_PRODUCT_ID, selecting which
+            sensor structure to decode the response as.
+
+    Returns:
+        Optional[Union[PMD2SensorStruct, PMD2XSensorStruct]]: Decoded sensor
+            structure, or None if the read failed.
+    """
+    struct_type = PMD2XSensorStruct if product_id == PMD2X_PRODUCT_ID else PMD2SensorStruct
+    buffer = read_pmd2_uart(ser, PMD2_CMD.CMD_READ_SENSOR_VALUES, sizeof(struct_type))
+    if buffer is None:
+        logger.warning("Failed to read sensors from device")
+        return None
+    return struct_type.from_buffer_copy(buffer)
+
+
+# --- Sensor translation ---
+
+# Channel index -> rail name, for each product. Matches SENSOR_POWER_* in
+# the PMD2-FW pmd2.h header (private repo).
+# Index 4 ("HPWR"/"HPWR1") is computed by the firmware itself from the six
+# wire channels (10-15) -- it isn't something the host needs to average.
+PMD2_CHANNELS = {
+    0: "12V", 1: "5V", 2: "5VSB", 3: "3.3V",
+    4: "HPWR",
+    5: "EPS1", 6: "EPS2",
+    7: "PCIE1", 8: "PCIE2", 9: "PCIE3",
+}
+
+PMD2X_CHANNELS = {
+    0: "12V", 1: "5V", 2: "5VSB", 3: "3.3V",
+    4: "HPWR",
+    5: "EPS1", 6: "EPS2",
+    7: "PCIE1", 8: "PCIE2", 9: "PCIE3",
+    10: "HPWR_W1", 11: "HPWR_W2", 12: "HPWR_W3",
+    13: "HPWR_W4", 14: "HPWR_W5", 15: "HPWR_W6",
+}
+
+
+def _pmd2_reading(voltage: int, current: int, power: int) -> Dict[str, float]:
+    return {"voltage": voltage / 1000, "current": current / 1000, "power": power / 1000}
+
+
+def translate_pmd2_sensor_struct(
+    sensors: Union[PMD2SensorStruct, PMD2XSensorStruct],
+    product_id: int,
+) -> Dict[str, Dict[str, float]]:
+    """Convert a raw sensor struct into a dict of rail name -> {voltage, current, power} (SI units).
+
+    Args:
+        sensors: Decoded sensor struct from read_pmd2_sensors().
+        product_id: PMD2_PRODUCT_ID or PMD2X_PRODUCT_ID.
+
+    Returns:
+        Dict[str, Dict[str, float]]: Rail name -> reading.
+    """
+    channels = PMD2_CHANNELS if product_id == PMD2_PRODUCT_ID else PMD2X_CHANNELS
+    readings = sensors.PowerReadings
+
+    return {
+        name: _pmd2_reading(readings[idx].Voltage, readings[idx].Current, readings[idx].Power)
+        for idx, name in channels.items()
+    }
+
+
+def translate_pmd2_aggregate_power(
+    sensors: Union[PMD2SensorStruct, PMD2XSensorStruct],
+) -> Dict[str, float]:
+    """Read the firmware-computed power aggregates, in watts.
+
+    The device sums these on-board rather than requiring the host to add up
+    individual rails:
+        - eps: EPS/CPU power (EPS1 + EPS2)
+        - pcie: PCIe/GPU power (PCIE1-3, plus HPWR on PMD2X)
+        - mb: motherboard power (ATX24 rails: 12V/5V/5VSB/3.3V)
+        - total: sum of all of the above
+    """
+    return {
+        "eps": sensors.EpsPower / 1000,
+        "pcie": sensors.PciePower / 1000,
+        "mb": sensors.MbPower / 1000,
+        "total": sensors.TotalPower / 1000,
+    }
+
+
+def translate_pmd2_chip_sensors(sensors: Union[PMD2SensorStruct, PMD2XSensorStruct]) -> Dict[str, float]:
+    """Read the device's own supply voltage and chip temperature.
+
+    Tchip is in tenths of a degree C, per sensor.c's TH_GetTs()/
+    __LL_ADC_CALC_TEMPERATURE() usage -- confirmed against a live device
+    (raw 320 read back as a plausible 32.0 C, not 320 C).
+
+    Returns:
+        Dict[str, float]: 'vdd' in volts, 'tchip' in degrees Celsius.
+    """
+    return {"vdd": sensors.Vdd / 1000, "tchip": sensors.Tchip / 10}
+
+
+def translate_pmd2x_hpwr_temperatures(sensors: PMD2XSensorStruct) -> Dict[str, Optional[float]]:
+    """Read the 12VHPWR connector's two thermistor temperatures (PMD2X only), in Celsius.
+
+    Ts[] comes from TH_GetTs() (see PMD2-FW's th.c/th_lut.h), which is also
+    in tenths of a degree C. 0x7FFF means the thermistor read out of range,
+    i.e. nothing is plugged in.
+
+    Returns:
+        Dict[str, Optional[float]]: 'ts_in' and 'ts_out'; either is None if
+            that thermistor is not connected.
+    """
+    def _value(raw: int) -> Optional[float]:
+        return None if raw == PMD2X_TS_NOT_CONNECTED else raw / 10
+
+    return {
+        "ts_in": _value(sensors.Ts[PMD2X_TS_IN]),
+        "ts_out": _value(sensors.Ts[PMD2X_TS_OUT]),
+    }

pmd_pycore/core/pmdusb.py

@@ -0,0 +1,264 @@
+"""
+Wire-format structures, serial I/O, and sensor translation for the ElmorLabs PMD-USB.
+
+PMD-USB is a different device family from PMD2/PMD2X: it connects via a
+CH340 USB-serial bridge rather than an STM32 CDC-ACM VCP, and uses its own
+command numbering and sensor layout (PCIE1/PCIE2/EPS1/EPS2 only -- no ATX24
+rails, no 12VHPWR). There is no public firmware source; this was ported
+from and verified against:
+https://github.com/ElmorLabs/PMDLogger (C# reference, PMD_USB_Device.cs)
+https://github.com/ElmorLabs/PMD-USB (official GUI app, FormPMD.cs)
+https://github.com/ElmorLabs/pmd-usb-serial-interface-fast
+https://github.com/bjorntas/elmorlabs-pmd-usb-serial-interface
+
+Example:
+    >>> from pmd_pycore.core import get_pmdusb_ports, read_pmdusb_id, read_pmdusb_sensors
+    >>> ports = get_pmdusb_ports()
+    >>> if ports:
+    >>>     import serial
+    >>>     ser = serial.Serial(ports[0]['port'], 115200, timeout=1)
+    >>>     info = read_pmdusb_id(ser)
+    >>>     sensors = read_pmdusb_sensors(ser)
+    >>>     ser.close()
+"""
+
+import os
+import sys
+import time
+import logging
+import serial
+import serial.tools.list_ports
+from ctypes import LittleEndianStructure, c_uint8, c_int16, sizeof
+from enum import IntEnum
+from typing import List, Dict, Optional
+
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
+logger = logging.getLogger("pmd_pycore.core.pmdusb")
+logger.setLevel(getattr(logging, LOG_LEVEL, logging.INFO))
+
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+
+# --- Structures ---
+
+PMDUSB_VENDOR_ID = 0xEE
+PMDUSB_PRODUCT_ID = 0x0A
+
+PMDUSB_PRODUCT_STRING = "ElmorLabs PMD-USB"
+
+PMDUSB_CHANNEL_NUM = 4
+
+
+class PMDUSB_CMD(IntEnum):
+    """UART_CMD, per PMDLogger's PMD_USB_Device.cs and the official GUI app's FormPMD.cs."""
+
+    CMD_WELCOME = 0
+    CMD_READ_ID = 1
+    CMD_READ_SENSORS = 2
+    CMD_READ_SENSOR_VALUES = 3
+    CMD_READ_CONFIG = 4
+    CMD_WRITE_CONFIG = 5
+    CMD_READ_ADC = 6
+    CMD_WRITE_CONFIG_CONT_TX = 7
+    CMD_WRITE_CONFIG_UART = 8
+    CMD_RESET = 0xF0
+    CMD_BOOTLOADER = 0xF1
+    CMD_NOP = 0xFF
+
+    def toByte(self) -> bytes:
+        return self.value.to_bytes(1, byteorder="little")
+
+
+class PMDUSBIdStruct(LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("VendorId", c_uint8),
+        ("ProductId", c_uint8),
+        ("FwVersion", c_uint8),
+    ]
+
+    def __str__(self):
+        return (
+            f"VendorId: {hex(self.VendorId)}, "
+            f"ProductId: {hex(self.ProductId)}, "
+            f"FwVersion: {hex(self.FwVersion)}"
+        )
+
+
+class PMDUSBChannelValues(LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("Voltage", c_int16),
+        ("Current", c_int16),
+    ]
+
+
+class PMDUSBSensorStruct(LittleEndianStructure):
+    """CMD_READ_SENSOR_VALUES reply: 4 channels x {Voltage, Current}, 16 bytes total.
+
+    Voltage is raw*0.01 V, current is raw*0.1 A -- plain signed int16.
+    Already calibrated on-device (confirmed against the official GUI app's
+    live monitoring loop, which uses this command directly with no
+    client-side offset/gain correction); CMD_READ_ADC's raw-ADC path isn't
+    needed or implemented here.
+    """
+
+    _pack_ = 1
+    _fields_ = [
+        ("Channels", PMDUSBChannelValues * PMDUSB_CHANNEL_NUM),
+    ]
+
+
+# Channel index -> rail name, per PMDLogger's PMD_USB_Device constructor and
+# bjorntas's elmorlabs-pmd-usb-serial-interface main.py.
+PMDUSB_CHANNELS = {
+    0: "PCIE1",
+    1: "PCIE2",
+    2: "EPS1",
+    3: "EPS2",
+}
+
+# Channel indices feeding each aggregate, matching the official PMD-USB GUI
+# app's update_task() (FormPMD.cs): PCIE1+PCIE2 -> GPU, EPS1+EPS2 -> CPU.
+_GPU_CHANNELS = (0, 1)
+_CPU_CHANNELS = (2, 3)
+
+
+# --- Serial I/O ---
+
+# PMD-USB uses a CH340 USB-serial bridge, not the STM32 VCP that PMD2/PMD2X
+# use -- a different VID:PID entirely.
+_PMDUSB_VID_PID = "VID:PID=1A86:7523"
+
+_WELCOME_REPLY_LEN = len(PMDUSB_PRODUCT_STRING)
+
+
+def get_pmdusb_ports() -> List[Dict[str, str]]:
+    """Return all candidate PMD-USB COM ports without opening them.
+
+    Returns:
+        List[Dict[str, str]]: List of dicts with a 'port' key, e.g. [{'port': 'COM3'}].
+    """
+    try:
+        ports = serial.tools.list_ports.comports()
+    except serial.SerialException as e:
+        logger.error("Failed to enumerate serial ports: %s", e)
+        raise
+
+    pmdusb_ports = []
+    for p in ports:
+        if _PMDUSB_VID_PID in p.hwid.upper():
+            pmdusb_ports.append({"port": p.device})
+    return pmdusb_ports
+
+
+def read_pmdusb_uart(ser: serial.Serial, cmd: PMDUSB_CMD, size: int) -> Optional[bytes]:
+    """Send a command and read `size` bytes from the device.
+
+    Returns:
+        Optional[bytes]: Raw bytes read, or None if the read was incomplete.
+    """
+    ser.reset_input_buffer()
+    ser.write(cmd.toByte())
+    # Measured 0/5000 failures at 0ms across 5 trials against a live
+    # PMD-USB (its CH340 bridge responds faster than PMD2/PMD2X's STM32
+    # CDC-ACM stack did), but a small margin is kept anyway -- that same
+    # "0ms looked fine" read on PMD2/PMD2X didn't hold up under more
+    # sustained testing, and a cheap sleep costs far less than a stall on
+    # the read timeout if it's ever wrong on different hardware.
+    time.sleep(0.002)
+    buffer = ser.read(size)
+    if len(buffer) != size:
+        logger.warning("UART read incomplete: expected %d, got %d bytes", size, len(buffer))
+        return None
+    return buffer
+
+
+def read_pmdusb_welcome_string(ser: serial.Serial) -> Optional[str]:
+    """Send CMD_WELCOME and return the device's product name.
+
+    Returns:
+        Optional[str]: Decoded product name, or None if the read failed.
+    """
+    buffer = read_pmdusb_uart(ser, PMDUSB_CMD.CMD_WELCOME, _WELCOME_REPLY_LEN)
+    if buffer is None:
+        return None
+    try:
+        return buffer.decode("ascii").rstrip("\x00")
+    except UnicodeDecodeError:
+        logger.warning("Failed to decode welcome string: %r", buffer)
+        return None
+
+
+def read_pmdusb_id(ser: serial.Serial) -> Optional[Dict[str, int]]:
+    """Read and validate vendor/product/firmware info from the device.
+
+    Returns:
+        Optional[Dict[str, int]]: Dict with 'VendorId', 'ProductId', 'FwVersion',
+            or None if the read failed or the vendor/product ID didn't match.
+    """
+    buffer = read_pmdusb_uart(ser, PMDUSB_CMD.CMD_READ_ID, sizeof(PMDUSBIdStruct))
+    if buffer is None:
+        return None
+
+    id_struct = PMDUSBIdStruct.from_buffer_copy(buffer)
+    if id_struct.VendorId != PMDUSB_VENDOR_ID or id_struct.ProductId != PMDUSB_PRODUCT_ID:
+        logger.warning("Unexpected vendor data: %s", id_struct)
+        return None
+
+    return {
+        "VendorId": id_struct.VendorId,
+        "ProductId": id_struct.ProductId,
+        "FwVersion": id_struct.FwVersion,
+    }
+
+
+def read_pmdusb_sensors(ser: serial.Serial) -> Optional[PMDUSBSensorStruct]:
+    """Read all sensor values from the device.
+
+    Returns:
+        Optional[PMDUSBSensorStruct]: Decoded sensor structure, or None if the
+            read failed.
+    """
+    buffer = read_pmdusb_uart(ser, PMDUSB_CMD.CMD_READ_SENSOR_VALUES, sizeof(PMDUSBSensorStruct))
+    if buffer is None:
+        logger.warning("Failed to read sensors from device")
+        return None
+    return PMDUSBSensorStruct.from_buffer_copy(buffer)
+
+
+# --- Sensor translation ---
+
+def translate_pmdusb_sensors(sensors: PMDUSBSensorStruct) -> Dict[str, Dict[str, float]]:
+    """Convert a raw PMD-USB sensor struct into a dict of channel name -> reading.
+
+    Returns:
+        Dict[str, Dict[str, float]]: Channel name -> {voltage, current, power}.
+    """
+    result = {}
+    for idx, name in PMDUSB_CHANNELS.items():
+        channel = sensors.Channels[idx]
+        voltage = channel.Voltage * 0.01
+        current = channel.Current * 0.1
+        result[name] = {"voltage": voltage, "current": current, "power": voltage * current}
+    return result
+
+
+def translate_pmdusb_aggregate_power(sensors: PMDUSBSensorStruct) -> Dict[str, float]:
+    """Compute GPU/CPU/Total power from the per-channel readings, in watts.
+
+    Unlike PMD2/PMD2X, the PMD-USB firmware doesn't compute these aggregates
+    on-device -- they're derived client-side here, matching the official
+    GUI app: gpu = PCIE1 + PCIE2, cpu = EPS1 + EPS2, total = gpu + cpu.
+    """
+    readings = translate_pmdusb_sensors(sensors)
+    channel_names = list(PMDUSB_CHANNELS.values())
+
+    gpu = sum(readings[channel_names[i]]["power"] for i in _GPU_CHANNELS)
+    cpu = sum(readings[channel_names[i]]["power"] for i in _CPU_CHANNELS)
+
+    return {"gpu": gpu, "cpu": cpu, "total": gpu + cpu}

pmd_pycore/version.py

@@ -0,0 +1,5 @@
+"""
+Version information for pmd-pycore
+"""
+
+__version__ = "0.2.3"

pmd_pycore-0.2.3.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: pmd-pycore
+Version: 0.2.3
+Summary: PMD PyCore - Python Interface for ElmorLabs PMD2/PMD2X/PMD-USB
+Home-page: https://github.com/ElmorLabs-P1/pmd-pycore
+Author: Pieter Plaisier
+Author-email: Pieter Plaisier <pieter@hanweiconsulting.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ElmorLabs-P1/pmd-pycore
+Project-URL: Issues, https://github.com/ElmorLabs-P1/pmd-pycore/issues
+Keywords: telemetry,hardware,pmd2,pmd-usb,elmorlabs,sensors
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+
+# pmd-pycore
+
+Python interface for ElmorLabs PMD power measurement devices (PMD2, PMD2X, PMD-USB).
+
+## Supported devices
+
+| [PMD-USB](https://elmorlabs.com/product/elmorlabs-pmd-usb-power-measurement-device-with-usb/) *(discontinued)* | [PMD2](https://elmorlabs.com/product/elmorlabs-pmd2/) *(discontinued)* | [PMD2X](https://elmorlabs.com/product/elmorlabs-pmd2x-power-measurement-device-2x/) *(current)* |
+|:---:|:---:|:---:|
+| <img src="https://elmorlabs.com/wp-content/uploads/2022/05/with_case-scaled.jpg" width="220"> | <img src="https://elmorlabs.com/wp-content/uploads/2024/10/IMG_0216-scaled.jpg" width="220"> | <img src="https://elmorlabs.com/wp-content/uploads/2026/05/IMG_7900-scaled.jpg" width="220"> |
+| 4 channels (PCIE1, PCIE2, EPS1, EPS2) over a CH340 USB-serial bridge. No ATX24/motherboard rail, no 12VHPWR. | 2x EPS, 3x PCIe, 1x ATX24, 1x 12VHPWR connector. STM32 USB-serial interface. Superseded by PMD2X. | Same rail set as PMD2, plus per-wire 12VHPWR monitoring and connector thermistors. |
+
+PMD-USB was superseded by PMD2, which was in turn superseded by PMD2X -- the only one of the
+three still sold. All three measure voltage/current/power on CPU, GPU, and (PMD2/PMD2X only)
+motherboard power cables, with an OLED display and USB connection to a PC for logging.
+
+## Pre-requisites
+- Python >= 3.11, with pyserial (and numpy for the example scripts)
+- PMD-USB uses a CH340 USB-serial chip. Linux has an in-kernel driver for it (binds
+  automatically, nothing to install). **Windows does not ship one** -- if the device shows up
+  in Device Manager but never gets a COM port, install the CH340/CH341 driver from the chip
+  manufacturer's site ([wch-ic.com](https://www.wch-ic.com/), search "CH340"/"CH341") and
+  replug. PMD2/PMD2X use an STM32 VCP instead and don't need a separate driver on either OS.
+
+## Install
+
+```
+pip install -r requirements.txt
+pip install -e .
+```
+
+## Usage
+
+### PMD2 / PMD2X
+
+```python
+from pmd_pycore.core import (
+    get_pmd2_ports,
+    read_pmd2_welcome_string,
+    read_pmd2_device,
+    read_pmd2_uid,
+    read_pmd2_sensors,
+    translate_pmd2_sensor_struct,
+)
+import serial
+
+port = get_pmd2_ports()[0]["port"]
+ser = serial.Serial(port, 115200, timeout=1, rtscts=False, dsrdtr=False)
+
+device_info = read_pmd2_device(ser)
+sensors = read_pmd2_sensors(ser, device_info["ProductId"])
+readings = translate_pmd2_sensor_struct(sensors, device_info["ProductId"])
+print(readings["12V"])  # {'voltage': 12.0, 'current': 1.0, 'power': 12.0}
+```
+
+Currently implemented are the device's read-only commands:
+`CMD_WELCOME` (`read_pmd2_welcome_string`), `CMD_READ_VENDOR_DATA` (`read_pmd2_device`),
+`CMD_READ_UID` (`read_pmd2_uid`), and `CMD_READ_SENSOR_VALUES` (`read_pmd2_sensors`).
+Writing/action commands (continuous TX, config read/write, reset, bootloader) are not
+implemented.
+
+See `examples/read_sensors.py` — a polling/averaging loop that mirrors the original sample script.
+
+### PMD-USB
+
+PMD-USB is a different device family -- a CH340 USB-serial bridge rather than PMD2/PMD2X's STM32
+VCP, with its own command set and a simpler sensor set (PCIE1, PCIE2, EPS1, EPS2 only; no ATX24
+rails, no 12VHPWR). There's no firmware source for it, so this was ported from and verified
+against the reference implementations linked below plus a real device.
+
+```python
+from pmd_pycore.core import get_pmdusb_ports, read_pmdusb_id, read_pmdusb_sensors, translate_pmdusb_sensors
+import serial
+
+port = get_pmdusb_ports()[0]["port"]
+ser = serial.Serial(port, 115200, timeout=1)
+
+device_info = read_pmdusb_id(ser)
+sensors = read_pmdusb_sensors(ser)
+readings = translate_pmdusb_sensors(sensors)
+print(readings["EPS1"])  # {'voltage': 12.0, 'current': 1.0, 'power': 12.0}
+```
+
+Implemented: `CMD_WELCOME` (`read_pmdusb_welcome_string`), `CMD_READ_ID` (`read_pmdusb_id`), and
+`CMD_READ_SENSOR_VALUES` (`read_pmdusb_sensors`/`translate_pmdusb_sensors`). This command already
+returns calibrated readings -- confirmed against the official PMD-USB GUI app's source, which
+uses it directly with no client-side calibration math -- so `CMD_READ_ADC`'s raw path isn't
+needed. `translate_pmdusb_aggregate_power` adds GPU/CPU/Total power (PCIE1+PCIE2 /  EPS1+EPS2 /
+sum), computed client-side the same way the official app does; PMD-USB's firmware doesn't
+compute these on-device the way PMD2/PMD2X's does.
+
+Note: PMD-USB has no per-unit UID/serial number anywhere -- not in the UART protocol (no command
+for it), and not at the USB level (the CH340 chip's serial number field reads empty on the
+device tested here). If you have more than one, there's no way to tell them apart besides which
+COM port they land on.
+
+See [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) for what's deliberately out of scope and why.
+
+## Examples
+
+- `examples/quickstart.py` — connect to the first device found, trying PMD2/PMD2X first and
+  falling back to PMD-USB, print its identity, and read sensor values once (for PMD2/PMD2X:
+  per-rail readings, firmware-computed aggregate power, chip health, and PMD2X's 12VHPWR
+  connector temperatures).
+- `examples/read_sensors.py` — a polling/averaging loop, refreshing in place, for whichever
+  device family is connected (same PMD2/PMD2X-first-then-PMD-USB detection as `quickstart.py`).
+
+## Status
+
+This repository is under active development at
+[ElmorLabs-P1/pmd-pycore](https://github.com/ElmorLabs-P1/pmd-pycore). It provides an installable
+`pmd_pycore` package (serial discovery, UART command helpers, sensor structures, and
+readable-unit translation for the supported devices), a test suite, and CI for tests and tagged
+releases.
+
+Tagged releases build an sdist/wheel and attach them to a GitHub Release. A PyPI-publish job is
+wired into the release workflow but not yet active -- it needs PyPI Trusted Publishing configured
+for this repo first (no credentials are stored in GitHub either way). Until that's set up,
+install from the GitHub Release assets or `pip install -e .` from a checkout.
+
+## Related repositories
+
+- [PMDLogger](https://github.com/ElmorLabs/PMDLogger) — C# reference implementation for PMD-USB
+  (there's no public PMD-USB firmware source); `PMD_USB_Device.cs` has the command set and sensor
+  scaling used here.
+- [PMD-USB](https://github.com/ElmorLabs/PMD-USB) — the official PMD-USB GUI app; `FormPMD.cs`
+  confirmed `CMD_READ_SENSOR_VALUES` is already calibrated and has the `CMD_READ_CONFIG` struct
+  layout.
+- [pmd-usb-serial-interface-fast](https://github.com/ElmorLabs/pmd-usb-serial-interface-fast) /
+  [elmorlabs-pmd-usb-serial-interface](https://github.com/bjorntas/elmorlabs-pmd-usb-serial-interface) —
+  Python sample scripts for PMD-USB, cross-checked against PMDLogger and a real device.

pmd_pycore-0.2.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+pmd_pycore/__init__.py,sha256=_eMxohfq3Rre4-AtzyY1XK2EuCx7YIkO-Y5aKqmH6ps,400
+pmd_pycore/version.py,sha256=OOGCofDv3M0OLYtA34LHnGR4QealaIU1hWXnl6tcCpM,66
+pmd_pycore/core/__init__.py,sha256=683DROQK8mv9Me4e87LgLo_GMOkkoaKXE_Qr4neRMBc,2390
+pmd_pycore/core/pmd2.py,sha256=8hti6tUW9YXDNTB7U3m5eQGcxQeF6mBfbXxbn36y0BY,13405
+pmd_pycore/core/pmdusb.py,sha256=BqHQ045QnXlIKzTmR7YgFaf4Z-tT2cqR_xR-qK3Gjxg,8713
+pmd_pycore-0.2.3.dist-info/METADATA,sha256=qeAG9zmZHTX8rZbLlzepHty_oPOYg9GU0nwbtdl3yn4,7501
+pmd_pycore-0.2.3.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pmd_pycore-0.2.3.dist-info/top_level.txt,sha256=_mxv8fuS_9QkcY0Xuy4t-Md2XJK_5Zi3WsiBSsS1g1Q,11
+pmd_pycore-0.2.3.dist-info/RECORD,,

pmd_pycore-0.2.3.dist-info/WHEEL

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

pmd_pycore-0.2.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+pmd_pycore