584 lines
13 KiB
Markdown
584 lines
13 KiB
Markdown
# 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 <token>
|
|
|
|
{
|
|
"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: <file>
|
|
- 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
|
|
<select id="filterLicense">
|
|
<option value="">All Licenses</option>
|
|
<option value="Unknown">Unknown</option>
|
|
<option value="MIT">MIT</option>
|
|
<option value="Creative Commons">Creative Commons</option>
|
|
<option value="CC0">CC0 (Public Domain)</option>
|
|
<option value="GPL">GPL</option>
|
|
<option value="Apache">Apache</option>
|
|
<option value="Custom">Custom</option>
|
|
</select>
|
|
```
|
|
|
|
---
|
|
|
|
## 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 <token>
|
|
|
|
{
|
|
"printerName": "Bambu Lab X1",
|
|
"serialNumber": "0000000ABC123",
|
|
"modelName": "X1-Carbon",
|
|
"accessToken": "<bambu_access_token>"
|
|
}
|
|
```
|
|
|
|
#### Get Connected Printers
|
|
```bash
|
|
GET /api/printers/printers
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
#### Get Printer Status
|
|
```bash
|
|
GET /api/printers/bambu/:printerId/status
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
**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 <token>
|
|
|
|
{
|
|
"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
|
|
|