diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..0743e4b --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020 Javier Peletier + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..de5b980 --- /dev/null +++ b/README.md @@ -0,0 +1,166 @@ +![Go](https://github.com/jpeletier/koolnova2mqtt/workflows/Go/badge.svg) +[![Go Report](https://goreportcard.com/badge/github.com/jpeletier/koolnova2mqtt)](https://goreportcard.com/report/github.com/jpeletier/koolnova2mqtt) +[![Godoc Reference](https://godoc.org/github.com/jpeletier/koolnova2mqtt?status.svg)](https://pkg.go.dev/github.com/jpeletier/koolnova2mqtt) + +# koolnova2mqtt bridge + +![homeassistant](gr/ha.png) + +![openhab](gr/openhab.png) + +![koolnova](gr/koolnova.png) + +***DISCLAIMER: This is not a Koolnova official product. Use at your own risk.*** + +**koolnova2mqtt** is a bidirectional bridge between MQTT and Koolnova's [100-CPND00](https://koolnova.com/catalogo/novaplus-domotica-100-cpnd00/) family of controllers, featuring auto-discovery for [Home Assistant](https://www.home-assistant.io), and compatible with [OpenHAB](https://www.openhab.org/) and any other automation platform that supports MQTT. + +## Features + +* Bi-directional synchronization between MQTT topics and Koolnova thermostats. +* Home Assistant auto-discovery as `climate` component thermostats and `sensor` reporting current temperature +* Written in go, cross-platform. + +When connected, **koolnova2mqtt** reads all configuration parameters and exports to your MQTT server a topic structure and configuration parameters for Home Assistant. This allows to use thermostats and temperature sensor cards like this one: + ![ha thermostat](gr/ha-thermostat.png) + +Koolnova thermostat modes can be changed by entering the thermostat settings menu (three dots in the top right) and selecting various modes: + +![ha thermostat settings](gr/ha-thermostat-settings.png) + +# Getting Started + +## Requirements + +* A Raspberry Pi or a PC +* A RS4835 USB dongle, such as [this one](https://es.aliexpress.com/item/32978270588.html):![dongle](gr/dongle.png) + +## Connecting + +Wire the controller's D+ and D- ports as follows: + +![Schematic](gr/schematic.png) + +* Controller D+ to USB dongle A +* Controller D- to USB dongle B +* Controller GND to USB dongle GND + +## Download + +Check the [Releases](https://github.com/jpeletier/koolnova2mqtt/releases) page and download the appropriate binary for your platform. + +## Running koolnova2mqtt + +Before using `koolnova2mqtt`, test your connection with a tool such as [modpoll](https://www.modbusdriver.com/modpoll.html) to ensure your PC and controller can communicate. For example, the following command should return the controller's slave id (default 49): + +```bash +./modpoll -b 9600 -p even -d 8 -s 1 -m rtu -t 4 -a 49 -1 -r 78 -4 100 /dev/ttyUSB0 +``` + +Where: + +* `-a 49` means send the message to slave with id `49` +* `-r 78` means read register #40078, which contains the slave ID +* `/dev/ttyUSB0` is the USB dongle's serial port. In Windows it would look like `COM3` or similar. Look in `/dev/ttyUSB*` or in Windows Device Manager to locate the port for your dongle. + +Check [modpoll](https://www.modbusdriver.com/modpoll.html) documentation for further information. + +## Command line reference +Once you are certain your dongle is properly connected, you can launch `koolnova2mqtt` with these parameters: + +``` +SYNTAX: + +koolnova2mqtt [options] + +options: + --clientid string + A clientid for the connection (default "your hostname") + --hassPrefix string + Home assistant discovery prefix (default "homeassistant") + --modbusDataBits int + Modbus port data bits (default 8) + --modbusParity string + N - None, E - Even, O - Odd (default E) (The use of no parity requires 2 stop bits.) (default "E") + --modbusPort string + Serial port where modbus hardware is connected (default "/dev/ttyUSB0") + --modbusRate int + Modbus port data rate (default 9600) + --modbusSlaveIDs string + Comma-separated list of modbus slave IDs to manage (default "49") + --modbusSlaveNames string + Comma-separated list of modbus slave names. Defaults to 'slave#' + --modbusStopBits int + Modbus port stop bits (default 1) + --password string + Password to match MQTT username + --prefix string + MQTT topic root where to publish/read topics (default "koolnova2mqtt") + --server string + The full url of the MQTT server to connect to ex: tcp://127.0.0.1:1883 (default "tcp://127.0.0.1:1883") + --username string + A username to authenticate to the MQTT server +``` + +### Example: + +``` +koolnova2mqtt --server tcp://192.168.1.1:1883 --modbusPort '/dev/ttyUSB1' --modbusSlaveIDs '49,50' --modbusSlaveNames 'firstFloor,secondFloor' +``` + +## MQTT topic structure + +The generated structure in MQTT looks as follows: + +``` +koolnova2mqtt +└── firstFloor + ├── zone1 + │ ├── fanMode = auto + │ ├── targetTemp = 20.5 + │ ├── currentTemp = 21 + │ └── hvacMode = heat + ├── zone2 + │ ├── fanMode = low + │ ├── targetTemp = 21 + │ ├── currentTemp = 20 + │ └── hvacMode = heat + ├── zone3 + │ ├── fanMode = auto + │ ├── targetTemp = 21 + │ ├── currentTemp = 21.5 + │ └── hvacMode = heat + └── sys + ├── ac1 + │ ├── airflow = 0 + │ ├── targetTemp = 0 + │ └── fanMode = high + ├── ac2 + │ ├── airflow = 0 + │ ├── targetTemp = 0 + │ └── fanMode = high + ├── ac3 + │ ├── airflow = 0 + │ ├── targetTemp = 0 + │ └── fanMode = high + ├── ac4 + │ ├── airflow = 0 + │ ├── targetTemp = 0 + │ └── fanMode = high + ├── efficiency = 3 + ├── enabled = true + ├── serialBaud = 9600 + ├── serialParity = even + └── holdMode = underfloor and fan + +``` +Most of the topics have a child `set` topic that allow you to modify that value. Thus, to change the target temperature of zone2 to 20.5ºC, write the string `20.5` to `koolnova2mqtt/firstFloor/zone2/targetTemp/set` topic. With the tool `mosquitto_pub`: + +```bash +mosquitto_pub -t "koolnova2mqtt/firstFloor/zone2/targetTemp/set" -m "20.5" +``` + +If the operation is successful, the topic `"koolnova2mqtt/firstFloor/zone2/targetTemp"` (without `set`) will be updated with the new target temperature, and the thermostat will show the new value. + +## Author(s) + +This package is written and maintained by Javier Peletier ([@jpeletier](https://github.com/jpeletier)) \ No newline at end of file diff --git a/gr/dongle.png b/gr/dongle.png new file mode 100644 index 0000000..0aa5363 Binary files /dev/null and b/gr/dongle.png differ diff --git a/gr/ha-thermostat-settings.png b/gr/ha-thermostat-settings.png new file mode 100644 index 0000000..c470340 Binary files /dev/null and b/gr/ha-thermostat-settings.png differ diff --git a/gr/ha-thermostat.png b/gr/ha-thermostat.png new file mode 100644 index 0000000..e9c179f Binary files /dev/null and b/gr/ha-thermostat.png differ diff --git a/gr/ha.png b/gr/ha.png new file mode 100644 index 0000000..5cb832b Binary files /dev/null and b/gr/ha.png differ diff --git a/gr/koolnova.png b/gr/koolnova.png new file mode 100644 index 0000000..b2846ac Binary files /dev/null and b/gr/koolnova.png differ diff --git a/gr/openhab.png b/gr/openhab.png new file mode 100644 index 0000000..9ba14de Binary files /dev/null and b/gr/openhab.png differ diff --git a/gr/schematic.png b/gr/schematic.png new file mode 100644 index 0000000..c8c4c7d Binary files /dev/null and b/gr/schematic.png differ