espark-core 0.0.0__py3-none-any.whl

espark_core-0.0.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: espark-core
+Version: 0.0.0
+Summary: The core module of the Espark ESP32-based IoT device management framework.
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiomqtt==2.4.0
+Requires-Dist: apscheduler==3.11.1
+Requires-Dist: fastapi==0.124.0
+Requires-Dist: sqlalchemy==2.0.45
+Requires-Dist: sqlmodel==0.0.27
+Requires-Dist: uvicorn[standard]==0.38.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite==0.21.0; extra == "dev"
+Requires-Dist: autopep8==2.3.2; extra == "dev"
+Requires-Dist: build==1.3.0; extra == "dev"
+Requires-Dist: fastapi-cli[standard-no-fastapi-cloud-cli]==0.0.16; extra == "dev"
+Requires-Dist: httpx==0.28.1; extra == "dev"
+Requires-Dist: pycodestyle==2.14.0; extra == "dev"
+Requires-Dist: pylint==4.0.4; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
+Requires-Dist: pytest-cov==7.0.0; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Espark
+
+Espark is a lightweight framework for building scalable and efficient ESP32-based IoT applications. It provides a modular architecture, easy-to-use APIs, and built-in support for common IoT protocols.
+
+## Project Goals
+
+- Simplify the development of ESP32 applications.
+- Provide a modular and extensible architecture.
+- Support common IoT protocols like MQTT.
+- Ensure efficient resource management for low-power devices.
+- Provide a clean and easy-to-use API.
+- Provide an user-friendly UI for configuration and monitoring.
+
+## Features
+
+- **Device Provisioning**: Easy setup and configuration of ESP32 devices.
+- **Telemetry Collection**: Built-in support for collecting and sending telemetry data.
+- **Scalable Architecture**: Designed to handle a large number of devices efficiently.
+- **Seamless Communication**: Support for MQTT protocol.
+
+## Hardware Requirements
+
+- ESP32 Development Board
+- USB Cable for programming and power
+- Optional: Sensors and triggers for specific applications
+
+## Project Structure
+
+```
+espark/
+├── espark-core/
+│   ├── esparkcore/      # FastAPI backend framework
+│   │   ├── data/              # Models, repositories
+│   │   ├── routers/           # API endpoints
+│   │   ├── schedules/         # Background tasks
+│   │   ├── services/          # Business logic, MQTT handling
+│   │   └── utils/             # Utility functions
+│   └── Makefile
+├── espark-node/
+│   ├── esparknode/      # MicroPython application framework
+│   │   ├── actions/           # Action handlers
+│   │   ├── data/              # Data storage
+│   │   ├── libraries/         # External libraries
+│   │   ├── networks/          # Network management
+│   │   ├── sensors/           # Sensor interfaces
+│   │   ├── triggers/          # Trigger interfaces
+│   │   ├── utils/             # Utility functions
+│   │   └── base_node.py       # Main application file
+│   └── Makefile
+└── espark-react/        # React frontend application
+    ├── src/
+    │   ├── data/              # Data models and data providers
+    │   ├── i18n/              # Internationalization files
+    │   ├── pages/             # Application pages
+    │   ├── routes/            # Application routing
+    │   ├── utils/             # Utility functions
+    │   ├── App.tsx            # Main application component
+    │   └── index.tsx          # Application entry point
+    └── package.json
+```
+
+## Development Workflows
+
+### Setting up the backend
+
+1. Add espark-core as a dependency in your FastAPI project.
+2. Configure database connections and MQTT settings as environment variables.
+3. Implement additional data models, repositories, routers, and business logic if needed.
+4. Add the `DeviceRouter`, `TelemetryRouter`, and other additional routers to your FastAPI app.
+
+### Setting up the ESP32 application
+
+1. Clone the espark-node repository to your local machine.
+2. Copy `espark-core/Makefile.template` to `Makefile` and customize it for your device.
+3. Run `make upgrade` to copy the espark-core library to your device project.
+4. Implement device-specific actions, sensors, and triggers as needed.
+5. Run `make flash` to upload the firmware to your ESP32 device.
+6. Run `make deploy` to upload the application to the device.
+
+### Setting up the frontend
+
+1. Add espark-react as a dependency in your React project.
+2. Render `<EsparkApp />` in your main application file.
+
+### Configurations
+
+- **espark-core**: Use environment variables, or `.env` file, for database and MQTT configurations.
+- **espark-node**: Use `esparknode.configs` for device-specific configurations.
+- **espark-react**: Customise `EsparkApp` props for application settings.
+
+## Examples and Patterns
+
+- **Router Example**: `device_router.py` in `espark-core/esparkcore/routers/` demonstrates how to create API endpoints for device management.
+- **Respository Example**: `device_repository.py` in `espark-core/esparkcore/data/repositories/` shows how to implement data access logic for devices.
+- **Action Example**: `esp32_relay.py` in `espark-node/esparknode/actions/` illustrates how to define actions for ESP32 devices.
+- **Sensor Example**: `sht20_sensor.py` in `espark-node/esparknode/sensors/` demonstrates how to read data from a SHT20 sensor.
+- **Trigger Example**: `gpio_trigger.py` in `espark-node/esparknode/triggers/` shows how to create GPIO-based triggers for device actions.
+- **List, Show, Edit Screens Example**: `DeviceList`, `DeviceShow`, and `DeviceEdit` components in `espark-react/src/pages/devices/` demonstrate how to create CRUD screens for device management.
+
+## Example Projects
+
+- **Espartan**: A smart thermostat and open-door alert automation system using ESP32-C3 devices, leveraging espark for device management and telemetry, available at [https://github.com/ayltai/Espartan](https://github.com/ayltai/Espartan).

espark_core-0.0.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+esparkcore/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+esparkcore/constants.py,sha256=jgbhkana_NU_AdcGI0B0OjEOSBAuYNmTroC-vdlD69I,338
+esparkcore/data/__init__.py,sha256=abMOPq6jC5qOQCl9j7iPDv8iyjzDF-oVd_gW0la5kL4,45
+esparkcore/data/database.py,sha256=OaJSBDW6Qge-rsKkSIksJXOg3xF_y6LuBew--6uFbG4,532
+esparkcore/data/models/__init__.py,sha256=y4tnMxZGRsqYTWw-ctWzPMHj1B9xfPYc3Ettoz2vYAI,92
+esparkcore/data/models/device.py,sha256=xXewJHBx4_R_m-N81m0_mcgNmbxzcK0KyCvIGazU3Ck,823
+esparkcore/data/models/outbox.py,sha256=r5bgjIbj9H-OsGhE-CWKGRf4Tp88qMvmxPYHNGOApY4,1309
+esparkcore/data/models/telemetry.py,sha256=OfzGqGj2Y1sdK519sSOEXhfuErHoeEdpy5qmJMIc27A,652
+esparkcore/data/repositories/__init__.py,sha256=uuzaSYEtrifTHYMXr7xGPwXLhvuvccGYfur6w9UG72E,195
+esparkcore/data/repositories/base_repository.py,sha256=L5APTp8SczndbWqgJyEqKe-4NQoL_YYOapUN6i572cM,2097
+esparkcore/data/repositories/device_repository.py,sha256=P9KK-Ta9MgMdrnct5hbGEoipPOPrrDQ4wINQnZZ6iZY,1131
+esparkcore/data/repositories/outbox_repository.py,sha256=PdPyKq2Km4_7732O6HhA4BlV_zBjYF91GkMltNKUovg,1015
+esparkcore/data/repositories/telemetry_repository.py,sha256=5UBBmY-ugcgP0Xji7cu58_nGt8MWKeHz9DHNVJxk0BY,1116
+esparkcore/routers/__init__.py,sha256=kVr51MhvJYVKYZXS9maqf4XXj-4qLyM9UFk5x9BEAnQ,86
+esparkcore/routers/base_router.py,sha256=t-x8tYZVzBk9bD__9yaGYhm66glq_oM_lAHn0eplM2M,3902
+esparkcore/routers/device_router.py,sha256=mIBAyTyxl9AF8Os_Sms6Bb0vEvWfljyElbTWEGLo0iU,1172
+esparkcore/routers/telemetry_router.py,sha256=3ZpgY1fjGkXLmoaxm2paNJNVc5VMf1iZqsDh0xa0TyI,2014
+esparkcore/schedules/__init__.py,sha256=v5Wy3Cbt2AnudGMGXv_Cyaa10s6NAmP66rDjcMSvf0o,74
+esparkcore/schedules/outbox.py,sha256=GGANvjkI7w1BdmmVRgKog498ASD_xRN0g8bG6yC_SN4,811
+esparkcore/schedules/scheduler.py,sha256=aYQXImLZ4tW-hRavn3ObuV3lYjmOZD813YkeG1NsYfY,170
+esparkcore/services/__init__.py,sha256=RIZOHBfkWn3HsApdA5rH9EZbbXGq0NfiGoOWDO_JX1k,30
+esparkcore/services/mqtt.py,sha256=292ZJ9YZbAYGghNFtRoXWbMenOiOo57bIo-D9Pwyr8o,4831
+esparkcore/utils/__init__.py,sha256=rzuCJUAaQl-yPhM1vcWB_1zVXqtA71ChYP2aM_3UfKk,42
+esparkcore/utils/logging.py,sha256=sRO8uOcPkFH-DwepqLOTS2qGaopXpMdVOjzZL6RpGs4,257
+espark_core-0.0.0.dist-info/METADATA,sha256=ozNf9Ni4OQ62CgrIEYc0MEh9Q6fhPYCGffEX2naNRp0,6221
+espark_core-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+espark_core-0.0.0.dist-info/top_level.txt,sha256=hXVyhIPB4aGskFm5queWALxDPhcDkrN7_8vcjwA1iE4,11
+espark_core-0.0.0.dist-info/RECORD,,

espark_core-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

espark_core-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+esparkcore

esparkcore/constants.py

@@ -0,0 +1,9 @@
+ENV_DATABASE_URL : str = 'DATABASE_URL'
+ENV_MQTT_HOST    : str = 'MQTT_HOST'
+ENV_MQTT_PORT    : str = 'MQTT_PORT'
+
+TOPIC_DEVICE       : str = 'espark/device'
+TOPIC_REGISTRATION : str = 'espark/registration'
+TOPIC_TELEMETRY    : str = 'espark/telemetry'
+TOPIC_ACTION       : str = 'espark/action'
+TOPIC_CRASH        : str = 'espark/crash'

esparkcore/data/__init__.py

@@ -0,0 +1 @@
+from .database import async_session, init_db

esparkcore/data/database.py

@@ -0,0 +1,15 @@
+from os import getenv
+
+from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession, create_async_engine
+from sqlmodel import SQLModel
+
+from ..constants import ENV_DATABASE_URL
+
+# pylint: disable=invalid-name
+engine        = create_async_engine(getenv(ENV_DATABASE_URL, 'sqlite+aiosqlite:///database.db'), echo=True)
+async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def init_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)

