# 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