MikroTik

The MikroTik integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] offers presence detection and device management for MikroTik routers, switches, and Cloud Hosted Routers (CHR) running RouterOS.

Common use cases include:

• Track connected devices for presence detection to trigger automations when family members arrive home or leave.
• Monitor router health, such as CPU, memory, and disk usage, or device temperature and power voltage.
• Get notified about RouterOS and RouterBOARD firmware updates and install them from Home Assistant.
• Enable or disable specific Ethernet or Wi-Fi interfaces, or PoE output on interfaces that support it.
• Restart or shut down the router as part of an automation.

Supported devices

This integration works with any device running MikroTik RouterOS, including physical routers and switches as well as the Cloud Hosted Router (CHR) virtual appliance, on RouterOS versions 6 and 7.

Some entities depend on hardware and firmware capabilities and are only created when the router reports the corresponding data:

• The RouterBOARD update entity is only available on physical devices that have a RouterBOARD. It doesn’t appear on the Cloud Hosted Router (CHR) or other RouterOS installations without one.
• Wireless-related entities depend on which wireless system the router uses: CAPsMAN, or the wireless, wifiwave2, or wifi package.

Prerequisites

You have to enable accessing the RouterOS API on your router to use this platform.

RouterOS uses a ping test to determine client presence, make sure you are not blocking this on the client (Windows firewall default behavior), as this will result in the provided device_tracker having the state not_home.

Terminal:

/ip service
set api disabled=no port=8728

Web Frontend:

Go to IP > Services > API and enable it.

Make sure that port 8728 or the port you choose is accessible from your network.

Configuration

To add the MikroTik device to your Home Assistant instance, use this My button:

Configuration options

The integration provides the following configuration options:

Use a certificate

To use SSL to connect to the API (via api-ssl instead of api service) further configuration is required at RouterOS side. You have to upload or generate a certificate and configure api-ssl service to use it. Here is an example of a self-signed certificate:

/certificate add common-name="Self signed demo certificate for API" days-valid=3650 name="Self signed demo certificate for API" key-usage=digital-signature,key-encipherment,tls-server,key-cert-sign,crl-sign
/certificate sign "Self signed demo certificate for API"
/ip service set api-ssl certificate="Self signed demo certificate for API"
/ip service enable api-ssl

If everything is working fine you can disable the pure api service in RouterOS:

/ip service disable api

The user privileges in RouterOS

To use this device tracker, you only need limited privileges. To enhance the security of your MikroTik device, create a “read only” group with solely API and ping test permissions and add a user to that group:

/user
group add name=homeassistant policy=read,api,test
add group=homeassistant name=homeassistant

You will be prompted to set a password for the newly created user. Depending on your RouterOS version and configuration, you might need to set a password yourself:

/user set [find username=homeassistant] password=PASSWORD

Supported functionality

The MikroTik integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following entities.

Binary Sensor

The integration creates binary sensor entities when the connected device exposes that information. Not every device supports every sensor.

• Interface: Ethernet, Wifi, Bridge connectivity

Sensors

The integration creates sensor entities when the connected device exposes that information. Not every device supports every sensor.

• Uptime
• Memory usage
• Disk usage
• CPU usage
• Device temperature
• Device power voltage

Buttons

The integration creates the following button entities:

• Restart: Reboots the MikroTik device.
• Shutdown: Powers off the MikroTik device. After a shutdown, the device is no longer reachable over the network and cannot be powered back on remotely from Home Assistant.

Select

The integration creates select entities when the connected device exposes that information. Not every device supports every select entity.

• Poe (out): Set PoE out behavior for specific interface: off, auto-on, forced-on

Switches

The integration creates switch entities when the connected device exposes that information. Not every device supports every sensor.

• Ethernet
• Wifi

Update

The integration creates the following update entities:

• RouterOS: Updates OS firmware.
• RouterBOARD: Updates BOARD firmware.

MikroTik automation examples

Automation: Notify when a family member arrives home

• Trigger: State changed
  • Entity: John’s phone
  • To: Home
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Notify when a family member arrives home"
triggers:
  - trigger: state
    entity_id: device_tracker.johns_phone
    to: "home"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "John is home."

Automation: Turn off the guest Wi-Fi at bedtime

• Trigger: Time
  • At time: 22:00:00
• Action: Turn off switch
  • Target: Guest Wi-Fi (switch.guest_wifi)

alias: "Turn off the guest Wi-Fi at bedtime"
triggers:
  - trigger: time
    at: "22:00:00"
actions:
  - action: switch.turn_off
    target:
      entity_id: switch.guest_wifi

Data updates

The MikroTik integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] the router’s RouterOS API every 10 seconds for device, interface, and system information.

Known limitations

• Presence detection only tracks clients connected to the router configured in the integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more]. If your network has multiple MikroTik devices, such as a separate wireless access point or a CAPsMAN cluster, add each device as its own integration entry to track the devices connected to it.
• The RouterBOARD update entity is only created on devices that report RouterBOARD information. It’s not available on the Cloud Hosted Router (CHR) or other installations without a RouterBOARD.
• Tracking isn’t limited to MikroTik-branded devices, but not every connected client is tracked. Wireless clients are tracked through the router’s wireless registration table, even without a DHCP lease. Wired clients are tracked from the DHCP lease table, which the integration uses when the wireless registration table returns no devices or when Force scanning using DHCP is enabled. A wired device without a DHCP lease, such as one with a manually configured static IP address, isn’t tracked.

Troubleshooting

A wired device shows as not home while it’s connected

Resolution

The integration tracks wired devices from the router’s DHCP lease table, which it uses automatically when the wireless registration table returns no devices, and always when Force scanning using DHCP is enabled. If a wired device that has a DHCP lease still shows as not_home while it’s connected, enable the Force scanning using DHCP configuration option so the lease table is always scanned, and optionally enable Enable ARP ping so the integration verifies that the device is still reachable instead of trusting the lease. A wired device without a DHCP lease, such as one with a manually configured static IP address, can’t be tracked.

Setup fails with a connection or authentication error

Resolution

1. Make sure the RouterOS API service is enabled and reachable on the configured port, as described under Prerequisites.
2. Make sure the username and password are correct and that the user has at least the read, api, and test privileges.
3. If you use the api-ssl service, make sure Verify SSL certificate matches your certificate setup.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.