LEDMatrix/wiki/cache_management.md

Cache Management

The LEDMatrix application uses caching to improve performance and reduce API calls. However, sometimes cache data can become stale or corrupted, leading to issues like false live game detection or outdated information.

Cache Clearing Utility

The clear_cache.py script provides a command-line interface for managing the LEDMatrix cache. This utility is essential for debugging cache-related issues and ensuring fresh data retrieval.

Basic Usage

# Show help and current cache status
python clear_cache.py

# List all available cache keys
python clear_cache.py --list

# Clear all cache data
python clear_cache.py --clear-all

# Clear a specific cache key
python clear_cache.py --clear KEY_NAME

# Show information about a specific cache key
python clear_cache.py --info KEY_NAME

Command Reference

Command	Short	Description
--list	-l	List all available cache keys
--clear-all	-a	Clear all cache data
--clear KEY	-c	Clear a specific cache key
--info KEY	-i	Show information about a specific cache key

Common Cache Keys

MiLB (Minor League Baseball)

• milb_live_api_data - Live game data from MiLB API
• milb_upcoming_api_data - Upcoming game schedules
• milb_recent_api_data - Recent game results

MLB (Major League Baseball)

• mlb_live_api_data - Live game data from MLB API
• mlb_upcoming_api_data - Upcoming game schedules
• mlb_recent_api_data - Recent game results

Soccer

• soccer_live_api_data - Live soccer match data
• soccer_upcoming_api_data - Upcoming soccer matches

Other Services

• weather_api_data - Weather information
• news_api_data - News headlines
• stocks_api_data - Stock market data

Usage Examples

Scenario 1: False Live Game Detection

Problem: The MiLB manager is showing "Tam vs Dun" as a live game when it's actually old data.

Solution:

# First, check what's in the MiLB live cache
python clear_cache.py --info milb_live_api_data

# Clear the problematic cache
python clear_cache.py --clear milb_live_api_data

# Restart the application to fetch fresh data

Scenario 2: Stale Upcoming Games

Problem: The display is showing outdated game schedules.

Solution:

# Clear all MiLB cache data
python clear_cache.py --clear milb_upcoming_api_data
python clear_cache.py --clear milb_live_api_data
python clear_cache.py --clear milb_recent_api_data

Scenario 3: Complete Cache Reset

Problem: Multiple cache-related issues or corrupted data.

Solution:

# Nuclear option - clear everything
python clear_cache.py --clear-all

# Verify cache is empty
python clear_cache.py --list

Scenario 4: Debugging Cache Issues

Problem: Unusual behavior that might be cache-related.

Solution:

# List all cache keys to see what's stored
python clear_cache.py --list

# Inspect specific cache entries
python clear_cache.py --info milb_live_api_data
python clear_cache.py --info weather_api_data

# Clear specific problematic caches
python clear_cache.py --clear milb_live_api_data

Troubleshooting

Cache Directory Issues

If you encounter errors about cache directories:

# Check if cache directory exists
ls -la ~/.ledmatrix_cache/

# If it doesn't exist, the application will create it automatically
# You can also manually create it:
mkdir -p ~/.ledmatrix_cache/

Permission Issues

If you get permission errors:

# Check cache directory permissions
ls -la ~/.ledmatrix_cache/

# Fix permissions if needed
chmod 755 ~/.ledmatrix_cache/
chown $USER:$USER ~/.ledmatrix_cache/

Import Errors

If you get import errors when running the script:

# Make sure you're in the LEDMatrix root directory
cd /path/to/LEDMatrix

# Check that the src directory exists
ls -la src/

# Run the script from the correct location
python clear_cache.py --list

When to Use Cache Clearing

Recommended Times to Clear Cache

1. After configuration changes - Clear relevant caches when you modify team preferences or display settings
2. When experiencing false live data - Clear live game caches if old games appear as "live"
3. After API changes - Clear caches if you notice API endpoints have changed
4. For debugging - Clear caches when investigating display or data issues
5. After long periods of inactivity - Clear caches if the application hasn't been used for days

Cache Types and Their Impact

Cache Type	Impact of Clearing	When to Clear
Live game data	Forces fresh live data fetch	False live game detection
Upcoming games	Refreshes schedules	Outdated game times
Recent games	Updates final scores	Missing recent results
Weather	Gets current conditions	Stale weather data
News	Fetches latest headlines	Old news stories

Best Practices

1. Targeted Clearing: Clear specific cache keys rather than all cache when possible
2. Verify Results: Use --info to check cache contents before and after clearing
3. Restart Application: Restart the LEDMatrix application after clearing caches
4. Monitor Logs: Check application logs after cache clearing to ensure fresh data is fetched
5. Backup Important Data: Cache data is automatically regenerated, but be aware that clearing will force new API calls

Integration with Application

The cache clearing utility works independently of the main application. You can run it while the application is running, but for best results:

1. Stop the LEDMatrix application
2. Clear relevant caches
3. Restart the application

This ensures the application starts with fresh data and doesn't immediately re-cache potentially problematic data.

Advanced Usage

Scripting Cache Management

You can integrate cache clearing into scripts or cron jobs:

#!/bin/bash
# Daily cache cleanup script

# Clear old live game data at midnight
python clear_cache.py --clear milb_live_api_data
python clear_cache.py --clear mlb_live_api_data

# Log the cleanup
echo "$(date): Cache cleared" >> /var/log/ledmatrix_cache.log

Conditional Cache Clearing

#!/bin/bash
# Only clear cache if it's older than 24 hours

# Check cache age and clear if needed
# (This would require additional logic to check cache timestamps)

Related Documentation

• Configuration Guide
• Troubleshooting Guide
• API Integration
• Display Controller