|
1 | | -# Pyectool |
| 1 | +# libectool |
2 | 2 |
|
3 | | -**Pyectool** is a Python package with C++ bindings for interacting with the Embedded Controller (EC) on ChromeOS and Framework devices. It is extracted from and based on [`ectool`](https://gitlab.howett.net/DHowett/ectool) utility, and exposes EC control functions directly to Python programs via a native extension. |
| 3 | +libectool is a shared library extracted from ectool, providing programmatic access to Embedded Controller (EC) functionalities on ChromeOS and compatible devices. |
4 | 4 |
|
5 | | -## Features |
6 | | - |
7 | | -- Python bindings for EC functionality using `pybind11`. |
8 | | -- Supports fan duty control, temperature reading, AC power status, and more. |
9 | | -- Designed for integration with hardware management or fan control tools. |
10 | | -- Shared core logic with `libectool` for C/C++ integration. |
11 | | - |
12 | | ---- |
13 | | - |
14 | | -## Build & Install (Python Package) |
15 | | - |
16 | | -We use [`scikit-build-core`](https://scikit-build-core.readthedocs.io/en/latest/) to build the C++ extension via CMake. |
17 | | - |
18 | | -### Prerequisites |
19 | | - |
20 | | -Install the required system dependencies: |
| 5 | +## Features |
| 6 | +- Exposes EC control functions via a shared library (`libectool.so`). |
| 7 | +- Supports fan control, battery management, temperature monitoring, and more. |
| 8 | +- Designed for integration into other applications. |
21 | 9 |
|
| 10 | +## Build Instructions |
22 | 11 | ```sh |
23 | | -sudo apt update |
24 | | -sudo apt install -y libusb-1.0-0-dev libftdi1-dev pkg-config |
25 | | -```` |
26 | | -### Clone the repository |
27 | | - |
28 | | -## Install system-wide |
29 | | -```sh |
30 | | -sudo pip install . |
31 | | -``` |
32 | | -Or: |
33 | | - |
34 | | -```bash |
35 | | -sudo env "PIP_BREAK_SYSTEM_PACKAGES=1" pip install . |
| 12 | +cd libectool |
| 13 | +mkdir build && cd build |
| 14 | +cmake .. |
| 15 | +cmake --build . |
36 | 16 | ``` |
37 | | -(Required on modern distros like Ubuntu 24.04 due to PEP 668.) |
38 | | - |
39 | | -### Test from outside the repo dir |
40 | | -After installing, **do not run Python from the `libectool/` directory**, since it contains a `pyectool/` folder that may shadow the installed package. |
41 | | - |
42 | | -Instead, test from another location, e.g.: |
| 17 | +## Post Build Instructions |
| 18 | +After building, you need to move `libectool.so` to a library directory where it can be found by your system: |
43 | 19 |
|
| 20 | +### Option 1 — User-specific (Recommended for non-root users) |
44 | 21 | ```sh |
45 | | -cd .. |
46 | | -sudo python -c "import pyectool; print(pyectool.is_on_ac())" |
| 22 | +mkdir -p ~/.local/lib |
| 23 | +cp src/core/libectool.so ~/.local/lib/libectool.so |
| 24 | +export LD_LIBRARY_PATH="$HOME/.local/lib:$LD_LIBRARY_PATH" |
47 | 25 | ``` |
48 | | - |
49 | | -## VENV INSTALLATION |
50 | | - |
51 | | -If you **don’t** want to touch system Python: |
52 | | - |
53 | | -### Create venv |
54 | | - |
55 | | -```bash |
56 | | -python3 -m venv ~/.venv/pyectool |
57 | | -source ~/.venv/pyectool/bin/activate |
58 | | -``` |
59 | | - |
60 | | -### Install your package |
61 | | - |
62 | | -Inside the venv: |
63 | | -```bash |
64 | | -pip install . |
| 26 | +To make it persistent across sessions, add the export to your shell configuration: |
| 27 | +```sh |
| 28 | +echo 'export LD_LIBRARY_PATH="$HOME/.local/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc |
65 | 29 | ``` |
66 | | -### Test from outside the repo dir |
67 | | -```bash |
68 | | -cd .. |
69 | | -sudo env "PATH=$PATH" python -c "import pyectool; print(pyectool.is_on_ac())" |
| 30 | +### Option 2 — Global installation |
| 31 | +```sh |
| 32 | +sudo cp src/core/libectool.so /usr/local/lib/libectool.so |
70 | 33 | ``` |
71 | | - |
72 | | -### Available Functions |
73 | | - |
74 | | -| Function | Description | |
75 | | -| ------------------------------------------ | -------------------------------------------------------------------------------- | |
76 | | -| `auto_fan_control()` | Enables automatic fan control by the EC. | |
77 | | -| `get_max_non_battery_temperature() -> float` | Returns the highest temperature (in °C) from all sensors except the battery. | |
78 | | -| `get_max_temperature() -> float` | Returns the highest temperature (in °C) from all EC sensors including battery. | |
79 | | -| `is_on_ac() -> bool` | Checks whether the device is running on AC power. | |
80 | | -| `set_fan_duty(percent: int)` | Sets the fan duty cycle manually (0–100%). | |
0 commit comments