Handbuch TC3 IoT Communicator - Beckhoff Automation · Erforderliche TwinCAT-LizenzTF6730 TC3 IoT...

Handbuch

TC3 IoT Communicator

TwinCAT 3

1.103.04.2018TF6730

Version:Datum:Bestell-Nr.:

Inhaltsverzeichnis

TC3 IoT Communicator 3Version: 1.1

Inhaltsverzeichnis1 Vorwort ....................................................................................................................................................... 5

1.1 Hinweise zur Dokumentation .......................................................................................................... 51.2 Sicherheitshinweise ........................................................................................................................ 6

2 Übersicht .................................................................................................................................................... 7

3 Installation.................................................................................................................................................. 83.1 Systemvoraussetzungen ................................................................................................................ 83.2 Installation....................................................................................................................................... 83.3 Lizenzierung ................................................................................................................................... 8

4 Technische Einführung........................................................................................................................... 134.1 MQTT............................................................................................................................................ 13

4.1.1 Broker............................................................................................................................... 134.1.2 Topicstruktur .................................................................................................................... 134.1.3 Quality of Service............................................................................................................. 13

4.2 Sicherheit ...................................................................................................................................... 154.2.1 Authentifizierung .............................................................................................................. 154.2.2 Verschlüsselung............................................................................................................... 15

5 Konfiguration ........................................................................................................................................... 165.1 Attribute ........................................................................................................................................ 16

6 SPS API .................................................................................................................................................... 176.1 Funktionsbausteine....................................................................................................................... 17

6.1.1 FB_IotCommunicator ....................................................................................................... 176.1.2 FB_IotCommand.............................................................................................................. 20

6.2 Datentypen ................................................................................................................................... 226.2.1 ST_IotCommunicatorTls .................................................................................................. 22

7 Beispiele................................................................................................................................................... 237.1 Applikationsbeispiel ...................................................................................................................... 23

8 Support und Service ............................................................................................................................... 25

Inhaltsverzeichnis

TC3 IoT Communicator4 Version: 1.1

Vorwort


1 Vorwort

1.1 Hinweise zur DokumentationDiese Beschreibung wendet sich ausschließlich an ausgebildetes Fachpersonal der Steuerungs- undAutomatisierungstechnik, das mit den geltenden nationalen Normen vertraut ist.Zur Installation und Inbetriebnahme der Komponenten ist die Beachtung der Dokumentation und dernachfolgenden Hinweise und Erklärungen unbedingt notwendig. Das Fachpersonal ist verpflichtet, für jede Installation und Inbetriebnahme die zu dem betreffenden Zeitpunktveröffentliche Dokumentation zu verwenden.

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

Disclaimer

Diese Dokumentation wurde sorgfältig erstellt. Die beschriebenen Produkte werden jedoch ständig weiterentwickelt.Wir behalten uns das Recht vor, die Dokumentation jederzeit und ohne Ankündigung zu überarbeiten und zuändern.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 eingetrageneund lizenzierte Marken der Beckhoff Automation GmbH.Die Verwendung anderer in dieser Dokumentation enthaltenen Marken oder Kennzeichen durch Dritte kannzu einer Verletzung von Rechten der Inhaber der entsprechenden Bezeichnungen führen.

Patente

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

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

EtherCAT® ist eine eingetragene Marke und patentierte Technologie lizensiert durch die BeckhoffAutomation GmbH, Deutschland

Copyright

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

Vorwort


1.2 Sicherheitshinweise

Sicherheitsbestimmungen

Beachten Sie die folgenden Sicherheitshinweise und Erklärungen!Produktspezifische Sicherheitshinweise finden Sie auf den folgenden Seiten oder in den Bereichen Montage,Verdrahtung, Inbetriebnahme usw.

Haftungsausschluss

Die gesamten Komponenten werden je nach Anwendungsbestimmungen in bestimmten Hard- und Software-Konfigurationen ausgeliefert. Änderungen der Hard- oder Software-Konfiguration, die über diedokumentierten Möglichkeiten hinausgehen, sind unzulässig und bewirken den Haftungsausschluss derBeckhoff Automation GmbH & Co. KG.

Qualifikation des Personals

Diese Beschreibung wendet sich ausschließlich an ausgebildetes Fachpersonal der Steuerungs-,Automatisierungs- und Antriebstechnik, das mit den geltenden Normen vertraut ist.

Erklärung der Symbole

In der vorliegenden Dokumentation werden die folgenden Symbole mit einem nebenstehendenSicherheitshinweis oder Hinweistext verwendet. Die Sicherheitshinweise sind aufmerksam zu lesen undunbedingt zu befolgen!

GEFAHR

Akute Verletzungsgefahr!Wenn der Sicherheitshinweis neben diesem Symbol nicht beachtet wird, besteht unmittel-bare Gefahr für Leben und Gesundheit von Personen!

WARNUNG

