You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+42-12Lines changed: 42 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,20 +10,23 @@ As well as a higher-level abstracted interface for easy access to some of the mo
10
10
11
11
### Linux
12
12
13
-
For a basic installation with full Linux Device support, run:
13
+
> [!NOTE]
14
+
> Don't forget to read the [permissions](#permissions) section below.
15
+
16
+
For a basic installation with full Linux Device support, run:
14
17
15
18
```bash
16
19
pip install cros-ec-python
17
20
```
18
21
19
22
Some interfaces require additional dependencies, for example the LPC interface performs best with the `portio` package:
20
23
21
-
22
24
```bash
23
25
pip install cros-ec-python[lpc]
24
26
```
25
27
26
28
#### Permissions
29
+
27
30
Since we're playing around with actual hardware, we're going to need some pretty high permissions.
28
31
29
32
The recommended way is to copy [`60-cros_ec_python.rules`](60-cros_ec_python.rules) to `/etc/udev/rules.d/` and run:
@@ -35,28 +38,53 @@ sudo udevadm trigger
35
38
36
39
This will give the current user access to both `/dev/cros_ec` for the Linux Device interface, and the IO ports for the LPC interface.
37
40
41
+
38
42
##### Linux Device Interface
43
+
39
44
This library requires write permission to `/dev/cros_ec` when using the Linux Device interface,
40
45
which is usually only accessible by root. You can either run your script as root, add a udev rule,
41
46
or just manually change the permissions. Read permission is not needed, only write.
42
47
43
48
##### LPC Bus Interface
49
+
44
50
This library requires access to IO ports using the `CAP_SYS_RAWIO` capability.
45
51
It's easiest just to run your script as root.
46
52
47
53
### Windows
48
54
49
-
The Windows version requires WinRing0 to access IO ports. You can find signed versions online, that do not require disabling driver signature enforcement.
50
-
You will need to copy `WinRing0x64.dll` and `WinRing0x64.sys` to either the same
51
-
directory as `python.exe`, or to `C:\Windows\System32`.
55
+
> [!NOTE]
56
+
> Loading a driver will likely require administrator permissions, so you may need to run your script as an administrator.
57
+
58
+
The Windows version supports 2 different drivers to access the EC:
52
59
53
-
Then you can install the package with:
60
+
-`PawnIO` which is a fairly new scriptable kernel driver, the official signed version can be downloaded [here](https://pawnio.eu/).
61
+
-`WinRing0` which while still signed, it has been abandoned and is listed on the Microsoft Vulnerable Driver Blocklist.
62
+
63
+
Install one of the drivers, and then install the package using pip:
54
64
55
65
```bash
56
66
pip install cros-ec-python
57
67
```
58
68
59
-
WinRing0 will likely require administrator permissions to access IO ports, so you may need to run your script as an administrator.
69
+
#### PawnIO
70
+
71
+
> [!TIP]
72
+
> PawnIO is [designed to be a secure alternative to WinRing0](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor/issues/984#issuecomment-1585591691), and is the recommended driver for Windows.
73
+
74
+
[PawnIO](https://pawnio.eu/) can be installed using the installer from the website.
75
+
PawnIO is signed and does not require disabling driver signature enforcement.
76
+
77
+
You will also need to download the [`LpcCrOSEC`](https://github.com/namazso/PawnIO.Modules/pull/3) module, and copy it to your working directory.
78
+
79
+
#### WinRing0
80
+
81
+
> [!WARNING]
82
+
> WinRing0 is listed on the Microsoft Vulnerable Driver Blocklist, making it frequently flagged by antivirus and anti cheat software. Download links are not provided, use at your own risk.
83
+
84
+
Alternatively, WinRing0 can be used to access the IO ports required for communication to the EC. You can find signed versions online, that do not require disabling driver signature enforcement.
85
+
86
+
You will need to copy `WinRing0x64.dll` and `WinRing0x64.sys` to either the same
87
+
directory as `python.exe`, or to `C:\Windows\System32`.
60
88
61
89
## Documentation
62
90
@@ -67,15 +95,16 @@ and every function has usage in the [`tests`](https://github.com/Steve-Tech/CrOS
67
95
68
96
### Running Tests
69
97
98
+
> [!CAUTION]
99
+
> This will test against your EC, nothing is mocked.
100
+
70
101
This package uses the built-in `unittest` module for testing. To run the tests, simply run:
71
102
72
103
```bash
73
104
cd tests
74
105
python -m unittest
75
106
```
76
107
77
-
***Note: This will test against your EC, nothing is mocked.***
78
-
79
108
### Generating Documentation
80
109
81
110
The documentation is generated using `pdoc`. To generate the documentation, run:
@@ -93,15 +122,17 @@ pdoc cros_ec_python
93
122
### Supported Interfaces
94
123
95
124
-[x] Linux Device (Requires the `cros_ec_dev` kernel module)
125
+
-[x] Windows [PawnIO](https://pawnio.eu/) using [LpcCrOSEC](https://github.com/namazso/PawnIO.Modules/pull/3)
96
126
-[x] LPC Bus Interface (Soft-requires the [`portio` package](https://pypi.org/project/portio/))
97
127
-[ ] MEC LPC Interface
98
128
-[ ] I2C Interface
99
129
-[ ] Servo SPI Interface
100
130
101
131
### Supported Commands
102
132
103
-
The goal of this project is *not* to abstract away 100% of the CrOS EC commands, but to abstract the ones that may be useful.
104
-
If a command is not abstracted it can still be used by calling the `ec.command()` method instead.
133
+
> [!NOTE]
134
+
> The goal of this project is *not* to abstract away 100% of the CrOS EC commands, but to abstract the ones that may be useful.
135
+
> If a command is not abstracted it can still be used by calling the `ec.command()` method instead.
105
136
106
137
Here's a list of all known CrOS EC commands, and whether they are abstracted in this library.
107
138
The implemented commands are split up into modules for maintainability reasons.
@@ -506,4 +537,3 @@ The implemented commands are split up into modules for maintainability reasons.
0 commit comments