Modul orbit_framework.devices

Dieses Modul implementiert den Gerätemanager von ORBIT.

Das Modul umfasst die folgenden Klassen:

Darüber hinaus enthält es einige Hilfsfunktionen für den Umgang mit TinkerForge-Gerätetypen:

Klassen

DeviceManager

class orbit_framework.devices.DeviceManager(core)

Diese Klasse implementiert den Gerätemanager einer ORBIT-Anwendung.

Parameter

core

Ein Verweis auf den Anwendungskern der ORBIT-Anwendung. Eine Instanz der Klasse Core.

Beschreibung

Der Gerätemanager baut eine Verbindung zu einem TinkerForge-Server auf, ermittelt die angeschlossenen Bricks und Bricklets und stellt den Komponenten in den Jobs die jeweils geforderten Geräte zur Verfügung.

Dabei behält der Gerätemanager die Kontrolle über den Gerätezugriff. Das bedeutet, dass der Gerätemanager die Autorität hat, einer Komponente ein Gerät zur Verfügung zu stellen, aber auch wieder zu entziehen.

Eine Komponente bekommt ein von ihm angefordertes Gerät i.d.R. dann zugewiesen, wenn die Komponente aktiv und das Gerät verfügbar ist. Wird die Verbindung zum TinkerForge-Server unterbrochen oder verliert der TinkerForge-Server die Verbindung zum Master-Brick (USB-Kabel herausgezogen), entzieht der Gerätemanager der Komponente automatisch das Gerät, so dass eine Komponente i.d.R. keine Verbindungsprobleme behandeln muss.

Umgesetzt wird dieses Konzept mit Hilfe der Klassen SingleDeviceHandle und MultiDeviceHandle.

add_device_callback(uid, event, callback)

Richtet eine Callback-Funktion für ein Ereignis eines Bricks oder eines Bricklets ein.

Parameter

uid

Die UID des Gerätes für das ein Ereignis abgefangen werden soll.

event

Die ID für das abzufangene Ereignis. Z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.CALLBACK_BUTTON_PRESSED

callback

Eine Callback-Funktion die bei Auftreten des Ereignisses aufgerufen werden soll.

Beschreibung

Da jedes Ereignis andere Ereignisparameter besitzt, muss die richtige Signatur für die Callback-Funktion der TinkerForge-Dokumentation entnommen werden. Die Ereignisparameter werden in der API-Dokumentation für jeden Brick und jedes Bricklet im Abschnitt Callbacks beschrieben.

Bemerkung

Der Gerätemanager stellt einen zentralen Mechanismus für die Registrierung von Callbacks für Geräteereignisse zur Verfügung, weil die TinkerForge-Geräteklassen nur ein Callback per Ereignis zulassen. Der Gerätemanager hingegen unterstützt beliebig viele Callbacks für ein Ereignis eines Gerätes.

Siehe auch: remove_device_callback()

add_device_finalizer(device_identifier, finalizer)

Richtet eine Abschlussfunktion für einen Brick- oder Bricklet-Typ ein.

Parameter

device_identifier

Die Geräte-ID der TinkerForge-API. Z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.DEVICE_IDENTIFIER

finalizer

Eine Funktion, welche als Parameter eine Instanz der TinkerForge-Geräteklasse entgegennimmt.

Beschreibung

Sobald der Gerätemanager die Verbindung zu einem Gerät selbstständig aufgibt (d.h. die Verbindung nicht durch eine Störung unterbrochen wurde), ruft er alle Abschlussfunktionen für die entsprechende Geräte-ID auf.

Siehe auch: add_device_initializer()

add_device_initializer(device_identifier, initializer)

Richtet eine Initialisierungsfunktion für einen Brick- oder Bricklet-Typ ein.

Parameter

device_identifier

Die Geräte-ID der TinkerForge-API. Z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.DEVICE_IDENTIFIER

initializer

Eine Funktion, welche als Parameter eine Instanz der TinkerForge-Geräteklasse entgegennimmt.

Beschreibung

Sobald der Gerätemanager ein neues Gerät entdeckt, zu dem er bisher keine Verbindung aufgebaut hatte, ruft er alle Initialisierungsfunktionen für die entsprechende Geräte-ID auf.

Siehe auch: add_device_finalizer()

add_handle(device_handle)

