grabowski/wedding-phone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Comprehensive documentation update - v1.2.0

Browse Source 
**CHANGELOG.md Created:**
- Complete version history from 1.0.0 to 1.2.0
- Detailed changelog with all features, changes, fixes
- API endpoints documentation
- Configuration changes documentation
- Upgrade notes from 1.0.0 to 1.2.0
- Known issues and future enhancements

**README.md Enhanced:**
- Added Quick Start section at top
- Added comprehensive Table of Contents
- Updated Python version requirement (3.7 -> 3.8)
- Added UV and Make to software requirements
- Added new API endpoints (backup, delay)
- Expanded Contributing section with guidelines
- Added Version History section (current: v1.2.0)
- Enhanced License section with clear permissions
- Added Credits and Technologies Used sections
- Added Support & Community section
- Added proper closing with emoji
- Updated file structure with CHANGELOG.md
- Better file descriptions in structure

**Documentation Improvements:**
- Clear upgrade path from 1.0.0 to 1.2.0
- All new features documented
- All configuration changes documented
- Better organization with TOC
- More professional presentation
- Complete feature list
- Development guidelines for contributors

**Version Information:**
- Current version: 1.2.0
- Major features: USB backup, systemd service, UV support
- Breaking changes: Python 3.8+ required
- New scripts: setup_usb.sh, install_service.sh
- New commands: make start, make test, make sync

**Key Highlights:**
- ✅ Professional documentation structure
- ✅ Easy to navigate with TOC
- ✅ Quick Start for new users
- ✅ Complete changelog for upgrading
- ✅ Clear contribution guidelines
- ✅ Proper version tracking

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alexander Grabowski
2025-10-24 17:19:31 +07:00
parent 42041006b7
commit 6ff7664f31
2 changed files with 360 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
CHANGELOG.md Normal file
View File

@@ -0,0 +1,218 @@
# Changelog
All notable changes to the Wedding Phone project are documented in this file.
## [1.2.0] - 2025-01-24
### Added
- **USB Backup System with CRC32 Verification**
- Automatic backup to multiple USB drives
- CRC32 checksum verification for data integrity
- Configurable backup paths in config.json
- Web interface for monitoring USB drive status
- Test backup functionality
- Automatic cleanup of corrupted backups
- `setup_usb.sh` script for easy USB drive setup with proper permissions
- **Systemd Service Support**
- `wedding-phone.service` systemd service file
- `install_service.sh` automated service installer
- Auto-start on boot capability
- Automatic restart on failure
- Service log viewing with journalctl
- **UV Package Manager Integration**
- Makefile for simplified commands (`make start`, `make test`, `make sync`)
- UV-based dependency management
- No-build direct script execution
- Faster, more reliable installation
- **Greeting Delay Feature**
- Configurable delay (0-10 seconds) before greeting plays
- Web interface slider for real-time adjustment
- Useful for giving guests time to position phone
- **Extra Button Support**
- Optional GPIO button for playing sounds during recording
- Button sound only plays during recording phase (not greeting)
- Separate PyAudio instance prevents blocking
- Configurable button sound upload via web interface
### Changed
- **Immediate Hook Detection**
- Playback and recording now check GPIO directly for instant response
- No more delays when handset is hung up
- Greeting stops immediately when phone is hung up
- Recording stops immediately when phone is hung up
- **Recording Improvements**
- Minimum 1-second duration required to save recording
- Recordings shorter than 1 second are automatically deleted
- Aborted recordings are cleaned up automatically
- No more empty or accidental recordings
- **Volume Control Enhancement**
- Real-time volume adjustment (0-100%)
- Volume persists in user_config.json
- Applies to both greetings and button sounds
- **Configuration System Overhaul**
- Separated system config (config.json) from runtime config (user_config.json)
- No hardcoded paths (e.g., /home/berwn)
- All GPIO pins configurable
- All paths configurable (relative or absolute)
- Backup settings in configuration
- **Python Version Requirement**
- Updated from Python 3.7+ to Python 3.8+ (Flask requirement)
### Fixed
- **USB Backup Permissions**
- Fixed "Permission denied" errors on USB backup
- Better error messages with fix suggestions
- Proper permission checking for user-mounted drives
- No longer requires running as root
- **UV Build Issues**
- Removed hatchling build system (not needed for scripts)
- Uses `--no-project` mode for direct execution
- Simplified dependency installation
- No more build errors
- **Extra Button Sound Playback**
- Fixed button sound not playing during recording
- Uses separate PyAudio instance to prevent stream conflicts
- Button sound plays completely without interruption
- Recording continues while button sound plays
- **Template Regeneration**
- Templates now regenerate when deleted
- New features appear after template deletion
- Documented template regeneration process
### Security
- **Service Hardening**
- NoNewPrivileges enabled
- PrivateTmp enabled
- Runs as regular user (not root)
- GPIO and audio group access configured
### Documentation
- **Comprehensive README Updates**
- Added USB backup guide with mounting instructions
- Added systemd service installation guide
- Added Makefile usage documentation
- Added greeting delay documentation
- Added extra button operation guide
- Added troubleshooting section expansions
- Updated Python version requirements
- Added UV installation and usage guide
- **New Documentation Files**
- `CHANGELOG.md` - This file
- `setup_usb.sh` - USB drive setup script
### API Endpoints Added
- `GET /api/backup/status` - Get USB backup drive status
- `POST /api/backup/test` - Test backup to all USB drives
- `GET /api/greeting_delay` - Get current greeting delay
- `POST /api/greeting_delay` - Set greeting delay
- `GET /api/volume` - Get current volume
- `POST /api/volume` - Set volume
### Configuration Changes
New sections in `config.json`:
```json
{
"backup": {
"enabled": true,
"usb_paths": ["/media/usb0", "/media/usb1"],
"verify_crc": true,
"backup_on_write": true
},
"gpio": {
"extra_button_enabled": true,
"extra_button_pin": 27,
"extra_button_pressed_state": "LOW"
},
"system": {
"greeting_delay_seconds": 0,
"volume": 70
}
}
```
## [1.0.0] - Initial Release
### Features
- Rotary phone hookswitch detection via GPIO
- Custom greeting message playback
- Voice recording after greeting
- Web interface for file management
- HiFiBerry DAC+ADC Pro support
- Dial tone generation
- Basic configuration via config file
---
## Upgrade Notes
### Upgrading from 1.0.0 to 1.2.0
1. **Update Python version**
```bash
python3 --version # Must be 3.8 or higher
```
2. **Update configuration file**
- Copy `config.example.json` to see new options
- Add `backup` section if using USB backup
- Add `gpio.extra_button_*` if using extra button
- Add `system.greeting_delay_seconds` and `system.volume`
3. **Install UV (recommended)**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
4. **Install dependencies**
```bash
make sync
```
5. **Delete old templates** (to get new web features)
```bash
rm -rf templates/
```
6. **Optional: Install as service**
```bash
./install_service.sh
```
7. **Optional: Setup USB backup**
```bash
sudo ./setup_usb.sh
```
---
## Known Issues
- Template files must be manually deleted to get UI updates (this is by design)
- USB drives must be mounted with proper user permissions for backup to work
- PyAudio installation may require system packages: `sudo apt-get install python3-pyaudio portaudio19-dev`
---
## Future Enhancements
Potential features for future releases:
- Web-based configuration editor
- Multiple language support
- Email notifications for new recordings
- Cloud backup integration
- Mobile app for remote management
- Recording transcription
- Guest photo capture
- QR code generation for easy access

