livebox

README

Livebox API client

This Go library makes it easy to communicate with Livebox's API. This API is usually available at http://192.168.1.1/ws. Authentication is handled by the library, set the admin password and start sending requests.

It was tested with a Livebox 5. Other Livebox models might not be supported.

Usage

Get the library by running the following command:

go get -u github.com/Tomy2e/livebox-api-client

Import the library in your source file:

import "github.com/Tomy2e/livebox-api-client"
import "github.com/Tomy2e/livebox-api-client/api/request"

Create a new client:

// Client with default HTTP client
client, _ := livebox.NewClient("<admin-password>")

// Client with custom HTTP client
client, _ := livebox.NewClient("<admin-password>", livebox.WithHTTPClient(&http.Client{}))

Send requests using the client:

var r json.RawMessage

_ = client.Request(
    context.Background(),
    request.New("TopologyDiagnostics", "buildTopology", map[string]interface{}{"SendXmlFile": false}),
    &r,
)

fmt.Println(string(r))

Livebox CLI Usage

The livebox-cli tool allows to easily send requests to the Livebox API. It writes the JSON responses to stdout.

Pre-built binaries are available in the Releases section. If you have Go installed, you can run it with:

go run github.com/Tomy2e/livebox-api-client/cmd/livebox-cli

Options

The tool accepts the following command-line options:

Name	Description	Default value
-service	Livebox service
-method	Method to use
-params	Optional JSON-encoded params

The tool reads the following environment variables:

Name	Description	Default value
ADMIN_PASSWORD	Password of the Livebox "admin" user.

Documentation

Overview

Package livebox provides a client to easily communicate with Livebox 5's API.

This API is usually available at `http://192.168.1.1/ws`. Authentication is handled by the library, set the `admin` password and start sending requests.

Index

• Constants
• Variables
• type Client
  • func NewClient(password string, opts ...Opt) (*Client, error)
  • func (c *Client) Events(ctx context.Context, events []string) <-chan *response.Event
  • func (c *Client) Request(ctx context.Context, req *request.Request, out any) error
• type Opt
  • func WithAddress(address string) Opt
  • func WithHTTPClient(httpClient *http.Client) Opt
  • func WithLogger(log *slog.Logger) Opt
  • func WithUsername(username string) Opt

Constants

const (
	DefaultAddress  = "http://192.168.1.1"
	DefaultUsername = "admin"
)

Variables

var ErrInvalidCredentials = client.ErrInvalidCredentials

ErrInvalidCredentials is returned when the login is not successful because the login or password is invalid.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a Livebox API Client. Requests sent using a client will be automatically authenticated using the specified password. Client is thread safe.

func NewClient

func NewClient(password string, opts ...Opt) (*Client, error)

NewClient returns a new Client that will be authenticated using the given password.

func (*Client) Events

func (c *Client) Events(ctx context.Context, events []string) <-chan *response.Event

Events watches the specified events until context is canceled.

func (*Client) Request

func (c *Client) Request(ctx context.Context, req *request.Request, out any) error

Request sends a request to the Livebox API. If the client is not yet authenticated, or the session is expired, the client will try to authenticate using the admin password given during the creation of the client.

type Opt

type Opt func(c *clientOpts)

Opt is a Livebox client option.

func WithAddress

func WithAddress(address string) Opt

WithAddress allows using a custom Livebox address. If not used, the Livebox address is set to http://192.168.1.1.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Opt

WithHTTPClient allows using a custom http client. If not used, the Go default HTTP client is used.

func WithLogger

func WithLogger(log *slog.Logger) Opt

WithLogger attaches a logger to the client. Logging is disabled if unset.

func WithUsername

func WithUsername(username string) Opt

WithUsername sets the username that will be used to authenticate. Defaults to "admin" if not specified.