ENGAGE - JSON Data Structures

Proprietary and Confidential, © 2019 Allegion™

Introduction

JSON Data Structures

The communication protocol that is used to transfer data directly between the ENGAGE family of devices and the database host device is based on the JSON file format. The database host can be any device that connects to an ENGAGE device through a WiFi or Bluetooth Low Energy (BLE) connection.

This section defines all possible JSON tags that are used to configure an ENGAGE device, however tags are not applicable to all system configurations or devices. Tags which are utilized only in either the ENGAGE Gateway or ENGAGE API may be defined only in the ENGAGE – SAM API Integration documents.

Within the data structure tables, there are parent tags which do not include any data elements. Parent tags are implemented because they allow for the re-use of common tag names within a different parent tag context. An example of a common tag name is the tag “days”. This tag is common to the credential schedule and auto unlock parent tags. Another example is within the user records data structure. The “add”, “update” and “delete” parent tags share parameters that are specific elements with an individual user record. Parent tags within the tables are shown in Bold Text to differentiate from Child records.

For information regarding the JSON standard, the web site www.json.org contains many helpful links. The JSON specification can also be found at this link: http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf.

Device Messages

There are four (4) main categories for JSON data structures that are sent to and from a host system (access control panel or SW system) and the security device located at the entryway (lock or other device). These categories are:

1. Database
2. Configuration
3. Audit Trail
4. Asynchronous Events / Alerts

Data transfers between a host and device will occur within a “session”. The session contains data that is formatted to the JSON specification. The JSON “files” are sent over BLE or WiFi to an embedded device that has limited RAM. As a result, the JSON data files are written to the lock’s flash memory and parsed after the data transfer has completed.

NOTE: ENGAGE Edge devices support only standard English language ASCII characters less than 0x7F.

Database Overview

During a connected event when a device is either requesting a database update from the host directly over WiFi or when the database is being updated via BLE, the device can receive a database update. The database received by the device can contain user records, credential schedules, holidays, and auto unlock data sent by the host.

The database consists of several different sub-components. The sub-components are user records, holidays, user schedules and auto unlock events. The parent tag of the database is expressed with the JSON “db” tag.

From these sub-components, only individual user records can be modified during a database update. This is accomplished through the “deleteAll, “delete”, “update” and “add” tags.

If the holidays, user schedules or auto unlock records need to be added or updated, the records should be sent as a whole. For these records, no individual records can be deleted or updated. When the holidays or auto unlock records need to be completely erased from the lock, the tag is sent with an empty “[ ]” collection. (i.e. “holidays”: [ ] or “autoUnlock”: [ ])

When a database update occurs for devices with user credential capabilities, at least one credential schedule must always be sent with the default schedule of access 24 hrs x 7 days / week. An empty collection for credential schedules is not possible. If the host fails to send the default 24x7 credential schedule, even valid credentials will not gain access.

Configurations can also be included with the database but they use a separate JSON parent tag structure.

Database Request Records

The “nxtDbVerTS” tag is used to keep the host synchronized with the ENGAGE device. This timestamp is inserted into the URL by the ENGAGE device on each database request. When the ENGAGE device requests a database for the very first time, it does so with respect to a value of “0” for the “nxtDbVerTS” tag. The host responds by sending an initial database, and it includes an updated value for the “nxtDbVerTS” tag. When the lock makes the next database request, it includes the updated nxtDbVerTS in the URL. This process continues until a device reset occurs.

If the ENGAGE device is a networked offline device, the host must include in the database records the specific time that the device will request the next database. This is accomplished through the “dbDwnLdTm” database download time. See Table 1.

Table 1: Database Download Records

User Records

User records come to the device through a “new” or an “updated” database. This ability is controlled through the “deleteAll” tag. When the “deleteAll” tag value is set to “1”, the device gets a new user database. When this value is set to “0”, the device gets an update to the existing user database.

There are instances when a completely new database is sent to the device. This happens under two conditions. When the:

• ENGAGE device is programmed for the very first time.

• Host device determines that the differences between the device’s existing database and the new database are too numerous.

When the host sends user records to the device, the records are grouped in terms of user records that will be deleted, updated, or added to the device. The order in which these records are sent from the host must be in that same order: delete, update and add. All four of the tags (deleteAll, delete, update, add) must be included inside the db tag, even if there is no applicable user record changes to the respective tag. When user records need to be updated within the ENGAGE device, it is logical that the device has knowledge of which records need to be deleted before updating and adding new user records.

