MC4Y CMDB – Home-Assistant-Integration – Schritt für Schritt
============================================================

DEUTSCH
-------
Diese Integration meldet den Rechner, auf dem Home Assistant läuft, samt der von Home Assistant verwalteten
Geräte regelmäßig an die CMDB der MC4Y-Suite. Reine Bestandsaufnahme – keine Zustände, Messwerte oder
Verläufe. Sie richten sie in IHREM eigenen Netz ein; die Daten bleiben in Ihrer Suite.

WELCHER WEG PASST ZU MIR?
  Nehmen Sie diese Integration, wenn Sie Home Assistant (auf einem Raspberry Pi oder unter Windows) nutzen und
  das Gerät samt der dort verwalteten Smart-Home-Geräte in der CMDB sehen möchten. Für gewöhnliche Rechner
  nehmen Sie stattdessen den Agenten aus dem Paket „mc4y-erkennung.zip“.

WAS SIE BRAUCHEN
  • Eine laufende MC4Y-Suite, deren Adresse Sie kennen, und darin ein Konto mit Vollzugriff auf das Modul „CMDB“.
  • Zugriff auf das Konfigurationsverzeichnis von Home Assistant. Am einfachsten über das Add-on „File editor“
    (Studio Code Server geht auch); alternativ über eine Samba-Freigabe oder SSH.
  • Dieses Paket, entpackt – darin der Ordner „custom_components/mc4y_cmdb“.

SCHRITT 1 – EINRICHTUNGSSCHLÜSSEL IN DER SUITE HOLEN
  Melden Sie sich in der Suite an → „Verwaltung › CMDB › 📡 Erkennung“ → „Einrichtungsschlüssel erzeugen“.
  Sie sehen jetzt eine lange Zeichenkette (den Schlüssel). Notieren Sie sich außerdem die Adresse Ihrer Suite.
  TIPP (weniger Schritte): Klicken Sie zusätzlich auf „Einrichtungsdatei herunterladen“. Es wird die Datei
  „mc4y-erkennung.json“ gespeichert, die Adresse und Schlüssel enthält – damit füllt sich der Dialog in Schritt 4
  von selbst aus, und Sie müssen nichts abtippen.

SCHRITT 2 – DIE INTEGRATION IN HOME ASSISTANT KOPIEREN
  Kopieren Sie den Ordner „custom_components/mc4y_cmdb“ aus dem Paket in das Konfigurationsverzeichnis von Home
  Assistant, sodass der Pfad  <config>/custom_components/mc4y_cmdb/  entsteht (mit dem File-editor-Add-on hochladen
  bzw. über Samba/SSH hineinkopieren). Gibt es den Ordner „custom_components“ noch nicht, legen Sie ihn an.
  Sie sehen jetzt im Dateieditor den Ordner „mc4y_cmdb“ mit den Dateien darin.
  Wenn Sie die Datei „mc4y-erkennung.json“ aus Schritt 1 haben, legen Sie sie in denselben Ordner
  (<config>/custom_components/mc4y_cmdb/) oder in den Konfigurationsordner von Home Assistant – dann sind Adresse
  und Schlüssel in Schritt 4 schon ausgefüllt.

SCHRITT 3 – HOME ASSISTANT NEU STARTEN
  „Einstellungen › System“, oben rechts das Menü (⋮) → „Neu starten“ → „Home Assistant neu starten“.
  Sie sehen jetzt nach kurzer Zeit wieder die Anmelde- bzw. Startseite.

SCHRITT 4 – DIE INTEGRATION HINZUFÜGEN
  „Einstellungen › Geräte & Dienste“ → unten rechts „Integration hinzufügen“ → „MC4Y CMDB“ tippen und auswählen.
  Haben Sie die Datei aus Schritt 1 hineingelegt, sind Adresse und Einrichtungsschlüssel schon ausgefüllt – prüfen
  Sie sie und klicken Sie „Senden“. Sonst tragen Sie Adresse und Schlüssel jetzt ein (bei selbst signiertem
  Zertifikat zusätzlich die Zertifikatsdatei). Sie sehen jetzt „MC4Y CMDB“ als konfigurierte Integration.

SO PRÜFEN SIE, OB ES GEKLAPPT HAT
  In der Suite erscheint unter „Verwaltung › CMDB › 📡 Erkennung“ der neue Agent. Sofort melden: in Home Assistant
  unter „Entwicklerwerkzeuge › Aktionen“ (ältere Fassungen: „Dienste“) die Aktion  mc4y_cmdb.melden_jetzt  ausführen;
  danach steht das Gerät im Modul „CMDB“.

HÄUFIGE PROBLEME
  • „MC4Y CMDB“ erscheint nicht in der Liste: Liegt der Ordner wirklich unter <config>/custom_components/mc4y_cmdb/?
    Wurde Home Assistant danach neu gestartet?
  • Anmeldung abgelehnt: Der Einrichtungsschlüssel gilt nur begrenzt – in der Suite einen neuen erzeugen.
  • Firewall: nur AUSGEHEND HTTPS (Port 443) zur Suite ist nötig; auf dem Gerät muss kein Port geöffnet werden.
  • Virenscanner: auf dem Home-Assistant-Gerät üblicherweise kein Thema; läuft Home Assistant unter Windows mit
    einem Virenscanner, nehmen Sie den Ordner wie beim Agenten als Ausnahme auf.

