Agrync : A Modular Integration Layer for Industrial IoT interoperability in Agro-industrial Environments

📚 Documentation  ·  Introduction  ·  Installation  ·  First steps  ·  Technical docs  ·  Architecture

---

Agroindustrial facilities typically operate hundreds of sensors and PLCs from different manufacturers, each speaking its own protocol — Modbus, OPC-UA, or proprietary variants — creating isolated data silos that are expensive to integrate, hard to maintain, and impossible to monitor from a single interface. Bridging this IT/OT gap has traditionally required specialist engineering teams and customized middleware that few small or mid-size agro-processing plants can afford. Agrync is a full-stack platform — FastAPI backend and React + Vite frontend — built to eliminate that barrier: it provides a unified, open-source layer that speaks the industrial protocols already present on the plant floor, normalises the data, and exposes it through a modern web interface, so operators can configure, monitor and manage every sensor in the facility without writing a single line of integration code.

---

M. Muñoz* · J.J. León · M. Torres · A. Becerra-Terón · J.A. Sánchez
University of Almería, Spain · *Corresponding author: mmr411@ual.es

---

Documentation

Full documentation — installation, configuration, usage guides and API reference — is available at:

https://agrync.readthedocs.io/

---

Key features

• Modbus TCP/IP reader: collect telemetry from Modbus-enabled devices and PLCs.
• OPC UA server: optionally expose collected data via an OPC UA server for OT integration.
• FIWARE integration: forward telemetry to FIWARE or similar IoT platforms for storage and analytics.
• Sensor management center: add, edit, or remove sensors one-by-one via the web UI, or perform bulk configuration by uploading a JSON file.
• Docker Compose based deployment: the repository is configured so the entire stack can be launched with Docker Compose.

---

Repository layout

• agrync_backend/ — FastAPI backend (includes Dockerfile)
• agrync_frontend/ — Vite + React + TypeScript frontend (includes Dockerfile)
• docker-compose.yml — Docker Compose configuration for development
• .github/workflows/ci.yml — GitHub Actions CI pipeline

---

Prerequisites

• Docker & Docker Compose (recommended)
• Node.js >= 18 (for frontend development)
• Python 3.11+ (for backend development)
• Git

---

Launching the full stack (recommended)

The recommended way to run the entire system (backend + database + frontend) is using Docker Compose from the repository root:

docker compose up --build

After the services start:

Service	URL	Notes
Frontend	http://localhost:5173	React + Vite UI
Backend REST API	http://localhost:8000/api/v1	FastAPI
Swagger / OpenAPI	http://localhost:8000/api/v1/docs	Interactive API docs
OPC UA Server	opc.tcp://localhost:4842	Exposed by the backend container
FIWARE Orion	http://localhost:1026	NGSI v2 Context Broker
MongoDB	localhost:27020	Internal port 27017

To stop and remove containers:

docker compose down

---

Demo mode (reproducibility)

Agrync ships with a self-contained demo that simulates a virtual greenhouse PLC — no physical hardware, OPC-UA certificates, or external services needed. This is the recommended way for software reviewers to verify the full pipeline.

How it differs from the normal stack

In production the data flow is:

Modbus device → OPC-UA Server → OPCtoFIWARE task → FIWARE Orion → backend webhook → MongoDB

In demo mode the OPC-UA layer is replaced by a lightweight built-in poller:

Modbus Simulator (Docker) → demo_task → FIWARE Orion → backend webhook → MongoDB

Quick start

1. Copy the demo environment file

cp .env.demo.example .env.demo

2. Start the demo stack

docker-compose -f docker-compose.yml -f docker-compose.demo.yml up --build

Six containers start: mongodb, orion, agrync_backend, agrync_frontend, modbus_simulator, modbus_demo_task.

3. Set the admin password
Open http://localhost:5173/create-password and set a password for admin@agrync-demo.com. No REST API call is needed — account activation is done entirely through the web form.

