https://github.com/canstralian/piflash
Raspberry Pi Image Flasher Web Application
https://github.com/canstralian/piflash
raspberry-pi
Last synced: 2 months ago
JSON representation
Raspberry Pi Image Flasher Web Application
- Host: GitHub
- URL: https://github.com/canstralian/piflash
- Owner: canstralian
- Created: 2025-06-20T16:02:11.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-05T04:03:29.000Z (9 months ago)
- Last Synced: 2025-10-05T05:39:40.188Z (9 months ago)
- Topics: raspberry-pi
- Language: JavaScript
- Homepage: https://huggingface.co/spaces/S-Dreamer/piflash
- Size: 99.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
---
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
1. **Clone or download** this repository
2. **Open index.html** in your web browser
3. **Select a storage device** (SD card or USB drive)
4. **Choose an OS image** from the library or upload your own
5. **Configure settings** (optional): Wi-Fi, SSH, hostname
6. **Click Flash** to start the process
## Development Setup
```bash
# 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
1. **Device Selection**: Choose target storage device
2. **Image Preparation**: Download or prepare the OS image
3. **Unmounting**: Safely unmount the device
4. **Writing**: Write the image data to the device
5. **Verification**: Verify the written data (if enabled)
6. **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
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **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:
```bash
# 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:
1. Navigate to browser settings
2. Find "Site permissions" or "Privacy and security"
3. Allow file system access for this application
## License
This project is licensed under the MIT License - see the [LICENSE](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!** 🥧✨