Documentation for Etekcity / Valceno Smart Bulbs↲

Table of Contents↲

See each device class for available attributes and methods:

• BulbState Class
• Etekcity Smart Bulb ESL100
• Etekcity Smart Bulb ESL100CW
• Etekcity Smart Bulb ESL100MC
• Valceno Smart Bulb ESL100MC
• VeSyncBulb Abstract Base Class

pyvesync.base_devices.bulb_base.BulbState ↲

BulbState(
    device: VeSyncBulb,
    details: ResponseDeviceDetailsModel,
    feature_map: BulbMap,
)

Bases: DeviceState

VeSync Bulb State Base.

Base class to hold all state attributes for bulb devices. Inherits from DeviceState. This class should not be used directly for devices, but rather subclassed for each bulb type.

Parameters:

Name	Type	Description	Default
device	VeSyncBulb	VeSync Bulb device.	required
details	ResponseDeviceDetailsModel	Device details from API.	required
feature_map	BulbMap	Feature map for bulb.	required

Attributes:

Name	Type	Description
_exclude_serialization	list[str]	List of attributes to exclude from serialization.
active_time	int	Active time of device, defaults to None.
connection_status	str	Connection status of device.
device	VeSyncBaseDevice	Device object.
device_status	str	Device status.
features	dict	Features of device.
last_update_ts	int	Last update timestamp of device, defaults to None.
brightness	int	Brightness of bulb (0-100).
color_temp	int	White color temperature of bulb in percent (0-100).
color_temp_kelvin	int	White color temperature of bulb in Kelvin.
color	Color	Color of bulb in the form of a dataclass with two namedtuple attributes - hsv & rgb. See utils.colors.Colors.
color_mode	str	Color mode of bulb.
color_modes	list[str]	List of color modes supported by bulb.

Methods:

Name	Description
update_ts	Update last update timestamp.
to_dict	Dump state to JSON.
to_json	Dump state to JSON string.
to_jsonb	Dump state to JSON bytes.
as_tuple	Convert state to tuple of (name, value) tuples.

See Also

• VeSyncBulb
• [ResponseDeviceDetailsModel][ pyvesync.models.device_list_models.ResponseDeviceDetailsModel]
• BulbMap

Inherited From DeviceState

Initialize VeSync Bulb State Base.

Source code in src/pyvesync/base_devices/bulb_base.py

def __init__(
    self,
    device: VeSyncBulb,
    details: ResponseDeviceDetailsModel,
    feature_map: BulbMap,
) -> None:
    """Initialize VeSync Bulb State Base."""
    super().__init__(device, details, feature_map)
    self._exclude_serialization: list[str] = ['rgb', 'hsv']
    self.features: list[str] = feature_map.features
    self.color_modes: list[str] = feature_map.color_modes
    self.device: VeSyncBulb = device
    self.color_mode: str | None = None
    self._brightness: int | None = None
    self._color_temp: int | None = None
    self._color: Color | None = None

Attributes↲

active_time instance-attribute ↲

active_time: int | None = None

Inherited From DeviceState

brightness property writable ↲

brightness: int | None

Brightness of vesync bulb 0-100.

color property writable ↲

color: Color | None

Return color of bulb.

color_mode instance-attribute ↲

color_mode: str | None = None

color_modes instance-attribute ↲

color_modes: list[str] = color_modes

color_temp property writable ↲

color_temp: int | None

White color temperature of bulb in percent (0-100).

color_temp_kelvin property ↲

color_temp_kelvin: int | None

Return white color temperature of bulb in Kelvin.

connection_status instance-attribute ↲

connection_status: str = connectionStatus or UNKNOWN

Inherited From DeviceState

device instance-attribute ↲

device: VeSyncBulb = device

Inherited From DeviceState

device_status instance-attribute ↲

device_status: str = deviceStatus or UNKNOWN

Inherited From DeviceState

features instance-attribute ↲

features: list[str] = features

Inherited From DeviceState

hsv property writable ↲

hsv: HSV | None

Return color of bulb as HSV.

last_update_ts instance-attribute ↲

last_update_ts: int | None = None

Inherited From DeviceState

rgb property writable ↲

rgb: RGB | None

Return color of bulb as RGB.

timer instance-attribute ↲

timer: Timer | None = None

Inherited From DeviceState

Functions↲

as_tuple ↲

as_tuple() -> tuple[tuple[str, Any], ...]

Inherited From DeviceState

Convert state to tuple of (name, value) tuples.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def as_tuple(self) -> tuple[tuple[str, Any], ...]:
    """Convert state to tuple of (name, value) tuples."""
    return tuple((k, v) for k, v in self._serialize().items())

display ↲

display() -> None

Inherited From DeviceState

Print formatted state to stdout.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def display(self) -> None:
    """Print formatted state to stdout."""
    for name, val in self._serialize().items():
        print(f'{name:.<30} {val}')  # noqa: T201

to_dict ↲

to_dict() -> dict[str, Any]

Inherited From DeviceState

Convert state to dictionary.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_dict(self) -> dict[str, Any]:
    """Convert state to dictionary."""
    return self._serialize()

to_json ↲

to_json(indent: bool = False) -> str

Inherited From DeviceState

Dump state to JSON string.

Parameters:

Name	Type	Description	Default
indent	bool	If True, indent JSON output, defaults to False.	False

Returns:

Name	Type	Description
str	str	JSON formatted string of device state.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_json(self, indent: bool = False) -> str:
    """Dump state to JSON string.

    Args:
        indent (bool): If True, indent JSON output, defaults to False.

    Returns:
        str: JSON formatted string of device state.
    """
    return self.to_jsonb(indent=indent).decode()

to_jsonb ↲

to_jsonb(indent: bool = False) -> bytes

Inherited From DeviceState

Convert state to JSON bytes.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_jsonb(self, indent: bool = False) -> bytes:
    """Convert state to JSON bytes."""
    if indent:
        return orjson.dumps(
            self._serialize(), option=orjson.OPT_NON_STR_KEYS | orjson.OPT_INDENT_2
        )
    return orjson.dumps(self._serialize(), option=orjson.OPT_NON_STR_KEYS)

update_ts ↲

update_ts() -> None

Inherited From DeviceState

Update last update timestamp as UTC timestamp.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def update_ts(self) -> None:
    """Update last update timestamp as UTC timestamp."""
    self.last_update_ts = int(dt.now(tz=UTC).timestamp())

pyvesync.devices.vesyncbulb.VeSyncBulbESL100 ↲

VeSyncBulbESL100(
    details: ResponseDeviceDetailsModel,
    manager: VeSync,
    feature_map: BulbMap,
)

Bases: BypassV1Mixin, VeSyncBulb

Object to hold VeSync ESL100 light bulb.

Device state is held in the state attribute, which is an instance of BulbState. The state attribute contains all settable states for the bulb.

This bulb only has the dimmable feature. Inherits from [VeSyncBulb][pyvesync.devices.vesyncbulb.VeSyncBulb] and VeSyncBaseToggleDevice.

Parameters:

Name	Type	Description	Default
details	dict	Dictionary of bulb state details.	required
manager	VeSync	Manager class used to make API calls	required
feature_map	BulbMap	Device configuration map.	required

Attributes:

Name	Type	Description
state	BulbState	Device state object Each device has a separate state base class in the base_devices module.
last_response	ResponseInfo	Last response from API call.
manager	VeSync	Manager object for API calls.
device_name	str	Name of device.
device_image	str	URL for device image.
cid	str	Device ID.
connection_type	str	Connection type of device.
device_type	str	Type of device.
type	str	Type of device.
uuid	str	UUID of device, not always present.
config_module	str	Configuration module of device.
mac_id	str	MAC ID of device.
current_firm_version	str	Current firmware version of device.
device_region	str	Region of device. (US, EU, etc.)
pid	str	Product ID of device, pulled by some devices on update.
sub_device_no	int	Sub-device number of device.
product_type	str	Product type of device.
features	dict	Features of device.

Inherited From VeSyncBulb

Initialize Etekcity ESL100 Dimmable Bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

def __init__(
    self, details: ResponseDeviceDetailsModel, manager: VeSync, feature_map: BulbMap
) -> None:
    """Initialize Etekcity ESL100 Dimmable Bulb."""
    super().__init__(details, manager, feature_map)

Attributes↲

cid instance-attribute ↲

cid: str = cid

Inherited From VeSyncBaseDevice

config_module instance-attribute ↲

config_module: str = configModule

Inherited From VeSyncBaseDevice

connection_type instance-attribute ↲

connection_type: str | None = connectionType

Inherited From VeSyncBaseDevice

current_firm_version instance-attribute ↲

current_firm_version = currentFirmVersion

Inherited From VeSyncBaseDevice

device_image instance-attribute ↲

device_image: str | None = deviceImg

Inherited From VeSyncBaseDevice

device_name instance-attribute ↲

device_name: str = deviceName

Inherited From VeSyncBaseDevice

device_region instance-attribute ↲

device_region: str | None = deviceRegion

Inherited From VeSyncBaseDevice

device_type instance-attribute ↲

device_type: str = deviceType

Inherited From VeSyncBaseDevice

enabled instance-attribute ↲

enabled: bool = True

Inherited From VeSyncBaseDevice

features instance-attribute ↲

features: list[str] = features

Inherited From VeSyncBaseDevice

firmware_update property ↲

firmware_update: bool

Inherited From VeSyncBaseDevice

Return True if firmware update available.

This is going to be updated.

is_on property ↲

is_on: bool

Inherited From VeSyncBaseDevice

Return true if device is on.

last_response instance-attribute ↲

last_response: ResponseInfo | None = None

Inherited From VeSyncBaseDevice

latest_firm_version instance-attribute ↲

latest_firm_version: str | None = None

Inherited From VeSyncBaseDevice

mac_id instance-attribute ↲

mac_id: str | None = macID

Inherited From VeSyncBaseDevice

manager instance-attribute ↲

manager: VeSync

Inherited From BypassV1Mixin

pid instance-attribute ↲

pid: str | None = None

Inherited From VeSyncBaseDevice

product_type instance-attribute ↲

product_type: str = product_type

Inherited From VeSyncBaseDevice

request_keys class-attribute instance-attribute ↲

request_keys: tuple[str, ...] = (
    'acceptLanguage',
    'appVersion',
    'phoneBrand',
    'phoneOS',
    'accountID',
    'cid',
    'configModule',
    'debugMode',
    'traceId',
    'timeZone',
    'token',
    'userCountryCode',
    'uuid',
    'configModel',
    'deviceId',
)

Inherited From BypassV1Mixin

state instance-attribute ↲

state: BulbState = BulbState(self, details, feature_map)

Inherited From VeSyncBulb

sub_device_no instance-attribute ↲

sub_device_no: int | None = subDeviceNo

Inherited From VeSyncBaseDevice

supports_brightness property ↲

supports_brightness: bool

Inherited From VeSyncBulb

Return True if bulb supports brightness.

type instance-attribute ↲

type: str | None = type

Inherited From VeSyncBaseDevice

uuid instance-attribute ↲

uuid: str | None = uuid

Inherited From VeSyncBaseDevice

Functions↲

call_bypassv1_api async ↲

call_bypassv1_api(
    request_model: type[RequestBypassV1],
    update_dict: dict | None = None,
    method: str = 'bypass',
    endpoint: str = 'bypass',
) -> dict | None

Inherited From BypassV1Mixin

Send ByPass V1 API request.

This uses the _build_request method to send API requests to the Bypass V1 API. The endpoint can be overridden with the endpoint argument.

Parameters:

Name	Type	Description	Default
request_model	type[RequestBypassV1]	The request model to use.	required
update_dict	dict	Additional keys to add on.	None
method	str	The method to use in the outer body.	'bypass'
endpoint	str | None	The last part of the url path, defaults to bypass, e.g. /cloud/v1/deviceManaged/bypass.	'bypass'

Returns:

Name	Type	Description
bytes	dict | None	The response from the API request.

Source code in src/pyvesync/utils/device_mixins.py

async def call_bypassv1_api(
    self,
    request_model: type[RequestBypassV1],
    update_dict: dict | None = None,
    method: str = 'bypass',
    endpoint: str = 'bypass',
) -> dict | None:
    """Send ByPass V1 API request.

    This uses the `_build_request` method to send API requests to the Bypass V1 API.
    The endpoint can be overridden with the `endpoint` argument.

    Args:
        request_model (type[RequestBypassV1]): The request model to use.
        update_dict (dict): Additional keys to add on.
        method (str): The method to use in the outer body.
        endpoint (str | None): The last part of the url path, defaults to
            `bypass`, e.g. `/cloud/v1/deviceManaged/bypass`.

    Returns:
        bytes: The response from the API request.
    """
    request = self._build_request(request_model, update_dict, method)
    url_path = BYPASS_V1_PATH + endpoint
    resp_dict, _ = await self.manager.async_call_api(
        url_path, 'post', request, Helpers.req_header_bypass()
    )

    return resp_dict

