aioswitcher Documentation

aioswitcher 2.0.4 documentation

Install

pip install aioswitcher

Usage

Bridge

We can use the Bridge implementation to discover devices and their state.

The following code will print all discovered devices for 60 seconds.

async def print_devices(delay):
    def on_device_found_callback(device):
        print(asdict(device))

    async with SwitcherBridge(on_device_found_callback):
        await asyncio.sleep(delay)

asyncio.get_event_loop().run_until_complete(print_devices(60))

Note

A Switcher device will broadcast every 4 seconds.
Discovered devices can either be a Power Plug or a Water Heater.

API

We can use the API to gain the following capabilities:

  • Get the current state

  • Turn on and off

  • Set the name

  • Configure auto shutdown

  • Retrieve the schedules

  • Create and Delete schedules

async def control_device(device_ip, device_id) :
    # for connecting to a device we need its id and ip address
    async with SwitcherApi(device_ip, device_id) as api:
        # get the device current state
        await api.get_state()
        # turn the device on for 15
        await api.control_device(Command.ON, 15)
        # turn the device off
        await api.control_device(Command.OFF)
        # set the device name
        await api.set_device_name("my new name")
        # configure the device for 02:30 auto shutdown
        await api.set_auto_shutdown(timedelta(hours=2, minutes=30))
        # get the schedules from the device
        await api.get_schedules()
        # delete and existing schedule with id 1
        await api.delete_schedule("1")
        # create a new recurring schedule for 13:00-14:30 executing on sunday and friday
        await api.create_schedule("13:00", "14:30", {Days.SUNDAY, Days.FRIDAY})

asyncio.get_event_loop().run_until_complete(control_device("111.222.11.22", "ab1c2d"))

Note

All requests return a response, you can use the asdict utility function to get familiarize with the various responses.

You can visit the API response messages section and review the various response objects. Note that if a request doesn’t have a specific response extending the base response, then the base response is the yielding response.

Supported Devices

You can find the supported device types stated as this enum members.

Command Line Scripts

Discover Devices

discover_devices.py

Discover and print info of Switcher devices

usage: discover_devices.py [-h] [delay]

delay

number of seconds to run, defaults to 60

-h, --help

show this help message and exit

Control Device

control_device.py

Control your Switcher device

usage: control_device.py [-h] [-v] -d DEVICE_ID -i IP_ADDRESS {get_state,turn_on,turn_off,set_name,set_auto_shutdown,get_schedules,delete_schedule,create_schedule} …

-h, --help

show this help message and exit

-v, --verbose

include the raw message

-d <device_id>, --device-id <device_id>

the identification of the device

-i <ip_address>, --ip-address <ip_address>

the ip address assigned to the device

example usage:

python control_device.py -d ab1c2d -i “111.222.11.22” get_state

python control_device.py -d ab1c2d -i “111.222.11.22” turn_on

python control_device.py -d ab1c2d -i “111.222.11.22” turn_on -t 15

python control_device.py -d ab1c2d -i “111.222.11.22” turn_off

python control_device.py -d ab1c2d -i “111.222.11.22” set_name -n “My Boiler”

python control_device.py -d ab1c2d -i “111.222.11.22” set_auto_shutdown -r 2 -m 30

python control_device.py -d ab1c2d -i “111.222.11.22” get_schedules

python control_device.py -d ab1c2d -i “111.222.11.22” delete_schedule -s 3

python control_device.py -d ab1c2d -i “111.222.11.22” create_schedule -n “14:00” -f “14:30”

python control_device.py -d ab1c2d -i “111.222.11.22” create_schedule -n “17:30” -f “18:30” -w Sunday Monday Friday

control_device.py create_schedule

usage: control_device.py create_schedule [-h] -n START_TIME -f END_TIME [-w [{Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday} …]]

-h, --help

show this help message and exit

-n <start_time>, --start-time <start_time>

the on time for the schedule, e.g. 13:00

-f <end_time>, --end-time <end_time>

the off time for the schedule, e.g. 13:30

-w {Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday}, --weekdays {Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday}

days for recurring schedules, possible values: [‘Monday’, ‘Tuesday’, ‘Wednesday’, ‘Thursday’, ‘Friday’, ‘Saturday’, ‘Sunday’]

control_device.py delete_schedule

usage: control_device.py delete_schedule [-h] -s SCHEDULE_ID

-h, --help

show this help message and exit

-s <schedule_id>, --schedule-id <schedule_id>

the id of the schedule for deletion

control_device.py get_schedules

usage: control_device.py get_schedules [-h]

-h, --help

show this help message and exit

control_device.py get_state

usage: control_device.py get_state [-h]

-h, --help

show this help message and exit

control_device.py set_auto_shutdown