Verletzungsgefahr!Wenn der Sicherheitshinweis neben diesem Symbol nicht beachtet wird, besteht Gefahr fürLeben und Gesundheit von Personen!

VORSICHT

Schädigung von Personen!Wenn der Sicherheitshinweis neben diesem Symbol nicht beachtet wird, können Personengeschädigt werden!

Achtung

Schädigung von Umwelt oder GerätenWenn der Hinweis neben diesem Symbol nicht beachtet wird, können Umwelt oder Gerätegeschädigt werden.

Hinweis

Tipp oder FingerzeigDieses Symbol kennzeichnet Informationen, die zum besseren Verständnis beitragen.

Übersicht


2 ÜbersichtMit den Funktionsbausteinen der SPS-Bibliothek Tc3_IoTCommunicator kann ein Datenaustausch zwischender lokalen TwinCAT SPS und einem mobilem Endgerät (Smart Device) über einen MQTT-Message-Brokerrealisiert werden. Symbole können hierbei sowohl gesendet als auch empfangen werden. Nachrichtenkönnen auf dem Broker gespeichert und via Smart Device gelesen und gelöscht werden. Dazu muss aufdem mobilen Endgerät die TwinCAT IoT Communicator App installiert und ausgeführt werden.

Die TwinCAT IoT Communicator App steht im Apple AppStore und Google PlayStore kostenfrei zumDownload zur Verfügung.

Google Play and the Google Play logo are trademarks of Google Inc.

Installation


3 Installation

3.1 SystemvoraussetzungenTechnische Daten BeschreibungBetriebssystem Windows 7/10, Windows Embedded Standard 7, Windows CE 7Zielplattform PC-Architektur (x86, x64 und ARM)Minimale TwinCAT-Version TwinCAT 3.1 Build 4022.0 und höherErforderliches TwinCAT-Setup-Level TwinCAT 3 XAE, XARErforderliche TwinCAT-Lizenz TF6730 TC3 IoT CommunicatorEinzubindende TwinCAT-Bibliothek TC3_IotCommunicator

3.2 InstallationFür die Function TF6730 IoT Communicator wird kein separates Setup benötigt. Die benötigten Treiber-Komponenten werden direkt mit dem TwinCAT Setup (XAE und XAR) ausgeliefert.

3.3 LizenzierungDie TwinCAT 3 Function ist zusätzlich zur Vollversion auch in einer 7-Tage Testversion freischaltbar. BeideLizenztypen sind über TwinCAT XAE aktivierbar. Weitere Information zum TwinCAT 3Lizenzierungsverfahren finden Sie im TwinCAT 3 Hilfesystem. Das folgende Dokument beschreibt denLizenzierungsvorgang einer TwinCAT 3 Function und gliedert sich dabei in die folgenden beidenUnterkapitel:

• Lizenzierung einer 7-Tage Testversion [} 8]

• Lizenzierung einer Vollversion [} 9]

Lizenzierung einer 7-Tage Testversion1. Starten Sie TwinCAT XAE2. Öffnen Sie ein bestehendes TwinCAT 3 Projekt, oder legen Sie ein neues Projekt an3. Navigieren Sie im Solution Explorer zum Eintrag System\License

Installation


4. Öffnen Sie die Registerkarte Manage Licenses und fügen Sie eine Runtime License für Ihr Produkthinzu (in diesem Screenshot TE1300: TC3 Scope View Professional)

5. Optional : Möchten Sie die Lizenz für ein Remote Gerät hinzufügen, müssen Sie sich zunächst mitdiesem Gerät über die TwinCAT XAE Toolbar verbinden

6. Aktivieren Sie in der Registerkarte Order Information über den Button Activate 7 Days TrialLicense... eine Testversion

7. Starten Sie im Anschluss daran das TwinCAT 3 System einmal neu

Lizenzierung einer Vollversion8. Starten Sie TwinCAT XAE9. Öffnen Sie ein bestehendes TwinCAT 3 Projekt oder legen Sie ein neues Projekt an

Installation


10. Navigieren Sie im Solution Explorer zum Eintrag SYSTEM/License

11. Öffnen Sie die Registerkarte Manage Licenses und fügen Sie eine Runtime License für Ihr Produkthinzu (in diesem Screenshot TE1300: TC3 Scope View Professional).

12. Optional: Möchten Sie die Lizenz für ein Remote Gerät hinzufügen, müssen Sie sich zunächst mitdiesem Gerät über die TwinCAT XAE Toolbar verbinden

13. Öffnen Sie die Registerkarte Order InformationDie Felder System-ID und HW Platform können nicht geändert werden, sie beschreiben die zulizensierende Plattform. Generell wird eine TwinCAT 3 Lizenz an zwei Kennzahlen gebunden:Die System-ID identifiziert Ihr Gerät eindeutig.Die HW Platform ist eine Kennzahl für die Performanz des Gerätes.

