| Name | wccontrol JSON |
| Version |
2.0.2
JSON |
| download |
| home_page | |
| Summary | Python module/program to control Watts Clever switch |
| upload_time | 2023-10-31 23:34:43 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | GPLv3 |
| keywords |
rpi
pi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## WCCONTROL - Watts Clever Switch Control
[](https://pypi.org/project/wccontrol/)
This is a Raspberry Pi command line program and Python module to switch
on and off a Watts Clever RF Switch via a cheap 433 MHz transmitter
module. I also have a higher level program
[`wcscheduler`](https://github.com/bulletmark/wcscheduler) which imports
this module and can be used to schedule one or more switches on/off at
specified times and days of week.
The `wccontrol` module implements the protocol which was reverse
engineered in the excellent posts
[here](https://goughlui.com/2016/04/10/reverse-eng-watts-clever-easy-off-sockets-wsmart-box-es-aus1103/)
and
[here](https://goughlui.com/2016/04/13/reverse-eng-pt-2-watts-clever-easy-off-wsmart-box-es-aus1103/).
The latest version of this document and code is available at
https://github.com/bulletmark/wccontrol.
## Watts Clever Switch
You need one or more of these:
Often this is purchased in a pack with 2, 3, or 4 such switches, and an
IR (infra-red) receiver box which allows you to operate the remote
switches using a standard TV remote which talks IR to the receiver, then
the receiver talks RF 433 MHz to the switches. E.g the pack is:
The `wccontrol` module allows your Raspberry Pi to talk directly via RF
to the switches. You do not need the IR receiver box at all (i.e. you do
not need the blue box in above image), neither to operate or initially
program the switches. `wccontrol` can be used to fully program
switch group and addresses, and then to operate the switches on and off.
## RF Transmitter
You also need a 433 MHz RF transmitter to connect to your Raspberry Pi.
RF modules like the above for Raspberry Pi and similar devices are
purchased for only a few bucks on ebay etc, usually as a transmitter and
receiver pair. To use `wccontrol`, we only need the transmitter which is
the smaller board as shown above.
The transmitter has 3 pins which you directly connect to the RPi header
pins using push-on [female to female jumper
wires](https://www.adafruit.com/product/266) as follows.
Tx pin | Description | Raspberry Pi GPIO header
------ | ----------- | ------------------------
Left | Data | GPIO4 (board pin 7)
Middle | VCC | 5V power (e.g. board pin 4 or 2)
Right | GND | Ground (e.g. board pin 6 or 9 or etc)
You can significantly increase the range of the transmitter by soldering
a 17.3 cm copper wire to the ANT pad in the corner of the PCB. Ideally,
orientate the wire parallel to the switches, i.e. if you plug the RF
switch unit directly into a wall socket then orientate the antenna wire
vertically.
Note that `wccontrol` uses GPIO4 by default to drive the transmitter but
you can easily set it to use any of the other Raspberry Pi GPIO pins by
passing the `pin` argument.
## Installation
Requires Python 3.6 or later. Does not work with Python 2.
`wccontrol` is [available on PyPI](https://pypi.org/project/wccontrol/)
so install the usual way, e.g:
```bash
$ pipx install -U wccontrol
```
Or explicitly from [github](https://github.com/bulletmark/wccontrol):
```bash
$ git clone https://github.com/bulletmark/wccontrol.git
$ cd wccontrol
$ pipx install .
```
### Make GPIO Device Accessible
To be able to run this utility/module as your normal user you need to
install a udev rule and assign yourself to the `gpio` group.
As root, create `gpio` group:
```bash
$ sudo groupadd -f -r gpio
```
Add your user to that group:
```bash
$ sudo usermod -aG gpio $USER
```
Fetch `gpio.rules` from this repo and copy it to the appropriate place
on your system:
```bash
$ sudo curl -L https://raw.githubusercontent.com/bulletmark/wccontrol/master/gpio.rules -o /etc/udev/rules.d/99-gpio.rules
```
Reboot your RPi and log back in again.
## Groups and Addresses
Before you can operate a switch on/off you must first program it to
respond to a specific _group_ and _address_.
A _group_ is a number 0 to 1023. An _address_ is a number 0 to 7 within
a group that you allocate to specific switches. Address number 6 is
special as it means "all addresses in same group", i.e. you can switch
all devices together in the same group by using address 6. So there are
actually only 7 unique addresses which you can use per group, 0->5 and
7. Thus there are potentially 1024 x 7 individually addressable devices
you can control.
### Program Group and Address to Device
E.g. say you want to assign your first switch as address 0 in group 0.
1. Ensure power is applied to the switch.
1. Ensure switch is OFF, i.e. press button to turn LED OFF.
1. Press and hold the switch button until the LED fast flashes, then
slow flashes, then release.
1. Execute the ON command `wccontrol 0 0 1` to program ON.
1. Execute the OFF command `wccontrol 0 0 0` to program OFF.
1. The LED will go OFF and the switch is now programmed.
1. Test using `wccontrol 0 0 1` to confirm the switch goes ON then
`wccontrol 0 0 0` to confirm the switch goes OFF.
1. Repeat the above steps for your other switches using a different group/address.
## Example Commands to Switch On and Off
Switch group 0, device 2 to ON:
```bash
$ wccontrol 0 2 1
```
Switch group 0, device 2 to OFF:
```bash
$ wccontrol 0 2 0
```
Switch group 0, device 3 to ON:
```bash
$ wccontrol 0 3 1
```
Switch group 0, device 3 to OFF:
```bash
$ wccontrol 0 3 0
```
Switch both (i.e. all) devices in group 0 to ON:
```bash
$ wccontrol 0 6 1
```
Switch both (i.e. all) devices in group 0 to OFF:
```bash
$ wccontrol 0 6 0
```
## Command Line Options
Type `wccontrol -h` to view the usage summary:
```
usage: wccontrol [-h] [-p PIN] [-r RETRIES] group address {0,1}
Module/program to set a Watts Clever Smart switch on or off.
positional arguments:
group group, 0 to 1023
address switch address to write to, 0 to 7 (6=all in same
group)
{0,1} value 0=off, 1=on
options:
-h, --help show this help message and exit
-p PIN, --pin PIN RPi BCM GPIO pin to output (default: 4)
-r RETRIES, --retries RETRIES
number of retries to send (default: 15)
```
## Using as a Python Module
```python
from wccontrol import WCcontrol
# Create instance on given "pin"
wc = WCcontrol(pin)
# Use this instance
wc.set(0, 2, 1)
```
See the stub code in
[`wccontrol.py`](https://github.com/bulletmark/wccontrol/blob/master/wccontrol.py)
or my [scheduler
application](https://github.com/bulletmark/wcscheduler/blob/master/wcscheduler)
for more complete examples using the python module.
## IFTTT Integration
Another example of how this module can be used is to call it from a tiny
web service application you can run on your Raspberry Pi and which can
receive [IFTTT](https://ifttt.com/discover) web-hook messages from the
internet to turn devices on and off. Usually you would just forward a
port from your home firewall/router to the RPi. The web-hooks can be
triggered by the Google Assistant service. So you can say "Hey Google,
turn the Living Room lights on" and it happens! Quite simple and cheap
to implement given the hardware described here. My [scheduler
application](https://github.com/bulletmark/wcscheduler)
for _wccontrol_ has [IFTTT](https://ifttt.com/discover) integration.
<!-- vim: se ai syn=markdown: -->
Raw data
{
"_id": null,
"home_page": "",
"name": "wccontrol",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "rpi,pi",
"author": "",
"author_email": "Mark Blakeney <mark.blakeney@bullet-systems.net>",
"download_url": "https://files.pythonhosted.org/packages/55/cb/fef31bc50d7293a7b04dcd7dba1f28f025fc3544de58d1f944238f0a2601/wccontrol-2.0.2.tar.gz",
"platform": null,
"description": "## WCCONTROL - Watts Clever Switch Control\n[](https://pypi.org/project/wccontrol/)\n\nThis is a Raspberry Pi command line program and Python module to switch\non and off a Watts Clever RF Switch via a cheap 433 MHz transmitter\nmodule. I also have a higher level program\n[`wcscheduler`](https://github.com/bulletmark/wcscheduler) which imports\nthis module and can be used to schedule one or more switches on/off at\nspecified times and days of week.\n\nThe `wccontrol` module implements the protocol which was reverse\nengineered in the excellent posts\n[here](https://goughlui.com/2016/04/10/reverse-eng-watts-clever-easy-off-sockets-wsmart-box-es-aus1103/)\nand\n[here](https://goughlui.com/2016/04/13/reverse-eng-pt-2-watts-clever-easy-off-wsmart-box-es-aus1103/).\n\nThe latest version of this document and code is available at\nhttps://github.com/bulletmark/wccontrol.\n\n## Watts Clever Switch\n\nYou need one or more of these:\n\n\n\nOften this is purchased in a pack with 2, 3, or 4 such switches, and an\nIR (infra-red) receiver box which allows you to operate the remote\nswitches using a standard TV remote which talks IR to the receiver, then\nthe receiver talks RF 433 MHz to the switches. E.g the pack is:\n\n\n\nThe `wccontrol` module allows your Raspberry Pi to talk directly via RF\nto the switches. You do not need the IR receiver box at all (i.e. you do\nnot need the blue box in above image), neither to operate or initially\nprogram the switches. `wccontrol` can be used to fully program\nswitch group and addresses, and then to operate the switches on and off.\n\n## RF Transmitter\n\nYou also need a 433 MHz RF transmitter to connect to your Raspberry Pi.\n\n\n\nRF modules like the above for Raspberry Pi and similar devices are\npurchased for only a few bucks on ebay etc, usually as a transmitter and\nreceiver pair. To use `wccontrol`, we only need the transmitter which is\nthe smaller board as shown above.\n\nThe transmitter has 3 pins which you directly connect to the RPi header\npins using push-on [female to female jumper\nwires](https://www.adafruit.com/product/266) as follows.\n\nTx pin | Description | Raspberry Pi GPIO header\n------ | ----------- | ------------------------\nLeft | Data | GPIO4 (board pin 7)\nMiddle | VCC | 5V power (e.g. board pin 4 or 2)\nRight | GND | Ground (e.g. board pin 6 or 9 or etc)\n\nYou can significantly increase the range of the transmitter by soldering\na 17.3 cm copper wire to the ANT pad in the corner of the PCB. Ideally,\norientate the wire parallel to the switches, i.e. if you plug the RF\nswitch unit directly into a wall socket then orientate the antenna wire\nvertically.\n\nNote that `wccontrol` uses GPIO4 by default to drive the transmitter but\nyou can easily set it to use any of the other Raspberry Pi GPIO pins by\npassing the `pin` argument.\n\n## Installation\n\nRequires Python 3.6 or later. Does not work with Python 2.\n\n`wccontrol` is [available on PyPI](https://pypi.org/project/wccontrol/)\nso install the usual way, e.g:\n\n```bash\n$ pipx install -U wccontrol\n```\n\nOr explicitly from [github](https://github.com/bulletmark/wccontrol):\n\n```bash\n$ git clone https://github.com/bulletmark/wccontrol.git\n$ cd wccontrol\n$ pipx install .\n```\n\n### Make GPIO Device Accessible\n\nTo be able to run this utility/module as your normal user you need to\ninstall a udev rule and assign yourself to the `gpio` group.\n\nAs root, create `gpio` group:\n\n```bash\n$ sudo groupadd -f -r gpio\n```\n\nAdd your user to that group:\n\n```bash\n$ sudo usermod -aG gpio $USER\n```\n\nFetch `gpio.rules` from this repo and copy it to the appropriate place\non your system:\n\n```bash\n$ sudo curl -L https://raw.githubusercontent.com/bulletmark/wccontrol/master/gpio.rules -o /etc/udev/rules.d/99-gpio.rules\n```\n\nReboot your RPi and log back in again.\n\n## Groups and Addresses\n\nBefore you can operate a switch on/off you must first program it to\nrespond to a specific _group_ and _address_.\n\nA _group_ is a number 0 to 1023. An _address_ is a number 0 to 7 within\na group that you allocate to specific switches. Address number 6 is\nspecial as it means \"all addresses in same group\", i.e. you can switch\nall devices together in the same group by using address 6. So there are\nactually only 7 unique addresses which you can use per group, 0->5 and\n7. Thus there are potentially 1024 x 7 individually addressable devices\nyou can control.\n\n### Program Group and Address to Device\n\nE.g. say you want to assign your first switch as address 0 in group 0.\n\n1. Ensure power is applied to the switch.\n1. Ensure switch is OFF, i.e. press button to turn LED OFF.\n1. Press and hold the switch button until the LED fast flashes, then\n slow flashes, then release.\n1. Execute the ON command `wccontrol 0 0 1` to program ON.\n1. Execute the OFF command `wccontrol 0 0 0` to program OFF.\n1. The LED will go OFF and the switch is now programmed.\n1. Test using `wccontrol 0 0 1` to confirm the switch goes ON then \n `wccontrol 0 0 0` to confirm the switch goes OFF.\n1. Repeat the above steps for your other switches using a different group/address.\n\n## Example Commands to Switch On and Off\n\nSwitch group 0, device 2 to ON:\n\n```bash\n$ wccontrol 0 2 1\n```\n\nSwitch group 0, device 2 to OFF:\n\n```bash\n$ wccontrol 0 2 0\n```\n\nSwitch group 0, device 3 to ON:\n\n```bash\n$ wccontrol 0 3 1\n```\n\nSwitch group 0, device 3 to OFF:\n\n```bash\n$ wccontrol 0 3 0\n```\n\nSwitch both (i.e. all) devices in group 0 to ON:\n\n```bash\n$ wccontrol 0 6 1\n```\n\nSwitch both (i.e. all) devices in group 0 to OFF:\n\n```bash\n$ wccontrol 0 6 0\n```\n\n## Command Line Options\n\nType `wccontrol -h` to view the usage summary:\n\n```\nusage: wccontrol [-h] [-p PIN] [-r RETRIES] group address {0,1}\n\nModule/program to set a Watts Clever Smart switch on or off.\n\npositional arguments:\n group group, 0 to 1023\n address switch address to write to, 0 to 7 (6=all in same\n group)\n {0,1} value 0=off, 1=on\n\noptions:\n -h, --help show this help message and exit\n -p PIN, --pin PIN RPi BCM GPIO pin to output (default: 4)\n -r RETRIES, --retries RETRIES\n number of retries to send (default: 15)\n```\n\n## Using as a Python Module\n\n```python\nfrom wccontrol import WCcontrol\n\n# Create instance on given \"pin\"\nwc = WCcontrol(pin)\n\n# Use this instance\nwc.set(0, 2, 1)\n```\n\nSee the stub code in\n[`wccontrol.py`](https://github.com/bulletmark/wccontrol/blob/master/wccontrol.py)\nor my [scheduler\napplication](https://github.com/bulletmark/wcscheduler/blob/master/wcscheduler)\nfor more complete examples using the python module.\n\n## IFTTT Integration\n\nAnother example of how this module can be used is to call it from a tiny\nweb service application you can run on your Raspberry Pi and which can\nreceive [IFTTT](https://ifttt.com/discover) web-hook messages from the\ninternet to turn devices on and off. Usually you would just forward a\nport from your home firewall/router to the RPi. The web-hooks can be\ntriggered by the Google Assistant service. So you can say \"Hey Google,\nturn the Living Room lights on\" and it happens! Quite simple and cheap\nto implement given the hardware described here. My [scheduler\napplication](https://github.com/bulletmark/wcscheduler)\nfor _wccontrol_ has [IFTTT](https://ifttt.com/discover) integration.\n\n<!-- vim: se ai syn=markdown: -->\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Python module/program to control Watts Clever switch",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/bulletmark/wccontrol"
},
"split_keywords": [
"rpi",
"pi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31593010fd15149486b3b2c2a75850d4b1c027dccb4155692f360a4206dd08a1",
"md5": "d04fd9e0da4047116a116227b9ef6c2a",
"sha256": "fba457f3b531f6095af1f748ba69bc37d6ce32c6e4eb525f6b27ebe5370f7fb1"
},
"downloads": -1,
"filename": "wccontrol-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d04fd9e0da4047116a116227b9ef6c2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6017,
"upload_time": "2023-10-31T23:34:41",
"upload_time_iso_8601": "2023-10-31T23:34:41.559400Z",
"url": "https://files.pythonhosted.org/packages/31/59/3010fd15149486b3b2c2a75850d4b1c027dccb4155692f360a4206dd08a1/wccontrol-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55cbfef31bc50d7293a7b04dcd7dba1f28f025fc3544de58d1f944238f0a2601",
"md5": "dbe6dcdc7d369938683d28250a1f82b5",
"sha256": "2c332b9977da1762900c17ba6fe5cadbea94a46202fd0ba25ede6450c9834bbb"
},
"downloads": -1,
"filename": "wccontrol-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "dbe6dcdc7d369938683d28250a1f82b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6579,
"upload_time": "2023-10-31T23:34:43",
"upload_time_iso_8601": "2023-10-31T23:34:43.368893Z",
"url": "https://files.pythonhosted.org/packages/55/cb/fef31bc50d7293a7b04dcd7dba1f28f025fc3544de58d1f944238f0a2601/wccontrol-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-31 23:34:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bulletmark",
"github_project": "wccontrol",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wccontrol"
}
