metadata
license: apache-2.0
title: PiFlash
sdk: static
emoji: 📈
colorFrom: red
colorTo: green
short_description: A modern, web-based tool for flashing Raspberry Pi OS images
PiFlash - Raspberry Pi Image Flasher Web Application
A modern, web-based tool for flashing Raspberry Pi OS images to SD cards. Built with vanilla JavaScript, HTML5, and Tailwind CSS for maximum compatibility and ease of use.
Features
- Device Detection: Automatically detects available storage devices
- OS Image Library: Browse recommended and community OS images
- Custom Image Support: Upload and flash your own image files
- Progress Tracking: Real-time progress monitoring with detailed status
- Configuration Options: Pre-configure Wi-Fi, SSH, and hostname settings
- Responsive Design: Works on desktop and mobile devices
- No Installation Required: Runs directly in your web browser
Quick Start
- Clone or download this repository
- Open index.html in your web browser
- Select a storage device (SD card or USB drive)
- Choose an OS image from the library or upload your own
- Configure settings (optional): Wi-Fi, SSH, hostname
- Click Flash to start the process
Development Setup
# Install dependencies
npm install
# Start development server
npm run dev
# Run tests
npm test
Browser Compatibility
- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+
Supported File Formats
.img- Raw disk images.zip- Compressed disk images.gz- Gzip compressed images.xz- XZ compressed images
Security Considerations
⚠️ Important: This application requires access to storage devices, which may require elevated permissions or browser API access. Always verify the source and integrity of image files before flashing.
Web API Requirements
This application uses the following web APIs:
- File System Access API (Chrome 86+) - For device access
- Web USB API (Experimental) - For USB device communication
- File API - For reading uploaded files
Configuration Options
Wi-Fi Setup
- SSID: Network name (max 32 characters)
- Password: Network password (WPA/WPA2)
SSH Configuration
- Disabled: SSH access turned off (default)
- Password: Enable SSH with password authentication
- Key: Enable SSH with public key authentication only
System Settings
- Hostname: Custom device name (default: raspberrypi)
- Validation: Verify write after flashing
- Compression: Auto-detect and handle compressed images
Flashing Process
- Device Selection: Choose target storage device
- Image Preparation: Download or prepare the OS image
- Unmounting: Safely unmount the device
- Writing: Write the image data to the device
- Verification: Verify the written data (if enabled)
- Ejection: Safely eject the device when complete
File Structure
piflash-web-app/
├── index.html # Main application interface
├── styles.css # Custom CSS styles and animations
├── js/
│ └── app.js # Main application logic
├── package.json # Project configuration
├── README.md # This file
├── .gitignore # Git ignore rules
└── pre-commit.sh # Pre-commit hooks
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Guidelines
- Use ES6+ JavaScript features
- Follow responsive design principles
- Add comprehensive comments for complex logic
- Include unit tests for new functionality
- Maintain cross-browser compatibility
Testing
The application includes unit tests for core functionality:
# Run all tests
npm test
# Test specific components
npm test -- --testNamePattern="device"
Troubleshooting
Common Issues
Device not detected
- Ensure the SD card is properly inserted
- Try refreshing the device list
- Check browser permissions for device access
Flash process fails
- Verify the image file is not corrupted
- Ensure sufficient space on the target device
- Try using a different SD card
Browser compatibility
- Use a modern browser with File System Access API support
- Enable experimental web platform features if required
- Clear browser cache and cookies
Browser Permissions
Some browsers may require explicit permission to access storage devices:
- Navigate to browser settings
- Find "Site permissions" or "Privacy and security"
- Allow file system access for this application
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Raspberry Pi Foundation for the excellent hardware and documentation
- Tailwind CSS for the utility-first CSS framework
- Font Awesome for the comprehensive icon library
- Community contributors who help improve this tool
Disclaimer
This tool is provided as-is without warranty. Always backup important data before flashing storage devices. The authors are not responsible for data loss or hardware damage.
Happy Flashing! 🥧✨