14. Tragen Sie optional eine eigene Bestellnummer und einen Kommentar für Ihre Zwecke ein

Installation


15. Generieren Sie in der Registerkarte Order Information über den Button Generate License RequestFile... eine Lizenzanforderungs-Datei, die durch einen Beckhoff-Lizenzserver validiert wird (wenn IhnenIhre Beckhoff License ID nicht bekannt ist, wenden Sie sich an Ihren Ansprechpartner aus demBeckhoff Vertrieb).

16. Nachdem Sie das License Request File gespeichert haben, fragt das System, ob die Datei per Mail anden Beckhoff Lizenz Server geschickt werden soll:

17. Wenn Sie den Dialog mit Yes bestätigen, öffnet sich Ihr Standard E-Mail Client und erzeugt eine neueE-Mail für [email protected], die das License Request File enthält

18. Senden Sie diesen Activation Request an BeckhoffHINWEIS! das License Response File wird an die dieselbe E-Mail Adresse versendet, die das

License Request File verschickt hat19. Kurz darauf erhalten Sie vom Beckhoff-Lizenzserver eine Lizenzdatei,

importieren Sie diese über den Button Activate License Response File..., um das Produkt zuaktivieren

mailto:[email protected]

Installation


20. Wählen Sie in Ihrem Ordnersystem das erhaltene License Response File aus

21. Das License Response File wird importiert und alle enthaltenen Lizenzen werden aktiviert, sämtlichebetroffenen Demo-Lizenzen werden entfernt

22. Starten Sie TwinCAT neu, um die Lizenz zu aktivieren

HINWEIS! Das Lizenzfile wird automatisch auf Ihre lokale Festplatte unter ...\TwinCAT\3.1\Target\License kopiert.

Technische Einführung


4 Technische Einführung

4.1 MQTT

4.1.1 BrokerUm Prozessdaten und Meldungen mit einem Smart Device auszutauschen bzw. zu synchronisieren, wird einMQTT-Broker benötigt.

Hinweis

Der MQTT-Broker muss von der TwinCAT SPS und dem mobilem Endgerät via IP-Adresseoder Hostname erreichbar sein. TwinCAT und Smartphone müssen nicht direkt verbundenwerden.

MQTT ist ein Publisher/Subscriber-basiertes Kommunikationsprotokoll, welches eine Nachrichten-basierteÜbertragung zwischen Applikationen ermöglicht. Eine zentrale Komponente bei dieser Art der Übertragungist der sogenannte Message Broker. Dieser hat die Aufgabe, Nachrichten zwischen den einzelnenApplikationen bzw. dem Sender und Empfänger einer Nachricht zu verteilen. Der Message Brokerentkoppelt dabei Sender und Empfänger voneinander, sodass diese keine gegenseitigenAddressinformationen kennen und austauschen müssen. Alle Kommunikationsteilnehmer wenden sich beimSenden und Empfangen an den Message Broker und dieser übernimmt die Verteilung der Nachrichten.

MQTT-Broker Voraussetzungen für TC3 IoT Communicator

Für die optimale Nutzung der TwinCAT IoT Communicator App sollte der MQTT-Broker folgendeVoraussetzungen erfüllen:

• MQTT-Protokollversion 3.1.1 (siehe Spezifikation OASIS-Standard)

• Clients benötigen den Zugang auf die Topics (siehe Topicstruktur [} 13])

• Retain-Nachrichten und Quality of Service 0 & 1 (siehe Quality of Service [} 13])

4.1.2 TopicstrukturDie SPS-Bibliothek TC3_IotCommunicator sendet und empfängt Daten mittels einer von Beckhoff definiertenStruktur von MQTT-Topics.

Zum Verbinden einer TwinCAT SPS mit dem MQTT-Broker muss lediglich ein sogenanntes „Main-Topic“angegeben werden. Siehe dazu die API-Referenz zum Baustein FB_IotCommunicator [} 17].

4.1.3 Quality of ServiceQuality of Service (QoS) ist eine Vereinbarung zwischen dem Sender und Empfänger einer Nachricht inBezug auf das Garantieren der Nachrichtenübermittlung. Es existieren drei verschiedene Level in MQTT:

• 0 – höchstens einmal• 1 – mindestens einmal• 2 – genau einmal

Beide Kommunikationsarten (Publish/Subscribe) zum Message Broker müssen berücksichtigt und getrenntvoneinander betrachtet werden. Das QoS-Level, welches ein Client beim Publishen einer Nachrichtverwendet, wird vom jeweiligen Client gesetzt. Wenn der Broker nun die Nachricht an einen Clientweiterleitet, der sich entsprechend auf das Topic subscribed hat, wird das QoS-Level vom Subscriberverwendet, welches beim Herstellen der Subscription angegeben wurde. Dies bedeutet, dass ein QoS-Level,welches vom Publisher vielleicht mit 2 angegeben wurde, vom Subscriber mit 0 „überschrieben“ werdenkann.