usage: control_device.py set_auto_shutdown [-h] -r HOURS [-m [MINUTES]]

-h, --help

show this help message and exit

-r <hours>, --hours <hours>

number hours for the auto shutdown

-m <minutes>, --minutes <minutes>

number hours for the auto shutdown

control_device.py set_name

usage: control_device.py set_name [-h] -n NAME

-h, --help

show this help message and exit

-n <name>, --name <name>

new name for the device

control_device.py turn_off

usage: control_device.py turn_off [-h]

-h, --help

show this help message and exit

control_device.py turn_on

usage: control_device.py turn_on [-h] [-t [TIMER]]

-h, --help

show this help message and exit

-t <timer>, --timer <timer>

set minutes timer for turn on operation

Code Documentation

aioswitcher.api

class aioswitcher.api.Command(value)

Enum for turning the device on or off.

OFF = '0'
ON = '1'
final class aioswitcher.api.SwitcherApi(ip_address, device_id, port=9957)

Switcher TCP based API.

Parameters
  • ip_address (str) – the ip address assigned to the device.

  • device_id (str) – the id of the desired device.

  • port (int) – the port of the device, default is 9957.

Return type

None

async connect()

Connect to asynchronous socket and get reader and writer object.

Return type

None

property connected: bool

Return true if api is connected.

async control_device(command, minutes=0)

Use for sending the control packet to the device.

Parameters
  • command (aioswitcher.api.Command) – use the aioswitcher.api.Command enum.

  • minutes (int) – if turning-on optionally incorporate a timer.

Returns

An instance of SwitcherBaseResponse.

Return type

aioswitcher.api.messages.SwitcherBaseResponse

async create_schedule(start_time, end_time, days={})

Use for creating a new schedule in the next empty schedule slot.

Parameters
  • start_time (str) – a string start time in %H:%M format. e.g. 13:00.

  • end_time (str) – a string start time in %H:%M format. e.g. 13:00.

  • days (Set[aioswitcher.schedule.Days]) – for recurring schedules, add Days.

Returns

An instance of SwitcherBaseResponse.

Return type

aioswitcher.api.messages.SwitcherBaseResponse

async delete_schedule(schedule_id)

Use for deleting a schedule from the device.

Use get_schedules to retrieve the schedule instance.

Parameters

schedule_id (str) – the identification of the schedule for deletion.

Returns

An instance of SwitcherBaseResponse.

Return type

aioswitcher.api.messages.SwitcherBaseResponse

async disconnect()

Disconnect from asynchronous socket.

Return type

None

async get_schedules()

Use for retrieval of the schedules from the device.

Returns

An instance of SwitcherGetSchedulesResponse.

Return type

aioswitcher.api.messages.SwitcherGetSchedulesResponse

async get_state()

Use for sending the get state packet to the device.

Returns

An instance of SwitcherStateResponse.

Return type

aioswitcher.api.messages.SwitcherStateResponse

async set_auto_shutdown(full_time)

Use for sending the set auto-off packet to the device.

Parameters
  • full_time (datetime.timedelta) – timedelta value containing the configuration value for

  • auto-shutdown.

Returns

An instance of SwitcherBaseResponse.

Return type

aioswitcher.api.messages.SwitcherBaseResponse

async set_device_name(name)

Use for sending the set name packet to the device.

Parameters

name (str) – string name with the length of 2 >= x >= 32.

Returns

An instance of SwitcherBaseResponse.

Return type

aioswitcher.api.messages.SwitcherBaseResponse

aioswitcher.api.messages

class aioswitcher.api.messages.SwitcherBaseResponse(unparsed_response)

Representation of the switcher base response message.

Applicable for all messages that do no require post initialization. e.g. not applicable for SwitcherLoginResponse, SwitcherStateResponse, SwitcherGetScheduleResponse.

Parameters

unparsed_response (bytes) – the raw response from the device.

Return type

None

property successful: bool

Return true if the response is not empty.

Partially indicating the request was successful.

unparsed_response: bytes
final class aioswitcher.api.messages.SwitcherLoginResponse(unparsed_response)

Bases: aioswitcher.api.messages.SwitcherBaseResponse

Representations of the switcher login response message.

Parameters

unparsed_response (bytes) –

Return type

None

session_id: str
property successful: bool

Return true if the response is not empty.

Partially indicating the request was successful.

unparsed_response: bytes
final class aioswitcher.api.messages.SwitcherStateResponse(unparsed_response)

Bases: aioswitcher.api.messages.SwitcherBaseResponse

Representation of the switcher state response message.

Parameters

unparsed_response (bytes) –

Return type

None

auto_shutdown: str
electric_current: float
power_consumption: int
state: aioswitcher.device.DeviceState
property successful: bool

