Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tomaae/homeassistant-mikrotik_router
Mikrotik router integration for Home Assistant
https://github.com/tomaae/homeassistant-mikrotik_router
hacs homeassistant homeassistant-components homeassistant-integration mikrotik
Last synced: about 2 months ago
JSON representation
Mikrotik router integration for Home Assistant
- Host: GitHub
- URL: https://github.com/tomaae/homeassistant-mikrotik_router
- Owner: tomaae
- License: apache-2.0
- Created: 2019-12-01T23:45:48.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-04-25T08:20:07.000Z (8 months ago)
- Last Synced: 2024-04-25T09:32:01.863Z (8 months ago)
- Topics: hacs, homeassistant, homeassistant-components, homeassistant-integration, mikrotik
- Language: Python
- Homepage:
- Size: 3.29 MB
- Stars: 274
- Watchers: 16
- Forks: 39
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Mikrotik Router
[](https://github.com/hacs/integration)
[](https://app.lokalise.com/public/581188395e9778a6060128.17699416/)
Monitor and control your Mikrotik device from Home Assistant.
* Interfaces:
* Enable/disable interfaces
* SFP status and information
* POE status, control and information
* Monitor RX/TX traffic per interface
* Monitor device presence per interface
* IP, MAC, Link information per an interface for connected devices
* Enable/disable NAT rule switches
* Enable/disable Simple Queue switches
* Enable/disable Mangle switches
* Enable/disable Filter switches
* Monitor and control PPP users
* Monitor UPS
* Monitor GPS coordinates
* Captive Portal
* Kid Control
* Client Traffic RX/TX WAN/LAN monitoring though Accounting or Kid Control Devices (depending on RouterOS FW version)
* Device tracker for hosts in network
* System sensors (CPU, Memory, HDD, Temperature)
* Check and update RouterOS and RouterBOARD firmware
* Execute scripts
* View environment variables
* Configurable update interval
* Configurable traffic unit (bps, Kbps, Mbps, B/s, KB/s, MB/s)
* Supports monitoring of multiple mikrotik devices simultaneously
# Features
## Interfaces
Monitor and control status on each Mikrotik interface, both lan and wlan. Both physical and virtual.
## NAT
Monitor and control individual NAT rules.
More information about NAT rules can be found on [Mikrotik support page](https://help.mikrotik.com/docs/display/ROS/NAT).
## Mangle
Monitor and control individual Mangle rules.
More information about Mangle rules can be found on [Mikrotik support page](https://help.mikrotik.com/docs/display/ROS/Mangle).
## Simple Queue
Control simple queues.
More information about simple queues can be found on [Mikrotik support page](https://help.mikrotik.com/docs/display/ROS/Queues#heading-SimpleQueue).
NOTE: FastTracked packets are not processed by Simple Queues.
## PPP
Control and monitor PPP users.
## Host Tracking
Track availability of all network devices. All devices visible to Mikrotik device can be tracked, including: LAN connected devices and both Wireless and CAPsMAN from Mikrotik wireless package.
## Netwatch Tracking
Track netwatch status.
## Scripts
Execute Mikrotik Router scripts.
You can execute scripts by automatically created switches or using services.
## Kid Control
Monitor and control Kid Control.
## Client Traffic
### Client Traffic for RouterOS v6
Monitor per-IP throughput tracking based on Mikrotik Accounting.
Feature is present in Winbox IP-Accounting. Make sure that threshold is set to reasonable value to store all connections between user defined scan interval. Max value is 8192 so for piece of mind I recommend setting that value.
More information about Accounting can be found on [Mikrotik support page](https://wiki.mikrotik.com/wiki/Manual:IP/Accounting).
NOTE: Accounting does not count in FastTracked packets.
### Client Traffic for RouterOS v7+
In RouterOS v7 Accounting feature is deprecated so alternative approach for is to use
Kid Control Devices feature (IP - Kid Control - Devices).
This feature requires at least one 'kid' to be defined,
after that Mikrotik will dynamically start tracking bandwidth usage of all known devices.
Simple dummy Kid entry can be defined with
```/ip kid-control add name=Monitor mon=0s-1d tue=0s-1d wed=0s-1d thu=0s-1d fri=0s-1d sat=0s-1d sun=0s-1d```
## UPS sensor
Monitor your UPS.
## GPS sensors
Monitor your GPS coordinates.
## Update sensor
Update Mikrotik OS and firmare directly from Home Assistant.
# Install integration
This integration is distributed using [HACS](https://hacs.xyz/).
You can find it under "Integrations", named "Mikrotik Router"
Minimum requirements:
* RouterOS v6.43/v7.1
* Home Assistant 0.114.0
## Using Mikrotik development branch
If you are using development branch for mikrotik, some features may stop working due to major changes in RouterOS.
Use integration master branch instead of latest release to keep up with RouterOS beta adjustments.
## Setup integration
1. Create user for homeassistant on your mikrotik router with following permissions:
* read, write, api, reboot, policy, test
* lower permissions are supported, but it will limit functionality (read and api permissions are mandatory).
* system health sensors won't be available without write permissions. this limitation is on mikrotik side.
2. If you want to be able to execute scripts on your mikrotik router from HA, script needs to have only following policies:
* read, write
or check "Don't Require Permissions" option
3. Setup this integration for your Mikrotik device in Home Assistant via `Configuration -> Integrations -> Add -> Mikrotik Router`.
You can add this integration several times for different devices.
NOTES:
- Do not mistake "Mikrotik Router" integration with HA build-in integration named "Mikrotik".
- If you dont see "Mikrotik Router" integration, clear your browser cache.
* "Name of the integration" - Friendly name for this router
* "Host" - Use hostname or IP
* "Port" - Leave at 0 for defaults
## Configuration
First options page:
* "Scan interval" - Scan/refresh time in seconds. HA needs to be reloaded for scan interval change to be applied
* "Unit of measurement" - Traffic sensor measurement (bps, Kbps, Mbps, B/s, KB/s, MB/s)
* "Show client MAC and IP on interfaces" - Display connected IP and MAC address for devices connected to ports on router
* "Track network devices timeout" - Tracked devices will be marked as away after timeout (does not apply to Mikrotik wireless and caps-man)
* "Zone for device tracker" - Add new tracked devices to a specified Home Assistant zone
Second options page:
Select sensors you want to use in Home Assistant.
# Development
## Translation
To help out with the translation you need an account on Lokalise, the easiest way to get one is to [click here](https://lokalise.com/login/) then select "Log in with GitHub".
After you have created your account [click here to join Mikrotik Router project on Lokalise](https://app.lokalise.com/public/581188395e9778a6060128.17699416/).
If you want to add translations for a language that is not listed please [open a Feature request](https://github.com/tomaae/homeassistant-mikrotik_router/issues/new?labels=enhancement&title=%5BLokalise%5D%20Add%20new%20translations%20language).
## Diagnostics
Download diagnostics data for investigation:
## Enabling debug
To enable debug for Mikrotik router integration, add following to your configuration.yaml:
```
logger:
default: info
logs:
custom_components.mikrotik_router: debug
```