Configuration Guide¶

OWL uses two configuration files to separate detection settings from infrastructure settings. Both are standard INI files that can be edited with any text editor or adjusted through the web dashboard.

Config File Overview¶

File	Location	Purpose
`GENERAL_CONFIG.ini`	`~/owl/config/`	Detection parameters, camera, sensitivity presets, tracking, relay mapping
`CONTROLLER.ini`	`~/owl/config/`	MQTT, network mode, GPS, web dashboard, actuation timing

An active_config.txt file in the same directory points to the current detection config (defaults to config/GENERAL_CONFIG.ini).

Copy-on-write protection

GENERAL_CONFIG.ini and CONTROLLER.ini are protected defaults. When changes are made through the dashboard, a timestamped copy is created automatically (e.g. GENERAL_CONFIG_20260318_1430.ini) so the originals are never corrupted.

Sensitivity Presets¶

Instead of separate config files for each sensitivity level, OWL embeds sensitivity presets directly in GENERAL_CONFIG.ini:

[Sensitivity]
active = medium

[Sensitivity_Low]
exg_min = 25
exg_max = 200
hue_min = 41
hue_max = 80
...

[Sensitivity_Medium]
exg_min = 25
exg_max = 200
hue_min = 39
hue_max = 83
...

[Sensitivity_High]
exg_min = 22
exg_max = 210
hue_min = 35
hue_max = 85
...

Each preset stores the 9 GreenOnBrown threshold values. The [Sensitivity] active key determines which preset is loaded at startup. You can switch presets from the dashboard, the wired controller sensitivity switch, or the AI assistant.

Custom presets can be saved from the dashboard and are stored as additional [Sensitivity_YourName] sections in the config file.

Changing Settings¶

There are several ways to adjust OWL settings:

Dashboard sliders (recommended): The web dashboard provides range sliders for all detection parameters. Changes take effect immediately and are persisted to the config file.
AI assistant: Open the Agent tab in the dashboard and describe what you want in plain language — e.g. “make detection more sensitive” or “switch to the exg algorithm”. See the AI Assistant guide.
Direct INI editing: Edit the config file directly with a text editor:

nano ~/owl/config/GENERAL_CONFIG.ini

Save the file and restart OWL for changes to take effect.

Command line flags: Override the config file or enable display mode at startup:

# Use a specific config file
python owl.py --config config/my_custom.ini

# Show display for threshold adjustment
python owl.py --show-display

# Camera focus mode
python owl.py --focus

# Process a video or image directory
python owl.py --input path/to/media

Complete GENERAL_CONFIG.ini Template¶

[System]
algorithm = exhsv
input_file_or_directory =
relay_num = 4
actuation_duration = 0.15
delay = 0
actuation_zone = 100

[Controller]
controller_type = none
status_led_pin = 40
gps_led_pin = 38
switch_purpose = recording
switch_pin = 36
detection_mode_pin_up = 36
detection_mode_pin_down = 35
recording_pin = 33
sensitivity_pin = 32

[Visualisation]
image_loop_time = 5

[Camera]
resolution_width = 1456
resolution_height = 1088
exp_compensation = -2
crop_factor_horizontal = 0.02
crop_factor_vertical = 0.02
camera_type = auto

[GreenOnGreen]
model_path = models
confidence = 0.5
detect_classes =
actuation_mode = centre
min_detection_pixels = 50
inference_resolution = 320
crop_buffer_px = 20

[GreenOnBrown]
exg_min = 25
exg_max = 200
hue_min = 39
hue_max = 83
saturation_min = 50
saturation_max = 220
brightness_min = 60
brightness_max = 190
min_detection_area = 10
invert_hue = False

[DataCollection]
image_sample_enable = False
detection_enable = True
sample_method = whole
sample_frequency = 30
save_directory = /media/owl/SanDisk
log_fps = False
camera_name = cam1

[Relays]
0 = 13
1 = 15
2 = 16
3 = 18

[Tracking]
tracking_enabled = False
track_class_window = 5
track_crop_persist = 3

[Sensitivity]
active = medium

