RouterOS Home Assistant MQTT Integration Tool WEB

3rd party tools
1

RouterOS Home Assistant MQTT Integration Tool

Overview

A powerful web-based generator tool for easily integrating MikroTik RouterOS devices with Home Assistant via MQTT protocol. This tool generates auto-discovery compatible scripts that seamlessly expose RouterOS metrics as Home Assistant entities.

Key Features:

  • :bullseye: Web-based configuration interface with real-time preview
  • :bar_chart: Support for 30+ sensor types (temperature, CPU, memory, traffic, uptime, etc.)
  • :radio_button: Button and Switch control support with full MQTT command handling
  • :house: Full Home Assistant MQTT Discovery protocol compatibility
  • :gear: Custom expression support for advanced metrics
  • :counterclockwise_arrows_button: Automatic entity discovery in Home Assistant
  • :shield: Built-in duplicate execution prevention
  • :bug: Complete debugging tools and troubleshooting guides

Supported Sensor Types

System Sensors

  • uptime - System uptime in seconds
  • board-name - Device model identification
  • identity - RouterOS system identity
  • free-memory - Available RAM (MB)
  • total-memory - Total installed RAM (MB)
  • cpu-load - CPU usage percentage
  • cpu-count - Number of CPU cores
  • temperature - System temperature (RB devices only)
  • cpu-temperature - CPU temperature (RB devices only)
  • voltage - System voltage reading (RB devices only)

Storage Sensors

  • write-sect-total - Total write sectors (if supported)
  • write-sect-since-reboot - Write sectors since last boot
  • bad-blocks - Number of bad blocks detected

Network Sensors

  • interface-count - Number of network interfaces
  • bridge-count - Number of bridge interfaces
  • gre-count - Number of GRE tunnels
  • vlan-count - Number of VLAN interfaces
  • ether-count - Number of Ethernet ports
  • wireless-count - Number of wireless interfaces

Interface Traffic Monitoring

  • rx-bits-per-second - Inbound traffic (bps)
  • tx-bits-per-second - Outbound traffic (bps)
  • rx-drops - Inbound dropped packets
  • tx-drops - Outbound dropped packets
  • rx-errors - Inbound transmission errors
  • tx-errors - Outbound transmission errors

Control Types

  • button - Momentary action triggers
  • switch - Stateful ON/OFF controls

Quick Start Guide

Prerequisites

  • RouterOS v7.1 or later with IoT package installed (iot.npk)
  • Home Assistant with MQTT integration configured
  • Mosquitto Broker or compatible MQTT broker

Step 1: Configure MQTT Broker in RouterOS

/iot mqtt brokers add \
    name=homeassistant \
    address=<YOUR_BROKER_IP> \
    port=1883 \
    username=<USERNAME> \
    password=<PASSWORD> \
    client-id=mikrotik-<SERIAL>

Step 2: Select Sensors

  1. Visit the web-based tool
  2. Choose your device model (hAP ax², RB4011, etc.)
  3. Select desired sensors from each category
  4. Configure Home Assistant Discovery Prefix (default: "homeassistant")

Step 3: Generate Main Script

  1. Click the MAIN SCRIPT tab
  2. Copy the generated RouterOS script
  3. Open Terminal in RouterOS WebUI (System → Terminals)
  4. Paste and execute the script
  5. Script will auto-configure and start publishing metrics

Step 4: Generate Subscription Scripts (for Button/Switch)

  1. If you selected Button or Switch controls:
  2. Go to SUBSCRIPTION tab
  3. Copy subscription commands
  4. Execute in RouterOS Terminal
  5. Subscriptions enable MQTT command handling

Step 5: Verify in Home Assistant

  1. Open Home Assistant → Settings → Devices & Services → MQTT
  2. New devices should appear under "mikrotik-{serial}"
  3. All selected sensors will be auto-discovered and available
  4. Configure automations and use sensors as needed

Step 6: Schedule Regular Updates (Optional)

/system scheduler add \
    name=mqtt-update \
    interval=30s \
    on-event="/system script run mqtt-publish"

Feature Details

Auto-Discovery

The tool generates Home Assistant MQTT Discovery messages automatically. On first execution:

  • Creates device entry in HA with manufacturer info, model, and firmware version
  • Registers all selected sensors as individual entities
  • Configures proper unit of measurement and device classes
  • Sets up state topics for real-time updates

Main Script

