advanced usage

Advanced Usage

This page covers advanced features of system2mqtt including user-defined callbacks, built-in remote commands, Argon ONE Raspberry Pi case support, and storage filtering.

---

User-Defined MQTT Callbacks

You can define custom Python functions that are triggered when a specific MQTT message is received.

Setup

Step 1: Create user_callbacks.py in the root of the repository by copying the example:

cp user_callbacks.py.example user_callbacks.py

Step 2: Define your functions in user_callbacks.py. Each function must accept the following signature:

def my_function(client, userdata, message, *args, **kwargs):
    payload = message.payload.decode("utf-8")
    # do something...

Parameter	Description
client	The Paho MQTT client instance. Use client.publish(topic, payload) to publish back.
userdata	Arbitrary user data (usually not needed).
message	The MQTT message object. Access payload via message.payload.decode("utf-8").

Step 3: Map MQTT topics to your functions in s2m.conf:

USER_CALLBACKS=True
CALLBACKS={'system2mqtt/MyComputer/callbacks/lights': 'toggleLights', 'system2mqtt/MyComputer/callbacks/alarm': 'triggerAlarm'}

The key is the full MQTT topic to subscribe to. The value is the function name from user_callbacks.py.

Example

# user_callbacks.py

def toggleLights(client, userdata, message, *args, **kwargs):
    payload = message.payload.decode("utf-8")
    if payload == "on":
        print("Turning lights ON")
        # add your light control logic here
    elif payload == "off":
        print("Turning lights OFF")

def triggerAlarm(client, userdata, message, *args, **kwargs):
    payload = message.payload.decode("utf-8")
    if payload == "1":
        print("Alarm triggered!")
        # publish a confirmation
        client.publish("system2mqtt/MyComputer/alarm/status", "triggered")

Trigger from the command line:

mosquitto_pub -h localhost -t "system2mqtt/MyComputer/callbacks/lights" -m "on"

---

Built-in Remote Commands

system2mqtt subscribes to several command topics automatically. No extra configuration is needed.

Topic	Payload	Effect
<base>/tele/PUBLISH_PERIOD	Integer (seconds)	Change the publish interval at runtime.
<base>/callbacks/s2m_quit	(any)	Gracefully stop the application.
<base>/callbacks/shutdown	1	Shut down the host system.
<base>/callbacks/reboot	1	Reboot the host system.

Warning: The shutdown and reboot commands execute operating system commands. Ensure your MQTT broker is secured appropriately to prevent unauthorized access.

Example — change publish interval to every 10 seconds:

mosquitto_pub -h localhost -t "system2mqtt/MyServer/tele/PUBLISH_PERIOD" -m "10"

---

Argon ONE Raspberry Pi Case

The Argon ONE and Argon EON cases for Raspberry Pi include a programmable fan and (in the EON) support for attached storage. system2mqtt can monitor both.

Enable Argon ONE support

ARGON=True

What gets monitored

Metric	Source
Fan speed (fan_speed)	Read from /tmp/fanspeed.txt (set by the Argon daemon), or calculated from CPU temperature thresholds in /etc/argoneon.conf or /etc/argononed.conf.
HDD temperatures (disks/temperature/<disk>)	Read via smartctl from attached drives.

Requirements

• The Argon ONE / EON daemon must be installed for fan speed to be read from /tmp/fanspeed.txt. Without it, system2mqtt calculates fan speed from CPU temperature thresholds.
• smartmontools must be installed: sudo apt install smartmontools
• Reading disk temperatures typically requires elevated privileges. Run with sudo or grant permissions via sudoers.

---

Storage Filtering

By default, system2mqtt reports all mounted disks. You can filter which disks are included.

Include specific disks

STORAGE_INCLUDE=["sysroot", "mynas"]

When STORAGE_INCLUDE is set, only the listed disk labels are reported. All others are ignored.

Exclude specific disks

STORAGE_EXCLUDE=["tmpfs", "devtmpfs", "udev"]

When STORAGE_EXCLUDE is set, the listed disk labels are skipped. All others are reported.

STORAGE_INCLUDE takes precedence over STORAGE_EXCLUDE. If both are set, only STORAGE_INCLUDE is used.

Finding disk labels

Disk labels correspond to the partition or device name reported by psutil. To see what labels your system uses, enable debug logging temporarily:

DEBUG_LOG=True

Then look for log entries listing disk partitions on startup.

---

ZFS Support

system2mqtt includes support for ZFS pools via the zfslib library. ZFS pools are detected automatically alongside standard partitions and included in disk storage reporting.

No extra configuration is required. ZFS pools appear in storage topics using their pool name as the label:

system2mqtt/MyServer/disks/storage/rpool
system2mqtt/MyServer/disks/mount/rpool