@xbibzlibrary/espwebjs

v1.0.2

Published

5 months ago

Advanced ESP Web Flasher Library - Powerful ESP8266/ESP32 Flasher dengan Web Serial API, Auto-Detection, dan Multi-Protocol Support

0High
0Medium
0Low

xbibzbackup

esp8266 esp32 esptool flasher firmware web-serial iot embedded xbibz flash-tool esp32s2 esp32c3 esp32s3

⚡ ESP Web Flasher by Xbibz Official

🚀 Advanced ESP8266/ESP32 Web Flasher Library

📖 Documentation • 🎯 Features • 🚀 Quick Start • 💡 Examples

🎨 Apa itu ESP Web Flasher?

ESP Web Flasher adalah library JavaScript modern yang memungkinkan Anda untuk flash firmware ESP8266/ESP32 langsung dari browser web tanpa perlu software eksternal!

Bayangkan: Drag, Drop, Flash! 🔥

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Browser   │ ───▶ │ Web Serial   │ ───▶ │ ESP Device  │
│  (Chrome)   │      │     API      │      │  (ESP32)    │
└─────────────┘      └──────────────┘      └─────────────┘
      ↓                     ↓                      ↓
   Pick File          Auto Detect           Flash Success!

✨ Fitur Unggulan

🎯 Multi-Chip Support

✅ ESP8266
✅ ESP32
✅ ESP32-S2
✅ ESP32-C3
✅ ESP32-S3

⚡ Auto Everything

✅ Auto-Detection
✅ Auto-Reset
✅ Auto-Protocol Selection
✅ Auto-Error Recovery

🔧 Developer Friendly

✅ Zero Dependencies
✅ TypeScript Ready
✅ UMD Format
✅ Browser & Node.js

📊 Advanced Features

✅ Real-time Logging
✅ Performance Monitor
✅ Progress Tracking
✅ Error Handling

🚀 Quick Start

📦 Instalasi

Opsi 1: NPM

npm install @xbibzlibrary/espwebjs

Opsi 2: CDN

<script src="https://unpkg.com/@xbibzlibrary/espwebjs@latest/esp-web-flasher.js"></script>

Opsi 3: Download Langsung

# Clone repository
git clone https://github.com/xbibzlibrary/espwebjs
cd espwebjs

⚡ Penggunaan Super Cepat (3 Langkah!)

<!DOCTYPE html>
<html>
<head>
    <script src="esp-web-flasher.js"></script>
</head>
<body>
    <input type="file" id="firmware" accept=".bin">
    <button onclick="flash()">🔥 Flash Now!</button>

    <script>
        // 1️⃣ Initialize
        const flasher = new ESPWebFlasher.ESPFlasher();
        
        // 2️⃣ Request Port
        async function flash() {
            await flasher.initialize();
            const port = await flasher.requestPort();
            
            // 3️⃣ Flash!
            const file = document.getElementById('firmware').files[0];
            await flasher.flash(port, file);
            
            alert('✅ Flash Complete!');
        }
    </script>
</body>
</html>

🎉 That's it! Serius, cuma 3 langkah!

📖 Documentation

🏗️ Arsitektur Library

@xbibzlibrary/espwebjs
│
├── 🧠 Core Modules
│   ├── ESPFlasher         → Main controller
│   ├── FlashManager       → Flash operations
│   └── DeviceDetector     → Auto chip detection
│
├── 📡 Protocol Handlers
│   ├── ESP8266Protocol    → ESP8266 specific
│   ├── ESP32Protocol      → ESP32 base protocol
│   ├── ESP32S2Protocol    → ESP32-S2 support
│   ├── ESP32C3Protocol    → ESP32-C3 support
│   └── ESP32S3Protocol    → ESP32-S3 support
│
├── 🛠️ Utilities
│   ├── ErrorHandler       → Comprehensive error management
│   ├── Validator          → Input validation
│   ├── PerformanceMonitor → Real-time metrics
│   ├── FileProcessor      → Firmware file handling
│   └── PortScanner        → Serial port detection
│
└── 🔧 Reset System
    ├── ResetHandler       → Reset coordination
    └── DeviceReset        → Hardware reset sequences

🎯 API Reference

ESPFlasher (Main Class)

const flasher = new ESPWebFlasher.ESPFlasher();