clear_timer async ↲

clear_timer() -> bool

Inherited From VeSyncBaseDevice

Clear timer for device from API.

This may not be implemented for all devices. Please open an issue if there is an error.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def clear_timer(self) -> bool:
    if self.state.timer is None:
        logger.debug('No timer set - run get_timer() first')
        return False
    timer = self.state.timer
    r_dict = await self.call_bypassv1_api(
        TimerModels.RequestV1ClearTimer,
        {'timerId': str(timer.id), 'status': '1'},
        'deleteTimer',
        'timer/deleteTimer',
    )
    result = Helpers.process_dev_response(logger, 'clear_timer', self, r_dict)
    if result is None:
        return False
    self.state.timer = None
    return True

display ↲

display(state: bool = True) -> None

Inherited From VeSyncBaseDevice

Print formatted static device info to stdout.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in display, defaults to True.	True

Example:

Device Name:..................Living Room Lamp
Model:........................ESL100
Subdevice No:.................0
Type:.........................wifi
CID:..........................1234567890abcdef

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def display(self, state: bool = True) -> None:
    """Print formatted static device info to stdout.

    Args:
        state (bool): If True, include state in display, defaults to True.

    Example:
    ```
    Device Name:..................Living Room Lamp
    Model:........................ESL100
    Subdevice No:.................0
    Type:.........................wifi
    CID:..........................1234567890abcdef
    ```
    """
    # noinspection SpellCheckingInspection
    display_list = [
        ('Device Name:', self.device_name),
        ('Product Type: ', self.product_type),
        ('Model: ', self.device_type),
        ('Subdevice No: ', str(self.sub_device_no)),
        ('Type: ', self.type),
        ('CID: ', self.cid),
        ('Config Module: ', self.config_module),
        ('Connection Type: ', self.connection_type),
        ('Features', self.features),
        ('Last Response: ', self.last_response),
    ]
    if self.uuid is not None:
        display_list.append(('UUID: ', self.uuid))

    for line in display_list:
        print(f'{line[0]:.<30} {line[1]}')  # noqa: T201
    if state:
        self.state.display()

enable_white_mode async deprecated ↲

enable_white_mode() -> bool

Inherited From VeSyncBulb

Deprecated

Use set_white_mode instead.

Enable white mode if supported by bulb.

Source code in src/pyvesync/base_devices/bulb_base.py

@deprecated('Use `set_white_mode` instead.')
async def enable_white_mode(self) -> bool:
    """Enable white mode if supported by bulb."""
    return await self.set_white_mode()

get_details async ↲

get_details() -> None

Inherited From VeSyncBaseDevice

Get device details.

This method is defined in each device class to contain the logic to pull the device state from the API and update the device's state attribute. The update() method should be called to update the device state.

Source code in src/pyvesync/devices/vesyncbulb.py

async def get_details(self) -> None:
    method_dict = {
        'method': 'deviceDetail',
    }

    r_dict = await self.call_bypassv1_api(
        bulb_models.RequestESL100Detail, method_dict, 'deviceDetail', 'deviceDetail'
    )
    model = process_bypassv1_result(
        self, logger, 'get_details', r_dict, bulb_models.ResponseESL100DetailResult
    )

    if model is None:
        self.state.connection_status = ConnectionStatus.OFFLINE
        return
    self.state.brightness = model.brightness
    self.state.device_status = model.deviceStatus
    self.state.connection_status = model.connectionStatus

get_state ↲

get_state(state_attr: str) -> Any

Inherited From VeSyncBaseDevice

Get device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def get_state(self, state_attr: str) -> Any:  # noqa: ANN401
    """Get device state attribute."""
    return getattr(self.state, state_attr)

get_timer async ↲

get_timer() -> None

Inherited From VeSyncBaseDevice

Get timer for device from API and set the state.Timer attribute.

This may not be implemented for all devices. Please open an issue if there is an error.

Note

This method may not be implemented for all devices. Please open an issue if there is an error.

Source code in src/pyvesync/devices/vesyncbulb.py

async def get_timer(self) -> None:
    r_dict = await self.call_bypassv1_api(
        TimerModels.RequestV1GetTimer, {}, 'getTimers', 'timer/getTimers'
    )
    result_model = process_bypassv1_result(
        self, logger, 'get_timer', r_dict, TimerModels.ResultV1GetTimer
    )
    if result_model is None:
        return
    if not isinstance(result_model.timers, list) or not result_model.timers:
        self.state.timer = None
        logger.debug('No timers found')
        return
    timer = result_model.timers
    if not isinstance(timer, TimerModels.TimerItemV1):
        logger.warning('Invalid timer item type')
        return
    self.state.timer = Timer(
        int(timer.counterTimer),
        timer.action,
        int(timer.timerID),
    )

set_brightness async ↲

set_brightness(brightness: int) -> bool

Inherited From VeSyncBulb

Set brightness if supported by bulb.

Parameters:

Name	Type	Description	Default
brightness	NUMERIC_T	Brightness 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_brightness(self, brightness: int) -> bool:
    if not self.supports_brightness:
        logger.warning('%s is not dimmable', self.device_name)
        return False
    if not Validators.validate_zero_to_hundred(brightness):
        logger.warning('Invalid brightness value')
        return False
    brightness_update = brightness
    if (
        self.state.device_status == DeviceStatus.ON
        and brightness_update == self.supports_brightness
    ):
        logger.debug('Device already in requested state')
        return True

    method_dict = {
        'brightNess': str(brightness_update),
        'status': 'on',
    }
    r_dict = await self.call_bypassv1_api(
        bulb_models.RequestESL100Brightness,
        method_dict,
        'smartBulbBrightnessCtl',
        'smartBulbBrightnessCtl',
    )

    r = Helpers.process_dev_response(logger, 'set_brightness', self, r_dict)
    if r is None:
        return False

    self.state.brightness = brightness_update
    self.state.device_status = DeviceStatus.ON
    self.state.connection_status = ConnectionStatus.ONLINE
    return True

set_state ↲

set_state(state_attr: str, stat_value: Any) -> None

Inherited From VeSyncBaseDevice

Set device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def set_state(self, state_attr: str, stat_value: Any) -> None:  # noqa: ANN401
    """Set device state attribute."""
    setattr(self, state_attr, stat_value)

set_status async deprecated ↲

set_status(brightness: int) -> bool

Deprecated

Use set_brightness() instead

Set brightness of dimmable bulb.

Parameters:

Name	Type	Description	Default
brightness	int	Brightness of bulb (0-100).	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

@deprecated('Use set_brightness() instead')
async def set_status(self, brightness: int) -> bool:
    """Set brightness of dimmable bulb.

    Args:
        brightness (int): Brightness of bulb (0-100).

    Returns:
        bool: True if successful, False otherwise.
    """
    return await self.set_brightness(brightness=brightness)

set_timer async ↲

set_timer(duration: int, action: str | None = None) -> bool

Inherited From VeSyncBaseDevice

Set timer for device.

This may not be implemented for all devices. Please open an issue if there is an error.

Parameters:

Name	Type	Description	Default
duration	int	Duration in seconds.	required
action	str | None	Action to take when timer expires.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_timer(self, duration: int, action: str | None = None) -> bool:
    if action is None:
        action = (
            DeviceStatus.ON
            if self.state.device_status == DeviceStatus.OFF
            else DeviceStatus.OFF
        )
    if action not in [DeviceStatus.ON, DeviceStatus.OFF]:
        logger.warning("Invalid action value - must be 'on' or 'off'")
        return False
    update_dict = {
        'action': action,
        'counterTime': str(duration),
        'status': '1',
    }
    r_dict = await self.call_bypassv1_api(
        TimerModels.RequestV1SetTime, update_dict, 'addTimer', 'timer/addTimer'
    )
    result_model = process_bypassv1_result(
        self, logger, 'set_timer', r_dict, TimerModels.ResultV1SetTimer
    )
    if result_model is None:
        return False
    self.state.timer = Timer(duration, action, int(result_model.timerID))
    return True

set_white_mode async ↲

set_white_mode() -> bool

Inherited From VeSyncBulb

Set white mode if supported by bulb.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_white_mode(self) -> bool:
    """Set white mode if supported by bulb.

    Returns:
        bool: True if successful, False otherwise.
    """
    if self.supports_multicolor:
        logger.debug('White mode is not configured on this bulb.')
    else:
        logger.warning('White mode not supported by this bulb')
    return False

to_dict ↲

to_dict(state: bool = True) -> dict[str, Any]

Inherited From VeSyncBaseDevice

Return device information as a dictionary.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in dictionary, defaults to True.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing device information.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_dict(self, state: bool = True) -> dict[str, Any]:
    """Return device information as a dictionary.

    Args:
        state (bool): If True, include state in dictionary, defaults to True.

    Returns:
        dict[str, Any]: Dictionary containing device information.
    """
    device_dict = {
        'device_name': self.device_name,
        'product_type': self.product_type,
        'model': self.device_type,
        'subdevice_no': str(self.sub_device_no),
        'type': self.type,
        'cid': self.cid,
        'features:': self.features,
        'config_module': self.config_module,
        'connection_type': self.connection_type,
        'last_response': self.last_response,
    }
    state_dict = self.state.to_dict() if state else {}
    return device_dict | state_dict

to_json ↲

to_json(state: bool = True, indent: bool = True) -> str

Inherited From VeSyncBaseDevice

Print JSON API string for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
str	str	JSON formatted string of device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_json(self, state: bool = True, indent: bool = True) -> str:
    """Print JSON API string for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        str: JSON formatted string of device details.
    """
    return self.to_jsonb(state, indent).decode()

to_jsonb ↲

to_jsonb(state: bool = True, indent: bool = True) -> bytes

Inherited From VeSyncBaseDevice

JSON API bytes for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
bytes	bytes	JSON formatted bytes of device details.

Example

This is an example without state.

{
    "Device Name": "Living Room Lamp",
    "Model": "ESL100",
    "Subdevice No": "0",
    "Type": "wifi",
    "CID": "1234567890abcdef"
}

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_jsonb(self, state: bool = True, indent: bool = True) -> bytes:
    """JSON API bytes for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        bytes: JSON formatted bytes of device details.

    Example:
        This is an example without state.
        ```
        {
            "Device Name": "Living Room Lamp",
            "Model": "ESL100",
            "Subdevice No": "0",
            "Type": "wifi",
            "CID": "1234567890abcdef"
        }
        ```
    """
    return_dict = self.to_dict(state=state)
    if indent:
        return orjson.dumps(
            return_dict,
            option=orjson.OPT_INDENT_2 | orjson.OPT_NON_STR_KEYS,
        )

    return orjson.dumps(return_dict, option=orjson.OPT_NON_STR_KEYS)

toggle async deprecated ↲

toggle(status: str) -> bool

Deprecated

toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead

Toggle switch of ESL100 bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

@deprecated(
    'toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead'
)
async def toggle(self, status: str) -> bool:
    """Toggle switch of ESL100 bulb."""
    status_bool = status != DeviceStatus.ON
    return await self.toggle_switch(status_bool)

toggle_switch async ↲

toggle_switch(toggle: bool | None = None) -> bool

Inherited From VeSyncBaseToggleDevice

Toggle device power on or off.

Parameters:

Name	Type	Description	Default
toggle	bool | None	True to turn on, False to turn off, None to toggle.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def toggle_switch(self, toggle: bool | None = None) -> bool:
    if toggle is None:
        toggle = self.state.device_status != DeviceStatus.ON
    status = DeviceStatus.ON if toggle else DeviceStatus.OFF
    method_dict = {
        'status': status,
    }
    r_dict = await self.call_bypassv1_api(
        bulb_models.RequestESL100Status,
        method_dict,
        'smartBulbPowerSwitchCtl',
        'smartBulbPowerSwitchCtl',
    )

    r = Helpers.process_dev_response(logger, 'toggle', self, r_dict)
    if r is None:
        return False

    self.state.device_status = status
    return True

turn_off async ↲

turn_off() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device off.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_off(self) -> bool:
    """Turn device off."""
    return await self.toggle_switch(False)

turn_on async ↲

turn_on() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device on.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_on(self) -> bool:
    """Turn device on."""
    return await self.toggle_switch(True)

update async ↲

update() -> None

Inherited From VeSyncBaseDevice

Update device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def update(self) -> None:
    """Update device details."""
    await self.get_details()

pyvesync.devices.vesyncbulb.VeSyncBulbESL100CW ↲

VeSyncBulbESL100CW(
    details: ResponseDeviceDetailsModel,
    manager: VeSync,
    feature_map: BulbMap,
)

