FreeCAD-Addon Handbuch

Das FreeCAD-PLM Addon verbindet FreeCAD direkt mit dem PLM-Server. Es ist für den täglichen CAD-Arbeitsablauf gedacht: Projekt finden, Teil oder Baugruppe auswählen, Revision öffnen, Änderungen auschecken, bearbeiten und wieder einchecken.

Dieses Handbuch richtet sich an technisch versierte Anwender. Es erklärt nicht FreeCAD selbst, sondern wie das Addon mit FreeCAD-PLM zusammenspielt, welche lokalen Dateien entstehen und welche typischen Fehlerbilder du einordnen solltest.

Ziel des Addons

Das Addon ist kein Ersatz für die Web-Oberfläche. Die Web-UI bleibt die Stelle für Übersicht, Administration, Revisionhistorie, Artefakte, Fertigungsdateien und tiefergehende Prüfung. Das Addon ist die Arbeitsbrücke in FreeCAD.

Der Normalfall sieht so aus:

PLM verbinden
  -> Projekt wählen
  -> Teil oder Baugruppe wählen
  -> Revision wählen
  -> read-only ansehen oder auschecken
  -> in FreeCAD bearbeiten
  -> einchecken oder Checkout abbrechen

Wichtig ist die Unterscheidung zwischen read-only öffnen und auschecken:

• Read-only öffnen lädt eine Revision zum Ansehen. Es entsteht kein Checkout-Lock auf dem Server.
• Auschecken reserviert die Revision für dich, lädt den zusammengehörenden Dateisatz und aktiviert Check-in/Abbrechen.

Voraussetzungen

Du brauchst:

• FreeCAD mit installiertem FreeCAD-PLM Workbench-Addon,
• eine erreichbare FreeCAD-PLM-Server-URL,
• ein API-Token mit passenden Scopes,
• Schreibzugriff auf den lokalen Workspace-Ordner.

Typische Server-URL:

https://plm.lan.schumbi.de

Typischer Workspace:

~/FreeCAD-PLM

Das API-Token wird serverseitig erzeugt. Für normale CAD-Arbeit werden diese Scopes empfohlen:

read write checkout

Für Projektanlage und Projektmetadaten über das Addon ist zusätzlich admin nötig:

read write checkout admin

Scope-Bedeutung:

• read: Projekte, Teile, Revisionen, Manifeste, Downloads und Anmerkungen lesen.
• write: Teile anlegen/bearbeiten, Projektstände importieren, Notizen und Anmerkungen schreiben.
• checkout: Revisionen auschecken, aktive Checkouts laden, einchecken und abbrechen; zusammen mit write auch neue FCStd-Teile direkt öffnen.
• admin: Projekte anlegen oder Projektstammdaten ändern.

Installation und Aktivierung

Das Addon muss als FreeCAD-Workbench im Benutzer-Mod-Verzeichnis liegen.

Unter Linux mit Flatpak ist der typische Pfad:

~/.var/app/org.freecad.FreeCAD/data/FreeCAD/v1-1/Mod/freecad-plm-addon

Bei klassischer Linux-Installation ist es oft:

~/.local/share/FreeCAD/Mod/freecad-plm-addon

In FreeCAD kannst du den tatsächlich verwendeten Benutzerpfad in der Python-Konsole abfragen:

import FreeCAD as App
App.getUserAppDataDir()

Nach dem Start von FreeCAD wählst du die Workbench FreeCAD-PLM. Die Toolbar enthält Befehle wie:

• PLM-Verbindung aktivieren,
• Verbinden,
• Aktualisieren,
• Auschecken,
• Einchecken,
• Checkout abbrechen,
• Anmerkung erstellen.

Beim Start registriert das Addon außerdem freecad-plm:// für den aktuellen Benutzer. Linux nutzt einen XDG-MIME-Handler, Windows eine benutzerspezifische Registry-Zuordnung unter HKCU; Administratorrechte sind nicht erforderlich. Der Menüpunkt FreeCAD-PLM -> Web-Link-Handler einrichten erneuert die Zuordnung bei Bedarf.

Der wichtigste Einstieg ist PLM-Verbindung aktivieren. Dadurch öffnet sich das Dock und das Addon versucht, Projekte und aktive Checkouts zu laden.

Verbindung einrichten

Oben im Addon-Dock steht der Verbindungsstatus, zum Beispiel:

Verbunden mit plm.lan.schumbi.de

Über Verbindungseinstellungen öffnest du den Dialog für:

• Server-URL,
• API-Token,
• Workspace,
• Cache-Limits für read-only geöffnete Dateien.

Nach Speichern und verbinden speichert das Addon die Werte in den FreeCAD-Preferences und lädt Projekte sowie aktive Checkouts neu.

Die Einstellungen liegen in FreeCAD unter:

User parameter:BaseApp/Preferences/Mod/FreeCADPLM

