Easy Homelab Server Switch

» Project overview «

Explore the docs »

Table of Contents

1. Useful shortcuts
   • Project overview
   • Cloudflare
   • Server
   • Microcontroller (ESP32)
   • Client
2. About the project
3. Guide
4. Deployment roadmap
5. Getting Started
   • Key features
   • Requirements
   • Roles
   • My configuration
6. MQTT
   • Sequence diagrams
   • State machine diagrams
   • Communication architecture
   • Messages (payload) dictionary

Useful shortcuts

Module	Repository	README	License
Project overview
Cloudflare
Server
Microcontroller (ESP32)
Client

(back to top)

About the project

You can get information about the project on the official website.

(back to top)

Guide

If you want to get the system up and running as quickly as possible, consider following the guide.

Alternatively, you can follow the free deployment roadmap.

(back to top)

Deployment roadmap (TL;DR)

This roadmap provides the essential steps to get EHSS running.

MQTT Broker

• Use MQTT broker of your choice or self-host Mosquitto.
• Create three sets of credentials (with Pub/Sub permissions) for: Server, ESP32, and Client.
• Note your Broker URL and Port.

Cloudflare Worker

Option A (With GitHub Pages):

• Create a static "Offline" page repo on GitHub.
• Create a new DNS record (CNAME) in Cloudflare for username.github.io
• Create new DNS records (A) on domain registrar page following the GitHub docs.
• Adjust the configuration file (wrangler.toml) by modifying the following fields.
• Deploy the worker via Wrangler.

Option B (Without GitHub Pages):

• Adjust the configuration file (wrangler.toml) by modifying the following fields.
• Adjust the build_offline_page() function in the index.js file to customize the page.
• Deploy the worker via Wrangler.

Linux Server

• Adjust the configuration file (config.py) by modifying the following fields.
• Deploy via Docker: sudo docker-compose up -d --build --force-recreate.

ESP32

• Use Arduino IDE with ESP32 board support.
• Install the required libraries.
• Adjust the configuration file (config.cpp) by modifying the following fields.
• Upload the firmware to the microcontroler.

Client App

Windows

• Make sure you have required software installed on the PC.
• Adjust the configuration file (config.py) by modifying the following fields.

Android (Optional)

• Make sure you have required software installed on the VM.
• Adjust the configuration file (config.py) by modifying the following fields.
• Initialize Buildozer.
• Adjust the Buildozer configuration file (buildozer.spec) by modifying the following fields.
• Build the Android APK buildozer -v android debug.

Getting started

Key features

• Remote shutdown of the server
• Remote wake-up of the server
• Real-time status monitoring (via TCP port checks and heartbeats)
• TLS support
• Cross-platform client (Windows, Android)
• Works behind CGNAT (no public IP required)

(back to top)

Requirements

Before starting, make sure you have access to the following components and tools:

Accounts

• MQTT broker
• Cloudflare account
• GitHub account

Hardware

• Linux server with static IP
• Linux VM
• ESP32 microcontroller
• Client device
  • PC with Windows
  • (optional) Android phone

Software

Depending on which components you deploy, you may need the following tools:

Device	Tool
Server	Docker
	Docker Compose
PC	Python 3.10+
	git
	pip
	Arduino IDE
VM	ADB
	npm
	openjdk 17
	buildozer

Arduino IDE

Library	Author
ArduinoJson	Benoit Blanchon
LibSSH-ESP32	Ewan Parker
PubSubClient	Nick O'Leary
WakeOnLan	a7md0

(back to top)

Roles

MQTT Broker

• Receives MQTT commands (all topics)
• Receives MQTT messages (all topics)
• Routes MQTT commands (all topics)
• Routes MQTT messages (all topics)

Cloudflare Worker

• Routes traffic when the server is down
  (no redirects — the user stays on the same URL)
• Displays a static "Server is offline" page

Linux Server

• Receives MQTT commands (TOPIC_SYSTEM)
• Sends MQTT messages (TOPIC_HEARTBEAT)
• Executes server shutdown

ESP32 Controller

• Receives MQTT messages (TOPIC_CONTROL, TOPIC_HEARTBEAT)
• Sends MQTT commands (TOPIC_SYSTEM)
• Sends MQTT messages (TOPIC_STATE, TOPIC_ESP32_STATE)
• Sends WOL magic packets to start the server
• Monitors server state via TCP port checks
• Switches the Cloudflare Worker mode

Client Application

• Receives MQTT messages (TOPIC_STATE, TOPIC_ESP32_STATE)
• Sends MQTT messages (TOPIC_CONTROL)
• Opens an SSH window on Windows (LAN)

(back to top)

My configuration

MQTT

• Cloud broker: HiveMQ Cloud (Free “Serverless” option)
• Separate users for server, ESP32, and client

Cloudflare

• Worker name: offline-mode

Linux Server

• OS: Ubuntu Server 24.04.3 LTS
• Kernel: GNU/Linux 6.8.0-101-generic x86_64

ESP32 Controller

• Model: ESP32-C3-MINI-1

Client

PC

• OS: Windows 10 21H2
• Python: 3.13.7

Phone

• OS: Android 16

VM (for building Android client and deploying Cloudflare Worker)

• OS: Ubuntu Desktop 24.04.4 LTS

(back to top)

MQTT

Sequence diagrams

Turning on the server

Turning off the server

Turning on the ESP32

Turning on the ESP32

(back to top)

State machine diagrams

TOPIC_STATE

TOPIC_ESP32_STATE

TOPIC_CONTROL

TOPIC_SYSTEM

TOPIC_HEARTBEAT

(back to top)

Communication architecture

Topic	Publisher	Subscriber(s)	Usage	Supported messages (Payloads)
TOPIC_CONTROL	Client	Microcontroller	Sending on/off commands	ON OFF
TOPIC_SYSTEM	Microcontroller	Server	Sending system commands	SHUTDOWN
TOPIC_HEARTBEAT	Server	Microcontroller	Sending server state	ALIVE DEAD
TOPIC_STATE	Microcontroller	Client	Announcing server state	STARTING ONLINE SHUTTING_DOWN OFFLINE
TOPIC_ESP32_STATE	Microcontroller	Client	Announcing microcontroller state	ONLINE OFFLINE

(back to top)

Messages (payload) dictionary

Topic	Message (Payload)	Meaning	Retained?
TOPIC_CONTROL	ON	Server start request	No
	OFF	Server shutdown request	No
TOPIC_SYSTEM	SHUTDOWN	Server shutdown command	No
TOPIC_HEARTBEAT	ALIVE	Server is active	Yes
	DEAD	Server is not active	Yes
TOPIC_STATE	STARTING	Server is starting	Yes
	ONLINE	Server is responding	Yes
	SHUTTING_DOWN	Server is shutting down	Yes
	OFFLINE	Server is not responding	Yes
TOPIC_ESP32_STATE	ONLINE	ESP32 is active	Yes
	OFFLINE	ESP32 is not active	Yes

(back to top)