Solution Overview

• 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

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

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

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

relay-x410.py 10.124.1.23 2