CrOS_EC_Python

A Python library for interacting with a Chrome OS EC. Commonly found in Chromebooks and Framework laptops.

It provides a somewhat lower-level interface to the CrOS EC, allowing you to send and receive any EC command, and read any byte from the memory map. As well as a higher-level abstracted interface for easy access to some of the more common commands.

Installation

Linux & FreeBSD

For a basic installation with full Linux Device support, run:

pip install cros-ec-python

Some interfaces require additional dependencies, for example the LPC & MEC interface performs best with the portio package:

pip install cros-ec-python[lpc]

Linux Permissions

Since we're playing around with actual hardware, we're going to need some pretty high permissions.

The recommended way is to copy 60-cros_ec_python.rules to /etc/udev/rules.d/ and run:

sudo udevadm control --reload-rules
sudo udevadm trigger

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.

Linux Device Interface

This library requires write permission to /dev/cros_ec when using the Linux Device interface, which is usually only accessible by root. You can either run your script as root, add a udev rule, or just manually change the permissions. Read permission is not needed, only write.

LPC Bus Interface

This library requires access to IO ports using the CAP_SYS_RAWIO capability. Read/Write permission to /dev/port is also required if not using portio. It's easiest just to run your script as root.

Windows

The Windows version supports 3 different drivers to access the EC (only one is required):

  • The Framework EC driver which is provided in the driver bundles and requires a supported BIOS version. This driver does not require administrator and is the recommended way of using CrOS_EC_Python on supported devices.
  • PawnIO which is a fairly new scriptable kernel driver, the official signed version can be downloaded here.
  • WinRing0 which while still signed, it has been abandoned and is listed on the Microsoft Vulnerable Driver Blocklist.

Install one of the drivers, and then install the package using pip:

pip install cros-ec-python

PawnIO

PawnIO can be installed using the installer from the website. PawnIO is signed and does not require disabling driver signature enforcement.

You will also need to download the latest release of the PawnIO modules and copy LpcCrOSEC.bin to your working directory.

WinRing0

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.

You will need to copy WinRing0x64.dll and WinRing0x64.sys to either the same directory as python.exe, or to C:\Windows\System32.

Documentation

The documentation for this project can be found here.

There are also some examples in the examples directory, and every function has usage in the tests directory.

Running Tests

This package uses the built-in unittest module for testing. To run the tests, simply run:

cd tests
python -m unittest

Generating Documentation

The documentation is generated using pdoc. To generate the documentation, run:

pdoc -o docs/ cros_ec_python

Or to generate the documentation and serve it locally:

pdoc cros_ec_python

Supported Interfaces

  • Linux Device (Requires the cros_ec_dev kernel module)
  • Windows Framework EC Driver
  • Windows PawnIO using LpcCrOSEC
  • LPC Bus Interface (Soft-requires the portio package)
  • MEC LPC Interface (Soft-requires the portio package)
  • I2C Interface
  • Servo SPI Interface

Known Issues

Supported Commands

Here's a list of all known CrOS EC commands, and whether they are abstracted in this library. The implemented commands are split up into modules for maintainability reasons.

Implemented CrOS commands

General / test commands (general)

  • EC_CMD_PROTO_VERSION (0x0000)
  • EC_CMD_HELLO (0x0001)
  • EC_CMD_GET_VERSION (0x0002)
  • EC_CMD_READ_TEST (0x0003)
  • EC_CMD_GET_BUILD_INFO (0x0004)
  • EC_CMD_GET_CHIP_INFO (0x0005)
  • EC_CMD_GET_BOARD_VERSION (0x0006)
  • EC_CMD_READ_MEMMAP (0x0007)
  • EC_CMD_GET_CMD_VERSIONS (0x0008)
  • EC_CMD_GET_COMMS_STATUS (0x0009)
  • EC_CMD_TEST_PROTOCOL (0x000A)
  • EC_CMD_GET_PROTOCOL_INFO (0x000B)

