iotlabkit 1.0.0__py3-none-any.whl

iotlabkit/__init__.py

@@ -0,0 +1,30 @@
+"""iotlabkit - A Beginner-Friendly IoT Lab Code Generator.
+
+Designed for MSc/MCA Semester 3 IoT Laboratory practicals (Programs 5-17).
+Generates clean, working, self-contained project templates in Learning and Exam modes.
+"""
+
+__version__ = "1.0.0"
+__author__ = "IoT Lab Contributors"
+__license__ = "MIT"
+
+from iotlabkit.registry import (
+    PROGRAMS,
+    SUPPORTED_PROGRAM_IDS,
+    EXCLUDED_PROGRAM_IDS,
+    get_program,
+    list_programs,
+)
+from iotlabkit.generator import generate_program
+from iotlabkit.doctor import run_doctor
+
+__all__ = [
+    "__version__",
+    "PROGRAMS",
+    "SUPPORTED_PROGRAM_IDS",
+    "EXCLUDED_PROGRAM_IDS",
+    "get_program",
+    "list_programs",
+    "generate_program",
+    "run_doctor",
+]

iotlabkit/cli.py

@@ -0,0 +1,239 @@
+"""Command-Line Interface (CLI) for iotlabkit.
+
+Provides beginner-friendly commands:
+  - `iotlabkit list`
+  - `iotlabkit info <id>`
+  - `iotlabkit create <id> [--mode learning|exam] [--output <dir>] [--force]`
+  - `iotlabkit doctor`
+"""
+
+import argparse
+import sys
+from iotlabkit import __version__
+from iotlabkit.registry import (
+    PROGRAMS,
+    SUPPORTED_PROGRAM_IDS,
+    EXCLUDED_PROGRAM_IDS,
+    get_program,
+    list_programs,
+)
+from iotlabkit.generator import generate_program
+from iotlabkit.doctor import run_doctor
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """Displays all supported practical programs and their operational flags."""
+    programs = list_programs()
+
+    print("\n" + "=" * 90)
+    print("           iotlabkit — MSc/MCA IoT Laboratory Practicals (Programs 5-17)")
+    print("=" * 90)
+    print(
+        f"{'ID':<4} | {'Title':<45} | {'Net':<4} | {'Keys':<5} | {'Broker':<6} | {'Data':<5} | {'Server':<6}"
+    )
+    print("-" * 90)
+
+    current_layer = None
+    for p in programs:
+        if p.layer != current_layer:
+            current_layer = p.layer
+            print(f"\n--- {current_layer} ---")
+
+        net_str = "Yes" if p.requires_internet else "No"
+        keys_str = "Yes" if p.requires_credentials else "No"
+        broker_str = "Yes" if p.requires_broker else "No"
+        data_str = "Yes" if p.requires_dataset else "No"
+        srv_str = "Yes" if p.requires_server else "No"
+
+        title_trunc = p.title if len(p.title) <= 45 else p.title[:42] + "..."
+        print(
+            f"{p.id:<4} | {title_trunc:<45} | {net_str:<4} | {keys_str:<5} | {broker_str:<6} | {data_str:<5} | {srv_str:<6}"
+        )
+
+    print("\n" + "-" * 90)
+    print("Legend:")
+    print("  Net    : Requires active internet connectivity")
+    print("  Keys   : Requires cloud credentials (e.g. Supabase, Firebase, ThingsBoard)")
+    print("  Broker : Requires external or local MQTT broker")
+    print("  Data   : Requires local dataset file (included or downloadable)")
+    print("  Server : Runs or requires a local server component")
+    print("\nCommands:")
+    print("  iotlabkit info <id>                  # View full details & viva for a program")
+    print("  iotlabkit create <id>                # Generate project in learning mode")
+    print("  iotlabkit create <id> --mode exam    # Generate concise project for lab exams")
+    print("=" * 90 + "\n")
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    """Displays detailed information, setup steps, and viva preview for a practical."""
+    program_id = args.program_id
+
+    if program_id in EXCLUDED_PROGRAM_IDS:
+        print(f"\n❌ Error: Program {program_id} is outside the supported syllabus scope.")
+        print("   Only Programs 5 through 17 are included in iotlabkit.\n")
+        return 1
+
+    try:
+        p = get_program(program_id)
+    except ValueError as err:
+        print(f"\n❌ Error: {err}\n")
+        return 1
+
+    print("\n" + "=" * 75)
+    print(f"Program {p.id}: {p.title}")
+    print("=" * 75)
+    print(f"Layer            : {p.layer}")
+    print(f"Description      : {p.description}")
+    print(f"Core Objective   : {p.objective}")
+    print(f"Data Source / API: {p.source_info}")
+
+    print("\nOperational Flags:")
+    print(f"  • Internet Required  : {'Yes' if p.requires_internet else 'No'}")
+    print(f"  • Cloud Credentials  : {'Yes' if p.requires_credentials else 'No'}")
+    print(f"  • External Broker    : {'Yes' if p.requires_broker else 'No'}")
+    print(f"  • Local Dataset      : {'Yes' if p.requires_dataset else 'No'}")
+    print(f"  • Local Server       : {'Yes' if p.requires_server else 'No'}")
+
+    print("\nRequired Python Dependencies:")
+    if p.dependencies:
+        print(f"  {', '.join(p.dependencies)}")
+    else:
+        print("  None (Pure Python standard library)")
+
+    print("\nPrerequisites:")
+    for pre in p.prerequisites:
+        print(f"  - {pre}")
+
+    print("\nSetup & Execution Steps:")
+    for step in p.setup_steps:
+        print(f"  {step}")
+
+    print("\nGenerated Files:")
+    for gf in p.generated_files:
+        print(f"  • {gf}")
+
+    if p.viva_preview:
+        print("\nSample Viva Questions & Answers:")
+        for q, a in p.viva_preview:
+            print(f"  Q: {q}")
+            print(f"  A: {a}\n")
+
+    print("=" * 75)
+    print(f"To generate this practical:")
+    print(f"  iotlabkit create {p.id} --mode learning   # Detailed guide & comments")
+    print(f"  iotlabkit create {p.id} --mode exam       # Concise code for lab examination")
+    print("=" * 75 + "\n")
+    return 0
+
+
+def cmd_create(args: argparse.Namespace) -> int:
+    """Generates project directory for requested practical."""
+    program_id = args.program_id
+
+    if program_id in EXCLUDED_PROGRAM_IDS:
+        print(f"\n❌ Error: Program {program_id} is outside the supported syllabus scope.")
+        print("   Only Programs 5 through 17 are included in iotlabkit.\n")
+        return 1
+
+    try:
+        generate_program(
+            program_id=program_id,
+            output_dir=args.output,
+            mode=args.mode,
+            force=args.force,
+            interactive=not args.force,
+        )
+        return 0
+    except Exception as err:
+        print(f"\n❌ Error generating practical {program_id}: {err}\n")
+        return 1
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    """Runs system diagnostics."""
+    return run_doctor()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Builds and returns the main argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="iotlabkit",
+        description="iotlabkit — A Beginner-Friendly IoT Lab Code Generator (Programs 5-17).",
+        epilog="Designed for MSc/MCA Semester 3 IoT Laboratory practicals.",
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # list
+    parser_list = subparsers.add_parser("list", help="List all supported practical programs")
+    parser_list.set_defaults(func=cmd_list)
+
+    # info
+    parser_info = subparsers.add_parser(
+        "info", help="Display description, prerequisites, and viva for a program"
+    )
+    parser_info.add_argument(
+        "program_id", type=int, help="Program number (e.g. 5, 8, 12, 15, 17)"
+    )
+    parser_info.set_defaults(func=cmd_info)
+
+    # create
+    parser_create = subparsers.add_parser(
+        "create", help="Generate a complete project directory for a program"
+    )
+    parser_create.add_argument(
+        "program_id", type=int, help="Program number (5 through 17)"
+    )
+    parser_create.add_argument(
+        "-m",
+        "--mode",
+        choices=["learning", "exam"],
+        default="learning",
+        help="Presentation mode: 'learning' (detailed guides) or 'exam' (concise lab submission)",
+    )
+    parser_create.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default=None,
+        help="Custom output directory name (defaults to 'labXX')",
+    )
+    parser_create.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Overwrite existing files without prompting for confirmation",
+    )
+    parser_create.set_defaults(func=cmd_create)
+
+    # doctor
+    parser_doctor = subparsers.add_parser(
+        "doctor", help="Check Python environment, dependencies, and configuration"
+    )
+    parser_doctor.set_defaults(func=cmd_doctor)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    """CLI main entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    if hasattr(args, "func"):
+        return args.func(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

iotlabkit/coap_util.py

@@ -0,0 +1,322 @@
+"""Pure Python RFC 7252 CoAP (Constrained Application Protocol) Client and Server.
+
+This module provides a lightweight, pure-Python implementation of RFC 7252 CoAP over UDP.
+It operates on UDP port 5683 by default and requires ZERO external dependencies,
+ensuring beginner students can immediately run Programs 8 and 10 in standard lab environments.
+"""
+
+import socket
+import struct
+import threading
+import time
+from typing import Callable, Dict, List, Optional, Tuple
+
+# CoAP Message Types
+TYPE_CON = 0  # Confirmable
+TYPE_NON = 1  # Non-confirmable
+TYPE_ACK = 2  # Acknowledgement
+TYPE_RST = 3  # Reset
+
+# CoAP Method Codes (Request)
+METHOD_EMPTY = 0
+METHOD_GET = 1
+METHOD_POST = 2
+METHOD_PUT = 3
+METHOD_DELETE = 4
+
+# CoAP Response Codes: (class << 5) | detail
+CODE_CONTENT = (2 << 5) | 5         # 2.05 Content (69)
+CODE_CHANGED = (2 << 5) | 4         # 2.04 Changed (68)
+CODE_CREATED = (2 << 5) | 1         # 2.01 Created (65)
+CODE_BAD_REQUEST = (4 << 5) | 0     # 4.00 Bad Request (128)
+CODE_NOT_FOUND = (4 << 5) | 4       # 4.04 Not Found (132)
+CODE_INTERNAL_ERR = (5 << 5) | 0    # 5.00 Internal Server Error (160)
+
+# CoAP Option Numbers
+OPT_URI_PATH = 11
+OPT_CONTENT_FORMAT = 12
+OPT_URI_QUERY = 15
+
+# Content Formats
+FORMAT_TEXT_PLAIN = 0
+FORMAT_APP_JSON = 50
+
+DEFAULT_COAP_PORT = 5683
+
+
+class CoAPMessage:
+    """Represents a standard RFC 7252 CoAP message."""
+
+    def __init__(
+        self,
+        msg_type: int = TYPE_CON,
+        code: int = METHOD_GET,
+        msg_id: int = 1,
+        token: bytes = b"",
+        options: Optional[List[Tuple[int, bytes]]] = None,
+        payload: bytes = b"",
+    ):
+        self.version = 1
+        self.msg_type = msg_type
+        self.code = code
+        self.msg_id = msg_id
+        self.token = token
+        self.options = options or []
+        self.payload = payload
+
+    @property
+    def path(self) -> str:
+        """Extracts the URI path from Uri-Path options."""
+        segments = []
+        for opt_num, opt_val in self.options:
+            if opt_num == OPT_URI_PATH:
+                segments.append(opt_val.decode("utf-8", errors="replace"))
+        return "/" + "/".join(segments) if segments else "/"
+
+    @property
+    def payload_text(self) -> str:
+        """Returns payload decoded as UTF-8 text."""
+        return self.payload.decode("utf-8", errors="replace")
+
+    def encode(self) -> bytes:
+        """Encodes the CoAP message into standard RFC 7252 binary format."""
+        tkl = len(self.token) & 0x0F
+        first_byte = ((self.version & 0x03) << 6) | ((self.msg_type & 0x03) << 4) | tkl
+        header = struct.pack("!BBH", first_byte, self.code & 0xFF, self.msg_id & 0xFFFF)
+        buf = bytearray(header)
+        buf.extend(self.token[:tkl])
+
+        # Sort options by option number
+        sorted_opts = sorted(self.options, key=lambda x: x[0])
+        last_opt_num = 0
+
+        for opt_num, opt_val in sorted_opts:
+            delta = opt_num - last_opt_num
+            length = len(opt_val)
+
+            delta_nibble, delta_ext = self._encode_opt_field(delta)
+            length_nibble, length_ext = self._encode_opt_field(length)
+
+            opt_header = ((delta_nibble & 0x0F) << 4) | (length_nibble & 0x0F)
+            buf.append(opt_header)
+            buf.extend(delta_ext)
+            buf.extend(length_ext)
+            buf.extend(opt_val)
+
+            last_opt_num = opt_num
+
+        if self.payload:
+            buf.append(0xFF)  # Payload marker
+            buf.extend(self.payload)
+
+        return bytes(buf)
+
+    @classmethod
+    def decode(cls, data: bytes) -> "CoAPMessage":
+        """Decodes an RFC 7252 binary buffer into a CoAPMessage."""
+        if len(data) < 4:
+            raise ValueError(f"CoAP message too short: {len(data)} bytes")
+
+        first_byte, code, msg_id = struct.unpack("!BBH", data[:4])
+        version = (first_byte >> 6) & 0x03
+        msg_type = (first_byte >> 4) & 0x03
+        tkl = first_byte & 0x0F
+
+        if version != 1:
+            raise ValueError(f"Unsupported CoAP version: {version}")
+
+        idx = 4
+        token = data[idx : idx + tkl]
+        idx += tkl
+
+        options = []
+        last_opt_num = 0
+        payload = b""
+
+        while idx < len(data):
+            if data[idx] == 0xFF:
+                # Payload marker reached
+                payload = data[idx + 1 :]
+                break
+
+            opt_header = data[idx]
+            idx += 1
+            delta_nibble = (opt_header >> 4) & 0x0F
+            length_nibble = opt_header & 0x0F
+
+            delta, idx = cls._decode_opt_field(delta_nibble, data, idx)
+            length, idx = cls._decode_opt_field(length_nibble, data, idx)
+
+            opt_num = last_opt_num + delta
+            opt_val = data[idx : idx + length]
+            idx += length
+
+            options.append((opt_num, opt_val))
+            last_opt_num = opt_num
+
+        msg = cls(
+            msg_type=msg_type,
+            code=code,
+            msg_id=msg_id,
+            token=token,
+            options=options,
+            payload=payload,
+        )
+        return msg
+
+    @staticmethod
+    def _encode_opt_field(val: int) -> Tuple[int, bytes]:
+        if val < 13:
+            return val, b""
+        elif val < 269:
+            return 13, struct.pack("!B", val - 13)
+        else:
+            return 14, struct.pack("!H", val - 269)
+
+    @staticmethod
+    def _decode_opt_field(nibble: int, data: bytes, idx: int) -> Tuple[int, int]:
+        if nibble < 13:
+            return nibble, idx
+        elif nibble == 13:
+            if idx >= len(data):
+                raise ValueError("Unexpected end of option delta/length")
+            val = data[idx] + 13
+            return val, idx + 1
+        elif nibble == 14:
+            if idx + 1 >= len(data):
+                raise ValueError("Unexpected end of option delta/length (2-byte)")
+            val = struct.unpack("!H", data[idx : idx + 2])[0] + 269
+            return val, idx + 2
+        else:
+            raise ValueError(f"Reserved option nibble: {nibble}")
+
+    def __repr__(self) -> str:
+        code_str = f"{self.code >> 5}.{self.code & 0x1F:02d}"
+        return (
+            f"CoAPMessage(type={self.msg_type}, code={code_str}, id={self.msg_id}, "
+            f"path='{self.path}', payload_len={len(self.payload)})"
+        )
+
+
+class CoAPServer:
+    """A lightweight, multi-threaded CoAP UDP Server."""
+
+    def __init__(self, host: str = "0.0.0.0", port: int = DEFAULT_COAP_PORT):
+        self.host = host
+        self.port = port
+        self.resources: Dict[str, Callable[[], Tuple[int, str]]] = {}
+        self.sock: Optional[socket.socket] = None
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+
+    def add_resource(self, path: str, handler: Callable[[], Tuple[int, str]]):
+        """Registers a URL path handler that returns (status_code, payload_text)."""
+        clean_path = "/" + path.strip("/")
+        self.resources[clean_path] = handler
+
+    def start(self, blocking: bool = False):
+        """Binds socket and starts listening for CoAP client requests."""
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.sock.bind((self.host, self.port))
+        self.sock.settimeout(1.0)
+        self._running = True
+
+        if blocking:
+            self._serve()
+        else:
+            self._thread = threading.Thread(target=self._serve, daemon=True)
+            self._thread.start()
+
+    def _serve(self):
+        while self._running:
+            try:
+                data, addr = self.sock.recvfrom(2048)
+            except (socket.timeout, OSError):
+                continue
+
+            try:
+                req = CoAPMessage.decode(data)
+                resp = self._handle_request(req)
+                self.sock.sendto(resp.encode(), addr)
+            except Exception as e:
+                pass
+
+    def _handle_request(self, req: CoAPMessage) -> CoAPMessage:
+        path = req.path
+        handler = self.resources.get(path)
+
+        if not handler:
+            return CoAPMessage(
+                msg_type=TYPE_ACK if req.msg_type == TYPE_CON else TYPE_NON,
+                code=CODE_NOT_FOUND,
+                msg_id=req.msg_id,
+                token=req.token,
+                payload=f"Resource '{path}' not found".encode("utf-8"),
+            )
+
+        try:
+            status_code, payload_text = handler()
+            payload_bytes = payload_text.encode("utf-8")
+            return CoAPMessage(
+                msg_type=TYPE_ACK if req.msg_type == TYPE_CON else TYPE_NON,
+                code=status_code,
+                msg_id=req.msg_id,
+                token=req.token,
+                options=[(OPT_CONTENT_FORMAT, struct.pack("!B", FORMAT_APP_JSON))],
+                payload=payload_bytes,
+            )
+        except Exception as err:
+            return CoAPMessage(
+                msg_type=TYPE_ACK if req.msg_type == TYPE_CON else TYPE_NON,
+                code=CODE_INTERNAL_ERR,
+                msg_id=req.msg_id,
+                token=req.token,
+                payload=f"Server error: {err}".encode("utf-8"),
+            )
+
+    def stop(self):
+        """Stops the server and releases the socket."""
+        self._running = False
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=2.0)
+        if self.sock:
+            try:
+                self.sock.close()
+            except Exception:
+                pass
+
+
+class CoAPClient:
+    """A synchronous CoAP client for making GET requests."""
+
+    def __init__(self, timeout: float = 3.0):
+        self.timeout = timeout
+        self._msg_counter = 100
+
+    def get(self, host: str, port: int, path: str) -> CoAPMessage:
+        """Sends a CoAP GET request to the specified host:port/path."""
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.settimeout(self.timeout)
+
+        self._msg_counter = (self._msg_counter + 1) % 65535
+        clean_path = path.strip("/")
+        options = []
+        if clean_path:
+            for segment in clean_path.split("/"):
+                options.append((OPT_URI_PATH, segment.encode("utf-8")))
+
+        req = CoAPMessage(
+            msg_type=TYPE_CON,
+            code=METHOD_GET,
+            msg_id=self._msg_counter,
+            token=struct.pack("!H", self._msg_counter),
+            options=options,
+        )
+
+        try:
+            sock.sendto(req.encode(), (host, port))
+            data, _ = sock.recvfrom(2048)
+            return CoAPMessage.decode(data)
+        finally:
+            sock.close()