aha

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Dec 28, 2025 License: MIT Imports: 12 Imported by: 0

README

AHA HTTP Interface

Go wrapper for the AVM Home Automation HTTP Interface.

API Background

AHA HTTP Interface (/webservices/homeautoswitch.lua)

  • XML-based, available since FRITZ!OS 5.53
  • AVM Documentation
  • Somewhat difficult to work with, missing some functionality

Usage

import (
    "github.com/ByteSizedMarius/go-fritzbox-api"
    "github.com/ByteSizedMarius/go-fritzbox-api/aha"
)

client := fritzbox.New("username", "password")
client.Connect()

// Get all devices
deviceList, err := aha.GetDeviceList(client)

// Find device with specific capability
for _, device := range deviceList.Devices {
    if device.HasCapability(aha.CHKR) {
        hkr := aha.GetCapability[*aha.Hkr](device)

        // Read temperature
        temp, _ := hkr.DECTGetSoll(client)

        // Set temperature
        hkr.DECTSetSoll(client, 21.5)
    }
}

Capabilities

Constant Type Description
CHanfun *HanFun HAN-FUN device
CButton *ButtonDevice Button device (e.g., FRITZ!DECT 440)
CHKR *Hkr Radiator thermostat (Heizkörperregler)
CTempSensor *Temperature Temperature sensor

Many capability types (lights, sockets, blinds, etc.) are not yet implemented - only devices I actually own are supported for now. PRs are welcome.

HKR (Radiator Thermostat)

See HKR Documentation for comprehensive coverage of:

  • Temperature presets (comfort/reduced)
  • Operating modes (boost, window open, summer, holiday)
  • Timer schedules and locks
  • API comparison (AHA vs REST)

Key Types

  • DeviceList - List of all AHA devices
  • Device - Individual device with capabilities
  • Capability - Interface for device features

API Pattern

Methods prefixed with DECT make network requests:

temp, err := hkr.DECTGetSoll(client)  // network request

Methods without prefix read cached values from the struct:

temp := hkr.GetSoll()  // local read, no network

Call hkr.Reload(client) to refresh cached values after external changes.

Documentation

Overview

Package aha is a Go-Wrapper for the AHA HTTP Interface (AVM Home Automation HTTP Interface)

Index

Constants

View Source 
const (
	TempOff = 253 // radiator off (snowflake)
	TempMax = 254 // radiator max

	CHanfun           = "HAN-FUN Gerät"
	CLicht            = "Licht/Lampe"
	CAlarm            = "Alarm-Sensor"
	CButton           = "AVM-ButtonDevice"
	CHKR              = "Heizkörperregler"
	CEnergieMesser    = "Energie Messgerät"
	CTempSensor       = "Temperatursensor"
	CSteckdose        = "Schaltsteckdose"
	CRepeater         = "AVM DECT Repeater"
	CMikrofon         = "Mikrofon"
	CHanfunUnit       = "HAN-FUN-Units" // Sozusagen das "Kind" des Han-Fun-Geräts
	CSchaltbar        = "an-/ausschaltbares Gerät/Steckdose/Lampe/Aktor"
	CDimmbar          = "Gerät mit einstellbarem Dimm-, Höhen- bzw. Niveau-Level"
	CLampeMitFarbtemp = "Lampe mit einstellbarer Farbe/Farbtemperatur"
	CRollladen        = "Rollladen(Blind) - hoch, runter, stop und level 0% bis 100 %"

	EvTastendruckKurz = "kurz"
	EvTastendruckLang = "lang"
)

Beschreibung inkl. Fehler aus der Doku übernommen ;)

Variables

This section is empty.

Functions

func GetCapability 

func GetCapability[C Capability](d Device) (r C)

GetCapability returns the capability of the given type for the device.

func GetDeviceInfos 

func GetDeviceInfos(c *fritzbox.Client, identifier string, dest Capability) (err error)

GetDeviceInfos fetches the device information from the fritzbox and unmarshals the response into the given Capability. Note: For HanFun devices, this only fetches the parent device. HanFun units (child devices) are not populated. Use GetDeviceList to get HanFun devices with their units.

func GetDeviceInfosRaw 

func GetDeviceInfosRaw(c *fritzbox.Client, identifier string) (res json.RawMessage, err error)

GetDeviceInfosRaw fetches the device information from the fritzbox and returns the raw response converted to json.

Types

type Alert 

type Alert struct {
	State          string `json:"state"`
	LastChangeTime string `json:"lastalertchgtimestamp"`
}

func (Alert) GetLastAlertTimestamp 

func (hfa Alert) GetLastAlertTimestamp() time.Time

