enstadtpfaff-platform-mock-api v0.5.2

enstadtpfaff-platform-mock-api - Dokumentation

enstadtpfaff-platform-mock-api ist das Software Development Kit (SDK) für den EnStadt:Pfaff Platform Mock. Vorliegend handelt es sich um die Version für JavaScript-basierte Projekte (JavaScript, TypeScript, NodeJS, ...).

Derzeit wird primär die Kommunikation mit dem zentralen EventBroker des Platform Mock unterstützt. Hierzu stellen wir sogenannte EventBuilder bereit, die das Erstellen konformer Event-Nachrichten unterstützen. Weiterhin unterstützen wir das Veröffentlichen sowie das Empfangen von Event-Nachrichten.

TL;DR

npm install enstadtpfaff-platform-mock-api

import { connect, createEvent, Event, nameForSharedTopic, smartHomeEventBuilder } from 'enstadtpfaff-platform-mock-api';

const platformMockApi = connect(
  process.env.MQTT_ADDRESS as string,
  process.env.MQTT_USERNAME as string,
  process.env.MQTT_PASSWORD as string,
  'meine-tolle-applikation',
  function (event: Event) {
    console.log('message arrived on topic ' + event.topic + ': ' + event.payload);
  }
);

const eventBroker = platformMockApi.eventBroker;
eventBroker.subscribe(nameForSharedTopic('smart-home'));
eventBroker.publish(
  smartHomeEventBuilder.indoorClimate(
    'mein-haus',
    'mein-stock',
    'meine-einheit',
    'my-room',
    'my-device',
    {
      currentTemperature: 22,
      targetTemperature: 12,
      thermostatMode: 'OFF',
      currentHeatingPower: 0,
    }
  )
);

TODO

enstadtpfaff-platform-mock-api ist das Software Development Kit (SDK) für den EnStadt:Pfaff Platform Mock. Vorliegend handelt es sich um die Version für JavaScript-basierte Projekte (JavaScript, TypeScript, NodeJS, ...).

Derzeit wird primär die Kommunikation mit dem zentralen EventBroker des Platform Mock unterstützt.

Hierzu stellen wir sogenannte EventBuilder bereit, die das Erstellen konformer Event-Nachrichten unterstützen. Weiterhin unterstützen wir das Veröffentlichen sowie das Empfangen von Event-Nachrichten. Das Veröffentlichen bezeichnen wir als publish. Zum Empfangen ist ein subscribe auf das beziehungsweise die jeweiligen Topics notwendig. Für eingehende Event-Nachrichten wird der sogenannte EventHandler aufgerufen, in dem eigene Logik implementiert werden kann.

Event-Nachrichten haben keinen Empfänger, sie werden auf Topics veröffentlicht. Die Topics des EventBroker unterliegen den Regeln des Topic-Management, die von allen einzuhalten sind.

EventBroker

Der EventBroker ist ein zentrales Element des EnStadt:Pfaff Platform Mock und soll ein dynamisches Zusammenspiel verschiedenster Akteure ermöglichen. Im Detail haben wir uns für MQTT als technische Lösung entschieden. Die Artikelserie MQTT Essentials ist in diesem Zusammenhang besonders empfehlenswert.

Im Wesentlichen verstehen wir die Topics des EventBroker als asynchrone, öffentliche Informationskanäle zum Austausch interessanter Fakten. Diese Fakten werden als Event-Nachrichten veröffentlicht und können von daran interessierten Akteuren empfangen werden. Das zugrundeliegende Muster wird als Publish-Subscribe Pattern bezeichnet.

In software architecture, publish–subscribe is a messaging pattern where senders of messages, called publishers, do not program the messages to be sent directly to specific receivers, called subscribers, but instead categorize published messages into classes without knowledge of which subscribers, if any, there may be. Similarly, subscribers express interest in one or more classes and only receive messages that are of interest, without knowledge of which publishers, if any, there are.

-- Wikipedia

Hierbei ist wichtig zu verstehen und zu verinnerlichen, dass Event-Nachrichten nicht an spezifische Empfänger adressiert sind. Sie werden lediglich auf einem bestimmten Topic veröffentlicht und vom EventBroker an jene Akteure ausgeliefert, die über ein entsprechendes, aktives Abonnement (Subscription) verfügen. Folglich dürfen keine Annahmen darüber getroffen werden, von wem und/oder ob eine Event-Nachricht überhaupt empfangen/verarbeitet wird.

