Modul orbit_framework¶

Diese Modul enthält die wichtigsten Klassen für die Entwicklung einer ORBIT-Anwendung. Eine ORBIT-Anwendung wird von einem Core verwaltet und kann mehrere Job-Objekte enthalten. Jeder Job fasst eine Gruppe von Component-Objekten zusammen. Ein Job ist entweder eine App oder ein Service.

Die TinkerForge-Bricklets werden durch den devices.DeviceManager verwaltet und den Component-Objekten über devices.DeviceHandle-Objekte zugeordnet.

Component- und Job-Objekte kommunizieren asynchron über das ORBIT-Nachrichtensystem welches durch die Klasse messaging.MessageBus implementiert wird.

Component- und Job-Objekte können jederzeit Nachrichten senden. Diese Nachrichten werden in einer Warteschlange abgelegt und in einem dedizierten Nachrichten-Thread an die Empfänger versandt (Job.send(), Component.send()).

Für den Empfang von Nachrichten werden messaging.Listener-Objekte verwendet. Ein messaging.Listener bindet ein Empfangsmuster/-filter an ein Callback (messaging.Slot, Job.add_listener(), Component.add_listener()). Wird eine Nachricht über das Nachrichtensystem versandt, welches dem Empfangsmuster entspricht, wird das Callback des Empfängers aufgerufen.

Das Modul enthält die folgenden Klassen:

Core
Job
App
Service
Component

Core¶

class orbit_framework.Core(config = Configuration())¶

Diese Klasse repräsentiert den Kern einer ORBIT-Anwendung.

Parameter

config (optional): Die Konfiguration für die ORBIT-Anwendung. Eine Instanz der Klasse setup.Configuration.

Beschreibung

Diese Klasse ist verantwortlich für die Einrichtung des Nachrichtensystems und der Geräteverwaltung. Des Weiteren verwaltet sie alle Dienste und Apps, die in der ORBIT-Anwendung verwendet werden.

Für die Einrichtung einer Anwendung wird zunächst eine Instanz von Core erzeugt. Dabei kann optional eine benutzerdefinierte Konfiguration (setup.Configuration) an den Konstruktor übergeben werden. Anschließend werden durch den mehrfachen Aufruf von install() Jobs hinzugefügt. Jobs können Dienste (Service) oder Apps (App) sein. Über die Eigenschaft default_application kann eine App als Standard-App festgelegt werden.

Um die ORBIT-Anwendung zu starten wird die Methode start() aufgerufen. Um die ORBIT-Anwendung zu beenden, kann entweder direkt die Methode stop() aufgerufen werden, oder es werden vor dem Start der Anwendung ein oder mehrere Slots (Ereignisempfänger für das ORBIT-Nachrichtensystem) hinzugefügt, welche die Anwendung stoppen sollen.

activate(application)¶

Aktiviert eine App. Die App kann direkt übergeben oder durch ihren Namen identifiziert werden.

Zu jedem Zeitpunkt ist immer nur eine App aktiv. Ist bereits eine andere App aktiv, wird diese deaktiviert, bevor die übergebene App aktiviert wird.

Ist die Eigenschaft App.in_history der bereits aktiven App gleich True, wird die App vor dem Deaktivieren in der App-History vermerkt.

Wird der Name einer App übergeben, die nicht in der ORBIT-Anwendung installiert ist, wird eine KeyError ausgelöst.

Siehe auch: deactivate(), clear_application_history(), for_each_active_job(), Job.active

add_stopper(slot)¶

Fügt einen messaging.Slot hinzu, der das Stoppen der ORBIT-Anwendung veranlassen soll.

Siehe auch: remove_stopper()

clear_application_history()¶

Leert die App-History.

Das hat zur Folge, dass nach dem Deaktivieren der zur Zeit aktiven App die Standard-App oder gar keine aktiviert wird.

Siehe auch: activate(), deactivate()

configuration¶