Publishes selected sensor metrics at intervals:

  • Uses global variables to avoid re-initialization
  • Implements duplicate-execution prevention via script environment storage
  • Collects all metrics and publishes via MQTT
  • Configurable interval via scheduler (recommended: 5-30 seconds)

Subscription Script (Button/Switch)

Enables two-way communication:

  • Button: Triggers actions on MQTT PRESS events
  • Switch: Publishes state to /state topic, listens for ON/OFF commands
  • Full logging of received commands
  • Extensible event handlers with TODO placeholders

Custom Expressions

Advanced users can define custom expressions:

[/ip address print as-value where interface=ether1 stats]

Expressions are pre-evaluated and cached for performance.

Debugging and Troubleshooting

Check Broker Connection

/iot mqtt brokers print

Look for connected=yes status.

View Active Subscriptions

/iot mqtt subscriptions print detail

Verify topic patterns match your configuration.

Debug Mode - Monitor All MQTT Traffic

/iot mqtt subscriptions add broker=homeassistant \
    topic="homeassistant/#" \
    on-message=":log info (\"Topic: \" . \$topic . \" | Data: \" . \$data)"

Then check logs: /log print where topics~"mqtt"

Remove Debug Subscription

/iot mqtt subscriptions remove [find topic="homeassistant/#"]

Force Configuration Refresh

Reset configuration tracking to force full re-discovery:

/system script environment remove [find name="configPublished"]

Execute main script again - it will re-send all discovery messages.

Advanced Configuration

Custom Sensor Expressions

Instead of predefined metrics, use RouterOS commands:

# Get highest CPU core temperature
[/system health print as-value count=1 | grep "temperature"]

Multiple Device Support

Generate separate scripts for different RouterOS devices:

  • Use unique device names in Discovery Prefix
  • Each device maintains independent script environments
  • All devices publish to same MQTT broker

Filtering by Interface

Monitor specific interface traffic:

[/interface ethernet print as-value where name=ether1]

Common Issues & Solutions

Issue: Entities Not Appearing in Home Assistant

Solution:

  1. Verify MQTT broker is connected: /iot mqtt brokers print
  2. Check HA MQTT integration is enabled in Settings → Devices & Services
  3. Review HA MQTT logs for subscription errors
  4. Reset configuration: /system script environment remove [find name="configPublished"]
  5. Execute main script again

Issue: Metrics Not Updating

Solution:

  1. Verify scheduler is active: /system scheduler print
  2. Check script logs: /log print where topics~"publish"
  3. Ensure broker connection is stable
  4. Increase scheduler frequency temporarily for testing

Issue: Button/Switch Commands Not Working

Solution:

  1. Verify subscriptions exist: /iot mqtt subscriptions print
  2. Test subscription with debug mode (see Debugging section)
  3. Ensure on-message script has proper syntax
  4. Check /log for error messages: /log print

Issue: High CPU Usage

Solution:

  1. Reduce scheduler frequency (increase interval to 30-60 seconds)
  2. Select fewer sensors to publish
  3. Use simpler expressions (avoid complex command chains)
  4. Check for infinite loops in custom expressions

Important Notes

Device Compatibility

  • temperature and cpu-temperature are separate metrics (model dependent)
  • Temperature, Bad Blocks, Voltage sensors only work on RB hardware
  • write-sect-* sensors may not be available on all models
  • Verify sensor availability on your device before configuration

Performance Considerations

  • Publication interval: 5-30 seconds (recommended)
  • Faster intervals increase CPU usage and MQTT traffic
  • Each sensor requires one MQTT publish operation
  • Disable unused sensors to improve performance

Duplicate Execution Prevention

  • Script tracks configuration hash in script environment
  • If configuration unchanged, skip discovery republish
  • Automatic on each execution
  • Manual reset available via script environment removal

Security

  • Always use MQTT broker with authentication
  • Consider using TLS/SSL for remote MQTT connections
  • Protect RouterOS SSH access
  • Regularly update RouterOS firmware for security patches

Tool URL

Access the web-based configuration tool and start generating your RouterOS MQTT integration scripts today!

http://www.routeros.cn/tool/iot.php

License & Attribution

This tool generates RouterOS scripts compatible with Home Assistant MQTT Discovery protocol. All generated scripts are yours to use and modify freely.

The above instructions and the tool itself are heavily customized using AI tools, so there may be omissions in the explanations. All functions of the tool itself have been thoroughly tested.