API reference

invisoutlet

Python client library for InvisOutlet smart outlets.

Classes

ColorEffect

Bases: IntEnum

Animated effect modes for a color array (callback 17, arg 2).

Modes 1 (static HSV) and 2 (static temperature) are set via the set_color_* helpers; these are the self-animating modes.

Attributes

BREATHING class-attribute instance-attribute

BREATHING = 3

STROBING class-attribute instance-attribute

STROBING = 4

COLOR_CYCLE class-attribute instance-attribute

COLOR_CYCLE = 5

RAINBOW class-attribute instance-attribute

RAINBOW = 6

STARRY_NIGHT class-attribute instance-attribute

STARRY_NIGHT = 7

InvisOutletClient

Client for InvisOutlet smart outlet devices over WebSocket.

Attributes

host instance-attribute

host = host

port instance-attribute

port = port

Functions

connect async

connect() -> None

Connect to the device and keep the connection alive.

Raises on the initial connection failure. Once connected, a background task reads messages and automatically reconnects with backoff if the connection drops, until :meth:close is called. Registered listeners survive reconnects, so pushes resume automatically.

close async

close() -> None

Close the connection and stop reconnecting.

on_connect

on_connect(callback: Callable[[], None]) -> Callable[[], None]

Register a callback invoked after each successful (re)connect.

Returns a function to unregister the callback.

on_disconnect

on_disconnect(callback: Callable[[], None]) -> Callable[[], None]

Register a callback invoked when the connection is lost.

Not fired on an intentional :meth:close. Returns a function to unregister the callback.

on_sensor_data

on_sensor_data(callback: Callable[[SensorData], None]) -> Callable[[], None]

Register a callback for sensor data updates.

Returns a function to unregister the callback.

on_outlet_status

on_outlet_status(callback: Callable[[OutletStatus], None]) -> Callable[[], None]

Register a callback for pushed outlet-status updates.

The device broadcasts callback 9 when outlet state changes (e.g. from another controller or the physical button). The push envelope may carry the status list directly or wrapped, so both shapes are accepted.

Returns a function to unregister the callback.

on_message

on_message(callback_name: int, callback: Callable[[dict[str, Any]], None]) -> Callable[[], None]

Register a callback for a specific message type.

Returns a function to unregister the callback.

set_outlet async

set_outlet(outlet: int, on: bool, timeout: float = 5.0) -> None

Set the state of an outlet.

Parameters:

Name	Type	Description	Default
outlet	int	Outlet number (1 or 2).	required
on	bool	True to turn on, False to turn off.	required

get_config async

get_config(timeout: float = 5.0) -> DeviceConfig

Request device configuration.

get_sensor_data async

get_sensor_data(timeout: float = 5.0) -> SensorData

Fetch the faceplate's latest sensor readings on demand (callback 11).

Returns the same payload the device streams; fields a faceplate lacks are omitted and come back as None.

set_config async

set_config(*, outlet_power_indicator_on: bool | None = None, pm_indicator_brightness: int | None = None, capacitive_ctrl: bool | None = None, aqi_color_rgb_feature: bool | None = None, motion_away_feature: bool | None = None, adaptive_nightlight_feature: bool | None = None, adaptive_min_brightness: int | None = None, adaptive_max_brightness: int | None = None, occupancy_nightlight_feature: bool | None = None, override_adaptive_occupancy_nightlight_feature: bool | None = None, magic_touch_ctrl: bool | None = None, home_away_enabled: bool | None = None, home_away_outlet1_enabled: bool | None = None, home_away_outlet2_enabled: bool | None = None, home_away_nightlight_enabled: bool | None = None, home_away_min_brightness: int | None = None, home_away_max_brightness: int | None = None, home_away_min_on_duration: int | None = None, home_away_max_on_duration: int | None = None, home_away_min_off_duration: int | None = None, home_away_max_off_duration: int | None = None, mqtt_enabled: bool | None = None, mqtt_broker_url: str | None = None, mqtt_user: str | None = None, mqtt_password: str | None = None, mqtt_qos: int | None = None, timeout: float = 5.0) -> None

Set device configuration.

Only the fields you pass are sent; everything left as None is omitted from the wire payload.

get_device_info async

get_device_info(timeout: float = 5.0) -> DeviceInfo

Request device information.

get_accessory_names async

get_accessory_names(timeout: float = 5.0) -> list[AccessoryName]

Request the user-assigned accessory names.

set_accessory_names async

set_accessory_names(names: list[AccessoryName], timeout: float = 5.0) -> None

Set the user-assigned accessory names.

restart async

restart() -> None

Restart the InvisOutlet. The device sends no response.

