PixelPot 🖼️

A lightweight image display system for Raspberry Pi that allows users to upload images via a web interface and automatically displays them on a connected screen.

Features

• 📱 Mobile-friendly web interface for image uploads
• 🔄 Automatic slideshow of uploaded images
• 🖥️ Direct framebuffer display (no X server required)
• 🚀 Lightweight - runs smoothly on Raspberry Pi Zero W 2
• 🔁 Auto-restart and boot startup support
• 🗑️ Image management (view and delete uploaded images)

Requirements

• Raspberry Pi (tested on Pi Zero W 2)
• Raspbian OS (terminal mode is fine)
• Screen connected via HDMI
• Network connection (WiFi or Ethernet)

Quick Installation

1. Transfer the Project to Your Pi

From your development machine:

# Using git (on the Pi):
git clone https://github.com/yourusername/pixelpot.git
cd pixelpot

# Or using scp (from your machine):
scp -r /path/to/pixelpot pi@raspi.local:~/
ssh pi@raspi.local
cd ~/pixelpot

2. Run Installation Script

cd ~/pixelpot
chmod +x scripts/install.sh
./scripts/install.sh

This will:

• Install system dependencies (fbi, imagemagick, nodejs, npm, python3)
• Install Node.js packages
• Set up Python virtual environment
• Configure permissions

3. Start the Services

Option A: Manual Start (for testing)

./scripts/start.sh

Option B: Install as System Services (recommended)

sudo ./scripts/install-services.sh

This will:

• Install systemd services
• Enable auto-start on boot
• Start the services immediately

Usage

1. Access the Web Interface

   • Open a browser on any device on the same network
   • Navigate to: http://raspi.local:3000 or http://[PI-IP]:3000

2. Upload Images

   • Click the upload area or drag & drop images
   • Supported formats: JPEG, PNG, GIF, WebP
   • Maximum file size: 5MB

3. View on Screen

   • Images will automatically display on the connected screen
   • Each image shows for 10 seconds by default
   • The slideshow loops continuously

Configuration

Change Display Time

Edit the display service or run manually with different timing:

cd ~/pixelpot/display
source venv/bin/activate
python display.py --time 5  # 5 seconds per image

Change Server Port

Set the PORT environment variable:

PORT=8080 npm start

Service Management

Check Service Status

sudo systemctl status pixelpot-server
sudo systemctl status pixelpot-display

View Logs

# Real-time logs
sudo journalctl -u pixelpot-server -f
sudo journalctl -u pixelpot-display -f

# Or check log files
tail -f /var/log/pixelpot-server.log
tail -f /var/log/pixelpot-display.log

Stop Services

sudo systemctl stop pixelpot-server pixelpot-display

Restart Services

sudo systemctl restart pixelpot-server pixelpot-display

Disable Auto-start

sudo systemctl disable pixelpot-server pixelpot-display

Cloudflare Tunnel Setup (Optional)

To access your PixelPot from anywhere:

1. Install cloudflared:

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

2. Authenticate:

cloudflared tunnel login

3. Create tunnel:

cloudflared tunnel create pixelpot

4. Configure tunnel (create ~/.cloudflared/config.yml):

tunnel: YOUR_TUNNEL_ID
credentials-file: /home/pi/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: pixelpot.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404

5. Route traffic:

cloudflared tunnel route dns pixelpot pixelpot.yourdomain.com

6. Run tunnel:

cloudflared tunnel run pixelpot

Project Structure

pixelpot/
├── server/           # Node.js Express server
│   ├── index.js      # Main server file
│   └── package.json  # Node dependencies
├── display/          # Python display script
│   ├── display.py    # Image display controller
│   └── requirements.txt
├── public/           # Web interface
│   ├── index.html
│   ├── style.css
│   └── script.js
├── uploads/          # Uploaded images directory
└── scripts/          # Installation and service scripts

Troubleshooting

Display Not Working

• Ensure you're in the video group: groups $USER
• Try running with sudo: sudo python display.py
• Check if framebuffer exists: ls /dev/fb*

Server Not Accessible

• Check firewall: sudo ufw status
• Verify server is running: ps aux | grep node
• Check port: sudo netstat -tlnp | grep 3000

Images Not Displaying

• Check uploads directory permissions: ls -la ~/pixelpot/uploads
• Verify fbi is installed: which fbi
• Check Python script logs: sudo journalctl -u pixelpot-display -n 50

Performance Tips

• Keep images under 2MB for best performance on Pi Zero
• Consider resizing images before upload
• Clean old images periodically to save space
• Monitor disk space: df -h

Security Notes

• The server accepts uploads from any device on the network
• Consider adding authentication if exposing to internet
• Regularly clean uploaded images to prevent disk filling
• Use Cloudflare Tunnel instead of port forwarding for internet access

License

MIT

Contributing

Pull requests welcome! Please test on Raspberry Pi before submitting.