Gibt die ORBIT-Anwendungskonfiguration zurück. (schreibgeschützt)

Siehe auch: setup.Configuration

deactivate(application)¶

Deaktiviert eine App. Die App App kann direkt übergeben oder durch ihren Namen identifiziert werden.

Nach dem Deaktivieren der App wird geprüft, ob in der App-History eine App vermerkt ist, welche vorher aktiv war. Ist dies der Fall wird jene App automatisch aktiviert.

Ist die App-History leer, wird geprüft ob eine Standard-App registriert ist (default_application) und ggf. diese aktiviert.

Siehe auch: activate(), clear_application_history(), Job.active

default_application¶

Gibt die Standard-App zurück oder legt sie fest.

Siehe auch: App

device_manager¶

Gibt den Gerätemanager zurück. (schreibgeschützt)

Siehe auch: devices.DeviceManager

for_each_active_job(f)¶

Führt eine Funktion für jeden aktiven Job aus.

Siehe auch: activate(), deactivate()

for_each_job(f)¶

Führt eine Funktion für jeden installierten Job aus.

Siehe auch: jobs, install(), uninstall()

install(job)¶

Fügt der ORBIT-Anwendung einen Job (Job) hinzu. Ein Job kann ein Dienst (Service) oder eine App (App) sein. Jobs können vor oder nach dem Starten der ORBIT-Anwendung hinzugefügt werden.

Ein Job kann immer nur in einer ORBIT-Anwendung installiert werden. Wird ein Job, der bereits in einer Anwendung installiert ist, an install() übergeben, geschieht nichts.

Siehe auch: uninstall(), jobs, App, Service

is_started¶

Gibt an ob die ORBIT-Anwendung gestartet wurde oder nicht. (schreibgeschützt) Ist True wenn die Anwendung läuft, sonst False.

Siehe auch: start(), stop()

jobs¶

Gibt ein Dictionary mit allen installierten Jobs zurück. (schreibgeschützt) Der Schlüssel ist der Name des Jobs und der Wert ist der Job selbst.

Siehe auch: Job, install(), uninstall()

message_bus¶

Gibt das Nachrichtensystem zurück. (schreibgeschützt)

Siehe auch: messaging.MessageBus

remove_stopper(slot)¶

Entfernt einen messaging.Slot, der das Stoppen der ORBIT-Anwendung veranlassen sollte.

Siehe auch: add_stopper()

start()¶

Startet die ORBIT-Anwendung.

Beim Start wird das Nachrichtensystem gestartet und damit die Weiterleitung von Ereignissen zwischen den Jobs und Komponenten aktiviert. Des Weiteren wird der Gerätemanager gestartet, der die Verbindung zum TinkerForge-Server aufbaut und die angeschlossenen Bricks und Bricklets ermittelt.

Ist die Infrastruktur des Kerns erfolgreich gestartet, werden zunächst alle Dienste, und zum Schluss die Standard-App aktiviert.

Bemerkung

Wird diese Methode aufgerufen, wenn die ORBIT-Anwendung bereits gestartet wurde, wird lediglich eine Meldung auf der Konsole ausgegeben.

Siehe auch: stop(), is_started

stop()¶

Stoppt die ORBIT-Anwendung.

Beim Stoppen werden zunächst alle Jobs (Dienste und Apps) deaktiviert. Anschließend wird der Gerätemanager beendet und dabei die Verbindung zum TinkerForge-Server getrennt. Zum Schluss wird das Nachrichtensystem beendet und die Weiterleitung von Ereignissen gestoppt.

Bemerkung

Wird diese Methode aufgerufen, wenn die ORBIT-Anwendung nicht gestartet ist, wird lediglich eine Meldung auf der Konsole ausgegeben.

Siehe auch: start(), is_started

trace(text)¶: Schreibt eine Nachverfolgungsmeldung mit dem Ursprung Core auf die Konsole.

uninstall(job)¶