reset_network async

reset_network() -> None

Reset the InvisOutlet's network settings. Sends no response.

The device will drop off the network after this call.

factory_reset async

factory_reset() -> None

Factory-reset the InvisOutlet. Sends no response.

This erases all configuration; the device returns to setup mode.

get_outlet_status async

get_outlet_status(timeout: float = 5.0) -> OutletStatus

Fetch the on/off state of each outlet.

set_nightlight async

set_nightlight(mode: int, brightness: int, timeout: float = 5.0) -> None

Control the nightlight.

Parameters:

Name	Type	Description	Default
mode	int	Nightlight mode (0 = off, >0 = on).	required
brightness	int	Brightness 0-100.	required

get_nightlight async

get_nightlight(timeout: float = 5.0) -> NightlightState

Fetch the current nightlight state.

set_color_hsv async

set_color_hsv(light: int, hue: int, saturation: int, brightness: int = 100, on: bool = True, count: int = 1, timeout: float = 5.0) -> None

Set a color array (light selector) to an HSV color.

A single entry broadcasts across the array, but the firmware animates the fill; pass count = the number of LEDs to set them all at once instead.

set_color_temperature async

set_color_temperature(light: int, kelvin: int, brightness: int = 100, on: bool = True, count: int = 1, timeout: float = 5.0) -> None

Set a color array (light selector) to a white temperature.

Unlike the HSV path, the firmware does not broadcast a single temperature entry across the array, so pass count = the number of LEDs to light them all (one identical entry per LED).

set_color_temperatures async

set_color_temperatures(light: int, temperatures: list[int], brightness: list[int] | None = None, states: list[bool] | None = None, timeout: float = 5.0) -> None

Set a color array to a per-LED white temperature.

temperatures is one kelvin per LED; brightness (0-100) and states are optional matching lists (default full + on).

set_color_pixels async

set_color_pixels(light: int, colors: list[tuple[int, int]], brightness: list[int] | None = None, mode: int = 1, timeout: float = 5.0) -> None

Set per-LED colors (and optionally the mode) by round-tripping the frame.

colors is a list of (hue, saturation) applied to LEDs 0..N-1 in order; LEDs beyond the list — and the device's undocumented trailing fields — are left untouched. brightness, if given, is a matching list of 0-100 levels applied to the same LEDs. mode selects static color (1) or an effect (:class:ColorEffect) that animates the palette.

set_color_effect_pixels async

set_color_effect_pixels(light: int, colors: list[tuple[int, int]], effect: ColorEffect | int, speed: int, randomize: bool, level: int, brightness: list[int] | None = None, timeout: float = 5.0) -> None

Run an animated effect over a per-LED palette.

Sends [light, mode, [[state, brightness, [hue, sat]], ...], speed, randomize, level] — the per-LED color array followed by speed, the randomize flag, and a brightness level (used by the device only when randomizing).

get_color async

get_color(light: int, timeout: float = 5.0) -> ColorLightState

Fetch a color array's state (light selector).

Raises InvisOutletCommandError if the device returns no data for that selector (e.g. no Aura attached).

get_available_updates async

get_available_updates(timeout: float = 5.0) -> AvailableUpdates

Request available firmware updates.

check_firmware async

check_firmware(target: OtaTarget, model: str, hw_rev: str, current_fw_rev: str, variant: str | None = None, timeout: float = 10.0) -> FirmwareRelease | None

Look up the latest firmware for a module from the update service.

