Y.A.R.D. - API

Um die Einbindung von Y.A.R.D. in andere Software zu erleichtern?, habe ich mich entschieden, daß die yards.exe einen COM-Server enthalten sollte - welchen man auch von VB, Delphi und C++ aus erreichen kann.
Bevor man hier weiterliest sollte man erstmal im Generellen damit vertraut sein wie COM funktioniert und man es benutzt.

Laufende Instanz ermitteln

Wer meine zur Verfügung gestellten Pascalsourcen verwendet, kann direkt auf die Funktionen der Unit yardTools.pas zugreifen. Diese erledigen alle notwendigen Low-Level API aufruf (Rund-um-sorglos-paket).

function getYard:IYard;

Liefert einen Interface Zeiger auf eine laufende Instanz der yards.exe, wenn keine aktive yards.exe vorhanden ist liefert die Funktion nil zurück.

function getStartYard:IYARD.;

Diese Funktion liefert einen Interface Zeiger auf eine laufende Instanz der yards.exe, wenn keine yards.exe gestartet ist - wird dieser gestartet. Sofern die yards.exe mindestens einmal vorher gestartet und konfiguriert wurde, wenn das nicht der Fall ist liefert diese Funktion ebenfalls nil.

Native Zugriff

Wer nicht meine API verwendet sollte sich an dieses Verfahren halten:
  1. GetActiveObject(CLASS_YARD.,nil,aUNK);
  2. aUNK.QueryInterface(IID_IYard, myYardInstance);
wenn GetActiveObject keine Instanz ermitteln konnte, muß diese mittels CreateProcess gestartet werden. Den Namen des ExeServers habe ich der Einfachheit halber in der Registry abgespeichert. Im Schlüssel HKCU\Software\Webers\Y.A.R.D\ gibt es einen Eintrag program in diesem steht der vollständige Dateiname der Serveranwendung. Bevor man nach dem CreateProcess versucht mittels GetActiveObject das Interface zu erhalten sollte man darauf warten das der Server in den Idle Status übergegangen ist. Das Geschieht mit der Funktion WaitForInputIdle(pinf.hProcess,10000); die 10 Sekunden haben bei mir bisher immer gereicht, damit der Serverprozess in den Status Idle eintritt und somit für die externe Benutzung zur Verfügung steht.

Achtung: Y.A.R.D. Server nicht über CoCreateInstance starten!

Die Funktionen des Interfaces IYard

Über dieses Interfaces können die Funktionen der Y.A.R.D. Hardware aufgerufen werden. Die Schnittstelle ist Threadsafe. Die Serialisierung der Zugriff auf die Hardware erfolgt im Serverprozess. Bei schwerwiegenden Fehler werden Exceptions ausgelöst.
Funktion Parameter
SendRemoteKey
RemoteName: WideString; Name der Fernbedienung, wie im Y.A.R.D.server hinterlegt (Der Vergleich erfolgt nicht casesensitiv!)
KeyName: WideString; Name der Taste der FB wie im Y.A.R.D.server hinterlegt (Der Vergleich erfolgt nicht casesensitiv!)
NumRepeats: Integer Anzahl der Wiederholungen die gesendet werden sollen. Mindestens 1, bei einigen Protokollen werden aber automatisch mindestens 2 Wiederholungen gesendet. (Sony)
Rückgabewert: WordBool ist True wenn der RemoteName und der Tastenname im Y.A.R.D. Server bekannt sind, andernfalls False Bei Kommunikationsfehlern werden Exceptions ausgelöst.

Mit dieser Funktion werden IR-Befehle gesendet, wobei man sich als Anwender keine Gedanken darüber machen muss wie der Befehl kodiert wird.
Die Funktion wartet nach dem senden des IR-Codes noch solange, dass sofort nach der Rückkehr der Funktion zum Aufrufenden ein neuer Aufruf erfolgen kann, ohne dass dadurch die Zeit zwischen zwei IR-Übertragungen zu kurz wird. Die Wartezeit kann über den Y.A.R.D. Server in der Seite IR-Protokolle konfiguriert werden. Die exakte Dauer wird durch das verwendete IR-Protokoll festgelegt.

Funktion Parameter
SendIrCode
protocolName: WideString; Name des Protokolls, wie im Y.A.R.D.server hinterlegt (Der Vergleich erfolgt nicht casesensitiv!)
codeSeq: WideString; Hexadezimale Darstellung des Codepaketes beginnend mit 0x gefolgt von bis zu 6 Bytes in hexadezimaler Notation, oder ohne 0x am Anfang in Binäre Notation. Die Anzahl der Bits die mindestens erforderlich sind steht im jeweiligen Protokoll. Achtung: Bei Protokollen mit Stopbits müssen diese ebenfalls mit enthalten sein.
NumRepeats: Integer Anzahl der Wiederholungen die gesendet werden sollen. Mindestens 1, bei einigen Protokollen werden aber automatisch mindestens 2 Wiederholungen gesendet. (Sony)
Rückgabewert: WordBool ist True wenn der Protokollname im Y.A.R.D. Server bekannt sind, andernfalls False Bei Kommunikationsfehlern werden Exceptions ausgelöst.

