A Fritz!Box Home Automation API Client for Elixir.
Usage
iex> {:ok, client} = FritzApi.Client.new()
...> |> FritzApi.Client.login("admin", "changeme")
iex> FritzApi.set_switch_off(client, "687690315761")
:ok
iex> FritzApi.get_temperature(client, "687690315761")
{:ok, 23.5}Configuration
The main way to configure FritzApi is through the options passed to FritzApi.Client.new/1.
To customize the behaviour of the HTTP client used by FritzApi, you can configure FritzApi
through the application environment. For example, you can do this in config/runtime.exs:
# config/runtime.exs
config :fritz_api,
client: FritzApi.HTTPClient.Finch,
client_pool_opts: [size: 10],
client_request_opts: [receive_timeout: 10_000]You can use these options:
:client(module/0) - A module that implements theFritzApi.HTTPClientbehaviour. Defaults toFritzApi.HTTPClient.Finch(requires:finch).:client_pool_opts(keyword/0) - Options to configure the HTTP client pool. SeeFinch.start_link/1. Defaults to[].:client_request_opts(keyword/0) - Options passed to theFritzApi.HTTPClient.get/2callback. SeeFinch.request/3. Defaults to[].
Summary
Types
Unique actor identifier.
Temperature (Celsius) of a radiator controller, or its on/off state.
Password of the FritzBox user.
The result of a command that returns no value.
The result of a command that returns a value.
Name of the FritzBox user.
Functions
Disable the target temperature of the radiator controller.
Enable the target temperature of the radiator controller.
Get essential information of all smart home devices.
Get the comfort temperature (Celsius) set for time switching of the radiator controller.
Get the economy temperature (Celsius) set for time switching of the radiator controller.
Get the target temperature (Celsius) currently set for the radiator controller.
Get the total energy usage (kWh) of the switch.
Get the actuator identification numbers (AIN) of all known actors.
Get the name of the actor.
Get the current power consumption (Watt) of the switch.
Get the current connection state of the actor.
Get the current switching state.
Get the last measured temperature (Celsius) of the actor.
Set the target temperature (Celsius) of the radiator controller.
Turn off the switch.
Turn on the switch.
Toggle the switch.
Types
@type ain() :: String.t()
Unique actor identifier.
@type hkr_temperature() :: :on | :off | float()
Temperature (Celsius) of a radiator controller, or its on/off state.
@type password() :: String.t()
Password of the FritzBox user.
@type result() :: :ok | {:error, FritzApi.Error.t()}
The result of a command that returns no value.
@type result(value) :: {:ok, value} | {:error, FritzApi.Error.t()}
The result of a command that returns a value.
@type username() :: String.t()
Name of the FritzBox user.
Note
With FRITZ! OS 7.24 and later, the user name cannot be empty.
Functions
@spec disable_hkr_target_temperature(FritzApi.Client.t(), ain()) :: result()
Disable the target temperature of the radiator controller.
Example
iex> FritzApi.disable_hkr_target_temperature(client, "687690315761")
:ok@spec enable_hkr_target_temperature(FritzApi.Client.t(), ain()) :: result()
Enable the target temperature of the radiator controller.
Example
iex> FritzApi.enable_hkr_target_temperature(client, "687690315761")
:ok@spec get_device_list_infos(FritzApi.Client.t()) :: result([FritzApi.Actor.t()])
Get essential information of all smart home devices.
Example
iex> FritzApi.get_device_list_infos(client)
{:ok, [%FritzApi.Actor{
ain: "687690315761",
alert: nil,
functions: ["Energie Messgerät", "Temperatursensor",
"Schaltsteckdose", "Mikrofon"],
fwversion: "04.17",
id: 1,
manufacturer: "AVM",
name: "Aussensteckdose",
powermeter: %FritzApi.Powermeter{
energy: 8.94,
power: 0.0,
voltage: 231.17
},
present: true,
productname: "FRITZ!DECT 210",
switch: %FritzApi.Switch{
devicelock: false,
lock: false,
mode: :auto,
state: false
},
temperature: %FritzApi.Temperature{
celsius: 21.0,
offset: 0.0
}
}]}@spec get_hkr_comfort_temperature(FritzApi.Client.t(), ain()) :: result(hkr_temperature())
Get the comfort temperature (Celsius) set for time switching of the radiator controller.
Example
iex> FritzApi.get_hkr_comfort_temperature(client, "687690315761")
{:ok, 23.5}@spec get_hkr_economy_temperature(FritzApi.Client.t(), ain()) :: result(hkr_temperature())
Get the economy temperature (Celsius) set for time switching of the radiator controller.
Example
iex> FritzApi.get_hkr_economy_temperature(client, "687690315761")
{:ok, 23.5}@spec get_hkr_target_temperature(FritzApi.Client.t(), ain()) :: result(hkr_temperature())
Get the target temperature (Celsius) currently set for the radiator controller.
Example
iex> FritzApi.get_hkr_target_temperature(client, "687690315761")
{:ok, 23.5}@spec get_switch_energy(FritzApi.Client.t(), ain()) :: result(:unknown | float())
Get the total energy usage (kWh) of the switch.
Returns {:ok, :unknown} if the state is unknown.
Example
iex> FritzApi.get_switch_energy(client, "687690315761")
{:ok, 0.475}@spec get_switch_list(FritzApi.Client.t()) :: result([ain()])
Get the actuator identification numbers (AIN) of all known actors.
Example
iex> FritzApi.get_switch_list(client)
{:ok, ["687690315761"]}@spec get_switch_name(FritzApi.Client.t(), ain()) :: result(String.t())
Get the name of the actor.
Example
iex> FritzApi.get_switch_name(client, "687690315761")
{:ok, "FRITZ!DECT #1"}@spec get_switch_power(FritzApi.Client.t(), ain()) :: result(:unknown | float())
Get the current power consumption (Watt) of the switch.
Returns {:ok, :unknown} if the state is unknown.
Example
iex> FritzApi.get_switch_power(client, "687690315761")
{:ok, 0.0}@spec get_switch_present(FritzApi.Client.t(), ain()) :: result(boolean())
Get the current connection state of the actor.
Example
iex> FritzApi.get_switch_present(client, "687690315761")
{:ok, true}@spec get_switch_state(FritzApi.Client.t(), ain()) :: result(:unknown | :on | :off)
Get the current switching state.
Returns {:ok, :unknown} if the state is unknown.
Example
iex> FritzApi.get_switch_state(client, "687690315761")
{:ok, :on}@spec get_temperature(FritzApi.Client.t(), ain()) :: result(:unknown | float())
Get the last measured temperature (Celsius) of the actor.
Returns {:ok, :unknown} if the temperature could not be measured.
Example
iex> FritzApi.get_temperature(client, "687690315761")
{:ok, 23.5}@spec set_hkr_target_temperature(FritzApi.Client.t(), ain(), number()) :: result()
Set the target temperature (Celsius) of the radiator controller.
The temperature is rounded to the nearest half degree and must be between
8.0 and 28.0.
Example
iex> FritzApi.set_hkr_target_temperature(client, "687690315761", 21.5)
:ok@spec set_switch_off(FritzApi.Client.t(), ain()) :: result()
Turn off the switch.
Example
iex> FritzApi.set_switch_off(client, "687690315761")
:ok@spec set_switch_on(FritzApi.Client.t(), ain()) :: result()
Turn on the switch.
Example
iex> FritzApi.set_switch_on(client, "687690315761")
:ok@spec set_switch_toggle(FritzApi.Client.t(), ain()) :: result(:on | :off)
Toggle the switch.
Example
iex> FritzApi.set_switch_toggle(client, "687690315761")
{:ok, :off}