chromebook-volume-buttons/README.md

Chromebook Volume Buttons Driver

Hardware volume button driver for Chromebook devices with non-functional side-mounted volume controls.

Free and Open Source Software

This project is completely free and open source under the MIT License.

You are free to:

• Use this software for any purpose (personal, commercial, educational)
• Study and modify the source code
• Redistribute original or modified versions
• Integrate into your own projects
• Create derivative works

No restrictions except:

• Include the original MIT License and copyright notice
• Provide attribution to the original author

Philosophy: This software is released in the spirit of collaboration and knowledge sharing. It builds upon the work of countless open source contributors (see CREDITS.md) and continues that tradition by remaining completely free for everyone.

Contributions Welcome: Pull requests, bug reports, documentation improvements, and hardware compatibility reports are encouraged and appreciated. See CONTRIBUTING.md for guidelines.

Hardware Compatibility

Primary Target:

• Lenovo IdeaPad Flex 5i Chromebook Gen 8
• Codename: Taeko (Google Brya family)
• Processor: Intel Core i3-1215U
• BIOS: MrChromebox custom firmware

GPIO Configuration:

• Volume Down: GPIO 3 (EC:EC_VOLDN_BTN_ODL)
• Volume Up: GPIO 4 (EC:EC_VOLUP_BTN_ODL)
• Chip: /dev/gpiochip1 (cros-ec-gpio)

Features

• Real-time volume button detection via GPIO polling
• Automatic key repeat after 1 second hold
• Repeat interval: 200ms
• Systemd service for automatic startup
• Low CPU overhead (10ms polling interval)

Prerequisites

Required packages:

sudo pacman -S python-evdev libgpiod

Python dependencies:

• python-gpiod (>= 2.2.0)
• python-evdev (>= 1.9.0)

Installation

Quick Installation

git clone https://gitea.legion-muyue.fr/Muyue/chromebook-volume-buttons.git
cd chromebook-volume-buttons
sudo bash install.sh

Manual Installation

1. Copy the script to system location:

sudo cp volume_buttons.py /usr/local/bin/chromebook-volume-buttons
sudo chmod +x /usr/local/bin/chromebook-volume-buttons

2. Install systemd service:

sudo cp chromebook-volume-buttons.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable chromebook-volume-buttons.service
sudo systemctl start chromebook-volume-buttons.service

Usage

The service starts automatically on boot. Manual control:

# Check status
sudo systemctl status chromebook-volume-buttons.service

# View live logs
sudo journalctl -u chromebook-volume-buttons.service -f

# Restart service
sudo systemctl restart chromebook-volume-buttons.service

# Stop service
sudo systemctl stop chromebook-volume-buttons.service

# Disable auto-start
sudo systemctl disable chromebook-volume-buttons.service

Technical Details

Architecture

The driver operates in userspace by:

1. Reading GPIO states via libgpiod (cros-ec-gpio chip)
2. Detecting button state transitions (pressed/released)
3. Emulating keyboard events via uinput (/dev/input/eventX)
4. Implementing key repeat logic for held buttons

GPIO Signaling

The buttons use Open Drain Low (ODL) logic:

• Value.INACTIVE = Button pressed (LOW)
• Value.ACTIVE = Button released (HIGH)

Timing Specifications

Parameter	Value	Description
Poll Interval	10ms	GPIO sampling rate
Hold Delay	1000ms	Time before repeat starts
Repeat Interval	200ms	Time between repeated events

Troubleshooting

Buttons Not Detected

1. Verify GPIO accessibility:

sudo gpioinfo | grep -E "VOLDN|VOLUP"

Expected output:

line   3: "EC:EC_VOLDN_BTN_ODL" input
line   4: "EC:EC_VOLUP_BTN_ODL" input

2. Check permissions:

ls -l /dev/gpiochip1

3. Verify service status:

sudo systemctl status chromebook-volume-buttons.service

High CPU Usage

Check polling interval in source code (default: 10ms = 0.01s). Adjust POLL_INTERVAL if needed.

Volume Not Changing

Ensure no conflicting volume control services are running. Check with:

ps aux | grep -i volume

Development

Testing Without Service

Run the script directly for debugging:

sudo python3 volume_buttons.py

Press Ctrl+C to stop.

Modifying Timing

Edit the following constants in volume_buttons.py:

self.HOLD_DELAY = 1.0      # Seconds before repeat
self.REPEAT_INTERVAL = 0.2  # Seconds between repeats
POLL_INTERVAL = 0.01        # GPIO polling interval

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome. Please:

1. Test on compatible hardware
2. Follow existing code style
3. Update documentation for changes
4. Submit pull requests with clear descriptions

Hardware Variations

If your Chromebook model differs, check GPIO mappings:

sudo gpioinfo

Look for volume button GPIO lines and update constants in the script:

VOLUME_DOWN_PIN = 3  # Update if different
VOLUME_UP_PIN = 4    # Update if different

References

• ChromiumOS EC GPIO Documentation
• Linux GPIO Userspace API (libgpiod)
• Python evdev Documentation
• MrChromebox Firmware

Author

Muyue

Acknowledgments

This project is possible thanks to the work of many individuals and organizations:

• MrChromebox - Custom UEFI firmware for Chromebooks
• ChromiumOS Team - Embedded controller firmware and documentation
• Linux Kernel Contributors - GPIO subsystem and input subsystem
• libgpiod Project - Bartosz Golaszewski and contributors
• python-evdev - Georgi Valkov and contributors
• Open Source Community - All contributors to tools, libraries, and documentation used

For a complete list of acknowledgments, see CREDITS.md.

This project stands on the shoulders of giants. Thank you to everyone who makes open source possible.