SpeamBoxes

Zweck

SpeamBoxes (Speambox) sind die IoT-Gateways der Speam GmbH — sie verbinden Brandmeldeanlagen, Sprinkler, Sicherheits-Beleuchtung und andere Anlagentechnik per Dual-SIM (3G/4G), Ethernet, RS485/RS232/GPIO und MQTT mit der SpeamCore-Plattform. Pro Box pflegen Sie Stammdaten, Sub-Identifier, Konfiguration, Live-Logs, Modul-Verbindungen, Dashboards, Panel-Status und Notification-Streams.

Voraussetzungen

- Hardware-Box mit gueltiger Seriennummer. - Berechtigung `create:Speambox`. - Vorhandener `SpeamboxSystemType` (bestimmt `enabledFeatures` und damit sichtbare Tabs).

Berechtigungen (CASL)

Frontend-Page-Guard:

Action	Subject	Keycloak-Rolle
view	FE_Speambox, Speambox	—
create/update/delete	Speambox	APP_SPEAMCORE_CREATE/UPDATE/DELETE_SPEAMBOX
view	SpeamboxSystemType	APP_SPEAMCORE_VIEW_SPEAMBOX_SYSTEM_TYPE

Tab-Subjects: abhaengig vom jeweiligen Sub-Modell — z. B. view:SpeamboxModule für den Modules-Tab.

Schritt-für-Schritt-Anleitung

Box anlegen

1. SpeamBoxes (/speamboxes) → + Neu.
2. Im Stepper-Modal (SpeamboxCreateStepperModal) den Box-Typ und die Seriennummer auswählen.
3. Anschliessend name, parentId (polymorph), iccidPrimary/iccidSecondary (SIM-Karten), speamboxSystemTypeId pflegen.
4. Änderungen werden automatisch gespeichert (Auto-Submit on Change).

`type` und `serialNumber` sind nach dem ersten Speichern **disabled** — Änderung erfordert Löschen + Neuanlegen.

Box aktivieren — Aktivierungs-Assistent (Mai 2026)

Für die Erst-Inbetriebnahme vor Ort gibt es einen geführten Aktivierungs-Assistenten (SpeamboxActivationWizard). Er führt den Techniker in fester Reihenfolge durch fünf Schritte:

1. Seriennummer — Box-Seriennummer eingeben, „Prüfen" führt die Hardware-Suche durch (die frühere separate Außen-Prüfung ist in diesen Schritt zusammengefasst).
2. Anlagentyp — SpeamboxSystemType auswählen (bestimmt die aktiven Features/Tabs).
3. Installationsanleitung — die hinterlegte Montage-Anleitung wird angezeigt.
4. Modul-Prüfung — angeschlossene Module werden geprüft bzw. angelegt.
5. Standort — GPS-Position speichern. Das Speichern aktiviert die Box zugleich (isActivated=true); der Assistent schließt und springt auf die Box-Detailseite. Einen separaten „Finalisierung"-Schritt gibt es nicht mehr.

Zwischen **Modul-Prüfung** und **Standort** kann ein zusätzlicher Schritt **„Telekom-Check"** erscheinen — aber **nur**, wenn die SIM-Erreichbarkeitsprüfung den Status `fail` liefert (beide SIM-Karten nicht erreichbar). Ist mindestens eine SIM erreichbar oder die Prüfung nicht konfiguriert, bleibt der Schritt unsichtbar. Der Assistent pollt die Prüfung alle 8 Sekunden; sobald wieder eine SIM erreichbar ist, verschwindet der Schritt automatisch.

Der frühere „Verbindungs-Check" (Typron-Online-Polling) wurde entfernt — die Box gilt jetzt als dauerhaft online; die Telekom-Erreichbarkeit ersetzt die Diagnose.

SIM-Erreichbarkeit prüfen (Telekom-Check)

Über GET /api/speamboxes/:id/telekom-check prüft SpeamCore die beiden SIM-Karten (iccidPrimary, iccidSecondary) gegen die Telekom-Schnittstelle. Das Ergebnis:

status	reason	Bedeutung
pass	at-least-one-reachable	Mindestens eine SIM ist erreichbar — alles in Ordnung.
fail	all-iccids-down	Keine SIM erreichbar — löst den Telekom-Schritt im Assistenten aus.
unavailable	no-iccids	An der Box sind keine ICCIDs hinterlegt.
unavailable	not-configured	Die Telekom-Schnittstelle ist im Mandanten nicht konfiguriert.
unavailable	api-unreachable	Die Telekom-API war nicht erreichbar (Prüfung nicht aussagekräftig).