QoS-Level 0

Bei diesem QoS-Level erfolgt keine Bestätigung des Empfängers, ob die Nachrichten empfangen wurdenoder nicht. In der Folge wird die Nachricht auch kein zweites Mal gesendet.

QoS-Level 1

Bei diesem QoS-Level wird garantiert, dass die Nachricht zumindest einmal beim Empfänger ankommt. Aberdie Nachricht kann unter Umständen auch mehrfach beim Empfänger eintreffen. Der Sender speichert dieNachricht intern bis er eine Bestätigung in Form einer PUBACK-Nachricht vom Empfänger erhält. Wenn diePUBACK-Nachricht für eine bestimmte Zeit ausbleibt, wird die Nachricht erneut gesendet.

QoS-Level 2

Bei diesem QoS-Level wird garantiert, dass die Nachricht maximal einmal beim Empfänger ankommt. Dieswird MQTT-seitig durch einen Handshake-Mechanismus realisiert. QoS-Level 2 ist der sicherste (aus Sichtder Nachrichtenübermittlung), aber auch langsamste QoS-Level. Wenn ein Empfänger eine Nachricht mitQoS-Level 2 erhält, bestätigt er die Nachricht mit einem PUBREC. Der Absender der Nachricht merkt sichdiese intern bis er ein PUBCOMP empfangen hat. Dieser zusätzliche Handshake (verglichen mit QoS 1) istwichtig, damit die Nachricht nicht doppelt übertragen wird. Wenn der Absender der Nachricht ein PUBRECerhält, kann er den initiale Publish verwerfen, da er weiß, dass die Nachricht einmal vom Empfängerempfangen wurde. Er merkt sich somit intern den PUBREC und sendet seinerseits ein PUBREL. Nachdemder Empfänger ein PUBREL empfangen hat, kann er die sich zuvor gemerkten Zustände verwerfen und miteinem PUBCOMP antworten. Umgekehrt genauso. Immer dann, wenn ein Paket verloren geht, ist derjeweilige Kommunikationsteilnehmer dafür verantwortlich, die zuletzt gesendete Nachricht nach einerbestimmten Zeit noch einmal zu senden.



4.2 SicherheitDie MQTT-Spezifikation bietet einem MQTT-Client die Möglichkeit zur Benutzung von Username/Password-Authentifizierung am Message Broker. Zusätzlich können gängige Kryptografie-Mechanismen, wie z. B. TLS(Transport Layer Security), verwendet werden, um die Datenkommunikation zwischen Client und MessageBroker zusätzlich abzusichern.

4.2.1 AuthentifizierungDie SPS-Bibliothek TC3_IoTCommunicator, sowie die TwinCAT IoT Communicator App können einenAuthentifizierungsmechanismus nutzen, welcher im MQTT-Protokoll standardisiert und implementiert ist(siehe Spezifikation OASIS-Standard). Die SPS-Bibliothek und die App nutzen die MQTT-Protokollversion3.1.1.

Achtung

Authentifizierung garantiert keinen Schutz vor Cyber-AttackenImplementieren Sie zusätzlich zur Authentifizierung eine TLS-Verschlüsselung. Anderen-falls werden Benutzername und Passwort im Klartext übertragen. (Siehe Verschlüsselung[} 15])

4.2.2 VerschlüsselungEine Verschlüsselung und Authentifizierung via TLS kann mithilfe einer Zertifizierungsstelle (engl. CertificateAuthority (CA)) erfolgen. Hierbei stellt die CA eine Signatur über den Public Key sowohl für den MessageBroker (der sogenannte „Server-Key“) als auch üblicherweise für alle sich verbindenden Clients aus. AlleKommunikationsteilnehmer können sich dann gegenseitig vertrauen, indem sie der ausstellendenZertifizierungsstelle vertrauen. Je nach Message Broker kann sich ein MQTT Client jedoch auch ohneeigenes Client-Zertifikat verbinden. Hierbei verwendet der Client dann nur den Public Key der ausstellendenZertifizierungsstelle während der Verbindungherstellung mit dem Broker.

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718116

Konfiguration


5 Konfiguration

5.1 Attribute

Anzeigename der Variablen (iot.DisplayName)

Syntax: {attribute 'iot.DisplayName' := 'Ceiling Lights'}

Definiert den Namen, der in der App für diese Variable angezeigt werden soll. Wenn dieses Attribut nichtangegeben wird, wird in der App der SPS-Variablenname angezeigt.

Einheit der Variablen (iot.Unit)

Syntax: {attribute 'iot.Unit' := '°C'}

Definiert die Einheit, die in der App hinter dem Wert der Variablen steht. Wenn dieses Attribut nichtangegeben wird, bleibt die Einheit hinter dem Wert leer.

Variable nicht veränderbar (iot.Readonly)

Syntax: {attribute 'iot.ReadOnly' := 'TRUE'}

