LEDMatrix/WEB_INTERFACE_V2_README.md

LED Matrix Web Interface V2

A modern, lightweight, and feature-rich web interface for controlling and customizing your LED Matrix display. This interface provides real-time display monitoring, drag-and-drop layout editing, and comprehensive system management.

Features

🖥️ Real-Time Display Preview

• Live display monitoring with WebSocket connectivity
• Scaled-up preview for better visibility
• Real-time updates as content changes
• Screenshot capture functionality

✏️ Display Editor Mode

• Drag-and-drop interface for creating custom layouts
• Element palette with text, weather icons, shapes, and more
• Properties panel for fine-tuning element appearance
• Real-time preview of changes
• Save/load custom layouts for reuse

📊 System Monitoring

• Real-time system stats (CPU temperature, memory usage, uptime)
• Service status monitoring
• Performance metrics with visual indicators
• Connection status indicator

⚙️ Configuration Management

• Modern tabbed interface for easy navigation
• Real-time configuration updates
• Visual controls (sliders, toggles, dropdowns)
• Instant feedback on changes

🎨 Modern UI Design

• Responsive design that works on desktop and mobile
• Dark/light theme support
• Smooth animations and transitions
• Professional card-based layout
• Color-coded status indicators

Installation

Prerequisites

• Python 3.7+
• LED Matrix hardware properly configured
• Existing LED Matrix project setup

Quick Setup

1. Install dependencies:

   pip install -r requirements_web_v2.txt
   

2. Make the startup script executable:

   chmod +x start_web_v2.py
   

3. Start the web interface:

   python3 start_web_v2.py
   

4. Access the interface: Open your browser and navigate to http://your-pi-ip:5001

Advanced Setup

For production use, you can set up the web interface as a systemd service:

1. Create a service file:

   sudo nano /etc/systemd/system/ledmatrix-web.service
   

2. Add the following content:

   [Unit]
   Description=LED Matrix Web Interface V2
   After=network.target
   
   [Service]
   Type=simple
   User=pi
   WorkingDirectory=/home/pi/LEDMatrix
   ExecStart=/usr/bin/python3 /home/pi/LEDMatrix/start_web_v2.py
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

3. Enable and start the service:

   sudo systemctl enable ledmatrix-web
   sudo systemctl start ledmatrix-web
   

Usage Guide

Getting Started

1. Connect to your display:

   • The interface will automatically attempt to connect to your LED matrix
   • Check the connection status indicator in the bottom-right corner

2. Monitor your system:

   • View real-time system stats in the header
   • Check service status and performance metrics in the Overview tab

3. Control your display:

   • Use the Start/Stop buttons to control display operation
   • Take screenshots for documentation or troubleshooting

Using the Display Editor

1. Enter Editor Mode:

   • Click the "Enter Editor" button to pause normal display operation
   • The display will switch to editor mode, allowing you to customize layouts

2. Add Elements:

   • Drag elements from the palette onto the display preview
   • Elements will appear where you drop them
   • Click on elements to select and edit their properties

3. Customize Elements:

   • Use the Properties panel to adjust position, color, text, and other settings
   • Changes are reflected in real-time on the display

4. Save Your Layout:

   • Click "Save Layout" to store your custom design
   • Layouts are saved locally and can be reloaded later

Element Types

Text Elements

• Static text: Display fixed text with custom positioning and colors
• Data-driven text: Display dynamic data using template variables
• Clock elements: Show current time with customizable formats

Visual Elements

• Weather icons: Display weather conditions with various icon styles
• Rectangles: Create borders, backgrounds, or decorative elements
• Lines: Add separators or decorative lines

Advanced Elements

• Data text: Connect to live data sources (weather, stocks, etc.)
• Template text: Use variables like {weather.temperature} in text

Configuration Management

Display Settings

• Brightness: Adjust LED brightness (1-100%)
• Schedule: Set automatic on/off times
• Hardware settings: Configure matrix dimensions and timing

System Management

• Service control: Start, stop, or restart the LED matrix service
• System updates: Pull latest code from git repository
• Log viewing: Access system logs for troubleshooting
• System reboot: Safely restart the system

API Reference

The web interface provides a REST API for programmatic control:

Display Control

• POST /api/display/start - Start the display
• POST /api/display/stop - Stop the display
• GET /api/display/current - Get current display image

Editor Mode

• POST /api/editor/toggle - Toggle editor mode
• POST /api/editor/preview - Update preview with layout

Configuration

• POST /api/config/save - Save configuration changes
• GET /api/system/status - Get system status

System Actions

• POST /api/system/action - Execute system actions

Customization

Creating Custom Layouts

Layouts are stored as JSON files with the following structure:

{
  "layout_name": {
    "elements": [
      {
        "type": "text",
        "x": 10,
        "y": 10,
        "properties": {
          "text": "Hello World",
          "color": [255, 255, 255],
          "font_size": "normal"
        }
      }
    ],
    "description": "Layout description",
    "created": "2024-01-01T00:00:00",
    "modified": "2024-01-01T00:00:00"
  }
}

Adding Custom Element Types

You can extend the layout manager to support custom element types:

1. Add the element type to the palette in templates/index_v2.html
2. Implement the rendering logic in src/layout_manager.py
3. Update the properties panel to support element-specific settings

Theming

The interface uses CSS custom properties for easy theming. Modify the :root section in the HTML template to change colors:

:root {
    --primary-color: #2c3e50;
    --secondary-color: #3498db;
    --accent-color: #e74c3c;
    /* ... more color variables */
}

Troubleshooting

Common Issues

1. Connection Failed:

   • Check that the LED matrix hardware is properly connected
   • Verify that the display service is running
   • Check firewall settings on port 5001

2. Editor Mode Not Working:

   • Ensure you have proper permissions to control the display
   • Check that the display manager is properly initialized
   • Review logs for error messages

3. Performance Issues:

   • Monitor system resources in the Overview tab
   • Reduce display update frequency if needed
   • Check for memory leaks in long-running sessions

Getting Help

1. Check the logs:

   • Use the "View Logs" button in the System tab
   • Check /tmp/web_interface_v2.log for detailed error messages

2. System status:

   • Monitor the system stats for resource usage
   • Check service status indicators

3. Debug mode:

   • Set debug=True in web_interface_v2.py for detailed error messages
   • Use browser developer tools to check for JavaScript errors

Performance Considerations

Raspberry Pi Optimization

The interface is designed to be lightweight and efficient for Raspberry Pi:

• Minimal resource usage: Uses efficient WebSocket connections
• Optimized image processing: Scales images appropriately for web display
• Caching: Reduces unnecessary API calls and processing
• Background processing: Offloads heavy operations to background threads

Network Optimization

• Compressed data transfer: Uses efficient binary protocols where possible
• Selective updates: Only sends changed data to reduce bandwidth
• Connection management: Automatic reconnection on network issues

Security Considerations

• Local network only: Interface is designed for local network access
• Sudo permissions: Some system operations require sudo access
• File permissions: Ensure proper permissions on configuration files
• Firewall: Consider firewall rules for port 5001

Future Enhancements

Planned features for future releases:

• Multi-user support with role-based permissions
• Plugin system for custom element types
• Animation support for dynamic layouts
• Mobile app companion
• Cloud sync for layout sharing
• Advanced scheduling with conditional logic
• Integration APIs for smart home systems

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on Raspberry Pi hardware
5. Submit a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For support and questions:

• Check the troubleshooting section above
• Review the system logs
• Open an issue on the project repository
• Join the community discussions

---

Enjoy your new modern LED Matrix web interface! 🎉