Documentation

Configuration guides, integration setup, and API reference.

Configuration

Bambuddy can be configured through the web interface or by setting environment variables.

Environment Variables

Variable Description Default
HOST Server bind address 0.0.0.0
PORT Server port 8000
DATABASE_URL Database URL (SQLite default, or PostgreSQL) sqlite:///./bambuddy.db or postgresql+asyncpg://user:pass@host:5432/bambuddy
LOG_LEVEL Logging verbosity INFO
TIMEZONE Server timezone UTC
.env 
# Example .env file
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
TIMEZONE=America/New_York

Printer Setup

Add printers through the Bambuddy web interface. You'll need the following information for each printer:

Required Information

  • Printer IP address
  • Serial number
  • LAN access code
  • Printer model
Finding Printer Info: IP address and serial number can be found in your printer's network settings. The access code is displayed when you enable Developer Mode.

Notification Setup

Configure notifications to stay informed about print status, errors, and completions.

Telegram

1

Create a bot via @BotFather on Telegram

2

Copy the bot token provided by BotFather

3

Get your chat ID by messaging @userinfobot

4

Enter both values in Bambuddy's notification settings

Discord

1

In your Discord server, go to Server Settings > Integrations > Webhooks

2

Create a new webhook and copy the URL

3

Paste the webhook URL in Bambuddy's Discord notification settings

Other Services

Bambuddy also supports WhatsApp, Email, Pushover, ntfy, and Home Assistant. Configure these in the Settings > Notifications section of the web interface. Home Assistant sends persistent notifications to your HA dashboard — no extra config needed beyond the HA connection in Settings > Network.

Integrations

Spoolman

Spoolman is a filament inventory management system. Bambuddy can sync with Spoolman to track filament usage automatically, including per-filament usage reporting after each print.

configuration 
# In Bambuddy settings
Spoolman URL: http://your-spoolman-host:7912
Enable Sync: Yes
# Optional: Disable AMS weight sync to prefer Spoolman usage tracking
# Optional: Enable partial usage reporting for failed prints

Smart Plugs

Control your printer's power with smart plugs. Bambuddy supports four plug types:

  • Tasmota — Auto-discovered on your network
  • Home Assistant — Select entities from your HA instance
  • MQTT — Zigbee2MQTT, Shelly, or any MQTT-enabled device
  • REST/Webhook — Any device with an HTTP API (openHAB, ioBroker, FHEM, Node-RED, etc.)

All plug types support automatic power-on before scheduled prints, safe shutdown after cooldown, remote power control from the dashboard, and energy monitoring.

configuration 
# Per-printer Tasmota settings
Tasmota IP: 192.168.1.xxx
Cooldown Delay: 300  # seconds to wait after print

# REST/Webhook example (openHAB)
ON URL:  POST http://openhab:8080/rest/items/Printer_Power
ON Body: ON
OFF URL: POST http://openhab:8080/rest/items/Printer_Power
OFF Body: OFF
Headers: {"Content-Type": "text/plain"}

Bambu Cloud (Optional)

While Bambuddy is designed for local-only operation, you can optionally sync profiles from Bambu Cloud for convenience. This is entirely optional and can be disabled.

API Reference

Bambuddy exposes a REST API for integration with other tools and automation.

Interactive Docs: Access the full API documentation at http://your-bambuddy-host:8000/docs (Swagger UI) or /redoc (ReDoc).

Key Endpoints

Endpoint Method Description
/api/printers GET List all printers and their status
/api/printers/{id} GET Get specific printer details
/api/prints GET List archived prints
/api/prints/{id}/reprint POST Send print to a printer
/api/queue GET View print queue
/api/stats GET Get printing statistics

WebSocket Events

Real-time updates are available via WebSocket at /ws.

javascript 
const ws = new WebSocket('ws://localhost:8000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Printer update:', data);
};

// Event types: printer_status, print_progress,
// print_complete, print_error, hms_error

Development

Want to contribute or customize Bambuddy? Here's how to set up a development environment.

Development Setup

bash 
# Clone the repository
git clone https://github.com/maziggy/bambuddy.git
cd bambuddy

# Backend setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run backend with hot reload
uvicorn backend.app.main:app --reload

# Frontend setup (separate terminal)
cd frontend
npm install
npm run dev

Project Structure

text 
bambuddy/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI application
│   │   ├── models/          # SQLAlchemy models
│   │   ├── routers/         # API endpoints
│   │   ├── services/        # Business logic
│   │   └── utils/           # Helper functions
│   └── tests/
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── pages/           # Page components
│   │   ├── hooks/           # Custom hooks
│   │   └── utils/           # Utilities
│   └── public/
└── docs/

Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.