Praktisch bedeutet das: Die Werte gehören zum FreeCAD-Benutzerprofil, nicht zum Projektordner.

Aufbau der Addon-Ansicht

Die aktuelle Ansicht ist auf den Arbeitsfluss reduziert.

+----------------------------------------------------+
| Verbunden mit ...   Aktualisieren  Verbindungseinstellungen |
+----------------------------------------------------+
| ▾ CHIPBOX                                          |
|   ▾ P-001 - Box                                    |
|       R0001 · Entwurf · Box.FCStd · Checkout lokal |
|   ▸ P-002 - Deckel                                 |
+----------------------------------------------------+
| Checkout lokal · R0001          Einchecken  Mehr   |
+----------------------------------------------------+

Der Baum bildet Projekt, Teil/Baugruppe und Revision in einer Hierarchie ab. Teile und Revisionen werden erst beim Aufklappen geladen. Aktive Checkouts klappt das Addon dagegen automatisch bis zur betroffenen Revision auf. Dadurch bleibt auch ein großes PLM in einem schmalen FreeCAD-Dock übersichtlich.

Projekte

Die oberste Ebene des Baums zeigt Projekte als:

CODE - Name

Aktionen in diesem Bereich:

• Projekt importieren: lokalen FreeCAD-Ordner als Projektstand importieren oder neues Projekt anlegen.
• Projekt bearbeiten: Code, Name, Status, Datum und Beschreibung bearbeiten.

Teile

Unter einem aufgeklappten Projekt stehen Teile und Baugruppen als:

P-001 - Box

Wenn ein Status vorhanden ist, erscheint er in eckigen Klammern.

Aktionen:

• Neues Teil: Teil oder Baugruppe mit leerer FCStd-Revision R0001 anlegen und direkt öffnen.
• Teil bearbeiten: Name, Kategorie, Beschreibung, Material, Lieferant, Tags und Archivstatus bearbeiten.

Revisionen

Unter einem aufgeklappten Teil stehen dessen Revisionen. Labels sind bewusst kurz:

R0001 · Entwurf · Box.FCStd · 2026-07-10

Aktionen:

• Einfachklick: Revision auswählen.
• Doppelklick: FCStd auschecken; STEP/STP oder STL schreibgeschützt öffnen.
• Auschecken: Checkout-Lock erzeugen und Dateien in den Workspace laden.
• Read-only öffnen: Revision ohne Lock öffnen.
• Details: technische und fachliche Revisionsdaten anzeigen.
• Notizen: Revisionsnotizen bearbeiten.
• Anmerkungen: Anmerkungen zu Teil und Revision anzeigen und bearbeiten.

Dieselben Aktionen sind passend zum ausgewählten Knoten über Rechtsklick erreichbar. Seltenere Aktionen liegen unter Mehr, damit die ständig sichtbare Leiste auf den aktuellen Arbeitsfluss beschränkt bleibt.

FCStd-, STEP- und STL-Revisionen können schreibgeschützt geöffnet werden. STEP/STP lädt das Addon dabei über FreeCADs Import-Modul, STL über das Mesh-Modul. Auschecken und Check-in stehen nur für FCStd-Revisionen zur Verfügung, weil nur dort die FreeCAD-Dokumentstruktur und technische Änderungssignatur verlässlich geführt werden.

Im Slicer öffnen

Für FCStd-, STEP- und STL-Revisionen erzeugt beziehungsweise lädt die Aktion Im Slicer öffnen einen veränderlichen 3MF-Arbeitsstand. Beim ersten Öffnen exportiert das Addon die sichtbare Geometrie. Ein sichtbarer PartDesign::Body ersetzt dabei seine sichtbaren Feature-Kinder, damit Body und Tip nicht als doppelte Modelle im Slicer erscheinen.

Neu erzeugte 3MF enthalten eine Liste der exportierten CAD-Quellen mit Revisions-IDs, Dateipfaden und SHA-256-Hashes. Beim Öffnen wird sie mit dem aktuellen PLM-Stand verglichen. Änderungen an abhängigen Teilen werden auch dann erkannt, wenn sich die Revision der Druckbaugruppe nicht geändert hat.

Bei Abweichungen bietet das Addon 3MF neu erzeugen, Bisherigen Stand öffnen oder Abbrechen an. Fehlen die Quellenangaben, etwa bei älteren 3MF oder weil ein Slicer sie entfernt hat, lautet der Hinweis nicht prüfbar. Die Angaben beschreiben den ursprünglichen CAD-Export, nicht später im Slicer hinzugefügte oder manuell bearbeitete Geometrie.