Bases: BypassV1Mixin, VeSyncBulb

VeSync Tunable and Dimmable White Bulb.

This bulb only has the dimmable feature. Inherits from [VeSyncBulb][pyvesync.devices.vesyncbulb.VeSyncBulb] and VeSyncBaseToggleDevice.

Device state is held in the state attribute, which is an instance of BulbState. The state attribute contains all settable states for the bulb.

Parameters:

Name	Type	Description	Default
details	dict	Dictionary of bulb state details.	required
manager	VeSync	Manager class used to make API calls	required
feature_map	BulbMap	Device configuration map.	required

Attributes:

Name	Type	Description
state	BulbState	Device state object Each device has a separate state base class in the base_devices module.
last_response	ResponseInfo	Last response from API call.
manager	VeSync	Manager object for API calls.
device_name	str	Name of device.
device_image	str	URL for device image.
cid	str	Device ID.
connection_type	str	Connection type of device.
device_type	str	Type of device.
type	str	Type of device.
uuid	str	UUID of device, not always present.
config_module	str	Configuration module of device.
mac_id	str	MAC ID of device.
current_firm_version	str	Current firmware version of device.
device_region	str	Region of device. (US, EU, etc.)
pid	str	Product ID of device, pulled by some devices on update.
sub_device_no	int	Sub-device number of device.
product_type	str	Product type of device.
features	dict	Features of device.

Inherited From VeSyncBulb

Initialize Etekcity Tunable white bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

def __init__(
    self, details: ResponseDeviceDetailsModel, manager: VeSync, feature_map: BulbMap
) -> None:
    """Initialize Etekcity Tunable white bulb."""
    super().__init__(details, manager, feature_map)

Attributes↲

cid instance-attribute ↲

cid: str = cid

Inherited From VeSyncBaseDevice

config_module instance-attribute ↲

config_module: str = configModule

Inherited From VeSyncBaseDevice

connection_type instance-attribute ↲

connection_type: str | None = connectionType

Inherited From VeSyncBaseDevice

current_firm_version instance-attribute ↲

current_firm_version = currentFirmVersion

Inherited From VeSyncBaseDevice

device_image instance-attribute ↲

device_image: str | None = deviceImg

Inherited From VeSyncBaseDevice

device_name instance-attribute ↲

device_name: str = deviceName

Inherited From VeSyncBaseDevice

device_region instance-attribute ↲

device_region: str | None = deviceRegion

Inherited From VeSyncBaseDevice

device_type instance-attribute ↲

device_type: str = deviceType

Inherited From VeSyncBaseDevice

enabled instance-attribute ↲

enabled: bool = True

Inherited From VeSyncBaseDevice

features instance-attribute ↲

features: list[str] = features

Inherited From VeSyncBaseDevice

firmware_update property ↲

firmware_update: bool

Inherited From VeSyncBaseDevice

Return True if firmware update available.

This is going to be updated.

is_on property ↲

is_on: bool

Inherited From VeSyncBaseDevice

Return true if device is on.

last_response instance-attribute ↲

last_response: ResponseInfo | None = None

Inherited From VeSyncBaseDevice

latest_firm_version instance-attribute ↲

latest_firm_version: str | None = None

Inherited From VeSyncBaseDevice

mac_id instance-attribute ↲

mac_id: str | None = macID

Inherited From VeSyncBaseDevice

manager instance-attribute ↲

manager: VeSync

Inherited From BypassV1Mixin

pid instance-attribute ↲

pid: str | None = None

Inherited From VeSyncBaseDevice

product_type instance-attribute ↲

product_type: str = product_type

Inherited From VeSyncBaseDevice

request_keys class-attribute instance-attribute ↲

request_keys: tuple[str, ...] = (
    'acceptLanguage',
    'appVersion',
    'phoneBrand',
    'phoneOS',
    'accountID',
    'cid',
    'configModule',
    'debugMode',
    'traceId',
    'timeZone',
    'token',
    'userCountryCode',
    'uuid',
    'configModel',
    'deviceId',
)

Inherited From BypassV1Mixin

state instance-attribute ↲

state: BulbState = BulbState(self, details, feature_map)

Inherited From VeSyncBulb

sub_device_no instance-attribute ↲

sub_device_no: int | None = subDeviceNo

Inherited From VeSyncBaseDevice

supports_brightness property ↲

supports_brightness: bool

Inherited From VeSyncBulb

Return True if bulb supports brightness.

type instance-attribute ↲

type: str | None = type

Inherited From VeSyncBaseDevice

uuid instance-attribute ↲

uuid: str | None = uuid

Inherited From VeSyncBaseDevice

Functions↲

call_bypassv1_api async ↲

call_bypassv1_api(
    request_model: type[RequestBypassV1],
    update_dict: dict | None = None,
    method: str = 'bypass',
    endpoint: str = 'bypass',
) -> dict | None

Inherited From BypassV1Mixin

Send ByPass V1 API request.

This uses the _build_request method to send API requests to the Bypass V1 API. The endpoint can be overridden with the endpoint argument.

Parameters:

Name	Type	Description	Default
request_model	type[RequestBypassV1]	The request model to use.	required
update_dict	dict	Additional keys to add on.	None
method	str	The method to use in the outer body.	'bypass'
endpoint	str | None	The last part of the url path, defaults to bypass, e.g. /cloud/v1/deviceManaged/bypass.	'bypass'

Returns:

Name	Type	Description
bytes	dict | None	The response from the API request.

Source code in src/pyvesync/utils/device_mixins.py

async def call_bypassv1_api(
    self,
    request_model: type[RequestBypassV1],
    update_dict: dict | None = None,
    method: str = 'bypass',
    endpoint: str = 'bypass',
) -> dict | None:
    """Send ByPass V1 API request.

    This uses the `_build_request` method to send API requests to the Bypass V1 API.
    The endpoint can be overridden with the `endpoint` argument.

    Args:
        request_model (type[RequestBypassV1]): The request model to use.
        update_dict (dict): Additional keys to add on.
        method (str): The method to use in the outer body.
        endpoint (str | None): The last part of the url path, defaults to
            `bypass`, e.g. `/cloud/v1/deviceManaged/bypass`.

    Returns:
        bytes: The response from the API request.
    """
    request = self._build_request(request_model, update_dict, method)
    url_path = BYPASS_V1_PATH + endpoint
    resp_dict, _ = await self.manager.async_call_api(
        url_path, 'post', request, Helpers.req_header_bypass()
    )

    return resp_dict

clear_timer async ↲

clear_timer() -> bool

Inherited From VeSyncBaseDevice

Clear timer for device from API.

This may not be implemented for all devices. Please open an issue if there is an error.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def clear_timer(self) -> bool:
    if self.state.timer is None:
        logger.debug('No timer set - run get_timer() first')
        return False
    timer = self.state.timer
    r_dict = await self.call_bypassv1_api(
        TimerModels.RequestV1ClearTimer,
        {'timerId': str(timer.id), 'status': '1'},
        'deleteTimer',
        'timer/deleteTimer',
    )
    r = Helpers.process_dev_response(logger, 'clear_timer', self, r_dict)
    if r is None:
        return False
    self.state.timer = None
    return True

display ↲

display(state: bool = True) -> None

Inherited From VeSyncBaseDevice

Print formatted static device info to stdout.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in display, defaults to True.	True

Example:

Device Name:..................Living Room Lamp
Model:........................ESL100
Subdevice No:.................0
Type:.........................wifi
CID:..........................1234567890abcdef

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def display(self, state: bool = True) -> None:
    """Print formatted static device info to stdout.

    Args:
        state (bool): If True, include state in display, defaults to True.

    Example:
    ```
    Device Name:..................Living Room Lamp
    Model:........................ESL100
    Subdevice No:.................0
    Type:.........................wifi
    CID:..........................1234567890abcdef
    ```
    """
    # noinspection SpellCheckingInspection
    display_list = [
        ('Device Name:', self.device_name),
        ('Product Type: ', self.product_type),
        ('Model: ', self.device_type),
        ('Subdevice No: ', str(self.sub_device_no)),
        ('Type: ', self.type),
        ('CID: ', self.cid),
        ('Config Module: ', self.config_module),
        ('Connection Type: ', self.connection_type),
        ('Features', self.features),
        ('Last Response: ', self.last_response),
    ]
    if self.uuid is not None:
        display_list.append(('UUID: ', self.uuid))

    for line in display_list:
        print(f'{line[0]:.<30} {line[1]}')  # noqa: T201
    if state:
        self.state.display()

enable_white_mode async deprecated ↲

enable_white_mode() -> bool

Inherited From VeSyncBulb

Deprecated

Use set_white_mode instead.

Enable white mode if supported by bulb.

Source code in src/pyvesync/base_devices/bulb_base.py

@deprecated('Use `set_white_mode` instead.')
async def enable_white_mode(self) -> bool:
    """Enable white mode if supported by bulb."""
    return await self.set_white_mode()

get_details async ↲

get_details() -> None

Inherited From VeSyncBaseDevice

Get device details.

This method is defined in each device class to contain the logic to pull the device state from the API and update the device's state attribute. The update() method should be called to update the device state.

Source code in src/pyvesync/devices/vesyncbulb.py

async def get_details(self) -> None:
    r_dict = await self.call_bypassv1_api(
        bulb_models.RequestESL100CWBase,
        {'jsonCmd': {'getLightStatus': 'get'}},
    )

    light_resp = process_bypassv1_result(
        self, logger, 'get_details', r_dict, bulb_models.ResponseESL100CWDetailResult
    )
    if light_resp is None:
        self.state.connection_status = ConnectionStatus.OFFLINE
        return
    self._interpret_apicall_result(light_resp)

get_state ↲

get_state(state_attr: str) -> Any

Inherited From VeSyncBaseDevice

Get device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def get_state(self, state_attr: str) -> Any:  # noqa: ANN401
    """Get device state attribute."""
    return getattr(self.state, state_attr)

get_timer async ↲

get_timer() -> None

Inherited From VeSyncBaseDevice

Get timer for device from API and set the state.Timer attribute.

This may not be implemented for all devices. Please open an issue if there is an error.

Note

This method may not be implemented for all devices. Please open an issue if there is an error.

Source code in src/pyvesync/devices/vesyncbulb.py

async def get_timer(self) -> None:
    r_dict = await self.call_bypassv1_api(
        TimerModels.RequestV1GetTimer, {}, 'getTimers', 'timer/getTimers'
    )
    result_model = process_bypassv1_result(
        self, logger, 'get_timer', r_dict, TimerModels.ResultV1GetTimer
    )
    if result_model is None:
        return
    if not isinstance(result_model.timers, list) or not result_model.timers:
        logger.debug('No timers found')
        return
    timers = result_model.timers
    if len(timers) > 1:
        logger.debug('Multiple timers found, returning first timer')
    timer = timers[0]
    if not isinstance(timer, TimerModels.TimeItemV1):
        logger.warning('Invalid timer item type')
        return
    self.state.timer = Timer(
        int(timer.counterTime),
        timer.action,
        int(timer.timerID),
    )

set_brightness async ↲

set_brightness(brightness: int) -> bool

Inherited From VeSyncBulb

Set brightness of tunable bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_brightness(self, brightness: int) -> bool:
    """Set brightness of tunable bulb."""
    return await self.set_status(brightness=brightness)

set_state ↲

set_state(state_attr: str, stat_value: Any) -> None

Inherited From VeSyncBaseDevice

Set device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def set_state(self, state_attr: str, stat_value: Any) -> None:  # noqa: ANN401
    """Set device state attribute."""
    setattr(self, state_attr, stat_value)

set_status async ↲

set_status(
    brightness: int | None = None,
    color_temp: int | None = None,
) -> bool

Set status of tunable bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_status(
    self, /, brightness: int | None = None, color_temp: int | None = None
) -> bool:
    """Set status of tunable bulb."""
    if brightness is not None:
        if Validators.validate_zero_to_hundred(brightness):
            brightness_update = int(brightness)
        else:
            logger.warning('Invalid brightness value')
            return False
    elif self.state.brightness is not None:
        brightness_update = self.state.brightness
    else:
        brightness_update = 100
    if color_temp is not None:
        if Validators.validate_zero_to_hundred(color_temp):
            color_temp_update = color_temp
        else:
            logger.warning('Invalid color temperature value')
            return False
    elif self.state.color_temp is not None:
        color_temp_update = self.state.color_temp
    else:
        color_temp_update = 100
    if (
        self.state.device_status == DeviceStatus.ON
        and brightness_update == self.state.brightness
        and color_temp_update == self.state.color_temp
    ):
        logger.debug('Device already in requested state')
        return True
    light_dict: dict[str, NUMERIC_OPT | str] = {
        'colorTempe': color_temp_update,
        'brightness': brightness_update,
        'action': DeviceStatus.ON,
    }

    r_dict = await self.call_bypassv1_api(
        bulb_models.RequestESL100CWBase,
        {'jsonCmd': {'light': light_dict}},
        'bypass',
        'bypass',
    )

    r = Helpers.process_dev_response(logger, 'set_brightness', self, r_dict)
    if r is None:
        return False

    self.state.brightness = brightness_update
    self.state.color_temp = color_temp_update
    self.state.device_status = DeviceStatus.ON
    self.state.connection_status = ConnectionStatus.ONLINE
    return True

