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:**
```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

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](CREDITS.md).

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