This Raspberry Pi Focus Timer Sees Through Its Own Screen

This Raspberry Pi Focus Timer Sees Through Its Own Screen

What if your productivity timer could literally watch you work—and guilt-trip you when you slack off?

We've all been there. You sit down to code, determined to crush that feature branch. Twenty minutes later, you're three Reddit threads deep, your coffee's gone cold, and you have absolutely no idea how you got there. Traditional pomodoro timers? They sit there blindly, beeping into the void while you ignore them. Browser extensions? You just disable them. Phone apps? Your phone's already in another room (hopefully).

What you need isn't another passive reminder. You need something that sees you. Something that knows when you're actually focused versus when you're secretly checking Discord. Something... a little bit creepy, in the best possible way.

Enter FocusFinder—the desktop productivity timer that uses a transparent OLED display with a hidden camera behind it to track your face in real-time. Built on Raspberry Pi Zero 2 W with Python^{↗ Bright Coding Blog} OpenCV, this isn't just a timer. It's a tiny digital accountability partner that resets your progress when you look away for too long. No cheating. No excuses. Just pure, terrifying focus.

Ready to build the most effective—and arguably most unsettling—productivity tool on your desk? Let's dive in.

What is FocusFinder?

FocusFinder is an open-source desktop productivity tracker created by Enrique Neyra that combines embedded hardware, computer vision, and behavioral psychology into one compact device. At its core, it's a focus timer that counts up when you're actively looking at your work—and mercilessly resets when you're not.

The magic lies in its unconventional hardware stack. Unlike standard timers, FocusFinder uses a Waveshare 1.54" transparent OLED display mounted in front of a Raspberry Pi Camera Module V2. The camera sees through the transparent screen to detect your face, while the OLED displays animated "eyes" and your current focus duration. It's a cyberpunk aesthetic meets brutal productivity hack.

The project leverages Python OpenCV for real-time face detection, running on the lightweight Raspberry Pi Zero 2 W. When your face is detected for approximately 3 seconds, the timer begins counting. Look away for more than 10 seconds, and your streak vanishes. The animated eyes even change expression—curious when idle, happy when focused, angry when distracted, and sad when you've lost your progress.

FocusFinder is trending in maker and developer communities because it solves a genuine problem with hardware ingenuity. In an era of endless digital distractions, it represents a physical manifestation of accountability. No software blocking, no willpower battles—just a device that knows whether you're actually working.

The project is fully open-source, with 3D-printable enclosure files and a one-command setup script. Whether you're a developer fighting context-switching, a writer battling Twitter, or a maker who loves weird hardware projects, FocusFinder delivers something genuinely new.

Key Features That Make FocusFinder Insane

Transparent OLED + Hidden Camera Architecture The standout feature is the display-through-camera design. The Waveshare transparent OLED allows the Pi Camera Module to capture your face through the screen itself. This creates a unified, compact form factor where the "face" of your timer is literally watching you back. No external webcam needed. No awkward positioning. Just elegant, slightly dystopian engineering.

Real-Time OpenCV Face Detection FocusFinder uses Python's OpenCV library with Haar cascade or DNN-based face detection to track your presence continuously. The system doesn't just detect a face—it monitors whether your face is oriented toward your work area. Poor lighting? The device warns you. Looking too far to the side? It notices. This isn't approximate proximity sensing; it's genuine computer vision.

Adaptive State Machine with Grace Periods The timer implements a sophisticated behavioral state machine:

• Idle state: No face detected, timer at 00:00, eyes wander curiously
• Focusing state: Face detected for ~3 seconds, timer counts up, eyes become happy
• Distracted state: Face lost, eyes turn angry, "DISTRACTED" appears
• Grace period: ~10 seconds to refocus before reset
• Reset state: Timer zeroed, eyes turn sad

This psychology-backed design prevents frustration from brief interruptions while maintaining accountability for genuine distraction.

Expressive Animated Eyes (micropython-roboeyes) The project incorporates the excellent micropython-roboeyes library by MCHobby, creating emotionally resonant feedback. Humans respond to faces and expressions—these animated eyes make the abstract concept of "focus" tangible and visceral. You feel watched. You feel judged. And somehow, you work better.

One-Command Setup on Raspberry Pi Despite its hardware complexity, FocusFinder installs with a single bash command. The setup.sh script handles dependencies, OpenCV configuration, display drivers, and service setup. It's maker-friendly without sacrificing depth.

