Face identification for access control with Raspberry Pi and Camera

Face identification for access control with Raspberry Pi and Camera

1. Overview

Create a facial recognition system to unlock a door using a Raspberry Pi, webcam, and computer vision.

Whether you're securing a home, office, or secret lair, this project shows you how to build a smart access control system powered by facial recognition and Viam.

What You'll Build

Prerequisites

What You'll Learn

What You'll Need

Watch the Video

See a demonstration of the "Securibot", the door access system, in action:

Securibot | office access with facial recognition

2. Set up your Raspberry Pi

The Raspberry Pi boots from a USB flash drive (or microSD card). You need to install Raspberry Pi OS on a storage device that you will use with your Pi. For more details about alternative methods of setting up your Raspberry Pi, refer to the Viam docs.

Install Raspberry Pi OS

  1. Connect the USB flash drive (or microSD card) to your computer.
  2. Download the Raspberry Pi Imager and launch it.
  3. Click CHOOSE DEVICE. Select your model of Pi, which is Raspberry Pi 4.
  4. Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
  5. Click CHOOSE STORAGE. From the list of devices, select the storage device you intend to use in your Raspberry Pi.
  6. Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
  7. Check Set hostname and enter the name you would like to access the Pi by in that field, for example, test.
  8. Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be pi (not recommended for security reasons). And specify a password.
  9. Connect your Pi to Wi-Fi so that you can run viam-server wirelessly. Check Configure wireless LAN and enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Change the section Wireless LAN country to where your router is currently being operated.
  10. Select the SERVICES tab, check Enable SSH, and select Use password authentication.
  11. Save your updates, and confirm YES to apply OS customization settings. Confirm YES to erase data on your storage device. You may also be prompted by your operating system to enter an administrator password. After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to your storage device.
  12. Remove the storage device from your computer when the installation is complete.

Connect with SSH

  1. Place the storage device into your Raspberry Pi and boot the Pi by plugging it in to an outlet. A red LED will turn on to indicate that the Pi is connected to power.

  2. Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <USERNAME> and <HOSTNAME> should be replaced with the user and hostname you configured when you set up your Pi.

ssh <USERNAME>@<HOSTNAME>.local
  1. If you are prompted "Are you sure you want to continue connecting?", type "yes" and hit enter. Then, enter the password for your username. You should be greeted by a login message and a command prompt.
  2. Update your Raspberry Pi to ensure all the latest packages are installed
sudo apt update
sudo apt upgrade

3. Set up the hardware

The Viam office currently uses a fob system to unlock a security door. By adding computer vision and facial recognition, we can verify that specific individuals are authorized to enter and automatically unlock the door. In this setup, a webcam can be mounted above the door to detect faces. When an authorized face is recognized, a servo waves a heated pad in front of a PIR motion sensor (originally intended for people leaving the office) to trigger the door to unlock.

Your door setup may differ, so this section may need to be adjusted based on your specific configuration.

Add your servo

  1. Wire the servo to the Raspberry Pi: The servo can be controlled via a GPIO pin on the Raspberry Pi. Refer to the following wiring diagram to connect the Raspberry Pi to the servo and heated pad.
Raspberry Pi Servo and Heated pad
Pin 2 (5V) Power for heated pad
Pin 4 (5V) Power for servo
Pin 6 (Ground) GND for servo
Pin 9 (Ground) GND for heated pad
Pin 16 (GPIO 23) GPIO for servo

Now that you have physically connected the hardware components, let's configure the software in the next section.

4. Configure your machine and peripherals

Configure your machine

  1. In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine.
  2. Click View setup instructions.
  3. To install viam-server on the Raspberry Pi device that you want to use to communicate with and control your webcam, select the Linux / Aarch64 platform for the Raspberry Pi, and leave your installation method as viam-agent.
  4. Use the viam-agent to download and install viam-server on your Raspberry Pi. Follow the instructions to run the command provided in the setup instructions from the SSH prompt of your Raspberry Pi.
  5. The setup page will indicate when the machine is successfully connected.

Configure your Raspberry Pi board

To access the GPIO pins, let's add our Raspberry Pi board to our machine in the Viam app.

  1. In the Viam app, find the CONFIGURE tab.
  2. Click the + icon in the left-hand menu and select Component.
  3. Select board, and find the raspberry-pi:rpi4 module. This adds the module for working with the Raspberry Pi 4's GPIO pins. Leave the default name board-1 for now.
  4. Notice adding this module adds the board hardware component called board-1. The collapsible card on the right corresponds to the part listed in the left sidebar.
  5. Click Save in the top right to save and apply your configuration changes.

Configure your servo

  1. In the Viam app, find the CONFIGURE tab.
  2. Click the + icon in the left-hand menu and select Component.
  3. Select servo, and find the gpio module. This adds the module for working with the servo using the Raspberry Pi 4's GPIO pins. Leave the default name servo-1 for now.
  4. Notice adding this module adds the board hardware component called servo-1. The collapsible card on the right corresponds to the part listed in the left sidebar.
  5. Under the Attributes section, select board-1 as the Raspberry Pi board, and input 16 as the physical pin number on the Raspberry Pi where we will be controlling the servo motor.
  6. Click Save in the top right to save and apply your configuration changes.
  7. Expand the TEST section to make sure you can control the servo using the current configuration.