GetLastAlertTimestamp converts the last change timestamp into go time struct

func (Alert) IsAlertActive 

func (hfa Alert) IsAlertActive() bool

IsAlertActive returns true if alert is active

func (Alert) String 

func (hfa Alert) String() string

String returns a string representation of the alert

type Button 

type Button struct {
	ID                   string `json:"-id"`
	Type                 string
	Name                 string `json:"name"`
	Identifier           string `json:"-identifier"`
	LastPressedTimeStamp string `json:"lastpressedtimestamp"`
}

Button is a part of the ButtonDevice capability A ButtonDevice can have multiple buttons

func (Button) GetLastPressTime 

func (bp Button) GetLastPressTime() time.Time

GetLastPressTime converts the last-press-time string to a time-struct

func (Button) String 

func (bp Button) String() string

type ButtonDevice 

type ButtonDevice struct {
	CapName    string
	Buttons    []Button
	Batterylow string
	Battery    string
	// contains filtered or unexported fields
}

ButtonDevice is the capability for a button

func (*ButtonDevice) Device 

func (b *ButtonDevice) Device() *Device

Device returns the device the capability belongs to

func (*ButtonDevice) Name 

func (b *ButtonDevice) Name() string

Name returns the name of the capability

func (*ButtonDevice) Reload 

func (b *ButtonDevice) Reload(c *fritzbox.Client) error

Reload reloads all client values

func (*ButtonDevice) String 

func (b *ButtonDevice) String() string

String returns a string representation of the capability

type Capabilities 

type Capabilities map[string]Capability

Capabilities is a map of the capabilities available for the device. They can be access using the Capability-Constants (starting with C, for example CHKR -> HeizungsKörperRegler, etc.) HasCapability can be used to check whether a device has a certain capability, without checking the map-keys.

func (Capabilities) String 

func (c Capabilities) String() string

String returns a string representation of the capabilities

type Capability 

type Capability interface {
	Name() string
	String() string
	Device() *Device
	// contains filtered or unexported methods
}

Capability is the interface for all capabilities. It is self-contained in that it has a reference to the device it belongs to.

type ColorControl 

type ColorControl struct {
}

func (ColorControl) String 

func (hfcc ColorControl) String() string

type Device 

type Device struct {
	Identifier   string
	ID           string
	Fwversion    string
	Manufacturer string
	Productname  string
	Txbusy       string
	Name         string
	Present      string
	Capabilities Capabilities
}

Device is the main type for aha-devices. It holds the values all devices have; all other properties are handled via the respective capabilities.

func (*Device) DECTGetName 

func (d *Device) DECTGetName(c *fritzbox.Client) (response string, err error)

DECTGetName fetches device-Name from the fritzbox and updates internally stored value.

func (*Device) DECTIsSwitchPresent 

func (d *Device) DECTIsSwitchPresent(c *fritzbox.Client) (bool, error)

DECTIsSwitchPresent fetches the connection status from the fritzbox and updates the objects internal value. Note: According to the documentation, it may take multiple minutes for the status to update after a device disconnects.

func (*Device) DECTSetName 

func (d *Device) DECTSetName(c *fritzbox.Client, name string) error

DECTSetName updates device Name based on identifier and updates internal values if successful.

func (*Device) HasCapability 

func (d *Device) HasCapability(cap string) bool

HasCapability returns true, if device has given capability. Use capability-constants.

func (*Device) IsSwitchPresent 

func (d *Device) IsSwitchPresent() bool

IsSwitchPresent returns true if device is present.

func (*Device) String 

func (d *Device) String() string

type DeviceList 

type DeviceList struct {
	Version   string
	Fwversion string
	Devices   []Device
	// contains filtered or unexported fields
}

func GetDeviceList 

func GetDeviceList(c *fritzbox.Client) (*DeviceList, error)

GetDeviceList implements the getdevicelistinfos endpoint of the AHA-API and returns a DeviceList.

func GetDeviceListFilter 

func GetDeviceListFilter(c *fritzbox.Client, cap Capability) (dl *DeviceList, err error)

func (*DeviceList) String 

func (dl *DeviceList) String() string

String returns a string representation of the DeviceList.

type ETSIUnitInfo 

type ETSIUnitInfo struct {
	ETSIDeviceID string `json:"etsideviceid"`
	Interface    string `json:"interfaces"`
	UnitType     string `json:"unittype"`
}

func (ETSIUnitInfo) GetInterfaceString 

func (e ETSIUnitInfo) GetInterfaceString() string

GetInterfaceString returns the units interface-type as a string (values taken from documentation)

func (ETSIUnitInfo) GetUnitString 