AKTUALISIEREN UND ENTFERNEN
  • Aktualisieren: den neuen Ordner „mc4y_cmdb“ kopieren (den alten ersetzen), Home Assistant neu starten.
  • Entfernen: unter „Geräte & Dienste“ die Integration „MC4Y CMDB“ löschen – dabei wird der Agent in der Suite
    abgemeldet. Danach kann der Ordner „custom_components/mc4y_cmdb“ gelöscht werden.

FÜR FACHLEUTE
  Die Integration wird als einfacher custom_components-Ordner geliefert (HACS wird nicht benötigt). Übertragen
  werden nur Bestandsdaten und Gerätenamen (z. B. Raumnamen) als Bestandteile – keine Zustände oder Messwerte.
  Gesendet wird nur an die eingetragene Suite über HTTPS; keine Telemetrie, keine Abfrage fremder Server.


ENGLISH
-------
This integration regularly reports the machine running Home Assistant and the devices it manages to the CMDB of
the MC4Y suite. Inventory only – no states, measurements or history. You set it up in YOUR own network; the data
stays in your suite.

WHICH WAY SUITS ME?
  Use this integration if you run Home Assistant (on a Raspberry Pi or on Windows) and want that machine and the
  smart-home devices it manages to appear in the CMDB. For ordinary computers, use the agent from the
  "mc4y-erkennung.zip" package instead.

WHAT YOU NEED
  • A running MC4Y suite whose address you know, and an account there with full access to the "CMDB" module.
  • Access to the Home Assistant configuration directory. Easiest with the "File editor" add-on (Studio Code
    Server works too); alternatively via a Samba share or SSH.
  • This package, unpacked – it contains the folder "custom_components/mc4y_cmdb".

STEP 1 – GET THE SETUP KEY IN THE SUITE
  Sign in to the suite → "Administration › CMDB › 📡 Discovery" → "Create setup key". You now see a long string
  (the key). Also note the address of your suite.
  TIP (fewer steps): also click "Download setup file". It saves the file "mc4y-erkennung.json" containing the
  address and key – with it the dialog in step 4 fills itself in and you need not type anything.

STEP 2 – COPY THE INTEGRATION INTO HOME ASSISTANT
  Copy the folder "custom_components/mc4y_cmdb" from the package into the Home Assistant configuration directory so
  that the path  <config>/custom_components/mc4y_cmdb/  exists (upload it with the File editor add-on, or copy it in
  via Samba/SSH). If the "custom_components" folder does not exist yet, create it.
  You now see the "mc4y_cmdb" folder with its files in the file editor.
  If you have the file "mc4y-erkennung.json" from step 1, place it in the same folder
  (<config>/custom_components/mc4y_cmdb/) or in the Home Assistant configuration folder – then the address and key
  are already filled in at step 4.

STEP 3 – RESTART HOME ASSISTANT
  "Settings › System", top-right menu (⋮) → "Restart" → "Restart Home Assistant".
  You now see the login/start page again after a short while.

STEP 4 – ADD THE INTEGRATION
  "Settings › Devices & Services" → bottom right "Add integration" → type and pick "MC4Y CMDB".
  If you placed the file from step 1, the address and setup key are already filled in – check them and click
  "Submit". Otherwise enter the address and key now (for a self-signed certificate, also the certificate file).
  You now see "MC4Y CMDB" listed as a configured integration.

HOW TO CHECK IT WORKED
  In the suite, the new agent appears under "Administration › CMDB › 📡 Discovery". To report at once, run the
  action  mc4y_cmdb.melden_jetzt  under "Developer tools › Actions" (older versions: "Services"); the device then
  appears in the "CMDB" module.

COMMON PROBLEMS
  • "MC4Y CMDB" not in the list: is the folder really at <config>/custom_components/mc4y_cmdb/? Was Home Assistant
    restarted afterwards?
  • Sign-in refused: the setup key is valid for a limited time only – create a new one in the suite.
  • Firewall: only OUTBOUND HTTPS (port 443) to the suite is required; no port needs to be opened on the device.
  • Virus scanner: usually not an issue on the Home Assistant device; if Home Assistant runs on Windows with a
    virus scanner, add the folder as an exception as for the agent.

UPDATING AND REMOVING
  • Update: copy the new "mc4y_cmdb" folder (replacing the old one), restart Home Assistant.
  • Remove: under "Devices & Services", delete the "MC4Y CMDB" integration – this de-registers the agent in the
    suite. You can then delete the "custom_components/mc4y_cmdb" folder.

FOR EXPERTS
  The integration ships as a plain custom_components folder (HACS is not required). Only inventory data and device
  names (e.g. room names) are transmitted as components – no states or measurements. Sent only to the entered
  suite over HTTPS; no telemetry, no query to outside servers.


License: GPL-3.0-or-later – MY COACHING FOR YOU (https://www.my-coaching4you.de)