4. Log in
Open http://localhost:5173/login — email admin@agrync-demo.com.

5. Import the demo device
Administration → Devices → Upload — select modbus_simulator/demo_devices.json. After the import, the Devices table shows Demo_Greenhouse with its two Modbus slaves.

6. Assign the device to the admin user
Administration → Users → Devices (button) → move Demo_Greenhouse to Assigned → Save.

7. View live data
Open Dashboard — 10 sensor cards update every 5 seconds.

8. Explore historical data
Open Graphs, select a date range and one or more variables — the chart renders historical trends from the data already collected by the simulator.

Verifying data in FIWARE Orion

Once the stack is running you can query FIWARE Orion directly to verify the pipeline is active (requires the Fiware-Service: demo header):

# List all entities published by the demo poller
curl -s \
  -H "Fiware-Service: demo" \
  -H "Fiware-ServicePath: /" \
  http://localhost:1026/v2/entities | python3 -m json.tool

# Environmental sensors entity
curl -s \
  -H "Fiware-Service: demo" \
  -H "Fiware-ServicePath: /" \
  "http://localhost:1026/v2/entities/Demo_Greenhouse-Env_Sensors" | python3 -m json.tool

# Actuators entity
curl -s \
  -H "Fiware-Service: demo" \
  -H "Fiware-ServicePath: /" \
  "http://localhost:1026/v2/entities/Demo_Greenhouse-Actuators" | python3 -m json.tool

Expected response: a JSON object with attributes Interior_Temp, Relative_Humidity, CO2_Concentration, Global_Radiation, Soil_Temp_5cm, Soil_Temp_30cm (Env_Sensors entity) and Zenith_Ventilation, Lateral_Ventilation, Thermal_Screen, Active_Irrigation (Actuators entity), each carrying a value and a timestamp metadata field updated every 5 seconds.

Note on the Monitoring panel: Administration → Monitoring controls the OPC-UA background tasks, which are intentionally inactive in demo mode. A banner on each page explains this. Data acquisition is handled autonomously by the modbus_demo_task container.

Stopping the demo

docker-compose -f docker-compose.yml -f docker-compose.demo.yml down
# Add -v to also remove the MongoDB data volume

---

Production deployment — Backend

1. Create and activate a virtual environment:

cd agrync_backend
python -m venv .venv
source .venv/bin/activate

2. Install Python dependencies:

pip install -r requirements.txt

3. Environment variables

All environment variables must be provided before starting the backend. Full configuration reference is available at https://agrync.readthedocs.io/en/latest/technical/configuration/.

Create a .env file in agrync_backend/ (or export the variables directly):

# ── MongoDB ────────────────────────────────────────────────
MONGO_URI=mongodb://localhost:27017

# ── Authentication (JWT) ───────────────────────────────────
ACCESS_TOKEN_SECRET_KEY=change-me-access
REFRESH_TOKEN_SECRET_KEY=change-me-refresh
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_MINUTES=1440
ADMIN_EMAIL=admin@example.com

# ── OPC UA Server ──────────────────────────────────────────
OPCUA_IP_PORT=4842
URL=opc.tcp://localhost:{OPCUA_IP_PORT}
URL_ADMIN=opc.tcp://localhost:{OPCUA_IP_PORT}
URI=urn:agrync:server
USERNAME_OPC=operator
PASSWORD_OPC=change-me
USERNAME_OPC_ADMIN=admin
PASSWORD_OPC_ADMIN=change-me
CERT=certificate/my_cert.der
PRIVATE_KEY=certificate/private_key.pem
CLIENT_CERT=certificate/client_cert.der
CLIENT_APP_URI=urn:agrync:client

# ── Modbus task ────────────────────────────────────────────
RECONNECTION_TIME=5

# ── FIWARE Orion ───────────────────────────────────────────
FIWARE_URL=http://orion:1026
FIWARE_SERVICE=agrync
FIWARE_SERVICE_PATH=/

