Software-Schnittstellen: Beschreibung konform IEC 62304

Software-Systeme sollten aus Komponenten bestehen, die über Software-Schnittstellen miteinander kommunizieren.

Dokumentation von Software-Schnittstellen

Spezifikationen sollten das spezifizierte Objekt als Blackbox d.h. über dessen Schnittstellen beschreiben. Das gilt für Systeme (z.B. physische Geräte mit Medizingeräte (PEMS) oder stand-alone Software-System) ebenso wie für Komponenten solcher Systeme (z.B. Programmierbare Elektrische Subsysteme PESS oder Softwarekomponenten). Software verfügt über drei Schnittstellentypen:

1. Benutzer-System-Schnittstellen (User Interface, GUI)
2. System-System-Schnittstellen (Datenschnittstellen wie APIs, BUS-Systeme, Sensoren, Aktoren, Webservices)
3. Schnittstelle zur Laufzeitumgebung

1. Schritt: Übersicht über die Software-Schnittstellen mit Komponentendiagrammen

Wie granular Sie die Software-Schnittstellen spezifizieren müssen, legen Normen wie die IEC 62304 nicht fest. Sie müssen die Schnittstellen aber dokumentieren.

Der erste und einfachste Schritt besteht darin, die Schnittstellen überhaupt in der Software-Architektur kenntlich zu machen. Hier empfehlen sich Komponenten-Diagramme und die Lolipop-Notation (siehe Abb. 1). Die Lollipops helfen Ihnen besonders gut zu visualisieren, welche Schnittstellen es gibt, welche Software-Komponenten die Schnittstellen implementieren und welche Komponenten die Schnittstellen anderer Komponenten nutzen.

2. Schritt: Beschreibung der Software-Schnittstellen

Eine bloße Nennung der Schnittstellen ist aber noch etwas zu wenig, sowohl um Normenkonformität zu erreichen als auch um den eigentlichen Sinn dieser Dokumentation zu erreichen: Den Entwicklern und den Komponenten-Testern ausreichend Informationen für deren Arbeit zu geben.

Programmierschnittstellen API

Daher besteht der nächste Schritt darin, die API der Schnittstellen zu formulieren. Erst damit spezifizieren Sie wirklich die Komponenten. Die API beschreibt:

1. Namen und Zweck der nach außen verfügbaren Funktionen/Methoden
2. Name, Bedeutung und Wertebereiche von Übergabe- und Rückgabeparametern
3. Verhalten der Komponente bei Nutzung einer Funktion/Methode. Dieses Verhalten kann sich nur über eine Schnittstellen der Komponente zeigen. Software-Komponenten haben nur folgende Schnittstellen-Typen: Zum Anwender (UI), zu anderen Systemen (d.h. wieder über Funktionen/Methoden) und zur Laufzeitumgebung einschließlich Hardware bzw. Sensorik.

Andere Schnittstellentypen

Wenn Sie andere Software-Schnittstellen beschreiben müssen wie z.B.

• Webservices
• REST-Schnittstellen
• Bussysteme (CAN-Bus, USB, I2C …)
• usw.

empfehlen wir Ihnen, diese anhand des Interoperabilitätsmodells zu spezifizieren und auf Vollständigkeit zu prüfen.

3. Schritt: Dokumentation von „nicht-funktionalen“ Eigenschaften

Ergänzen Sie die Beschreibung Ihrer API um nicht-funktionale Eigenschaften wie

1. Performanz: Wie schnell muss die Komponente auf Aufrufe über die Schnittstelle reagieren? Wie ändert sich diese Geschwindigkeit in Abhängigkeit von der Anzahl der Aufrufe pro Zeiteinheit oder von der Größe der übertragenen Daten?
2. Security: Werden die Daten verschlüsselt übertragen? Auf welcher Übertragungsschicht? Wie müssen sich andere Komponenten an der spezifizierten autorisieren?
3. Zuverlässigkeit/Robustheit: Wie reagiert die Komponente auf fehlerhafte Inputs um, auf fehlende Inputs, auf Inputs in falscher Reihenfolge? Fehlerhaft beinhaltet: Falsche Datentypen, falsche Wertebereiche, falsche Kodierung (sowohl auf strukturelle, syntaktischer und semantischer Ebene), falsche Datenmengen, falsche Aufrufgeschwindigkeit usw.

4. Schritt: Dokumentation von Software-Schnittstellen bei SOUPs

SOUPs sind zuerst nichts anderes als Komponenten in Ihrem Software-System. Entsprechend muss die Architektur diese Komponenten erkennen lassen. Die Besonderheit besteht aber darin, dass SOUPs insbesondere Frameworks (z.B.  .NET) häufig so viele Funktionen anbieten, dass eine API-Beschreibung nicht mehr sinnvoll möglich ist. Ein bloßer Verweis auf die API des SOUP-Herstellers würde aber auch nicht genügen, weil damit nicht klar wäre, wie die eigenen Komponenten mit der SOUP interagieren.

In diesem Fall können Sie statt konkrete Interfaces auf „abstrakte“ Interfaces verweisen. Beispiele dafür wären „Persistenz“, „Webservice“ und „UI“. Dass natürlich eine UI 1000e Klassen und noch mehr Methoden bereitstellt, ist unbestritten. Diese aber zu listen, wäre von endlichem Wert. Im Gegenteil, der Sinn einer Architektur wäre damit konterkariert:

1. Entwicklern und Testern eine präzise Vorgabe für deren Arbeit geben
2. Die Güte der Architektur bewerten können.
3. Auswirkungen von Änderungen auf andere Komponenten und damit Risiken beurteilen können.

