Maschinen & Werkzeuge

Was die Oberfläche heute zeigt

Die Seite „Maschinenwand“ ist eine Live-Anzeige für den Betrieb. Sie zeigt pro aktiver Maschine Name, ID, Fähigkeiten, Zustand und gegebenenfalls den letzten Zustandsgrund. Die Farbe am linken Kartenrand folgt dem Zustand. Die Seite ist kein Maschineneditor.

Maschinen registrieren, ändern und außer Betrieb nehmen sowie Werkzeuge verwalten Sie derzeit ausschließlich über die REST-API. Auch direkte Zustandswechsel haben keinen eigenen Standarddialog. Eine konfigurierte Aktion kann einen Zustandswechsel in einer eigenen Ansicht anbieten; die Maschinenwand selbst bleibt schreibgeschützt.

Die API-Beispiele auf dieser Seite setzen die Serveradresse in WERKSPUR und einen gültigen Sitzungstoken in WERKSPUR_TOKEN voraus.

Eine Maschine registrieren

Nur ein Admin darf POST /api/machines aufrufen:

curl -sS -X POST "$WERKSPUR/api/machines" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "fraese-1",
    "name": "Fräse 1",
    "capabilities": ["milling"],
    "tooling": ["fraeser-8mm"],
    "binding": {},
    "hourly_rate_cents": 9500
  }'

Die ID ist ein unveränderlicher Slug aus Kleinbuchstaben, Ziffern und Bindestrichen. Sie beginnt mit einem Buchstaben oder einer Ziffer, ist höchstens 63 Zeichen lang und darf nicht doppelt vorkommen. name darf nicht leer sein. capabilities braucht mindestens einen nicht leeren Eintrag. Fehlen tooling und binding, speichert der Server eine leere Liste und ein leeres Objekt.

Eine neue Maschine beginnt im Zustand idle und im Lebenszyklus active. hourly_rate_cents ist der Kostensatz pro Maschinenstunde in Cent. Er darf nicht negativ sein. Die Kennzahlen verwenden ihn, um aus Stillstandssekunden die Stillstandskosten zu berechnen.

Fähigkeiten und Zuordnungen

Die Liste capabilities verbindet Auftragsplanung und Shopfloor. Ein Auftragsschritt nennt genau eine benötigte Fähigkeit. Beim Einscannen prüft WERKSPUR, ob die gewählte Maschine diese Fähigkeit besitzt. Fehlt sie, lehnt der Server den Scan ab.

tooling ist die Liste der aktuell an der Maschine montierten Werkzeug-IDs. Wenn ein Schrittabschluss keine eigene Werkzeugliste mitgibt, stempelt der Server diese Maschinenliste in den Prozessdatensatz. Eine Änderung wirkt daher auf spätere Buchungen, nicht rückwirkend auf bereits gespeicherte Vorgänge.

binding nimmt die technische Zuordnung der Maschine auf. Das Maschinenmodul speichert dieses JSON-Objekt mit der Maschine. Konkrete Live-Daten werden jedoch über OPC UA, MQTT-Zuordnungen und Telemetrie angebunden.

Eine Maschine aktualisieren

Ein Admin ersetzt die veränderlichen Felder mit PUT /api/machines/{id}:

curl -sS -X PUT "$WERKSPUR/api/machines/fraese-1" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Fräse 1",
    "capabilities": ["milling", "drilling"],
    "tooling": ["bohrer-6mm"],
    "binding": {},
    "hourly_rate_cents": 9800
  }'

Der Aufruf ersetzt name, capabilities, tooling, binding und hourly_rate_cents gemeinsam. Senden Sie deshalb immer den vollständigen gewünschten Stand. Ein weggelassenes tooling wird zur leeren Liste, ein weggelassenes binding zum leeren Objekt und ein weggelassener Kostensatz zu null. Die ID lässt sich nicht ändern.

Maschinenzustände und Gründe

WERKSPUR kennt vier Maschinenzustände:

• running. Die Maschine arbeitet.
• idle. Die Maschine ist betriebsbereit, arbeitet aber gerade nicht.
• down. Die Maschine steht ungeplant.
• maintenance. Die Maschine befindet sich in Wartung.

Ein Benutzer ab der Rolle operator meldet einen Zustand mit POST /api/machines/{id}/state:

curl -sS -X POST "$WERKSPUR/api/machines/fraese-1/state" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"state":"down","reason":"WERKZEUGBRUCH"}'

Der Grund ist optional. Wenn Sie einen Grund mitsenden, muss er als aktiver Maschinen-Grund-Code registriert sein. Ein unbekannter oder deaktivierter Code wird abgelehnt. Ein Wechsel auf denselben Zustand erzeugt kein neues Zustandsereignis. Ein Wechsel auf einen anderen Zustand erzeugt MachineStateChanged; die Maschinenwand übernimmt ihn über ihren Live-Datenstrom.