[Sensitivity_Low]
exg_min = 25
exg_max = 200
hue_min = 41
hue_max = 80
saturation_min = 52
saturation_max = 218
brightness_min = 62
brightness_max = 188
min_detection_area = 20

[Sensitivity_Medium]
exg_min = 25
exg_max = 200
hue_min = 39
hue_max = 83
saturation_min = 50
saturation_max = 220
brightness_min = 60
brightness_max = 190
min_detection_area = 10

[Sensitivity_High]
exg_min = 22
exg_max = 210
hue_min = 35
hue_max = 85
saturation_min = 40
saturation_max = 225
brightness_min = 50
brightness_max = 200
min_detection_area = 5

Complete CONTROLLER.ini Reference¶

[MQTT]
enable = True
broker_ip = localhost
broker_port = 1883
device_id = auto

[WebDashboard]
port = 8000

[Network]
mode = networked
static_ip = localhost
controller_ip = localhost

[GPS]
# GPS data source (none / serial / tcp / gpsd)
source = none
# Serial device path and baud (only used when source = serial)
port = /dev/ttyACM0
baudrate = 9600
# TCP listener (only when source = tcp). `enable = True` is a deprecated
# back-compat alias for `source = tcp`.
enable = False
nmea_port = 8500
# Session / coverage tracking (applies to every non-none source)
boom_width = 12.0
track_save_directory = tracks

[Actuation]
# Relay timing — used as fallback when no GPS speed data
actuation_duration = 0.15
delay = 0.0
# Speed-adaptive actuation geometry (networked controller)
actuation_length_cm = 10
offset_cm = 30
speed_avg_window = 5.0

Parameter Reference — GENERAL_CONFIG.ini¶

System¶

Parameter	Default	Description
`algorithm`	`exhsv`	Detection algorithm: `exg`, `exgr`, `maxg`, `nexg`, `exhsv`, `hsv`, `gndvi`, `gog`, `gog-hybrid`
`input_file_or_directory`	(empty)	Path to image, video, or directory for offline processing. Leave empty for live camera.
`relay_num`	`4`	Number of relay lanes (1-4).
`actuation_duration`	`0.15`	Relay activation time in seconds.
`delay`	`0`	Delay between detection and actuation in seconds.
`actuation_zone`	`100`	Percentage of the frame width used for relay lane mapping (1-100).

Controller¶

Parameter	Default	Description
`controller_type`	`none`	Wired controller type: `none`, `ute`, or `advanced`.
`status_led_pin`	`40`	BOARD pin for status indicator LED (shared by Ute and Advanced).
`gps_led_pin`	`38`	BOARD pin for GPS status LED (shared by Ute and Advanced).
`switch_purpose`	`recording`	Ute controller switch function: `recording` or `detection`.
`switch_pin`	`36`	BOARD pin for Ute controller toggle switch. Avoid BOARD 37 if using Sixfab HAT.
`detection_mode_pin_up`	`36`	BOARD pin for detection mode up (Advanced controller).
`detection_mode_pin_down`	`35`	BOARD pin for detection mode down (Advanced controller).
`recording_pin`	`33`	BOARD pin for recording toggle (Advanced controller).
`sensitivity_pin`	`32`	BOARD pin for sensitivity switch (Advanced controller).

Camera¶

Parameter	Default	Description
`resolution_width`	`1456`	Camera capture width in pixels.
`resolution_height`	`1088`	Camera capture height in pixels.
`exp_compensation`	`-2`	Exposure compensation (-8 to 8). Negative values give faster shutter speed.
`crop_factor_horizontal`	`0.02`	Fraction of width to crop from each side (0.0-0.5).
`crop_factor_vertical`	`0.02`	Fraction of height to crop from each side (0.0-0.5).
`camera_type`	`auto`	Camera selection: `auto` (auto-detect), `rpi` (force Pi camera), `usb` (force USB webcam).
`allow_high_resolution`	`False`	Bypass the Pi 3/4 832x640 safety clamp. Leave `False` unless you’ve verified your hardware handles the target resolution.

