MQTT Topics Documentation¶

Introduction¶

This document describes the MQTT topics published by the Genius Gateway. The gateway supports both Home Assistant auto-discovery and custom MQTT topics for integration with other home automation systems connecting to a MQTT broker.

MQTT Configuration¶

MQTT functionality is mainly configured via web frontend or HTTP API endpoints:

Framework MQTT Settings: /rest/mqttSettings - Basic MQTT connection settings
Gateway MQTT Settings: /rest/mqtt-settings - Genius Gateway specific publishing options

Framework MQTT Topics (ESP32 SvelteKit)¶

Device Status Topic (LWT)¶

Topic

genius-gateway/{device-mac}/status

device-mac format

device-mac is the device's MAC address with lowercase hex digits and without any delimiters.
E.g.: 1A:2B:3C:4D:5E:6F 1a2b3c4d5e6f

Description: Framework device online/offline status using MQTT Last Will and Testament (LWT)

QoS: 1

Retain: true

Payloads

Published when device connects to MQTT broker:

"online"

Published automatically by broker when device disconnects (LWT message):

"offline"

Home Assistant Auto-Discovery¶

The gateway supports Home Assistant's MQTT Discovery protocol for automatic device integration.

Gateway Device¶

The Genius Gateway itself is published as a Home Assistant device with diagnostic sensors, remote control buttons, and configuration switches.

Requirements:

Home Assistant Integration must be enabled
MQTT broker must be connected

Overview¶

The gateway device publishes:

1 Status Sensor - Registers the gateway device in Home Assistant
2 Diagnostic Sensors - Free heap memory (%) and core temperature (°C)
1 Restart Button - Remote gateway restart capability
4 Configuration Switches - Remote control of gateway settings

Topic Structure:

{discovery_prefix}genius-gateway/{gateway_device_id}

Gateway Device ID Format

The gateway_device_id follows the format genius-gateway-{device-mac}, where device-mac is the device's MAC address with lowercase hex digits and without any delimiters.
E.g.: 1A:2B:3C:4D:5E:6F genius-gateway-1a2b3c4d5e6f

Device Status Sensor¶

Topic

{discovery_prefix}sensor/{gateway_device_id}/status/config

Example: homeassistant/sensor/genius-gateway-1a2b3c4d5e6f/status/config

Description: Device registration sensor that makes the gateway visible in Home Assistant

QoS: 0

Retain: true

Payload

{
  "~": "homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f",
  "name": "Status",
  "unique_id": "genius-gateway-1a2b3c4d5e6f_status",
  "state_topic": "~/status/state",
  "value_template": "{{value_json.state}}",
  "icon": "mdi:heart-pulse",
  "entity_category": "diagnostic",
  "device": {
    "identifiers": ["genius-gateway-1a2b3c4d5e6f"],
    "name": "Genius Gateway",
    "manufacturer": "Genius Gateway Project",
    "model": "Genius Gateway",
    "sw_version": "1.1.0",
    "configuration_url": "http://192.168.1.100"
  }
}

Payload Fields

~ - Topic prefix (base path for relative references)
name - Entity name shown in Home Assistant
unique_id - Unique identifier for this sensor
state_topic - Relative path to state topic
value_template - Jinja2 template to extract state from JSON
icon - Material Design icon identifier
entity_category - Category (diagnostic for system status)
device - Device information object
identifiers - Device identifier (array with gateway device ID)
name - Device name shown in Home Assistant
manufacturer - Project name
model - Device model
sw_version - Current firmware version
configuration_url - Web interface URL (only included if gateway has valid IP)

State Topic: {discovery_prefix}genius-gateway/{gateway_device_id}/status/state

State Payload

{
  "state": "online"
}

Publishing Behavior

Published when MQTT connection is established
Re-published when MQTT settings change
State published immediately after config
Published only if Home Assistant Integration is enabled

Home Assistant Integration

Automatically creates gateway device with all associated entities
Provides device information panel with manufacturer, model, and firmware version
Links to gateway web interface via configuration URL

Diagnostic Sensors¶

The gateway publishes two diagnostic sensors that share a common state topic for efficient updates.

Free Heap Sensor¶

Config Topic

{discovery_prefix}sensor/{gateway_device_id}/free_heap/config

Example: homeassistant/sensor/genius-gateway-1a2b3c4d5e6f/free_heap/config

Description: Monitors available heap memory as percentage of total heap

QoS: 0

Retain: true

Config Payload