| Method | Description | Return | |--------|-------------|--------| | initialize() | Initialize flasher system | Promise<boolean> | | requestPort() | Request serial port access | Promise<SerialPort> | | listPorts() | List all available ports | Promise<Array> | | autoDetect() | Auto-detect ESP devices | Promise<Array> | | flash(port, file, options) | Flash firmware to device | Promise<boolean> | | erase(port, options) | Erase device flash | Promise<boolean> | | readMac(port) | Read device MAC address | Promise<string> | | getChipInfo(port) | Get chip information | Promise<Object> | | getStatus() | Get current operation status | Object | | setLogLevel(level) | Set logging level | void | | cancelOperation() | Cancel current operation | boolean |

Flash Options

const options = {
    flashSize: '4MB',      // '1MB', '2MB', '4MB', '8MB', '16MB'
    flashMode: 'dio',      // 'qio', 'qout', 'dio', 'dout'
    flashFreq: '80m',      // '40m', '80m'
    offset: 0x0000,        // Flash address offset
    baudRate: 115200       // Baud rate for flashing
};

await flasher.flash(port, firmwareFile, options);

💡 Contoh Penggunaan

🎬 Example 1: Basic Flash

// Simple flash operation
async function simpleFlash() {
    const flasher = new ESPWebFlasher.ESPFlasher();
    
    // Initialize
    await flasher.initialize();
    
    // Get port
    const port = await flasher.requestPort();
    
    // Get file from input
    const fileInput = document.getElementById('firmwareFile');
    const file = fileInput.files[0];
    
    // Flash!
    try {
        await flasher.flash(port, file);
        console.log('✅ Flash successful!');
    } catch (error) {
        console.error('❌ Flash failed:', error.message);
    }
}

🎯 Example 2: Advanced Flash dengan Progress

async function advancedFlash() {
    const flasher = new ESPWebFlasher.ESPFlasher();
    
    // Set log level untuk debugging
    flasher.setLogLevel('DEBUG');
    
    // Initialize dengan error handling
    try {
        await flasher.initialize();
    } catch (error) {
        if (error.code === 'SERIAL_NOT_AVAILABLE') {
            alert('⚠️ Browser Anda tidak support Web Serial API!');
            return;
        }
    }
    
    // Auto-detect semua device
    const devices = await flasher.autoDetect();
    console.log(`🔍 Found ${devices.length} device(s)`);
    
    devices.forEach(device => {
        console.log(`📟 ${device.info.chip} - ${device.info.macAddress}`);
    });
    
    // Flash dengan custom options
    const options = {
        flashSize: '4MB',
        flashMode: 'dio',
        flashFreq: '80m',
        offset: 0x1000
    };
    
    // Monitor progress
    const checkProgress = setInterval(() => {
        const status = flasher.getStatus();
        console.log(`⏳ Progress: ${status.operationStatus.currentOperation}`);
    }, 1000);
    
    // Flash
    await flasher.flash(devices[0].port, file, options);
    
    clearInterval(checkProgress);
    console.log('🎉 Flash completed!');
}

🔥 Example 3: Multi-Device Flash

async function flashMultipleDevices() {
    const flasher = new ESPWebFlasher.ESPFlasher();
    await flasher.initialize();
    
    // Scan all devices
    const devices = await flasher.autoDetect();
    
    // Flash each device
    for (const device of devices) {
        console.log(`🔄 Flashing ${device.info.chip}...`);
        
        try {
            await flasher.flash(device.port, firmwareFile);
            console.log(`✅ ${device.info.chip} flashed successfully!`);
        } catch (error) {
            console.error(`❌ Failed to flash ${device.info.chip}:`, error.message);
        }
    }
    
    console.log('🎊 All devices flashed!');
}

📊 Example 4: Real-time Monitoring

async function flashWithMonitoring() {
    const flasher = new ESPWebFlasher.ESPFlasher();
    await flasher.initialize();
    
    const port = await flasher.requestPort();
    
    // Setup monitoring
    const monitor = setInterval(() => {
        const status = flasher.getStatus();
        
        // Display metrics
        console.log('📊 Performance Metrics:');
        status.performance.forEach(metric => {
            console.log(`  ${metric.operation}: ${metric.duration}ms`);
        });
        
        // Display logs
        const recentLogs = status.logHistory.slice(-5);
        console.log('📝 Recent Logs:');
        recentLogs.forEach(log => {
            console.log(`  [${log.level}] ${log.message}`);
        });
    }, 2000);
    
    // Flash
    await flasher.flash(port, file);
    
    clearInterval(monitor);
}

