https://github.com/tcsenpai/pybooklid
A simple library to get readings from MacBooks lid angle sensor
https://github.com/tcsenpai/pybooklid
Last synced: 28 days ago
JSON representation
A simple library to get readings from MacBooks lid angle sensor
- Host: GitHub
- URL: https://github.com/tcsenpai/pybooklid
- Owner: tcsenpai
- License: mit
- Created: 2025-09-07T18:06:27.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-09-07T18:16:22.000Z (about 1 month ago)
- Last Synced: 2025-09-08T08:54:01.278Z (about 1 month ago)
- Language: Python
- Size: 11.7 KB
- Stars: 17
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# PyBookLid - MacBook Lid Angle Sensor
A Python library for reading MacBook lid angle sensor data on macOS. This library provides real-time access to the built-in lid angle sensor available on modern MacBooks.
## Features
- **One-shot readings** - Get the current lid angle instantly
- **Continuous monitoring** - Stream angle changes in real-time
- **Adaptive audio synthesis** - Generate door creak sounds that respond to movement
- **Context manager support** - Clean resource management
- **Type hints** - Full typing support for better IDE integration
- **Error handling** - Graceful handling of sensor unavailability
## Requirements
- macOS (tested on Apple Silicon)
- Python 3.7+
- Modern MacBook with lid angle sensor (most 2016+ models)
## Installation
Install from PyPI:
```bash
pip install pybooklid
```
Or install with audio features for creak sound generation:
```bash
pip install pybooklid[audio]
```
The library automatically handles the required `DYLD_LIBRARY_PATH` setup for hidapi on macOS.
### Development Installation
1. Clone this repository:
```bash
git clone
cd pybooklid
```
2. Install in development mode:
```bash
pip install -e .
# Or with audio features
pip install -e .[audio]
```
## Quick Start
### One-shot reading
```python
from pybooklid import read_lid_angle
angle = read_lid_angle()
if angle is not None:
print(f"Current lid angle: {angle:.1f}°")
else:
print("Sensor not available")
```
### Continuous monitoring
```python
from pybooklid import LidSensor
with LidSensor() as sensor:
for angle in sensor.monitor(interval=0.1):
print(f"Angle: {angle:.1f}°")
if angle < 10: # Nearly closed
break
```
### Advanced usage
```python
from pybooklid import LidSensor
# Manual connection management
sensor = LidSensor(auto_connect=False)
try:
sensor.connect()
# Wait for significant movement
new_angle = sensor.wait_for_change(threshold=5.0, timeout=10.0)
if new_angle:
print(f"Lid moved to {new_angle:.1f}°")
# Monitor with callback
def on_angle_change(angle):
print(f"Callback: {angle:.1f}°")
for angle in sensor.monitor(callback=on_angle_change, max_duration=30):
# Process angle data
pass
finally:
sensor.disconnect()
```
## API Reference
### `LidSensor` Class
The main sensor interface class.
#### Methods:
- `__init__(auto_connect=True)` - Initialize sensor, optionally auto-connecting
- `connect()` - Connect to the lid angle sensor
- `disconnect()` - Disconnect from the sensor
- `is_connected()` - Check connection status
- `read_angle()` - Get current angle in degrees (0-180°)
- `monitor(interval=0.1, callback=None, max_duration=None)` - Continuous monitoring iterator
- `wait_for_change(threshold=1.0, timeout=None)` - Wait for angle to change
### Convenience Functions
- `read_lid_angle()` - Quick one-shot reading
- `is_sensor_available()` - Check if sensor is available
### Command Line Tools
After installation, you can use the command line tools:
```bash
# Run basic sensor demo
pybooklid-demo
# Run advanced monitoring app
pybooklid-monitor
```
## Sensor Details
The lid angle sensor reports values in degrees:
- **0°** - Lid fully closed
- **90°** - Lid at right angle
- **~180°** - Lid fully open (varies by MacBook model)
The sensor uses Apple's HID interface:
- **Vendor ID**: 0x05AC (Apple)
- **Product ID**: 0x8104 (Sensor Hub)
- **Usage Page**: 0x0020 (Sensor)
- **Usage**: 0x008A (Orientation)
## Error Handling
The library includes comprehensive error handling:
- `LidSensorError` - Base exception for sensor-related errors
- Graceful degradation when sensor is unavailable
- Automatic reconnection attempts
- Safe cleanup on exit
## Compatibility
Tested on:
- MacBook Pro (Apple Silicon)
- macOS Sonoma/Sequoia
- Python 3.12
Should work on most modern MacBooks with lid angle sensors.
## Example Scripts
### Simple Usage (`examples/simple_usage.py`)
Demonstrates basic sensor usage patterns and gesture detection.
### Advanced Monitor (`examples/monitor_app.py`)
Full-featured monitoring application with statistics, logging, and CSV export.
### Creaky Door Effect (`examples/creaky_door.py`)
Fun demonstration that plays adaptive door creak sounds based on lid movement.
### Real-time Audio Synthesis (`creak_synthesizer.py`)
Advanced audio synthesis that generates realistic door sounds adapting to:
- Movement speed (faster = louder, more intense)
- Lid angle (different positions make different sounds)
- Direction (opening vs closing has different characteristics)
## Troubleshooting
### "Sensor not found" error
- Ensure you're on a supported MacBook model
- Try running with `sudo` if permission issues occur
- Check that no other applications are using the sensor
### Library import errors
- Verify hidapi installation: `pip show hidapi`
- On older macOS, install Homebrew and run `brew install hidapi`
### Inconsistent readings
- The sensor may have noise - use averaging for stable readings
- Some MacBook models may have different angle ranges
## Development
Based on reverse engineering of the IOKit HID interface used by Apple's internal sensor framework.
### Credits
This library was made possible by the reverse engineering work done by Sam Henri Gold in the [LidAngleSensor project](https://github.com/samhenrigold/LidAngleSensor). The key insights about the HID Feature Reports and data format were discovered through that original research.
### Key insights:
- Uses HID Feature Reports (not Input Reports)
- Report ID 1 contains angle data
- Data format: `[report_id, angle_low_byte, angle_high_byte]`
- 16-bit little-endian angle value in degrees
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions welcome! Please test on different MacBook models and report compatibility.