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)

Software:

• Raspberry Pi OS Lite, Trixie (Debian 13) or Bookworm (Debian 12). Trixie is the current release; Bookworm is listed as Legacy in Raspberry Pi Imager. No other system is supported, and the installer says so up front.
• The OS's own Python: 3.13 on Trixie, 3.11 on Bookworm

Network:

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

---

Quick Start

1. Install LEDMatrix

There is no prebuilt SD card image — you install LEDMatrix onto stock Raspberry Pi OS Lite yourself:

1. Flash Raspberry Pi OS Lite (Trixie, or Bookworm) to the MicroSD card (Raspberry Pi Imager)

2. Connect the LED matrix to your Raspberry Pi, insert the card, and power on

3. SSH into the Pi and run the one-shot installer:

   curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | bash
   

   or clone the repo and run sudo ./first_time_install.sh — see the README Installation Steps / Quick Install for full details

   The one-shot installer installs the newest release (the stable update channel). To run the newest, unreleased code from main instead (the beta channel), put LEDMATRIX_CHANNEL=beta in front of bash:

   curl -fsSL https://raw.githubusercontent.com/ChuckBuilds/LEDMatrix/main/scripts/install/one-shot-install.sh | LEDMATRIX_CHANNEL=beta bash
   

   A manual clone starts on main; add --beta to first_time_install.sh to stay on it, or leave it off and the first update after the next release moves the device onto releases. You can switch channels later on the General tab.

Expected Behavior after install:

• LED matrix will light up
• A fresh install ships only the bundled starlark-apps and web-ui-info plugins — clock, weather, sports, etc. must be installed from the Plugin Store (web UI → Plugin Manager) before anything else displays
• 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:5000
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:5000

3. Access the Web Interface

Once connected, access the web interface:

http://your-pi-ip:5000

You should see:

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

---

Initial Configuration (15 Minutes)

Step 1: Configure Display Hardware

1. Open the Display tab
2. Set your matrix configuration:
   • Rows: match your panel — commonly 32 or 64; any even number from 8 to 64
   • Columns: match your panel — commonly 64 or 96; at least 16, with no upper limit
   • Chain Length: Number of panels chained horizontally
   • Hardware Mapping: usually adafruit-hat-pwm (with the PWM jumper mod) or adafruit-hat (without). See the root README for the full list.
   • Brightness: 70–90 is fine for indoor use
3. Click Save
4. From the Overview tab, click Restart Display Service to apply

Tip: if the display shows garbage or nothing, the most common culprits are an incorrect hardware_mapping, a gpio_slowdown value that doesn't match your Pi model, or panels needing the E-line mod. See TROUBLESHOOTING.md.

Step 2: Set Timezone and Location

1. Open the General tab
2. Set your timezone (e.g., America/New_York) and location
3. Click Save

Correct timezone ensures accurate time display, and location is used by weather and other location-aware plugins.

Step 3: Install Plugins

1. Open the Plugin Manager tab
2. Scroll to the Plugin Store section to browse available plugins
3. Click Install on the plugins you want
4. Wait for installation to finish — installed plugins appear in the Installed Plugins section above and get their own tab in the second nav row
5. Toggle the plugin to enabled. The running display loads it within a few seconds; no restart is needed

You can also install community plugins straight from a GitHub URL using the Install from GitHub section further down the same tab — see PLUGIN_STORE_GUIDE.md for details.

Step 4: Configure Plugins

1. Each installed plugin gets its own tab in the second navigation row
2. Open that plugin's tab to edit its settings (favorite teams, API keys, update intervals, etc.)
3. Click Save. The display service watches config.json and hands the new settings to the running plugin, so no restart is needed. If a plugin still shows old settings, restart the display service from Overview

Note: how long each plugin stays on screen is not set in the plugin's own tab — use the Rotation tab's Screen Durations section instead (saved to display.display_durations in config.json).

Example: Weather Plugin

