Ein eigener SiLA2-Client — Schritt für Schritt, in Python

SiLA 2 ist der Laborautomatisierungs-Standard für Gerätesteuerung über gRPC + TLS. Die Begriffe, die ihr braucht:

1 · FeliX starten (läuft er schon, weiter zu Schritt 2):

cd "/Users/marcelweissgerber/Downloads/icm-lh-development 2"
docker compose -f docker-compose.local.yml -f docker-compose.local.mac.yml up -d

Ports: 5108 REST/UI · 5109 CASE-gRPC · 5111 SiLA2 (TLS). Kontrolle: localhost:5108/sila-console — dort seht ihr später jeden Call eures Clients live.

2 · CA-Zertifikat holen — der Trust-Anker für den untrusted-Modus (der Server generiert es beim ersten Start selbst):

docker cp icm-felix-local:/opt/icm/ca.crt .

3 · Python-Umgebung — die offizielle SiLA2-Referenzimplementierung:

python3 -m venv silaenv && source silaenv/bin/activate
pip install sila2

from sila2.client import SilaClient

ca = open("ca.crt", "rb").read()
client = SilaClient("127.0.0.1", 5111, root_certs=ca)

print(client.SiLAService.ServerName.get())    # ICM FeliX SiLA2 Server
print(client.SiLAService.ServerUUID.get())    # f91b13d1-… (stabil über Neustarts)
print(client.SiLAService.ImplementedFeatures.get())

Checkpoint: Beide FQFIs erscheinen, und in der /sila-console tauchen eure Calls mit Peer-Adresse und user-agent: grpc-python… auf.

Welche Aktionen ExecuteActivity versteht, sagt die Property ActivitySchema — identisch mit GET /api/activity/schema, eine Quelle für REST und SiLA:

import json
lhc = client.LiquidHandlingController
schema = json.loads(lhc.ActivitySchema.get())
print(schema["schemaVersion"], len(schema["actions"]))   # 2.11  38

Jede Action bringt Parameter-Namen, Datentypen und kopfspezifische Volumen-Ranges mit — euer Client validiert Protokolle, bevor das Gerät sie sieht.

import time
cmd = lhc.ExecuteActivity("WAIT", json.dumps([{"Key": "waitTime", "Value": "1"}]), True)
print(cmd.execution_uuid)          # sofort da — die Aktion läuft im Hintergrund
while not cmd.done: time.sleep(0.3)
result = cmd.get_responses()       # ChecklistJson mit dem Step-Ergebnis

Die Observable-Command-Trias: ① sofortige Bestätigung mit UUID · ② Info-Stream (intern, speist cmd.done) · ③ Ergebnis-Abruf, erst wenn fertig.

Der eigentliche Arbeitsmodus — nur Body-Schritte, den Rest macht der Server:

protocol = {"steps": [
    {"activity": "MOVE", "parameters": [{"Key": "deckPosition", "Value": "7"},
                                    {"Key": "zReference", "Value": "Topmost"}]},
    {"activity": "WAIT", "parameters": [{"Key": "waitTime", "Value": "1"}]},
]}
cmd = lhc.ExecuteProtocol(json.dumps(protocol), True)   # True = simuliert
while not cmd.done: time.sleep(0.5)
for step in json.loads(cmd.get_responses().StepResultsJson):
    print(step["Step"], step["Activity"], step["Success"])

1 INIT True · 2 MOVE True · 3 WAIT True · 4 WORKFLOW_SHUTDOWN True

Der Server validiert vor dem ersten Gerätekommando: unbekannte Typen und Lifecycle-Actions im Body werden synchron als ValidationError abgelehnt.

USER_NOTIFICATION und USER_INPUT sind normale Body-Schritte. Der Server pausiert dort (Gerät bleibt initialisiert!), meldet über den Intermediate-Stream — euer Client quittiert per ConfirmUserPrompt:

import threading

def handle_prompts():
    for intermediate in cmd.subscribe_to_intermediate_responses():
        prompt = json.loads(intermediate.PromptJson)
        print("BEDIENHINWEIS:", prompt["Message"])
        lhc.ConfirmUserPrompt(str(cmd.execution_uuid), prompt["PromptId"], "OK")

threading.Thread(target=handle_prompts, daemon=True).start()

Schritt 3 USER_NOTIFICATION: OK — Quittung 'OK' um 2026-08-06T07:36:46.335…+00:00

SiLA-Fehler sind typisiert und kommen in Python als Exceptions an:

Alles zusammen — CLI, Schema-Vorab-Validierung, interaktive Quittung (oder --auto für Skripte), Ergebnis-Report: tools/masterclass/felix_client.py (~100 Zeilen, im Repo).

