IAP/WS API

Owned by Nina Cardillo
Last updated: 14-Aug-2024
3 min read

WebSockets are used in two way: general purpose WebSocket and data log WebSocket.

General Purpose WebSocket

A single general purpose WebSocket is used to get datapoint value, device status and alarm updates. Most of the popups messages you see in the top right-hand corner of the CMS Web page are WebSocket updates.

Unlike many other REST APIs in which request errors show up in the REST request response, the SmartServer REST request errors or warnings sometimes show up in the REST request response and sometimes these error/warning messages only show up as a general purpose WebSockets update.  

The general purpose WebSocket initialed by sending the following IAP/WS request "/iap/ws" to open a WebSocket which stays open as long as the Web page is open. All other request are performed using IAP/REST requests like IAP/REST subscribe or IAP/REST On-demand GET requests.

The following list describes some common WebSocket update types:

Query Parameter                                 

Description

CRT:ALARM
DEL:ALARM
CRT:NOTIFICATIONThis is a general purpose notification, for example, when a device does not respond back to a request.
DEL:DEVICEShows when a device is deleted.
UPD:CPU

Shows CMS CPU.


UPD:SC:CPU

Shows segment controller (SmartServer) CPU.


UPD:DEVICEShow device status updates like device is provisioned, down or normal.
UPD:DEVICE_TEST_RESULT
UPD:EPSShows CMS EPS.
UPD:DATAPOINTShows datapoint updates. The REST subscribe request controls which datapoints have updates. If there is more than one CMS web page, or custom web page using WebSockets, then the page that issued the last subscribe request determines which datapoints appear in the CMS.
UPD:MONITORINGSTATEShows whether monitoring is enabled disabled (this shows the state of the CMS Devices widget pause/play icon).
UPD:TOTAL_EPS
NTF:JOINShows received service pin messages.

NTF:TIME

Shows the current CMS timestamp. Supported in SmartServer 4.1 (Beta) and higher.

Note: to limit the amount of data logs retrieve in one request always use &value parameter.  It is good to limit the &value range. 

Data Log WebSocket

Data log WebSockets, which is only used to get data logs, are temporary WebSocket connection which stay open only as long as needed to process the specific IAP/WS request. These WebSockets always end with a "end" update. The WebSocket is automatically closed by the SmartServer after sending the "end".

Special characters in the data log WebSocket request may have to be encoded based on where they show up in the request.  

The following list describes the optional query parameters, see for encoding requirements:

Query Parameter                                 

Description

dev={device id or name}

Device id or device name.

Formats: "?dev={device Id}" or "?dev=*+name=={device name}"

Examples: "?dev=2", and "?dev=*+name==Sensor 1"

blockName={block name}

Block instance name or XIF name. 

Format: "&blockName={block instance name}", "&blockName=*+xifName=={block XIF name}", "&blockName=*+name=={block instance name}"

Examples: "&blockName=LightSensor", "&blockName=*+xifName==LightSensor",  and "&blockName=*+name==LightSensor"

blockIndex={Index}Block Index

dpName={datapoint name}

Datapoint instance name or XIF name.

Formats:  "&dpName={datapoint instance name}", "&dpName=*+xifName=={datapoint XIF name}", "&dpName=*+name=={datapoint instance name}"

Examples: "&dpName=nvoLightLevel", "&dpName=*+xifName==nvoLuxLevel",  and "&dpName=*+name==nvoLightLevel"

value={time range}

timestamp range Filters.

Example formats: "&value=*+utc>{utc starting timestamp}", "&value=*+utc<={utc ending timestamp}", and "&value=*+utc>{utc starting timestamp}&utc<={utc ending timestamp"

Example: "&value=*+utc>2021-04-22T08:00:00.000&utc<=2021-04-22T17:35:10.000"

To limit the amount of data logs returned it recommended that you use starting and ending timestamps, or limit request to specific datapoints

Note: to limit the amount of data logs retrieve in one request always use &value parameter.  It is good to limit the &value range. 

Examples

1. To get all logs between UTC timestamp 2021-04-22T08:00:00.000 and 2021-04-22T17:35:10.000

Request:  

/iap/ws?value=*+utc>2021-04-22T08:00:00.000&utc<=2021-04-22T17:35:10.000


Encoded:  (shown in red in the request)

  • “*+” = “%2A%2B"
  • “>” = “%3E”
  • “&” in range “%26” 
  • “<=” = “%3C%3D”

/iap/ws?value=%2A%2Butc%3E2021-04-22T08:00:00.000%26utc%3C%3D2021-04-22T17:35:10.000


2. To get all logs for a specific datapoint using XIF name between UTC timestamp 2021-04-22T08:00:00.000 and 2021-04-22T17:35:10.000

Datapoint XIF Name:  Sensor 1/LightSensor/0/nvoLuxLevel[1]


Request:  datapoint XIF name

/iap/ws?dev=*+name==Sensor 1&blockName=*+xifName==LightSensor&blockIndex=0&dpName=*+xifName==nvoLuxLevel[1]&value=*+utc>2021-04-22T08:00:00.000&utc<=2021-04-22T17:35:10.000


Encoded:  (shown in red in the request)

  • space name ("Sensor 1") = “%20”
  • “*+” = “%2A%2B"
  • “==” = “%3D%3D”
  • “>” = “%3E”
  • “&” in range “%26”
  • “<=” = “%3C%3D”

/iap/ws?dev=%2A%2Bname==Sensor%201&blockName=%2A%2BxifName%3D%3DLightSensor&blockIndex=0&dpName=%2A%2BxifName%3D%3DnvoLuxLevel[1]&value=%2A%2Butc%3E2021-04-22T08:00:00.000%26utc%3C%3D2021-04-22T17:35:10.000