LEDMatrix/docs/GETTING_STARTED.md

Getting Started with LEDMatrix

Welcome

This guide will help you set up your LEDMatrix display for the first time and get it running in under 30 minutes.

---

Prerequisites

Hardware:

• Raspberry Pi (3, 4, or 5 recommended)
• RGB LED Matrix panel (32x64 or 64x64)
• Adafruit RGB Matrix HAT or similar
• Power supply (5V, 4A minimum recommended)
• MicroSD card (16GB minimum)

Network:

• WiFi network (or Ethernet cable)
• Computer with web browser on same network

---

Quick Start (5 Minutes)

1. First Boot

1. Insert the MicroSD card with LEDMatrix installed
2. Connect the LED matrix to your Raspberry Pi
3. Plug in the power supply
4. Wait for the Pi to boot (about 60 seconds)

Expected Behavior:

• LED matrix will light up
• Display will show default plugins (clock, weather, etc.)
• Pi creates WiFi network "LEDMatrix-Setup" if not connected

2. Connect to WiFi

If you see "LEDMatrix-Setup" WiFi network:

1. Connect your device to "LEDMatrix-Setup" (open network, no password)
2. Open browser to: http://192.168.4.1:5050
3. Navigate to the WiFi tab
4. Click "Scan" to find your WiFi network
5. Select your network, enter password
6. Click "Connect"
7. Wait for connection (LED matrix will show confirmation)

If already connected to WiFi:

1. Find your Pi's IP address (check your router, or run hostname -I on the Pi)
2. Open browser to: http://your-pi-ip:5050

3. Access the Web Interface

Once connected, access the web interface:

http://your-pi-ip:5050

You should see:

• Overview tab with system stats
• Live display preview
• Quick action buttons

---

Initial Configuration (15 Minutes)

Step 1: Configure Display Hardware

1. Navigate to Settings → Display Settings
2. Set your matrix configuration:
   • Rows: 32 or 64 (match your hardware)
   • Columns: 64, 128, or 256 (match your hardware)
   • Chain Length: Number of panels chained together
   • Brightness: 50-75% recommended for indoor use
3. Click Save Configuration
4. Click Restart Display to apply changes

Tip: If the display doesn't look right, try different hardware mapping options.

Step 2: Set Timezone and Location

1. Navigate to Settings → General Settings
2. Set your timezone (e.g., "America/New_York")
3. Set your location (city, state, country)
4. Click Save Configuration

Why it matters: Correct timezone ensures accurate time display. Location enables weather and location-based features.

Step 3: Install Plugins

1. Navigate to Plugin Store tab
2. Browse available plugins:
   • Time & Date: Clock, calendar
   • Weather: Weather forecasts
   • Sports: NHL, NBA, NFL, MLB scores
   • Finance: Stocks, crypto
   • Custom: Community plugins
3. Click Install on desired plugins
4. Wait for installation to complete
5. Navigate to Plugin Management tab
6. Enable installed plugins (toggle switch)
7. Click Restart Display

Popular First Plugins:

