View source for Fritzbox-java-api

{{OsProject
|id=com.bitplan.fritzbox
|owner=BITPlan
|title=Java API for Fritzbox
|url=https://github.com/BITPlan/com.bitplan.fritzbox
|version=0.0.5
|date=2018/08/24
}}

= API =
* see https://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/AHA-HTTP-Interface.pdf
* see https://stackoverflow.com/tags/fritzbox/info (with Links to Implementations)

= Unit tests =
The unit tests can be run with:
<source lang='bash'>
mvn test
</source>
If you did not setup your configuration file yet the test will run against a mocked FritzBox.
When the application properties are set you might want to change the test parameters according to your environment.

= Configuration File =
You might want to set your application properties in $HOME/.fritzbox/application.properties
<source lang='bash'>
fritzbox.url=http://fritz.box:443
fritzbox.username=user
fritzbox.password=secret
</source>
= Code Example =
see https://github.com/BITPlan/com.bitplan.fritzbox/blob/master/src/main/java/com/bitplan/fritzbox/CmdLine.java
<source lang='java'>
 /**
   * handle the command line command
   */
  public void doCommand() throws Exception {
    if (fritzbox==null)
      fritzbox = FritzboxImpl.readFromProperties();

    if (fritzbox==null) {
      String msg=String.format("no %s found\nYou might want to create one see http://wiki.bitplan.com/index.php/Fritzbox-java-api#Configuration_File",FritzboxImpl.getPropertyFile().getPath());
      error(msg);
      return;
    }
    if (debug) {
      LOGGER.log(Level.INFO,String.format("Logging in to %s with username %s", fritzbox.getUrl(),
          fritzbox.getUsername()));
    }
    FritzBoxSession session=fritzbox.login();
    final HomeAutomation homeAutomation = new HomeAutomationImpl(session);

    final DeviceList deviceList = homeAutomation.getDeviceListInfos();
    if (debug) {
      LOGGER.log(Level.INFO,String.format("Found %s devices", deviceList.devices.size()));
      for (final Device device : deviceList.devices) {
        LOGGER.log(Level.INFO,String.format("\t%s", device));
      }
    }

    final List<String> ids = homeAutomation.getSwitchList();
    if (debug) {
      LOGGER.log(Level.INFO,String.format("Found %3d device ids: %s", ids.size(), ids));
    }

    if (deviceList.devices.isEmpty()) {
      session.logout();
      return;
    }

    if (listDevices) {
      show("%20s | %10s | %25s | %s", "Name", "By", "Product", "Identifier");
      show("%21s+%12s+%27s+%s", dash(21), dash(12), dash(27), dash(25));
      for (final Device device : deviceList.devices) {
        show("%20s | %10s | %25s | %s", device.name,
            device.manufacturer, device.productname,
            device.identifier);
      }
    }
    final Map<String, String> ainByName = new HashMap<>();
    for (final Device device : deviceList.devices) {
      ainByName.put(device.name, device.getAin());
    }
    /**
     * loop over all devices to be read
     */
    for (final String readDevice : readDevices) {
      // devices can be specified by name or id
      String ain = readDevice;
      // check if a name was given
      if (ainByName.containsKey(ain)) {
        // get the ain for the name
        ain = ainByName.get(ain);
      }
      readSwitch(homeAutomation, ain);
    }

    /**
     * loop over all devices to be set
     */
    if (setDevices.size() % 2 != 0) {
      usage("set needs pairs of name=on/off");
    }
    for (int i = 0; i < setDevices.size(); i += 2) {
      final String name = setDevices.get(i);
      final String powerState = setDevices.get(i + 1);
      // check if a name was given
      String ain = name;
      if (ainByName.containsKey(ain)) {
        // get the ain for the name
        ain = ainByName.get(ain);
      }
      boolean newState = false;
      switch (powerState) {
      case "on":
        newState = true;
        break;
      case "off":
        newState = false;
        break;
      default:
        usage(String.format(
            "%s is not a valid powerState it needs to be on or off",
            powerState));
      }
      show("switching %s %s", name, powerState);
      homeAutomation.setSwitchOnOff(ain, newState);
    }
    
  }
}
</source>

= CmdLine =
== Help / Usage ==
<source lang='bash'>
java -jar fritzbox-java.jar -h

Help
FritzBox Java API Command Line Version: 0.0.1

github: https://github.com/BITPlan/com.bitplan.fritzbox

  usage: java -jar fritzbox.jar
 -d (--debug)         : debug
                        create additional debug output if this switch is used
                        (Vorgabe: false)
 -h (--help)          : help
                        show this usage (Vorgabe: true)
 -l (--list)          : list
                        list devices (Vorgabe: false)
 -r (--read) STRING[] : read
                        read the given devices
 -s (--set) STRING[]  : set
                        set the given devices to the givnen states e.g. main off
 -v (--version)       : showVersion
                        show current version if this switch is used (Vorgabe:
                        false)

</source>

== List devices  ==
<source lang='bash'>
java -jar fritzbox.jar -l
                Name |         By |         Product | Identifier
---------------------+------------+-----------------+-------------------------
            Aquarium |        AVM |  FRITZ!DECT 200 | 08761 0033476
          Wohnzimmer |        AVM |  FRITZ!DECT 200 | 08761 0092893
</source>

== read devices ==
<source lang='bash'>
java -jar fritzbox.jar -r Aquarium Wohnzimmer
 name: Aquarium
   id: 087610033476 
alive: true
   on: false
 uses:     0     W
 used:   940,882 kWh
 temp:    25,0   °C

 name: Wohnzimmer
   id: 087610092893 
alive: true
   on: true
 uses:     1     W
 used:    35,510 kWh
 temp:    24,5   °C
</source>

== switch devices on / off ==
<source lang='bash'>
java -jar fritzbox.jar -s Aquarium off  Wohnzimmer on
switching Aquarium off
switching Wohnzimmer on
</source>

= Links =
* https://www.pcwelt.de/ratgeber/Dect-Funksteckdosen-10022547.html
* https://wiki.ubuntuusers.de/FritzBox/Skripte/
* https://github.com/andig/fritzapi

= History =
* https://github.com/WolfgangFahl/fritzbox-java-api was a fork of
* https://github.com/kaklakariada/fritzbox-java-api
and was used at BITPlan internally for a while until we got unhappy with the license and the details of the implementation.
Therefore we started a new implementation "from scratch".

== C# version ==
The code at:
* https://github.com/WolfgangFahl/fritz-csharp-api
is a starting point. It reads the same application.properties and gets a session id to work with.
[[Category:frontend]]