Hinweise zur Dokumentation

Diese Beschreibung wendet sich ausschließlich an ausgebildetes Fachpersonal der Steuerungs- und Automatisierungstechnik, das mit den geltenden nationalen Normen vertraut ist.
Zur Installation und Inbetriebnahme der Komponenten ist die Beachtung der nachfolgenden Hinweise und Erklärungen unbedingt notwendig.

Das Fachpersonal hat sicherzustellen, dass die Anwendung bzw. der Einsatz der beschriebenen Produkte alle Sicherheitsanforderungen, einschließlich sämtlicher anwendbaren Gesetze, Vorschriften, Bestimmungen und Normen erfüllt.

Disclaimer

Diese Dokumentation wurde sorgfältig erstellt. Die beschriebenen Produkte werden jedoch ständig weiter entwickelt.
Deshalb ist die Dokumentation nicht in jedem Fall vollständig auf die Übereinstimmung mit den beschriebenen Leistungsdaten, Normen oder sonstigen Merkmalen geprüft.
Falls sie technische oder redaktionelle Fehler enthält, behalten wir uns das Recht vor, Änderungen jederzeit und ohne Ankündigung vorzunehmen.
Aus den Angaben, Abbildungen und Beschreibungen in dieser Dokumentation können keine Ansprüche auf Änderung bereits gelieferter Produkte geltend gemacht werden.

Marken

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE®, XFC® und XTS® sind eingetragene und lizenzierte Marken der Beckhoff Automation GmbH.
Die Verwendung anderer in dieser Dokumentation enthaltenen Marken oder Kennzeichen durch Dritte kann zu einer Verletzung von Rechten der Inhaber der entsprechenden Bezeichnungen führen.

Patente

Die EtherCAT Technologie ist patentrechtlich geschützt, insbesondere durch folgende Anmeldungen und Patente:
EP1590927, EP1789857, DE102004044764, DE102007017835
mit den entsprechenden Anmeldungen und Eintragungen in verschiedenen anderen Ländern.

Die TwinCAT Technologie ist patentrechtlich geschützt, insbesondere durch folgende Anmeldungen und Patente:
EP0851348, US6167425 mit den entsprechenden Anmeldungen und Eintragungen in verschiedenen anderen Ländern.

Copyright

© Beckhoff Automation GmbH & Co. KG, Deutschland.
Weitergabe sowie Vervielfältigung dieses Dokuments, Verwertung und Mitteilung seines Inhalts sind verboten, soweit nicht ausdrücklich gestattet.
Zuwiderhandlungen verpflichten zu Schadenersatz. Alle Rechte für den Fall der Patent-, Gebrauchsmuster- oder Geschmacksmustereintragung vorbehalten.


Allgemein

Das TwinCAT System kann von einer zentralen Stelle aus gestartet bzw. gestoppt werden. Dies geschieht in der Regel manuell durch den Inbetriebnehmer bzw. Entwickler oder programmatisch aufgrund äußerer Einflüsse wie Spannungsausfall oder Windows Shutdown. Um einer Applikationssoftware mehr Einfluss auf das TwinCAT System zu ermöglichen, wurde ein COM Objekt im TwinCAT System Service eingeführt.

Einsatz

Über das TwinCAT System Objekt kann TwinCAT z.B. gestartet oder auch gestoppt werden, durch den Einsatz von COM/DCOM ist dies auch per Netzwerk möglich. Weiterhin kann über dieses COM Objekt auch der Zustand (RUN bzw. STOP) erfragt werden, auf Wunsch können auch COM Events zur Signalisierung eines Start bzw. Stop des TwinCAT Systems ausgelöst werden. Nun ist es zum Beispiel für eine Applikation möglich, über den Zustandswechsel eines entfernten TwinCAT Systems informiert zu werden.


TcSystemServer (CoClass)

In der Klasse TcSystemServer ist das COM Interface zum TwinCAT System implementiert. TcSystemServer bietet zusätzlich zum ADS die Möglichkeit, dass TwinCAT System über COM/DCOM zu steuern. Gegenüber der ADS Kommunikation bietet COM die Möglichkeit, auch ein gestopptes TwinCAT zu starten und darüber hinaus auch Ereignisse zum TwinCAT Start bzw. Stop empfangen zu können. Dank DCOM sind alle Funktionen auch per Netzwerk erreichbar.

