Skip to content

Commit 856c179

Browse files
committed
Update README
1 parent 90ebd1e commit 856c179

File tree

1 file changed

+42
-12
lines changed

1 file changed

+42
-12
lines changed

README.md

Lines changed: 42 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,23 @@ As well as a higher-level abstracted interface for easy access to some of the mo
1010

1111
### Linux
1212

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:
1417

1518
```bash
1619
pip install cros-ec-python
1720
```
1821

1922
Some interfaces require additional dependencies, for example the LPC interface performs best with the `portio` package:
2023

21-
2224
```bash
2325
pip install cros-ec-python[lpc]
2426
```
2527

2628
#### Permissions
29+
2730
Since we're playing around with actual hardware, we're going to need some pretty high permissions.
2831

2932
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
3538

3639
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.
3740

41+
3842
##### Linux Device Interface
43+
3944
This library requires write permission to `/dev/cros_ec` when using the Linux Device interface,
4045
which is usually only accessible by root. You can either run your script as root, add a udev rule,
4146
or just manually change the permissions. Read permission is not needed, only write.
4247

4348
##### LPC Bus Interface
49+
4450
This library requires access to IO ports using the `CAP_SYS_RAWIO` capability.
4551
It's easiest just to run your script as root.
4652

4753
### Windows
4854

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:
5259

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:
5464

5565
```bash
5666
pip install cros-ec-python
5767
```
5868

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`.
6088

6189
## Documentation
6290

@@ -67,15 +95,16 @@ and every function has usage in the [`tests`](https://github.com/Steve-Tech/CrOS
6795

6896
### Running Tests
6997

98+
> [!CAUTION]
99+
> This will test against your EC, nothing is mocked.
100+
70101
This package uses the built-in `unittest` module for testing. To run the tests, simply run:
71102

72103
```bash
73104
cd tests
74105
python -m unittest
75106
```
76107

77-
***Note: This will test against your EC, nothing is mocked.***
78-
79108
### Generating Documentation
80109

81110
The documentation is generated using `pdoc`. To generate the documentation, run:
@@ -93,15 +122,17 @@ pdoc cros_ec_python
93122
### Supported Interfaces
94123

95124
- [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)
96126
- [x] LPC Bus Interface (Soft-requires the [`portio` package](https://pypi.org/project/portio/))
97127
- [ ] MEC LPC Interface
98128
- [ ] I2C Interface
99129
- [ ] Servo SPI Interface
100130

101131
### Supported Commands
102132

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.
105136
106137
Here's a list of all known CrOS EC commands, and whether they are abstracted in this library.
107138
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.
506537
- [x] `EC_CMD_BATTERY_EXTENDER` (`0x3E24`)
507538

508539
</details>
509-

0 commit comments

Comments
 (0)