fritz

package
v1.4.22 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 12, 2018 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package fritz contains the main clients for interacting with the fritz box.

Index

Examples

Constants

This section is empty.

Variables

View Source 
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 BoxData added in v1.4.18 

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 Call added in v1.4.18 

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 Client added in v1.4.9 

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 added in v1.4.9 

func NewClient(configfile string) (*Client, error)

NewClient creates a new Client with values read from a config file, given by the parameter configfile. Deprecated: use NewClientFromConfig.

func NewClientFromConfig added in v1.4.19 

func NewClientFromConfig(cfg *config.Config) *Client

NewClientFromConfig creates a new Client with the passed configuration.

func (*Client) Login added in v1.4.9 

func (client *Client) Login() error

Login tries to login into the box and obtain the session id.

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 measurment 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.
}

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) IsSwitch added in v1.4.6 

func (d *Device) IsSwitch() bool

IsSwitch returns true if the device is recognized to be a switch and returns false otherwise.

func (*Device) IsThermostat added in v1.4.6 

func (d *Device) IsThermostat() bool

IsThermostat returns true if the device is recognized to be a HKR device and returns false otherwise.

type DeviceGroup added in v1.4.13 

type DeviceGroup struct {
	Group   Group
	Devices []Device
}

DeviceGroup is an inflated version of one Group with multiple Device members.

type Devicelist 

type Devicelist struct {
	Devices []Device `xml:"device"`
	Groups  []Group  `xml:"group"`
}

Devicelist wraps a list of devices. This corresponds to the outer layer of the xml that the FRITZ!Box returns.

func (*Devicelist) DeviceGroups added in v1.4.13 

func (l *Devicelist) DeviceGroups() []DeviceGroup

DeviceGroups returns a slice of DeviceGroup by joining Group.Members() on Device.ID.

func (*Devicelist) DeviceWithID added in v1.4.13 

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 added in v1.4.13 

func (l *Devicelist) NamesAndAins() map[string]string

NamesAndAins returns a lookup name -> AIN.

func (*Devicelist) Switches added in v1.4.6 

func (l *Devicelist) Switches() []Device

Switches returns the devices which satisfy IsSwitch.

func (*Devicelist) Thermostats added in v1.4.6 

func (l *Devicelist) Thermostats() []Device

Thermostats returns the devices which satisfy IsThermostat.

type FirmwareVersion added in v1.4.18 

type FirmwareVersion struct {
	Image             string
	OsVersionMajor    string
	OsVersionMinor    string
	OsVersionRevision string
}

FirmwareVersion represent the FRITZ!OS version.

func (FirmwareVersion) String added in v1.4.18 

func (v FirmwareVersion) String() string

String returns a textual representation of FirmwareVersion.

type Group added in v1.4.13 

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 added in v1.4.13 

func (g *Group) MadeFromSwitches() bool

MadeFromSwitches returns true if the devices consist of switches.

func (*Group) MadeFromThermostats added in v1.4.13 

func (g *Group) MadeFromThermostats() bool

MadeFromThermostats returns true if the devices consist of thermostats.

func (*Group) Members added in v1.4.13 

func (g *Group) Members() []string

Members returns a slice of internal IDs corresponding to the device members that belong to this group.

type GroupInfo added in v1.4.13 

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 added in v1.4.9 

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/bpicode/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 added in v1.4.9 

func NewHomeAuto(options ...Option) HomeAuto

NewHomeAuto a HomeAuto that communicates with the FRITZ!Box by means of the Home Automation HTTP Interface.

type Internal added in v1.4.6 

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 added in v1.4.17 

func NewInternal(client *Client) Internal

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 Message 

type Message []string

Message corresponds to a single log message.

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 Model added in v1.4.18 

type Model struct {
	Name     string
	Annex    string
	Branding string
}

Model contains information about the type of the box.

func (Model) String added in v1.4.18 

func (m Model) String() string

String returns a textual representation of Model.

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 added in v1.4.6 

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 added in v1.4.6 

func (n *NextChange) FmtTimestamp(ref time.Time) string

FmtTimestamp formats the epoch timestamp into a compact readable form. See fmtEpochSecondString.

type Option added in v1.4.9 

type Option func(h *homeAuto)

Option applies fine-grained configuration to the HomeAuto client.

func AuthEndpoint added in v1.4.9 

func AuthEndpoint(s string) Option

AuthEndpoint configures the the endpoint for authentication. The default is "/login_sid.lua".

func Caching added in v1.4.17 

func Caching(b bool) Option

Caching activates (or deactivates) caching of obtained data, such as the list of devices.

func Certificate added in v1.4.9 

func Certificate(bs []byte) Option

Certificate actives TLS verification of the FRITZ!Box server, where the certificate is explicitly specified as byte array, encoded in PEM format.

func Credentials added in v1.4.9 

func Credentials(username, password string) Option

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 added in v1.4.9 

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.

func URL added in v1.4.9 

func URL(u *url.URL) Option

URL sets the target host of the FRITZ!Box. Note that for usual setups, the url https://fritz.box:443 works.

type Phone added in v1.4.18 

type Phone interface {
	Calls() ([]Call, error)
}

Phone describes the supported operations.

func NewPhone added in v1.4.18 

func NewPhone(client *Client) Phone

NewPhone creates a client for interaction with the FB phone sector.

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 added in v1.4.6 

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 added in v1.4.6 

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 Rights added in v1.4.18 

type Rights struct {
	Names        []string `xml:"Name"`
	AccessLevels []string `xml:"Access"`
}

Rights wrap set of pairs (name, access-level).

type Runtime added in v1.4.18 

type Runtime struct {
	Hours   uint64
	Days    uint64
	Months  uint64
	Years   uint64
	Reboots uint64
}

Runtime contains data on how long the FRITZ!Box has been running.

func (Runtime) String added in v1.4.18 

func (r Runtime) String() string

String returns a textual representation of Runtime.

type SessionInfo added in v1.4.9 

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 added in v1.4.6 

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 added in v1.4.6 

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.
}

Thermostat models the "HKR" device. codebeat:disable[TOO_MANY_IVARS]

func (*Thermostat) FmtComfortTemperature added in v1.4.6 

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 added in v1.4.6 

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 added in v1.4.6 

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 added in v1.4.6 

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_current_bps"`
	DownStreamMedia         []float64 `json:"mc_current_bps"`
	UpstreamRealtime        []float64 `json:"prio_realtime_bps"`
	UpstreamHighPriority    []float64 `json:"prio_high_bps"`
	UpstreamDefaultPriority []float64 `json:"prio_default_bps"`
	UpstreamLowPriority     []float64 `json:"prio_low_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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.