0. May required if not already installed
Great 👍
Your steps are almost perfect. I’ll now do two things:
Clean + correct your guide (no confusion, no missing logic)
Mark what is REQUIRED vs OPTIONAL
Make it copy-paste safe and future-proof
I will NOT change your working approach, only refine it.
✅ FINAL STEP-BY-STEP GUIDE
WS2812 LED Control App (Virtualenv + Desktop Shortcut)
This guide works on:
Raspberry Pi OS (Bullseye / Bookworm / Trixie)
Uses virtual environment (safe, recommended)
Launchable from Desktop icon
Copy-pasteable to another Raspberry Pi
🔹 0. System requirements (run once)
sudo apt update
sudo apt upgrade -y
sudo apt install -y \
python3 \
python3-venv \
python3-dev \
python3-tk \
build-essential
✔ Required
✔ No risk
✔ Needed for Tkinter + rpi_ws281x build
🔹 1. Create project folder
mkdir ~/WS2812_LED_Project
cd ~/WS2812_LED_Project
🔹 2. Create virtual environment
python3 -m venv wsenv
✔ Keeps system Python safe
✔ Required because of PEP 668
🔹 3. Activate virtual environment
source wsenv/bin/activate
Prompt will change to:
(wsenv) pi@raspberrypi:~
🔹 4. Upgrade pip tools
pip install --upgrade pip setuptools wheel
🔹 5. Install required Python libraries
pip install rpi_ws281x flask
⚠️ Flask is optional now (not used), but OK to keep.
🔹 6. Create application file
nano led_app.py
➡ Paste your FULL working code
➡ Save with CTRL+O → ENTER → CTRL+X
🔹 7. Test app from terminal (IMPORTANT)
sudo ./wsenv/bin/python led_app.py
Or full path (always works):
sudo /home/pi/WS2812_LED_Project/wsenv/bin/python \
/home/pi/WS2812_LED_Project/led_app.py
✔ LEDs should work
✔ GUI should open
✔ No errors
🔹 8. Create run script (wrapper)
nano run.sh
Paste exactly:
#!/bin/bash
cd "$(dirname "$0")"
sudo ./wsenv/bin/python led_app.py
Save & exit.
Make executable:
chmod +x run.sh
⚠️ If Nano creates run.sh.save, rename:
mv run.sh.save run.sh
chmod +x run.sh
🔹 9. Create Desktop launcher file
nano WS2812_LED_Control.desktop
Paste exactly (NO extra spaces):
[Desktop Entry]
Name=WS2812 LED Control
Comment=Control WS2812 LEDs
Exec=/home/pi/WS2812_LED_Project/run.sh
Icon=applications-graphics
Terminal=false
Type=Application
Categories=Utility;
Save & exit.
🔹 10. Fix .save issue (VERY IMPORTANT)
If file becomes WS2812_LED_Control.desktop.save:
mv ~/WS2812_LED_Project/WS2812_LED_Control.desktop.save \
~/WS2812_LED_Project/WS2812_LED_Control.desktop
Set permissions:
chmod 755 ~/WS2812_LED_Project/WS2812_LED_Control.desktop
🔹 11. Copy shortcut to Desktop
cp ~/WS2812_LED_Project/WS2812_LED_Control.desktop ~/Desktop/
chmod +x ~/Desktop/WS2812_LED_Control.desktop
Trust the shortcut:
gio set ~/Desktop/WS2812_LED_Control.desktop metadata::trusted true
✅ Now double-click works
⚠️ Password prompt appears because WS2812 needs sudo GPIO access
(This is normal and expected)
🔹 12. Project structure (FINAL)
WS2812_LED_Project/
├── led_app.py
├── led_settings.json
├── run.sh
├── WS2812_LED_Control.desktop
└── wsenv/
📦 COPYING PROJECT TO ANOTHER RASPBERRY PI
OPTION A (Recommended – clean & safe)
Copy only these files:
led_app.py
run.sh
WS2812_LED_Control.desktop
On new Pi:
mkdir ~/WS2812_LED_Project
cd ~/WS2812_LED_Project
python3 -m venv wsenv
source wsenv/bin/activate
pip install rpi_ws281x flask
chmod +x run.sh
chmod +x wsenv/bin/python
Run:
sudo ./wsenv/bin/python led_app.py
OPTION B (Fast but heavier)
Copy entire folder including wsenv/
chmod +x run.sh
chmod +x wsenv/bin/python
sudo ./wsenv/bin/python led_app.py
⚠️ Works only if same OS + same Python version
🧠 IMPORTANT NOTES (Read Once)
✔ You CANNOT replace .py with .bin directly
✔ Virtual environment is correct & safe
✔ .save issue is Nano editor behavior
✔ Desktop shortcut needs trust flag
✔ rpi_ws281x requires sudo
✅ YOU NOW HAVE
✔ Professional project structure
✔ Desktop-click app
✔ Copy-paste ready
✔ No system Python breakage
✔ Future PyInstaller compatible
If you want next:
🔐 remove sudo password
🔒 MAC-locked binary
🚀 auto-start on boot
📦 USB installer for customers
Just say the word 👍
Comments
Post a Comment