Anwendung erstellen mit der HS URL-Endpoints JS API
Inhalt
1.
Einleitung
2.
Voraussetzungen
3.
Anleitung

## 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.