Das default Interface von TcSystemServer heißt ITcSystemServer, implementiert ist TcSystemServer als "Out of Process Server" in der EXE-Datei "TCATSysSrv.exe".


ITcSystemServer

TwinCAT System COM Objekt: Referenz

ITcSystemServer - Überblick

Über das Interface ITcSystemServer kann das TwinCAT System gesteuert werden. ITcSystemServer ist als OLE Automation Interface ausgeführt, so dass es auch von Scriptsprachen wie Visual Basic Script genutzt werden kann.

Methoden in Vtable Reihenfolge

IUnknown Methoden | Beschreibung
QueryInterface | Liefert einen Zeiger auf das angeforderte Interface zurück.
AddRef | Inkrementiert den Referenzzähler.
Release | Dekrementiert den Referenzzähler.

IDispatch Methoden | Beschreibung
GetTypeInfoCount | Liefert die Anzahl der "Type Information" Interfaces, die ein Objekt anbietet. (0 or 1).
GetTypeInfo | Holt die Typinformationen für ein Objekt.
GetIDsOfNames | Verknüpft Namen von Methoden mit optionalen Argumenten mit einem zugehörigem Satz von DISPIDs.
Invoke | Bietet den Zugriff auf Eigenschaften und Methoden eines Objekts.

ITcSystemServer Methoden | Beschreibung
StartSystem | Startet das TwinCAT System.
StopSystem | Stoppt das TwinCAT System.
RestartSystem | Stop mit nachfolgendem Start des TwinCAT Systems.
SaveServerCfg | Fordert alle TwinCAT COM Server auf, ihre Konfiguration in die TwinCAT Projektdatei (*.tps) zu speichern.
SystemState | Eigenschaft, die den aktuellen Zustand des TwinCAT System anzeigt.
AmsNetId | Eigenschaft mit der die AmsNetId eines TwinCAT Systems erfragt werden kann.
RtcTimeDiff | Eigenschaft mit der die aktuelle Zeitdifferenz der Windows NT Systemzeit zur Echtzeituhr des PC anzeigt wird.
AdjustSystemTimeToRtcTime | Synchronisiert die Windows NT Systemzeit zur Echtzeituhr des PC.


_ITcSystemEvents

Über das Event-Interface _ITcSystemEvents kann sich eine Applikation für die unten aufgeführten Ereignisse anmelden. Das Event-Interface ist als OLE Connection Point implementiert und kann somit von Visual Basic sehr einfach eingebunden werden. Für die Einbindung in andere Programmiersprachen wie z.B. C++ gibt es einige Beispiele in der MSDN Library.

Methoden in Vtable Reihenfolge

IUnknown Methoden | Beschreibung
QueryInterface | Liefert einen Zeiger auf das angeforderte Interface zurück.
AddRef | Inkrementiert den Referenzzähler.
Release | Dekrementiert den Referenzzähler.

IDispatch Methoden | Beschreibung
GetTypeInfoCount | Liefert die Anzahl der "Type Information" Interfaces, die ein Objekt anbietet (0 or 1).
GetTypeInfo | Holt die Typinformationen für ein Objekt.
GetIDsOfNames | Verknüpft Namen von Methoden mit optionalen Argumenten mit einem zugehörigem Satz von DISPIDs.
Invoke | Bietet den Zugriff auf Eigenschaften und Methoden eines Objekts.

_ITcSystemEvents Methoden | Beschreibung
OnSystemStart | Signalisiert den Start eines TwinCAT Systems.
OnSystemStop | Signalisiert den Stop eines TwinCAT Systems.


ITcSystemServer:StartSystem

ITcSystemServer::StartSystem

Methode zum Start des TwinCAT Systems per COM/DCOM.

HRESULT StartSystem(
  [in,optional] VARIANT startParm,
);

Parameters

startParm
[in,optional]
Optionaler Startparameter, der zur Zeit noch nicht ausgewertet wird.

Return Values

HRESULT == S_OK
TwinCAT Start erfolgreich durchgeführt.
HRESULT == E_FAIL
Start konnte nicht durchgeführt werden.

Bemerkungen

