Release 1.0.0a1 AVM › pdf › fritzctl › master › fritzctl.pdf · Working with Homeautomation...
Transcript of Release 1.0.0a1 AVM › pdf › fritzctl › master › fritzctl.pdf · Working with Homeautomation...
fritzctl DocumentationRelease 1.0.0a1
AVM
July 15, 2016
Contents
1 Guides 31.1 Getting Started with fritzctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Contributing to fritzctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2 fritzctl - Python Client Library for the AVM TR64 API 112.1 Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 Root Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3 Indices and tables 35
Python Module Index 37
i
ii
fritzctl Documentation, Release 1.0.0a1
Contents:
Contents 1
fritzctl Documentation, Release 1.0.0a1
2 Contents
CHAPTER 1
Guides
1.1 Getting Started with fritzctl
1.1.1 Installation via pip
The recommended way of installing fritzctl is via pip
$ pip install fritzctl
If you do not have pip installed, you can find how to install it in the documentation.
1.1.2 Manual Installation
Due to its complexity, fritzctl needs multiple steps to be installed successfully.
Requirements
The fritzctl module needs the latest Python 2.7.x installed, see the Official Python Website and select the fileappropriate for your system.
Note: This module currently does not work with Python 3.x, so be sure to click on Download Python 2.7.x.
In addition, you will also need to install both the requests and simpletr64 modules. See Requests for how toinstall requests and simpletr64 for how to install lxml.
Installing fritzctl itself
Installing fritzctl itself is fairly easy, simply download the latest release, unzip to a directory of your choice andopen a terminal where you extracted your archive.
If you completed these steps, execute the following command:
$ python setup.py install
Note that when running under linux, you may need to run this command as root:
$ sudo python setup.py install
3
fritzctl Documentation, Release 1.0.0a1
You can verify that you installed fritzctl correctly by opening a python interactive interpreter and running:
>>> import fritzctl
If you get an ImportError, you didn’t install fritzctl correctly.
1.1.3 Quickstart
All of the examples in this section assume that you have created an account called fritzctl with the passwordmypassword on your local FRITZ!Box and that it is accessable via http://fritz.box/. The test account usedin this tutorial needs the Smart Home, Calls and User Interface permissions to work properly.
Also, this Guide uses a switchable FRITZ!Powerline 546E to demonstrate the Homeauto API and Homeplug API.
If you have a different setup, simply change the appropriate parameters.
Creating a Session
If you want to follow along with the tutorial, you should run all these examples in the same interactive Python session.
But first, we should create a Session()
>>> import fritzctl>>> mysession = fritzctl.Session("fritz.box","fritzctl","mypassword") # Note that the URL is without both http:// and www.
If do not have a switchable Socket/Powerline for testing, you should still read at least some of the steps so you can geta feel for how this API works.
Alternatively, you can skip to the next Subsection about the Device Information API.
Getting an API
There are muliple ways to create API Objects to interface with the server, but in this quick guide we will only look atthe Object-Oriented APIs.
We will start with the Homeautomation API:
>>> api = mysession.getOOAPI("avm_homeauto")# Alternatively:>>> api = mysession.getOOAPI("urn:dslforum-org:service:X_AVM-DE_Homeauto:1")
This will give us an instance of fritzctl.ooapi.avm_homeauto.API_avm_homeauto to play with. Youcan find a full list of the features of this API by clicking on the linked class name.
Working with the API
There are also multiple ways to get to a specific device. In particular, you can list all devices and pick them yourselfor request it by its index or AIN/MAC Address.
In this scenario, we will presume that there is only one Homeautomation Device connected:
>>> mydevice = api.getDeviceByIndex(0)# Or:>>> mydevice = api.getDeviceList()[0]# Or:>>> mydevice = api.getDeviceByAIN("12:34:56:78:90:AB")
4 Chapter 1. Guides
fritzctl Documentation, Release 1.0.0a1
You can find the full API docs here.
Working with Homeautomation Devices
Now that we have the HomeautoDevice(), we should check if it actually is the device we expected and thenmanipulate it:
>>> mydevice.productname"FRITZ!Powerline 546E"# If you get something different, try the above section again but with the zero replaced by a one instead>>> mydevice.name # Can be changed in the userinterface, so may differ"FRITZ!Powerline 546E">>> mydevice.ain # Will be different but in the same format"12:34:56:78:90:AB"
Seems that we got the right device, now we can check what features it has:
>>> mydevice.energy_flagTrue>>> mydevice.temp_flagFalse>>> mydevice.switch_flagTrue>>> mydevice.hkr_flagFalse>>> mydevice.energy_validTrue>>> mydevice.switch_validTrue
We now know that this device can read power flowing through it via a multimeter and that we can switch it.
Switching the Switch
After we have all these different objects and flags, we can now safely toggle the switch:
>>> mydevice.switch_stateFalse>>> mydevice.switch_state = True# Should turn on the socket>>> mydevice.switch_stateTrue# Alternatively toggle the switch:>>> mydevice.switch_state = "toggle">>> mydevice.switch_stateFalse
You can also switch the device directly from the API:
>>> api.switchByAIN("12:34:56:78:90:AB",True)
Energy Measurements
As we have seen, this device also supports measuring the energy flowing through it.
Now, we will measure the energy flow currently measured:
1.1. Getting Started with fritzctl 5
fritzctl Documentation, Release 1.0.0a1
>>> mydevice.energy_power0.0>>> mydevice.energy_energy0.0
You may think that this library doesn’t work correctly, but this is intended behaviour.
That there currently are zero watts flowing through the device makes sense, because it is turned off and the total energyis only displayed in 1-Wh increments due to how the API works.
Now, let us switch the switch back on:
>>> mydevice.switch_state = "toggle"# wait ~20 seconds to be safe>>> mydevice.energy_power # depends highly on connected device60.0>>> mydevice.energy_energy # 1min in theory after the switch is turned on, if 60 watts are constantly used1.0
Normally, we would have to refresh our data, but toggling the switch automatically reloads it.
If you want to manually update your data, simply call reloadData() and it will reload the data in-place.
More Variables
There are a lot more variables available on these Devices, but it would take to long to describethem all here. If you want to use these, you should take a look at their API Documentation<fritzctl.ooapi.avm_homeauto.HomeautoDevice() where you can find them all in the constructor.
1.1.4 Device Information API
As the second example, we will take a look at the fritzctl.ooapi.general_deviceinfo.API_general_deviceinfo()API.
Preparation
You probably already know the procedure from above, but here is it again:
$ python...>>> import fritzctl>>> s = fritzctl.Session("fritz.box","fritzctl","mypassword")>>> api = s.getOOAPI("general_deviceinfo")
Getting our Device
It should be noted that this API is not for general Devices, it only gives information about the FRITZ!Box itself.
Since we got our API in the last step, now we can get our device info:
>>> devinfo = api.getDeviceInfo()
Quick and easy, as it should be.
6 Chapter 1. Guides
fritzctl Documentation, Release 1.0.0a1
Static Device Variables
These are all static Variables, but you can still call reloadData() on the object we got in the last step to reload thedata.
Static Variables:
>>> devinfo.manufacturer"AVM">>> devinfo.manufacturerOUI"00040E">>> devinfo.modelname"FRITZ!Box 7580">>> devinfo.description# like the modelname, but more verbose>>> devinfo.productclass"FRITZ!Box">>> devinfo.hwversion"FRITZ!Box 7580">>> devinfo.specversion"1.0"
Of course, you probably knew most of those variables before, but this can helpful if e.g. you need to detect a specificmodel and then run some special compatibility code.
Dynamic Device Variables
These are similiar to the variables above, but they are often different for every box and some will change rapidly:
>>> devinfo.serialnumber# 12 chars of presumably hex and probably unique because 12**16=a lot>>> devinfo.swversion # will probably be higher than what I have"153.06.51">>> devinfo.provisioningcode>>> # No output if you have a direct-bought box with an open provider>>> # Alternatively 4 groups of 3-digit numbers seperated by dots should be output>>> devinfo.uptime # can be almost any number, in seconds20018>>> devinfo.devicelog# Lots of text
These are all the variables supported by this API, but you can still take a look at the documentation.
1.1.5 Further References
I highly recommend you to take a look at the general API Documentation for lots of information about almostall features.
You should also take a look at the official TR64 AVM API Documentation, the site itself is only available in German,but the PDFs are in English. The overview page can be found on the official Website and an overview about everyservice supported can be found here.
You can also look at the official simpletr64 Documentation for more information about the underlying module. Itshould be noted that I have found simpletr64’s FRITZ!Box helper classes not to work on my system.
1.1. Getting Started with fritzctl 7
fritzctl Documentation, Release 1.0.0a1
1.2 Contributing to fritzctl
Since the underlying API changes from time to time, it may be necessary to implement new API classes and bugfixesfor existing ones.
Also, because of the sheer amount of APIs, it is not possible for me alone to implement all Service Types by myself.
This is why I am writing this guide, aiming to allow future developers and maintainers to understand the designconcepts used in this library.
1.2.1 Naming Conventions
Almost all Variable names should be written in camelCase with the first letter lowercase, except for ClassNames.
Constants and global Mappings should be written in CAPSLOCK.
This is as far as I know the only deviation from PEP 8, everywhere else you should strictly follow this PEP whenwriting code for fritzctl.
1.2.2 Writing OO Wrapper Classes
Naming
When writing Object-Oriented Wrapper Classes, there are several things to be aware of.
First, when choosing the name, the module should be called fritzctl.ooapi.<category>[_<subcategory>]_<name>where subcategory is optional. Category may be one of avm, general and net and name should be derived from theService Type URN.
As an example, the Service Type URN urn:dslforum-org:service:WANIPConnection:1 translates tocategory net, subcategory wan and name ipconnection, resulting in the final name net_wan_ipconnection.
Some names may be shortened, e.g. config is generally shortened to cfg.
In most of the cases, it will not be necessary to name a Service Type, as it will probably already have entries infritzctl.session.NAME_TO_URN .
Now, we need to create the class name, which is simply API_<name> in the corresponding module. Note that theremay only be one API Class per module.
When you successfully built a new name, make sure to register it in both fritzctl.session.NAME_TO_URNand fritzctl.ooapi.OO_APIS and the corresponding documentation.
Writing the class
After you have created your new module and empty class, you will need to make sure that the base class isfritzctl.ooapi.base.API_base and add the appropriate imports.
You should not need to override the __init__ method as all needed instance variables are already set.
It is also highly recommended to take a look at e.g. the fritzctl.ooapi.avm_homeauto.API_avm_homeauto()class and similiar to get a feeling of how they work.
If you need no additional classes for e.g. devices you should have everything you need to know.
8 Chapter 1. Guides
fritzctl Documentation, Release 1.0.0a1
Writing Helper/Device classes
If you are for example writing an API for a new Homeautomation API, you will need write additional device classes.
In this example, we assume that the API name is avm_homeautomation and the API class is calledAPI_avm_homeautomation.
Using the names above, we can derive the device class name to be HomeautomationDevice() orHomeautoDevice(). You can choose the name freely, but it is recommended to always end it with either De-vice or Info or Config, depending on what type of class you are creating.
Look at the fritzctl.ooapi.avm_homeauto.HomeautoDevice() class for an example of how to writethese classes.
It should be noted that the index parameter is only there for legacy purposes and is not needed in new classes.
You can often copy and paste the docstrings from already existing modules and change the names of mentioned classesto save on typing the same docstring again.
1.2.3 Releasing
When releasing a new version, you will need to open the setup.py file and change the version.
When changing the version, you should change the last digit after the a only for minor bugfixes immediately after therelease, for when you discover a critical bug not noticed during testing.
The 3rd digit, the so called bugfix version, should be changed when fixing bugs and will often stay at zero.
The 2nd digit, the so called minor version, should be changed when new features are added that are mostly backwardscompatible, e.g. adding a new service type plus wrapper classes.
The 2st digit, the so called major version, should only be changed when new backwards-incompatible changes havebeen made or after introducing a completely new system and corresponding API.
After changing the version, you should make sure that:
• all documentation has been written, run make coverage and check in _build/coverage/python.txtand make sure that every module is fully documented
• all new features are working as intended, simply run each feature once and stress-test important features
• all debug outputs are removed
• most critical bugs are fixed
• the code runs on all supported platforms
You will also need to create a file called .pypirc in your home directory with the following contents:
[distutils]index-servers =
pypi
[pypi]username:usernamepassword:password
The password and username should be changed to a valid combination.
After you have triple-checked that everything works, you can simply run this command to publish to PyPI:
$ sudo python setup.py install sdist bdist bdist_wheel register upload
1.2. Contributing to fritzctl 9
fritzctl Documentation, Release 1.0.0a1
This command has been tested under Ubuntu 16.04 and will need to be modified to work under windows.
If the process fails during the upload step, simply re-run the command without the register step.
After having released, you should try installing the package on another machine that does not have fritzctl installed,just to see if you missed an added dependency or have another bug that only shows itself on another system.
10 Chapter 1. Guides
CHAPTER 2
fritzctl - Python Client Library for the AVM TR64 API
2.1 Submodules
2.1.1 fritzctl.session - TR64 Session and Device Management
fritzctl.session.NAME_TO_URNAllows for conversion between user-friendly names and internal Service Type URNs.
All service types that could be found in the file /tr64desc.xml on the 7th of July 2016 with a FRITZ!Box7580 are supported.
The naming scheme is quite simple, all AVM specific names begin with avm_, all general-purpose namesbegin with general_ and all network-related names begin with net_. For net_* names, there are threesub-categories: net_wan_, net_lan_ and net_wlan_.
See also:
See the docs for getAPI() and getOOAPI() for more information about how to use these names.
Table of Name -> URN mapping:
Name URN OO-Supportavm_homeauto urn:dslforum-org:service:X_AVM-DE_Homeauto:1 Yesavm_myfritz urn:dslforum-org:service:X_AVM-DE_MyFritz:1 Noavm_remoteaccess urn:dslforum-org:service:X_AVM-DE_RemoteAccess:1 Noavm_storage urn:dslforum-org:service:X_AVM-DE_Storage:1 Noavm_speedtest urn:dslforum-org:service:X_AVM-DE_Speedtest:1 Noavm_appsetup urn:dslforum-org:service:X_AVM-DE_AppSetup:1 Noavm_dect urn:dslforum-org:service:X_AVM-DE_Dect:1 Noavm_upnp urn:dslforum-org:service:X_AVM-DE_UPnP:1 Noavm_ontel urn:dslforum-org:service:X_AVM-DE_OnTel:1 Noavm_filelinks urn:dslforum-org:service:X_AVM-DE_Filelinks:1 Noavm_webdavclient urn:dslforum-org:service:X_AVM-DE_WebDAVClient:1 Noavm_homeplug urn:dslforum-org:service:X_AVM-DE_Homeplug:1 Yesavm_tam urn:dslforum-org:service:X_AVM-DE_TAM:1 Nogeneral_time urn:dslforum-org:service:Time:1 Yesgeneral_deviceinfo urn:dslforum-org:service:DeviceInfo:1 Yesgeneral_deviceconfig urn:dslforum-org:service:DeviceConfig:1 Yesgeneral_hosts urn:dslforum-org:service:Hosts:1 Yesgeneral_userinterface urn:dslforum-org:service:UserInterface:1 No
Continued on next page
11
fritzctl Documentation, Release 1.0.0a1
Table 2.1 – continued from previous pageName URN OO-Supportgeneral_managementserver urn:dslforum-org:service:ManagementServer:1 Nogeneral_layer3fwd urn:dslforum-org:service:Layer3Forwarding:1 Nogeneral_x_voip urn:dslforum-org:service:X_VoIP:1 Nonet_wan_dsllinkconfig urn:dslforum-org:service:WANDSLLinkConfig:1 Nonet_wan_ipconnection urn:dslforum-org:service:WANIPConnection:1 Nonet_wan_commoninterfacecfg urn:dslforum-org:service:WANCommonInterfaceConfig:1 Nonet_wan_dslinterfacecfg urn:dslforum-org:service:WANDSLInterfaceConfig:1 Nonet_wan_pppconnection urn:dslforum-org:service:WANPPPConnection:1 Nonet_wan_ethernetlinkcfg urn:dslforum-org:service:WANEthernetLinkConfig:1 Nonet_lan_configsecurity urn:dslforum-org:service:LANConfigSecurity:1 Nonet_lan_hostcfgmanagement urn:dslforum-org:service:LANHostConfigManagement:1 Nonet_lan_ethernetinterfacecfg urn:dslforum-org:service:LANEthernetInterfaceConfig:1 Nonet_wlan_2.4ghz urn:dslforum-org:service:WLANConfiguration:1 Yesnet_wlan_2nd urn:dslforum-org:service:WLANConfiguration:2 Yesnet_wlan_3rd urn:dslforum-org:service:WLANConfiguration:3 Yes
As you may have noticed, there are three WLANConfiguration URNs, this is because they correspond to thenormal wifi, 5ghz wifi and the guest network.
The first URN always corresponds to the 2.4ghz network, but the second depends on what networks are active.If there is an 5ghz network, it will always be the second network and the guest network will be the third network.If there is no 5ghz network, the second network will be the guest network.
You may be able to make an educated guess about which network is which by querying certain parameters ofeach network.
See the fritzctl.ooapi package for specific OO APIs, as indicated in the table.
class fritzctl.session.Session(server=None, user=None, pwd=None, port=49000, au-thcheck=True)
Session object storing the credentials and context.
Parameters
• server (str) – Server to connect to, e.g. fritz.box
• user (str) – Optional Username for authentification
• pwd (str) – Optional Password for authentification
• port (int) – Port to use when connecting, defaults to 49000
• authcheck (bool) – If the credentials should be checked, simply requests thegeneral_deviceinfo API.
Instance Variables:
Variables
• server – Server connected to
• user – Username for authentification
• pwd – Password for authentification
• device – simpletr64.DeviceTR64() Instance used for managing authentification
• urns – List of URNs found on the server, can be used for debugging
12 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
execute(*args, **kwargs)Executes the given action on the server.
This method simply passes through all parameters to the internal simpletr64.DeviceTR64() in-stance.
getAPI(name)Requests an API object by either URN or user-friendly name.
See NAME_TO_URN for a list of user-friendly names.
Parameters name (str) – API Name, either Service Type URN or user-friendly name
Returns A DynamicAPI() instance ready-for-use
Raises ValueError – if the URN is not known or is not in NAME_TO_URN
getOOAPI(name)Requests an Object-Oriented API by either URN or user-friendly name.
See NAME_TO_URN for a list of user-friendly names.
Note that the methods available vary depending on what API you requested, see the appropriate module in:py:module‘fritzctl.ooapi‘ for specific informations.
Parameters name (str) – API Name, either Service Type URN or user-friendly name
Returns An Object-oriented API interface
Return type Instance of a subclass of fritzctl.ooapi.base.API_base()‘
2.1.2 fritzctl.dynapi - Dynamic API Classes
class fritzctl.dynapi.DynamicAPI(session, urn)Dynamic API class that automagically generates methods for calling actions.
This class will generate API methods based on the device definitions found in the session. You may passarguments to the auto-generated methods via keyword arguments only.
If you need to pass an argument that is not a valid Python identifier, use this trick:api.MyAPIMethod(**{"Some-Strange-Name":"Value"}).
Parameters
• session (Session) – Session() object used for requests
• urn (str) – Service Type URN to be wrapped by this instance
Variables
• session – Stored session object
• urn – Stored URN for requests
• url – Action URL for requests, specific to the URN
callAPI(action, *args, **kwargs)Fallback to use if the API action is not a valid Python identifier or was added after the session was initial-ized.
2.1. Submodules 13
fritzctl Documentation, Release 1.0.0a1
2.1.3 fritzctl.ooapi - Object-Oriented API Wrappers
fritzctl.ooapi.base - Base Object-Oriented API Class
class fritzctl.ooapi.base.API_base(session, urn)Base class for all Object-Oriented API Classes.
This class simply stores the session and URN and requests a dynamic API.
Parameters
• session (Session) – Session object this API should be bound to
• urn (str) – Service Type URN for identifying the service to be wrapped.
Variables
• session – Same as the argument
• urn – Same as the argument
• dynapi – DynamicAPI() instance to be used for requesting data.
fritzctl.ooapi.avm_homeauto - Homeautomation OO Wrapper Classes
class fritzctl.ooapi.avm_homeauto.API_avm_homeauto(session, urn)AVM Homeauto TR64 Object-Oriented API.
Can be instantiated via session.getOOAPI("avm_homeauto") orsession.getOOAPI("urn:dslforum-org:service:X_AVM-DE_Homeauto:1").
Same parameters and attributes as fritzctl.ooapi.base.API_base().
getAINByIndex(index)Returns the AIN associated with the given index.
Parameters index (int) – Index of the Device
Returns AIN corresponding to the given index
Return type str
Raises
• AssertionError – if the supplied index is invalid, e.g. not an integer or less than 0
• ValueError – if the supplied index is out of range
getDeviceByAIN(ain)Returns the device associated to the given AIN.
Parameters ain (str) – AIN of the device to return
Returns Device Object allowing manipulation of its properties
Return type HomeautoDevice
Raises
• AssertionError – if the supplied AIN is not a string
• ValueError – if the supplied AIN is unknown
getDeviceByIndex(index)Returns the device identified by the integer index.
14 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
Parameters index (int) – Index of the device to return
Returns the device object
Return type Instance of HomeautoDevice()
Raises
• ValueError – if the supplied index is invalid
• AssertionError – if the supplied index is invalid, e.g. not an integer or less than 0
getDeviceList(limit=-1)Returns a list of devices, optionally up to the specified limit.
Parameters limit (int) – Optional Limit for the returned list
Returns List of all known devices
Return type List of instances of HomeautoDevice().
Raises AssertionError – if the supplied limit is invalid, e.g. not an integer or less than -1
switchByAIN(ain, state)Switches the given Actors socket on, off or toggles it.
Parameters
• ain (str) – AIN of the device to switch
• state (True, False or toggle) – State to switch to, see STATE2SwStateEnumfor a list of values
Raises
• ValueError – if the supplied AIN is unknown
• KeyError – if the supplied state is invalid
class fritzctl.ooapi.avm_homeauto.HomeautoDevice(api, index, info)Generic Device class representing any device queryable via the TR64 Homeauto API.
Note that some instance variables may be set to arbitrary values if the device does not support the feature.
Parameters
• api (API_avm_homeauto) – API object to use when querying for data
• index (int) – Index this device had when requested viaGetGenericDeviceInfos(), may be -1 if unknown
• info (dict) – Dictionary containing the TR64 Response with all the data about the device;automatically passed to loadData()
Variables
• api (API_avm_homeauto) – stores the supplied API object
• index (int) – stores the supplied index
• info (dict) – stores the data in a dictionary
General Device Variables:
Variables
• ain (str) – AIN of the device
• deviceID (int) – Device ID
2.1. Submodules 15
fritzctl Documentation, Release 1.0.0a1
• functionbitmask (int) – Bitmask containing the flags if specific features are enabled,also see the *_flag variables
• fwversion (str) – Firmware Version currently installed
• manufacturer (str) – Manufacturer Name, e.g. AVM
• productname (str) – Full Product Name of the device, e.g. FRITZ!Powerline546E
• name (str) – User-Defined Name of the device
• present (int) – Integer determining the connection state, see PresentEnum2INT formore information
Energy/Multimeter specific Variables:
Variables
• energy_flag (bool) – Flag if the device supports Multimeter features
• energy_valid (bool) – Flag if the following variables are valid
• energy_power (float) – Current power flowing through the device, in Watts
• energy_energy (float) – Total amount of energy that flowed through this device sincethe last reset in Watthours
Temperature/Thermometer specific Variables:
Variables
• temp_flag (bool) – Flag if the device supports Thermometer features
• temp_valid (bool) – Flag if the following variables are valid
• temp_celsius (float) – Current temperature measured in degrees Celsius
• temp_offset (float) – Offset Temperature defined by the User in degrees Celsius
Switch specific Variables:
Variables
• switch_flag (bool) – Flag if the device supports switch features
• switch_valid (bool) – Flag if the following variables are valid
• switch_state (bool) – Property used to switch the switch, see switch_state
• switch_mode (str) – Either automatic or manual, as set by the user
• switch_lock (bool) – Flag if the switch is locked via hardware
HKR/Heating regulator specific Variables, all temperatures are in degrees celsius:
Variables
• hkr_flag (bool) – Flag if the device supports HKR features
• hkr_valid (bool) – Flag if the following variables are valid
• hkr_temp_is (float) – Current temperature
• hkr_valve_set (str) – Set Valve state
• hkr_temp_set (float) – Set Temperature
• hkr_valve_reduce (str) – Reduce Valve state
16 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
• hkr_temp_reduce (float) – Reduce Temperature
• hkr_valve_comfort (str) – Comfort Valve state
• hkr_temp_comfort (float) – Comfort Temperature
Valve states may be either open, close or temp, where temp means regulated. Refer to the documentationof the TR-064 AVM API for more information.
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
reloadData()Reloads the data from the server.
Note that even if the object was originally constructed using getDeviceByIndex() this method willrequest the data via its AIN.
switch_stateProperty used for getting and setting the switch state.
The value returned by the getter is only updated when reloadData() is called.
The setter immediately sets the switch state and refreshes the data.
See STATE2SwStateEnum for a list of valid values.
Raises
• AssertionError – if this device does not support switching
• KeyError – if the assigned value is invalid
fritzctl.ooapi.avm_homeauto.PresentEnum2INT = {‘UNKNOWN’: -1, ‘REGISTERED’: 2, ‘CONNECTED’: 1, ‘DISCONNECTED’: 0}Mapping for mapping PresentEnum members to Integers.
PresentEnum member Python EquivalentDISCONNECTED 0CONNECTED 1REGISTERED 2UNKNOWN -1
See HomeautoDevice.present for more information.
fritzctl.ooapi.avm_homeauto.STATE2SwStateEnum = {False: ‘OFF’, True: ‘ON’, ‘toggle’: ‘TOGGLE’}Mapping for mapping Python Boolean values to SwStateEnum members.
Either True or False can be used to force-switch or you can use toggle for toggling the current state.
See switchByAIN() for more information about switches.
fritzctl.ooapi.avm_homeplug - Powerline Information OO Wrapper Classes
class fritzctl.ooapi.avm_homeplug.API_avm_homeplug(session, urn)AVM Homeplug TR64 Object-Oriented API.
Can be instantiated via session.getOOAPI("avm_homeplug") orsession.getAPI("urn:dslforum-org:service:X_AVM-DE_Homeplug:1")
Same parameters and attributes as fritzctl.ooapi.base.API_base().
getDeviceByIndex(index)Returns a device object associated with the given index.
2.1. Submodules 17
fritzctl Documentation, Release 1.0.0a1
Parameters index (int) – Index of the device to return
Returns Device Object
Return type HomeplugDevice
Raises
• AssertionError – if the index is invalid, e.g. not an integer or less than 0
• ValueError – if the index is out of bounds
getDeviceByMAC(mac)Returns an device based on its MAC Address.
Parameters mac (str) – MAC Address of the device
Returns Device corresponding to the MAC Address
Return type HomeplugDevice
Raises
• AssertionError – if the MAC Address is not a string
• ValueError – if the MAC Address is not known
getDeviceList()Returns a list of all known Homeplug devices.
Returns List of known Homeplug devices
Return type List of instances of HomeplugDevice()
getDeviceListLength()Returns the length of the list of devices.
Returns Length of the device list
Return type int
getMACByIndex(index)Returns the MAC Address of the corresponding device.
Parameters index (int) – Index of the device
Returns MAC Address
Return type str
Raises
• AssertionError – if the index is invalid, e.g. not an integer or less than 0
• ValueError – if the index is out of bounds
class fritzctl.ooapi.avm_homeplug.HomeplugDevice(api, index, info)Device class representing any device queryable via the Homeplug TR64 API.
Parameters
• api (API_avm_homeplug) – API object used for queries
• index (int) – Index used to request this object, may be -1 if unknown
• info (dict) – Dictionary containing all the data about the device as a TR64 response
Variables
• api (API_avm_homeplug) – Stored API Object
18 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
• index (int) – Stored Index
• info (dict) – Stored Raw Data
Device Variables:
Variables
• mac (str) – MAC Address of the Device
• active (bool) – Flag if the device is currently active
• name (str) – User-Defined Name of the device
• model (str) – Full Model Name of the device
• update_available (bool) – Flag if there is an update available
• update_successful (bool) – Flag if the last update was successful, also False if un-known.
doUpdate()Requests that the device should update itself.
You can check if the update is done by comparing update_available and other attributes after re-freshing.
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
reloadData()Reloads the data from the server.
Note that even if the object was originally constructed using getDeviceByIndex() this method willrequest the data via its MAC Address.
fritzctl.ooapi.general_time - Time configuration OO Wrapper Classes
class fritzctl.ooapi.general_time.API_general_time(session, urn)Time configuration TR64 Object-Oriented API.
Can be instantiated via session.getOOAPI("general_time") orsession.getOOAPI("urn:dslforum-org:service:Time:1").
Same parameters and attributes as fritzctl.ooapi.base.API_base().
getInfo()Returns information about the time configuration.
Returns Information about the time configuration on the server
Return type TimeInfo
setNTPServers(server1, server2)Sets the NTP Servers to be used by the server.
Parameters
• server1 (str) – NTP Server #1
• server2 (str) – NTP Server #2
Raises ValueError – if the servers are invalid
2.1. Submodules 19
fritzctl Documentation, Release 1.0.0a1
class fritzctl.ooapi.general_time.TimeInfo(api, info)Time configuration information class.
Parameters
• api (API_general_time) – API object to use when querying for data
• info (dict) – Dictionary containing the TR64 Response with all the data about the device;automatically passed to loadData()
Variables
• api (API_general_time) – stores the supplied API object
• info (dict) – stores the data in a dictionary
Configuration Variables:
Variables
• server1 – NTP Server address #1
• server2 – NTP Server address #2
• time (str) – String containing the formatted current time on the server.
Variables not supported by the FRITZ!Box, but included for compatibility:
Variables
• timezone (str) – String Representing the local Timezone
• dst_used (bool) – Flag if Daylight Saving Time is enabled
• dst_start (str) – Formatted Time when DST begins
• dst_end (str) – Formatted Time when DST ends
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
reloadData()Reloads the data from the server in-place.
fritzctl.ooapi.general_deviceinfo - Device Information OO Wrapper Classes
class fritzctl.ooapi.general_deviceinfo.API_general_deviceinfo(session, urn)Device Information TR64 Object-Oriented Wrapper API.
Can be instantiated via session.getOOAPI("general_deviceinfo") orsession.getOOAPI("urn:dslforum-org:service:DeviceInfo:1").
Same parameters and attributes as fritzctl.ooapi.base.API_base().
getDeviceInfo()Returns an information object with all relevant data.
Returns Information Object about the server
Return type DeviceInfo
getDeviceLog()Returns the device log since the last reboot.
Note that the log is just one long string, and may need to be split on newlines.
20 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
Returns The device log since the last reboot
Return type str
getSecurityPort()Returns the secure port number used for secure TR64 Connections.
Returns The Secure Port Number
Return type int
setProvisioningCode(code)Sets the TR-069 Provisioning Code. The provisioning code must match the RegEx[0-9]{3}\.[0-9]{3}\.[0-9]{3}\.[0-9]{3}.
Parameters code (str) – A Valid TR-069 Provisioning Code
Raises
• AssertionError – if the supplied code does not match the RegEx
• ValueError – if the supplied code was rejected by the server
class fritzctl.ooapi.general_deviceinfo.DeviceInfo(api, info)Class representing the system the server runs on, e.g. the FRITZ!Box.
Parameters
• api (API_general_deviceinfo) – API object to use when querying for data
• info (dict) – Dictionary containing the TR64 Response with all the data about the device;automatically passed to loadData()
Variables
• api (API_general_deviceinfo) – stores the supplied API object
• info (dict) – stores the data in a dictionary
General Device Variables:
Variables
• manufacturer (str) – Manufacturer, e.g. AVM
• manufacturerOUI (str) – Manufacturer OUI, e.g. 00040E
• modelname (str) – Name of the Model of the device, e.g. FRITZ!Box 7580
• description (str) – Short description of the Model, usually a longer version ofmodelname
• productclass (str) – Class of the Product, e.g. FRITZ!Box
• serialnumber (str) – Serialnumber of the Device, can be used to distinguish devices.
• swversion (str) – Softwareversion of the device, e.g. 153.06.51
• hwversion (str) – Hardwareversion of the device, e.g. FRITZ!Box 7580
• specversion (str) – Version of the Specification, e.g. 1.0
• provisioningcode (str) – TR-069 Provisioning Code, can be set viaAPI_general_deviceinfo.setProvisioningCode()
• uptime (int) – Uptime of the Device in seconds, as of the creation of this object. Can berefreshed with reloadData()
2.1. Submodules 21
fritzctl Documentation, Release 1.0.0a1
• devicelog (str) – String containing the log of the device, seeAPI_general_deviceinfo.getDeviceLog() for more information.
All the examples are based on a FRITZ!Box 7580 on the newest Beta Firmware as of the 12th of July 2016.
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
reloadData()Reloads the data from the server and updates it in-place.
fritzctl.ooapi.general_deviceconfig - Device Configuration OO Wrapper Classes
class fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig(session, urn)Device Configuration TR64 Object-Oriented API.
Can be instantiated via session.getOOAPI("general_deviceconfig") orsession.getOOAPI("urn:dslforum-org:service:DeviceConfig:1").
Same parameters and attributes as fritzctl.ooapi.base.API_base().
createURLSessionID()Creates an Session ID usable with e.g. the AHA HTTP API or the user interface.
Returns A Valid Session ID
Return type str
factoryReset()Factory Resets the Device.
Warning: Use extreme care when using this method in your programs, as accidentally triggering itdue to bugs can and will cut your internet.
finishConfiguration()Counterpart to startConfiguration(), closes the session.
Returns the new status of the configuration
Return type str
getConfigFile(password)Helper method wrapping getConfigFileURL() for an easier way to get the configfile.
Parameters password (str) – Password used to encrypt the configfile, needed to decrypt
Returns The raw encrypted Configfile
Return type str
getConfigFileURL(password)Returns an HTTPS URL valid for less than 30 seconds to request an encrypted configfile.
Additionally, the FRITZ!Box requires HTTP Digest Authentication using the TR64 credentials to requestthe URL.
See also:
See getConfigFile() for an easier way to get the config file.
Parameters password (str) – Password used to encrypt the configfile, needed to decrypt
22 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
Returns An URL allowing you to access the configfile for 30 seconds
Return type str
Raises
• AssertionError – if the password is not a string
• ValueError – if the password was rejected by the server
getSecureURL(url)Gets a secure URL using a Session ID.
Make sure that your URLs end either with a slash or a questionmark, else you will get ConnectionErrors.Also, you must include a scheme.
Parameters url (str) – URL to GET the data from
Returns The raw page content
Return type str
Raises requests.exceptions.* – if there is an error while getting the URL
persistentDataProperty allowing the user to store Persistent Data on the Device.
This Property is not cached and requests/stores the persistent Data immediately and blocking on the device.
This Property can be written to and read from.
reboot()Reboots the Device.
Warning: Be careful when using this method in automated scripts, as it can cause boot-shutdown-boot... loops.
setConfigFile(password, configurl)Sets the configfile to the file found at the specified URL and encrypted with the password.
Parameters
• password (str) – Password usable to decrypt the configfile
• configurl (str) – URL storing the encrypted configfile
Raises
• AssertionError – if the password is not a string
• ValueError – if the password was rejected by the server or invalid
startConfiguration()Starts a single Configuration Transaction during which no other client may modify settings.
This session will timeout after 45 seconds.
You can alos use every instance of this class as a context manager:
with api:# do some configuration...
# Session automatically closed
2.1. Submodules 23
fritzctl Documentation, Release 1.0.0a1
fritzctl.ooapi.general_hosts - General Host Information OO Wrapper Classes
class fritzctl.ooapi.general_hosts.API_general_hosts(session, urn)General Host Information TR64 Object-Oriented API.
Can be instantiated via session.getOOAPI("general_hosts") orsession.getOOAPI("urn:dslforum-org:service:Hosts:1").
Same parameters and attributes as fritzctl.ooapi.base.API_base().
getChangeCounter()Returns the current change counter.
Returns The current change counter
Return type int
getHostByIndex(index, ext=True)Returns the Host associated with the given Index.
Parameters
• index (int) – The Index of the Host
• ext (bool) – Optional Flag if information from the AVM Extension should be integrated,defaults to True
Returns Host Information Object
Return type Host
Raises
• AssertionError – if the index is invalid, e.g. not an integer or lower than 0
• ValueError – if the index is out-of-bounds
getHostByMAC(mac, ext=True)Returns the Host associated with the given MAC Address.
Parameters
• mac (str) – MAC Address of the Host
• ext (bool) – Optional Flag if information from the AVM Extension should be integrated,defaults to True
Returns Host Information Object
Return type Host
Raises
• AssertionError – if the MAC Address is invalid, e.g. not a string
• ValueError – if the MAC Address is unknown
getHostList(ext=True)Returns a list of all hosts.
Parameters ext (bool) – Optional Flag if information from the AVM Extension should beintegrated, defaults to True
Returns List of Hosts
Return type List of Host()
24 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
getHostListLength()Returns the length of the List of all known Hosts.
Returns Number of Entries in the host list.
Return type int
getMacByIndex(index)Returns the MAC Address of the device associated with the given index.
Parameters index (int) – Index of the Device to return
Returns MAC Address
Return type str
wakeUp(mac)Sends a WakeOnLAN request to the specified Host.
Parameters mac (str) – MAC Address to wake up
Raises
• AssertionError – if the MAC Address is invalid, e.g. not a string
• ValueError – if the MAC Address is unknown
class fritzctl.ooapi.general_hosts.Host(api, index, info)Host Information and Configuration Class.
Parameters
• api (API_avm_homeauto) – API object to use when querying for data
• index (int) – Index this device had when requested via GetGenericHostEntry(),may be -1 if unknown
• info (dict) – Dictionary containing the TR64 Response with all the data about the device;automatically passed to loadData()
Variables
• api (API_avm_homeauto) – stores the supplied API object
• index (int) – stores the supplied index
• info (dict) – stores the data in a dictionary
info stores a flag if extension data is available in the _ext key.
Variables
• mac (str) – MAC Address of this Host
• ip (str) – IP Address of this Host
• address_source (str) – Source of the Address
• lease_remaining (int) – Time in second until the DHCP Lease expires
• interface_type (str) – Type of the interface this Host is connected with
• active (bool) – Flag if this host is active
• hostname (str) – Property for reading and writing hostname, see hostname
Extension Variables:
Variables
2.1. Submodules 25
fritzctl Documentation, Release 1.0.0a1
• ethport (int) – Which ethernet port the host is connected with, from 1-4 or 0 if not viaLAN
• speed (float) – Current Connection Speed
• updateAvailable (bool) – Flag if an update is available, where applicable
• updateSuccessful (bool) – Flag if the last update was successful, where applicable
• infourl (str) – URL for getting Information
• model (str) – Model of the Host
• url (str) – URL of the Host
autoWOLProperty controlling the Auto-WakeOnLAN Feature.
This Property is not cached and can be written to and read from.
checkForUpdates()Checks for Updates.
Note that this method does not return anything as the underlying API call gives no variables in return. Thismethod automatically reloads the data to update any update flags that may have changed.
doUpdate()Requests that the host does an update.
Note that this may not work on every host
hostnameProperty controlling the hostname of the device.
This property will only update the displayed hostname if it is modified or the data is refreshed.
This property can be read from and written to
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
Note that the _ext key must be set to a boolean flag indicating if extension information is contained inthe response.
reloadData()Reloads the data from the server.
Note that this method will only request extension data if the key _ext is set to True.
wakeUp()Sends a WakeOnLAN request to this host and tries to wake it up.
fritzctl.ooapi.net_wlan_multi - WLAN Configuration OO Wrapper Classes
class fritzctl.ooapi.net_wlan_multi.API_net_wlan_multi(session, urn)Wlan Configuration TR64 Object-Oriented API.
Can be instantiated via session.getOOAPI("avm_homeauto") orsession.getOOAPI("urn:dslforum-org:service:X_AVM-DE_Homeauto:1").
Same parameters and attributes as fritzctl.ooapi.base.API_base().
getConfig(ext=True)Returns a WLAN Information Object about the current network.
26 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
Parameters ext (bool) – Optional Flag if AVM Extension Wlan data should be integrated,defaults to True
Returns WLAN Information Object
Return type WlanConfig
getDeviceByIndex(index)Returns a specific Wlan device by Index.
Parameters index (int) – Index of the Wlan Device
Returns Wlan Device Object
Return type AssociatedDeviceInfo
Raises
• AssertionError – if the index is invalid, e.g. not an integer or less than zero.
• ValueError – if the index is out of bounds
getDeviceByMAC(mac)Returns the Wlan Device associated with the MAC Address.
Parameters mac (str) – MAC Address of the device to return
Returns Wlan Device Object
Return type AssociatedDeviceInfo
Raises
• AssertionError – if the MAC Address is invalid, e.g. not a string
• ValueError – if the MAC Address was rejected by the server or unknown
getDevices()Returns a list of Wlan Devices.
Returns List of Wlan Devices
Return type List of AssociatedDeviceInfo()
class fritzctl.ooapi.net_wlan_multi.AssociatedDeviceInfo(api, index, info)General Wlan Device Class.
Parameters
• api (API_net_wlan_multi) – API object to use when querying for data
• index (int) – Index this device had when requested viaGetGenericAssociatedDeviceInfos(), may be -1 if unknown
• info (dict) – Dictionary containing the TR64 Response with all the data about the device;automatically passed to loadData()
Variables
• api (API_net_wlan_multi) – stores the supplied API object
• index (int) – stores the supplied index
• info (dict) – stores the data in a dictionary
Device Variables:
Variables
2.1. Submodules 27
fritzctl Documentation, Release 1.0.0a1
• mac (str) – MAC Address of the Device
• ip (str) – IP Address of the Device
• authstate (bool) – Flag if the device is authentificated or not
• speed (int) – Speed of the connection in Mbits/s
• signalstrength (int) – Strength of the signal from 0 to 70, unit unknown
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
reloadData()Reloads the data from the server and integrates it in-place.
fritzctl.ooapi.net_wlan_multi.KEYLONGMapping converting between user-friendly key names and TR64 State Variables.
Mapping:
User-Friendly Name Internal Namewep0 NewWEPKey0wep1 NewWEPKey1wep2 NewWEPKey2wep3 NewWEPKey3psk NewPreSharedKeypassphrase NewKeyPassphrase
class fritzctl.ooapi.net_wlan_multi.WLANGuestInfo(api)Simple storage object used by WlanConfig() to represent a guest network.
Parameters api (API_net_wlan_multi) – API object stored for future use
Variables api (API_net_wlan_multi) – Stored API object
Instance Variables set by WlanConfig.loadData():
Variables
• apenabled (bool) – Flag indicating if the Guest Network is enabled
• aptype (str) – Access Point Type, e.g. normal
• timeout_active (bool) – Flag if a timeout was set
• timeout_remain – Time in seconds that remain
• timeout_timeout – Duration of the Timeout
• noforcedoff (bool) – Flag if force should be used when going off
• userisolation – Type of Userisolation
• encmode – Type of Encryption used
• timestamp (int) – Timestamp of the Access Point
fritzctl.ooapi.net_wlan_multi.WLANHYBRIDNAMESDictionary used to convert a WlanHybridModeConfig() to a dictionary.
Mapping:
28 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
User-Friendly Name Internal Nameenable NewEnablebeacontype NewBeaconTypekeypassphrase NewKeyPassphrasessid NewSSIDbssid NewBSSIDtrafficmode NewTrafficModemanualspeed NewManualSoeedmaxspeed_down NewMaxSpeedDSmaxspeed_up NewMaxSpeedUS
class fritzctl.ooapi.net_wlan_multi.WlanConfig(api, info)WLAN Configuration Object.
Allows getting and setting various properties of the network this object is associated with.
See also:
See fritzctl.session.NAME_TO_URN for more information about how to get specific networks.
Parameters
• api (API_net_wlan_multi) – API object to use when querying for data
• info (dict) – Dictionary containing the TR64 Response with all the data about the device;automatically passed to loadData()
Variables
• api (API_net_wlan_multi) – stores the supplied API object
• info (dict) – stores the supplied data in a dictionary
• keylist (WlanSecurityKeys) – Keylist allowing for easy key access, seeWlanSecurityKeys()
• hybrid (WlanHybridModeConfig) – Special config for accessing the hybrid network
WLAN Network Configuration Values:
Variables
• enable (bool) – Flag if the network is enabled, see enable for more information aboutthis propertys
• status (str) – Status string, either Up or Down
• maxbitrate (str) – String containing either Auto or the maximum bitrate
• channel (int) – Property containing the current channel used, see channel
• possibleChannels (list) – List of all possible channels, updated when gettingchannel
• ssid (str) – Property containing the SSID of the network, see ssid
• beaconType (str) – Property containing the Beacon Type used by this network, seebeaconType
• maccontrol (bool) – Flag if the MAC Address Filter is enabled, allowing only knowndevices to connect
• standard (str) – WLAN Standard supported by the network, e.g. g
• bssid (str) – Property containing the BSSID of the network, see bssid
2.1. Submodules 29
fritzctl Documentation, Release 1.0.0a1
• basic_enc_modes (str) – Basic Encryption Modes as set by the server, seems to be"None" right now
• basic_auth_mode (str) – Basic Authentification Mode as set by the server, seems tobe "None" right now
• ssid_maxlen (int) – Maximum allowed length of the SSID
• ssid_minlen (int) – Minimum allowed length of the SSID
• ssid_allowedchars (str) – String of all characters allowed in an SSID
• psk_minlen (int) – Minimum allowed length of the PreSharedKey
• psk_maxlen (int) – Maximum allowed length of the PreSharedKey
• psk_allowedchars (str) – Similiar to ssid_allowedchars, but for PSK
Extension Variables only present if the _ext key is set to True:
Variables guest (WLANGuestInfo) – Guest Network Information Object, seeWLANGuestInfo() for more information
beaconAdvertisementProperty Flag if the network uses a beacon advertisement.
This property can also be written to.
Raises AssertionError – if the given flag is not a boolean value
beaconSecurityPropertiesProperty for accessing the security properties of the beacon.
This property can also be written to.
The format of both getter and setter is (EncryptionMode,AuthMode).
Raises
• AssertionError – if the given value is invalid, e.g. not a tuple or list, length not equalto two or one of the values is not a string
• ValueError – if the given values were rejected by the server
beaconTypeProperty for managing the beacon type used by the network.
This property may also be written to.
Raises
• AssertionError – if the supplied beacon type is invalid, e.g. not a string
• ValueError – if the beacon type is rejected by the server
bssidProperty for getting the BSSID of the current network.
Note that this property is not cached and will be slow to get.
channelProperty used to manage the wireless channel used by the network.
This property can also be written to.
Note that even just reading this property will also update the possibleChannels attribute.
Raises
30 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
• AssertionError – if the supplied channel is invalid, e.g. not an integer or not inpossibleChannels
• ValueError – if the channel is rejected by the server
defaultWEPKeyIndexProperty for managing the default WEP Key Index.
This property is not cached and can also be written to.
Raises AssertionError – if the supplied key index is invalid, e.g. not an integer or notbetween 0 and 3 inclusive
enableHighFrequencyBandRead-only Property for setting the high frequency band either on or off.
Raises
• AssertionError – if the value is not a boolean value
• NotImplementedError – if you try to read from this property
enabledProperty used to control if the network is enabled.
This property can also be written to with standard Python bool values.
getNightControl()Gets the night control settings.
Returns 2-tuple of (NightControl,NoForcedOff) where NightControl may be None
Return type tuple
getStatistics()Returns packet statistics for the current network.
Todo
Check the difference between GetStatistics() and GetPacketStatistics()
Returns 2-tuple of (TotalPacketsSent,TotalPacketsReceived)
Return type tuple
iptvOptimizedProperty for managing if the network is IPTV Optimized.
This property is not cached but can be written to.
Raises AssertionError – if the supplied value is not boolean
loadData(data)Populates instance variables with the supplied TR64 response. This method is automatically called uponconstruction with the supplied info dict.
pushConfig()Pushes modified data to the server.
Note that only some variables are pushed, as not all are supported.
Mapping of variable names to internal names:
2.1. Submodules 31
fritzctl Documentation, Release 1.0.0a1
Instance Variable TR64 State Variablemaxbitrate NewMaxBitRatechannel NewChannelssid NewSSIDbeaconType NewBeaconTypemaccontrol NewMacAddressControlEnabledbasic_enc_modes NewBasicEncryptionModesbasic_auth_mode NewBasicAuthenticationMode
reloadData()Reloads the stored information in-place.
Note that extension data is only refreshed if the _ext key is set to True.
ssidProperty allowing access to the SSID of the network.
The SSID is often displayed by User Agents for ease-of-use.
This property is uncached and may also be written to, see the ssid_minlen, ssid_maxlen andssid_allowedchars attributes.
Raises
• AssertionError – if the supplied SSID is invalid, e.g. not a string or contains charac-ters that are not allowed
• ValueError – if the server rejects the SSID, examine the traceback for more informa-tion
stickSurfEnableWrite-Only property used to set if sticksurf should be enabled.
Raises
• AssertionError – if the supplied value is not boolean
• NotImplementedError – if you try to write to this property
totalAssociationsProperty containing the amount of total associations by this network.
This property is read-only.
class fritzctl.ooapi.net_wlan_multi.WlanHybridModeConfig(wlaninfo, api)WLAN Hybrid Mode Configuration Helper Class.
This object can be used like a dictionary, for valid keys see WLANHYBRIDNAMES.
Note that none of these Methods are cached.
If you need to get multiple variables you can do a batched request with toDict()
toDict()Gets the whole WLAN Hybrid Mode Config as a dictionary.
Returns Dictionary containing the WLAN Hybrid Config
Return type dict
class fritzctl.ooapi.net_wlan_multi.WlanSecurityKeys(wlaninfo, api)Security Key Helper class for ease-of-use.
This object may be used like a list or a dict.
If used like a list, only indices 0-3 are accepted, referring to the respective WEP Keys.
32 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
fritzctl Documentation, Release 1.0.0a1
The dictionary access allows for usage of user-friendly short names:
Index Short Name Long Name0 wep0 NewWEPKey01 wep1 NewWEPKey12 wep2 NewWEPKey23 wep3 NewWEPKey3— psk NewPreSharedKey— passphrase NewKeyPassphrase
You can also use both of these access methods for reading and writing.
Note that it is slow if you set each key sequentially, instead see setKeys() for batched key setting.
It should also be possible to set this object to a list, tuple or dict by setting the corresponding attribute of itsparent. This mechanic will not work if this object is not an attribute.
getKeyDict()Returns the keys as a dictionary.
For a list of keys see WlanSecurityKeys() or KEYLONG.
You can change the keys without modifying the keys on the server, but you may apply the changes youmade via setKeys().
Returns Dictionary with all 6 keys
Return type dict
getKeyList()Returns the keys in form of a list.
The list has the order [wep0,wep1,wep2,wep3,psk,passphrase].
You can modify this list without modifying the list on the server and when you are done you may applythese changes via setKeys().
Returns List of all 6 keys
Return type list
setKeys(keys)Sets the keys on the server from either a list, tuple or dict.
See getKeyList() for the format of the list or tuple and see getKeyDict() for the keys of thedictionary.
Parameters keys (list, tuple or dict) – Keys to be set
Raises TypeErrror – if the given keys are neither a list, tuple or dict
Package containing Object-Oriented API Wrappers around DynamicAPI() making it easier to work with theseAPIs.
You should not directly instantiate these APIs, instead see getOOAPI() for how to request these APIs.
fritzctl.ooapi.OO_APISMapping of Service Type URNs to OO API classes.
See NAME_TO_URN for a list of URNs, names and which of these have Object-Oriented APIs defined.
2.1. Submodules 33
fritzctl Documentation, Release 1.0.0a1
2.2 Root Module
Root module for fritzctl containing the fritzctl.session, fritzctl.dynapi and fritzctl.ooapimod-ules and packages.
This package automatically imports the session module with from ... import *, this means that you canaccess e.g. fritzctl.session.Session() as fritzctl.Session().
34 Chapter 2. fritzctl - Python Client Library for the AVM TR64 API
CHAPTER 3
Indices and tables
• genindex
• modindex
• search
35
fritzctl Documentation, Release 1.0.0a1
36 Chapter 3. Indices and tables
Python Module Index
ffritzctl, 34fritzctl.dynapi, 13fritzctl.ooapi, 33fritzctl.ooapi.avm_homeauto, 14fritzctl.ooapi.avm_homeplug, 17fritzctl.ooapi.base, 14fritzctl.ooapi.general_deviceconfig, 22fritzctl.ooapi.general_deviceinfo, 20fritzctl.ooapi.general_hosts, 24fritzctl.ooapi.general_time, 19fritzctl.ooapi.net_wlan_multi, 26fritzctl.session, 11
37
fritzctl Documentation, Release 1.0.0a1
38 Python Module Index
Index
AAPI_avm_homeauto (class in
fritzctl.ooapi.avm_homeauto), 14API_avm_homeplug (class in
fritzctl.ooapi.avm_homeplug), 17API_base (class in fritzctl.ooapi.base), 14API_general_deviceconfig (class in
fritzctl.ooapi.general_deviceconfig), 22API_general_deviceinfo (class in
fritzctl.ooapi.general_deviceinfo), 20API_general_hosts (class in fritzctl.ooapi.general_hosts),
24API_general_time (class in fritzctl.ooapi.general_time),
19API_net_wlan_multi (class in
fritzctl.ooapi.net_wlan_multi), 26AssociatedDeviceInfo (class in
fritzctl.ooapi.net_wlan_multi), 27autoWOL (fritzctl.ooapi.general_hosts.Host attribute), 26
BbeaconAdvertisement (fritzctl.ooapi.net_wlan_multi.WlanConfig
attribute), 30beaconSecurityProperties
(fritzctl.ooapi.net_wlan_multi.WlanConfigattribute), 30
beaconType (fritzctl.ooapi.net_wlan_multi.WlanConfigattribute), 30
bssid (fritzctl.ooapi.net_wlan_multi.WlanConfig at-tribute), 30
CcallAPI() (fritzctl.dynapi.DynamicAPI method), 13channel (fritzctl.ooapi.net_wlan_multi.WlanConfig at-
tribute), 30checkForUpdates() (fritzctl.ooapi.general_hosts.Host
method), 26createURLSessionID() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 22
DdefaultWEPKeyIndex (fritzctl.ooapi.net_wlan_multi.WlanConfig
attribute), 31DeviceInfo (class in fritzctl.ooapi.general_deviceinfo), 21doUpdate() (fritzctl.ooapi.avm_homeplug.HomeplugDevice
method), 19doUpdate() (fritzctl.ooapi.general_hosts.Host method),
26DynamicAPI (class in fritzctl.dynapi), 13
Eenabled (fritzctl.ooapi.net_wlan_multi.WlanConfig at-
tribute), 31enableHighFrequencyBand
(fritzctl.ooapi.net_wlan_multi.WlanConfigattribute), 31
execute() (fritzctl.session.Session method), 12
FfactoryReset() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 22finishConfiguration() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 22fritzctl (module), 34fritzctl.dynapi (module), 13fritzctl.ooapi (module), 33fritzctl.ooapi.avm_homeauto (module), 14fritzctl.ooapi.avm_homeplug (module), 17fritzctl.ooapi.base (module), 14fritzctl.ooapi.general_deviceconfig (module), 22fritzctl.ooapi.general_deviceinfo (module), 20fritzctl.ooapi.general_hosts (module), 24fritzctl.ooapi.general_time (module), 19fritzctl.ooapi.net_wlan_multi (module), 26fritzctl.session (module), 11
GgetAINByIndex() (fritzctl.ooapi.avm_homeauto.API_avm_homeauto
method), 14getAPI() (fritzctl.session.Session method), 13
39
fritzctl Documentation, Release 1.0.0a1
getChangeCounter() (fritzctl.ooapi.general_hosts.API_general_hostsmethod), 24
getConfig() (fritzctl.ooapi.net_wlan_multi.API_net_wlan_multimethod), 26
getConfigFile() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfigmethod), 22
getConfigFileURL() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfigmethod), 22
getDeviceByAIN() (fritzctl.ooapi.avm_homeauto.API_avm_homeautomethod), 14
getDeviceByIndex() (fritzctl.ooapi.avm_homeauto.API_avm_homeautomethod), 14
getDeviceByIndex() (fritzctl.ooapi.avm_homeplug.API_avm_homeplugmethod), 17
getDeviceByIndex() (fritzctl.ooapi.net_wlan_multi.API_net_wlan_multimethod), 27
getDeviceByMAC() (fritzctl.ooapi.avm_homeplug.API_avm_homeplugmethod), 18
getDeviceByMAC() (fritzctl.ooapi.net_wlan_multi.API_net_wlan_multimethod), 27
getDeviceInfo() (fritzctl.ooapi.general_deviceinfo.API_general_deviceinfomethod), 20
getDeviceList() (fritzctl.ooapi.avm_homeauto.API_avm_homeautomethod), 15
getDeviceList() (fritzctl.ooapi.avm_homeplug.API_avm_homeplugmethod), 18
getDeviceListLength() (fritzctl.ooapi.avm_homeplug.API_avm_homeplugmethod), 18
getDeviceLog() (fritzctl.ooapi.general_deviceinfo.API_general_deviceinfomethod), 20
getDevices() (fritzctl.ooapi.net_wlan_multi.API_net_wlan_multimethod), 27
getHostByIndex() (fritzctl.ooapi.general_hosts.API_general_hostsmethod), 24
getHostByMAC() (fritzctl.ooapi.general_hosts.API_general_hostsmethod), 24
getHostList() (fritzctl.ooapi.general_hosts.API_general_hostsmethod), 24
getHostListLength() (fritzctl.ooapi.general_hosts.API_general_hostsmethod), 24
getInfo() (fritzctl.ooapi.general_time.API_general_timemethod), 19
getKeyDict() (fritzctl.ooapi.net_wlan_multi.WlanSecurityKeysmethod), 33
getKeyList() (fritzctl.ooapi.net_wlan_multi.WlanSecurityKeysmethod), 33
getMACByIndex() (fritzctl.ooapi.avm_homeplug.API_avm_homeplugmethod), 18
getMacByIndex() (fritzctl.ooapi.general_hosts.API_general_hostsmethod), 25
getNightControl() (fritzctl.ooapi.net_wlan_multi.WlanConfigmethod), 31
getOOAPI() (fritzctl.session.Session method), 13getSecureURL() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 23getSecurityPort() (fritzctl.ooapi.general_deviceinfo.API_general_deviceinfo
method), 21getStatistics() (fritzctl.ooapi.net_wlan_multi.WlanConfig
method), 31
HHomeautoDevice (class in fritzctl.ooapi.avm_homeauto),
15HomeplugDevice (class in fritzctl.ooapi.avm_homeplug),
18Host (class in fritzctl.ooapi.general_hosts), 25hostname (fritzctl.ooapi.general_hosts.Host attribute), 26
IiptvOptimized (fritzctl.ooapi.net_wlan_multi.WlanConfig
attribute), 31
KKEYLONG (in module fritzctl.ooapi.net_wlan_multi), 28
LloadData() (fritzctl.ooapi.avm_homeauto.HomeautoDevice
method), 17loadData() (fritzctl.ooapi.avm_homeplug.HomeplugDevice
method), 19loadData() (fritzctl.ooapi.general_deviceinfo.DeviceInfo
method), 22loadData() (fritzctl.ooapi.general_hosts.Host method), 26loadData() (fritzctl.ooapi.general_time.TimeInfo
method), 20loadData() (fritzctl.ooapi.net_wlan_multi.AssociatedDeviceInfo
method), 28loadData() (fritzctl.ooapi.net_wlan_multi.WlanConfig
method), 31
NNAME_TO_URN (in module fritzctl.session), 11
OOO_APIS (in module fritzctl.ooapi), 33
PpersistentData (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
attribute), 23PresentEnum2INT (in module
fritzctl.ooapi.avm_homeauto), 17pushConfig() (fritzctl.ooapi.net_wlan_multi.WlanConfig
method), 31Python Enhancement Proposals
PEP 8, 8
40 Index
fritzctl Documentation, Release 1.0.0a1
Rreboot() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 23reloadData() (fritzctl.ooapi.avm_homeauto.HomeautoDevice
method), 17reloadData() (fritzctl.ooapi.avm_homeplug.HomeplugDevice
method), 19reloadData() (fritzctl.ooapi.general_deviceinfo.DeviceInfo
method), 22reloadData() (fritzctl.ooapi.general_hosts.Host method),
26reloadData() (fritzctl.ooapi.general_time.TimeInfo
method), 20reloadData() (fritzctl.ooapi.net_wlan_multi.AssociatedDeviceInfo
method), 28reloadData() (fritzctl.ooapi.net_wlan_multi.WlanConfig
method), 32
SSession (class in fritzctl.session), 12setConfigFile() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 23setKeys() (fritzctl.ooapi.net_wlan_multi.WlanSecurityKeys
method), 33setNTPServers() (fritzctl.ooapi.general_time.API_general_time
method), 19setProvisioningCode() (fritzctl.ooapi.general_deviceinfo.API_general_deviceinfo
method), 21ssid (fritzctl.ooapi.net_wlan_multi.WlanConfig attribute),
32startConfiguration() (fritzctl.ooapi.general_deviceconfig.API_general_deviceconfig
method), 23STATE2SwStateEnum (in module
fritzctl.ooapi.avm_homeauto), 17stickSurfEnable (fritzctl.ooapi.net_wlan_multi.WlanConfig
attribute), 32switch_state (fritzctl.ooapi.avm_homeauto.HomeautoDevice
attribute), 17switchByAIN() (fritzctl.ooapi.avm_homeauto.API_avm_homeauto
method), 15
TTimeInfo (class in fritzctl.ooapi.general_time), 19toDict() (fritzctl.ooapi.net_wlan_multi.WlanHybridModeConfig
method), 32totalAssociations (fritzctl.ooapi.net_wlan_multi.WlanConfig
attribute), 32
WwakeUp() (fritzctl.ooapi.general_hosts.API_general_hosts
method), 25wakeUp() (fritzctl.ooapi.general_hosts.Host method), 26WlanConfig (class in fritzctl.ooapi.net_wlan_multi), 29
WLANGuestInfo (class in fritzctl.ooapi.net_wlan_multi),28
WlanHybridModeConfig (class infritzctl.ooapi.net_wlan_multi), 32
WLANHYBRIDNAMES (in modulefritzctl.ooapi.net_wlan_multi), 28
WlanSecurityKeys (class infritzctl.ooapi.net_wlan_multi), 32
Index 41