# Zustände (Traits)

Traits bieten die Möglichkeit, den Zustand von Ressourcen zu ändern. Ressourcen können mehrere Traits besitzen und diese kombiniert nutzen. Mit Traits erhalten Nutzer Zugriff auf die Ressource, nachdem sie einen [Claim](https://docs.fab-access.org/books/was-ist-fabaccess-grundkonzepte/page/claims-notify-und-interest-das-konzept-vom-anspruch-erheben "Claims, Notify und Interest (das Konzept vom "Anspruch erheben")") erhalten haben. Dabei können Traits verwendet werden, um Ressourcen aus bestehenden Traits zusammenzusetzen oder spezifische Traits zu implementieren. Um eine optimale Anzeige der Traits für Nutzer in Clients zu ermöglichen, kann einer Ressource ein "Hint" hinzugefügt werden. Dieser ermöglicht es einem Client, eine verbesserte Ansicht der Ressource für Nutzer zu generieren.

## Traits und OIDs

Traits werden anhand einer [OID (Object Identifier)](https://docs.fab-access.org/books/awesome-fabinfra/page/glossar-begrifflichkeiten-und-abkurzungen#bkmrk-oid-%28object-identifi) bereitgestellt. Die OID-Struktur von FabAccess folgt dem Schema:

```mysql
1.3.6.1.4.1.61783.612.1.2
              │    │  │ │
  RLKM UG PEN ╯    │  │ │
                   │  │ │
 FabAccess subtree ╯  │ │
                      │ │
               Traits ╯ │
                        │
               Doorable ╯
```

Für das Projekt wurde eine gesonderte [Private Enterprise Numer (PEN)](https://docs.fab-access.org/books/awesome-fabinfra/page/glossar-begrifflichkeiten-und-abkurzungen#bkmrk-pen-%28private-enterpr "Glossar (Begrifflichkeiten und Abkürzungen)") bei IANA auf "FabInfra" registiert. Das feste PEN-Präfix lautet `1.3.6.1.4.1`. Die PEN-Nummer für RLKM lautet `61783` (Siehe [https://www.iana.org/assignments/enterprise-numbers/?q=61783](https://www.iana.org/assignments/enterprise-numbers/?q=61783).). Das Projekt FabAccess hat eine fest vergebene Unternummer `612`. Danach folgt die Unterklasse `1` (Traits) und dann die möglichen Zustandsnummern (Enumeration) `0` ... `5` (z.B. Doorable, Locatable, ...).

<p class="callout info">In älteren Versionen der API wurde die [PEN 48398](https://www.iana.org/assignments/enterprise-numbers/?q=48398) genutzt ("Paranoidlabs").</p>

Die OID-Bezeichner werden in der Zustandsdatenbank abgespeichert. Siehe auch [Datenbeispiel eines Dumps](https://docs.fab-access.org/books/fabaccess-konfiguration/page/cheat-sheet-wichtigste-befehle-ubersicht#bkmrk-datenbeispiel-eines-).

## Übersicht über die vorhandenen Traits und OIDs

In FabAccess gibt es bereits vordefinierte Traits für grundlegende Funktionen, mit denen viele Zustände von Ressourcen abgebildet werden können.

### FabAccess-API

<p class="callout success">Aktuell ist diese API in Verwendung. Siehe [https://gitlab.com/fabinfra/fabaccess/fabaccess-api](https://gitlab.com/fabinfra/fabaccess/fabaccess-api)</p>

In diesem API-Modell gibt es nur die folgenden [7 Zustände](https://gitlab.com/fabinfra/fabaccess/fabaccess-api/-/blob/main/machine.capnp?ref_type=heads#L15) (Traits) von 0 bis 6:

- 0: `Free` - eIne Ressource frei verfügbar für Nutzer mit Zugriff machen
- 1: `InUse:<UserId>` - eine Ressource durch einen Nutzer "In Benutzung" setzen
- 2: `ToCheck:<UserId>` - eine Ressource auf "muss überprüft werden" setzen (z.B. ob Reinigung nach Benutzung notwendig ist) - **Achtung**: Dieser Zustand kann nur über die [API](https://docs.fab-access.org/books/schnittstellen-und-apis/page/fabaccess-api "FabAccess API") und nicht über Client genutzt werden (weil nicht implementiert. Siehe auch [eine Ressource bedienen](https://docs.fab-access.org/books/fabaccess-konfiguration/page/client-benutzen-und-typische-konfigurationsfehler-bei-server-und-clients#bkmrk-eine-ressource-bedie))
- 3: `Blocked:<UserId>` - eine Ressource blockieren (z.B. weil die Maschine defekt ist)
- 4: `Disabled` - eine Ressource deaktivieren (z.B., weil die Ressource zum aktuellen Zeitpunkt zu laut wäre und deshalb die Benutzung verboten ist)
- 5: `Reserved:<UserId>` - eine Ressource für die spätere Nutzung vorreservieren - **Achtung**: dieser Zustand kann aus dem Borepin Client nicht gesetzt werden (Siehe auch [eine Ressource bedienen](https://docs.fab-access.org/books/fabaccess-konfiguration/page/client-benutzen-und-typische-konfigurationsfehler-bei-server-und-clients#bkmrk-eine-ressource-bedie)), jedoch im [Process Aktor](https://docs.fab-access.org/books/fabaccess-konfiguration/page/hauptkonfiguration-bffhdhall#bkmrk-process-actor "Hauptkonfiguration - bffh.dhall") und im [Python Process Actor Template](https://docs.fab-access.org/books/plugins-aktoren-initiatoren/page/aktor-generisches-python-template-fur-process "Aktor: Generisches Python-Template für "Process"") schon
- 6: `totakeover` - eine Maschine von einem anderem Nutzer übernehmen - **Achtung**: dieser Zustand ist weder in BFFH, noch im [Process Aktor](https://docs.fab-access.org/books/fabaccess-konfiguration/page/hauptkonfiguration-bffhdhall#bkmrk-process-actor "Hauptkonfiguration - bffh.dhall"), noch im [Python Process Actor Template](https://docs.fab-access.org/books/plugins-aktoren-initiatoren/page/aktor-generisches-python-template-fur-process "Aktor: Generisches Python-Template für "Process"") implementiert. Dieser Zustand existiert aktuell nur in der API-Beschreibung.

Neben den definierten Zuständen gibt es auch die Möglichkeit, direkte Rohdaten zu liefern:

- `Raw:<data>` - Ressourcen können bei Statuswechsel auch direkt mit Binärdaten versorgt werden, um zum Beispiel spezielle Operationen wie das Übersenden einer STL-Datei an einen 3D-Drucker zu erlauben

<p class="callout warning">Die API verwendet in einen OID-Wert (value) `<span class="s">1.3.6.1.4.1.48398.612.2.4</span>` vom OID-Typ (type) `<span class="s">1.3.6.1.4.1.48398.612.2.14</span>` für den Zustand (state) im Allgemeinen.</p>

<details id="bkmrk-prodable-kommt-vom-e"><summary>Prodable</summary>

Kommt vom englischen Wort "prodded" und bedeutet soviel wie "anstubsen". Ein Prodable ist also etwas Anstubsbares. Das lässt sich im Sinne einer Ereignisschleife verstehen, in der eine Sache die Möglichkeit hat, etwas zu tun. Wird im [BFFH Server](https://gitlab.com/fabinfra/fabaccess/bffh/-/blob/feature/cardloginwithtoken/bffhd/capnp/machine.rs?ref_type=heads) verwendet - es findet Nutzen beim [FabLock](https://docs.fab-access.org/books/schliessfacher-locker/page/ikea-kallax-regal-mit-fablock "FabLock"). Dort hat es den Zweck vor dem Öffnen eines Schließfachs in einem Spind mit mehreren Fächern vorher kurz eine LED aufleuchten zu lassen, die signalisiert, wo genau sich das Fach befindet.

Prodable protokollieren keine Ressourcennutzung durch einen Nutzer.

Der `Prodable` Trait existiert namentlich so in der neuen C# API nicht mehr - er wurde in `Locatable` umbenannt. Weiterhin gibt es spezialisierte Traits `Doorable` für Eingangstüren und `Lockers` für Schließfächer.

</details>### FabAccess-API-cs

<p class="callout warning">Diese API Version ist aktuell noch nicht in Verwendung. Siehe [https://gitlab.com/fabinfra/fabaccess/fabaccess-api-cs](https://gitlab.com/fabinfra/fabaccess/fabaccess-api-cs)</p>

<details id="bkmrk-claimable-der-trait-"><summary>Claimable (OID 1.3.6.1.4.1.61783.612.1.0)</summary>

Der Trait "Claimable" stellt einen Sonderfall dar, da er dazu dient, dass sich ein Nutzer über den Claim-Zustand einer Ressource informieren kann.

Nutzer können auf diesem Trait keine Aktionen ausführen, sondern lediglich den Zustand abfragen.

</details><details id="bkmrk-powerable-%22powerable"><summary>Powerable (OID 1.3.6.1.4.1.61783.612.1.1)</summary>

"Powerable" ist der grundlegendste Trait, den FabAccess unterstützt. Er dient dazu abzubilden, ob eine Ressource eingeschaltet bzw. mit Strom versorgt ist.

</details><details id="bkmrk-doorable-der-trait-%22"><summary>Doorable (OID 1.3.6.1.4.1.61783.612.1.2)</summary>

Der Trait "Doorable" ermöglicht die Abbildung von Türen oder anderen Schließsystemen. Dabei besteht die Möglichkeit, kurzzeitige Öffnungen zu realisieren. Die genaue Zeitdauer, für die die Ressource geöffnet wird, wird dabei vom Server bestimmt.

**[](#states)States**

[![doorable.png](https://docs.fab-access.org/uploads/images/gallery/2024-10/scaled-1680-/SHOdTUHcQgWn0042-doorable.png)](https://docs.fab-access.org/uploads/images/gallery/2024-10/SHOdTUHcQgWn0042-doorable.png)

**als Mermaid**

```markdown
stateDiagram
    [*] --> CLOSED
    CLOSED --> OPEN: unlock
    OPEN --> CLOSED: lock
    CLOSED --> tempOPEN: unlocktemp
    tempOPEN --> OPEN: unlock
    tempOPEN --> CLOSED: lock
    tempOPEN --> CLOSED: AUTO
```

</details><details id="bkmrk-checkable-checkable-"><summary>Checkable (OID 1.3.6.1.4.1.61783.612.1.3)</summary>

Der komplexere Trait "Checkable" ermöglicht die Abbildung von Ressourcen, die nach der Benutzung überprüft werden müssen. Bei einer Überprüfung durch einen berechtigten Nutzer kann die Ressource entweder für alle wieder freigegeben oder zurückgewiesen werden. Falls die Ressource zurückgewiesen wurde, kann der ursprüngliche Nutzer die Ressource weiterhin verwenden oder erneut zur Überprüfung einreichen, nachdem die Fehler behoben wurden.

**States**

**[![checkable.png](https://docs.fab-access.org/uploads/images/gallery/2024-10/scaled-1680-/Z21hZBWfcYHz9PtP-checkable.png)](https://docs.fab-access.org/uploads/images/gallery/2024-10/Z21hZBWfcYHz9PtP-checkable.png)**

**als Mermaid**

```markdown
stateDiagram
    [*] --> FREE
    FREE --> INUSE: use
    INUSE --> CHECK: giveback
    CHECK --> FREE: accept
    CHECK --> REJECTED: reject
    REJECTED --> INUSE: use
    REJECTED --> CHECK: giveback
    REJECTED --> FREE: accept
```

</details><details id="bkmrk-lockers-%22lockers%22-is"><summary>Lockers (OID 1.3.6.1.4.1.61783.612.1.4)</summary>

"Lockers" ist einer der komplexeren Traits, mit dem Schlösser von Ressourcen genauer abgebildet werden können. Der Nutzer kann die Ressource nicht in jedem Zustand zurückgeben; erst wenn alles korrekt zurückgegeben wurde, kann die Ressource auch wieder gesperrt werden.

Die Zustandsänderungen zwischen den vom Nutzer verwendbaren Übergängen können von einem Initiator herbeigeführt werden.

**States**

[![lockers.png](https://docs.fab-access.org/uploads/images/gallery/2024-10/scaled-1680-/LxDF7zhhMfekZwaH-lockers.png)](https://docs.fab-access.org/uploads/images/gallery/2024-10/LxDF7zhhMfekZwaH-lockers.png)

**als Mermaid**

```markdown
stateDiagram
    [*] --> locked
    locked --> unlocked: unengage
    unlocked --> locked: engage
    unlocked --> open: AUTO
    open --> unengaged: AUTO
    unengaged --> locked: engage
    unengaged --> open: AUTO
```

</details><details id="bkmrk-locatable-der-trait-"><summary>Locatable (OID 1.3.6.1.4.1.61783.612.1.5)</summary>

Der Trait "Locatable" ermöglicht die Identifizierung von Ressourcen, wie beispielsweise Schließfächer oder 3D-Drucker in einer Druckerfarm. Dabei kann entweder eine kurzfristige Identifikation abgegeben werden oder die Identifizierung dauerhaft gesetzt werden.

</details><p class="callout info">**Hinweis:** Die Mermaid-Diagramme sind mit [https://mermaid.live](https://mermaid.live) gerendert und als PNG exportiert und hier importiert worden, da BookStack keinen integrierten Mermaid Renderer besitzt.</p>