esparkcore/data/models/__init__.py

@@ -0,0 +1,3 @@
+from .device import Device
+from .outbox import OutboxEvent
+from .telemetry import Telemetry

esparkcore/data/models/device.py

@@ -0,0 +1,13 @@
+from datetime import datetime
+from typing import Dict, Optional
+
+from sqlalchemy import Column
+from sqlmodel import SQLModel, Field, JSON
+
+
+class Device(SQLModel, table=True):
+    id           : str                         = Field(primary_key=True, description='Unique identifier for the device')
+    display_name : Optional[str]               = Field(default=None, description='Human-readable name of the device')
+    capabilities : Optional[str]               = Field(default=None, description='Comma separated capabilities of the device')
+    parameters   : Dict[str, str | int | bool] = Field(default_factory=dict, sa_column=Column(JSON), description='JSON string of capability-specific parameters')
+    last_seen    : datetime                    = Field(index=True, description='Last time the device was seen online')

esparkcore/data/models/outbox.py

@@ -0,0 +1,20 @@
+from datetime import datetime
+from typing import Dict, Optional
+from uuid import UUID, uuid4
+
+from sqlalchemy import Column
+from sqlmodel import SQLModel, Field, JSON, UniqueConstraint
+
+
+class OutboxEvent(SQLModel, table=True):
+    __table_args__ = (
+        UniqueConstraint('device_id', 'event_type', 'is_processed', name='uq_device_event'),
+    )
+
+    id           : UUID               = Field(default_factory=uuid4, primary_key=True, description='Unique identifier for the outbox event')
+    device_id    : str                = Field(foreign_key='device.id', ondelete='CASCADE', index=True, description='Identifier of the device associated with the event')
+    event_type   : str                = Field(index=True, description='Type of the event')
+    payload      : Dict[str, str]     = Field(default_factory=dict, sa_column=Column(JSON), description='JSON string of event-specific payload data')
+    created_at   : datetime           = Field(default_factory=datetime.now, index=True, description='Timestamp when the event was created')
+    processed_at : Optional[datetime] = Field(default=None, index=True, description='Timestamp when the event was processed')
+    is_processed : bool               = Field(default=False, index=True, description='Flag indicating whether the event has been processed')