StartSystem startet das TwinCAT System auf dem Rechner, auf dem das TcSystemServer Objekt instanziert wurde. Alle Meldungen werden in die dortige Windows Ereigniszeige geschrieben.


ITcSystemServer:StopSystem

ITcSystemServer::StopSystem

Methode zum Stoppen des TwinCAT Systems per COM/DCOM.

HRESULT StartSystem(
  [in,optional] VARIANT stopParm,
);

Parameters

stopParm
[in,optional]
Optionaler Stopparameter, der zur Zeit noch nicht ausgewertet wird.

Return Values

HRESULT == S_OK
TwinCAT Stop erfolgreich durchgeführt.
HRESULT == E_FAIL
Fehler beim Stoppen des TwinCAT Systems.

Bemerkungen

StopSystem stoppt das TwinCAT System auf dem Rechner, auf dem das TcSystemServer Objekt instanziert wurde. Alle Meldungen werden in die dortige Windows Ereigniszeige geschrieben. Auch wenn StopSystem einen Fehler zurückliefert, ist das betreffende TwinCAT System gestoppt.


ITcSystemServer:RestartSystem

ITcSystemServer::RestartSystem

Methode zum Stop mit nachfolgendem Start des TwinCAT Systems per COM/DCOM.

HRESULT RestartSystem(
  [in,optional] VARIANT restParm,
);

Parameters

restParm
[in,optional]
Optionaler Pparameter, der zur Zeit noch nicht ausgewertet wird.

Return Values

HRESULT == S_OK
TwinCAT Restart erfolgreich durchgeführt.
HRESULT == E_FAIL
Fehler beim Restart des TwinCAT Systems.

Bemerkungen

RestartSystem stoppt und startet danach das TwinCAT System auf dem Rechner, auf dem das TcSystemServer Objekt instanziert wurde. Alle Meldungen werden in die dortige Windows Ereigniszeige geschrieben. Wenn RestartSystem einen Fehler zurückliefert, ist das betreffende TwinCAT System im Stop-Zustand.


ITcSystemServer:SaveServerConfig

ITcSystemServer::SaveServerConfig

Diese Methode veranlassst alle bei TwinCAT angemeldeten COM/DCOM Server ihre Konfiguration zu speichern.

HRESULT SaveServerConfig(
  [in,optional] VARIANT saveParm,
);

Parameters

saveParm
[in,optional]
Falls nur ein bestimmter COM-Server seine Daten sichern soll, kann in "saveParm" die entsprechende Class-ID als BSTR übergeben werden.

Return Values

HRESULT == S_OK
Sicherung erfolgreich durchgeführt.
HRESULT != S_OK
Fehler beim Sichern.

Bemerkungen

Der Aufruf dieser Methode kann je nach Konfiguration einige Zeit in Anspruch nehmen und sollte deshalb nur aufgerufen werden wenn es applikationsbedingt notwendig ist.


ITcSystemServer:SystemState

ITcSystemServer::SystemState

Eigenschaft (Property), die den aktuellen Zustand des TwinCAT Systems anzeigt.

HRESULT SystemState(
  [out,retval] long* pVal,
);

Parameters

pVal
[out, retval]
Der Wert in pVal zeigt den Zustand des TwinCAT Systems an. Aktuell sind die Zustände ADSSTATE_RUN (5) und ADSSTATE_STOP (6) implemetiert.

Return Values

HRESULT == S_OK
Lesen erfolgreich durchgeführt.
HRESULT != S_OK
Fehler beim Lesen des aktuellen Status.

Bemerkungen

Bei Aufruf von SystemState wird der aktuelle Zustand des TwinCAT Systems zurückgeliefert.


ITcSystemServer:AmsNetId

ITcSystemServer::AmsNetId

Eigenschaft (Property), die die AmsNetId des betreffenden TwinCAT Systems als String zurückliefert.

HRESULT AmsNetId(
  [out,retval] BSTR* pVal,
);

Parameters

pVal
[out, retval]
In pVal wird die 6 Byte AmsNetId als Basic String (BSTR) zurückgeliefert.

Return Values

HRESULT == S_OK
Lesen erfolgreich durchgeführt.
HRESULT != S_OK
Fehler beim Lesen der AmsNetId.

Bemerkungen

