Lab8DATAPROCESSOR/context.md

Project Context

This file captures the current integration state without storing API tokens, passwords, or private credentials.

Repository

• Remote repository: https://git.tcom.space/tcom/Lab8DATAPROCESSOR.git
• Server checkout path: C:\Users\tcom\Lab8DATAPROCESSOR
• Service container: bambuddy-inventree-sync
• Host port: 8088
• Container port: 8080

Systems

• Bambuddy API base: http://192.168.1.5:8000/api/v1
• InvenTree base: http://192.168.0.3:1337
• Real API keys and tokens are stored only in .env, which is ignored by git.

Printed Parts Sync

Printed parts sync is already implemented and tested.

• Bambuddy successful Archives create/reuse InvenTree Part records.
• Each successful archive creates one InvenTree StockItem.
• Duplicate protection uses SQLite and StockItem.batch = bambuddy-<archive_id>.
• Printed parts category: 3D_PRINT/BAMBUDY, ID 26.
• Printed parts stock location: PRODUCTION/PRINTED-PART, ID 98.
• Part parameters synced:
  • Weight
  • PrintTime
• Bambuddy archive thumbnails sync to InvenTree Part.image.
• Bambuddy archive external link points to the InvenTree Part page.
• Failed, stopped, running, or still-printing archives are skipped when SYNC_SUCCESS_ONLY=true.

Filament Tracking

InvenTree is the source of truth for spool identity, spool location, and remaining stock.

Core rule:

InvenTree StockItem.batch == Bambuddy Spool.tag_uid

Configured InvenTree IDs:

Purpose	ID
Filament part category	19
Filament storage root	85
Loaded-in-printers root	72
B1 stock location	93
B2 stock location	94
B3 stock location	95
B4 stock location	96

Current Bambuddy printer IDs discovered from API:

Printer	Bambuddy printer ID
B1	5
B2	2
B3	3
B4	4

Printer IDs are auto-detected from Bambuddy printer names unless FILAMENT_PRINTER_ID_MAP is set.

Current Filament State

As of the last tested state:

• InvenTree filament stock items: 28
• Bambuddy spools: 28
• Matched batch codes: 28
• Bambuddy assignments: 3
• Assigned batches:
  • B1 tray 0: batch 1010
  • B1 tray 1: batch 1060
  • B1 tray 2: batch 1061
• B2 and B3 assignments were removed after their spools were moved back to InvenTree Filament_Storage.
• stale_assignments was empty after cleanup.
• Bambuddy usage records were still 0 at the last check.

Filament Behavior

When a stock item is moved in InvenTree:

• Move a spool into location 93, 94, 95, or 96: the service creates a Bambuddy assignment for B1, B2, B3, or B4.
• Move a spool from a printer location back to storage: the service removes the matching Bambuddy assignment.
• If Bambuddy has an assignment that does not match InvenTree printer locations, it appears in stale_assignments and /sync/filament/assignments?dry_run=true shows it in would_delete.
• FILAMENT_UNASSIGN_MISSING_ASSIGNMENTS=true enables this cleanup.
• FILAMENT_RETURN_UNASSIGNED_TO_STORAGE=false is intentionally kept off; InvenTree location changes are the source of truth.

The service does not infer physical spool presence from the Bambuddy dashboard. The dashboard can show generic filament loaded by the printer firmware. The integration uses InvenTree location and Bambuddy API assignments.

Key Endpoints

Health and validation:

curl.exe http://localhost:8088/health
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/validate

Status:

curl.exe -H "X-Service-Token: change-me" http://localhost:8088/sync/status
curl.exe -H "X-Service-Token: change-me" http://localhost:8088/filament/status

Archive sync:

curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/backfill?max_archives=1"
curl.exe -X POST -H "X-Service-Token: change-me" http://localhost:8088/sync/backfill
curl.exe -X POST -H "X-Service-Token: change-me" http://localhost:8088/sync/archive/ARCHIVE_ID

Filament sync:

curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/spools?dry_run=true"
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/assignments?dry_run=true"
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/locations?dry_run=true"
curl.exe -X POST -H "X-Service-Token: change-me" "http://localhost:8088/sync/filament/usage?dry_run=true"

Use dry_run=false only after the dry-run output has been checked.

After Testing

Keep FILAMENT_DRY_RUN=true until:

• /filament/status has no unexpected missing_in_bambuddy, missing_in_inventree, or stale_assignments.
• /sync/filament/assignments?dry_run=true shows expected would_create and would_delete.
• After a real successful print, /sync/filament/usage?dry_run=true shows the expected would_remove batch and grams.

Then production mode can be enabled:

FILAMENT_TRACKING_ENABLED=true
FILAMENT_DRY_RUN=false
FILAMENT_SYNC_SPOOLS=true
FILAMENT_SYNC_ASSIGNMENTS=true
FILAMENT_UNASSIGN_MISSING_ASSIGNMENTS=true
FILAMENT_SYNC_LOCATIONS=true
FILAMENT_SYNC_USAGE=true
FILAMENT_RETURN_UNASSIGNED_TO_STORAGE=false
POLL_INTERVAL_SECONDS=300
SYNC_ON_STARTUP=false

Restart after .env changes:

docker compose up -d

Docker Operations

Update deployed service:

cd C:\Users\tcom\Lab8DATAPROCESSOR
git pull
docker compose up -d --build

Logs:

docker compose logs --tail=100

Backup:

• Back up .env separately.
• Back up data/sync.sqlite3.
• Do not commit .env, tokens, passwords, or database files.