README
¶
go-fritzbox-api
Go client library for AVM FRITZ!Box routers and smart home devices.
Attribution
- Authentication based on Philipp Franke's go-fritzbox
- Window detector support based on contribution by @btwotch
Installation
go get github.com/ByteSizedMarius/go-fritzbox-api/v2
Quick Start
package main
import (
"fmt"
"github.com/ByteSizedMarius/go-fritzbox-api/v2"
"github.com/ByteSizedMarius/go-fritzbox-api/v2/smart"
)
func main() {
client := fritzbox.New("username", "password")
if err := client.Connect(); err != nil {
panic(err)
}
thermostats, _ := smart.GetAllThermostats(client)
for _, t := range thermostats {
fmt.Printf("%s: %.1f°C\n", t.Name, t.CurrentTemp)
}
}
Or run the example CLI directly:
go run github.com/ByteSizedMarius/go-fritzbox-api/v2/smart/examples/thermostat@latest -user=admin -pass=secret
See smart/README.md for the full API, examples, and thermostat concepts.
Packages
| Package | API | Description |
|---|---|---|
smart/ |
REST | Wrapper for rest/ with nicer API for selected functionality |
rest/ |
REST | JSON API, generated types (FRITZ!OS 8.20+) |
unsafe/ |
data.lua | Router internals (unstable) |
aha/ |
AHA HTTP | (Legacy) XML API for DECT devices |
Scope
Currently supported device types:
- Thermostats - full support (state, config, schedules, holidays)
- Buttons - partial support
- Window detectors - state and thermostat linking
- Temperature sensors - read-only
If you own any of the missing devices and would like to help with implementation, please let me know!
API Landscape
FRITZ!Box has two official smart home APIs:
- Smart Home REST API (
/api/v0/smarthome/...): JSON-based, requires FRITZ!OS 8.20+. More comprehensive; OpenAPI spec - AHA HTTP Interface (
/webservices/homeautoswitch.lua): XML-based, available since FRITZ!OS 5.53; Docs
Compatibility
Tested with FRITZ!OS 8.21 on the 6690 Cable. Smart home implementations (DECT) are stable across versions and routers. Endpoints in the unsafe/ package may break between firmware versions.
Breaking changes are possible in v2.X, but will always be released with a new tag.
Contributing
Issues, Pull Requests and E-Mails are welcome.
Documentation
¶
Overview ¶
Package fritzbox provides a client for interacting with AVM FRITZ!Box routers.
Index ¶
- Variables
- func Pow(n, m int) int
- func ValueFromJsonPath(body string, pathKeys []string) (v map[string]interface{}, err error)
- type Client
- func (c *Client) AhaRequest(method, path string, data Values) (*http.Response, error)
- func (c *Client) AhaRequestString(method, path string, data Values) (int, string, error)
- func (c *Client) AhaRequestXML(method, path string, data Values, target any) error
- func (c *Client) CheckExpiry() error
- func (c *Client) Close()
- func (c *Client) Connect() error
- func (c *Client) IsConnected() bool
- func (c *Client) IsExpired() bool
- func (c *Client) RestDelete(path string) ([]byte, int, error)
- func (c *Client) RestGet(path string) ([]byte, int, error)
- func (c *Client) RestPost(path string, body any) ([]byte, int, error)
- func (c *Client) RestPut(path string, body any) ([]byte, int, error)
- func (c *Client) RestRequest(method, path string, body any) ([]byte, int, error)
- func (c *Client) SID() string
- func (c *Client) SetHTTPClient(client *http.Client)
- func (c *Client) String() string
- type Values
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidCredentials = errors.New("invalid credentials")
Functions ¶
Types ¶
type Client ¶
type Client struct {
BaseUrl string
Username string
Password string
// contains filtered or unexported fields
}
Client handles authentication and communication with the FRITZ!Box.
func New ¶
New creates a new client with the given credentials. Call Connect() to authenticate with the FRITZ!Box.
func (*Client) AhaRequest ¶
AhaRequest sends a form-encoded request to the FRITZ!Box. GET: data as query parameters. POST: data as form body.
func (*Client) AhaRequestString ¶
AhaRequestString sends a request and returns the response body as a string.
func (*Client) AhaRequestXML ¶
AhaRequestXML sends a request and decodes the XML response into target.
func (*Client) CheckExpiry ¶
CheckExpiry reconnects if the session is expired or not connected.
func (*Client) Close ¶
func (c *Client) Close()
Close terminates the session and releases resources.
func (*Client) Connect ¶
Connect initializes and authenticates the client. If already connected, the existing session is closed first.
func (*Client) IsConnected ¶
IsConnected returns true if the client has an active session.
func (*Client) RestDelete ¶
RestDelete sends a DELETE request to the REST API.
func (*Client) RestRequest ¶
RestRequest sends a JSON request to the FRITZ!Box REST API. Body is JSON-marshaled for PUT/POST requests. Pass nil for GET/DELETE.
func (*Client) SetHTTPClient ¶
SetHTTPClient sets a custom HTTP client. Must be called before Connect().
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package aha is a Go-Wrapper for the AHA HTTP Interface (AVM Home Automation HTTP Interface)
|
Package aha is a Go-Wrapper for the AHA HTTP Interface (AVM Home Automation HTTP Interface) |
|
Package rest provides access to FRITZ!Box Smart Home features via the REST API.
|
Package rest provides access to FRITZ!Box Smart Home features via the REST API. |
|
Package smart provides high-level helpers for the rest package.
|
Package smart provides high-level helpers for the rest package. |
|
examples/thermostat
command
|
|