🤖 Printernizer Auto-Download System Documentation¶

Version: 1.0 Date: September 2024 Status: Production Ready

Overview¶

The Printernizer Auto-Download System is a comprehensive, enterprise-grade solution for automatically downloading and processing 3D printer files with thumbnail generation. It provides intelligent job detection, prioritized download queues, and professional fallback handling.

🎯 Key Features¶

Automatic Job Detection¶

Real-time monitoring via WebSocket connections
Fallback polling every 30 seconds for reliability
Multi-printer support (Bambu Lab A1, Prusa Core One)
Smart triggering when jobs start printing

Advanced Queue Management¶

Prioritized processing (Urgent → High → Normal → Low)
Concurrent downloads (configurable, default: 2 simultaneous)
Intelligent retry logic with exponential backoff
Error recovery and detailed failure tracking

Thumbnail Processing Pipeline¶

Multi-format support: 3MF, STL, OBJ, G-code, BGCode
Three processing methods:
Extract: Get embedded thumbnails from 3MF/BGCode
Generate: Create thumbnails from STL/OBJ models
Analyze: Extract preview data from G-code
Professional fallbacks when processing fails

Comprehensive Logging¶

Full audit trail of all activities
Performance metrics and success rates
Session tracking for debugging
Export capabilities for analysis

🏗️ Architecture¶

┌─────────────────────────────────────────────────────────────┐
│                    AUTO-DOWNLOAD SYSTEM                     │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │   Job Monitor   │    │  Download Queue │                │
│  │  (WebSocket +   │───▶│   Management    │                │
│  │   Polling)      │    │  (Prioritized)  │                │
│  └─────────────────┘    └─────────────────┘                │
│           │                       │                        │
│           ▼                       ▼                        │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │ Auto-Detection  │    │ Thumbnail Queue │                │
│  │   & Triggers    │    │   Processing    │                │
│  │ (Multi-Printer) │    │ (Multi-Format)  │                │
│  └─────────────────┘    └─────────────────┘                │
│           │                       │                        │
│           ▼                       ▼                        │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │ Logging System  │    │  UI Management  │                │
│  │   & Analytics   │    │   (Real-time)   │                │
│  └─────────────────┘    └─────────────────┘                │
└─────────────────────────────────────────────────────────────┘

🔧 Components¶

Core Components¶

AutoDownloadManager (`auto-download-manager.js`)¶

Main coordinator for the entire system
WebSocket integration for real-time monitoring
Auto-detection logic for job start/completion
Configuration management and system status

DownloadQueue (`download-queue.js`)¶

Prioritized queue management for file downloads
Concurrent processing with configurable limits
Retry logic with exponential backoff
Task lifecycle management (queued → processing → completed/failed)

ThumbnailQueue (`thumbnail-queue.js`)¶

Specialized queue for thumbnail processing
Multi-format support with appropriate processing methods
Priority handling based on file type
Integration with download queue completion

DownloadLogger (`download-logger.js`)¶

Comprehensive logging of all system activities
Performance metrics and analytics
Session tracking and audit trails
Export functionality for external analysis

AutoDownloadUI (`auto-download-ui.js`)¶

Management interface for monitoring and control
Real-time updates of queue status
System controls for enable/disable functionality
History and error viewing

Integration Components¶

AutoDownloadSystemInitializer (`auto-download-init.js`)¶

System startup and component coordination
WebSocket integration enhancement
Existing function replacement for seamless integration
Graceful error handling during initialization

🖨️ Printer Support¶

Bambu Lab A1¶

Protocol: MQTT via bambulabs-api library
File Sources: SD card, cloud storage
Auto-Detection: Real-time via MQTT callbacks
Supported Formats: 3MF (with embedded thumbnails), G-code

Prusa Core One¶

Protocol: HTTP REST API via PrusaLink
File Sources: USB storage, PrusaLink uploads
Auto-Detection: HTTP polling + WebSocket events
Supported Formats: 3MF, STL, G-code

Universal Features¶

Identical processing for both printer types
Unified queue management
Same thumbnail generation pipeline
Consistent user interface

📋 Download Process Flow¶

1. Job Detection¶

Printer Status Change → WebSocket Event → Auto-Detection Logic
                                      ↓
Status: idle/offline → printing = Job Started
                                      ↓
                            Create Download Task
                                      ↓
                           Add to Priority Queue

2. Download Processing¶

Queue Manager → Select Next Task → Execute Download
                                         ↓
                            API Call to Backend
                                         ↓
                        Success/Failure Handling
                                         ↓
                     Complete or Retry with Backoff

3. Thumbnail Processing¶

Download Complete → Check for Thumbnail → Add to Thumbnail Queue
                                              ↓
                                    Select Processing Method
                                              ↓
                              Extract/Generate/Analyze
                                              ↓
                                 Update UI with Result

🎛️ Configuration¶

Default Settings¶

{
    maxConcurrentDownloads: 2,      // Simultaneous downloads
    maxConcurrentThumbnails: 1,     // Thumbnail processing
    retryAttempts: 3,               // Max retry attempts
    retryDelay: 5000,               // Initial retry delay (ms)
    autoDetectionEnabled: true,     // Auto job detection
    logRetentionDays: 30           // Log retention period
}

Priority Levels¶

