make the first time install script more inclusive of user actions

2026-04-10 13:02:59 +00:00 · 2025-08-12 17:42:22 -05:00
parent 2526c6097e
commit 30cf8ee2e8
8 changed files with 457 additions and 62 deletions
--- a/wiki/INSTALLATION_GUIDE.md
+++ b/wiki/INSTALLATION_GUIDE.md
@@ -0,0 +1,334 @@
+# LED Matrix Installation Guide
+
+## Quick Start (Recommended for First-Time Installation)
+
+# System Setup & Installation
+
+1. Open PowerShell and ssh into your Raspberry Pi with ledpi@ledpi (or Username@Hostname)
+```bash
+ssh ledpi@ledpi
+```
+
+2. Update repositories, upgrade raspberry pi OS, install git
+```bash
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y git python3-pip cython3 build-essential python3-dev python3-pillow scons
+```
+
+3. Clone this repository:
+```bash
+git clone https://github.com/ChuckBuilds/LEDMatrix.git
+cd LEDMatrix
+```
+
+4. Install dependencies:
+```bash
+sudo pip3 install --break-system-packages -r requirements.txt
+```
+--break-system-packages allows us to install without a virtual environment
+
+
+5. Install rpi-rgb-led-matrix dependencies:
+```bash
+cd rpi-rgb-led-matrix-master
+```
+```bash
+sudo make build-python PYTHON=$(which python3)
+```
+```bash
+cd bindings/python
+sudo python3 setup.py install
+```
+Test it with:
+```bash
+python3 -c 'from rgbmatrix import RGBMatrix, RGBMatrixOptions; print("Success!")'
+```
+
+## Important: Sound Module Configuration
+
+1. Remove unnecessary services that might interfere with the LED matrix:
+```bash
+sudo apt-get remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
+```
+
+2. Blacklist the sound module:
+```bash
+cat <<EOF | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
+blacklist snd_bcm2835
+EOF
+```
+
+then execute
+
+```bash
+sudo update-initramfs -u
+```
+
+3. Reboot:
+```bash
+sudo reboot
+```
+
+## Performance Optimization
+
+To reduce flickering and improve display quality:
+
+1. Edit `/boot/firmware/cmdline.txt`:
+```bash
+sudo nano /boot/firmware/cmdline.txt
+```
+
+2. Add `isolcpus=3` at the end of the line
+
+3. Ctrl + X to exit, Y to save, Enter to Confirm
+
+4. Edit /boot/firmware/config.txt  with
+```bash
+sudo nano /boot/firmware/config.txt
+```  
+
+6. Edit the `dtparam=audio=on` section to `dtparam=audio=off`
+
+7. Ctrl + X to exit, Y to save, Enter to Confirm
+
+8. Save and reboot:
+```bash
+sudo reboot
+```
+
+9. Run the first_time_install.sh
+```bash
+chmod +x first_time_install.sh
+sudo ./first_time_install.sh
+```
+
+This handles dependency setup, service installation, permissions, and sudoers configuration.
+
+10. Web Interface (V2)
+
+- If `"web_display_autostart": true` is set in `config/config.json` (recommended), the web interface will be started by the installed service.
+- Access the web UI at:
+```
+http://your-pi-ip:5001
+```
+- To launch manually instead of using the service:
+```bash
+python3 start_web_v2.py
+```
+This installs any missing dependencies and starts `web_interface_v2.py` on port 5001.
+-----------------------------------------------------------------------------------
+
+## Configuration
+
+1.Edit `config/config.json` with your preferences via `sudo nano config/config.json`
+
+###API Keys
+
+For sensitive settings like API keys:
+Copy the template: `cp config/config_secrets.template.json config/config_secrets.json`
+Edit `config/config_secrets.json` with your API keys via `sudo nano config/config_secrets.json`
+Ctrl + X to exit, Y to overwrite, Enter to Confirm
+
+Everything is configured via `config/config.json` and `config/config_secrets.json`.
+
+
+For a complete first-time installation, run:
+
+```bash
+chmod +x first_time_install.sh
+```
+then
+
+```bash
+sudo ./first_time_install.sh
+```
+
+This single script handles everything you need for a new installation.
+
+## Individual Scripts Explained
+
+### **First-Time Installation Scripts**
+
+#### `first_time_install.sh` ⭐ **RECOMMENDED**
+- **When to use**: New installations only
+- **What it does**: Complete setup including all steps below
+- **Usage**: `sudo ./first_time_install.sh`
+
+### **Service Installation Scripts**
+
+#### `install_service.sh`
+- **When to use**: Install main LED Matrix display service
+- **What it does**: 
+  - Creates systemd service for main display
+  - Creates systemd service for web interface
+  - Enables services to start on boot
+- **Usage**: `sudo ./install_service.sh`
+
+#### `install_web_service.sh`
+- **When to use**: Install only the web interface service (legacy)
+- **What it does**: Installs the web interface systemd service
+- **Usage**: `sudo ./install_web_service.sh`
+- **Note**: `install_service.sh` now handles this automatically
+
+### **Permission Fix Scripts**
+
+#### `fix_cache_permissions.sh`
+- **When to use**: When you see cache permission errors
+- **What it does**:
+  - Creates cache directories (`/var/cache/ledmatrix`)
+  - Sets proper permissions for cache access
+  - Creates placeholder logo directories
+- **Usage**: `sudo ./fix_cache_permissions.sh`
+
+#### `fix_web_permissions.sh`
+- **When to use**: When web interface can't access logs or system commands
+- **What it does**:
+  - Adds user to `systemd-journal` group (for log access)
+  - Adds user to `adm` group (for system access)
+  - Sets proper file ownership
+- **Usage**: `./fix_web_permissions.sh` (run as regular user)
+
+#### `configure_web_sudo.sh`
+- **When to use**: When web interface buttons don't work (sudo password errors)
+- **What it does**:
+  - Configures passwordless sudo access for web interface
+  - Allows web interface to start/stop services without password
+- **Usage**: `./configure_web_sudo.sh` (run as regular user)
+
+### **Dependency Installation Scripts**
+
+#### `install_dependencies_apt.py`
+- **When to use**: When you want to install packages via apt first, then pip
+- **What it does**:
+  - Tries to install packages via apt (system packages)
+  - Falls back to pip with `--break-system-packages`
+  - Handles externally managed Python environments
+- **Usage**: `sudo python3 install_dependencies_apt.py`
+
+#### `start_web_v2.py`
+- **When to use**: Manual web interface startup
+- **What it does**:
+  - Installs dependencies
+  - Starts web interface directly
+  - Includes comprehensive logging
+- **Usage**: `python3 start_web_v2.py`
+
+#### `run_web_v2.sh`
+- **When to use**: Manual web interface startup (shell script version)
+- **What it does**: Same as `start_web_v2.py` but as a shell script
+- **Usage**: `./run_web_v2.sh`
+
+### **Utility Scripts**
+
+#### `cleanup_venv.sh`
+- **When to use**: Remove virtual environment if you don't want to use it
+- **What it does**: Removes `venv_web_v2` directory
+- **Usage**: `./cleanup_venv.sh`
+
+#### `start_web_conditionally.py`
+- **When to use**: Called by systemd service (don't run manually)
+- **What it does**:
+  - Checks config for `web_display_autostart` setting
+  - Starts web interface only if enabled
+  - Used by the systemd service
+
+## Installation Scenarios
+
+### **Scenario 1: Brand New Installation**
+```bash
+# One command does everything
+sudo ./first_time_install.sh
+```
+
+### **Scenario 2: Adding Web Interface to Existing Installation**
+```bash
+# Install web interface dependencies
+sudo python3 install_dependencies_apt.py
+
+# Fix permissions
+./fix_web_permissions.sh
+
+# Configure sudo access
+./configure_web_sudo.sh
+
+# Install services
+sudo ./install_service.sh
+```
+
+### **Scenario 3: Fixing Permission Issues**
+```bash
+# Fix cache permissions
+sudo ./fix_cache_permissions.sh
+
+# Fix web interface permissions
+./fix_web_permissions.sh
+
+# Configure sudo access
+./configure_web_sudo.sh
+
+# Log out and back in for group changes to take effect
+```
+
+### **Scenario 4: Manual Web Interface Startup**
+```bash
+# Start web interface manually (for testing)
+python3 start_web_v2.py
+```
+
+## Post-Installation Steps
+
+### **1. Log Out and Log Back In**
+After running permission scripts, you need to log out and back in for group changes to take effect:
+```bash
+# Or use this command to apply group changes immediately
+newgrp systemd-journal
+```
+
+### **2. Configure the Web Interface**
+Edit `config/config.json` and set:
+```json
+{
+    "web_display_autostart": true
+}
+```
+
+### **3. Access the Web Interface**
+Open your browser and go to:
+```
+http://your-pi-ip:5001
+```
+
+### **4. Test Everything**
+- Check if services are running: `sudo systemctl status ledmatrix.service`
+- Check web interface: `sudo systemctl status ledmatrix-web.service`
+- View logs: `journalctl -u ledmatrix.service -f`
+
+## Troubleshooting
+
+### **Web Interface Not Accessible**
+1. Check if service is running: `sudo systemctl status ledmatrix-web.service`
+2. Check logs: `journalctl -u ledmatrix-web.service -f`
+3. Ensure `web_display_autostart` is `true` in config
+
+### **Permission Errors**
+1. Run: `./fix_web_permissions.sh`
+2. Run: `./configure_web_sudo.sh`
+3. Log out and back in
+
+### **Cache Permission Errors**
+1. Run: `sudo ./fix_cache_permissions.sh`
+
+### **Sudo Password Prompts**
+1. Run: `./configure_web_sudo.sh`
+2. Log out and back in
+
+### **Dependency Installation Errors**
+1. Run: `sudo python3 install_dependencies_apt.py`
+
+## Summary
+
+For **first-time installations**: Use `first_time_install.sh`
+
+For **existing installations with issues**: Use the individual permission and configuration scripts as needed.
+
+The `first_time_install.sh` script is designed to handle everything automatically, so you typically only need to run individual scripts if you're troubleshooting specific issues.
--- a/wiki/WEB_INTERFACE_INSTALLATION.md
+++ b/wiki/WEB_INTERFACE_INSTALLATION.md
@@ -17,7 +17,7 @@ The web interface provides:

 ### Prerequisites

- LEDMatrix system already installed and configured
+- LEDMatrix system already installed and configured (or run `first_time_install.sh` first)
 - Python 3.7+ installed
 - Network access to the Raspberry Pi

--- a/wiki/WIKI_HOME.md
+++ b/wiki/WIKI_HOME.md
@@ -38,6 +38,10 @@ Detailed documentation for each display manager and their configuration options.
 - [General Troubleshooting](WIKI_TROUBLESHOOTING.md)
 - [MiLB Troubleshooting](MILB_TROUBLESHOOTING.md)

+## 🚀 Install & Quick Start
+- [Installation Guide](INSTALLATION_GUIDE.md)
+- [Quick Start](WIKI_QUICK_START.md)
+
 ---

 ## Quick Navigation
--- a/wiki/WIKI_QUICK_START.md
+++ b/wiki/WIKI_QUICK_START.md
@@ -2,6 +2,23 @@

 Get your LEDMatrix system up and running in minutes! This guide covers the essential steps to get your display working.

+## Fast Path (Recommended)
+
+If this is a brand new install, you can run the all-in-one installer and then use the web UI:
+
+```bash
+chmod +x first_time_install.sh
+sudo ./first_time_install.sh
+```
+
+Then open the web UI at:
+
+```
+http://your-pi-ip:5001
+```
+
+The steps below document the manual process for advanced users.
+
 ## Prerequisites

 ### Hardware Requirements
@@ -219,7 +236,23 @@ sudo ./start_display.sh
 sudo ./stop_display.sh
 ```

-## Step 8: Add More Features
+## Step 8: Web Interface (V2)
+
+### 8.1 Start the web interface manually (optional)
+```bash
+python3 start_web_v2.py
+```
+
+### 8.2 Autostart the web interface (recommended)
+Set `"web_display_autostart": true` in `config/config.json`.
+The installed `ledmatrix-web.service` will call `start_web_conditionally.py` to start the web UI on boot.
+
+Access the web interface at:
+```
+http://your-pi-ip:5001
+```
+
+## Step 9: Add More Features

 ### 8.1 Enable Stocks
 Edit `config/config.json`:
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -0,0 +1,30 @@
+## LEDMatrix Wiki
+
+- [Home](WIKI_HOME.md)
+
+### Get Started
+- [Quick Start](WIKI_QUICK_START.md)
+- [Installation Guide](INSTALLATION_GUIDE.md)
+
+### Configure & Use
+- [Configuration Guide](WIKI_CONFIGURATION.md)
+- [Display Managers](WIKI_DISPLAY_MANAGERS.md)
+- [Web Interface Installation](WEB_INTERFACE_INSTALLATION.md)
+- [Web Interface V2 Enhancements](WEB_INTERFACE_V2_ENHANCED_SUMMARY.md)
+
+### Features
+- [News Manager](NEWS_MANAGER_README.md)
+- [Custom RSS Feeds](CUSTOM_FEEDS_GUIDE.md)
+- [Dynamic Duration (Overview)](dynamic_duration.md)
+- [Dynamic Duration Guide](DYNAMIC_DURATION_GUIDE.md)
+- [Dynamic Duration (Stocks)](DYNAMIC_DURATION_STOCKS_IMPLEMENTATION.md)
+
+### Performance & Caching
+- [Cache Strategy](CACHE_STRATEGY.md)
+- [Cache Management](cache_management.md)
+
+### Troubleshooting
+- [General Troubleshooting](WIKI_TROUBLESHOOTING.md)
+- [MiLB Troubleshooting](MILB_TROUBLESHOOTING.md)
+
+