set_timer async ↲

set_timer(duration: int, action: str | None = None) -> bool

Inherited From VeSyncBaseDevice

Set timer for device.

This may not be implemented for all devices. Please open an issue if there is an error.

Parameters:

Name	Type	Description	Default
duration	int	Duration in seconds.	required
action	str | None	Action to take when timer expires.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_timer(self, duration: int, action: str | None = None) -> bool:
    if action is None:
        action = (
            DeviceStatus.ON
            if self.state.device_status == DeviceStatus.OFF
            else DeviceStatus.OFF
        )
    if action not in [DeviceStatus.ON, DeviceStatus.OFF]:
        logger.warning("Invalid action value - must be 'on' or 'off'")
        return False
    update_dict = {
        'action': action,
        'counterTime': str(duration),
        'status': '1',
    }
    r_dict = await self.call_bypassv1_api(
        TimerModels.RequestV1SetTime, update_dict, 'addTimer', 'timer/addTimer'
    )
    result_model = process_bypassv1_result(
        self, logger, 'set_timer', r_dict, TimerModels.ResultV1SetTimer
    )
    if result_model is None:
        return False
    self.state.timer = Timer(duration, action, int(result_model.timerID))
    return True

set_white_mode async ↲

set_white_mode() -> bool

Inherited From VeSyncBulb

Set white mode if supported by bulb.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_white_mode(self) -> bool:
    """Set white mode if supported by bulb.

    Returns:
        bool: True if successful, False otherwise.
    """
    if self.supports_multicolor:
        logger.debug('White mode is not configured on this bulb.')
    else:
        logger.warning('White mode not supported by this bulb')
    return False

to_dict ↲

to_dict(state: bool = True) -> dict[str, Any]

Inherited From VeSyncBaseDevice

Return device information as a dictionary.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in dictionary, defaults to True.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing device information.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_dict(self, state: bool = True) -> dict[str, Any]:
    """Return device information as a dictionary.

    Args:
        state (bool): If True, include state in dictionary, defaults to True.

    Returns:
        dict[str, Any]: Dictionary containing device information.
    """
    device_dict = {
        'device_name': self.device_name,
        'product_type': self.product_type,
        'model': self.device_type,
        'subdevice_no': str(self.sub_device_no),
        'type': self.type,
        'cid': self.cid,
        'features:': self.features,
        'config_module': self.config_module,
        'connection_type': self.connection_type,
        'last_response': self.last_response,
    }
    state_dict = self.state.to_dict() if state else {}
    return device_dict | state_dict

to_json ↲

to_json(state: bool = True, indent: bool = True) -> str

Inherited From VeSyncBaseDevice

Print JSON API string for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
str	str	JSON formatted string of device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_json(self, state: bool = True, indent: bool = True) -> str:
    """Print JSON API string for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        str: JSON formatted string of device details.
    """
    return self.to_jsonb(state, indent).decode()

to_jsonb ↲

to_jsonb(state: bool = True, indent: bool = True) -> bytes

Inherited From VeSyncBaseDevice

JSON API bytes for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
bytes	bytes	JSON formatted bytes of device details.

Example

This is an example without state.

{
    "Device Name": "Living Room Lamp",
    "Model": "ESL100",
    "Subdevice No": "0",
    "Type": "wifi",
    "CID": "1234567890abcdef"
}

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_jsonb(self, state: bool = True, indent: bool = True) -> bytes:
    """JSON API bytes for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        bytes: JSON formatted bytes of device details.

    Example:
        This is an example without state.
        ```
        {
            "Device Name": "Living Room Lamp",
            "Model": "ESL100",
            "Subdevice No": "0",
            "Type": "wifi",
            "CID": "1234567890abcdef"
        }
        ```
    """
    return_dict = self.to_dict(state=state)
    if indent:
        return orjson.dumps(
            return_dict,
            option=orjson.OPT_INDENT_2 | orjson.OPT_NON_STR_KEYS,
        )

    return orjson.dumps(return_dict, option=orjson.OPT_NON_STR_KEYS)

toggle async deprecated ↲

toggle(status: str) -> bool

Deprecated

toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead

Deprecated - use toggle_switch().

Source code in src/pyvesync/devices/vesyncbulb.py

@deprecated(
    'toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead'
)
async def toggle(self, status: str) -> bool:
    """Deprecated - use toggle_switch()."""
    status_bool = status == DeviceStatus.ON
    return await self.toggle_switch(status_bool)

toggle_switch async ↲

toggle_switch(toggle: bool | None = None) -> bool

Inherited From VeSyncBaseToggleDevice

Toggle device power on or off.

Parameters:

Name	Type	Description	Default
toggle	bool | None	True to turn on, False to turn off, None to toggle.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def toggle_switch(self, toggle: bool | None = None) -> bool:
    if toggle is None:
        toggle = self.state.device_status == DeviceStatus.OFF
    status = DeviceStatus.ON if toggle else DeviceStatus.OFF

    r_dict = await self.call_bypassv1_api(
        bulb_models.RequestESL100CWBase,
        {'jsonCmd': {'light': {'action': status}}},
        'bypass',
        'bypass',
    )

    r = Helpers.process_dev_response(logger, 'toggle', self, r_dict)
    if r is None:
        logger.info('%s offline', self.device_name)
        return False
    self.state.device_status = status
    return True

turn_off async ↲

turn_off() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device off.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_off(self) -> bool:
    """Turn device off."""
    return await self.toggle_switch(False)

turn_on async ↲

turn_on() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device on.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_on(self) -> bool:
    """Turn device on."""
    return await self.toggle_switch(True)

update async ↲

update() -> None

Inherited From VeSyncBaseDevice

Update device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def update(self) -> None:
    """Update device details."""
    await self.get_details()

pyvesync.devices.vesyncbulb.VeSyncBulbESL100MC ↲

VeSyncBulbESL100MC(
    details: ResponseDeviceDetailsModel,
    manager: VeSync,
    feature_map: BulbMap,
)

Bases: BypassV2Mixin, VeSyncBulb

Etekcity ESL100 Multi Color Bulb device.

Inherits from VeSyncBulb and VeSyncBaseDevice.

The state of the bulb is stored in the state attribute, which is an of BulbState. The state attribute contains all settable states for the bulb.

Parameters:

Name	Type	Description	Default
details	dict	Dictionary of bulb state details.	required
manager	VeSync	Manager class used to make API calls.	required
feature_map	BulbMap	Device configuration map.	required

Attributes:

Name	Type	Description
state	BulbState	Device state object Each device has a separate state base class in the base_devices module.
last_response	ResponseInfo	Last response from API call.
manager	VeSync	Manager object for API calls.
device_name	str	Name of device.
device_image	str	URL for device image.
cid	str	Device ID.
connection_type	str	Connection type of device.
device_type	str	Type of device.
type	str	Type of device.
uuid	str	UUID of device, not always present.
config_module	str	Configuration module of device.
mac_id	str	MAC ID of device.
current_firm_version	str	Current firmware version of device.
device_region	str	Region of device. (US, EU, etc.)
pid	str	Product ID of device, pulled by some devices on update.
sub_device_no	int	Sub-device number of device.
product_type	str	Product type of device.
features	dict	Features of device.

Notes

The details dictionary contains the device information retrieved by the update() method:

details = {
    'brightness': 50,
    'colorMode': 'rgb',
    'color' : Color(red=0, green=0, blue=0)
}

See pyvesync.helpers.color.Color for more information on the Color dataclass.

Inherited From VeSyncBulb

Instantiate ESL100MC Multicolor Bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

def __init__(
    self, details: ResponseDeviceDetailsModel, manager: VeSync, feature_map: BulbMap
) -> None:
    """Instantiate ESL100MC Multicolor Bulb."""
    super().__init__(details, manager, feature_map)

Attributes↲

cid instance-attribute ↲

cid: str = cid

Inherited From VeSyncBaseDevice

config_module instance-attribute ↲

config_module: str = configModule

Inherited From VeSyncBaseDevice

connection_type instance-attribute ↲

connection_type: str | None = connectionType

Inherited From VeSyncBaseDevice

current_firm_version instance-attribute ↲

current_firm_version = currentFirmVersion

Inherited From VeSyncBaseDevice

device_image instance-attribute ↲

device_image: str | None = deviceImg

Inherited From VeSyncBaseDevice

device_name instance-attribute ↲

device_name: str = deviceName

Inherited From VeSyncBaseDevice

device_region instance-attribute ↲

device_region: str | None = deviceRegion

Inherited From VeSyncBaseDevice

device_type instance-attribute ↲

device_type: str = deviceType

Inherited From VeSyncBaseDevice

enabled instance-attribute ↲

enabled: bool = True

Inherited From VeSyncBaseDevice

features instance-attribute ↲

features: list[str] = features

Inherited From VeSyncBaseDevice

firmware_update property ↲

firmware_update: bool

Inherited From VeSyncBaseDevice

Return True if firmware update available.

This is going to be updated.

is_on property ↲

is_on: bool

Inherited From VeSyncBaseDevice

Return true if device is on.

last_response instance-attribute ↲

last_response: ResponseInfo | None = None

Inherited From VeSyncBaseDevice

latest_firm_version instance-attribute ↲

latest_firm_version: str | None = None

Inherited From VeSyncBaseDevice

mac_id instance-attribute ↲

mac_id: str | None = macID

Inherited From VeSyncBaseDevice

manager instance-attribute ↲

manager: VeSync

Inherited From BypassV2Mixin

pid instance-attribute ↲

pid: str | None = None

Inherited From VeSyncBaseDevice

product_type instance-attribute ↲

product_type: str = product_type

Inherited From VeSyncBaseDevice

request_keys class-attribute instance-attribute ↲

request_keys: tuple[str, ...] = (
    'acceptLanguage',
    'appVersion',
    'phoneBrand',
    'phoneOS',
    'accountID',
    'cid',
    'configModule',
    'debugMode',
    'traceId',
    'timeZone',
    'token',
    'userCountryCode',
    'configModel',
    'deviceId',
)

Inherited From BypassV2Mixin

state instance-attribute ↲

state: BulbState = BulbState(self, details, feature_map)

Inherited From VeSyncBulb

sub_device_no instance-attribute ↲

sub_device_no: int | None = subDeviceNo

Inherited From VeSyncBaseDevice

supports_brightness property ↲

supports_brightness: bool

Inherited From VeSyncBulb

Return True if bulb supports brightness.

supports_color_temp property ↲

supports_color_temp: bool

Inherited From VeSyncBulb

Return True if bulb supports color temperature.

supports_multicolor property ↲

supports_multicolor: bool

Inherited From VeSyncBulb

Return True if bulb supports backlight.

type instance-attribute ↲

type: str | None = type

Inherited From VeSyncBaseDevice

uuid instance-attribute ↲

uuid: str | None = uuid

Inherited From VeSyncBaseDevice

Functions↲

call_bypassv2_api async ↲

call_bypassv2_api(
    payload_method: str,
    data: dict | None = None,
    method: str = 'bypassV2',
    endpoint: str = 'bypassV2',
    payload_update: dict | None = None,
) -> dict | None

Inherited From BypassV2Mixin

Send Bypass V2 API request.

This uses the _build_request method to send API requests to the Bypass V2 API.

Parameters:

Name	Type	Description	Default
payload_method	str	The method to use in the payload dict.	required
data	dict | None	The data to send in the request.	None
method	str	The method to use in the outer body.	'bypassV2'
endpoint	str | None	The last part of the API url, defaults to bypassV2, e.g. /cloud/v2/deviceManaged/bypassV2.	'bypassV2'
payload_update	dict | None	Additional keys to add to the payload.	None

Returns:

Name	Type	Description
bytes	dict | None	The response from the API request.

Source code in src/pyvesync/utils/device_mixins.py

