MSA Grid RESTful API Startup Manual
  1. Manuals
  2. Brands
  3. MSA Manuals
  4. Safety Equipment
  5. Grid RESTful API
  6. Startup manual
MSA Grid RESTful API Startup Manual

MSA Grid RESTful API Startup Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

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

Advertisement

Table of Contents
loading

Related Manuals for MSA Grid RESTful API

Summary of Contents for MSA Grid RESTful API

  • Page 1 Start-up Guide Grid RESTful API APPLICABILITY & EFFECTIVITY Effective for all systems manufactured after August 2021. Document Revision: 2.A T18663 Grid RESTful API Start-up Guide MSAsafety.com...
  • Page 2 MSA Safety 1991 Tarob Court Milpitas, CA 95035 Website: www.MSAsafety.com U.S. Support Information: +1 408 964-4443 +1 800 727-4377 Email: smc-support@msasafety.com EMEA Support Information: +31 33 808 0590 Email: smc-support.emea@msasafety.com Grid RESTful API Start-up Guide...
  • Page 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...
  • Page 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...

  • Page 5: Table Of Contents

    Data Structure ........................43 Using CURL to Generate Grid RESTful API Requests ............44 How to Access the RESTful API Through Fiddler ..............45 Generic Information for Access to the Grid RESTful API ............48 3.4.1 Authenticate via GET Command .................... 48 3.4.2...

  • Page 6: Overview

    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)

  • Page 7: Grid Restful Api Supported Functions

    Grid RESTful API Supported Functions Grid RESTful API Supported Functions 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.

  • Page 8: Data Read/Write

    Grid RESTful API Supported Functions Example JSON Response: "message": "Logged in ok", "data": { "token": "eyJ0eXAiOiJKV1QiLCJhbGcoIoJIUzI1NiJ9.ImlkfDI1MGYxYWIwLWQzMjktNGQyNS1hMTE5LThlOTJhZDc0MzcyZXx0eXBlfH RpbWVzdGFtcHxpc0VuY3J5cHRlZHxvcmlnaW58MTAtMC0yOC0xODFfNTcwMDB8cG9saWN5fDB8dHRsfGluYWN0aXZpdHlf dGhyZXNob2xkfDF8cGVybWlzc2lvblNldEtleXwvT0VNK0FkbWluLy9fTUVTSF9HU1QvfGlzVG9rZW58dXNlcm5hbWV8ZWdnZ XJzamVuc0BnbWFpbC5jb21eMHxKNjZCOFBGR3wwfDBeXiQwfDF8MnxIfDN8SXw0fC0yfDV8Nnw3fCQ4fCQ5fEp8QXwtM11 8QnwkOXxLfEF8LTNdXXxDfER8RXwtMXxGfEddIg.ihjURRHILcXp-iTl4FvjjAma1sI1_CDINGyQuSNacDM" "error": null 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.

  • Page 9: All Field Device Types

    Grid RESTful API Supported Functions 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.

  • Page 10: Device Type: System View

    Grid RESTful API Supported Functions 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.
  • Page 11 Grid RESTful API Supported Functions "parameters": { "parameter1": "2", "node_id": "3", "parameter2": "2" "parameter1": "2", "parameter2": "1" "type": "Device2", "mapping": "Device2", "type": "Device2", "name": "Device_2_Profile_2", "mapping": "Device2", "path": "/profileView/devices/Device_2_Profile_2", "name": "Device_2_Profile_1", "events": { "path": "/profileView/devices/Device_2_Profile_1", "alarm": false, "events": { "trouble": false, "alarm": false,...
  • Page 12 Grid RESTful API Supported Functions "BAC_IP_Falcon_Steam_2_/BURN_CTL_ STATUS", "BAC_IP_Falcon_Steam_2_ /INLETWATERTEMPDEGF" Example JSON Response: (array of paths) "message": "Unknown field device: BAC_IP_Falcon_Steam_2_" "message": "Call successful", "data": { "lightninghide_EJ2PQsKJb": { "data": [ "error": { "message": "Unknown field device: "error": { BAC_IP_Falcon_Steam_2_" "message": "Unknown field device: BAC_IP_Falcon_Hydronic_1_"...
  • Page 13 Grid RESTful API Supported Functions "error": { "crackfisher_N1-": { "message": "Unknown field device: "error": { BAC_IP_Falcon_Hydronic_1_" "message": "timeout" "hurricanestone_NkvQCitk-": { "data": "BAC_IP_Falcon_Steam" "error": { "message": "timeout" "data": 1 "tulipgorilla_EyGpqsFkb": { "error": { "error": { "message": "timeout" "message": "Unknown property for device BAC_IP_Falcon_Steam_2_: INLETWATERTEMPDEGF"...
  • Page 14 Grid RESTful API Supported Functions "activeEvents": {}, "node": "Dev_2", "address": "1", "events": { "location": "R&D Lab Unit 1", "alarm": true, "status_class": "status_normal", "trouble": false, "status": "Normal", "warning": false "oldStatus": "Normal", "BOILERLEADLAGSETPOINTDEGC": 58.9 "activeEvents": {}, "address": "2", "status_class": "status_normal", "parameters": { "status": "Alarm",...
  • Page 15 "activeEvents": {}, "BURNER_ENABLE": 1 "address": "2", "status_class": "status_normal", "status": "Normal", "oldStatus": "Normal", "BURNER_ENABLE": 1 "error": null "gateway_2": { Example 2 – POST URL: /rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC Example 2 – JSON POST: (deviceID specified) "parameters": { "deviceID": "gateway_1" Grid RESTful API Start-up Guide...
  • Page 16 "gateway_1": { "name": "BAC_IP_Falcon_Hydronic_1_", "data": [ "status": "Normal", "BOILERLEADLAGSETPOINTDEGC": 58.9 "type": "BAC_IP_Falcon_Hydronic", "name": "BAC_IP_Falcon_Hydronic_1_", "status": "Normal", "type": "BAC_IP_Falcon_Steam", "BOILERLEADLAGSETPOINTDEGC": 58.9 "name": "BAC_IP_Falcon_Steam_2_", "status": "Alarm", "BURNER_ENABLE": 1 "type": "BAC_IP_Falcon_Steam", "name": "BAC_IP_Falcon_Steam_2_", "status": "Normal", "BURNER_ENABLE": 1 "error": null Grid RESTful API Start-up Guide...
  • Page 17 "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 Grid RESTful API Start-up Guide...
  • Page 18 "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 Grid RESTful API Start-up Guide...
  • Page 19 - the path of the value to set; this must be done at the leaf level “deviceName/propertyName” value - 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 Grid RESTful API Start-up Guide...

  • Page 20: Device Type: Bacnet Explorer Ng

    - 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 Grid RESTful API Start-up Guide...
  • Page 21 (optional) - priority to set from 1 to 16 Example Body Parameters: "parameters": { "deviceID": "bigelf_rkr", "path": "200/analog-value:0/present-value", "value": { "value": 24, "type": "REAL" "options": { "asn1": true, "priority": 16 Example JSON Response: "message": "Call successful", "data": null, "error": null Grid RESTful API Start-up Guide...

  • Page 22: Device Type: Bacnet Iot Gateway

    (optional) – an optional object containing: dataFilter – a MongoDB-style sift query object (see ); result https://www.npmjs.com/package/sift objects relating to downstream field devices are only included in the response if they match this filter Grid RESTful API Start-up Guide...
  • Page 23 "deviceInstance": 1, "deviceName": "WeatherLink_1", "pollInterval": 5, "offline": false, "objects": { "analog-input:1": { "objectType": "analog-input", "objectInstance": 1, "objectName": "INSIDE_TEMPERATURE", "deviceInstance": 2, "properties": { "deviceName": "WeatherLink_2", "present-value": { "pollInterval": 5, "propertyIdentifier": "present-value", "offline": false, "value": { "objects": { Grid RESTful API Start-up Guide...
  • Page 24 "value": { "data": [ "value": 42.39999771118164, "type": "REAL" "deviceInstance": 1, "deviceName": "WeatherLink_1", "lastRead": 1513689232174, "pollInterval": 5, "log": { "offline": false, "enabled": false, "objects": { "keys": [] "analog-input:1": { "objectType": "analog-input", "objectInstance": 1, "objectName": "INSIDE_TEMPERATURE", "properties": { Grid RESTful API Start-up Guide...
  • Page 25 "properties": { "present-value": { "error": null "propertyIdentifier": "present-value", "value": { "value": 87.9000015258789, Example 3 – URL: (HTTP POST with "deviceID" parameter specified in body) /rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC Example 3 – JSON body: "parameters": { "deviceID": "gateway_1", "deviceAPIVersion": "2" Grid RESTful API Start-up Guide...
  • Page 26 "value": { "log": { "value": 39.5, "enabled": true, "type": "REAL" "keys": [ "2/analog-input:2/present-value" "lastRead": 1513689232174, "log": { "enabled": true, "keys": [ "1/analog-input:2/present-value" "error": null Example 4 – URL: (HTTP POST with "path" parameter specified) /rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC Grid RESTful API Start-up Guide...
  • Page 27 Example 5 – URL: (HTTP POST with "dataFilter" parameter specified) /rest/method/fieldpop-api/getDeviceData?happn_token=eyJ0eXAiOiJKV1QiLC Example 5 – JSON body: "parameters": { "deviceID": "gateway_1", "deviceAPIVersion": "2", "path": [ "deviceName", "offline", "objects/analog-input:1/objectName", "objects/analog-input:1/properties/present-value/value", "objects/analog-input:1/properties/present-value/lastRead" "options": { "dataFilter": { "deviceInstance": { "$eq": 1 Grid RESTful API Start-up Guide...
  • Page 28 "enabled": true, "objectName": "INSIDE_TEMPERATURE", "keys": [ "properties": { "1/analog-input:2/present-value" "present-value": { "propertyIdentifier": "present-value", "value": { "value": 41.5, "type": "REAL" "lastRead": 1513693293092, "log": { "enabled": false, "deviceInstance": 2, "keys": [] "deviceName": "WeatherLink_2", "pollInterval": 5, "offline": false, Grid RESTful API Start-up Guide...
  • Page 29 "propertyIdentifier": "present-value", "log": { "value": { "enabled": true, "value": 88.5999984741211, "keys": [ "type": "REAL" "2/analog-input:2/present-value" "lastRead": 1513693293192, "log": { "enabled": false, "keys": [] "analog-input:2": { "objectType": "analog-input", "error": null "objectInstance": 2, "objectName": "OUTSIDE_TEMPERATURE", "properties": { Grid RESTful API Start-up Guide...
  • Page 30 – the BACnet device instance. Example – URL: (HTTP POST) /rest/method/fieldpop-api/callDeviceMethod?happn_token=eyJ0eXAiOiJKV1QiLC Example – JSON body: "parameters": { "deviceID": "gateway_1", "methodName": "getBACnetDeviceInfo", "deviceInstance": 200 Example – JSON Response: "message": "Call successful", "data": { "DNET": 59915, "MAC": "c0a86409bac0" "error": null Grid RESTful API Start-up Guide...
  • Page 31 Example – URL: (HTTP POST) /rest/method/fieldpop-api/callDeviceMethod?happn_token=eyJ0eXAiOiJKV1QiLC Example – JSON body: "parameters": { "deviceID": "gateway_1", "deviceAPIVersion": "2", "methodName": "getBACnetDeviceInfo", "deviceInstance": 200 Example – JSON Response: "message": "Call successful", "data": { "DNET": 59915, "DADR": "c0a86409bac0" "error": null Grid RESTful API Start-up Guide...
  • Page 32 Example – JSON body: "parameters": { "deviceID": "gateway_1", "deviceAPIVersion": "2", "methodName": "getBACnetPropertyValue", "deviceInstance": 200, "objectType": "analog-value", "objectInstance": 0, "propertyIdentifier": "present-value" Example – JSON Response: "message": "Call successful", "data": { "value": 27, "type": "REAL" "error": null Grid RESTful API Start-up Guide...
  • Page 33 "parameters": { "deviceID": "gateway_1", "deviceAPIVersion": "2", "methodName": "setBACnetPropertyValue", "deviceInstance": 200, "objectType": "analog-value", "objectInstance": 0, "propertyIdentifier": "present-value", "propertyValue": { "type": "REAL", "value": 444 "priority": 16 Example – JSON Response: "message": "Call successful", "data": null, "error": null Grid RESTful API Start-up Guide...

  • Page 34: User Methods

    "state": "Normal", "data": [ "installationInfo": { "address": { "company": "SMC", "streetAddress": "201 W Passaic St", "description": "ProtoAir monitoring US and SA weather", "suburb": "Rochelle Park", "deviceId": "flickerpalm_N1ytNF-y7", "city": "Roodepoort", "location": "-26.13226, 27.90566000000001", "state": "Gauteng", "macAddress": "00:50:4E:60:00:16", Grid RESTful API Start-up Guide...
  • Page 35 Example 2 – GET URL: (list parameter set) /rest/method/fieldpop-api/getUserDevices?happn_token=eyJ0eXAiOiJKV1QiLC&list=true Example 2 – JSON Response: "message": "Call successful", "data": [ "flickerpalm_N1ytNF-y7", "cybersparrow_NkWMIrKbyQ" "error": null Example 3 – POST URL: (list and filter specified) /rest/method/fieldpop-api/getUserDevices?happn_token=eyJ0eXAiOiJKV1QiLC Grid RESTful API Start-up Guide...
  • Page 36 "state": "Normal", "packageInfo": { "cpu": "armv7", "productName": "BACnet IoT Gateway", "platform": "ProtoAir_ARMv7", "customerName": "Sierra Monitor Corporation", "platform-revision": 1 "productVersion": "5.0.0", "deviceAPIVersion": [ "deviceOnline": true "2.0.0" "moduleVersions": { "error": null "ae": { "name": "@smc/bacnet-explorer", "version": "6.0.0" Grid RESTful API Start-up Guide...

  • Page 37: Listdeviceusers

    Query String Parameters: • happn_token - Token obtained from login request. • deviceID - the IIoT gateway ID (see Section 3.1.1) Example GET URL: /rest/method/fieldpop-api/getUserInfo?happn_token=eyJ0eXAiOiJKV1QiLC&deviceID=cybersparrow_NkWMIrKb Example JSON Response: "message": "Call successful", "data": [ "admin@gmail.com", "user@company.com" "error": null Grid RESTful API Start-up Guide...

  • Page 38: Protocast Methods

    URL: /rest/method/fieldpop-api/createOemUser Query String Parameters: • happn_token - Token obtained from login request. Contact MSA Safety support for credentials with access this method. • email - the email address of the user for which an account should be created. •...

  • Page 39: Getdevicedata

    "message": "Call successful", "data": [ "ProtoCast": { "type": "ProtoCast", "name": "Socomec", "path": "/Fieldcast/devices/Socomec", "status": "Normal", "status_class": "status_normal", "events": { "alarm": false, "warning": false, "trouble": false "points_count": 2, "Volts (V)": 123.9, "Current (mA)": 120 "error": null Grid RESTful API Start-up Guide...

  • Page 40: Getdevicedatawithtime

    "type": "ProtoCast", "name": "Socomec", "path": "/Fieldcast/devices/Socomec", "status": "Normal", "status_class": "status_normal", "events": { "alarm": false, "warning": false, "trouble": false "points_count": 2, "Volts (V)": { "value": 123.55, "time": 1550187148 "Current (mA)": { "value": 130, "time": 1550187305 "error": null Grid RESTful API Start-up Guide...

  • Page 41: Firmware Methods

    /rest/method/fieldpop-api/getDeviceFirmwareVersions?happn_token=eyJ0eXAiOiJKV1QiLC Example 3 – JSON Payload: "parameters": { "deviceID": "cybersparrow_NkWMIrKbyQ" Example 3 – JSON Response: "5.4.2" "message": "Call successful", "data": { "SMC": { "SMC ProtoCast": { "error": null "model": "SMC ProtoCast", "versions": [ "5.4.0", "5.4.1", Grid RESTful API Start-up Guide...

  • Page 42: Upgradefirmware

    - the semantic versioning (or semver) of firmware to load on the IIoT Gateway Example 3 – POST URL: /rest/method/fieldpop-api/upgradeFirmware?happn_token=eyJ0eXAiOiJKV1QiLC Example 3 – JSON Payload: "parameters": { "deviceID": "cybersparrow_NkWMIrKbyQ", "firmwareVersion": "5.4.2" Example 3 – JSON Response: "message": "Call successful", "data": null, "error": null Grid RESTful API Start-up Guide...

  • Page 43: Additional Information

    The RESTful API will provide access to all data retained on the Grid. The duration for which data is retained on the Grid is an operation decision outside the scope of this document. 3.1.4 Data Structure All data will be returned in a self-describing JSON format. Grid RESTful API Start-up Guide...

  • Page 44: Using Curl To Generate Grid Restful Api Requests

    Troubleshooting Using CURL to Generate Grid RESTful API Requests When using CURL to generate REST API requests, the URL must be in quotes when specifying URL parameters. Here are some examples: deviceDataLog curl -v -L 'https://www.fieldpop.io/rest/method/fieldpop-api/deviceDataLog?deviceID=enter-device-id- here&happn_token=enter-token-here' getDeviceData curl -v -L -H "Content-Type: application/json" -X POST -d '{"parameters": {"deviceID": "enter-device-id- here","path": "1001/analog-input:1/present-value","options": {"asn1": true}}}'...

  • Page 45: How To Access The Restful Api Through Fiddler

    5. Set the HTTP verb to GET from the dropdown menu and enter the following HTTPS address: https://www.fieldpop.io/rest/login?username=<username>&password=<password> NOTE: For the italisized portions of the address above (“<username>” and “<password>”), the authenticated username and password must be added. No brackets should be included (“<” or “>”). Grid RESTful API Start-up Guide...
  • Page 46 11. Select the JSON box below to see the JSON data response from the RESTful API. 12. Record the data.token value. NOTE: The token is the authentication token needed to get the device data logs. Grid RESTful API Start-up Guide...
  • Page 47 20. Select JSON to see the response in JSON format. 21. Copy the token. 22. Compose the URL again to get the device data logs (https://www.fieldpop.io/rest/method/fieldpop- api/deviceDataLog). 23. Pass the copied token as a query parameter (deviceID=deviceID&happn_token=authtoken&startUTCsec=1477388259&endUTCsec=1500000 000). Grid RESTful API Start-up Guide...

  • Page 48: Generic Information For Access To The Grid Restful Api

    Troubleshooting Generic Information for Access to the Grid RESTful API NOTE: In the tables that follow, italicized characters indicate placeholder text that must be filled in by the user with the correct information. 3.4.1 Authenticate via GET Command Method https://www.fieldpop.io/rest/login?username=username&password=password...

  • Page 49: Troubleshooting

    • Click “Forgot Password” on the MSA Grid Login Screen. • Once the Password Reset Window appears, enter the email address of the MSA Grid account and click Submit. Then close the window that appears. • Click on the “Reset Your Password” button in the email sent from notification@fieldpop.io to reset the MSA Grid password.

  • Page 50: Useful Features

    (port 80 and 443). To connect to a ProtoNode via MSA Grid, a device tunnel is created that has a unique subdomain in the URL. Therefore, the best way to configure a firewall rule is to use a wildcard domain: *.tunnel.fieldpop.io...

  • Page 51: Viewing The Certificate

    Open a web browser on the local PC and go to www.smccloud.net. • Move the cursor to the padlock icon ( ) next to the website address. • Click the padlock icon to open a dropdown menu for website information and browser settings. Grid RESTful API Start-up Guide...
  • Page 52 Troubleshooting • Review the information and click the Certificate button. • Examine the certificate as needed. NOTE: To download the certificate, click the Details tab and click the ‘Copy to File’ button. Grid RESTful API Start-up Guide...

  • Page 53: Warranty

    MSA Safety warrants its products to be free from defects in workmanship or material under normal use and service for two years after date of shipment. MSA Safety will repair or replace any equipment found to be defective during the warranty period. Final determination of the nature and responsibility for defective or damaged equipment will be made by MSA Safety personnel.

Table of Contents