> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/devices/mioty-blueprints.md).
# MIOTY-Blueprints
Dekodieren Sie MIOTY-Payloads in Kilo IoT mit Blueprints — System- vs. Benutzerkatalog und Snapshots pro Gerät.
Ein Blueprint ist die Dekoder-Spezifikation für einen MIOTY-Endpunkt: ein JSON-Dokument, gebunden an ein `typeEui`, das dem Kilo IoT Server sagt, wie eine Roh-Nutzlast in benannte Felder umgewandelt wird. Telemetriedaten eines MIOTY-Geräts werden erst dekodiert, wenn dafür ein Blueprint ausgewählt wurde — das Binden eines Blueprints ist also das, was einen registrierten Endpunkt in ein Gerät verwandelt, das nutzbare Daten liefert.
Blueprints sind als Katalog organisiert: **Hersteller → Gerätemodell → Blueprint**. Ein Hersteller enthält seine Modelle; ein Modell enthält seine Blueprint-Versionen. Die Blueprint-Konfiguration im Geräteformular ist der Ort, an dem Sie entweder aus diesem Katalog auswählen oder einen neuen Eintrag anlegen.
## Die wichtigste Idee: gerätespezifische Snapshots
Wenn Sie einen Blueprint für ein Gerät auswählen, wird er **als unabhängiger Snapshot auf dieses Gerät kopiert**.
Es ist kein Live-Verweis auf den Katalog. Es enthält seine eigene Kopie des Dekoders. Das bedeutet:
* **Das Bearbeiten eines Katalog-Blueprints ändert keine bereits daran gebundenen Geräte.** Sie laufen weiterhin mit der Kopie, mit der sie in Betrieb genommen wurden.
* **Das Löschen eines Katalogeintrags beschädigt keine Geräte, die ihn bereits verwenden.** Sie dekodieren weiterhin mit ihrem Snapshot; der Eintrag verschwindet lediglich aus dem Katalog und kann für neue Geräte nicht mehr gewählt werden.
* **Zwei Geräte desselben Modells können unterschiedliche Blueprints ausführen.** Eine Pilotserie mit einem korrigierten Dekoder und eine Produktionsflotte mit dem bewährten ist ein normaler Zustand, kein Konflikt.
* **Eine neue Version erreicht ein Gerät nur, wenn Sie sie ausdrücklich anwenden.** Nichts an einer Katalogänderung verbreitet sich von selbst.
Dies ist dasselbe Modell, das die Plattform für LoRaWAN-Codecs verwendet, und es existiert aus einem bestimmten Grund: In einer Flotte mit mehreren tausend Endpunkten wäre eine versehentliche Änderung des Dekoders, die unbemerkt umschreibt, wie jede Einheit ihre Nutzlast interpretiert, ein Ausfall, den Sie über Ihre Dashboards entdecken würden. Die Snapshot-Grenze bedeutet, dass Katalogarbeit und Produktionsverhalten getrennte Belange sind. Sie verbessern eine Vorlage frei; Sie rollen sie nach Ihrem Zeitplan aus.
## System- und benutzerdefinierte Kataloge
Der Katalog ist in zwei Bereiche aufgeteilt, und beide werden niemals in einer Liste vermischt — Sie wechseln zwischen ihnen.
| Katalog | Wer ihn sehen und verwenden kann | Wer ihn ändern kann |
| ---------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **System-** | Alle — Hersteller, Modelle und Blueprints können von jeder Organisation verwendet werden | Nur Administratoren. Das Erstellen, Bearbeiten und Löschen von System-Einträgen erfordert einen Administrator. |
| **Benutzerdefiniert-** | Ihre Organisation | Von Ihnen frei verwaltbar — ohne Einschränkung erstellen, bearbeiten und löschen |
Die Verwendung eines System-Blueprints auf einem Gerät erzeugt **nur den Snapshot auf diesem Gerät**. Nichts wird in Ihren benutzerdefinierten Katalog kopiert, und Ihr benutzerdefinierter Katalog bleibt genau so, wie Sie ihn aufgebaut haben.
Die praktische Aufteilung: System deckt die Hardware ab, die die Plattform bereits kennt. Custom ist der Ort, an dem Ihre eigenen Dekoder, Ihre herstellerspezifischen Varianten und Ihre Korrekturen für Firmware-Versionen liegen.
## Verwendung eines vorhandenen Blueprints
Dies ist der Weg für Hardware, die der Katalog bereits abdeckt.
1. Im Geräteformular finden Sie **Blueprint-Konfiguration**.
2. Schalten Sie **Vorhandenen Blueprint verwenden** **EIN**.
3. Wählen Sie im Katalog — **System-** oder **Benutzerdefiniert-**.
4. Wählen Sie den **Hersteller**.
5. Wählen Sie den **Gerätemodell**. Die Liste wird auf die Modelle dieses Herstellers eingegrenzt.
6. Wählen Sie den **Blueprint-Version**.
Die Dekoder-Spezifikation wird schreibgeschützt zur Prüfung angezeigt, und die **Type EUI** wird im Geräteformular automatisch ausgefüllt und ist nicht bearbeitbar — sie stammt aus dem Blueprint. Speichern Sie das Gerät, und der Blueprint wird als Snapshot darauf übernommen.
Sobald das geschehen ist, wird das Gerät bezeichnet als **Angehefteter Snapshot**, sodass Sie auf einen Blick sehen, dass das, was Sie sehen, zu diesem Gerät gehört und nicht zum gemeinsamen Katalogeintrag. Wenn der Katalog-Blueprint, von dem es kopiert wurde, inzwischen gelöscht wurde, lautet das Label **Angehefteter Snapshot (Quellvorlage gelöscht)** — das Gerät bleibt unbeeinträchtigt und dekodiert weiterhin mit seiner eigenen Kopie, aber das Label sagt Ihnen, dass dahinter kein Katalogeintrag mehr zum Vergleichen existiert.
Die **Der erste für ein Modell erstellte Blueprint wird zum Standard für neue Geräte dieses Modells** — sobald ein Modell korrekt eingerichtet ist, besteht die Inbetriebnahme des restlichen Bestands nur noch darin, das Modell auszuwählen.
## Einen neuen Blueprint erstellen
Nehmen Sie diesen Weg, wenn der Katalog Ihre Hardware nicht abdeckt oder wenn eine Firmware-Version anders dekodiert als der vorhandene Eintrag.
1. Schalten Sie **Vorhandenen Blueprint verwenden** **AUS**.
2. **Hersteller** — wählen Sie einen vorhandenen aus oder klicken Sie auf **+ Neuen Hersteller hinzufügen** und benennen Sie ihn.
3. **Neues Gerätemodell** — geben Sie den Modellnamen ein. Wenn er mit einem vorhandenen Modell übereinstimmt, markiert das Formular dies — prüfen Sie, ob Sie stattdessen tatsächlich eine Version zu diesem Modell hinzufügen möchten.
4. **Blueprint-Version** — geben Sie eine Version ein, zum Beispiel `1.0.0`. Version absichtlich, nicht beiläufig; dieser String ist das, womit Ihr Team in einem Jahr zwei Dekoder voneinander unterscheiden wird.
5. **Blueprint-JSON** — fügen Sie die Dekoder-Spezifikation ein. Sie muss gültiges JSON sein und muss eine `typeEui` mit genau 16 hexadezimalen Zeichen enthalten.
6. Wenn die Spezifikation gültig ist, zeigt ein Helfer den geparsten Wert an — **"Type EUI: …"** — und bestätigt damit, woran das Gerät gebunden wird.
7. Klicken Sie auf **Blueprint speichern**. Eine Toast-Meldung bestätigt *"Blueprint erstellt"*, und das neue Modell, die neue Version und die Type EUI werden in das Geräteformular eingetragen.
### Validierungsmeldungen
| Meldung | Was es bedeutet |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **"Blueprint-Spezifikation muss gültiges JSON sein"** | Der eingefügte Text lässt sich nicht parsen. Prüfen Sie auf ein abschließendes Komma, einen abgeschnittenen Einfügevorgang oder typografische Anführungszeichen aus einem Dokument. |
| **"typeEui muss 16 hexadezimale Zeichen lang sein"** | Die `typeEui` Das Feld ist vorhanden, besteht aber nicht genau aus 16 hexadezimalen Zeichen. |
| Eine Meldung, die Sie darauf hinweist, zu **"Vorhandenen Blueprint verwenden"** | Die `typeEui` wird bereits von einem vorhandenen Modell verwendet. Dieser Payload-Typ ist bereits im Katalog — wählen Sie ihn aus, statt einen konkurrierenden Eintrag zu erstellen. |
Letzteres zu verstehen ist wichtiger, als es zu umgehen. Der `typeEui` kennzeichnet einen Payload-Typ. Wenn er bereits existiert, ist der richtige Schritt, das vorhandene Modell zu verwenden — und wenn Sie dafür einen anderen Dekoder benötigen, fügen Sie diesem Modell eine Version hinzu.
## Dekodier-Vorschau
Bevor Sie speichern, verwenden Sie **Dekodier-Vorschau** um den Dekoder mit einer Beispiel-Nutzlast auszuführen und die Felder zu prüfen, die er erzeugt.
Nutzen Sie es. Ein Blueprint, der als JSON geparst werden kann, ist nicht dasselbe wie ein Blueprint, der korrekt dekodiert — Skalierungsfaktoren, Byte-Reihenfolge und vorzeichenbehaftete Werte sind die klassischen Stellen, an denen ein Dekoder syntaktisch perfekt und semantisch falsch ist. Eine Beispiel-Nutzlast mit einem bekannten Wert kostet am Prüfstand eine Minute und erspart Ihnen, das Problem als Temperaturdiagramm zu entdecken, das plausibel aussieht und um den Faktor zehn danebenliegt. Nehmen Sie eine Nutzlast aus der Dokumentation des Geräts oder von einer Einheit, die Sie bereits in Betrieb genommen haben.
## Eine neue Version anwenden
Da Geräte auf Snapshots laufen, erreicht eine neue Blueprint-Version ein Gerät nur, wenn Sie sie anwenden:
1. Erstellen Sie die neue Version unter demselben Hersteller und Modell.
2. Öffnen Sie das Gerät, das Sie umstellen möchten.
3. Wählen Sie in der Blueprint-Konfiguration den neuen **Blueprint-Version**.
4. Speichern.
Rollen Sie zuerst auf ein Gerät aus und bestätigen Sie dessen dekodierte Felder anhand der Live-Nutzlast, bevor Sie die gesamte Flotte umstellen. Das Snapshot-Modell ist es, das diese gestaffelte Ausrollung möglich macht — der Rest der Flotte bleibt unberührt, während Sie prüfen.
## Katalogeinträge löschen
Das Löschen Ihres eigenen Blueprints, Modells oder Herstellers aus dem benutzerdefinierten Katalog ist immer erlaubt.
Wenn Geräte den Eintrag verwenden, erhalten Sie eine **Warnung mit einer Anzahl** der betroffenen Geräte. Diese Geräte funktionieren weiter — sie laufen auf ihren Snapshots. Was sich ändert, ist der Katalog: Der Eintrag verschwindet und kann für neue Geräte nicht mehr gewählt werden.
Lesen Sie die Anzahl vor dem Bestätigen. Das ist kein Hindernis, aber es sagt Ihnen, wie viele Gerätedatensätze jetzt einen Dekoder tragen, hinter dem kein Katalogeintrag mehr steht — was wichtig wird, wenn das nächste Mal jemand versucht, eine passende Einheit in Betrieb zu nehmen und nichts zum Auswählen findet.
Das Löschen eines **System-** Eintrags erfordert einen Administrator.
## Tipps
* **Einmal erstellen, viele in Betrieb nehmen.** Für ein Flotten-Rollout richten Sie den Blueprint auf einem Gerät mit der Dekodier-Vorschau korrekt ein und lassen Sie dann den Modell-Standard den Rest übernehmen.
* **Version nach Firmware, nicht nach Datum.** Wenn ein Hersteller eine Firmware-Revision ausliefert, die die Nutzlast verändert, ist das eine neue Blueprint-Version. Benennen Sie sie so, dass der Zusammenhang offensichtlich ist.
* **Bevorzugen Sie System, wo es passt.** Wenn der System-Katalog Ihre Hardware abdeckt, verwenden Sie ihn — Sie erhalten den Dekoder, ohne dessen Wartung selbst übernehmen zu müssen, und Ihr Gerät erhält trotzdem seinen eigenen Snapshot.
* **Metriken nach dem Dekodieren zuordnen.** Ein Blueprint erzeugt benannte Felder; Metrikvorlagen normalisieren diese Felder in einen herstellerübergreifend gemeinsamen Wortschatz. Siehe [Messwerte](/kilo-docs-de/kilo-iot-server/devices/metric-templates.md).
## Wie geht es weiter
* **Den Endpunkt in Betrieb nehmen** — das MIOTY-Geräteformular Abschnitt für Abschnitt. Siehe [MIOTY-Geräte](/kilo-docs-de/kilo-iot-server/devices/mioty-devices.md).
* **Die dekodierten Felder normalisieren** — ordnen Sie sie dem Messvokabular Ihrer Bereitstellung zu. Siehe [Messwerte](/kilo-docs-de/kilo-iot-server/devices/metric-templates.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/devices/mioty-blueprints.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