Get/Set miscellaneous values (system)

  • EC_CMD_GSV_PAUSE_IN_S5 (0x000C)
  • EC_CMD_GET_FEATURES (0x000D)
  • EC_CMD_GET_SKU_ID (0x000E)
  • EC_CMD_SET_SKU_ID (0x000F)

Flash commands (flash)

  • EC_CMD_FLASH_INFO (0x0010)
  • EC_CMD_FLASH_READ (0x0011)
  • EC_CMD_FLASH_WRITE (0x0012)
  • EC_CMD_FLASH_ERASE (0x0013)
  • EC_CMD_FLASH_PROTECT (0x0015)
  • EC_CMD_FLASH_REGION_INFO (0x0016)
  • EC_CMD_FLASH_SPI_INFO (0x0018)
  • EC_CMD_FLASH_SELECT (0x0019)

Cryptography and Sysinfo (system)

  • EC_CMD_RAND_NUM (0x001A)
  • EC_CMD_RWSIG_INFO (0x001B)
  • EC_CMD_SYSINFO (0x001C)

PWM commands (pwm)

  • EC_CMD_PWM_GET_FAN_TARGET_RPM (0x0020)
  • EC_CMD_PWM_SET_FAN_TARGET_RPM (0x0021)
  • EC_CMD_PWM_GET_KEYBOARD_BACKLIGHT (0x0022)
  • EC_CMD_PWM_SET_KEYBOARD_BACKLIGHT (0x0023)
  • EC_CMD_PWM_SET_FAN_DUTY (0x0024)
  • EC_CMD_PWM_SET_DUTY (0x0025)
  • EC_CMD_PWM_GET_DUTY (0x0026)

Lightbar commands (lightbar)

  • EC_CMD_LIGHTBAR_CMD (0x0028)

LED control commands (leds)

  • EC_CMD_LED_CONTROL (0x0029)

Verified boot commands (system)

  • EC_CMD_VBOOT_HASH (0x002A)

Motion sense commands (motion_sense)

  • EC_CMD_MOTION_SENSE_CMD (0x002B)

Power control commands (system)

  • EC_CMD_FORCE_LID_OPEN (0x002C)
  • EC_CMD_CONFIG_POWER_BUTTON (0x002D)
  • EC_CMD_USB_CHARGE_SET_MODE (0x0030)
  • EC_CMD_SET_TABLET_MODE (0x0031)

Persistent storage for host (pstore)

  • EC_CMD_PSTORE_INFO (0x0040)
  • EC_CMD_PSTORE_READ (0x0041)
  • EC_CMD_PSTORE_WRITE (0x0042)

Real-time clock (rtc)

  • EC_CMD_RTC_GET_VALUE (0x0044)
  • EC_CMD_RTC_GET_ALARM (0x0045)
  • EC_CMD_RTC_SET_VALUE (0x0046)
  • EC_CMD_RTC_SET_ALARM (0x0047)

Port 80 log access (system)

  • EC_CMD_PORT80_LAST_BOOT (0x0048)
  • EC_CMD_PORT80_READ (0x0048)

Get persistent storage info (pstore)

  • EC_CMD_VSTORE_INFO (0x0049)
  • EC_CMD_VSTORE_READ (0x004A)
  • EC_CMD_VSTORE_WRITE (0x004B)

Thermal engine commands (thermal)

  • EC_CMD_THERMAL_SET_THRESHOLD (0x0050)
  • EC_CMD_THERMAL_GET_THRESHOLD (0x0051)
  • EC_CMD_THERMAL_AUTO_FAN_CTRL (0x0052)
  • EC_CMD_TMP006_GET_CALIBRATION (0x0053)
  • EC_CMD_TMP006_SET_CALIBRATION (0x0054)
  • EC_CMD_TMP006_GET_RAW (0x0055)

