mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 21:03:01 +00:00
update requirements for web ui
This commit is contained in:
Chuck
351
wiki/WEB_INTERFACE_INSTALLATION.md
Normal file
351
wiki/WEB_INTERFACE_INSTALLATION.md
Normal file
@@ -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
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user