Telemetrieregeln können dieselben Zustandsereignisse automatisch erzeugen. Für solche Systemwechsel darf der Grund Freitext sein. Manuelle API-Aufrufe unterliegen dagegen dem verwalteten Maschinenkatalog.

Eine Maschine außer Betrieb nehmen

Nur ein Admin darf eine Maschine außer Betrieb nehmen:

curl -sS -X POST "$WERKSPUR/api/machines/fraese-1/decommission" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Anlage ersetzt"}'

Der Grund ist optional. Die Maschine wechselt im Lebenszyklus von active zu archived. Der Aufruf ist idempotent. Ein zweiter Aufruf ändert nichts zusätzlich.

Die Außerbetriebnahme ist endgültig. Es gibt keinen API-Aufruf für eine Wiederinbetriebnahme. Eine archivierte Maschine bleibt über GET /api/machines/{id} und in ihrer Ereignishistorie auffindbar. Sie verschwindet aber aus GET /api/machines, aus der „Maschinenwand“ und aus der Maschinenauswahl am „Scan-Terminal“. Aktualisierungen und manuelle Zustandswechsel werden für sie abgelehnt.

Aktive Maschinen zählen

GET /api/machines/active-count liefert die Abrechnungsbasis und braucht die Rolle admin:

{"active_machines": 12}

Gezählt werden ausschließlich Maschinen mit dem Lebenszyklus active. Der Maschinenzustand spielt keine Rolle. Eine aktive Maschine mit down oder maintenance zählt also weiterhin. Erst die Außerbetriebnahme entfernt sie aus dem aktiven Bestand. Werkzeuge, Stationen und archivierte Maschinen zählen nicht mit.

Werkzeuge registrieren und melden

Das Werkzeugregister ist von der montierten tooling-Liste einer Maschine zu unterscheiden. Das Register führt ein Werkzeug mit eigener ID, eigenem Zustand und optionaler Maschinenzuordnung. Die Maschinenliste beschreibt dagegen, was aktuell montiert ist. Die API synchronisiert diese beiden Angaben nicht automatisch.

Nur ein Admin registriert ein Werkzeug mit POST /api/tools:

curl -sS -X POST "$WERKSPUR/api/tools" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"id":"fraeser-8mm","name":"Fräser 8 mm","machine_id":"fraese-1"}'

Die Werkzeug-ID folgt denselben Slug-Regeln wie eine Maschinen-ID. Der Name darf nicht leer sein. machine_id ist optional. Wenn sie gesetzt ist, muss die Maschine existieren. Ein neues Werkzeug beginnt im Zustand ok.

GET /api/tools steht allen angemeldeten Rollen offen. Die Liste enthält ID, Name, Zustand, optionale Maschinen-ID und den Zeitpunkt der letzten Änderung. Es gibt derzeit keinen API-Aufruf zum Umbenennen, Neuzuordnen oder Löschen eines Werkzeugs.

Ein Benutzer ab der Rolle operator setzt den Werkzeugzustand über POST /api/tools/{id}/state:

curl -sS -X POST "$WERKSPUR/api/tools/fraeser-8mm/state" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"state":"broken","reason":"Schneide beschädigt"}'

Erlaubt sind ok, broken und maintenance. Der Grund ist optional und wird im Zustandsereignis gespeichert. Die aktuelle Werkzeugliste zeigt den Grund nicht an. Ein erneuter Wechsel auf denselben Zustand erzeugt kein zusätzliches Ereignis.

Die Maschinenwand im Betrieb

Öffnen Sie „Maschinenwand“, um aktive Maschinen zu beobachten. Jede Karte zeigt den rohen Zustandswert running, idle, down oder maintenance. Darunter stehen die Fähigkeiten und, falls vorhanden, der letzte Zustandsgrund. Bei einem manuellen Wechsel ist das ein Maschinen-Grund-Code, bei einem automatischen Wechsel kann es Freitext sein.

Im Kopf der Seite sehen Sie den Zustand des Live-Datenstroms. Ein eingehendes MachineStateChanged aktualisiert die betroffene Karte sofort. Nach einer Wiederverbindung lädt die Seite die vollständige Maschinenliste neu, damit zwischenzeitlich verpasste Ereignisse nicht fehlen. Über „Terminal“ wechseln Sie direkt zum „Scan-Terminal“.

Die Maschinenwand zeigt keine Werkzeuge, Kostensätze, technischen Zuordnungen oder archivierten Maschinen. Lesen Sie diese Daten bei Bedarf über die genannten API-Endpunkte oder über eigene Ansichten.