MKBP - Matrix KeyBoard Protocol (mkbp)

  • EC_CMD_MKBP_STATE (0x0060)
  • EC_CMD_MKBP_INFO (0x0061)
  • EC_CMD_MKBP_SIMULATE_KEY (0x0062)
  • EC_CMD_MKBP_SET_CONFIG (0x0064)
  • EC_CMD_MKBP_GET_CONFIG (0x0065)
  • EC_CMD_KEYSCAN_SEQ_CTRL (0x0066)
  • EC_CMD_GET_NEXT_EVENT (0x0067)
  • EC_CMD_KEYBOARD_FACTORY_TEST (0x0068)
  • EC_CMD_MKBP_WAKE_MASK (0x0069)

Temperature sensor commands (thermal)

  • EC_CMD_TEMP_SENSOR_GET_INFO (0x0070)

Host event commands (events)

  • EC_CMD_HOST_EVENT_GET_B (0x0087)
  • EC_CMD_HOST_EVENT_GET_SMI_MASK (0x0088)
  • EC_CMD_HOST_EVENT_GET_SCI_MASK (0x0089)
  • EC_CMD_HOST_EVENT_GET_WAKE_MASK (0x008D)
  • EC_CMD_HOST_EVENT_SET_SMI_MASK (0x008A)
  • EC_CMD_HOST_EVENT_SET_SCI_MASK (0x008B)
  • EC_CMD_HOST_EVENT_CLEAR (0x008C)
  • EC_CMD_HOST_EVENT_SET_WAKE_MASK (0x008E)
  • EC_CMD_HOST_EVENT_CLEAR_B (0x008F)
  • EC_CMD_HOST_EVENT (0x00A4)

Switch commands (system)

  • EC_CMD_SWITCH_ENABLE_BKLIGHT (0x0090)
  • EC_CMD_SWITCH_ENABLE_WIRELESS (0x0091)

GPIO commands (gpio)

  • EC_CMD_GPIO_SET (0x0092)
  • EC_CMD_GPIO_GET (0x0093)

I2C commands (i2c)

  • EC_CMD_I2C_READ (0x0094)
  • EC_CMD_I2C_WRITE (0x0095)

Charge state commands (charge)

  • EC_CMD_CHARGE_CONTROL (0x0096)

Console commands (console)

  • EC_CMD_CONSOLE_SNAPSHOT (0x0097)
  • EC_CMD_CONSOLE_READ (0x0098)

Battery commands (charge)

  • EC_CMD_BATTERY_CUT_OFF (0x0099)

USB port mux control (usb)

  • EC_CMD_USB_MUX (0x009A)

LDOs / FETs control (power)

  • EC_CMD_LDO_SET (0x009B)
  • EC_CMD_LDO_GET (0x009C)

Power info (power)

  • EC_CMD_POWER_INFO (0x009D)

I2C passthru command (i2c)

  • EC_CMD_I2C_PASSTHRU (0x009E)

Power button hang detect (system)

  • EC_CMD_HANG_DETECT (0x009F)

Commands for battery charging (charge)

  • EC_CMD_CHARGE_STATE (0x00A0)
  • EC_CMD_CHARGE_CURRENT_LIMIT (0x00A1)
  • EC_CMD_EXTERNAL_POWER_LIMIT (0x00A2)
  • EC_CMD_OVERRIDE_DEDICATED_CHARGER_LIMIT (0x00A3)
  • EC_CMD_CHARGESPLASH (0x00A5)

Hibernate/Deep Sleep Commands (system)

  • EC_CMD_HIBERNATION_DELAY (0x00A8)
  • EC_CMD_HOST_SLEEP_EVENT (0x00A9)

Device events (events)

  • EC_CMD_DEVICE_EVENT (0x00AA)

Get s0ix counter (system)

  • EC_CMD_GET_S0IX_COUNTER (0x00AB)

Smart battery pass-through (battery)

  • EC_CMD_SB_READ_WORD (0x00B0)
  • EC_CMD_SB_WRITE_WORD (0x00B1)
  • EC_CMD_SB_READ_BLOCK (0x00B2)
  • EC_CMD_SB_WRITE_BLOCK (0x00B3)