Diese Funktion kann verwendet werden um beliebige IR-Codes zu senden, man kann damit auch fortlaufende Probesendungen durchführen.

Funktion Parameter
GetWakeupTime keine Parameter
Rückgabewert: TDateTime (varDate) Bei Kommunikationsfehlern werden Exceptions ausgelöst.

Liefert die aktuell eingestellte Weckzeit zurück.

Funktion Parameter
GetTime keine Parameter
Rückgabewert: TDateTime (varDate) Bei Kommunikationsfehlern werden Exceptions ausgelöst.

Liefert die aktuelle Uhrzeit der Hardware zurück.

Funktion Parameter
SetWakeupTime
DateTimeValue: DateTime; DateTimeValue = Zeit wann Y.A.R.D. den PC einschalten soll.
Rückgabewert: bool true - wenn Weckzeit gesetzt werden konnte, false - wenn Y.A.R.D. nicht reagiert hat(bedingt).

Dient zum Einstellen der Weckzeit. Das Datum muss nach dem 1.1.2005 liegen. (Da der 1.1.2005 die Bezugszeit für Y.A.R.D. darstellt.)

Funktion Parameter
SetSecondWakeupTime
DateTimeValue: DateTime; DateTimeValue = Zeit wann Y.A.R.D. den PC einschalten soll.
Rückgabewert: bool true - wenn Weckzeit gesetzt werden konnte, false - wenn Y.A.R.D. nicht reagiert hat(bedingt).

Dient zum Einstellen der 2. Weckzeit. Das Datum muss nach dem 1.1.2005 liegen. (Da der 1.1.2005 die Bezugszeit für Y.A.R.D. darstellt.) Diese hat derzeit noch keine spezielle Bedeutung...,d.h. kann frei verwendet werden. z.b. um den HTPC als Wecker zu missbrauchen.

Funktion Parameter
SetTime
DateTimeValue: DateTime; DateTimeValue = Uhrzeit die in der Hardware eingestellt werden soll.

Uhrzeit der Hardware einstellen. Das Datum muss nach dem 1.1.2005 liegen. Dieser Vorgang ist relativ kritisch, da der Funktionsaufruf ein gewisse Latenzzeit besitzt bis die Zeit eingestellt ist und die Uhr damit wieder anläuft.
Daher muss das Einstellen der Zeit nach diesem Schema erfolgen:

  • Aktuelle Zeit vom PC auslesen + auf diese 1.5ms addieren
  • SetTime mit der inkrementierten Zeit aufrufen
Woher die 1.5ms? - der Y.A.R.D. Befehl in Serieller Notation ist 7 Byte lang. (4-Byte als Zeit in Sekunden, +3 Byte fürs Protocol) bei einer Übertragungsrate von 57600 Bit/s - dauert die Übertragung alleine schon 1,09ms dazu kommt noch die Dauer für den Aufruf der COM-Schnittstelle u.s.w.

Funktion Parameter
GetBootReason keine Parameter

Liefert als Wert der Aufzählung PowerOnReasons den Grund warum Y.A.R.D. den PC eingeschaltet hat. Z.b. wenn PowerOnReason = porPowerOnReturn ist wurde der PC neu gestartet damit die Clientsoftware die Uhr und die Weckzeit neu einstellen kann und danach den PC wieder ausschalten kann.
Funktion Parameter
ReadUserPort
portNr: Integer Nummer des Ports (derzeit gibt es nur PortNr=0!)
Rückgabewert: bool ist True wenn der freie Eingang des µC einen H-Pegel anliegen hat, bzw. False wenn der Pegel-L ist.

Mit dieser Funktion kann der Status des freien Ports vom µC ausgelesen werden.

Funktion Parameter
Read_I2C
adresse: SmallInt Adresse des Gerätes am I2C Bus Zahl zwischen 0 und 127
adressenumReadBytes: SmallInt Anzahl der Bytes die von dem Gerät gelesen werden sollen. Die Anzahl muss kleiner als 127 Byte sein. (bedingt durch das serielle Y.A.R.D. Protokol)
firstWriteBytesArray: OleVariant Wenn vor dem Lesen der Daten bestimmte Bytes an das Gerät gesendet werden sollen müssen diese als ein Array of bytes in diesem Variant übergeben werden. (z.b. wenn aus einem I2C EEprom gelesen werden soll, muß vorher die Adresse selektiert werden)

Rückgabewert: OleVariant mit dem Inhalt der gelesenen Bytes als Variant ByteArray

Funktion Parameter
Write_I2C
adresse: SmallInt Adresse des Gerätes am I2C Bus Zahl zwischen 0 und 127
Daten: OleVariant ByteArray als Variant, dass die Daten enthält welche über den I2C Bus an das Gerät gesendet werden sollen. Das Array darf momentan lediglich 32 Byte Nutzdaten enthalten.

