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.
- 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.
The wiring diagram below shows a similar model of fingerprint sensor. Follow the sensor specification sheets if there's any doubts about the wiring schema. Adafruit has a detailed summary of wiring different fingerprint sensors.
In the photo show below, Wago lever nuts are used to quickly facilitate the connection to the USB serial adapter. You can choose a different method of connecting the wires, such as soldering. The blue and white wires of the fingerprint sensor are not being used.
- Connect the servo to the Pi: Jumper wires are required to connect the servo wires to the Raspberry Pi.
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 sectionWireless 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 thehostname
andusername
you set, as you will need this when you SSH into your Pi.
- Save your updates, and confirm
YES
to apply OS customization settings. ConfirmYES
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.
- 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.
- 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 theLinux / Aarch64
platform for the Raspberry Pi, and leave your installation method asviam-agent
.
- Use the
viam-agent
to download and installviam-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.
- 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 therpi
model. This adds theraspberry-pi
module for working with the Raspberry Pi 4's GPIO pins. Leave the default nameboard-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.
- Click the + icon in the left-hand menu and select Component or service.
- Select
sensor
, and find theadafruit-r503
model. This adds thefingerprint
module for working with the fingerprint sensor. Rename the default name tofingerprint-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.
- Click the + icon in the left-hand menu and select Component or service.
- Select
servo
, and find therpi-servo
model. This adds the module to run a servo with Raspberry Pi 0 to 4. Leave the default nameservo-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
and180
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 and180
represents an open latch position, in order to secure our lockbox.
- 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 offalse
.
- 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.
- 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 slot1
. 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 instart_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
to199
.
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.
- Under the CONFIGURE tab, click the + icon in the left-hand menu and select Component or service.
- Search for a model
fingerServo
and add thecontrol-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 tocontroller
. - 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, andservo_open_angle
andservo_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 callingdo_commands()
tostart_enrollment
,capture
,create_model
, andstore_model
. Once the fingerprint is successfully enrolled, users can place the finger on the sensor again to unlock the geocache.
Comments