A Hybrid Edge-Cloud IoT Framework for Date Palm Leaf Disease Diagnosis Using Knowledge-Distilled Deep Learning — Research Artifacts

This repository contains the complete research artifacts for the thesis titled “A Hybrid Edge–Cloud IoT Framework for Date Palm Leaf Disease Diagnosis Using Knowledge-Distilled Deep Learning.” It provides a fully reproducible implementation of PalmNet, a hybrid edge–cloud IoT system designed for automated diagnosis of date palm leaf diseases and nutrient deficiencies directly in field environments. Overview Date palm (Phoenix dactylifera L.) is one of the most economically important crops in arid and semi-arid regions. Early and accurate detection of leaf diseases and nutrient deficiencies is essential for maintaining crop health and agricultural productivity. PalmNet addresses this challenge through a three-tier architecture composed of edge computing, cloud intelligence, and mobile integration. Edge Device (Raspberry Pi Zero 2 W) The edge layer performs real-time, low-power inference using a knowledge-distilled ShuffleNetV2 model exported to ONNX format. This enables efficient deployment on resource-constrained hardware while maintaining practical inference performance in field conditions. Cloud Backend (Google Cloud Run) The cloud layer hosts a high-capacity ConvNeXt-Tiny teacher model that processes uncertain or low-confidence cases offloaded from the edge device. The service is implemented using FastAPI and deployed on Google Cloud Run. Android Application The Android application serves as the primary user interface for farmers and agricultural experts. It provides diagnosis history visualization, GPS-tagged records, offline-capable inference, cloud synchronization, and expert review functionality. The proposed system implements intelligent confidence-based routing between edge and cloud components, supported by temperature-scaled probability calibration to improve the reliability of offloading decisions. Repository Contents 1. Dataset and Research Paper This section contains the research paper and the curated dataset consisting of nine classes: Potassium Deficiency Manganese Deficiency Magnesium Deficiency Black Scorch Leaf Spots Fusarium Wilt Rachis Blight Parlatoria Blanchardi Healthy Sample 2. Models and Training Pipeline This section includes: Python scripts for preprocessing and model training Teacher model optimization pipeline Teacher and student architecture comparison scripts Knowledge distillation implementation Jupyter notebook containing the complete experimental workflow Training logs, optimization records, and evaluation summaries 3. Trained Models The repository provides the following trained models: Optimized ConvNeXt-Tiny teacher model (convnext_tiny_best.pth) Baseline student models: EfficientNet-Lite0 MobileNetV3-Small ShuffleNetV2 Final distilled ShuffleNetV2 student model 4. Exported Deployment Models Exported deployment formats include: ONNX models for Raspberry Pi edge inference TensorFlow Lite models (float16 and float32) for Android inference 5. Results and Analysis This section contains: Full system evaluation metrics Per-class performance analysis Latency measurements and deployment benchmarks Confidence calibration plots Threshold sensitivity analysis Grad-CAM visualizations for model interpretability 6. Edge Device Implementation The Raspberry Pi deployment package includes: Hybrid edge–cloud inference source code (hybrid_edge.py) System evaluation pipeline (evaluate_system.py) GPIO button listener for physical deployment Setup instructions and Linux service configuration files 7. Cloud Service The cloud backend package contains: FastAPI inference service Firebase integration components Docker deployment configuration Google Cloud Run deployment files Environment variable templates and infrastructure documentation 8. Android Application The Android Studio project is implemented using Kotlin and Jetpack Compose and includes: On-device TensorFlow Lite inference Cloud offloading support Firebase Realtime Database synchronization GPS mapping functionality PDF report generation Expert review and validation workflow Key Technical Contributions Knowledge Distillation The system compresses a 28-million-parameter ConvNeXt-Tiny teacher model into a lightweight ShuffleNetV2 student model suitable for deployment on resource-constrained IoT edge devices. Confidence Calibration Temperature scaling is applied to improve probability calibration and produce reliable confidence estimates for edge–cloud routing decisions. Hybrid Edge–Cloud Routing A two-threshold routing strategy enables approximately 75% of cases to be processed locally on the edge device while uncertain samples are automatically offloaded to the cloud teacher model. Multi-Platform Model Export The framework supports deployment across multiple platforms through export pipelines for PyTorch, ONNX, and TensorFlow Lite. Real-World IoT Integration The proposed system integrates GPS-tagged diagnosis logging, offline caching, cloud synchronization, and Firebase-based data management for practical field deployment. Usage Notes For security and privacy purposes, all sensitive configuration values have been replaced with placeholders. These include: API keys Firebase project identifiers Service account credentials Cloud endpoint URLs To reproduce or deploy the system, users must: Create a personal Firebase project and generate new credentials Deploy the cloud backend to a personal Google Cloud Run instance Generate a new google-services.json file for the Android application Configure a valid Google Maps API key Detailed deployment and setup instructions are provided in the included README.md file.本仓库包含题为《基于知识蒸馏深度学习的椰枣叶部病害诊断混合边云物联网框架》的学位论文的完整研究成果。它提供了PalmNet的完全可复现实现——PalmNet是一款面向田间环境的椰枣叶部病害与营养缺失自动化诊断的混合边云物联网系统。 概述 椰枣（Phoenix dactylifera L.）是干旱与半干旱地区经济价值最高的作物之一。早期精准检测叶部病害与营养缺失，对于维持作物健康与农业生产力至关重要。PalmNet通过由边缘计算、云端智能与移动集成组成的三层架构解决该挑战。 边缘设备（树莓派Zero 2 W（Raspberry Pi Zero 2 W）） 边缘层采用导出为ONNX（Open Neural Network Exchange）格式的知识蒸馏ShuffleNetV2模型，实现实时低功耗推理。这使得该系统可在资源受限的硬件上高效部署，同时在田间环境中保持实用的推理性能。 云端后端（Google Cloud Run） 云端层搭载高性能ConvNeXt-Tiny教师模型，用于处理从边缘设备卸载的不确定或低置信度样本。该服务基于FastAPI实现，并部署于Google Cloud Run。 安卓应用（Android Application） 该安卓应用面向农户与农业专家，作为核心用户界面。它提供诊断历史可视化、GPS标记记录、离线推理、云同步以及专家评审功能。 本系统实现了基于智能置信度的边云组件间路由机制，并辅以温度缩放概率校准，以提升卸载决策的可靠性。 仓库内容 1. 数据集与研究论文 本板块包含研究论文与精选整理的数据集，共包含9个类别： 钾缺乏、锰缺乏、镁缺乏、黑焦病、叶斑病、镰刀菌枯萎病、穗枯病、椰圆盾蚧（Parlatoria Blanchardi）、健康样本。 2. 模型与训练流程 本板块包含： 预处理与模型训练的Python脚本、教师模型优化流程、教师与学生架构对比脚本、知识蒸馏实现代码、包含完整实验流程的Jupyter Notebook、训练日志、优化记录与评估总结。 3. 预训练模型 本仓库提供以下预训练模型： 优化后的ConvNeXt-Tiny教师模型（convnext_tiny_best.pth）、基线学生模型：EfficientNet-Lite0、MobileNetV3-Small、ShuffleNetV2，以及最终蒸馏得到的ShuffleNetV2学生模型。 4. 导出部署模型 导出的部署格式包括： 适用于树莓派边缘推理的ONNX模型、适用于安卓推理的TensorFlow Lite模型（float16与float32精度）。 5. 结果与分析 本板块包含： 完整系统评估指标、逐类别性能分析、延迟测量与部署基准测试、置信度校准曲线、阈值敏感性分析、用于模型可解释性的Grad-CAM可视化结果。 6. 边缘设备实现 树莓派部署包包含： 混合边云推理源代码（hybrid_edge.py）、系统评估流程（evaluate_system.py）、用于物理部署的GPIO（General Purpose Input/Output）按钮监听器、设置说明与Linux服务配置文件。 7. 云服务 云端后端包包含： FastAPI推理服务、Firebase集成组件、Docker部署配置、Google Cloud Run部署文件、环境变量模板与基础设施文档。 8. 安卓应用 该安卓项目基于Kotlin与Jetpack Compose开发，包含： 设备端TensorFlow Lite推理、云卸载支持、Firebase实时数据库同步、GPS地图功能、PDF报告生成、专家评审与验证工作流。 核心技术贡献 知识蒸馏：本系统将参数量达2800万的ConvNeXt-Tiny教师模型，压缩为适用于资源受限物联网边缘设备的轻量级ShuffleNetV2学生模型。 置信度校准：采用温度缩放方法优化概率校准，为边云路由决策提供可靠的置信度估计。 混合边云路由：双阈值路由策略可使约75%的样本在边缘设备本地处理，不确定样本则自动卸载至云端教师模型。 多平台模型导出：本框架通过针对PyTorch、ONNX与TensorFlow Lite的导出流水线，支持跨平台部署。 实际物联网集成：本系统集成了GPS标记诊断日志、离线缓存、云同步与基于Firebase的数据管理功能，适配实际田间部署。 使用说明 出于安全与隐私考量，所有敏感配置值已替换为占位符，包括：API密钥、Firebase项目标识符、服务账户凭据、云端端点URL。 若要复现或部署本系统，用户需： 创建个人Firebase项目并生成新的凭据、将云端后端部署至个人Google Cloud Run实例、为安卓应用生成新的google-services.json文件、配置有效的Google Maps API密钥。 详细的部署与设置说明见附带的README.md文件。