MSA Grid RESTful API User guide

Grid RESTful API Start-up Guide 0
Start-up Guide
GridRESTful API
MSAsafety.com
Document Revision: 2.A
T18663
APPLICABILITY & EFFECTIVITY
Effective for all systems manufactured after August 2021.

Grid RESTful API Start-up Guide 2
MSA Safety
1991 Tarob Court
Milpitas, CA 95035
Website: www.MSAsafety.com
U.S. Support Information:
[phone]
[phone]
Email: [email protected]
EMEA Support Information:
[phone]
Email: [email protected]

Grid RESTful API Start-up Guide 3
Assumptions
The following items should be complete before moving forward with Grid RESTful API setup.
✓Install preferred RESTful client program.
✓Setup a Grid account.
✓Login to a computer with access to the internet and web browser.

Grid RESTful API Start-up Guide 4
Quick Start Guide
1. Open the preferred RESTful client.
2. Authenticate with www.FieldPoP.io/rest/login.
3. Test the API.
a. Set up a sample
b. Run the sample
4. Run GET device data log commands.

Grid RESTful API Start-up Guide 5
Table of Contents
1Overview............................................................................................................................................6
2Grid RESTful API Supported Functions.........................................................................................7
2.1 HTTP Usage.............................................................................................................................7
2.2 Authentication...........................................................................................................................7
2.2.1 Login.........................................................................................................................................7
2.3 Data Read/Write.......................................................................................................................8
2.3.1 Data Path Parameter ...............................................................................................................8
2.3.2 All Field Device Types..............................................................................................................9
2.3.3 Device Type: System View ....................................................................................................10
2.3.4 Device Type: BACnet Explorer NG........................................................................................20
2.3.5 Device Type: BACnet IoT Gateway.......................................................................................22
2.4 User Methods .........................................................................................................................34
2.4.1 GetUserInfo............................................................................................................................34
2.4.2 GetUserDevices.....................................................................................................................34
2.4.3 ListDeviceUsers .....................................................................................................................37
2.5 ProtoCast Methods.................................................................................................................38
2.5.1 CreateOEMUser.....................................................................................................................38
2.5.2 GetFieldCastOEMList ............................................................................................................38
2.5.3 GetDeviceData.......................................................................................................................39
2.5.4 GetDeviceDataWithTime........................................................................................................40
2.6 Firmware Methods..................................................................................................................41
2.6.1 GetDeviceFirmwareVersions .................................................................................................41
2.6.2 UpgradeFirmware...................................................................................................................42
3Additional Information...................................................................................................................43
3.1 General Notes.........................................................................................................................43
3.1.1 How to Obtain an IIoT Device ID (DeviceID Parameter Value).............................................43
3.1.2 Device API Version................................................................................................................43
3.1.3 Data Retention .......................................................................................................................43
3.1.4 Data Structure........................................................................................................................43
3.2 Using CURL to Generate Grid RESTful API Requests..........................................................44
3.3 How to Access the RESTful API Through Fiddler..................................................................45
3.4 Generic Information for Access to the Grid RESTful API.......................................................48
3.4.1 Authenticate via GET Command............................................................................................48
3.4.2 Authenticate via POST Command.........................................................................................48
3.4.3 Run GET Command to Deliver Device Data Logs.................................................................48
4Troubleshooting.............................................................................................................................49
4.1 Lost MSA Grod Login Password............................................................................................49
5Useful Features ..............................................................................................................................50
5.1 Security...................................................................................................................................50
5.1.1 PC to MSA Grid......................................................................................................................50
5.1.2 FieldServer to MSA Grid........................................................................................................50
5.1.3 Viewing the Certificate ...........................................................................................................51
6Warranty..........................................................................................................................................53