async def call_bypassv2_api(
    self,
    payload_method: str,
    data: dict | None = None,
    method: str = 'bypassV2',
    endpoint: str = 'bypassV2',
    payload_update: dict | None = None,
) -> dict | None:
    """Send Bypass V2 API request.

    This uses the `_build_request` method to send API requests to the Bypass V2 API.

    Args:
        payload_method (str): The method to use in the payload dict.
        data (dict | None): The data to send in the request.
        method (str): The method to use in the outer body.
        endpoint (str | None): The last part of the API url, defaults to
            `bypassV2`, e.g. `/cloud/v2/deviceManaged/bypassV2`.
        payload_update (dict | None): Additional keys to add to the payload.

    Returns:
        bytes: The response from the API request.
    """
    request = self._build_request(payload_method, data, method, payload_update)
    endpoint = BYPASS_V2_BASE + endpoint
    resp_dict, _ = await self.manager.async_call_api(
        endpoint, 'post', request, Helpers.req_header_bypass()
    )
    return resp_dict

clear_timer async ↲

clear_timer() -> bool

Inherited From VeSyncBaseDevice

Clear timer for device from API.

This may not be implemented for all devices. Please open an issue if there is an error.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def clear_timer(self) -> bool:
    """Clear timer for device from API.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Returns:
        bool: True if successful, False otherwise.
    """
    logger.debug('Not implemented - clear_timer')
    return False

display ↲

display(state: bool = True) -> None

Inherited From VeSyncBaseDevice

Print formatted static device info to stdout.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in display, defaults to True.	True

Example:

Device Name:..................Living Room Lamp
Model:........................ESL100
Subdevice No:.................0
Type:.........................wifi
CID:..........................1234567890abcdef

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def display(self, state: bool = True) -> None:
    """Print formatted static device info to stdout.

    Args:
        state (bool): If True, include state in display, defaults to True.

    Example:
    ```
    Device Name:..................Living Room Lamp
    Model:........................ESL100
    Subdevice No:.................0
    Type:.........................wifi
    CID:..........................1234567890abcdef
    ```
    """
    # noinspection SpellCheckingInspection
    display_list = [
        ('Device Name:', self.device_name),
        ('Product Type: ', self.product_type),
        ('Model: ', self.device_type),
        ('Subdevice No: ', str(self.sub_device_no)),
        ('Type: ', self.type),
        ('CID: ', self.cid),
        ('Config Module: ', self.config_module),
        ('Connection Type: ', self.connection_type),
        ('Features', self.features),
        ('Last Response: ', self.last_response),
    ]
    if self.uuid is not None:
        display_list.append(('UUID: ', self.uuid))

    for line in display_list:
        print(f'{line[0]:.<30} {line[1]}')  # noqa: T201
    if state:
        self.state.display()

enable_white_mode async deprecated ↲

enable_white_mode() -> bool

Inherited From VeSyncBulb

Deprecated

Use set_white_mode instead.

Enable white mode if supported by bulb.

Source code in src/pyvesync/base_devices/bulb_base.py

@deprecated('Use `set_white_mode` instead.')
async def enable_white_mode(self) -> bool:
    """Enable white mode if supported by bulb."""
    return await self.set_white_mode()

get_details async ↲

get_details() -> None

Inherited From VeSyncBaseDevice

Get device details.

This method is defined in each device class to contain the logic to pull the device state from the API and update the device's state attribute. The update() method should be called to update the device state.

Source code in src/pyvesync/devices/vesyncbulb.py

async def get_details(self) -> None:
    r_dict = await self.call_bypassv2_api('getLightStatus')

    result_model = process_bypassv2_result(
        self, logger, 'get_details', r_dict, bulb_models.ResponseESL100MCResult
    )
    if result_model is None:
        return
    self._set_state(result_model)
    return

get_state ↲

get_state(state_attr: str) -> Any

Inherited From VeSyncBaseDevice

Get device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def get_state(self, state_attr: str) -> Any:  # noqa: ANN401
    """Get device state attribute."""
    return getattr(self.state, state_attr)

get_timer async ↲

get_timer() -> Timer | None

Inherited From VeSyncBaseDevice

Get timer for device from API and set the state.Timer attribute.

This may not be implemented for all devices. Please open an issue if there is an error.

Note

This method may not be implemented for all devices. Please open an issue if there is an error.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def get_timer(self) -> Timer | None:
    """Get timer for device from API and set the `state.Timer` attribute.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Note:
        This method may not be implemented for all devices. Please
        open an issue if there is an error.
    """
    logger.debug('Not implemented - get_timer')
    return None

set_brightness async ↲

set_brightness(brightness: int) -> bool

Inherited From VeSyncBulb

Set brightness if supported by bulb.

Parameters:

Name	Type	Description	Default
brightness	NUMERIC_T	Brightness 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_brightness(self, brightness: int) -> bool:
    return await self.set_status(brightness=brightness)

set_color_mode async ↲

set_color_mode(color_mode: str) -> bool

Inherited From VeSyncBulb

Set color mode if supported by bulb.

Parameters:

Name	Type	Description	Default
color_mode	str	Color mode to set.	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_color_mode(self, color_mode: str) -> bool:
    """Set color mode if supported by bulb.

    Args:
        color_mode (str): Color mode to set.

    Returns:
        bool: True if successful, False otherwise.
    """
    del color_mode
    if self.supports_multicolor:
        logger.debug('Color mode is not configured on this bulb.')
    else:
        logger.warning('Color mode not supported by this bulb')
    return False

set_color_temp async ↲

set_color_temp(color_temp: int) -> bool

Inherited From VeSyncBulb

Set color temperature if supported by bulb.

Parameters:

Name	Type	Description	Default
color_temp	int	Color temperature 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_color_temp(self, color_temp: int) -> bool:
    """Set color temperature if supported by bulb.

    Args:
        color_temp (int): Color temperature 0-100

    Returns:
        bool: True if successful, False otherwise.
    """
    del color_temp
    if self.supports_color_temp:
        logger.debug('Color temperature is not configured on this bulb.')
    else:
        logger.debug('Color temperature not supported by this bulb')
    return False

set_hsv async ↲

set_hsv(
    hue: float, saturation: float, value: float
) -> bool

Inherited From VeSyncBulb

Set HSV if supported by bulb.

Parameters:

Name	Type	Description	Default
hue	float	Hue 0-360	required
saturation	float	Saturation 0-100	required
value	float	Value 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_hsv(self, hue: float, saturation: float, value: float) -> bool:
    hsv = Color.from_hsv(hue=hue, saturation=saturation, value=value)
    if hsv is not None:
        return await self.set_status(
            red=hsv.rgb.red, green=hsv.rgb.green, blue=hsv.rgb.blue
        )
    logger.warning('Invalid HSV values')
    return False

set_rgb async ↲

set_rgb(red: float, green: float, blue: float) -> bool

Inherited From VeSyncBulb

Set RGB if supported by bulb.

Parameters:

Name	Type	Description	Default
red	float	Red 0-255	required
green	float	green 0-255	required
blue	float	blue 0-255	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_rgb(self, red: float, green: float, blue: float) -> bool:
    return await self.set_status(red=red, green=green, blue=blue)

set_state ↲

set_state(state_attr: str, stat_value: Any) -> None

Inherited From VeSyncBaseDevice

Set device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def set_state(self, state_attr: str, stat_value: Any) -> None:  # noqa: ANN401
    """Set device state attribute."""
    setattr(self, state_attr, stat_value)

set_status async ↲

set_status(
    brightness: float | None = None,
    red: float | None = None,
    green: float | None = None,
    blue: float | None = None,
) -> bool

Set color of VeSync ESL100MC.

Brightness or RGB values must be provided. If RGB values are provided, brightness is ignored.

Parameters:

Name	Type	Description	Default
brightness	float | None	Brightness of bulb (0-100).	None
red	float | None	Red value of RGB color, 0-255.	None
green	float | None	Green value of RGB color, 0-255.	None
blue	float | None	Blue value of RGB color, 0-255.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_status(
    self,
    brightness: float | None = None,
    red: float | None = None,
    green: float | None = None,
    blue: float | None = None,
) -> bool:
    """Set color of VeSync ESL100MC.

    Brightness or RGB values must be provided. If RGB values are provided,
    brightness is ignored.

    Args:
        brightness (float | None): Brightness of bulb (0-100).
        red (float | None): Red value of RGB color, 0-255.
        green (float | None): Green value of RGB color, 0-255.
        blue (float | None): Blue value of RGB color, 0-255.

    Returns:
        bool: True if successful, False otherwise.
    """
    brightness_update = 100
    if red is not None and green is not None and blue is not None:
        new_color = Color.from_rgb(red, green, blue)
        color_mode = 'color'
        if (
            self.state.device_status == DeviceStatus.ON
            and new_color == self.state.color
        ):
            logger.debug('New color is same as current color')
            return True
    else:
        logger.debug('RGB Values not provided')
        new_color = None
        if brightness is not None:
            if Validators.validate_zero_to_hundred(brightness):
                brightness_update = int(brightness)
            else:
                logger.warning('Invalid brightness value')
                return False
            if (
                self.state.device_status == DeviceStatus.ON
                and brightness_update == self.state.brightness
            ):
                logger.debug('Brightness already set to %s', brightness)
                return True
            color_mode = 'white'
        else:
            logger.warning('Brightness and RGB values are not set')
            return False

    data = {
        'action': DeviceStatus.ON,
        'speed': 0,
        'brightness': brightness_update,
        'red': 0 if new_color is None else int(new_color.rgb.red),
        'green': 0 if new_color is None else int(new_color.rgb.green),
        'blue': 0 if new_color is None else int(new_color.rgb.blue),
        'colorMode': 'color' if new_color is not None else 'white',
    }
    r_dict = await self.call_bypassv2_api('setLightStatus', data)

    r = Helpers.process_dev_response(logger, 'set_status', self, r_dict)
    if r is None:
        return False

    if color_mode == 'color' and new_color is not None:
        self.state.color_mode = 'color'
        self.state.color = new_color
    elif brightness is not None:
        self.state.brightness = int(brightness_update)
        self.state.color_mode = 'white'

    self.state.device_status = DeviceStatus.ON
    self.state.connection_status = ConnectionStatus.ONLINE
    return True

set_timer async ↲

set_timer(duration: int, action: str | None = None) -> bool

Inherited From VeSyncBaseDevice

Set timer for device.

This may not be implemented for all devices. Please open an issue if there is an error.

Parameters:

Name	Type	Description	Default
duration	int	Duration in seconds.	required
action	str | None	Action to take when timer expires.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def set_timer(self, duration: int, action: str | None = None) -> bool:
    """Set timer for device.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Args:
        duration (int): Duration in seconds.
        action (str | None): Action to take when timer expires.

    Returns:
        bool: True if successful, False otherwise.
    """
    del duration
    del action
    logger.debug('Not implemented - set_timer')
    return False

set_white_mode async ↲

set_white_mode() -> bool

Inherited From VeSyncBulb

Set white mode if supported by bulb.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_white_mode(self) -> bool:
    return await self.set_status(brightness=100)

to_dict ↲

to_dict(state: bool = True) -> dict[str, Any]

Inherited From VeSyncBaseDevice

Return device information as a dictionary.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in dictionary, defaults to True.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing device information.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_dict(self, state: bool = True) -> dict[str, Any]:
    """Return device information as a dictionary.

    Args:
        state (bool): If True, include state in dictionary, defaults to True.

    Returns:
        dict[str, Any]: Dictionary containing device information.
    """
    device_dict = {
        'device_name': self.device_name,
        'product_type': self.product_type,
        'model': self.device_type,
        'subdevice_no': str(self.sub_device_no),
        'type': self.type,
        'cid': self.cid,
        'features:': self.features,
        'config_module': self.config_module,
        'connection_type': self.connection_type,
        'last_response': self.last_response,
    }
    state_dict = self.state.to_dict() if state else {}
    return device_dict | state_dict

to_json ↲

to_json(state: bool = True, indent: bool = True) -> str

Inherited From VeSyncBaseDevice

Print JSON API string for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
str	str	JSON formatted string of device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_json(self, state: bool = True, indent: bool = True) -> str:
    """Print JSON API string for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        str: JSON formatted string of device details.
    """
    return self.to_jsonb(state, indent).decode()

to_jsonb ↲

to_jsonb(state: bool = True, indent: bool = True) -> bytes

Inherited From VeSyncBaseDevice

JSON API bytes for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
bytes	bytes	JSON formatted bytes of device details.

Example

This is an example without state.

{
    "Device Name": "Living Room Lamp",
    "Model": "ESL100",
    "Subdevice No": "0",
    "Type": "wifi",
    "CID": "1234567890abcdef"
}

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_jsonb(self, state: bool = True, indent: bool = True) -> bytes:
    """JSON API bytes for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        bytes: JSON formatted bytes of device details.

    Example:
        This is an example without state.
        ```
        {
            "Device Name": "Living Room Lamp",
            "Model": "ESL100",
            "Subdevice No": "0",
            "Type": "wifi",
            "CID": "1234567890abcdef"
        }
        ```
    """
    return_dict = self.to_dict(state=state)
    if indent:
        return orjson.dumps(
            return_dict,
            option=orjson.OPT_INDENT_2 | orjson.OPT_NON_STR_KEYS,
        )

    return orjson.dumps(return_dict, option=orjson.OPT_NON_STR_KEYS)