{
  "~": "homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f",
  "name": "Free Heap",
  "unique_id": "genius-gateway-1a2b3c4d5e6f_free_heap",
  "state_topic": "~/diagnostics/state",
  "value_template": "{{value_json.free_heap_percent|round(1)}}",
  "unit_of_measurement": "%",
  "state_class": "measurement",
  "icon": "mdi:memory",
  "entity_category": "diagnostic",
  "device": {
    "identifiers": ["genius-gateway-1a2b3c4d5e6f"]
  }
}

Core Temperature Sensor¶

Config Topic

{discovery_prefix}sensor/{gateway_device_id}/core_temp/config

Example: homeassistant/sensor/genius-gateway-1a2b3c4d5e6f/core_temp/config

Description: Monitors ESP32 internal core temperature

QoS: 0

Retain: true

Config Payload

{
  "~": "homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f",
  "name": "Core Temperature",
  "unique_id": "genius-gateway-1a2b3c4d5e6f_core_temp",
  "state_topic": "~/diagnostics/state",
  "value_template": "{{value_json.core_temp|round(1)}}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "state_class": "measurement",
  "icon": "mdi:thermometer",
  "entity_category": "diagnostic",
  "device": {
    "identifiers": ["genius-gateway-1a2b3c4d5e6f"]
  }
}

Diagnostic State Topic¶

Topic

{discovery_prefix}genius-gateway/{gateway_device_id}/diagnostics/state

Example: homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f/diagnostics/state

Description: Combined state topic for both diagnostic sensors

QoS: 0

Retain: false

Payload

{
  "free_heap_percent": 73.5,
  "core_temp": 42.3
}

Payload Fields

free_heap_percent - Available heap memory as percentage of total heap (float, 0-100)
core_temp - ESP32 internal core temperature in degrees Celsius (float)

Publishing Behavior

Published immediately after config messages (initial state)
Published every 60 seconds via timer
Re-published when MQTT connection is established
Published only if Home Assistant Integration is enabled

Home Assistant Integration

Automatically creates sensor entities with proper units and device classes
Enables historical data tracking and graphing
Can trigger automations based on memory or temperature thresholds
Useful for monitoring gateway health and detecting potential issues

Restart Button¶

Config Topic

{discovery_prefix}button/{gateway_device_id}/restart/config

Example: homeassistant/button/genius-gateway-1a2b3c4d5e6f/restart/config

Description: Button entity for remotely restarting the gateway

QoS: 0

Retain: true

Config Payload

{
  "~": "homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f",
  "name": "Restart",
  "unique_id": "genius-gateway-1a2b3c4d5e6f_restart",
  "command_topic": "~/restart/command",
  "payload_press": "PRESS",
  "icon": "mdi:restart",
  "entity_category": "config",
  "device": {
    "identifiers": ["genius-gateway-1a2b3c4d5e6f"]
  }
}

Key Fields

command_topic - Topic where button press commands are published
payload_press - Payload sent when button is pressed ("PRESS")
icon - Restart icon for visual identification
entity_category - Category (config for configuration entities)

Command Topic: {discovery_prefix}genius-gateway/{gateway_device_id}/restart/command

Command Payload

"PRESS"

Publishing Behavior

Config published when MQTT connection is established
Config re-published when MQTT settings change
Gateway subscribes to command topic automatically
Trigger immediate gateway restart on command reception

Home Assistant Integration

Automatically creates button entity
Press button to restart gateway remotely
Useful for maintenance and troubleshooting without physical access
Can be used in automations (e.g., scheduled restarts)

Configuration Switches¶

Four switches provide remote control of gateway configuration settings that affect device discovery and alert processing.

Config Topic Pattern

{discovery_prefix}switch/{gateway_device_id}/{switch_suffix}/config

Switch Types:

Suffix	Display Name	Setting Controlled
`alert_unknown`	Alert on Unknown Detectors	Process alerts from unregistered smoke detectors
`line_commissioning`	Add Line from Commissioning	Auto-add alarm lines from commissioning packets
`line_alarm`	Add Line from Alarm	Auto-add alarm lines from alarm packets
`line_test`	Add Line from Line Test	Auto-add alarm lines from line test packets

Config Payload Example (Alert on Unknown Detectors)

{
  "~": "homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f",
  "name": "Alert on Unknown Detectors",
  "unique_id": "genius-gateway-1a2b3c4d5e6f_alert_unknown",
  "state_topic": "~/gateway/state",
  "value_template": "{{ value_json.alert_unknown }}",
  "command_topic": "~/gateway/switch/alert_unknown/set",
  "payload_on": "ON",
  "payload_off": "OFF",
  "state_on": "ON",
  "state_off": "OFF",
  "icon": "mdi:toggle-switch-off-outline",
  "entity_category": "config",
  "device": {
    "identifiers": ["genius-gateway-1a2b3c4d5e6f"]
  }
}