Über Mehr → 3MF neu erzeugen lässt sich der Export jederzeit wiederholen. Vorher das bisherige Projekt im Slicer schließen und gewünschte Checkout-Änderungen einchecken: Grundlage ist die gespeicherte CAD-Revision mit ihren Abhängigkeiten. Die Neuerzeugung übernimmt keine Druckeinstellungen, Plattenanordnung, Farbzuweisungen oder zusätzlich eingefügten Quellen. Der bisherige Stand einschließlich sync.json wird lokal im Unterordner backups/<UTC-Zeitstempel>-<Kennung>/ neben der Arbeitsdatei gesichert. Zum Wiederherstellen die gesicherte 3MF im Slicer öffnen und als Arbeitsdatei speichern. Bei Export- oder Sicherungsfehlern bleibt die bisherige 3MF erhalten.

Nach dem Speichern überwacht das Addon die 3MF-Datei und synchronisiert sie automatisch zur ausgewählten Revision. Ein bereits vorhandener Serverstand wird beim nächsten Öffnen wiederverwendet. Für die Synchronisation muss FreeCAD laufen; ein zusätzlicher Hintergrunddienst ist nicht erforderlich.

Die Slicer-Einstellungen liegen unter Verbindungseinstellungen. Unter Linux kann das Addon Bambu Studio und OrcaSlicer als Flatpak erkennen und aus einer FreeCAD-Flatpak-Installation über den Host starten.

Aktive Checkouts

Aktive Checkouts deines API-Benutzers stehen direkt an der zugehörigen Revision im Projektbaum. Dadurch gehen Checkout-Locks nicht verloren, nur weil FreeCAD geschlossen wurde, und es gibt keine zweite Checkout-Liste mehr, die mit dem Projektbaum abgeglichen werden muss.

• Grün und fett: Dieser Checkout ist in der aktuellen FreeCAD-Sitzung lokal geöffnet.
• Orange: Der Server kennt den Checkout, lokal ist er noch nicht geöffnet.
• Rot: Der Checkout konnte nicht eindeutig zugeordnet oder lokal nicht geöffnet werden; der Tooltip nennt den Fehler.

Die untere Arbeitsleiste richtet sich nach der Auswahl. Für einen lokal geöffneten Checkout ist Einchecken die Hauptaktion. Checkout öffnen, Teil hinzufügen, Teil entfernen und Checkout abbrechen stehen unter Mehr; das Abbrechen fragt weiterhin ausdrücklich nach einer Bestätigung. Ein serverseitiger Checkout wird mit Checkout öffnen wiederhergestellt.

Revisionslink aus dem Web öffnen

Revisionskarten im Web bieten Links im Format:

freecad-plm://revision/123?project_id=7&part_id=42&action=checkout

Das Addon verknüpft das Schema beim FreeCAD-Start unter Linux, Linux-Flatpak und Windows automatisch. Der Browser kann den Link damit direkt an FreeCAD übergeben, unabhängig davon, ob FreeCAD bereits läuft. Intern wird eine kurzlebige .FCPLMLink-Datei verwendet, damit FreeCADs Ein-Instanz-Mechanismus den Auftrag zuverlässig an das vorhandene Fenster weiterreicht. Als betriebssystemunabhängiger Rückfall steht in der Workbench der Befehl PLM-Link öffnen bereit; dort kannst du den kopierten Link einfügen.

Das Add-on akzeptiert nur die Aktionen checkout, readonly und slicer sowie die bekannten IDs. Es prüft Projekt und Teil anhand der Serverdaten. Bevor ein Link tatsächlich einen Checkout startet, musst du nochmals bestätigen. Ein Link enthält niemals API-Token oder andere Zugangsdaten.

Konsolenausgaben

Das Addon schreibt Statusmeldungen in das normale FreeCAD-Ausgabefenster. Alle Meldungen beginnen mit:

[FreeCAD-PLM]

Beispiele:

[FreeCAD-PLM] 4 Projekte geladen. Aktive Checkouts: 1.
[FreeCAD-PLM] Checkout geöffnet (3 Datei(en))
[FreeCAD-PLM] Checkout geöffnet: /home/ralf/FreeCAD-PLM/.../Box.FCStd (3 Datei(en))

Wenn du ein Problem analysierst, öffne zuerst FreeCADs Ausgabefenster beziehungsweise Report View und suche nach [FreeCAD-PLM].

Lokaler Workspace

Das Addon legt Dateien nicht irgendwo neben deiner aktuellen Konstruktion ab, sondern unter dem konfigurierten Workspace.

Default:

~/FreeCAD-PLM

Checkout-Pfad:

~/FreeCAD-PLM/<server-slug>/<project-code>/checkout-<checkout-id>/

Beispiel:

~/FreeCAD-PLM/plm-lan-schumbi-de/CHIPBOX/checkout-42/

Darin liegen:

manifest.json
checkout.json
files/
  Box.FCStd
  parts/Halter.FCStd

Bedeutung:

• manifest.json: vom Server gelieferte Dateiliste mit Revisionen, Pfaden, Hashes und Root-Datei.
• checkout.json: lokale technische Metadaten zur Änderungserkennung.
• files/: die wirklichen FreeCAD-Dateien mit relativer Struktur aus dem Manifest.

