Initial release v1.0.0

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

README.md

@@ -0,0 +1,206 @@
+# 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