Battery vendor parameters (battery)

  • EC_CMD_BATTERY_VENDOR_PARAM (0x00B4)

Smart Battery Firmware Update (battery)

  • EC_CMD_SB_FW_UPDATE (0x00B5)
  • EC_CMD_ENTERING_MODE (0x00B6)

I2C passthru protection (i2c)

  • EC_CMD_I2C_PASSTHRU_PROTECT (0x00B7)

HDMI CEC commands (hdmi)

  • EC_CMD_CEC_WRITE_MSG (0x00B8)
  • EC_CMD_CEC_SET (0x00BA)
  • EC_CMD_CEC_GET (0x00BB)

Commands for audio codec (audio)

  • EC_CMD_EC_CODEC (0x00BC)
  • EC_CMD_EC_CODEC_DMIC (0x00BD)
  • EC_CMD_EC_CODEC_I2S_RX (0x00BE)
  • EC_CMD_EC_CODEC_WOV (0x00BF)

Commands for PoE PSE controller (power)

  • EC_CMD_PSE (0x00C0)

System commands (system)

  • EC_CMD_REBOOT_EC (0x00D2)
  • EC_CMD_GET_PANIC_INFO (0x00D3)
  • EC_CMD_REBOOT (0x00D1) 'Think "die"'
  • EC_CMD_RESEND_RESPONSE (0x00DB)
  • EC_CMD_VERSION0 (0x00DC)
  • EC_CMD_MEMORY_DUMP_GET_METADATA (0x00DD)
  • EC_CMD_MEMORY_DUMP_GET_ENTRY_INFO (0x00DE)
  • EC_CMD_MEMORY_DUMP_READ_MEMORY (0x00DF)

PD commands (usb)

  • EC_CMD_PD_EXCHANGE_STATUS (0x0100)
  • EC_CMD_PD_HOST_EVENT_STATUS (0x0104)
  • EC_CMD_USB_PD_CONTROL (0x0101)
  • EC_CMD_USB_PD_PORTS (0x0102)
  • EC_CMD_USB_PD_POWER_INFO (0x0103)
  • EC_CMD_CHARGE_PORT_COUNT (0x0105)
  • EC_CMD_USB_PD_DPS_CONTROL (0x0106)
  • EC_CMD_USB_PD_FW_UPDATE (0x0110)
  • EC_CMD_USB_PD_RW_HASH_ENTRY (0x0111)
  • EC_CMD_USB_PD_DEV_INFO (0x0112)
  • EC_CMD_USB_PD_DISCOVERY (0x0113)
  • EC_CMD_PD_CHARGE_PORT_OVERRIDE (0x0114)
  • EC_CMD_PD_GET_LOG_ENTRY (0x0115)
  • EC_CMD_USB_PD_GET_AMODE (0x0116)
  • EC_CMD_USB_PD_SET_AMODE (0x0117)
  • EC_CMD_PD_WRITE_LOG_ENTRY (0x0118)
  • EC_CMD_PD_CONTROL (0x0119)
  • EC_CMD_USB_PD_MUX_INFO (0x011A)
  • EC_CMD_PD_CHIP_INFO (0x011B)

Board commands (board)

  • EC_CMD_RWSIG_CHECK_STATUS (0x011C)
  • EC_CMD_RWSIG_ACTION (0x011D)
  • EC_CMD_EFS_VERIFY (0x011E)
  • EC_CMD_GET_CROS_BOARD_INFO (0x011F)
  • EC_CMD_SET_CROS_BOARD_INFO (0x0120)
  • EC_CMD_GET_UPTIME_INFO (0x0121)
  • EC_CMD_ADD_ENTROPY (0x0122)
  • EC_CMD_ADC_READ (0x0123)
  • EC_CMD_ROLLBACK_INFO (0x0124)
  • EC_CMD_AP_RESET (0x0125)
  • EC_CMD_LOCATE_CHIP (0x0126)
  • EC_CMD_REBOOT_AP_ON_G3 (0x0127)
  • EC_CMD_GET_PD_PORT_CAPS (0x0128)
  • EC_CMD_BUTTON (0x0129)
  • EC_CMD_GET_KEYBD_CONFIG (0x012A)