Interne versus externe Software-Schnittstellen

Produkte wie Medizinprodukte, gleich ob standalone Software oder physische Geräte, sollten aus Komponenten bestehen. Damit haben Produkte wie Medizinprodukte nicht nur externe Schnittstellen, sondern auch interne, nämlich zwischen den einzelnen Komponenten.

Abb 2.: Externe Schnittstellen sind immer auch interne Schnittstellen (hier mit orangenen Kreisen markiert). Umgekehrt haben interne Schnittstellen nicht immer ein externes Pendant.

Interne = externe Schnittstellen?

Zerlegt man das Objekt in (Sub-)Komponenten, gilt es im nächsten Schritt diese Subkomponenten zu spezifizieren. Und auch dieses Mal sollten die Schnittstellen beschrieben sein. Dabei kann und muss es vorkommen, dass die Schnittstellen der äußeren Komponente gleichzeitig die der inneren Komponenten sind.

Beispielsweise wird die GUI eines Medizingeräts gleichzeitig die GUI der Subkomponente sein, auf der die „Software-GUI“ läuft. Eine „Ethernet-Schnittstelle“ wird direkt zu einer Subkomponente durchgereicht.

Natürlich spezifiziert man diese Schnittstellen nicht redundant, sondern verweist in der Sub-Komponenten-Spezifikation auf die entsprechende Spezifikation der übergeordneten Komponente. Wohlgemerkt von der Sub-Komponente zur übergeordneten Komponente.

Internet als interne Software-Schnittstelle?

Eine Software-Schnittstelle zum Internet ist immer eine externe Schnittstelle, richtig oder? Nein: Ob eine solche Schnittstelle intern oder extern ist, hängt davon ab, was man als Medizinprodukt definiert.

Wenn Sie beispielsweise

• das Gesamtsystem aus Mobile Medical App und zugehöriger Server-Software als ein Medizinprodukt und
• zugleich die Gesamtheit aller Software als Ihr Software-System

definieren, dann ist das Internet eine interne(!) Software-Schnittstelle, die zwei Komponenten des Software-Systems verbindet: Eben die Medical-App-Software-Komponente mit der Server-Software-Komponente.

Wir raten Ihnen allerdings davon ab, das Software-System als Gesamtheit aller Software zu definieren. Ein Software-System sollte immer an den Grenzen der jeweiligen Prozessor-/Speichereinheit enden. In obigem Beispiel hätte man somit zwei Software-Systeme: die App und die Server-Software. Dann sind die Schnittstellen zum Internet jeweils externe Software-Schnittstellen.

Diese Aufteilung empfehlen wir übrigens unabhängig davon, ob Sie beide Systeme zu einem Medizinprodukt zählen oder nicht.

Dokumentation von Schnittstellen: Regulatorische Anforderungen

Die IEC 62304 verlangt in Kapitel 5.3.2, dass die Hersteller die Software-Schnittstellen zwischen den Software-Komponenten dokumentieren. Eine nahezu identische Forderung findet sich im Kapitel 5.4.3, die ebenfalls die „Entwicklung eines detaillierten Designs für Schnittstellen“ fordert. Beide Kapitel legen aber nicht fest, wie diese Software-Schnittstellen zu beschreiben/spezifizieren sind.

Ähnlich unkonkret fordert die FDA im Software Validation Guidance eine „definition of all external and user interfaces, as well as any internal software-to-system interfaces;“

Wenn Sie die Schnittstellen wie in diesem Artikel vorgeschlagen dokumentieren, erfüllen Sie die regulatorischen Anforderungen.

Typische Fehler

1. Falscher Zeitpunkt

Sie sollten keinesfalls in der übergeordneten Komponente diese Spezifikation der Software-Schnitttstellen noch offen lassen, um das zu einem späteren Zeitpunkt nachzuholen, nämlich dem Zeitpunkt, zu dem die Subkomponente spezifiziert wird. Wer das tut, läuft Gefahr

• Fehler zu spät zu bemerken, unnötige Nachbesserungen zu verursachen und dadurch das Projekt zu verzögern,
• missverstandene Anforderungen des Kunden zu spät zu entdecken und dadurch Konflikte mit ihm zu verursachen,
• wider den Vorschriften der Normen zu entwickeln,
• Rollen mit Aufgaben zu beauftragen, die dafür nicht ausgebildet sind beispielsweise Entwickler mit der Spezifikation der GUI statt Usability Engineers.

In den Videotrainings im Auditgarant beschreibe ich genau, wie Sie Schnittstellen schnell und normenkonform spezifizieren können und so die Voraussetzung für eine zielgerichtete Entwicklung ohne unnötige Nachbesserungsschleifen schaffen.

Videotrainings ansehen

2. Fehler in der IEC 62304 mit Bezug zu Software-Schnittstellen

Die IEC 62304 ist leider unpräzise um nicht sogar zu sagen falsch an einigen Stellen des Kapitel 5.3. Es ist gerade nicht Gegenstand der Schnittstellen-Bescheibung auf externe Schnittstellen einzugehen. Das ist Gegenstand der Software-Anforderungen, die das System aus Blackbox-Sicht beschreiben sollen.

3. Schlechte Architektur

Wenn Sie das Gefühl haben, dass diese Beschreibung zu aufwendig weil zu umfangreich sei, dann ist das ein Hinweis, dass Sie zu „breite“ Schnittstellen und damit eine suboptimale Kapselung Ihrer Komponenten planen: Eine schlechte Architektur. Eine gute Architektur zeichnet sich durch ein „weak coupling“ der Komponenten d.h. durch schmale und wohldefinierte Schnittstellen aus.