Overview
Grid RESTful API Start-up Guide 6
1 Overview
Setting up the Grid as a RESTful API allows Grid users to automate the sending of recorded device data
(gathered from the Grid) to the cloud.
NOTE: For general Grid registration and use instructions, see the MSA Grid Start-up Guide.
The Grid RESTful API acts as a RESTful server using HTTPS. The API will support authentication, read
operations, and write operations, including:
•Read (HTTP GET)
odata logs recorded on the Grid
oevent logs recorded on the Grid
ocurrent data values exposed to the Grid by devices
•Write (HTTP PUT)
owritable values (e.g. setpoints) exposed to the Grid by devices
In a Javascript environment, a Happner client would be the suggested access method.
NOTE: All URLs are given relative to https://www.fieldpop.io/.

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 7
2 Grid RESTful API Supported Functions
2.1 HTTP Usage
Most RESTful requests can be made using either POST or GET requests. POST requests must specify
parameters in a JSON payload and GET requests must specify parameters as query parameters in the
URL. Parameters that are too complex for the query parameter syntax will necessitate a JSON POST
request.
All POST requests containing a JSON payload must set the following HTTP header:
Content-Type: application/json
2.2 Authentication
A RESTful client acquires an API token using the Authenticate RESTful call. This token must
accompany every RESTful request as a query parameter in order to authenticate the request.
Authentication tokens inherit the permissions of the user who created them.
Important Note:
All GET and POST requests other than Authentication requests must provide the authentication
token as a query parameter, happn_token:
/rest/method/fieldpop-api/deviceDataLog?happn_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ImlkfGNiMmQ0N
Dg5LTAyNTQtNGJlYy1hZWNiLThkZDM3NDY0NjA3Mnx0eXBlfHRpbWVzdGFtcHxpc0VuY3J5cHRlZHxvcmlnaW58Z
mllbGRwb3AtbWFpbnxwb2xpY3l8MHx0dGx8aW5hY3Rpdml0eV90aHJlc2hvbGR8MXxwZXJtaXNzaW9uU2V0S2V5f
C9PRU0rQWRtaW4vL19NRVNIX0dTVC98aXNUb2tlbnx1c2VybmFtZXxlZ2dlcnNqZW5zQGdtYWlsLmNvbV4wfEozW
DRKU0pLfDB8MF5eJDB8MXwyfEh8M3xJfDR8LTJ8NXw2fDd8JDh8JDl8SnxBfC0zXXxCfCQ5fEt8QXwtM11dfEN8R
HxFfC0xfR10i.H7BAXttwX1aug4HXDnJwBh8m4njAi2ggQAMCNBGWRE
This query parameter will be shortened in the examples below for brevity.
2.2.1 Login
NOTE: Check if the Grid password uses “#”. If so, the password must be changed to remove it
before moving forward. See the MSA Grid Start-up Guide for instructions. The # symbol is
a reserved character in URL web services.
Description: Use user credentials to obtain a new API token.
HTTP Verb: GET or POST
URL: /rest/login
JSON Parameters: username (email address), password
Example GET URL: rest/[email protected]&password=Ip6ISBKiOy5U
Example POST URL: rest/login
Example POST Payload:
{
"username": "admi[email protected]",
"password": "Ip6ISBKiOy5U"
}

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 8
Example JSON Response:
{
"message": "Logged in ok",
"data": {
"token":
"eyJ0eXAiOiJKV1QiLCJhbGcoIoJIUzI1NiJ9.ImlkfDI1MGYxYWIwLWQzMjktNGQyNS1hMTE5LThlOTJhZDc0MzcyZXx0eXBlfH
RpbWVzdGFtcHxpc0VuY3J5cHRlZHxvcmlnaW58MTAtMC0yOC0xODFfNTcwMDB8cG9saWN5fDB8dHRsfGluYWN0aXZpdHlf
dGhyZXNob2xkfDF8cGVybWlzc2lvblNldEtleXwvT0VNK0FkbWluLy9fTUVTSF9HU1QvfGlzVG9rZW58dXNlcm5hbWV8ZWdnZ
XJzamVuc0BnbWFpbC5jb21eMHxKNjZCOFBGR3wwfDBeXiQwfDF8MnxIfDN8SXw0fC0yfDV8Nnw3fCQ4fCQ5fEp8QXwtM11
8QnwkOXxLfEF8LTNdXXxDfER8RXwtMXxGfEddIg.ihjURRHILcXp-iTl4FvjjAma1sI1_CDINGyQuSNacDM"
},
"error": null
}
2.3 Data Read/Write
2.3.1 Data Path Parameter
Whenever a parameter is specified as a path, this acts as a wildcard and includes all items that
appear below the specified path.
Examples:
•/device1/plc1/point3 returns the JSON value of point3 (e.g. 1.234)
•/device1/plc1 returns a JSON value with all points belonging to plc1:
{
"point1": true,
"point2": false,
"point3": 1.234
}

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 9
2.3.2 All Field Device Types
DeviceDataLog
Description: Get all data logs available to user, narrowed down by optional parameters.
HTTP Verb: GET or POST
URL: /rest/method/fieldpop-api/deviceDataLog
Parameters:
•happn_token - Token obtained from the login request.
•deviceID –the IIoT gateway ID (see Section 3.1.1).
•startUTCsec (optional) - Start time in seconds since start of UTC epoch.
•endUTCsec (optional) - End time in seconds since start of UTC epoch.
JSON Response: Object containing time series data.
Example GET URL:
/rest/method/fieldpop-api/deviceDataLog?happn_token=eyJ0eXAiOiJKV1QiLCJhbGci&deviceID=lavenderqueste
r_4k9q5oU-Q&startUTCsec=1502375626
Example POST URL: /rest/method/fieldpop-api/deviceDataLog?happn_token=eyJ0eXAiOiJKV1QiLCJhbGci
Example POST Payload:
{
"parameters": {
"deviceID": "lavenderquester_4k9q5oU-Q",
"path": "lavenderquester_4k9q5oU-Q/BAC_IP_Steam_1/Blower",
"startUTCsec": 1499332783,
"endUTCsec": 1499334577
}
}
Example JSON Response:
{
"message": "Call successful",
"data": {
"Steam_2": {
"Main_Valve": [
{
"time": 1502375626,
"value": 0
},
{
"time": 1502376528,
"value": 0
},
{
"time": 1502377421,
"value": 0
}
],
"FIRING_RATE": [
{
"time": 1502375626,
"value": 0
},
{
"time": 1502376528,
"value": 0
},
{
"time": 1502377421,
"value": 0
}
]
}
},
"error": null
}

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 10
2.3.3 Device Type: System View
GetDeviceData (System View v.2, v.3)
Description: Retrieve the data available under the specified device and data path.
HTTP Verb: GET or POST
URL: /rest/method/fieldpop-api/getDeviceData
Parameters:
•happn_token - token obtained from the login request.
•IIoT device selector (optional) –one of two ways of specifying the target IIoT device(s):
odeviceID - the IIoT gateway ID (see Section 3.1.1)
odeviceFilter –MongoDB-style query object (see https://www.npmjs.com/package/sift); this
option can only be specified by posting parameters in a JSON payload
•path (optional) - the path of the values to read from the specified gateway devices. This can be
done at multiple levels:
ono path - the response will contain all devices with all their properties
odevice - the response will contain the properties of the specified device
odevice/property - the response will just contain the property value
JSON Response: data object -includes all data matching specified path parameter:
•no path - all available data for all devices.
•device - all available properties for specified device.
•device/property - value of specified property on specified device.
Example GET URL: (no path specified)
/rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC&deviceID=blazescowl_VygDWeqmz
Example JSON Response: (no path specified)
{
"message": "Call successful",
"data": {
"Device_1_Profile_1": {
"parameters": {
"node_id": "1",
"parameter1": "1",
"parameter2": "1"
},
"type": "Device1",
"mapping": "Device1",
"name": "Device_1_Profile_1",
"path": "/profileView/devices/Device_1_Profile_1",
"node": "Dev_1_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"property0": 1,
"property1": 1,
"alarm_property": 0,
"trouble_property": 0
},
"Device_1_Profile_2": {
"parameters": {
"node_id": "2",
"parameter1": "1",
"parameter2": "2"
},
"type": "Device1",
"mapping": "Device1",
"name": "Device_1_Profile_2",
"path": "/profileView/devices/Device_1_Profile_2",
"node": "Dev_1_2",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"property0": 1,
"property1": 2,
"alarm_property": 0,
"trouble_property": 0
},
"Device_2_Profile_1": {

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 11
"parameters": {
"node_id": "3",
"parameter1": "2",
"parameter2": "1"
},
"type": "Device2",
"mapping": "Device2",
"name": "Device_2_Profile_1",
"path": "/profileView/devices/Device_2_Profile_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"property0": 1
},
"Device_2_Profile_2": {
"parameters": {
"node_id": "4",
"parameter1": "2",
"parameter2": "2"
},
"type": "Device2",
"mapping": "Device2",
"name": "Device_2_Profile_2",
"path": "/profileView/devices/Device_2_Profile_2",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"property0": 2
}
},
"error": null
}
Example JSON Response: (path = Device_1_Profile_1)
{
"message": "Call successful",
"data": {
"parameters": {
"node_id": "1",
"parameter1": "1",
"parameter2": "1"
},
"type": "Device1",
"mapping": "Device1",
"name": "Device_1_Profile_1",
"path": "/profileView/devices/Device_1_Profile_1",
"node": "Dev_1_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"property0": 1,
"property1": 1,
"alarm_property": 0,
"trouble_property": 0
},
"error": null
}
Example JSON Response: (path = Device_1_Profile_1/property0)
{
"message": "Call successful",
"data": 1,
"error": null
}
Example POST URL: /rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLCJhbGci
Example POST Payload: (array of paths)
{
"parameters": {
"deviceFilter": {
"$ne": "Normal"
},
"path": [
"BAC_IP_Falcon_Hydronic_1_/type",
"BAC_IP_Falcon_Hydronic_1_/BURN_CTL_
STATUS",
"BAC_IP_Falcon_Hydronic_1_/
INLETWATERTEMPDEGF",
"BAC_IP_Falcon_Steam_2_/type",

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 12
"BAC_IP_Falcon_Steam_2_/BURN_CTL_
STATUS",
"BAC_IP_Falcon_Steam_2_
/INLETWATERTEMPDEGF"
]
}
}
Example JSON Response: (array of paths)
{
"message": "Call successful",
"data": {
"lightninghide_EJ2PQsKJb": {
"data": [
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Hydronic_1_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Hydronic_1_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Hydronic_1_"
}
},
{
"data": "BAC_IP_Falcon_Steam"
},
{
"data": 1
},
{
"error": {
"message": "Unknown property for device
BAC_IP_Falcon_Steam_2_:
INLETWATERTEMPDEGF"
}
}
]
},
"shagcrest_Nk9hhqHFz": {
"data": [
{
"data": "BAC_IP_Falcon_Hydronic"
},
{
"data": 48
},
{
"data": 78.8
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Steam_2_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Steam_2_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Steam_2_"
}
}
]
},
"cybergecko_VJU": {
"data": [
{
"data": "BAC_IP_Falcon_Hydronic"
},
{
"data": 48
},
{
"data": 82.94
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Steam_2_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Steam_2_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Steam_2_"
}
}
]
},
"lavenderquester_4k9q5oU-Q": {
"data": [
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Hydronic_1_"
}
},
{
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Hydronic_1_"
}
},
{

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 13
"error": {
"message": "Unknown field device:
BAC_IP_Falcon_Hydronic_1_"
}
},
{
"data": "BAC_IP_Falcon_Steam"
},
{
"data": 1
},
{
"error": {
"message": "Unknown property for device
BAC_IP_Falcon_Steam_2_:
INLETWATERTEMPDEGF"
}
}
]
},
"crackfisher_N1-": {
"error": {
"message": "timeout"
}
},
"hurricanestone_NkvQCitk-": {
"error": {
"message": "timeout"
}
},
"tulipgorilla_EyGpqsFkb": {
"error": {
"message": "timeout"
}
}
},
"error": null
}
GetDeviceData (System View v.4)
Description: Retrieve the data available under the specified device(s) and data path(s).
HTTP Verb: GET or POST
URL: /rest/method/fieldpop-api/getDeviceData
Data Model: The underlying data is structured as an object keyed by IIoT gateway identifier
(deviceID) values at the top level. Each gateway value is an array of downstream field device objects.
Here is a schematic example of the full available data for a given user.
{
"gateway_1": {
"data": [
{
"parameters": {
"node_id": "1"
},
"type": "BAC_IP_Falcon_Hydronic",
"mapping": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"path":
"/profileView/devices/BAC_IP_Falcon_Hydronic_1_",
"node": "Dev_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "1",
"location": "R&D Lab Unit 1",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"parameters": {
"node_id": "2"
},
"type": "BAC_IP_Falcon_Steam",
"mapping": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"path":
"/profileView/devices/BAC_IP_Falcon_Steam_2_",
"node": "Dev_2",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "2",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BURNER_ENABLE": 1
}
]
},
"gateway_2": {
"data": [
{
"parameters": {
"node_id": "1"
},
"type": "BAC_IP_Falcon_Hydronic",
"mapping": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"path":
"/profileView/devices/BAC_IP_Falcon_Hydronic_1_",
"node": "Dev_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},

Grid RESTful API Supported Functions
Grid RESTful API Start-up Guide 14
"activeEvents": {},
"address": "1",
"location": "R&D Lab Unit 1",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"parameters": {
"node_id": "2"
},
"type": "BAC_IP_Falcon_Steam",
"mapping": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"path":
"/profileView/devices/BAC_IP_Falcon_Steam_2_",
"node": "Dev_2",
"events": {
"alarm": true,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "2",
"status_class": "status_normal",
"status": "Alarm",
"oldStatus": "Normal",
"BURNER_ENABLE": 1
}
]
}
}
A query can narrow the entire data set down by:
•selecting only certain gateway devices (e.g. gateways reporting an Alarm state), using the
deviceFilter parameter.
•selecting only certain downstream devices within the selected gateway devices (e.g. those
reporting an Alarm status), using the dataFilter parameter.
•selecting only certain data paths to be read from the selected downstream devices, using the
path parameter.
Parameters:
•happn_token - token obtained from the login request.
•IIoT device selector (optional) –one of two ways of specifying the target IIoT device(s):
odeviceID –the IIoT gateway ID (see Section 3.1.1)
odeviceFilter –MongoDB-style query object (see https://www.npmjs.com/package/sift); this
option can only be specified by posting parameters in a JSON payload
If no gateway device selection criteria are given, all gateways are queried. Use with care! Not
specifying IIoT device(s) will cause requests to be sent to all IIoT devices!
•path (optional):
oeither a path string, pointing to a value within each downstream field device (boiler) object,
e.g. "propertyName/subPropertyName"
oor an array of such path strings, e.g. ["propertyName_1/subPropertyName_1",
"propertyName_2/subPropertyName_2"]
onote that any unmatched path value is simply ignored and left out of the result
oif no path is specified, all available values are returned
•options (optional) –an optional object containing:
odataFilter –a MongoDB-style sift query object (see https://www.npmjs.com/package/sift);
result objects relating to downstream field devices are only included in the response if they
match this filter
JSON Response: data object containing an Array of filtered query response objects.
Example 1 –POST URL: (no JSON parameters specified)
/rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC

Install OpenVPN Client
Grid RESTful API Start-up Guide 15
Example 1 –JSON Response:
{
"message": "Call successful",
"data": {
"gateway_1": {
"data": [
{
"parameters": {
"node_id": "1"
},
"type": "BAC_IP_Falcon_Hydronic",
"mapping": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"path":
"/profileView/devices/BAC_IP_Falcon_Hydronic_1_",
"node": "Dev_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "1",
"location": "R&D Lab Unit 1",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"parameters": {
"node_id": "2"
},
"type": "BAC_IP_Falcon_Steam",
"mapping": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"path":
"/profileView/devices/BAC_IP_Falcon_Steam_2_",
"node": "Dev_2",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "2",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BURNER_ENABLE": 1
}
]
},
"gateway_2": {
"data": [
{
"parameters": {
"node_id": "1"
},
"type": "BAC_IP_Falcon_Hydronic",
"mapping": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"path":
"/profileView/devices/BAC_IP_Falcon_Hydronic_1_",
"node": "Dev_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "1",
"location": "R&D Lab Unit 1",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"parameters": {
"node_id": "2"
},
"type": "BAC_IP_Falcon_Steam",
"mapping": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"path":
"/profileView/devices/BAC_IP_Falcon_Steam_2_",
"node": "Dev_2",
"events": {
"alarm": true,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "2",
"status_class": "status_normal",
"status": "Alarm",
"oldStatus": "Normal",
"BURNER_ENABLE": 1
}
]
}
},
"error": null
}
Example 2 –POST URL: /rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC
Example 2 –JSON POST: (deviceID specified)
{
"parameters": {
"deviceID": "gateway_1"
}
}

Install OpenVPN Client
Grid RESTful API Start-up Guide 16
Example 2 –JSON Response:
{
"message": "Call successful",
"data": [
{
"parameters": {
"node_id": "1"
},
"type": "BAC_IP_Falcon_Hydronic",
"mapping": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"path":
"/profileView/devices/BAC_IP_Falcon_Hydronic_1_",
"node": "Dev_1",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "1",
"location": "R&D Lab Unit 1",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"parameters": {
"node_id": "2"
},
"type": "BAC_IP_Falcon_Steam",
"mapping": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"path":
"/profileView/devices/BAC_IP_Falcon_Steam_2_",
"node": "Dev_2",
"events": {
"alarm": false,
"trouble": false,
"warning": false
},
"activeEvents": {},
"address": "2",
"status_class": "status_normal",
"status": "Normal",
"oldStatus": "Normal",
"BURNER_ENABLE": 1
}
],
"error": null
}
Example 3 –POST URL:
/rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC
Example 3 –JSON POST: (path specified, but no IIoT device selector or dataFilter)
{
"parameters": {
"path": [
"name",
"type",
"status",
"BOILERLEADLAGSETPOINTDEGC",
"BURNER_ENABLE"
]
}
}
Example 3 –JSON Response:
{
"message": "Call successful",
"data": {
"gateway_1": {
"data": [
{
"type": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"status": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"type": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"status": "Normal",
"BURNER_ENABLE": 1
}
]
},
"gateway_2": {
"data": [
{
"type": "BAC_IP_Falcon_Hydronic",
"name": "BAC_IP_Falcon_Hydronic_1_",
"status": "Normal",
"BOILERLEADLAGSETPOINTDEGC": 58.9
},
{
"type": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"status": "Alarm",
"BURNER_ENABLE": 1
}
]
}
},
"error": null
}

Install OpenVPN Client
Grid RESTful API Start-up Guide 17
Example 4 –POST URL:
/rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC
Example 4 –JSON POST: (path and dataFilter specified, but no IIoT device selector)
{
"parameters": {
"path": [
"property0",
"property1",
"events/alarm"
],
"options": {
"dataFilter": {
"name": {
"$eq": "Device_1_Profile_1"
}
}
}
}
}
Example 4 –JSON Response:
{
"message": "Call successful",
"data": {
"gateway_1": {
"data": [
{
"events": {
"alarm": false
},
"property0": 1,
"property1": 1
}
]
},
"gateway_2": {
"data": [ ]
}
},
"error": null
}

Install OpenVPN Client
Grid RESTful API Start-up Guide 18
Example 5 –JSON POST: (deviceFilter, path and dataFilter specified)
{
"parameters": {
"deviceFilter": {
"state": {
"$eq": "Alarm"
}
},
"path": [
"name",
"type",
"status",
"BOILERLEADLAGSETPOINTDEGC",
"BURNER_ENABLE"
],
"options": {
"dataFilter": {
"status": {
"$eq": "Alarm"
}
}
}
}
}
Example 5 –JSON Response:
{
"message": "Call successful",
"data": {
"gateway_2": {
"data": [
{
"type": "BAC_IP_Falcon_Steam",
"name": "BAC_IP_Falcon_Steam_2_",
"status": "Alarm",
"BURNER_ENABLE": 1
}
]
}
},
"error": null
}

Install OpenVPN Client
Grid RESTful API Start-up Guide 19
SetDeviceData (System View)
Description: Set the data available under the specified device and data path.
HTTP Verb: POST
URL: /rest/method/fieldpop-api/setDeviceData
Query String Parameters:
•happn_token - token obtained from the login request.
HTTP Headers:
•Content-Type - application/json
Body Parameters (JSON):
•parameters - object containing the following fields:
odeviceID - the IIoT gateway ID (see Section 3.1.1)
opath - the path of the value to set; this must be done at the leaf level
“deviceName/propertyName”
ovalue - the value to set
Example Body Parameters:
{
"parameters": {
"deviceID": "blazescowl_VygDWeqmz",
"path": "BAC_IP_EVG_1_/BoilerModel",
"value": 50
}
}
Example JSON Response:
{
"message": "Call successful",
"data": null,
"error": null
}

Install OpenVPN Client
Grid RESTful API Start-up Guide 20
2.3.4 Device Type: BACnet Explorer NG
Please note that the 'BACnet Explorer NG' product is obsolete. Contact support to upgrade
your product to a 'BACnet IoT Gateway' –see Section 2.3.5.
GetDeviceData (BACnet Explorer NG)
Description: Retrieve the data available under the specified device and data path.
HTTP Verb: POST
URL: /rest/method/fieldpop-api/getDeviceData
Query String Parameters:
•happn_token - token obtained from the login request.
HTTP Headers:
•Content-Type - application/json
Body Parameters (JSON):
•parameters - object containing the following fields:
odeviceID - the IIoT gateway ID (see Section 3.1.1)
opath - the path of the value to get (must be 3 levels deep:
"deviceInstance/objectType:objectInstance/propertyIdentifier")
ooptions - object containing the following fields:
▪asn1 - must be set to true since default representation might change in the future
Example Body Parameters:
{
"parameters": {
"deviceID": "bigelf_rkr",
"path": "200/analog-value:0/present-value",
"options": {
"asn1": true
}
}
}
Example JSON Response:
{
"message": "Call successful",
"data": {
"value": 28,
"type": "REAL"
},
"error": null
}