Smart discharge (charge)

  • EC_CMD_SMART_DISCHARGE (0x012B)

Regulator commands (power)

  • EC_CMD_REGULATOR_GET_INFO (0x012C)
  • EC_CMD_REGULATOR_ENABLE (0x012D)
  • EC_CMD_REGULATOR_IS_ENABLED (0x012E)
  • EC_CMD_REGULATOR_SET_VOLTAGE (0x012F)
  • EC_CMD_REGULATOR_GET_VOLTAGE (0x0130)

Type-C commands (usb)

  • EC_CMD_TYPEC_DISCOVERY (0x0131)
  • EC_CMD_TYPEC_CONTROL (0x0132)
  • EC_CMD_TYPEC_STATUS (0x0133)
  • EC_CMD_PCHG_COUNT (0x0134)
  • EC_CMD_PCHG (0x0135)
  • EC_CMD_PCHG_UPDATE (0x0136)

Charging related? (charge)

  • EC_CMD_DISPLAY_SOC (0x0137)
  • EC_CMD_SET_BASE_STATE (0x0138)

Subcommands for I2C control (i2c)

  • EC_CMD_I2C_CONTROL (0x0139)

RGB keyboard commands (rgb_keyboard)

  • EC_CMD_RGBKBD_SET_COLOR (0x013A)
  • EC_CMD_RGBKBD (0x013B)

Type C VDM response (usb)

  • EC_CMD_TYPEC_VDM_RESPONSE (0x013C)

Fingerprint MCU commands (fingerprint)

  • EC_CMD_FP_PASSTHRU (0x0400)
  • EC_CMD_FP_MODE (0x0402)
  • EC_CMD_FP_INFO (0x0403)
  • EC_CMD_FP_FRAME (0x0404)
  • EC_CMD_FP_TEMPLATE (0x0405)
  • EC_CMD_FP_CONTEXT (0x0406)
  • EC_CMD_FP_STATS (0x0407)
  • EC_CMD_FP_SEED (0x0408)
  • EC_CMD_FP_ENC_STATUS (0x0409)
  • EC_CMD_FP_READ_MATCH_SECRET (0x040A)
  • EC_CMD_FP_ESTABLISH_PAIRING_KEY_KEYGEN (0x0410)
  • EC_CMD_FP_ESTABLISH_PAIRING_KEY_WRAP (0x0411)

Touchpad MCU commands (touchpad)

  • EC_CMD_TP_SELF_TEST (0x0500)
  • EC_CMD_TP_FRAME_INFO (0x0501)
  • EC_CMD_TP_FRAME_SNAPSHOT (0x0502)
  • EC_CMD_TP_FRAME_GET (0x0503)
Implemented Manufacturer commands

