Platform v2.0 Django 5.2.8

Smart Field Solutions Documentation

Complete technical reference for the Smart Agriculture Platform. Sensor integration, API endpoints, architecture, and deployment guide.

Overview

Platform introduction and purpose

Smart Field Solutions is a Smart Agriculture Platform built for Algerian farms. It combines real-time IoT sensor data, satellite imagery, weather forecasting, and intelligent automation to help farmers monitor their land, optimize irrigation, and increase crop yields.

Tech Stack

  • Django 5.2.8 Backend framework
  • PostgreSQL Database
  • MQTT ChirpStack integration
  • LoRaWAN Sensor connectivity
  • Flutter Mobile application
  • Tailwind CSS Frontend styling

Core Capabilities

  • Monitor agricultural lands and crops
  • Manage IoT sensors (pH, moisture, EC)
  • Control irrigation valves remotely
  • Satellite imagery with NDVI analysis
  • Weather forecasts and alerts
  • Automated IF/THEN rules engine

How to Test

Quick start guide for testing the platform

1

Web Access

Open the platform in your browser:

http://164.68.107.160
2

Register an Account

Create an account via the web form at /register/ or through the API:

POST /api/v1/auth/register/ Content-Type: application/json { "email": "user@example.com", "password": "your_password", "first_name": "Ahmed", "last_name": "Benali", "phone": "+213555123456" }
3

Login

Use the web form at /login/ or the API endpoint:

POST /api/v1/auth/login/ Content-Type: application/json { "email": "user@example.com", "password": "your_password" } // Returns: { "token": "abc123..." }
4

Explore the Dashboard

After login you are redirected to the main dashboard with weather overview, lands summary, and sensor status cards. First-time users will enter the onboarding flow -- a guided field setup where you name your field, choose a crop type, and draw boundaries on a satellite map.

5

Mobile App

Build the Flutter app from the mobile/ directory and connect it to the same backend API:

http://164.68.107.160/api/v1/

User Roles & Subscription Plans

Access levels and pricing tiers

Role / Plan Description Access
Farm Owner Primary user, manages lands, sensors, and irrigation Full access within plan
Admin (Django) Superuser via /admin/ Full database & user management
Trial User New registration, 30-day free trial All features for 30 days
Essential 2,500 DZD/month Basic subscription tier Sensors, satellite NDVI, alerts, basic reports
Pro 5,000 DZD/month Mid-tier subscription + Automation rules, meteo station, irrigation control
Enterprise 12,000 DZD/month Full access subscription + Fertigation, full API access, priority support

Real Working Features

Connected to actual hardware and APIs

Feature Hardware / API How It Works
Soil pH Sensor (LSPH-01) Dragino LoRaWAN Real MQTT data via ChirpStack gateway
Leaf Moisture Sensor (LLMS01) Dragino LoRaWAN Real MQTT data via ChirpStack
Soil Moisture/EC (SE0X-LB) Dragino LoRaWAN Real MQTT (1 probe active due to RS485 bus conflict)
Weather Station (WSC01-L) Dragino LoRaWAN Real sensor data routed to meteo app
Valve Control LT-22222-L Relay Real downlink commands via ChirpStack to open/close irrigation valves
Irrigation Scheduler Django background service Runs schedules automatically, skips irrigation if rain forecasted
Weather Forecast Open-Meteo API Live 7-day forecast: temperature, humidity, wind, precipitation (free, no auth)
Satellite NDVI Sentinel Hub API Real Sentinel-2 satellite imagery + vegetation index calculation
Alert Engine Sensor-driven rules Evaluates alert rules on each MQTT sensor reading
Automation (IF/THEN) Sensor → Valve pipeline Real sensor triggers → real valve actions (e.g., soil moisture < 30% → open valve)
Reports & PDF Database + ReportLab Generates PDF reports from real sensor and irrigation data

Demo / Mock Features

Features with simulated or partial functionality

Feature Status Details
Fertigation Mock Controller Database-only operations, logs [MOCK] prefix, no hardware commands sent. Ready for hardware integration following the ValveController pattern.
Billing / Payment Manual Only No Stripe or payment gateway integrated. Subscriptions created manually by admin. Feature gating (plan-based access control) works but payment is offline/manual.

API Reference

REST API endpoints summary

Authentication Required

All API endpoints require Token authentication except register and login. Include the header:

