Allegion Developer Portal
Allegion Developer Portal
Sites must be created through the API for the site key to be known by the SAM and ENGAGE. Creating a new site with the mobile application will not allow for a SAM to control the devices directly. Only ENGAGE managed and RSI sites can be created through the mobile app. SAM Managed 200, 210, and 410IP sites must be created via API.
WiFi Call-in:
For the standard periodic WiFi call-in, devices perform three RESTful calls in the following order:
PUT /swordfish/lock/Config
NOTE: – supported by NDE firmware version 2.6 and newer
GET /swordfish/lock/db/{timestamp}
POST /swordfish/lock/audit
See the ENGAGE Edge Device Services APIs section for more details on these calls and more specific information regarding HTTP and REST.
For ENGAGE 6.0 and later Firmware, only firmware updates and installations are prevented during a low battery condition. PUT Config, GET db, POST audit, POST alert, and GET certificates are all allowed during low battery conditions.
HTTP 1.1.
Currently required by the device firmware, the device completes the PUT to Config with HTTP 1.0, however it does not complete the GET db or the POST audit.
“Content-Length:”
Content length must be sent as a case sensitive string in the HTTP header in order for the ENGAGE edge device to properly process the GET /db.
HTTP Response
The HTTP response to POST /swordfish/lock/audit must be a 201 or 202 to indicate successful reception of the audit payload. 201 should be used when the device first calls in to report its audits and the audit file is created on the SAM host system. 202 should be used for subsequent updates from the device when the host audit file is updated. A 200 response should only be used when the response contains a payload of information. The response to POST /swordfish/lock/audit should not contain any payload information and therefore should not be a 200.
ENGAGE Edge devices (NDE, LE, RMRU, etc)
ENGAGE Edge devices which provide WiFi functionality do not natively support static IP addressing. If a software alliance member wishes to force a static IP address assignment on a per edge device basis, this may be accomplished via MAC reservations on the host router configurations. The edge devices connect to the WiFi access point and request an IP address via DHCP negotiation.
Firewall Exceptions:
Devices make use of standard HTTP (port 80) / HTTPS (port 443) for outgoing calls to the host. As such, most networks capable of internet access routing should operate without the need for router configuration changes.
The ENGAGE Gateway acts a web server providing secured incoming communication on port 443. Intra-LAN devices connecting to the Gateway may need internal routing tables configured. Remote (internet) hosts connecting to the Gateway will need firewall exceptions [port forwarding] to successfully complete connectivity.
Firewall Exceptions can be removed when the Gateway is configured to act as a WebSocket client, this will require that the IP Host provide a WebSocket Server.
NDE Max Transmission Rate:
The NDE has a max supported transmission rate of 24Mbps. As such, routers that allow for min 2.4 GHz rate configurations need to ensure that no value above 24Mbps is set as required/mandatory or the NDE will not be able to connect to the access point.
Zeroconf:
Zeroconf enables dynamic configuration of IPv4 link-local address without DHCP or static IP assignment (RFC-3927) as well as device and service advertisement for discovery (RFC-6762 and RFC-6763).
The ENGAGE Gateway supports Zeroconf networking, advertising its HTTPS service as ‘ENGAGEGateway v1.0’. This service can be used to locate Gateways and their associated IP addresses.
Note the ENGAGE Gateway will always obtain a link-local address (169.254.x.x) at power-on. This means that the Gateway is capable of responding to two distinct IP addresses should DHCP or static IP address assignment be made as well.
WebSockets:
Gateway firmware versions 01.49.12 and later have implemented the capability to act as an IP websocket client communicating with an IP host (set up by Allegion ENGAGE Alliance Partners) which supports the WebSocket Protocol version 13 as standardized by the IETF as RFC 6455.
This feature allows Gateways which reside on a different subnet from the host, or would traditionally require port forwarding, to bypass the network firewall in order to initiate full-duplex communication with an IP host which is located at a publically addressable IP address.
Communication is performed over TCP port 443 using standard TLS security.
The IP host must contain a unique X.509 root certificate and private key used to authenticate itself to gateway clients during TLS session establishment and provide HTTP services with for a limited number of URLs for use by the Gateway.
The Gateway will download and validate the server’s X.509 certificate using the root certificate authority’s HMAC-SHA1 which uses the Site Key for encryption.
Upon the completion of commissioning a Gateway for websocket communication, the Gateway will authenticate itself to the IP host prior to establishing a connection. At a minimum the Gateway will re-authenticate itself every 24 hours.
The Gateway will drop the connection if it has existed for more than 24 hours and will reestablish connection automatically any time a connection is dropped or does not exist.
The IP host must create a unique, temporary Basic Authentication password (per Gateway) used by the Gateway to establish a secure websocket connection, and must decline all websocket connection requests (HTTP Upgrade requests) by HTTP clients not having the correct Basic credentials.
The ENGAGE WebSocket Sub protocol is an application level protocol layered over the base websocket protocol that defines the structure and contents of a frame’s Application Data payload. Sub protocol negotiation occurs during connection establishment using the Sec-WebSocket-Protocol request header field.
Request messages emulate the request content conveyed by HTTP in the RESTful API utilized by non websocket enabled Gateways.
Magnetic Door Position Sensor (NDE Only):
The DPS is only monitored once every 3 seconds to maximize battery life.
For security reasons the device will annunciate a magnetic tamper audit if the DPS sensor loses its calibration due to a strong magnetic field being present.
As there is a considerable amount of metal inside of the device, holding the REX lever is considered by the device as opening the door, even if the door remains closed. This is due to the change in the relative magnetic field around the device when the chassis moves due to the movement of the lever.
Battery Levels:
As the device is used and the battery is drained, the device may annunciate a low or critical battery audit. Please refer to the JSON Data Structures section for specific battery level information.
Battery life estimates assume one (1) WiFi update per day operation and take into account the droop that is inherent to the chemistry of alkaline batteries in order to prevent brownout in the worst-case conditions.
While devices maintain an active connection to the Gateway when operating in real-time modes, battery consumption is kept to a minimum by the depowering of select, unused portions of the device. These portions are re-energized when commands are received that require processing. As such, the often common practice of an access control panel periodically resending device commands should be avoided; excessive drain on the battery will occur if redundant commands or configurations are transmitted continuously to a device.
Cap Sense (Credential Card Presentation Detection):
Baseline upon power up and every minute thereafter to adjust for changing conditions. If something is placed in front of the device for a period of time it will “blind” the device.
NDE Firmware versions 02.09.08 and later and LE Firmware versions 01.04.83 and later support an adjustable “Cap Sense” feature to allow for improved reader detection. Please change this setting to “High” or “Max” with the iOS or Android Mobile Application.
Tamper:
To prevent corruption of data if batteries are pulled during a “write” operation, when the tamper is active, much of the device functions are disabled. It will trigger a WiFi Alert Event, but the device will cease operation for a few minutes until the time-out clears the tamper flag and allows the device to resume normal operations.
On Board LED (May not be applicable for all devices)
The LED on the back on the mainboard (visible when removing the battery cover on NDE) is used to communicate that the tamper is active.
Switch Status messages over RSI protocol (ENGAGE Gateway)
The NDE might send all status messages at once, whereas AD could send them in sequence.