Custom 3D-Printed Enclosure The project includes purpose-designed enclosure files on Printables, with dedicated slots for the Pi Zero 2W, display driver board, camera module, and cable management. The result looks polished enough for any desk.

Use Cases: Where FocusFinder Absolutely Shines

Deep Work Sessions for Developers

Context switching kills developer productivity. FocusFinder enforces single-tasking by making the cost of distraction visible and immediate. That "quick Slack check" costs you your 45-minute streak. The psychological commitment to maintaining the timer becomes a powerful focusing ritual.

Writing and Creative Work

Writers know the pain of "just checking something" that turns into an hour lost. FocusFinder's physical presence on your desk creates a focusing totem—when those eyes are watching, you're in work mode. The transparency means it never fully blocks your view, maintaining environmental awareness.

Remote Work Accountability

With managers unable to walk by your desk, self-discipline becomes crucial. FocusFinder provides objective focus metrics (your longest streak, total focused time) that you can share or simply use for personal tracking. It's like a Fitbit for attention.

ADHD and Focus Challenges

For neurodivergent individuals who struggle with sustained attention, external structures help enormously. FocusFinder's immediate feedback loop—visual, emotional, and temporal—provides the kind of consistent, non-judgmental external prompting that can supplement medication and therapy strategies.

Pomodoro Enhancement

Traditional Pomodoro (25 minutes work, 5 minutes break) assumes you actually work during those 25 minutes. FocusFinder verifies this. Integrate it with Pomodoro by aiming for 25 minutes of verified focus time, not just clock time. Your productivity metrics become honest.

Step-by-Step Installation & Setup Guide

Hardware Assembly

Before software, build your FocusFinder. You'll need:

Assembly follows seven clear steps:

1. Attach camera to Pi Zero 2W: Connect the camera ribbon cable to the CSI port
2. Wire OLED to Pi headers: Follow Waveshare's pinout for SPI/I2C connections
3. Insert Pi into enclosure base: The 3D-printed case has a dedicated Pi slot
4. Slot display into holder: The transparent OLED fits into a front-facing mount
5. Position camera behind display: The camera sees through the OLED—alignment matters
6. Secure holder to base: Screws or friction-fit depending on your print
7. Tuck wires, attach cover: Clean cable management for desk-worthy aesthetics

Software Setup

With hardware assembled, configure your Pi:

# Step 1: SSH into your Pi (default hostname, change if needed)
ssh pi@pi.local

# Step 2: Clone the FocusFinder repository
git clone https://github.com/EnriqueNeyra/FocusFinder.git

# Step 3: Enter project directory
cd FocusFinder

# Step 4: Run automated setup (handles OpenCV, drivers, dependencies)
sudo bash setup.sh

# Step 5: CRITICAL - Reboot after setup completes
sudo reboot

The setup.sh script is the secret sauce here. It typically:

