espark-core 0.3.0__tar.gz

espark_core-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alan Tai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

espark_core-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include requirements.txt
+include requirements.dev.txt
+include ../README.md
+include LICENSE

espark_core-0.3.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: espark-core
+Version: 0.3.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
+License-File: LICENSE
+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: license-file
+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.3.0/README.md

@@ -0,0 +1,102 @@
+# 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.3.0/espark_core.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: espark-core
+Version: 0.3.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
+License-File: LICENSE
+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: license-file
+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.3.0/espark_core.egg-info/SOURCES.txt

@@ -0,0 +1,61 @@
+LICENSE
+MANIFEST.in
+README.md
+requirements.dev.txt
+requirements.txt
+setup.cfg
+setup.py
+../README.md
+./esparkcore/__init__.py
+./esparkcore/constants.py
+./esparkcore/data/__init__.py
+./esparkcore/data/database.py
+./esparkcore/data/models/__init__.py
+./esparkcore/data/models/device.py
+./esparkcore/data/models/outbox.py
+./esparkcore/data/models/telemetry.py
+./esparkcore/data/repositories/__init__.py
+./esparkcore/data/repositories/base_repository.py
+./esparkcore/data/repositories/device_repository.py
+./esparkcore/data/repositories/outbox_repository.py
+./esparkcore/data/repositories/telemetry_repository.py
+./esparkcore/routers/__init__.py
+./esparkcore/routers/base_router.py
+./esparkcore/routers/device_router.py
+./esparkcore/routers/telemetry_router.py
+./esparkcore/schedules/__init__.py
+./esparkcore/schedules/outbox.py
+./esparkcore/schedules/scheduler.py
+./esparkcore/services/__init__.py
+./esparkcore/services/mqtt.py
+./esparkcore/utils/__init__.py
+./esparkcore/utils/logging.py
+espark_core.egg-info/PKG-INFO
+espark_core.egg-info/SOURCES.txt
+espark_core.egg-info/dependency_links.txt
+espark_core.egg-info/requires.txt
+espark_core.egg-info/top_level.txt
+esparkcore/__init__.py
+esparkcore/constants.py
+esparkcore/data/__init__.py
+esparkcore/data/database.py
+esparkcore/data/models/__init__.py
+esparkcore/data/models/device.py
+esparkcore/data/models/outbox.py
+esparkcore/data/models/telemetry.py
+esparkcore/data/repositories/__init__.py
+esparkcore/data/repositories/base_repository.py
+esparkcore/data/repositories/device_repository.py
+esparkcore/data/repositories/outbox_repository.py
+esparkcore/data/repositories/telemetry_repository.py
+esparkcore/routers/__init__.py
+esparkcore/routers/base_router.py
+esparkcore/routers/device_router.py
+esparkcore/routers/telemetry_router.py
+esparkcore/schedules/__init__.py
+esparkcore/schedules/outbox.py
+esparkcore/schedules/scheduler.py
+esparkcore/services/__init__.py
+esparkcore/services/mqtt.py
+esparkcore/utils/__init__.py
+esparkcore/utils/logging.py

espark_core-0.3.0/espark_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

espark_core-0.3.0/espark_core.egg-info/requires.txt

@@ -0,0 +1,19 @@
+aiomqtt==2.4.0
+apscheduler==3.11.1
+fastapi==0.124.0
+sqlalchemy==2.0.45
+sqlmodel==0.0.27
+uvicorn[standard]==0.38.0
+
+[dev]
+aiosqlite==0.21.0
+autopep8==2.3.2
+build==1.3.0
+fastapi-cli[standard-no-fastapi-cloud-cli]==0.0.16
+httpx==0.28.1
+pycodestyle==2.14.0
+pylint==4.0.4
+pytest==9.0.2
+pytest-asyncio==1.3.0
+pytest-cov==7.0.0
+twine==6.2.0

espark_core-0.3.0/espark_core.egg-info/top_level.txt

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

espark_core-0.3.0/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'

espark_core-0.3.0/esparkcore/data/__init__.py

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

espark_core-0.3.0/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)

espark_core-0.3.0/esparkcore/data/models/__init__.py

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

espark_core-0.3.0/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')

espark_core-0.3.0/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')

espark_core-0.3.0/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)')

espark_core-0.3.0/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

espark_core-0.3.0/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

espark_core-0.3.0/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())

espark_core-0.3.0/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)

espark_core-0.3.0/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)

espark_core-0.3.0/esparkcore/routers/__init__.py

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

espark_core-0.3.0/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

espark_core-0.3.0/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)

espark_core-0.3.0/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()

espark_core-0.3.0/esparkcore/schedules/__init__.py

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

espark_core-0.3.0/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()

espark_core-0.3.0/esparkcore/schedules/scheduler.py

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

espark_core-0.3.0/esparkcore/services/__init__.py

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

espark_core-0.3.0/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()))

espark_core-0.3.0/esparkcore/utils/__init__.py

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

espark_core-0.3.0/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

espark_core-0.3.0/requirements.dev.txt

@@ -0,0 +1,11 @@
+aiosqlite==0.21.0
+autopep8==2.3.2
+build==1.3.0
+fastapi-cli[standard-no-fastapi-cloud-cli]==0.0.16
+httpx==0.28.1
+pycodestyle==2.14.0
+pylint==4.0.4
+pytest==9.0.2
+pytest-asyncio==1.3.0
+pytest-cov==7.0.0
+twine==6.2.0

espark_core-0.3.0/requirements.txt

@@ -0,0 +1,6 @@
+aiomqtt==2.4.0
+apscheduler==3.11.1
+fastapi==0.124.0
+sqlalchemy==2.0.45
+sqlmodel==0.0.27
+uvicorn[standard]==0.38.0

espark_core-0.3.0/setup.cfg

@@ -0,0 +1,7 @@
+[pycodestyle]
+ignore = E501,E203,E221,E712
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

espark_core-0.3.0/setup.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+from setuptools import find_packages, setup
+
+def read_requirements(filename: str):
+    return [line.strip() for line in Path(filename).read_text().splitlines() if line.strip() and not line.startswith("#")]
+
+root                    = Path(__file__).resolve().parent
+production_requirements = (root / 'requirements.txt').read_text().splitlines()
+extra_requirements      = (root / 'requirements.dev.txt').read_text().splitlines()
+
+setup(
+    name='espark-core',
+    version='0.3.0',
+    description='The core module of the Espark ESP32-based IoT device management framework.',
+    long_description=(root / 'README.md').read_text(),
+    long_description_content_type='text/markdown',
+    license='MIT',
+    license_files=[
+        'LICENSE',
+    ],
+    python_requires='>=3.8',
+    packages=find_packages(where='.'),
+    package_dir={
+        '' : '.',
+    },
+    install_requires=production_requirements,
+    extras_require={
+        'dev' :  extra_requirements,
+    },
+)