🛠️ Example 5: Error Handling & Recovery

async function robustFlash() {
    const flasher = new ESPWebFlasher.ESPFlasher();
    
    try {
        await flasher.initialize();
        const port = await flasher.requestPort();
        
        // Verify chip before flashing
        const chipInfo = await flasher.getChipInfo(port);
        console.log(`🔍 Detected: ${chipInfo.chip}`);
        
        // Read MAC for verification
        const mac = await flasher.readMac(port);
        console.log(`📟 MAC Address: ${mac}`);
        
        // Flash with retry logic
        let attempts = 0;
        const maxAttempts = 3;
        
        while (attempts < maxAttempts) {
            try {
                await flasher.flash(port, file);
                console.log('✅ Flash successful!');
                break;
            } catch (error) {
                attempts++;
                console.warn(`⚠️ Attempt ${attempts} failed: ${error.message}`);
                
                if (attempts < maxAttempts) {
                    console.log('🔄 Retrying...');
                    await new Promise(resolve => setTimeout(resolve, 2000));
                } else {
                    throw new Error('❌ Max attempts reached');
                }
            }
        }
        
    } catch (error) {
        console.error('💥 Fatal error:', error.message);
        
        // Attempt recovery
        console.log('🔧 Attempting recovery...');
        flasher.cancelOperation();
        flasher.reset();
    }
}

🎨 UI Examples

📱 Contoh Interface Sederhana

<style>
    .flash-container {
        max-width: 600px;
        margin: 50px auto;
        padding: 30px;
        border-radius: 12px;
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        color: white;
        box-shadow: 0 10px 40px rgba(0,0,0,0.2);
    }
    
    .flash-button {
        background: white;
        color: #667eea;
        border: none;
        padding: 15px 30px;
        border-radius: 8px;
        font-size: 18px;
        font-weight: bold;
        cursor: pointer;
        transition: transform 0.2s;
    }
    
    .flash-button:hover {
        transform: scale(1.05);
    }
    
    .progress-bar {
        height: 8px;
        background: rgba(255,255,255,0.3);
        border-radius: 4px;
        overflow: hidden;
        margin: 20px 0;
    }
    
    .progress-fill {
        height: 100%;
        background: white;
        transition: width 0.3s;
    }
</style>

<div class="flash-container">
    <h2>⚡ ESP Web Flasher</h2>
    <input type="file" id="firmware" accept=".bin" style="margin: 20px 0;">
    <button class="flash-button" onclick="flashDevice()">
        🔥 Flash Device
    </button>
    <div class="progress-bar">
        <div class="progress-fill" id="progress" style="width: 0%"></div>
    </div>
    <div id="status">Ready to flash...</div>
</div>

🔧 Browser Compatibility

| Browser | Version | Support | |---------|---------|---------| | 🌐 Chrome | 89+ | ✅ Full Support | | 🦊 Firefox | - | ❌ Not Yet | | 🧭 Edge | 89+ | ✅ Full Support | | 🎭 Opera | 76+ | ✅ Full Support | | 🧪 Safari | - | ❌ Not Yet |

Note: Web Serial API diperlukan. Pastikan browser Anda support!

🤝 Contributing

Kami sangat welcome kontribusi! 🎉

🍴 Fork repository
🌿 Buat branch baru (git checkout -b feature/AmazingFeature)
💾 Commit changes (git commit -m 'Add some AmazingFeature')
📤 Push ke branch (git push origin feature/AmazingFeature)
🎯 Buat Pull Request

📞 Support & Contact

💬 Connect with Xbibz Official

⭐ Jika project ini membantu, berikan star di GitHub!

📄 License

See LICENSE file for details.

🎯 Roadmap

[x] ESP8266 Support
[x] ESP32 Support
[x] ESP32-S2/C3/S3 Support
[x] Auto-detection
[x] Real-time logging
[ ] OTA Update Support
[ ] File System Upload
[ ] SPIFFS Support
[ ] TypeScript Definitions
[ ] React Component
[ ] Vue Component
[ ] Electron Support

🌟 Made with ❤️ by Xbibz Official

Happy Flashing! 🚀