MineMon

MineMon is a tiny ESP32-C3 gadget that watches your Minecraft server and shows its status on an RGB LED — no laptop, no dashboard, just a light on your desk. A physical button lets you start the server remotely, and the LED flashes purple whenever a new player joins.

LED	Meaning
Solid green	Minecraft server is up
Solid red	Minecraft server is down
Blinking yellow	Start requested, server booting up
Blinking red	Host machine itself is unreachable (nothing can be started remotely)
Blinking purple	A player just joined (for ~20s)

How it works

• The ESP32-C3 connects to your WiFi and repeatedly probes the Minecraft server's TCP port. It also polls a small HTTP control server running on the same machine as Minecraft, to check for a "player joined" event and to trigger a server start.
• A Flask script (Minecraft_script/minecraft_server_control.py) runs on the machine hosting the Minecraft server. It exposes two HTTP endpoints: one to launch the server via a shell script you provide, and one that reports whether a player has joined recently (detected by tailing the server's log file).
• A button wired to the ESP32 lets you request a server start by pressing it — the ESP32 checks the Flask host, fires the start request, and blinks yellow until the Minecraft port comes up.

Hardware

• ESP32-C3 Supermini board (or any ESP32-C3; adjust GPIO numbers if your board differs)
• A common RGB LED (or three individual LEDs) wired to three GPIOs
• A push button wired to one GPIO and GND

Default wiring (see #defines at the top of main/main.c):

Signal	GPIO
Button	GPIO10 (to GND, uses internal pull-up)
LED red	GPIO3
LED green	GPIO4
LED blue	GPIO2

Installing the firmware

Requires ESP-IDF (this project was built against v6.0).

git clone <this-repo-url>
cd MineMon

# Fill in your WiFi and server details (this file is gitignored, never committed)
cp main/config.h.example main/config.h
$EDITOR main/config.h

. /path/to/esp-idf/export.sh   # source the ESP-IDF environment if not already active

idf.py set-target esp32c3
idf.py build
idf.py flash monitor

main/config.h holds:

• WIFI_SSID / WIFI_PASS — your WiFi network credentials
• TARGET_IP / TARGET_PORT — the Minecraft server's IP and port (usually 25565)
• START_SERVER_PORT / START_SERVER_PATH — where the Flask control script (below) is listening, on the same host as the Minecraft server

Installing the control script

On the machine that runs your Minecraft server, install Flask and run Minecraft_script/minecraft_server_control.py:

pip install flask

Configure it via environment variables (all optional, with placeholder defaults):

Variable	Purpose	Default
MINEMON_START_SCRIPT	Path to a script that starts your Minecraft server	/path/to/start_server.sh
MINEMON_LOG_PATH	Path to the server's log file (e.g. logs/latest.log for Spigot/Paper)	/path/to/minecraft/logs/latest.log
MINEMON_CONTROL_PORT	Port for this control server to listen on — must match START_SERVER_PORT in config.h	8080

MINEMON_START_SCRIPT=/home/you/minecraft/start.sh \
MINEMON_LOG_PATH=/home/you/minecraft/logs/latest.log \
python3 Minecraft_script/minecraft_server_control.py

For it to survive reboots, run it as a service (systemd user service, screen/tmux, or similar) that starts on login/boot.

Note: the "player joined" detection just looks for "joined the game" in the log file, which matches vanilla Spigot/Paper output. If a plugin changes that message format, update JOIN_PATTERN in the script.