Definiert, ob die Variable von der App aus verändert werden darf. Wird dieses Attribut mit dem Wert TRUEangegeben, ist die Variable nicht mehr veränderbar und es erscheint ein Schloss-Symbol neben demVariablennamen. Wenn dieses Attribut nicht angegeben wird, ist die Variable standardmäßig veränderbar.

Minimal- und Maximalwert der Variable (iot.MinValue und iot.MaxValue)

Syntax: {attribute 'iot.MinValue' := '10'} {attribute 'iot.MaxValue' := '30'}

Definiert einen Minimal- und Maximalwert für numerische Variablen. Wenn beide Attribute ('MinValue' UND'MaxValue') angegeben werden, wird in der App anhand einer Fortschrittsanzeige angezeigt, inwieweit deraktuelle Wert in Bezug auf den Minimal- und Maximalwert fortgeschritten ist. HINWEIS! Minimal- undMaximalwert definieren den Bereich, den die Fortschrittsanzeige in der App berücksichtigt. Der Wertkann in der SPS die angegebenen Werte über- oder unterschreiten.

Beispiel

Siehe auch: Beispiele > Applikationsbeispiel [} 23]

SPS API


6 SPS API

6.1 Funktionsbausteine

6.1.1 FB_IotCommunicatorDer Funktionsbaustein ermöglicht die Kommunikation zu einem MQTT-Broker.

Ein FB_IotCommunicator-Funktionsbaustein ist für die Verbindung zu genau einem Broker und für dasSenden und Empfangen von Daten genau eines Gerätes („Device“) zuständig. Um dieHintergrundkommunikation zu diesem Broker zu gewährleisten und somit das Senden und Empfangen vonDaten und Nachrichten zu ermöglichen, muss die Execute-Methode des Funktionsbausteins zyklischaufgerufen werden.

Alle Verbindungsparameter sind als Eingangsparameter vorhanden und werden beim Verbindungsaufbauausgewertet.

Syntax

Definition:FUNCTION_BLOCK FB_IotCommunicatorVAR_INPUT sHostName : STRING := '127.0.0.1'; // IP address/hostname of MQTT broker, default 'localhost' nPort : UINT := 1883; // (*optional*) Port to use for connection to broker - default: 1883 sClientId : STRING; // (*optional*) Unique name to connect to MQTT broker sMainTopic : STRING; // MQTT topic the TC3 IoT Communicator will communicate with sDeviceName : STRING; // e.g. ’Machine XYZ’ or 'Room 015 - Kitchen' sUser : STRING; // (*optional*) Username for authentication sPassword : STRING; // (*optional*) Password for specified User stTls : ST_IotCommunicatorTls; // (*optional*) Specify details for secure tls connection bRetain : BOOL := TRUE; // (*optional*) default true - if false, data, messages & deviceswill not be stored eQoS : TcIotMqttQos := TcIotMqttQos.AtLeastOnceDelivery; // (*optional*) quality of ser-vice between client & broker - default: 1END_VARVAR_OUTPUT bError : BOOL; hrErrorCode : HRESULT; eConnectionState : ETcIotMqttClientState; bConnected : BOOL; fbCommand : FB_IoTCommand; //provides functionality to receive commandsEND_VAR

SPS API


Eingänge

Name Typ BeschreibungsHostName STRING sHostName kann als Name oder als IP-Adresse angegeben werden.

Bei fehlender Angabe wird Local Host verwendetnPort UINT Hier wird der Host Port angegeben. (Default: 1883)sClientId STRING Die Client ID kann individuell angegeben werden. Bei fehlender

Angabe wird eine ID generiert.sMainTopic STRING Hier wird angegeben, in welches Maintopic die Daten und

Nachrichten gesendet werden.sDeviceName STRING Hier wird der Name des Gerätes eingetragen, zu dem die Daten und

Nachrichten gehören.sUser STRING Optional kann ein Benutzername angegeben werden.sPassword STRING Zum Benutzernamen kann hier ein Passwort angegeben werden.stTLS STRING Wenn der Broker eine TLS gesicherte Verbindung anbietet, kann hier

die nötige Konfiguration vorgenommen werden. DieParameterstruktur ist vom Typ ST_IotCommunicatorTls [} 22].

bRetain BOOL Die aktuellsten Daten und die letzten 255 Nachrichten, sowie deraktuelle Status des Gerätes werden standardmäßig vom Brokergespeichert. Ist dies nicht erwünscht, kann bRetain auf FALSEgesetzt werden.

eQoS TcIotMqttQos "Quality of Service"

Ausgänge

Name Typ BeschreibungbError BOOL TRUE, sobald eine Fehlersituation eintritt.hrErrorCode HRESULT Liefert bei einem gesetzten bError-Ausgang einen

Fehlercode.eConnectionState ETcIotMqttClientState Gibt den Zustand der Verbindung vom Client zum Broker

