blacksenator/fritzsoap

Reading/writing FRITZ!Box data via TR-064 interface

v2.6.7 2021-04-08 19:17 UTC

This package is auto-updated.

Last update: 2021-10-24 09:50:33 UTC


README

Attention! Since version 2.x class structure changed and therefore a new instantiation of the classes and their SOAP-clients (see Usage) is required.

Purpose

This class provides functions to read and manipulate data via TR-064 and UPnP (IGD) interfaces on FRITZ!Box routers and FRITZ!Repeater from AVM. For example, the FRITZ!Box 7590 provides 505 interfaces (actions) in 55 services.

For reference, it is highly recommended to consult the information AVM provides for interfaces! Despite the large number of actions, not everything that is displayed or parameterized via the FRITZ!OS GUI can be queried or adapted via these interfaces. This library was created to make the large number of interfaces as easy to use as possible. This library makes use of the fact that the available interfaces are declared by each FRITZ!Box itself with descriptive XML files. So there is no need to program something that is already made available in machine-readable form.

Excerpt

You just have to take care of little to perform a desired SOAP-action. The matching SOAP client only needs to be called with the instantiation of its class and gets automatically the correct location (serviceType) and uri (locationURL). So you just need to know what action you need and in what service it is provided. Than you know which class you need to instantiate and how the function is namened - that is the difficult part!

Would you like to get the current list of callers?

$fritzbox = new x_contact($url, $user, $password);
$callList = $fritzbox->getCallList();

That´s all! Simple, convenient, straightforward!

fritzsoap.php is the main class providing general basic objects. All other subclasses are extensions of this class. You usually use this subclasses. Each subclass refers to exactly one service! The naming is identical. There is also one function for each action. The function name matches the name of the action - following php coding rules: first char lower case and no hyphens! For example, the X_AVM-DE_GetIPTVOptimized action is called with the x_AVM_DE_GetIPTVOptimized function.