• Set your location (city, state, country)
• Add an API key from OpenWeatherMap (free signup) to config/config_secrets.json or directly in the plugin's config screen
• Set the update interval (300 seconds is reasonable)

---

Testing Your Display

Run a single plugin on demand

The fastest way to verify a plugin works without waiting for the rotation:

1. Open the plugin's tab (second nav row)
2. Scroll to On-Demand Controls
3. Click Run On-Demand — the plugin runs immediately even if disabled
4. Click Stop On-Demand to return to the normal rotation

Check the live preview and logs

• The Overview tab shows a Live Display Preview that mirrors what's on the matrix in real time — handy for debugging without looking at the panel.
• The Logs tab streams the display and web service logs. Look for ERROR lines if something isn't working; normal operation just 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 the bonnet/HAT correctly
3. Display service running: sudo systemctl status ledmatrix
4. Hardware configuration matches your matrix (rows/cols/chain length)

Fix:

1. Restart from the Overview tab → Restart Display Service
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: the web UI listens on :5000
4. Firewall not blocking port 5000

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. Plugin is enabled (toggle on the Plugin Manager tab)
2. Plugin's display duration is non-zero
3. No errors in the Logs tab for that plugin. A plugin whose validate_config() fails is not loaded until its settings are fixed

Fix:

1. Enable the plugin from Plugin Manager
2. Check the Logs tab for plugin-specific errors
3. If it still does not appear, click Restart Display Service on Overview

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:

• Open the Rotation tab and use the Screen Durations section to set how long each plugin stays on screen per rotation (saved to display.display_durations).

Organize plugin order:

• The Rotation tab also has a drag-and-drop Rotation Order list (saved to display.plugin_rotation_order). Enable/disable plugins from the Plugin Manager tab.

Add more plugins:

• Check the Plugin Store section of Plugin Manager for new plugins.
• Install community plugins straight from a GitHub URL via Install from GitHub on the same tab.

Keep LEDMatrix Up to Date

• Update Code on the Overview tab installs the newest version, and a banner at the top of the page says when one is available.
• General → Automatic Updates does it once a week, overnight, with a health check that undoes an update that breaks the device.
• General → Update Channel picks which version that is. Stable (the default) installs releases, which have been tested and have release notes. Beta installs the newest code as soon as it is written, before it is released: fixes arrive sooner, and so do new problems.
• Switching to Stable never installs an older version than the one you have. If your device is already newer than the latest release (which is normal if it was set up or updated from the newest code), it keeps getting the newest code until the next release includes it, then follows releases from there. The General tab says when this is the case.

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
├── plugin-repos/             # Installed plugins (default location)
└── web_interface/            # Web interface files

Cached data does not live in the project directory — the cache manager uses the first writable location among /var/cache/ledmatrix, ~/.ledmatrix_cache, /opt/ledmatrix/cache, and $TMPDIR/ledmatrix_cache.

The plugin install location is configurable via plugin_system.plugins_directory in config.json. The default is plugin-repos/. Plugin discovery (PluginManager.discover_plugins()) only scans the configured directory — it does not fall back to plugins/. However, the Plugin Store install/update path and the web UI's schema loader do also probe plugins/ so the dev symlinks created by scripts/dev/dev_plugin_setup.sh keep working.

Web Interface

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

System tabs:
- Overview          System stats, live preview, quick actions
- General           Timezone, location, plugin-system settings
- WiFi              Network selection and AP-mode setup
- Schedule          Power and dim schedules
- Display           Matrix hardware configuration
- Rotation          Rotation order (drag-and-drop) and screen durations
- Config Editor     Raw config.json editor
- Backup & Restore  Config backup and restore
- Fonts             Upload and manage fonts
- Logs              Real-time log viewing
- Cache             Cached data inspection and cleanup
- Operation History Recent service operations
- Tools             System diagnostics, updates, dependencies, maintenance

Plugin tabs (second row):
- Plugin Manager    Browse the Plugin Store, install/enable plugins
- <plugin-id>       One tab per installed plugin for its config

WiFi Access Point

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

---

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!