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
- Öffnen Sie den HS/FS-Experte und erstellen Sie ein neues leeres Projekt.
- In das Feld Projektname mein_erstes_endpoint_projekt eintragen und mit OK bestätigen.
- In der Maske Benutzer einen neuen Benutzer namens
admin
einrichten. Dass Passwort des Benutzers kann beliebig gewählt werden. In diesem HowTo ist es aufPw.12345
gesetzt. Ein abweichendes Passwort muss beim JavaScript Code weiter unten berücksichtigt werden. - In den Reiter Benutzerrechte wechseln und dort dem Benutzer
admin
den Zugriff per Passwort aufListen
,Endpunkte
undAdministration
gestatten. - Die Netzwerkeinstellungen (z.B. IP-Adresse, Netzmaske, ggf. IP-Port, usw...) in der Maske Projekt/Netzwerk nach Bedarf konfigurieren.
- Die Maske Kommunikationsobjekte/Intern öffnen.
- Einen neuen Ordner unter Interne Objekte mit dem Namen
Endpoints
anlegen. - Im (neuen) Ordner Endpoints ein neues Objekt anlegen.
- Als Bezeichnung für das neue Objekt
iKO1
eingeben. - Als Datentyp für das Objekt 32Bit (2147483648..2147483647/EIS 11) auswählen.
- In den Reiter Endpunkt wechseln und als ID
meinKO
eingeben. - Das Projekt speichern.
- Den Explorer öffnen und in ein beliebiges (Arbeits-) Verzeichnis wechseln.
- Eine neue Datei mit dem Namen
start.html
erzeugen. - Die Datei start.html mit einem (Text-) Editor öffnen.
- Nun den benötigten HTML & JavaScript Code in die Datei schreiben:
- Das HTML Gerüst definieren:
<!DOCTYPE html>
<html>
<head>
<title>Meine erste Endpoints Anwendung</title>
</head>
<body>
</body>
</html>
- 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>
- 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>
- 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>
- 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>
...
- 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>
...
- 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>
...
- 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>
- Das HTML Gerüst definieren:
- 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>
- 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
) - Es müssen zwei Dateien hierher kopiert werden:
- Die soeben neu erstellte Datei
start.html
. - 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
- In der in Kapitel 2 erwähnten URL-Endpoints Dokumentation
- Die soeben neu erstellte Datei
- Zurück in den Experten wechseln und das Projekt übertragen.
- Den Browser öffnen und die URL
https://[HS-IP]/opt/start.html
bzw.http://[HS-IP]/opt/start.html
, je nach Projektierung, öffnen. - 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 Dateihs.min.js
im hsupload-Verzeichnis fehlt.