[GH-ISSUE #1220] [Feature]: Assign last scanned NFC spool to the next AMS slot that becomes occupied #886

New issue

Open

opened 2026-05-07 00:14:43 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-07 00:14:43 +02:00

Owner

Originally created by @MiguelAngelLV on GitHub (May 6, 2026).
Original GitHub issue: https://github.com/maziggy/bambuddy/issues/1220

Problem or Use Case

Summary

Add an API endpoint that accepts an NFC tag scan (tag UID / tray UUID) and automatically assigns the corresponding inventory spool to the next AMS slot that transitions from empty to occupied, for a specified printer. This enables a “scan → insert spool → auto-configure that slot” workflow.

Problem / Motivation

Today, the SpoolBuddy NFC flow (POST /nfc/tag-scanned) only detects/matches a spool and broadcasts websocket events for the UI, but it does not perform any automatic assignment to an AMS slot. Assignment is manual via the UI (select AMS + tray).

For kiosk/production setups, the desired workflow is:

Scan NFC tag on a spool
Physically place spool into any free AMS slot
Bambuddy automatically assigns/configures that slot with the scanned spool’s inventory data

This should work regardless of what the printer reports in that slot’s filament metadata, and should rely on the physical slot transition (empty → occupied).

Proposed Solution

Proposed API

Add a dedicated endpoint, e.g.:

POST /spoolbuddy/nfc/assign-next-slot
(or under existing SpoolBuddy routes: POST /nfc/assign-next-slot)

Request (example)

{
  "device_id": "spoolbuddy-01",
  "printer_id": 3,
  "tag_uid": "04AABBCCDD11",
  "tray_uuid": "xxxx-optional-if-available",
  "timeout_seconds": 30
}

Response (example)

{
  "status": "ok",
  "matched": true,
  "spool_id": 123,
  "printer_id": 3,
  "assigned": true,
  "ams_id": 0,
  "tray_id": 2
}

Expected Behavior

When this endpoint is called:

Match the spool from inventory using the provided NFC data (same matching rules as current tag-scanned flow: tray_uuid preferred, fallback to tag_uid matching).
Store a pending “assignment intent” for that printer (and optionally for that device_id):
- “The next AMS slot that changes from empty → occupied should be assigned to spool_id.”
Listen for AMS updates for that specific printer (the same AMS change events already processed via MQTT).
When any AMS slot transitions:
- from empty (no tray_type / no spool present)
- to occupied (tray_type present / spool inserted)
then assign that slot to the pending spool:
- Create/update the SpoolAssignment for (printer_id, ams_id, tray_id) with the matched spool
- Perform the same “manual assignment” configuration behavior as the existing assignment route (ideally reuse the same code path used by POST /inventory/assignments so it sets filament settings consistently)
Once assigned, clear the pending intent and return success (or if the endpoint is asynchronous, broadcast a websocket event).

Important Requirements / Notes

Printer scoping: the request should accept printer_id (preferably required) to avoid ambiguity in multi-printer setups.
Independence from reported spool metadata: the match is from the NFC tag. The chosen slot is purely based on “empty → occupied” transition, not based on what the printer claims the spool is.
Timeout: if no slot transition happens within timeout_seconds, return an error like 409 Conflict / 408 Request Timeout / 202 Accepted depending on implementation choice.
Idempotency / concurrency:
- If there is already a pending intent for that printer, decide policy:
  - Reject with 409 (“pending assignment already exists”), or
  - Replace/update the pending intent (“latest scan wins”)
Security: endpoint should require the same auth as existing SpoolBuddy endpoints (token/API key).

Suggested WebSocket Events (optional but helpful)

spoolbuddy_pending_assignment_created (printer_id, spool_id, expires_at)
spoolbuddy_pending_assignment_timeout
spoolbuddy_pending_assignment_completed (printer_id, ams_id, tray_id, spool_id)

Acceptance Criteria

Calling the endpoint with a known tag, then inserting a spool into an empty AMS slot within the timeout:
- Automatically creates/updates the SpoolAssignment for that slot
- Configures the slot with the inventory spool’s settings (equivalent to manual assignment)
- Emits a completion event and/or returns assigned slot info
If no slot changes to occupied before timeout:
- Pending assignment is cleared
- API returns a clear timeout/failed response
Works correctly when multiple AMS units exist (ams_id) and multiple trays (tray_id).
Works in multi-printer setups without cross-assigning.

Why this is valuable

This feature enables a “hands-free” workflow for workshops/farms: operators can scan a spool and insert it into AMS without touching the UI, reducing errors and speeding up spool changes.

Alternatives Considered

No response

Feature Category

API

Priority

Would improve my workflow

Mockups or Examples

No response

Contribution

I would be willing to help implement this feature

Checklist

I have searched existing issues to ensure this feature hasn't already been requested

Originally created by @MiguelAngelLV on GitHub (May 6, 2026). Original GitHub issue: https://github.com/maziggy/bambuddy/issues/1220 ### Problem or Use Case ### Summary Add an API endpoint that accepts an NFC tag scan (tag UID / tray UUID) and automatically assigns the corresponding inventory spool to the **next AMS slot that transitions from empty to occupied**, for a specified printer. This enables a “scan → insert spool → auto-configure that slot” workflow. ### Problem / Motivation Today, the SpoolBuddy NFC flow (`POST /nfc/tag-scanned`) only detects/matches a spool and broadcasts websocket events for the UI, but it does **not** perform any automatic assignment to an AMS slot. Assignment is manual via the UI (select AMS + tray). For kiosk/production setups, the desired workflow is: 1. Scan NFC tag on a spool 2. Physically place spool into any free AMS slot 3. Bambuddy automatically assigns/configures that slot with the scanned spool’s inventory data This should work **regardless of what the printer reports in that slot’s filament metadata**, and should rely on the physical slot transition (empty → occupied). ### Proposed Solution ### Proposed API Add a dedicated endpoint, e.g.: `POST /spoolbuddy/nfc/assign-next-slot` (or under existing SpoolBuddy routes: `POST /nfc/assign-next-slot`) **Request (example)** ```json { "device_id": "spoolbuddy-01", "printer_id": 3, "tag_uid": "04AABBCCDD11", "tray_uuid": "xxxx-optional-if-available", "timeout_seconds": 30 } ``` **Response (example)** ```json { "status": "ok", "matched": true, "spool_id": 123, "printer_id": 3, "assigned": true, "ams_id": 0, "tray_id": 2 } ``` ### Expected Behavior When this endpoint is called: 1. **Match the spool** from inventory using the provided NFC data (same matching rules as current tag-scanned flow: tray_uuid preferred, fallback to tag_uid matching). 2. Store a **pending “assignment intent”** for that printer (and optionally for that device_id): - “The next AMS slot that changes from empty → occupied should be assigned to `spool_id`.” 3. Listen for AMS updates for that specific printer (the same AMS change events already processed via MQTT). 4. When any AMS slot transitions: - from `empty` (no tray_type / no spool present) - to `occupied` (tray_type present / spool inserted) then **assign that slot** to the pending spool: - Create/update the `SpoolAssignment` for `(printer_id, ams_id, tray_id)` with the matched spool - Perform the same “manual assignment” configuration behavior as the existing assignment route (ideally reuse the same code path used by `POST /inventory/assignments` so it sets filament settings consistently) 5. Once assigned, clear the pending intent and return success (or if the endpoint is asynchronous, broadcast a websocket event). ### Important Requirements / Notes - **Printer scoping**: the request should accept `printer_id` (preferably required) to avoid ambiguity in multi-printer setups. - **Independence from reported spool metadata**: the match is from the NFC tag. The chosen slot is purely based on “empty → occupied” transition, not based on what the printer claims the spool is. - **Timeout**: if no slot transition happens within `timeout_seconds`, return an error like `409 Conflict` / `408 Request Timeout` / `202 Accepted` depending on implementation choice. - **Idempotency / concurrency**: - If there is already a pending intent for that printer, decide policy: - Reject with 409 (“pending assignment already exists”), or - Replace/update the pending intent (“latest scan wins”) - **Security**: endpoint should require the same auth as existing SpoolBuddy endpoints (token/API key). ### Suggested WebSocket Events (optional but helpful) - `spoolbuddy_pending_assignment_created` (printer_id, spool_id, expires_at) - `spoolbuddy_pending_assignment_timeout` - `spoolbuddy_pending_assignment_completed` (printer_id, ams_id, tray_id, spool_id) ### Acceptance Criteria - Calling the endpoint with a known tag, then inserting a spool into an empty AMS slot within the timeout: - Automatically creates/updates the `SpoolAssignment` for that slot - Configures the slot with the inventory spool’s settings (equivalent to manual assignment) - Emits a completion event and/or returns assigned slot info - If no slot changes to occupied before timeout: - Pending assignment is cleared - API returns a clear timeout/failed response - Works correctly when multiple AMS units exist (ams_id) and multiple trays (tray_id). - Works in multi-printer setups without cross-assigning. ### Why this is valuable This feature enables a “hands-free” workflow for workshops/farms: operators can scan a spool and insert it into AMS without touching the UI, reducing errors and speeding up spool changes. ### Alternatives Considered _No response_ ### Feature Category API ### Priority Would improve my workflow ### Mockups or Examples _No response_ ### Contribution - [x] I would be willing to help implement this feature ### Checklist - [x] I have searched existing issues to ensure this feature hasn't already been requested