Bei read-only geöffneten Revisionen nutzt das Addon einen getrennten Cache:

~/FreeCAD-PLM/<server-slug>/<project-code>/readonly/revision-<revision-id>/

Read-only Dateien werden lokal schreibgeschützt abgelegt. Sie sind zum Ansehen gedacht, nicht als Arbeitskopie.

Ablauf: Verbinden und Daten laden

Benutzer klickt PLM-Verbindung aktivieren
  -> Addon liest Server-URL, Token und Workspace aus FreeCAD-Preferences
  -> GET /api/projects/
  -> GET /api/checkouts/active/
  -> Projekte anzeigen
  -> aktive Checkouts anzeigen
  -> Status ins FreeCAD-Ausgabefenster schreiben

Wenn dieser Ablauf scheitert, prüfe:

• stimmt die Server-URL?
• ist das Token eingetragen?
• ist das Token noch gültig?
• hat das Token mindestens read und checkout?
• ist der Server aus FreeCAD heraus erreichbar?

Ablauf: Projekt, Teil und Revision finden

Projekt auswählen
  -> GET /api/projects/<id>/parts/
  -> Teilknoten im Projektbaum füllen

Teil auswählen
  -> GET /api/parts/<id>/
  -> Revisionen aus Antwort lesen
  -> Revisionsknoten unter dem Teil füllen
  -> Anmerkungen für Teil/Revision laden

Die Web-Oberfläche ist weiterhin besser für globale Suche und Historie. Das Addon ist absichtlich auf den aktuellen Projektkontext optimiert.

Ablauf: Revision read-only öffnen

Read-only ist der sichere Weg, wenn du nur prüfen, messen, ansehen oder eine alte Revision vergleichen willst.

Revision auswählen
  -> Read-only öffnen
  -> GET /api/revisions/<revision-id>/manifest/
  -> manifest.files herunterladen
  -> SHA-256 je Datei prüfen
  -> manifest.json in readonly Cache schreiben
  -> Root-Datei öffnen
  -> vollständigen lokalen Pfad im FreeCAD-Ausgabefenster melden

Dabei entsteht kein aktiver Checkout auf dem Server.

Nutze read-only für:

• Kontrolle alter Revisionen,
• Sichtprüfung,
• Vergleich,
• Referenzieren ohne Änderungsabsicht.

Nutze read-only nicht für echte Bearbeitung. Wenn du Änderungen einchecken willst, musst du auschecken.

Ablauf: Revision auschecken

Checkout ist der normale Bearbeitungspfad.

Revision auswählen oder doppelklicken
  -> Addon prüft lokalen aktiven Checkout
  -> wenn kein Checkout aktiv: POST /api/revisions/<id>/checkout/
  -> Manifest laden oder aus Checkout-Antwort übernehmen
  -> Dateien herunterladen
  -> SHA-256 prüfen
  -> manifest.json und checkout.json schreiben
  -> Root-Datei in FreeCAD öffnen
  -> aktiven Checkout im Dock anzeigen

Ein Checkout erzeugt serverseitig einen Lock. Dadurch soll verhindert werden, dass mehrere Benutzer denselben Stand gleichzeitig als Arbeitsstand einchecken.

Checkout-Guard

Das Addon verhindert absichtliches oder versehentliches Überschreiben des lokalen Arbeitskontexts.

Auschecken angefordert
  -> keine Revision gewählt?
       Meldung ausgeben
  -> kein aktiver Checkout?
       Checkout starten
  -> gleiche Revision bereits lokal aktiv?
       aktive Root-Datei öffnen/fokussieren
  -> anderer Checkout lokal aktiv?
       Entscheidungsdialog anzeigen

Bei einem anderen aktiven Checkout fragt das Addon:

• Aktiven Checkout öffnen,
• Einchecken,
• Checkout abbrechen,
• Nicht starten.

Es startet keinen stillen zweiten Checkout.

Ablauf: Aktiven Checkout wieder öffnen

Nach einem FreeCAD-Neustart kann der Server noch aktive Checkouts kennen. Diese Revisionen werden im Projektbaum orange markiert und automatisch aufgeklappt.

Orange markierte Checkout-Revision auswählen oder doppelklicken
  -> Checkout öffnen
  -> wenn derselbe Checkout lokal schon aktiv ist:
       Root-Datei öffnen/fokussieren
  -> sonst:
       lokalen Workspace-Pfad rekonstruieren
       Manifest vom Server laden, falls nötig
       fehlende Dateien herunterladen
       checkout.json prüfen
       Root-Datei öffnen

Wenn checkout.json fehlt, meldet das Addon:

[FreeCAD-PLM] PLM-Fehler: Checkout-Metadaten fehlen. Bitte Checkout abbrechen und neu auschecken.