esparkcore/data/models/telemetry.py

@@ -0,0 +1,12 @@
+from datetime import datetime
+from typing import Optional
+
+from sqlmodel import SQLModel, Field
+
+
+class Telemetry(SQLModel, table=True):
+    id        : Optional[int] = Field(primary_key=True, default=None)
+    device_id : str           = Field(foreign_key='device.id', ondelete='CASCADE', description='Device that sent this data')
+    timestamp : datetime      = Field(index=True, description='Timestamp of the data')
+    data_type : str           = Field(index=True, description='Type of the data (e.g., motion, temperature)')
+    value     : int           = Field(description='Value of the data (e.g., temperature, human presence detected or not)')

esparkcore/data/repositories/__init__.py

@@ -0,0 +1,4 @@
+from .base_repository import AsyncRepository
+from .device_repository import DeviceRepository
+from .outbox_repository import OutboxRepository
+from .telemetry_repository import TelemetryRepository

esparkcore/data/repositories/base_repository.py

@@ -0,0 +1,70 @@
+from typing import Generic, Optional, Sequence, Type, TypeVar
+
+from sqlalchemy import func, ColumnElement
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select, SQLModel
+
+T = TypeVar('T', bound=SQLModel)
+
+
+class AsyncRepository(Generic[T]):
+    def __init__(self, model: Type[T]):
+        self.model = model
+
+    async def count(self, session: AsyncSession, *conditions: ColumnElement) -> int:
+        # pylint: disable=not-callable
+        query = select(func.count()).select_from(self.model)
+
+        if conditions:
+            query = query.where(*conditions)
+
+        result = await session.execute(query)
+        return result.scalar_one()
+
+    async def add(self, session: AsyncSession, entity: T) -> T:
+        session.add(entity)
+
+        await session.commit()
+        await session.refresh(entity)
+
+        return entity
+
+    async def delete(self, session: AsyncSession, entity: T) -> None:
+        await session.delete(entity)
+        await session.commit()
+
+    async def get(self, session: AsyncSession, *conditions: ColumnElement) -> Optional[T]:
+        query = select(self.model)
+
+        if conditions:
+            query = query.where(*conditions)
+
+        return (await session.execute(query)).scalars().first()
+
+    async def list(self, session: AsyncSession, *conditions: ColumnElement[bool], offset: Optional[int] = None, order_by=None, limit: Optional[int] = None) -> Sequence[T]:
+        query = select(self.model)
+
+        if conditions:
+            query = query.where(*conditions)
+
+        if order_by is not None:
+            query = query.order_by(order_by)
+
+        if offset is not None:
+            query = query.offset(offset)
+
+        if limit is not None:
+            query = query.limit(limit)
+
+        return (await session.execute(query)).scalars().all()
+
+    async def update(self, session: AsyncSession, entity: T, **kwargs) -> T:
+        for key, value in kwargs.items():
+            setattr(entity, key, value)
+
+        session.add(entity)
+
+        await session.commit()
+        await session.refresh(entity)
+
+        return entity