variant (a faceplate's type, e.g. "Aura") takes precedence over model for the product code, since faceplates share a model name. Returns None for a model with no known product code (i.e. no known update channel). Unlike :meth:get_available_updates, this also yields the download URL and release notes.

perform_ota_update async

perform_ota_update(target: OtaTarget, method: int = 0) -> None

Start an OTA update.

Parameters:

Name	Type	Description	Default
target	OtaTarget	Which device to update (see :class:OtaTarget).	required
method	int	For the InvisDeco, 0 = over its own Wi-Fi, 1 = via the InvisOutlet. Ignored for the InvisOutlet.	0

Fire-and-forget: the device may not acknowledge before it gets busy starting the download, so this does not wait for a reply. Progress and result arrive asynchronously via on_ota_progress and on_ota_result.

restart_invisdeco async

restart_invisdeco(timeout: float = 5.0) -> None

Restart the attached InvisDeco sub-device.

reset_invisdeco async

reset_invisdeco(timeout: float = 5.0) -> None

Reset the attached InvisDeco sub-device.

calibrate_occupancy async

calibrate_occupancy(duration_seconds: int, timeout: float = 5.0) -> None

Run occupancy-sensor calibration for the given duration.

calibrate_temp_humidity async

calibrate_temp_humidity(temperature_celsius: float, humidity_percent: float, timeout: float = 5.0) -> None

Calibrate temperature and relative humidity to reference values.

The device expects millidegrees and millipercent; this converts for you.

on_ota_progress

on_ota_progress(callback: Callable[[OtaProgress], None]) -> Callable[[], None]

Register a callback for server-pushed OTA progress updates.

Returns a function to unregister the callback.

on_ota_result

on_ota_result(callback: Callable[[OtaResult], None]) -> Callable[[], None]

Register a callback for OTA result updates. Returns an unsubscribe.

Results are gated to paper over a firmware quirk: the device emits a junk status=0 result at the start of every update, before any download. Such a pre-progress status=0 is suppressed; a stall (no progress within :data:_OTA_STALL_TIMEOUT) is instead reported as a synthesized status=0 result. Callbacks therefore fire exactly once per update: a real status=1 success, a real failure after progress began, or the synthesized stall failure.

OtaTarget

Bases: IntEnum

Which device an OTA firmware update targets (callback 21).

Values match the device's 1-based numbering, shared with the device_type in the progress/result pushes (callbacks 22/23).

Attributes

INVISOUTLET class-attribute instance-attribute

INVISOUTLET = 1

INVISDECO class-attribute instance-attribute

INVISDECO = 2

DiscoveredDevice dataclass

An InvisOutlet device found via mDNS.

Attributes

name instance-attribute

name: str

host instance-attribute

host: str

port instance-attribute

port: int

serial_number instance-attribute

serial_number: str

device_type instance-attribute

device_type: str

sub_type class-attribute instance-attribute

sub_type: str | None = None

sub_device class-attribute instance-attribute

sub_device: str | None = None

sub_sn class-attribute instance-attribute

sub_sn: str | None = None

InvisOutletCommandError

Bases: InvisOutletError

Raised when the device reports a command failure (PUBACK == 0).

InvisOutletConnectionError

Bases: InvisOutletError

Raised when unable to connect to the device.

InvisOutletError

Bases: Exception

Base exception for InvisOutlet client.

InvisOutletTimeoutError

Bases: InvisOutletError

Raised when a request times out.

AccessoryName dataclass

A user-assigned label for an accessory (outlet or nightlight).

Attributes

accessory instance-attribute

accessory: int

name instance-attribute

name: str

AvailableUpdates dataclass

Available firmware updates for the outlet (IM) and sub-device (PM).

Attributes

im instance-attribute

im: FirmwareUpdate

pm class-attribute instance-attribute

pm: FirmwareUpdate | None = None

update_available property

update_available: bool

Whether any module has an update available.

ColorLedEntry dataclass

A single LED entry within a color light.

For static-temperature control only temperature is used; full color state additionally carries hue/saturation.

Attributes

state instance-attribute

state: bool

brightness instance-attribute

brightness: int

temperature class-attribute instance-attribute

temperature: int | None = None

hue class-attribute instance-attribute

hue: int | None = None

saturation class-attribute instance-attribute

saturation: int | None = None

ColorLightState dataclass

State of an addressable color light (e.g. InvisDeco Aura).

Attributes

light instance-attribute

light: int

mode instance-attribute

mode: int

leds instance-attribute

leds: list[ColorLedEntry]

extra class-attribute instance-attribute

extra: list[Any] = field(default_factory=list)

DeviceConfig dataclass

Bases: WireModel

Device configuration.

Attributes

outlet_power_indicator_on class-attribute instance-attribute

outlet_power_indicator_on: bool | None = wire('acc_prefs', 'outletPwrIndicatorOn', bool_int=True)

pm_indicator_brightness class-attribute instance-attribute

pm_indicator_brightness: int | None = wire('acc_prefs', 'pmIndicatorBrightness')

capacitive_ctrl class-attribute instance-attribute

capacitive_ctrl: bool | None = wire('acc_prefs', 'capacitiveCtrl', bool_int=True)

aqi_color_rgb_feature class-attribute instance-attribute

aqi_color_rgb_feature: bool | None = wire('acc_prefs', 'aqiColorRGBFeature', bool_int=True)

motion_away_feature class-attribute instance-attribute

motion_away_feature: bool | None = wire('acc_prefs', 'motionAwayFeature', bool_int=True)

adaptive_nightlight_feature class-attribute instance-attribute

adaptive_nightlight_feature: bool | None = wire('acc_prefs', 'adaptiveNightlightFeature', bool_int=True)

adaptive_min_brightness class-attribute instance-attribute

adaptive_min_brightness: int | None = wire('acc_prefs', 'adaptiveMinBrightness')

adaptive_max_brightness class-attribute instance-attribute

adaptive_max_brightness: int | None = wire('acc_prefs', 'adaptiveMaxBrightness')

occupancy_nightlight_feature class-attribute instance-attribute

occupancy_nightlight_feature: bool | None = wire('acc_prefs', 'occupancyNightlightFeature', bool_int=True)

override_adaptive_occupancy_nightlight_feature class-attribute instance-attribute

override_adaptive_occupancy_nightlight_feature: bool | None = wire('acc_prefs', 'overrideAdaptiveOccupancyNightlightFeature', bool_int=True)

magic_touch_ctrl class-attribute instance-attribute

magic_touch_ctrl: bool | None = wire('acc_prefs', 'magicTouchCtrl', bool_int=True)

home_away_enabled class-attribute instance-attribute

home_away_enabled: bool | None = wire('acc_prefs', 'homeAwayMode', 'enabled', bool_int=True)

home_away_outlet1_enabled class-attribute instance-attribute

home_away_outlet1_enabled: bool | None = wire('acc_prefs', 'homeAwayMode', 'outlet1Enabled', bool_int=True)

home_away_outlet2_enabled class-attribute instance-attribute

home_away_outlet2_enabled: bool | None = wire('acc_prefs', 'homeAwayMode', 'outlet2Enabled', bool_int=True)

home_away_nightlight_enabled class-attribute instance-attribute

home_away_nightlight_enabled: bool | None = wire('acc_prefs', 'homeAwayMode', 'nightlightEnabled', bool_int=True)

home_away_min_brightness class-attribute instance-attribute

home_away_min_brightness: int | None = wire('acc_prefs', 'homeAwayMode', 'minBrightness')

home_away_max_brightness class-attribute instance-attribute

home_away_max_brightness: int | None = wire('acc_prefs', 'homeAwayMode', 'maxBrightness')

home_away_min_on_duration class-attribute instance-attribute

home_away_min_on_duration: int | None = wire('acc_prefs', 'homeAwayMode', 'minOnDuration')

home_away_max_on_duration class-attribute instance-attribute

home_away_max_on_duration: int | None = wire('acc_prefs', 'homeAwayMode', 'maxOnDuration')

home_away_min_off_duration class-attribute instance-attribute

home_away_min_off_duration: int | None = wire('acc_prefs', 'homeAwayMode', 'minOffDuration')

home_away_max_off_duration class-attribute instance-attribute

home_away_max_off_duration: int | None = wire('acc_prefs', 'homeAwayMode', 'maxOffDuration')

mqtt_enabled class-attribute instance-attribute

mqtt_enabled: bool | None = wire('sys_prefs', 'mqtt', 'enabled', bool_int=True)

mqtt_broker_url class-attribute instance-attribute

mqtt_broker_url: str | None = wire('sys_prefs', 'mqtt', 'mqtt_broker_url')

mqtt_user class-attribute instance-attribute

mqtt_user: str | None = wire('sys_prefs', 'mqtt', 'user')

mqtt_password class-attribute instance-attribute

mqtt_password: str | None = wire('sys_prefs', 'mqtt', 'pass')

mqtt_qos class-attribute instance-attribute

mqtt_qos: int | None = wire('sys_prefs', 'mqtt', 'qos')

internet_ip class-attribute instance-attribute

internet_ip: str | None = wire('sys_prefs', 'internet', 'ip')

internet_main_dns class-attribute instance-attribute

internet_main_dns: str | None = wire('sys_prefs', 'internet', 'mainDNS')

internet_backup_dns class-attribute instance-attribute

internet_backup_dns: str | None = wire('sys_prefs', 'internet', 'backupDNS')

DeviceInfo dataclass

Device information for an InvisOutlet outlet.

Attributes

serial_number instance-attribute

serial_number: str

mac instance-attribute

mac: str

device instance-attribute

device: str

hw_rev class-attribute instance-attribute

hw_rev: str | None = None

fw_rev class-attribute instance-attribute

fw_rev: str | None = None

host class-attribute instance-attribute

host: str = ''

port class-attribute instance-attribute

port: int = 3333

sub_device class-attribute instance-attribute

sub_device: SubDeviceInfo | None = None

FirmwareRelease dataclass

A firmware release from the InvisOutlet update service.

Returned by the OTA-check endpoint for a single module: the latest available revision, its download URL and the release notes (message).

Attributes

current_fw_rev instance-attribute

current_fw_rev: str

available_fw_rev instance-attribute

available_fw_rev: str

ota_bin_url instance-attribute

ota_bin_url: str

message instance-attribute

message: str

update_available property

update_available: bool

Whether the available revision differs from the installed one.

FirmwareUpdate dataclass

Installed and available firmware revisions for a single module.

Attributes

fw_rev class-attribute instance-attribute

fw_rev: str | None = None

available_fw_rev class-attribute instance-attribute

available_fw_rev: str | None = None

www_fw_rev class-attribute instance-attribute

www_fw_rev: str | None = None

available_www_fw_rev class-attribute instance-attribute

available_www_fw_rev: str | None = None

update_available property

update_available: bool

Whether a newer firmware revision is available.

NightlightState dataclass

Nightlight mode and brightness.

Attributes

mode instance-attribute

mode: int

brightness instance-attribute

brightness: int

on property

on: bool

Whether the nightlight is active.

OtaProgress dataclass

A server-pushed OTA download progress update (callback 22).

Attributes

device_type instance-attribute

device_type: int

progress instance-attribute

progress: int

OtaResult dataclass

A server-pushed OTA result update (callback 23).

Attributes

device_type instance-attribute

device_type: int

status instance-attribute

status: int

success property

success: bool

Whether the OTA update succeeded (status 1 = success, 0 = fail).

OutletStatus dataclass

On/off state of each outlet, indexed from outlet 1.

Attributes

outlets instance-attribute

outlets: list[bool]

Functions

is_on

is_on(outlet: int) -> bool

Return whether the given 1-based outlet is on.

SensorData dataclass

Sensor readings from an InvisOutlet outlet.

Attributes

temperature class-attribute instance-attribute

temperature: float | None = None

humidity class-attribute instance-attribute

humidity: float | None = None

air_quality_index class-attribute instance-attribute

air_quality_index: int | None = None

co2 class-attribute instance-attribute

co2: int | None = None

voc class-attribute instance-attribute

voc: float | None = None

pressure class-attribute instance-attribute

pressure: float | None = None

illuminance class-attribute instance-attribute

illuminance: float | None = None

distance class-attribute instance-attribute

distance: int | None = None

occupancy_state class-attribute instance-attribute

occupancy_state: int | None = None

movement_energy class-attribute instance-attribute

movement_energy: int | None = None

stationary_energy class-attribute instance-attribute

stationary_energy: int | None = None

gas class-attribute instance-attribute

gas: int | None = None

aqi_accuracy class-attribute instance-attribute

aqi_accuracy: int | None = None

temp_humidity_accuracy class-attribute instance-attribute

temp_humidity_accuracy: int | None = None

co2_peak class-attribute instance-attribute

co2_peak: int | None = None

co2_accuracy class-attribute instance-attribute

co2_accuracy: int | None = None

voc_accuracy class-attribute instance-attribute

voc_accuracy: int | None = None

temp_valid class-attribute instance-attribute

temp_valid: bool | None = None

aqi_valid class-attribute instance-attribute

aqi_valid: bool | None = None

lux_valid class-attribute instance-attribute

lux_valid: bool | None = None

occupancy_valid class-attribute instance-attribute

occupancy_valid: bool | None = None

occupancy property

occupancy: bool | None

Whether occupancy is detected.

motion property

motion: bool | None

Whether motion is detected.

SubDeviceInfo dataclass

Information about an attached sub-device (e.g. InvisDeco).

Attributes

serial_number instance-attribute

serial_number: str

mac instance-attribute

mac: str

device instance-attribute

device: str

device_type class-attribute instance-attribute

device_type: str | None = None

hw_rev class-attribute instance-attribute

hw_rev: str | None = None

fw_rev class-attribute instance-attribute

fw_rev: str | None = None

online class-attribute instance-attribute

online: bool = False

radar_fw_ver class-attribute instance-attribute

radar_fw_ver: str | None = None

radar_hw_type class-attribute instance-attribute

radar_hw_type: str | None = None

radar_mac class-attribute instance-attribute

radar_mac: str | None = None

Functions

target_for_device_type

target_for_device_type(device_type: int) -> OtaTarget | None

Map an OTA push device_type to the :class:OtaTarget it belongs to.

The pushes (callbacks 22/23) are 1-based: 1 = InvisOutlet, 2 = InvisDeco, 3 = the outlet's WWW partition (part of the outlet's own update). Returns None for an unrecognized value.

discover async

discover(timeout: float = 5.0) -> list[DiscoveredDevice]

Scan the network for InvisOutlet devices.

Parameters:

Name	Type	Description	Default
timeout	float	How long to scan in seconds.	5.0

Returns:

Type	Description
list[DiscoveredDevice]	List of discovered devices.