eufy-home-security

Asyncio Python library and command-line tool for eufy Security systems. It talks to the HomeBase and its cameras directly over the local network, and uses eufy's cloud only for login, keys and push events. It is written for a Home Assistant integration, but it has no Home Assistant dependency and works on its own.

Status: beta, incomplete. This is a 0.x release. It works day to day on the hardware it was developed against, but device coverage is narrow, much of the device support is unproven, and the API may change in any release. Do not make it the only thing between you and an intruder: keep the eufy app installed. Not affiliated with Anker or eufy.

What it does

• Local P2P to the station: guard mode, status (battery, signal, storage, firmware), device settings, live video and audio, stored recordings and stills, the station's event history, and pan/tilt presets. Once connected, commands and state stay on your LAN.
• eufy cloud (the eufy_mega backend): login with the e-mailed code or captcha, the device list, the per-station keys a local session needs, and firmware-update notices.
• Push events over FCM: guard-mode changes made elsewhere (app, keypad, schedule), and events when the host is not on the station's LAN.
• A session cache, so a restart needs no cloud call.
• Per-model settings from eufy's own code: each product's settings (values, labels, units, how to write and read them) are generated from the thing description and handler the eufy app downloads, and ship with the library for 107 products.
• Every product the eufy app names: the model list (161 serial prefixes, with kind and cloud device type) is generated from the app's own tables, so a camera is recognised as a camera even when nobody has tested it.
• Support graded as data: every model and capability carries verified (proven on hardware), declared (from the eufy app, not proven) or unknown, with its source, so a consumer can tell what is proven.

Pure asyncio on aiohttp, cryptography, firebase-messaging and protobuf: no Node.js bridge, no add-on, no threads.

Status

The full picture is in the generated support matrix and the hardware verification page. A setting comes from eufy's code, not from a test on hardware: it may be rejected by a device, and the page names the ones written and read back.

Requirements

• Python 3.13 or newer.
• A eufy Security account that can see the station: the owner's, or a member it is shared with (commands are sent on the owner's behalf).
• For local access, a host on the same L2 network as the station: discovery is a broadcast, and a routed host cannot reach it. Login and push work from anywhere.
• If inbound UDP is filtered: a fixed IP and a pinned local port per station. eufy-security network prints what each station needs.

Install

uv add eufy-home-security                       # the library, in a uv project (or: pip install eufy-home-security)
uv tool install eufy-home-security              # the eufy-security CLI on PATH
uvx --from eufy-home-security eufy-security --help   # run once

The development version: uv add "eufy-home-security @ git+https://github.com/alaraun/python-eufy-home-security", or from a checkout uv sync && uv run eufy-security --help.

Usage

Command line

eufy-security login                 # asks for the password and the e-mailed code once
eufy-security status                # guard mode, firmware, storage, every paired device
eufy-security guard set home
eufy-security settings --model T8160 # a model's settings, keyed by eufy's identifiers
eufy-security set detection_sensitivity 4 --channel 0
eufy-security live --channel 0 --seconds 10 --out clip
eufy-security monitor               # print events as they arrive

The password is never a flag: it comes from $EUFY_PASSWORD, the session cache or a prompt. Every command is in the CLI reference.

Library

import asyncio

import aiohttp

from eufy_home_security import EufySecurity, JsonFileStore, LoginChallengeError


async def main() -> None:
    async with aiohttp.ClientSession() as http:
        eufy = EufySecurity(
            http, "you@example.com", "password", store=JsonFileStore("~/.eufy-cache.json")
        )
        try:
            await eufy.async_login()
        except LoginChallengeError as challenge:
            if challenge.kind != "verify_code":
                raise
            await eufy.async_login(verify_code=input("code from the e-mail: "))

        station = (await eufy.async_discover())[0]
        state = await station.async_update()
        print(station.name, state.guard_mode, state.firmware)

        await station.async_set_guard_mode("home")  # returns once the station confirms
        await eufy.async_close()


asyncio.run(main())

Events from the local session and from push arrive on one stream:

eufy.subscribe(print)
await eufy.async_start()  # local sessions and cloud push, until async_close()

Arming returns only after the station confirms it; a setting write returns how far it got (CommandOutcome). A failure raises a typed error from eufy_home_security.exceptions. The cache file holds the cloud session, the station keys and the account password: keep it private.

More in getting started and, for an integration, the Home Assistant guide.

Documentation

Contributing

Reports from other hardware help most: eufy-security status --raw and eufy-security coverage show what a station reports, and add a device explains how an entry becomes verified. Never post serials, credentials or captures from your home; see CONTRIBUTING.md and SECURITY.md.

uv sync
uv run pytest -n auto
uv run ruff check && uv run ruff format --check
uv run mypy

Support

This project is built in spare time and is free to use. If it is useful to you, donations are welcome. They are voluntary, buy no support or priority, and are not tax-deductible.

• Ko-fi

Donated eufy hardware helps develop future features; please get in touch first.

License

MIT. eufy and Anker are trademarks of Anker Innovations; this project is not affiliated with or endorsed by them.