feat: add heater support

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -46,6 +46,7 @@ body:
         - Switcher Light SL02
         - Switcher Light SL02 Mini
         - Switcher Light SL03
+        - Switcher Heater
     validations:
       required: true
 

docs/scripts.md

@@ -170,7 +170,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -245,7 +245,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -385,7 +385,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -423,7 +423,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -451,13 +451,15 @@ python control_device.py stop_shutter -c "runners12" -k "zvVvd7JxtN7CgvkD1Psujw=
 ```shell title="scripts/control_device.py turn_off"
 $ poetry run control_device turn_off --help
 
-usage: control_device.py turn_off [-h] [-v] -c DEVICE_TYPE -d DEVICE_ID [-l DEVICE_KEY] -i IP_ADDRESS
+usage: control_device.py turn_off [-h] [-v] -c DEVICE_TYPE [-k TOKEN] -d DEVICE_ID [-l DEVICE_KEY] -i IP_ADDRESS
 
 options:
   -h, --help            show this help message and exit
   -v, --verbose         include the raw message
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
+  -k TOKEN, --token TOKEN
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -470,21 +472,25 @@ example usage:
 python control_device.py turn_off -c "touch" -d ab1c2d -i "111.222.11.22"
 
 python control_device.py turn_off -c "touch" -d ab1c2d -l 18 -i "111.222.11.22"
+
+python control_device.py turn_off -c "heater" -k "zvVvd7JxtN7CgvkD1Psujw==" -d f2239a -l 18 -i "192.168.50.98"
 ```
 
 ### Turn on
 
 ```shell title="scripts/control_device.py turn_on"
 $ poetry run control_device turn_on --help
 
-usage: control_device.py turn_on [-h] [-v] -c DEVICE_TYPE -d DEVICE_ID [-l DEVICE_KEY] -i IP_ADDRESS
+usage: control_device.py turn_on [-h] [-v] -c DEVICE_TYPE [-k TOKEN] -d DEVICE_ID [-l DEVICE_KEY] -i IP_ADDRESS
                                  [-t [TIMER]]
 
 options:
   -h, --help            show this help message and exit
   -v, --verbose         include the raw message
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
+  -k TOKEN, --token TOKEN
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -501,6 +507,10 @@ python control_device.py turn_on -c "touch" -d ab1c2d -i "111.222.11.22"
 python control_device.py turn_on -c "touch" -d ab1c2d -l 18 -i "111.222.11.22"
 
 python control_device.py turn_on -c "touch" -d ab1c2d -i "111.222.11.22" -t 15
+
+python control_device.py turn_on -c "heater" -k "zvVvd7JxtN7CgvkD1Psujw==" -d f2239a -l 18 -i "192.168.50.98"
+
+python control_device.py turn_on -c "heater" -k "zvVvd7JxtN7CgvkD1Psujw==" -d f2239a -l 18 -i "192.168.50.98" -t 15
 ```
 
 ### Turn off light
@@ -516,7 +526,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -566,7 +576,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -616,7 +626,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -652,7 +662,7 @@ options:
   -c DEVICE_TYPE, --device-type DEVICE_TYPE
                         the type of the device
   -k TOKEN, --token TOKEN
-                        the token for communicating with the new switcher devices
+                        the token for communicating with switcher token-based devices
   -d DEVICE_ID, --device-id DEVICE_ID
                         the identification of the device
   -l DEVICE_KEY, --device-key DEVICE_KEY