Key Fields

state_topic - Shared JSON topic publishing all switch states
value_template - Template to extract specific switch state from JSON
command_topic - Individual topic accepting switch commands
payload_on / payload_off - Payloads for ON/OFF commands
state_on / state_off - State values indicating ON/OFF
entity_category - Category (config for configuration entities)

Central State Topic:

{discovery_prefix}genius-gateway/{gateway_device_id}/gateway/state

State Payload (JSON with all switches)

{
  "alert_unknown": "ON",
  "line_commissioning": "OFF",
  "line_alarm": "OFF",
  "line_test": "ON"
}

Individual Command Topics:

{discovery_prefix}genius-gateway/{gateway_device_id}/gateway/switch/{switch_suffix}/set

Examples: - homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f/gateway/switch/alert_unknown/set - homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f/gateway/switch/line_commissioning/set - homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f/gateway/switch/line_alarm/set - homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f/gateway/switch/line_test/set

Command Payloads

Turn setting ON:

"ON"

Turn setting OFF:

"OFF"

Publishing Behavior

Config published when MQTT connection is established
Config re-published when MQTT settings change
Combined JSON state published immediately after configs (initial state)
Single JSON state published when any setting changes (via web interface or MQTT)
Gateway subscribes to all individual command topics automatically

Home Assistant Integration

Automatically creates switch entities grouped under gateway device
Toggle switches to modify gateway settings remotely
State synchronization between Home Assistant and gateway web interface
Can be used in automations for dynamic behavior control
Useful for temporarily enabling/disabling features without accessing web UI
Efficient state updates - All switches updated with a single MQTT message

Setting Synchronization

Changes made via Home Assistant switches are immediately reflected in the gateway web interface and vice versa. All settings are synchronized bidirectionally.

Efficient State Updates

All four configuration switches share a single JSON state topic. When any setting changes (even just one), all states are published in a single MQTT message, reducing network traffic and ensuring atomic updates.

Firmware Update Entity¶

The gateway publishes an update entity that integrates with Home Assistant's update functionality to manage firmware updates.

Config Topic

{discovery_prefix}update/{gateway_device_id}/firmware/config

Example: homeassistant/update/genius-gateway-1a2b3c4d5e6f/firmware/config

Description: Update entity for firmware management with automatic version checking

QoS: 0

Retain: true

Config Payload

{
  "~": "homeassistant/genius-gateway/genius-gateway-1a2b3c4d5e6f",
  "name": "Firmware Update",
  "unique_id": "genius-gateway-1a2b3c4d5e6f_firmware_update",
  "state_topic": "~/update/state",
  "command_topic": "~/update/install",
  "payload_install": "INSTALL",
  "title": "Genius Gateway Firmware",
  "device_class": "firmware",
  "entity_category": "config",
  "icon": "mdi:cloud-download",
  "device": {
    "identifiers": ["genius-gateway-1a2b3c4d5e6f"]
  }
}

Key Fields

state_topic - Topic publishing firmware version information
command_topic - Topic accepting update installation commands
payload_install - Payload to trigger update installation ("INSTALL")
device_class - Device class (firmware for firmware updates)
title - Update entity title
entity_category - Category (config for configuration entities)

State Topic: {discovery_prefix}genius-gateway/{gateway_device_id}/update/state

State Payload

When no update is available:

{
  "installed_version": "1.1.0",
  "latest_version": "1.1.0",
  "title": "Genius Gateway Firmware 1.1.0",
  "release_url": "https://github.com/hmbacher/genius-gateway/releases/latest"
}

When update is available:

{
  "installed_version": "1.1.0",
  "latest_version": "1.2.0",
  "title": "Genius Gateway Firmware 1.2.0",
  "release_url": "https://github.com/hmbacher/genius-gateway/releases/latest"
}

State Fields

installed_version - Currently installed firmware version
latest_version - Latest available firmware version from GitHub releases
title - Human-readable update title
release_url - URL to GitHub releases page

Command Topic: {discovery_prefix}genius-gateway/{gateway_device_id}/update/install

Command Payload

"INSTALL"

Publishing Behavior

Config published when MQTT connection is established
Config re-published when MQTT settings change
State published after GitHub version check (periodic and on-demand)
State updated when new firmware version is detected
Gateway subscribes to command topic automatically

Update Process

Gateway periodically checks GitHub for new releases
When update is available, state reflects new version
User can trigger installation via Home Assistant or web interface
Gateway downloads firmware from GitHub releases
Firmware is validated and installed
Gateway automatically restarts with new version