Diese Meldung bedeutet: Der Server kennt noch den Checkout, aber die lokale Arbeitskopie ist nicht mehr vollständig genug, um Änderungen sicher zu erkennen. Das Addon kann dann nicht garantieren, welche Dateien wirklich geändert wurden.

Sinnvolle Reaktion:

• Wenn du keine lokalen Änderungen brauchst: Checkout abbrechen und neu auschecken.
• Wenn du lokale Änderungen retten musst: Workspace-Ordner manuell sichern, danach mit dem PLM-Zustand abgleichen.

Ablauf: Neues FreeCAD-Teil anlegen

Neues Teil benötigt keine zuvor lokal gespeicherte Datei und keinen Dateiauswahldialog.

Projekt auswählen
  -> Neues Teil
  -> Name, optionale Teilenummer und Typ eingeben
  -> Anlegen und öffnen
  -> Addon erzeugt intern eine leere FCStd-Datei
  -> POST /api/projects/<id>/parts/create-fcstd/
  -> Server legt Teil und R0001 gemeinsam an
  -> Addon lädt Manifest und Datei, prüft SHA-256 und öffnet das Dokument

Ist ein Projekt-Checkout in der aktuellen FreeCAD-Sitzung geöffnet, wird die neue FCStd-Datei direkt in dessen Manifest und Workspace aufgenommen. So kann sie sofort im Hauptmodell verlinkt werden. Ohne aktiven Checkout entsteht ein eigener Checkout für das neue Teil.

Wichtig:

• Die Aktion benötigt write und checkout.
• Ein auf dem Server aktiver Projekt-Checkout muss zuerst über Aktiven Checkout öffnen lokal geöffnet werden.
• Das ausgewählte Projekt wird bei einem geöffneten Checkout automatisch an dessen Projekt angeglichen.
• Schlägt die serverseitige Anlage oder Manifest-Erweiterung fehl, bleibt kein unvollständiges Teil mit Revision in der Datenbank zurück.

Vorhandene lokale FCStd als neues Teil übernehmen

Lokale FCStd hinzufügen verwendet denselben atomaren Serverablauf, lädt aber anstelle eines leeren Dokuments eine bereits gespeicherte .FCStd-Datei hoch. Name, optionale Teilenummer und Kategorie werden vor dem Upload abgefragt. Bei einem lokal geöffneten Projekt-Checkout ergänzt der Server dessen Manifest; das Addon schließt anschließend das ursprüngliche Dokument und öffnet die verwaltete Arbeitskopie aus dem Checkout-Workspace. Nicht gespeicherte FreeCAD-Dokumente werden nicht übernommen.

Revision einem Druckprojekt zuordnen

Zum Druckprojekt hinzufügen ordnet die ausgewählte Revision einem bereits vorhandenen Druckprojekt desselben PLM-Projekts als Quelle zu. Zusätzlich lädt das Addon das Revisionsmanifest, exportiert die sichtbare Geometrie als STL in slicer-projects/print-project-<id>/source-additions/ und öffnet diesen Ordner. Die STL wird anschließend bewusst im Slicer auf der gewünschten Platte eingefügt; das Addon schreibt nicht automatisch in ein bestehendes 3MF.

Ablauf: Teil zum aktiven Checkout hinzufügen

Mit Teil hinzufügen kannst du eine bereits im PLM vorhandene Revision in den geöffneten Projekt-Checkout aufnehmen. Das ist insbesondere nötig, wenn eine neue Datei zwar als Teil mit Revision im Projekt vorhanden ist, vom Hauptteil aber noch nicht referenziert wird. Ohne diese Aktion wäre die Datei nicht im Checkout-Manifest und könnte in FreeCAD nicht verlinkt werden.

Projekt und Teil auswählen
  -> gewünschte Revision auswählen
  -> aktiven Master-Checkout lokal öffnen
  -> Teil hinzufügen
  -> POST /api/checkouts/<id>/files/add/
  -> Server ergänzt das Checkout-Manifest
  -> Addon lädt die Datei in den Checkout-Workspace
  -> checkout.json wird ergänzt, ohne bestehende Änderungsbasen zu überschreiben
  -> Datei wird als separates FreeCAD-Dokument geöffnet
  -> Datei im Hauptteil verlinken und Hauptteil speichern

Der Server verwendet einen bereits bekannten Pfad aus dem Ausgangs-Projektstand. Ist das Teil dort noch nicht enthalten, wird die Datei in das Verzeichnis der Root-Datei gelegt. Bei einer Root-Datei praxis/Kleberschale.FCStd wird beispielsweise bigBottle.FCStd als praxis/bigBottle.FCStd ergänzt.

Voraussetzungen:

• Teil und Revision gehören zum selben Projekt wie der aktive Checkout.
• Der aktive Checkout basiert auf einem Projektstand.
• Das Teil ist nicht archiviert und noch nicht im Checkout enthalten.
• Für das hinzuzufügende Teil besteht kein eigener aktiver Checkout.

