Salto1: How to integrate Salto door locks

Architecture

It is possible to integrate event information from Salto online door locks. The following figure shows how the integration has to be done.

Salto 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 Salto and have the aim to translate ZigBee packet 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 Salto server software. This software package provides an interface called Salto Event Stream. This interface provides the opportunity to send events via push notification to third-party software. This means that the Salto software (TCP client) which sends TCP/IP packets to our NETx Server (TCP server). The Salto Event Stream interface provides two event message formats - CSV or JSON based. The NETx Server uses the JSON based variant.

Installation

The driver is implement as a plugin for the NETx Server. Therefore, it has to be installed via the Extension Manager. To do so, stop the server and open the Extension Manager from "Extensions" tab. Select the "Salto" interface and press install as shown in the following screenshot:

After having installed the interface, restart the NETx Server.

Integration steps

First, the Salto Event Stream has to be configured. Open the Salto Software "RW Pro-Access For Service" and create a new Event Stream within the menu "Tools". In the second step of the wizard, give the event stream a name, select TCP/IP, enter the IP where the NETx Server is running, select a communication port (e.g. 6001), select "JSON" as event message format and "ANSI" as encoding. The following screenshot shows an example.

In the next step, select the information that shall be retrieved by the NETx Server. If you want to retrieve all available information, select all fields. In the next step, the users, doors, operation, and the time can be limited. After having created a new event stream, the Salto service has to be restarted.

As next, open the studio. First, configure the communication port. This can be done by selecting "Driver Configuration" within the menu "Modules" -> "Salto".

Then, the used doors have to be created. This is done within the "Door definitions" within the menu "Modules" -> "Salto". Each definition line corresponds to one door. Either the column "Door name" or "Door ExtID" must be present. These fields must exactly contain the same name which are used within the Salto system since they are used to assign a retrieved event to the corresponding door. 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 2.0 only) and "Synchronize" have the same functionality as for all other interfaces within the NETx Server. 

FieldDescription
Door name*Must exactly contain the same name which are used within the Salto system
Door ExtID*Must exactly contain the same name which are used within the Salto system
PathDefine an optional structure within the item tree
Description Provide additional information which is stored within the item property


After having defined all doors, the server has to be restarted. Afterwards, the configured doors are shown within the item tree under the sub tree "NETx\XIO\SALTO".

item_tree.png

The retrieved information from Salto is stored as Server Items. Each retrieved field is stored as one server item. Regardless which fields are selected within the Salto Event Stream information, all fields are always shown within the NETx Server. However, only 5 Server Items are counted to the license for each defined door. All other items are not counted to the license and are thus for free.

The most important information is the "Operation ID" which indicates the event type. This ID 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 "Operation IDs" and their meaning:

Operation ID

Description

Operation ID

Description

8

New renovation code for key (online).
16Door opened: inside handle.
17Door opened: key.
18Door opened: key and keyboard.
19Door opened: multiple guest key.
20Door opened: unique opening.
21Door opened: switch.
22Door opened: mechanical key.
25Door opened: PPD.
26Door opened: keyboard.
27Door opened: spare card (hotel).
28Door opened: online command.
29Door most probably opened: key and PIN.
33Door closed: key.
34Door closed: key and keyboard.
35Door closed: keyboard.
36Door closed: switch.
37Key inserted (energy saving device).
38Key removed (energy saving device).
39Room prepared (energy saving device).
40Start of privacy.
41End of privacy.
49Start of office mode.
50End of office mode.
51Hotel guest cancelled.
54Door programmed with spare key.
55New hotel guest key.
56Start of forced opening (online).
57End of forced opening (online).
58Start of forced closing (online).
59End of forced closing (online).
60Alarm: intrusion (online).
61Alarm: tamper (online)
62Door left opened (DLO).
63End of DLO (door left opened).
64End of intrusion.
65Start of office mode (online).
66End of office mode (online).
67End of tamper.
68Automatic change.
69Key updated in "out of site" mode (online).
70Expiration automatically extended (offline).
72Online peripheral updated.
76Key updated (online).
78Key deleted (online).

79

Door has lost communication with the Salto software.
80Door has re-established communication with the Salto software.
81Opening not allowed: key no activated.
82Opening not allowed: key expired.
83Opening not allowed: key out of date.
84Opening not allowed: key not allowed in this door.
85Opening not allowed: out of time.
87Opening not allowed: key does not override privacy.
88Opening not allowed: old hotel guest key.
89Opening not allowed: hotel guest key cancelled.
90Opening not allowed: antipassback.
92Opening not allowed: no associated authorization.
93Opening not allowed: invalid PIN.
95Opening not allowed: door in emergency state.
96Opening not allowed: key cancelled.
97Opening not allowed: unique opening key already used.
98Opening not allowed: key with old renovation number.
99Warning: key has not been completely updated (online).
100Opening not allowed: run out of battery.
101Opening not allowed: unable to audit on the key.
102Opening not allowed: locker occupancy timeout.
103Opening not allowed: denied by host.
104Blacklisted key deleted.
107Opening not allowed: key with data manipulated.
111Closing not allowed: door in emergency state.
112New renovation code.
113PPD connection.
114Time modified (daylight saving time).
115Low battery level.
116Incorrect clock value.
117RF Lock date and time updated.
118RF Lock updated.
1000The Salto software has re-established communication with the door.
1001The Salto software has lost communication with the door.
2000Guest new key
2001Guest copy key

Article applies to the following products:

  • NETx BMS Platform
  • NETx Multi Protocol Server
  • NETx BMS Server 2.0