{"id":29246648,"url":"https://github.com/marincervinschi/hvac-system","last_synced_at":"2026-02-03T18:31:35.357Z","repository":{"id":302315520,"uuid":"1012006839","full_name":"MarinCervinschi/HVAC-System","owner":"MarinCervinschi","description":"A distributed system for the control and monitoring of HVAC plants based on IoT and microservices architecture. The system integrates smart objects, CoAP gateways, MQTT broker, web dashboard, and telemetry system for intelligent management.","archived":false,"fork":false,"pushed_at":"2025-07-09T15:02:42.000Z","size":367,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-09T15:48:40.642Z","etag":null,"topics":["coap","dasbo","docker","flask","flask-restful","gateway","grafana","hvac","infuxdb","iot","mqtt","nextjs","python","smart-object"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarinCervinschi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-07-01T16:59:17.000Z","updated_at":"2025-07-09T15:02:45.000Z","dependencies_parsed_at":"2025-07-01T18:36:05.501Z","dependency_job_id":null,"html_url":"https://github.com/MarinCervinschi/HVAC-System","commit_stats":null,"previous_names":["marincervinschi/hvac-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MarinCervinschi/HVAC-System","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FHVAC-System","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FHVAC-System/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FHVAC-System/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FHVAC-System/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarinCervinschi","download_url":"https://codeload.github.com/MarinCervinschi/HVAC-System/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarinCervinschi%2FHVAC-System/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29052630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T15:43:47.601Z","status":"ssl_error","status_checked_at":"2026-02-03T15:43:46.709Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["coap","dasbo","docker","flask","flask-restful","gateway","grafana","hvac","infuxdb","iot","mqtt","nextjs","python","smart-object"],"created_at":"2025-07-03T23:05:39.329Z","updated_at":"2026-02-03T18:31:35.351Z","avatar_url":"https://github.com/MarinCervinschi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HVAC System - Intelligent HVAC Control and Monitoring System\n\n\u003c!-- Badges --\u003e\n\u003cdiv align=\"center\"\u003e\n\n![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)\n![Next.js](https://img.shields.io/badge/Next.js-15-000000?style=for-the-badge\u0026logo=next.js\u0026logoColor=white)\n![React](https://img.shields.io/badge/React-19-61DAFB?style=for-the-badge\u0026logo=react\u0026logoColor=black)\n![Flask](https://img.shields.io/badge/Flask-000000?style=for-the-badge\u0026logo=flask\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n\n![MQTT](https://img.shields.io/badge/MQTT-660066?style=for-the-badge\u0026logo=mqtt\u0026logoColor=white)\n![CoAP](https://img.shields.io/badge/CoAP-RFC7252-FF6B6B?style=for-the-badge)\n![InfluxDB](https://img.shields.io/badge/InfluxDB-22ADF6?style=for-the-badge\u0026logo=influxdb\u0026logoColor=white)\n![Grafana](https://img.shields.io/badge/Grafana-F46800?style=for-the-badge\u0026logo=grafana\u0026logoColor=white)\n![TailwindCSS](https://img.shields.io/badge/Tailwind_CSS-38B2AC?style=for-the-badge\u0026logo=tailwind-css\u0026logoColor=white)\n[![GitHub license](https://img.shields.io/github/license/MarinCervinschi/HVAC-System?style=for-the-badge)](LICENSE)\n\n![GitHub views](https://komarev.com/ghpvc/?username=MarinCervinschi\u0026repo=HVAC-System\u0026style=for-the-badge)\n![GitHub repo size](https://img.shields.io/github/repo-size/MarinCervinschi/HVAC-System?style=for-the-badge)\n![GitHub last commit](https://img.shields.io/github/last-commit/MarinCervinschi/HVAC-System?style=for-the-badge)\n![GitHub issues](https://img.shields.io/github/issues/MarinCervinschi/HVAC-System?style=for-the-badge)\n![GitHub stars](https://img.shields.io/github/stars/MarinCervinschi/HVAC-System?style=for-the-badge)\n\n\u003c/div\u003e\n\n---\n\nA distributed system for the control and monitoring of HVAC (Heating, Ventilation, Air Conditioning) plants based on IoT and microservices architecture. The system integrates smart objects, CoAP gateways, MQTT broker, web dashboard, and telemetry system for intelligent management of rooms and cooling racks.\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Main Components](#main-components)\n- [Smart Objects](#smart-objects)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [API Endpoints](#api-endpoints)\n- [Dashboard](#dashboard)\n- [Monitoring](#monitoring)\n- [Development](#development)\n- [Contributing](#contributing)\n\n## 🔍 Overview\n\nThe HVAC system manages the automatic control of temperature, humidity, air pressure, and energy consumption through:\n\n- **IoT Smart Objects**: Virtual devices simulating sensors and actuators\n- **CoAP Gateway**: Proxy for device communication\n- **Policy System**: Automation based on configurable rules\n- **Web Dashboard**: Modern user interface for control and monitoring\n- **Telemetry**: Data collection and storage with InfluxDB and visualization with Grafana\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Dashboard     │    │   Data Collector│    │  Cloud Simulator│\n│   (Next.js)     │    │   (Flask API)   │    │   (Flask API)   │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n         │                       │                       │\n         └───────────────────────┼───────────────────────┘\n                                 │\n         ┌─────────────────┐     │     ┌─────────────────┐\n         │  Gateway CoAP   │─────┼─────│  MQTT Broker    │\n         │                 │     │     │                 │\n         └─────────────────┘     │     └─────────────────┘\n                                 │\n         ┌─────────────────┐     │     ┌─────────────────┐\n         │  Smart Objects  │─────┼─────│  Monitoring     │\n         │  (IoT Devices)  │     │     │  (Grafana)      │\n         └─────────────────┘     │     └─────────────────┘\n                                 │\n                         ┌─────────────────┐\n                         │  InfluxDB       │\n                         │  (Time Series)  │\n                         └─────────────────┘\n```\n\n## 🧩 Main Components\n\n### 1. Gateway (`/gateway`)\n\n- **Function**: CoAP proxy for discovery and communication with smart objects\n- **Technologies**: aiocoap, asyncio\n- **Port**: 5683 (CoAP standard)\n\n### 2. Data Collector (`/data_collector`)\n\n- **Function**: REST API for managing rooms, racks, and devices\n- **Technologies**: Flask, Flask-RESTful, Flask-CORS\n- **Port**: 5000\n- **Endpoints**: `/hvac/api/rooms`, `/hvac/api/room/{id}`, `/hvac/api/rack/{id}`\n\n### 3. Cloud Simulator (`/cloud_simulator`)\n\n- **Function**: Cloud simulation for telemetry collection\n- **Technologies**: Flask, InfluxDB Client\n- **Port**: 5002\n- **Storage**: InfluxDB + JSONL files\n\n### 4. Dashboard (`/dashboard`)\n\n- **Function**: Responsive web interface for control and monitoring\n- **Technologies**: Next.js 15, React 19, TypeScript, Tailwind CSS\n- **Port**: 3000\n- **Features**: Real-time MQTT, charts, actuator control\n\n### 5. Smart Objects (`/smart_objects`)\n\n- **Function**: IoT device simulation with sensors and actuators\n- **Technologies**: Python, paho-mqtt, aiocoap\n- **Protocols**: MQTT (telemetry), CoAP (control)\n\n## 🤖 Smart Objects\n\n### Available Devices\n\n#### 1. **RackCoolingUnit** 🌡️\n\n- **Sensors**: Temperature Sensor\n- **Actuators**: Fan Actuator\n- **Purpose**: Server rack cooling control\n\n#### 2. **WaterLoopController** 💧\n\n- **Sensors**: Pressure Sensor\n- **Actuators**: Pump Actuator\n- **Purpose**: Water cooling circuit management\n\n#### 3. **AirflowManager** 💨\n\n- **Sensors**: Airspeed Sensor\n- **Actuators**: Cooling Level Actuator\n- **Purpose**: Airflow and cooling level control\n\n#### 4. **EnvironmentMonitor** 🌍\n\n- **Sensors**: Temperature Sensor, Humidity Sensor\n- **Purpose**: Room environmental monitoring\n\n#### 5. **EnergyMeteringUnit** ⚡\n\n- **Sensors**: Energy Sensor\n- **Purpose**: Energy consumption monitoring\n\n#### 6. **CoolingSystemHub** ❄️\n\n- **Actuators**: Cooling Level Actuator\n- **Purpose**: Central hub for cooling control\n\n### Sensor Types\n\n- **Temperature**: 0-60°C, accuracy 0.01°C\n- **Humidity**: 0-70%, accuracy 0.01%\n- **Pressure**: 950-1050 hPa, accuracy 0.01 hPa\n- **Airspeed**: 0.1-15 m/s, accuracy 0.01 m/s\n- **Energy**: 0-1000 kWh, accuracy 0.001 kWh\n\n### Actuator Types\n\n- **Fan**: ON/OFF + speed (0-100%)\n- **Pump**: ON/OFF\n- **Cooling Level**: Levels 0-5\n\n## 📋 Requirements\n\n### Software\n\n- **Python**: 3.11+\n- **Node.js**: 18+\n- **Docker**: 20.0+\n- **Docker Compose**: 2.0+\n\n### Recommended Hardware\n\n- **RAM**: 4GB+\n- **Storage**: 2GB+ free\n- **CPU**: 2+ cores\n\n## 🚀 Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone \u003crepository-url\u003e\ncd HVAC-System\n```\n\n### 2. Setup Python Environment\n\n```bash\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # Linux/Mac\n# venv\\Scripts\\activate   # Windows\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### 3. Setup Dashboard (Next.js)\n\n```bash\ncd dashboard\nnpm install\nnpm run build\ncd ..\n```\n\n### 4. Start Docker Services\n\n```bash\n# Start InfluxDB, Grafana, and Cloud API\ndocker compose up -d\n\n# Or rebuild everything\nchmod +x rebuild.sh\n./rebuild.sh\n```\n\n## ⚙️ Configuration\n\n### 1. MQTT Configuration (`/config/mqtt_conf_params.py`)\n\n```python\nBROKER_ADDRESS = \"127.0.0.1\"\nBROKER_PORT = 1883\nBASE_TOPIC = \"hvac/system\"\n```\n\n### 2. CoAP Configuration (`/config/coap_conf_params.py`)\n\n```python\nCOAP_SERVER_ADDRESS = \"127.0.0.1\"\nCOAP_GATEWAY_PORT = 5683\nGATEWAY_URI = \"coap://127.0.0.1:5683\"\n```\n\n### 3. Rooms Configuration (`/data_collector/conf/rooms_config.json`)\n\n```json\n{\n  \"rooms\": [\n    {\n      \"room_id\": \"room_A1\",\n      \"location\": \"Building A, Floor 1\",\n      \"racks\": [\n        {\n          \"rack_id\": \"rack_A1\",\n          \"type\": \"air_cooled\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### 4. Automation Policies (`/data_collector/conf/policy.json`)\n\nDefines automatic rules for control based on sensor values.\n\n## 🏃‍♂️ Usage\n\n### 1. Start Components\n\n#### CoAP Gateway\n\n```bash\npython gateway.py\n```\n\n#### Data Collector API\n\n```bash\npython run_app.py\n```\n\n#### Web Dashboard\n\n```bash\ncd dashboard\nnpm run dev\n```\n\n#### Smart Objects (Example)\n\n```bash\npython tests_scripts/process.py\n```\n\n### 2. System Testing\n\n#### CoAP Connectivity Test\n\n```bash\npython tests_scripts/coap_test.py\n```\n\n#### Event Monitoring\n\n```bash\npython tests_scripts/monitor_control_events.py\n```\n\n### 3. Access Interfaces\n\n- **Dashboard**: http://localhost:3000\n- **API**: http://localhost:5000/hvac/api\n- **Grafana**: http://localhost:3000/grafana (admin/admin)\n- **Cloud API**: http://localhost:5002/api\n\n## 📡 API Endpoints\n\n### Rooms API\n\n```\nGET    /hvac/api/rooms              # List rooms\nGET    /hvac/api/room/{room_id}     # Room details\n```\n\n### Racks API\n\n```\nGET    /hvac/api/rack/{rack_id}     # Rack details\n```\n\n### Device Control API\n\n```\nPOST   /hvac/api/device/control     # Device control\n```\n\n### Policy API\n\n```\nPOST   /hvac/api/policy/update      # Update policies\nGET    /hvac/api/policy/room/{id}   # Room policies\nGET    /hvac/api/policy/rack/{id}   # Rack policies\n```\n\n### Cloud API\n\n```\nPOST   /api/telemetry/{room_id}     # Send telemetry\nGET    /api/telemetry/{room_id}     # Retrieve telemetry\n```\n\n## 📊 Dashboard\n\n### Main Features\n\n- **Room View**: Overview and controls per room\n- **Rack View**: Rack details with smart objects\n- **Real-time Charts**: Sensor data visualization\n- **Actuator Control**: Toggles and controls for actuators\n- **Policy Management**: Create and edit automation rules\n- **Responsive Design**: Optimized for desktop and mobile\n\n### UI Components\n\n- **Sensor Cards**: Sensor status display\n- **Actuator Cards**: Actuator controls\n- **Telemetry Tables**: Historical data tables\n- **Policy Dialogs**: Modals for policy management\n\n## 📈 Monitoring\n\n### InfluxDB\n\n- **Organization**: hvac-org\n- **Bucket**: hvac_data\n- **Token**: my-secret-token\n- **Retention**: Configurable\n\n### Grafana\n\n- **Dashboards**: Pre-configured for HVAC\n- **Panels**: Temperature, Humidity, Energy, Airflow\n- **Alerts**: Configurable for critical thresholds\n\n### Logs\n\n- **Telemetry**: `/telemetry_logs/` (JSONL format)\n- **Application**: Console output with configurable levels\n- **Gateway**: `/gateway/logs/`\n\n## 🛠️ Development\n\n### Project Structure\n\n```\nHVAC-System/\n├── config/                 # System configurations\n├── data_collector/         # Main Flask API\n├── dashboard/              # Next.js frontend\n├── gateway/                # CoAP Gateway\n├── smart_objects/          # Simulated IoT devices\n├── cloud_simulator/        # Cloud simulator\n├── mqtt_broker/            # MQTT configuration\n└── docker-compose.yml      # Service orchestration\n```\n\n### Adding New Smart Objects\n\n1. **Create the device** in `/smart_objects/devices/`\n2. **Implement sensors/actuators** in `/smart_objects/sensors/` or `/actuators/`\n3. **Update the factory** in `/data_collector/factories/smart_object_factory.py`\n4. **Configure policies** in `/data_collector/conf/policy.json`\n5. **Update UI** in `/dashboard/components/`\n\n### Testing and Debugging\n\n```bash\n# Test individual smart objects\npython process.py\n\n# CoAP test\npython coap_test.py\n\n# Event monitoring\npython monitor_control_events.py\n\n# Docker logs\ndocker compose logs -f\n```\n\n## 🤝 Contributing\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/AmazingFeature`)\n3. **Commit** your changes (`git commit -m 'Add some AmazingFeature'`)\n4. **Push** to the branch (`git push origin feature/AmazingFeature`)\n5. **Open** a Pull Request\n\n### Guidelines\n\n- Follow existing code style\n- Add tests for new features\n- Update documentation\n- Test across all components\n\n## 📄 License\n\nThis project is developed for academic purposes - UNIMORE.\n\n---\n\n**Note**: This is a simulation system for educational purposes. For production use, implement additional security measures and real hardware validation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarincervinschi%2Fhvac-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarincervinschi%2Fhvac-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarincervinschi%2Fhvac-system/lists"}