@@ -675,6 +685,32 @@ python control_device.py turn_on_shutter_child_lock -c "runners11" -k "zvVvd7Jxt
 python control_device.py turn_on_shutter_child_lock -c "runners12" -k "zvVvd7JxtN7CgvkD1Psujw==" -d ab1c2d -i "111.222.11.22"
 ```
 
+### Get heater state
+
+```shell title="scripts/control_device.py get_heater_state"
+$ poetry run control_device get_heater_state --help
+
+usage: control_device.py get_heater_state [-h] [-v] -c DEVICE_TYPE [-k TOKEN] -d DEVICE_ID [-l DEVICE_KEY] -i IP_ADDRESS
+
+options:
+  -h, --help            show this help message and exit
+  -v, --verbose         include the raw message
+  -c DEVICE_TYPE, --device-type DEVICE_TYPE
+                        the type of the device
+  -k TOKEN, --token TOKEN
+                        the token for communicating with switcher token-based devices
+  -d DEVICE_ID, --device-id DEVICE_ID
+                        the identification of the device
+  -l DEVICE_KEY, --device-key DEVICE_KEY
+                        the login key of the device
+  -i IP_ADDRESS, --ip-address IP_ADDRESS
+                        the ip address assigned to the device
+
+example usage:
+
+python control_device.py get_heater_state -c "heater" -k "zvVvd7JxtN7CgvkD1Psujw==" -d f2239a -i "192.168.50.98"
+```
+
 ## Discover devices
 
 Use to discover devices and their states.

docs/supported.md

@@ -1,20 +1,21 @@
-| Name                     |                Link                 | Included from version |
-|--------------------------|:-----------------------------------:|:---------------------:|
-| Switcher V2              |       [product][switcher-v2]        |         1.x.x         |
-| Switcher Mini            |      [product][switcher-mini]       |         1.x.x         |
-| Switcher Touch (V3)      |      [product][switcher-touch]      |         1.x.x         |
-| Switcher V4              |       [product][switcher-v4]        |         1.x.x         |
-| Switcher Power Plug      |   [product][switcher-power-plug]    |         2.x.x         |
-| Switcher Breeze          |     [product][switcher-breeze]      |         3.x.x         |
-| Switcher Runner          |     [product][switcher-runner]      |         3.x.x         |
-| Switcher Runner Mini     |   [product][switcher-runner-mini]   |         3.x.x         |
-| Switcher Runner S11      |   [product][switcher-runner-s11]    |         4.x.x         |
-| Switcher Runner S12      |   [product][switcher-runner-s12]    |         4.1.x         |
-| Switcher Light SL01      |   [product][switcher-light-sl01]    |         4.2.x         |
-| Switcher Light SL01 Mini | [product][switcher-light-sl01-mini] |         4.2.x         |
-| Switcher Light SL02      |   [product][switcher-light-sl02]    |         4.3.x         |
-| Switcher Light SL02 Mini | [product][switcher-light-sl02-mini] |         4.3.x         |
-| Switcher Light SL03      |   [product][switcher-light-sl03]    |         4.4.x         |
+| Name                     |                Link                 | Included from version | Requires token     |
+|--------------------------|:-----------------------------------:|:---------------------:|:------------------:|
+| Switcher V2              |       [product][switcher-v2]        |         1.x.x         |         No         |
+| Switcher Mini            |      [product][switcher-mini]       |         1.x.x         |         No         |
+| Switcher Touch (V3)      |      [product][switcher-touch]      |         1.x.x         |         No         |
+| Switcher V4              |       [product][switcher-v4]        |         1.x.x         |         No         |
+| Switcher Power Plug      |   [product][switcher-power-plug]    |         2.x.x         |         No         |
+| Switcher Breeze          |     [product][switcher-breeze]      |         3.x.x         |         No         |
+| Switcher Runner          |     [product][switcher-runner]      |         3.x.x         |         No         |
+| Switcher Runner Mini     |   [product][switcher-runner-mini]   |         3.x.x         |         No         |
+| Switcher Runner S11      |   [product][switcher-runner-s11]    |         4.x.x         |         Yes        |
+| Switcher Runner S12      |   [product][switcher-runner-s12]    |         4.1.x         |         Yes        |
+| Switcher Light SL01      |   [product][switcher-light-sl01]    |         4.2.x         |         Yes        |
+| Switcher Light SL01 Mini | [product][switcher-light-sl01-mini] |         4.2.x         |         Yes        |
+| Switcher Light SL02      |   [product][switcher-light-sl02]    |         4.3.x         |         Yes        |
+| Switcher Light SL02 Mini | [product][switcher-light-sl02-mini] |         4.3.x         |         Yes        |
+| Switcher Light SL03      |   [product][switcher-light-sl03]    |         4.4.x         |         Yes        |
+| Switcher Heater          |       [product][switcher-heater]    |         6.x.x         |         Yes        |
 
 !!!note
     Newer Switcher devices, such as Runner S11, require a token. Get yours at: https://switcher.co.il/GetKey
@@ -34,3 +35,4 @@
 [switcher-light-sl02]: https://switcher.co.il/%D7%9E%D7%95%D7%A6%D7%A8/switcher-light-sl02/
 [switcher-light-sl02-mini]: https://switcher.co.il/%D7%9E%D7%95%D7%A6%D7%A8/switcher-light-slmini02/
 [switcher-light-sl03]: https://switcher.co.il/%D7%9E%D7%95%D7%A6%D7%A8/switcher-light-sl03/
+[switcher-heater]: https://switcher.co.il/%D7%9E%D7%95%D7%A6%D7%A8/switcher-heater/

docs/usage_api.md

@@ -141,3 +141,23 @@ asyncio.run(control_light(DeviceType.LIGHT_SL02, "111.222.11.22", "ab1c2d", "00"
 asyncio.run(control_light(DeviceType.LIGHT_SL02_MINI, "111.222.11.22", "ab1c2d", "00", "zvVvd7JxtN7CgvkD1Psujw=="))
 asyncio.run(control_light(DeviceType.LIGHT_SL03, "111.222.11.22", "ab1c2d", "00", "zvVvd7JxtN7CgvkD1Psujw=="))
 ```