Home Assistant Integration

Automatically creates update entity with current and available versions
Shows "Update Available" badge when new firmware is released
Links to GitHub releases page for release notes
Click "Install" in Home Assistant to trigger OTA update
Progress tracking via web interface and event notifications

Internet Connection Required

Firmware updates require an active internet connection to download from GitHub. The gateway must be able to reach github.com and objects.githubusercontent.com.

Smoke Detectors¶

The following topics are used for smoke detector integration with Home Assistant.

Configuration Topic¶

Topic (Default)

homeassistant/binary_sensor/genius-{smoke_detector_sn}/config

Description: Device configuration for Home Assistant auto-discovery

QoS: 0

Retain: true

Payload

{
  "~": "homeassistant/binary_sensor/genius-12345678",
  "name": "Genius Plus X",
  "unique_id": "12345678",
  "device_class": "smoke",
  "state_topic": "~/state",
  "schema": "json",
  "value_template": "{{value_json.state}}",
  "entity_picture": "http://192.168.1.100/hekatron-genius-plus-x.png",
  "device": {
    "identifiers": "12345678",
    "manufacturer": "Hekatron Vertriebs GmbH",
    "model": "Genius Plus X",
    "name": "Rauchmelder",
    "serial_number": "12345678",
    "suggested_area": "Living Room"
  }
}

Payload Fields

~ - Topic prefix (base path for relative references)
name - Entity name shown in Home Assistant
unique_id - Unique identifier (smoke detector serial number)
device_class - Device class (smoke for smoke detectors)
state_topic - Relative path to state topic (expands to {prefix}{sn}/state)
schema - Payload format (json)
value_template - Jinja2 template to extract state from JSON
entity_picture - URL to device icon (only included if gateway has valid IP)
device - Device information object
identifiers - Device identifier for grouping entities
manufacturer - Device manufacturer
model - Device model name
name - Device name
serial_number - Serial number
suggested_area - Suggested Home Assistant area/room

Publishing Behavior

Published when smoke detector is first created or imported
Re-published when MQTT connection is established
Re-published when MQTT settings change
Published only if device publishing is enabled

Home Assistant Integration

Automatically creates binary sensor entity
Adds icon and plenty of metadata (manufacturer, model, serial number, etc.)
Can be used in automations and scenes

State Topic¶

Topic (Default)

homeassistant/binary_sensor/genius-{smoke_detector_sn}/state

Description: Current alarm state of individual smoke detector

QoS: 0

Retain: true

Payload

Published when device is not alarming:

{
  "state": "OFF"
}

Published when device is alarming:

{
  "state": "ON"
}

Payload Fields

state - Alarm state
- "OFF" - Smoke detector not alarming
- "ON" - Smoke detector actively alarming

Publishing Behavior

Published when device alarm state changes
Re-published when MQTT connection is established
Re-published when device configuration changes (location, etc.)
Published only if device publishing is enabled

Home Assistant Integration

Automatically updates binary sensor entity
Entity shows as "Clear" (OFF) or "Smoke detected" (ON)
Can be used in automations and scenes

Alarm Lines¶

The following topics enable remote control of alarm line actions (line tests and fire alarm tests) via MQTT.

Requirements:

Alarm lines must be configured in Genius Gateway
Home Assistant Integration must be enabled
MQTT broker must be connected

Overview¶

Each configured alarm line publishes:

4 Button entities for triggering actions (line test start/stop, fire alarm start/stop)
1 Sensor entity for transmission state monitoring

Topic Structure:

{discovery_prefix}genius-alarmline/{line_id}/{entity_type}/{command|state}

Button Entities Configuration¶

Topic Pattern

{discovery_prefix}button/genius-alarmline-{line_id}-{button_type}/config

Description: Configuration messages for Home Assistant button discovery

QoS: 0

Retain: true

Button Types:

linetest - Start Line Test button
linetest-stop - Stop Line Test button
firealarm - Start Fire Alarm button
firealarm-stop - Stop Fire Alarm button

Example Payload (Line Test Start)

{
  "~": "homeassistant/genius-alarmline/123456789",
  "name": "Start Line Test",
  "unique_id": "genius-alarmline_123456789_linetest_start",
  "command_topic": "homeassistant/genius-alarmline/123456789/linetest/command",
  "payload_press": "{\"action\":\"start\"}",
  "icon": "mdi:map-marker",
  "availability": [{
    "topic": "homeassistant/genius-alarmline/123456789/transmission/state",
    "value_template": "{% if value_json.state == 'Nothing' %}online{% else %}offline{% endif %}"
  }],
  "availability_mode": "all",
  "device": {
    "identifiers": "genius-alarmline-123456789",
    "name": "Alarm Line 'First Floor'",
    "manufacturer": "Hekatron Vertriebs GmbH",
    "model": "Genius Plus X Alarm Line"
  }
}