func (e ETSIUnitInfo) GetUnitString() string

GetUnitString returns the units type as a string (values taken from documentation)

func (ETSIUnitInfo) String 

func (e ETSIUnitInfo) String() string

type HFSuotaUpdate 

type HFSuotaUpdate struct {
}

func (HFSuotaUpdate) String 

func (hfsu HFSuotaUpdate) String() string

type HanFun 

type HanFun struct {
	CapName string
	Units   Units // A single HanFun-Device can potentially consist of multiple units
	// contains filtered or unexported fields
}

HanFun is the capability for a HanFun-Device HanFun is an open standard for smart home devices and is supported by the Fritz!Box

func (*HanFun) Device 

func (hf *HanFun) Device() *Device

Device returns the device the capability is attached to

func (*HanFun) GetInterface 

func (hf *HanFun) GetInterface(i Interface) interface{}

GetInterface returns a pointer to the requested interface if present, nil if not. For example: [...].GetInterface(Alert{}).(Alert)

func (*HanFun) HasInterface 

func (hf *HanFun) HasInterface(i Interface) bool

HasInterface returns true, if the given HanFun-Interface is present in the current devices' units For example: [...].HasInterface(Alert{})

func (*HanFun) Name 

func (hf *HanFun) Name() string

Name returns the name of the capability

func (*HanFun) Reload 

func (hf *HanFun) Reload(c *fritzbox.Client) error

Reload reloads the device itself and all its units.

func (*HanFun) String 

func (hf *HanFun) String() string

String returns a string representation of the capability

type Hkr 

type Hkr struct {
	CapName                 string
	Tsoll                   string `json:"tsoll"`
	Absenk                  string `json:"absenk"`
	Komfort                 string `json:"komfort"`
	Lock                    string `json:"lock"`                    // Keylock (Tastensperre) configurated via Web-UI/API, activated automatically if summeractive or holdidayactive
	Devicelock              string `json:"devicelock"`              // Same as lock, configurated manually on the device itself
	Errorcode               string `json:"errorcode"`               // 0 = no error
	Windowopenactiv         string `json:"windowopenactiv"`         // 1 if window currently detected as open. The typo is part of the official API.
	Windowopenactiveendtime string `json:"windowopenactiveendtime"` // time in seconds until radiator turns back on
	Boostactive             string `json:"boostactive"`             // same as window
	Boostactiveendtime      string `json:"boostactiveendtime"`      // same as window
	Batterylow              string `json:"batterylow"`              // 1 if battery low
	Battery                 string `json:"battery"`                 // battery %
	Nextchange              struct {
		Endperiod string `json:"endperiod"`
		Tchange   string `json:"tchange"`
	} `json:"nextchange"`
	Summeractive  string `json:"summeractive"`  // 1 if summer is currently active
	Holidayactive string `json:"holidayactive"` // same as summer
	// contains filtered or unexported fields
}

Hkr is the struct for HeizungsKörperRegler. Note: current temperature can be accessed via the temperature-capability.

func (*Hkr) DECTDeactivateBoost 

func (h *Hkr) DECTDeactivateBoost(c *fritzbox.Client) error

DECTDeactivateBoost turns boost off if currently enabled

func (*Hkr) DECTDeactivateWindowOpen 

func (h *Hkr) DECTDeactivateWindowOpen(c *fritzbox.Client) error

func (*Hkr) DECTGetAbsenk 

func (h *Hkr) DECTGetAbsenk(c *fritzbox.Client) (string, error)

DECTGetAbsenk is similar to DECTGetSoll

func (*Hkr) DECTGetAbsenkNumeric 

func (h *Hkr) DECTGetAbsenkNumeric(c *fritzbox.Client) (float64, error)

DECTGetAbsenkNumeric is similar to DECTGetSollNumeric

func (*Hkr) DECTGetKomfort 

func (h *Hkr) DECTGetKomfort(c *fritzbox.Client) (string, error)

DECTGetKomfort is similar to DECTGetSoll

func (*Hkr) DECTGetKomfortNumeric 

func (h *Hkr) DECTGetKomfortNumeric(c *fritzbox.Client) (float64, error)

DECTGetKomfortNumeric is similar to DECTGetSollNumeric

func (*Hkr) DECTGetSoll 

func (h *Hkr) DECTGetSoll(c *fritzbox.Client) (r string, err error)

DECTGetSoll sends an API-Request to get the current soll-temperature from the fritzbox/device itself. It will then update the current device locally and return the same output as GetSoll.

func (*Hkr) DECTGetSollNumeric 

func (h *Hkr) DECTGetSollNumeric(c *fritzbox.Client) (float64, error)

