rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-12 05:42:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh and correct stale documentation across repo

Browse Source 
Walked the README and docs/ tree against current code and fixed several
real bugs and many stale references. Highlights:

User-facing
- README.md: web interface install instructions referenced
  install_web_service.sh at the repo root, but it actually lives at
  scripts/install/install_web_service.sh.
- docs/GETTING_STARTED.md: every web UI port reference said 5050, but
  the real server in web_interface/start.py:123 binds 5000. Same bug
  was duplicated in docs/TROUBLESHOOTING.md (17 occurrences). Fixed
  both.
- docs/GETTING_STARTED.md: rewrote tab-by-tab instructions. The doc
  referenced "Plugin Store", "Plugin Management", "Sports Configuration",
  "Durations", and "Font Management" tabs - none of which exist. Real
  tabs (verified in web_interface/templates/v3/base.html) are: Overview,
  General, WiFi, Schedule, Display, Config Editor, Fonts, Logs, Cache,
  Operation History, Plugin Manager (+ per-plugin tabs).
- docs/GETTING_STARTED.md: removed references to a "Test Display"
  button (doesn't exist) and "Show Now" / "Stop" plugin buttons. Real
  controls are "Run On-Demand" / "Stop On-Demand" inside each plugin's
  tab (partials/plugin_config.html:792).
- docs/TROUBLESHOOTING.md: removed dead reference to
  troubleshoot_weather.sh (doesn't exist anywhere in the repo); weather
  is now a plugin in ledmatrix-plugins.

Developer-facing
- docs/PLUGIN_API_REFERENCE.md: documented draw_image() doesn't exist
  on DisplayManager. Real plugins paste onto display_manager.image
  directly (verified in src/base_classes/{baseball,basketball,football,
  hockey}.py). Replaced with the canonical pattern.
- docs/PLUGIN_API_REFERENCE.md: documented cache_manager.delete() doesn't
  exist. Real method is clear_cache(key=None). Updated the section.
- docs/PLUGIN_API_REFERENCE.md: added 10 missing BasePlugin methods that
  the doc never mentioned: dynamic-duration hooks, live-priority hooks,
  and the full Vegas-mode interface.
- docs/PLUGIN_DEVELOPMENT_GUIDE.md: same draw_image fix.
- docs/DEVELOPMENT.md: corrected the "Plugin Submodules" section. Plugins
  are NOT git submodules - .gitmodules only contains
  rpi-rgb-led-matrix-master. Plugins are installed at runtime into the
  plugins directory configured by plugin_system.plugins_directory
  (default plugin-repos/). Both internal links in this doc were also
  broken (missing relative path adjustment).
- docs/HOW_TO_RUN_TESTS.md: removed pytest-timeout from install line
  (not in requirements.txt) and corrected the test/integration/ path
  (real integration tests are at test/web_interface/integration/).
  Replaced the fictional file structure diagram with the real one.
- docs/EMULATOR_SETUP_GUIDE.md: clone URL was a placeholder; default
  pixel_size was documented as 16 but emulator_config.json ships with 5.

Index
- docs/README.md: rewrote. Old index claimed "16-17 files after
  consolidation" but docs/ actually has 38 .md files. Four were missing
  from the index entirely (CONFIG_DEBUGGING, DEV_PREVIEW,
  PLUGIN_ERROR_HANDLING, STARLARK_APPS_GUIDE). Trimmed the navel-gazing
  consolidation/statistics sections.

Out of scope but worth flagging:
- src/plugin_system/resource_monitor.py:343 and src/common/api_helper.py:287
  call cache_manager.delete(key) but no such method exists on
  CacheManager. Both call sites would AttributeError at runtime if hit.
  Not fixed in this docs PR - either add a delete() shim or convert
  callers to clear_cache().

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-04-06 20:45:19 -04:00
parent efe6b1fe23
commit 2a7a318cf7
9 changed files with 394 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
docs/TROUBLESHOOTING.md
View File

@@ -47,13 +47,15 @@ bash scripts/diagnose_web_interface.sh
# WiFi setup verification
./scripts/verify_wifi_setup.sh
# Weather plugin troubleshooting
./troubleshoot_weather.sh
# Captive portal troubleshooting
./scripts/troubleshoot_captive_portal.sh
```
> Weather is provided by the `ledmatrix-weather` plugin (installed via the
> Plugin Store). To troubleshoot weather, check that plugin's tab in the
> web UI for its API key and recent error messages, then watch the
> **Logs** tab.
### 4. Check Configuration
```bash
@@ -85,7 +87,7 @@ python3 web_interface/start.py
#### Service Not Running/Starting
**Symptoms:**
- Cannot access web interface at http://your-pi-ip:5050
- Cannot access web interface at http://your-pi-ip:5000
- `systemctl status ledmatrix-web` shows `inactive (dead)`
**Solutions:**
@@ -157,13 +159,13 @@ sudo systemctl restart ledmatrix-web
**Symptoms:**
- Error: `Address already in use`
- Service fails to bind to port 5050
- Service fails to bind to port 5000
**Solutions:**
1. **Check what's using the port:**
```bash
sudo lsof -i :5050
sudo lsof -i :5000
```
2. **Kill the conflicting process:**
@@ -265,7 +267,7 @@ sudo systemctl cat ledmatrix-web | grep User
6. **Manually enable AP mode:**
```bash
# Via API
curl -X POST http://localhost:5050/api/wifi/ap/enable
curl -X POST http://localhost:5000/api/wifi/ap/enable
# Via Python
python3 -c "
@@ -291,9 +293,8 @@ sudo systemctl cat ledmatrix-web | grep User
```
2. **Use correct IP address and port:**
- Correct: `http://192.168.4.1:5050`
- NOT: `http://192.168.4.1` (port 80)
- NOT: `http://192.168.4.1:5000`
- Correct: `http://192.168.4.1:5000`
- NOT: `http://192.168.4.1` (port 80 — nothing listens there)
3. **Check wlan0 has correct IP:**
```bash
@@ -309,7 +310,7 @@ sudo systemctl cat ledmatrix-web | grep User
5. **Test from the Pi itself:**
```bash
curl http://192.168.4.1:5050
curl http://192.168.4.1:5000
# Should return HTML
```
@@ -340,11 +341,11 @@ sudo systemctl cat ledmatrix-web | grep User
4. **Manual captive portal testing:**
- Try these URLs manually:
- `http://192.168.4.1:5050`
- `http://192.168.4.1:5000`
- `http://captive.apple.com`
- `http://connectivitycheck.gstatic.com/generate_204`
#### Firewall Blocking Port 5050
#### Firewall Blocking Port 5000
**Symptoms:**
- Services running but cannot connect
@@ -357,9 +358,9 @@ sudo systemctl cat ledmatrix-web | grep User
sudo ufw status
```
2. **Allow port 5050:**
2. **Allow port 5000:**
```bash
sudo ufw allow 5050/tcp
sudo ufw allow 5000/tcp
```
3. **Check iptables:**
@@ -372,7 +373,7 @@ sudo systemctl cat ledmatrix-web | grep User
sudo ufw disable
# Test if it works, then re-enable and add rule
sudo ufw enable
sudo ufw allow 5050/tcp
sudo ufw allow 5000/tcp
```
---
@@ -403,9 +404,9 @@ sudo systemctl cat ledmatrix-web | grep User
```
3. **Verify in web interface:**
- Navigate to Plugin Management tab
- Toggle the switch to enable
- Restart display
- Open the **Plugin Manager** tab
- Toggle the plugin switch to enable
- From **Overview**, click **Restart Display Service**
#### Plugin Not Loading
@@ -690,12 +691,12 @@ nslookup api.openweathermap.org
dig api.openweathermap.org
# Test HTTP endpoint
curl -I http://your-pi-ip:5050
curl http://192.168.4.1:5050
curl -I http://your-pi-ip:5000
curl http://192.168.4.1:5000
# Check listening ports
sudo lsof -i :5050
sudo netstat -tuln | grep 5050
sudo lsof -i :5000
sudo netstat -tuln | grep 5000
# Check network interfaces
ip addr show
@@ -808,7 +809,7 @@ echo ""
echo "4. Network Status:"
ip addr show | grep -E "(wlan|eth|inet )"
curl -s http://localhost:5050 > /dev/null && echo "Web interface: OK" || echo "Web interface: FAILED"
curl -s http://localhost:5000 > /dev/null && echo "Web interface: OK" || echo "Web interface: FAILED"
echo ""
echo "5. File Structure:"
@@ -837,22 +838,22 @@ A properly functioning system should show:
```
2. **Web Interface Accessible:**
- Navigate to http://your-pi-ip:5050
- Navigate to http://your-pi-ip:5000
- Page loads successfully
- Display preview visible
3. **Logs Show Normal Operation:**
```
INFO: Web interface started on port 5050
INFO: Web interface started on port 5000
INFO: Loaded X plugins
INFO: Display rotation active
```
4. **Process Listening on Port:**
```bash
$ sudo lsof -i :5050
$ sudo lsof -i :5000
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
python3 1234 ledpi 3u IPv4 12345 0t0 TCP *:5050 (LISTEN)
python3 1234 ledpi 3u IPv4 12345 0t0 TCP *:5000 (LISTEN)
```
5. **Plugins Loading:**