Entfernt einen Job aus der ORBIT-Anwendung. Ist der Job zur Zeit aktiv, wird er deaktiviert bevor er aus der Anwendung entfernt wird.

Wird ein Job an install() übergeben, der nicht in dieser ORBIT-Anwendung installiert ist, geschieht nicht.

Siehe auch: install(), jobs

wait_for_stop()¶

Blockiert solange den Aufrufer, bis die ORBIT-Anwendung beendet wurde.

Der Grund für das Beenden kann ein direkter Aufruf von stop() oder das Abfangen eines Ereignisses von einem der Stopper-Slots sein.

Zusätzlich wird das Unterbrechungssignal (SIGINT z.B. Strg+C) abgefangen. Tritt das Unterbrechungssignal auf, wird die ORBIT-Anwendung durch den Aufruf von stop() gestoppt und die Methode kehrt zum Aufrufer zurück.

Bemerkung

Die Methode kehrt erst dann zum Aufrufer zurück,

wenn alle Jobs deaktiviert wurden,
der Gerätemanager alle Bricks und Bricklets freigegeben und die Verbindung zum TinkerForge-Server beendet hat
und das Nachrichtensystem alle ausstehenden Ereignisse weitergeleitet hat und beendet wurde.

Warnung

Diese Methode darf nicht direkt oder indirekt durch einen messaging.Listener aufgerufen werden, da sie andernfalls das Nachrichtensystem der ORBIT-Anwendung blockiert.

Siehe auch: stop(), add_stopper(), remove_stopper()

Job¶

class orbit_framework.Job(name, background)¶

Dies ist die Basisklasse für Aufgaben in einer ORBIT-Anwendung.

Parameter

