Two-Step Install¶

This guide covers setting up an OWL unit using the automated installer:

Step 1 — Flash Raspberry Pi OS onto an SD card
Step 2 — Download and run the setup script

The installer handles everything: system updates, camera check, Python environment, OpenCV, dependencies, and boot configuration. It takes around 20-30 minutes.

Prerequisites¶

Requirement	Details
Hardware	Fully assembled OWL with Raspberry Pi and camera
Camera	Connected Raspberry Pi camera module or USB camera
Internet	WiFi or Ethernet connection (for initial setup only)

Step 1: Prepare the Raspberry Pi¶

Flash the operating system¶

Download and install Raspberry Pi Imager
Select Raspberry Pi OS (64-bit) as the operating system
Click the settings cog before writing to configure:

Important

Required settings:

Username: owl (strongly recommended for compatibility)
Password: Choose a secure password
SSH: Enable for remote access
WiFi: Configure your network for initial setup
Locale: Set your timezone and keyboard layout

Use Raspberry Pi Imager to flash the OS and configure initial settings.¶

Write the image to your SD card
Insert the SD card into your Raspberry Pi and boot

Connect to your Pi¶

Option A: Direct connection — Connect a monitor and keyboard directly to the Pi. Simplest approach, avoids any SSH dropout issues during network changes.

Option B: SSH — Find the Pi’s IP address and connect from another device on the same network:

ssh owl@<your-pi-ip-address>

Tip

It’s often convenient to connect the Pi to a phone hotspot for internet access. If your computer is on the same hotspot, you can SSH in easily — check your phone’s hotspot settings for the Pi’s IP address.

Step 2: Run the installer¶

Open a terminal (press Ctrl+Alt+T if using a monitor) and run:

git clone https://github.com/geezacoleman/OpenWeedLocator owl
cd owl
bash owl_setup.sh

Tip

Dashboard features (Standalone and Networked) are included in the main branch. The installer will ask whether you want to enable the web dashboard during setup.

Warning

Do not run with sudo! The installer will request elevated permissions only when needed.

The installer will work through system updates, camera checks, Python environment setup, OpenCV, and dependencies. You’ll see [OK] for each successful step. If a step fails, you’ll see [FAIL] with an error message.

When the installer reaches the dashboard prompt, choose your setup path:

Do you want to add a web dashboard for remote control? (y/n):

Choosing your setup type

Basic OWL — Enter n. The installer finishes and you’re done.

Standalone OWL — Enter y, then select option 1. This creates a WiFi hotspot with a local dashboard. See Standalone Setup for the dashboard configuration steps.

Networked OWL — Enter y, then select option 2. This connects to an existing WiFi network with a central controller. See Networked Setup for the dashboard configuration steps.

After all steps complete, you’ll see the final summary:

[INFO] Installation Summary:
[OK] System Upgrade
[OK] Camera Detected
[OK] Camera Test
[OK] Virtual Environment Created
[OK] Global NumPy Version Detected
[OK] OpenCV Installed
[OK] NumPy Versions Aligned
[OK] OWL Dependencies Installed
[OK] OWL Service (systemd) Started
[OK] Desktop Icon Created
[OK] Dashboard Python dependencies installed
[OK] Web Dashboard Configured

[COMPLETE] OWL version installed: X.X.X

Start OWL focusing? (y/n):

Enter y to start the focusing procedure immediately, or n to focus later using the desktop icon.

Full installation output step-by-step (click to expand)

System update:

[INFO] Updating and upgrading the system...
[OK] System upgrade completed successfully.

Camera check and test:

[INFO] Checking for connected Raspberry Pi camera...
[INFO] Camera detected successfully.
[INFO] Testing camera functionality...
[INFO] Camera is working correctly.

If no camera is found, the installer will pause and ask you to connect one. If the camera test fails, it will attempt a full system upgrade to resolve driver issues and retry automatically.

Space cleanup:

[INFO] Freeing up space by removing unnecessary packages...
[OK] Cleaning up completed successfully.

Python environment:

[INFO] Setting up the virtual environment...
[OK] Installing virtualenv packages completed successfully.
[OK] Virtualenv configuration completed successfully.
[INFO] Creating the 'owl' virtual environment...
[OK] Creating virtual environment 'owl' completed successfully.
[INFO] Checking NumPy consistency (system vs venv) ...
[OK] System NumPy: 1.24.2 at /usr/lib/python3/dist-packages/numpy/__init__.py.
[INFO] Venv NumPy: 1.24.2 at /usr/lib/python3/dist-packages/numpy/__init__.py
[OK] NumPy versions match: 1.24.2

If the NumPy versions differ between system and virtual environment, the installer aligns them automatically.

OpenCV and dependencies:

[INFO] Installing opencv-contrib-python in the 'owl' virtual environment...
[OK] Installing opencv-contrib-python completed successfully.
[OK] Final check: NumPy 1.24.2, OpenCV 4.9.0
[INFO] Installing the OWL Python dependencies...
[OK] Installing dependencies from requirements.txt completed successfully.

Service and desktop setup:

[INFO] Setting up OWL to start on boot with systemd...
[INFO] Creating systemd service for OWL...
[INFO] Starting OWL service...
[OK] OWL systemd service is active
[OK] Creating OWL systemd service completed successfully.
[INFO] Setting desktop background...
[OK] Setting desktop background completed successfully.
[INFO] Creating OWL Focusing desktop icon...
[OK] Creating desktop icon completed successfully.

Dashboard setup (if selected):

[INFO] Setting up OWL Dashboard...
[INFO] Installing dashboard Python dependencies...
[OK] Installing dashboard Python dependencies completed successfully.
[INFO] Verifying Python package installations...
[OK] Flask: 3.0.0, Gunicorn: 21.2.0, Paho-MQTT: installed
[OK] Verifying Python dependencies completed successfully.

After the dashboard dependencies install, the controller/shared/setup.sh script runs automatically. See the Standalone or Networked pages for what happens next.

If any steps show [FAIL]

The summary will show error details. Review the specific error and re-run the installer:

cd ~/owl
bash owl_setup.sh

If only the dashboard setup needs re-running:

sudo bash ~/owl/controller/shared/setup.sh

If OWL is already running

If you’re re-running the installer and owl.service is already active, you’ll be prompted to stop it first. Enter y to continue.

After installation¶

Focus your camera¶

Proper focus is critical for accurate weed detection.

If you said y to the focusing prompt at the end of installation, the focus tool is already running. Otherwise, start it using the Focus desktop icon, or from the command line:

~/owl/./owl.py --focus

Point the camera at vegetation or a focus target
Observe the sharpness value displayed on screen
Slowly rotate the lens focus ring to find the highest sharpness value
Lock the focus ring (if your lens has a lock screw)

Tip

For field deployment, focus at your typical operating distance (usually 0.9 m for 1 m wide coverage).

Verify the installation¶

# Check the OWL detection service is running
sudo systemctl status owl.service

# Check the dashboard service (Standalone only)
sudo systemctl status owl-dash

# View live detection logs
journalctl -u owl.service -f

# Run with on-screen display for testing
~/owl/./owl.py --show-display

Next steps¶

Set up your dashboard

If you chose Standalone or Networked mode during installation, continue with your dashboard setup:

Standalone Setup — WiFi hotspot with local dashboard
Networked Setup — Join existing network with central controller