For the purposes of updating a user record, the entire user record is sent from the host. The record includes data that needs to be updated along with data that does not need to be updated.

When an individual user record needs to be deleted, only the primary credential ID and primary credential type is sent as the identifier for that record.

A user record describes the parameters associated with each user of the access control device. A complete user record is delimited with several different JSON tags. The individual tags within a User Record are described in Table 2.

The order defined in the usrRcrd tag defines the searching order for the lock. As user records are modified, these are appended to the devices database.

The credential records must be encrypted as specified in the Schlage ENGAGE Sort & Encryption document.

Table 2: User Record

Credential Schedule Records

Credential Schedule Records are used to describe a set of times when an individual credential can be granted access. These times are described by a specific day of the week and time, not by a specific calendar date. These records are stored in the device and are applied to individual user records through the “Credential Schedule” tag within individual user records.

Table 3 describes each of the fields associated with a credential schedule.

Devices with Credential Readers

In order for a credential to have access to a device, at least one credential schedule must be programmed into the device. If an existing credential schedule needs to be deleted from the lock, then the host must send at least one credential schedule that allows access 24 hrs / day, 7 days a week.

The credential schedules must be explicitly defined for every database structure provided to the lock, even if previously defined.

Table 3: Credential Schedule Record

Holiday Records

Holiday records are events that describe when a device should be put into a special state based upon a certain calendar date and time, overriding an auto-unlock schedule. A secured holiday puts the device into the normally secured state. A passage holiday puts the device into a normal passage state. The restricted secured holiday puts the device into a secured state, but the device only accepts 2 card types in this state, pass-through and freeze.

When in a restricted secured state if a freeze credential is presented, the device transitions from restricted secured to a normal secured state – allowing the expanded credential types to be allowed at the door. To restore the device to the restricted secured state, a freeze credential must be presented two more times; (the first takes the device to frozen secured state, the second triggers a schedule look-up causing the device to resume restricted secured state). The pass-through credential functions as expected, momentarily unlocking the door.

In the event that the existing holiday record needs to be deleted from the device, and not replaced with a new set of holidays, then an ID empty tag of “[]” is sent from the host.

Holiday records must be explicitly defined for every database structure provided to the device, even if previously defined.

Table 4 describes each of the fields associated with a holiday record.

Table 4: Holiday Record Fields

Auto Unlock Records

Auto unlock records are device specific events that describe when the device should be put into secure or passage mode based upon a specific day of the week and time. An auto-unlock record only describes when the device should change its current state. In order to put the device back to its original state, an additional auto unlock record is required. For many doors, a good “rule of thumb” is to have an auto-lock schedule, scheduled for midnight. This way if someone toggles a device unlocked during the day, the door will relock itself at midnight.

In the event that the existing auto unlock record needs to be deleted from the device, and not replaced with a new set of auto unlockevents, then an ID empty tag of “[ ]” is sent from the host.

Auto unlock must be explicitly defined for every database structure provided to the device, even if previously defined.

Table 5 describes each of the fields associated with an auto unlock record.

Table 5: Auto Unlock Record Fields

Device Parameters

This section describes the data structures for modifying and retrieving device parameters.

Modifiable Parameters

Some device parameters can be changed by a host device. When modifying (configuring) parameters, a host sends a JSON data structure to the device that contains a set of configuration parameters. Table 6 shows a complete list of the JSON data tags and tag values that can be modified by a host. Some of the parameters are device specific and may not apply to all devices.

Modifiable (configurable) parameters vary by each device’s capability or the specific configuration of the device.

To support a standard of JSON configurations moving into the future, the standard has been established to use “T” / “F” for configuration tags/items (to enable or disable a feature). However, because some of the currently established tags do not use this standard, the previously implemented tag types maintain their current implementation and the standard will be established for new tags implemented in the future.

See the Example of Configuration Records (JSON) section below for an example of this data structure.

Table 6 shows a listing of Modifiable (Configurable) Parameters.

Table 6: Modifiable (Configurable) Parameters

Retrievable Parameters

When a host makes a request to the device for information that resides in the device, it receives all of the retrievable parameters for that device at that time.