DECTGetSollNumeric does the same as DECTGetSoll but returns the result like GetSollNumeric

func (*Hkr) DECTSetSoll 

func (h *Hkr) DECTSetSoll(c *fritzbox.Client, sollTemp any) error

DECTSetSoll sets the soll temperature to the given temperature (meaning 21.5 = 21.5 C). This method accepts float64/32, int and string (XX,X/ XX.X). Values with additional decimal places will be rounded to XX.0/XX.5 respectively. Only values from 8-28 are valid.

func (*Hkr) DECTSetSollMax 

func (h *Hkr) DECTSetSollMax(c *fritzbox.Client) error

DECTSetSollMax turns the soll-temperature on. Allegedly, it should use the last known temperature. However, for me, it just sets the radiator to MAX.

func (*Hkr) DECTSetSollOff 

func (h *Hkr) DECTSetSollOff(c *fritzbox.Client) error

DECTSetSollOff turns the soll-temperature off. The Hkr will show the snowflake in its display.

func (*Hkr) DECTSetWindowOpen 

func (h *Hkr) DECTSetWindowOpen(c *fritzbox.Client, d time.Duration) (tm time.Time, err error)

func (*Hkr) Device 

func (h *Hkr) Device() *Device

func (*Hkr) GetAbsenk 

func (h *Hkr) GetAbsenk() (r string)

GetAbsenk is similar to GetSoll

func (*Hkr) GetAbsenkNumeric 

func (h *Hkr) GetAbsenkNumeric() float64

GetAbsenkNumeric is similar to GetSollNumeric

func (*Hkr) GetBoostEndtime 

func (h *Hkr) GetBoostEndtime() time.Time

GetBoostEndtime converts the endtime to a time-struct

func (*Hkr) GetErrorString 

func (h *Hkr) GetErrorString() string

GetErrorString returns the error-message for the respective error-code. Errorcode 0 means no error. The error-messages originate from the official docs.

func (*Hkr) GetKomfort 

func (h *Hkr) GetKomfort() (r string)

GetKomfort is similar to GetSoll

func (*Hkr) GetKomfortNumeric 

func (h *Hkr) GetKomfortNumeric() float64

GetKomfortNumeric is similar to GetSollNumeric

func (*Hkr) GetNextChangeTemperature 

func (h *Hkr) GetNextChangeTemperature() string

GetNextChangeTemperature returns the temperature, that the next change will set it to (as string)

func (*Hkr) GetNextChangeTemperatureNumeric 

func (h *Hkr) GetNextChangeTemperatureNumeric() float64

GetNextChangeTemperatureNumeric returns the temperature, that the next change will set it to (numeric)

func (*Hkr) GetNextchangeEndtime 

func (h *Hkr) GetNextchangeEndtime() time.Time

GetNextchangeEndtime returns the time of the next temperature-change

func (*Hkr) GetSoll 

func (h *Hkr) GetSoll() (r string)

GetSoll returns the same values as GetSollNumeric, but as a string. Instead of -1 and -2, it returns "OFF" or "MAX"

func (*Hkr) GetSollNumeric 

func (h *Hkr) GetSollNumeric() float64

GetSollNumeric returns the current locally saved soll-temperature. It returns temperatures in Celsius from 8-28, as well as -1 (MAX) -2 (OFF).

func (*Hkr) GetWindowOpenEndtime 

func (h *Hkr) GetWindowOpenEndtime() time.Time

func (*Hkr) IsBatteryLow 

func (h *Hkr) IsBatteryLow() bool

IsBatteryLow returns true if the device reports battery low

func (*Hkr) IsBoostActive 

func (h *Hkr) IsBoostActive() bool

IsBoostActive returns true, if the boost is currently active

func (*Hkr) IsHolidayActive 

func (h *Hkr) IsHolidayActive() bool

IsHolidayActive returns true, if holiday-mode is currently active

func (*Hkr) IsSummerActive 

func (h *Hkr) IsSummerActive() bool

IsSummerActive returns true, if summer-mode is currently active

func (*Hkr) IsWindowOpen 

func (h *Hkr) IsWindowOpen() bool

func (*Hkr) Name 

func (h *Hkr) Name() string

func (*Hkr) Reload 

func (h *Hkr) Reload(c *fritzbox.Client) error

Reload reloads all client values

func (*Hkr) SetBoost 

func (h *Hkr) SetBoost(c *fritzbox.Client, d time.Duration) (tm time.Time, err error)

SetBoost activates the radiators boost-function for the specified duration (max. 24hrs). Returns the end-time of the boost.

func (*Hkr) String 

func (h *Hkr) String() string

type Interface 

