# Plugin: Moonraker

The **Moonraker integration** consists of two components that together enable full Klipper/Moonraker printer connectivity with FilaMan:

1. **FilaMan Moonraker Driver Plugin** – installed in FilaMan, provides the printer driver
2. **FilaMan Moonraker Component** – manually installed in Moonraker, runs on the printer server (e.g. Raspberry Pi); handles extrusion tracking and consumption reporting

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

---

## Overview

| Property | Value |
|----------|-------|
| **Plugin Type** | Driver (Printer Driver) |
| **Author** | FilaMan |
| **Source** | [Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) (Registry) |
| **Connection** | HTTP over local network |
| **Capabilities** | Spool assignment, extrusion tracking, automatic consumption reporting |

---

## Part 1: FilaMan Moonraker Driver Plugin

The driver plugin is installed in FilaMan and enables communication with the Moonraker server. It forwards spool assignments from FilaMan to the Moonraker endpoint `/server/filaman/spool_id`.

### Configuration

When adding or editing a Moonraker printer, the following configuration fields are available:

| Field | Required | Description |
|-------|----------|-------------|
| **Moonraker URL** | Yes | Address of the Moonraker server (e.g. `http://192.168.1.20:7125`) |
| **API Key** | No | Moonraker API key, if configured in Moonraker |
| **Mode** | No | Operating mode: `toolhead_only` (default) or `tray_macros` |
| **Request Timeout (s)** | No | Timeout in seconds for HTTP requests (default: 10) |
| **Slot Count** | No | Number of manual slots (only for manual configuration) |
| **Slot Targets** | No | Manual slot configuration (overrides auto-discovery) |

Example configuration (JSON):

```json
{
  "moonraker_url": "http://192.168.1.20:7125",
  "api_key": "",
  "mode": "toolhead_only",
  "request_timeout_seconds": 10,
  "slot_count": 1,
  "slot_targets": [
    {
      "slot_index": "0-0",
      "slot_name": "Toolhead 1",
      "slot_kind": "toolhead",
      "assign_gcode": "SET_TRAY_SPOOL TRAY=1 SPOOL={spool_id}"
    }
  ]
}
```

### Modes

| Mode | Behavior |
|------|----------|
| `toolhead_only` (default) | Spool assignment only sets the active spool in Moonraker. Slots are automatically discovered from Moonraker (toolheads and available trays). |
| `tray_macros` | Spool assignment sets the active spool in Moonraker **and** additionally executes the `assign_gcode` of the matching slot. |

### Slot Discovery (Auto-Detection)

The plugin automatically detects available slots from the Moonraker printer objects:

- **Toolhead slots** are discovered from printer objects (`extruder`, `extruder1`, ...)
- **Tray slots** (AFC/MMU) are only shown when Moonraker reports corresponding AFC or MMU objects
- If no tray objects are present, only toolhead slots are displayed
- Manually specifying `slot_targets` in the configuration overrides auto-discovery

### Placeholders for `assign_gcode`

In `tray_macros` mode, the `assign_gcode` field supports the following placeholders:

| Placeholder | Description |
|-------------|-------------|
| `{spool_id}` | FilaMan spool ID |
| `{slot_index}` | Slot index (e.g. `0-0`) |
| `{ams_id}` | AMS/tray unit |
| `{tray_id}` | Tray slot number |
| `{material_type}` | Material type (e.g. `PLA`) |
| `{color}` | Spool color (hex) |

---

## Part 2: FilaMan Moonraker Component (Manual Installation)

The Moonraker component is a native Moonraker extension that runs on the same server as Moonraker (usually a Raspberry Pi). It handles:

- **Consumption tracking** – measuring extrusion length from Klipper toolhead updates
- **Weight calculation** – converting length (mm) to weight (g) using filament metadata
- **Consumption reporting** – automatically reporting usage to FilaMan (`/api/v1/spools/{id}/consumptions`)
- **Spool tracking** – managing the active spool via Moonraker endpoint and remote method

> **Note:** The Moonraker component is **optional** but recommended. Without it, FilaMan cannot perform automatic consumption tracking for Klipper printers.

