DOCSEARCHbyAlgolia
Submit Docs

pyvesync 3.4.2

repository·dev·Indexed 42 days ago

https://github.com/webdjoe/pyvesync

An asynchronous Python library to manage and control VeSync-compatible smart home devices, including Etekcity devices, Cosori air fryers, and Levoit air purifiers. It provides a DeviceContainer to access outlets, switches, fans, bulbs, humidifiers, air purifiers, air fryers, and thermostats.

Tokens
27.6K
Snippets
66
Records
133
Agent score
54%

What's inside pyvesync

  1. Available Smart Bulb device classes

    dev

    The pyvesync library provides several device classes for controlling Etekcity and Valceno smart bulbs. Depending on your specific hardware model (Dimmable, Tunable, or Multicolor), you should use the corresponding class to access the correct attributes and methods.

    Supported bulb classes include:

    • VeSyncBulbESL100: Etekcity Dimmable ESL100
    • VeSyncBulbESL100CW: Etekcity Tunable ESL100CW
    • VeSyncBulbESL100MC: Etekcity Multicolor ESL100MC
    • VeSyncBulbValcenoA19MC: Valceno Multicolor Bulb

    All bulb classes inherit from the VeSyncBulb abstract base class and utilize the BulbState class to manage state information.

  2. Explore supported device classes in pyvesync

    dev

    Devices in pyvesync are organized into specific modules based on their product type. To interact with a device, you must identify its corresponding device class. The available device classes are:

    • Bulbs
    • Fans
    • Humidifiers
    • Outlets
    • Purifiers
    • Switches
    • Thermostats
    • Air Fryers

    Each class provides a unique set of methods (for controlling the device) and state attributes (for reading the device's current status). To find the specific API for your hardware, consult the documentation for the relevant class. You can map your physical device to a class by checking the supported_devices.md list.

  3. Available Etekcity Smart Switch device classes

    dev

    The pyvesync library provides specific classes for controlling different types of Etekcity smart switches. Depending on your hardware, you should use one of the following classes:

    • VeSyncDimmerSwitch: For Etekcity Dimmer Switch models (e.g., EWD16).
    • VeSyncWallSwitch: For Etekcity Wall Switch models (e.g., ESWL01 & ESWL03).
    • VeSyncSwitch: The abstract base class that defines the core interface for all switch devices.

    All switch devices utilize the SwitchState class to manage and represent the current state of the switch.

  4. Bypass V1 API request and response structures

    dev

    Request Structure

    Bypass V1 requests use the /cloud/v1/deviceManaged/ path. There are two variations:

    1. Direct Method: The last path segment is the method name (e.g., /deviceDetail). The request body includes the method name as a key.
    2. Bypass Method: The last path segment is bypass. The request body uses method: "bypass" and contains a jsonCmd key for the actual command.

    Response Structure

    Responses include a result key containing the actual device data.

    {
    "traceId": "TIMESTAMP",
    "code": 0,
    "msg": "request success",
    "module": null,
    "stacktrace": null,
    "result": {
        "light": {
            "action": "off",
            "brightness": 30,
            "colorTempe": 5
        }
    }
}

  5. How parametrized test generation works

    dev

    Tests are automatically generated by conftest.py based on class attributes in your test classes. By defining specific attributes, you can instruct the suite to run tests against multiple devices and methods.

    Configuration Attributes

    • device: The device category name.
    • outlets (or similar): A list of setup_entry strings.
    • base_methods: A list of methods to test on all devices in the class.
    • device_methods: A dictionary mapping specific device models (e.g., 'ESW15-USA') to their unique methods.

    Generated Tests

    This configuration automatically creates:

    • test_details(setup_entry, method): Verifies get_details() requests.
    • test_methods(setup_entry, method): Verifies specific device methods.

    Test IDs follow the pattern: {device}.{setup_entry}.{method}.

    class TestOutlets(TestBase):
    device = 'outlets'
    outlets = call_json_outlets.OUTLETS
    base_methods = [['turn_on'], ['turn_off']]
    device_methods = {
        'ESW15-USA': [['turn_on_nightlight'], ['get_weekly_energy']],
    }

  6. Use the VeSync class to manage devices and authentication

    dev
    The pyvesync.vesync.VeSync class is the primary entry point for the library. It instantiates a session that holds your authenticated connection and maintains a collection of your connected devices. You use this class to interact with the VeSync cloud API and manage your smart home hardware.

  7. Identify supported device classes in pyvesync

    dev

    The pyvesync library organizes devices into specific classes based on their product type. When you interact with the manager.devices container, it provides access to these devices through categorized lists. Use these categories to find the specific device objects you need to control.

    Device Categories:

    • manager.devices.bulbs: VeSyncBulb instances
    • manager.devices.outlets: VeSyncOutlet instances
    • manager.devices.switches: VeSyncSwitch instances
    • manager.devices.fans: VeSyncFan instances
    • manager.devices.humidifiers: VeSyncHumidifier instances
    • manager.devices.purifiers: VeSyncAirPurifier instances
    • manager.devices.switches: VeSyncSwitch instances
    • manager.devices.air_fryers: VeSyncAirFryer instances
    • manager.devices.thermostats: VeSyncThermostat instances

  8. Understand the VeSyncSwitch base class

    dev
    The pyvesync.base_devices.switch_base.VeSyncSwitch is the abstract base class for all switch-type devices in the library. It defines the common attributes and methods that all switch implementations (like dimmers and wall switches) must follow, ensuring a consistent API for developers.

  9. How the pyvesync architecture works

    dev

    The library is centered around the pyvesync.vesync.VeSync class (often called the manager). This is the primary entry point and the only class that should be directly instantiated. It manages authentication and holds the collection of device objects.

    Key architectural components:

    • Manager (VeSync): Handles authentication and provides the async_call_api method for all asynchronous API communication.
    • Devices: Each device type has a dedicated module containing its specific class and API calls. Device classes inherit from VeSyncBaseDevice or VeSyncToggleDevice (found in pyvesync.base_devices).
    • Device State: Represented as a dataclass. The state is updated whenever the update() method is called on a device. Attributes not supported by all models should use IntFlag.NOT_SUPPORTED or StrFlag.NOT_SUPPORTED.
    from pyvesync.vesync import VeSync

# The manager is the central control
manager = VeSync(session=your_session) # or generated internally

  10. Manage devices using DeviceContainer

    dev

    The manager.devices attribute holds a DeviceContainer object, which is a singleton that manages all discovered devices. It behaves like a MutableSet containing unique device objects.

    Common Operations

    • Add/Remove: Use add(device), remove(device), or clear() to manage the set. To remove a device using its unique ID, use remove_by_cid(cid: str).
    • Search: Use get_by_name(name: str) to find a specific device by its name.
    • Bulk Management: Use add_new_devices(response_model) and remove_stale_devices(response_model) to synchronize the container with a device list response.

    Accessing Specific Product Types

    The DeviceContainer provides properties for each product type that return a list of matching devices. For example, manager.devices.outlets returns all outlet devices.

    # Example: Accessing all outlets
outlets = manager.devices.outlets

# Example: Removing a device by its CID
manager.devices.remove_by_cid("DEVICE_CID_HERE")

# Example: Finding a device by name
device = manager.devices.get_by_name("Living Room Lamp")

  12. Understand the VeSync API types: Bypass V1 vs Bypass V2

    dev

    The VeSync API is categorized into two main types based on the device generation:

    1. Bypass V1 API: Used for older devices like bulbs, switches, outlets, and the first air purifier model (LV-PUR131S). It uses the base endpoint /cloud/v1/deviceManaged/.
    2. Bypass V2 API: Used for newer devices, such as humidifiers and newer purifiers. It uses the base endpoint /cloud/v2/deviceManaged/bypassV2.

    Understanding which API your device uses is critical for determining the correct request/response structure and which mixin to use for implementation.