esparkcore/data/repositories/device_repository.py

@@ -0,0 +1,26 @@
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Sequence
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..models import Device
+from .base_repository import AsyncRepository
+
+OFFLINE_THRESHOLD_MINUTES: int = 1440
+
+
+class DeviceRepository(AsyncRepository[Device]):
+    def __init__(self):
+        super().__init__(Device)
+
+    async def get_by_id(self, session: AsyncSession, id: str) -> Optional[Device]:
+        # pylint: disable=unexpected-keyword-arg
+        return await self.get(session, Device.id == id)
+
+    async def list_by_capability(self, session: AsyncSession, capability: str) -> Sequence[Device]:
+        # pylint: disable=no-member,unexpected-keyword-arg
+        return await self.list(session, Device.capabilities.contains(capability))
+
+    async def list_offline(self, session: AsyncSession, offline_threshold_minutes: int = OFFLINE_THRESHOLD_MINUTES) -> Sequence[Device]:
+        # pylint: disable=no-member
+        return await self.list(session, Device.last_seen < datetime.now(timezone.utc) - timedelta(minutes=offline_threshold_minutes), order_by=Device.last_seen.asc())

esparkcore/data/repositories/outbox_repository.py

@@ -0,0 +1,22 @@
+from typing import Optional
+
+from sqlmodel import and_
+
+from ..models import OutboxEvent
+from .base_repository import AsyncRepository
+
+
+class OutboxRepository(AsyncRepository[OutboxEvent]):
+    def __init__(self):
+        super().__init__(OutboxEvent)
+
+    async def get_next(self, session, device_id: str, event_type: str) -> Optional[OutboxEvent]:
+        # pylint: disable=no-member,singleton-comparison
+        events = await self.list(session, and_(OutboxEvent.device_id == device_id, OutboxEvent.event_type == event_type, OutboxEvent.is_processed == False), order_by=OutboxEvent.created_at.desc())
+        return events[0] if events else None
+
+    async def delete_pending(self, session, device_id: str, event_type: str) -> None:
+        # pylint: disable=singleton-comparison
+        events = await self.list(session, and_(OutboxEvent.device_id == device_id, OutboxEvent.event_type == event_type, OutboxEvent.is_processed == False))
+        for event in events:
+            await self.delete(session, event)