Device Profile

Later firmware versions of ENGAGE devices include a section that defines the type and any special type variances (called extensions) supported by the device as part of a dvcProfile block contained at the beginning of the config block.

To support a standard of JSON configs moving into the future, the standard is for all device profiles to be implemented as integers. However, because some of the currently established tags do not use this standard, the previously implemented tag types maintain their current implementation and the standard will be established for new tags implemented in the future.

Table 7: Currently Established Non-Integer Tags

Extensions and their supported custom arguments.

External Device Parameters

Table 8 shows a complete list of all the JSON data tags and values that can be read by an external device. Some of the retrievable parameters are device specific and may not apply to all devices.

ENGAGE devices report all retrievable parameters in one large block, and include some parameters that may not directly apply to the device or its mode of operation. For example; RSI protocol capable devices might report RSI parameters when the device is not configured for RSI protocol operation.

See the Device Settings section for an example of this data structure.

Table 8: Retrievable Parameters

NOTE: For ENGAGE 6.1 and later devices, devices configured for IP or stand-alone communication may not transmit their RSI parameters (rsiPrmtrs) or any children tags under the RSI parameters as they are not relevant to IP or stand-alone operation. The device accepts any changes to the RSI parameters if they are provided to the device, however the device does not provide the updated information back to the host.

Audit Trail Reporting

To minimize the amount of data transfer time, the device only sends audits that have never been successfully transferred to the host. Appended to the end of an audit trail transmission is the device’s current value for the “nxtDbVerTS”. Appending this time stamp to the end of the audit trail block also ensures that the device and host are synchronized. If the JSON configuration tag “lockId” is changed, this tag will also be appended to the end of the audit trail transmission.

Table 11 describes an audit trail record JSON data structure.

Table 11: Audit Trail Record

Asynchronous Events/Alerts Reporting

Asynchronous Events/Alerts are actions that occur at the device and must be reported back to the host device. These events are the same event codes that are used for audit trail entries. For networked devices, asynchronous events are sent individually at the time the actual event occurs. See Table 12.

Table 12: Asynchronous Event Record

The asynchronous events that are reported in real time are listed below.

NOTE: Real time reporting of these alerts can be suppressed using the wifiAlertEn config tag. This tag must proceed the wifiAlertSel tag populated with an empty array. Additionally, the dpsEn config tag can be used to stop the reporting of the Forced Door and Magnetic Tamper alerts and audits, as well stopping the Propped Door audit from reporting.

210 or 410

• Forced Door Alert - unexpected door position movement detected

• Tamper Alert - lock tampering detected

• Low Battery - battery voltage <= 4.5V (N, LE) ; 4.6V (SC); 5.0V (RMRU)

• Critical Battery - battery voltage <= 4V (N, LE) ; 4.3V (SC); 4.8V (RMRU)

• Magnetic Tamper Alert - door position sensor tampering detected

• Corrupt database - user access database corruption detected

• Reader Tamper Alert - reader tampering detected (CTE)

WiFi Device Commissioning

If the device is to be configured with WiFi communication directly to the host, the device requires several different parameters that are associated with the ability to login to a host system. See Table 13.

This data is sent from the mobile application during the commissioning process.

Table 13: WiFi Commissioning Record

*Only NDE supports “kyIndx” = 1 till 4 (if configured through host). Usage of a Key Index other than 1 is NOT recommended. For LE, RMRU, MT20W, CTE and ENGAGE Mobile Application “kyIndx” = 1.

Keyed-Hashing for Message Authentication (HMAC)

Keyed-Hashing for Message Authentication (HMAC) Authentication, by an IP Host, BLE enabled mobile application, or ENGAGE™ device, requires JSON structures that allows the use of a securing method for JSON General Parameter communications and methods to allow reception device targeting and contextual time relevance.

General Parameters JSON Object

To isolate the general parameters of a device, the general parameters JSON object is required and this object and all of its content are required when JSON Message Authentication is enabled for the site. See Table 14.

Table 14: General Parameters JSON Object

Hash Message Authentication Code (HMAC) Data JSON Object

To isolate the HMAC data parameters of a device the HMAC data JSON object was created. Each tag within the HMAC Data JSON Object is required in messages that have the HMAC-based JSON Message Authentication enabled for a site. See Table 15.

