iobroker.controme v0.3.4-alpha.2

ioBroker.controme

Tests:

ioBroker adapter for Controme mini servier

Connect to local Controme mini server using the official API.

Controme is a heating control system with which you can control your floor heating, central heating system, radiators or other forms of climate control. At the core of a Controme Smart-Heat-System is the Controme mini server, a local Raspberry Pi based system. For more information on the Controme Smart-Heat-System, see the Controme website.

The adapter periodically reads the room temperatures from the mini server as well as allows to set the setpoint temperatures on the server from ioBroker. To use this adapter, you need to have Controme activate the API. The adapter is not intended to replace the Controme UI, but shall over basic data and functionality to integrate Controme with other Smart Home devices and services.

The adapter provides the following data for each room defined in the Controme UI: | Object | Type | Description | | --- | --- | --- | | roomID | device | Each room is represented with its Controme room ID and the room name as device name. | | roomID.actualTemperature | state | The actual temperature of the room, with a role of level.temperature. This state is read-only. If no room temperature sensor for a particular room is defined, the actual temperature returned from the Controme mini server is null. | | roomID.setPointTemperature | state | The target / setpoint temperature of the room, with a role of value.temperature. This state is read/write. | | roomID.temperatureOffset | state | The offset temperature of the room, by which the sensor measurements are different from the actual temperature of the room. The temperature offset value can be set manually in the Controme UI, and in addition is calculated by various Controme modules. This state if read-only. | | roomID.offsets | channel | Offsets are added or subtracted from the setpoint room temperature. This channel groups all offsets that belong to the respective room. | | roomID.offsets.OFFSET-GROUP | channel | Each offset source is repesented by a dedicated channel within the offsets channel of the room the offset belongs to. | | roomID.offsets.OFFSET-GROUP.OFFSET | state | The individual offset state represent the different adjustments made by the Controme mini server. These states are read-only. | | roomID.offsets.api | channel | This offset group is special, since its states can be written to and can be used to manipulate the actual room offset. | | roomID.offsets.api.api | state | This offset state is created by default by the adapter. You can use it to manipulate the actual room offsets. The offset values are reset by the server each 10 minutes. This state is read/write. | | roomID.sensors | channel | Sensors provide the actual measurements associated with the room. This channel groups all sensors assigned to the respective room. | | roomID.sensors.SENSOR-ID | device | Each sensor is represented by a device within the sensors channel of the room it is assigned to. | | roomID.sensors.SENSOR-ID.isRoomTemperatureSensor | state | This boolean state indicates if a sensor is used as room temperature sensor. For each room, only a single sensor can be used as room temperature sensor. This state is read-only. | | roomID.sensors.SENSOR-ID.actualTemperature | state | This state represents the actual temperature measured by the sensor. The state is read/write, but only 1Wire sensors or virtual sensors will accept the provided values. In case you write a value to a real sensor, the value will be overwritten when the next reading is done. | | roomID.outputs | channel | Outputs typically control valves that control the room's heating. This channel groups all outputs assigned to the respective room. | | roomID.outputs.OUTPUT-ID | state | Each output is represented by a state within the output channel of the room it belongs to. The output ID number represents the number of the output on the gateway. | | gatewayMAC | device | Each gateway is represented with its MAC address and the gateway name as device name. | | gatewayMAC.gatewayType | state | The type of the gateway. Currently, there are four controme gateways: floor gateway smart, floor gateway pro, universal gateway mini, universal gateway pro. | | gatewayMAC.isUniversal | state | Indicates if gateway is one of the universal gateways. Data from universal gateways need to be polled in a different way. | | gatewayMAC.outputs | channel | Outputs typically control valves that control the room's heating for floor gateways or devices in the heating room (pumps, valves). This channel groups all outputs of the respective gateway. | | gatewayMAC.outputs.OUTPUT-ID | state | Each output is represented by a state within the output channel of the gateway it is assigned to. The output ID number represents the number of the output on the gateway as setup in the configuration. |