Add and configure your USB webcam

  1. Connect the USB webcam to the Raspberry Pi.
  2. In the Viam app, find the CONFIGURE tab.
  3. Click the + icon in the left-hand menu and select Component.
  4. Select camera, and find the webcam module. This adds the module for working with a USB webcam. Leave the default name camera-1 for now.
  5. Notice adding this component adds the webcam hardware component called camera-1. The collapsible panel on the right corresponds to the part listed in the left sidebar.
  6. Under Attributes, leave the video_path blank and the camera will use the default video path for your machine. If this doesn't work when you test your camera later, you can try a different video path by following the prompt in the Viam app to add a webcam discovery service and identify path options.
  7. Click Save in the top right to save and apply your configuration changes.
  8. At the bottom of the camera-1 panel, expand the TEST section to ensure you have configured the camera properly.

5. Add a vision service

Now that your hardware is working the way you want it, it's time to add a vision service to detect and identify a face.

Prepare your machine to run the control code

  1. SSH into your board: From the terminal window, run the following command to SSH (Secure Shell) into your board, where the text in <USERNAME> and <REMOTE-HOSTNAME> should be replaced with the user and hostname you configured when you set up your machine.
ssh <USERNAME>@<REMOTE-HOSTNAME>.local
  1. On the Raspberry Pi, create a directory called known_faces to store photos of people who are allowed access to the office.
mkdir known_faces
  1. Verify the directory location: the directory is located within the home directory of the user joncha in this example. Running the following command results in /home/joncha/ so we know the full path to the directory is /home/joncha/known_faces. We will need this path in an upcoming step.
pwd

Configure a vision service

  1. In the Viam app, click the + icon in the left-hand menu and select Service, and then vision.
  2. Search for a module called face-identification. Then click Add module, and Create a new vision service, renaming the service as face-identification.
  3. Notice this creates two new items in the left sidebar. The first is your new vision service called face-identification based on a module also called face-identification.
  4. In the face-identification panel for the vision service under the CONFIGURE section, add the following attributes. This configures the vision service to depend on data coming in from the named webcam, refer to a directory of known_faces to be stored on the Raspberry Pi, and establish a sensitivity threshold for the vision service.
{
     "picture_directory": "/home/joncha/known_faces",
     "identification_threshold": 0.5,
     "camera_name": "camera-1"
}
  1. Save your changes in the top right and wait a few moments for the configuration changes to take effect.
  2. At the bottom of the face-identification vision service panel, expand the TEST section to ensure you have configured the vision service properly. Point the webcam towards a face to see if the camera detects it.
  3. If the camera detects a face, a bounding box will highlight the item in the video feed, and display it on the right under Labels.

Configure an automation service

Next, let's set up a service to ensure the camera is always running the facial detection program. When a recognized face is detected, the servo will activate to unlock the door. If the face is not recognized, no action will be taken.

  1. In the Viam app, click the + icon in the left-hand menu and select Service, and then generic. Then search for a module called securibot:doorbot.
  2. Click Add module, and Create a new vision service, renaming the service as automation.
  3. Notice this creates two new items in the left sidebar. The first is your new generic service called automation based on a module called doorbot.
  4. In the automation panel for the generic service under the CONFIGURE section, add the following attributes. This configures the service to depend on data coming in from the named webcam (camera-1), trigger the named servo (servo-1), and named vision service (face-identification).
{
     "camera_name": "camera-1",
     "servo_name": "servo-1",
     "vision_name": "face-identification"
}
  1. Save your changes in the top right and wait a few moments for the configuration changes to take effect.

6. Finishing touches

Now that your servo is working as intended, it's time to tidy up the project and make it practical for real-world use.

  1. Mount the webcam: Find a place outside the door to mount your webcam with a preferably unobstructed view of people's faces, for example, above a door frame.
  2. Mount the unlocking mechanism: For this scenario, we are mounting an arm connected to a heated pad to trigger an existing PIR sensor. This sensor was originally intended to enable access for people leaving the Viam office, but we are repurposing it to allow people to enter the office after verifying they are authorized access.
  3. Assemble an enclosure for the Pi: 3D print (or buy) an enclosure for your Raspberry Pi. I found an existing design that I liked to fit a Raspberry Pi 4 Model B that provides access to the GPIO pins.
  4. Tidy the wires: Neatly bundle the remaining wires using zip ties, twist ties, or cable clips to keep everything organized and out of the way.

7. Next Steps

What you learned

Advanced scenarios for your facial recognition door system

In addition to the project ideas mentioned above, consider other ways to continue your journey with Viam.

Real-World Applications of Face-Based Access Systems

Facial recognition access control isn't just a fun Raspberry Pi project. It's used in serious applications, including: