vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-04-06 18:21:46 -07:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity
Files
706ef1a8a15e083d386593cfc5e430249aa6a650
NetAlertX/front/plugins/fritzbox/README.md
sebingel 706ef1a8a1 Fix incorrect connection status field mapping in Fritz!Box README 
The device information table in README.md incorrectly stated that the
Connection Status field ("Active"/"Inactive") maps to devVendor in the
devices table. In reality, watchedValue2 has no mapped_to_column entry
in config.json, meaning the value is stored only in the plugin's own
Plugins_FRITZBOX table and never promoted to the Devices table. A user
following the documentation to filter or display Connection Status via
devVendor would find no data there.

Changes:
- Correct the "Mapped To" column for Connection Status (README.md:86)
  Changed from "`devVendor` (shown as vendor field)" to "Plugin table
  only (not mapped to device fields)" to accurately reflect config.json
  behavior.

Users now have a correct expectation: Connection Status is visible in
the Fritz!Box plugin view but not in standard device columns. No
functional code was changed.
2026-04-06 07:49:16 +00:00

9.0 KiB
Executable File
Raw Blame History

Overview

The Fritz!Box plugin queries connected devices from a Fritz!Box router using the TR-064 protocol (Technical Report 064), a standardized interface for managing DSL routers and home network devices. This plugin discovers all network-connected devices and reports their MAC addresses, IP addresses, hostnames, and connection types to NetAlertX.

TR-064 is a UPnP-based protocol that provides programmatic access to Fritz!Box configuration and status information. Unlike web scraping, it offers a stable, documented API that works across Fritz!Box models.

Features

  • Device Discovery: Automatically detects all connected devices (WiFi 2.4GHz, WiFi 5GHz, Ethernet)
  • Real-time Status: Reports active connection status for each device
  • Guest WiFi Monitoring: Optional synthetic Access Point device to track guest network status
  • Flexible Filtering: Choose to report only active devices or include disconnected devices in Fritz!Box memory
  • Secure Connection: Supports both HTTP and HTTPS with configurable SSL verification

Tip

TR-064 is typically enabled by default on Fritz!Box routers. If you encounter connection issues, check that it hasn't been disabled in your Fritz!Box settings under Home Network > Network > Network Settings > Allow access for applications.

Quick Setup Guide

To set up the plugin correctly:

  1. Enable TR-064 on Fritz!Box (usually already enabled):

    • Log in to your Fritz!Box web interface (typically fritz.box or 192.168.178.1)
    • Navigate to: Home Network > Network > Network Settings
    • Ensure "Allow access for applications" is checked
    • Note: Some models show this as "Allow remote access" - enable both HTTP and HTTPS

  2. Configure Plugin in NetAlertX:

    • Head to Settings > Fritz!Box Plugin
    • Set the required settings (see below)
    • Choose run mode: schedule (recommended, runs every 5 minutes)

Required Settings

  • Fritz!Box Host (FRITZBOX_HOST): Hostname or IP address of your Fritz!Box

    • Default: fritz.box
    • Alternative: 192.168.178.1 (or your Fritz!Box's IP)

  • TR-064 Port (FRITZBOX_PORT): Port for TR-064 protocol

    • Default: 49443 (HTTPS). Use 49000 if HTTPS is disabled

  • Username (FRITZBOX_USER): Fritz!Box username

    • Can be empty for some models when accessing from local network
    • For newer models, use an admin username

  • Password (FRITZBOX_PASS): Fritz!Box password

    • Required: Your Fritz!Box admin password

Optional Settings

  • Use HTTPS (FRITZBOX_USE_TLS): Enable secure HTTPS connection (default: true)

    • Recommended for security
    • Requires port 49443 instead of 49000

  • Report Guest WiFi (FRITZBOX_REPORT_GUEST): Create Access Point device for guest WiFi (default: false)

    • When enabled, adds a synthetic "Guest WiFi Network" device to your device list
    • Device appears only when guest WiFi is active
    • Useful for monitoring guest network status

  • Guest WiFi Service (FRITZBOX_GUEST_SERVICE): Which WLANConfiguration service is the guest network (default: 3)

    • Fritz!Box typically uses 1 for 2.4GHz, 2 for 5GHz, 3 for guest WiFi
    • Only relevant when Report Guest WiFi is enabled
    • Change this if your Fritz!Box uses a non-standard configuration

  • Active Devices Only (FRITZBOX_ACTIVE_ONLY): Report only connected devices (default: true)

    • When enabled, only currently connected devices appear
    • When disabled, includes all devices stored in Fritz!Box memory (even if disconnected)

Usage

  1. Head to Settings > Fritz!Box to configure the plugin
  2. Set When to run to schedule (recommended) or once for manual testing
  3. The plugin will run every 5 minutes by default (configurable via Schedule setting)
  4. View discovered devices in the Devices page
  5. Check logs at /tmp/log/plugins/script.FRITZBOX.log for troubleshooting

Device Information Reported

The plugin reports the following information for each device:

Field Description Mapped To
MAC Address Device hardware address (normalized format) devMac
IP Address Current IPv4 address devLastIP
Hostname Device name from Fritz!Box devName
Connection Status "Active" or "Inactive" Plugin table only (not mapped to device fields)
Interface Type WiFi / LAN / Guest Network devType

Guest WiFi Feature

When Report Guest WiFi is enabled and guest WiFi is active on your Fritz!Box:

  • A synthetic device named "Guest WiFi Network" appears in your device list
  • Device Type: Access Point
  • MAC Address: Locally-administered synthetic MAC derived from Fritz!Box MAC (e.g., 02:a1:b2:c3:d4:e5)
  • Status: Only appears when guest WiFi is enabled

This allows you to:

  • Monitor when guest WiFi is active
  • Set up notifications when guest network is enabled/disabled
  • Track guest network status alongside other network devices

Note

The guest WiFi device is synthetic (not a real physical device). It's created by the plugin to represent the guest network state.

Troubleshooting

Connection Refused / Timeout Errors

Symptoms: Plugin logs show "Failed to connect to Fritz!Box" or timeout errors

Solutions:

  1. Verify Fritz!Box is reachable:

    ping fritz.box
# or
ping 192.168.178.1

  2. Check TR-064 is enabled:

    • Fritz!Box web interface > Home Network > Network > Network Settings
    • Enable "Allow access for applications"

  3. Verify correct port:

    • HTTP: Port 49000
    • HTTPS: Port 49443
    • Match Use HTTPS setting with port

  4. Check firewall rules (if NetAlertX runs in Docker):

    • Ensure container can reach Fritz!Box network
    • Use host IP instead of fritz.box if DNS resolution fails

Authentication Failed

Symptoms: "Authentication error" or "Invalid credentials"

Solutions:

  1. Verify password is correct
  2. Try leaving Username empty (some models allow this from local network)
  3. Create a dedicated user in Fritz!Box:
    • System > Fritz!Box Users > Add User
    • Grant network access permissions
  4. For newer Fritz!OS versions, ensure user has "Access from home network" permission

No Devices Found

Symptoms: Plugin runs successfully but reports 0 devices

Solutions:

  1. Check Active Devices Only setting:
    • If enabled, only connected devices appear
    • Disable to see all devices in Fritz!Box memory
  2. Verify devices are actually connected to Fritz!Box
  3. Check Fritz!Box web interface > Home Network > Mesh to see devices
  4. Increase log level to verbose and check /tmp/log/plugins/script.FRITZBOX.log

Guest WiFi Not Detected

Symptoms: Guest WiFi enabled but no Access Point device appears

Solutions:

  1. Ensure Report Guest WiFi is enabled
  2. Guest WiFi must be active (not just configured)
  3. Some Fritz!Box models don't expose guest network via TR-064
  4. Check plugin logs for "Guest WiFi active" message

Limitations

  • Active-only filtering: When FRITZBOX_ACTIVE_ONLY is enabled, the plugin only reports currently connected devices. Disconnected devices stored in Fritz!Box memory are ignored.

  • Guest WiFi synthetic device: The guest WiFi Access Point is a synthetic device created by the plugin. Its MAC address is derived from the Fritz!Box MAC and doesn't represent a physical device.

  • Model differences: Some Fritz!Box models may not expose all TR-064 services (e.g., guest WiFi detection). The plugin degrades gracefully if services are unavailable.

  • IPv6 support: Currently reports IPv4 addresses only. IPv6 support may be added in future versions.

  • Device type detection: Interface type (WiFi/LAN) is reported, but detailed device categorization (smartphone, laptop, etc.) is handled by NetAlertX's device type detection, not this plugin.

Technical Details

Protocol: TR-064 (Technical Report 064) - UPnP-based device management protocol

Library: fritzconnection >= 1.15.1

Services Used:

  • FritzHosts: Device discovery and information
  • WLANConfiguration: Guest WiFi status detection
  • DeviceInfo: Fritz!Box MAC address retrieval

Execution Schedule: Default every 5 minutes (configurable via cron syntax)

Timeout: 60 seconds (configurable via RUN_TIMEOUT)

Notes

  • Performance: TR-064 queries typically complete in under 2 seconds, even with many devices
  • Security: Passwords are stored in NetAlertX's configuration database and not logged
  • Compatibility: Tested with Fritz!Box models running Fritz!OS 7.x and 8.x
  • Dependencies: Requires fritzconnection Python library (automatically installed via requirements.txt)

Version

  • Version: 1.0.0
  • Author: NetAlertX Community
  • Release Date: January 2026
  • License: GPL-3.0

Support

For issues, questions, or feature requests:

Reference in New Issue View Git Blame Copy Permalink