Richtet eine Geräteanforderung (Geräte-Handle) ein.

Eine Geräteanforderung ist eine Instanz einer Sub-Klasse von DeviceHandle. Das kann entweder eine Instanz von SingleDeviceHandle oder von MultiDeviceHandle sein.

Das übergebene Geräte-Handle wird über alle neu entdeckten Geräte mit einem Aufruf von DeviceHandle.on_bind_device() benachrichtigt. Je nach Konfiguration nimmt das Handle das neue Gerät an oder ignoriert es. Verliert der Gerätemanager die Verbindung zu einem Gerät, wird das Geräte-Handle ebenfalls mit einem Aufruf von DeviceHandle.on_unbind_device() benachrichtigt.

Siehe auch: remove_handle()

property devices

Ein Dictionary mit allen zur Zeit verfügbaren Geräten. Die UID des Geräts ist der Schlüssel und der Wert ist eine Instanz der TinkerForge-Geräte-Klasse (wie z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4).

remove_device_callback(uid, event, callback)

Entfernt eine Callback-Funktion von einem Ereignis eines Bricks oder eines Bricklets.

Parameter

uid

Die UID des Gerätes für das ein Callback aufgehoben werden soll.

event

Die ID für das Ereignis. Z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.CALLBACK_BUTTON_PRESSED

callback

Die registrierte Callback-Funktion die entfernt werde soll.

Beschreibung

Für die Aufhebung des Callbacks muss die gleiche Funktionsreferenz übergeben werden wie bei der Einrichtung des Callback.

Siehe auch: add_device_callback()

remove_handle(device_handle)

Entfernt eine Geräteanforderung (Geräte-Handle).

Eine Geräteanforderung ist eine Instanz einer Sub-Klasse von DeviceHandle. Das kann entweder eine Instanz von SingleDeviceHandle oder von MultiDeviceHandle sein.

Siehe auch: add_handle()

start()

Startet den Gerätemanager und baut eine Verbindung zu einem TinkerForge-Server auf. Die Verbindungdaten für den Server werden der ORBIT-Konfiguration entnommen.

Gibt True zurück, wenn die Verbindung aufgebaut werden konnte, sonst False.

Siehe auch: stop()

stop()

Trennt die Verbindung zum TinkerForge-Server und beendet den Gerätemanager.

Vor dem Trennen der Verbindung wird die Zuordnung zwischen den Geräten und den Komponenten aufgehoben.

Siehe auch: start()

trace(text)

Schreibt eine Nachverfolgungsmeldung mit dem Ursprung DeviceManager auf die Konsole.

DeviceHandle

class orbit_framework.devices.DeviceHandle(name, bind_callback, unbind_callback)

Diese Klasse ist die Basisklasse für Geräteanforderungen.

Anstelle diese Klasse direkt zu verwenden, werden die beiden Kindklassen SingleDeviceHandle und MultiDeviceHandle verwendet.

Parameter

name

Der Name der Geräteanforderung. Dieser Name hilft, verschiedene Geräte, die von einer Komponente angesteuert werden, zu unterscheiden.

bind_callback

Eine Funktion, die aufgerufen wird, sobald die Verbindung zu einem Gerät verfügbar ist.

unbind_callback

Eine Funktion, die aufgerufen wird, sobald eine Verbindung zu einem Gerät verloren geht.

Beschreibung

Eine Geräteanforderung repräsentiert die Fähigkeit einer Komponente mit einem Typ von TinkerForge-Brick(let)s zu kommunizieren. Sie entbindet die Komponente aber von der Aufgabe die Verbindung zu den Brick(let)s zu verwalten. Die Komponente wird durch Callbacks darüber informiert, ab wann ein Brick(let) verfügbar ist und ab wann es nicht mehr verfügbar ist. Eine Geräteanforderung kann mehrere Brick(let)s gleichen Typs umfassen. Eine Komponente kann jederzeit alle verfügbaren Brick(let)s einer Geräteanforderung abfragen und ansteuern.

Geräteanforderungen verwalten auch Ereignis-Callbacks für Brick(let)s. Eine Komponente kann durch den Aufruf von register_callback() ein Callback für ein Brick(let)-Ereignis einrichten und die Geräteanforderung übernimmt gemeinsam mit dem DeviceManager die Verwaltung.

