DOCSEARCHbyAlgolia
Submit Docs

fritzconnection Documentation

repository·master·Indexed 19 days ago

https://github.com/kbr/fritzconnection

A Python interface for communicating with AVM Fritz!Box routers. It provides access to the TR-064 protocol via call_action() and the (AHA)-HTTP-Interface via call_http() for network management, status monitoring, and home automation. The library includes the FritzMonitor module for real-time call monitoring via socket connections and a CLI tool for inspecting model-specific TR-064 APIs.

Tokens
22.6K
Snippets
90
Records
112
Agent score
61%

What's inside fritzconnection

  2. How call_action() and call_http() work together

    master
    A single FritzConnection instance can use both the TR-064 (call_action) and the HTTP (call_http) interfaces side-by-side. This allows you to combine different communication methods to achieve complex automation or monitoring tasks on the same router.

  3. How TR-064 services, actions, and arguments work

    master

    The TR-064 protocol is organized into a hierarchy:

    1. Services: Collections of related actions (e.g., WLANConfiguration1, DeviceInfo1). Service names often end in a numeric value to distinguish between multiple instances (like different WLAN bands).
    2. Actions: Specific operations within a service (e.g., GetInfo, SetEnable).
    3. Arguments: Data sent to (in direction) or received from (out direction) the router.

    Note that services starting with X_AVM are AVM-specific extensions and are not part of the standard TR-064 protocol.

  4. Manage Home Automation devices with FritzHomeAutomation

    master

    The FritzHomeAutomation module uses the HomeAutomationDevice class to represent the properties and state of individual devices.

    To interact with devices, use:

    • get_homeautomation_device(): To get a specific device.
    • get_homeautomation_devices(): To get all devices.
    • get_device_information_list(): To get a list of device information (replaces the deprecated device_informations()).
    # Get all devices
devices = automation.get_homeautomation_devices()

# Get info for a specific device
info = automation.get_device_information_list()

  5. Optimize performance by reusing FritzConnection instances

    master

    Creating a FritzConnection instance is an I/O-heavy operation because it inspects the Fritz!Box API to discover available services. To avoid repeated slow inspections, you should create a single FritzConnection instance and pass it to the constructors of specialized library modules (like FritzWLAN or FritzHomeAutomation).

    from fritzconnection import FritzConnection
from fritzconnection.lib.fritzhomeauto import FritzHomeAutomation
from fritzconnection.lib.fritzwlan import FritzWLAN

# Create the base connection once
fc = FritzConnection(address='192.168.178.1', password=<password>)

# Reuse the instance for different modules
fw = FritzWLAN(fc)
print(fw.total_host_number)

fh = FritzHomeAutomation(fc)

  6. Use long qualified service names for multiple services

    master

    To call actions on specific instances of a service (e.g., when multiple WAN connections exist), use long qualified names in the format servicename:index.

    If the extension (e.g., :2) is omitted, fritzconnection defaults to :1 for backward compatibility.

    connection = FritzConnection()
# Calling a specific service instance
info = connection.call_action('WANIPConnection:2', 'GetInfo')

  8. Quickstart with fritzconnection

    master

    To use fritzconnection, instantiate a FritzConnection object with the router's IP address, username, and password. This object provides access to both the TR-064 and HTTP interfaces for interacting with FRITZ!Box routers.

    Available features depend on your specific router model and system software.

    from fritzconnection import FritzConnection

# Initialize connection
fc = FritzConnection(address="192.168.178.1", user="user", password="pw")

# Print router model information
print(fc)

  10. Implement real-time call monitoring with FritzMonitor

    master

    The fritzmonitor module provides real-time information about incoming and outgoing phone calls via a separate socket connection (not TR-064).

    To use it in your code:

    1. Use FritzMonitor as a context manager to ensure the monitor thread is shut down correctly when finished.
    2. Call .start() on the monitor instance to begin the connection and receive a queue.Queue object.
    3. Retrieve events from the queue. Events are returned as string types in the AVM format.
    4. Monitor the monitor.is_alive property to detect if the connection to the router has failed.
    import queue
from fritzconnection.core.fritzmonitor import FritzMonitor

def process_events(monitor, event_queue, healthcheck_interval=10):
    while True:
        try:
            # Pull events from the queue
            event = event_queue.get(timeout=healthcheck_interval)
        except queue.Empty:
            # Check if the connection is still alive if no events arrive
            if not monitor.is_alive:
                raise OSError("Error: fritzmonitor connection failed")
        else:
            # Process the AVM string event here
            print(event)

def main():
    try:
        # Use as a context manager to ensure thread shutdown
        with FritzMonitor(address='192.168.178.1') as monitor:
            event_queue = monitor.start()
            process_events(monitor, event_queue)
    except (OSError, KeyboardInterrupt) as err:
        print(err)

if __name__ == "__main__":
    main()