+
+## Heater excerpt
+
+```python
+import asyncio
+from aioswitcher.api import Command, SwitcherApi
+from aioswitcher.device import DeviceType
+
+async def control_heater(device_type, device_ip, device_id, device_key, token) :
+    # for connecting to a device we need its type, id, login key, ip address and token
+    async with SwitcherApi(device_type, device_ip, device_id, device_key, token) as api:
+        # get the device's current state
+        await api.get_heater_state()
+        # turn the device on for 15 minutes
+        await api.control_device(Command.ON, 15)
+        # turn the device off
+        await api.control_device(Command.OFF)
+
+asyncio.run(control_heater(DeviceType.HEATER, "111.222.11.22", "ab1c2d" , "00", "zvVvd7JxtN7CgvkD1Psujw=="))
+```

scripts/control_device.py

@@ -53,6 +53,7 @@
     "light02": DeviceType.LIGHT_SL02,
     "light02mini": DeviceType.LIGHT_SL02_MINI,
     "light03": DeviceType.LIGHT_SL03,
+    "heater": DeviceType.HEATER,
 }
 
 # shared parse
@@ -78,7 +79,7 @@
     "--token",
     default=None,
     type=str,
-    help="the token for communicating with the new switcher devices",
+    help="the token for communicating with switcher token-based devices",
 )
 shared_parser.add_argument(
     "-d",
@@ -582,6 +583,18 @@
     help="the circuit number to turn on",
 )
 
+# get_heater_state parser
+_get_heater_state_examples = """example usage:
+
+poetry run control_device get_heater_state -c "heater" -k "zvVvd7JxtN7CgvkD1Psujw==" -d ab1c2d -i "111.222.11.22"\n """  # noqa E501
+subparsers.add_parser(
+    "get_heater_state",
+    help="get the current state of a heater device",
+    epilog=_get_heater_state_examples,
+    formatter_class=RawDescriptionHelpFormatter,
+    parents=[shared_parser],
+)
+
 
 def asdict(dc: object, verbose: bool = False) -> Dict[str, Any]:
     """Use as custom implementation of the asdict utility method."""
@@ -671,9 +684,10 @@ async def turn_on(
     device_ip: str,
     timer: int,
     verbose: bool,
+    token: Union[str, None] = None,
 ) -> None:
     """Use to launch a turn_on request."""
-    async with SwitcherApi(device_type, device_ip, device_id, device_key) as api:
+    async with SwitcherApi(device_type, device_ip, device_id, device_key, token) as api:
         printer.pprint(asdict(await api.control_device(Command.ON, timer), verbose))
 
 
@@ -683,9 +697,10 @@ async def turn_off(
     device_key: str,
     device_ip: str,
     verbose: bool,
+    token: Union[str, None] = None,
 ) -> None:
     """Use to launch a turn_off request."""
-    async with SwitcherApi(device_type, device_ip, device_id, device_key) as api:
+    async with SwitcherApi(device_type, device_ip, device_id, device_key, token) as api:
         printer.pprint(asdict(await api.control_device(Command.OFF), verbose))
 
 
@@ -889,6 +904,19 @@ async def turn_off_light(
         printer.pprint(asdict(await api.set_light(DeviceState.OFF, index), verbose))
 
 
+async def get_heater_state(
+    device_type: DeviceType,
+    device_id: str,
+    device_key: str,
+    device_ip: str,
+    verbose: bool,
+    token: Union[str, None] = None,
+) -> None:
+    """Use to launch a get_heater_state request."""
+    async with SwitcherApi(device_type, device_ip, device_id, device_key, token) as api:
+        printer.pprint(asdict(await api.get_heater_state(), verbose))
+
+
 def main() -> None:
     """Run the device controller script."""
     try:
@@ -918,6 +946,7 @@ def main() -> None:
                     args.ip_address,
                     args.timer,
                     args.verbose,
+                    args.token,
                 )
             )
         elif args.action == "turn_off":
@@ -928,6 +957,7 @@ def main() -> None:
                     args.device_key,
                     args.ip_address,
                     args.verbose,
+                    args.token,
                 )
             )
         elif args.action == "set_name":
@@ -1123,6 +1153,18 @@ def main() -> None:
                 )
             )
 
+        elif args.action == "get_heater_state":
+            asyncio.run(
+                get_heater_state(
+                    device_type,
+                    args.device_id,
+                    args.device_key,
+                    args.ip_address,
+                    args.verbose,
+                    args.token,
+                )
+            )
+
     except KeyboardInterrupt:
         exit()