Siehe auch: SingleDeviceHandle, MultiDeviceHandle, orbit_framework.Component.add_device_handle(), register_callback()

accept_device(device)

Nimmt ein Gerät in die Geräteanforderung auf. Wird von on_bind_device() aufgerufen.

Siehe auch: on_bind_device()

property devices

Gibt eine Liste mit allen verfügbaren Brick(let)s zurück.

Ein Brick(let) wird durch ein Objekt der entsprechenden TinkerForge-Geräteklasse (wie z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4) repräsentiert.

for_each_device(f)

Führt eine Funktion für alle verfügbaren Geräte dieser Geräteanforderung aus.

property name

Gibt den Namen der Geräteanforderung zurück.

on_add_handle(device_manager)

Wird aufgerufen, wenn die Geräteanforderung im DeviceManager registriert wurde.

Bemerkung

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

Siehe auch: DeviceManager.add_handle(), on_remove_handle()

on_bind_device(device)

Wird aufgerufen, wenn ein beliebiges Gerät verfügbar wird.

Bemerkung

Muss von einer abgeleiteten Klasse überschrieben werden.

Eine Implementierung muss die Methode accept_device() für alle Geräte aufrufen, die der Geräteanforderung entsprechen.

Siehe auch: accept_device()

on_remove_handle()

Wird aufgerufen, wenn die Geräteanforderung im DeviceManager deregistriert wurde.

Bemerkung

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

Siehe auch: DeviceManager.remove_handle(), on_add_handle()

on_unbind_device(device)

Wird aufgerufen, wenn ein beliebiges Gerät nicht mehr verfügbar ist.

Ruft die Methode release_device() auf, wenn das Gerät in dieser Geräteanforderung gebunden ist.

Siehe auch: release_device()

register_callback(event_code, callback)

Richtet ein Callback für ein Brick(let)-Ereignis ein.

Parameter

event_code

Der Code für das Brick(let)-Ereignis. Der Code kann der TinkerForge-Dokumentation entnommen werden. (Z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.CALLBACK_BUTTON_PRESSED)

callback

Das Callback, das bei Eintreten des Ereignisses aufgerufen werden soll. Die Signatur muss dem Ereignis entsprechen und ist der TinkerForge-Dokumentation zu entnehmen.

Beschreibung

Für jeden Ereignis-Code kann in jeder Geräteanforderung immer nur ein Callback registriert werden. Das Callback wird immer aufgerufen, sobald ein verfügbares Brick(let) dieser Geräteanforderung das beschriebene Ereignis auslöst.

Siehe auch: unregister_callback(), DeviceManager.add_device_callback()

release_device(device)

Wird aufgerufen, wenn ein Gerät aus der Geräteanforderung nicht mehr verfügbar ist.

Bemerkung

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

Siehe auch: on_unbind_device()

unregister_callback(event_code)

Meldet ein Callback von einem Brick(let)-Ereignis ab.

Parameter

event_code

Der Code für das Brick(let)-Ereignis.

Siehe auch: register_callback(), DeviceManager.remove_device_callback()

SingleDeviceHandle

class orbit_framework.devices.SingleDeviceHandle(name, device_name_or_id, bind_callback=None, unbind_callback=None, uid=None, auto_fix=False)

Eine Geräteanforderung für ein einzelnes Brick(let).

Parameter

name

Der Name der Geräteanforderung. Der Name wird zur Unterscheidung von mehreren Geräteanforderungen einer Komponente verwendet.

device_name_or_id

Der Typenname oder die Typen-ID des Gerätes. Wird eine Zeichenkette übergeben, wird sie als Name des Brick(let)s interpretiert, z.B. 'LCD 20x4 Bricklet'. Wird eine Zahl übergeben, wird sie als Typen-ID interpretiert, z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.DEVICE_IDENTIFIER.

bind_callback (optional)

Ein Callback das aufgerufen wird, sobald ein Gerät an die Geräteanforderung gebunden wird. Der Standardwert ist None.

unbind_callback (optional)

Ein Callback das aufgerufen wird, sobald ein gebundenes Gerät nicht mehr verfügbar ist. Der Standardwert ist None.

uid (optional)

Die UID eines Brick(let)s. Wenn eine UID angegeben wird, akzeptiert die Geräteanforderung nur genau dieses Brick(let). Wenn keine UID angegeben wird, wird das erste Gerät mit dem angegebenen Gerätetyp akzeptiert. Der Standardwert ist None.

