TWFarmBot

FarmBot implementation at UAS Technikum Wien — an open research platform for autonomous, AI-assisted precision farming.

---

What is TWFarmBot?

TWFarmBot is a modular, service-oriented control system for a FarmBot research installation. It connects the physical robot to modern AI services — computer vision, large-language-model planning, sensor fusion and safety validation — while keeping student projects and experiments isolated from core infrastructure.

The repository is a monorepo split into apps, services, shared core libraries, student projects and reproducible experiments.

Quick start

This is a uv workspace. After cloning:

# Install all packages and create the virtual environment
uv sync

# Start the API server
uv run twfarmbot-api

# In another terminal, start the dashboard
uv run twfarmbot-ui

# Or start the local ReSiReg-Mini vision server
uv run resireg-server

Open the UI at http://localhost:8501, the API docs at http://localhost:8000/docs, and the ReSiReg server at http://localhost:8080.

Running as services (auto-start + auto-restart)

Install the systemd user services once:

./scripts/install_services.sh
# Then, so services start at boot before anyone logs in:
sudo loginctl enable-linger farmbot

Start, stop, or restart everything:

./scripts/start_all.sh
./scripts/stop_all.sh
./scripts/restart_all.sh

View live logs:

./scripts/logs.sh
# or for a single service:
journalctl --user -u twfarmbot-api -f

Each service restarts automatically on failure. To disable auto-start on boot:

systemctl --user disable twfarmbot-resireg twfarmbot-api twfarmbot-ui

Continuous Integration

Every push and pull request is checked by GitHub Actions:

Workflow	File	Purpose
Pylint	.github/workflows/pylint.yml	Static analysis with Pylint
Ruff	.github/workflows/ruff.yml	Formatting and linting with Ruff
Mypy	.github/workflows/mypy.yml	Static type checking
Tests	.github/workflows/tests.yml	Test suite with pytest

View all runs on the Actions tab.

Local checks

All CI checks can be reproduced locally from the workspace root:

uv run ruff format --check apps/ services/ libs/ core/ tests/
uv run ruff check apps/ services/ libs/ core/ tests/
uv run mypy apps/ services/ libs/ core/ tests/
uv run pylint apps/ services/ libs/ core/ tests/
uv run pytest tests/ -q

Repository structure

Folder	Purpose
apps/	Runnable applications: ui (Streamlit), api_server (FastAPI), worker (background jobs)
core/	Shared primitives: Action, Point3D, GardenWorld, config, logging, events
services/	One service per concern, e.g. hardware gateway, watering, vision, planning, spatial, safety
projects/	Isolated student / research projects
experiments/	Reproducible evaluations with their own configs and outputs
libs/	Reusable, framework-agnostic utilities (geometry, ML helpers, FarmBot client)
tests/	Cross-cutting and integration tests (unit tests live next to the code)
configs/	YAML/JSON environment, robot and sensor configuration
docs/	Architecture, ADRs and onboarding guides

See docs/architecture.md for the full system design, action flow and how to add a new service or handler.

Design principles

1. Only services/farmbot_gateway/ talks to the FarmBot hardware.
   Everything else goes through the gateway.
2. apps/ orchestrates, services/ decides, libs/ computes.
   Keep I/O in apps, domain logic in services, pure helpers in libs.
3. core/ defines the shared vocabulary.
   Action, Point3D, GardenEntity, GardenWorld, Event, … live here.
4. safety_service gates every real-world action.
   Watering, moving, tooling — all validated before execution.
5. Student projects stay isolated in projects/.
   They import from core/ and libs/ and call public service APIs, but never modify shared code.
6. Experiments are reproducible.
   Config-driven runs under experiments/, results in their own outputs/ folders.
7. Configuration is data, not code.
   Robot coordinates, thresholds, experiment params live in configs/.
8. Tests live with the code.
   Unit tests sit next to modules; cross-service tests live in tests/.

Subpackages

Folder	Distribution	Purpose
core/	twfarmbot-core	Shared domain, config, logging, events
apps/ui/	twfarmbot-ui	Streamlit dashboard
apps/api_server/	twfarmbot-api-server	FastAPI HTTP API
apps/worker/	twfarmbot-worker	Background jobs / experiments

Each subpackage has its own pyproject.toml and can be developed independently.

License

This project is licensed under the GNU General Public License v3.0 or later — see LICENSE for the full text.

Contributing

• Follow the folder structure above.
• Keep code formatted with Ruff and typed with Mypy.
• Add tests for new behaviour.
• Update docs/architecture.md for structural changes.
• Open a pull request against main.

If your shell exports a PYTHONPATH that points at system site-packages (for example ROS), run uv commands with PYTHONPATH= uv run … so the venv isn't poisoned by incompatible system packages.