Die Antwort enthält zusätzlich checkedIccids[] und reachableIccids[].

Live-Dashboard nutzen

Tab Dashboard (/speamboxes/:id/dashboard) zeigt Echtzeit-Metriken aus der Box. useSpeamboxLiveEvents() invalidiert die Queries automatisch bei eingehenden Engine-Events.

Speambox-System-Dashboard auf der Startseite (Juni 2026)

Neben dem Live-Dashboard pro Box gibt es ein Speambox-System-Dashboard als eingebaute Kachel auf der Startseite — ein Live-Überblick über alle SpeamBoxen, ohne in die Liste zu wechseln. Es ist Teil des Startseiten-Sliders (HomeDashboardSlider) und wird nicht als eigenes Dashboard in der Datenbank gespeichert (interne ID __speambox_system_dashboard__); die Reihenfolge im Slider merkt sich der Browser lokal.

Aufbau der Kacheln:

• KPI-Karten — Anlagenzahl, aktive Anlagen, aktive Ereignisse (24 h).
• Letzte Alarme — kompakte Liste der jüngsten Ereignisse.
• Letzte Aktivitäten — Tabelle (Anlage, Typ, Status, Letztes Update).
• Systemstatus — Anlagen online/offline, letztes Update.
• Status-Verteilung (Donut) und Live-Karte (geografisch).

Die Kachel ist nur sichtbar mit Berechtigung view:FE_Speambox und view:Speambox.

<KIHinweis titel="„Stille" Ereignisse werden hier ausgeblendet"> Ereignis-Typen oder -Optionen, die als stumm markiert sind (isSilent, siehe Benachrichtigungs-Event-Typen), erscheinen nicht in den System-Dashboard-Kacheln (KPI, Letzte Alarme, Letzte Aktivitäten, Systemstatus). Die Ereignisse werden weiterhin erzeugt und protokolliert — nur die Dashboard-Anzeige wird ruhiger.

Adressierungs-Kontext der Modul-Status (statusContext)

