Enable physical access using a fingerprint sensor

You can use a fingerprint sensor to unlock a geocache box, open a garage door, or enable access to just about anything.

In this tutorial, you'll use the R503 fingerprint sensor with Viam to unlock a servo-powered latch when an enrolled fingerprint is detected. This project demonstrates how to use biometric input as a trigger for a physical access control system.

servo latch demo

Prerequisites

Sign up for a free Viam account, and then sign in to the Viam app
Hardware and supplies requirements
- 1 - Raspberry Pi 4
- 1 - USB flash drive or microSD card to use with your Pi
- 1 - USB cable to power your Pi
- 1 - R503 fingerprint sensor
- 1 - Servo motor (SG90 or similar)
- 1 - CP2102 USB 2.0 to TTL Serial Adapter
- 7 - Jumper wires
- 1 - Phillips screwdriver to mount the servo motor
- 1 - 3D printed mount and enclosure (optional)

What You'll Learn

How to use modules from the Viam registry
How to run control logic on your Viam achine
How to configure a biometric sensor with Viam
How to use control logic to actuate a servo on fingerprint match
How to use Viam's do_command() interface for testing

What You'll Build

A physical access system that unlocks a servo latch on fingerprint recognition

Watch the Video

See a demonstration and overview of the access control system in this video.

Wire your fingerprint sensor

Connect the adapter: Connect the USB to serial adapter to a USB port in your Raspberry Pi. Jumper wires may be required to connect the R503 sensor to your Raspberry Pi.
UART pins are easier for compact setups, but USB adapters simplify voltage matching.

Wire the R503 sensor to the adapter: Refer to the following wiring diagram to see how to connect the adapter to the R503 fingerprint sensor. Make sure the transmitting pin (TX) on the adapter is connected to the receiving pin (RX) on the sensor, and vice versa.

CP2102	R503
Transmitting (TXO)	Receiving (RX), Purple/brown wire (4th when counting from the Red wire)
Receiving (RXI)	Transmitting (TX), Yellow wire (3rd when counting from the Red wire)
Power (3V3)	VCC, Red wire
Ground (GND)	GND, Black wire

Wire your servo motor

Connect the servo to the Pi: Jumper wires are required to connect the servo wires to the Raspberry Pi.

Servo

Raspberry Pi

Power wire (red)

Pin 4 (VCC 5V)

Ground wire (black)

Pin 6 (GND)

Data wire (yellow)

Pin 8 (GPIO 14)

The website pinout.xyz is a helpful resource with the exact layout and role of each pin for Raspberry Pi. When working with Viam, make sure to reference the physical pin numbers, and not the GPIO numbers listed on pinout.xyz.

The Raspberry Pi boots from a USB flash drive (or microSD card). You need to install Raspberry Pi OS on a USB flash drive 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

Connect the USB flash drive (or microSD card) to your computer.
Download the Raspberry Pi Imager and launch it.
Click CHOOSE DEVICE. Select your model of Pi, which is Raspberry Pi 4.
Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
Click CHOOSE STORAGE. From the list of devices, select the USB flash drive you intend to use in your Raspberry Pi.
Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
Check Set hostname and enter the name you would like to access the Pi by in that field, for example, test.
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.
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.
Select the SERVICES tab, check Enable SSH, and select Use password authentication.
Be sure that you remember the hostname and username you set, as you will need this when you SSH into your Pi.
Save your updates, and confirm YES to apply OS customization settings. Confirm YES to erase data on the USB flash drive. 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 the USB flash drive.
Remove the USB flash drive from your computer when the installation is complete.

Connect with SSH

Place the USB flash drive 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.
Make sure you are using a 5V 3A USB-C power supply to power your Raspberry Pi 4. Using a power supply with inadequate amperage can lead to instability, throttling, or unexpected behavior. Additionally, while USB boot is enabled by default on newer Raspberry Pi 4 models, older versions may require a firmware update to enable it. Refer to the Raspberry Pi documentation for detailed setup instructions and compatibility.
Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <> should be replaced (including the < and > symbols themselves) with the user and hostname you configured when you set up your Pi.
```
ssh <USERNAME>@<HOSTNAME>.local
```
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.
Update your Raspberry Pi to ensure all the latest packages are installed
```
sudo apt update
sudo apt upgrade
```

Enable communication protocols

Launch the Pi configuration tool by running the following command
```
sudo raspi-config
```
Use your keyboard to select "Interface Options", and press return.
Enable the relevant protocols to support our hardware. Since you are using a sensor that communicates over the serial port, enable Serial Port.
Confirm the options to enable the serial login shell and serial interface. And reboot the Pi when you're finished.