Urgent: Critical system downloads
High: Current job files (auto-triggered)
Normal: Manual downloads
Low: Background/maintenance tasks

File Type Processing Priorities¶

3MF: Priority 1 (embedded thumbnails)
BGCode: Priority 1 (embedded data)
STL/OBJ: Priority 2 (generate thumbnails)
G-code: Priority 3 (analyze for previews)

🔌 API Integration¶

Required Backend Endpoints¶

Download Endpoints¶

POST /printers/{id}/download-current-job
POST /printers/{id}/download-file
GET  /printers/{id}/files

Thumbnail Processing Endpoints¶

POST /files/{fileId}/thumbnail/extract
POST /files/{fileId}/thumbnail/generate
POST /files/{fileId}/analyze/gcode

Expected Response Formats¶

Download Response¶

{
    "status": "success|processed|exists_with_thumbnail|exists_no_thumbnail|not_printing|no_file",
    "file_id": "unique_file_identifier",
    "filename": "example.3mf",
    "has_thumbnail": true,
    "message": "Download successful"
}

Thumbnail Response¶

{
    "success": true,
    "method": "extracted|generated|analyzed",
    "thumbnail_url": "/api/files/{fileId}/thumbnail",
    "metadata": { /* optional file metadata */ },
    "message": "Thumbnail processed successfully"
}

🎨 UI Integration¶

Dashboard Status Card¶

System status indicator (active/inactive)
Queue statistics (downloads, processing)
Management button for detailed control

Management Panel¶

System overview with real-time statistics
Queue monitoring (downloads and thumbnails)
History view with success/error logs
Controls for enable/disable auto-detection

Toast Notifications¶

Download started/completed notifications
Thumbnail processing updates
Error notifications with retry options
System status changes

🔄 Integration with Existing Systems¶

WebSocket Enhancement¶

Non-intrusive integration with existing WebSocket manager
Event forwarding to auto-download logic
Fallback compatibility if WebSocket unavailable

Function Replacement¶

triggerCurrentJobDownload(): Enhanced with queue management
DruckerDateienManager: Integrated with download queue
Thumbnail handling: Automatic updates after processing

Printer Card Updates¶

Real-time thumbnail updates after processing
Placeholder handling for missing thumbnails
Status indicators for download progress

📊 Monitoring and Analytics¶

Real-time Metrics¶

Queue depth (downloads and thumbnails)
Processing time averages
Success/failure rates
Active downloads count

Historical Data¶

Download history (last 7/30 days)
Error log analysis
Performance trends
Printer-specific statistics

Export Capabilities¶

JSON export of logs and metrics
Configurable time ranges
Structured data for external analysis

🛡️ Error Handling¶

Download Failures¶

Automatic retry with exponential backoff
Maximum retry limits to prevent infinite loops
Detailed error logging for debugging
User notifications for permanent failures

Thumbnail Processing Failures¶

Graceful fallback to placeholder images
Alternative processing methods when possible
Clear error messages in management interface

System Failures¶

Component isolation prevents cascading failures
Graceful degradation when services unavailable
Recovery procedures for common issues

🚀 Performance Considerations¶

Resource Management¶

Concurrent limits prevent system overload
Queue prioritization ensures important tasks first
Memory management with automatic cleanup

Network Optimization¶

Batched API calls where possible
Connection pooling for efficiency
Timeout handling for slow responses

Storage Management¶

Log rotation to prevent disk space issues
Thumbnail caching for improved performance
Cleanup procedures for old data

🔒 Security Considerations¶

API Security¶

Authentication required for all endpoints
Input validation on all parameters
Rate limiting to prevent abuse

File Handling¶

Secure file naming to prevent path traversal
Virus scanning integration points
Access control for downloaded files

Logging Security¶

No sensitive data in logs
Log access controls
Audit trail integrity

🐛 Troubleshooting¶

Common Issues¶

System Not Starting¶

Check console for initialization errors
Verify all script files are loaded
Confirm WebSocket connectivity

Downloads Not Processing¶

Verify backend endpoints are available
Check printer connectivity
Review download queue status

Thumbnails Not Generating¶

Confirm file format support
Check thumbnail processing queue
Review API response status

Debug Tools¶

Console Commands¶

// Check system status
window.autoDownloadSystemInitializer.getSystemStatus()

// View queue contents
window.downloadQueue.getQueueContents()
window.thumbnailQueue.getQueueContents()

// Export logs
window.downloadLogger.exportLogs(7)

Management Interface¶

Queue monitoring for live status
Error logs for failure analysis
System controls for testing

📈 Future Enhancements¶

Planned Features¶

Bulk download operations
Scheduled downloads for maintenance
Advanced filtering and search
Custom thumbnail templates

Integration Opportunities¶

Home Assistant addon support
Database storage for large deployments
REST API for external integration
Mobile app notifications

🤝 Contributing¶

Development Setup¶

Clone repository and install dependencies
Start development server
Enable debug logging for development
Test with multiple printer types

Testing Guidelines¶

Unit tests for core components
Integration tests for API endpoints
End-to-end tests for complete workflows
Performance tests under load

Code Standards¶

ESLint configuration for consistency
Documentation for all public methods
Error handling best practices
Security considerations in all code

📞 Support¶

For issues, questions, or contributions: - GitHub Issues: Report bugs and feature requests - Documentation: This file and inline code comments - Logs: Use export functionality for support requests