Nach dem Aufruf von AmsNetId steht die AmsNetId als Zeichenkette zur Verfügung. Der Speicher für die Zeichenkette wird vom System zur Verfügung gestellt und muss nicht von der Aufrufen Applikation alloziert werden. Wird diese Methode von C bzw. C++ ohne "Wrapper" Funktionen aufgerufen, so ist die aufrufende Applikation dafür verantwortlich den Speicher mit SysFreeString wieder freizugeben.


_ITcSystemEvents:OnSystemStart

_ITcSystemEvents::OnSystemStart

Methode, die nach dem Start des TwinCAT Systems aufgerufen wird.

HRESULT OnSystemStart(
  [in,optional] VARIANT startParm,
);

Parameters

startParm
[in,optional]
Optionaler Startparameter, der zur Zeit noch nicht ausgewertet wird.

Return Values

Die Rückgabewerte werden nicht ausgewertet.

Bemerkungen

OnSystemStart wird nach dem erfolgreichen Start von TwinCAT aufgerufen. Wenn dieses Ereignis signalisiert wird, sind alle Bestandteile von TwinCAT gestartet.


_ITcSystemEvents:OnSystemStop

_ITcSystemEvents::OnSystemStop

Methode, die beim Stop des TwinCAT Systems aufgerufen wird.

HRESULT OnSystemStop(
  [in,optional] VARIANT stopParm,
);

Parameters

stopParm
[in,optional]
Optionaler Parameter, der zur Zeit noch nicht ausgewertet wird.

Return Values

Die Rückgabewerte werden nicht ausgewertet.

Bemerkungen

OnSystemStop wird vor dem endgültigen Stop von TwinCAT aufgerufen.


ITcSystemServer: RtcTimeDiff

ITcSystemServer::RtcTimeDiff

Eigenschaft, in der die aktuelle Zeitdifferenz (in Sekunden) der Windows NT System Zeit zur Echtzeituhr des PC angezeigt wird.

HRESULT RtcTimeDiff(
  [out,retval] LONG* pVal,
);

Parameters

pVal
[out, retval]
In pVal wird die aktuelle Zeitdifferenz in Sekunden als Long Wert zurückgeliefert.

Return Values

HRESULT == S_OK
Lesen erfolgreich durchgeführt.
HRESULT != S_OK
Fehler beim Lesen der Zeitdifferenz.

Bemerkungen

Durch den Aufruf von RtcTimeDiff werden die aktuellen Werte der Echtzeituhr (RTC bzw. CMOS Clock) gelesen und mit der Windows NT Systemzeit verglichen. Die Differenz ergibt sich aus NT Systemzeit minus RTC-Zeit. Da die Systemzeit pro Tag maximal 1 Sekunde von der RTC Zeit abweicht, sind häufige Aufrufe dieser Funktion unnötig.


ITcSystemServer:AdjustSystemTimeToRtcTime

ITcSystemServer::AdjustSystemTimeToRtcTime

Methode zur Anpassung der Windows NT Systemzeit an die Echtzeituhr des PC.

HRESULT AdjustSystemTimeToRtcTime(
  [in,optional] VARIANT parm,
);

Parameters

parm
[in,optional]
Optionaler boolescher Wert, der bestimmt ob die TwinCAT Systemzeit mit angeglichen werden soll. Parm gleich TRUE bedeutet, dass die TwinCAT Systemzeit angeglichen wird, FALSE oder kein Parameter bedeutet, dass nur die Windows NT Systemzeit angepasst wird. Beim Aufruf von C++ ist zu beachten, dass der übergebene Parameter vom Typ VT_BOOL ist und TRUE dem Wert 0xFFFF entspricht.

Return Values

HRESULT == S_OK
Anpassung erfolgreich durchgeführt.
HRESULT == E_FAIL
Start konnte nicht durchgeführt werden.

Bemerkungen

AdjustSystemTimeToRtcTime vergleicht die Echtzeituhr mit der Windows NT Systemzeit und korrigiert die Windows NT Systemzeit um die ermittelte Differenz. Zeitzonen und Sommerzeit werden dabei berücksichtigt. Falls im optionalen Parameter ein TRUE übergeben wird, so wird auch die TwinCAT Systemzeit korrigiert. Zu Beachten ist, dass es durch die Korrektur zu Zeitsprüngen während Messungen oder Logbuchaufzeichnungen kommen kann.