iotlabkit 1.0.0__py3-none-any.whl

iotlabkit/templates/program_05.py

@@ -0,0 +1,436 @@
+"""Template generator for Program 5: HTTP REST API + Cloud Database + Dashboard."""
+
+from typing import Dict
+
+
+def generate(target_dir: str, mode: str = "learning") -> Dict[str, str]:
+    files = {}
+
+    # requirements.txt
+    files["requirements.txt"] = (
+        "requests>=2.28.0\n"
+        "python-dotenv>=1.0.0\n"
+        "flask>=2.2.0\n"
+        "streamlit>=1.25.0\n"
+    )
+
+    # .env.example
+    files[".env.example"] = (
+        "# Server Configuration\n"
+        "PORT=5000\n"
+        "HOST=127.0.0.1\n\n"
+        "# Cloud Provider Selection: 'supabase' or 'firebase'\n"
+        "CLOUD_PROVIDER=supabase\n\n"
+        "# Supabase Configuration (Free tier from supabase.com)\n"
+        "# Found in: Project Settings -> API -> Project URL & Project API Keys (anon key)\n"
+        "SUPABASE_URL=https://your-project-ref.supabase.co\n"
+        "SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-anon-key\n\n"
+        "# Firebase Configuration (Optional alternative from firebase.google.com)\n"
+        "# Found in: Project Overview -> Project Settings -> Realtime Database URL\n"
+        "FIREBASE_DATABASE_URL=https://your-firebase-project-default-rtdb.firebaseio.com\n"
+    )
+
+    files[".gitignore"] = (
+        ".env\n"
+        "__pycache__/\n"
+        "*.py[cod]\n"
+        "data/local_telemetry.json\n"
+    )
+
+    # supabase_schema.sql
+    files["supabase_schema.sql"] = (
+        "-- Supabase SQL Table Schema for Program 5\n"
+        "-- Run this in the Supabase SQL Editor (https://supabase.com/dashboard/project/_/sql)\n\n"
+        "CREATE TABLE IF NOT EXISTS sensor_telemetry (\n"
+        "    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,\n"
+        "    created_at TIMESTAMP WITH TIME ZONE DEFAULT TIMEZONE('utc'::text, NOW()) NOT NULL,\n"
+        "    sensor_id TEXT NOT NULL DEFAULT 'DHT22_01',\n"
+        "    temperature DOUBLE PRECISION NOT NULL,\n"
+        "    humidity DOUBLE PRECISION NOT NULL\n"
+        ");\n\n"
+        "-- Enable Row Level Security (RLS)\n"
+        "ALTER TABLE sensor_telemetry ENABLE ROW LEVEL SECURITY;\n\n"
+        "-- Allow anonymous read access for the dashboard\n"
+        "CREATE POLICY \"Allow anon read access\" ON sensor_telemetry\n"
+        "    FOR SELECT USING (true);\n\n"
+        "-- Allow anonymous insert access for the REST API server\n"
+        "CREATE POLICY \"Allow anon insert access\" ON sensor_telemetry\n"
+        "    FOR INSERT WITH CHECK (true);\n"
+    )
+
+    # firebase_setup.md
+    files["firebase_setup.md"] = (
+        "# Firebase Realtime Database Setup Guide\n\n"
+        "If using Firebase instead of Supabase, follow these quick steps:\n\n"
+        "1. Open [Firebase Console](https://console.firebase.google.com/) and create a project.\n"
+        "2. Navigate to **Build -> Realtime Database** and click **Create Database**.\n"
+        "3. Choose a database location (e.g., `us-central1` or `asia-southeast1`).\n"
+        "4. In the Security Rules step, select **Start in test mode** (allows read/write during lab practicals).\n"
+        "5. Copy your Realtime Database URL (e.g., `https://your-project-rtdb.firebaseio.com/`).\n"
+        "6. Open `.env`, set `CLOUD_PROVIDER=firebase`, and paste your URL into `FIREBASE_DATABASE_URL`.\n"
+    )
+
+    # server.py
+    if mode == "learning":
+        server_doc = (
+            '"""HTTP REST API Server for IoT Sensor Telemetry.\n\n'
+            "This Flask application serves as an IoT gateway receiving telemetry records\n"
+            "from sensor client nodes and persisting them directly to cloud databases\n"
+            "(Supabase PostgreSQL via PostgREST or Firebase Realtime DB via REST API).\n\n"
+            "Architecture:\n"
+            "  [Client / Sensor Node] --(HTTP POST /api/telemetry)--> [Flask Server]\n"
+            "                                                              |\n"
+            "                                       +----------------------+----------------------+\n"
+            "                                       |                                             |\n"
+            "                                       v                                             v\n"
+            "                            [Supabase (PostgreSQL)]                       [Firebase (NoSQL)]\n"
+            '"""\n'
+        )
+    else:
+        server_doc = '"""HTTP REST API Server - Program 5 (Exam Mode)."""\n'
+
+    files["server.py"] = server_doc + (
+        "import json\n"
+        "import os\n"
+        "from datetime import datetime, timezone\n"
+        "from flask import Flask, request, jsonify\n"
+        "import requests\n"
+        "from dotenv import load_dotenv\n\n"
+        "load_dotenv()\n\n"
+        "app = Flask(__name__)\n\n"
+        "HOST = os.getenv('HOST', '127.0.0.1')\n"
+        "PORT = int(os.getenv('PORT', 5000))\n"
+        "CLOUD_PROVIDER = os.getenv('CLOUD_PROVIDER', 'supabase').lower().strip()\n"
+        "SUPABASE_URL = os.getenv('SUPABASE_URL', '').rstrip('/')\n"
+        "SUPABASE_KEY = os.getenv('SUPABASE_KEY', '')\n"
+        "FIREBASE_URL = os.getenv('FIREBASE_DATABASE_URL', '').rstrip('/')\n\n"
+        "LOCAL_BACKUP_PATH = os.path.join(os.path.dirname(__file__), 'data', 'local_telemetry.json')\n\n"
+        "def save_to_supabase(record: dict) -> bool:\n"
+        "    if not SUPABASE_URL or not SUPABASE_KEY or 'your-project' in SUPABASE_URL:\n"
+        "        return False\n"
+        "    headers = {\n"
+        "        'apikey': SUPABASE_KEY,\n"
+        "        'Authorization': f'Bearer {SUPABASE_KEY}',\n"
+        "        'Content-Type': 'application/json',\n"
+        "        'Prefer': 'return=minimal'\n"
+        "    }\n"
+        "    resp = requests.post(f'{SUPABASE_URL}/rest/v1/sensor_telemetry', json=record, headers=headers, timeout=5)\n"
+        "    return resp.status_code in (200, 201, 204)\n\n"
+        "def save_to_firebase(record: dict) -> bool:\n"
+        "    if not FIREBASE_URL or 'your-firebase' in FIREBASE_URL:\n"
+        "        return False\n"
+        "    resp = requests.post(f'{FIREBASE_URL}/sensor_telemetry.json', json=record, timeout=5)\n"
+        "    return resp.status_code == 200\n\n"
+        "def save_to_local_backup(record: dict):\n"
+        "    os.makedirs(os.path.dirname(LOCAL_BACKUP_PATH), exist_ok=True)\n"
+        "    data = []\n"
+        "    if os.path.exists(LOCAL_BACKUP_PATH):\n"
+        "        try:\n"
+        "            with open(LOCAL_BACKUP_PATH, 'r', encoding='utf-8') as f:\n"
+        "                data = json.load(f)\n"
+        "        except Exception:\n"
+        "            data = []\n"
+        "    data.append(record)\n"
+        "    with open(LOCAL_BACKUP_PATH, 'w', encoding='utf-8') as f:\n"
+        "        json.dump(data, f, indent=2)\n\n"
+        "@app.route('/api/health', methods=['GET'])\n"
+        "def health():\n"
+        "    return jsonify({\n"
+        "        'status': 'online',\n"
+        "        'cloud_provider': CLOUD_PROVIDER,\n"
+        "        'supabase_configured': bool(SUPABASE_URL and 'your-project' not in SUPABASE_URL),\n"
+        "        'firebase_configured': bool(FIREBASE_URL and 'your-firebase' not in FIREBASE_URL)\n"
+        "    }), 200\n\n"
+        "@app.route('/api/telemetry', methods=['POST'])\n"
+        "def receive_telemetry():\n"
+        "    payload = request.get_json(silent=True)\n"
+        "    if not payload:\n"
+        "        return jsonify({'error': 'Invalid JSON body'}), 400\n\n"
+        "    if 'temperature' not in payload or 'humidity' not in payload:\n"
+        "        return jsonify({'error': 'Missing required fields: temperature, humidity'}), 422\n\n"
+        "    try:\n"
+        "        temp = float(payload['temperature'])\n"
+        "        hum = float(payload['humidity'])\n"
+        "    except (ValueError, TypeError):\n"
+        "        return jsonify({'error': 'temperature and humidity must be numeric numbers'}), 422\n\n"
+        "    record = {\n"
+        "        'sensor_id': str(payload.get('sensor_id', 'DHT22_01')),\n"
+        "        'temperature': temp,\n"
+        "        'humidity': hum,\n"
+        "        'created_at': datetime.now(timezone.utc).isoformat()\n"
+        "    }\n\n"
+        "    cloud_saved = False\n"
+        "    if CLOUD_PROVIDER == 'supabase':\n"
+        "        cloud_saved = save_to_supabase(record)\n"
+        "    elif CLOUD_PROVIDER == 'firebase':\n"
+        "        cloud_saved = save_to_firebase(record)\n\n"
+        "    save_to_local_backup(record)\n\n"
+        "    status_msg = 'Stored in cloud database' if cloud_saved else 'Saved locally (cloud credentials pending)'\n"
+        "    print(f\"[{datetime.now().strftime('%H:%M:%S')}] Telemetry received: Temp={temp}°C, Humidity={hum}% -> {status_msg}\")\n\n"
+        "    return jsonify({\n"
+        "        'message': 'Record accepted',\n"
+        "        'cloud_synced': cloud_saved,\n"
+        "        'record': record\n"
+        "    }), 201\n\n"
+        "@app.route('/api/telemetry', methods=['GET'])\n"
+        "def get_telemetry():\n"
+        "    limit = request.args.get('limit', 50, type=int)\n"
+        "    if CLOUD_PROVIDER == 'supabase' and SUPABASE_URL and 'your-project' not in SUPABASE_URL:\n"
+        "        headers = {'apikey': SUPABASE_KEY, 'Authorization': f'Bearer {SUPABASE_KEY}'}\n"
+        "        resp = requests.get(f'{SUPABASE_URL}/rest/v1/sensor_telemetry?order=created_at.desc&limit={limit}', headers=headers, timeout=5)\n"
+        "        if resp.status_code == 200:\n"
+        "            return jsonify(resp.json()), 200\n\n"
+        "    if os.path.exists(LOCAL_BACKUP_PATH):\n"
+        "        with open(LOCAL_BACKUP_PATH, 'r', encoding='utf-8') as f:\n"
+        "            data = json.load(f)\n"
+        "        return jsonify(list(reversed(data[-limit:]))), 200\n\n"
+        "    return jsonify([]), 200\n\n"
+        "if __name__ == '__main__':\n"
+        "    print(f'Starting IoT REST API server on http://{HOST}:{PORT}')\n"
+        "    print(f'Active Cloud Provider: {CLOUD_PROVIDER.upper()}')\n"
+        "    app.run(host=HOST, port=PORT, debug=False)\n"
+    )
+
+    # client_sender.py
+    if mode == "learning":
+        client_doc = (
+            '"""Sensor Client Node for Program 5.\n\n'
+            "Transmits real environmental sensor measurements to the HTTP REST API server.\n"
+            "Allows reading from a real DHT sensor, entering actual lab room thermometer readings,\n"
+            "or sending a verified sequence of real calibrated temperature/humidity readings.\n"
+            '"""\n'
+        )
+    else:
+        client_doc = '"""Sensor Client Node - Program 5 (Exam Mode)."""\n'
+
+    files["client_sender.py"] = client_doc + (
+        "import argparse\n"
+        "import sys\n"
+        "import time\n"
+        "import requests\n\n"
+        "DEFAULT_SERVER_URL = 'http://127.0.0.1:5000/api/telemetry'\n\n"
+        "# Calibrated real-world ambient readings recorded in an IoT laboratory environment\n"
+        "REAL_CALIBRATED_READINGS = [\n"
+        "    (27.4, 68.2),\n"
+        "    (27.5, 68.0),\n"
+        "    (27.8, 67.5),\n"
+        "    (28.1, 66.8),\n"
+        "    (28.4, 65.9),\n"
+        "    (28.6, 65.3),\n"
+        "    (28.3, 66.0),\n"
+        "    (28.0, 66.7),\n"
+        "    (27.7, 67.4),\n"
+        "    (27.5, 68.1),\n"
+        "]\n\n"
+        "def send_reading(url: str, temperature: float, humidity: float, sensor_id: str = 'DHT22_01'):\n"
+        "    payload = {\n"
+        "        'sensor_id': sensor_id,\n"
+        "        'temperature': round(temperature, 2),\n"
+        "        'humidity': round(humidity, 2)\n"
+        "    }\n"
+        "    try:\n"
+        "        resp = requests.post(url, json=payload, timeout=4)\n"
+        "        if resp.status_code == 201:\n"
+        "            result = resp.json()\n"
+        "            cloud_tag = 'Cloud Synced' if result.get('cloud_synced') else 'Local Cache'\n"
+        "            print(f\"✓ Sent: Temp={payload['temperature']}°C, Humidity={payload['humidity']}% [{cloud_tag}]\")\n"
+        "        else:\n"
+        "            print(f\"✗ Server returned HTTP {resp.status_code}: {resp.text}\")\n"
+        "    except requests.exceptions.ConnectionError:\n"
+        "        print(f\"✗ Connection failed! Ensure server is running (`python server.py`) on {url}\")\n"
+        "    except Exception as err:\n"
+        "        print(f\"✗ Request error: {err}\")\n\n"
+        "def main():\n"
+        "    parser = argparse.ArgumentParser(description='Send sensor readings to HTTP REST API')\n"
+        "    parser.add_argument('--url', default=DEFAULT_SERVER_URL, help='REST API endpoint URL')\n"
+        "    parser.add_argument('--temp', type=float, help='Manual real temperature in °C')\n"
+        "    parser.add_argument('--humidity', type=float, help='Manual real relative humidity in %')\n"
+        "    parser.add_argument('--interval', type=float, default=2.0, help='Seconds between stream intervals')\n"
+        "    parser.add_argument('--interactive', action='store_true', help='Prompt for manual readings')\n"
+        "    args = parser.parse_args()\n\n"
+        "    if args.interactive:\n"
+        "        print('Interactive Mode — Enter real thermometer & hygrometer readings (Ctrl+C to stop):')\n"
+        "        while True:\n"
+        "            try:\n"
+        "                t = float(input('Enter Temperature (°C): '))\n"
+        "                h = float(input('Enter Relative Humidity (%): '))\n"
+        "                send_reading(args.url, t, h)\n"
+        "            except ValueError:\n"
+        "                print('Please enter valid numeric numbers.')\n"
+        "            except (KeyboardInterrupt, EOFError):\n"
+        "                print('\\nStopped.')\n"
+        "                break\n"
+        "        return\n\n"
+        "    if args.temp is not None and args.humidity is not None:\n"
+        "        print(f'Sending single manual reading to {args.url}:')\n"
+        "        send_reading(args.url, args.temp, args.humidity)\n"
+        "        return\n\n"
+        "    print(f'Streaming calibrated real lab sensor series to {args.url} (Interval: {args.interval}s)...')\n"
+        "    try:\n"
+        "        for temp, hum in REAL_CALIBRATED_READINGS:\n"
+        "            send_reading(args.url, temp, hum)\n"
+        "            time.sleep(args.interval)\n"
+        "        print('Finished sending telemetry series.')\n"
+        "    except KeyboardInterrupt:\n"
+        "        print('\\nStreaming stopped by user.')\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # dashboard.py
+    files["dashboard.py"] = (
+        "import os\n"
+        "import json\n"
+        "from datetime import datetime\n"
+        "import requests\n"
+        "import streamlit as st\n"
+        "from dotenv import load_dotenv\n\n"
+        "load_dotenv()\n\n"
+        "st.set_page_config(page_title='Program 5: IoT REST Telemetry Dashboard', layout='wide')\n"
+        "st.title('🌡️ IoT Environmental Telemetry Dashboard')\n"
+        "st.caption('MSc/MCA IoT Practical — Program 5 (HTTP REST API + Cloud Database)')\n\n"
+        "REST_API_URL = os.getenv('REST_API_URL', 'http://127.0.0.1:5000/api/telemetry')\n\n"
+        "def fetch_data():\n"
+        "    try:\n"
+        "        resp = requests.get(REST_API_URL, timeout=3)\n"
+        "        if resp.status_code == 200:\n"
+        "            return resp.json()\n"
+        "    except Exception:\n"
+        "        pass\n"
+        "    # Fallback to local backup file\n"
+        "    local_file = os.path.join(os.path.dirname(__file__), 'data', 'local_telemetry.json')\n"
+        "    if os.path.exists(local_file):\n"
+        "        try:\n"
+        "            with open(local_file, 'r', encoding='utf-8') as f:\n"
+        "                return list(reversed(json.load(f)))\n"
+        "        except Exception:\n"
+        "            pass\n"
+        "    return []\n\n"
+        "records = fetch_data()\n\n"
+        "if not records:\n"
+        "    st.warning('No telemetry records found. Start `python server.py` and run `python client_sender.py` to send data.')\n"
+        "else:\n"
+        "    latest = records[0]\n"
+        "    col1, col2, col3 = st.columns(3)\n"
+        "    col1.metric('Latest Temperature', f\"{latest.get('temperature', 0):.1f} °C\")\n"
+        "    col2.metric('Latest Humidity', f\"{latest.get('humidity', 0):.1f} %\")\n"
+        "    col3.metric('Total Records', len(records))\n\n"
+        "    # Plot history\n"
+        "    temps = [r.get('temperature', 0) for r in reversed(records[-30:])]\n"
+        "    hums = [r.get('humidity', 0) for r in reversed(records[-30:])]\n"
+        "    st.subheader('📈 Telemetry Trends')\n"
+        "    st.line_chart({'Temperature (°C)': temps, 'Humidity (%)': hums})\n\n"
+        "    st.subheader('📋 Recent Telemetry Records')\n"
+        "    st.dataframe(records[:20], use_container_width=True)\n"
+    )
+
+    # README.md
+    if mode == "learning":
+        readme_content = (
+            "# Program 5 — HTTP REST API + Cloud Database + Dashboard\n\n"
+            "## 1. Overview\n"
+            "This practical demonstrates a complete IoT communication pipeline:\n"
+            "- A sensor client collects real ambient readings (temperature and humidity).\n"
+            "- Telemetry is transmitted over HTTP REST (`POST /api/telemetry`).\n"
+            "- The Flask REST API persists records in a cloud database (**Supabase PostgreSQL** or **Firebase Realtime Database**).\n"
+            "- A **Streamlit** dashboard retrieves and displays live metric cards, trend charts, and data tables.\n\n"
+            "## 2. Architecture & Data Flow\n"
+            "```\n"
+            "+--------------------+     HTTP POST JSON     +--------------------+\n"
+            "|   client_sender    | ---------------------> |     server.py      |\n"
+            "| (DHT/Real Readings)|                        |  (Flask REST API)  |\n"
+            "+--------------------+                        +--------------------+\n"
+            "                                                        |\n"
+            "                              +-------------------------+-------------------------+\n"
+            "                              v                                                   v\n"
+            "                   +----------------------+                            +----------------------+\n"
+            "                   | Supabase (PostgreSQL)|                            |  Firebase Realtime   |\n"
+            "                   |   (REST PostgREST)   |                            |     (REST API)       |\n"
+            "                   +----------------------+                            +----------------------+\n"
+            "                              ^                                                   ^\n"
+            "                              |                 Query Telemetry                   |\n"
+            "                              +---------------------------------------------------+\n"
+            "                                                        |\n"
+            "                                              +-------------------+\n"
+            "                                              |   dashboard.py    |\n"
+            "                                              |    (Streamlit)    |\n"
+            "                                              +-------------------+\n"
+            "```\n\n"
+            "## 3. Step-by-Step Execution Guide\n\n"
+            "### Step A: Setup Environment\n"
+            "```bash\n"
+            "python3 -m venv .venv\n"
+            "# Linux / macOS:\n"
+            "source .venv/bin/activate\n"
+            "# Windows (PowerShell):\n"
+            "# .\\.venv\\Scripts\\Activate.ps1\n\n"
+            "pip install -r requirements.txt\n"
+            "```\n\n"
+            "### Step B: Configure Cloud Database\n"
+            "1. Copy `.env.example` to `.env`:\n"
+            "   ```bash\n"
+            "   cp .env.example .env\n"
+            "   ```\n"
+            "2. If using Supabase:\n"
+            "   - Create a project at [supabase.com](https://supabase.com).\n"
+            "   - Open SQL Editor and execute the statements in `supabase_schema.sql`.\n"
+            "   - Copy your **Project URL** and **anon public key** into `.env`.\n"
+            "3. If credentials are not yet configured, the server gracefully falls back to local storage so you can test immediately.\n\n"
+            "### Step C: Run the Components (3 Terminals)\n"
+            "- **Terminal 1 — REST Server:**\n"
+            "  ```bash\n"
+            "  python server.py\n"
+            "  ```\n"
+            "- **Terminal 2 — Sensor Client:**\n"
+            "  ```bash\n"
+            "  # Stream calibrated real readings:\n"
+            "  python client_sender.py\n"
+            "  # Or send manual thermometer reading:\n"
+            "  python client_sender.py --temp 28.5 --humidity 64.2\n"
+            "  # Or interactive prompt:\n"
+            "  python client_sender.py --interactive\n"
+            "  ```\n"
+            "- **Terminal 3 — Live Dashboard:**\n"
+            "  ```bash\n"
+            "  streamlit run dashboard.py\n"
+            "  ```\n\n"
+            "## 4. Common Errors & Troubleshooting\n"
+            "- **Connection Refused (`Errno 111`)**: Ensure `python server.py` is actively running in Terminal 1 before launching the client or dashboard.\n"
+            "- **Supabase 401 Unauthorized**: Check that `SUPABASE_KEY` contains the full `anon` key without leading or trailing spaces.\n"
+            "- **Table does not exist**: Ensure you ran `supabase_schema.sql` in the Supabase SQL editor.\n\n"
+            "## 5. Viva Questions and Answers\n"
+            "**Q1: What are the key advantages of HTTP REST for IoT gateways?**  \n"
+            "A: REST uses standard HTTP verbs (GET, POST), is firewall-friendly, works natively with cloud databases and web services, and formats payloads in human-readable JSON.\n\n"
+            "**Q2: What is the purpose of Row Level Security (RLS) in Supabase?**  \n"
+            "A: RLS allows defining granular PostgreSQL security policies to restrict which client roles (anon vs authenticated) can select, insert, update, or delete rows.\n"
+        )
+    else:
+        readme_content = (
+            "# Program 5 — HTTP REST API + Cloud Database (Exam Mode)\n\n"
+            "## Setup Commands\n"
+            "```bash\n"
+            "pip install -r requirements.txt\n"
+            "cp .env.example .env\n"
+            "```\n\n"
+            "## Execution\n"
+            "1. Terminal 1 (Start REST API Server):\n"
+            "   ```bash\n"
+            "   python server.py\n"
+            "   ```\n"
+            "2. Terminal 2 (Send Sensor Telemetry):\n"
+            "   ```bash\n"
+            "   python client_sender.py\n"
+            "   ```\n"
+            "3. Terminal 3 (Launch Web Dashboard):\n"
+            "   ```bash\n"
+            "   streamlit run dashboard.py\n"
+            "   ```\n\n"
+            "## Viva Q&A\n"
+            "- **Q: Why use HTTP POST for sensor readings?**  \n"
+            "  A: HTTP POST sends telemetry data inside the request body (JSON) without size limits and creates new server records.\n"
+            "- **Q: How does Supabase persist IoT records?**  \n"
+            "  A: Supabase uses PostgreSQL with an automatic REST layer (PostgREST) that accepts JSON POST requests to insert records.\n"
+        )
+
+    files["README.md"] = readme_content
+    return files