Return true if the response is not empty.

Partially indicating the request was successful.

time_left: str
time_on: str
unparsed_response: bytes
final class aioswitcher.api.messages.SwitcherGetSchedulesResponse(unparsed_response)

Bases: aioswitcher.api.messages.SwitcherBaseResponse

Representation of the switcher get schedule message.

Parameters

unparsed_response (bytes) –

Return type

None

property found_schedules: bool

Return true if found schedules in the response.

schedules: Set[aioswitcher.schedule.parser.SwitcherSchedule]
property successful: bool

Return true if the response is not empty.

Partially indicating the request was successful.

unparsed_response: bytes

aioswitcher.bridge

final class aioswitcher.bridge.SwitcherBridge(on_device, broadcast_port=20002)

Use for running a UDP client for bridging Switcher devices broadcast messages.

Parameters
  • on_device (Callable[[aioswitcher.device.SwitcherBase], Any]) – a callable to which every new SwitcherBase device found will be send.

  • broadcast_port (int) – broadcast port, default is 20002.

Return type

None

property is_running: bool

Return true if bridge is running.

Type

bool

async start()

Create an asynchronous listener and start the bridge.

Return type

None

async stop()

Stop the asynchronous bridge.

Return type

None

aioswitcher.device

class aioswitcher.device.DeviceCategory(value)

Enum for relaying the device category.

POWER_PLUG = 2
WATER_HEATER = 1
class aioswitcher.device.DeviceType(value)

Enum for relaying the type of the switcher devices.

MINI = 'Switcher Mini'
POWER_PLUG = 'Switcher Power Plug'
TOUCH = 'Switcher Touch'
V2_ESP = 'Switcher V2 (esp)'
V2_QCA = 'Switcher V2 (qualcomm)'
V4 = 'Switcher V4'
property category: aioswitcher.device.DeviceCategory

Return the category of the device type.

property hex_rep: str

Return the hexadecimal representation of the device type.

class aioswitcher.device.DeviceState(value)

Enum class representing the device’s state.

OFF = '0000'
ON = '0100'
property display: str

Return the display name of the state.

final class aioswitcher.device.SwitcherPowerPlug(device_type, device_state, device_id, ip_address, mac_address, name, power_consumption, electric_current)

Bases: aioswitcher.device.SwitcherPowerBase, aioswitcher.device.SwitcherBase

Implementation of the Switcher Power Plug device.

Please Note the order of the inherited classes to understand the order of the instantiation parameters and the super call.

Parameters
Return type

None

device_id: str
device_state: aioswitcher.device.DeviceState
device_type: aioswitcher.device.DeviceType
electric_current: float
ip_address: str
last_data_update: datetime.datetime
mac_address: str
name: str
power_consumption: int
final class aioswitcher.device.SwitcherWaterHeater(device_type, device_state, device_id, ip_address, mac_address, name, power_consumption, electric_current, remaining_time, auto_shutdown)

Bases: aioswitcher.device.SwitcherTimedBase, aioswitcher.device.SwitcherPowerBase, aioswitcher.device.SwitcherBase

Implementation of the Switcher Water Heater device.

Please Note the order of the inherited classes to understand the order of the instantiation parameters and the super call.

Parameters
Return type

None

property auto_off_set: str

Fix for backward compability issues with home assistant.

auto_shutdown: str
device_id: str
device_state: aioswitcher.device.DeviceState
device_type: aioswitcher.device.DeviceType
electric_current: float
ip_address: str
last_data_update: datetime.datetime
mac_address: str
name: str
power_consumption: int
remaining_time: str

aioswitcher.schedule

class aioswitcher.schedule.Days(value)

Enum class representing the day entity.

FRIDAY = 'Friday'
MONDAY = 'Monday'
SATURDAY = 'Saturday'
SUNDAY = 'Sunday'
THURSDAY = 'Thursday'
TUESDAY = 'Tuesday'
WEDNESDAY = 'Wednesday'
property bit_rep: int

Return the bit representation of the day.

property hex_rep: int

Return the hexadecimal representation of the day.

property weekday: int

Return the weekday of the day.

final class aioswitcher.schedule.parser.SwitcherSchedule(schedule_id, recurring, days, start_time, end_time)

representation of the Switcher schedule slot.

Parameters
  • schedule_id (str) – the id of the schedule

  • recurring (bool) – is a recurring schedule

  • days (Set[aioswitcher.schedule.Days]) – a set of schedule days, or empty set for non recurring schedules

  • start_time (str) – the start time of the schedule

  • end_time (str) – the end time of the schedule

Return type

None

days: Set[aioswitcher.schedule.Days]
display: str
duration: str
end_time: str
recurring: bool
schedule_id: str
start_time: str