Creating an application with the HS URL endpoints JS API
Contents

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

  1. Open the HS/FS Expert and create a new empty project.
  2. Enter my_first_endpoint_project in the Project name field and confirm by clicking OK.
  3. 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 to Pw.12345. A different password must be taken into account for the JavaScript code further below.
  4. Switch to the User rights tab and allow the admin user to access Listen, Endpunkte and Administration there using a password.
  5. Configure the network settings (e.g. IP address, netmask, IP port, etc...) in the Project/Network mask as required.
  6. Open the Communication objects/Internal mask.
  7. Create a new folder under Internal objects and call it Endpoints.
  8. Create a new object in the (new) Endpoints folder.
  9. Enter iKO1 as the designation for the new object.
  10. Select 32Bit (2147483648..2147483647/EIS 11) as the data type for the object.
  11. Switch to the Endpoint tab and enter meinKO as the ID.
  12. Save the project.
  13. Open the Explorer and switch to any (work) directory.
  14. Create a new file and call it start.html.
  15. Open the start.html file using a (text) editor.
  16. Now write the required HTML & JavaScript code in the file:
    1. Define the HTML structure:
      <!DOCTYPE html>
      <html>
         <head>
            <title>Meine erste Endpoints Anwendung</title>
         </head>
         <body>
         </body>
      </html>
    2. 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>
    3. 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>
    4. 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>
    5. 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>
      ...
    6. 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>
      ...
    7. 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>
      ...
    8. 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>
  17. 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>
  18. 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)
  19. You must copy two files to this:
    1. The start.html file which you have just created.
    2. 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
  20. Switch back to the Expert and transfer the project.
  21. Open the browser and open the URL https://[HS-IP]/opt/start.html or http://[HS-IP]/opt/start.html, depending on your configuration.
  22. 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 the hs.min.js file is missing in the hsupload directory.