Wenn das Zielteil bereits eigenständig ausgecheckt ist, brich diesen Checkout zuerst ab oder checke ihn ein. Danach kannst du seine Revision zum Master-Checkout hinzufügen.

Das Hinzufügen ist eine Änderung der Projektstruktur. Beim Check-in entsteht deshalb auch dann ein neuer Projektstand, wenn die hinzugefügte Datei selbst unverändert bleibt. Eine neue Revision entsteht nur für Dateien mit modellrelevanten Änderungen.

Ablauf: Teil aus dem aktiven Checkout entfernen

Teil entfernen zeigt die nicht als Root markierten Dateien des Checkout-Manifests. Das Hauptteil kann nicht entfernt werden.

Teil entfernen
  -> nicht benötigte Manifest-Datei auswählen
  -> geöffnete Datei in FreeCAD schließen
  -> POST /api/checkouts/<id>/files/remove/
  -> Manifest und checkout.json aktualisieren
  -> lokale Datei aus dem Checkout-Workspace löschen

Wurde eine Datei erst während desselben Checkouts hinzugefügt, macht Teil entfernen diese noch nicht eingecheckte Ergänzung wieder rückgängig. Bei einer Datei aus dem Ausgangs-Projektstand wird die Entfernung für den nächsten Projektstand vorgemerkt.

Auch eine reine Entfernung kann ohne neue Dateirevision einen neuen Projektstand erzeugen.

Ablauf: Einchecken

Beim Check-in speichert das Addon zuerst geöffnete Checkout-Dokumente und prüft dann, welche Manifest-Dateien modellrelevant geändert wurden.

Einchecken
  -> geöffnete Checkout-Dokumente speichern
  -> manifest.json lesen
  -> checkout.json lesen
  -> technische Änderungen analysieren
  -> unveränderte Dateien ignorieren
  -> Änderungskommentar abfragen
  -> geänderte Dateien mit Metadaten senden
  -> POST /api/checkouts/<id>/checkin/
  -> neue Revisionen vom Server übernehmen
  -> lokale Checkout-Dokumente schließen
  -> Checkout aus lokalem aktiven Zustand entfernen
  -> Projekte/Revisionen/aktive Checkouts neu laden

Der Änderungskommentar ist Pflicht. Er soll fachlich beschreiben, was geändert wurde, zum Beispiel:

Laschenposition angepasst und Wandstärke auf 2,4 mm erhöht.

Nicht hilfreich sind Kommentare wie:

update
neu
fix

Änderungserkennung

FreeCAD speichert viele technische Daten, die sich ändern können, ohne dass sich das Modell fachlich geändert hat. Das Addon versucht, solche Speicherartefakte nicht als neue Revision zu behandeln.

Grundprinzip:

Base-Datei aus Checkout
  -> aktuelle Datei aus Workspace
  -> technische FCStd-Inhalte normalisieren
  -> modellrelevante Änderung erkennen

Wenn weder modellrelevante Änderungen noch hinzugefügte oder entfernte Dateien gefunden werden, bleibt der Checkout aktiv. Das Addon bietet dann an, den Checkout abzubrechen.

Bei hinzugefügten oder entfernten Dateien darf der Check-in dagegen auch ohne neue Dateirevision abgeschlossen werden. Der Server erzeugt dann einen neuen Projektstand mit der geänderten Dateizusammenstellung.

Das ist Absicht: Eine neue Revision soll eine fachliche Änderung dokumentieren, nicht nur einen FreeCAD-Speichervorgang.

Ablauf: Checkout abbrechen

Checkout abbrechen bedeutet: Der Server-Lock wird freigegeben, ohne neue Revision anzulegen.

Checkout abbrechen
  -> Bestätigung abfragen
  -> POST /api/checkouts/<id>/cancel/
  -> geöffnete Checkout-Dokumente schließen
  -> lokalen aktiven Checkout zurücksetzen
  -> aktive Checkouts neu laden

Nutze Abbrechen, wenn:

• du nur etwas ausprobiert hast,
• keine fachliche Änderung entstanden ist,
• du neu vom Serverstand starten willst,
• der lokale Workspace unbrauchbar geworden ist.

Brich nicht ab, wenn du lokale Änderungen noch brauchst. Sichere dann zuerst die Dateien aus dem Checkout-Workspace.

Projekt importieren aus FreeCAD

Das Addon kann einen lokalen FreeCAD-Ordner als Projektstand importieren.

Projekt importieren
  -> neues oder ausgewähltes Projekt wählen
  -> lokalen Ordner wählen
  -> alle .FCStd-, .step-, .stp- und .stl-Dateien darunter in ZIP packen
  -> ZIP an Server senden
  -> Server legt fehlende Teile/Baugruppen und Revisionen an
  -> Server legt Projektstand an
  -> optional importiertes Root-Teil direkt auschecken
  -> optional lokalen Importordner archivieren

