LEDMatrix/wiki/WEB_INTERFACE_INSTALLATION.md

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:

cd /home/ledpi/LEDMatrix

2. Make the install script executable:

chmod +x install_web_service.sh

3. Run the install script with sudo:

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:

sudo nano config/config.json

2. Ensure the web interface autostart is enabled:

{
    "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

sudo systemctl status ledmatrix-web.service

View Service Logs

journalctl -u ledmatrix-web.service -f

Start/Stop the Service

# 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

# 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:

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

Solutions:

1. If service is not running, start it:

sudo systemctl start ledmatrix-web.service

2. If service is not enabled, enable it:

sudo systemctl enable ledmatrix-web.service

3. If configuration is incorrect, fix it:

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:

sudo netstat -tlnp | grep 5001

2. Verify firewall settings:

sudo ufw status

3. Check if another service is using port 5001:

sudo lsof -i :5001

Solutions:

1. If port is blocked by firewall, allow it:

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:

journalctl -u ledmatrix-web.service -n 50

2. Verify Python dependencies:

python3 -c "import flask, flask_socketio, PIL, numpy"

3. Check virtual environment:

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:

sudo systemctl restart ledmatrix-web.service

2. If dependencies are missing, install them manually:

# 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:

rm -rf venv_web_v2
sudo systemctl restart ledmatrix-web.service

4. If permissions are wrong, fix them:

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:

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:

sudo cp ledmatrix-web.service /etc/systemd/system/

2. Reload systemd:

sudo systemctl daemon-reload

3. Enable and start the service:

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:

sudo systemctl stop ledmatrix-web.service
sudo systemctl disable ledmatrix-web.service

2. Remove the service file:

sudo rm /etc/systemd/system/ledmatrix-web.service

3. Reload systemd:

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