type Interface interface {
	String() string
	// contains filtered or unexported methods
}

type KeepAlive 

type KeepAlive struct {
}

func (KeepAlive) String 

func (hfka KeepAlive) String() string

type LevelControl 

type LevelControl struct {
}

func (LevelControl) String 

func (hflc LevelControl) String() string

type OnOff 

type OnOff struct {
}

func (OnOff) String 

func (hfoo OnOff) String() string

type OpenClose 

type OpenClose struct {
}

func (OpenClose) String 

func (hfoc OpenClose) String() string

type OpenCloseConfig 

type OpenCloseConfig struct {
}

func (OpenCloseConfig) String 

func (hfocc OpenCloseConfig) String() string

type SimpleButton 

type SimpleButton struct {
}

func (SimpleButton) String 

func (hfsb SimpleButton) String() string

type Temperature 

type Temperature struct {
	CapName string
	Celsius string `json:"celsius"`
	Offset  string `json:"offset"`
	// contains filtered or unexported fields
}

Temperature is the struct for the temperature capability.

func (*Temperature) DECTGetCelsiusNumeric 

func (t *Temperature) DECTGetCelsiusNumeric(c *fritzbox.Client) (float64, error)

DECTGetCelsiusNumeric is the same as GetCelsiusNumeric, but it will fetch the current value from the fritzbox and update the local state of the device before returning.

func (*Temperature) DECTGetDeviceStats 

func (t *Temperature) DECTGetDeviceStats(c *fritzbox.Client) (ts TemperatureStats, err error)

DECTGetDeviceStats returns the temperatures measured from the device in the last 24 hours

func (*Temperature) Device 

func (t *Temperature) Device() *Device

Device returns the device the capability belongs to

func (*Temperature) GetCelsiusNumeric 

func (t *Temperature) GetCelsiusNumeric() float64

GetCelsiusNumeric returns the temperature reading in float converted to the usual format (eg. 21.5)

func (*Temperature) GetOffsetNumeric 

func (t *Temperature) GetOffsetNumeric() float64

GetOffsetNumeric returns the temperature offset set for the device in float converted to the usual format (eg. 21.5)

func (*Temperature) Name 

func (t *Temperature) Name() string

Name returns the name of the capability

func (*Temperature) Reload 

func (t *Temperature) Reload(c *fritzbox.Client) error

Reload fetches the current device and updates the current capability

func (*Temperature) String 

func (t *Temperature) String() string

String returns a string representation of the capability

type TemperatureStats 

type TemperatureStats struct {
	Values                     []float64
	AmountOfValues             int
	SecondsBetweenMeasurements int
}

TemperatureStats is the struct for the temperature statistics. It contains the temperature values, often from the last 24 hours, the amount of values and the amount of seconds between measurements.

func (TemperatureStats) String 

func (ts TemperatureStats) String() string

String returns a string representation of the temperature statistics

type Unit 

type Unit struct {
	// Saves all properties of the unit in raw json-messages.
	// Does not include values already represented (values present in the device-struct, as well as etsi-unit-info)
	// This allows access to functionality that may not yet be implemented.
	RawProperties map[string]json.RawMessage
	ETSIUnitInfo  ETSIUnitInfo
	Interface     Interface
	// contains filtered or unexported fields
}

Unit is a generic struct for a hanfun unit Hanfun is an open standard for smart home devices by the ULE Alliance that seems to be mostly dead in the water.

func (*Unit) Device 

func (h *Unit) Device() *Device

Device returns the device the unit is associated with

func (*Unit) FromJSON 

func (*Unit) FromJSON(m map[string]json.RawMessage, d *Device) (*Unit, error)

FromJSON parses the json into a HanFun-Unit

func (*Unit) GetRawProperties 

func (h *Unit) GetRawProperties() (s map[string]string, err error)

GetRawProperties returns the local interface-values as a string in json.

func (*Unit) IsUnitOfType 

func (h *Unit) IsUnitOfType(t Interface) bool

IsUnitOfType returns true if the unit's interface is of the given type For example [...].IsUnitOfType(Alert{})

func (*Unit) Reload 

func (h *Unit) Reload(c *fritzbox.Client) error

Reload fetches the device-information for this unit from the fritzbox and updates the structs' values

func (*Unit) String 

func (h *Unit) String() string

String returns a string representation of the unit

func (*Unit) UnmarshalProperty 

func (h *Unit) UnmarshalProperty(propertyKey string, dest Interface) error

UnmarshalProperty unmarshals a property into the given interface

type Units 

type Units []*Unit

func (Units) String 

func (hfus Units) String() string

String returns a string representation of the units

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.