cros_ec_python.cros_ec

 1"""
 2This submodule provides some helper functions to make it easier to use the library.
 3
 4For example, you can use `get_cros_ec()` instead of manually picking between
 5`cros_ec_python.devices.lpc.CrosEcLpc` and `cros_ec_python.devices.dev.CrosEcDev`.
 6"""
 7
 8import sys
 9
10from .constants.COMMON import *
11from .baseclass import CrosEcClass
12from .devices import lpc, mec
13if sys.platform == "linux":
14    from .devices import dev
15else:
16    dev = None
17if sys.platform == "win32":
18    from .devices import pawnio, win_fw_ec
19else:
20    pawnio = win_fw_ec = None
21
22class DeviceTypes(Enum):
23    """
24    An Enum of different interfaces supported by the library.
25    """
26    LinuxDev = 0
27    """
28    This is the Linux device interface, which uses the `/dev/cros_ec` device file.
29    *Recommended if you have the `cros_ec_dev` kernel module loaded.*
30    """
31    WinFrameworkEC = 1
32    """
33    This is the Framework Windows driver interface.
34    *Recommended if you have a Framework laptop with a supported BIOS and driver.*
35    """
36    PawnIO = 2
37    "This is the Windows PawnIO interface, which is otherwise recommended on Windows Systems."
38    LPC = 3
39    "This manually talks to the EC over the LPC interface, using the ioports."
40    MEC = 4
41    "This manually talks to the EC over the MEC LPC interface, using the ioports."
42
43
44def pick_device() -> DeviceTypes:
45    """
46    Pick the device to use. Used by `get_cros_ec`.
47    Devices are picked in the following order:
48    * `DeviceTypes.LinuxDev` (see `cros_ec_python.devices.dev.CrosEcDev.detect()`)
49    * `DeviceTypes.WinFrameworkEC` (see `cros_ec_python.devices.win_fw_ec.WinFrameworkEc.detect()`)
50    * `DeviceTypes.PawnIO` (see `cros_ec_python.devices.pawnio.CrosEcPawnIO.detect()`)
51    * `DeviceTypes.LPC` (see `cros_ec_python.devices.lpc.CrosEcLpc.detect()`)
52    * `DeviceTypes.MEC` (see `cros_ec_python.devices.mec.CrosEcMec.detect()`)
53    """
54    if dev and dev.CrosEcDev.detect():
55        return DeviceTypes.LinuxDev
56    elif win_fw_ec and win_fw_ec.WinFrameworkEc.detect():
57        return DeviceTypes.WinFrameworkEC
58    elif pawnio and pawnio.CrosEcPawnIO.detect():
59        return DeviceTypes.PawnIO
60    elif lpc and lpc.CrosEcLpc.detect():
61        return DeviceTypes.LPC
62    elif mec and mec.CrosEcMec.detect():
63        return DeviceTypes.MEC
64    else:
65        raise OSError("Could not auto detect device, check you have the required permissions, or specify manually.")
66
67
68def get_cros_ec(dev_type: DeviceTypes | None = None, **kwargs) -> CrosEcClass:
69    """
70    Find and initialise the correct CrosEc class.
71    This is the recommended way of obtaining a `cros_ec_python.baseclass.CrosEcClass` object.
72    :param dev_type: The device type to use. If None, it will be picked automatically.
73    :param kwargs: Keyword arguments to pass to the CrosEc class.
74    """
75
76    if dev_type is None:
77        dev_type = pick_device()
78
79    match dev_type:
80        case DeviceTypes.LinuxDev:
81            return dev.CrosEcDev(**kwargs)
82        case DeviceTypes.WinFrameworkEC:
83            return win_fw_ec.WinFrameworkEc(**kwargs)
84        case DeviceTypes.PawnIO:
85            return pawnio.CrosEcPawnIO(**kwargs)
86        case DeviceTypes.LPC:
87            return lpc.CrosEcLpc(**kwargs)
88        case DeviceTypes.MEC:
89            return mec.CrosEcMec(**kwargs)
90        case _:
91            raise ValueError("Invalid device type.")