Glossary¶

A reference for terminal commands, Linux concepts, and OWL-specific terms. If you’re new to the command line or Raspberry Pi, start here.

Terminal Basics¶

The terminal (also called the command line) is a text-based interface for controlling your Raspberry Pi. Instead of clicking icons, you type commands and press Enter.

Opening a terminal:

If you have a screen and keyboard connected, press CTRL + ALT + T or click the >_ icon in the taskbar.
If connecting remotely, use SSH from another computer.

What the prompt looks like:

owl@raspberrypi:~ $

This tells you:

owl — your username
raspberrypi — the hostname of the Pi
~ — your current directory (home folder)
$ — ready for a command

When you see (owl) at the start:

(owl) owl@raspberrypi:~ $

The (owl) prefix means the OWL virtual environment is active. Many installation commands require this — if it’s missing, run workon owl to activate it.

Essential Commands¶

cat¶

Display file contents. Prints the entire contents of a file to the terminal.

cat config.ini

cd¶

Change directory. Moves you into a different folder.

cd ~/owl        # go to the owl folder
cd ..           # go up one level
cd ~            # go to your home folder

chmod¶

Change file permissions. Controls who can read, write, or execute a file.

chmod a+x owl.py       # make owl.py executable by everyone

ls¶

List files. Shows the files and folders in your current directory.

ls              # list contents
ls -la          # show hidden files and details

nano¶

Text editor. A simple terminal-based editor for modifying files. Save with Ctrl + X, then Y, then Enter.

nano config.ini
sudo nano /etc/hosts

pip / pip3¶

Python package installer. Installs Python libraries. Inside a virtual environment, pip and pip3 are interchangeable.

pip install opencv-contrib-python
pip install -r requirements.txt

pwd¶

Print working directory. Shows the full path of where you are right now.

reboot¶

Restart the Raspberry Pi. Usually run with sudo.

sudo reboot

source¶

Reload shell configuration. Re-reads a configuration file (like .bashrc) without restarting the terminal.

source ~/.bashrc

sudo¶

Superuser do. Runs a command with administrator privileges. Required for system-level changes like installing software or managing services.

sudo apt update
sudo systemctl restart owl.service

Git Commands¶

Git is a version control system. For the OWL, you mainly use it to download and update the software.

git clone¶

Download a repository. Copies the entire OWL codebase from GitHub to your Pi.

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

git pull¶

Update to the latest version. Downloads the newest changes from GitHub into your existing copy.

cd ~/owl
git pull

Linux & Raspberry Pi Concepts¶

.bashrc¶

Shell configuration file. A script that runs every time you open a terminal. Used to set up environment variables and the virtual environment.

crontab¶

Scheduled tasks. A legacy system for running commands on events like startup. (OWL now uses systemd services for automatic startup — see the install guide.)

sudo crontab -e                      # edit the root cron schedule

File paths¶

Locations on disk are written as paths separated by /:

~/owl/ — the OWL folder in your home directory
/etc/ — system configuration files
/home/owl/ — your full home directory path

Home directory¶

Your personal folder, represented by ~. For the owl user, this is /home/owl/. When you open a terminal, you start here.

journalctl¶

View service logs. Shows output and error messages from systemd services.

journalctl -u owl.service -f        # follow OWL logs in real time

Permissions¶

Linux controls who can read, write, or run files. Use sudo to run commands as administrator, and chmod to change file permissions.

systemd¶

The service manager on modern Linux. It handles starting, stopping, and monitoring background programs (called services).

sudo systemctl start owl.service     # start the OWL
sudo systemctl stop owl.service      # stop the OWL
sudo systemctl status owl.service    # check if it's running
sudo systemctl enable owl.service    # start automatically on boot

Virtual environment¶

An isolated copy of Python packages, separate from the system Python. Prevents conflicts between different projects. The OWL uses a virtual environment called owl.

Activate: workon owl
Deactivate: deactivate
When active, you see (owl) at the start of the prompt.

Networking Concepts¶

Firewall¶

Software that controls which network connections are allowed. The OWL uses UFW (Uncomplicated Firewall) to open only the ports it needs.

Gateway¶

The device (usually a router) that connects your local network to the internet or other networks.

IP address¶

A number that identifies a device on a network (e.g. 192.168.4.1). Each device on the same network has a unique IP address.

mDNS¶

