# New Features Documentation ## Overview This document describes the 5 new features added to MakerStash: 1. **Filament/Resin Cost Calculator** - Estimate printing costs based on file size 2. **Full-Text Search** - Search across all metadata fields 3. **License Management** - Track and filter models by license type 4. **Bambu Printer Integration** - Connect and control Bambu printers 5. **Dark/Light Theme Toggle** - Theme preference with persistence --- ## 1. Filament/Resin Cost Calculator ### Overview Automatically estimate filament or resin costs for your 3D models based on file size and material type. ### Features - **Multiple Material Types**: PLA, ABS, PETG, Nylon, TPU, Carbon Fiber, Bamboo, and various resins - **Accurate Estimates**: Uses density calculations and heuristic algorithms - **Batch Calculation**: Calculate costs for multiple models at once - **Customizable Costs**: Update material costs per kg/ml - **Confidence Levels**: Shows estimation confidence (currently "low" for file-size-based estimates) ### Backend API #### Calculate Cost for Single Model ```bash GET /api/models/:id/cost?materialType=pla ``` **Response:** ```json { "modelId": 1, "name": "Model Name", "fileName": "model.stl", "fileSize": 5242880, "material": "pla", "weight": 52.4, "units": 0.052, "costPerUnit": 15, "estimatedCost": 0.78, "confidence": "low" } ``` #### Batch Calculate Costs ```bash POST /api/models/batch/cost Content-Type: application/json Authorization: Bearer { "modelIds": [1, 2, 3], "materialType": "pla" } ``` **Response:** ```json { "materialType": "pla", "models": [...], "totalCost": 2.34, "averageCost": 0.78 } ``` #### Get Available Materials ```bash GET /api/models/config/materials ``` **Response:** ```json { "materials": [ { "type": "pla", "costPerUnit": 15, "density": 1.24 }, { "type": "abs", "costPerUnit": 18, "density": 1.04 }, ... ] } ``` ### Frontend Usage #### Show Cost Calculator ```javascript showCostCalculator(); // Opens modal ``` #### Calculate for Selected Models ```javascript updateCostEstimate(); // Uses selected models in grid ``` #### Frontend Files Modified - `client/index.html` - Added cost calculator modal - `client/styles.css` - Added cost calculator styles - `client/features.js` - Cost calculator functions ### Material Costs (Default) - **FDM Filaments**: $15-50/kg - PLA: $15/kg - ABS: $18/kg - PETG: $20/kg - Nylon: $35/kg - TPU: $40/kg - Carbon Fiber: $50/kg - Bamboo: $25/kg - **Resins**: $12-25/ml - Standard: $12/ml - Tough: $18/ml - Flexible: $20/ml - Castable: $25/ml --- ## 2. Full-Text Search ### Overview Enhanced search that looks across all model metadata fields, not just name and description. ### Searchable Fields - Model Name - Description - Creator - Notes - Source URL - License ### Implementation #### Backend Updated `GET /api/models` endpoint to include full-text search: ```bash GET /api/models?search=keyword&license=MIT&fileType=.stl&sortBy=name&sortOrder=ASC ``` Query Parameters: - `search` - Search term (full-text across all fields) - `license` - Filter by license - `fileType` - Filter by file type - `minSize` - Minimum file size in bytes - `maxSize` - Maximum file size in bytes - `hasSupports` - Filter by support status (true/false) - `sortBy` - Sort field (name, created_at, updated_at, file_size) - `sortOrder` - Sort direction (ASC/DESC) - `page` - Page number (default: 1) - `limit` - Results per page (default: 20) #### Frontend Updated search bar to use advanced filters: ```javascript handleAdvancedSearch(query); // Uses filter values from sidebar applyFilters(); // Apply all active filters ``` ### Updated Search Logic ```javascript // Search across metadata query += ` AND ( m.name LIKE ? OR m.description LIKE ? OR m.creator LIKE ? OR m.notes LIKE ? OR m.source_url LIKE ? OR m.license LIKE ? )`; ``` --- ## 3. License Management ### Overview Track and manage model licenses (MIT, Creative Commons, GPL, Apache, CC0, Custom, Unknown). ### Features - **License Types**: Predefined common licenses + custom option - **License Filter**: Filter models by license in sidebar - **License Display**: Shows license in model metadata - **Database Field**: New `license` column in models table ### Implementation #### Database New column added to `models` table: ```sql ALTER TABLE models ADD COLUMN license TEXT DEFAULT 'Unknown'; ``` #### API ##### Create Model with License ```bash POST /api/models Content-Type: multipart/form-data - files: - name: Model Name - license: MIT Response: Model created with license field ``` ##### Filter by License ```bash GET /api/models?license=MIT ``` #### Frontend License dropdown in upload form and sidebar filters: ```html ``` --- ## 4. Bambu Printer Integration ### Overview Connect your Bambu Lab printers (X1, X1 Carbon) and control them directly from MakerStash. ### Features - **Printer Management**: Add, store, and manage multiple printers - **Real-time Status**: Check printer status, temperature, current job - **Print Control**: Pause, resume, stop active prints - **Print History**: View past prints and statistics - **Secure Token Storage**: Access tokens stored server-side ### Backend API #### Add/Connect Printer ```bash POST /api/printers/bambu/connect Content-Type: application/json Authorization: Bearer { "printerName": "Bambu Lab X1", "serialNumber": "0000000ABC123", "modelName": "X1-Carbon", "accessToken": "" } ``` #### Get Connected Printers ```bash GET /api/printers/printers Authorization: Bearer ``` #### Get Printer Status ```bash GET /api/printers/bambu/:printerId/status Authorization: Bearer ``` **Response:** ```json { "success": true, "data": { "status": "idle", ... } } ``` #### Get Current Print Job ```bash GET /api/printers/bambu/:printerId/job ``` **Response:** ```json { "success": true, "data": { "jobId": "...", "fileName": "model.3mf", "progress": 45, "timeRemaining": 3600, "status": "printing", "layer": 100, "totalLayers": 220 } } ``` #### Get Temperature ```bash GET /api/printers/bambu/:printerId/temperature ``` #### Get Print History ```bash GET /api/printers/bambu/:printerId/history?limit=10 ``` #### Control Print ```bash POST /api/printers/bambu/:printerId/control Content-Type: application/json { "action": "pause" | "resume" | "stop" } ``` #### Disconnect Printer ```bash DELETE /api/printers/printers/:printerId ``` ### Database New table created to store printer settings: ```sql CREATE TABLE printer_settings ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER, printer_type TEXT, printer_name TEXT, access_token TEXT, serial_number TEXT, model_name TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ); ``` ### Frontend Printer settings modal: ```javascript showPrinterSettings(); // Opens printer management UI loadPrinters(); // Loads user's connected printers handleAddPrinter(event); // Connects new printer refreshPrinterStatus(printerId); // Checks printer status removePrinter(printerId); // Disconnects printer ``` ### Getting Your Bambu Access Token 1. Go to https://bambulab.com/login 2. Log in with your account 3. Navigate to Account Settings > Security 4. Generate an API Token 5. Copy the token to MakerStash printer settings --- ## 5. Dark/Light Theme Toggle ### Overview Users can now switch between light and dark themes, with preferences saved per user. ### Features - **Theme Toggle Button**: Quick toggle in navigation bar - **User Preference Persistence**: Theme saved to server and local storage - **CSS Variables**: Entire UI theme controlled by CSS variables - **Smooth Transitions**: Theme changes animate smoothly - **Automatic Detection**: Respects system theme preference on first visit ### Implementation #### Database New column in `users` table: ```sql ALTER TABLE users ADD COLUMN theme TEXT DEFAULT 'light'; ``` #### API ##### Get Current User (includes theme) ```bash GET /api/auth/me ``` **Response:** ```json { "user": { "id": 1, "username": "user123", "email": "user@example.com", "theme": "dark", "created_at": "2024-01-01T00:00:00Z" } } ``` ##### Update Theme Preference ```bash PUT /api/auth/me/theme Content-Type: application/json Authorization: Bearer { "theme": "dark" } ``` #### Frontend ##### Toggle Theme ```javascript toggleTheme(); // Switches between light and dark ``` ##### Set Specific Theme ```javascript setTheme('dark'); // Or 'light' ``` ##### Get Current Theme ```javascript const current = getCurrentTheme(); // Returns 'light' or 'dark' ``` #### CSS Variables **Light Theme:** ```css --bg-primary: #ffffff --bg-secondary: #f5f5f5 --text-primary: #222222 --text-secondary: #666666 --border-color: #e0e0e0 --shadow-color: rgba(0, 0, 0, 0.1) ``` **Dark Theme:** ```css --bg-primary: #1a1a1a --bg-secondary: #2d2d2d --text-primary: #ffffff --text-secondary: #cccccc --border-color: #404040 --shadow-color: rgba(0, 0, 0, 0.3) ``` #### Frontend Files - `client/theme.js` - Theme management and CSS variable application - `client/styles.css` - CSS variables and dark mode styles - `client/index.html` - Theme toggle button in navbar --- ## Files Modified/Created ### Backend Files - `server/database.js` - Added license column, theme column, printer_settings table - `server/routes/models.js` - Updated with cost endpoints, full-text search - `server/routes/auth.js` - Added theme preference endpoints - `server/routes/printers.js` - New printer management endpoints - `server/services/costCalculator.js` - New cost calculation service - `server/services/bambuPrinterAPI.js` - New Bambu API integration - `server/index.js` - Registered printers route ### Frontend Files - `client/index.html` - Added modals, theme toggle, license filter - `client/styles.css` - Added theme variables, cost calculator styles, printer styles - `client/theme.js` - New theme management system - `client/features.js` - New feature implementations - `client/app.js` - Enhanced with theme support --- ## Usage Examples ### Example 1: Calculate Printing Costs ```javascript // Select models in the grid // Click "Calculate Costs" or use showCostCalculator() // Choose material type // View estimated costs for selected models ``` ### Example 2: Search with Filters ```javascript // Use search bar for full-text search // Filter by license in sidebar // Filter by file type // Sort results // Results update in real-time ``` ### Example 3: Connect Bambu Printer ```javascript // Click printer icon in top menu // Enter printer name, serial number, model, and access token // Click "Connect Printer" // View printer status, control prints, check history ``` ### Example 4: Switch Themes ```javascript // Click theme toggle button (moon/sun icon) in navbar // Theme switches instantly // Preference saved to server // Applied automatically on next login ``` --- ## Configuration ### Cost Calculator Configuration Edit default material costs in `server/services/costCalculator.js`: ```javascript const DEFAULT_COSTS = { 'pla': 15, // $15/kg 'abs': 18, // $18/kg // ... etc }; ``` ### Bambu API Configuration Update API base URL in `server/services/bambuPrinterAPI.js` if needed: ```javascript const BAMBU_API_BASE = 'https://api.bambulab.com'; ``` --- ## Troubleshooting ### Cost Calculator Shows "Unknown Confidence" - This is normal - file size-based estimates have low confidence - For better accuracy, extract actual model dimensions (future feature) ### Bambu Printer Connection Fails - Verify access token is correct and hasn't expired - Check printer serial number matches exactly - Ensure printer is connected to internet - Check Bambu Labs API status ### Theme Not Saving - Verify you're logged in (theme saved per user) - Check browser localStorage isn't disabled - Check server can reach the `/api/auth/me/theme` endpoint ### Search Not Finding Results - Check spelling and try alternative keywords - Try searching different fields (creator, notes, etc.) - Remove filters to see all results - Search is case-insensitive --- ## Future Enhancements 1. **3D Model Dimension Extraction** - Get actual volume for cost accuracy 2. **Print Time Estimation** - Integration with Cura, PrusaSlicer 3. **Material Library** - Community material costs and properties 4. **Printer Fleet Dashboard** - Monitor multiple printers simultaneously 5. **Filament Tracking** - Track filament inventory and costs 6. **Cost History** - Track printing costs over time 7. **Advanced Theme Customization** - Custom color schemes 8. **Multi-language Support** - Localized search and interfaces --- ## Support For issues or questions about these features: 1. Check this documentation 2. Review the API documentation in `README.md` 3. Check browser console for JavaScript errors 4. Review server logs for backend errors