A self-hosted IoT home automation platform built around ESP32 devices, MQTT, Kubernetes microservices, a React dashboard, and an Android app.

The fastest way to understand or run home-anthill is through the documentation repository:

Use the full-project helper when you want the main service, app, firmware, and infrastructure repositories in one local workspace:

curl -fsSLO https://raw.githubusercontent.com/home-anthill/docs/master/download-full-project.sh
sh download-full-project.sh
cd home-anthill

Then follow Local development setup to start MongoDB, Redis, RabbitMQ, Mosquitto, and the services you need.

After api-server and admission are running, seed sample homes, rooms, devices, and assignments with:

curl -fsSLO https://raw.githubusercontent.com/home-anthill/docs/master/fill-local-db.sh
chmod +x fill-local-db.sh
./fill-local-db.sh "<JWT_VALUE>" "oauth_session=<COOKIE_VALUE>"

fill-local-db.sh defaults to API_SERVER=http://localhost:8082 and ADMISSION_SERVER=http://localhost:8099; override those environment variables if your local services use different addresses.

home-anthill is a full-stack home automation project for collecting sensor data, controlling devices, tracking device presence, and sending mobile notifications.

The system starts at the edge: ESP32 microcontrollers run environmental sensor nodes, infrared air-conditioner controllers, or an offline-first thermostat. They communicate over MQTT with a backend that validates, routes, stores, and exposes device state through APIs. Users interact with the platform through a web dashboard and an Android app backed by GitHub OAuth2 authentication.

The project is intentionally split into focused repositories. Each service owns a small part of the system, while the docs and deployer repositories explain how to run everything together locally or on Kubernetes.

• Register homes, rooms, devices, profiles, and sensors.
• Collect temperature, humidity, motion, light, air pressure, and air quality readings from ESP32 devices.
• Control supported devices, including infrared air conditioners and thermostat-style controllers.
• Run an offline-first heating or cooling thermostat with persisted setpoint and tolerance settings, hysteresis control, and dedicated heat, cold, fan, and pump outputs.
• Bench-test the thermostat without a physical thermocouple by using a second ESP32-S3 as an MCP9600 I2C simulator.
• Track whether devices are online by consuming signed MQTT presence messages.
• Store sensor history in MongoDB and online state in Redis.
• Send Firebase Cloud Messaging notifications when monitored devices go offline.
• Provide REST and gRPC APIs for web, mobile, and service-to-service workflows.
• Run locally with Docker-based infrastructure or in production on a K3s Kubernetes cluster.

Device and service messages are designed around signed payloads rather than trusted plaintext messages:

• MQTT sensor and presence messages include signed payloads with timestamp, nonce, and HMAC validation.
• producer forwards MQTT messages into RabbitMQ, and consumer verifies RabbitMQ message HMACs before applying side effects.
• consumer and alarm-receiver use Redis SET NX EX replay keys to reject reused signed nonces.
• Public user-facing APIs use GitHub OAuth2 and JWT-backed sessions.
• Profile device API tokens are stored hashed and encrypted in MongoDB, not as plaintext token fields.

Production deployments terminate public TLS at the Kubernetes ingress layer. Internal service traffic is expected to run inside the cluster network.

The firmwares repository contains independently buildable ESP32 projects:

Supported controller work includes Beko RG52A9/BGEF and LG AKB74955603 style IR remotes, with firmware integration built on crankyoldgit/IRremoteESP8266.

The device projects use Arduino CLI and include host-side CMake/GoogleTest suites. The MCP9600 simulator is a standalone ESP-IDF project.

1. An ESP32 publishes signed MQTT sensor or presence data to Mosquitto.
2. producer receives sensor messages and writes them to RabbitMQ.
3. consumer verifies message integrity and replay state, then stores sensor values in MongoDB.
4. alarm-receiver receives presence messages, verifies them, and updates Redis.
5. online exposes online state and FCM token APIs.
6. alarm-notifier checks Redis for offline devices and sends mobile notifications.
7. api-server, api-devices, and admission manage user-facing device, home, room, profile, and registration workflows.
8. gui and app give users web and mobile access to the same backend.

The thermostat keeps its heating or cooling control loop on the ESP32, so local temperature control continues without backend connectivity; MQTT connects it to registration, telemetry, and remote configuration workflows.

For a full local checkout, see docs/download-full-project.sh, which clones the main service, app, firmware, and infrastructure repositories into one workspace.

Most repositories include their own README and service-specific development guidance. In general:

• Go and Rust services use make build and make test where available.
• The React dashboard uses npm, Vite, Nx, Vitest, React Testing Library, and MSW.
• Android builds use Gradle and Jetpack Compose.
• Firmware device builds use arduino-cli and generated configuration headers; host tests use CMake/GoogleTest, and the MCP9600 simulator uses ESP-IDF.
• Local integration testing depends on MongoDB, Redis, RabbitMQ, and Mosquitto running with the documented local settings.

The current roadmap is tracked in the public home-anthill project board. Use the board as the source of truth for planned work, active items, completed work, and priority changes across repositories.