Configure your machine

In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine.
Click View setup instructions.
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.
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.
The setup page will indicate when the machine is successfully connected.

Add your Raspberry Pi

In the Viam app, find the CONFIGURE tab. It's time to configure your hardware.
Click the + icon in the left-hand menu and select Component or service.
Select board, and find the rpi model. This adds the raspberry-pi module for working with the Raspberry Pi 4's GPIO pins. Leave the default name board-1 for now.
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.
Click Save in the top right to save and apply your configuration changes.
If any problems occur, check under the LOGS tab to see what might be going wrong.

Add your fingerprint sensor

Click the + icon in the left-hand menu and select Component or service.
Select sensor, and find the adafruit-r503 model. This adds the fingerprint module for working with the fingerprint sensor. Rename the default name to fingerprint-sensor.
Notice adding this module adds the board hardware component called fingerprint-sensor.
Click Save in the top right to save and apply your configuration changes.

Add your servo

Click the + icon in the left-hand menu and select Component or service.
Select servo, and find the rpi-servo model. This adds the module to run a servo with Raspberry Pi 0 to 4. Leave the default name servo-1 for now.
Notice adding this module adds the board hardware component called servo-1. Add the following JSON object under the CONFIGURE section of the new corresponding panel. This configuration allows Viam to accept data inputs from physical pin 8 on the Raspberry Pi.
```
{
  "pin": "8",
  "board": "board-1"
}
```
Click Save in the top right to save and apply your configuration changes.

Now that we have added and configured these components in the Viam app, we can test them.

Test your servo

Find the component servo-1 and expand the TEST section of the corresponding panel.
Input a value between 0 and 180 within the Desired angle (º) field, and click the Execute button to see what happens.
Continue experimenting with different inputs to see what happens. In the upcoming steps, you will mount the servo in a way that an angle of 0 represents a closed latch position and 180 represents an open latch position, in order to secure our lockbox.

Test your fingerprint sensor

Find the component fingerprint-sensor and expand the TEST section of the corresponding panel.
Under the Get Readings header, you should see finger_detected with a value of false.
Now go to the CONTROL tab within the Viam app and find the fingerprint-sensor component where you should see the same Get Readings header beneath the TEST section. This time, expand the DO COMMAND section and input the following JSON object, and click the Execute button while watching the fingerprint sensor to see an LED effect.
```
{ "test_led": true }
```

In the next section we will execute more do commands to enroll our fingerprints.

The fingerprint module supports several commands for fingerprint enrollment, matching, template management, and LED testing. Each command can be triggered using a do command request with a corresponding JSON payload. The enrollment process captures two fingerprint scans and stores them to a slot in memory.

Enroll your fingerprint

Start the enrollment: Go to the CONTROL tab within the Viam app and find the fingerprint-sensor component to again expand the DO COMMAND section. Input the following JSON object, and click the Execute button to begins enrollment for slot 1. For each DO COMMAND executed, this particular module returns a message indicating whether the command was successful. Upon a successful execution, the sensor will now wait for fingerprint scans.
```
{ "start_enrollment": 1 }
```
Capture 2 scans: Run the following command twice. First with finger pressed on the sensor. Then remove and re-place the same finger for the second scan. If there's an issue (e.g. misaligned finger), repeat this step. The enrollment state tracks progress automatically.
```
{ "capture": true }
```
Create fingerprint model: Run the following command to create a model from the two captured scans. If the prints don't match, the response message will prompt you to retry the second scan (capture again).
```
{ "create_model": true }
```
Store the model: Run the following command to store the created model in slot 1 (or the slot used in start_enrollment). You can enroll the same fingerprint multiple times in different slots to improve match reliability under varying finger angles or pressure.
```
{ "store_model": 1 }
```
Repeat: Repeat these steps with any other fingerprints you'd like to enroll, using a different numbered slot for each model. You can even enroll the same finger multiple times to improve the reliability of resulting in a positive match. The Adafruit R503 fingerprint sensor supports up to 200 fingerprint slots for storing templates, with slots indexed from 0 to 199.
Troubleshooting: If your sensor isn't responding to your finger placement:
- Check sensor placement and connection
- Try adjusting finger position or cleaning the sensor
- Finger might have moved during scanning
- Finger positions were too different between scans
- Make sure your finger is clean and not too dry.
- Apply firm, even pressure, but don't press too hard.
- Try enrolling the same fingerprint multiple times in different slots to improve match reliability under varying angles or pressure. In other words, you will have multiple slots dedicated to enrolling the same finger.