als Enumeration ETcIotMqttClientState an.bConnected BOOL TRUE, wenn eine Verbindung vom Client zum Broker

besteht.fbCommand FB_IoTCommand Stellt alle nötigen Funktionalitäten bereit, um empfangene

Daten („Commands“) auswerten zu können. DieserAusgang ist vom Typ FB_IotCommand [} 20].

Methoden

Name BeschreibungExecute [} 19] Methode zur Hintergrundkommunikation mit dem TwinCAT-Treiber. Die

Methode muss zyklisch aufgerufen werden.SendData [} 19] Methode zum Senden von Daten an den angegebenen MQTT Message

Broker.SendMessage [} 20] Methode zum Senden einer (Push-)Nachricht an den angegebenen

MQTT Message Broker.

SPS API


Hinweis

Strings im UTF-8-FormatDie hier verwendeten Variablen vom Typ STRING nutzen das UTF-8-Format. DieseSTRING-Formatierung ist üblich bei der MQTT-Kommunikation.Um auch Sonderzeichen und Texte verschiedenster Sprachen empfangen zu können, wirdder Zeichensatz in der Tc3_IotCommunicator-Bibliothek nicht auf den typischen Zeichen-satz vom Datentyp STRING beschränkt. Stattdessen wird der Unicode-Zeichensatz alsUTF-8-Format in Verbindung mit dem Datentyp STRING verwendet.Bei Verwendung des ASCII-Zeichensatzes besteht kein Unterschied zwischen der typi-schen Formatierung in einem STRING und der UTF-8-Formatierung eines STRING.

Voraussetzungen

Entwicklungsumgebung Zielplattform Einzubindende SPS-BibliothekenTwinCAT v3.1.4022.0 IPC oder CX (x86, x64, ARM) Tc3_IotCommunicator

6.1.1.1 Execute

Diese Methode muss zyklisch aufgerufen werden, um die Hintergrundkommunikation mit dem MQTT Brokerzu gewährleisten.

SyntaxMETHOD ExecuteVAR_INPUT bConnect : BOOL;END_VAR

Eingänge

Name Typ BeschreibungbConnect BOOL Wenn bConnect auf TRUE gesetzt wird, findet der Verbindungsaufbau zum Broker

statt. Um die Verbindung zu halten, muss bConnect gesetzt bleiben. Bei Aufruf derExecute()-Methode mit bConnect gleich FALSE, wird die Verbindung zum Brokerabgebaut.

Mögliche Fehler werden an den Ausgängen bError, hrErrorCode und eConnectionState der Bausteininstanzausgegeben

6.1.1.2 SendData

Diese Methode wird einmalig aufgerufen, um Daten an den Broker zu senden.

SyntaxMETHOD SendData : BOOLVAR_INPUT pMachineStruct : PVOID; nStructSize : UINT;END_VAR

Eingänge

Name Typ BeschreibungpMachineStruct PVOID Adresse zur Struktur, in der die Variablen des Gerätes deklariert werden.nStructSize UINT Größe der bei pMachineStruct angegebenen Struktur.

SPS API


Rückgabewert

Name Typ BeschreibungSendData BOOL Bei erfolgreichem Aufruf liefert die Methode den Rückgabewert TRUE.

Mögliche Fehler werden an den Ausgängen bError und hrErrorCode der Bausteininstanz ausgegeben.

6.1.1.3 SendMessage

Diese Methode wird einmalig aufgerufen, um eine (Push-)Nachricht an den Broker zu senden.

SyntaxMETHOD SendMessage : BOOLVAR_INPUT sMessage : STRING(255);END_VAR

Eingänge

Name Typ BeschreibungsMessage STRING Text der (Push-)Nachricht, die an den Broker geschickt werden soll.

Rückgabewert

Name Typ BeschreibungSendMessage BOOL Bei erfolgreichem Aufruf liefert die Methode den Rückgabewert

TRUE.

Mögliche Fehler werden an den Ausgängen bError und hrErrorCode der Bausteininstanz ausgegeben.

Hinweis

Strings im UTF-8-FormatDie hier verwendeten Variablen vom Typ STRING nutzen das UTF-8-Format. DieseSTRING-Formatierung ist üblich bei der MQTT-Kommunikation.Um auch Sonderzeichen und Texte verschiedenster Sprachen empfangen zu können, wirdder Zeichensatz in der Tc3_IotCommunicator-Bibliothek nicht auf den typischen Zeichen-satz vom Datentyp STRING beschränkt. Stattdessen wird der Unicode-Zeichensatz alsUTF-8-Format in Verbindung mit dem Datentyp STRING verwendet.Bei Verwendung des ASCII-Zeichensatzes besteht kein Unterschied zwischen der typi-schen Formatierung in einem STRING und der UTF-8-Formatierung eines STRING.

