Tutorial: Integrating Kaba door locks
- Nahel Falhout (Unlicensed)
- Wolfgang Granzer
Architecture
Our server provides the opportunity to integrate event information from Kaba online door locks. The following figure shows how the integration has to be done.
Kaba door locks are using a wireless communication protocol which is based on ZigBee. In order to retrieve information like door events, ZigBee/IP hubs are required. These hubs are provided by Kaba and have the aim to translate ZigBee packets into IP packets for the local area network (LAN). Depending on the project multiple ZigBee hubs are needed.
Kaba door locks are using a wireless communication protocol which is based on ZigBee. In order to retrieve information like door events, ZigBee/IP hubs are required. These hubs are provided by Kaba and have the aim to translate ZigBee packets into IP packets for the local area network (LAN). Depending on the project multiple ZigBee hubs are needed.
The events are centrally collected by the Kaba server software. This software package provides an interface called Messenger LENS web service interface. This interface provides the opportunity to send events via push notifications to third-party software. In detail, the Kaba software acts as a web service client that sends web service requests to our server which in turn acts as web service server. The communication protocol itself is based on SOAP web services.
Installation
driver is implement as a plugin for the NETx BMS Core Server. Therefore, it has to be installed via the Extension Manager. To do so, stop the NETx Server, Extension Manager in "Extensions" tab. Select the "Kaba" interface and press install as shown in the following screenshot:
After having installed the interface, restart the server.
Integration steps
First, the Messenger LENS web service interface has to be configured. Open a web browser and open the login screen of the Messenger LENS web interface. Within the http URL, use the IP address of the PC where the Kaba software is running.
Afterwards, select the "Configuration" tab, select "Group Permissions" and add a new group permission. Within the wizard, go through step 1 - 3 and select the events and locks that you want to receive within the NETx Server. Within step 4, select "Allow User's Web Service" and enter the following URL (replace <IP NETx Server> with the IP address of the PC where the NETx Server is running and choose a free port (e.g. 6005):
http://<IP BMS Server>:<Port>/
The following screenshot shows an example.
Finish the configuration by going through the remaining steps 5 - 7.
Afterwards, change to the tab "Operations", select "Subscription" and add a new subscription. Select the events, the user and the locks. Within the last step (step 4) of the wizard, "Notify me on my Web server" should be selected and the web service URL should be shown.
As next, open the studio. First, configure the communication port that you have enter within the web service URL. This can be done by selecting "Driver Configuration" within the menu "Modules" -> "Kaba".
Then, the used devices have to be created. This is done within the "Device definitions" within the menu "Modules" -> "Kaba". Each definition line corresponds to one device. The first column defines the device name. The device name must be unique and is shown within the item tree the NETx Server. The next column "Device ID" is optional. "Device Name" and "Device ID" are used to assign a web service notification to the corresponding item within the item tree. This means that either "Device Name" or "Device ID" must be the same as the Kaba software uses within the web service request. The 3rd column "Path" is used to define an optional structure within the item tree. "Description" is used to provide additional information which is stored within the item property "Description". The remaining field "Persistent", "Historical" (NETx BMS Server 2.0 only) and "Synchronize" have the same functionality as for all other interfaces within the NETx Server.
| Filed | Description |
|---|---|
| Device Name | Must be the same as the Kaba software uses within the web service request |
| Device ID | Must be the same as the Kaba software uses within the web service request |
| Path | Define an optional structure within the item tree |
| Description | Provide additional information which is stored within the item property |
The following figure shows an example where 1 door lock is defined. In addition, the ZigBee/IP called "Hub Floor1" is also defined in order to receive events dedicated to the ZigBee/IP hub.
After having defined all devices, the server has to be restarted. Afterwards, the configured devices are shown within the item tree under the sub tree "NETx\XIO\Kaba".
The retrieved information from Kaba is stored as Server Items. Each retrieved field from the web service request is stored as one server item. Regardless which fields are selected within the Messenger LENS interface, all fields are always shown within the server. However, only 5 Server Items are counted to the license for each defined device. All other items are not counted to the license and are thus for free.
The most important information is the "Event ID" and "Event Name" which indicate the event type. This information can be linked to an XLogic command or LUA task in order to trigger some actions like changing a data point (e.g. trigger a lighting scene). The following table gives an overview of all events:
Event ID | Event Name | Event Description |
|---|---|---|
| 3 | Door Ajar Generic | Device left open (unlocked) for more than 5 minutes |
| 4 | Door ajar clear or door secure | Device secured [before X number of minutes] |
| 7 | Key Error - Canceled key used | Canceled credential/key card used at the device |
| 8 | Key Error - Other | Device access denied for a credential/key card for a reason not otherwise specified |
| 10 | Low battery | Battery voltage level in the device is low |
| 17 | Generic Egress | Guest egress; the door is locked |
| 18 | Door Latched | "Lock door" command sent to the door (secure mode) |
| 22 | Wandering Intruder | Alert: possible wandering intruder; credential/key card presented at multiple doors |
| 23 | Standing Intruder | Alert: Possible standing intruder; multiple credentials/key cards are presented at a single door |
| 26 | Deadbolt / Privacy | Deadbolt (privacy feature) thrown |
| 31 | Key error - Wrong room | Credential/key card used at the wrong room |
| 34 | Date time Error | Device reports: Date and/or time not set; date-time error |
| 37 | Low Battery Clear or Battery Normal | Device reports: Low Battery Clear or Battery Normal |
| 38 | Door Ajar Staff Short | Staff Ajar "A" timer reached |
| 39 | Door Ajar Staff Long | Staff Ajar "B" timer reached |
40 | Door Ajar Guest Short | Guest Ajar "A" timer reached |
| 41 | Door Ajar Guest Long | Guest Ajar "B" timer reached |
| 42 | Deadbolt reset (retracted) | Deadbolt has been reset (retracted) |
| 44 | New Guest Key Used | New Guest Key Used |
| 45 | Guest Key Used | Guest-level credential/key card used |
| 46 | Staff Key Used | Staff-level or non-opening credential/key card used |
| 50 | Door Unlatched | "Door unlock" command sent to the door (Unlatched mode) |
| 52 | Date time OK | Device reports: Date time OK (after an error notification) |
| 53 | Transaction Failed | Messenger-initiated transaction failed (including errors or and timing out) |
| 54 | Lock status ONLINE | ZigBee lock back online (after having been offline) |
| 55 | Lock status OFFLINE | ZigBee lock offline (after having been online) |
| 66 | Key error - Expired | Expired credential/key card used at the device |
| 99 | Paging Keys | Paging key used |
| 8194 | Hub status ONLINE | Hub back online (after having been offline) |
| 8195 | Hub status OFFLINE | Hub offline (after having been online) |
| 100 | T/A Clock In | The employee {0} has clocked-in |
| 101 | T/A Absence | The employee {0} initiated an absence |
| 102 | T/A Clock Out | The employee {0} has clocked-out |
| 103 | T/A Pause | The employee {0} initiated a pause |
| 104 | SSA Guest - Check-In | The guest user has checked-in |
| 105 | SSA Guest - Check-Out | The guest user has checked-out |
| 106 | SSA Guest - Room Move | The guest user changed his/her room |
| 107 | SSA Guest - Extended Stay | The guest user has extended his/her stay |
| 108 | SSA Paging - Multi-Media | Problem detected on one or more media devices |
| 109 | SSA Paging - Electrical | Electrical problem detected |
| 110 | SSA Paging - Room Vacant | Part 1 of VCI state |
| 111 | SSA Paging - Room Service Pick-up | Request for room service pick-up |
| 112 | SSA Paging - Plumbing Service | Plumbing problem detected |
| 113 | SSA Paging - Room Cleaned | Part 2 of VCI state |
| 114 | SSA Paging - Laundry Service | Request for laundry service |
| 115 | SSA Paging - HVAC | Problem detected on heating/ventilation system |
| 116 | SSA Paging - Room Inspected | Part 3 of VCI state |
| 117 | SSA Paging - Generic Repair | Request for a generic repair |
| 507 | Digital Key error - Cancel | Canceled digital key used at the device |
| 508 | Digital Key error - Others | Device access denied for a digital key for a reason not otherwise specified |
| 510 | Digital Low battery | Digital key reports that the Battery voltage level in the device is low |
| 522 | Digital Key Wandering Intruder | Digital key used as a wandering intruder |
| 523 | Digital Key Standing Intruder | Digital key used as a standing intruder |
| 531 | Digital Key error - Wrong Room | Digital key accessing wrong room |
| 544 | Digital New Guest Key Used | Digital key used for New Guest |
| 545 | Digital Existing Guest Key Used | Digital key used for current Guest |
| 546 | Digital Staff Key Used | Digital key used for staff |
| 566 | Digital Key Error Expired | Digital key expired |
Article applies to the following products:
- NETx BMS Platform
- NETx Multi Protocol Server
- NETx BMS Server 2.0