Versions Compared

Old Version 3

changes.mady.by.user Nina Cardillo

Saved on

compared with

New Version Current

changes.mady.by.user Nina Cardillo

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Custom web pages support requires SmartServer IoT 2.6 or higher.

You can create custom web pages for the SmartServer that enable users to interact with devices in a standalone or LON network. These custom web pages can query and update device datapoints served by the SmartServer. You can access the SmartServer directly by using the IAP/REST and IAP/MQ APIs. This section describes the process of creating a web page with the IAP/REST API. Similar requirements are needed for web pages created with the IAP/MQ API.

Custom web pages support requires SmartServer IoT 2.6 or higher.

This section consists of the following:  

...

The following images show examples of custom web pages that can be created for the SmartServer.  The SmartServer IoT browser web page example (first on the left) is available on the EnOcean github Github repository.

      

Overview

...

On-demand GET using Datapoint Tags

Datapoint tags are can be used to request datapoint values for multiple datapoints in a single request. Datapoint tags consist of a tag (also called tagName) and a tag.value. The tag is a unique identifier (no other web page or internal SmartServer function should use this tagName). The tag tag.value is used to differentiate datapoints on a single web page. The tag names typically include the web page developer's company initials and some other unique identifier, if multiple people or groups within the company create web pages, plus a unique name for the web page (such as, "xyz_dashboard =1"). Tag value (tag.value) is optional. That is, you should only set a tag.value if you need it.

...

If you are not using tag.value, then for floor1 the tag would be "xyzjd_floor1".