6.1.2 FB_IotCommandDer Funktionsbaustein stellt Funktionen zur Verfügung, um empfangene Befehle („Commands“)auszuwerten. Er darf nicht instanziiert werden, da er am Ausgang der FB_IotCommunicator [} 17]-Instanzbereits deklariert ist und darüber auf die Ausgänge und die empfangenen Befehle zugegriffen wird.

Syntax

Definition:FUNCTION BLOCK FB_IotCommandVAR_INPUTEND_VARVAR_OUTPUT bError : BOOL; hrErrorCode : HRESULT;

SPS API


bAvailable : BOOL // if true, a new command is available sVarName : STRING // Name of variable in currently available commandEND_VAR

Ausgänge

Name Typ BeschreibungbError BOOL TRUE, sobald eine Fehlersituation eintritt.hrErrorCode HRESULT Liefert bei einem gesetzten bError-Ausgang einen Fehlercode.bAvailable BOOL TRUE, wenn ein neuer Befehl („Command“) verfügbar ist.sVarName STRING Wenn bAvailable TRUE ist, enthält sVarName den Namen der

Variablen, die empfangen wurde.

Methoden

Name BeschreibungGetValue [} 21] Methode, um an den Wert des Befehls zu kommen, wenn bAvailable

TRUE istRemove [} 22] Methode, um den aktuell verfügbaren Befehl zu verwerfen

Voraussetzungen

Entwicklungsumgebung Zielplattform Einzubindende SPS-BibliothekenTwinCAT v3.1.4022.0 IPC oder CX (x86, x64, ARM) Tc3_IotCommunicator

6.1.2.1 GetValue

Diese Methode wird aufgerufen, um an den Wert der Variable im aktuellen Befehl („Command“) zu kommen.

SyntaxMETHOD GetValue : BOOLVAR_INPUT pValue : PVOID; nSize : UDINT; eDatatype : E_IotCommunicatorDatatype;END_VAR

Eingänge

Name Typ BeschreibungpValue PVOID Adresse zur Variable, in die der empfangene Wert

geschrieben werden soll.nSize UDINT Größe der in pValue angegebenen VariableneDatatype E_IotCommunicatorDatatype Datentyp der in pValue angegebenen Variablen, anhand

des Enums E_IotCommunicatorDatatype

Rückgabewert

Name Typ BeschreibungGetValue BOOL Bei erfolgreichem Aufruf liefert die Methode den

Rückgabewert TRUE.

SPS API


6.1.2.2 Remove

Diese Methode wird aufgerufen, um den aktuell verfügbaren Befehl aus dem Speicher zu entfernen.

6.2 Datentypen

6.2.1 ST_IotCommunicatorTlsTLS-Sicherheitseinstellungen für den MQTT-Client.

Syntax

Definition:TYPE ST_IotCommunicatorTls :STRUCT eVersion : E_IotCommunicatorTlsVersion := E_IotCommunicatorTlsVersion.tlsv1_2; // TLS-Versi-on, which is used sCA : STRING(255); // certificate authority as filename (PEM or DER for-mat) or as string (PEM) sCert : STRING(255); // (*optional*) client certificate as filename (PEM or DER for-mat) or as string (PEM)END_STRUCTEND_TYPE

Parameter

Name Typ BeschreibungeVersion E_IotCommunicatorTlsVersion Zu verwendende TLS-Version, anhand des Enums

E_IotCommunicatorTlsVersion.sCA STRING(255) Zertifikat der Certificate Authority (CA)sCert STRING(255) Client-Zertifikat, das zur Authentifizierung am Broker

verwendet wird (optional)

Beispiele


7 Beispiele

7.1 Applikationsbeispiel

Erstellung des SPS-Programms

Struktur definieren

Erzeugen Sie eine Struktur, innerhalb der Sie die zu sendenden Prozessdaten definieren. Weisen Sie dabeiden deklarierten Variablen Attribute zu, um deren Darstellung in der App zu definieren (siehe Attribute[} 16]).TYPE ST_ProcessData :STRUCT {attribute 'iot.DisplayName' := 'Kitchen Lights'} bLamp1 : BOOL;

{attribute 'iot.DisplayName' := 'Living Room Lights'} bLamp2 : BOOL;

{attribute 'iot.DisplayName' := 'Outside Temperature'} {attribute 'iot.ReadOnly' := 'true'} {attribute 'iot.Unit' := 'Celsius'} {attribute 'iot.MinValue' := '5'} {attribute 'iot.MaxValue' := '30'} nTemp : REAL;END_STRUCTEND_TYPE

Konfiguration

