Detailed Installation¶

This setup approach may take longer (~60 minutes) but you’ll be better prepared for problem solving, upgrades or changes. Use this if you want to understand what’s happening under the hood.

Prefer the automated installer?

The Two-Step Install automates all of these steps and takes ~10 minutes.

Step 1: Raspberry Pi Setup¶

Step 1a - Raspberry Pi OS¶

Before powering up the Raspberry Pi, you’ll need to install the Raspbian operating system on the SD card.

From your own computer, download and flash the latest 64-bit version of Raspbian from the official Raspberry Pi website to the empty SD card. The official Raspberry Pi Imager is recommended.

Configuration during flashing:

Leave the hostname as default
Set the username to owl
Choose a password
Optionally specify WiFi network settings

Raspberry Pi Imager	Configuring the OWL

Step 1b - Setting up the OWL¶

Once the Raspbian OS has been flashed to the SD Card (may take 5-10 minutes), remove the SD card and insert it into the Raspberry Pi. Connect the screen, keyboard and mouse and then power up the Pi.

Alternatively, you can SSH into your OWL from a separate device and install it remotely. A good guide on how to do that is available here.

First boot¶

On the first boot you may be asked to set country, timezone, keyboard, connect to WiFi and look for updates. If you haven’t already set the username, set it to owl and choose a password. Uninstall the unused browser - this will save space on the Pi. Finally, you will be asked to restart the Pi.

Opening terminal¶

After the restart, open up Terminal. You can press CTRL + ALT + T, or click the icon in the top left with the >_ symbol.

Terminal Commands

All commands below are provided for easy copy/paste. When using terminal you should see owl@raspberrypi:~ $ at the start of each line and (owl) owl@raspberrypi:~ $ when operating within the owl virtual environment. Pay close attention to the presence/absence of (owl) in front of each line.

Requirements:

Raspberry Pi
Empty SD Card (SanDisk 32GB SDXC recommended)
Your own computer with SD card reader
Power supply (if not using the OWL unit)
Screen and keyboard
WiFi/Ethernet cable

Step 2: Manual Installation¶

Free up space¶

The Raspberry Pi comes pre-installed with software that can be removed to free up space. These commands use sudo because they modify system packages:

sudo apt-get purge wolfram-engine

sudo apt-get purge libreoffice*

sudo apt-get clean

Set up the virtual environment¶

A virtual environment contains all the necessary packages in one neat spot. We’ll use virtualenv and virtualenvwrapper.

Update the system:

sudo apt update && sudo apt full-upgrade

Add environment configuration to .bashrc:

echo "# virtualenv and virtualenvwrapper" >> ~/.bashrc

echo "export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python" >> ~/.bashrc

source ~/.bashrc

Install virtualenv packages:

sudo apt-get install python3-virtualenv

sudo apt-get install python3-virtualenvwrapper

Add more configuration:

echo "export WORKON_HOME=$HOME/.virtualenvs" >> ~/.bashrc

echo "source /usr/share/virtualenvwrapper/virtualenvwrapper.sh" >> ~/.bashrc

source ~/.bashrc

Create the owl environment:

mkvirtualenv --system-site-packages -p python owl

The command line should now look like (owl) owl@raspberrypi:~ $. The (owl) means you’re in the virtual environment. Use deactivate to exit and workon owl to re-enter.

Installing packages¶

Virtual Environment Required

The (owl) prefix MUST be present at the start of each line for this section. Run workon owl if unsure.

Ensure you’re in the owl environment:

workon owl

Install OpenCV using pip:

pip3 install opencv-contrib-python

Verify the installation:

python

>>> import cv2
>>> import picamera2
>>> exit()

Downloading the OWL repository¶

Change to the home directory:

cd ~

Clone the repository:

git clone https://github.com/geezacoleman/OpenWeedLocator owl

Verify with ls - you should see the owl folder.

Installing OWL Python dependencies¶

The OWL requires these packages:

OpenCV (already installed)
numpy
gpiozero
pandas
RPi.GPIO
tqdm
blessed
matplotlib
Pillow
ultralytics (YOLO object detection)
ncnn (neural network inference on ARM)

Change to the owl directory:

cd ~/owl

Install all requirements:

pip install -r requirements.txt

Verify the installation:

python

>>> import cv2
>>> import numpy
>>> import gpiozero
>>> import pandas
>>> exit()

Starting OWL on boot¶

OWL uses systemd to start automatically on boot. The setup script (owl_setup.sh) creates the service for you during installation.

If you installed manually, run the shared setup script to create the systemd service:

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

This creates owl.service which starts the detection pipeline automatically on every boot.

Useful commands:

# Check if OWL is running
sudo systemctl status owl.service

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

# Stop OWL
sudo systemctl stop owl.service

# Restart OWL
sudo systemctl restart owl.service

# Disable auto-start on boot
sudo systemctl disable owl.service

Step 3: Focusing the Camera¶

Automatic Focus Cameras

Cameras with automatic focus such as the Raspberry Pi Camera Module 3 will be automatically focused to 1.2m distance. This guide is for the HQ and Global Shutter cameras which require manual focusing.

Run the focus command:

owl.py --focus

A sharpness estimation is provided on the video feed. The higher the value, the better the focus.

Blurry Image	Clear Image

Manual focusing (older software)¶

If needed, stop the background process first:

ps -C owl.py

Note the PID (process ID) from the output, then stop it:

sudo kill <PID>

Launch with display:

~/owl/./owl.py --show-display

Press Esc to exit when focusing is complete.

Step 4: Final Reboot¶

Shut down the Raspberry Pi and unplug the power. Reconnect the camera and all GPIO pins/power. Double check the camera cable is inserted, then reconnect power and wait for a beep.

If you hear a beep, test with something green under the camera. If the relays start clicking, congratulations - your OWL is working!

Lighting Conditions

The unit does not perform well under office/artificial lighting. The thresholds have been set for outdoor conditions.

Optional: RTC Module Setup¶

For RTC (Real Time Clock) module setup, follow the Adafruit instructions. The RTC uses a CR1220 button cell battery and connects to GPIO pins 1-6.

Next Steps¶

Set up your dashboard

After installation, set up your dashboard for remote monitoring and control:

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