A typical web page shows multiple datapoints from multiple devices. Datapoints are usually defined as a datapoint path, such as Sensor1/LightSensor/0/nvoLuxLevel. You can determine the names of datapoints by going to the CMS Datapoint Browser widget, looking at a DLA file, or issuing a REST API command. To see datapoint properties for a device named "Sensor1", you could run the following REST API GET:  /iap/devs/*+name==Sensor1/if/*/*/*/*. 

GET request pagination should be used when using datapoint tags or wild cards in the GET request. Pagination is used to reduce the number of entries returned each request. For the request above, the first request would be For SmartServer release 3.6 and higher

Datapoint tags can be assigned in the Datapoint Properties Widget, or by your custom Web page. Since the Datapoint Properties Widget is for device types then all devices of that device type will have that specific tag for the specific datapoint. If you only want to add the tag to one device then you will need to add the tag with your custom Web page.

For SmartServer 3.5 and prior releases

Datapoint tags are assigned by your custom Web page. Typically this is done only the first time this Web page is used. All susequent access to this Web page only uses GET request with the tags. 

To assign a tag to a specific device and datapoint

POST  /iap/devs/*+name==Sensor1/if/

...

LightSensor/

...

0/

...

nvoLuxLevel/tags    Payload {"xyz_floor1"="1"} 

To get datapoints with a specific tag

Get /iap/devs/*

...

/if/*/*/*

...

Datapoint values can be scalar (that is, a single field or a single piece of data) or structured (that is, the datapoint contains multiple fields like SNVT_switch which has both a "state" and a "value"  field). 

...

+tag==xyz_floor1&tag.value==1/value?pg=1&sz=30&max_age=1

Typical Web page

A typical web page shows multiple datapoints from multiple devices. Datapoints are usually defined as a datapoint path, such as Sensor1/LightSensor/0/nvoLuxLevel. You can determine the names of datapoints by going to the CMS Datapoint Browser widget, looking at a DLA file, or issuing a REST API command. To see datapoint properties for a device named "Sensor1", you could run the following REST API GET:  /iap/devs/*+name==Sensor1/if/*/*/*/*. 

GET request pagination should be used when using datapoint tags or wild cards in the GET request. Pagination is used to reduce the number of entries returned each request. For the request above, the first request would be /iap/devs/*+name==Sensor1/if/*/*/*/*?pg=1&sz=30. If there are more than 30 datapoints in the sensor device, you would have to make more requests using the snapshot number provided in the first request response. If there were more than 30 datapoints and the snapshot number returned in the first response was 48378, then the next request would be  /iap/devs/*+name==Sensor1/if/*/*/*/*?pg=2&sz=30&xs=48378. You would continue sending the second request with a new "pg" number until the web page received all the datapoints.

Datapoint values can be scalar (that is, a single field or a single piece of data) or structured (that is, the datapoint contains multiple fields like SNVT_switch which has both a "state" and a "value"  field). 

The SmartServer is based on Linux OS, therefore, web page names are case sensitive. This means that "Test.html" and "test.html" are different web pages.

There are two types of poll rates that are important for web page development. One poll rate is how often you send out a GET request to get datapoint values from the SmartServer. When poll rate is mentioned in web page development, it is usually referring to the GET poll rate. This rate is related to getting the cached data from the SmartServer. The second poll rate is related to the SmartServer getting live data from the end device. There are two ways of getting live data. One way is to configure monitoring in the CMS Datapoint Properties widget. The other way is to do on-demand polling using maxage (Get the latest cached value, but if the datapoint hasn't been read within the specified maxage time, go on the wire and get the latest value). For some device protocols the SmartServer automatically has the latest values (like Internal LON devices). For others, like external LON devices, you may need to set up monitoring (polling or event driven) in order to see live datasee live data.

In most cases, you will want the Datapoint Properties polling to be set for slow polling. To get faster updates for your Web page you will use on-demand polling (maxage).

Three sample web pages are provided to help you get familiar with creating a custom web page for the SmartServer. The "Simple Read" and "Simple Write" examples are intended for you to understand how to read and write datapoint values. These examples are for basic understanding, but are missing background polling of datapoints that is normally used for most SmartServer custom web pages.

...

  • The following sub-directories are provided for common files (files used by multiple web pages):

    • /var/apollo/www/user – custom web page files html, javascript, images, and css
    • /var/apollo/www/js – common JavaScript files
    • /var/apollo/www/images – common
    files (files used by multiple web pages)
    • image files
    • /var/apollo/www/css – common style sheets

  • Required files for new home page:
    • /var/apollo/www/user/home.html

  • Required files for login prompt:
    • /var/apollo/www/user – custom web page files html, javascript, images, and css/login.html
    • /var/apollo/www/js – common JavaScript files
    • /var/apollo/www/images – common image files
      • /var/apollo/www/css – common style sheets
    Required files for new home page:/var/apollo/www/user/home.html
  • Required files for login prompt:
    • /var/apollo/www/user/login.html
    • /var/apollo/www/user/images/LoginLogo.png

Image Removed

...

    • user/images/LoginLogo.png

Image Added

Adding a Login Prompt

Starting with SmartServer release 3.5 or higher the SmartServer defaults to enhanced security which checks to make sure your password meets the enhance security requirements (like being 14 characters or more). 

If you use the Original login1.html page, provided on the SmartServer then the login Web page may get stuck. You can either disable enhanced security (see ssh/console commands) or use the new login1.html file included with SmartServer release 4.0 and higher.

For the apollo user you should only change the password using the SmartServer Configuration System Web page and not using the CMS User Widget. Also password reset email is not supported for the apollo user. All other users you can request a password reset email (if SMTP is configured), or change the Password with the CMS User Widget or with the SmartServer release 4.0 or higher updated login1.html page.


The SmartServer comes with a built-in login prompt, but by default it is not enabled for your custom web pages.

  1. With SmartServer IoT 2.6, an example Login1 prompt and LoginLog1.png are provided which you can use with your custom web page. 

  2. You need to rename these files in order to use them as a SmartServer software update may change these files.

  3. You may customize the login prompt. One common modification to the login prompt is to change the company logo to your company logo, or the end customer company log.

  4. To use the login prompt, you need to rename login1.html and LoginLogo1 by removing the "1" from each.  
    a. Change the names of the file.

    Default:
    /var/apollo/www/user/login1.html
    /var/apollo/www/images/LoginLogo1.png

    New:
    /var/apollo/www/user/login.html
    /var/apollo/www/images/LoginLogo.png

    SmartServer 3.6 and previous releases

b. Change the login.html file link to point to LoginLogo.png instead of LoginLogo1.png by removing the "1" at the end.

Default:
<img src="../images/LoginLogo1.png1" alt=" " class="avatar">

New:
<img src="../images/LoginLogo.png" alt=" " class="avatar">

...

  1. Use the web page development tool to identify issues during development.
    1. Tools like Visual Studio Code will show formatting issue (like missing "}" and if the catch of a try catch is missing.

  2. Look at the web browser console, which shows run-time issues.
    1. Some run-time issues show up in the console, which shows the line number of the file causing an issue.

    2. Add console.log() in your source code to see messages.

  3. Web page debugger.
    1. Most web browsers have a debugger mode that you can use to troubleshoot your web pages.

    2. Look at network traffic to see if GET requests are happening.

    3. Single-step through your code.

  4. The web page does not change in the web browser after downloading new source code onto the SmartServer.
    1. This is usually due to the web browser caching the web page data.
      Chrome may cache graphic images so if the old graphic still shows up then, then clear the browsing history.

    2. Exit all tabs and web browsers accessing this web page.

    3. Delete the web browser temporary internet files (clear browser history), exit the web browser, and then start it again.

    4. Do "a" and "b" above and then restart your computer. Sometimes even deleting the cache does not work and you also need to reboot the computer.

  5. Datapoint value does not appear in the web page.
    1. The device does not exist.

    2. The datapoint path is wrong.
      1. If in IMM mode, the datapoint path needs to include device subsystems path.
        For example, device Sensor1 could have the following datapoint path Subsystem 1.classroom1.Sensor1/Thermometer/0/temp.

    3. Check datapoint path with Datapoint Browser Datapoints widget or API tester.

  6. Datapoint value does not change.
    1. Verify value changes with Datapoint BrowserDatapoints widget.

    2. If not using on-demand (max_age) for datapoint updates, then check if monitoring is enabled using the Datapoint Properties widget.

    3. If the value does not change, but you think it should, then use LonScanner Protocol Analyzer to see updates.

    4. If the value changes in Datapoint Browser widget.
      1. Verify web page tag assigned to tag.
        GET /iap/devs/*+name==Sensor1/if/LightSensor/0/nvoLuxLevel/tags/*

      2. Make sure that the datapoint pathname is correct in web page.

  7. Datapoint write does not change value on device.
    1. The SmartServer may return HTTP 204 (no content) for a PUT request whether the request was successful or not. That is, you will not get an error message if the URL or payload is incorrect. 
      1. Some write errors or warning may be reported in the write response but most other write errors or warnings show up in a WebSocket update (In the CMS Web page WebSocket updates show up as a pop up messages seen in the upper right-hand corner of the CMS Web page)
      2. If you don't use WebSockets then you can open the CMS Web page (set the Datapoint Widget polling to zero) and do a write, any write errors will show up as CMS pop up warning/error.
    2. Make sure the URL is correct and payload is properly formatted.   

    3. Use one or both of the following to see if the write PUT payload has an invalid format or the data value is invalid:
      1. ssh and issue following command (do not use the SmartServer console). Copy to notepad (or any text editor) before copying to ssh console:
               mosquitto_sub -v -t glp/0/+/ev/error 
      2. Use a MQTT tool like MQTT explorer (requires port 1883 to be open) and look at: 
               glp/0/+/ev/error

    4. Use LonScanner to see if the SmartServer sent the datapoint update.

  8. After writing to a datapoint, you see the end device change but do not see a change in the web page.
    1. For many applications you write to an input datapoint and you use a corresponding output datapoint for the status.
      1. In most cases, you should see the end device input datapoint updated quickly.
      2. Seeing output updates depends on whether the SmartServer automatically gets the updates.
        1. For certain devices (like external LON devices), the SmartServer does not get automatic updates; therefore, you need to do one or more of the following:
          1. Set up monitoring (polling or event driven), add a connection or use max_age.
        2. For internal LON devices, the SmartServer gets updated automatically, so check the status (ssh to SmartServer and type "sudo supervisorctl status") to make sure the service is running.

  9. Datapoint writes show datapoint switching back and forth between old and new values on the web page (datapoint flickering).
    1. Even though writing to datapoint changes in the device almost instantaneously, the next GET request may not show the new value.
      1. It takes a finite amount of time the write value to occur. If a GET response comes in when you are writing to a datapoint then after you process the write with a new value, processing the GET response with the old value will show your html element jumping to the new value, then the old value, and eventually the new value.
      2. If you use one datapoint to write to a device and a second feedback datapoint that shows the actual state, then it can take several GET requests to see the output value change. 
    2. To reduce datapoint flicker, you may need to add a feedback delay of up to 10 seconds for this datapoint.
      1. After you write to a datapoint, ignore all datapoint updates for this datapoint for a feedback time period.

...