1.Introduction
This how-to demonstrates how to use the URL endpoints JavaScript API based on a simple HTML application. The value of a communication object is read out and set using HTML/JavaScript. For this purpose, a suitable project is created in the HS/FS Expert.
2.Requirements
The requirements for this how-to are as follows:
- HS/FS with firmware 4.7 or higher
- HS/FS Expert version 4.7 or higher
- URL endpoints JavaScript API (extracted)
- If you do not have the complete URL endpoints documentation, you can download it here.
- Text editor (e.g. PSPad, Notepad++, ...)
- Latest browser (e.g. Chrome, Firefox, ...)
3.Instructions
- Open the HS/FS Expert and create a new empty project.
- Enter my_first_endpoint_project in the Project name field and confirm by clicking OK.
- In the User mask configure a new user called
admin
. You can choose any password for this user. The password in this how-to is set toPw.12345
. A different password must be taken into account for the JavaScript code further below. - Switch to the User rights tab and allow the
admin
user to accessListen
,Endpunkte
andAdministration
there using a password. - Configure the network settings (e.g. IP address, netmask, IP port, etc...) in the Project/Network mask as required.
- Open the Communication objects/Internal mask.
- Create a new folder under Internal objects and call it
Endpoints
. - Create a new object in the (new) Endpoints folder.
- Enter
iKO1
as the designation for the new object. - Select 32Bit (2147483648..2147483647/EIS 11) as the data type for the object.
- Switch to the Endpoint tab and enter
meinKO
as the ID. - Save the project.
- Open the Explorer and switch to any (work) directory.
- Create a new file and call it
start.html
. - Open the start.html file using a (text) editor.
- Now write the required HTML & JavaScript code in the file:
- Define the HTML structure:
<!DOCTYPE html>
<html>
<head>
<title>Meine erste Endpoints Anwendung</title>
</head>
<body>
</body>
</html>
- Create the buttons for the read and write commands as well as the text fields:
<!DOCTYPE html>
<html>
<head>
<title>My first endpoints application</title>
</head>
<body>
<input type="text" id="input_read" readonly>
<button id="btn_read">read</button>
<br>
<input type="text" id="input_write">
<button id="btn_write">write</button>
</body>
</html>
- Embed the URL endpoints JavaScript API (hs.min.js):
<!DOCTYPE html>
<html>
<head>
<title>My first endpoints aplication</title>
<script src="hs.min.js"></script>
</head>
<body>
<input type="text" id="input_read" readonly>
<button id="btn_read">read</button>
<br>
<input type="text" id="input_write">
<button id="btn_write">write</button>
</body>
</html>
- Insert an area for JavaScript code:
<!DOCTYPE html>
<html>
<head>
<title>My first endpoints application</title>
<script src="hs.min.js"></script>
</head>
<body>
<input type="text" id="input_read" readonly>
<button id="btn_read">read</button>
<br>
<input type="text" id="input_write">
<button id="btn_write">write</button>
<script>
</script>
</body>
</html>
- Create references to the HTML elements in the JavaScript code. The two buttons btn_read and btn_write are disabled. They are only enabled once a connection to the HS/FS has been established:
...
<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>
...
- Connect to the HS/FS via the URL endpoints API:
...
<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;
// Create connection object with user "admin"
// and password "Pw.12345"
var conn = HomeServerConnector.createConnection("admin","Pw.12345");
// This function is called
// as soon as the connection is established.
conn.onConnect = function () {
btn_read.disabled = false;
btn_write.disabled = false;
};
// This function is called
// as soon as the connection is terminated.
conn.onDisconnect = function (code, reason, cleanly) {
btn_read.disabled = true;
btn_write.disabled = true;
};
// Establish connection
conn.connect(true);
</script>
...
- Provide functions for reading (readCO) and writing (writeCO) the value of the myCO communication object:
...
<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;
// Create connection object with user "admin"
// and password "Pw.12345"
var conn = HomeServerConnector.createConnection("admin","Pw.12345");
// This function is called
// as soon as the connection is established.
conn.onConnect = function () {
btn_read.disabled = false;
btn_write.disabled = false;
};
// This function is called
// as soon as the connection is terminated.
conn.onDisconnect = function (code, reason ,cleanly) {
btn_read.disabled = true;
btn_write.disabled = true;
};
// Reads the value of the CO and writes it to the read text field.
function readCO () {
// Get object with the ID "myCO"
var co = conn.getCommunicationObject ("CO@myCO");
// Get value of the CO.
// The value is transferred to the CallbackFunktion
co getValue (function (err, value) {
input_read.value = value;
});
}
// Writes the value from the write text field to the CO.
function writeCO () {
// Get object from the CO with the ID "myCO"
var co = conn.getCommunicationObject("CO@myCO");
var valueToSet = parseFloat(input_write.value);
// Set value of the CO
co.setValue (valueToSet, function (err) {});
}
// Establish connection
conn.connect(true);
</script>
...
- The readCO and writeCO functions are to be executed the respective button is clicked (onclick):
<!DOCTYPE html>
<html>
<head>
<title>My first endpoints application</title>
<script src="hs.min.js"></script>
</head>
<body>
<input type="text" id="input_read" readonly>
<button onclick="readCO()" id="btn_read">read</button>
<br>
<input type="text" id="input_write">
<button onclick="writeCO()" id="btn_write">write</button>
<script>
...
</script>
</body>
</html>
- Define the HTML structure:
- Save the
start.html
file. Here are the entire contents of the file:<!DOCTYPE html>
<html>
<head>
<title>My first endpoints application</title>
<script src="hs.min.js"></script>
</head>
<body>
<input type="text" id="input_read" readonly>
<button onclick="readCO()" id="btn_read">read</button>
<br>
<input type="text" id="input_write">
<button onclick="writeCO()" id="btn_write">write</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;
// Create connection object with user "admin"
// and password "Pw.12345"
var conn = HomeServerConnector.createConnection("admin","Pw.12345");
// This function is called
// as soon as the connection is established.
conn.onConnect = function () {
btn_read.disabled = false;
btn_write.disabled = false;
};
// This function is called
// as soon as the connection is terminated.
conn.onDisconnect = function (code, reason ,cleanly) {
btn_read.disabled = true;
btn_write.disabled = true;
};
// Reads the value of the CO and writes it to the read text field.
function readCO () {
// Get object from the CO with the ID "myCO"
var co = conn.getCommunicationObject ("CO@meinKO");
// Get value of the CO.
// The value is transferred to the CallbackFunktion
co getValue (function (err, value) {
input_read.value = value;
});
}
// Writes the value from the write text field to the CO.
function writeCO () {
// Get object from the CO with the ID "myCO"
var co = conn.getCommunicationObject("CO@myCO");
var valueToSet = parseFloat(input_write.value);
// Set value of the CO
co.setValue (valueToSet, function (err) {});
}
// Establish connection
conn.connect(true);
</script>
</body>
</html>
- Switch to the Explorer and open the
hsupload
directory of your project. (The directory is displayed in the Expert title line. E.g.:
[Projektordner]\mein_erstes_endpoint_projekt\mein_erstes_endpoint_projekt\hsupload
) - You must copy two files to this:
- The
start.html
file which you have just created. - The optimised version of the URL endpoints JavaScript API (
hs.min.js
)
. You can find this file in two locations:- In the URL endpoints documentation mentioned in Chapter 2
in the\URL Endpoint\JS API\js\
subdirectory - In the
hsupload
directory of the URL endpoints sample project
- In the URL endpoints documentation mentioned in Chapter 2
- The
- Switch back to the Expert and transfer the project.
- Open the browser and open the URL
https://[HS-IP]/opt/start.html
orhttp://[HS-IP]/opt/start.html
, depending on your configuration. - By clicking the read button, you can read out the value of the iKO1 communication object here. By clicking the write button, the value of the iKO1 communication object is written.
Note: The buttons remain disabled if the user name and password are incorrect, for example, or thehs.min.js
file is missing in the hsupload directory.