Homebridge Setup (mqttthing)
Relevant source files
The following files were used as context for generating this wiki page:The homebridge-mqttthing plugin is a crucial component of the Overlord Network Kill Switch project. It acts as the bridge between the Apple HomeKit ecosystem and the project's MQTT-based control system. This allows users to control network access—such as blocking streaming services or disabling internet for specific devices—through simple switches on their iOS devices.
This setup relies on a chain of components: HomeKit sends a command to Homebridge, which translates it into an MQTT message. A Node-RED instance listens for these messages, parses them, and makes corresponding API calls to the backend Gunicorn/FastAPI server, which in turn controls Pi-hole and Ubiquiti devices.
Sources: README.md:4-8, AGENTS.md:9-11
Architecture Overview
The integration of Homebridge via mqttthing fits into the overall system architecture as the primary user interface entry point. A user action in the Home app on an iOS device initiates a command that flows through the system to execute a network change.
The following diagram illustrates the data flow from a user's action in HomeKit to the target service (Pi-hole or Ubiquiti).
Sources: README.md:104-123, AGENTS.md:9-11
Configuration
To integrate with the system, homebridge-mqttthing requires a specific JSON configuration for each switch you want to create in HomeKit. Each switch is defined as an accessory of type switch.
Sources: README.md:66-67
Example mqttthing Configuration
Here is an example configuration for three different switches: one for a specific service ("HBO"), one for master ad-blocking control, and one for a group of domains ("SchoolWork").
{
"type": "switch",
"name": "HBO",
"debounceRecvms": 100,
"topics": {
"getOnline": "stat/dns_controller/master/service_status",
"getOn": "stat/dns_controller/media/hbomax/status",
"setOn": "cmnd/dns_controller/media/hbomax/change"
},
"accessory": "mqttthing"
},
{
"type": "switch",
"name": "ADs On(♾️)",
"topics": {
"getOnline": "stat/dns_controller/master/service_status",
"getOn": "stat/dns_controller/master/status",
"setOn": "cmnd/dns_controller/master/perm_change"
},
"accessory": "mqttthing"
},
{
"type": "switch",
"name": "SchoolWork",
"topics": {
"getOnline": "stat/dns_controller/master/service_status",
"getOn": "stat/dns_controller/media/school_work/status",
"setOn": "cmnd/dns_controller/media/school_work/change"
},
"accessory": "mqttthing"
}
Sources: README.md:68-99
MQTT Topic Breakdown
The functionality of each switch is defined by its topics configuration. These topics dictate how mqttthing interacts with the MQTT broker to get status and send commands.
| Topic Key | Purpose | Example Topic | Direction |
|---|---|---|---|
getOnline | Determines if the backend service is running. This is a global status for all switches. | stat/dns_controller/master/service_status | mqttthing <- |
getOn | Gets the current on/off state of the specific switch (e.g., is "HBO" currently blocked?). | stat/dns_controller/media/hbomax/status | mqttthing <- |
setOn | Sends a command to change the state of the switch (e.g., turn blocking for "HBO" on or off). | cmnd/dns_controller/media/hbomax/change | mqttthing -> |
Sources: README.md:72-75, node_red_flows/dns.json
The getOnline topic is a Last Will and Testament (LWT) topic published by the backend FastAPI application to indicate its availability.
Sources: cgi-bin/controller.py:160-167, 185-186
Node-RED Message Flow
Node-RED is the intermediary that translates MQTT messages from mqttthing into HTTP API calls to the backend server. The provided dns.json flow defines the logic for this translation.
Command Flow (cmnd)
When a user toggles a switch in HomeKit, mqttthing publishes a message to a cmnd/... topic. Node-RED processes this message to trigger an action.
The following diagram shows how a command to change a media-related domain block is handled.
The logic within the Node-RED function node is responsible for constructing the correct API endpoint based on the MQTT topic and payload.
- A message on
cmnd/dns_controller/media/+/changeis parsed to extract the target (e.g.,hbomax). - The payload (
trueorfalse) determines the action (enableordisable). - An HTTP POST request is made to the corresponding endpoint, e.g.,
/pihole/enable/hbomax.
Sources: node_red_flows/dns.json:48-73
Status Flow (stat)
To keep the HomeKit switch state in sync, the backend system (or Node-RED itself) publishes status updates to stat/... topics. mqttthing subscribes to these topics to update the UI.
The following diagram shows the flow for a status update.
Sources: README.md:73, node_red_flows/dns.json:74-83
Node-RED also plays a role in propagating status. After a successful command, it takes the HTTP response from the API server, extracts the status, and publishes it back to the appropriate stat topic on the MQTT broker.
Sources: node_red_flows/dns.json:96-110, 298-312
Summary
The homebridge-mqttthing plugin provides a user-friendly interface for the powerful network control capabilities of the Overlord project. By defining simple switch accessories with specific MQTT topics, users can seamlessly manage Pi-hole domain blocking and Ubiquiti firewall rules directly from Apple's Home app. The integration is made possible by Node-RED, which acts as a flexible and robust bridge between the MQTT messages generated by HomeKit actions and the project's backend RESTful API.
Sources: README.md:4-8, AGENTS.md:9-11