.. fritzconnection documentation master file, created by
   sphinx-quickstart on Tue Mar 19 10:09:48 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.


fritzconnection documentation
=============================


fritzconnection is a `Python <https://www.python.org/>`_ library to communicate with `FRITZ!Box <https://en.avm.de/produkte/fritzbox/>`_ routers (and partly other devices, like repeaters) by the TR-064 protocol, the AHA-HTTP-Interface and also provides call-monitoring. This allows to read status-information from the router, read and change configuration settings and state, interact with smart-home-devices and monitor realtime phone calls.

.. note::
   The Python Library "fritzconnection" is neither related nor supported by "FRITZ! GmbH"". Furthermore  terms like i.e. "FRITZ!" or "Fritz!Box" (and more variants) are trademarks of `FRITZ! GmbH <https://fritz.com/policies/legal-notice/>`_.


The available features are depending on the router-model and the according system software. Using fritzconnection is as easy as: ::

    from fritzconnection import FritzConnection

    fc = FritzConnection(address="192.168.178.1", user="user", password="pw")
    print(fc)  # print router model information

    # tr-064 interface: reconnect for a new ip
    fc.call_action("WANIPConn1", "ForceTermination")
    fc.reconnect()  # do the same with a shortcut

    # http interface: get history data from a device with given 'ain'
    fc.call_http("getbasicdevicestats", "12345 7891011")

FritzConnection provides two basic commands to communicate with the router APIs: *call_action()* for the TR-064-Interface and *call_http()* for the (AHA)-HTTP-Interface. Both APIs can be used on the same FritzConnection instance side by side. With the `call_action()` and `call_http()` methods every service/action-combination and commands documented by the `FRITZ! support-page (Apps/TR-064, HTTP) <https://fritz.com/pages/schnittstellen/>`_ can get executed.

- ``call_action()`` expects a ``TR-064`` service- and an action-name (and optional arguments). In general FritzConnection can execute every service and action provided by the (model-specific) API as documented by AVM. For i.e. this can be network settings, status informations, access to home automation devices and much more. The *call_action()* method returns the response from the router as a dictionary with the values already converted to the matching Python datatypes.

- ``call_http()`` expects a command for the ``http-interface`` like "getbasicdevicestats" and, depending on the command, additional arguments like a device "ain" (identifier). A call to the method returns a dictionary with the *content-type*, the *encoding* and the *response* data of the http-response. The content-type of the response-data is typical "text/plain" or "text/xml" and may need further processing.

The fritzconnection-package comes with a library to make some common tasks easier and can also serve as example code. For a detailed overview refer to :doc:`sources/getting_started` and the documentation of the :doc:`library <sources/library_modules>`.



.. toctree::
   :maxdepth: 1
   :caption: Contents:


   sources/installation
   sources/getting_started
   sources/fritzconnection_api
   sources/library_modules
   sources/call_monitoring
   sources/further_reading
   sources/version_history
   sources/authors
   sources/license