Setting the resolution¶

Resolution can be changed two ways — pick whichever fits your workflow.

Dashboard Config tab. Open the dashboard → CONFIG tab → Camera section → Resolution dropdown. The dropdown offers the supported presets (1456x1088, 1280x960, 1280x720, 1024x768, 800x600, 640x480, 416x320, 320x240) and writes both resolution_width and resolution_height to the active config in a single step. Changes are persisted via the copy-on-write mechanism described above.

Direct INI editing. Set resolution_width and resolution_height independently under [Camera], then restart OWL for the change to take effect. This route is fine when you’re already editing the file for other reasons, or when you need a resolution outside the dashboard preset list.

Pi 3 / Pi 4 safety clamp

On the Raspberry Pi 3 and Pi 4, requests above 832x640 are silently clamped to 640x480. Older Pi models are known to lock up at higher resolutions, and the clamp prevents bricked devices in the field.

To override the clamp, set [Camera] allow_high_resolution = True — but only after verifying that the specific Pi hardware in front of you actually copes with the resolution you’re requesting. The dashboard surfaces an active clamp via a banner in the Camera section.

The Pi 5 is not affected by the clamp.

Visualisation¶

Parameter	Default	Description
`image_loop_time`	`5`	Seconds between display frame updates when using `--show-display`.

GreenOnGreen¶

Parameter	Default	Description
`model_path`	`models`	Directory containing YOLO model files (NCNN or PyTorch).
`confidence`	`0.5`	Minimum confidence threshold for detections (0.0-1.0).
`detect_classes`	(empty)	Comma-separated class IDs to detect. Empty means all classes.
`actuation_mode`	`centre`	How detections map to relays: `centre` (bounding box centre) or `zone` (segmentation mask pixel count, requires seg model).
`min_detection_pixels`	`50`	Minimum pixel count for valid segmentation detections (zone mode).
`inference_resolution`	`320`	Input image size for YOLO inference. Smaller is faster, larger is more accurate.
`crop_buffer_px`	`20`	Pixel buffer added around crop mask regions (gog-hybrid mode).

GreenOnBrown¶

Parameter	Default	Description
`exg_min`	`25`	Minimum Excess Green threshold (0-255). Lower = more sensitive.
`exg_max`	`200`	Maximum Excess Green threshold (0-255). Keep above 180.
`hue_min`	`39`	Minimum hue threshold (0-179). Green vegetation is typically 39-83.
`hue_max`	`83`	Maximum hue threshold (0-179).
`saturation_min`	`50`	Minimum saturation threshold (0-255).
`saturation_max`	`220`	Maximum saturation threshold (0-255).
`brightness_min`	`60`	Minimum brightness threshold (0-255).
`brightness_max`	`190`	Maximum brightness threshold (0-255).
`min_detection_area`	`10`	Minimum pixel area for a valid detection. Increase to ignore small noise.
`invert_hue`	`False`	When True, detects colours outside the hue range instead of inside. Useful for detecting non-green targets.

DataCollection¶

Parameter	Default	Description
`image_sample_enable`	`False`	Enable image data collection to USB drive.
`detection_enable`	`True`	Enable weed detection and relay actuation. Set False for data collection only.
`sample_method`	`whole`	Image sampling method: `bbox` (bounding boxes only), `square` (square crops), `whole` (full frame).
`sample_frequency`	`30`	Save an image every N frames.
`save_directory`	`/media/owl/SanDisk`	Directory for saved images. Typically a USB drive mount point.
`log_fps`	`False`	Log frame processing times to file.
`camera_name`	`cam1`	Camera identifier used in saved file names.

Tracking¶

Parameter	Default	Description
`tracking_enabled`	`False`	Enable ByteTrack multi-object tracking for persistent weed IDs across frames.
`track_class_window`	`5`	Number of frames to smooth class predictions over. Reduces class flickering.
`track_crop_persist`	`3`	Number of frames a crop mask region persists after the crop leaves frame (gog-hybrid mode).

Relays¶

