silabs-pycommander-core 1.0.0__py3-none-win_amd64.whl

pycommander_core/__init__.py

@@ -0,0 +1,25 @@
+"""
+License
+Copyright 2026 Silicon Laboratories Inc. www.silabs.com
+*******************************************************************************
+The licensor of this software is Silicon Laboratories Inc. Your use of this
+software is governed by the terms of Silicon Labs Master Software License
+Agreement (MSLA) available at
+www.silabs.com/about-us/legal/master-software-license-agreement. This
+software is distributed to you in Source Code format and is governed by the
+sections of the MSLA applicable to Source Code.
+*******************************************************************************
+"""
+
+# This is the entry point for the PyCommander package, when you do `import pycommander`
+from .commander_base import CommanderBase
+from .adapter_base import AdapterBase
+from .target import Target
+from ._version import __version__
+
+__all__ = [
+  "CommanderBase",
+  "AdapterBase",
+  "Target",
+  "__version__",
+]

pycommander_core/__main__.py

@@ -0,0 +1,18 @@
+"""
+License
+Copyright 2026 Silicon Laboratories Inc. www.silabs.com
+*******************************************************************************
+The licensor of this software is Silicon Laboratories Inc. Your use of this
+software is governed by the terms of Silicon Labs Master Software License
+Agreement (MSLA) available at
+www.silabs.com/about-us/legal/master-software-license-agreement. This
+software is distributed to you in Source Code format and is governed by the
+sections of the MSLA applicable to Source Code.
+*******************************************************************************
+"""
+
+# Entry point for `pycommander` command and `python3 -m pycommander`
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pycommander_core/_ensure_commander.py

@@ -0,0 +1,114 @@
+"""
+License
+Copyright 2026 Silicon Laboratories Inc. www.silabs.com
+*******************************************************************************
+The licensor of this software is Silicon Laboratories Inc. Your use of this
+software is governed by the terms of Silicon Labs Master Software License
+Agreement (MSLA) available at
+www.silabs.com/about-us/legal/master-software-license-agreement. This
+software is distributed to you in Source Code format and is governed by the
+sections of the MSLA applicable to Source Code.
+*******************************************************************************
+"""
+
+# Ensure that the Commander executable is present
+# This entails checking if the executable is present where it should be, and if not, extracting it from the
+# archive embedded in the package.
+import sys
+import hashlib
+import subprocess
+import shutil
+
+import importlib.resources as ir
+
+from pathlib import Path
+from platformdirs import user_cache_dir
+
+from .paths import EXECUTABLE_PATH_CLI, EXECUTABLE_PATH_GUI
+
+def ensure_commander(cli: bool = True) -> Path:
+  if cli:
+    package_name        = "pycommander_cli._archive"
+    executable_path     = EXECUTABLE_PATH_CLI
+  else:
+    package_name        = "pycommander_gui._archive"
+    executable_path     = EXECUTABLE_PATH_GUI
+  
+  cache_dir = Path(user_cache_dir(f"pycommander", "silabs"))
+  archive_path = Path(_find_executable_archive_resource(package_name))
+  archive_hash = _compute_hash_of_file(archive_path)
+
+  target_dir = cache_dir / archive_hash
+
+  if not target_dir.exists():
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    _extract_commander(archive_path, target_dir)
+
+  return Path(target_dir / executable_path)
+
+def _extract_commander(zip_file_path: Path, destination: Path) -> None:
+  # Remove the existing executable and stamp files, if they exist.
+  if destination.exists():
+    shutil.rmtree(destination, ignore_errors=True)
+
+  # Find the filename of the executable in the archive
+  with ir.as_file(zip_file_path) as zip_file:
+    if sys.platform == "darwin":
+      _extract_commander_macos(zip_file, destination)
+    elif sys.platform == "linux":
+      _extract_commander_linux(zip_file, destination)
+    elif sys.platform == "win32":
+      _extract_commander_windows(zip_file, destination)
+    else:
+      raise ValueError(f"Unsupported platform: {sys.platform}")
+
+def _extract_commander_macos(zip_file: Path, destination: Path) -> None:
+  if not zip_file.exists():
+    raise FileNotFoundError(f"Executable archive not found: {zip_file}")
+
+  destination.mkdir(parents=True, exist_ok=True)
+  subprocess.run(
+    ["ditto", "-xk", str(zip_file), str(destination)],
+    check=True
+  )
+
+def _extract_commander_linux(zip_file: Path, destination: Path) -> None:
+  if not zip_file.exists():
+    raise FileNotFoundError(f"Executable archive not found: {zip_file}")
+
+  destination.mkdir(parents=True, exist_ok=True)
+  subprocess.run(
+    ["tar", "-xjf", str(zip_file), "-C", str(destination)],
+    check=True
+  )
+
+def _extract_commander_windows(zip_file: Path, destination: Path) -> None:
+  if not zip_file.exists():
+    raise FileNotFoundError(f"Executable archive not found: {zip_file}")
+
+  destination.mkdir(parents=True, exist_ok=True)
+  subprocess.run(
+    ["powershell", "-Command", "Expand-Archive", f"-Path {str(zip_file)}", f"-DestinationPath {str(destination)}"],
+    check=True
+  )
+
+def _compute_hash_of_file(path: Path) -> str:
+  hash = hashlib.sha256()
+  hash.update(path.read_bytes())
+  return hash.hexdigest()[:16]
+
+def _find_executable_archive_resource(package: str) -> Path:
+  root = ir.files(package)
+  candidates : list[Path] = []
+  for entry in root.iterdir():
+    if not entry.is_file():
+      continue
+    name = entry.name
+    if name.endswith(".zip") or name.endswith(".tar.bz"):
+      candidates.append(root / name)
+
+  if len(candidates) == 0:
+    raise FileNotFoundError(f"No executable archive found in {root}")
+
+  return candidates[0]

