Versions Compared

Old Version 3

changes.mady.by.user Nina Cardillo

Saved on

compared with

New Version 4

changes.mady.by.user Nina Cardillo

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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/*/*/*

...

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

...

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

...

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 and it is setup . 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 dataevent driven) in order to see 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 changes must be made to both files on each SmartServer that will run the custom web page:

...

# Everything Else 

and

...

  sudo nginx -s reload 

...

# Everything Else - TBD
# 1) check for maintenance page and display if it exists
# 2) check for local (static) file
# 3) check for local directory
# 4) pass request to IzoT Server
#location / {
# try_files /maintenance.html $uri $uri/ @izot-server;
#}

...

auth_basic "Restricted";
auth_basic_user_file /etc/apollo/.htpasswd;
}

Saving Custom Web Page Files

Custom web pages should be located in the following SmartServer directories to ensure that custom files are not deleted with SmartServer updates:

  • /var/apollo/www – location for all custom web pages

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

...

  • /var/apollo/www/user/login.html
  • /var/apollo/www/user/images/LoginLogo.png

Image Removed

...

the custom web page:

  1. Backup the apollo.secure and apollo.self files either on the SmartServer or to your computer. These files are unique per SmartServer so you will need to do this on each SmartServer.

  2. Edit /etc/nginx/sites-available/apollo.secure.
    You can do this with WinSCP or by coping the file to your computer and using notepad or any other text editor. Save as Text only.

  3. Look for the following two entries:

    # Everything Else 

    and

    # IzoT Router (PHP Server)

  4. Copy the following text to a text editor (such as notepad.exe) on your computer or Writer so that all text formatting information is removed:

        # CMS REST API Server
        # 1) pass request to Jetty (CMS REST API Server)
        location /iap {
        #rewrite ^/iap(.*) /$1 break;
        proxy_pass https://localhost:8443;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass_header Server;
        }

  5. Copy the text from your text editor to just before the following entry:
    # IzoT Router (PHP Server)

  6. Save the file.

  7. Repeat steps 2-6 for /etc/nginx/sites-available/apollo.self.

  8. Re-start nginx by running the following command in the SmartServer console, or by rebooting the SmartServer.

  sudo nginx -s reload 


The following example shows the added content (shown in red):

# Everything Else - TBD
# 1) check for maintenance page and display if it exists
# 2) check for local (static) file
# 3) check for local directory
# 4) pass request to IzoT Server
#location / {
# try_files /maintenance.html $uri $uri/ @izot-server;
#}

# CMS REST API Server
# 1) pass request to Jetty (CMS REST API Server)
location /iap {
proxy_pass https://localhost:8443;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass_header Server;
}

# IzoT Router (PHP Server)
# 1) verify PHP file exists
# 2) pass request to PHP Server
location @apollo-config {
# APOLLO try_files $uri = 404;
# APOLLO fastcgi_split_path_info ^(.*?\.php)(/.*)$;
# APOLLO fastcgi_pass unix:/run/php/php7.0-fpm.sock;
# APOLLO fastcgi_index index.php;
# APOLLO include fastcgi_params;
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
fastcgi_read_timeout 300;

auth_basic "Restricted";
auth_basic_user_file /etc/apollo/.htpasswd;
}

Saving Custom Web Page Files

Custom web pages should be located in the following SmartServer directories to ensure that custom files are not deleted with SmartServer updates:

  • /var/apollo/www – location for all 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 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 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">

...