From 151777fbd650d707d5e2e52285336a7faa00db31 Mon Sep 17 00:00:00 2001 From: Chuck <33324927+ChuckBuilds@users.noreply.github.com> Date: Sun, 10 Aug 2025 21:22:36 -0500 Subject: [PATCH] update requirements for web ui --- README.md | 96 ++++++++ requirements_web_v2.txt | 5 +- start_web_conditionally.py | 80 ++++++- wiki/WEB_INTERFACE_INSTALLATION.md | 351 +++++++++++++++++++++++++++++ wiki/WIKI_HOME.md | 3 + 5 files changed, 528 insertions(+), 7 deletions(-) create mode 100644 wiki/WEB_INTERFACE_INSTALLATION.md diff --git a/README.md b/README.md index 5b174cbf..e4aec5ba 100644 --- a/README.md +++ b/README.md @@ -867,6 +867,102 @@ sudo ./start_display.sh sudo ./stop_display.sh ``` +----------------------------------------------------------------------------------- + +## Web Interface Installation + +The LEDMatrix system includes a web interface that allows you to control and configure the display remotely. The web interface runs on port 5001 and provides real-time display preview, configuration management, and on-demand display controls. + +### Installing the Web Interface Service + +1. Make the install script executable: +```bash +chmod +x install_web_service.sh +``` + +2. Run the install script with sudo: +```bash +sudo ./install_web_service.sh +``` + +The script will: +- Copy the web service file to `/etc/systemd/system/` +- Enable the service to start on boot +- Start the service immediately +- Show the service status + +### Web Interface Configuration + +The web interface can be configured to start automatically with the main display service: + +1. In `config/config.json`, ensure the web interface autostart is enabled: +```json +{ + "web_display_autostart": true +} +``` + +2. The web interface will now start automatically when: + - The system boots + - The `web_display_autostart` setting is `true` in your config + +### Accessing the Web Interface + +Once installed, you can access the web interface at: +``` +http://your-pi-ip:5001 +``` + +### Managing the Web Interface Service + +```bash +# Check service status +sudo systemctl status ledmatrix-web.service + +# View logs +journalctl -u ledmatrix-web.service -f + +# Stop the service +sudo systemctl stop ledmatrix-web.service + +# Start the service +sudo systemctl start ledmatrix-web.service + +# Disable autostart +sudo systemctl disable ledmatrix-web.service + +# Enable autostart +sudo systemctl enable ledmatrix-web.service +``` + +### Web Interface Features + +- **Real-time Display Preview**: See what's currently displayed on the LED matrix +- **Configuration Management**: Edit settings through a web interface +- **On-Demand Controls**: Start specific displays (weather, stocks, sports) on demand +- **Service Management**: Start/stop the main display service +- **System Controls**: Restart, update code, and manage the system +- **API Metrics**: Monitor API usage and system performance +- **Logs**: View system logs in real-time + +### Troubleshooting Web Interface + +**Web Interface Not Accessible After Restart:** +1. Check if the web service is running: `sudo systemctl status ledmatrix-web.service` +2. Verify the service is enabled: `sudo systemctl is-enabled ledmatrix-web.service` +3. Check logs for errors: `journalctl -u ledmatrix-web.service -f` +4. Ensure `web_display_autostart` is set to `true` in `config/config.json` + +**Port 5001 Not Accessible:** +1. Check if the service is running on the correct port +2. Verify firewall settings allow access to port 5001 +3. Check if another service is using port 5001 + +**Service Fails to Start:** +1. Check Python dependencies are installed +2. Verify the virtual environment is set up correctly +3. Check file permissions and ownership + ----------------------------------------------------------------------------------- diff --git a/requirements_web_v2.txt b/requirements_web_v2.txt index 4696b7b3..dadfec68 100644 --- a/requirements_web_v2.txt +++ b/requirements_web_v2.txt @@ -5,4 +5,7 @@ eventlet>=0.33.3 Pillow>=10.0.0 psutil>=5.9.0 werkzeug>=2.3.0 -freetype-py>=2.3.0 \ No newline at end of file +freetype-py>=2.3.0 +numpy>=1.21.0 +requests>=2.25.0 +python-dateutil>=2.8.0 \ No newline at end of file diff --git a/start_web_conditionally.py b/start_web_conditionally.py index 78be6803..60564c00 100644 --- a/start_web_conditionally.py +++ b/start_web_conditionally.py @@ -2,19 +2,78 @@ import json import os import sys import subprocess +from pathlib import Path PROJECT_DIR = os.path.dirname(os.path.abspath(__file__)) CONFIG_FILE = os.path.join(PROJECT_DIR, 'config', 'config.json') WEB_INTERFACE_SCRIPT = os.path.join(PROJECT_DIR, 'web_interface_v2.py') + +def setup_virtual_environment(): + """Set up a virtual environment for the web interface if it doesn't exist.""" + venv_path = Path(PROJECT_DIR) / 'venv_web_v2' + + if not venv_path.exists(): + print("Creating virtual environment...") + try: + subprocess.check_call([ + sys.executable, '-m', 'venv', str(venv_path) + ]) + print("Virtual environment created successfully") + except subprocess.CalledProcessError as e: + print(f"Failed to create virtual environment: {e}") + return None + + return venv_path + +def get_venv_python(venv_path): + """Get the Python executable path from the virtual environment.""" + if os.name == 'nt': # Windows + return venv_path / 'Scripts' / 'python.exe' + else: # Unix/Linux + return venv_path / 'bin' / 'python' + +def get_venv_pip(venv_path): + """Get the pip executable path from the virtual environment.""" + if os.name == 'nt': # Windows + return venv_path / 'Scripts' / 'pip.exe' + else: # Unix/Linux + return venv_path / 'bin' / 'pip' + +def install_dependencies(venv_path): + """Install required dependencies in the virtual environment.""" + print("Installing dependencies...") + try: + venv_pip = get_venv_pip(venv_path) + requirements_file = os.path.join(PROJECT_DIR, 'requirements_web_v2.txt') + subprocess.check_call([ + str(venv_pip), 'install', '-r', requirements_file + ]) + print("Dependencies installed successfully") + + # Install rgbmatrix module from local source + print("Installing rgbmatrix module...") + rgbmatrix_path = Path(PROJECT_DIR) / 'rpi-rgb-led-matrix-master' / 'bindings' / 'python' + if rgbmatrix_path.exists(): + subprocess.check_call([ + str(venv_pip), 'install', '-e', str(rgbmatrix_path) + ], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + print("rgbmatrix module installed successfully") + + return True + except subprocess.CalledProcessError as e: + print(f"Failed to install dependencies: {e}") + return False + def get_python_executable(): """Prefer the venv_web_v2 Python if present, else fall back to current interpreter.""" project_dir = PROJECT_DIR - if os.name == 'nt': - venv_python = os.path.join(project_dir, 'venv_web_v2', 'Scripts', 'python.exe') - else: - venv_python = os.path.join(project_dir, 'venv_web_v2', 'bin', 'python') - if os.path.exists(venv_python): - return venv_python + venv_path = Path(project_dir) / 'venv_web_v2' + + if venv_path.exists(): + venv_python = get_venv_python(venv_path) + if venv_python.exists(): + return str(venv_python) + return sys.executable def main(): @@ -32,6 +91,15 @@ def main(): if autostart_enabled is True: # Explicitly check for True print("Configuration 'web_display_autostart' is true. Starting web interface...") + + # Set up virtual environment if it doesn't exist + venv_path = setup_virtual_environment() + if venv_path: + # Install dependencies + if not install_dependencies(venv_path): + print("Failed to install dependencies. Exiting.") + sys.exit(1) + try: # Replace the current process with web_interface.py # This is important for systemd to correctly manage the web server process. diff --git a/wiki/WEB_INTERFACE_INSTALLATION.md b/wiki/WEB_INTERFACE_INSTALLATION.md new file mode 100644 index 00000000..b3ff25a2 --- /dev/null +++ b/wiki/WEB_INTERFACE_INSTALLATION.md @@ -0,0 +1,351 @@ +# Web Interface Installation Guide + +The LEDMatrix system includes a modern web interface that allows you to control and configure the display remotely. This guide covers installation, configuration, and troubleshooting. + +## Overview + +The web interface provides: +- **Real-time Display Preview**: See what's currently displayed on the LED matrix +- **Configuration Management**: Edit settings through a web interface +- **On-Demand Controls**: Start specific displays (weather, stocks, sports) on demand +- **Service Management**: Start/stop the main display service +- **System Controls**: Restart, update code, and manage the system +- **API Metrics**: Monitor API usage and system performance +- **Logs**: View system logs in real-time + +## Installation + +### Prerequisites + +- LEDMatrix system already installed and configured +- Python 3.7+ installed +- Network access to the Raspberry Pi + +### Step 1: Install the Web Interface Service + +1. Navigate to your LEDMatrix directory: +```bash +cd /home/ledpi/LEDMatrix +``` + +2. Make the install script executable: +```bash +chmod +x install_web_service.sh +``` + +3. Run the install script with sudo: +```bash +sudo ./install_web_service.sh +``` + +The script will: +- Copy the web service file to `/etc/systemd/system/` +- Reload systemd to recognize the new service +- Enable the service to start on boot +- Start the service immediately +- Show the service status + +**Note**: The first time the service starts, it will automatically: +- Create a Python virtual environment (`venv_web_v2`) +- Install required dependencies (Flask, numpy, requests, etc.) +- Install the rgbmatrix module from the local source + +This process may take a few minutes on the first run. + +### Step 2: Configure Web Interface Autostart + +1. Edit your configuration file: +```bash +sudo nano config/config.json +``` + +2. Ensure the web interface autostart is enabled: +```json +{ + "web_display_autostart": true +} +``` + +3. Save and exit (Ctrl+X, Y, Enter) + +### Step 3: Access the Web Interface + +Once installed, you can access the web interface at: +``` +http://your-pi-ip:5001 +``` + +Replace `your-pi-ip` with your Raspberry Pi's IP address. + +## Service Management + +### Check Service Status +```bash +sudo systemctl status ledmatrix-web.service +``` + +### View Service Logs +```bash +journalctl -u ledmatrix-web.service -f +``` + +### Start/Stop the Service +```bash +# Start the service +sudo systemctl start ledmatrix-web.service + +# Stop the service +sudo systemctl stop ledmatrix-web.service + +# Restart the service +sudo systemctl restart ledmatrix-web.service +``` + +### Enable/Disable Autostart +```bash +# Enable autostart on boot +sudo systemctl enable ledmatrix-web.service + +# Disable autostart on boot +sudo systemctl disable ledmatrix-web.service +``` + +## Web Interface Features + +### Overview Tab +- System status and uptime +- Current display mode +- API usage metrics +- Quick controls for starting/stopping services + +### Configuration Tab +- Edit main configuration settings +- Modify display durations +- Configure sports teams and preferences +- Update API keys and endpoints + +### Sports Tab +- Configure individual sports leagues +- Set favorite teams +- Enable/disable specific display modes +- On-demand controls for each sport + +### Weather Tab +- Configure weather settings +- Set location and units +- On-demand weather display controls + +### Stocks Tab +- Configure stock and crypto symbols +- Set update intervals +- On-demand stock display controls + +### On-Demand Controls +- Start specific displays immediately +- Stop on-demand displays +- View current on-demand status + +## Troubleshooting + +### Web Interface Not Accessible After Restart + +**Symptoms:** +- Can't access `http://your-pi-ip:5001` after system restart +- Service appears to be running but web interface doesn't respond + +**Diagnosis:** +1. Check if the web service is running: +```bash +sudo systemctl status ledmatrix-web.service +``` + +2. Verify the service is enabled: +```bash +sudo systemctl is-enabled ledmatrix-web.service +``` + +3. Check logs for errors: +```bash +journalctl -u ledmatrix-web.service -f +``` + +4. Ensure `web_display_autostart` is set to `true` in `config/config.json` + +**Solutions:** +1. If service is not running, start it: +```bash +sudo systemctl start ledmatrix-web.service +``` + +2. If service is not enabled, enable it: +```bash +sudo systemctl enable ledmatrix-web.service +``` + +3. If configuration is incorrect, fix it: +```bash +sudo nano config/config.json +# Set "web_display_autostart": true +``` + +### Port 5001 Not Accessible + +**Symptoms:** +- Connection refused on port 5001 +- Service running but can't connect + +**Diagnosis:** +1. Check if the service is running on the correct port: +```bash +sudo netstat -tlnp | grep 5001 +``` + +2. Verify firewall settings: +```bash +sudo ufw status +``` + +3. Check if another service is using port 5001: +```bash +sudo lsof -i :5001 +``` + +**Solutions:** +1. If port is blocked by firewall, allow it: +```bash +sudo ufw allow 5001 +``` + +2. If another service is using the port, stop it or change the web interface port + +### Service Fails to Start + +**Symptoms:** +- Service shows as failed in systemctl status +- Error messages in logs +- Common error: `ModuleNotFoundError: No module named 'numpy'` + +**Diagnosis:** +1. Check service logs: +```bash +journalctl -u ledmatrix-web.service -n 50 +``` + +2. Verify Python dependencies: +```bash +python3 -c "import flask, flask_socketio, PIL, numpy" +``` + +3. Check virtual environment: +```bash +ls -la venv_web_v2/ +``` + +**Solutions:** +1. **Most Common Fix**: The service will automatically create the virtual environment and install dependencies on first run. If it fails, restart the service: +```bash +sudo systemctl restart ledmatrix-web.service +``` + +2. If dependencies are missing, install them manually: +```bash +# Create virtual environment +python3 -m venv venv_web_v2 +source venv_web_v2/bin/activate +pip install -r requirements_web_v2.txt + +# Install rgbmatrix module +pip install -e rpi-rgb-led-matrix-master/bindings/python +``` + +3. If virtual environment is corrupted, recreate it: +```bash +rm -rf venv_web_v2 +sudo systemctl restart ledmatrix-web.service +``` + +4. If permissions are wrong, fix them: +```bash +sudo chown -R ledpi:ledpi /home/ledpi/LEDMatrix +sudo chmod +x install_web_service.sh +``` + +### Import Errors + +**Symptoms:** +- Service fails with ImportError messages +- Main display service also fails to start + +**Cause:** +The source modules try to import from `web_interface_v2`, which can fail when the web interface isn't running. + +**Solution:** +The import errors have been fixed with try/except blocks. If you still see issues, ensure all source files have the proper import handling: + +```python +try: + from web_interface_v2 import increment_api_counter +except ImportError: + # Fallback if web interface is not available + def increment_api_counter(kind: str, count: int = 1): + pass +``` + +## Manual Installation (Alternative) + +If the automated installation script doesn't work, you can install manually: + +1. Copy the service file: +```bash +sudo cp ledmatrix-web.service /etc/systemd/system/ +``` + +2. Reload systemd: +```bash +sudo systemctl daemon-reload +``` + +3. Enable and start the service: +```bash +sudo systemctl enable ledmatrix-web.service +sudo systemctl start ledmatrix-web.service +``` + +## Security Considerations + +- The web interface runs on port 5001 by default +- Consider using a reverse proxy (nginx) for production use +- Change default ports if needed +- Use HTTPS in production environments +- Restrict access to trusted networks + +## Uninstallation + +To remove the web interface service: + +1. Stop and disable the service: +```bash +sudo systemctl stop ledmatrix-web.service +sudo systemctl disable ledmatrix-web.service +``` + +2. Remove the service file: +```bash +sudo rm /etc/systemd/system/ledmatrix-web.service +``` + +3. Reload systemd: +```bash +sudo systemctl daemon-reload +``` + +4. Set `web_display_autostart` to `false` in `config/config.json` if desired + +## Support + +If you continue to have issues: + +1. Check the main README.md for general troubleshooting +2. Review the service logs for specific error messages +3. Verify your system meets all prerequisites +4. Ensure all dependencies are properly installed diff --git a/wiki/WIKI_HOME.md b/wiki/WIKI_HOME.md index da1228fc..9b596277 100644 --- a/wiki/WIKI_HOME.md +++ b/wiki/WIKI_HOME.md @@ -29,6 +29,9 @@ Step-by-step instructions for setting up your Raspberry Pi for LEDMatrix. ## 🚀 [Installation & Deployment](WIKI_INSTALLATION.md) Complete installation process, service setup, and deployment options. +## 🌐 [Web Interface Installation](WEB_INTERFACE_INSTALLATION.md) +Install and configure the web interface for remote control and configuration. + ## 🔐 [API Authentication](WIKI_API_AUTH.md) How to set up API keys and authentication for all supported services.