# ── Telegram alerts (optional) ─────────────────────────────
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
ALERT_INTERVAL=60

# ── Logging ────────────────────────────────────────────────
LOG_CONFIG=logging.conf
LOG_MODBUS=ModbusLogger
LOG_OPC=OPCLogger
LOG_OPC_FIWARE=OPCtoFIWARELogger

4. Run the backend in development:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

5. API docs (Swagger/OpenAPI):

Open http://localhost:8000/api/v1/docs

---

Production deployment — Frontend

1. Install dependencies and run the dev server:

cd agrync_frontend
npm install
npm run dev
# or use pnpm/yarn

2. Dev server URL: http://localhost:5173

3. If the frontend needs a specific API URL, check agrync_frontend/src/api or environment configuration and set the appropriate base URL.

---

Docker images (optional)

Build backend image:

docker build agrync_backend -t agrync-backend:latest

Build frontend image:

docker build agrync_frontend -t agrync-frontend:latest

---

Background tasks

The core integration logic runs as three independent background processes managed from the Administration panel. See the "Docs" column for detailed documentation on each task.

Task	Description	Docs
Modbus	Polls all configured Modbus TCP/IP devices at their configured intervals, decodes register values (Int16/32/64, Float32/64, endianness, scaling) and persists them in MongoDB (LastVariable + HistoricalVariable). Also subscribes to the OPC UA server to relay write-back commands to writable registers.	→ docs
ServerOPC	Starts an OPC UA server (port 4842) secured with X.509 certificates (Basic256Sha256 + SignAndEncrypt). Exposes every Modbus variable as an OPC UA node and keeps their values in sync from the database.	→ docs
OPCtoFIWARE	Connects as an OPC UA client to ServerOPC, subscribes to all nodes, and forwards value changes to a FIWARE Orion Context Broker via NGSI v2 PATCH requests. Registers a webhook on Orion so that platform-side updates flow back to the database. Supports optional Telegram alerts on out-of-range values.	→ docs

Tasks are started and stopped from the web UI (Administration → Monitoring) or via the REST API (POST /api/v1/tasks/{name}/start). ServerOPC and OPCtoFIWARE are locked tasks (they start and stop together as a pair).

---

Configuration notes

• The backend uses Beanie + Motor to interact with MongoDB. Use a supported MongoDB server.
• Tasks and connectors (Modbus/OPC) are managed under tasks/ and routers/. Review their configs before enabling production connectors.
• The project includes example JSON configuration files for bulk device/sensor import in agrync_frontend/public and agrync_backend/static.

---

Troubleshooting

• If TypeScript or JSX errors appear in the frontend, run npm install in agrync_frontend to install dependencies and type packages.
• If the backend cannot connect to MongoDB, check MONGODB_URI, network access and that MongoDB is running.

---

Running the tests

Full testing documentation is available at https://agrync.readthedocs.io/en/latest/technical/testing/.

Backend (pytest)

The backend test suite uses an in-memory MongoDB mock — no running database or Docker is required.

cd agrync_backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt
pytest -v

To run a single file:

pytest tests/test_auth.py -v

Expected result: 99 passed, 1 xfailed.

Frontend — unit tests (Vitest)

cd agrync_frontend
npm install
npm run test -- --run

With coverage report:

npm run test -- --coverage

Expected result: 49 passed.

Frontend — end-to-end tests (Playwright)

E2E tests require the full stack to be running first:

# From the repository root
docker compose up -d

# Then, in a separate terminal
cd agrync_frontend
npx playwright test --config playwright.config.cjs

To run a single spec:

npx playwright test e2e/login.spec.cjs --config playwright.config.cjs

Expected result: 11 passed. An HTML report can be opened with:

npx playwright show-report

---

Screenshots — production deployment

Dashboard — real-time sensor values

Modbus device management

Task monitoring — Modbus running

---

License

See LICENSE.