esparkcore/data/repositories/telemetry_repository.py

@@ -0,0 +1,25 @@
+from typing import Optional, Sequence
+
+from sqlalchemy import ColumnElement
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import and_
+
+from ..models import Telemetry
+from .base_repository import AsyncRepository
+
+
+class TelemetryRepository(AsyncRepository[Telemetry]):
+    def __init__(self):
+        super().__init__(Telemetry)
+
+    async def get_latest_for_device(self, session: AsyncSession, device_id: str, data_type: str) -> Optional[Telemetry]:
+        # pylint: disable=no-member
+        results = await self.list(session, and_(Telemetry.device_id == device_id, Telemetry.data_type == data_type), order_by=Telemetry.timestamp.desc(), limit=1)
+        return results[0] if results else None
+
+    async def list(self, session: AsyncSession, *conditions: ColumnElement[bool], offset: Optional[int] = None, order_by=None, limit: Optional[int] = None) -> Sequence[Telemetry]:
+        if order_by is None:
+            # pylint: disable=no-member
+            order_by = Telemetry.timestamp.desc()
+
+        return await super().list(session, *conditions, offset=offset, order_by=order_by, limit=limit)

esparkcore/routers/__init__.py

@@ -0,0 +1,2 @@
+from .device_router import DeviceRouter
+from .telemetry_router import TelemetryRouter

esparkcore/routers/base_router.py