Authorization: Token <your_token>

Authentication

POST /api/v1/auth/register/ # Create account POST /api/v1/auth/login/ # Get auth token POST /api/v1/auth/logout/ # Invalidate token

Dashboard

GET /api/v1/dashboard/summary/ # Overview data

Lands

GET /api/v1/lands/ # List all lands POST /api/v1/lands/ # Create a land GET /api/v1/lands/{id}/ # Get land detail PUT /api/v1/lands/{id}/ # Update land DELETE /api/v1/lands/{id}/ # Delete land

Sensors

GET /api/v1/sensors/ # List sensors GET /api/v1/sensors/{id}/ # Sensor detail GET /api/v1/sensors/{id}/readings/ # Sensor readings

Irrigation

GET /api/v1/irrigation/zones/ # List zones GET /api/v1/irrigation/valves/{id}/control/ # Valve status POST /api/v1/irrigation/valves/{id}/control/ # Open/close valve GET /api/v1/irrigation/schedules/ # List schedules GET /api/v1/irrigation/sessions/ # Irrigation history

Automation

GET /api/v1/automation/rules/ # List rules POST /api/v1/automation/rules/ # Create rule GET /api/v1/automation/logs/ # Execution logs

Fertigation

GET /api/v1/fertigation/stations/ # List stations GET /api/v1/fertigation/reservoirs/ # List reservoirs GET /api/v1/fertigation/recipes/ # List recipes

Weather

GET /api/v1/weather/current/ # Current weather GET /api/v1/weather/forecast/ # 7-day forecast

Satellite

GET /api/v1/satellite/images/ # List NDVI images POST /api/v1/satellite/fetch-ndvi/ # Request new NDVI

Alerts

GET /api/v1/alerts/ # List alerts GET /api/v1/alerts/rules/ # Alert rules

Reports

GET /api/v1/reports/ # List reports POST /api/v1/reports/ # Generate report GET /api/v1/reports/{id}/download/ # Download PDF

Billing

GET /api/v1/billing/subscription/ # Current subscription GET /api/v1/billing/plans/ # Available plans

Architecture

System data flow and component diagram

LoRaWAN Sensors
     |
     v
Dragino Gateway ──────> ChirpStack MQTT Broker ──────> Django MQTT Client
                                                              |
                                                              v
                                                     ┌────────────────┐
                                                     |   PostgreSQL    |
                                                     |   Database      |
                                                     └───────┬────────┘
                                                              |
                                   ┌──────────────────────────┼──────────────────────┐
                                   |                          |                      |
                                   v                          v                      v
                          Alert Engine            Automation Rules          Irrigation
                               |                          |               Scheduler
                               v                          v                      |
                      Push Notifications         Valve Control                   v
                                              (ChirpStack Downlinks)     Auto Schedules

                                                              |
                                   ┌──────────────────────────┼──────────────────────┐
                                   |                          |                      |
                                   v                          v                      v
                          Web Dashboard  <────>  REST API  <────>  Flutter Mobile App
                                                              |
                                   ┌──────────────────────────┼──────────────────────┐
                                   |                                                 |
                                   v                                                 v
                          Open-Meteo API                                 Sentinel Hub API
                           (Weather Data)                                 (Satellite NDVI)
Core platform services
External services & gateways
Processing & rule engines

Deployment

Server infrastructure and services

Server

  • VPS Contabo VPS, Ubuntu Linux
  • Web Nginx reverse proxy → Gunicorn (WSGI)
  • DB PostgreSQL relational database

Systemd Services

  • smartfield Gunicorn application server
  • mqtt_client ChirpStack MQTT listener
  • irrigation_scheduler Background irrigation runner

Static Files

  • collect Collected via collectstatic, served by Nginx
  • media User uploads served via Nginx

Integrations

  • MQTT ChirpStack for all LoRaWAN sensor data
  • Cron Periodic irrigation schedule & sensor health checks

Request Flow

# Web request flow Client Browser ──> Nginx :80/:443 ──> Gunicorn :8000 ──> Django App ──> PostgreSQL # Sensor data flow LoRaWAN Sensor ──> Dragino Gateway ──> ChirpStack MQTT ──> mqtt_client ──> PostgreSQL # Irrigation automation Cron / Scheduler ──> Django Management CMD ──> ChirpStack API ──> Downlink ──> Valve Relay