Wichtig sind die relativen Pfade. Wenn deine Baugruppe auf parts/Halter.FCStd verweist, muss diese Struktur im lokalen Ordner vorhanden sein.

Beispiel:

Chipbox.FCStd
parts/Halter.FCStd
parts/Deckel.FCStd

Nach erfolgreichem Import kann das Addon den Ursprungsordner nach:

~/FreeCAD-PLM/imported/<server>/<project-code>/...

verschieben. Das verhindert, dass du versehentlich im alten Importordner weiterarbeitest, während der PLM-Checkout die eigentliche Arbeitskopie ist.

Projekt und Teil bearbeiten

Projekt- und Teilstammdaten liegen nicht dauerhaft im Hauptpanel, sondern in Dialogen.

Projekt bearbeiten:

• Code,
• Name,
• Status,
• Datum,
• Beschreibung.

Teil bearbeiten:

• Name,
• Kategorie,
• Beschreibung,
• Material,
• Lieferant,
• Tags,
• Archivstatus.

Die Nummer eines vorhandenen Teils wird im Addon nicht frei editiert. Sie ist die stabile fachliche Kennung.

Notizen und Anmerkungen

Notizen gehören zur Revision. Sie sind gut für freien technischen Kontext, der nicht als strukturierter Status modelliert ist.

Anmerkungen gehören zum Teil beziehungsweise optional zu einer Revision. Sie können einen Status haben und lassen sich erledigen oder wieder öffnen.

Typischer Ablauf:

Revision auswählen
  -> Anmerkungen
  -> Filter wählen
  -> Neu oder Bearbeiten
  -> Text speichern

Aus FreeCAD heraus kann der Toolbar-Befehl Anmerkung erstellen versuchen, die aktuelle Auswahl als Objekt/Subelement zu übernehmen. Das ist hilfreich, wenn du eine Anmerkung auf ein bestimmtes FreeCAD-Element beziehen willst.

Server-API, die das Addon verwendet

Für die Fehlersuche ist nützlich zu wissen, welche Endpunkte beteiligt sind.

GET    /api/projects/
GET    /api/projects/<id>/parts/
GET    /api/parts/<id>/
POST   /api/projects/<id>/
POST   /api/projects/<id>/parts/
POST   /api/projects/<id>/parts/create-fcstd/
POST   /api/parts/<id>/
POST   /api/projects/import/
POST   /api/projects/<id>/snapshots/import/
GET    /api/revisions/<id>/
POST   /api/revisions/<id>/notes/
GET    /api/revisions/<id>/file/
GET    /api/revisions/<id>/manifest/
POST   /api/revisions/<id>/checkout/
GET    /api/checkouts/active/
GET    /api/checkouts/<id>/manifest/
POST   /api/checkouts/<id>/files/add/
POST   /api/checkouts/<id>/files/remove/
POST   /api/checkouts/<id>/checkin/
POST   /api/checkouts/<id>/cancel/
GET    /api/parts/<id>/annotations/
POST   /api/parts/<id>/annotations/
POST   /api/annotations/<id>/
DELETE /api/annotations/<id>/

Alle Requests senden:

Authorization: Bearer <token>

Dateidownloads werden ebenfalls mit Bearer Token ausgeführt.

Cache-Limits

Die Verbindungseinstellungen enthalten Limits für read-only Caches:

• maximale FCStd-Dateien,
• maximale Projekte,
• maximale Revisionen pro Projekt.

Diese Limits betreffen den read-only Cache. Checkout-Workspaces werden nicht als Wegwerf-Cache behandelt, weil sie aktive Arbeit enthalten können.

Best Practices

Arbeite mit dieser Grundregel:

Ansehen = read-only
Ändern = auschecken
Abgeben = einchecken
Verwerfen = abbrechen

Weitere Empfehlungen:

• Öffne eine Revision read-only, wenn du unsicher bist, ob du sie ändern willst.
• Checke nur aus, wenn du wirklich bearbeiten möchtest.
• Halte nur einen lokalen Checkout aktiv, solange du nicht bewusst mehrere Arbeitsstände koordinierst.
• Schreibe Änderungskommentare so, dass du sie in sechs Monaten noch verstehst.
• Arbeite nach einem Import nicht im alten Quellordner weiter, sondern im Checkout-Workspace.
• Verändere manifest.json und checkout.json nicht manuell.
• Lösche Checkout-Ordner nicht, solange der Server-Checkout noch aktiv ist.

Troubleshooting

Keine Projekte werden geladen

Prüfe im FreeCAD-Ausgabefenster die Meldung mit [FreeCAD-PLM].

Typische Ursachen:

• Server-URL falsch,
• Token leer oder abgelaufen,
• Token hat keinen read-Scope,
• Server ist aus FreeCAD nicht erreichbar,
• Reverse Proxy oder Zertifikat blockiert die Verbindung.

