PiSafe GUI 🫐

A graphical interface (PyQt5) for the pisafe tool — an easy way to flash system images onto SD/USB drives and create backups of them, without using the terminal.

---

📸 Preview

---

✨ Features

• ⚡ Flash image → SD/USB — pick an image file (.img, .zip, .xz, .gz, .zst) and a target drive, flash it in one click
• 💾 Backup SD/USB → image — create backups of SD cards with your choice of compression format
• 🗂️ Image version management — group backups into named projects with their own base folder, tag each one with a free-text version label (v1, v2, "stable", ...), and browse/delete them in a dedicated tab (SQLite-backed)
• ✅ Checksum verification — optionally verify a flash by comparing the SHA256 of the source .img/.iso against what was actually written to the disk, reported automatically as a match/mismatch
• 🔎 Downloaded image check — check a downloaded image's integrity before flashing it: auto-detects a .sha256/.sha256sum/.md5 file next to it, or lets you paste the expected checksum from the download page
• 📀 Flash to multiple disks at once — add up to 8 target disks with +/- and flash the same image to all of them in parallel, with a per-disk progress row and a final success/failure summary
• 🔧 Quick format — format a disk (FAT32/exFAT/NTFS/ext4), restricted to USB/SD disks just like flashing
• 🛡️ System disk protection — the app automatically detects and hides disks where the system is mounted (/, /boot, /home, etc.), so there's no risk of accidentally overwriting your own system
• 📋 Disk list — full overview of connected block devices (lsblk)
• 📜 Real-time logs — full command output visible inside the app
• 🎨 Dark theme — interface styled after Catppuccin Mocha

---

🌐 Languages

The interface is available in:

• 🇬🇧 English (default)
• 🇵🇱 Polski
• 🇪🇸 Español
• 🇵🇹 Português
• 🇮🇹 Italiano
• 🇩🇪 Deutsch

Switch language from the dropdown in the app's header — the app restarts to apply the change. Translations live in translations.py as plain key → text dictionaries, so adding a new language doesn't require touching any UI code. Want to add yours? See Contributing below.

---

🖥️ Requirements

• Linux / Raspberry Pi OS
• Python 3.7+
• PyQt5
• pisafe (the underlying tool, installed automatically by install.sh)

---

🚀 Installation

git clone https://github.com/cyryllo/pisafe-gui.git
cd pisafe-gui
bash install.sh

The install.sh script:

1. Installs python3-pyqt5, pv and sqlite3
2. Installs PolicyKit (pkexec), needed to run flash/backup with administrator rights
3. Installs the pisafe tool if it's not already present on the system
4. Creates an application shortcut in the system menu

---

▶️ Running the app

From the application menu: Accessories/Utilities > PiSafe GUI

From the terminal:

python3 pisafe_gui.py

Flash/backup operations require administrator privileges, since pisafe operates directly on block devices. The app runs them via pkexec (PolicyKit), which shows a native graphical password prompt — no terminal needed. pkexec is installed automatically by install.sh (polkitd + pkexec, falling back to the policykit-1 package on older systems).

---

📁 Project structure

pisafe-gui/
├── pisafe_gui.py       # Main PyQt5 application
├── translations.py     # i18n strings and language persistence
├── db.py               # SQLite storage for image version management
├── requirements.txt    # Python dependencies
├── install.sh          # Installation script
├── icon.png            # App icon
├── VERSION             # Current version number
├── LICENSE             # GPLv3 license text
├── doc/                # Screenshots and other docs assets
├── README.md
└── README_pl.md        # Polish translation of this README

---

🗺️ Planned features (TODO)

• Debian (.deb) package
• Store a checksum (SHA256) for each backed-up image, and reuse it in "Check image" instead of needing a sidecar file or manual paste
• "Flash this version" shortcut button in the Versions tab, pre-filling the Flash tab's image path
• Retention/cleanup tools for old versions (e.g. keep last N, or older-than-X-days)

---

🤝 Contributing

Pull requests and issues are welcome! If you find a bug or have a feature idea, please open an issue in this repository.

Adding a translation: open translations.py, add your language code and name to LANGUAGES, then copy the "en" dictionary under a new key and translate the values (keep the {placeholders} as they are). That's it — no other code changes needed. PRs for new languages are very welcome!

---

📄 License

This project is available under the GNU GPLv3 license.

Built on top of pisafe by RichardMidnight (also GPLv3).

---

🙏 Acknowledgments

• RichardMidnight — for creating the pisafe tool
• Catppuccin — for the theme's color palette