mqtt-presence 0.2.9

Lightweight MQTT-based presence detection with shutdown and Raspberry Pi GPio support

mqtt-presence

mqtt-presence is a lightweight Python-based presence indicator for MQTT systems. Originally designed for Raspberry Pi environments, it now supports Windows, Linux. It reports the online status of a device (e.g., a PC) and listens for shutdown or restart commands.
It is especially useful in smart home environments such as Home Assistant in combination with a mqtt broker.

---

✨ Features

• Publishes device online state and other pc information to MQTT
• Receives shutdown and restart commands via MQTT
• Supports Home Assistant MQTT Discovery (optional)
• Allows configuration of RaspberryPI GPiOs to control inputs (Buttons) and outputs (LEDs) using mqtt and homeassistant
• Configurable status leds for running and mqtt-status using RaspberryPi GPIOs
• RaspberryPi GPIO button support for restart and shutdown
  • Can be used to power down a RaspberryPi with a phyiscal button
• Cross-platform: Windows, Linux (GPIOs only RaspberryPi)
• Configuration via YAML using web UI
• Various installation options, winget, pip, docker, remote script, windows setup, portable exe

---

🚀 Getting Started

The prgramm will be installed as a service placed in sytsem directories (details below). After a succefull installation, the web ui can be opened using:

http://localhost:8100

🐧 Linux

Just use the install / uninstall script. mqtt-presence will be installed as system.d service.

Install

curl -sSL "https://raw.githubusercontent.com/bjoernboeckle/mqtt-presence/main/scripts/install.sh" | bash

Uninstall

curl -sSL "https://raw.githubusercontent.com/bjoernboeckle/mqtt-presence/main/scripts/uninstall.sh" | bash -s -- --yes

---

🐳 Docker

Shutdown/Restart are not supported if running in a container and therefore they are disabled by default.

Docker compose

services:
  mqtt-presence:
    image: bjoernboeckle/mqtt-presence:latest
    container_name: mqtt-presence
    volumes:
      - ./config/:/config
      - ./log/:/log
    network_mode: host      

---

🖥️ Windows

Download and run the installer exe from the latest release:

GitHub releases

mqtt-presence-vx.x.x-setup.exe

Or use winget (latest version will be installed automatically)

winget install mqtt-presence

Note: Installation and uninstallation require admin rights.

📦 Or using portable Executable

Download the latest executable from the GitHub releases page.

mqtt-presence-vx.x.x.exe

---

🐍 As Python Package

Install via pip:

pip install mqtt-presence

Run:

mqtt-presence

Run as Python module:

python -m mqtt_presence.main

---

⚙️ Command Line Options

mqtt-presence.exe --config CONFIG_PATH --log LOG_PATH   # use CONFIG_PATH as configuration directory
                                                        # use LOG_PATH as log directory

---

📟 Web UI

Access the Web UI in your browser at:

http://<ip-address>:8100

Example: http://localhost:8100

Apply configuration needs to executed to apply changed settings!

App config

On this page app base settings can be changed:

Parameter	Description
Host	Web UI listen server 0.0.0.0 to listen on all IP adresses.
Port	WebUI port number
update rate	Frequency which is used to update data and publishes to mqtt
Enable MQTT	Enables / Disabled mqtt, if diabled, GPIOs etc.can still be used in WebUI
Enable PC Utilities	PC Information will not be send if dsabled
Enable RaspberryPi	Disabled RaspberryPi GPIOs

MQTT

This pages is used to configure mqtt connection and settings.

Parameter	Description
Broker	IP address of mqtt broker
Username	Username for mqtt broker
Password	Password for mqtt user, password will not be save inside the configuration.yaml file
Prefix	Topic prefix for this client PC
Enable Homeasistant Discovery	used to enable/disable home assitant discovery. Homeassiatnat must have autodiscovery enabled.
Discovery Prefix	Discoveryprefix for homeassistant, should be "homeassistant" if bnot changed in HAS
Device name	Device name shown in Homeassistant

PC utilities

This pages is used to enable/disable shutdown/resatrt commands and to view current oc status.

Parameter	Description
Enable shutdown	Shutdown command is is enabled/disabled
Enable reboot	Reboot command is is enabled/disabled
Enable infos	PC infos can be disabled (CPU frequency, ram usage ....

Raspberry PI

This interface allows you to add, edit, and remove GPIO pins for your Raspberry Pi in the app. Each GPIO pin can be configured either as an LED or a Button, with various setting options.

Each GPIO entry is displayed as a row.

On the far left is a red ❌ button to remove that GPIO entry. To the right are all the input fields for configuring the GPIO.

Parameter	Description
Pin	Numeric GPIO pin number on the Raspberry Pi. Example: 17. --> must be unique.
Mode	GPio is used as LED or Button (Input or output)
Name	A free-text name to easily identify the pin.
LED
LED Mode	On/Off or Blink, Blink toggles on off in 1 second intervalls if switched on
LED Function	None: LED / output can be used by mqtt or web interface App running: LED is on while the app is running MQTT online: The LED is on as long as there is an active mqtt connection
Button
Bounce	Sets a debounce time, to avoid bouncing if a buton is pressed
Pull-up	Enables/Disables an internal pull up resistor
Pressed Released Held	Sets a button function for pressed, released or held: None: The button can be used for instance in homeassistant Shutdown Shutsdown the PC Reboot Reboots the pc

---

🛠 Configuration

Configuration files are created on first run.

Application Settings: (configuration.yaml)

This file is configured using the webUI.

# Configuration file for MQTT Presence
# Please refer to the documentation for details on how to configure.
app:
  updateRate: 2
  webServer:
    host: 0.0.0.0
    port: 8100
  mqtt:
    enabled: true
    broker:

Changes require a restart of the service, which will be automatically done using the web UI. Manuall changes require a manual restart.

📁 Directory Structure

Installation paths used by installer/scripts:

OS	Paths
Linux	Install: /opt/mqtt_presence Data: /etc/mqtt_presence Logs: /var/log
Windows	Install: %ProgramData%\mqtt_presence Data: %ProgramData%\mqtt_presence\data Logs: %ProgramData%\mqtt_presence\log

---

Default Config/Data Paths

OS	Config Path
Linux	~/.config/mqtt_presence
Windows	%APPDATA%\mqtt_presence
macOS	~/Library/Application Support/mqtt_presence

---

Default Log Paths

OS	Log Path
Linux	~/.local/state/mqtt_presence/
Windows	%LOCALAPPDATA%\mqtt_presence\
macOS	~/Library/Logs/mqtt_presence/

---

Cache Paths

OS	Cache Path
Linux	~/.cache/mqtt_presence/status.cache
Windows	%LOCALAPPDATA%\mqtt_presence\Cache\status.cache
macOS	~/Library/Caches/mqtt_presence/status.cache

---

🧠 License

Licensed under the Apache License 2.0.