bbl-shutter-cam

Use a Bambu Lab CyberBrick / BBL_SHUTTER Bluetooth shutter to trigger photos on a Raspberry Pi using rpicam-still.

Perfect for: Headless, reliable time-lapse capture inside 3D printer enclosures with support for multiple printers/cameras through profile-based configuration.

---

What This Does

• 🎥 BLE Listening - Pairs with BBL_SHUTTER and listens for shutter signals
• 📸 Auto Capture - Triggers rpicam-still on each press (configurable)
• 🔧 Multi-Printer - Manage multiple printers/cameras with profiles
• 🎛️ Interactive Tuning - Dial in camera settings interactively
• 🔋 Headless - Runs without GUI; optional systemd auto-start
• 📝 Config-Driven - TOML profiles for easy setup and tweaking
• 🎯 Smart Debounce - Prevents accidental double-triggers
• 📊 Signal Discovery - Auto-detect unknown BLE triggers

---

Quick Start

1. Install System Dependencies

sudo apt update && sudo apt install -y \
  bluetooth bluez libcamera-apps

2. Install bbl-shutter-cam

Option A: Standalone Executable (Recommended - easiest, no Python needed)

1. Download the latest release from GitHub Releases

2. Choose the correct ARM binary for your Pi:

   • 64-bit (most common): bbl-shutter-cam-<version>-linux-arm64
   • 32-bit older Pi: bbl-shutter-cam-<version>-linux-armv7

3. Make it executable and install:

# Option 1: System-wide installation (requires sudo)
chmod +x bbl-shutter-cam-<version>-linux-arm64
sudo mv bbl-shutter-cam-<version>-linux-arm64 /usr/local/bin/bbl-shutter-cam
bbl-shutter-cam --help

# Option 2: User installation (no sudo required)
mkdir -p ~/.local/bin
chmod +x bbl-shutter-cam-<version>-linux-arm64
mv bbl-shutter-cam-<version>-linux-arm64 ~/.local/bin/bbl-shutter-cam
export PATH="$HOME/.local/bin:$PATH"
bbl-shutter-cam --help

Option B: From Source (for developers or custom modifications)

# Install Python development tools first
sudo apt install -y python3 python3-venv python3-pip

# Clone and install
git clone https://github.com/bodybybuddha/bbl-shutter-cam.git
cd bbl-shutter-cam
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bbl-shutter-cam --help

3. Pair Your Device

Complete Bluetooth setup guide →

Quick overview:

sudo bluetoothctl
# power on
# agent on
# scan on
# [wait for BBL_SHUTTER]
# pair AA:BB:CC:DD:EE:FF
# trust AA:BB:CC:DD:EE:FF
# quit

# Note: paired shutters may sleep and not appear in scans.
# Press the shutter button to wake it before scanning or setup.

4. Configure & Run

# Setup first time (learns shutter signal)
bbl-shutter-cam setup --profile my-printer

# Tune camera settings interactively (optional)
bbl-shutter-cam tune --profile my-printer

# Test (no photos taken)
bbl-shutter-cam run --profile my-printer --dry-run --verbose

# Run for real
bbl-shutter-cam run --profile my-printer

Photos save to ~/.config/bbl-shutter-cam/config.toml output directory.

---

Documentation

Installation & Setup:

• Hardware & Software Requirements
• Bluetooth Setup Detailed Guide
• Raspberry Pi System Setup

Using bbl-shutter-cam:

• Quick Start Guide
• Profiles & Configuration
• Camera Settings & Tuning
• Signal Discovery

Advanced:

• Headless Operation & Systemd
• Building Standalone Executables
• Code Architecture & Extending

Help:

• Troubleshooting
• FAQ

---

Features & Configuration

Profiles

Multiple printer setups via named profiles:

bbl-shutter-cam setup --profile p1s-office
bbl-shutter-cam setup --profile p1s-workshop
bbl-shutter-cam run --profile p1s-office

Camera Options

• Resolution (width, height)
• Rotation (0°/90°/180°/270°)
• Flip (horizontal, vertical)
• Exposure (EV compensation, shutter speed, manual gain)
• White balance (auto, daylight, tungsten, custom gains)
• Denoising, sharpness, and other rpicam-still options

See Camera Settings for all options.

Signal Discovery

Auto-detect new trigger signals:

bbl-shutter-cam debug --profile my-printer --duration 120 --update-config

Captures all BLE signals while you trigger the shutter or Bambu Studio app and saves them to config.

---

Tips & Best Practices

• BLE Connection Issues? Press the shutter button to wake the device
• Prevent Double Captures? Adjust min_interval_sec in camera config (default: 0.5s)
• Varying Enclosure Lighting? Lock exposure with manual shutter and gain settings
• Headless Setup? Use --log-file for debugging on remote systems
• Auto-Start on Boot? Optional Systemd Service helps ensure the tool is always listening

---

Contributing

Want to help? See CONTRIBUTING.md for:

• Development setup
• Code style & testing
• VSCode workspace configuration
• Submitting changes

Quick start for developers:

pip install -e ".[dev]"
python -m pytest tests/ -v          # Run tests
./scripts/build.sh                  # Build executable

---

License & Status

License: MIT (see LICENSE)

Status: Stable - v1.0.0 release

Roadmap: See ROADMAP.md for planned features:

• Hardware detection & interactive setup wizard (Stage TBD)
• Web streaming & Home Assistant integration - Live preview and remote monitoring (Stage 4, planned post-v1)
  • Optional /snapshot and /stream HTTP endpoints
  • Lightweight on Pi Zero 2W (MJPEG @ 640×480, 10-15 fps)
  • Home Assistant camera entity integration
  • Smartphone-friendly web UI
  • See Web Streaming Documentation for details
• Multi-machine CLI and config management (future)

---

GitHub

• Repository: https://github.com/bodybybuddha/bbl-shutter-cam
• Issues & Bugs: GitHub Issues

---

System Requirements

Component	Minimum	Recommended
Raspberry Pi	Pi 3B+	Pi Zero 2 W or Pi 5
OS	Bullseye	Bookworm (Lite)
Python	3.9	3.11+
Camera	libcamera compatible	Pi Camera Module 3
Bluetooth	Built-in/USB adapter	Built-in module

See Requirements for full details.