Usage¶
This module provides two separate integrations with the Switcher device, both fully asynchronous.
The first integration is a UDP Bridge constantly listening to broadcast messages launched from the device approximately every 4 seconds. This integration provides constant device state updates.
The second integration is a TCP Socket API providing the ability, to not only get the current state of the device, but also control it.
TOC
UDP Bridge¶
With the UDP Bridge integration, we’re constantly listening to messages broadcast from the device containing information about the device and the device’s state.
The message is being broadcast from the device approximately every 4 seconds,
once the message is received and verified it will be put
in a asyncio.Queue with the max
size of 1, which means the Queue
always has 1
or None
messages waiting, containing the
latest state received.
Each message will be an updated instance of the SwitcherV2Device object.
The bridge can be used as a Context Manager
as well as being instantiated and controlled
manually.
Note
The UDP Bridge integration will allow you to receive Real-Time updates from the device approximately every 4 seconds, yet it will not allow you to control the device.
For controlling the device you can use the TCP Socket API integration. (Both work simultaneously).
Example of UDP Bridge usage¶
import asyncio
from datetime import datetime
from aioswitcher.bridge import SwitcherV2Bridge
from aioswitcher.devices import SwitcherV2Device
# instructions on getting this data is in,
# https://github.com/NightRang3r/Switcher-V2-Python
phone_id = "your_devices's_phone_id"
device_id = "your_devices's_device_id"
device_password = "your_devices's_device_password"
# create a new event loop
your_loop = asyncio.get_event_loop()
"""Use as instance."""
async def run_as_instance() -> None:
v2bridge = SwitcherV2Bridge(
your_loop, phone_id, device_id, device_password
)
# start the bridge
await v2bridge.start()
# get the Queue
queue = v2bridge.queue # type: asyncio.Queue
# create an event to signal your coroutine to start/stop
signal_event = asyncio.Event()
signal_event.set()
# coroutine for getting the device from the queue
async def get_device_from_queue() -> None:
device = await queue.get() # type: SwitcherV2Device
print("instance state is: {}".format(device.state))
print(datetime.now())
if signal_event.is_set():
your_loop.call_soon(get_device_from_queue)
return None
# schedule your coroutine which will wait for the device
# to be put in the queue, and print the time and its state
# afterwards it will call itself again, the result will be
# the device state being printed every approximately 4 seconds
your_loop.call_soon(get_device_from_queue)
# wait for 40 seconds
# the state should be printed about 8 to 10 times
await asyncio.sleep(40)
# stop the coroutine
signal_event.clear()
# stop the bridge
await v2bridge.stop()
return None
"""Use as context manager."""
async def run_as_context_manager() -> None:
async with SwitcherV2Bridge(
your_loop,
phone_id,
device_id,
device_password,
) as v2bridge:
# get the Queue
queue = v2bridge.queue # type: asyncio.Queue
# create an event to signal your coroutine to start/stop
signal_event = asyncio.Event()
signal_event.set()
# coroutine for getting the device from the queue
async def get_device_from_queue() -> None:
device = await queue.get() # type: SwitcherV2Device
print("context manager state is: {}".format(device.state))
print(datetime.now())
if signal_event.is_set():
your_loop.call_soon(get_device_from_queue)
return None
# schedule your coroutine which will wait for the device
# to be put in the queue, and print the time and its state
# afterwards it will call itself again, the result will be
# the device state being printed every approximately 4 seconds
your_loop.call_soon(get_device_from_queue)
# wait for 40 seconds
# the state should be printed about 8 to 10 times
await asyncio.sleep(40)
# stop the coroutine
signal_event.clear()
return None
your_loop.run_until_complete(run_as_instance())
your_loop.run_until_complete(run_as_context_manager())
loop.close()
TCP Socket API¶
With TCP Socket API integration we gain the following abilities:
|
Note
Although the TCP Socket API is applicable as a context manager
and as an instance of an
object, It is preferable to use it as a context manager
due to the nature of the
tcp connection
(you don’t want to occupy a connection slot on the device any longer then you
have to or you’ll start seeing TimeOutErrors
).
To use as an instance (which will not be covered here), you can rely on the UDP Bridge
example and just substitute start()
and stop()
with connect()
and disconnect()
.
The various responses are covered in the API Response Messages section.
Example of TCP Socket API usage¶
import asyncio
from datetime import timedelta
from aioswitcher import consts, tools
from aioswitcher.api import SwitcherV2Api, messages
from aioswitcher.schedules import SwitcherV2Schedule
# create a new event loop
your_loop = asyncio.get_event_loop()
# if you're also using the udp bridge,
# the ip address is available at (SwitcherV2Device).ip_addr
ip_address = "your_device's_ip_address"
# instructions on getting this data is in
# https://github.com/NightRang3r/Switcher-V2-Python
phone_id = "your_devices's_phone_id"
device_id = "your_devices's_device_id"
device_password = "your_devices's_device_password"
"""Use as context manager."""
async def run_as_context_manager() -> None:
async with SwitcherV2Api(
your_loop, ip_address, phone_id,
device_id, device_password) as swapi:
# get the device state
# response: messages.SwitcherV2StateResponseMSG
state_response = await swapi.get_state()
# control the device: on / off / on + (15/30/45/60) minutes timer
# response: messages.SwitcherV2ControlResponseMSG
turn_on_response = await swapi.control_device(
consts.COMMAND_ON)
turn_off_response = await swapi.control_device(
consts.COMMAND_OFF)
turn_on_30_min_response = await swapi.control_device(
consts.COMMAND_ON, '30')
# set the limit time to auto-shutdown the device (1 < hours < 24)
# response: messages.SwitcherV2SetAutoOffResponseMSG
time_to_off = timedelta(hours=1, minutes=30)
set_auto_off_response = await swapi.set_auto_shutdown(time_to_off)
# set the device name (2 < length < 33)
# response: messages.SwitcherV2UpdateNameResponseMSG
set_name_response = await swapi.set_device_name("new device name")
# get the configured schedules from the device
# response: messages.SwitcherV2GetScheduleResponseMSG
get_schedules_response = await swapi.get_schedules()
# disable or enable a schedule
# schedule_data = (SwitcherV2Schedule).schedule_data
# response: messages.SwitcherV2DisableEnableScheduleResponseMSG
#
# the following will enable the schedule:
# updated_schedule_data = (
# schedule_data[0:2] + consts.ENABLE_SCHEDULE + schedule_data[4:])
#
# the following will disable the schedule:
# updated_schedule_data = (
# schedule_data[0:2] + consts.DISABLE_SCHEDULE + schedule_data[4:])
enable_disable_response = await swapi.disable_enable_schedule(
updated_schedule_data)
# delete a schedule (0 <= schedule_id <= 7)
# schedule_id = (SwitcherV2Schedule).schedule_id
# response: messages.SwitcherV2DeleteScheduleResponseMSG
delete_response = await swapi.delete_schedule(schedule_id)
# create a schedule to turn on at 20:30 and off at 21:00
# response: messages.SwitcherV2CreateScheduleResponseMSG
schedule_days = [0]
# append selected days, if non-recurring skip next
schedule_days.append(consts.DAY_TO_INT_DICT[consts.SUNDAY])
schedule_days.append(consts.DAY_TO_INT_DICT[consts.MONDAY])
schedule_days.append(consts.DAY_TO_INT_DICT[consts.TUESDAY])
schedule_days.append(consts.DAY_TO_INT_DICT[consts.WEDNESDAY])
schedule_days.append(consts.DAY_TO_INT_DICT[consts.THURSDAY])
schedule_days.append(consts.DAY_TO_INT_DICT[consts.FRIDAY])
schedule_days.append(consts.DAY_TO_INT_DICT[consts.SATURDAY])
# skip here if non-recurring
weekdays = await tools.create_weekdays_value(
your_loop, schedule_days)
start_time = await tools.timedelta_str_to_schedule_time(
your_loop, str(timedelta(hours=20, minutes=30)))
end_time = await tools.timedelta_str_to_schedule_time(
your_loop, str(timedelta(hours=21)))
schedule_data = consts.SCHEDULE_CREATE_DATA_FORMAT.format(
weekdays, start_time, end_time)
create_response = await swapi.create_schedule(schedule_data)
return None
your_loop.run_until_complete(run_as_context_manager())
your_loop.close()
Objects and Properties¶
There are two main objects you need to be aware of:
The first object is the one representing the device itself,
aioswitcher.devices.SwitcherV2Device
SwitcherV2Device.The second object is the one representing the device’s schedule,
aioswitcher.schedules.SwitcherV2Schedule
SwitcherV2Schedule.
SwitcherV2Device¶
Property |
Type |
Description |
Possible Values |
Default Value |
---|---|---|---|---|
device_id |
|
Return the device id. |
ab1c2d |
|
ip_addr |
|
Return the ip address. |
192.168.100.157 |
waiting_for_data |
mac_addr |
|
Return the mac address. |
A1:B2:C3:45:67:D8 |
waiting_for_data |
name |
|
Return the device name. |
device name |
waiting_for_data |
state |
|
Return the device state. |
on, off |
|
remaining_time |
|
Return the auto-off configuration value. |
%H:%M:%S |
waiting_for_data |
auto_off_set |
|
Return the time left to auto-off. |
%H:%M:%S |
waiting_for_data |
power_consumption |
|
Return the power consumption in watts. |
2780 |
0 |
electric_current |
|
Return the power consumption in amps. |
12.8 |
0.0 |
phone_id |
|
Return the the phone id. |
1234 |
|
last_data_update |
|
Return the timestamp of the last update. |
%Y-%m-%dTH:%M:%S.%F |
|
last_state_change |
|
Return the timestamp of the last state change. |
%Y-%m-%dTH:%M:%S.%F |
SwitcherV2Schedule¶
Property |
Type |
Description |
Possible Values |
Default |
---|---|---|---|---|
schedule_id |
|
Return the schedule id. |
0-7 |
|
enabled |
|
Return true if enabled. Has a setter manipulating the schedule status. |
True, False |
False |
recurring |
|
Return true if recurring. |
True, False |
False |
days |
|
Return the weekdays of the schedule. |
|
|
start_time |
|
Return the start time of the schedule. |
%H:%M |
waiting_for_data |
end_time |
|
Return the end time of the schedule. |
%H:%M |
waiting_for_data |
duration |
|
Return the duration time of the schedule. |
0:30:00 |
waiting_for_data |
schedule_data |
|
Return the schedule data for managing the schedule. has a setter manipulating the schedule data. |
Any |
waiting_for_data |
init_future |
|
Return the future of the init. |
SwitcherV2Schedule |
API Response Messages¶
The following are the response message objects returning from the various API functions.
The source of the responses can be found aioswitcher.api.messages
.
Please note the aioswitcher.api.messagesResponseMessageType
Enum Class for identifying the
response message types:
|
|
|
|
SwitcherV2BaseResponseMSG¶
Property |
Type |
Description |
---|---|---|
unparsed_response |
|
Return the unparsed response message. |
successful |
|
Return the status of the message. |
msg_type |
|
Return the response message type. |
SwitcherV2StateResponseMSG¶
- Extends
- Response Type
ResponseMessageType.STATE
Property |
Type |
Description |
---|---|---|
state |
|
Return the state. Possible values are:
|
time_left |
|
Return the time left to auto-off. |
time_on |
|
Return the time in “on” state. Relevant only if the current state is “on”. |
auto_off |
|
Return the auto-off configuration value. |
power |
|
Return the current power consumption in watts. |
current |
|
Return the power consumption in amps. |
init_future |
|
Return the future of the initialization. As the initialization of this message requires some
asynchronous actions, please use
|
SwitcherV2ControlResponseMSG¶
- Extends
- Response Type
ResponseMessageType.CONTROL
No properties are added by object.
SwitcherV2SetAutoOffResponseMSG¶
- Extends
- Response Type
ResponseMessageType.AUTO_OFF
No properties are added by object.
SwitcherV2UpdateNameResponseMSG¶
- Extends
- Response Type
ResponseMessageType.UPDATE_NAME
No properties are added by object.
SwitcherV2GetScheduleResponseMSG¶
- Extends
- Response Type
ResponseMessageType.GET_SCHEDULES
Property |
Type |
Description |
---|---|---|
found_schedules |
|
Return true if found schedules in the response. |
get_schedules |
|
Return a list of SwitcherV2Schedule. |
SwitcherV2DisableEnableScheduleResponseMSG¶
- Extends
- Response Type
ResponseMessageType.DISABLE_ENABLE_SCHEDULE
No properties are added by object.
SwitcherV2DeleteScheduleResponseMSG¶
- Extends
- Response Type
ResponseMessageType.DELETE_SCHEDULE
No properties are added by object.
SwitcherV2CreateScheduleResponseMSG¶
- Extends
- Response Type
ResponseMessageType.CREATE_SCHEDULE
No properties are added by object.