Table 15: Hash Message Authentication Code (HMAC) Data JSON Object

Examples of User Records (JSON)

deleteAll Tag Set

The following JSON data structure excerpt represents how the user record data structure might look if a user list was being sent for the very first time or when the current user list needs to be erased and populated with a new user list. Note the value of “deleteAll” is set to 1, which signifies that the database should replace the existing database.

{
 "db": {
    "usrRcrd": {
    "deleteAll": 1,
    "delete": [],
    "update": [],
    "add": [
     {
      "usrID": "64",
      "adaEn": 0,
      "actDtTm": "20140101000000",
      "expDtTm": "20200101000000",
      "fnctn": "norm",
      "crSch": [1, 3],
      "primeCr": "01020304050607080910111213141516",
      "prCrTyp": "card"
     },
     {
      "usrID": "146",
      "adaEn": 1,
      "actDtTm": "20100101000000",
      "expDtTm": "20200101000000",
      "fnctn": "norm",
      "crSch": [1, 3],
      "primeCr": "16151413121110090807060504030201",
      "prCrTyp": "card"
    }]
}

deleteAll Tag Cleared

The following JSON data structure excerpt represents how the user record data structure might look if an updated user list was being sent to the device. This list might contain a set of users to delete, update and add.

NOTE: The value of “deleteAll” is set to 0, which signifies that the existing database in the device should be updated.

{
 "db": {
   "usrRcrd": {
   "deleteAll": 0,
   "delete": [
    {
     "primeCr": "02030405060708091011121314151617",
     "prCrTyp": "card"
    },
    {
     "primeCr": "17161514131211100908070605040302",
     "prCrTyp": "card"
    },
    {
     "primeCr": "03040506070809101112131415161718",
     "prCrTyp": "card"
    }
  ],
  "update": [
    {
     "usrID": "149",
     "adaEn": 1,
     "actDtTm": "20100101000000",
     "expDtTm": "20200101000000",
     "fnctn": "toggle",
     "crSch": [1],
     "primeCr": "16151413121110090807060504030201",
     "prCrTyp": "card"
    }
  ],
   "add": [
    {
     "usrID": "148",
     "adaEn": 0,
     "actDtTm": "20100101000000",
     "expDtTm": "20200101000000",
     "fnctn": "norm",
     "crSch": [1],
     "primeCr": "01020304050607080910111213141516",
     "prCrTyp": "card"
    }
   ]
  },

deleteAll Tag Cleared, No User Records to Update

The following JSON data structure excerpt represents how the user record data structure might look if an updated database is sent that contains no updates to the user records. Note the delete, update and add records are empty ( [] ), which signifies that there are no records to delete, add, or update.

{
 "db": {
  "usrRcrd": {
   "deleteAll": 0,
   "delete": [],
   "update": [],
   "add": []
 },

Example of Holiday Records (JSON)

The following JSON data structure represents how the data structure might look if the holiday records were being sent to the device.

{
  “db”:{
    "holidays": [
    {
     "strtDtTm": "20141223000000",
     "endDtTm": "20141227000000",
     "action": "pass"
    },
    {
     "strtDtTm": "20140703000000",
     "endDtTm": "20140705000000",
     "action": "rstrctSec"
    }
  ],
 }
}

Example of Credential Schedule Records (JSON)

The following JSON data structure represents how the data structure might look if the credential schedule records were being sent to the device.

{
  “db”: {
   "schedules": [
   {
    "days": ["Su","Mo","Tu","We","Th",”Fr","Sa"],
    "strtHr": 0,
    "strtMn": 0,
    "lngth": 1439
   },
   {
    "days": ["Mo","Tu","We","Th","Fr"],
    "strtHr": 8,
    "strtMn": 0,
    "lngth": 540
   },
   {
    "days": ["Mo","We","Fr"],
    "strtHr": 8,
    "strtMn": 0,
    "lngth": 240
   }
  ],
 }
}

Example of Auto Unlock Records (JSON)

The following JSON data structure represents how the data structure might look if the auto event records were being sent to the device.

{
  “db”: {
   "autoUnlock": [
    {
     "action": "pass",
     "strtHr": 8,
     "strtMn": 0,
     "days": ["Mo","Tu","We", "Th","Fr" ]
    },
    {
     "action": "sec",
     "strtHr": 17,
     "strtMn": 0,
     "days": ["Mo","Tu","We","Th","Fr" ]
    }
   ]
 }
}

Example of Configuration Records (JSON)

The following JSON data structure represents how the data structure might look if the configuration records were being sent to the device.

 {
 "config":{
   "battFail":"sec",
   "proxConfGE4001":"T",
   "rtcTime":"20140424152753",
   "iClsUID40b":"T",
   "bprEn":"T",
   "proxConfHID":"T",
   "uid15693":"T",
   "name":"sw555",
   "mi14443":"T",
   "uid14443":"F",
   "proxConfGECASI":"T",
   "dstStart":"12b0",
   "ada":"30",
   "proxConfAWID":"T",
   "proxConfGE4002":"F",
   "doorProp":"20",
   "relock":"3",
   "noc14443":"T",
   "dstEnd":"2230",
   "firstManIn":"false",
   "dstEnable":"false",
   "fwUrl":""
   },
"apCfgNew":
   {
    "apCfgNewEn":"T",
    "ssidNew":"02.04.12",
    "psswdNew":" G10N\@113",
    "usrNmNew":"Cr649",
    "wifiSecNew":"entrprs",
    "apCfgNewStrtTm":"20140527141029"
   },
   "rsiConfigs":{
   "rsiHrtbtTm":1234,
   "rsiRtryTm":4,"rsiSubqtDly":13,
   "rsiFrstDly":14,"autoPrg":"T",
   "rsiCommFailSfMd":"disbld",
   "relockMethod":"tmr"
   }
  }

Partial User Database Update

Putting all the records together, the following might represent the JSON data structure for a sample database that could be sent to update an existing device database.

{
 "db": {
  "usrRcrd": {
   "deleteAll": 0,
   "delete": [],
   "update": [],
   "add": [
   {
    "usrID": "64",
    "adaEn": 0,
    "actDtTm": "20140101000000",
    "expDtTm": "20200101000000",
    "fnctn": "norm",
    "crSch": [1,3],
    "primeCr": "01020304050607080910111213141516",
    "prCrTyp": "card"
   },
   {
    "usrID": "146",
    "adaEn": 1,
    "actDtTm": "20100101000000",
    "expDtTm": "20200101000000",
    "fnctn": "norm",
    "crSch": [1,3],
    "primeCr": "16151413121110090807060504030201",
    "prCrTyp": "card"
   },
   {
    "usrID": "149",
    "adaEn": 1,
    "actDtTm": "20100101000000",
    "expDtTm": "20200101000000",
    "fnctn": "toggle",
    "crSch": [1],
    "primeCr": "02030405060708091011121314151617",
    "prCrTyp": "card"
   },
   {
    "usrID": "148",
    "adaEn": 0,
    "actDtTm": "20100101000000",
    "expDtTm": "20200101000000",
    "fnctn": "norm",
    "crSch": [1],
    "primeCr": "14161514131211100908070605040302",
    "prCrTyp": "card"
   }
  ]
 },
  "schedules": [
   {
    "days": [ "Su", "Mo","Tu","We","Th","Fr","Sa"],
    "strtHr": 0,
    "strtMn": 0,
    "lngth": 1439
   },
   {
    "days": [
    "Mo",
    "Tu",
    "We",
    "Th",
    "Fr"
   ],
    "strtHr": 8,
    "strtMn": 0,
    "lngth": 540
   },
   {
    "days": [
    "Mo",
    "We",
    "Fr"
   ],
    "strtHr": 8,
    "strtMn": 0,
    "lngth": 240
   }
  ],
  "holidays": [
   {
    "strtDtTm": "20141223000000",
    "endDtTm": "20141227000000",
    "action": "pass"
   },
   {
    "strtDtTm": "20140703000000",
    "endDtTm": "20140705000000",
    "action": "rstrctSec"
   }
  ],
  "autoUnlock": [
   {
    "action": "pass",
    "strtHr": 8,
    "strtMn": 0,
    "days": ["Mo","Tu","We","Th","Fr"]
   },
   {
    "action": "sec",
    "strtHr": 8,
    "strtMn": 0,
    "days": ["Mo","Tu","We","Th","Fr"]
   }
  ]
 },
 "config": {
  "relock": 3,
  "doorProp": 20,
  "ada": 30,
  "firstManIn": 0,
  "dstEnable": 0,
  "dstStart": "3022",
  "dstEnd": "B012",
  "battFail": "asIs",
  "bprEn": "T",
  "rtcTime": "20140701170122"
 },
 "dbDwnLdTm": "20140702210122",
 "nxtDbVerTS": "0x08d16386bfaec212"
}

Delete Holiday Records

There may be instances when holiday records need to be deleted from the device. The host must be able to provide a JSON data structure that permits this operation.

The following JSON structure represents how holiday records would be erased from the device during a database update.

{
 “db”:{
  "holidays": [],
 }
}

Delete Auto Unlock Event Records

There may be instances when auto unlock records need to be deleted from the device. The host must be able to provide a JSON data structure that permits this operation.

The following JSON structure represents how auto unlock records would be erased from the device during a database update.

{
 “db”:{
  "autoUnlock": []
 }
}

WiFi Commissioning

The following structure represents a JSON data structure that contains WiFi commissioning data.

{
  "wifiCmsh":
   {
     "hstCnfg":
     {
       "ipDNS":"orcaintegration.cloudapp.net",
       "altDNS":"orcabackup.cloudapp.net",
       "scrCnn":"https",
       "dscvryTyp":"ipAddr"
     },
     "apCnfg":
     {
       "ssid":"test",
       "psswd":"password123",
       "usrNm":"default",
       "wifiSec":"prsnl"
     }
   }
}

Audit Trail

The following structure represents a JSON data structure for an audit trail block that contains 3 audits. Note that this data structure does not contain a parent tag. This is because audit trails are being requested by the host, therefore the data type is not needed.

{“audits”:[
       {
         "event":"1122334455",
         "time":20131113091752
       },
       {
         "event":"008A0000",
         "time":20131113092022
       },
       {
         "event":"00860000",
         "time":20131113092513
       }
],
“nxtDbVerTS”:”0x0873828198485981”}

Asynchronous Events

The following structure represents a JSON data structure that contains an asynchronous event.

{
   “asyncEvent":
   {
       "event":"00830000",
       "time":20131113091752
   }
}

Device Settings

This section gives an example of how the data is structured by the device when a request is made for the device parameters. These parameters are broken down into 5 different components so that redundant tags can be used.

Example Data Structure

When a mobile device connects to a device, the device reports a set of parameters to the mobile device. This is an example of the data structure that would be returned by the device.

{
   "dvcProfile":
   {
           "baseType":"nde",
           "key":"NewAPCfg",
           "value":"1"
   },
   "battV":
   {
           "main":"5.87",
           "li":"2.99"
   },
   "fwVer":
   {
           "main":"01.03.11",
           "credRdr":"01.02.10",
           "ble":"01.02.10",
           "wifi":"01.05.10",
           "mainBl":"00.01.03",
           "credRdrBl":"00.01.01"
   },
   "wifiStngs":
   {
           "ssid":"01.03.11",
           "psswd":"\@113G10N",
           "usrNm":"Br549",
           "wifiSec":"entrprs",
           "encrypt":"wep",
           "kyIndx":4,
           "dscvryTyp":"ipAddr",
           "scrCnn": "http",
           "ip":"196.23.43.113",
           "dns":"firstChoice",
           "altDNS":"secondChoice"
   },
   "apCfgNew":
   {
           "apCfgNewEn":"T",
           "ssidNew":"02.04.12",
           "psswdNew":" G10N\@113",
           "usrNmNew":"Cr649",
           "wifiSecNew":"entrprs",
           "apCfgNewStrtTm":"20140527160629"
   },
   "lckPrmtrs":
   {
           "nm":"corner office",
           "mdl": "nde",
           "lckSn":"1122334455",
           "mnSn":"2233445566",
           "mfgDt":"20140607",
           "daysInUse":145,
           "hwVer":"c1",
           "type":"strm",
           "relock":1,
           "doorProp":20,
           "ada":30,
           "firstManIn":0,
           "dstEnable":0,
           "dstStart": "3022",
           "dstEnd": "B012",
           "battFail": "sec",
           "rtcTime": "20140527140629",
           "dbDwnldTm":"20140528020000"
   },
   "rdrPrmtrs":
   {
           "bprEn": "T",
           "sn":"4455667788",
           "mfgDt":"20140607",
           "daysInUse":145,
           "hwVer":"c1"
   }
}

Gateway JSON Data Structures and IP API

The following section defines JSON structures that are used in communication with the ENGAGE Gateway.

None of the following JSON structures should be used to directly communicate with an ENGAGE device.

Edge Device JSON Data Structures

Gateway Edge Device Link List

The Gateway link list is an array object which contains an array entry for each of the Gateway linked devices.

Table 17: Gateway Edge Device Link List

Example: Linked Device Data

{
 "linkList": [
   {
     "linkId": "dev00000",
     "linkCommStatus": "connected",
     "deviceName": "Front Door",
     "modelType": "nde",
     "deviceId": "a000000000000123",
     "macAddr": "00:07:80:78:2F:88",
     "macType": "public",
     "battV": {
      "main": " 5.52",
      "li": "0"
     }
    }
  ]
}

Linking Edge Devices

When linking an Edge Device to a specific Gateway, the Gateway responds with the parent tag linkInfo as defined in Table 18.

Table 18: Linking Edge Devices

Example: JSON body response from POST /edgeDevices

{
 "linkInfo": {
   "linkId": "dev00000",
   "deviceId": "a000000000000123",
   "deviceName": "Front Door",
   "linkCommStatus": "connected",
   "modelType": "nde"
  }
}

Linked Edge Device Data

To configure and control an online edge device that is linked to an ENGAGE Gateway, the host may need to know the current device parameters. This data structure builds on device parameters that are provided in the Device JSON Messages Section, and the real-time access control structures that follow in the Gateway JSON Data Structures Section. To configure and control an online edge device that is linked to an ENGAGE Gateway, the Gateway provides the following edge device information:

Table 19: Linked Edge Device Data

NOTE: For ENGAGE 6.1 and later devices, devices configured for IP or stand-alone communication may not transmit their RSI parameters (rsiPrmtrs) or any children tags under the RSI parameters as they are not relevant to IP or stand-alone operation. The device will accept any changes to the RSI parameters if they are provided to the device, however the device will not provide the updated information back to the host.

Device Control

These device JSON structures are only accessible via the Gateway. These data structures cannot be written directly to a device.

NOTE: lockLEDFlash and lockState are independent. The client issuing the command can send only lockState, only lockLEDFlash or both. If the lock state and lock are combined the lock will first flash default.

Table 20: Device Control

Device Status

The Device Status JSON structures are used only to represent a device status from a Gateway to an IP host. This JSON cannot be queried directly from a device.

Individual device status varies based on the device model type. The JSON structures shown in Table 21 are a master list of possible status tags, but are dependent on the hardware of the device.

Table 21: Device Status JSON Tags

Gateway JSON Data Structures

Gateway Scan List

The scan list object contains a report detailing ENGAGE devices that are within BLE wireless distance of the Gateway.

Table 22: Gateway Scan List

Gateway Configuration

Table 23: Gateway Configuration

Edge Device Firmware Update via Gateway

Gateway firmware version 01.49.12 and later supports updating linked edge devices’ firmware for sites which are running 410-IP mode with the edgeDeviceFwUrls JSON tag as defined above in Section 4.2.2. All linked edge devices matching the Device Model Type tag will be updated to the requested firmware. Please note that if the specified Firmware Version (fwVer) does not match the actual version downloaded from the Firmware Address (fwurl), the edge device will not be updated.

Status of the firmware update can be monitored through the resource GET /gateway/deviceInfo. The children tags, edgeDeviceFwUrls, status, and extendedStatus contain all relevant information regarding the firmware update.

Gateway firmware versions 1.52.16 and later support firmware download of a secure connection. In this case the host must provide the fwurl specified with “https://” and the required port (ex. “https://10.200.136.198:444/gw_image.bin”) If no port is specified in the request, it is assumed that the user intends to use port 443.

When completing a firmware download from the host over HTTPS the gateway will utilize the port specified (or 443) and complete the download via TLS, however the gateway will not download or validate the certificate from the host.

The example below illustrates initiating a firmware update for all linked NDE edge devices to take effect immediately.

Example: application/json

{
   "gatewayConfig": {
     "edgeDeviceFwUrls": [
     {
     "fwurl": "http://192.168.43.24/nde_02.08.13_Releasepkg.02.08.13.bin",
     "mdl": "nde",
     "fwDwnldTm": "0",
     "fwImplTm": "0",
     "fwVer": "02.08.13"
     }
     ]
   }
}

Device Information Records (Gateway)

ENGAGE devices report all retrievable parameters in one large block and includes some parameters that may not directly apply to the device or its mode of operation. For example; RSI protocol capable devices might report RSI parameters when the device is not configured for RSI protocol operation.

Table 24: Device Information Records (Gateway)

Gateway IP Host Authentication Setup

Used between a Gateway and IP host during initialization of the Gateway using default logins. This object is returned to the IP Host during a GET from /gateway/newCredentials.

Table 25: Gateway IP Host Authentication

Site Survey Results

Gateway reports the results of a site survey once the site survey is completed.

Table 26: Site Survey Results

Appendix A: Credential Tag Name Definitions

“norm” (Normal)

A normal credential opens a door for a specified time. The time span is defined by the relock delay. The normal function works on all devices.

“freeze” (Freeze)

A freeze credential disables the credential reader. After a freeze credential has been used on a lock, only a pass through credential will operate the lock. Present a freeze credential to return the lock to an operational state.

“toggle” (Toggle)

A toggle credential opens a door and leaves it open until it is closed again by a toggle credential. It toggles a door between locked and unlocked.

“passThru” (Pass Through)

A pass through credential will always unlock a lock that is in secured lockout mode, regardless of how the lock was put in secured lockout mode.

“lockDown” (Lock Down)

A lockdown credential will always put the lock into the secured mode plus freeze credential functionality.

“oneTm” (One Time Use)

A onetime use credential opens a door only once with the normal function. Once a onetime use credential has been used on a door, it will no longer work on that door. It can still work on other doors, to which is has been assigned.

“dogd” (Dogged)

Toggle credential functionality for a crash bar exit device.

“suprv” (Supervised)

Supervised credentials allow access only when a second supervised credential is presented.

“delAlrm” (Delete with Alarm)

A delete with audit/alarm credential will log an audit entry that the credential was used. However, the credential will NOT unlock the door. If an alarm is available on the lock, then the alarm will sound. This functionality is the same as the “blocked” credential type.

“ctAux” (Ct Auxiliary)

A CT Aux credential operates the auxiliary relay of a CT Controller, but not the main relay. The time span the relay is activated is specified by the relock delay.

“ctMnAux” (Ct Main and Aux)

A CT Main and Aux credential operates both the auxiliary relay and main relay of a CT controller. The time span the relays are activated as specified by the relock delay.

“ctAuxToggle” (Ct Auxiliary Toggle)

A CT Auxiliary Toggle credential changes the state of the auxiliary relay from locked to unlocked, or vice versa, unless in a Freeze state.

“ctMnAuxToggle” (Ct Main + Aux Toggle)

A CT Main + Aux Toggle credential changes the state of both the main and auxiliary relays from locked to unlocked, or vice versa, unless in a Freeze state.

“ctMnAuxPassThru” (Ct Main + Aux Pass Through)

A CT Main + Aux pass through credential unlocks both the main and auxiliary relays regardless of state, for the time of the relock delay.

“updtFrmSvr”(Update from server)

Update from server credential will trigger the update from server in SF210 mode irrespective of lock state. In Sf200 mode this credential will be treated as invalid credential.

“updtFrmSvrNrm” (Update from server+Normal)

Update from server+Normal credential will behave as normal credential and then trigger the update from server in SF210 mode irrespective of lock state.

In SF200 mode this credential will be treated as normal credential only.

“runDiag” (run internal diagnostics and report audits)

The run diagnostics credential will trigger the built-in self-test routines of the device and initiate an update from server in order to report the results in SF210 mode irrespective of lock state.

In 410IP mode, resultant audits will be sent immediately to the Gateway.

In SF200 and 410RSI mode this credential will be treated as invalid.

“calDPS” (calibrate door position sensor)

The calibrate DPS credential will establish a new closed “home” position for the device. This calibration performs the same functionality as executed during commissioning for home position.

“blocked” (Blocked)

The functionality of the blocked credential type is identical to the “delAlrm” credential type as defined above.

Credential Tags Supported by Device

Table 28: Credential Tags Supported by Device

Appendix B: Device Specific Characteristics

Table 29: Device Specific Characteristics