SmartServer Developer's Guide

Owned by Nina Cardillo
Last updated: 10-Jan-2024
6 min read

You can create custom applications (apps), drivers, services, and web pages for the SmartServer. The APIs can also be used by a remote server (like a cloud server) to access the SmartServer. Your custom software can provide a custom service on the SmartServer, can provide an interface to other IoT services external to the SmartServer, or can provide an interface to IoT devices external to the SmartServer that do not use one of the protocols supported by the SmartServer.  Your custom software can also be implemented as custom web pages that interact with the SmartServer using the REST protocol.

Your custom software components interact with the SmartServer using the IoT Access Protocol (IAP).  IAP defines the following four application programming interfaces (APIs):

  • IAP/MQ – The IAP/MQ API is based on the MQTT messaging protocol.  MQTT is an ISO standard (ISO/IEC PRF 20922) publish-subscribe-based messaging protocol. It works on top of a TCP connection over an IP network. It is a lightweight protocol that is suitable for implementing applications, services, and drivers on a wide range of devices and servers including small code footprint edge devices, edge servers, and cloud hosts. IAP/MQ is used to connect applications, services, and drivers within the SmartServer, and is also used to connect SmartServers to a Remote CMS, to cloud applications and services, and to each other.  Custom software can use IAP/MQ to get datapoint updates from a large number of datapoints or a for an entire site. You can subscribe to a single wildcard topic such as "glp/0/+/ev/data/#" to send all datapoint updates to your MQTT application as they occur. Your MQTT application can then filter the datapoints of interest.

  • IAP/REST – The IAP/REST API is based on the REST (REpresentational State Transfer) web services protocol, sometimes called the RESTful protocol.  REST web services provide an interoperable web-standard interface for web clients such as web-page scripts running in web browsers to communicate with services hosted on web servers.  IAP/REST is typically used to connect client applications running within web-page scripts to an IAP/REST server, and can be used to implement any application supporting REST requests and responses.  The IAP/REST API is optimized for web pages that typically require a small amount of data per page.  For example, a monitoring web page may request 10 datapoint updates every two seconds.  The IAP/REST API is also preferred for scheduling applications due to additional scheduling services provided by IAP/REST that are not available in IAP/MQ.

    REST URL format is SmartServer-version specific

    • With SmartServer release 2.8 or higher, you do not have to specify the port number.
      https://<apollo_ip>/cms
    • With SmartServer 2.7 and prior, you have to specify the port number (8443).
      https://<apollo_ip>:8443/cms
  • IAP/WS – The IAP/WS API is based on WebSockets.  A WebSocket makes it possible to open a two-way interactive communication session between a web client such as a web browser and a server. Using a WebSocket API, a client can create a WebSocket from the server back to the client so the server can send event-driven responses to the client without the client having to poll the server for the updates.  You can use IAP/WS to get event-driven updates for device status changes, alarms, CPU usage, and current events per second (EPS).

You can develop custom software that runs internally to the SmartServer or than runs on a separate host from the SmartServer and communicates over an IP network attached to the SmartServer's LAN or WAN interface.  Custom software can use any services provided by the IAP/MQ, IAP/REST, or IAP/WS APIs, including services to read and write datapoints, provision and manage devices, manage data logs, or manage alarms.  You can also create an app that implements a virtual IAP or LON device on the SmartServer.  You can use virtual IAP or LON devices to make datapoints available through the IAP/MQ and IAP/REST APIs.  For example, you can create a custom app that implements a virtual LON device that makes any IAP/MQ datapoints available as LON network variables that can be used by LON tools and applications such as IzoT CT or any IzoT Net Server or LNS applications. 

You can develop custom web pages that are hosted on and served by the SmartServer.  Your custom web pages can provide a customized interface to the SmartServer.

You can develop custom applications and dashboards using any programming language that supports MQTT or REST.  You can develop custom web pages using any web page authoring tools that support REST.  You can also develop custom applications and dashboards using Node-RED which provides a graphical programming and web interface development environment.  Node-RED is integrated with the SmartServer, and includes built-in IAP nodes that simplify reading and writing any of the SmartServer datapoints from a Node-RED flow or dashboard.  Node-RED also includes built-in connector nodes that you can use to send datapoint updates to the cloud applications. 

The SmartServer will go on the wire and read a datapoint value from the device when datapoint monitoring is enabled for the datapoint, Node-RED is polling the datapoint, or when an on-demand read is requested. You can configure the datapoint properties using the CMS Datapoint Properties widget for a specific datapoint for a specific device type. This widget allows you to enable polling or for devices that support it event driving with polling. You can configure event driven with polling for BACnet devices that support COV, and LON device (DMM only, IMM doesn't support event driven). Event driven means as soon as the datapoint value has changed in the device then the value update is immediately sent from the edge device to the SmartServer. You can also specify whether each time the datapoint value is read it is always sent to all other drivers within the SmartServer, only when the value changes, or changes by a delta value. The CMS Datapoints widget poll rate and refresh button sends a on-demand request to the SmartServer for all datapoints listed. The on-demand request uses a maxage time which basically means if the datapoint value update is older then the specified time in seconds do a on-demand read. If the update time is less than the maxage time do not do a on-demand read. When an update occurs it is sent using MQTT so you will see it immediately on the IAP/MQ. If the datapoint is included in the WebSocket subscribe datapoint list then you will also see a WebSockets update for this datapoint.

Many of the topics in the Developer's Guide reference example apps, example drivers, example web pages, and the SmartServer Driver Framework.  Small examples are included inline in the following topics.  Longer examples and the SmartServer Driver Framework are available in the SmartServer GitHub repository at https://github.com/izot/smartserver-iot.  You can download the entire repository as a ZIP archive file or you can clone the repository on your local computer.  To download a ZIP archive, click SmartServer-IoT, then click Clone or Download, and then click Download ZIP.  To clone the repository, you can use the git application or you can use a development tool such as Visual Studio Code that includes an integrated git interface.  To clone with git, open a Windows command prompt, navigate to the directory you plan to use for the repository, and then type: git clone https://github.com/izot/smartserver-iot.git .  This action copies the SmartServer IoT repository on your local drive under a smartserver-iot folder.  See help.github.com/en/articles/cloning-a-repository for more information on cloning a GitHub repository.  See code.visualstudio.com for more information on Visual Studio Code.

The following topics describe how to set up your computer for developing customer apps or drivers, provide a programming tutorial that will take you through some basic steps related to writing programs for the SmartServer, describe how to develop custom apps and drivers, and describe how you can create custom web pages.

For SmartServer 4.0 and higher, most log data is in /var/log/syslog. Use smartserverctl to access SmartServer services.

For SmartServer 3.6 and prior releases, log data is distributed into specific log files, such as logs in /var/log/supervisor. Use supervisorctl to access SmartServer services.

Setting Up Your Development Environment

This section describes a development environment for creating custom apps and drivers to run on the SmartServer. 

General Programming Information

This section provides general information about creating applications for the SmartServer.  

Programming Tutorial

This section provides a introductory tutorial for developing a custom app.  It includes:

Creating a Custom LON App

This section describes how to create internal apps for the SmartServer.

IAP API Fundamentals

This section provides some basic information about the SmartServer APIs.

Programming Tasks

This section provides instructions on performing various programming tasks.  It includes:  

Creating Custom Web Pages

This section helps you create custom web pages for the SmartServer.