{"id":25553953,"url":"https://github.com/serdaraltin/iothena","last_synced_at":"2026-02-18T23:30:18.539Z","repository":{"id":276829043,"uuid":"930440077","full_name":"serdaraltin/iothena","owner":"serdaraltin","description":"iothena is a modular IoT framework that simplifies the development of scalable and flexible IoT applications. It provides essential components for device management, sensor integration, and real-time notifications, making it the perfect foundation for your IoT projects.","archived":false,"fork":false,"pushed_at":"2025-02-10T16:59:05.000Z","size":130,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-02-10T17:40:25.695Z","etag":null,"topics":["embedded","embedded-systems","internet-of-things","iot","iot-device","microcontrollers"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serdaraltin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-10T16:31:18.000Z","updated_at":"2025-02-10T16:58:48.000Z","dependencies_parsed_at":"2025-02-10T17:42:35.634Z","dependency_job_id":"3a418d5a-c325-4b8d-9e31-01fa33e6457e","html_url":"https://github.com/serdaraltin/iothena","commit_stats":null,"previous_names":["serdaraltin/iothena"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serdaraltin%2Fiothena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serdaraltin%2Fiothena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serdaraltin%2Fiothena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serdaraltin%2Fiothena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serdaraltin","download_url":"https://codeload.github.com/serdaraltin/iothena/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239833544,"owners_count":19704629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","embedded-systems","internet-of-things","iot","iot-device","microcontrollers"],"created_at":"2025-02-20T12:03:51.863Z","updated_at":"2026-02-18T23:30:18.387Z","avatar_url":"https://github.com/serdaraltin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **iothena - IoT Framework Documentation**\n\n## Overview\n\n**iothena** is a comprehensive Internet of Things (IoT) framework designed to provide a foundation for creating a wide variety of IoT applications. Whether you are building smart homes, industrial IoT systems, or environmental monitoring solutions, **iothena** offers a flexible, scalable, and modular platform to get your project off the ground quickly.\n\nIt includes components for device management, sensor data collection, event-driven actions, machine learning integration, real-time notifications, and more, making it suitable for both small and large IoT solutions. **iothena** aims to be the go-to framework for any IoT-based application, giving you the ability to customize and extend as needed.\n\n---\n\n## Table of Contents\n\n1. [Project Structure](#project-structure)\n2. [Core Features](#core-features)\n3. [System Requirements](#system-requirements)\n4. [Installation Guide](#installation-guide)\n5. [Configuration Files](#configuration-files)\n6. [API Documentation](#api-documentation)\n7. [Sensor Integration](#sensor-integration)\n8. [Event Handling and Alerts](#event-handling-and-alerts)\n9. [Machine Learning Integration](#machine-learning-integration)\n10. [Testing](#testing)\n11. [Contributing](#contributing)\n12. [License](#license)\n13. [Contact Information](#contact-information)\n\n---\n\n## Project Structure\n\nThe structure of **iothena** follows a modular design to allow flexibility. Here’s an overview:\n\n```\n├── app                     # Core application logic\n│   ├── api                 # REST API for device interaction, sensor data retrieval, etc.\n│   ├── controller          # Controller for handling device and event logic\n│   ├── events              # Event handling and triggers (e.g., alerts, device updates)\n│   ├── helpers             # Helper functions for various utilities (e.g., time handling, data conversion)\n│   ├── http                # HTTP handling for requests, middleware, and external integrations\n│   ├── models              # Data models representing devices, sensors, notifications, etc.\n│   ├── modules             # External modules (e.g., machine learning, image recognition)\n│   ├── notifications       # Real-time notification system (e.g., Telegram alerts)\n│   ├── services            # Core business logic (e.g., network, notification, sensor management)\n│   ├── utils               # Utility functions (e.g., system, firmware management, network handling)\n│   └── view                # Frontend components for UI interactions with the system\n├── config                  # Configuration files (network, devices, alerts, etc.)\n├── database                # Database connector and schema\n├── docker                  # Docker configuration for containerized deployment\n├── docs                    # Documentation files and requirements\n├── logs                    # Log files for system diagnostics\n├── main.py                 # Main entry point for the framework\n├── public                  # Public resources (e.g., images, static files)\n├── routes                  # API routing logic\n├── script                  # Setup and installation scripts\n├── storage                 # Persistent storage (e.g., database, device settings)\n└── tests                   # Unit and integration tests\n```\n\n### Key Directories and Files\n\n- **app/api**: The REST API for interaction with devices, sensors, and event management.\n- **app/controllers**: Manages the flow of data between models and services.\n- **app/events**: Event-driven logic for actions like sending notifications or triggering device actions.\n- **app/models**: Data models like devices, sensors, events, and notifications.\n- **app/services**: Core services managing business logic, such as networking and device control.\n- **config**: YAML configuration files for devices, sensors, alerts, and more.\n- **database**: Manages the database connection and schema for storing system data.\n- **logs**: Logs for monitoring system activity and debugging.\n- **routes**: API routes to handle various HTTP requests.\n- **tests**: Unit and integration tests to ensure stability.\n\n---\n\n## Core Features\n\n### 1. **Modular Architecture**\n\n**iothena** is designed to be modular, allowing developers to pick and choose components to suit their specific use case. Some core modules include:\n\n- **Sensor Integration**: Seamless support for sensors like temperature, humidity, and motion.\n- **Device Management**: Easily add and configure IoT devices.\n- **Real-Time Notifications**: Instant alerts via services like Telegram.\n- **Machine Learning**: Integration with AI models for tasks like object detection and data analysis.\n\n### 2. **Event-Driven System**\n\nThe framework supports defining custom events that trigger actions in response to changes in sensor data, device statuses, or other conditions. For example, if a sensor value exceeds a threshold, an event can trigger an action such as activating an actuator or sending an alert.\n\n### 3. **AI and Machine Learning Integration**\n\n**iothena** integrates machine learning models like YOLO for object detection and offers tools for analyzing sensor data and making intelligent decisions.\n\n### 4. **Cross-Platform Compatibility**\n\nThe framework is compatible with popular IoT devices such as Raspberry Pi, Arduino, and ESP32, making it easy to deploy on various hardware platforms.\n\n---\n\n## System Requirements\n\nTo get started with **iothena**, ensure you meet the following prerequisites:\n\n- **Python 3.12+**\n- **Docker** (recommended for containerized deployment)\n- **Database**: PostgreSQL, MySQL, or SQLite\n- **External Libraries**:\n    - `Flask` (for API handling)\n    - `TensorFlow` (for machine learning models)\n    - `OpenCV` (for image processing)\n    - `requests` (for HTTP requests)\n\n---\n\n## Installation Guide\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/yourusername/iothena.git\ncd iothena\n```\n\n### 2. Install Dependencies\n\nInstall the necessary dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n### 3. Configure Environment\n\nCopy the environment configuration file:\n\n```bash\ncp .env.example .env\n```\n\nThen, edit the `.env` file with the correct settings for your environment, such as database credentials and API keys.\n\n### 4. Run the Application\n\nYou can run **iothena** locally:\n\n```bash\npython main.py\n```\n\nAlternatively, use Docker for containerized deployment:\n\n```bash\ndocker-compose up --build\n```\n\n### 5. Test the Framework\n\nRun the tests to ensure everything is working:\n\n```bash\npytest\n```\n\n---\n\n## API Documentation\n\nThe **iothena** API allows you to interact with devices, sensors, and more.\n\n### Base URL\n\nThe API base URL is `http://localhost:5000/api/v1/`.\n\n### Example Endpoints\n\n- **GET /api/v1/devices**  \n  Retrieves a list of registered devices and their statuses.\n\n- **POST /api/v1/devices**  \n  Adds a new device to the network.\n\n- **GET /api/v1/sensors/{sensor_id}**  \n  Fetches the latest data from a specific sensor.\n\n- **POST /api/v1/alerts**  \n  Manually triggers an alert based on a predefined condition.\n\n---\n\n## Sensor Integration\n\nIntegrating sensors into **iothena** is simple. Supported sensors include:\n\n- **Temperature and Humidity Sensors**\n- **Motion Sensors**\n- **Voltage Sensors**\n\nYou can extend the framework to support additional sensors by creating new sensor modules in the `app/models/sensors/` directory.\n\n---\n\n## Event Handling and Alerts\n\nCustom events can be created to trigger actions based on sensor data, device status, or other conditions.\n\nFor example, an event could be created to send a notification when a sensor value exceeds a threshold:\n\n```python\ndef temperature_threshold_event(sensor_data):\n    if sensor_data[\"temperature\"] \u003e 30:\n        send_alert(\"Temperature exceeded threshold!\")\n```\n\n---\n\n## Machine Learning Integration\n\n**iothena** supports AI models such as YOLO for object detection. Here's how to use YOLO for object detection with a camera feed:\n\n```python\nfrom app/modules/yolo import YOLOService\n\nyolo_service = YOLOService()\ndetections = yolo_service.detect_objects(camera_feed)\n```\n\n---\n\n## Testing\n\n**iothena** includes unit and integration tests. You can run the tests using `pytest`:\n\n```bash\npytest tests\n```\n\nYou can also write your own tests in the `tests/` directory.\n\n---\n\n## Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork the repository.\n2. Create a new branch for your feature or fix.\n3. Write tests for the new functionality.\n4. Submit a pull request.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n---\n\n## Contact Information\n\nFor further assistance or inquiries, please contact us via email at [seyupaltin@gmail.com](seyupaltin@gmail.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserdaraltin%2Fiothena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserdaraltin%2Fiothena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserdaraltin%2Fiothena/lists"}