162
README.md
View File

@@ -2,6 +2,63 @@
A Raspberry Pi-based rotary phone system for weddings and events. Guests can pick up the handset to hear custom greeting messages and leave voice recordings. Features a modern web interface for managing messages and recordings.
## Quick Start
```bash
# 1. Clone and enter directory
git clone https://git.b4l.co.th/grabowski/wedding-phone.git
cd wedding-phone
# 2. Install UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. Create config from example
cp config.example.json config.json
nano config.json # Edit GPIO pins and audio device
# 4. Install dependencies
make sync
# 5. Configure HiFiBerry (if using)
./configure_hifiberry.sh
# 6. Test audio
make test
# 7. Run the system
make start
# 8. Optional: Install as service for auto-start
./install_service.sh
# 9. Optional: Setup USB backup
sudo ./setup_usb.sh
```
Web interface available at: `http://<raspberry-pi-ip>:8080`
## Table of Contents
- [Quick Start](#quick-start)
- [Features](#features)
- [Hardware Requirements](#hardware-requirements)
- [Software Requirements](#software-requirements)
- [Installation](#installation)
- [Running the System](#running-the-system)
- [Usage](#usage)
- [Web Interface](#web-interface)
- [Phone Operation](#phone-operation)
- [Extra Button](#extra-button-operation-optional)
- [Greeting Delay](#greeting-delay-optional)
- [USB Backup](#usb-backup-optional)
- [Configuration](#configuration)
- [Systemd Service](#install-as-system-service-optional)
- [Troubleshooting](#troubleshooting)
- [API Endpoints](#api-endpoints)
- [File Structure](#file-structure)
- [Contributing](#contributing)
- [License](#license)
## Features
- **Vintage Phone Integration**: Uses a real rotary phone with GPIO hook detection
@@ -30,13 +87,14 @@ A Raspberry Pi-based rotary phone system for weddings and events. Guests can pic
## Software Requirements
- Raspberry Pi OS (Bullseye or newer)
- Python 3.7+
- Python 3.8+ (required for Flask 2.3+)
- UV package manager (recommended) or pip
- Make (for simplified commands)
- Required Python packages:
- pyaudio
- flask
- numpy
- RPi.GPIO
- wave (built-in)
- flask>=2.3.0
- numpy>=1.21.0
- pyaudio>=0.2.13
- RPi.GPIO>=0.7.1
## Installation
@@ -395,20 +453,21 @@ ls -la /media/usb0 /media/usb1
```
wedding-phone/
├── rotary_phone_web.py # Main application
├── rotary_phone_web.py # Main application (Flask + GPIO + Audio)
├── test_complete.py # Audio testing script
├── configure_hifiberry.sh # HiFiBerry setup script
├── install_service.sh # Systemd service installer
├── setup_usb.sh # USB drive setup with permissions
├── wedding-phone.service # Systemd service file
├── Makefile # Make commands for easy running
├── configure_hifiberry.sh # HiFiBerry DAC+ADC setup script
├── install_service.sh # Systemd service installer (interactive)
├── setup_usb.sh # USB drive setup with permissions (interactive)
├── wedding-phone.service # Systemd service file template
├── Makefile # Make commands (start, test, sync, clean)
├── config.example.json # Example configuration (copy to config.json)
├── pyproject.toml # UV/pip package configuration
├── AUDIO_FIX.md # Audio configuration guide
├── README.md # This file
├── pyproject.toml # Python package configuration
├── AUDIO_FIX.md # Audio troubleshooting guide
├── CHANGELOG.md # Version history and upgrade notes
├── README.md # This file (main documentation)
├── .gitignore # Git ignore rules
└── templates/ # Auto-generated on first run
└── index.html # Web interface (embedded in script)
└── index.html # Web interface (auto-generated from script)
```
**Note:** The `templates/index.html` file is automatically generated when you first run `rotary_phone_web.py`. If you update the script and want to regenerate the template with new features, simply delete the `templates` directory and restart the script.
@@ -560,19 +619,82 @@ The system provides REST API endpoints:
- `GET /download/<filename>` - Download recording
- `POST /delete/<filename>` - Delete recording
- `POST /restore_default_sound` - Generate default dial tone
- `GET /api/backup/status` - Get USB backup drive status
- `POST /api/backup/test` - Test backup to all USB drives
- `GET /api/greeting_delay` - Get current greeting delay
- `POST /api/greeting_delay` - Set greeting delay (0-10 seconds)
## Contributing
Feel free to open issues or submit pull requests for improvements.
Contributions are welcome! Here's how you can help:
1. **Report Bugs**: Open an issue describing the bug and how to reproduce it
2. **Suggest Features**: Open an issue describing your feature idea
3. **Submit Pull Requests**: Fork the repo, make changes, and submit a PR
4. **Improve Documentation**: Help make the docs clearer and more complete
5. **Share Your Experience**: Post photos/videos of your wedding phone setup!
### Development Guidelines
- Follow existing code style
- Test your changes thoroughly
- Update documentation for new features
- Add entries to CHANGELOG.md
- Use descriptive commit messages
## Version History
See [CHANGELOG.md](CHANGELOG.md) for detailed version history and upgrade notes.
**Current Version**: 1.2.0
**Major Updates:**
- ✅ USB backup with CRC verification
- ✅ Systemd service support
- ✅ UV package manager integration
- ✅ Greeting delay control
- ✅ Extra button support
- ✅ Immediate hook detection
- ✅ Configurable everything (no hardcoded paths)
## License
This project is open source and available for personal and commercial use.
**License**: MIT License
Feel free to:
- ✅ Use for personal projects
- ✅ Use for commercial events
- ✅ Modify and customize
- ✅ Redistribute with attribution
## Credits
Created for wedding events to capture guest messages in a unique, nostalgic way.
**Created by**: grabowski
**Purpose**: Capture guest messages at weddings and events in a unique, nostalgic way
**Inspired by**: Vintage telephone systems and the desire to preserve wedding memories
## Support
### Technologies Used
For issues or questions, please open an issue on the repository.
- Python 3.8+
- Flask web framework
- PyAudio for audio handling
- RPi.GPIO for hardware control
- UV package manager
- HiFiBerry DAC+ADC Pro
- Systemd for service management
## Support & Community
- **Issues**: [GitHub Issues](https://git.b4l.co.th/grabowski/wedding-phone/issues)
- **Documentation**: This README and [CHANGELOG.md](CHANGELOG.md)
- **Repository**: https://git.b4l.co.th/grabowski/wedding-phone
## Acknowledgments
Thanks to everyone who has contributed ideas, bug reports, and improvements to make this project better!
---
**Made with ❤️ for preserving wedding memories** 🎉📞💍