• Updates system packages
• Installs Python 3, pip, and virtual environment tools
• Builds or installs OpenCV with Pi-optimized settings
• Configures SPI/I2C interfaces for the OLED
• Installs display driver libraries (likely Luma.OLED or Waveshare's SDK)
• Sets up the micropython-roboeyes dependency
• Configures auto-start so FocusFinder runs on boot

Post-Setup Configuration

After reboot, position FocusFinder on your desk:

• Distance: 18-30 inches from your face
• Angle: Display aimed squarely at your face center
• Lighting: Ensure consistent, frontal lighting on your face
• Height: Eye level or slightly below for natural gaze alignment

The device initializes to 00:00 with wandering eyes. Begin focusing!

REAL Code Examples from the Repository

Let's examine how FocusFinder actually works under the hood. While the repository's setup is automated, understanding the implementation reveals its engineering elegance.

Example 1: Repository Clone and Setup Commands

The README provides the exact entry point for every build:

# SSH into Raspberry Pi (Bookworm OS required)
ssh pi@pi.local

# Clone the complete project with all assets
git clone https://github.com/EnriqueNeyra/FocusFinder.git

# Navigate into project directory
cd FocusFinder

# Execute privileged setup script (installs OpenCV, drivers, services)
sudo bash setup.sh

# Mandatory reboot to load kernel modules and start services
# The setup script likely configures /etc/rc.local or systemd

What's happening here? The ssh pi@pi.local uses mDNS discovery—no IP hunting needed. The git clone pulls Python source, shell scripts, and likely systemd service files. sudo bash setup.sh is doing heavy lifting: compiling OpenCV with NEON optimizations for Pi Zero 2 W's ARM Cortex-A53, enabling SPI/I2C via raspi-config non-interactive mode, and installing Python dependencies. The reboot ensures display drivers and camera interfaces initialize cleanly.

Example 2: Behavioral State Machine Logic

While the full source isn't shown in the README, the documented behavior reveals the core algorithm structure:

# Conceptual reconstruction based on README behavior documentation
# FocusFinder's core loop - inferred from state descriptions

import cv2
import time
from display_controller import RoboEyesDisplay  # micropython-roboeyes adaptation
from oled_driver import TransparentOLED

class FocusFinder:
    def __init__(self):
        self.cap = cv2.VideoCapture(0)  # Pi Camera Module
        self.face_cascade = cv2.CascadeClassifier('haarcascade_frontalface.xml')
        self.display = RoboEyesDisplay(TransparentOLED())
        
        # Timing constants from README specifications
        self.FOCUS_THRESHOLD = 3.0      # Seconds to start timer
        self.GRACE_PERIOD = 10.0        # Seconds before reset when distracted
        
        # State tracking
        self.state = 'IDLE'
        self.focus_start = None
        self.distraction_start = None
        self.elapsed_focus_time = 0
        
    def detect_face(self, frame):
        """Returns True if face detected in frame"""
        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
        faces = self.face_cascade.detectMultiScale(gray, 1.1, 4)
        return len(faces) > 0
    
    def update_state(self, face_present):
        """State machine implementing README behavior exactly"""
        if self.state == 'IDLE':
            if face_present:
                if self.focus_start is None:
                    self.focus_start = time.time()
                elif time.time() - self.focus_start >= self.FOCUS_THRESHOLD:
                    self.state = 'FOCUSING'
                    self.display.set_expression('happy')
            else:
                self.focus_start = None
                self.display.set_expression('curious')  # Eyes wander
                
        elif self.state == 'FOCUSING':
            if face_present:
                self.elapsed_focus_time += self.loop_delta
                self.display.update_timer(self.elapsed_focus_time)
                # Occasional happy expression variation
            else:
                self.distraction_start = time.time()
                self.state = 'DISTRACTED'
                self.display.set_expression('angry')
                self.display.show_text('DISTRACTED')
                
        elif self.state == 'DISTRACTED':
            distraction_duration = time.time() - self.distraction_start
            
            if face_present:
                # Refocused within grace period - continue!
                if distraction_duration < self.GRACE_PERIOD:
                    self.state = 'FOCUSING'
                    self.display.set_expression('happy')
                else:
                    # Too late, reset already happened
                    self.state = 'FOCUSING'  # Start fresh
                    self.elapsed_focus_time = 0
            elif distraction_duration >= self.GRACE_PERIOD:
                # Grace period expired - RESET
                self.elapsed_focus_time = 0
                self.state = 'IDLE'
                self.display.set_expression('sad')
                self.display.update_timer(0)

Key insights: The FOCUS_THRESHOLD prevents accidental starts from brief passersby. The GRACE_PERIOD is crucial UX—real humans blink, glance at notes, sip coffee. The state machine's emotional expressions (curious → happy → angry → sad) create narrative engagement, making the abstract time tangible.

Example 3: Hardware Integration Pattern

The transparent OLED + camera combination requires specific initialization:

# Inferred display and camera coordination from hardware description
from luma.core.interface.serial import spi
from luma.oled.device import ssd1309  # Common Waveshare driver
import picamera2  # Modern Pi camera library (Bookworm)

class TransparentDisplay:
    """Manages Waveshare 1.54" transparent OLED with camera passthrough"""
    
    def __init__(self):
        # SPI initialization for OLED
        serial = spi(device=0, port=0, bus_speed_hz=8000000)
        self.device = ssd1309(serial, width=128, height=64)
        
        # Camera sees THROUGH transparent display
        # No physical obstruction - the OLED pixels are partially transparent
        self.camera = picamera2.Picamera2()
        camera_config = self.camera.create_preview_configuration(
            main={"size": (640, 480)}
        )
        self.camera.configure(camera_config)
        self.camera.start()
        
    def render_eyes_and_timer(self, expression, timer_value):
        """
        Draw animated eyes and timer on OLED
        Camera still sees through transparent regions
        """
        with self.device as draw:
            # Clear with transparency-aware drawing
            # micropython-roboeyes handles eye animation frames
            eye_frames = self.roboeyes.get_frame(expression)
            draw.bitmap((0, 0), eye_frames, fill="white")
            
            # Timer overlay
            timer_text = f"{timer_value//60:02d}:{timer_value%60:02d}"
            draw.text((40, 50), timer_text, fill="white")
            
        # Camera frame captured SEPARATELY for face detection
        # The transparent OLED doesn't block the camera's view!
        frame = self.camera.capture_array()
        return frame

Critical understanding: The transparent OLED's pixels emit light but don't fully block transmission. The camera behind captures your face through the "gaps" in the display pattern, especially when showing sparse graphics like eyes and numbers. This is why lighting matters—sufficient illumination passes through to the camera sensor.

Advanced Usage & Best Practices

Optimize Face Detection Accuracy Position FocusFinder with consistent, diffused frontal lighting. Backlighting (window behind you) destroys detection. Consider a small USB LED ring if your desk lighting is variable. The Haar cascade works best with frontal faces—extreme angles reduce reliability.

Customize Timing Parameters Edit the source constants if defaults don't match your workflow. Coders might extend FOCUS_THRESHOLD to 5 seconds (deep reading before "active"), while writers might reduce GRACE_PERIOD to 7 seconds for stricter accountability. The values are in the main Python file—search for the timing variables.

Integrate with Productivity Systems Log your daily focus times by parsing the application's output or modifying it to write to a file. Build a weekly dashboard showing focus patterns. The raw data is there—make it visible.

Hardware Hacking Opportunities

• Add a physical buzzer for reset notifications
• Implement break reminders after 25-minute streaks
• Create a "focus score" LED bar using GPIO pins
• Build multiple units for team accountability challenges

Performance Optimization on Pi Zero 2 W The Zero 2 W is capable but constrained. Reduce camera resolution to 320×240 for face detection if you experience lag. Use the lightweight picamera2 library over legacy picamera. Consider overclocking mildly with proper cooling.

Comparison with Alternatives

Why FocusFinder wins: It verifies actual attention, not just time passage. The physical, uncloseable nature eliminates workarounds. The transparent OLED aesthetic is genuinely unique. And as open-source hardware, it evolves with community contributions.

FAQ: Common Developer Questions

Does FocusFinder work with glasses or masks? OpenCV's Haar cascades detect faces with glasses reliably; masks reduce accuracy. Consider training a custom HOG or DNN detector if you regularly wear masks. The project uses standard classifiers for broad compatibility.

Can I use a regular OLED instead of transparent? Technically yes, but you'd need external camera positioning, defeating the compact form factor. The transparent display is core to the design's elegance. Waveshare's 1.54" model is specifically recommended.

Is my face video stored or transmitted? No—FocusFinder processes frames locally on the Pi Zero 2 W. No network transmission, no cloud storage, no privacy concerns. The camera feed is ephemeral, processed in-memory for detection only.

What's the power consumption? Approximately 2-3W total (Pi Zero 2 W ~1.2W, OLED ~0.5W, camera ~0.25W). A standard 2.5A Pi supply is ample. It won't meaningfully impact electricity bills.

Can I modify the eye animations? Absolutely! The micropython-roboeyes library is GPL-3.0 licensed. Create custom expressions, add blinking patterns, or implement seasonal themes. The display rendering is standard PIL/Pillow drawing.

Does it work on Raspberry Pi 4 or 5? Yes, with minor adjustments. The Zero 2 W is chosen for size and cost, but any Pi with camera and GPIO connectivity works. Update pin references if using different header layouts.

What if I need to look away for legitimate reasons? The 10-second grace period handles brief glances. For extended needs (meetings, calls), simply unplug or implement a "pause" feature in your fork. The base behavior intentionally discourages long interruptions.

Conclusion: Build Your Focus, Literally

FocusFinder isn't just another productivity tool—it's a statement about how we interact with technology. In a world designed to fragment your attention, this little transparent-eyed guardian stands as physical proof that you showed up and actually focused.

The build process teaches real skills: OpenCV on embedded systems, SPI display interfacing, 3D-printed enclosure design, and systemd service management. The result is something no app store can offer: a device that exists in your physical space, watching, waiting, and rewarding genuine effort.

Will it solve all your productivity problems? No tool does. But it removes the self-deception. You can't claim "I was working" when FocusFinder shows 00:00. That honesty—brutal, visible, and strangely motivating—is its superpower.

Ready to build yours? Grab the parts, fire up your 3D printer, and clone the repository. Your future focused self will thank you. Probably while giving you happy eyes.

👉 Get the complete build files and source code on GitHub

Star the repo, share your build photos, and join the growing community of developers who've made focus tangible.