Raspberry Pi Helpers

A collection of useful utilities and services for Raspberry Pi systems, designed to make common tasks easier and more automated.

Available Helpers

1. Display Management Service

A comprehensive solution for managing Wayland displays on Raspberry Pi, allowing you to turn displays on/off via SSH and optionally schedule display operations.

Features:

• Turn displays on/off via command line
• Toggle display states
• List available displays
• Set specific display modes
• SSH-friendly (no manual Wayland socket configuration needed)
• Optional systemd service integration
• Scheduled display operations with timers
• Web interface for remote display control (runs on port 80)
• Daily scheduled timers (auto-off at 19:00, auto-on at 7:30)

Requirements:

• Raspberry Pi with Wayland (typically Raspberry Pi OS with desktop)
• wlr-randr package

Tested Environment

This project has been tested and verified on the following environment:

Hardware:

• Raspberry Pi 5 Model B Rev 1.1
• 2x HDMI displays (ChangHong Electric Co.,Ltd 22P610FS)

Operating System:

• Debian GNU/Linux 12 (bookworm)
• Kernel: Linux 6.12.47+rpt-rpi-2712 (aarch64)
• Architecture: ARM64

Software Versions:

• Python: 3.11.2
• pip: 23.0.1
• systemd: 252.39-1~deb12u1
• wlr-randr: 0.2.0-2+rpt1
• python3-venv: 3.11.2-1+b1
• python3-flask: 2.2.2-3 (system package, but web service uses virtual environment)

Display Setup:

• Wayland compositor with wlr-randr support
• 2 HDMI outputs: HDMI-A-1 and HDMI-A-2
• Both displays support up to 1920x1080@75Hz

Note: While tested on this specific configuration, the tools should work on other Raspberry Pi models and Debian-based distributions with Wayland support.

Quick Start

Display Management

1. Install the display management CLI:

   cd display-management
   sudo ./install.sh

2. Basic usage:

   # List available displays
   wlr-display list
   
   # Turn off a display
   wlr-display off HDMI-A-1
   
   # Turn on a display with specific mode
   wlr-display on HDMI-A-1 --mode 1920x1080@60
   
   # Toggle display state
   wlr-display toggle HDMI-A-1

3. Optional: Set up systemd services for automation:

   cd display-management
   ./setup-services.sh

4. Web Service (Optional):

   # Configure connection settings (optional, defaults provided)
   cd display-management/web-service
   cp .env.example .env
   # Edit .env with your Raspberry Pi connection details
   
   # Install and start the web service for remote control
   ./install.sh

   Access the web interface at http://<your-raspberry-pi-host>/

   

   The web interface provides three main controls:

   • Turn All Displays On - Immediately turns on both displays
   • Turn On For 1 Hour - Turns on displays and automatically turns them off after 1 hour
   • Turn All Displays Off - Immediately turns off both displays

5. Scheduled Display Control (Optional):

   # Set up daily timers (off at 19:00, on at 7:30)
   cd display-management
   # Copy timer services to ~/.config/systemd/user/
   cp systemd/display-scheduled-*.{service,timer} ~/.config/systemd/user/
   systemctl --user daemon-reload
   systemctl --user enable --now display-scheduled-off.timer
   systemctl --user enable --now display-scheduled-on.timer

Project Structure

raspberry-pi-helpers/
├── README.md                           # This file
├── LICENSE                             # MIT License
├── display-management/                 # Display management helper
│   ├── README.md                      # Detailed documentation
│   ├── display-setup.md               # Setup documentation
│   ├── install.sh                     # CLI installation script
│   ├── setup-services.sh              # Systemd services setup
│   ├── wlr-display                    # Main CLI script
│   ├── systemd/                       # Systemd service templates
│   │   ├── wlr-display-off@.service
│   │   ├── wlr-display-on@.service
│   │   ├── wlr-display-off-nightly@.service
│   │   ├── wlr-display-off-nightly@.timer
│   │   ├── display-scheduled-off.service
│   │   ├── display-scheduled-on.service
│   │   ├── display-scheduled-off.timer
│   │   └── display-scheduled-on.timer
│   ├── web-service/                   # Web interface
│   │   ├── display_web_service.py    # Flask web application
│   │   ├── display-web.service        # Systemd service
│   │   ├── requirements.txt           # Python dependencies
│   │   ├── install.sh                 # Installation script
│   │   └── web-interface.png          # Web interface screenshot
│   └── examples/                      # Usage examples
│       └── scheduled-displays.md
└── CONTRIBUTING.md                    # Contribution guidelines

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please open an issue on GitHub.