Durch das Veröffentlichen (publish) von Event-Nachrichten können Informationen beigetragen werden, die für andere Akteure möglicherweise interessant sind. Interessierte Akteure können sich auf die für sie interessanten Informationskanäle (Topics) subscriben und so von den Informationen profitieren.

Auf dieser Grundlage sollen Akteure - meist handelt es sich dabei um Dienste - vernetzt werden, ohne starke Abhängigkeiten einzuführen. Darüber hinaus können neue Akteure jederzeit an das System andocken und sich integrieren.

Der EventBroker des EnStadt:Pfaff Platform Mock als Herzstück ermöglicht damit ein Ökosystem für Dienste, welches innovative Erweiterungen und insbesondere auch die Partizipation Dritter zulässt. Jeder kann einen Dienst entwickeln, der Event-Nachrichten veröffentlicht, empfängt oder sogar beides tut. Es bedarf lediglich kreativer Ideen, die sich der Plattform bedienen und andocken.

Damit ein solches Zusammenspiel zwischen verschiedenen Akteuren gelingen kann, bedarf es einiger Regeln. Wir möchten verhindern, dass Akteure beliebige Inhalte auf beliebigen Topics veröffentlichen. Dadurch würde nämlich nur Chaos entstehen. Unterschiedliche Topic-Namen, Nachrichtenformate, Inhalte und Semantiken behindern die von uns angestrebten Kooperationsmöglichkeiten. Für die Informationskanäle ist deshalb eine Ordnung notwendig, über die es einen gemeinsamen Konsens gibt. Unser Konzept dazu und die erarbeiteten Regeln bezeichnen wir mit dem Begriff Topic-Management.

Topic-Management

Mit dem Begriff Topic-Management bezeichnen wir unser Konzept und die Regeln zur Kommunikation über den EventBroker.

Wir sehen die Notwendigkeit, Ordnung bezüglich der Topics des EventBroker zu schaffen, um eine sinnvolle Kooperation zwischen den beteiligten Akteuren zu ermöglichen. Gleichzeitig erkennen wir an, dass es gewisse Freiheiten geben sollte, um neue Innovationen oder spezifische Anforderungen nicht von vornherein auszuschließen.

Aus diesem Grund unterteilen wir die Topics des EventBrokers in zwei grundlegende Bereiche: 1. Shared Topics (das sind die "Informationskanäle") 2. Service Specific Topics (Freiraum für spezifische ad-hoc Konzepte)

Aufbau und Inhalte der Shared Topics sind erschöpfend spezifiziert und alle Akteure müssen sich an die Spezifikation halten. Im Gegenzug dürfen sie sich auf die vorgegebenen Topic-Strukturen, Formate, Inhalte und Bedeutungen verlassen. Der Plattformbetreiber hat die Hoheit über die Spezifikation und veröffentlicht diese. Erweiterungen und Anpassungen sind möglich und können "von der Community" angeregt und diskutiert werden. Letztendlich müssen sie jedoch vom Plattformbetreiber - oder durch einen von ihm eingerichteten Community-Prozess - beschlossen und verabschiedet werden. Idealerweise sind Anpassungen abwärtskompatibel, sodass bestehende Akteure weiterhin funktionieren. Darüber hinaus sollten Erweiterungen nur neue Aspekte abdecken, die noch nicht anderweitig adressiert sind, um Dopplungen und/oder Unklarheiten zu vermeiden. Für einen Akteur sollte es keine Unsicherheit darüber geben, zu welchem Topic eine Information gehört.

Service Specific Topics sind - wie der Namen impliziert - spezifisch für einen Dienst. Dem Dienst wird ein eigener, individueller Namensraum bezüglich der Topics zugeordnet, über den allein er die Hoheit hat. Um Namenskonflikte zu vermeiden, werden Servicebezeichner vom Plattformbetreiber vergeben. Alternativ können "reversed Internet domain names" verwendet werden (Beispiel: de.pfaffhack.ride-sharing).

Das ist für eine Kooperation mit anderen Akteuren jedoch nicht unbedingt förderlich, da diese sich von den spezifischen Details eines Dritten abhängig machen. So wäre es für das Ökosystem als Ganzes eher ungünstig, wenn beispielsweise verschiedene Smart Home Gerätehersteller eigene, separate Topics verwenden, statt eines gemeinsamen. Wir empfehlen daher, möglichst auf den Einsatz von Service Specific Topics zu verzichten und stattdessen Shared Topics einzusetzen beziehungsweise zu deren Weiterentwicklung beizutragen.

