Muyue
bc9d6f8639
Add GPIO-based volume button driver for Lenovo IdeaPad Flex 5i Chromebook Gen 8 Features: - Volume button detection via GPIO polling - Key repeat with configurable timings - Systemd service integration - Professional documentation
207 lines
4.4 KiB
Markdown
207 lines
4.4 KiB
Markdown
# 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:**
|
|
```bash
|
|
sudo pacman -S python-evdev libgpiod
|
|
```
|
|
|
|
**Python dependencies:**
|
|
- python-gpiod (>= 2.2.0)
|
|
- python-evdev (>= 1.9.0)
|
|
|
|
## Installation
|
|
|
|
### Quick Installation
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
sudo cp volume_buttons.py /usr/local/bin/chromebook-volume-buttons
|
|
sudo chmod +x /usr/local/bin/chromebook-volume-buttons
|
|
```
|
|
|
|
2. Install systemd service:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
ls -l /dev/gpiochip1
|
|
```
|
|
|
|
3. Verify service status:
|
|
```bash
|
|
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:
|
|
```bash
|
|
ps aux | grep -i volume
|
|
```
|
|
|
|
## Development
|
|
|
|
### Testing Without Service
|
|
|
|
Run the script directly for debugging:
|
|
```bash
|
|
sudo python3 volume_buttons.py
|
|
```
|
|
|
|
Press Ctrl+C to stop.
|
|
|
|
### Modifying Timing
|
|
|
|
Edit the following constants in `volume_buttons.py`:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
sudo gpioinfo
|
|
```
|
|
|
|
Look for volume button GPIO lines and update constants in the script:
|
|
```python
|
|
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
|