Architecture
The NETx BMS Platform provides the opportunity to integrate event information from VingCard online door locks. The following figure shows how the integration has to be done.
VingCard door locks are using a wireless communication protocol which is based on ZigBee. In order to retrieve information like door events, ZigBee/IP gateways are required. These gateways are provided by VingCard and have the aim to translate ZigBee packets into IP packets for the local area network (LAN). Depending on the project multiple ZigBee gateways are needed.
The events are centrally collected by the VisiOnline server software. VisiOnline provides an interface for sending events via push notifications to third-party software. In detail, the VisiOnline acts as a TCP client that sends TCP packets to our NETx BMS Core Server which in turn acts as TCP server. The communication protocol itself is based on a binary TCP/IP protocol.
Configuration of VisiOnline
First, the VisiOnline software has to be configured. The interface for event notification is provided by a process called "TLCom.exe". The configuration of the TLCom process is done with a tool called "TLXMLEdit" which is located within the installation directory of VisiOnline. Open the WIndows Explorer, navigate to the installation directory of VisiOnline and start the tool.
Within the tool, different settings can be configured within a tree structure. For TLCom, navigate to the top level key "TLCom" and then select the key "Settings". If they are not existing, create the top level "TLCom" and the sub key "Settings" be using the menu "Edit". Afterwards, the following attributes have to defined using the menu "Edit":
- ExternalAddress: here the IP address of the NETx BMS Core Server has to be entered.
- ExternalPort: here the TCP port that shall be used for the communication has to be specified. You can choose any port that is not used within the NETx BMS Server (e.g. 4000). Please note that the same port must be used within the driver configuration within the NETx BMS Core Server (see blow).
- ForwardPMSTraffic: must be set to 1
- Logging_External: must be set to 1
- MonitorSocket: must be set to 1
The following screenshot shows an overview of all settings:
Afterwards, you have restart the TLCom process. This can be done by restarting the PC where VisiOnline is running. As alternative you can simply terminate the TLCom.exe process within the Windows task manager – VIsiOnline will restart the TLCom process automatically.
Please note that NETxAutomation is not responsible for TLCom and VisiOnline since it is within the responsability of VingCard/Assa Abloy. If you need support regarding TLCom and VisiOnline, please contact the technical team of VingCard/Assa Abloy.
Configuration of NETx BMS Core Server
After having finished the configuration of VisiOnline, open the BMS Core Studio. First, configure the communication port that is used by VisiOnline to send event messages. This can be done by selecting "Driver Configuration" within the menu "Modules" -> "VingCard".
SC
Then, the used rooms have to be defined. This is done within the "Device definitions" within the menu "Modules" -> "VingCard". Each definition line corresponds to one room.
| Field | Description |
|---|---|
| Room number | The room number must be unique and must correspond to the room number used within VisiOnline |
| Path | Define an optional structure within the item tree |
| Description | Provide additional information which is stored within the item property |
SC
After having defined all devices, the NETx BMS Core Server has to be restarted. Afterwards, the configured devices are shown within the item tree under the sub tree "NETx\XIO\VingCard".
The retrieved information from VisiOnline is stored as Server Items. Each retrieved information is stored as one server item. Regardless which information is present within the event message, the following items are always shown within the NETx BMS Core Server:
- EventNumber
- RegistrationNumber: RegistrationNumber is the card’s registration number. It is only included for staff and guest entrance. It is zero for all other events.
- MainGuestRoom (optional): MainGuestRoom is the main room the guest card has been issued for. Only used for guest entrance.
- SuiteRooms (optional): SuiteRooms indicates which adjacent rooms the guest card can access
- UserGroup (optional): UserGroup is the usergroup of the card. Only used for guest and staff entrance
MainGuestRoom, SuiteRooms, and UserGroup is only set if the VingCard system is providing this information. This depends on the configuration and used door locks. If not available, the Server Items remain UNCERTAIN.
The most important information is the "EventNumber" which indicate the event type. The following table gives an overview of all events:
| EventNumber | Event Name |
|---|---|
0 | Guest entrance |
| 1 | Staff Entrance |
| 2 | Inside open |
| 3 | Deadbolt thrown |
| 4 | Deadbolt released |
| 5 | Door closed |
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. changing the cooling mode). For VingCard door events, a special XLogic command called "VingCardEvent" is already included within the NETx BMS Core Server. Based on the event number, different server items with different values can be set. To use this command, open the "XCommand Event Definitions" within the "Extension" menu of the BMS Core Studio. For each door event that you would like to forward, create a new definition. Give it a name (first column) and select "Input" as type. As XCommand choose "Vingcardevent". Within the configuration dialog, select the Server Item for the corresponding VingCard event. For each event type, one Server Item can be specified. In addition, a value can be specified too. The following screenshot shows an example. If there is a guest entrance, the value "True" is written to the KNX group address 3/0/1. If there is a staff entrance, "15" is written to 3/0/2. All other events are ignored.
