liveboxapi

A synchronous Python client for Orange Livebox routers — the JSON-RPC "sah" protocol their web interface speaks. Read the state, change the settings, and ask the box itself what else it can do.

Unofficial. Not affiliated with, endorsed by, or supported by Orange or Sagemcom. Livebox is a trademark of Orange; it is used here only to say which device this talks to.

from liveboxapi import Livebox

with Livebox(password="…") as box:
    print(box.network.wan_status().ipv4)
    print(box.system.uptime())

    for lease in box.dhcp.static_leases():
        print(lease.ip, lease.mac)

$ livebox health
WAN            up  203.0.113.42
IPv6 prefix    2001:db8:1234:5600::/56
GPON           O5_Operation  rx -18.53 dBm  tx 2.14 dBm  58.0 °C
IPTV / VoIP    Available / Up
Missed calls   0
Firmware       SGW7-fr-G03.R09.C02_02
Uptime         14.4 days

Install

pip install liveboxapi

Only dependency: requests.

Credentials

Never in your code. The client resolves them, in order:

1. what you pass — Livebox(password="…");
2. the environment — LIVEBOX_PASSWORD, plus optional LIVEBOX_URL and LIVEBOX_USER; this is the path for a systemd unit or a container;
3. the 1Password command line — set LIVEBOX_OP_ITEM to the item name or uuid and LIVEBOX_OP_VAULT to its vault, and the client shells out to op.

Add your own store by appending to liveboxapi.credentials.RESOLVERS.

The factory password is the first eight characters of the Wi-Fi key printed on the label — which means anyone who has seen the back of the router knows it. Change it, and keep the new one in a password manager.

Read-only by default, when you want it

Writing to a home gateway is disruptive in ways that are hard to undo. Open the session read-only and any set*, add* or delete* raises before it reaches the network:

with Livebox(password="…", readonly=True) as box:
    box.firewall.set_upnp(False)   # ReadOnlyError

The livebox command does this on its own: read subcommands open a read-only session, and only the subcommands that name a change can write.

What it covers

Anything not wrapped is one call away: box.call(service, method, params).

Two things this does differently

Batch. Opening a session costs a round trip and a password check. Twenty readings, twenty sessions, several minutes. The same twenty in one session take seconds:

state = box.batch([
    {"key": "wan", "service": "NMC", "method": "getWANStatus"},
    {"key": "upnp", "service": "UPnP-IGD", "method": "get"},
    {"key": "leases", "service": "DHCPv4.Server.Pool.default", "method": "getStaticLeases"},
])

Introspection. The box describes itself — every method of every object, with its signature. That is the difference between guessing an API from a post written for another model and reading it off the device in front of you:

$ livebox functions Firewall --writes
setFirewallLevel(string level)
setPortForwarding(string id, string origin, string sourceInterface, …)
setPinhole(string id, string origin, …)
deleteDMZ(string id)
commit()

Existing tooling believes the operator disabled this from the Wi-Fi 7 model onwards, and gates it on the model number without retesting. On a Livebox W7 running SGW7-fr-G03.R09, the same REST route answers normally, full subtree included. If it fails on yours, please open an issue with your firmware string.

Alternatives, honestly

Two other projects cover this ground, both actively maintained, and you should pick on merit:

• aiosysbus — asynchronous, very broad coverage, GPL-3.0. The right choice for asyncio code, and what the Home Assistant community component uses.
• LiveboxMonitor — a full graphical application, MIT, with a reusable API layer inside. The right choice if you want a user interface rather than a library.

liveboxapi exists for the case neither covers: a small synchronous library, under a permissive licence, with no GUI toolkit in its dependency tree, usable from a cron job, an Ansible task or a monitoring script.

Documentation

Long form in docs/DOC.md, runnable scripts in examples/.

Licence

MIT. See LICENSE.