Anwendung erstellen mit der HS URL-Endpoints JS API
Inhalt

1.Einleitung

In diesem HowTo wird anhand einer einfachen HTML-Anwendung gezeigt, wie die URL-Endpoints JavaScript API genutzt werden kann. Per HTML/JavaScript wird der Wert eines Kommunikationsobjekts ausgelesen und gesetzt. Dazu wird ein passendes Projekt im HS/FS-Experte erstellt.

2.Voraussetzungen

Die Vorraussetzungen für die Durchführung dieses HowTo sind:
  • HS/FS mit Firmware 4.7 oder höher
  • HS/FS-Experte Version 4.7 oder höher
  • URL-Endpoints JavaScriptAPI (entpackt)
  • Texteditor (z.B. PSPad, Notepad++, ...)
  • aktueller Browser (z.B. Chrome, Firefox, ...)

3.Anleitung

  1. Öffnen Sie den HS/FS-Experte und erstellen Sie ein neues leeres Projekt.
  2. In das Feld Projektname mein_erstes_endpoint_projekt eintragen und mit OK bestätigen.
  3. In der Maske Benutzer einen neuen Benutzer namens admin einrichten. Dass Passwort des Benutzers kann beliebig gewählt werden. In diesem HowTo ist es auf Pw.12345 gesetzt. Ein abweichendes Passwort muss beim JavaScript Code weiter unten berücksichtigt werden.
  4. In den Reiter Benutzerrechte wechseln und dort dem Benutzer admin den Zugriff per Passwort auf Listen, Endpunkte und Administration gestatten.
  5. Die Netzwerkeinstellungen (z.B. IP-Adresse, Netzmaske, ggf. IP-Port, usw...) in der Maske Projekt/Netzwerk nach Bedarf konfigurieren.
  6. Die Maske Kommunikationsobjekte/Intern öffnen.
  7. Einen neuen Ordner unter Interne Objekte mit dem Namen Endpoints anlegen.
  8. Im (neuen) Ordner Endpoints ein neues Objekt anlegen.
  9. Als Bezeichnung für das neue Objekt iKO1 eingeben.
  10. Als Datentyp für das Objekt 32Bit (2147483648..2147483647/EIS 11) auswählen.
  11. In den Reiter Endpunkt wechseln und als ID meinKO eingeben.
  12. Das Projekt speichern.
  13. Den Explorer öffnen und in ein beliebiges (Arbeits-) Verzeichnis wechseln.
  14. Eine neue Datei mit dem Namen start.html erzeugen.
  15. Die Datei start.html mit einem (Text-) Editor öffnen.
  16. Nun den benötigten HTML & JavaScript Code in die Datei schreiben:
    1. Das HTML Gerüst definieren:
      <!DOCTYPE html>
      <html>
         <head>
            <title>Meine erste Endpoints Anwendung</title>
         </head>
         <body>
         </body>
      </html>
    2. Die Buttons für die Befehle lesen und schreiben, sowie die Textfelder anlegen:
      <!DOCTYPE html>
      <html>
         <head>
            <title>Meine erste Endpoints Anwendung</title>
         </head>
         <body>
            <input type="text" id="input_read" readonly>
            <button id="btn_read">lesen</button>
            <br>
            <input type="text" id="input_write">
            <button id="btn_write">schreiben</button>
         </body>
      </html>
    3. Die URL-Endpoints JavaScript-API (hs.min.js) einbinden:
      <!DOCTYPE html>
      <html>
         <head>
            <title>Meine erste Endpoints Anwendung</title>
            <script src="hs.min.js"></script>
         </head>
         <body>
            <input type="text" id="input_read" readonly>
            <button id="btn_read">lesen</button>
            <br>
            <input type="text" id="input_write">
            <button id="btn_write">schreiben</button>
         </body>
      </html>
    4. Einen Bereich für JavaScript Code einfügen:
      <!DOCTYPE html>
      <html>
         <head>
            <title>Meine erste Endpoints Anwendung</title>
            <script src="hs.min.js"></script>
         </head>
         <body>
            <input type="text" id="input_read" readonly>
            <button id="btn_read">lesen</button>
            <br>
            <input type="text" id="input_write">
            <button id="btn_write">schreiben</button>
            <script>
            </script>
         </body>
      </html>
    5. Im JavaScript Code Referenzen auf die HTML Elemente anlegen. Außerdem werden die beiden Buttons btn_read und btn_write inaktiv gesetzt. Sie werden erst aktiv, nachdem eine Verbindung mit dem HS/FS aufgebaut wurde:
      ...
      <script>
         var input_read = document.getElementById("input_read");
         var input_write = document.getElementById("input_write");
         var btn_read = document.getElementById("btn_read");
         var btn_write = document.getElementById("btn_write");
         btn_read.disabled = true;
         btn_write.disabled = true;
      </script>
      ...
    6. Verbindung zum HS/FS über die URL-Endpoints API herstellen:
      ...
      <script>
         var input_read = document.getElementById("input_read");
         var input_write = document.getElementById("input_write");
         var btn_read = document.getElementById("btn_read");
         var btn_write = document.getElementById("btn_write");
         btn_read.disabled = true;
         btn_write.disabled = true;

         // Verbindungsobjekt mit Benutzer "admin"
         // und Passwort "Pw.12345" erzeugen
         var conn = HomeServerConnector.createConnection("admin","Pw.12345");

         // Diese Funktion wird aufgerufen,
         // sobald die Verbindung hergestellt wird.
         conn.onConnect = function () {
            btn_read.disabled = false;
            btn_write.disabled = false;
         };

         // Diese Funktion wird aufgerufen,
         // sobald die Verbindung getrennt wird.
         conn.onDisconnect = function (code, reason ,cleanly) {
            btn_read.disabled = true;
            btn_write.disabled = true;
         };

         // Verbindung aufbauen
         conn.connect(true);
      </script>
      ...
    7. Funktionen für das Lesen (readCO) und das Schreiben (writeCO) des Werts des Kommunikationsobjekts meinKO bereitstellen:
      ...
      <script>
         var input_read = document.getElementById("input_read");
         var input_write = document.getElementById("input_write");
         var btn_read = document.getElementById("btn_read");
         var btn_write = document.getElementById("btn_write");
         btn_read.disabled = true;
         btn_write.disabled = true;

         // Verbindungsobjekt mit Benutzer "admin"
         // und Passwort "Pw.12345" erzeugen
         var conn = HomeServerConnector.createConnection("admin","Pw.12345");

         // Diese Funktion wird aufgerufen,
         // sobald die Verbindung hergestellt wird.
         conn.onConnect = function () {
            btn_read.disabled = false;
            btn_write.disabled = false;
         };

         // Diese Funktion wird aufgerufen,
         // sobald die Verbindung getrennt wird.
         conn.onDisconnect = function (code, reason ,cleanly) {
            btn_read.disabled = true;
            btn_write.disabled = true;
         };

         // Liest den Wert des KO und schreibt ihn in das LesenTextfeld.
         function readCO () {
            // Objekt vom KO mit der ID "meinKO" holen
            var co = conn.getCommunicationObject ("CO@meinKO");

            // Wert des KO holen.
            // Der Wert wird der CallbackFunktion übergeben
            co getValue (function (err, value) {
               input_read.value = value;
            });
         }

         // Schreibt den Wert aus dem Schreiben-Textfeld in das KO.
         function writeCO () {
            // Objekt vom KO mit der ID "meinKO" holen
            var co = conn.getCommunicationObject("CO@meinKO");
            var valueToSet = parseFloat(input_write.value);

            // Wert des KO setzen
            co.setValue (valueToSet, function (err) {});
         }

         // Verbindung aufbauen
         conn.connect(true);
      </script>
      ...
    8. Die Funktionen readCO und writeCO sollen beim Klicken des jeweiligen Buttons ausgeführt werden (onclick):
      <!DOCTYPE html>
      <html>
         <head>
            <title>Meine erste Endpoints Anwendung</title>
            <script src="hs.min.js"></script>
         </head>
         <body>
            <input type="text" id="input_read" readonly>
            <button onclick="readCO()" id="btn_read">lesen</button>
            <br>
            <input type="text" id="input_write">
            <button onclick="writeCO()" id="btn_write">schreiben</button>
            <script>
               ...
            </script>
         </body>
      </html>
  17. Die Datei start.html speichern. Hier der gesame Inhalt der Datei:
    <!DOCTYPE html>
    <html>
       <head>
          <title>Meine erste Endpoints Anwendung</title>
          <script src="hs.min.js"></script>
       </head>
       <body>
          <input type="text" id="input_read" readonly>
          <button onclick="readCO()" id="btn_read">lesen</button>
          <br>
          <input type="text" id="input_write">
          <button onclick="writeCO()" id="btn_write">schreiben</button>
          <script>
             var input_read = document.getElementById("input_read");
             var input_write = document.getElementById("input_write");
             var btn_read = document.getElementById("btn_read");
             var btn_write = document.getElementById("btn_write");
             btn_read.disabled = true;
             btn_write.disabled = true;

             // Verbindungsobjekt mit Benutzer "admin"
             // und Passwort "Pw.12345" erzeugen
             var conn = HomeServerConnector.createConnection("admin","Pw.12345");

             // Diese Funktion wird aufgerufen,
             // sobald die Verbindung hergestellt wird.
             conn.onConnect = function () {
                btn_read.disabled = false;
                btn_write.disabled = false;
             };

             // Diese Funktion wird aufgerufen,
             // sobald die Verbindung getrennt wird.
             conn.onDisconnect = function (code, reason ,cleanly) {
                btn_read.disabled = true;
                btn_write.disabled = true;
             };

             // Liest den Wert des KO und schreibt ihn in das LesenTextfeld.
             function readCO () {
                // Objekt vom KO mit der ID "meinKO" holen
                var co = conn.getCommunicationObject ("CO@meinKO");

                // Wert des KO holen.
                // Der Wert wird der CallbackFunktion übergeben
                co getValue (function (err, value) {
                   input_read.value = value;
                });
             }

             // Schreibt den Wert aus dem Schreiben-Textfeld in das KO.
             function writeCO () {
                // Objekt vom KO mit der ID "meinKO" holen
                var co = conn.getCommunicationObject("CO@meinKO");
                var valueToSet = parseFloat(input_write.value);

                // Wert des KO setzen
                co.setValue (valueToSet, function (err) {});
             }

             // Verbindung aufbauen
             conn.connect(true);
          </script>
       </body>
    </html>
  18. In den Explorer wechseln und das Verzeichnis hsupload Ihres Projekts öffnen. (Das Verzeichnis wird in der Titelzeile des Experten angezeigt. Z.B.:
    [Projektordner]\mein_erstes_endpoint_projekt\mein_erstes_endpoint_projekt\hsupload)
  19. Es müssen zwei Dateien hierher kopiert werden:
    1. Die soeben neu erstellte Datei start.html.
    2. Die optimierte Version der URL-Endpoints JavaScript API (hs.min.js)
      Diese Datei kann an zwei Stellen gefunden werden:
      • In der in Kapitel 2 erwähnten URL-Endpoints Dokumentation
        im Unter-Verzeichnis \URL Endpoint\JS API\js\
      • Im hsupload-Verzeichnis des URL-Endpoints Musterprojekts
  20. Zurück in den Experten wechseln und das Projekt übertragen.
  21. Den Browser öffnen und die URL https://[HS-IP]/opt/start.html bzw. http://[HS-IP]/opt/start.html, je nach Projektierung, öffnen.
  22. Hier kann per Klick auf den Button lesen der Wert des Kommunikationsobjekts iKO1 ausgelesen werden. Per Klick auf den Button schreiben wird der Wert des Kommunikationsobjekts iKO1 geschrieben.
    Anmerkung: Die Buttons bleiben inaktiv, wenn z.B. die Angaben zu Benutzername und Passwort falsch sind, oder die Datei hs.min.js im hsupload-Verzeichnis fehlt.