---

FlexiHome: Home Energy Management System

FlexiHome Hub 🔌

Description

This repository contains the FlexiHome Hub, a core component of the Home Energy Management System (FlexiHome). The FlexiHome Hub is a Python-based application designed to monitor and control smart home devices. It leverages MQTT for communication between itself and the FlexiHome micro-services on the cloud.

HEMS Hub can be run:

• As a Python application (for development and testing)
• As a Docker container (for production deployments)
• With Docker Compose (to easily integrate with an MQTT broker and supporting services)

✨ Features

• ⚡ MQTT communication layer (publish/subscribe with configurable broker)
• 🗂️ Device registry management (device_registry.json)
• ⏱️ Scheduler service for periodic tasks and heartbeats
• 🧩 Protocol support extensible via protocols/ (e.g., Modbus, OCPP)
• 🐳 Docker-ready for quick deployment

Table of Contents

• HEMS Overview
• Project Status
• Technology Stack
• Dependencies
• Installation
• Usage
• Known issues
• Links for Docs & demos
• Credits and References
• Contacts

---

FlexiHome Overview

EMSs (Energy Management Systems) play a key role in the flexibility enablement of consumers, residential and tertiary, which is paramount to accessing the previously untapped flexibility potential of residential DERs (Distributed Energy Resources). These resources, under the form of energy assets, are usually household appliances like heat pumps, EV chargers, dishwashers, PV inverts, batteries, etc. This is where the FlexiHome (Home Energy Management System) comes in.

The goal of this system is to facilitate the user’s participation in the flexibility value chain, while providing them with incentives in a clear, explainable way.

To fulfill this goal in an effective and scalable way, the FlexiHome is designed with a micro-services architecture (below), orchestrated in a Kubernetes environment, where each micro-service is modular and can be replaced or expanded, without breaking the remaining logic.

FlexiHome utilizes an IoT interoperable gateway (FlexiHome Hub) to connect to the end users DERs via interoperable protocols like OCPP and Modbus, which connects with the cloud system (FlexiHome Cloud) via an MQTT message broker.

The cloud operations are done via micro-services, where the flexibility optimization algorithms run. To complement these micro-services, support applications like postgres (database), elasticsearch (log database), prometheus (performance metrics) and grafana (metrics dashboard) are used.

Lastly, the user can view the information regarding their devices and flexibility on a user interface provided by the mobile app, which accesses the FlexiHome microservices using a REST API Gateway for additional security measures and routing of requests.

Visit all the FlexiHome micro-services:

• FlexiHome Account Manager - Manages user accounts, authentication, and implements cybersecurity measures within the FlexiHome ecosystem
• FlexiHome Statistics Manager - Collects and processes data gathered from IoT devices connected to the FlexiHome ecosystem
• FlexiHome Device Manager - Responsible for the integration and management of IoT devices to the FlexiHome ecosystem
• FlexiHome Energy Manager - Receives grid needs inputs from system operators and user comfort inputs to optimized the flexibility bids taken to market
• FlexiHome Hub - IoT interoperable gateway that implements the communication, using MQTT protocol, between the DERs and the FlexiHome services on the cloud
• FlexiHome Mobile App - mobile application targetted for residential end consumers to manage their flexible DERs. Available in Android and iOS

---

📂 Project Structure

.
├── Dockerfile              # Docker build instructions
├── docker-compose.yml      # Compose setup (Hub + Broker integration)
├── config.py               # Environment & config loader
├── main.py                 # Entry point for the HEMS Hub
├── device_registry.json    # Device registry (managed by the Hub)
├── hub.id                  # Unique identifier for the Hub
├── core/                   # Core services (hub state, scheduler)
├── devices/                # Device definitions and registry
├── mqtt/                   # MQTT client, handlers, topics, schemas
├── protocols/              # Protocol integrations (e.g. Modbus, OCPP)
├── utils/                  # Utility functions
└── requirements.txt        # Python dependencies

---

⚙️ Configuration

Configuration is managed via environment variables (with defaults from config.py).

Variable	Default	Description
ENVIRONMENT	development	Environment mode (development, production)
DEBUG	false	Enable debug logging
MQTT_BROKER_URL	localhost	MQTT broker hostname or IP
MQTT_BROKER_PORT	80	MQTT broker port
MQTT_BROKER_PATH	/mqtt	MQTT WebSocket path
MQTT_USERNAME	`` (empty)	MQTT username
MQTT_PASSWORD	`` (empty)	MQTT password
MQTT_KEEP_ALIVE	60	Keep-alive interval (seconds)
MQTT_RETRY_INTERVAL	5	Retry interval for reconnection (seconds)
MQTT_TLS_ENABLED	false	Enable TLS for MQTT connection
MQTT_CLIENT_ID	hems_hub_<pid>	Unique client ID (defaults to process ID)
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARN, ERROR)
DEVICE_REGISTRY_FILE	./device_registry.json	Path to device registry file
SCHEDULER_PUBLISH_INTERVAL	60	Scheduler publishing interval (seconds)
SCHEDULER_HEARTBEAT_INTERVAL	30	Heartbeat interval (seconds)

---

📦 Installation

1. Clone Repository

git clone https://github.com/INESCTEC/hems-hub.git
cd hems-hub

2. Python (Development Mode)

python3 -m venv venv
source venv/bin/activate   # Linux/Mac
venv\Scripts\activate      # Windows

pip install -r requirements.txt

Run the hub:

python main.py

---

🐳 Running with Docker

Build the image:

docker build -t hems-hub .

Run the container:

docker run --rm -it   -p 9050:8080   -e MQTT_BROKER_URL=<ip>   -e MQTT_BROKER_PORT=<port>   hems-hub

---

🐙 Running with Docker Compose

The project includes a docker-compose.yml that builds and runs the hub.

Start services:

docker-compose up --build

This maps port 9050 externally to 8080 inside the container by default.
You can override ports via environment variables:

HEMS_EXTERNAL_PORT=10000 HEMS_INTERNAL_PORT=8080 docker-compose up

---

📡 External Dependencies

HEMS requires an MQTT broker. You can use:

• A cloud broker (e.g., HiveMQ, EMQX, AWS IoT Core)
• A local broker (e.g., Mosquitto)

Example Mosquitto setup:

docker run -it --rm   -p 1883:1883   -p 9001:9001   eclipse-mosquitto

Or EMQX setup:

docker run -it --rm -p 18083:18083 -p 1883:1883 -p 9001:9001 emqx:latest

---

🧪 Example MQTT Interaction

Publish a command to a device:

mosquitto_pub -h localhost -t "hems/device1/command" -m "turn_on"

Subscribe to device status updates:

mosquitto_sub -h localhost -t "hems/device1/status"

If using EMQX the provided dashboard can be used by accessing: http://localhost:18083/

---

📋 Utilized MQTT Structure

To better understand the topic structure utilized, please review the Hems Hub MQTT Structure document.

---

Known Issues

• No major issues reported. Please use GitHub Issues to report bugs or request features.

---

Open Source Licensing Info

See LICENSE for details on usage rights and licensing.

---

Contacts

For questions or support, contact:

• Vasco Manuel Campos: vasco.m.campos@inesctec.pt
• Daniel Barros: daniel.barros@inesctec.pt
• Miguel Cerdeira: miguel.cerdeira@inesctec.pt