Troubleshooting

This guide covers common issues and solutions for both software and hardware problems with the OWL system.

Report Issues

If you encounter an error that isn’t covered here, please raise an issue on GitHub so we can update this guide and improve the error handling.

Software Errors

The table below includes all current error classes and their hierarchy. All errors include detailed logging, color-formatted terminal output, and standardized error handling. When encountering an error, check the terminal output for specific guidance.

OWLError

Base exception for all OWL-related errors.

Error

Common Causes

Solutions

CameraNotFoundError

Disconnected camera, damaged ribbon cable, camera not enabled

1. Check camera connections
2. Run vcgencmd get_camera
3. Enable camera in raspi-config

OWLAlreadyRunningError

Another OWL instance active, GPIO pins in use

1. Use kill <PID> to stop process
2. Check for zombie processes
3. Reboot if persists

StorageError

Base class for storage-related errors.

Error

Common Causes

Solutions

USBMountError

Device not properly mounted, permission issues

1. Check physical connection
2. Verify mount points
3. Check device permissions

USBWriteError

Write-protected device, full storage, permission issues

1. Check write protection
2. Verify available space
3. Check file permissions

NoWritableUSBError

No USB storage detected, all devices write-protected

1. Connect USB device
2. Check write protection
3. Format device if needed

StorageSystemError

Incompatible platform for storage operation

1. Use Linux/Raspberry Pi
2. Specify a valid local directory in config
3. Use --save-directory flag

OWLControllerError

Base class for controller-related errors.

Error

Common Causes

Solutions

ControllerPinError

Pin conflicts, invalid pin numbers, hardware issues

1. Check pin configurations
2. Verify physical connections
3. Check for conflicts

ControllerConfigError

Missing or invalid configuration

1. Check config file
2. Add missing settings
3. Ensure values are appropriate

OWLConfigError

Base class for configuration errors.

Error

Common Causes

Solutions

ConfigFileError

Missing config file, invalid file path, corrupt file

1. Verify file exists
2. Check file permissions
3. Validate file contents

ConfigSectionError

Missing required sections in config file

1. Add missing sections to the config file

ConfigKeyError

Missing required keys in a section

1. Add missing keys to the respective config section

ConfigValueError

Invalid configuration values

1. Correct values to fit expected ranges

Other Errors

Error

Common Causes

Solutions

AlgorithmError

Missing dependencies, invalid model files, AI accelerator issues

1. Install required packages
2. Verify model files
3. Check AI accelerator (AI Hat+) connection

OpenCVError

OpenCV not installed, wrong virtual environment

1. Run workon owl
2. Install opencv-python
3. Run owl_setup.sh

DependencyError

Missing Python packages, wrong virtual environment

1. Activate owl environment
2. Run pip install for package
3. Install from requirements.txt

Hardware Issues

Common symptoms and explanations for hardware-related errors.

Update Your Software

If you are using the original disk image without updating, there may be issues that have been fixed. We recommend updating to the latest software using bash ~/owl/owl_update.sh.

Symptom

Explanation

Solution

Pi won’t start (no green/red lights)

No power getting to the computer

Check the power source and all downstream components: Bulgin panel/plug connections, fuse connections and fuse, connections to Wago 2-way block, voltage regulator connections, cable into the Raspberry Pi

Pi starts (green light flashing) but no beep

OWL software has not started

This is likely a configuration/camera connection error. Boot the Pi with a screen connected, open a Terminal (Ctrl + T) and run ~/owl/./owl.py to see any errors

Beep heard, but no relays activating

Relays not receiving 12V power, or signal from Pi, or Pi not sending signal

Check all connections with a multimeter for 12V presence. Verify wiring matches the diagram. If connections are correct, run ~/owl/./owl.py in Terminal to check for errors

Diagnostic Commands

Check Camera

# Check camera is detected
vcgencmd get_camera

# Test camera capture (libcamera)
libcamera-still -o test.jpg

Check OWL Process

# Check if OWL is running
ps -C owl.py

# Kill existing OWL process
sudo kill <PID>

# View OWL logs
journalctl -u owl -f

Check Virtual Environment

# Activate OWL environment
workon owl

# Verify packages
pip list | grep opencv
python -c "import cv2; print(cv2.__version__)"

Check Services

# Check OWL service status
systemctl status owl

# Check dashboard service
systemctl status owl-dash

# Check MQTT broker
systemctl status mosquitto

Check GPIO

# Check GPIO pin states
gpio readall

# Test relay manually (in Python)
python3 -c "from gpiozero import LED; r = LED(13); r.on(); input('Press Enter'); r.off()"

Common Fixes

Restart OWL Service

sudo systemctl restart owl

Reboot System

sudo reboot

Reset Configuration

# Backup current config
cp ~/owl/config/DAY_SENSITIVITY_2.ini ~/owl/config/DAY_SENSITIVITY_2.ini.backup

# Copy default config
cp ~/owl/config/DAY_SENSITIVITY_2.ini.default ~/owl/config/DAY_SENSITIVITY_2.ini

Reinstall Dependencies

workon owl
pip install -r ~/owl/requirements.txt

Update OWL Software

bash ~/owl/owl_update.sh

Getting Help

If you’re still experiencing issues:

  1. Check the terminal output - Run ~/owl/./owl.py directly to see detailed error messages

  2. Search existing issues - Check GitHub Issues for similar problems

  3. Ask the community - Post in the OWL Community

  4. Report a bug - Create a new issue with:

    • Error message (full text)

    • Steps to reproduce

    • OWL version (git log -1 in owl directory)

    • Raspberry Pi model

Next Steps