Easy Homelab Server Switch

» Client component «

Explore the docs »

Table of Contents

1. Useful shortcuts
   • Project overview
   • Cloudflare
   • Server
   • Microcontroller (ESP32)
   • Client
2. Getting started
3. Components
   • Main
   • Configuration
   • Configuration module
   • MQTT module
   • Network module
   • TLS module
   • SSH module
   • Environment
   • UI control
   • Logger
   • Paths
4. Configuration
5. Buildozer configuration

Useful shortcuts

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

(back to top)

Getting started

This repository is part of the Easy Homelab Server Switch project. If you are exploring it for the first time, start with the Project Overview README repository which explains the architecture and interaction between all components.

(back to top)

Components

The client MQTT agent is organized into small modules, each responsible for a specific part of the system.

Main (main.py)

• The entry point of the Kivy application.
• Orchestrates the application.

(back to top)

Configuration (config.py)

• Defines the central dictionary for broker settings, credentials, and MQTT topics.

(back to top)

Configuration module (config_module.py)

• Provides validation to ensure all critical parameters are present before the system attempts to start.

(back to top)

MQTT module (mqtt_module.py)

• Manages the secure TLS connection to the MQTT broker.
• Subscribes to TOPIC_STATE and TOPIC_ESP32_STATEand triggers local actions based on incoming remote commands.
• Publishes commands on TOPIC_CONTROL.

(back to top)

Network module (net_module.py)

• Performs network validation, method depends on the OS.

(back to top)

TLS module (tls_module.py)

• Manages the CA certificates required for secure MQTT and Cloudflare communication.
• Ensures secure storage and retrieval of certificates data within the application's data directory.

(back to top)

SSH module (ssh_module.py)

• Enables remote server access via SSH if the client is in the same local subnet.

(back to top)

Environment (constants.py)

• Defines shared constants used across the application.

(back to top)

Translations (translations.py)

• Provides multi-language support for all UI labels and log messages.

(back to top)

Ui control (ui_control.py)

• Manages the Kivy-based graphical interface.

(back to top)

Logger (logger.py)

• Records application activity and errors to both the console and a local file for debugging.

(back to top)

Paths (paths.py)

• Resolves and creates the application data directory.

(back to top)

Configuration

The system is configured via the config.py file using environment variables.

Category	Variable	Description
---	LANG	Language in "xy" format
MQTT_CONFIG	ip	The IP address of the cloud cluster in MQTT broker.
	port	The secure MQTT port (default: 8883 for TLS)
	user	Username used for authenticating with the broker.
	pass	Password used for authenticating with the broker.
TOPICS	Check here	and here
SSH_CONFIG	user	User you want to log in via SSH
	ip	Local IP of the server
	subnet_prefix	Local internet prefix (default: 24)
---	MQTT_CA_CERTIFICATE	ISRG Root X1 certificate for validating the MQTT broker connection.

(back to top)

Buildozer configuration (Android)

The Buildozer is configured via the buildozer.spec file using environment variables.

Variable	Example
title	Server
package.name	server
package.domain	org.server

Make sure those settings match exactly.

Variable	Value
requirements	python3,kivy,paho-mqtt,pyjnius
android.permissions	INTERNET, WRITE_EXTERNAL_STORAGE, ACCESS_NETWORK_STATE

(back to top)