Documentation ¶
Overview ¶
Package fritz contains the main clients for interacting with the fritz box.
Index ¶
- Variables
- type AlertSensor
- type BoxData
- type Button
- type Call
- type Capability
- type Client
- type Device
- func (d *Device) CanMeasurePower() bool
- func (d *Device) CanMeasureTemp() bool
- func (d *Device) CanRepeatDECT() bool
- func (d *Device) Has(cs ...Capability) bool
- func (d *Device) HasAlertSensor() bool
- func (d *Device) HasHANFUNUnit() bool
- func (d *Device) HasMicrophone() bool
- func (d *Device) IsHANFUNCompatible() bool
- func (d *Device) IsSwitch() bool
- func (d *Device) IsThermostat() bool
- type DeviceGroup
- type Devicelist
- func (l *Devicelist) AlertSensors() []Device
- func (l *Devicelist) Buttons() []Device
- func (l *Devicelist) DeviceGroups() []DeviceGroup
- func (l *Devicelist) DeviceWithID(id string) (Device, bool)
- func (l *Devicelist) NamesAndAins() map[string]string
- func (l *Devicelist) Switches() []Device
- func (l *Devicelist) Thermostats() []Device
- type FirmwareVersion
- type Group
- type GroupInfo
- type HomeAuto
- type Internal
- type LanDevices
- type Message
- type MessageLog
- type Model
- type NetworkElement
- type NextChange
- type Option
- type Phone
- type Powermeter
- type Rights
- type Runtime
- type SessionInfo
- type Switch
- type Temperature
- type Thermostat
- type TrafficMonitoringData
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var HkrErrorDescriptions = map[string]string{
"": "",
"0": "",
"1": " Thermostat adjustment not possible. Is the device mounted correctly?",
"2": " Valve plunger cannot be driven far enough. Possible solutions: Open and close the plunger a couple of times by hand. Check if the battery is too weak.",
"3": " Valve plunger cannot be moved. Is it blocked?",
"4": " Preparing installation.",
"5": " Device in mode 'INSTALLATION'. It can be mounted now.",
"6": " Device is adjusting to the valve plunger.",
}
HkrErrorDescriptions has a translation of error code to a warning/error/status description.
Functions ¶
This section is empty.
Types ¶
type AlertSensor ¶
type AlertSensor struct {
State string `xml:"state"` // Last transmitted alert state, "0" - no alert, "1" - alert, "" if unknown or upon errors.
}
AlertSensor collects data from devices that have an alert sensor.
type BoxData ¶
type BoxData struct { Model Model FirmwareVersion FirmwareVersion Runtime Runtime Hash string Status string }
BoxData contains runtime information of the FRITZ!Box. codebeat:disable[TOO_MANY_IVARS]
type Button ¶
type Button struct {
LastPressedTimestamp string `xml:"lastpressedtimestamp"` // Timestamp (in epoch seconds) when the button was last pressed. "0" or "" if unknown.
}
Button collects data from devices that have a pressable button.
func (*Button) FmtLastPressedCompact ¶
FmtLastPressedCompact returns a compact format of the last pressed timestamp.
func (*Button) LastPressed ¶
LastPressed returns the time when the button was last pressed. It returns nil on absence of this information or upon parsing errors.
type Call ¶
type Call struct { Type string // "1"=incoming, "2"=missed call, "3"=unknown, "4"=outgoing. Date string Caller string PhoneNumber string Extension string OwnPhoneNumber string Duration string }
Call contains the data for one phone call record. codebeat:disable[TOO_MANY_IVARS]
type Capability ¶
type Capability int
Capability enumerates the device capabilities.
const ( HANFUNCompatibility Capability = iota AlertTrigger HeatControl PowerSensor TemperatureSensor StateSwitch DECTRepeater Microphone HANFUNUnit )
Known (specified) device capabilities.
type Client ¶
type Client struct { Config *config.Config // The client configuration. HTTPClient *http.Client // The HTTP client. SessionInfo *SessionInfo // The current session data of the client. }
Client encapsulates the FRITZ!Box interaction API.
func NewClient ¶
NewClient creates a new Client with values read from a config file, given by the parameter configfile. Deprecated: use NewClientFromConfig.
func NewClientFromConfig ¶
NewClientFromConfig creates a new Client with the passed configuration.
type Device ¶
type Device struct { Identifier string `xml:"identifier,attr"` // A unique ID like AIN, MAC address, etc. ID string `xml:"id,attr"` // Internal device ID of the FRITZ!Box. Functionbitmask string `xml:"functionbitmask,attr"` // Bitmask determining the functionality of the device: bit 6: Comet DECT, HKR, "thermostat", bit 7: energy measurement device, bit 8: temperature sensor, bit 9: switch, bit 10: AVM DECT repeater Fwversion string `xml:"fwversion,attr"` // Firmware version of the device. Manufacturer string `xml:"manufacturer,attr"` // Manufacturer of the device, usually set to "AVM". Productname string `xml:"productname,attr"` // Name of the product, empty for unknown or undefined devices. Present int `xml:"present"` // Device connected (1) or not (0). Name string `xml:"name"` // The name of the device. Can be assigned in the web gui of the FRITZ!Box. Switch Switch `xml:"switch"` // Only filled with sensible data for switch devices. Powermeter Powermeter `xml:"powermeter"` // Only filled with sensible data for devices with an energy actuator. Temperature Temperature `xml:"temperature"` // Only filled with sensible data for devices with a temperature sensor. Thermostat Thermostat `xml:"hkr"` // Thermostat data, only filled with sensible data for HKR devices. AlertSensor AlertSensor `xml:"alert"` // Only filled with sensible data for devices with an alert sensor. Button Button `xml:"button"` // Button data, only filled with sensible data for button devices. }
Device models a smart home device. This corresponds to the single entries of the xml that the FRITZ!Box returns. codebeat:disable[TOO_MANY_IVARS]
func (*Device) CanMeasurePower ¶
CanMeasurePower returns true if the device has powermeter functionality. Returns false otherwise.
func (*Device) CanMeasureTemp ¶
CanMeasureTemp returns true if the device has thermometer functionality. Returns false otherwise.
func (*Device) CanRepeatDECT ¶
CanRepeatDECT returns true if the device is capable of relaying Digital Enhanced Cordless Telecommunications (DECT) signals.
func (*Device) Has ¶
func (d *Device) Has(cs ...Capability) bool
Has checks the passed capabilities and returns true iff the device supports all capabilities.
func (*Device) HasAlertSensor ¶
HasAlertSensor returns true if the device has a sensor that may trigger alerts.
func (*Device) HasHANFUNUnit ¶
HasHANFUNUnit returns true if the device has a HAN FUN unit.
func (*Device) HasMicrophone ¶
HasMicrophone returns true if the device has a microphone.
func (*Device) IsHANFUNCompatible ¶
IsHANFUNCompatible returns true if the device speaks the "Home Area Network FUNctional protocol".
func (*Device) IsSwitch ¶
IsSwitch returns true if the device is recognized to be a switch and returns false otherwise.
func (*Device) IsThermostat ¶
IsThermostat returns true if the device is recognized to be a HKR device and returns false otherwise.
type DeviceGroup ¶
DeviceGroup is an inflated version of one Group with multiple Device members.
type Devicelist ¶
Devicelist wraps a list of devices. This corresponds to the outer layer of the xml that the FRITZ!Box returns.
func (*Devicelist) AlertSensors ¶
func (l *Devicelist) AlertSensors() []Device
AlertSensors returns the devices which satisfy HasAlertSensor.
func (*Devicelist) Buttons ¶
func (l *Devicelist) Buttons() []Device
Buttons returns the devices which have a pressable button.
func (*Devicelist) DeviceGroups ¶
func (l *Devicelist) DeviceGroups() []DeviceGroup
DeviceGroups returns a slice of DeviceGroup by joining Group.Members() on Device.ID.
func (*Devicelist) DeviceWithID ¶
func (l *Devicelist) DeviceWithID(id string) (Device, bool)
DeviceWithID searches for a Device by its ID returns a the found/zero value and a flag true/false indicating whether the search was successful.
func (*Devicelist) NamesAndAins ¶
func (l *Devicelist) NamesAndAins() map[string]string
NamesAndAins returns a lookup name -> AIN.
func (*Devicelist) Switches ¶
func (l *Devicelist) Switches() []Device
Switches returns the devices which satisfy IsSwitch.
func (*Devicelist) Thermostats ¶
func (l *Devicelist) Thermostats() []Device
Thermostats returns the devices which satisfy IsThermostat.
type FirmwareVersion ¶
type FirmwareVersion struct { Image string OsVersionMajor string OsVersionMinor string OsVersionRevision string }
FirmwareVersion represent the FRITZ!OS version.
func (FirmwareVersion) String ¶
func (v FirmwareVersion) String() string
String returns a textual representation of FirmwareVersion.
type Group ¶
type Group struct { Identifier string `xml:"identifier,attr"` // A unique ID like AIN, MAC address, etc. ID string `xml:"id,attr"` // Internal device ID of the FRITZ!Box. Functionbitmask string `xml:"functionbitmask,attr"` // Bitmask determining the functionality of the group: bit 6: Comet DECT, HKR, "thermostat", bit 7: energy measurment device, bit 8: temperature sensor, bit 9: switch, bit 10: AVM DECT repeater Fwversion string `xml:"fwversion,attr"` // Firmware version, usually "1.0". Manufacturer string `xml:"manufacturer,attr"` // Manufacturer, usually set to "AVM". Productname string `xml:"productname,attr"` // Name of the product, usually set to "". Present int `xml:"present"` // All devices connected (1) or not (0). Name string `xml:"name"` // The name of the group. Can be assigned in the web gui of the FRITZ!Box. Switch Switch `xml:"switch"` // Only filled with sensible data when switches are contained in the group. Thermostat Thermostat `xml:"hkr"` // Only filled with sensible data when thermostats are contained in the group. GroupInfo GroupInfo `xml:"groupinfo"` // Core data. "What makes up the group". }
Group models a grouping of smart home devices. This corresponds to the single entries of the xml that the FRITZ!Box returns. codebeat:disable[TOO_MANY_IVARS]
func (*Group) MadeFromSwitches ¶
MadeFromSwitches returns true if the devices consist of switches.
func (*Group) MadeFromThermostats ¶
MadeFromThermostats returns true if the devices consist of thermostats.
type GroupInfo ¶
type GroupInfo struct { MasterDeviceID string `xml:"masterdeviceid"` // Internal ID of the master-switch. "0" is no master is set. Members string `xml:"members"` // Internal IDs of the members of the group. Comma-separated values, references Device.ID. }
GroupInfo contains the topological data of the grouping, in particular the members of the group.
type HomeAuto ¶
type HomeAuto interface { Login() error List() (*Devicelist, error) On(names ...string) error Off(names ...string) error Toggle(names ...string) error Temp(value float64, names ...string) error }
HomeAuto is a client for the Home Automation HTTP Interface, see https://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/AHA-HTTP-Interface.pdf.
Example ¶
Interact with Home Automation API.
package main import ( "net/url" "github.com/gotohr/fritzctl/fritz" ) func main() { h := fritz.NewHomeAuto( fritz.URL(&url.URL{Host: "fritz-box.home", Scheme: "https"}), fritz.SkipTLSVerify(), fritz.Credentials("", "password")) h.Login() h.Temp(24.0, "Th1", "Th2") }
Output:
func NewHomeAuto ¶
NewHomeAuto a HomeAuto that communicates with the FRITZ!Box by means of the Home Automation HTTP Interface.
type Internal ¶
type Internal interface { ListLanDevices() (*LanDevices, error) ListLogs() (*MessageLog, error) InternetStats() (*TrafficMonitoringData, error) BoxInfo() (*BoxData, error) }
Internal exposes Fritz!Box internal and undocumented API.
func NewInternal ¶
NewInternal creates a Fritz/internal API from a given client.
type LanDevices ¶
type LanDevices struct {
Network []NetworkElement `json:"network"`
}
LanDevices is the top-level wrapper for the FRITZ!Box answer upon a query for lan devices.
type MessageLog ¶
type MessageLog struct {
Messages []Message `json:"mq_log"`
}
MessageLog is the top-level wrapper for the FRITZ!Box answer upon a query for log events.
type NetworkElement ¶
type NetworkElement struct { Name string `json:"name"` IP string `json:"ip"` Mac string `json:"mac"` UID string `json:"UID"` Dhcp string `json:"dhcp"` Wlan string `json:"wlan"` Ethernet string `json:"ethernet"` Active string `json:"active"` Wakeup string `json:"wakeup"` Deleteable string `json:"deleteable"` Source string `json:"source"` Online string `json:"online"` Speed string `json:"speed"` Guest string `json:"guest"` URL string `json:"url"` }
NetworkElement corresponds to a single entry in LanDevices. codebeat:disable[TOO_MANY_IVARS]
type NextChange ¶
type NextChange struct { TimeStamp string `xml:"endperiod"` // Timestamp (epoch time) when the next temperature switch is scheduled. Goal string `xml:"tchange"` // The temperature to switch to. Same unit convention as in Thermostat.Measured. }
NextChange corresponds to the next HKR switch event.
func (*NextChange) FmtGoalTemperature ¶
func (n *NextChange) FmtGoalTemperature() string
FmtGoalTemperature formats the value of t.Goal as obtained on the xml-over http interface to a floating point string, units in °C. If the value cannot be parsed an empty string is returned. If the value if 255, 254 or 253, "?", "ON" or "OFF" is returned, respectively. If the value is greater (less) than 56 (16) a cut-off "28" ("8") is returned.
func (*NextChange) FmtTimestamp ¶
func (n *NextChange) FmtTimestamp(ref time.Time) string
FmtTimestamp formats the epoch timestamp into a compact readable form. See fmtEpochSecondString.
type Option ¶
type Option func(h *homeAuto)
Option applies fine-grained configuration to the HomeAuto client.
func AuthEndpoint ¶
AuthEndpoint configures the the endpoint for authentication. The default is "/login_sid.lua".
func Caching ¶
Caching activates (or deactivates) caching of obtained data, such as the list of devices.
func Certificate ¶
Certificate actives TLS verification of the FRITZ!Box server, where the certificate is explicitly specified as byte array, encoded in PEM format.
func Credentials ¶
Credentials configures the username and password for authentication. If one wants to use the default admin account, the username should be an empty string.
func SkipTLSVerify ¶
func SkipTLSVerify() Option
SkipTLSVerify omits TLS verification of the FRITZ!Box server. It is not recommended to use it, rather go for the an explicit option with Certificate.
type Powermeter ¶
type Powermeter struct { Power string `xml:"power"` // Current power, refreshed approx every 2 minutes Energy string `xml:"energy"` // Absolute energy consumption since the device started operating }
Powermeter models a power measurement
func (*Powermeter) FmtEnergyWh ¶
func (p *Powermeter) FmtEnergyWh() string
FmtEnergyWh formats the value of p.Energy as obtained on the http interface as a string, units are Wh.
func (*Powermeter) FmtPowerW ¶
func (p *Powermeter) FmtPowerW() string
FmtPowerW formats the value of p.Power as obtained on the http interface as a string, units are W.
type SessionInfo ¶
type SessionInfo struct { Challenge string `xml:"Challenge"` // A challenge provided by the FRITZ!Box. SID string `xml:"SID"` // The session id issued by the FRITZ!Box, "0000000000000000" is considered invalid/"no session". BlockTime string `xml:"BlockTime"` // The time that needs to expire before the next login attempt can be made. Rights Rights `xml:"Rights"` // The Rights associated withe the session. }
SessionInfo models the xml upon accessing the login endpoint. See also https://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/AVM_Technical_Note_-_Session_ID.pdf.
type Switch ¶
type Switch struct { State string `xml:"state"` // Switch state 1/0 on/off (empty if not known or if there was an error). Mode string `xml:"mode"` // Switch mode manual/automatic (empty if not known or if there was an error). Lock string `xml:"lock"` // Switch locked (box defined)? 1/0 (empty if not known or if there was an error). DeviceLock string `xml:"devicelock"` // Switch locked (device defined)? 1/0 (empty if not known or if there was an error). }
Switch models the state of a switch. codebeat:disable[TOO_MANY_IVARS]
type Temperature ¶
type Temperature struct { Celsius string `xml:"celsius"` // Temperature measured at the device sensor in units of 0.1 °C. Negative and positive values are possible. Offset string `xml:"offset"` // Temperature offset (set by the user) in units of 0.1 °C. Negative and positive values are possible. }
Temperature models a temperature measurement.
func (*Temperature) FmtCelsius ¶
func (t *Temperature) FmtCelsius() string
FmtCelsius formats the value of t.Celsius as obtained on the http interface as a stringified floating point number.
func (*Temperature) FmtOffset ¶
func (t *Temperature) FmtOffset() string
FmtOffset formats the value of t.Offset as obtained on the http interface as a stringified floating point number.
type Thermostat ¶
type Thermostat struct { Measured string `xml:"tist"` // Measured temperature. Goal string `xml:"tsoll"` // Desired temperature, user controlled. Saving string `xml:"absenk"` // Energy saving temperature. Comfort string `xml:"komfort"` // Comfortable temperature. NextChange NextChange `xml:"nextchange"` // The next scheduled temperature change. Lock string `xml:"lock"` // Switch locked (box defined)? 1/0 (empty if not known or if there was an error). DeviceLock string `xml:"devicelock"` // Switch locked (device defined)? 1/0 (empty if not known or if there was an error). ErrorCode string `xml:"errorcode"` // Error codes: 0 = OK, 1 = ... see https://avm.de/fileadmin/user_upload/Global/Service/Schnittstellen/AHA-HTTP-Interface.pdf. BatteryLow string `xml:"batterylow"` // "0" if the battery is OK, "1" if it is running low on capacity. WindowOpen string `xml:"windowopenactiv"` // "1" if detected an open window (usually turns off heating), "0" if not. BatteryChargeLevel string `xml:"battery"` // Battery charge level in percent. }
Thermostat models the "HKR" device. codebeat:disable[TOO_MANY_IVARS]
func (*Thermostat) FmtComfortTemperature ¶
func (t *Thermostat) FmtComfortTemperature() string
FmtComfortTemperature formats the value of t.Comfort as obtained on the xml-over http interface to a floating point string, units in °C. If the value cannot be parsed an empty string is returned. If the value if 255, 254 or 253, "?", "ON" or "OFF" is returned, respectively. If the value is greater (less) than 56 (16) a cut-off "28" ("8") is returned.
func (*Thermostat) FmtGoalTemperature ¶
func (t *Thermostat) FmtGoalTemperature() string
FmtGoalTemperature formats the value of t.Goal as obtained on the xml-over http interface to a floating point string, units in °C. If the value cannot be parsed an empty string is returned. If the value if 255, 254 or 253, "?", "ON" or "OFF" is returned, respectively. If the value is greater (less) than 56 (16) a cut-off "28" ("8") is returned.
func (*Thermostat) FmtMeasuredTemperature ¶
func (t *Thermostat) FmtMeasuredTemperature() string
FmtMeasuredTemperature formats the value of t.Measured as obtained on the xml-over http interface to a floating point string, units in °C. If the value cannot be parsed an empty string is returned. If the value if 255, 254 or 253, "?", "ON" or "OFF" is returned, respectively. If the value is greater (less) than 56 (16) a cut-off "28" ("8") is returned.
func (*Thermostat) FmtSavingTemperature ¶
func (t *Thermostat) FmtSavingTemperature() string
FmtSavingTemperature formats the value of t.Saving as obtained on the xml-over http interface to a floating point string, units in °C. If the value cannot be parsed an empty string is returned. If the value if 255, 254 or 253, "?", "ON" or "OFF" is returned, respectively. If the value is greater (less) than 56 (16) a cut-off "28" ("8") is returned.
type TrafficMonitoringData ¶
type TrafficMonitoringData struct { DownstreamInternet []float64 `json:"ds_bps_curr"` DownStreamMedia []float64 `json:"ds_mc_bps_curr"` DownStreamGuest []float64 `json:"ds_guest_bps_curr"` UpstreamRealtime []float64 `json:"us_realtime_bps_curr"` UpstreamHighPriority []float64 `json:"us_important_bps_curr"` UpstreamDefaultPriority []float64 `json:"us_default_bps_curr"` UpstreamLowPriority []float64 `json:"us_background_bps_curr"` UpstreamGuest []float64 `json:"guest_us_bps"` }
TrafficMonitoringData holds the data for the up- and downstream traffic reported by the FRITZ!Box. codebeat:disable[TOO_MANY_IVARS]
func (TrafficMonitoringData) BitsPerSecond ¶
func (d TrafficMonitoringData) BitsPerSecond() TrafficMonitoringData
BitsPerSecond returns a TrafficMonitoringData with metrics in units of bits/second.
func (TrafficMonitoringData) KiloBitsPerSecond ¶
func (d TrafficMonitoringData) KiloBitsPerSecond() TrafficMonitoringData
KiloBitsPerSecond returns a TrafficMonitoringData with metrics in units of kbits/second.
Source Files ¶
- ain_based.go
- alertsensor.go
- api_aha.go
- api_aha_options.go
- api_internal.go
- api_phone.go
- bitmasked.go
- box_data.go
- button.go
- concurrent.go
- conversion_temperature.go
- device.go
- devicelist.go
- doc.go
- fritzapi_constants.go
- fritzclient.go
- group.go
- landevicelist.go
- message_log.go
- next_change.go
- powermeter.go
- switch.go
- temperature.go
- thermostat.go
- traffic_mon.go
- utf.go