From 01d04716857d77ec089ca70dd86badfbf06aebc5 Mon Sep 17 00:00:00 2001 From: Tim van Werkhoven Date: Sat, 10 Jul 2021 22:17:55 +0200 Subject: [PATCH 1/2] Fixed markdown header hierarchy Fixed markdown header hierarchy --- README.md | 71 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index b75ee31..32caa08 100755 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ v2.0 runs on Python3. Python 2.7 is no longer supported, but can be found as v1. Please submit an issue when stability issues occur. -#Key features: +## Key features - Web-interface to switch, configure and edit schedules and stand-by killer - MQTT interface for control and log meter readings. - Log every 10-seconds in monitoring mode. @@ -19,7 +19,7 @@ Please submit an issue when stability issues occur. - Homey interface through MQTT. - Home Assistant interface through MQTT. -##Introduction +## Introduction Plugwise-2-py evolved in a monitoring and control server for plugwise devices. In v2.0 it can connect to a MQTT server. Commands to for example switch on a light can be given through the MQTT server, and when enabled, power readings are published as MQTT topics. Plugwise-2.py is a program is a logger of recorded meterings by plugwise. @@ -47,8 +47,7 @@ Finally the code implements several commands that have not been published before Besides the new functions for logging and control purposes, there are major improvements in the robustness of the communication. Return status is checked and acted upon correctly. Replies are now correlated to messages, so that no mix-up occur. -Setup ------ +## Setup ```shell wget https://bootstrap.pypa.io/get-pip.py @@ -60,8 +59,9 @@ sudo pip install . ``` > Note: include the period "." in the line above! -##configuration: -*First time install* +## Configuration + +### First time install Template config files are provided in the `config-default` folder. Those can be copied to the `config` folder. Be careful not to overwrite earlier settings. @@ -72,7 +72,7 @@ cp -n config-default/pw-control.json config/ cp -n config-default/pw-conf.json config/ ``` -*configuring server and circles* +### Configuring server and circles In config/pw-hostconfig.json edit tmp_path, permanent_path, log_path and serial @@ -103,14 +103,14 @@ Plugwise-2-py provides a MQTT-client. A separate MQTT-server like Mosquitto need The default port is 1883. -##run: +### Run ```nohup python Plugwise-2.py >>/tmp/pwout.log&``` -##autostart: +### Autostart Plugwise-2-py and the web-server can be automatically started with upstart in Ubuntu, or a cron job on the Raspberry pi. See instructions in the `autostart-howto` folder. -##debug: +### Debug the log level can be programmed in pw-control.json. Changes are picked up latest after 10 seconds. `"log_level": "info"` can have values error, info, debug @@ -119,16 +119,16 @@ the log level can be programmed in pw-control.json. Changes are picked up latest log_comm results in logging to pw-communications.log, in the log folder specified through log_path in pw-hostconfig.json -Update from github ------------------- +### Update from github + ```shell #from Plugwise-2-py folder: git pull sudo pip install --upgrade . ``` -Web interface -------------- +## Web interface + Plugwise-2-py can be operated through a web interfaces. The packages comes with its own dedicated web-server also written in python. It makes use of websockets for efficient and unsolicited communication. ##setup @@ -146,18 +146,18 @@ Providing a user:password is optional, as well as using SSL/https. When the webs ```shell nohup python Plugwise-2-web.py 8001 secure user:password >>pwwebout.log& -#no username and password requested +# no username and password requested nohup python Plugwise-2-web.py 8000 secure >>pwwebout.log& -#plain http, with optional port +# plain http, with optional port nohup python Plugwise-2-web.py 8002 >>pwwebout.log& -#plain http, default port 8000 +# plain http, default port 8000 nohup python Plugwise-2-web.py >>pwwebout.log& ``` -##use -###Control (switch and monitor) +### Usage +#### Control (switch and monitor) type in browser `https://:8000` @@ -174,7 +174,7 @@ in case of SSL/secure: use https//: `https://localhost:8000/pw2py.html` -###Configure and edit schedules +#### Configure and edit schedules (No editing static configuration file supported yet) type in browser: @@ -185,17 +185,17 @@ for example: `http://localhost:8000/cfg-pw2py.html` -##require +### Require The Control web-application requires the MQTT connection to be operational. The configuration application can work without MQTT. -MQTT ----- -##power readings +## MQTT + +### Power readings power readings can be published - autonomous - on request -###Autonomous +#### Autonomous Autonomous messages are published when monitoring = "yes" and when savelog = "yes". The 10-seconds monitoring published messages: `plugwise2py/state/power/000D6F0001Annnnn {"typ":"pwpower","ts":1405452425,"mac":"000D6F0001Annnnn","power":9.78}` @@ -204,7 +204,7 @@ The readings of the Circle buffers are published as: `plugwise2py/state/energy/000D6F0001Annnnn {"typ":"pwenergy","ts":1405450200,"mac":"000D6F0001nnnnnn","power":214.2069,"energy":35.7012,"interval":10}` -###On request +#### On request From applications like openhab, a power reading can be requested when needed, or for example scheduled by a cron job. The request will return a full circle state including the short term (8 seconds) integrated power value of the circle. Requests: `plugwise2py/cmd/reqstate/000D6F00019nnnnn {"mac":"","cmd":"reqstate","val":"1"}` @@ -214,7 +214,7 @@ The response is published as: `plugwise2py/state/circle/000D6F00019nnnnn {"powerts": 1405452834, "name": "circle4", "schedule": "off", "power1s": 107.897, "power8s": 109.218, "readonly": false, "interval": 10, "switch": "on", "mac": "000D6F00019nnnnn", "production": false, "monitor": false, "lastseen": 1405452834, "power1h": 8.228, "online": true, "savelog": true, "type": "circle", "schedname": "test-alternate", "location": "hal1"}` -##controlling switches and schedules +### Controlling switches and schedules Circles can be switched by publishing a command: `plugwise2py/cmd/switch/000D6F0001Annnnn {"mac":"","cmd":"switch","val":"on"}` @@ -228,28 +228,29 @@ The circle does respond with a state message, from which it can be deduced wheth `plugwise2py/state/circle/000D6F0001Annnnn {.... "schedule": "off", "switch": "on" ....}` -Openhab -------- +## Integration +### Openhab + Openhab can communicate with Plugwise-2-py through a MQTT server. Openhab provides a convenient system to operate switches and schedules. Also it can be used to record power readings and draw some graphs. TODO: Add a description. Example sitemap, items, rules and transforms can be found in the openhab folder in this repository -Domoticz --------- +### Domoticz + A MQTT to HTTP commands interface (using Node-Red) has been developed: https://www.domoticz.com/forum/viewtopic.php?f=14&t=7420&sid=22502c728a9a4f7d5ac93e6f5c0642a9 I am investigating a more direct MQTT to Domoticz interface currently. -Homey --------- +### Homey + A Homey app is available in the appstore: https://apps.athom.com/app/com.gruijter.plugwise2py For further instructions please visit https://forum.athom.com/discussion/1998 -Home Assistant --------- +### Home Assistant + Interfacing with Home Assistant can be done through MQTT. Some examples: From 07ff79e94eabd94ccf7eef5d745aadd4147464bf Mon Sep 17 00:00:00 2001 From: Tim van Werkhoven Date: Sat, 10 Jul 2021 22:25:59 +0200 Subject: [PATCH 2/2] Update markdown formatting for improved legibility filenames as monospace, remarks in bold instead of quoted, etc. --- README.md | 45 ++++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 32caa08..b1c7695 100755 --- a/README.md +++ b/README.md @@ -27,16 +27,16 @@ It also serves as a controller of the switches, and it can be used to upload switching/standby schedules to the circles. The interface to control is a file interface. There are three configuration files: -- pw-hostconfig.json: some host/server specific settings. -- pw-conf.json: intended as static configuration of the plugs. -- pw-control.json: dynamic configuration. +- `pw-hostconfig.json`: some host/server specific settings. +- `pw-conf.json`: intended as static configuration of the plugs. +- `pw-control.json`: dynamic configuration. Switching / stand-by killer schedules are defines as json files in the schedules folder -- schedules/*.json: contains a week-schedule to switch the plugs on and off. +- `schedules/*.json`: contains a week-schedule to switch the plugs on and off. -Changes to pw-control.json and schedules/*.json are automatically picked up by Plugwise-2.py and applied. +Changes to `pw-control.json` and `schedules/*.json` are automatically picked up by Plugwise-2.py and applied. -pw-control.json and schedules/*.json can be edited with the web application (see below) +`pw-control.json` and `schedules/*.json` can be edited with the web application (see below) In the dynamic configuration: - logging of the in-circle integrated values can be enabled (usually the one-value-per-hour loggings. @@ -57,7 +57,8 @@ git clone https://github.com/SevenW/Plugwise-2-py.git cd Plugwise-2-py sudo pip install . ``` -> Note: include the period "." in the line above! + +**Note: include the period "." in the line above!** ## Configuration @@ -74,15 +75,15 @@ cp -n config-default/pw-conf.json config/ ### Configuring server and circles -In config/pw-hostconfig.json edit tmp_path, permanent_path, log_path and serial +In `config/pw-hostconfig.json` edit `tmp_path`, `permanent_path`, `log_path` and `serial`: ```{"permanent_path": "/home/pi/datalog", "tmp_path": "/tmp", "log_path": "/home/pi/pwlog", "serial": "/dev/ttyUSB0"}``` -> Note: For INFO/DEBUG logging, normally /var/log can be used as path. However, on the raspberry pi, only the root user can write in /var/log. Therefore it is better to log to /home//pwlog +**Note: For INFO/DEBUG logging, normally `/var/log` can be used as path. However, on the raspberry pi, only the root user can write in `/var/log`. Therefore it is better to log to `/home//pwlog`** -> Note: Editing JSON files is error-prone. Use a JSON Validator such as http://jsonlint.com/ to check the config files. +**Note: Editing JSON files is error-prone. Use a JSON Validator such as http://jsonlint.com/ to check the config files.** -Edit the proper Circle mac addresses in pw-conf.json and pw-control.json. Make more changes as appropriate to your needs. +Edit the proper Circle mac addresses in `pw-conf.json` and `pw-control.json`. Make more changes as appropriate to your needs. - Enable 10-seconds monitoring: `"monitor": "yes"` - Enable logging form Circle internal metering buffers: `"savelog": "yes"` @@ -91,11 +92,11 @@ Monitor this activity by tailing the log file: `tail -f /home/pi/pwlog/pw-logger.log` -MQTT can be enable by adding two key,values to pw-hostconfig.json +MQTT can be enable by adding two key, values to `pw-hostconfig.json` `"mqtt_ip": "127.0.0.1", "mqtt_port": "1883"` -An example config file can be found in pw-hostconfig-mqtt.json +An example config file can be found in `pw-hostconfig-mqtt.json` Plugwise-2-py provides a MQTT-client. A separate MQTT-server like Mosquitto needs to be installed to enable MQTT in Plugwise-2-py. On Ubuntu systems it can be done like this: @@ -111,13 +112,13 @@ The default port is 1883. Plugwise-2-py and the web-server can be automatically started with upstart in Ubuntu, or a cron job on the Raspberry pi. See instructions in the `autostart-howto` folder. ### Debug -the log level can be programmed in pw-control.json. Changes are picked up latest after 10 seconds. +the log level can be programmed in `pw-control.json`. Changes are picked up latest after 10 seconds. `"log_level": "info"` can have values error, info, debug `"log_comm": "no"` can have values no and yes. -log_comm results in logging to pw-communications.log, in the log folder specified through log_path in pw-hostconfig.json +`log_comm` results in logging to `pw-communications.log`, in the log folder specified through `log_path` in `pw-hostconfig.json`. ### Update from github @@ -130,23 +131,25 @@ sudo pip install --upgrade . ## Web interface Plugwise-2-py can be operated through a web interfaces. The packages comes with its own dedicated web-server also written in python. It makes use of websockets for efficient and unsolicited communication. -##setup + +## Setup ```shell #assume current directory is Plugwise-2-py main directory nohup python Plugwise-2-web.py 8000 secure plugwise:mysecret >>pwwebout.log& ``` -This uses SSL/https. Change plugwise:mysecret in a username:password chosen by yourself. The websserver uses port 8000 by default, and can be changed by an optional parameter: +This uses SSL/https. Change `plugwise:mysecret` in a `username:password` chosen by yourself. The websserver uses port 8000 by default, and can be changed by an optional parameter: `nohup python Plugwise-2-web.py 8001 secure plugwise:mysecret >>pwwebout.log&` -Providing a user:password is optional, as well as using SSL/https. When the website is only accessible within your LAN, then the server can be used as plain http, by omitting the secure parameter. The following parameter formats are valid: +Providing a `user:password` is optional, as well as using SSL/https. When the website is only accessible within your LAN, then the server can be used as plain http, by omitting the secure parameter. The following parameter formats are valid: ```shell +# https, with username and password nohup python Plugwise-2-web.py 8001 secure user:password >>pwwebout.log& -# no username and password requested +# https, no username and password requested nohup python Plugwise-2-web.py 8000 secure >>pwwebout.log& # plain http, with optional port @@ -196,7 +199,7 @@ power readings can be published - on request #### Autonomous -Autonomous messages are published when monitoring = "yes" and when savelog = "yes". The 10-seconds monitoring published messages: +Autonomous messages are published when `monitoring = "yes"` and when `savelog = "yes"`. The 10-seconds monitoring published messages: `plugwise2py/state/power/000D6F0001Annnnn {"typ":"pwpower","ts":1405452425,"mac":"000D6F0001Annnnn","power":9.78}` @@ -233,7 +236,7 @@ The circle does respond with a state message, from which it can be deduced wheth Openhab can communicate with Plugwise-2-py through a MQTT server. Openhab provides a convenient system to operate switches and schedules. Also it can be used to record power readings and draw some graphs. -TODO: Add a description. +**TODO: Add a description.** Example sitemap, items, rules and transforms can be found in the openhab folder in this repository ### Domoticz