A terminal-based tool for managing the Raspberry Pi Pico (W / 2W) directly from your terminal – no GUI or browser required, with an intuitive menu, full file management and an automatic backup system via mpremote.
- MicroPython Compatibility
- Motivation
- Features
- Installation
- Getting Started
- Menu Overview
- Function Reference
- Backup System
- Project Structure
- Configuration
- Troubleshooting
- Known Limitations
- Roadmap
- License
- Contributing
PicoHub communicates via mpremote and is therefore theoretically compatible with any device running MicroPython – including ESP32, ESP8266 and STM32.
Officially tested on the Raspberry Pi Pico and Pico 2W only. Functionality on other devices is theoretically possible but has not been verified. Different behaviour may occur.
Traditional tools like Thonny are impractical for larger project structures on the Raspberry Pi Pico. Manually transferring many files and subdirectories is time-consuming and error-prone.
PicoHub solves this with a central CLI interface that bundles all essential tasks:
- Efficient file transfer (batch upload/download)
- Comfortable file management without a browser
- Remote script execution with live output
- Automatic backup system
- REPL access for interactive development
💡 Tip: Remote Use via SSH & Tailscale
The decision to build a pure CLI application (instead of a GUI) was deliberate: PicoHub runs entirely on the Linux PC or server that the Pico is physically connected to via USB. Because it is terminal-based, you can reach that machine remotely – for example by SSHing into it, or by connecting it to a Tailscale network. This lets you control your Pico from another computer on the network or while on the go, without needing a graphical interface.
SSH and Tailscale run on the PC/server – not on the Pico. The Pico itself is not involved in the network setup at all; it only communicates with PicoHub locally over USB. Both tools are not part of this project and need to be set up separately. If you do use them, secure access accordingly (e.g. SSH keys instead of passwords, Tailscale ACLs) – as you would for any remote access.
File Management
- Upload & Download – transfer complete directories
- Nano Editor – edit or create files directly on the Pico
- Rename & Move – reorganise files and folders
- Delete – with confirmation prompt
- Create directories
cat– quickly view file contents in the terminal
File Structure
- Tree View – recursive display of all files and folders
Pico Control
- Run scripts – with live output in the terminal
- REPL Terminal – interactive MicroPython session
- Stop / Reset – cleanly stop a running script
- Factory Reset – full reset with safety confirmation
Backup System
- Automatic backups on Nano edit and reset
- Unlimited backup history as ZIP files
- Restore via menu
System Info
- Fetch Flash, RAM, temperature and device ID
- Automatic device detection via
mpremote devs - JSON export of stats
| Requirement | Details |
|---|---|
| Operating System | Linux (Windows via WSL2 only) |
| Python | 3.10 or newer |
| Raspberry Pi Pico | W / 2W (standard Pico also compatible) |
| mpremote | installed automatically via install.sh |
| nano | required for the built-in editor (2.3) |
# Clone the repository or extract the ZIP
git clone https://github.com/ColorFlowStudios/PicoHub.git
cd PicoHub
# Run the installation script
bash install/install.shThe script creates a Python virtual environment (venv) and installs all dependencies locally in the project folder. No sudo rights required.
If nano is missing:
sudo apt-get install nanoNote for GitHub:
config.jsonstores your Pico's hardware ID and is currently not listed in.gitignore. Add it there, or clearidandnicknamebefore pushing to a public repository.
bash start_cli.shThe script activates the virtual environment, checks the installation and opens the main menu. It must always be run from the project folder.
╔══════════════════════════════════════════════════════════╗
║ PicoHub v1.0 19.06.2026 22:41 ║
╠══════════════════════════════════════════════════════════╣
║ Device : /dev/ttyACM0 ║
║ ID : 82e05412055fd1c7 ║
║ Name : Pico 2W ║
║ ║
║ Stats : ║
║ RAM : 1.1% used (441 KB free / 446 KB) ║
║ Flash : 1.4% used (2524 KB free / 2560 KB) ║
║ Temp : 31.26 °C ║
╠══════════════════════════════════════════════════════════╣
║ [1] Info ║
║ [1.1] Fetch Stats ║
║ [1.2] Show Tree ║
║ [2] FileManager ║
║ [2.1] Download Data from Pico ║
║ [2.2] Upload Data to Pico ║
║ [2.3] Pico Nano Editor ║
║ [2.4] Pico cat ║
║ [2.5] Rename or Move File/Folder ║
║ [2.6] Delete File/Folder ║
║ [2.7] Create Directory ║
║ [3] PicoControl ║
║ [3.1] Reset Pico(Delete all Files on Pico!!!) ║
║ [3.2] Restore Backup ║
║ [3.3] Show Tree ║
║ [3.4] Run Script ║
║ [3.5] Stop / Reset ║
║ [3.6] REPL Terminal ║
║ [4] Upload (data/upload/) ║
║ [4.1] Add File/Folder from PC ║
║ [4.2] Show Tree ║
║ [4.3] Clear Folder ║
╠══════════════════════════════════════════════════════════╣
║ ║
╚══════════════════════════════════════════════════════════╝
Select a menu item by typing its number (e.g. 2.2 → Enter). Press q to quit PicoHub. If no Pico is connected, the header shows No Pico connected.
| Function | Description | Output |
|---|---|---|
| 1.1 Fetch Stats | Fetch Flash, RAM, temperature and device ID | data/json/pico_stats.json |
| 1.2 Show Tree | Display the complete file structure of the Pico | Terminal, read-only |
| Function | Description | Location |
|---|---|---|
| 2.1 Download Data from Pico | Download all files from the Pico | data/download/ |
| 2.2 Upload Data to Pico | Upload all files from data/upload/ – creates backup if changed |
Pico root |
| 2.3 Pico Nano Editor | Edit or create a file on the Pico using nano | On-device |
| 2.4 Pico cat | Display file contents in the terminal | Stdout, read-only |
| 2.5 Rename or Move File/Folder | Rename or move a file or folder | Pico |
| 2.6 Delete File/Folder | Delete a file or folder recursively (with confirmation) | — |
| 2.7 Create Directory | Create a new directory | Pico |
Note on 2.2: An automatic backup is created before upload if the file tree changes.
Note on 2.3: The Nano Editor downloads all files, opens the selected file, then completely resets the Pico and re-uploads everything. A backup is created automatically if the file tree has changed. For important projects, consider a manual backup beforehand.
Typical upload workflow:
# Copy file into the staging area
cp my_script.py data/upload/
# Start PicoHub and upload
bash start_cli.sh
# → [2] → [2.2]| Function | Description | Safety |
|---|---|---|
| 3.1 Reset Pico | Delete all files and folders on the Pico | Confirmation with YES required |
| 3.2 Restore Backup | Restore a backup from data/backup/ |
Select from numbered list |
| 3.3 Show Tree | Display file structure | Read-only |
| 3.4 Run Script | Run a script with live output | Ctrl+C interrupts, Ctrl+] exits connection |
| 3.5 Stop / Reset | Cleanly stop a running script | — |
| 3.6 REPL Terminal | Interactive MicroPython session | Ctrl+C interrupts, Ctrl+] exits connection |
Key bindings for Run Script and REPL:
| Key | Effect |
|---|---|
Ctrl + C |
Interrupt script/input – returns to >>> prompt |
Ctrl + ] |
Exit connection – this stops the Pico |
Ctrl + ]only works reliably at the>>>prompt. If you are stuck inside a running script, pressCtrl + Cfirst.
The data/upload/ folder is the staging area for uploads. Files go here before being transferred to the Pico with 2.2.
| Function | Description |
|---|---|
| 4.1 Add File/Folder from PC | Copy a file or folder from the PC to data/upload/ |
| 4.2 Show Tree | Display the current contents of data/upload/ |
| 4.3 Clear Folder | Empty data/upload/ completely (cannot be undone) |
Backups are created automatically for certain operations – but not all:
| Operation | Automatic Backup |
|---|---|
| 2.2 Upload | ✅ Yes, if the file tree has changed |
| 2.3 Nano Editor | ✅ Yes, if the file tree has changed |
| 3.1 Reset | ✅ Yes, if the file tree has changed |
Backups are stored as ZIP files in data/backup/. A log with timestamps and actions is kept in data/backup/backup_info.txt:
15.06.2026 10:39 | ID: 20260615_1039 | pico_reset: Pico fully cleared | zip: pico_nano_20260615_1039.zip
18.06.2026 00:40 | ID: 20260618_0040 | pico_nano: file test.py edited | zip: pico_nano_20260618_0040.zip
Restore via 3.2 Restore Backup.
PicoHub/
├── src/
│ ├── cli/
│ │ └── cli_layout.py # Menu rendering and UI
│ ├── controller/ # Workflow layer (user interaction, confirms)
│ │ ├── cli/
│ │ │ └── cli.py # Menu handler / main loop
│ │ └── core/
│ │ ├── pico_control/ # Run, Reset, REPL, Backup-Restore
│ │ ├── info/ # Stats, Tree
│ │ └── file_manager/ # Upload, Download, mv, rm, Nano Editor
│ ├── core/ # Low-level layer (mpremote calls)
│ │ ├── control/ # Device detection, script start/stop, REPL
│ │ ├── file_manager/ # Upload/download/backup helpers
│ │ └── info/ # Stats and tree queries
│ └── utils/
│ └── uni/ # Shared utilities (logger, config, paths)
├── data/
│ ├── backup/ # ZIP backups + backup_info.txt
│ ├── download/ # Download target (2.1)
│ ├── upload/ # Upload staging area (2.2)
│ ├── logs/error.log
│ └── json/pico_stats.json
├── install/
│ ├── install.sh # Initial installation
│ ├── check_install.sh # Dependency check
│ └── requirements.txt
├── start_cli.sh # Entry point
├── config.json # Configuration
config.json in the project root:
{
"pico": {
"info": {
"id": "",
"nickname": ""
}
}
}id– automatically filled with your Pico's hardware ID on the first call to 1.1 Fetch Stats, as long as the field is empty.nickname– optional, freely assignable; shown in the menu header when the storedidmatches the detected device.
Device path, baud rate and timeout are determined automatically via mpremote devs – there are no further settings.
config.jsonis currently not in.gitignore. Add it there or clearidandnicknamebefore committing to a public repository.
| Problem | Solution |
|---|---|
| "No Pico connected" | lsusb | grep Pico – check USB cable and port |
No access to /dev/ttyACM* |
sudo usermod -aG dialout $USER, then log out and back in |
nano not found |
sudo apt-get install nano |
ModuleNotFoundError |
source venv/bin/activate && pip install --upgrade -r install/requirements.txt |
| Wrong Python version | python3 --version – 3.10 or newer required |
| Start fails | Make sure bash start_cli.sh is run from the project folder |
| Limitation | Details | Workaround |
|---|---|---|
| Linux only | termios, tty and /dev/ttyACM* are Linux-specific |
WSL2 on Windows possible |
| Single Pico | Always uses the first detected device | Multi-Pico support planned for v2 |
| nano required | For editor function 2.3 | External editing + manual upload |
| Nano reset | After editing, the Pico is fully re-flashed | Create a backup beforehand |
Planned for v2:
- Multi-Pico support – manage multiple Picos simultaneously
- Web UI – Flask-based browser access
- Sync mode – bidirectional directory synchronisation
- Extended statistics – performance monitoring
- Windows support – native Windows compatibility
This project is available under the MIT License. See LICENSE for details.
Contributions are welcome:
- Bug reports – open an Issue
- Feature requests – submit your ideas
- Pull requests – contribute code improvements
- Documentation – improve the README or guides
git checkout -b feature/my-feature
git commit -am 'Add my-feature'
git push origin feature/my-feature
# → open a Pull RequestPicoHub v1.0 – Tested on Raspberry Pi Pico 2W