@@ -0,0 +1,97 @@
+from typing import Generic, List, Sequence, Type, TypeVar
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Query, status, Response
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import SQLModel
+
+from ..data.repositories import AsyncRepository
+from ..data import async_session
+
+T = TypeVar('T', bound=SQLModel)
+
+
+class BaseRouter(Generic[T]):
+    def __init__(self, model: Type[T], repo: AsyncRepository[T], prefix: str, tags: List[str]):
+        self.model  = model
+        self.repo   = repo
+        self.router = APIRouter(prefix=prefix, tags=tags)
+
+        self._setup_routes()
+
+    @staticmethod
+    async def _get_session():
+        async with async_session() as session:
+            yield session
+
+    async def _before_add(self, entity: T, session: AsyncSession) -> None:
+        pass
+
+    # pylint: disable=unused-argument
+    async def _after_add(self, entity: T, session: AsyncSession) -> None:
+        await session.commit()
+
+    async def _before_delete(self, entity: T, session: AsyncSession) -> None:
+        pass
+
+    # pylint: disable=unused-argument
+    async def _after_delete(self, entity: T, session: AsyncSession) -> None:
+        await session.commit()
+
+    # pylint: disable=unused-argument
+    async def _before_update(self, entity: T, data: dict, session: AsyncSession) -> None:
+        pass
+
+    # pylint: disable=unused-argument
+    async def _after_update(self, entity: T, session: AsyncSession) -> None:
+        await session.commit()
+
+    def _setup_routes(self) -> None:
+        @self.router.post('/', response_model=self.model, status_code=status.HTTP_201_CREATED)
+        async def add(data: dict = Body(...), session: AsyncSession = Depends(BaseRouter._get_session)) -> T:
+            entity = self.model(**data)
+
+            await self._before_add(entity, session)
+            result = await self.repo.add(session, entity)
+            await self._after_add(result, session)
+
+            return result
+
+        @self.router.delete('/{id}', status_code=status.HTTP_204_NO_CONTENT)
+        async def delete(id: str, session: AsyncSession = Depends(BaseRouter._get_session)) -> None:
+            entity = await self.repo.get(session, self.model.id == id)
+            if not entity:
+                raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+
+            await self._before_delete(entity, session)
+            await self.repo.delete(session, entity)
+            await self._after_delete(entity, session)
+
+        @self.router.get('/{id}', response_model=self.model)
+        async def get(id: str, session: AsyncSession = Depends(BaseRouter._get_session)) -> T:
+            entity = await self.repo.get(session, self.model.id == id)
+            if not entity:
+                raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+
+            return entity
+
+        @self.router.get('/', response_model=List[self.model])
+        async def list(response: Response, session: AsyncSession = Depends(BaseRouter._get_session), offset: int = Query(None, ge=0), limit: int = Query(None, ge=1, le=100)) -> Sequence[T]:
+            response.headers['X-Total-Count'] = str(await self.repo.count(session))
+
+            return await self.repo.list(session, offset=offset, limit=limit)
+
+        @self.router.put('/{id}', response_model=self.model)
+        async def update(id: str, data: dict = Body(...), session: AsyncSession = Depends(BaseRouter._get_session)) -> T:
+            entity = await self.repo.get(session, self.model.id == id)
+            if not entity:
+                raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+
+            await self._before_update(entity, data, session)
+
+            for key, value in data.items():
+                setattr(entity, key, value)
+
+            result = await self.repo.update(session, entity)
+            await self._after_update(result, session)
+
+            return result

esparkcore/routers/device_router.py

@@ -0,0 +1,29 @@
+from json import dumps
+from os import getenv
+
+from aiomqtt import Client
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..constants import ENV_MQTT_HOST, ENV_MQTT_PORT, TOPIC_DEVICE
+from ..data.models import Device
+from ..data.repositories import DeviceRepository
+from ..utils import log_debug
+from .base_router import BaseRouter
+
+
+class DeviceRouter(BaseRouter):
+    def __init__(self, repo: DeviceRepository = None) -> None:
+        self.repo : DeviceRepository = repo or DeviceRepository()
+
+        super().__init__(Device, self.repo, '/api/v1/devices', ['device'])
+
+    async def _publish_update(self, entity: Device) -> None:
+        log_debug(f'Publishing parameters update for device {entity.id}: {entity.parameters}')
+
+        async with Client(getenv(ENV_MQTT_HOST, 'localhost'), int(getenv(ENV_MQTT_PORT, '1883'))) as client:
+            await client.publish(f'{TOPIC_DEVICE}/{entity.id}', payload=dumps(entity.parameters) if entity.parameters else None, qos=1, retain=True)
+
+    async def _after_update(self, entity: Device, session: AsyncSession) -> None:
+        await super()._after_update(entity, session)
+
+        await self._publish_update(entity)

esparkcore/routers/telemetry_router.py