pycommander_core/_utils.py

@@ -0,0 +1,37 @@
+"""
+License
+Copyright 2026 Silicon Laboratories Inc. www.silabs.com
+*******************************************************************************
+The licensor of this software is Silicon Laboratories Inc. Your use of this
+software is governed by the terms of Silicon Labs Master Software License
+Agreement (MSLA) available at
+www.silabs.com/about-us/legal/master-software-license-agreement. This
+software is distributed to you in Source Code format and is governed by the
+sections of the MSLA applicable to Source Code.
+*******************************************************************************
+"""
+
+def sanitize_args(args: list[str | int | float | None]) -> list[str]:
+  # NOTE: We do NOT want to split any args that contain whitespace into multiple args.
+  #       There might be filenames or other arguments that have whitespace in them.
+
+  sanitized_args : list[str] = []
+  for arg in args:
+    # Remove any empty or None elements
+    if arg is None:
+      continue
+
+    # Stringify any non-string elements
+    if not isinstance(arg, str):
+      arg = str(arg)
+
+    # Remove any whitespace-only elements
+    if arg.strip() == "":
+      continue
+
+    # Trim leading and trailing whitespace
+    arg = arg.strip()
+
+    sanitized_args.append(arg)
+
+  return sanitized_args

pycommander_core/_version.py

@@ -0,0 +1,14 @@
+"""
+License
+Copyright 2026 Silicon Laboratories Inc. www.silabs.com
+*******************************************************************************
+The licensor of this software is Silicon Laboratories Inc. Your use of this
+software is governed by the terms of Silicon Labs Master Software License
+Agreement (MSLA) available at
+www.silabs.com/about-us/legal/master-software-license-agreement. This
+software is distributed to you in Source Code format and is governed by the
+sections of the MSLA applicable to Source Code.
+*******************************************************************************
+"""
+
+__version__ = "1.0.0"

pycommander_core/adapter_base.py