auto_fix (optional)

Gibt an, ob nach der Bindung zwischen einem Gerät und der Geräteanforderung andere Geräte gebunden werden dürfen.

Mögliche Werte sind True, wenn nach dem ersten gebundenen Gerät andere Geräte gebunden werden dürfen, und False, wenn nach einer Bindung nur noch dieses Gerät gebunden werden darf. Der Standardwert ist False.

Beschreibung

Diese Variante einer Geräteanforderung akzeptiert zu jeder Zeit immer nur ein Gerät. Wird keine UID angegeben, um ein konkretes Brick(let) zu beschreiben, wird das erste Brick(let) des angegebenen Gerätetyps aktzeptiert. Wird die Verbindung zum gebundenen Gerät getrennt, entscheidet der Parameter auto_fix ob anschließend das nächste verfügbare Gerät mit dem passenden Typ akzeptiert wird oder ob solange gewartet wird, bis das vormals gebundene Brick(let) wieder verfügbar wird.

Siehe auch: DeviceHandle, MultiDeviceHandle

property device

Gibt das gebundene Brick(let) oder None zurück.

Ein Brick(let) wird durch ein Objekt der entsprechenden TinkerForge-Geräteklasse (wie z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4) repräsentiert.

on_bind_device(device)

Wird aufgerufen, wenn ein beliebiges Gerät verfügbar wird.

Bemerkung

Muss von einer abgeleiteten Klasse überschrieben werden.

Eine Implementierung muss die Methode accept_device() für alle Geräte aufrufen, die der Geräteanforderung entsprechen.

Siehe auch: accept_device()

release_device(device)

Wird aufgerufen, wenn ein Gerät aus der Geräteanforderung nicht mehr verfügbar ist.

Bemerkung

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

Siehe auch: on_unbind_device()

MultiDeviceHandle

class orbit_framework.devices.MultiDeviceHandle(name, device_name_or_id, bind_callback=None, unbind_callback=None)

Eine Geräteanforderung für alle Brick(let)s eines Typs.

Parameter

name

Der Name der Geräteanforderung. Der Name wird zur Unterscheidung von mehreren Geräteanforderungen einer Komponente verwendet.

device_name_or_id

Der Typenname oder die Typen-ID des Gerätes. Wird eine Zeichenkette übergeben, wird sie als Name des Brick(let)s interpretiert, z.B. 'LCD 20x4 Bricklet'. Wird eine Zahl übergeben, wird sie als Typen-ID interpretiert, z.B. tinkerforge.bricklet_lcd_20x4.BrickletLCD20x4.DEVICE_IDENTIFIER.

bind_callback (optional)

Ein Callback das aufgerufen wird, sobald ein Gerät an die Geräteanforderung gebunden wird.

unbind_callback (optional)

Ein Callback das aufgerufen wird, sobald ein gebundenes Gerät nicht mehr verfügbar ist.

Beschreibung

Diese Variante einer Geräteanforderung akzeptiert alle Geräte des angegebenen Gerätetyps.

Siehe auch: DeviceHandle, SingleDeviceHandle

on_bind_device(device)

Wird aufgerufen, wenn ein beliebiges Gerät verfügbar wird.

Bemerkung

Muss von einer abgeleiteten Klasse überschrieben werden.

Eine Implementierung muss die Methode accept_device() für alle Geräte aufrufen, die der Geräteanforderung entsprechen.

Siehe auch: accept_device()

Funktionen

orbit_framework.devices.get_device_identifier(name_or_id)

Ermittelt die Geräte-ID für einen Gerätetyp. Es kann der Name des Gerätetyps oder die Geräte-ID übergeben werden.

orbit_framework.devices.device_identifier_from_name(name)

Gibt die Geräte-ID für einen Namen zurück.

orbit_framework.devices.device_instance(device_identifier, uid, ipcon)

Erzeugt eine TinkerForge-Binding-Instanz anhand der Geräte-ID, der UID und der Verbindung.

orbit_framework.devices.device_name(device_identifier)

Gibt den Namen eines Gerätetyps anhand der Geräte-ID zurück.

orbit_framework.devices.known_device(device_identifier)

Überprüft ob eine Geräte-ID bekannt ist.