From e6b3b8ba4830b4898a335fed2bc038fa17be6313 Mon Sep 17 00:00:00 2001
From: Donkie <daniel.cf.hultgren@gmail.com>
Date: Mon, 26 Jun 2023 20:19:05 +0200
Subject: [PATCH] docs: Added section for spoolman

Signed-off-by: Daniel Hultgren <daniel.cf.hultgren@gmail.com>
---
 docs/changelog.md     |   2 +
 docs/configuration.md |  16 +++++
 docs/web_api.md       | 140 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 158 insertions(+)

diff --git a/docs/changelog.md b/docs/changelog.md
index 8c1d639..b9b6280 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -15,6 +15,8 @@ The format is based on [Keep a Changelog].
 - **metadata**: Added support for OrcaSlicer
 - **zeroconf**: Added support for a configurable mDNS hostname.
 - **zeroconf**: Added support for UPnP/SSDP Discovery.
+- **spoolman**: Added integration to the
+  [Spoolman](https://github.com/Donkie/Spoolman) filament manager.
 
 ### Fixed
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 7f36a2a..bec47f2 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -2609,6 +2609,22 @@ state_response_template:
   {set_result("energy", notification["aenergy"]["by_minute"][0]|float * 0.000001)}
 ```
 
+### `[spoolman]`
+
+Enables integration with the [Spoolman](https://github.com/Donkie/Spoolman)
+filament manager. Moonraker will automatically send filament usage updates to
+the Spoolman database.
+
+Front ends can also utilize this config to provide a built-in management tool.
+
+```ini
+# moonraker.conf
+
+[spoolman]
+server: http://192.168.0.123:7912
+#   URL to the Spoolman instance. This parameter must be provided.
+```
+
 ## Include directives
 
 It is possible to include configuration from other files via include
diff --git a/docs/web_api.md b/docs/web_api.md
index a69a86a..447c19e 100644
--- a/docs/web_api.md
+++ b/docs/web_api.md
@@ -5211,6 +5211,127 @@ An object containing all measurements for every configured sensor:
 }
 ```
 
+### Spoolman APIs
+The following APIs are available to interact with the Spoolman integration:
+
+#### Set active spool
+Set the ID of the spool that Moonraker should report usage to Spoolman of.
+
+HTTP request:
+```http
+POST /spoolman/spool_id
+Content-Type: application/json
+
+{
+    "spool_id": 1
+}
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "spoolman.post_spool_id",
+    "params": {
+        "spool_id": 1
+    },
+    "id": 4654
+}
+```
+
+Returns:
+
+The id of the now active spool:
+
+```json
+{
+    "spool_id": 1
+}
+```
+
+!!! note
+    Send an empty object, `{}`, to un-set the spool ID and stop any reporting.
+    The response `spool_id` will then be set to *null*
+
+#### Get active spool
+Retrieve the ID of the spool to which Moonraker reports usage for Spoolman.
+
+HTTP request:
+```http
+GET /spoolman/spool_id
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "spoolman.get_spool_id",
+    "id": 4654
+}
+```
+
+Returns:
+
+The id of the active spool:
+
+```json
+{
+    "spool_id": 1
+}
+```
+
+!!! note
+    The `spool_id` can be *null* if there is no active spool.
+
+#### Proxy
+
+Moonraker supplies a proxy endpoint where you have full access to the Spoolman
+API without having to configure the endpoint yourself.
+
+See Spoolman's [OpenAPI Description](https://donkie.github.io/Spoolman/) for
+detailed information about it's API.
+
+HTTP request:
+```http
+POST /spoolman/proxy
+Content-Type: application/json
+
+{
+    "request_method": "POST",
+    "path": "/v1/spool",
+    "query": "a=1&b=4",
+    "body": {
+        "filament_id": 1
+    }
+}
+```
+
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "spoolman.post_proxy",
+    "params": {
+        "request_method": "POST",
+        "path": "/v1/spool",
+        "query": "a=1&b=4",
+        "body": {
+            "filament_id": 1
+        }
+    },
+    "id": 4654
+}
+```
+
+The following parameters are available. `request_method` and `path` are required, the rest are optional.
+
+- `request_method`: The HTTP request method, e.g. `GET`, `POST`, `DELETE`, etc.
+- `path`: The endpoint, including API version, e.g. `/v1/filament`.
+- `query`: The query part of the URL, e.g. `filament_material=PLA&vendor_name=Prima`.
+- `body`: The request body for the request.
+
+Returns:
+
+The json response from the Spoolman server.
+
 ### OctoPrint API emulation
 Partial support of OctoPrint API is implemented with the purpose of
 allowing uploading of sliced prints to a moonraker instance.
@@ -6623,6 +6744,25 @@ webcam is added, removed, or updated.
 The `webcams` field contans an array of objects like those returned by the
 [list webcams](#list-webcams) API.
 
+#### Spoolman active spool ID changed
+
+Moonraker will emit the `notify_active_spool_set` event when the active spool
+ID for the Spoolman integration has been changed.
+
+See the [Spoolman API](#spoolman-apis) for more information.
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "notify_active_spool_set",
+    "params": [
+        {
+            "spool_id": 1
+        }
+    ]
+}
+```
+
 #### Agent Events
 Moonraker will emit the `notify_agent_event` notification when it
 an agent event is received.