Der Live-Status eines Moduls (SpeamboxModuleStatus) kann pro Statusschlüssel einen Adressierungs-Kontext (statusContext) tragen — ein JSON-Objekt mit optionalen Feldern area (Bereich/Zone), lineNumber (VdS-Linie), detectorGroup (Meldergruppe) und detectorNumber (Meldernummer). Es wird beim Payload-Mapping (VdS 2465-3 / Klartext) befüllt und erlaubt es, eine Meldung präzise zu verorten (z. B. „Störung in Bereich 3, Linie 4"). Bei älteren Payloads ohne Register-Infos bleibt es leer. Diese Angabe ist vor allem für Integratoren relevant.

Toolbar (Detail-Seite)

Schlanke Toolbar oben rechts:

Icon	Aktion (aria-label)	CASL	Wirkung
←	Zurückgehen	—	Zurück zur Liste.
🏠	Zur Startseite gehen	—	Springt auf das Dashboard / /.
⏮/◀/▶/⏭	Pagination	—	Navigation durch die gefilterte Liste — Massen-Bearbeitung ohne Liste-Sprung.

Globale Floating-Drawer (links)

Wie auf jeder Detail-Seite verfuegbar — siehe Floating-Quickbar:

• KAL. (Mini-Kalender)
• ZEIT (Persoenliche Wochen-Arbeitszeit)
• ARBEIT (Eigene bevorstehende Aufträge)

UI-Elemente

Modal: SpeamboxCreateStepperModal

Stepper-Wizard mit Box-Typ-Auswahl, Seriennummern-Eingabe und initialer Parent-Zuordnung.

Komponente: useSpeamboxLiveEvents

React-Hook, der WebSocket-/SSE-Events der Box konsumiert und Queries invalidiert. Stellt Echtzeit-Status-Updates im Dashboard und Panel sicher.

Tab: „Panel"

Zeigt den Live-Status der angeschlossenen Anlage (z. B. „Betrieb", „Störung"). Nur sichtbar wenn Feature showPanel aktiv.

Felder und Eingaben

Feldname	Pflicht	Datentyp	Wirkung beim Ausfuellen	Voraussetzung
type	ja (disabled nach Anlage)	sput112/lite112/spbx01/vcm	Bestimmt Hardware-Klasse, MQTT-Topic-Pattern und unterstuetzte Modul-Typen.	—
serialNumber	ja (disabled nach Anlage)	String	Eindeutige Hardware-ID. Muss mit dem Box-Aufkleber uebereinstimmen.	Eindeutigkeit pro Mandant.
name	ja	String	Anzeigename in Listen, Dashboards, Notifications.	—
speamboxSystemTypeId	nein	UUID	Verknuepfung zu SpeamboxSystemType — bestimmt enabledFeatures und damit sichtbare Tabs.	view:SpeamboxSystemType.
iccidPrimary	nein	String	SIM-Karten-Identifikation (Primaer-SIM).	gültige ICCID.
iccidSecondary	nein	String	Sekundaer-SIM für Dual-SIM-Failover.	gültige ICCID.
parentId + parentType	nein	polymorph	Verknuepft die Box mit Kunde, Standort oder Lager. Bestimmt Sichtbarkeit und Mandanten-Scope.	Parent existiert; passende View-Permission.
panelActiveStatuses	nein	Array String	Status-Array für Panel-Anzeige (z. B. ["betrieb", "stoerung"]).	—
hasIngestApiKey	—	Boolean (read-only)	true bedeutet, dass die Box einen API-Schlüssel zum Datenupload hat.	—

Workflows und Zustaende

Status wird nicht als Feld gespeichert — er ergibt sich aus den LiveEvents und dem zuletzt empfangenen panelActiveStatuses-Update.

Wiederverwendbare Konzepte

• Polymorpher Parent-Pattern — Speambox.parentType ∈ {Customer, Location, Warehouse}.
• Berechtigungen verstehen (CASL)

Verknuepfungen zu anderen Modulen

• Anlagen — Speambox haengt typischerweise an einer Anlage; Anlagen werden über den Standort gefuehrt.
• NotificationEvents — Ereignisse der Box landen im Stream und triggern Subscriptions.
• Module — SpeamboxModule als Sub-Liste pro Box (Sensoren, Aktoren).
• MQTT — pro Box eine Topic-Struktur.

Häufige Fehler und Lösungen

Fehler	Lösung
Box ist offline	Tab Logs auf Verbindungs-Errors prüfen; iccidPrimary und Mobilfunk-Vertrag prüfen.
Tabs sehen anders aus als bei einer anderen Box	SpeamboxSystemType.enabledFeatures ist verschieden — Mandanten-Konfiguration vergleichen.
ICCID wird abgelehnt	Format prüfen — typisch 19–20 Ziffern, ohne Leerzeichen.
Live-Daten kommen verzoegert	Wartung der WebSocket/SSE-Verbindung prüfen.

API/Schnittstellen

Methode	Endpoint	Zweck	CASL
GET	/api/speamboxes	Liste	view Speambox
GET	/api/speamboxes/:id	Detail	view Speambox
GET	/api/speamboxes/:id/telekom-check	SIM-Erreichbarkeit prüfen	view Speambox
POST	/api/speamboxes	Anlegen	create Speambox
PATCH	/api/speamboxes/:id	Ändern	update Speambox
DELETE	/api/speamboxes/:id	Soft-Delete	delete Speambox

Sub-Resourcen über Tab-Sub-Pfade — z. B. GET /api/speamboxes/:id/modules, /notification-events etc.

Versionshinweise

• 2026-06-22: Speambox-System-Dashboard (Startseiten-Kachel, Live-Überblick aller Boxen) dokumentiert; „stille" Ereignisse (isSilent) werden in den Kacheln ausgeblendet; Adressierungs-Kontext statusContext (VdS-Linie/Meldergruppe) ergänzt. Verifiziert an SpeamboxSystemDashboard.tsx, HomeDashboardSlider.tsx, speamboxModuleStatus.model.ts.
• 2026-05-31: Aktivierungs-Assistent (5 Schritte) + bedingter Telekom-SIM-Check dokumentiert; GET /telekom-check-Endpoint ergänzt. Typron-Verbindungs-Check entfällt.
• 2026-04-29: Initiale Veroeffentlichung mit FE-Tiefen-Standard (12 Tabs dokumentiert).