Key Fields

~ - Topic prefix (base path for relative references)
name - Button name displayed in Home Assistant
unique_id - Unique identifier for this button
command_topic - Topic where button press commands are published
payload_press - JSON payload sent when button is pressed
icon - Material Design icon identifier
availability - Button is only available when no transmission is active
device - Groups all alarm line entities under one device

Publishing Behavior

Published when alarm line is first created
Re-published when MQTT connection is established
Re-published when MQTT settings change
Published only if Home Assistant Integration is enabled

Home Assistant Integration

Automatically creates button entities
Buttons are grouped under alarm line device
Buttons become unavailable during active transmissions
Can be used in automations and dashboards

Command Topics¶

Topic Patterns

{discovery_prefix}genius-alarmline/{line_id}/linetest/command
{discovery_prefix}genius-alarmline/{line_id}/firealarm/command

Description: Accepts commands to trigger line test or fire alarm actions on the specified alarm line

QoS: 0

Retain: false

Payload Format

Start action:

{"action": "start"}

Stop action:

{"action": "stop"}

Payload Fields

action - Command to execute
- "start" - Begin line test or fire alarm transmission
- "stop" - End line test or fire alarm transmission

Command Behavior

Commands are subscribed with wildcard: {prefix}genius-alarmline/+/linetest/command
Gateway extracts alarm line ID from topic path
Triggers RF transmission immediately if no other transmission is active
Rejects commands if previous transmission is still in progress (503 internally)
Updates transmission state sensor to reflect activity

Transmission Blocking

Only one transmission can be active at a time. Commands received during an active transmission are ignored until the current transmission completes (typically 3-10 seconds).

Transmission State Sensor¶

Topic

{discovery_prefix}genius-alarmline/{line_id}/transmission/state

Example: homeassistant/genius-alarmline/123456789/transmission/state

Description: Current transmission status of the alarm line

QoS: 0

Retain: true

Payload Examples

Idle state (no active transmission):

{"state": "Nothing"}

During line test start transmission:

{"state": "Line Test Start"}

During fire alarm stop transmission:

{"state": "Fire Alarm Stop"}

State Values

"Nothing" - No active transmission, all buttons available
"Line Test Start" - Line test start transmission in progress
"Line Test Stop" - Line test stop transmission in progress
"Fire Alarm Start" - Fire alarm start transmission in progress
"Fire Alarm Stop" - Fire alarm stop transmission in progress

Publishing Behavior

Published when transmission starts (state shows action type)
Published when transmission completes (state resets to "Nothing")
Published when transmission times out (state resets to "Nothing")
Re-published when MQTT connection is established
Controls button availability (buttons disabled when state ≠ "Nothing")

Home Assistant Integration

Automatically creates sensor entity
Used for button availability control via template
Displays current transmission activity
Can trigger automations based on transmission state changes
Useful for monitoring scheduled automated line tests

Global Alarm State Topic¶

Topic (Default)

smarthome/genius-gateway/alarm

Description: Global alarm state aggregated from all smoke detectors

QoS: 0

Retain: true

Payload:

Published if all devices are in standby:

{
  "isAlarming": false,
  "numAlarmingDevices": 0
}

Published when two smoke detectors are alarming (example):

{
  "isAlarming": true,
  "numAlarmingDevices": 2
}

Payload Fields

isAlarming - Global alarm state (boolean)
- true - At least one smoke detector is alarming
- false - No smoke detectors alarming
numAlarmingDevices - Number of smoke detectors currently in alarm state (integer)

Publishing Behavior

Published when an alarm starts on any smoke detector
Published when an alarm ends on any smoke detector (silenced by detector or manually via the API)
Published when all alarms are reset at once (via the end alarms API)
Published when MQTT connection is established or re-established — overwrites any stale retained message left from before a restart

Alarm state after restart

Genius Gateway does not persist the active alarm state across restarts. After a restart, isAlarming is always false and numAlarmingDevices is always 0, regardless of the state before the restart. The retained message on the broker is updated immediately on MQTT connect.

Independent of Home Assistant integration

Simple alarm publishing works independently of the Home Assistant integration. It is controlled solely by the Enable simple alarm publishing toggle and does not require HAIntegrationEnabled.

Published only if simple alarm publishing is enabled

Integration

This topic enables integration with all smart home systems that support MQTT.