In addition, this class uses fbvalidateurl. So you do not have to worry about whether you enter the router address with or without scheme (http:///https://), with hostname (fritz.box) or IP (192.168.178.1). Based on the validated URL, the correct SOAP port is also determined automatically!

Refreshing SID

Keep in mind that if programs have been running for a long time, the SID may need to be renewed by calling the getClient() function! So what does long time mean? The AVM documentation is also imprecise here: "...Once it has been assigned, a session ID is valid for 20 minutes. The validity is extended automatically whenever access to the FRITZ!Box is active ... A session can be ended at any time by deleting the session ID, even before the automatic 10-minute timeout kicks in..."

Genesis

Due to the large number of services and actions provided, it was impossible to code this all manually! So all subclasses were originally generated by a program! Base of this generation are the service description files (XML) of my FRITZ!Box 7590. All devices provide these description files via the SOAP port (e.g. //fritz.box:49000/tr64desc.xml). Read the information available there and generate the code from it was the easiest and flawless way to transfer the large amount of services, their actions and parameters into a generic structure of classes.

If you wanna know more more about this, have a closer look into the fritzsoap.php. The generation program is based on a specific subclass, which is NOT part of this library, because generating the classes redundantly on premise does not makes sense. If, contrary to expectations, you receive services with getServiceDescription(true) that are not included here, then simply send me the generated XML and I will generate the missing class from it (Needless to say: the XML does not contain any private data).

Doublets

"WAN*" services (capital letters!) refer to IGD resp. IGD2 descriptions and therefore appear twice: as WAN*_1.php and WAN*_2.php.

Completion

Round about 5% to 10% of the actions are reviewed and coding is ready to use. If so, you will find in the class header comment: THIS FILE IS AUTOMATIC ASSEMBLED BUT PARTLY REVIEWED! In all other cases: THIS FILE IS AUTOMATIC ASSEMBLED! if this class is still generic.

If no coding has been reviewed for your desired action in this class - which is probably the case - the existing examples should show how easy it is to complete the code of that function for your desired action (contributions to extend this class are highly appreciated!). In about half of the cases (if there are no input parameters), it is sufficient to adapt the message for a possible error, since the actions mainly provide arrays with return values that can be further processed by the calling program.

You will see if a function coding has been checked, when you look at the comments. In all other cases untouched functions are looking like the following example of an unreviewed function (from x_homeauto.php):

/**
 * setSwitch
 *
 * automatically generated; complete coding if necessary!
 *
 * in: NewAIN (string)
 * in: NewSwitchState (string)
 *
 * @param string $aIN
 * @param string $switchState
 * @return void
 */
public function setSwitch($aIN, $switchState)
{
    $result = $this->client->SetSwitch(
        new \SoapParam($aIN, 'NewAIN'),
        new \SoapParam($switchState, 'NewSwitchState'));
    if ($this->errorHandling($result, 'Could not ... from/to FRITZ!Box')) {
        return;
    }
}

You will find the input or output parameter (arguments) in the comment section and in the function coding - if it has any.

To facilitate the completion of this creation take a look at the finished functions to adjust function arguments and/or the return of the function (e.g. x_contact.php is the most productive source at the moment).

But as I said before:

  • it is highly recommended to consult the information AVM provides for interfaces
  • contributions are highly appreciated. Share your enhancements! With your PR, everyone benefits from further completion!

Ghosts

Automatic generation has also originate services that are not or not clearly documented by AVM. Accordingly, these classes have no link to a reference document in the class comment! These presumably refer to specifications from Open Connectivity Foundation (aka UPnP-Forum). But parsing that or keeping track of it manually is far beyond my capabilities.

AURA (AVM USB Remote Access)

So far there is one exception: AURA. Through a thread in the IP Phone Forum I learned how this service works. The six actions of this service are coded and an unofficial documentation can be found in the /docs folder. You must have activated the USB remote access function in the FRITZ!Box to be able to access this service!

Control

This group of ghosts includes the Control services, of which I found seven with different serviceType and controlURL. The services are therefore mapped accordingly in the classes Control_1 to Control_7.

Other ghosts

  • any (has no actions - generic template?)
  • avmnexus
  • fritzbox (with FRITZ!OS 7.25 no longer available)
  • l2tpv3

Requirements

Installation

You can install it through Composer:

"require": {
    "blacksenator/fritzsoap": "^2.4"
},

or

git clone https://github.com/blacksenator/fritzsoap.git

Usage

Example if you wanna get a file with your available services:

require_once('vendor/autoload.php');

use blacksenator\fritzsoap\x_contact;

$fritzbox = new x_contact($url, $user, $password);
$services = $fritzbox->getServiceDescription();
$services->asXML('services.xml');

Hint: The function getServiceDescription() is available in all classes! You can also get a more detailed structure with getServiceDescription(true). In this case, the information from the FRITZ!Box is gathered again and all parameters of the actions are also output, as well as the file name of the XML from which the information originates. Example output:

alt text

Example to get a list of all your network devices:

$fritzbox = new hosts($url, $user, $password);
$meshList = $fritzbox->x_AVM_DE_GetMeshListPath();

Example to dial a number (connected to one of your phone devices):

$fritzbox = new x_voip($url, $user, $password);
$fritzbox->x_AVM_DE_DialNumber('030399760');

Error handling

If calling a class or its functions leads to an error, possible causes could be:

  • that your FRITZ!Box/FRITZ!Repeater does not provide the service (range of functions depending on the FRITZ!Box model)
  • your settings:
    • the lack of activation of certain functions in the FRITZ!Box (e.g. UPnP or USB remote access)
    • that the FRITZ!Box user does not have the appropriate rights (TR-064 access)

Wishes

First of all, it has to be said that the TR-064 interface is a great thing. Although around 500 actions give the impression that almost everything of the FRITZ!Box can be output or changed via SOAP, this is of course not true! From my point of view, Actions (functions) are missing for some interesting output and tasks. Just to highlight a few:

  • telephony
    • disconnect inbound calls
  • parental controls
    • get connected devices
    • change filters of devices
    • get ticket list
    • refresh ticket list
  • USB devices
    • get connected devices
    • disconnect/reconnect devices

License

This script is released under MIT license.

Author

Copyright (c) 2019 - 2021 Volker Püschel