This article describes how to use SAFR to control a magnetic door lock or other door locking mechanism actuated by electrical signals.  This article is specific to directly controlling a door lock mechanism.  It does not cover unlocking doors via an access control system.   This article builds upon How to Trigger SAFR Actions which describes how to use SAFR Actions to trigger events. 


When possible, unlocking doors should be performed through an access control system. Most access control systems have capabilities that you can leverage such as managing users that need to be granted access, defining groups, associating those groups with resources that need to be accessed (i.e. doors), creating control groups, (i.e. door + camera + reader and related hardware) and interfacing with a wide range of hardware offerings. Although this functionality can be created within SAFR, it's a non-trivial task to do so and should only be attempted when other solution options are not available.


Solution Overview

The functionality described in this article includes:
  • Importing identities into SAFR
  • SAFR actions configuration needed to invoke a script
  • Web Relay Controller capable of accepting IP-based control commands and close an open circuit for the purpose of unlocking a door
  • Sample script capable of invoking an IP-based command to unlock a door
This document assumes that you are familiar with how SAFR performs recognition and triggers actions based on those recognitions.  See How to Trigger SAFR Actions for information on this.

Solution Architecture

Following shows the different components involved in providing secure access door unlocking.

The SAFR Platform includes SAFR Server and the Video Recognition Gateway(VIRGO) which processes video feeds from the cameras.  SAFR Actions (which can run on the same computer) will listen for recognition events.  When a face of a known person appears in any of the cameras, the person ID and camera ID are sent to SAFR Actions.  SAFR Actions then invokes a script which sends a command to the door lock that opens the relay and unlocks the door.

Solution Guide

Importing Identities into SAFR

To get started you will need to import identities into SAFR.  This means getting a face image of every person who will be authorized to gain access to your facility.  There are a few ways to accomplish this. The mechanics of each of these processes are already covered in more detail elsewhere in the user documentation and other solution guides, but here are brief descriptions of the processes:

  • Registration Kiosk - People stand in front of a tablet or phone and click the oval around their faces to add their names to the Identity Database. Often these devices are managed by a receptionist or a security guard to prevent unauthorized registration. The user can be prompted to enter their name and a number of additional fields of information when registering, if desired. A best practice is to manually review new registrants immediately after they register, and to add them to user groups so that they're granted access to the appropriate doors.
    • Registration kiosks can be implemented on mobile devices or on Windows of Mac computers with a webcam.
  • Image upload - Both the Desktop Client and the Web Console can be used to upload facial images to SAFR. This can be done one by one or in batches. The images will be imported and enrolled as new identities in the Identity Database. Imported identities can then be edited in the Person Window to add names, set their person types, and to add any desired metadata.
  • Upload Scripts - Images can be uploaded to SAFR through scripts using REST APIs. These APIs are available in cloud or on-premise deployments of SAFR Server. The REST APIs also support importing person metadata along with the facial images, so you can avoid any manual updating, should you so choose. Scripts can also be run to regularly keep SAFR in sync with external identity management systems. See Import Users via Script for more information.

SAFRActions.config Configuration

SAFR actions are used to connect an event (e.g. face recognition) to an action (e.g. close a relay on a door lock). Actions are defined in a SAFRActions.config file. Although you can manually edit this file yourself, the SAFR Actions component that's installed on Windows and Mac machines should instead be used to configure the file because it ensures the file is formatted correctly.


The following shows a sample SAFRActions.config file that invokes the unlock action for specific combinations of door, person type, and time of day.  Person types are assigned in the SAFR person records and allow you to group people to simplify the access control rules (i.e. who gets access to what).  You can also list specific individuals to be granted access. 


{
  "userId" : "",
  "userPwd" : ""
  "environment" : "PROD",
  "directory" : "main",
  "rules" : [
/* ============================================== */
/*  Rule 1 - Main Door hours for Regular Staff */
/* ============================================== */
    {
      "event" : {
        "source" : "Main Entrance",
        /* ================================================ */
        /*  Person types are defined in SAFR Person Records */
        /* ================================================ */
        "personType" : [
          "exec",
          "sales",
          "facilities",
          "guest"
        ]
      },
      "triggers" : [
        {
          "actions" : [
            ".\/scripts\/relay-x410.py 10.125.2.34 4"
          ],
          "daysOfWeek" : ["Mon", "Tue", "Wed", "Thu", "Fri"],
          "reply" : {
            "message" : "Welcome #N"
          },
          "timesOfDay" : [
            { "start" : "0700", "end" : "1700" }
          ]
        },
        /* ========================================================= */
        /*  This trigger performed if outside hours in above trigger */
        /* ========================================================= */
        {
          "reply" : {
            "message" : "Please swipe badge"
          }
        }
      ]
    },
/* ============================================== */
/*  Rule 2 - Main Door hours for Janitorial Staff */
/* ============================================== */
    {
      "event" : {
        "source" : "Main Entrance",
        "personType" : [
          "janitor"
        ]
      },
      "triggers" : [
        {
          "actions" : [
            ".\/scripts\/relay-x410.py 10.125.2.34 4"
          ],
          "daysOfWeek" : ["Mon", "Tue", "Wed", "Thu", "Fri"],
          "reply" : {
            "message" : "Welcome #N"
          },
          "timesOfDay" : [
            { "start" : "0530", "end" : "0630" },
            { "start" : "1800", "end" : "2000" }
            }
          ]
        },
        {
          "reply" : {
            "message" : "Please swipe badge"
          }
        }
      ]
    }
  ]
}