@@ -0,0 +1,45 @@
+from datetime import datetime, timedelta, timezone
+from typing import cast, Sequence
+
+from fastapi import Depends, Query, Response
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..data.models import Telemetry
+from ..data.repositories import DeviceRepository, TelemetryRepository
+from .base_router import BaseRouter
+
+
+class TelemetryRouter(BaseRouter):
+    def __init__(self, repo: TelemetryRepository = None) -> None:
+        self.repo : TelemetryRepository = repo or TelemetryRepository()
+
+        super().__init__(Telemetry, self.repo, '/api/v1/telemetry', ['telemetry'])
+
+    def _setup_routes(self) -> None:
+        @self.router.get('/recent', response_model=Sequence[Telemetry])
+        async def list_recent(response: Response, session: AsyncSession = Depends(BaseRouter._get_session), offset: int = Query(..., min=0)) -> Sequence[Telemetry]:
+            from_date   = datetime.now(timezone.utc) - timedelta(seconds=offset)
+            device_repo = DeviceRepository()
+            # pylint: disable=no-member
+            devices     = await device_repo.list(session)
+            results     = []
+
+            for device in devices:
+                capabilities = device.capabilities.split(',') if device.capabilities else []
+                for data_type in capabilities:
+                    if not data_type.startswith('action_'):
+                        telemetry = await cast(TelemetryRepository, self.repo).get_latest_for_device(session, device.id, data_type)
+                        if telemetry:
+                            if telemetry.timestamp.tzinfo is None:
+                                telemetry.timestamp = telemetry.timestamp.replace(tzinfo=timezone.utc)
+
+                            if telemetry.timestamp >= from_date:
+                                results.append(telemetry)
+
+            response.headers['X-Total-Count'] = str(len(results))
+
+            results.sort(key=lambda result: result.timestamp, reverse=True)
+
+            return results
+
+        super()._setup_routes()

esparkcore/schedules/__init__.py

@@ -0,0 +1,2 @@
+from .outbox import consume_outbox
+from .scheduler import start_scheduler

esparkcore/schedules/outbox.py

@@ -0,0 +1,24 @@
+from json import dumps
+from os import getenv
+
+from aiomqtt import Client
+
+from ..constants import ENV_MQTT_HOST, ENV_MQTT_PORT, TOPIC_ACTION
+from ..data import async_session
+from ..data.repositories import OutboxRepository
+
+
+async def consume_outbox(device_id: str, event_type: str) -> None:
+    outbox_repo = OutboxRepository()
+
+    async with async_session() as session:
+        event = await outbox_repo.get_next(session, device_id, event_type)
+        if not event:
+            return
+
+        await outbox_repo.delete_pending(session, device_id, event_type)
+
+        async with Client(getenv(ENV_MQTT_HOST, 'localhost'), int(getenv(ENV_MQTT_PORT, '1883'))) as client:
+            await client.publish(f'{TOPIC_ACTION}/{device_id}', dumps(event.payload), qos=1, retain=True)
+
+        await session.commit()

esparkcore/schedules/scheduler.py

@@ -0,0 +1,8 @@
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+
+async def start_scheduler():
+    scheduler = AsyncIOScheduler()
+    scheduler.start()
+
+    return scheduler

esparkcore/services/__init__.py

@@ -0,0 +1 @@
+from .mqtt import MQTTManager

esparkcore/services/mqtt.py