### Prerequisites

- Moonraker and Klipper are installed and running
- FilaMan is reachable on the local network
- SSH access to the printer server (e.g. Raspberry Pi)

### Installation

**Step 1: Download the component file**

Connect to the printer server via SSH and download the `filaman.py` file into the Moonraker components directory:

```bash
cd ~/moonraker/moonraker/components
wget https://github.com/Fire-Devils/FilaMan-Moonraker-Komponente/raw/main/filaman.py
```

Alternatively, download the file manually and transfer it via SFTP/SCP.

**Step 2: Update the Moonraker configuration**

Open `moonraker.conf` (typically located at `~/printer_data/config/moonraker.conf` or `~/klipper_config/moonraker.conf`) and add the following section:

```ini
[filaman]
server: http://192.168.1.50:8000
api_key: uak.123.xxxxxxxxxxxxxxxxxxxxx
sync_rate: 5
default_density_g_cm3: 1.24
default_diameter_mm: 1.75
```

Replace `http://192.168.1.50:8000` with the actual URL of your FilaMan instance.

**Step 3: Restart Moonraker**

```bash
sudo systemctl restart moonraker
```

Then check the Moonraker logs for errors:

```bash
journalctl -u moonraker -n 50
```

### Configuration Options

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `server` | Yes | – | Base URL of the FilaMan instance |
| `api_key` | Recommended | – | FilaMan API key (`uak.<id>.<secret>`) |
| `sync_rate` | No | `5` | Reporting interval in seconds |
| `default_density_g_cm3` | No | `1.24` | Fallback density for weight calculation (g/cm³) |
| `default_diameter_mm` | No | `1.75` | Fallback filament diameter in mm |

### HTTP Endpoints

After installation, the component exposes the following endpoints:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` / `POST` | `/server/filaman/spool_id` | Get or set the active spool |
| `GET` | `/server/filaman/status` | Connection and sync status |
| `POST` | `/server/filaman/proxy` | Forward proxy requests to FilaMan |

Additionally, Spoolman-compatible aliases are always active:

| Method | Endpoint |
|--------|----------|
| `GET` / `POST` | `/server/spoolman/spool_id` |
| `GET` | `/server/spoolman/status` |
| `POST` | `/server/spoolman/proxy` |

### Remote Methods (GCode Macros)

The component registers the following remote methods that can be called from Klipper macros:

- `filaman_set_active_spool`
- `spoolman_set_active_spool` (Spoolman-compatible alias)

### Setting Up GCode Macros

Add these macros to your `printer.cfg` or an included configuration file to control the active spool via GCode:

```ini
[gcode_macro SET_ACTIVE_SPOOL]
gcode:
  {% if params.ID %}
    {% set id = params.ID|int %}
    {action_call_remote_method("filaman_set_active_spool", spool_id=id)}
  {% else %}
    {action_respond_info("Parameter 'ID' is required")}
  {% endif %}

[gcode_macro CLEAR_ACTIVE_SPOOL]
gcode:
  {action_call_remote_method("filaman_set_active_spool", spool_id=None)}
```

You can then set the active spool in your print start macro or manually via the console:

```
SET_ACTIVE_SPOOL ID=42
CLEAR_ACTIVE_SPOOL
```

---

## How Both Components Work Together

```
FilaMan              Moonraker Server (Pi)
─────────            ─────────────────────
Driver Plugin  ←──►  Moonraker Component
  │                    │
  │  POST spool_id     │  Extrusion data
  │  (assignment)      │  (consumption report)
  └──────────────────► └──────────────────► FilaMan API
```

- The **Driver Plugin** sends spool assignments from FilaMan to Moonraker
- The **Moonraker Component** tracks extrusion progress and reports consumption directly back to FilaMan

> **Tip:** Both components work independently. You can use the Driver Plugin without the Moonraker Component (assignment only, no consumption tracking), or vice versa.

---

← [Back: FilaManDB Community Database](/Docs/En/18-Filamandb) | [Next: Installation on Raspberry Pi →](/Docs/En/20-Installation-Raspberry-Pi)