Service Specific Topics können für schnelles und spontanes Prototyping verwendet werden, wenn zum Beispiel noch kein geeignetes Shared Topic existiert. Sie können als Testballone fungieren und erlauben die Erprobung von Innovationen ohne einen strikten Spezifikationsprozess einhalten zu müssen. In solchen Fällen ist anzustreben, florierende Service Specific Topics in ein Shared Topic zu überführen, um das gesamte Ökosystem an der Neuerung teilhaben zu lassen.

Faustregeln:

• Verwende Shared Topics wann immer möglich
• Halte dich strikt an die Spezifikation des jeweiligen Shared Topics
• Trage zur Erweiterung / Anpassung der Shared Topics durch Vorschläge bei
• Verwende Service Specific Topics wenn du etwas Neues ausprobieren möchtest
• Halte dich strikt an die Spezifikation des jeweiligen Service Specific Topic
• Strebe die Transformation von Service Specific Topics zu Shared Topics an - alle sollen an deiner Innovation teilhaben
• Was sich nicht zu einem Shared Topic überführen lässt, hat vielleicht gar nichts auf dem EventBroker zu suchen

Topics sind hierarchisch aufgebaut, die Hierarchiestufen werden durch / getrennt. Für die Topics des EventBroker geben wir folgende Struktur vor:

• Shared Topics: platform-mock/shared/{shared-topic-id}[/{topic-specific-stuff}]
• Service Specific Topics platform-mock/services/{service-id}[/{topic-specific-stuff}]

Beispiele:

Das Shared Topic hints besteht lediglich aus platform-mock/shared/hints.

Das Shared Topic appointments besteht aus platform-mock/shared/appointments/appointment-created, platform-mock/shared/appointments/appointment-updated und platform-mock/shared/appointments/appointment-deleted.

Die Lösung smart-metering möchte etwas Neues ausprobieren und dafür ein Service Specific Topic verwenden. Sie hat die Hoheit über das Topic platform-mock/services/smart-metering und alle Topics, die mit platform-mock/services/smart-metering/ beginnen. Denkbar wären platform-mock/services/smart-metering, platform-mock/services/smart-metering/data, platform-mock/services/smart-metering/report, ... .

Verfügbare Shared Topics

appointments

Installation der Abhängigkeit

Unser Package ist im offiziellen Repository hinterlegt und kann mithilfe von npm viel folgt installiert werden:

npm install enstadtpfaff-platform-mock-api

Verbindungsaufbau

import {
  connect,
  createEvent,
  Event,
  smartHomeEventBuilder,
  nameForSharedTopic,
} from 'enstadtpfaff-platform-mock-api';

const platformMockApi = connect(
  process.env.MQTT_ADDRESS as string, // Konfiguration ueber Umgebungsvariablen statt hardcoded
  process.env.MQTT_USERNAME as string,
  process.env.MQTT_PASSWORD as string,
  'meine-tolle-applikation', // hier den Namen der Applikation eintragen
  function (event: Event) {
    // hier kann eigene Logik zur Verarbeitung von empfangenen Events platziert werden
    console.log(
      'message arrived on topic ' + event.topic + ': ' + event.payload
    );
  }
);

const eventBroker = platformMockApi.eventBroker;
// Subscribe auf das shared-topic 'smart-home'
eventBroker.subscribe(nameForSharedTopic('smart-home'));

// Veroeffentlichen eines Events
eventBroker.publish(

  // Der smartHomeEventBuilder unterstuetzt beim Erstellen valider Events fuer das 'smart-home' shared-topic
  //  und kuemmert sich um die Auswahl der passenden Topics.
  //  moderne Entwicklungsumgebungen oder beim Einsatz von TypeScript werden Vorschlaege unterbreitet 
  //  und der Code statisch ueberprueft.
  smartHomeEventBuilder.indoorClimate(
    'mein-haus',
    'mein-stock',
    'meine-einheit',
    'my-room',
    'my-device',
    {
      currentTemperature: 22,
      targetTemperature: 12,
      thermostatMode: 'OFF',
      currentHeatingPower: 0,
    }
  )

);

EventBuilder zu den shared topics

appointments

Hier werden Kalendereinträge veröffentlicht (genauer: deren Erstellung, Veränderung, Löschung)

import { appointmentsEventBuilder } from 'enstadtpfaff-platform-mock-api';

hints

Hier werden Ratschläge / Tipps veröffentlicht

import { hintsEventBuilder } from 'enstadtpfaff-platform-mock-api';

smart-home

Hier werden Zustandsänderungen von Smart-Home Geräten veröffentlicht

import { smartHomeEventBuilder } from 'enstadtpfaff-platform-mock-api';