cd tools/masterclass
docker cp icm-felix-local:/opt/icm/ca.crt .
python felix_client.py beispiel-protokoll.json --api-key KEY              # interaktiv
python felix_client.py beispiel-protokoll.json --api-key KEY --auto LOT-42 # unbeaufsichtigt

--api-key ist seit Modul 10 Pflicht für schreibende Kommandos: der Client meldet sich damit über das SiLA2-Core-Feature AuthenticationService an und hängt das erhaltene Token an ExecuteProtocol und ConfirmUserPrompt.

Verbunden: ICM FeliX SiLA2 Server (UUID f91b13d1-6142-47e7-b806-0f49723b6fc7)
Schema v2.11: alle 4 Schritte bekannt
>>> BEDIENHINWEIS (Schritt 3): Bitte Spalte 1 aus dem RoboTipTray entfernen. → quittiert 'OK'
>>> BEDIENHINWEIS (Schritt 5): Bitte die Lot-Nummer erfassen. → quittiert 'LOT-42'
Schritt 1 INIT: OK … Schritt 6 WORKFLOW_SHUTDOWN: OK

Hier läuft echtes CPython im Browser (Pyodide, von dieser Domain geladen — kein Server bei uns führt euren Code aus). Das Modul felix ist die Brücke: es spricht dieselben SiLA2-Aufrufe wie der Python-Client aus Modul 08, nur über gRPC-Web zu einem FeliX auf der Testing-Umgebung. print() und Tracebacks landen in der Konsole, Bedienhinweise erscheinen als Dialog.

Bis hierher konnte jeder, der den Port erreicht, das Gerät bewegen. Seit dem Auth-Ausbau verlangt FeliX für die schreibenden Kommandos — ConnectDevice, ExecuteActivity, ExecuteProtocol, ConfirmUserPrompt — ein AccessToken. SiLA2 bringt dafür zwei Core-Features mit, beide implementiert FeliX über die offizielle Referenz:

• AuthenticationService (org.silastandard/core/AuthenticationService/v1): Login(UserIdentification, Password, RequestedServer, RequestedFeatures) → Token + Lifetime. Das Password ist ein API-Schlüssel — derselbe, den auch die REST-Schnittstelle kennt (ICM_API_KEYS); es gibt bewusst nur EINE Credential-Quelle. RequestedServer muss die ServerUUID sein (FDL-Constraint: 36 Zeichen, lowercase) — die holt ein Client per Discovery, bevor er sich anmeldet.
• AuthorizationService (org.silastandard/core/AuthorizationService/v1): das Token reist als Client-Metadatum (sila-org.silastandard-core-authorizationservice-v1-metadata-accesstoken-bin) mit jedem geschützten Aufruf. Welche Calls betroffen sind, verrät der Server selbst: Get_FCPAffectedByMetadata_AccessToken.

In der Sandbox aus Modul 09: API-Schlüssel oben rechts eintragen (Login passiert dann automatisch beim ersten schreibenden Kommando) oder explizit im Code:

await server.login("EUER-API-SCHLUESSEL")   # Token holen
ergebnis = await server.execute_protocol(steps)  # Token reist als Metadatum mit
await server.logout()                        # Token verwerfen

Ohne Token antwortet der Server mit einem typisierten SiLA-Fehler (InvalidMetadata bzw. nach Logout InvalidAccessToken) — probiert Beispiel 7 aus der Beispiel-Liste. Ein falscher Schlüssel beim Login ergibt AuthenticationFailed. Alle drei Fehlerbilder lest ihr wie in Modul 07.

• UNAVAILABLE / Connection refused → läuft der Container? SiLA-Port ist 5111.
• TLS-Fehler → ca.crt neu aus dem Container kopieren.
• /sila-console zeigt nichts → Seite lädt sich nach Container-Neustart selbst neu; Clear-Button leert den Monitor.
• Sequenz-Regeln → Aspirate braucht Kopf + Tips; die Sim-Vorbereitung macht das INIT-Komposit von ExecuteProtocol automatisch.
• Wem vertraut ihr? Der FeliX signiert sein Zertifikat selbst. Der Python-Client der Masterclass bringt dafür ein Vertrauens-Gate mit (felix_trust.py): Fingerabdruck beim ersten Mal merken, danach vergleichen — und die Server-UUID aus der Zertifikats-Extension 1.3.6.1.4.1.58583 unterscheidet „Zertifikat erneuert" von „anderes Gerät". Es blockt nie, das Urteil gehört in den Nachweis. Details in Modul 9 der Repo-Fassung.
• Wie weiter → Auth/Lock der SiLA-Fläche ist offen (Atlas /r/9205) — vor Produktivbetrieb Pflicht. Discovery via mDNS statt Datei-CA. Epic zur SiLA2-Welle: /r/9197.

ICM FeliX · Branch feature/sila2-server · verifiziert 2026-08-06 · kanonische Quelle: documentation/masterclass-sila2-python-client.md im Repo