Home A - Z
Page Index

Blame

d23adc Manuel Weiser 2026-05-30 06:38:15
docs: Add Moonraker plugin documentation and update table of contents
1 
# Plugin: Moonraker
2
3
The **Moonraker integration** consists of two components that together enable full Klipper/Moonraker printer connectivity with FilaMan:
4
5
1. **FilaMan Moonraker Driver Plugin** – installed in FilaMan, provides the printer driver
6
2. **FilaMan Moonraker Component** – manually installed in Moonraker, runs on the printer server (e.g. Raspberry Pi); handles extrusion tracking and consumption reporting
7
8
**Installing the Driver Plugin:** → [Admin: Plugin Management](/Docs/En/11-Admin#115-system-plugin-management)
9
10
---
11
12
## Overview
13
14
| Property | Value |
15
|----------|-------|
16
| **Plugin Type** | Driver (Printer Driver) |
17
| **Author** | FilaMan |
18
| **Source** | [Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) (Registry) |
19
| **Connection** | HTTP over local network |
20
| **Capabilities** | Spool assignment, extrusion tracking, automatic consumption reporting |
21
22
---
23
24
## Part 1: FilaMan Moonraker Driver Plugin
25
26
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`.
27
28
### Configuration
29
30
When adding or editing a Moonraker printer, the following configuration fields are available:
31
32
| Field | Required | Description |
33
|-------|----------|-------------|
34
| **Moonraker URL** | Yes | Address of the Moonraker server (e.g. `http://192.168.1.20:7125`) |
35
| **API Key** | No | Moonraker API key, if configured in Moonraker |
36
| **Mode** | No | Operating mode: `toolhead_only` (default) or `tray_macros` |
37
| **Request Timeout (s)** | No | Timeout in seconds for HTTP requests (default: 10) |
38
| **Slot Count** | No | Number of manual slots (only for manual configuration) |
39
| **Slot Targets** | No | Manual slot configuration (overrides auto-discovery) |
40
41
Example configuration (JSON):
42
43
```json
44
{
45
"moonraker_url": "http://192.168.1.20:7125",
46
"api_key": "",
47
"mode": "toolhead_only",
48
"request_timeout_seconds": 10,
49
"slot_count": 1,
50
"slot_targets": [
51
{
52
"slot_index": "0-0",
53
"slot_name": "Toolhead 1",
54
"slot_kind": "toolhead",
55
"assign_gcode": "SET_TRAY_SPOOL TRAY=1 SPOOL={spool_id}"
56
}
57
]
58
}
59
```
60
61
### Modes
62
63
| Mode | Behavior |
64
|------|----------|
65
| `toolhead_only` (default) | Spool assignment only sets the active spool in Moonraker. Slots are automatically discovered from Moonraker (toolheads and available trays). |
66
| `tray_macros` | Spool assignment sets the active spool in Moonraker **and** additionally executes the `assign_gcode` of the matching slot. |
67
68
### Slot Discovery (Auto-Detection)
69
70
The plugin automatically detects available slots from the Moonraker printer objects:
71
72
- **Toolhead slots** are discovered from printer objects (`extruder`, `extruder1`, ...)
73
- **Tray slots** (AFC/MMU) are only shown when Moonraker reports corresponding AFC or MMU objects
74
- If no tray objects are present, only toolhead slots are displayed
75
- Manually specifying `slot_targets` in the configuration overrides auto-discovery
76
77
### Placeholders for `assign_gcode`
78
79
In `tray_macros` mode, the `assign_gcode` field supports the following placeholders:
80
81
| Placeholder | Description |
82
|-------------|-------------|
83
| `{spool_id}` | FilaMan spool ID |
84
| `{slot_index}` | Slot index (e.g. `0-0`) |
85
| `{ams_id}` | AMS/tray unit |
86
| `{tray_id}` | Tray slot number |
87
| `{material_type}` | Material type (e.g. `PLA`) |
88
| `{color}` | Spool color (hex) |
89
90
---
91
92
## Part 2: FilaMan Moonraker Component (Manual Installation)
93
94
The Moonraker component is a native Moonraker extension that runs on the same server as Moonraker (usually a Raspberry Pi). It handles:
95
96
- **Consumption tracking** – measuring extrusion length from Klipper toolhead updates
97
- **Weight calculation** – converting length (mm) to weight (g) using filament metadata
98
- **Consumption reporting** – automatically reporting usage to FilaMan (`/api/v1/spools/{id}/consumptions`)
99
- **Spool tracking** – managing the active spool via Moonraker endpoint and remote method
100
101
> **Note:** The Moonraker component is **optional** but recommended. Without it, FilaMan cannot perform automatic consumption tracking for Klipper printers.
102
103
### Prerequisites
104
105
- Moonraker and Klipper are installed and running
106
- FilaMan is reachable on the local network
107
- SSH access to the printer server (e.g. Raspberry Pi)
108
109
### Installation
110
111
**Step 1: Download the component file**
112
113
Connect to the printer server via SSH and download the `filaman.py` file into the Moonraker components directory:
114
115
```bash
116
cd ~/moonraker/moonraker/components
117
wget https://github.com/Fire-Devils/FilaMan-Moonraker-Komponente/raw/main/filaman.py
118
```
119
120
Alternatively, download the file manually and transfer it via SFTP/SCP.
121
122
**Step 2: Update the Moonraker configuration**
123
124
Open `moonraker.conf` (typically located at `~/printer_data/config/moonraker.conf` or `~/klipper_config/moonraker.conf`) and add the following section:
125
126
```ini
127
[filaman]
128
server: http://192.168.1.50:8000
129
api_key: uak.123.xxxxxxxxxxxxxxxxxxxxx
130
sync_rate: 5
131
default_density_g_cm3: 1.24
132
default_diameter_mm: 1.75
133
```
134
135
Replace `http://192.168.1.50:8000` with the actual URL of your FilaMan instance.
136
137
**Step 3: Restart Moonraker**
138
139
```bash
140
sudo systemctl restart moonraker
141
```
142
143
Then check the Moonraker logs for errors:
144
145
```bash
146
journalctl -u moonraker -n 50
147
```
148
149
### Configuration Options
150
151
| Option | Required | Default | Description |
152
|--------|----------|---------|-------------|
153
| `server` | Yes | – | Base URL of the FilaMan instance |
154
| `api_key` | Recommended | – | FilaMan API key (`uak.<id>.<secret>`) |
155
| `sync_rate` | No | `5` | Reporting interval in seconds |
156
| `default_density_g_cm3` | No | `1.24` | Fallback density for weight calculation (g/cm³) |
157
| `default_diameter_mm` | No | `1.75` | Fallback filament diameter in mm |
158
159
### HTTP Endpoints
160
161
After installation, the component exposes the following endpoints:
162
163
| Method | Endpoint | Description |
164
|--------|----------|-------------|
165
| `GET` / `POST` | `/server/filaman/spool_id` | Get or set the active spool |
166
| `GET` | `/server/filaman/status` | Connection and sync status |
167
| `POST` | `/server/filaman/proxy` | Forward proxy requests to FilaMan |
168
169
Additionally, Spoolman-compatible aliases are always active:
170
171
| Method | Endpoint |
172
|--------|----------|
173
| `GET` / `POST` | `/server/spoolman/spool_id` |
174
| `GET` | `/server/spoolman/status` |
175
| `POST` | `/server/spoolman/proxy` |
176
177
### Remote Methods (GCode Macros)
178
179
The component registers the following remote methods that can be called from Klipper macros:
180
181
- `filaman_set_active_spool`
182
- `spoolman_set_active_spool` (Spoolman-compatible alias)
183
184
### Setting Up GCode Macros
185
186
Add these macros to your `printer.cfg` or an included configuration file to control the active spool via GCode:
187
188
```ini
189
[gcode_macro SET_ACTIVE_SPOOL]
190
gcode:
191
{% if params.ID %}
192
{% set id = params.ID|int %}
193
{action_call_remote_method("filaman_set_active_spool", spool_id=id)}
194
{% else %}
195
{action_respond_info("Parameter 'ID' is required")}
196
{% endif %}
197
198
[gcode_macro CLEAR_ACTIVE_SPOOL]
199
gcode:
200
{action_call_remote_method("filaman_set_active_spool", spool_id=None)}
201
```
202
203
You can then set the active spool in your print start macro or manually via the console:
204
205
```
206
SET_ACTIVE_SPOOL ID=42
207
CLEAR_ACTIVE_SPOOL
208
```
209
210
---
211
212
## How Both Components Work Together
213
214
```
215
FilaMan Moonraker Server (Pi)
216
───────── ─────────────────────
217
Driver Plugin ←──► Moonraker Component
218
│ │
219
│ POST spool_id │ Extrusion data
220
│ (assignment) │ (consumption report)
221
└──────────────────► └──────────────────► FilaMan API
222
```
223
224
- The **Driver Plugin** sends spool assignments from FilaMan to Moonraker
225
- The **Moonraker Component** tracks extrusion progress and reports consumption directly back to FilaMan
226
227
> **Tip:** Both components work independently. You can use the Driver Plugin without the Moonraker Component (assignment only, no consumption tracking), or vice versa.
228
229
---
230
231
← [Back: FilaManDB Community Database](/Docs/En/18-Filamandb) | [Next: Installation on Raspberry Pi →](/Docs/En/20-Installation-Raspberry-Pi)