Deklarieren Sie im Hauptprogramm eine Instanz des Funktionsbausteins FB_IotCommunicator. DefinierenSie die Ausgänge entsprechend Ihren Verbindungsdaten (siehe FB_IotCommunicator [} 17]). Deklarieren Sieaußerdem die Struktur mit den zu sendenden Prozessdaten sowie eine Instanz des Timer-Funktionsbausteins TON.fbIoT : FB_IotCommunicator := ( sHostName := 'YOUR_MQTT_BROKER', // MQTT Broker Adress nPort := 1883, // MQTT Port sMainTopic := 'plants', // Main Topic sDeviceName := 'Building 12.3', // Device Name sUser := 'engineer1', // MQTT Username sPassword := 'abcdefg'); // MQTT Password

stData: ST_ProcessData; // Values to sendtimer : TON; // Timer to send data

Verbindung aufbauen

Rufen Sie im Implementierungsteil des Hauptprogramms über die Instanz des FunktionsbausteinsFB_IotCommunicator die Execute-Methode zyklisch auf, um die Verbindung zum Broker aufrechtzuerhaltenund somit das Senden und Empfangen von Daten und Nachrichten zu ermöglichen (siehe Execute [} 19]).fbIoT.Execute(TRUE);

Daten senden

Senden Sie die Prozessdaten mit einer Sample-Rate von 500 ms an den Broker. Rufen Sie dazu die Instanzdes Timer-Funktionsbausteins mit den entsprechenden Eingabevariablen sowie die SendData-Methode desFunktionsbausteins FB_IotCommunicatior auf (siehe SendData [} 19]).timer(IN := NOT timer.Q, PT := T#500MS);

IF fbIoT.bConnected AND timer.Q THEN fbIoT.SendData(ADR(stData), SIZEOF(stData));END_IF

Befehle empfangen und auswerten

Beispiele


Rufen Sie den Funktionsbaustein FB_IotCommand und deren Methoden auf, um Befehle zu empfangen undauszuwerten (siehe FB_IotCommand [} 20]).IF fbIoT.fbCommand.bAvailable THEN IF fbIoT.fbCommand.sVarName = 'bLamp1' THEN fbIoT.fbCommand.GetValue(ADR(stData.bLamp1), SIZEOF(stData.bLamp1), E_IotCommunicatorDataty-pe.type_BOOL); END_IF fbIoT.fbCommand.Remove();END_IF

(Push-) Nachrichten senden

Rufen Sie die SendMessage-Methode des Funktionsbausteins FB_IotCommunicator auf, um eine(Push-)Nachricht an den Broker zu senden (siehe SendMessage [} 20]).fbIoT.SendMessage('This is a test alarm message!');

Konfiguration der TwinCAT IoT Communicator App1. Geben Sie die Verbindungsdetails ein.2. Aktivieren Sie die Schaltfläche Authentication, um Benutzername und Passwort einzugeben.3. Tippen Sie auf List, um eine Verbindung mit dem MQTT-Broker aufzubauen.ð Der von Ihnen im SPS-Programm definierte „Device Name“ erscheint in der Liste.

Support und Service


8 Support und ServiceBeckhoff und seine weltweiten Partnerfirmen bieten einen umfassenden Support und Service, der eineschnelle und kompetente Unterstützung bei allen Fragen zu Beckhoff Produkten und Systemlösungen zurVerfügung stellt.

Beckhoff Support

Der Support bietet Ihnen einen umfangreichen technischen Support, der Sie nicht nur bei dem Einsatzeinzelner Beckhoff Produkte, sondern auch bei weiteren umfassenden Dienstleistungen unterstützt:

• Support• Planung, Programmierung und Inbetriebnahme komplexer Automatisierungssysteme• umfangreiches Schulungsprogramm für Beckhoff Systemkomponenten

Hotline: +49(0)5246/963-157Fax: +49(0)5246/963-9157E-Mail: [email protected]

Beckhoff Service

Das Beckhoff Service-Center unterstützt Sie rund um den After-Sales-Service:

• Vor-Ort-Service• Reparaturservice• Ersatzteilservice• Hotline-Service

Hotline: +49(0)5246/963-460Fax: +49(0)5246/963-479E-Mail: [email protected]

Weitere Support- und Serviceadressen finden Sie auf unseren Internetseiten unter http://www.beckhoff.de.

Beckhoff Firmenzentrale

Beckhoff Automation GmbH & Co. KG

Hülshorstweg 2033415 VerlDeutschland

Telefon: +49(0)5246/963-0Fax: +49(0)5246/963-198E-Mail: [email protected]

Die Adressen der weltweiten Beckhoff Niederlassungen und Vertretungen entnehmen Sie bitte unserenInternetseiten:http://www.beckhoff.de

Dort finden Sie auch weitere Dokumentationen zu Beckhoff Komponenten.

http://www.beckhoff.de

http://www.beckhoff.de

http://www.beckhoff.com/german/download/default.htm

Handbuch TC3 IoT Communicator - Beckhoff Automation · Erforderliche TwinCAT-LizenzTF6730 TC3 IoT...

Documents

Transcript of Handbuch TC3 IoT Communicator - Beckhoff Automation · Erforderliche TwinCAT-LizenzTF6730 TC3 IoT...