Chromebook Volume Buttons Driver

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

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

• MrChromebox for custom BIOS support
• ChromiumOS embedded controller team
• Linux GPIO subsystem maintainers