Allegion Developer Portal
Allegion Developer Portal
The Gateway WebSocket feature, which is also called “Gateway as IP Client” or “IP Client Mode”, introduces the ability to reverse the host / client relationship that existed with Gateway firmware versions prior to 01.49.12. Prior to this feature’s implementation the Gateway would act as an HTTP server providing RESTful API resources to the ENGAGE Alliance Partners’ host which acted as an HTTP client. This is illustrated in Figure 1.
Figure 1: Gateway as HTTP Server
With the implementation of the Gateway WebSockets feature, the Gateway can now be configured to act as a WebSocket client to initiate a secure IP connection with a remote IP Host acting as a WebSocket server. This allows ENGAGE Alliance Partners to provide a remote WebSocket server at a publicly addressable IP address, permitting the Gateway to initiate a connection with the IP Host. This is illustrated below in Figure 2.
Figure 2: Gateway as WebSocket Client
In a typical ENGAGE installation, IP mode gateways are hosted on a private LAN, with the gateway configured manually or automatically with a non-routable IP address. Additionally, the facility may provide indirect internet connectivity to the gateway via a router providing NAT/firewall and/or port forwarding features. As such, the gateway as IP server architecture results in several IP connectivity limitations:
IP Host clients must reside on the same subnet as the Gateway (or)
Routing and/or router port forwarding rules must be created so that off-subnet IP Hosts can reach the Gateway (or)
A VPN connection must be established between the remote IP Host and the Gateway LAN
Concerning the second point, IP routing is required when the IP Host and gateway are located on separate subnets. However, in many cases the ENGAGE installer will not have physical access to or permissions needed to create new routing rules in the router(s) that link the IP Host to the gateway LAN. Taken together, these limitations resulted in a desire to reverse the roles and to support a Gateway-as-IP client mode.
While the WebSocket protocol implementation in the Gateway overcomes many of the obstacles which may be present in traditional access control installations, it additionally allows for several auxiliary benefits. Due to the asynchronous, full-duplex nature of the WebSocket connections, Gateways which are configured to operate in this mode also support the ability to send additional events to the server as they occur in real-time (See the ENGAGE Event Subscription Message Format and ENGAGE Event Message Format Sections). These events are configurable and independent from the existing RESTful API resources which remain unchanged. Additionally, the existing RESTful API can be used within the WebSocket protocol with only a few changes to the format of the HTTP requests (See the ENGAGE Request Message Format and ENGAGE Response Message Format Sections) therefore allowing the Allegion Alliance Partners to implement the WebSocket protocol and Allegion WebSocket sub-protocol into their host servers in a favorably timely manner.