Framework Specific Commands (framework_laptop)

  • EC_CMD_FLASH_NOTIFIED (0x3E01)
  • EC_CMD_FACTORY_MODE (0x3E02)
  • EC_CMD_CHARGE_LIMIT_CONTROL (0x3E03)
  • EC_CMD_PWM_GET_FAN_ACTUAL_RPM (0x3E04)
  • EC_CMD_SET_AP_REBOOT_DELAY (0x3E05)
  • EC_CMD_ME_CONTROL (0x3E06)
  • EC_CMD_NON_ACPI_NOTIFY (0x3E07)
  • EC_CMD_DISABLE_PS2_EMULATION (0x3E08)
  • EC_CMD_CHASSIS_INTRUSION (0x3E09)
  • EC_CMD_BB_RETIMER_CONTROL (0x3E0A)
  • EC_CMD_DIAGNOSIS (0x3E0B)
  • EC_CMD_UPDATE_KEYBOARD_MATRIX (0x3E0C)
  • EC_CMD_VPRO_CONTROL (0x3E0D)
  • EC_CMD_FP_LED_LEVEL_CONTROL (0x3E0E)
  • EC_CMD_CHASSIS_OPEN_CHECK (0x3E0F)
  • EC_CMD_ACPI_NOTIFY (0x3E10)
  • EC_CMD_READ_PD_VERSION (0x3E11)
  • EC_CMD_THERMAL_QEVENT (0x3E12)
  • EC_CMD_STANDALONE_MODE (0x3E13)
  • EC_CMD_PRIVACY_SWITCHES_CHECK_MODE (0x3E14)
  • EC_CMD_CHASSIS_COUNTER (0x3E15)
  • EC_CMD_CHECK_DECK_STATE (0x3E16)
  • EC_CMD_GET_SIMPLE_VERSION (0x3E17)
  • EC_CMD_GET_ACTIVE_CHARGE_PD_CHIP (0x3E18)
  • EC_CMD_UEFI_APP_MODE (0x3E19)
  • EC_CMD_UEFI_APP_BTN_STATUS (0x3E1A)
  • EC_CMD_EXPANSION_BAY_STATUS (0x3E1B)
  • EC_CMD_GET_HW_DIAG (0x3E1C)
  • [?] EC_CMD_GET_GPU_SERIAL (0x3E1D)
  • [?] EC_CMD_GET_GPU_PCIE (0x3E1E)
  • EC_CMD_PROGRAM_GPU_EEPROM (0x3E1F)
  • [?] EC_CMD_FP_CONTROL (0x3E20)
  • EC_CMD_GET_CUTOFF_STATUS (0x3E21)
  • EC_CMD_BATTERY_EXTENDER (0x3E24)

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Steve-Tech from gravatar.com Steve-Tech

Credits

Author: Steve-Tech

License expression

GPL-2.0-or-later
View SPDX License List

Requires

Python >=3.10

Provides Extra

docs lpc

Classifiers

Metadata

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Steve-Tech from gravatar.com Steve-Tech

Credits

Author: Steve-Tech

License expression

GPL-2.0-or-later
View SPDX License List

Requires

Python >=3.10

Provides Extra

docs lpc

Classifiers

Release files for cros-ec-python 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cros-ec-python 0.4.0
File Size Uploaded Provenance Actions
cros_ec_python-0.4.0.tar.gz 49.3 kB Without provenance Details for cros_ec_python-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cros-ec-python 0.4.0
File Interpreter ABI Platform Actions
cros_ec_python-0.4.0-py3-none-any.whl 56.7 kB Without provenance Python 3 none any Details for cros_ec_python-0.4.0-py3-none-any.whl

Total release size: 106.1 kB

Release files / cros_ec_python-0.4.0.tar.gz

Download URL cros_ec_python-0.4.0.tar.gz
Size 49.3 kB
Tags Source
SHA-256 checksum
How to use checksums 		a6836903da1e8c0b2c74a538da845058b6db8264ca8213f052c7f2bde3007453
BLAKE2b-256 checksum
How to use checksums 		ee9e4d10360c6d69f6623c44fba91467a099eede456e6f3ac5e66bc362260416
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/6.1.0 CPython/3.13.12

Release files / cros_ec_python-0.4.0-py3-none-any.whl

Download URL cros_ec_python-0.4.0-py3-none-any.whl
Size 56.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums 		2fd7d62db706a967f2ad649a3f1cd0255019c3fc7aa411d021e5f5b4ec3f8b93
BLAKE2b-256 checksum
How to use checksums 		a426ee5564c942cf5aaa4d4e24c66f527cc99552b9a73e764dde8542909cd250
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/6.1.0 CPython/3.13.12

Security for cros-ec-python 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page