name: Der Name der Aufgabe. Der Name muss innerhalb der ORBIT-Anwendung eindeutig sein.
background: True wenn die Aufgabe als Hintergrunddienst laufen soll, sonst False`.

Beschreibung

Ein Job wird durch die Zusammenstellung von Komponenten implementiert. Wird ein Job aktiviert, werden alle seine Komponenten aktiviert. Wird ein Job deaktiviert, werden alle seine Komponenten deaktiviert. Ein aktiver Job kann Nachrichten über das Nachrichtensystem austauschen. Ein inaktiver Job kann keine Nachrichten senden oder empfangen.

Bemerkung

Die Job-Klasse sollte nicht direkt verwendet werden. Statt dessen sollten die abgeleiteten Klassen Service und App verwendet werden.

Siehe auch: add_component(), remove_component()

active¶

Gibt einen Wert zurück oder legt ihn fest, der angibt, ob der Job aktiv ist.

Bemerkung

Dieses Attribut sollte nicht direkt gesetzt werden. Statt dessen sollte Core.activate() und Core.deactivate() verwendet werden.

Siehe auch: Core.activate(), Core.deactivate(), on_activated(), on_deactivated()

add_component(component)¶

Fügt dem Job eine Komponente hinzu.

Siehe auch: remove_component(), components, Component

add_listener(listener)¶

Richtet einen Nachrichtenempfänger für das Nachrichtensystem ein.

Als Empfänger wird üblicherweise ein messaging.Listener-Objekt übergeben.

Siehe auch: messaging.Listener, messaging.MessageBus.add_listener(), remove_listener(), send()

background¶

Legt fest, ob der Job als Hintergrunddienst ausgeführt wird oder als Vordergrund-App.

Mögliche Werte sind True für Hintergrunddienst oder False für Vordergrund-App.

components¶

Gibt ein Dictionary mit allen Komponenten des Jobs zurück. Die Namen der Komponenten werden als Schlüssel verwendet. Die Komponenten selbst sind die Werte.

Siehe auch: add_component(), remove_component(), Component

configuration¶: Gibt die Anwendungskonfiguration zurück. Wenn der Job nicht installiert ist, wird None zurück gegeben.

core¶

Gibt eine Referenz auf den Anwendungskern zurück. Wenn der Job nicht installiert ist, wird None zurück gegeben.

Siehe auch: Core, Core.install()

event_tracing¶

Legt fest, ob über das Nachrichtensystem versendete Nachrichten auf der Konsole protokolliert werden sollen.

Mögliche Werte sind True oder False.

Siehe auch: send()

for_each_component(f)¶

Führt die übergebene Funktion für jede Komponente des Jobs aus.

Siehe auch: components

name¶: Gibt den Namen des Jobs zurück.

on_activated()¶

Wird aufgerufen, wenn der Job aktiviert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: active, Core.activate()

on_core_started()¶

Wird aufgerufen, wenn der Anwendungskern gestartet wurde.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Core.start()

on_core_stopped()¶

Wird aufgerufen, wenn der Anwendungskern gestoppt wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Core.stop()

on_deactivated()¶

Wird aufgerufen, wenn der Job deaktiviert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: active, Core.deactivate()

on_install(core)¶

Wird aufgerufen, wenn der Job installiert wird.

Parameter

core: Eine Referenz auf den Anwendungskern.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Core.install()

on_uninstall()¶

Wird aufgerufen, wenn der Job deinstalliert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Core.uninstall()

remove_component(component)¶

Entfernt eine Komponente aus dem Job.

Siehe auch: add_component(), components

remove_listener(listener)¶

Meldet einen Nachrichtenempfänger vom Nachrichtensystem ab.

Bemerkung

Es muss das selbe Empfängerobjekt übergeben werden, wie an add_listener() übergeben wurde.

Siehe auch: messaging.MessageBus.remove_listener(), add_listener(), send()

send(name, value=None)¶

Versendet eine Nachricht über das Nachrichtensystem.

Parameter

name: Der Ereignisname für die Nachricht.
value (optional): Der Inhalt der Nachricht. Das kann ein beliebiges Objekt sein.

Beschreibung

Die Methode übergibt die Nachricht an das Nachrichtensystem und kehrt sofort zum Aufrufer zurück. Die Nachricht wird asynchron an die Empfänger übermittelt. Als Absender-Job wird der Name dieses Jobs eingetragen. Als Absenderkomponente wird JOB eingetragen.

Siehe auch: add_listener(), remove_listener(), messaging.MessageBus.send()

trace(text)¶: Schreibt eine Nachverfolgungsmeldung mit dem Ursprung Service <Name> oder App <Name> auf die Konsole.

tracing¶

Legt fest, ob Nachverfolgungsmeldungen für diesen Job auf der Konsole ausgegeben werden sollen.

Mögliche Werte sind True oder False.

Siehe auch: trace()

Service¶

class orbit_framework.Service(name)¶

Diese Klasse implementiert eine Hintergrundaufgabe in einer ORBIT-Anwendung.

Parameter

name: Der Name der Aufgabe. Der Name muss innerhalb der ORBIT-Anwendung eindeutig sein.

Beschreibung

Hintergrundaufgaben werden üblicherweise direkt mit dem Starten der ORBIT-Anwendung aktiviert und erst mit dem Beenden der Anwendung wieder deaktiviert.

Diese Klasse erbt von Job und implementiert damit eine Aufgabe durch die Kombination von verschiedenen Komponenten. Diese Klasse kann direkt instanziert werden oder es kann eine Klasse abgeleitet werden.

Siehe auch: Job, Job.add_component(), Core.install()

App¶

class orbit_framework.App(name, in_history=False, activator=None, deactivator=None)¶

Diese Klasse implementiert eine Vordergrundaufgabe in einer ORBIT-Anwendung.

Parameter

name: Der Name der Aufgabe. Der Name muss innerhalb der ORBIT-Anwendung eindeutig sein.
in_history (optional): Gibt an, ob diese App in der App-History berücksichtigt werden soll. (Siehe auch: Core.activate(), Core.deactivate()) Mögliche Werte sind True wenn die App in der App-History vermerkt werden soll, sonst False.
activator (optional): Slots für die Aktivierung der App. Ein einzelner messaging.Slot, eine Sequenz von Slot-Objekten oder None. (Siehe auch: add_activator())
deactivator (optional): Slots für die Deaktivierung der App. Ein einzelner messaging.Slot, eine Sequenz von Slot-Objekten oder None. (Siehe auch: add_deactivator())

Beschreibung

Siehe auch: Job, Job.add_component(), Core.install()

activate()¶

Aktiviert die App.

Siehe auch: Core.activate()

add_activator(slot)¶

Fügt einen messaging.Slot für die Aktivierung der App hinzu.

Sobald eine Nachricht über das Nachrichtensystem gesendet wird, welche dem Empfangsmuster des übergebenen Slots entspricht, wird die App aktiviert.

Siehe auch: remove_activator(), add_deactivator()

add_deactivator(slot)¶

Fügt einen messaging.Slot für die Deaktivierung der App hinzu.

Sobald eine Nachricht über das Nachrichtensystem gesendet wird, welche dem Empfangsmuster des übergebenen Slots entspricht, wird die App deaktiviert.

Siehe auch: remove_deactivator(), add_activator()

deactivate()¶

Deaktiviert die App.

Siehe auch: Core.deactivate()

in_history¶

Gibt einen Wert zurück, der angibt, ob diese App in der App-History vermerkt wird oder nicht.

Mögliche Werte sind True oder False.

Siehe auch: Core.activate(), Core.deactivate()

on_install(core)¶

Wird aufgerufen, wenn die App installiert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Core.install(), Job.on_install()

on_uninstall()¶

Wird aufgerufen, wenn die App deinstalliert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Core.uninstall(), Job.on_uninstall()

remove_activator(slot)¶

Entfernt einen messaging.Slot für die Aktivierung der App.

Bemerkung

Es muss die selbe Referenz übergeben werden, wie an add_activator() übergeben wurde.

Siehe auch: add_activator()

remove_deactivator(slot)¶

Entfernt einen messaging.Slot für die Deaktivierung der App.

Bemerkung

Es muss die selbe Referenz übergeben werden, wie an add_deactivator() übergeben wurde.

Siehe auch: add_deactivator()

Component¶

class orbit_framework.Component(name)¶

Diese Klasse implementiert eine Komponente als Baustein für eine Aufgabe.

Parameter

name: Der Name der Komponente. Der Name muss innerhalb der Aufgabe eindeutig sein.

Beschreibung

Komponenten sind der typische Weg, in einer ORBIT-Anwendung, mit einem TinkerForge-Brick(let) zu kommunizieren. Eine Komponente wird implementiert, indem eine Klasse von Component abgeleitet wird und im Konstruktur durch den Aufruf von add_device_handle() Geräteanforderungen eingerichtet werden.

Komponenten können über das Nachrichtensystem kommunizieren. Dazu können mit dem Aufruf von add_listener() Empfänger eingerichtet und mit dem Aufruf von send() Nachrichten versandt werden.

Siehe auch: Job.add_component(), add_device_handle(), add_listener(), send()

add_device_handle(device_handle)¶

Richtet eine Geräteanforderung ein.

Als Parameter wird ein devices.SingleDeviceHandle oder ein devices.MultiDeviceHandle übergeben.

Siehe auch: remove_device_handle()

add_listener(listener)¶

Richtet einen Nachrichtenempfänger für das Nachrichtensystem ein.

Als Empfänger wird üblicherweise ein messaging.Listener-Objekt übergeben.

Siehe auch: messaging.Listener, messaging.MessageBus.add_listener(), remove_listener(), send()

enabled¶

Gibt an oder legt fest, ob die Komponente aktiv ist.

Mögliche Werte sind True wenn die Komponente aktiv ist und False wenn die Komponente nicht aktiv ist.

Alle Komponenten eines Jobs werden beim Aktivieren des Jobs automatisch aktiviert und mit dem Deaktivieren des Jobs automatisch deaktiviert. Das manuelle Setzen dieses Attributs ist i.d.R. nicht notwendig.

Eine aktive Komponente bekommt Geräte (Bricks und Bricklets) zugeordnet und kann Nachrichten empfangen und senden. Eine inaktive Komponente bekommt keine Geräte zugeordnet und erhält auch keine Nachrichten vom Nachrichtensystem zugestellt.

event_tracing¶

Legt fest, ob über das Nachrichtensystem versendete Nachrichten auf der Konsole protokolliert werden sollen.

Mögliche Werte sind True oder False.

Siehe auch: send()

job¶

Gibt den Eltern-Job oder None zurück.

Siehe auch: Job.add_component()

name¶: Gibt den Namen der Komponente zurück.

on_add_component(job)¶

Wird aufgerufen, wenn die Komponente einem Job hinzugefügt wird.

Parameter

job: Eine Referenz auf den Job.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Job.add_component()

on_core_started()¶

Wird aufgerufen, wenn der Anwendungskern gestartet wurde.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden.

Siehe auch: Core.start()

on_core_stopped()¶

Wird aufgerufen, wenn der Anwendungskern gestoppt wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden.

Siehe auch: Core.stop()

on_disabled()¶

Wird aufgerufen, wenn die Komponente deaktiviert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden.

Siehe auch: enabled

on_enabled()¶

Wird aufgerufen, wenn die Komponente aktiviert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden.

Siehe auch: enabled

on_job_activated()¶

Wird aufgerufen, wenn der Eltern-Job der Komponente aktiviert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden.

Siehe auch: Job.active, Core.activate()

on_job_deactivated()¶

Wird aufgerufen, wenn der Eltern-Job der Komponente deaktiviert wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden.

Siehe auch: Job.active, Core.deactivate()

on_remove_component()¶

Wird aufgerufen, wenn die Komponente aus einem Job entfernt wird.

Bemerkung

Kann von abgeleiteten Klassen überschrieben werden. Eine überschreibende Methode muss jedoch die Implementierung der Elternklasse aufrufen.

Siehe auch: Job.remove_component()

remove_device_handle(device_handle)¶

Entfernt eine Geräteanforderung.

Als Parameter wird ein devices.SingleDeviceHandle oder ein devices.MultiDeviceHandle übergeben.

Bemerkung

Es muss die selbe Referenz übergeben werden, wie an add_device_handle() übergeben wurde.

Siehe auch: add_device_handle()

remove_listener(listener)¶

Meldet einen Nachrichtenempfänger vom Nachrichtensystem ab.

Bemerkung

Es muss das selbe Empfängerobjekt übergeben werden, wie an add_listener() übergeben wurde.

Siehe auch: messaging.MessageBus.remove_listener(), add_listener(), send()

send(name, value=None)¶

Versendet eine Nachricht über das Nachrichtensystem.

Parameter

name: Der Ereignisname für die Nachricht.
value (optional): Der Inhalt der Nachricht. Das kann ein beliebiges Objekt sein.

Beschreibung

Die Methode übergibt die Nachricht an das Nachrichtensystem und kehrt sofort zum Aufrufer zurück. Die Nachricht wird asynchron an die Empfänger übermittelt. Als Absender-Job wird der Name des Eltern-Jobs dieser Komponente eingetragen. Als Absenderkomponente wird der Name dieser Komponente eingetragen.

Siehe auch: add_listener(), remove_listener(), messaging.MessageBus.send()

trace(text)¶: Schreibt eine Nachverfolgungsmeldung mit dem Ursprung Component <Job> <Name> auf die Konsole.

tracing¶

Legt fest, ob Nachverfolgungsmeldungen für diese Komponente auf der Konsole ausgegeben werden sollen.

Mögliche Werte sind True oder False.

Siehe auch: trace()