Rückgabewert: bool, true=ok, false=fehler, bei anderen Fehlern wie gehabt Exceptions.

Funktion Parameter
GetFirmwareVersion  

Rückgabewert: integer Zahl zwischen 0 und 255 als Versionsnummer der Firmware.

Funktion Parameter
RegisterNotifier
notifier: IYardNotification Der Notifier ist ein COM Objekt, das das IYardNotification Interface implementiert, Y.A.R.D. ruft dessen Methoden auf um z.B. Nachrichten über eingegangen IR-Befehle zu übermitteln.

Diese Funktion ist kein direkt an die Hardware abgesetzter Befehl, sondern registriert lediglich eine Schnittstelle zur Benachrichtigung über empfangener IR-Befehle. Das Zurückgelieferte Handle muss aufgehoben werden, damit eine Clientanwendung bei Ihrem Programmende den registrierten Notifier abmelden kann.

Funktion Parameter
UnRegisterNotifier
handle: integer Handle welches beim Aufruf der Funktion RegisterNotifier zurückgegeben wurde.

UnRegisterNotifier meldet den Notifier ab welcher unter dem übergebenen Handle registriert ist. Ein Programm muss alle seine Handler bei Programmende abmelden - sonst kann der Y.A.R.D.server beim nächsten Versuch eine Benachrichtigung zu verschicken crashen.
Seit der aktuellen Version, existiert parallel zum IYardNotifcation Interface noch ein IYardNotifcation2 Interface, welches IDispatch fähig ist und somit auch in VB und Python genutzt werden kann. Allerdings nicht über die Methoden RegisterNotifier und UnRegisterNotifier - hier müssen die Funktionen für COM Ereignisbehandlung verwendet werden.

Funktion Parameter
GetRemotes  

Rückgabewert: IYardRemotes Objekt mit Schnittstelle zum durchmustern oder finden einer bestimmten FB.

Die Funktionen des Interfaces IYardRemotes

Über dieses Interfaces kann man sich die Liste der im Yards Server definierten Fernbedienungen abrufen.
Funktion Parameter
get_count  

Rückgabewert: integer Anzahl der Fernbedienungen die im Y.A.R.D.s Server definiert sind.

Funktion Parameter
FindRemote
RemoteName: String Name der gesuchten FB

Rückgabewert: IYardRemote Interface für den Zugriff auf die Eigenschaften der FB.

Die Liste der Fernbedienungen nach einer mit dem gegebenen Namen suchen. Gross und Kleinschreibung wird dabei nicht berücksichtigt. Wird keine FB gefunden liefert diese Funktion NIL.

Funktion Parameter
Get_Item
index: integer Index der FB von 0 bis count-1

Rückgabewert: IYardRemote Interface für den Zugriff auf die Eigenschaften der FB.

Liefert eine bestimmte FB der Liste.

Die Funktionen des Interfaces IYardRemote

Über dieses Interfaces kann man die Eigenschaften einer FB abrufen, Name, Anzahl der Tasten etc.
Funktion Parameter
get_name (name)  

Rückgabewert: String Name der Fernbedienung.

Funktion Parameter
FindKey
KeyName: String Name der gesuchten Taste

Rückgabewert: IYardRemoteKey Interface für den Zugriff auf die Eigenschaften einer Taste.

Die Liste der Tasten nach einer mit dem gegebenen Namen durchsuchen. Gross und Kleinschreibung wird dabei nicht berücksichtigt. Wird keine Taste gefunden liefert diese Funktion NIL.

Funktion Parameter
get_count (count)  

Rückgabewert: Integer Anzahl der Tasten dieser Fernbedienung.

Funktion Parameter
Get_Keys
index: integer Index der Taste von 0 bis count-1

Rückgabewert: IYardRemoteKey Interface für den Zugriff auf die Eigenschaften einer Taste.

Liefert eine bestimmte Taste der FB.

Die Funktionen des Interfaces IYardRemoteKey

Über dieses Interfaces kann man die Eigenschaften einer Taste abrufen, Name, Code und IR-Protokoll.
Funktion Parameter
get_name (name)  

Rückgabewert: String Name der Taste.

Funktion Parameter
Get_Code (code)  

Rückgabewert: String Hexadezimale oder Bimäre Darstellung des IR-Codes.

Funktion Parameter
Get_Protocol (Protocol)  

Rückgabewert: String Namen des verwendeten IR-Protokolls.

Da ich mir sicher bin das meine Beschreibung nicht aussreicht habe ich in der Sourcedistribution eine Beispielanwendung untergebracht, welche fast alle Funktionen demonstriert. Der Quellecode ist im Ordner Y.A.R.D.-client-sample des Source-Zips zu finden.







Home Firmware Clientsoftware Hardware Teileliste Preisliste Downloads Impressum