DOCSEARCHbyAlgolia
Submit Docs

eufy-security-client

repository·master·Indexed 20 days ago

https://github.com/bropat/eufy-security-client

A TypeScript library for controlling Eufy security devices by connecting to Eufy cloud servers and communicating with stations and devices via local or remote P2P. It supports 2FA cloud login, push notifications, and a wide range of device controls including livestreaming, guard mode management, and sensor settings. Note: This library is currently considered a temporary stopgap as Eufy migrates to the Eufy Mega platform.

Tokens
21.6K
Snippets
64
Records
101
Agent score
72%

What's inside eufy-security-client

  1. Overview of eufy-security-client features

    master

    The eufy-security-client library allows control of Eufy security devices by connecting to Eufy cloud servers and communicating with local/remote stations via P2P.

    Core Capabilities:

    • Cloud Connection: Supports 2FA for Eufy cloud login.
    • P2P Communication: Connects to stations and devices locally or remotely.
    • Push Notifications: Unified interface for receiving push messages.
    • Device Control: Ability to get info/parameters via HTTPS or P2P and execute commands.

    Common P2P Commands:

    • Stations: Change guard mode, reboot station.
    • Devices: Start/stop livestreams (P2P or RTMP), enable/disable devices, toggle night vision, motion detection, pet detection, and sound detection, manage LED/anti-theft settings, and control smart locks (lock/unlock).

  2. Overview of eufy-security-client capabilities

    master

    The eufy-security-client is an adapter designed to control Eufy security devices by interfacing with Eufy cloud servers and local/remote stations.

    Core Functionality:

    • Cloud Connection: Requires Eufy Cloud login credentials to connect to your account.
    • Data Retrieval: Polls device data via HTTPS from the cloud.
    • Device Communication: Supports local or remote P2P connections to Eufy stations and devices.
    • Event Notifications: Supports MQTT event notification subscriptions for specific compatible devices.

    Scope: One instance of the Adapter manages all devices associated with a single Eufy Cloud account.

  3. Capabilities of eufy-security-client

    master

    The eufy-security-client provides a comprehensive interface for interacting with Eufy cloud services and local hardware. Key capabilities include:

    Connectivity

    • Cloud Connection: Connects to Eufy cloud with support for 2FA (Two-Factor Authentication).
    • P2P Communication: Supports both local and remote P2P connectivity to stations and devices.
    • MQTT Integration: Connects to the Eufy MQTT broker to receive event notifications for supported devices.
    • Push Notifications: Provides a unified interface for receiving push messages.

    Device Interaction

    • Information Retrieval: Fetch device information and parameters via HTTPS and/or P2P.
    • Command Execution: A basic P2P implementation allows for executing commands, including those not explicitly documented in the library.

    Supported P2P Commands by Category

    Station Commands

    • Change guard mode
    • Reboot station

    Device Commands

    • Livestreaming: Start/Stop livestream (via local/remote P2P or RTMP over cloud).
    • Audio: Start/Stop talkback.
    • Device State: Enable/disable device.
    • Camera Specifics:
      • Enable/disable auto night vision (camera products).
      • Enable/disable LED (camera 2, indoor, floodlight, solo, and doorbells).
      • Enable/disable anti-theft detection (camera 2 products).
      • Enable/disable motion detection.
      • Enable/disable pet detection (indoor cameras).
      • Enable/disable sound detection (indoor cameras).
      • Enable/disable RTSP stream (camera2, indoor, and solo cameras).
      • Change video watermark setting.
    • Video Management: Start/cancel video download.
    • Specialized Hardware:
      • Quick response (doorbells).
      • Lock/unlock (smart locks).

  4. Understand the eufy-security-client dependency tree

    master

    The eufy-security-client repository serves as the base library for several downstream integrations. Understanding this hierarchy is important for developers building on top of the ecosystem or maintaining related services:

    • Base library: bropat/eufy-security-client
      • WebSocket server wrapper: bropat/eufy-security-ws
        • Homey integration: martinjpoppen/com.eufylife.security
        • Home Assistant Add-on: bropat/hassio-eufy-security-ws
          • Home Assistant integration: fuatakgun/eufy_security

  5. Compare HTTP and P2P image retrieval paths

    master

    Eufy provides two distinct ways to retrieve images, which result in different data formats and requirements:

    PathSourceData FormatDecoding Required?
    HTTPGET the push pic_urlv2_eufysecurity:... (header-scrambled)Yes (requires header reconstruction)
    P2Pstation image download eventPlain JPEG (full-res)No (already a standard image)

    Warning: The dimensions of a P2P image do not match the dimensions of a v2_ blob for the same camera. Do not use P2P metadata to attempt to decode v2_ blobs.

  6. Breaking Changes in version 2.0.0

    master

    Version 2.0.0 introduced the following breaking changes:

    • Node.js Requirement: Requires Node.js version >= 14.17.
    • Class Instantiation: The instantiation patterns for HTTPApi, EufySecurity, and Device classes have changed.
    • Property Timestamps: The Timestamp for device and station properties has been removed.

  7. Manage device settings via P2P and HTTP API

    master

    The client supports a wide range of device configuration settings across various product lines (Indoor, Solo, Floodlight, Camera 2, Battery Doorbells, etc.). Common controllable settings include:

    • Motion & Detection: Sensitivity, motion detection type, person/pet/sound/crying notifications, and motion tracking (for pan & tilt cameras).
    • Video & Audio: Video/recording quality, WDR (Wide Dynamic Range), microphone mute, audio recording, speaker volume, and speaker enable/disable.
    • Power & Operation: Power source, power working mode, and custom recording clip lengths/retrigger intervals.
    • Alarms & Notifications: Trigger/reset alarm sounds, alarm volume, and various switch mode notifications (geofence, schedule, keypad).

  8. Breaking Changes in version 4.0.0

    master

    Version 4.0.0 introduced several breaking changes that require code updates:

    • Lock Settings: All lock settings parameters have been renamed to follow standard naming conventions.
    • Station Initialization: The Station class initialization is now an async operation.
    • P2P Discovery: Renewed p2p device address discovery, which now includes local discovery via broadcast and optimized cloud discovery.

  9. Understand the `v2_eufysecurity:` wire format

    master

    The v2_eufysecurity: format is used for image blobs retrieved via HTTP GET requests to the pic_url provided in push messages.

    Wire Format Structure: v2_eufysecurity : <STATION_SERIAL> : <10-DIGIT-PKT> : <binary payload>

    • Magic: v2_eufysecurity
    • Station Serial: e.g., T8...
    • Packet ID: A 10-digit identifier.
    • Binary Payload: The actual image data with a scrambled header.

    Note on Parsing: When splitting the string to extract the payload, you must split on the first 3 colons only. The binary payload itself may contain the colon character (0x3A), so subsequent splits will fail if not handled correctly.

  11. Deploy a new version of eufy-security-client

    master

    To release a new version of the eufy-security-client library, follow these steps:

    1. Update all npm dependencies.
    2. Run the release script to update the version and create a Pull Request (PR): sh scripts/cut_release <version>
    3. Review and merge the relevant PRs into the develop branch.
    4. Merge the develop branch into master.
    5. Create a new GitHub release and tag from the latest master branch.
    6. Generate changelog entries using the previous release's PR number: sh scripts/generate_changelog.sh <last_release_pr_number>
      • This outputs formatted entries (Feature, Fix, Chore).
      • Paste these entries into the Changelog section of the README.md under the new version heading.
    7. Submit and merge a PR containing the updated README.md.
    8. Publish the new version to npm locally using npm publish from the master branch.

    Note: After releasing the client, you must also release new versions of bropat/eufy-security-ws and bropat/hassio-eufy-security-ws to propagate changes.

    # Update version and create PR
sh scripts/cut_release <version>

# Generate changelog entries
sh scripts/generate_changelog.sh <last_release_pr_number>

# Publish to npm
npm publish

  12. Reporting an unknown device via GitHub

    master

    To request support for a new device, open a GitHub issue and include the following details:

    • The full log line containing New unknown device detected and all associated JSON fields.
    • The device name and model as they appear in the official eufy Security app.
    • A brief description of the device type (e.g., "Indoor camera", "Video doorbell").
    • The eufy-security-client version currently in use.