@@ -0,0 +1,116 @@
+from asyncio import create_task, gather, Queue, sleep
+from datetime import datetime, timezone
+from json import JSONDecodeError, loads
+from os import getenv
+from uuid import getnode
+
+from aiomqtt import Client, MqttError
+
+from ..constants import ENV_MQTT_HOST, ENV_MQTT_PORT, TOPIC_CRASH, TOPIC_REGISTRATION, TOPIC_TELEMETRY
+from ..data import async_session
+from ..data.models import Device, Telemetry
+from ..data.repositories import DeviceRepository, TelemetryRepository
+from ..utils import log_debug, log_error
+
+MQTT_RETRY_DELAY: int = 5
+
+
+class MQTTManager:
+    def __init__(self, device_repo: DeviceRepository = None, telemetry_repo: TelemetryRepository = None):
+        self.mqtt_host      : str                 = getenv(ENV_MQTT_HOST, 'localhost')
+        self.mqtt_port      : int                 = int(getenv(ENV_MQTT_PORT, '1883'))
+        self.device_repo    : DeviceRepository    = device_repo
+        self.telemetry_repo : TelemetryRepository = telemetry_repo
+        self.queue          : Queue               = Queue()
+
+    async def _handle_registration(self, device_id: str, payload: dict) -> None:
+        try:
+            log_debug(f'Registering device: {device_id}')
+
+            async with async_session() as session:
+                device = await self.device_repo.get(session, Device.id == device_id)
+                if device:
+                    device.capabilities = payload['capabilities']
+                    device.last_seen    = datetime.now(timezone.utc)
+
+                    await self.device_repo.update(session, device, last_seen=datetime.now(timezone.utc))
+                else:
+                    device = Device()
+
+                    device.id           = device_id
+                    device.display_name = None
+                    device.capabilities = payload['capabilities']
+                    device.last_seen    = datetime.now(timezone.utc)
+
+                    await self.device_repo.add(session, device)
+        # pylint: disable=broad-exception-caught
+        except Exception as e:
+            log_error(e)
+
+    async def _handle_telemetry(self, device_id: str, payload: dict) -> None:
+        try:
+            log_debug(f'Receiving telemetry from device: {device_id} - Payload: {payload}')
+
+            async with async_session() as session:
+                telemetry = Telemetry()
+
+                telemetry.device_id = device_id
+                telemetry.timestamp = datetime.now(timezone.utc)
+                telemetry.data_type = payload.get('data_type')
+                telemetry.value     = payload.get('value')
+
+                await self.telemetry_repo.add(session, telemetry)
+        # pylint: disable=broad-exception-caught
+        except Exception as e:
+            log_error(e)
+
+    async def _process_queue(self) -> None:
+        while True:
+            topic, payload = await self.queue.get()
+
+            topic_parts: list[str] = str(topic).split('/')
+            if len(topic_parts) != 3:
+                log_error(Exception('Invalid topic format, skipping message'))
+                continue
+
+            app_type, message_type, device_id = topic_parts
+            if app_type != 'espark':
+                log_debug('Invalid app type, skipping message')
+                continue
+
+            try:
+                payload = loads(payload.decode())
+            except JSONDecodeError as e:
+                log_error(e)
+                continue
+
+            if message_type == TOPIC_REGISTRATION.split('/')[1]:
+                await self._handle_registration(device_id, payload)
+            elif message_type == TOPIC_TELEMETRY.split('/')[1]:
+                await self._handle_telemetry(device_id, payload)
+            elif message_type == TOPIC_CRASH.split('/')[1]:
+                log_debug(f'Received crash report from device {device_id}: {payload}')
+            else:
+                log_debug(f'Unknown message type "{message_type}", skipping message')
+
+            self.queue.task_done()
+
+    async def _process_messages(self) -> None:
+        while True:
+            try:
+                async with Client(self.mqtt_host, self.mqtt_port, identifier=f'espark-core-{hex(getnode())}') as client:
+                    await client.subscribe(f'{TOPIC_REGISTRATION}/+')
+                    await client.subscribe(f'{TOPIC_TELEMETRY}/+')
+                    await client.subscribe(f'{TOPIC_CRASH}/+')
+
+                    async for message in client.messages:
+                        log_debug(f'Received MQTT message on topic {message.topic}')
+
+                        self.queue.put_nowait((message.topic, message.payload))
+            except MqttError as e:
+                log_error(e)
+
+                await sleep(MQTT_RETRY_DELAY)
+
+    async def start(self) -> None:
+        await gather(create_task(self._process_queue()), create_task(self._process_messages()))

esparkcore/utils/__init__.py

@@ -0,0 +1 @@
+from .logging import log_debug, log_error

esparkcore/utils/logging.py

@@ -0,0 +1,11 @@
+from datetime import datetime
+
+
+def log_debug(message: str) -> None:
+    print(f'{datetime.now().isoformat()} [DEBUG] {message}')
+
+
+def log_error(e: Exception) -> None:
+    print(f'{datetime.now().isoformat()} [ERROR] {type(e).__name__}: {e}')
+
+    raise e