The API documentation can be found on the Controme website.

To start the adapter, the following data need to be provided in the admin settings page for the adapter instance: | Data field | Type | Description | | --- | --- | --- | | url | text | The URL of the Controme mini server. Can be either the IP address or the name. | | house ID | number | The ID of the Controme installation. This should be either 1 or 2 according to the API documentation. | | interval | number | The interval in seconds in which the data is polled from the server. This value should be between 15 seconds and 3600 seconds. Too low values do not make sense, since Controme updates the sensor values only every 3-5 minutes. | | forceReInit | checkbox | If this checkbox is set, Controme purges the object structure in the ioBroker database and reloads the rooms from the server. This setting is only required when the room structure on the Controme server changes. | | warnOnNull | checkbox | If this checkbox is set, the adapter writes log warnings when a sensor returns a NULL value. Returning NULL values is expected behaviour for window sensors, but would indicate a connection problem for temperature sensors. The API does not allow to discern between | | username | text | The username with which to access the Controme API. This is usually the username of the main Controme user. | | password | password | The password of the user with which to access the Controme API. This password is encrypted. | | gateways | table | All gateways that the adapter shall poll the data for have to be configures with three values: | | gateways.gatewayMAC | string | The MAC address of the individual gateway. | | gateways.type | string | The type of the respective gateway. Can be either Floor Gateway Smart/Pro, Universal Gateway Mini or Universal Gateway Pro. | | gateways.name | string | The name of the respective gateway. | | gatewayOutputs | table | All outputs of all gateways that the adapter shall poll the data for have to be configures with three values: | | gatewayOutputs.gatewayMAC | string | The MAC address of the individual gateway. This has to match one of the gatewayMAC values configured in the gateways table. Please note that currently, the adapter does not validate if the gateway MAC addresses match to those configured in the gateways table. So please pay attention that gateway MAC addresses match in both tables. | | gatewayOutputs.outputID | number | The output ID of the respective gateway that shall be polled. For mini gateways, this number has to be 1 to 8, for other gateways is can be 1 to 15. | | gatewayOutputs.outputName | string | The name of the respective output of the gateway. |

To Dos

1. (in progress) Publish the adapter :)
2. Add data validation to config fields
3. (done, testing pending) Extend data fields received from Controme mini server (e.g. humidity)
4. (done) Add sensor data for each sensor and room
5. Implement target temperature (temporary changes to desired temperature for room) next to setpoint temperature
6. (done) Add option to set value for virtual sensors

Know Bugs

1. ...

Changelog

0.3.4-alpha.2 (2022-06-01)

• (MadErstam) Added validation of setTargetTemp, setSetpointTemp, setActualTemp, setOffsetTemp values
• (MadErstam) Changed dependencies
• (MadErstam) Cleaning up

0.3.4-alpha.1 (2022-04-25)

• (MadErstam) Prepare for release

0.3.4-alpha.0 (2022-04-25)

• (MadErstam) Prepare for release

0.3.3 (2022-04-25)

• (MadErstam) Updated dependencies

0.3.2 (2022-04-25)

• (MadErstam) Prepare for release

0.3.1 (2022-04-25)

• (MadErstam) Cleaning up adapter, bugfixing, extended readme

0.3.0

• (MadErstam) Extended API polling (outputs, gateways)

0.2.4

• (MadErstam) Bugfixing

0.2.3

• (MadErstam) Bugfixing

0.2.2

• (MadErstam) Bugfixing in offset handling

0.2.1

• (MadErstam) Improved offset handling

0.2.0

• (MadErstam) Added sensors and offsets

0.1.2

• (MadErstam) Preparations for adapter package release

0.1.1

• (MadErstam) Minor bug fixes

0.1.0

• (MadErstam) initial release

License

MIT License

Copyright (c) 2022 MadErstam erstam@gmx.de

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.