This SAFRActions.config defines 2 rules:

  • Rule 1: Open the main door for any regular staff during the hours of 7 AM to 6 PM.
  • Rule 2: Open the main door for janitorial staff during the hours 5:30-6:30 AM to 6-8 PM.

A single rule is needed for each combination of:

  • Door
  • Group
  • Time of day

You could also choose to include global rules such as granting regular staff access to all doors during certain hours.


As you can imagine, with many doors and many groups, the number of combinations can become complex.  This is just one reason why using an access control system is preferable for this use case.


Using SAFR actions to create your access rules and resource mapping is just one way to go about this. You could also choose to move this mapping into a data file or a database that is read and processed by your script.

Web Relay Controllers

A web relay controller enables the ability to  remotely close a low voltage circuit which in turn could trip high voltage circuits such as a magnetic door lock. An example of a web relay controller is the X-410 by ControlWeb <https://www.controlbyweb.com/x410/>. The x-410 costs between $200 and $400. There are also relays on the market for as low as $80. Just search Google for "web relay controller".


Some knowledge is required of your hardware in order to connect the x-410. Door lock hardware typically supports a mechanism to trip a high voltage circuit by closing a low voltage circuit. Information in the x-410 manual explains how to connect the low voltage circuit to the x-410. (A pdf of the x-410 Manual is attached.).


There are four independently controllable relays per device. Configure the relay defaults. You can set the default time the relays close on the device or you can set the default time via a remote HTTP command.  You can use user/pwd for remote control over HTTP or use a PSK (pre-shared key).  Our default script uses user/pwd.

The x-410 requires power input. You can get a power adapter for the relay or get the -E model which uses Power Over Ethernet (POE). POE , if available, is the preferred method to power the device because there is no need for a separate power input when you use POE.

You will need an IP address for your x-410. The x-410 manual describes 2 different ways to set the IP address: using a direct connection from your PC and using an address resolution protocol (arp) command to temporarily change the device's IP so you can then log in to permanently set it.


SAFR's action event listener, Actions Relay Event Service (ARES), is installed with a sample script named relay-x410.py that can close one of 4 different relays on an x-410 controller using a REST API command. The closing of the relay causes the door lock mechanism to trigger for a specified amount of time, which causes the door to unlock for that amount of time. relay-x410.py is located here:


  • On Windows: C:\Program Files\RealNetworks\SAFR\ares\scripts
  • On macOS/Library/RealNetworks/SAFR/ares/scripts
  • On Linux:/opt/RealNetworks/SAFR/ares/scripts

This script is described in the next section.


The ARES Script that Unlocks Doors

relay-x410.py sends a pulse command which triggers the actuator for the number of seconds specified when you run the script. The x-410 will keep the circuit closed for the duration of the pulse. If another pulse is received, the door's unlock timer is reset to the full amount of time specified when you ran the script.


Before using the script you need to edit it setting the username and password variables defined near the beginning of the script to your username and password. The script is run according to the following syntax: 


relay-x410.py IPADDRESS  RELAYNUM

For example:


relay-x410.py 10.124.1.23 2


The script should be invoked from the action field of the SAFRActions.config file as described above.  See How to Trigger SAFR actions for more information about setting up SAFR actions to trigger actions based on events.  

Test the Setup

It's a good idea to start with just the x-410 script in order to ensure that it's working on its own. In this way you can troubleshoot many issues by viewing output from the script directly.

Troubleshooting

If you encounter problems, here are 2 basic troubleshooting steps you can take.

  1. Ensure that you have the Python dependencies installed that your script(s) require. For the script used in this article,  relay-x410.py, you need the following libraries installed:
    • os
    • sys
    • datetime
  2. Check the ARES log, located here:
    • On Windows: C:\Program Files\RealNetworks\SAFR\ares\logs
    • On macOS: /Library/RealNetworks/SAFR/ares/logs
    • On Linux: /opt//RealNetworks/SAFR/ares/logs

        For information about ARES logs, see the Interpreting and Using Actions Relay Event Service (ARES) logs article.