@@ -0,0 +1,368 @@
+"""
+License
+Copyright 2026 Silicon Laboratories Inc. www.silabs.com
+*******************************************************************************
+The licensor of this software is Silicon Laboratories Inc. Your use of this
+software is governed by the terms of Silicon Labs Master Software License
+Agreement (MSLA) available at
+www.silabs.com/about-us/legal/master-software-license-agreement. This
+software is distributed to you in Source Code format and is governed by the
+sections of the MSLA applicable to Source Code.
+*******************************************************************************
+"""
+
+from pathlib import Path
+
+from . import types
+
+from .commander_base import CommanderBase
+from .target import Target
+
+class AdapterBase:
+  """High-level interface for interacting with a Silicon Labs adapter (kit/debugger).
+
+  The convenience methods on this class (adapter info, reset, supply voltage, VCOM
+  configuration, and energy analysis) rely on features that are only present on
+  Silicon Labs adapters, and are not available when using a generic J-Link adapter.
+  """
+
+  def __init__(self,
+              serial_number: str       | None = None,
+              ip_address: str          | None = None,
+              serial_port: str         | None = None,
+              target_device: str       | None = None,
+              debug_speed: int         | None = None,
+              debug_tif: str           | None = None,
+              debug_irpre: int         | None = None,
+              debug_drpre: int         | None = None,
+              target: Target           | None = None,
+              commander: CommanderBase | None = None):
+
+    if commander is None:
+      raise ValueError("commander must be provided")
+
+    self._commander : CommanderBase = commander
+    self.target : Target | None = target
+
+  def info(self) -> types.AdapterInfo | None:
+    """Get information about the adapter. Only available on Silicon Labs adapters.
+
+    Returns:
+      An AdapterInfo object containing the information about the adapter, or None if the information could not be retrieved.
+    """
+
+    result : dict = self._commander.adapter.probe()
+
+    if not result["success"]:
+      return None
+
+    if "board_lists" not in result["result"]:
+      return None
+
+    board_list : list[types.AdapterBoardInfo] = []
+    for board in result["result"]["board_lists"]:
+      board_list.append(types.AdapterBoardInfo(
+        name=board.get("name", None),
+        part_number=board.get("part_number", None),
+        serial_number=board.get("serial_number", None),
+        target_device=board.get("target_device", None),
+      ))
+
+    if "firmware_info" not in result["result"]:
+      return None
+
+    fw_info = types.AdapterFwInfo(
+      current_version=result["result"]["firmware_info"].get("fw_version", None),
+      latest_version=result["result"]["firmware_info"].get("new_fw_version", None),
+      upgrade_available=result["result"]["firmware_info"].get("upgrade_available", None),
+    )
+
+    if "kit_info" not in result["result"]:
+      return None
+
+    adapter_info = types.AdapterInfo(
+      board_list=board_list,
+      fw_info=fw_info,
+      jlink_serial_number=result["result"]["kit_info"].get("j_link_serial", None),
+      vcom_port=result["result"]["kit_info"].get("vcom_port", None),
+      vcom_supported=result["result"]["kit_info"].get("vcom_supported", None),
+      ip_supported=result["result"]["kit_info"].get("ip_supported", None),
+      ip_address=result["result"]["kit_info"].get("ip_address", None),
+      mac_address=result["result"]["kit_info"].get("mac_address", None),
+      nickname=result["result"]["kit_info"].get("nickname", None),
+      kit_name=result["result"]["kit_info"].get("kit_name", None),
+      kit_part_number=result["result"]["kit_info"].get("kit_part_number", None),
+      aem_supported=result["result"]["kit_info"].get("aem_supported", None),
+      debug_mode=result["result"]["kit_info"].get("debug_mode", None),
+      debug_part=result["result"]["kit_info"].get("debug_part", None),
+    )
+
+    return adapter_info
+
+  def reset(self) -> bool:
+    """Reset the adapter. Only available on Silicon Labs adapters.
+
+    Returns:
+      True if the adapter was reset successfully, False otherwise.
+    """
+    result : dict = self._commander.adapter.reset()
+    return result["success"]
+
+  def upgradeFirmware(self, filename: Path | None = None) -> types.AdapterFwUpgradeResult | None:
+    """Upgrade the firmware of the adapter. Only available on Silicon Labs adapters.
+
+    Args:
+      filename (Path | None): The path to the firmware package to upgrade (*.emz). If not provided, Commander's bundled firmware will be used; in this case, the upgrade will only be performed if the bundled version is newer than the installed version.
+
+    Returns:
+      An AdapterFwUpgradeResult object containing the result of the firmware upgrade, or None if the firmware upgrade could not be performed.
+    """
+
+    current_version : str | None = self.__get_current_firmware_version()
+
+    args = []
+    if filename is None or str(filename) == "":
+      # Check if a firmware upgrade is available first
+      result : dict = self._commander.adapter.fwupgradecheck()
+      if not result["success"]:
+        return None
+
+      if not result["result"].get("upgrade_available", False):
+        return types.AdapterFwUpgradeResult(
+          package_was_installed=False,
+          currently_installed_version=current_version,
+        )
+    else:
+      args.append(str(filename))
+
+    result : dict = self._commander.adapter.fwupgrade(*args)
+    if not result["success"]:
+      return None
+
+    new_version : str | None = self.__get_current_firmware_version()
+
+    return types.AdapterFwUpgradeResult(
+      package_was_installed=True,
+      currently_installed_version=new_version,
+    )
+
+  def getVoltage(self) -> types.AdapterVoltageInfo | None:
+    """Get the supply voltage for the target device. Only available on Silicon Labs adapters.
+
+    Returns:
+      A dictionary of rail indices and AdapterVoltageInfo objects containing the supply voltage 
+      information for each rail, or None if the supply voltage information could not be retrieved. 
+      If no supply voltage information is available for a rail, the rail index will not be present in the dictionary.
+    """
+    result : dict = self._commander.adapter.voltage()
+
+    if not result["success"]:
+      return None
+
+    voltage_info : types.AdapterVoltageInfo = types.AdapterVoltageInfo(rails=[])
+    for rail_info in result["result"]["voltages"]:
+      voltage_info.rails.append(types.AdapterRailInfo(
+        rail_index=rail_info.get("rail_index", None),
+        configured_voltage_v=rail_info.get("configured_voltage_v", None),
+        measured_voltage_v=rail_info.get("measured_voltage_v", None),
+        rail_powered=rail_info.get("rail_powered", None),
+      ))
+
+    return voltage_info
+
+  def setVoltage(self, voltage: float, calibrate: bool = True) -> bool:
+    """Set the supply voltage for the target device. Only available on Silicon Labs adapters.
+
+    Args:
+      voltage (float): Supply voltage to set.
+      calibrate (bool): If True, automatically calibrate if voltage has changed.
+
+    Returns:
+      True if the supply voltage was set successfully, False otherwise.
+    """
+    result : dict = self._commander.adapter.voltage(voltage=voltage, calibrate=calibrate)
+    return result["success"]
+
+  def setVcomConfig(self, baudrate: int, handshake: types.VcomHandshake, store: bool = False) -> bool:
+    """Set the VCOM configuration for the adapter. Only available on Silicon Labs adapters.
+
+    Args:
+      baudrate (int): VCOM baudrate.
+      handshake (VcomHandshake): VCOM handshake.
+      store (bool): Store the VCOM configuration.
+
+    Returns:
+      True if the VCOM configuration was set successfully, False otherwise.
+    """
+    if handshake not in types.VcomHandshake.__members__.values():
+      raise ValueError(f"Invalid handshake: {handshake}")
+
+    result : dict = self._commander.vcom.config(baudrate=baudrate, handshake=handshake.value, store=store)
+    return result["success"]
+
+  def analyzeEnergyUsage(self, duration_s: float, get_distribution: bool = False, cluster_states: bool = False, detect_period: bool = False) -> types.AemAnalysisResult | None:
+    """Analyze the energy usage of the target device. Only available on Silicon Labs adapters.
+
+    Args:
+      duration_s: Duration of the measurement in seconds.
+      get_distribution: If True, get the distribution of measurements.
+      cluster_states: If True, cluster the states of the measurements.
+      detect_period: If True, detect the period of the measurements.
+
+    Returns:
+      An AemAnalysisResult object containing the analysis results, or None if the analysis could not be performed.
+    """
+
+    if not get_distribution and not cluster_states and not detect_period:
+      raise ValueError("Distribution, cluster states, and period detection cannot all be False.")
+
+    result : dict = self._commander.aem.analyze(windowlength_ms=duration_s * 1000, get_distribution=get_distribution, cluster=cluster_states, find_period=detect_period)
+    if not result["success"]:
+      return None
+
+    aem_analysis_result : types.AemAnalysisResult | None = AdapterBase.__parse_aem_analyze_output(result)
+    return aem_analysis_result
+
+#########################################################
+
+  @staticmethod
+  def __parse_aem_analyze_output(result: dict) -> types.AemAnalysisResult | None:
+    if "result" not in result:
+      return None
+
+    aem_distribution           : types.AemDistribution          | None = None
+    aem_clustering             : types.AemClustering            | None = None
+    aem_period_detection       : types.AemPeriodDetection       | None = None
+    aem_signal_characteristics : types.AemSignalCharacteristics | None = None
+
+    dist_dict : dict | None = result["result"].get("distribution", None)
+    if dist_dict: 
+      aem_distribution = types.AemDistribution()
+      aem_distribution.bins = []
+      for bin in dist_dict.get("bins", {}):
+        aem_distribution.bins.append(types.AemDistributionBin(
+          average_current    = bin.get("average_current", None),
+          bin_max            = bin.get("bin_max", None),
+          bin_min            = bin.get("bin_min", None),
+          current_unit       = bin.get("current_unit", None),
+          num_samples        = bin.get("num_samples", None),
+          percentage         = bin.get("percentage", None),
+          standard_deviation = bin.get("standard_deviation", None),
+          time               = bin.get("time", None),
+          time_unit          = bin.get("time_unit", None),
+        ))
+
+      aem_distribution.configuration = types.AemDistributionConfiguration(
+        bins        = dist_dict.get("configuration", {}).get("bins", None),
+        logarithmic = dist_dict.get("configuration", {}).get("logarithmic", None),
+      )
+
+      aem_distribution.summary = types.AemDistributionSummary(
+        max_current       = dist_dict.get("summary", {}).get("max_current", None),
+        min_current       = dist_dict.get("summary", {}).get("min_current", None),
+        total_duration_ms = dist_dict.get("summary", {}).get("total_duration_ms", None),
+        total_samples     = dist_dict.get("summary", {}).get("total_samples", None),
+        unit              = dist_dict.get("summary", {}).get("unit", None),
+      )
+
+      aem_distribution.type = dist_dict.get("type", None)
+
+    cluster_dict : dict | None = result["result"].get("clustering", None)
+    if cluster_dict:
+      aem_clustering = types.AemClustering()
+      aem_clustering.blocks = []
+      for block in cluster_dict.get("blocks", {}):
+        aem_clustering.blocks.append(types.AemClusterBlock(
+          duration_ms = block.get("duration_ms", None),
+          end_ms      = block.get("end_ms", None),
+          level_mA    = block.get("level_mA", None),
+          max_mA      = block.get("max_mA", None),
+          min_mA      = block.get("min_mA", None),
+          range_mA    = block.get("range_mA", None),
+          samples     = block.get("samples", None),
+          start_ms    = block.get("start_ms", None),
+        ))
+      
+      aem_clustering.configuration = types.AemClusterConfiguration(
+        false_alarm_probability = cluster_dict.get("configuration", {}).get("false_alarm_probability", None),
+        max_points              = cluster_dict.get("configuration", {}).get("max_points", None),
+        min_segment_ms          = cluster_dict.get("configuration", {}).get("min_segment_ms", None),
+      )
+
+      aem_clustering.method        = cluster_dict.get("method", None)
+      aem_clustering.total_blocks  = cluster_dict.get("total_blocks", None)
+      aem_clustering.type          = cluster_dict.get("type", None)
+      aem_clustering.unique_states = cluster_dict.get("unique_states", None)
+
+    period_dict : dict | None = result["result"].get("period_detection", None)
+    if period_dict:
+      aem_period_detection = types.AemPeriodDetection()
+      aem_period_detection.configuration = types.AemPeriodDetectionConfiguration(
+        max_period_ms = period_dict.get("configuration", {}).get("max_period_ms", None),
+        min_period_ms = period_dict.get("configuration", {}).get("min_period_ms", None),
+      )
+
+      aem_period_detection.result = types.AemPeriodDetectionResult()
+      aem_period_detection.result.confidence = period_dict.get("result", {}).get("confidence", None)
+      aem_period_detection.result.frequency_hz = period_dict.get("result", {}).get("frequency_hz", None)
+
+      aem_period_detection.result.interval_summary = types.AemPeriodDetectionIntervalSummary(
+        average_mean_current_ma = period_dict.get("result", {}).get("interval_summary", {}).get("average_mean_current_ma", None),
+        average_peak_current_ma = period_dict.get("result", {}).get("interval_summary", {}).get("average_peak_current_ma", None),
+        max_period_ms           = period_dict.get("result", {}).get("interval_summary", {}).get("max_period_ms", None),
+        min_period_ms           = period_dict.get("result", {}).get("interval_summary", {}).get("min_period_ms", None),
+      )
+
+      aem_period_detection.result.intervals = []
+      for interval in period_dict.get("result", {}).get("intervals", {}):
+        aem_period_detection.result.intervals.append(types.AemPeriodDetectionInterval(
+          cycle           = interval.get("cycle", None),
+          end_index       = interval.get("end_index", None),
+          end_ms          = interval.get("end_ms", None),
+          mean_current_ma = interval.get("mean_current_ma", None),
+          peak_current_ma = interval.get("peak_current_ma", None),
+          period_ms       = interval.get("period_ms", None),
+          start_index     = interval.get("start_index", None),
+          start_ms        = interval.get("start_ms", None),
+        ))
+
+      aem_period_detection.result.is_periodic     = period_dict.get("result", {}).get("is_periodic", None)
+      aem_period_detection.result.jitter_relative = period_dict.get("result", {}).get("jitter_relative", None)
+      aem_period_detection.result.method          = period_dict.get("result", {}).get("method", None)
+      aem_period_detection.result.num_cycles      = period_dict.get("result", {}).get("num_cycles", None)
+      aem_period_detection.result.period_ms       = period_dict.get("result", {}).get("period_ms", None)
+      aem_period_detection.result.method_results  = []
+      for method_result in period_dict.get("result", {}).get("method_results", {}):
+        aem_period_detection.result.method_results.append(types.AemPeriodDetectionMethodResult(
+          method         = method_result.get("method", None),
+          detected       = method_result.get("detected", None),
+          confidence     = method_result.get("confidence", None),
+          period_ms      = method_result.get("period_ms", None),
+          relative_error = method_result.get("relative_error", None),
+        ))
+
+      aem_period_detection.type = period_dict.get("type", None)
+
+    signal_char_dict : dict | None = result["result"].get("signal_characteristics", None)
+    if signal_char_dict:
+      aem_signal_characteristics = types.AemSignalCharacteristics(
+        average_voltage_v        = signal_char_dict.get("average_voltage_V", None),
+        dynamic_range_ratio      = signal_char_dict.get("dynamic_range_ratio", None),
+        estimated_states         = signal_char_dict.get("estimated_states", None),
+        max_current_ma           = signal_char_dict.get("max_current_mA", None),
+        min_current_ma           = signal_char_dict.get("min_current_mA", None),
+        noise_level_mad_sigma_ma = signal_char_dict.get("noise_level_mad_sigma_mA", None),
+      )
+
+    return types.AemAnalysisResult(
+      distribution           = aem_distribution,
+      clustering             = aem_clustering,
+      period_detection       = aem_period_detection,
+      signal_characteristics = aem_signal_characteristics,
+    )
+
+  def __get_current_firmware_version(self) -> str | None:
+    result : dict = self._commander.adapter.probe()
+    if not result["success"]:
+      return None
+    return result["result"].get("firmware_info", {}).get("fw_version", None)