monkeybrain-runtime 1.0.0__py3-none-any.whl

services/iot/models/servers.py

@@ -0,0 +1,206 @@
+from datetime import datetime, date
+from typing import Optional, Literal, List
+from pydantic import BaseModel, Field, model_validator
+
+# ─────────────────────────────────────────────
+# LITERALS
+# ─────────────────────────────────────────────
+
+EdgeServerStatus = Literal[
+    "Online",
+    "Offline",
+    "Degraded",
+    "Maintenance",
+    "Decommissioned",
+]
+
+EdgeServerRole = Literal[
+    "Primary Gateway",
+    "Redundant Gateway",
+    "Protocol Translator",
+    "Data Aggregator",
+    "Local Historian",
+    "Other",
+]
+
+ConnectivityType = Literal[
+    "Ethernet",
+    "Wi-Fi",
+    "4G / LTE",
+    "5G",
+    "Fibre",
+    "Serial RS-485",
+    "Other",
+]
+
+OperatingSystem = Literal[
+    "Linux",
+    "Windows IoT",
+    "FreeRTOS",
+    "VxWorks",
+    "QNX",
+    "Other",
+]
+
+# ─────────────────────────────────────────────
+# BASE
+# ─────────────────────────────────────────────
+
+class EdgeServer(BaseModel):
+    server_id:            str              = Field(..., min_length=1)
+    serial_no:            str              = Field(..., min_length=1)
+    model_no:             str              = Field(..., min_length=1)
+    name:                 Optional[str]    = None
+    description:          Optional[str]    = None
+
+    role:                 EdgeServerRole   = "Primary Gateway"
+    status:               EdgeServerStatus = "Offline"
+
+    # Linkage
+    asset_tag:            Optional[str]    = None
+    parent_server_id:     Optional[str]    = None   # for redundant / hierarchical setups
+
+    # Location
+    plant_id:             str
+    building_id:          str
+    floor_id:             str
+    room_id:              str
+    bay_id:               str
+    workstation_id:       str
+    rack_position:        Optional[str]    = None   # e.g. "Rack A - U12"
+
+    # Manufacturer
+    manufacturer:         str
+    manufacturer_country: Optional[str]    = None
+
+    # Network
+    ip_address:           Optional[str]    = None
+    mac_address:          Optional[str]    = None
+    hostname:             Optional[str]    = None
+    subnet_mask:          Optional[str]    = None
+    gateway_ip:           Optional[str]    = None
+    connectivity_type:    ConnectivityType = "Ethernet"
+    vpn_enabled:          bool             = False
+
+    # Hardware specs
+    cpu:                  Optional[str]    = None   # e.g. "Intel Atom x6425E"
+    ram_gb:               Optional[float]  = Field(None, gt=0)
+    storage_gb:           Optional[float]  = Field(None, gt=0)
+    operating_system:     OperatingSystem  = "Linux"
+    os_version:           Optional[str]    = None
+    firmware_version:     Optional[str]    = None
+
+    # Supported protocols (list of protocols this gateway bridges)
+    supported_protocols:  List[str]        = Field(default_factory=list)
+
+    # Capacity
+    max_sensor_count:     Optional[int]    = Field(None, gt=0)
+    connected_sensor_count: int            = Field(default=0, ge=0)
+
+    # Uptime / health
+    last_heartbeat:       Optional[datetime] = None
+    uptime_seconds:       Optional[int]    = Field(None, ge=0)
+
+    # Cloud / SCADA upstream
+    upstream_broker_url:  Optional[str]    = None   # MQTT broker / OPC-UA server URL
+    upstream_topic_prefix: Optional[str]   = None
+
+    # Dates
+    purchase_date:        Optional[date]   = None
+    installation_date:    Optional[date]   = None
+    warranty_expiry_date: Optional[date]   = None
+
+    created_at:           datetime         = Field(default_factory=datetime.utcnow)
+    updated_at:           datetime         = Field(default_factory=datetime.utcnow)
+
+    # ── Validators ────────────────────────────────────────────────────────────
+
+    @model_validator(mode="after")
+    def installation_after_purchase(self):
+        if self.purchase_date and self.installation_date:
+            if self.installation_date < self.purchase_date:
+                raise ValueError("'installation_date' cannot be before 'purchase_date'.")
+        return self
+
+    @model_validator(mode="after")
+    def sensor_count_within_capacity(self):
+        if (
+            self.max_sensor_count is not None
+            and self.connected_sensor_count > self.max_sensor_count
+        ):
+            raise ValueError(
+                f"'connected_sensor_count' ({self.connected_sensor_count}) exceeds "
+                f"'max_sensor_count' ({self.max_sensor_count})."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def redundant_requires_parent(self):
+        if self.role == "Redundant Gateway" and not self.parent_server_id:
+            raise ValueError("A 'Redundant Gateway' must reference a 'parent_server_id'.")
+        return self
+
+# ─────────────────────────────────────────────
+# CREATE
+# ─────────────────────────────────────────────
+
+class EdgeServerCreate(EdgeServer):
+    pass
+
+# ─────────────────────────────────────────────
+# UPDATE
+# ─────────────────────────────────────────────
+
+class EdgeServerUpdate(BaseModel):
+    serial_no:               Optional[str]              = None
+    model_no:                Optional[str]              = None
+    name:                    Optional[str]              = None
+    description:             Optional[str]              = None
+    role:                    Optional[EdgeServerRole]   = None
+    status:                  Optional[EdgeServerStatus] = None
+    asset_tag:               Optional[str]              = None
+    parent_server_id:        Optional[str]              = None
+    facility:                Optional[str]              = None
+    building:                Optional[str]              = None
+    room:                    Optional[str]              = None
+    rack_position:           Optional[str]              = None
+    manufacturer:            Optional[str]              = None
+    manufacturer_country:    Optional[str]              = None
+    ip_address:              Optional[str]              = None
+    mac_address:             Optional[str]              = None
+    hostname:                Optional[str]              = None
+    subnet_mask:             Optional[str]              = None
+    gateway_ip:              Optional[str]              = None
+    connectivity_type:       Optional[ConnectivityType] = None
+    vpn_enabled:             Optional[bool]             = None
+    cpu:                     Optional[str]              = None
+    ram_gb:                  Optional[float]            = Field(None, gt=0)
+    storage_gb:              Optional[float]            = Field(None, gt=0)
+    operating_system:        Optional[OperatingSystem]  = None
+    os_version:              Optional[str]              = None
+    firmware_version:        Optional[str]              = None
+    supported_protocols:     Optional[List[str]]        = None
+    max_sensor_count:        Optional[int]              = Field(None, gt=0)
+    connected_sensor_count:  Optional[int]              = Field(None, ge=0)
+    last_heartbeat:          Optional[datetime]         = None
+    uptime_seconds:          Optional[int]              = Field(None, ge=0)
+    upstream_broker_url:     Optional[str]              = None
+    upstream_topic_prefix:   Optional[str]              = None
+    purchase_date:           Optional[date]             = None
+    installation_date:       Optional[date]             = None
+    warranty_expiry_date:    Optional[date]             = None
+    updated_at:              datetime                   = Field(default_factory=datetime.utcnow)
+
+# ─────────────────────────────────────────────
+# RESPONSE & PAGINATION
+# ─────────────────────────────────────────────
+
+class EdgeServerResponse(EdgeServer):
+    class Config:
+        from_attributes = True
+
+class PaginatedEdgeServerResponse(BaseModel):
+    total:     int
+    page:      int
+    page_size: int
+    results:   List[EdgeServerResponse]

services/iot/models/uwb_device.py

@@ -0,0 +1,106 @@
+from datetime import datetime
+from typing import Literal, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+from services.iot.models.ble_device import (
+    BatteryInfo,
+    Coordinates,
+    DeviceCapabilities,
+    FirmwareInfo,
+    SignalMetrics,
+)
+
+
+class UWBAnchorConfig(BaseModel):
+    anchor_id: str = Field(..., min_length=1, max_length=100)
+    role: Literal["anchor", "tag"]
+    update_rate_hz: Optional[int] = Field(10, gt=0)
+    positioning_mode: Literal["tdoa", "twr", "aoa"] = "tdoa"
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class UWBPrecisionMetrics(BaseModel):
+    accuracy_cm: Optional[float] = Field(None, ge=0)
+    distance_m: Optional[float] = Field(None, ge=0)
+    angle_deg: Optional[float] = None
+    update_frequency_hz: Optional[float] = Field(None, ge=0)
+
+
+class UWBDevice(BaseModel):
+    device_type: Literal["uwb"] = "uwb"
+    id: UUID | str = Field(default_factory=uuid4)
+    name: str = Field(..., min_length=1, max_length=150)
+    mac_address: Optional[str] = Field(None, max_length=32)
+    serial_number: Optional[str] = Field(None, max_length=100)
+    manufacturer: Optional[str] = Field(None, max_length=150)
+    model: Optional[str] = Field(None, max_length=150)
+    uwb_chipset: Optional[str] = Field(None, max_length=100)
+    uwb_channel: Optional[int] = Field(None, ge=0)
+    capabilities: DeviceCapabilities = Field(default_factory=DeviceCapabilities)
+    anchor_config: Optional[UWBAnchorConfig] = None
+    precision_metrics: Optional[UWBPrecisionMetrics] = None
+    signal_metrics: Optional[SignalMetrics] = None
+    battery: Optional[BatteryInfo] = None
+    firmware: Optional[FirmwareInfo] = None
+    current_location: Optional[Coordinates] = None
+    last_seen: datetime = Field(default_factory=datetime.utcnow)
+    active: bool = True
+    tags: list[str] = Field(default_factory=list)
+
+    model_config = {"str_strip_whitespace": True}
+
+    @field_validator("mac_address")
+    @classmethod
+    def normalize_mac_address(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+
+class UWBDeviceCreate(UWBDevice):
+    pass
+
+
+class UWBDeviceUpdate(BaseModel):
+    device_type: Optional[Literal["uwb"]] = None
+    name: Optional[str] = Field(None, min_length=1, max_length=150)
+    mac_address: Optional[str] = Field(None, max_length=32)
+    serial_number: Optional[str] = Field(None, max_length=100)
+    manufacturer: Optional[str] = Field(None, max_length=150)
+    model: Optional[str] = Field(None, max_length=150)
+    uwb_chipset: Optional[str] = Field(None, max_length=100)
+    uwb_channel: Optional[int] = Field(None, ge=0)
+    capabilities: Optional[DeviceCapabilities] = None
+    anchor_config: Optional[UWBAnchorConfig] = None
+    precision_metrics: Optional[UWBPrecisionMetrics] = None
+    signal_metrics: Optional[SignalMetrics] = None
+    battery: Optional[BatteryInfo] = None
+    firmware: Optional[FirmwareInfo] = None
+    current_location: Optional[Coordinates] = None
+    last_seen: Optional[datetime] = None
+    active: Optional[bool] = None
+    tags: Optional[list[str]] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @field_validator("mac_address")
+    @classmethod
+    def normalize_mac_address(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return None
+        return value.strip().upper()
+
+
+class UWBDeviceResponse(UWBDevice):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedUWBDeviceResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[UWBDeviceResponse]

services/iot/routers/__init__.py

@@ -0,0 +1,8 @@
+"""iot service routers package."""
+
+__all__ = [
+    "ble_device",
+    "sensors",
+    "servers",
+    "uwb_device",
+]

services/iot/routers/ble_device.py

@@ -0,0 +1,110 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.iot.helpers import ble_device as crud
+from services.iot.models.ble_device import (
+    BLEDeviceCreate,
+    BLEDeviceResponse,
+    BLEDeviceUpdate,
+    PaginatedBLEDeviceResponse,
+)
+from services.common.auth import require_permission
+from services.common.db import get_database
+
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedBLEDeviceResponse)
+async def list_ble_devices(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedBLEDeviceResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-mac/{mac_address}", response_model=BLEDeviceResponse)
+async def get_ble_device_by_mac_address(
+    mac_address: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    record = await crud.get_by_mac_address(db, mac_address)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"BLE device '{mac_address}' not found")
+    return record
+
+
+@router.get("/by-active/{active}", response_model=list[BLEDeviceResponse])
+async def list_ble_devices_by_active(
+    active: bool,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    return await crud.get_by_active(db, active)
+
+
+@router.get("/by-tag/{tag}", response_model=list[BLEDeviceResponse])
+async def list_ble_devices_by_tag(
+    tag: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    return await crud.get_by_tag(db, tag)
+
+
+@router.get("/{device_id}", response_model=BLEDeviceResponse)
+async def get_ble_device(
+    device_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    record = await crud.get_by_id(db, device_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"BLE device '{device_id}' not found")
+    return record
+
+
+@router.post("/", response_model=BLEDeviceResponse, status_code=status.HTTP_201_CREATED)
+async def create_ble_device(
+    data: BLEDeviceCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-devices")),
+):
+    device_id = str(data.id)
+    if await crud.get_by_id(db, device_id):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"BLE device '{device_id}' already exists")
+    if await crud.get_by_mac_address(db, data.mac_address):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"BLE device '{data.mac_address}' already exists")
+    return await crud.create(db, data)
+
+
+@router.patch("/{device_id}", response_model=BLEDeviceResponse)
+async def update_ble_device(
+    device_id: str,
+    data: BLEDeviceUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-devices")),
+):
+    if data.mac_address:
+        existing = await crud.get_by_mac_address(db, data.mac_address)
+        if existing and existing.get("id") != device_id:
+            raise HTTPException(status.HTTP_409_CONFLICT, detail=f"BLE device '{data.mac_address}' already exists")
+
+    updated = await crud.update(db, device_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"BLE device '{device_id}' not found")
+    return updated
+
+
+@router.delete("/{device_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_ble_device(
+    device_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-devices")),
+):
+    if not await crud.delete(db, device_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"BLE device '{device_id}' not found")

services/iot/routers/sensors.py

@@ -0,0 +1,144 @@
+from typing import Optional
+from fastapi import APIRouter, HTTPException, Depends, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.common.auth import require_permission
+from services.iot.models.sensors import (
+    SensorCreate,
+    SensorUpdate,
+    SensorResponse,
+    PaginatedSensorResponse,
+)
+from services.iot.helpers import sensors as crud
+from services.iot.helpers import sensor_readings
+
+router = APIRouter()
+
+
+# ── List ──────────────────────────────────────────────────────────────────────
+
+@router.get("/", response_model=PaginatedSensorResponse)
+async def list_sensors(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    sensors, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSensorResponse(total=total, page=page, page_size=page_size, results=sensors)
+
+
+# ── Get by machine ────────────────────────────────────────────────────────────
+
+@router.get("/by-machine/{machine_id}", response_model=list[SensorResponse])
+async def list_sensors_by_machine(
+    machine_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    return await crud.get_by_machine(db, machine_id)
+
+
+@router.get("/by-equipment/{equipment_id}", response_model=list[SensorResponse])
+async def list_sensors_by_equipment(
+    equipment_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    return await crud.get_by_equipment_id(db, equipment_id)
+
+# ── Get by edge server ────────────────────────────────────────────────────────
+
+@router.get("/by-edge-server/{edge_server_id}", response_model=list[SensorResponse])
+async def list_sensors_by_edge_server(
+    edge_server_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    return await crud.get_by_edge_server(db, edge_server_id)
+
+
+# ── Get by facility ───────────────────────────────────────────────────────────
+
+@router.get("/by-facility/{facility}", response_model=list[SensorResponse])
+async def list_sensors_by_facility(
+    facility: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    return await crud.get_by_facility(db, facility)
+
+
+# ── Get one ───────────────────────────────────────────────────────────────────
+
+@router.get("/{sensor_id}", response_model=SensorResponse)
+async def get_sensor(
+    sensor_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    record = await crud.get_by_id(db, sensor_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Sensor '{sensor_id}' not found")
+    return record
+
+
+@router.get("/{sensor_id}/readings")
+async def list_sensor_readings(
+    sensor_id: str,
+    limit: int = Query(100, ge=1, le=1000),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    return await sensor_readings.get_sensor_readings(sensor_id, limit=limit)
+
+
+@router.get("/{sensor_id}/readings/latest")
+async def get_latest_sensor_reading(
+    sensor_id: str,
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    reading = await sensor_readings.get_latest_sensor_reading(sensor_id)
+    if reading is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"No readings found for sensor '{sensor_id}'")
+    return reading
+
+
+# ── Create ────────────────────────────────────────────────────────────────────
+
+@router.post("/", response_model=SensorResponse, status_code=status.HTTP_201_CREATED)
+async def create_sensor(
+    data: SensorCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-sensors")),
+):
+    if await crud.get_by_id(db, data.sensor_id):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"Sensor '{data.sensor_id}' already exists")
+    return await crud.create(db, data)
+
+
+# ── Update ────────────────────────────────────────────────────────────────────
+
+@router.patch("/{sensor_id}", response_model=SensorResponse)
+async def update_sensor(
+    sensor_id: str,
+    data: SensorUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-sensors")),
+):
+    updated = await crud.update(db, sensor_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Sensor '{sensor_id}' not found")
+    return updated
+
+
+# ── Delete ────────────────────────────────────────────────────────────────────
+
+@router.delete("/{sensor_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_sensor(
+    sensor_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-sensors")),
+):
+    if not await crud.delete(db, sensor_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Sensor '{sensor_id}' not found")