toggle async deprecated ↲

toggle(status: str) -> bool

Deprecated

toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead

Toggle switch of VeSync ESL100MC.

Source code in src/pyvesync/devices/vesyncbulb.py

@deprecated(
    'toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead'
)
async def toggle(self, status: str) -> bool:
    """Toggle switch of VeSync ESL100MC."""
    status_bool = status == DeviceStatus.ON
    return await self.toggle_switch(status_bool)

toggle_switch async ↲

toggle_switch(toggle: bool | None = None) -> bool

Inherited From VeSyncBaseToggleDevice

Toggle device power on or off.

Parameters:

Name	Type	Description	Default
toggle	bool | None	True to turn on, False to turn off, None to toggle.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def toggle_switch(self, toggle: bool | None = None) -> bool:
    if toggle is None:
        toggle = self.state.device_status == DeviceStatus.OFF
    data = {'id': 0, 'enabled': toggle}

    r_dict = await self.call_bypassv2_api('setSwitch', data)

    r = Helpers.process_dev_response(logger, 'toggle', self, r_dict)
    if r is None:
        return False

    self.state.device_status = DeviceStatus.ON if toggle else DeviceStatus.OFF
    return True

turn_off async ↲

turn_off() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device off.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_off(self) -> bool:
    """Turn device off."""
    return await self.toggle_switch(False)

turn_on async ↲

turn_on() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device on.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_on(self) -> bool:
    """Turn device on."""
    return await self.toggle_switch(True)

update async ↲

update() -> None

Inherited From VeSyncBaseDevice

Update device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def update(self) -> None:
    """Update device details."""
    await self.get_details()

pyvesync.devices.vesyncbulb.VeSyncBulbValcenoA19MC ↲

VeSyncBulbValcenoA19MC(
    details: ResponseDeviceDetailsModel,
    manager: VeSync,
    feature_map: BulbMap,
)

Bases: VeSyncBulb

VeSync Multicolor Bulb.

This bulb only has the dimmable feature. Inherits from [VeSyncBulb][pyvesync.devices.vesyncbulb.VeSyncBulb] and VeSyncBaseToggleDevice.

Device state is held in the state attribute, which is an instance of BulbState. The state attribute contains all settable states for the bulb.

Parameters:

Name	Type	Description	Default
details	dict	Dictionary of bulb state details.	required
manager	VeSync	Manager class used to make API calls	required
feature_map	BulbMap	Device configuration map.	required

Attributes:

Name	Type	Description
state	BulbState	Device state object Each device has a separate state base class in the base_devices module.
last_response	ResponseInfo	Last response from API call.
manager	VeSync	Manager object for API calls.
device_name	str	Name of device.
device_image	str	URL for device image.
cid	str	Device ID.
connection_type	str	Connection type of device.
device_type	str	Type of device.
type	str	Type of device.
uuid	str	UUID of device, not always present.
config_module	str	Configuration module of device.
mac_id	str	MAC ID of device.
current_firm_version	str	Current firmware version of device.
device_region	str	Region of device. (US, EU, etc.)
pid	str	Product ID of device, pulled by some devices on update.
sub_device_no	int	Sub-device number of device.
product_type	str	Product type of device.
features	dict	Features of device.

Inherited From VeSyncBulb

Initialize Multicolor bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

def __init__(
    self, details: ResponseDeviceDetailsModel, manager: VeSync, feature_map: BulbMap
) -> None:
    """Initialize Multicolor bulb."""
    super().__init__(details, manager, feature_map)
    self.request_keys = (
        'acceptLanguage',
        'accountID',
        'appVersion',
        'cid',
        'configModule',
        'deviceRegion',
        'debugMode',
        'phoneBrand',
        'phoneOS',
        'timeZone',
        'token',
        'traceId',
    )

Attributes↲

cid instance-attribute ↲

cid: str = cid

Inherited From VeSyncBaseDevice

config_module instance-attribute ↲

config_module: str = configModule

Inherited From VeSyncBaseDevice

connection_type instance-attribute ↲

connection_type: str | None = connectionType

Inherited From VeSyncBaseDevice

current_firm_version instance-attribute ↲

current_firm_version = currentFirmVersion

Inherited From VeSyncBaseDevice

device_image instance-attribute ↲

device_image: str | None = deviceImg

Inherited From VeSyncBaseDevice

device_name instance-attribute ↲

device_name: str = deviceName

Inherited From VeSyncBaseDevice

device_region instance-attribute ↲

device_region: str | None = deviceRegion

Inherited From VeSyncBaseDevice

device_type instance-attribute ↲

device_type: str = deviceType

Inherited From VeSyncBaseDevice

enabled instance-attribute ↲

enabled: bool = True

Inherited From VeSyncBaseDevice

features instance-attribute ↲

features: list[str] = features

Inherited From VeSyncBaseDevice

firmware_update property ↲

firmware_update: bool

Inherited From VeSyncBaseDevice

Return True if firmware update available.

This is going to be updated.

is_on property ↲

is_on: bool

Inherited From VeSyncBaseDevice

Return true if device is on.

last_response instance-attribute ↲

last_response: ResponseInfo | None = None

Inherited From VeSyncBaseDevice

latest_firm_version instance-attribute ↲

latest_firm_version: str | None = None

Inherited From VeSyncBaseDevice

mac_id instance-attribute ↲

mac_id: str | None = macID

Inherited From VeSyncBaseDevice

manager instance-attribute ↲

manager = manager

Inherited From VeSyncBaseDevice

pid instance-attribute ↲

pid: str | None = None

Inherited From VeSyncBaseDevice

product_type instance-attribute ↲

product_type: str = product_type

Inherited From VeSyncBaseDevice

request_keys instance-attribute ↲

request_keys = (
    'acceptLanguage',
    'accountID',
    'appVersion',
    'cid',
    'configModule',
    'deviceRegion',
    'debugMode',
    'phoneBrand',
    'phoneOS',
    'timeZone',
    'token',
    'traceId',
)

state instance-attribute ↲

state: BulbState = BulbState(self, details, feature_map)

Inherited From VeSyncBulb

sub_device_no instance-attribute ↲

sub_device_no: int | None = subDeviceNo

Inherited From VeSyncBaseDevice

supports_brightness property ↲

supports_brightness: bool

Inherited From VeSyncBulb

Return True if bulb supports brightness.

supports_color_temp property ↲

supports_color_temp: bool

Inherited From VeSyncBulb

Return True if bulb supports color temperature.

supports_multicolor property ↲

supports_multicolor: bool

Inherited From VeSyncBulb

Return True if bulb supports backlight.

type instance-attribute ↲

type: str | None = type

Inherited From VeSyncBaseDevice

uuid instance-attribute ↲

uuid: str | None = uuid

Inherited From VeSyncBaseDevice

Functions↲

clear_timer async ↲

clear_timer() -> bool

Inherited From VeSyncBaseDevice

Clear timer for device from API.

This may not be implemented for all devices. Please open an issue if there is an error.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def clear_timer(self) -> bool:
    """Clear timer for device from API.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Returns:
        bool: True if successful, False otherwise.
    """
    logger.debug('Not implemented - clear_timer')
    return False

display ↲

display(state: bool = True) -> None

Inherited From VeSyncBaseDevice

Print formatted static device info to stdout.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in display, defaults to True.	True

Example:

Device Name:..................Living Room Lamp
Model:........................ESL100
Subdevice No:.................0
Type:.........................wifi
CID:..........................1234567890abcdef

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def display(self, state: bool = True) -> None:
    """Print formatted static device info to stdout.

    Args:
        state (bool): If True, include state in display, defaults to True.

    Example:
    ```
    Device Name:..................Living Room Lamp
    Model:........................ESL100
    Subdevice No:.................0
    Type:.........................wifi
    CID:..........................1234567890abcdef
    ```
    """
    # noinspection SpellCheckingInspection
    display_list = [
        ('Device Name:', self.device_name),
        ('Product Type: ', self.product_type),
        ('Model: ', self.device_type),
        ('Subdevice No: ', str(self.sub_device_no)),
        ('Type: ', self.type),
        ('CID: ', self.cid),
        ('Config Module: ', self.config_module),
        ('Connection Type: ', self.connection_type),
        ('Features', self.features),
        ('Last Response: ', self.last_response),
    ]
    if self.uuid is not None:
        display_list.append(('UUID: ', self.uuid))

    for line in display_list:
        print(f'{line[0]:.<30} {line[1]}')  # noqa: T201
    if state:
        self.state.display()

enable_white_mode async deprecated ↲

enable_white_mode() -> bool

Inherited From VeSyncBulb

Deprecated

Use set_white_mode instead.

Enable white mode if supported by bulb.

Source code in src/pyvesync/base_devices/bulb_base.py

@deprecated('Use `set_white_mode` instead.')
async def enable_white_mode(self) -> bool:
    """Enable white mode if supported by bulb."""
    return await self.set_white_mode()

get_details async ↲

get_details() -> None

Inherited From VeSyncBaseDevice

Get device details.

This method is defined in each device class to contain the logic to pull the device state from the API and update the device's state attribute. The update() method should be called to update the device state.

Source code in src/pyvesync/devices/vesyncbulb.py

async def get_details(self) -> None:
    r_dict = await self._call_valceno_api('getLightStatusV2', {})

    if r_dict is None:
        return

    status = bulb_models.ResponseValcenoStatus.from_dict(r_dict)
    self._interpret_apicall_result(status)

get_state ↲

get_state(state_attr: str) -> Any

Inherited From VeSyncBaseDevice

Get device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def get_state(self, state_attr: str) -> Any:  # noqa: ANN401
    """Get device state attribute."""
    return getattr(self.state, state_attr)

get_timer async ↲

get_timer() -> Timer | None

Inherited From VeSyncBaseDevice

Get timer for device from API and set the state.Timer attribute.

This may not be implemented for all devices. Please open an issue if there is an error.

Note

This method may not be implemented for all devices. Please open an issue if there is an error.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def get_timer(self) -> Timer | None:
    """Get timer for device from API and set the `state.Timer` attribute.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Note:
        This method may not be implemented for all devices. Please
        open an issue if there is an error.
    """
    logger.debug('Not implemented - get_timer')
    return None

set_brightness async ↲

set_brightness(brightness: int) -> bool

Inherited From VeSyncBulb

Set brightness of multicolor bulb.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_brightness(self, brightness: int) -> bool:
    """Set brightness of multicolor bulb."""
    return await self.set_status(brightness=brightness)

set_color_hue async ↲

set_color_hue(color_hue: float) -> bool

Set Color Hue of Bulb (0 - 360).

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_color_hue(self, color_hue: float) -> bool:
    """Set Color Hue of Bulb (0 - 360)."""
    return await self.set_status(color_hue=color_hue)

set_color_mode async ↲

set_color_mode(color_mode: str) -> bool

Inherited From VeSyncBulb

Set Color Mode of Bulb (white / hsv).

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_color_mode(self, color_mode: str) -> bool:
    """Set Color Mode of Bulb (white / hsv)."""
    return await self.set_status(color_mode=color_mode)

set_color_saturation async ↲

set_color_saturation(color_saturation: float) -> bool

Set Color Saturation of Bulb in pct (1 - 100).

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_color_saturation(self, color_saturation: float) -> bool:
    """Set Color Saturation of Bulb in pct (1 - 100)."""
    return await self.set_status(color_saturation=color_saturation)

set_color_temp async ↲

set_color_temp(color_temp: int) -> bool

Inherited From VeSyncBulb

Set White Temperature of Bulb in pct (0 - 100).

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_color_temp(self, color_temp: int) -> bool:
    """Set White Temperature of Bulb in pct (0 - 100)."""
    return await self.set_status(color_temp=color_temp)

set_color_value async ↲

set_color_value(color_value: float) -> bool

Set Value of multicolor bulb in pct (1 - 100).

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_color_value(self, color_value: float) -> bool:
    """Set Value of multicolor bulb in pct (1 - 100)."""
    # Equivalent to brightness level, when in color mode.
    return await self.set_status(color_value=color_value)

set_hsv async ↲

set_hsv(
    hue: float, saturation: float, value: float
) -> bool

Inherited From VeSyncBulb

Set HSV if supported by bulb.

Parameters:

Name	Type	Description	Default
hue	float	Hue 0-360	required
saturation	float	Saturation 0-100	required
value	float	Value 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_hsv(self, hue: float, saturation: float, value: float) -> bool:
    new_color = Color.from_hsv(hue=hue, saturation=saturation, value=value)
    if new_color is None:
        logger.warning('Invalid HSV values')
        return False

    # the api expects the hsv Value in the brightness parameter
    payload_data = self._build_status_payload(
        hue=hue,
        saturation=saturation,
        value=value,
    )
    if payload_data is None:
        return False
    resp = await self._call_valceno_api('setLightStatusV2', payload_data)
    if resp is None:
        return False

    r_dict = Helpers.process_dev_response(logger, 'set_hsv', self, resp)
    if r_dict is None:
        return False

    status = bulb_models.ResponseValcenoStatus.from_dict(r_dict)
    self._interpret_apicall_result(status)
    return True

set_rgb async ↲

set_rgb(red: float, green: float, blue: float) -> bool

Inherited From VeSyncBulb

Set RGB if supported by bulb.

Parameters:

Name	Type	Description	Default
red	float	Red 0-255	required
green	float	green 0-255	required
blue	float	blue 0-255	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_rgb(self, red: float, green: float, blue: float) -> bool:
    new_color = Color.from_rgb(red=red, green=green, blue=blue)
    if new_color is None:
        logger.warning('Invalid RGB values')
        return False

    return await self.set_hsv(
        hue=new_color.hsv.hue,
        saturation=new_color.hsv.saturation,
        value=new_color.hsv.value,
    )

set_state ↲

set_state(state_attr: str, stat_value: Any) -> None

Inherited From VeSyncBaseDevice

Set device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def set_state(self, state_attr: str, stat_value: Any) -> None:  # noqa: ANN401
    """Set device state attribute."""
    setattr(self, state_attr, stat_value)

set_status async ↲

set_status(
    *,
    brightness: float | None = None,
    color_temp: float | None = None,
    color_hue: float | None = None,
    color_saturation: float | None = None,
    color_value: float | None = None,
    color_mode: str | None = None,
) -> bool

Set multicolor bulb parameters.

No arguments turns bulb on. Kwargs only

Parameters:

Name	Type	Description	Default
brightness	int	brightness between 0 and 100	None
color_temp	int	color temperature between 0 and 100	None
color_mode	int	color mode hsv or white	None
color_hue	float	color hue between 0 and 360	None
color_saturation	float	color saturation between 0 and 100	None
color_value	int	color value between 0 and 100	None

Returns:

Name	Type	Description
bool	bool	True if call was successful, False otherwise

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_status(
    self,
    *,
    brightness: float | None = None,
    color_temp: float | None = None,
    color_hue: float | None = None,
    color_saturation: float | None = None,
    color_value: float | None = None,
    color_mode: str | None = None,
) -> bool:
    """Set multicolor bulb parameters.

    No arguments turns bulb on. **Kwargs only**

    Args:
        brightness (int, optional): brightness between 0 and 100
        color_temp (int, optional): color temperature between 0 and 100
        color_mode (int, optional): color mode hsv or white
        color_hue (float, optional): color hue between 0 and 360
        color_saturation (float, optional): color saturation between 0 and 100
        color_value (int, optional): color value between 0 and 100

    Returns:
        bool : True if call was successful, False otherwise
    """
    payload_data = self._build_status_payload(
        brightness=brightness,
        color_temp=color_temp,
        hue=color_hue,
        saturation=color_saturation,
        value=color_value,
        color_mode=color_mode,
    )
    if payload_data == self._payload_base():
        logger.debug('No state change.')
        return False
    if payload_data is None:
        logger.warning(
            'Invalid payload data for set_status call for %s', self.device_name
        )
        return False

    r_dict = await self._call_valceno_api('setLightStatusV2', payload_data)
    if r_dict is None:
        return False

    r_dict = Helpers.process_dev_response(logger, 'set_status', self, r_dict)
    if r_dict is None:
        return False

    r_model = bulb_models.ResponseValcenoStatus.from_dict(r_dict)
    self._interpret_apicall_result(r_model)
    return True

set_timer async ↲

set_timer(duration: int, action: str | None = None) -> bool

Inherited From VeSyncBaseDevice

Set timer for device.

This may not be implemented for all devices. Please open an issue if there is an error.

Parameters:

Name	Type	Description	Default
duration	int	Duration in seconds.	required
action	str | None	Action to take when timer expires.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def set_timer(self, duration: int, action: str | None = None) -> bool:
    """Set timer for device.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Args:
        duration (int): Duration in seconds.
        action (str | None): Action to take when timer expires.

    Returns:
        bool: True if successful, False otherwise.
    """
    del duration
    del action
    logger.debug('Not implemented - set_timer')
    return False

set_white_mode async ↲

set_white_mode() -> bool

Inherited From VeSyncBulb

Set white mode if supported by bulb.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def set_white_mode(self) -> bool:
    return await self.set_status(color_mode='white')

to_dict ↲

to_dict(state: bool = True) -> dict[str, Any]

Inherited From VeSyncBaseDevice

Return device information as a dictionary.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in dictionary, defaults to True.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing device information.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_dict(self, state: bool = True) -> dict[str, Any]:
    """Return device information as a dictionary.

    Args:
        state (bool): If True, include state in dictionary, defaults to True.

    Returns:
        dict[str, Any]: Dictionary containing device information.
    """
    device_dict = {
        'device_name': self.device_name,
        'product_type': self.product_type,
        'model': self.device_type,
        'subdevice_no': str(self.sub_device_no),
        'type': self.type,
        'cid': self.cid,
        'features:': self.features,
        'config_module': self.config_module,
        'connection_type': self.connection_type,
        'last_response': self.last_response,
    }
    state_dict = self.state.to_dict() if state else {}
    return device_dict | state_dict

to_json ↲

to_json(state: bool = True, indent: bool = True) -> str

Inherited From VeSyncBaseDevice

Print JSON API string for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
str	str	JSON formatted string of device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_json(self, state: bool = True, indent: bool = True) -> str:
    """Print JSON API string for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        str: JSON formatted string of device details.
    """
    return self.to_jsonb(state, indent).decode()

to_jsonb ↲

to_jsonb(state: bool = True, indent: bool = True) -> bytes

Inherited From VeSyncBaseDevice

JSON API bytes for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
bytes	bytes	JSON formatted bytes of device details.

Example

This is an example without state.

{
    "Device Name": "Living Room Lamp",
    "Model": "ESL100",
    "Subdevice No": "0",
    "Type": "wifi",
    "CID": "1234567890abcdef"
}

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_jsonb(self, state: bool = True, indent: bool = True) -> bytes:
    """JSON API bytes for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        bytes: JSON formatted bytes of device details.

    Example:
        This is an example without state.
        ```
        {
            "Device Name": "Living Room Lamp",
            "Model": "ESL100",
            "Subdevice No": "0",
            "Type": "wifi",
            "CID": "1234567890abcdef"
        }
        ```
    """
    return_dict = self.to_dict(state=state)
    if indent:
        return orjson.dumps(
            return_dict,
            option=orjson.OPT_INDENT_2 | orjson.OPT_NON_STR_KEYS,
        )

    return orjson.dumps(return_dict, option=orjson.OPT_NON_STR_KEYS)

toggle async deprecated ↲

toggle(status: str) -> bool

Deprecated

toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead

Deprecated - use toggle_switch().

Source code in src/pyvesync/devices/vesyncbulb.py

@deprecated(
    'toggle() is deprecated, use toggle_switch(toggle: bool | None = None) instead'
)
async def toggle(self, status: str) -> bool:
    """Deprecated - use toggle_switch()."""
    status_bool = status == DeviceStatus.ON
    return await self.toggle_switch(status_bool)

toggle_switch async ↲

toggle_switch(toggle: bool | None = None) -> bool

Inherited From VeSyncBaseToggleDevice

Toggle device power on or off.

Parameters:

Name	Type	Description	Default
toggle	bool | None	True to turn on, False to turn off, None to toggle.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/devices/vesyncbulb.py

async def toggle_switch(self, toggle: bool | None = None) -> bool:
    if toggle is None:
        toggle = self.state.device_status == DeviceStatus.OFF

    if toggle == self.state.device_status:
        logger.warning('Device already in requested state')
        return True

    payload_data = {
        'id': 0,
        'enabled': toggle,
    }
    method = 'setSwitch'

    r_dict = await self._call_valceno_api(method, payload_data)

    if r_dict is None:
        self.state.device_status = DeviceStatus.OFF
        return False
    self.state.device_status = DeviceStatus.ON if toggle else DeviceStatus.OFF
    self.state.connection_status = ConnectionStatus.ONLINE
    return True

turn_off async ↲

turn_off() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device off.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_off(self) -> bool:
    """Turn device off."""
    return await self.toggle_switch(False)

turn_on async ↲

turn_on() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device on.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_on(self) -> bool:
    """Turn device on."""
    return await self.toggle_switch(True)

update async ↲

update() -> None

Inherited From VeSyncBaseDevice

Update device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def update(self) -> None:
    """Update device details."""
    await self.get_details()

pyvesync.base_devices.bulb_base.VeSyncBulb ↲

VeSyncBulb(
    details: ResponseDeviceDetailsModel,
    manager: VeSync,
    feature_map: BulbMap,
)

Bases: VeSyncBaseToggleDevice[BulbState]

Base class for VeSync Bulbs.

Abstract base class to provide methods for controlling and getting details of VeSync bulbs. Inherits from VeSyncBaseDevice. This class should not be used directly for devices, but rather subclassed for each bulb.

Parameters:

Name	Type	Description	Default
details	ResponseDeviceDetailsModel	Device details from API.	required
manager	VeSync	VeSync API manager.	required
feature_map	BulbMap	Feature map for bulb.	required

Attributes:

Name	Type	Description
state	BulbState	Device state object Each device has a separate state base class in the base_devices module.
last_response	ResponseInfo	Last response from API call.
manager	VeSync	Manager object for API calls.
device_name	str	Name of device.
device_image	str	URL for device image.
cid	str	Device ID.
connection_type	str	Connection type of device.
device_type	str	Type of device.
type	str	Type of device.
uuid	str	UUID of device, not always present.
config_module	str	Configuration module of device.
mac_id	str	MAC ID of device.
current_firm_version	str	Current firmware version of device.
device_region	str	Region of device. (US, EU, etc.)
pid	str	Product ID of device, pulled by some devices on update.
sub_device_no	int	Sub-device number of device.
product_type	str	Product type of device.
features	dict	Features of device.

Inherited From VeSyncBaseDevice

Initialize VeSync smart bulb base class.

Source code in src/pyvesync/base_devices/bulb_base.py

def __init__(
    self, details: ResponseDeviceDetailsModel, manager: VeSync, feature_map: BulbMap
) -> None:
    """Initialize VeSync smart bulb base class."""
    super().__init__(details, manager, feature_map)
    self.state: BulbState = BulbState(self, details, feature_map)

Attributes↲

cid instance-attribute ↲

cid: str = cid

Inherited From VeSyncBaseDevice

config_module instance-attribute ↲

config_module: str = configModule

Inherited From VeSyncBaseDevice

connection_type instance-attribute ↲

connection_type: str | None = connectionType

Inherited From VeSyncBaseDevice

current_firm_version instance-attribute ↲

current_firm_version = currentFirmVersion

Inherited From VeSyncBaseDevice

device_image instance-attribute ↲

device_image: str | None = deviceImg

Inherited From VeSyncBaseDevice

device_name instance-attribute ↲

device_name: str = deviceName

Inherited From VeSyncBaseDevice

device_region instance-attribute ↲

device_region: str | None = deviceRegion

Inherited From VeSyncBaseDevice

device_type instance-attribute ↲

device_type: str = deviceType

Inherited From VeSyncBaseDevice

enabled instance-attribute ↲

enabled: bool = True

Inherited From VeSyncBaseDevice

features instance-attribute ↲

features: list[str] = features

Inherited From VeSyncBaseDevice

firmware_update property ↲

firmware_update: bool

Inherited From VeSyncBaseDevice

Return True if firmware update available.

This is going to be updated.

is_on property ↲

is_on: bool

Inherited From VeSyncBaseDevice

Return true if device is on.

last_response instance-attribute ↲

last_response: ResponseInfo | None = None

Inherited From VeSyncBaseDevice

latest_firm_version instance-attribute ↲

latest_firm_version: str | None = None

Inherited From VeSyncBaseDevice

mac_id instance-attribute ↲

mac_id: str | None = macID

Inherited From VeSyncBaseDevice

manager instance-attribute ↲

manager = manager

Inherited From VeSyncBaseDevice

pid instance-attribute ↲

pid: str | None = None

Inherited From VeSyncBaseDevice

product_type instance-attribute ↲

product_type: str = product_type

Inherited From VeSyncBaseDevice

state instance-attribute ↲

state: BulbState = BulbState(self, details, feature_map)

Inherited From VeSyncBulb

sub_device_no instance-attribute ↲