• clock-simple - Simple digital clock
• weather - Weather forecast
• nhl-scores - NHL scores (if you're a hockey fan)

Step 4: Configure Plugins

1. Navigate to Plugin Management tab
2. Find a plugin you installed
3. Click the ⚙️ Configure button
4. Edit settings (e.g., favorite teams, update intervals)
5. Click Save
6. Click Restart Display

Example: Weather Plugin

• Set your location (city, state, country)
• Add API key from OpenWeatherMap (free signup)
• Set update interval (300 seconds recommended)

---

Testing Your Display

Quick Test

1. Navigate to Overview tab
2. Click Test Display button
3. You should see a test pattern on your LED matrix

Manual Plugin Trigger

1. Navigate to Plugin Management tab
2. Find a plugin
3. Click Show Now button
4. The plugin should display immediately
5. Click Stop to return to rotation

Check Logs

1. Navigate to Logs tab
2. Watch real-time logs
3. Look for any ERROR messages
4. Normal operation shows INFO messages about plugin rotation

---

Common First-Time Issues

Display Not Showing Anything

Check:

1. Power supply connected and adequate (5V, 4A minimum)
2. LED matrix connected to GPIO pins correctly
3. Display service running: sudo systemctl status ledmatrix
4. Hardware configuration matches your matrix (rows/columns)

Fix:

1. Restart display: Settings → Overview → Restart Display
2. Or via SSH: sudo systemctl restart ledmatrix

Web Interface Won't Load

Check:

1. Pi is connected to network: ping your-pi-ip
2. Web service running: sudo systemctl status ledmatrix-web
3. Correct port: Use :5050 not :5000
4. Firewall not blocking port 5050

Fix:

1. Restart web service: sudo systemctl restart ledmatrix-web
2. Check logs: sudo journalctl -u ledmatrix-web -n 50

Plugins Not Showing

Check:

1. Plugins are enabled (toggle switch in Plugin Management)
2. Display has been restarted after enabling
3. Plugin duration is reasonable (not too short)
4. No errors in logs for the plugin

Fix:

1. Enable plugin in Plugin Management
2. Restart display
3. Check logs for plugin-specific errors

Weather Plugin Shows "No Data"

Check:

1. API key configured (OpenWeatherMap)
2. Location is correct (city, state, country)
3. Internet connection working

Fix:

1. Sign up at openweathermap.org (free)
2. Add API key to config_secrets.json or plugin config
3. Restart display

---

Next Steps

Customize Your Display

Adjust Display Durations:

• Navigate to Settings → Durations
• Set how long each plugin displays
• Save and restart

Organize Plugin Order:

• Use Plugin Management to enable/disable plugins
• Display cycles through enabled plugins in order

Add More Plugins:

• Check Plugin Store regularly for new plugins
• Install from GitHub URLs for custom/community plugins

Enable Advanced Features

Vegas Scroll Mode:

• Continuous scrolling ticker display
• See ADVANCED_FEATURES.md for details

On-Demand Display:

• Manually trigger specific plugins
• Pin important information
• See ADVANCED_FEATURES.md for details

Background Services:

• Non-blocking data fetching
• Faster plugin rotation
• See ADVANCED_FEATURES.md for details

Explore Documentation

• WEB_INTERFACE_GUIDE.md - Complete web interface guide
• WIFI_NETWORK_SETUP.md - WiFi configuration details
• PLUGIN_STORE_GUIDE.md - Installing and managing plugins
• TROUBLESHOOTING.md - Solving common issues
• ADVANCED_FEATURES.md - Advanced functionality

Join the Community

• Report issues on GitHub
• Share your custom plugins
• Help others in discussions
• Contribute improvements

---

Quick Reference

Service Commands

# Check status
sudo systemctl status ledmatrix
sudo systemctl status ledmatrix-web

# Restart services
sudo systemctl restart ledmatrix
sudo systemctl restart ledmatrix-web

# View logs
sudo journalctl -u ledmatrix -f
sudo journalctl -u ledmatrix-web -f

File Locations

/home/ledpi/LEDMatrix/
├── config/
│   ├── config.json           # Main configuration
│   ├── config_secrets.json   # API keys and secrets
│   └── wifi_config.json      # WiFi settings
├── plugins/                  # Installed plugins
├── cache/                    # Cached data
└── web_interface/            # Web interface files

Web Interface

Main Interface: http://your-pi-ip:5050

Tabs:
- Overview: System stats and quick actions
- General Settings: Timezone, location, autostart
- Display Settings: Hardware configuration
- Durations: Plugin display times
- Sports Configuration: Per-league settings
- Plugin Management: Enable/disable, configure
- Plugin Store: Install new plugins
- Font Management: Upload and manage fonts
- Logs: Real-time log viewing

WiFi Access Point

Network Name: LEDMatrix-Setup
Password: (none - open network)
URL when connected: http://192.168.4.1:5050

---

Congratulations!

Your LEDMatrix display is now set up and running. Explore the web interface, try different plugins, and customize it to your liking.

Need Help?

• Check TROUBLESHOOTING.md
• Review detailed guides for specific features
• Report issues on GitHub
• Ask questions in community discussions

Enjoy your LED matrix display!