Verify your fingerprint

Check enrolled print: Place your finger on the sensor to see what happens. Look under the Get Readings section of the fingerprint-sensor component. Also look at the LED ring surrounding the sensor.
Check un-enrolled print: Place a different finger on the sensor to see what happens.

Now that you have a sensor and a servo functioning separately, let's bring it all together by adding a control logic module. This module will move the servo to an open position if a fingerprint match is detected.

workflow diagram

Add a control logic module

Under the CONFIGURE tab, click the + icon in the left-hand menu and select Component or service.
Search for a model fingerServo and add the control-access-fingerServo module. This adds a generic service move the servo to an open position when a fingerprint match is detected. Rename the default name to controller.
Add the following JSON object to configure the module to connect to various components within the machine. As optional dependencies, the leave_open_timeout is the seconds the servo remains in the open position, and servo_open_angle and servo_closed_angle can be adjusted according to how your servo horn is positioned.
```
{
  "sensor": "fingerprint-sensor",
  "board": "board-1",
  "servo": "servo-1",
  "leave_open_timeout": 30,
  "servo_open_angle": 180,
  "servo_closed angle": 90
}
```
Save your updates, and wait for the change to take effect.
Test the control logic: Place a finger on the sensor to see if it opens the servo. Then place a finger that has not been enrolled to see what happens. If it's helpful, view the Get Readings section of the fingerprint-sensor component to see what the sensor is detecting in real time.

Now that your sensor and servo are working, it's time to tidy up our project so it's not a loose jumble of wires and parts.

Design an enclosure(s): Gather your Pi, sensor, and servo together so you can start sketching out how you want the components to come together. In this example, everything but the sensor can be contained within the split-body enclosure with hinge. This can be a 3D printed or laser-cut enclosure, a cardboard prototype, or a store-bought container.
Print and assemble servo latch: Print a housing for the servo latch mechanism, such as this one that can be mounted on the interior of the box.
If you're using this particular design:
- The cam may need to be sized up or down to fit the servo axle (horn) depending on your servo model in the comments. For my SG90, the cam fit snuggly when scaled down 97%. You could also use hot glue to make a tighter fit.
- To push against the back end of the latch down to the base, I added a spring from a ballpoint pen, cut down to use 30% of the original height.
No 3D printer? No problem. You can search for "servo latch" or "servo lock" to find a prebuilt mechanism. Or prototype with cardboard and household materials first to see if this project is worth a bigger investment.
Mount servo latch and fingerprint sensor: The servo latch can be mounted on the interior of the box. The fingerprint sensor can be mounted on the box so the sensor is open to the exterior of the box.
Invite others to enroll fingerprints: If you want other people to have access too, you can:
- Enroll fingerprints using do commands in the Viam app just like you did previously.
- Build a mobile app or web app using one of Viam's SDKs to guide others through the enrollment steps.
  Geocache box example: If the fingerprint sensor is being used to enable physical access in a remote location, users can use a mobile app or web app that you create in order to guide others through the enrollment steps. For example, the app can prompt users to place a finger on the sensor to scan the first fingerprint. Behind the scenes, the app is calling do_commands() to start_enrollment, capture, create_model, and store_model. Once the fingerprint is successfully enrolled, users can place the finger on the sensor again to unlock the geocache.

What You Learned

How to use modules from the Viam registry
How to run control logic on your Viam machine
How to configure a biometric sensor with Viam
How to use control logic to actuate a servo on fingerprint match
How to use Viam's do_command() interface for testing

Enhance your fingerprint access system

Now that you have created a servo latch powered by a fingerprint sensor, you can customize and make it your own. Suggestions for extending your project include the following:

Modify the sensing: Continue enrolling other fingerprints in other slots to let trusted friends access your box of secrets. Or delete their model to take away their access.
Modify the actuation: Enhance the actuation mechanism to sound an alarm when a fingerprint is detected but doesn't match. Or open a garage door using your fingerprint.
Modify the control logic: You can create your own control logic module to further customize your system. For example, update the LED colors or effects, or change the default leave_open_timeout to a longer duration.

Other access control projects

There's many ways to control physical access to a box, physical spaces, or

Face identification for access control: Use a webcam and Computer Vision to enable access to a physical space by following this codelab.
Smart door lock: Use Android devices to directly control a lock through a Numato USB Relay with serial commands using this Viam module
Door lock status: Use an infrared sensor to detect whether your door is locked or unlocked by following this codelab