sub_device_no: int | None = subDeviceNo

Inherited From VeSyncBaseDevice

supports_brightness property ↲

supports_brightness: bool

Inherited From VeSyncBulb

Return True if bulb supports brightness.

supports_color_temp property ↲

supports_color_temp: bool

Inherited From VeSyncBulb

Return True if bulb supports color temperature.

supports_multicolor property ↲

supports_multicolor: bool

Inherited From VeSyncBulb

Return True if bulb supports backlight.

type instance-attribute ↲

type: str | None = type

Inherited From VeSyncBaseDevice

uuid instance-attribute ↲

uuid: str | None = uuid

Inherited From VeSyncBaseDevice

Functions↲

clear_timer async ↲

clear_timer() -> bool

Inherited From VeSyncBaseDevice

Clear timer for device from API.

This may not be implemented for all devices. Please open an issue if there is an error.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def clear_timer(self) -> bool:
    """Clear timer for device from API.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Returns:
        bool: True if successful, False otherwise.
    """
    logger.debug('Not implemented - clear_timer')
    return False

display ↲

display(state: bool = True) -> None

Inherited From VeSyncBaseDevice

Print formatted static device info to stdout.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in display, defaults to True.	True

Example:

Device Name:..................Living Room Lamp
Model:........................ESL100
Subdevice No:.................0
Type:.........................wifi
CID:..........................1234567890abcdef

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def display(self, state: bool = True) -> None:
    """Print formatted static device info to stdout.

    Args:
        state (bool): If True, include state in display, defaults to True.

    Example:
    ```
    Device Name:..................Living Room Lamp
    Model:........................ESL100
    Subdevice No:.................0
    Type:.........................wifi
    CID:..........................1234567890abcdef
    ```
    """
    # noinspection SpellCheckingInspection
    display_list = [
        ('Device Name:', self.device_name),
        ('Product Type: ', self.product_type),
        ('Model: ', self.device_type),
        ('Subdevice No: ', str(self.sub_device_no)),
        ('Type: ', self.type),
        ('CID: ', self.cid),
        ('Config Module: ', self.config_module),
        ('Connection Type: ', self.connection_type),
        ('Features', self.features),
        ('Last Response: ', self.last_response),
    ]
    if self.uuid is not None:
        display_list.append(('UUID: ', self.uuid))

    for line in display_list:
        print(f'{line[0]:.<30} {line[1]}')  # noqa: T201
    if state:
        self.state.display()

enable_white_mode async deprecated ↲

enable_white_mode() -> bool

Inherited From VeSyncBulb

Deprecated

Use set_white_mode instead.

Enable white mode if supported by bulb.

Source code in src/pyvesync/base_devices/bulb_base.py

@deprecated('Use `set_white_mode` instead.')
async def enable_white_mode(self) -> bool:
    """Enable white mode if supported by bulb."""
    return await self.set_white_mode()

get_details abstractmethod async ↲

get_details() -> None

Inherited From VeSyncBaseDevice

Get device details.

This method is defined in each device class to contain the logic to pull the device state from the API and update the device's state attribute. The update() method should be called to update the device state.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

@abstractmethod
async def get_details(self) -> None:
    """Get device details.

    This method is defined in each device class to contain
    the logic to pull the device state from the API and update
    the device's `state` attribute. The `update()` method should
    be called to update the device state.
    """

get_state ↲

get_state(state_attr: str) -> Any

Inherited From VeSyncBaseDevice

Get device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def get_state(self, state_attr: str) -> Any:  # noqa: ANN401
    """Get device state attribute."""
    return getattr(self.state, state_attr)

get_timer async ↲

get_timer() -> Timer | None

Inherited From VeSyncBaseDevice

Get timer for device from API and set the state.Timer attribute.

This may not be implemented for all devices. Please open an issue if there is an error.

Note

This method may not be implemented for all devices. Please open an issue if there is an error.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def get_timer(self) -> Timer | None:
    """Get timer for device from API and set the `state.Timer` attribute.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Note:
        This method may not be implemented for all devices. Please
        open an issue if there is an error.
    """
    logger.debug('Not implemented - get_timer')
    return None

set_brightness async ↲

set_brightness(brightness: int) -> bool

Inherited From VeSyncBulb

Set brightness if supported by bulb.

Parameters:

Name	Type	Description	Default
brightness	NUMERIC_T	Brightness 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_brightness(self, brightness: int) -> bool:
    """Set brightness if supported by bulb.

    Args:
        brightness (NUMERIC_T): Brightness 0-100

    Returns:
        bool: True if successful, False otherwise.
    """
    del brightness
    logger.warning('Brightness not supported/configured by this bulb')
    return False

set_color_mode async ↲

set_color_mode(color_mode: str) -> bool

Inherited From VeSyncBulb

Set color mode if supported by bulb.

Parameters:

Name	Type	Description	Default
color_mode	str	Color mode to set.	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_color_mode(self, color_mode: str) -> bool:
    """Set color mode if supported by bulb.

    Args:
        color_mode (str): Color mode to set.

    Returns:
        bool: True if successful, False otherwise.
    """
    del color_mode
    if self.supports_multicolor:
        logger.debug('Color mode is not configured on this bulb.')
    else:
        logger.warning('Color mode not supported by this bulb')
    return False

set_color_temp async ↲

set_color_temp(color_temp: int) -> bool

Inherited From VeSyncBulb

Set color temperature if supported by bulb.

Parameters:

Name	Type	Description	Default
color_temp	int	Color temperature 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_color_temp(self, color_temp: int) -> bool:
    """Set color temperature if supported by bulb.

    Args:
        color_temp (int): Color temperature 0-100

    Returns:
        bool: True if successful, False otherwise.
    """
    del color_temp
    if self.supports_color_temp:
        logger.debug('Color temperature is not configured on this bulb.')
    else:
        logger.debug('Color temperature not supported by this bulb')
    return False

set_hsv async ↲

set_hsv(
    hue: float, saturation: float, value: float
) -> bool

Inherited From VeSyncBulb

Set HSV if supported by bulb.

Parameters:

Name	Type	Description	Default
hue	float	Hue 0-360	required
saturation	float	Saturation 0-100	required
value	float	Value 0-100	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_hsv(self, hue: float, saturation: float, value: float) -> bool:
    """Set HSV if supported by bulb.

    Args:
        hue (float): Hue 0-360
        saturation (float): Saturation 0-100
        value (float): Value 0-100

    Returns:
        bool: True if successful, False otherwise.
    """
    del hue, saturation, value
    if not self.supports_multicolor:
        logger.debug('Color mode is not supported on this bulb.')
    else:
        logger.debug('set_hsv not configured for %s bulb', self.device_type)
    return False

set_rgb async ↲

set_rgb(red: float, green: float, blue: float) -> bool

Inherited From VeSyncBulb

Set RGB if supported by bulb.

Parameters:

Name	Type	Description	Default
red	float	Red 0-255	required
green	float	green 0-255	required
blue	float	blue 0-255	required

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_rgb(self, red: float, green: float, blue: float) -> bool:
    """Set RGB if supported by bulb.

    Args:
        red (float): Red 0-255
        green (float): green 0-255
        blue (float): blue 0-255

    Returns:
        bool: True if successful, False otherwise.
    """
    del red, green, blue
    if not self.supports_multicolor:
        logger.debug('Color mode is not supported on this bulb.')
    else:
        logger.debug('set_rgb not configured for %s bulb', self.device_type)
    return False

set_state ↲

set_state(state_attr: str, stat_value: Any) -> None

Inherited From VeSyncBaseDevice

Set device state attribute.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def set_state(self, state_attr: str, stat_value: Any) -> None:  # noqa: ANN401
    """Set device state attribute."""
    setattr(self, state_attr, stat_value)

set_timer async ↲

set_timer(duration: int, action: str | None = None) -> bool

Inherited From VeSyncBaseDevice

Set timer for device.

This may not be implemented for all devices. Please open an issue if there is an error.

Parameters:

Name	Type	Description	Default
duration	int	Duration in seconds.	required
action	str | None	Action to take when timer expires.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def set_timer(self, duration: int, action: str | None = None) -> bool:
    """Set timer for device.

    This may not be implemented for all devices. Please open an issue
    if there is an error.

    Args:
        duration (int): Duration in seconds.
        action (str | None): Action to take when timer expires.

    Returns:
        bool: True if successful, False otherwise.
    """
    del duration
    del action
    logger.debug('Not implemented - set_timer')
    return False

set_white_mode async ↲

set_white_mode() -> bool

Inherited From VeSyncBulb

Set white mode if supported by bulb.

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/bulb_base.py

async def set_white_mode(self) -> bool:
    """Set white mode if supported by bulb.

    Returns:
        bool: True if successful, False otherwise.
    """
    if self.supports_multicolor:
        logger.debug('White mode is not configured on this bulb.')
    else:
        logger.warning('White mode not supported by this bulb')
    return False

to_dict ↲

to_dict(state: bool = True) -> dict[str, Any]

Inherited From VeSyncBaseDevice

Return device information as a dictionary.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in dictionary, defaults to True.	True

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Dictionary containing device information.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_dict(self, state: bool = True) -> dict[str, Any]:
    """Return device information as a dictionary.

    Args:
        state (bool): If True, include state in dictionary, defaults to True.

    Returns:
        dict[str, Any]: Dictionary containing device information.
    """
    device_dict = {
        'device_name': self.device_name,
        'product_type': self.product_type,
        'model': self.device_type,
        'subdevice_no': str(self.sub_device_no),
        'type': self.type,
        'cid': self.cid,
        'features:': self.features,
        'config_module': self.config_module,
        'connection_type': self.connection_type,
        'last_response': self.last_response,
    }
    state_dict = self.state.to_dict() if state else {}
    return device_dict | state_dict

to_json ↲

to_json(state: bool = True, indent: bool = True) -> str

Inherited From VeSyncBaseDevice

Print JSON API string for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
str	str	JSON formatted string of device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_json(self, state: bool = True, indent: bool = True) -> str:
    """Print JSON API string for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        str: JSON formatted string of device details.
    """
    return self.to_jsonb(state, indent).decode()

to_jsonb ↲

to_jsonb(state: bool = True, indent: bool = True) -> bytes

Inherited From VeSyncBaseDevice

JSON API bytes for device details.

Parameters:

Name	Type	Description	Default
state	bool	If True, include state in JSON output, defaults to True.	True
indent	bool	If True, indent JSON output, defaults to True.	True

Returns:

Name	Type	Description
bytes	bytes	JSON formatted bytes of device details.

Example

This is an example without state.

{
    "Device Name": "Living Room Lamp",
    "Model": "ESL100",
    "Subdevice No": "0",
    "Type": "wifi",
    "CID": "1234567890abcdef"
}

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

def to_jsonb(self, state: bool = True, indent: bool = True) -> bytes:
    """JSON API bytes for device details.

    Args:
        state (bool): If True, include state in JSON output, defaults to True.
        indent (bool): If True, indent JSON output, defaults to True.

    Returns:
        bytes: JSON formatted bytes of device details.

    Example:
        This is an example without state.
        ```
        {
            "Device Name": "Living Room Lamp",
            "Model": "ESL100",
            "Subdevice No": "0",
            "Type": "wifi",
            "CID": "1234567890abcdef"
        }
        ```
    """
    return_dict = self.to_dict(state=state)
    if indent:
        return orjson.dumps(
            return_dict,
            option=orjson.OPT_INDENT_2 | orjson.OPT_NON_STR_KEYS,
        )

    return orjson.dumps(return_dict, option=orjson.OPT_NON_STR_KEYS)

toggle_switch abstractmethod async ↲

toggle_switch(toggle: bool | None = None) -> bool

Inherited From VeSyncBaseToggleDevice

Toggle device power on or off.

Parameters:

Name	Type	Description	Default
toggle	bool | None	True to turn on, False to turn off, None to toggle.	None

Returns:

Name	Type	Description
bool	bool	True if successful, False otherwise.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

@abstractmethod
async def toggle_switch(self, toggle: bool | None = None) -> bool:
    """Toggle device power on or off.

    Args:
        toggle (bool | None): True to turn on, False to turn off, None to toggle.

    Returns:
        bool: True if successful, False otherwise.
    """

turn_off async ↲

turn_off() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device off.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_off(self) -> bool:
    """Turn device off."""
    return await self.toggle_switch(False)

turn_on async ↲

turn_on() -> bool

Inherited From VeSyncBaseToggleDevice

Turn device on.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def turn_on(self) -> bool:
    """Turn device on."""
    return await self.toggle_switch(True)

update async ↲

update() -> None

Inherited From VeSyncBaseDevice

Update device details.

Source code in src/pyvesync/base_devices/vesyncbasedevice.py

async def update(self) -> None:
    """Update device details."""
    await self.get_details()