Multicast DNS. Lets you use friendly names like owl.local instead of IP addresses. Powered by the Avahi service on the Pi.

Ports¶

Numbered channels for network traffic. Key ports used by the OWL:

1883 — MQTT messaging
443 — HTTPS (dashboard)
80 — HTTP (redirects to HTTPS)

SSH¶

Secure Shell. A way to control your Raspberry Pi remotely from another computer’s terminal. Requires the Pi’s IP address and your password.

ssh owl@192.168.4.1
ssh owl@owl.local

SSID¶

The name of a WiFi network. The OWL’s default hotspot name is OWL.

SSL certificate¶

A security certificate that encrypts web traffic (HTTPS). The OWL dashboard uses a self-signed certificate, so your browser may show a warning — this is normal and safe to proceed through.

Static IP¶

An IP address that doesn’t change. The OWL sets a static IP so you can always find it at the same address.

Subnet¶

A range of IP addresses that form a local network. Devices on the same subnet can talk to each other directly.

WiFi hotspot¶

A wireless access point created by the OWL itself. In Standalone mode, the OWL broadcasts its own WiFi network you can connect to from a phone or laptop.

OWL-Specific Terms¶

Avahi¶: A service that provides mDNS, allowing you to reach the OWL at owl.local instead of an IP address.
ByteTrack¶: A multi-object tracking algorithm that assigns persistent IDs to detected weeds across video frames. Used in Green-on-Green mode for class smoothing and crop mask stabilisation.
CONTROLLER.ini¶: Infrastructure configuration for MQTT, network mode, GPS, and web dashboard. Created by the setup script. Located at ~/owl/config/CONTROLLER.ini.
Dashboard¶: The web-based control panel for monitoring and adjusting your OWL. Access it from a browser on your phone, tablet, or computer.
ExG¶: Excess Green Index. A vegetation detection algorithm that emphasises green pixels. The default detection method for the OWL.
ExHSV¶: Excess Green minus Excess Red, in HSV colour space. An alternative detection algorithm.
GENERAL_CONFIG.ini¶: The main OWL configuration file. Contains detection parameters, camera settings, sensitivity presets, tracking, and GPIO relay mappings. Located at ~/owl/config/GENERAL_CONFIG.ini.
GPIO¶: General Purpose Input/Output. Physical pins on the Raspberry Pi used to control external hardware like relays and solenoids.
Gunicorn¶: Green Unicorn. A Python web server that runs the Flask dashboard application behind Nginx.
HSV¶: Hue, Saturation, Value. A colour model used by some detection algorithms. Allows filtering by colour ranges rather than simple green intensity.
Mosquitto¶: The MQTT broker software installed on the OWL. Handles message routing between OWL units and the dashboard.
MQTT¶: Message Queuing Telemetry Transport. A lightweight messaging protocol used for communication between OWL units and the dashboard. Messages are published to topics and received by subscribers.
MQTT broker¶: The central message server. In Standalone mode, the broker runs on the OWL itself (Mosquitto). In Networked mode, it runs on a central controller.
MQTT topics¶: Named channels for messages. For example, the OWL publishes detection data to specific topics that the dashboard subscribes to.
NCNN¶: A neural network inference framework optimised for ARM CPUs. The recommended model format for running YOLO on Raspberry Pi. Models consist of a .param and .bin file pair.
Nginx¶: A web server used as a reverse proxy for the OWL dashboard. Handles HTTPS encryption and forwards requests to Gunicorn.
NumPy¶: A Python library for numerical computing. Used by OpenCV for image processing. Must be version-aligned between the system and virtual environment.
OpenCV¶: Open Computer Vision. The image processing library that powers weed detection. Installed in the OWL virtual environment.
owl-dash.service¶: The systemd service that runs the web dashboard (Gunicorn + Flask). Only present after Standalone or Networked setup.
owl.service¶: The systemd service that runs the main OWL detection program. Starts automatically on boot.
Relay¶: An electrically operated switch. The OWL activates relays via GPIO pins to trigger solenoid valves for spot spraying.
Solenoid¶: An electrically activated valve that controls liquid flow. Connected to the OWL via relays and GPIO pins.
YOLO¶: You Only Look Once. An object detection model architecture used for Green-on-Green weed detection. Trained with the Ultralytics framework and exported to NCNN format for deployment on Raspberry Pi.