403 oder Scope-Fehler

Das Token reicht für die Aktion nicht aus.

Beispiele:

• Projekt bearbeiten braucht admin.
• Teile anlegen/ändern, Import und Anmerkungen ändern brauchen write.
• Auschecken, Einchecken und Abbrechen brauchen checkout.
• Neues Teil braucht write und checkout gemeinsam.

Checkout ist laut Server aktiv, lässt sich aber nicht wieder öffnen

Wenn die lokale Datei checkout.json fehlt oder veraltet ist, kann das Addon Änderungen nicht sicher erkennen. Dann meldet es einen Metadatenfehler.

Empfohlene Wege:

• lokale Änderungen nicht wichtig: Checkout abbrechen und neu auschecken,
• lokale Änderungen wichtig: Workspace manuell sichern, dann mit einem frischen Checkout vergleichen.

Server meldet bereits aktiven Checkout

Der Server ist die Wahrheit für Checkout-Locks. Wenn das Addon einen Konflikt meldet, lade aktive Checkouts neu und entscheide:

• aktiven Checkout öffnen,
• einchecken,
• abbrechen,
• neuen Checkout nicht starten.

Teil lässt sich nicht zum aktiven Checkout hinzufügen

Prüfe:

• ist der Master-Checkout lokal geöffnet?
• ist im Projektteil-Bereich eine konkrete Revision ausgewählt?
• gehören Master und Zielteil zum selben Projekt?
• ist das Zielteil bereits im Checkout-Manifest enthalten?
• ist das Zielteil archiviert oder noch eigenständig ausgecheckt?

Ein eigenständiger Checkout des Zielteils muss zuerst eingecheckt oder abgebrochen werden. Danach kann seine Revision zum Master-Checkout hinzugefügt werden.

Check-in erzeugt keine neue Revision

Dann wurden keine modellrelevanten Änderungen erkannt oder der Server hat keine neue Revision angelegt.

Prüfe:

• wurde die richtige Datei im Checkout-Workspace geändert?
• wurde die Datei gespeichert?
• ist die Änderung fachlich im Modell sichtbar?
• hast du nur technische FreeCAD-Speicherartefakte erzeugt?

SHA-256 stimmt nicht

Das Addon verwirft Downloads, deren Hash nicht zum Manifest passt.

Mögliche Ursachen:

• unvollständiger Download,
• Proxy- oder Serverproblem,
• Datei wurde serverseitig unerwartet geändert,
• falsches Manifest.

Lade erneut. Wenn der Fehler reproduzierbar bleibt, prüfe Serverlogs und Revisiondatei.

Referenzen fehlen nach dem Öffnen

Bei read-only und Checkout lädt das Addon Dateien aus dem Manifest. Wenn FreeCAD trotzdem Referenzen nicht findet, prüfe:

• ob die Baugruppe im PLM-Projektstand vollständig importiert wurde,
• ob relative Pfade im ursprünglichen Projektordner korrekt waren,
• ob referenzierte Dateien im Manifest enthalten sind,
• ob die Root-Datei wirklich aus files/ geöffnet wurde.

Meldungen erscheinen nicht im Dock

Das ist normal. Das Addon schreibt Statusmeldungen ins FreeCAD-Ausgabefenster, nicht in eine dauerhaft sichtbare Dock-Zeile. Suche dort nach [FreeCAD-PLM].

Begriffsabgleich

Begriff	Bedeutung im Addon
Projekt	fachlicher Rahmen, enthält Teile und Baugruppen
Teil/Baugruppe	CAD-Objekt mit Revisionen
Revision	unveränderlicher CAD-Dateistand als FCStd, STEP/STP oder STL
Projektstand	eingefrorene Kombination mehrerer Dateipfade und Revisionen
Manifest	Server-Dateiliste für read-only oder Checkout
Checkout	serverseitiger Bearbeitungs-Lock plus lokale Arbeitskopie
Check-in	Upload geänderter Dateien als neue Revisionen
Cancel/Abbrechen	Lock freigeben ohne neue Revision
Workspace	lokaler Addon-Arbeitsbereich unter ~/FreeCAD-PLM

Wann die Web-UI besser ist

Nutze die Web-Oberfläche für:

• globale Suche,
• Historie und Vergleich,
• Artefakte wie STEP, STL, PNG,
• Fertigungsdateien und 3MF-Metadaten,
• Benutzer, Rollen und Tokens,
• administrative Korrekturen.

Nutze das Addon für:

• schnelle Auswahl aus FreeCAD heraus,
• read-only Ansicht einer Revision,
• Checkout und Check-in,
• Bearbeitung im lokalen FreeCAD-Kontext,
• Anmerkungen direkt aus der Konstruktion heraus.

Beide Oberflächen greifen auf dieselbe Server-Wahrheit zu. Wenn du unsicher bist, prüfe den Stand im Web und lade danach im Addon neu.