Parameter	Description
`0 = 13`	Relay 0 maps to GPIO board pin 13
`1 = 15`	Relay 1 maps to GPIO board pin 15
`2 = 16`	Relay 2 maps to GPIO board pin 16
`3 = 18`	Relay 3 maps to GPIO board pin 18

Sensitivity¶

Parameter	Default	Description
`active`	`medium`	Active sensitivity preset name. Built-in presets: `low`, `medium`, `high`. Custom presets can be saved from the dashboard.

Parameter Reference — CONTROLLER.ini¶

MQTT¶

Parameter	Default	Description
`enable`	`True`	Enable MQTT communication with the dashboard.
`broker_ip`	`localhost`	MQTT broker IP address. `localhost` for standalone, controller IP for networked.
`broker_port`	`1883`	MQTT broker port.
`device_id`	`auto`	Unique device identifier. `auto` generates from hostname.

WebDashboard¶

Parameter	Default	Description
`port`	`8000`	Gunicorn listening port (behind Nginx reverse proxy).

Network¶

Parameter	Default	Description
`mode`	`networked`	Network mode: `standalone` (creates WiFi hotspot) or `networked` (joins existing network).
`static_ip`	`localhost`	Static IP for the OWL on the network.
`controller_ip`	`localhost`	IP address of the networked controller (networked mode only).

GPS¶

The networked controller supports four GPS input modes, selected via the source key. Pick whichever matches your hardware — only the keys relevant to your chosen source are read.

Parameter	Default	Description
`source`	`none`	GPS data source. One of: `none` (disabled), `serial` (USB/UART device on this Pi), `tcp` (NMEA pushed over TCP, e.g. from a Teltonika router), or `gpsd` (read from the local `gpsd` daemon on `localhost:2947`).
`port`	`/dev/ttyACM0`	Serial device path (used when `source = serial`, also passed to `gpsd` as its `DEVICES` hint). Ublox USB dongles enumerate as `/dev/ttyACM0`; CP2102/CH340 adapters as `/dev/ttyUSB0`; Pi primary UART is `/dev/ttyAMA0` (or `/dev/serial0` on Bookworm). To find yours: `ls /dev/ttyACM* /dev/ttyUSB*` after plugging in the GPS.
`baudrate`	`9600`	Serial link speed (used when `source = serial`). Ublox factory default is 9600; Sixfab GNSS HAT and some marine modules use 115200. Wrong baud = silent failure (garbled unicode in the log).
`enable`	`False`	DEPRECATED. Kept as a back-compat alias: if `source = none` and `enable = True`, the controller behaves as if `source = tcp`. New configs should set `source` directly.
`nmea_port`	`8500`	TCP port the controller listens on when `source = tcp`. Configure your router to forward NMEA to `<controller-ip>:<nmea_port>`. Port 8500 is pre-opened in the UFW firewall rules.
`boom_width`	`12.0`	Spray boom width in metres. Used to convert distance into hectares: `area_ha = distance_km × boom_width_m / 10`.
`track_save_directory`	`tracks`	Directory (relative to project root) where session GeoJSON track files are written as `track_YYYY-MM-DD_HHMMSS.geojson`. Files are never auto-deleted — monitor disk on long-running kiosks.

The GPS tab in the dashboard renders these breadcrumbs on a Leaflet map (OpenStreetMap tiles when online, dark grid fallback when offline) with a HDOP-coloured current-position marker and Centre/Fit-all controls.

Actuation¶

Parameter	Default	Description
`actuation_duration`	`0.15`	Relay activation time in seconds (fallback when no GPS speed data).
`delay`	`0.0`	Delay between detection and actuation in seconds.
`actuation_length_cm`	`10`	Physical spray patch length in cm (speed-adaptive calculation).
`offset_cm`	`30`	Distance from camera to nozzle in cm (speed-adaptive calculation).
`speed_avg_window`	`5.0`	Time window in seconds for GPS speed averaging.

Next Steps¶

Controller Setup - Build a controller for managing OWLs
Green-on-Green - In-crop weed detection using YOLO
AI Assistant - Control OWL through natural language
Troubleshooting - Common issues and solutions