VingCard1: Integrating VingCard door locks

Basic architecture

The NETx BMS Server 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 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 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 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.

Configuration of NETx BMS Server

After having finished the configuration of VisiOnline, open the BMS 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".

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. The first column defines the room number. The room numbermust be unique and must correspond to the room number used within VisiOnline. The 2nd 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" and "Synchronize" have the same functionality as for all other interfaces within the NETx BMS Server. The following figure shows an example;

After having defined all devices, the NETx BMS 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 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:

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 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 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.

Related articles