# Plugin: Bambuddy

The **Bambuddy Plugin** is a Driver plugin that connects FilaMan with [Bambuddy](https://github.com/your-org/bambuddy) — an alternative management interface for BambuLab printers. It synchronizes the FilaMan spool inventory bidirectionally with the Bambuddy inventory and automatically reports filament consumption after each print.

**Installation:** → [Admin: Plugin Management](/Docs/En/11-Admin#115-system-plugin-management)

---

## Overview

| Property | Value |
|----------|-------|
| **Plugin Type** | Driver (Printer Driver) |
| **Author** | FilaMan |
| **Connection** | HTTP REST API + WebSocket |
| **Capabilities** | Inventory sync, AMS slot display, consumption reporting, online/offline detection |

---

## Prerequisites

- A running **Bambuddy server** accessible over the network
- A valid **API key** from the Bambuddy settings
- The **Printer ID** of the Bambu printer in Bambuddy (found in the Bambuddy web interface)

---

## Configuration

When adding or editing a Bambuddy printer, the plugin shows the following configuration fields:

| Field | Required | Description |
|-------|----------|-------------|
| **Bambuddy URL** | Yes | Full URL of the Bambuddy server (e.g. `http://192.168.1.100:8080`) |
| **API Key** | Yes | API key from the Bambuddy settings (Bambuddy → Settings → API) |
| **Printer ID** | Yes | Printer ID in Bambuddy (numeric, visible in the Bambuddy printer overview) |
| **Sync Interval** | No | Interval in seconds for automatic inventory sync (default: 300 = 5 minutes) |
| **Reconnect Interval** | No | Wait time in seconds before reconnecting after a connection loss (default: 30) |

---

## How Does Synchronization Work?

The plugin keeps the **Bambuddy inventory** up to date automatically — FilaMan is the single source of truth.

### When Is a Sync Triggered?

| Trigger | Behavior |
|---------|----------|
| **On plugin start** | Full inventory sync of all active FilaMan spools |
| **Periodically** | Automatically every `Sync Interval` seconds (default: every 5 minutes) |
| **On FilaMan changes** | Immediate sync within 3 seconds of any data change (spool created, weight updated, filament changed, etc.) |

### How Are Spools Linked?

Every spool created in Bambuddy receives the value `filaman:{id}` (e.g. `filaman:42`) in its **"Note"** field. This key is the unique link between a FilaMan spool and a Bambuddy inventory entry. When the same FilaMan spool is synced again, the plugin updates the existing Bambuddy entry instead of creating a new one.

---

## What Gets Synchronized?

On every sync, the plugin transfers the following information from FilaMan to Bambuddy:

| FilaMan Field | Bambuddy Field | Description |
|---|---|---|
| `filament.material_type` | Material | Material type (PLA, PETG, ABS …) |
| `filament.manufacturer.name` | Brand | Manufacturer |
| `filament.colors[0].hex_code` | Color (RGBA) | Primary color of the spool |
| `initial_total_weight_g` | Label weight | Original total weight |
| `initial – remaining` | Weight used | Filament already consumed |
| `rfid_uid` | RFID tag | Transferred if present |
| `bambu_nozzle_temp_min/max` | Nozzle temperatures | From printer parameters |

---

## Consumption Reporting After Printing

The plugin maintains a **WebSocket connection** to the Bambuddy server. When a print job completes, Bambuddy sends a `print_complete` event containing filament consumption per AMS slot. The plugin automatically deducts this consumption from the corresponding FilaMan spool — no manual input required.

> **Prerequisite:** The spool must be assigned to an AMS slot before the print (see [AMS Slot Assignment](#ams-slot-display-and-assignment)).

---

## AMS Slot Display and Assignment

After a successful connection, FilaMan shows all AMS slots and their current contents on the **printer page** and the **spool detail page**. The display updates in **real time** via WebSocket.

### Online/Offline Status

If the Bambu printer is **unreachable** (reported as offline by Bambuddy), **no trays** are shown for this printer on the spool detail page. As soon as the printer comes back online, the slots appear automatically.

### Assigning a Spool to a Slot

On the **spool detail page**, you can assign a spool directly to an AMS slot in Bambuddy:

1. Click on a slot dot in the printer slot overview
2. Select **"Assign spool to this slot"** from the context menu
3. Bambuddy assigns the spool to the slot and automatically configures material, color, and temperatures

---

## Sync Actions

Two manual sync actions are available on the **printer detail page**:

| Action | Description |
|--------|-------------|
| **Sync Now** | Triggers an immediate inventory sync (FilaMan → Bambuddy) |
| **Full Resync** | Deletes **all** Bambuddy inventory spools and re-syncs the entire FilaMan stock from scratch. Useful when the Bambuddy inventory has become inconsistent due to external changes. ⚠️ Do not run during active print jobs. |

---

← [Back: Plugin: Spoolman API](/Docs/En/16-Plugin-Spoolmanapi)