optolink-bridge 1.0.0

package/config.toml

@@ -0,0 +1,292 @@
+# serial port of the Vitoconnect device, defaults to "/dev/ttyS0", Raspberry 3B+ (and some others) use "/dev/ttyAMA0"
+port_vito = "/dev/ttyS0"
+# serial port of the Optolink adapter / device, defaults to "/dev/ttyUSB0"
+port_opto = "/dev/ttyUSB0"
+
+# log level, one of "none", "error", "warn", "info", "trace" or "verbose" defaults to "warn"
+# note: this setting may be changed during runtime and is picked up from this file automatically
+log_level = "warn"
+
+# data points to listen to and publish
+# (use tools/convert_poll_items.js to convert your existing optolink-splitter poll_list to data_points)
+data_points = [
+  # [name, addr, [type], [scale]]
+    # name: name of the data point, as published
+    # addr: address of the data point, either as hexadecimal 0xab01 or as decimal 43873
+    # type:
+      # "raw" for raw data (0x..., alias for buffer)
+      # "int" / "uint" for integer values matching the size of the data (e.g. (u)int16 for 2 bytes)
+      #   corner case: 3 byte values are mapped to (u)int16 and 5 byte values to (u)int32
+      #      due to a many numerical data points having a trailing status byte that is ignored
+      # "byte" for a single byte value (alias for uint8)
+      # "vdatetime" for Viessmann specific date and time values
+      # "unixtime" for unix timestamps
+      # "utf8" for utf8 encoded strings
+      # or any data types supported by binary-parser (e.g. uint16)
+      # note that byte-bit filters are *not* yet supported
+    # scale: a factor to scale the numeric value by, e.g. 0.1 to convert 100 to 10.0
+  # if type is set to a number, the data point is treated as a integer matching the size of the data (e.g. (u)int16
+  # for 2 bytes), the number represents the scale, scale can the be set to true, to indicate a signed number
+  # if no type is given, the data point is treated as a raw
+
+  ["outside_temperature", 0x01C1, "int16", 0.1], # 3 bytes (sensor temp. w/ status), 2 bytes as 0x0101, but not sent by Vitoconnect
+  ["averaged_outside_temperature", 0x160D, "int16", 0.1],
+  ["averaging_time_outside_temperature", 0x7002, "int16"],
+
+  ["operating_mode", 0xB000, "byte"],
+
+  ["heating_circuit_circulation_pump", 0x048D, "byte"],
+  ["secondary_pump", 0x0484, "byte"],
+
+  ["hkl_level", 0x2006, "int16", 0.1],
+  ["hkl_slope", 0x2007, "int16", 0.1],
+  ["hysteresis", 0x6007, "int16", 0.1], # also as 0x7203, but not sent by Vitoconnect
+
+  ["buffer_temperature", 0x01CB, "int16", 0.1], # 3 bytes (sensor temp. w/ status), 2 bytes as 0x010B, but not sent by Vitoconnect
+
+  ["primary_circuit_flow_temperature", 0xb400, "int16", 0.1], # 3 bytes (sensor temp. w/ status), 2 bytes as 0x0103, but not sent by Vitoconnect
+  ["secondary_circuit_flow_temperature", 0xb402, "int16", 0.1], # 3 bytes (sensor temp. w/ status), 2 bytes as 0x0105, but not sent by Vitoconnect
+  ["return_temperature", 0x01c6, "int16", 0.1], # 3 bytes (sensor temp. w/ status), 2 bytes as 0x0106, but not sent by Vitoconnect
+
+  ["3way_valve_position", 0x0494, "byte"],
+
+  ["suction_gas_temperature", 0xb409, "int16", 0.1],
+  ["suction_gas_pressure", 0xb410, "int16", 0.1],
+  ["hot_gas_temperature", 0xb40a, "int16", 0.1],
+  ["hot_gas_pressure", 0xb411, "int16", 0.1],
+  ["liquid_gas_temperature", 0xb404, "int16", 0.1],
+  ["condensation_temperature", 0xb408, "int16", 0.1],
+  ["evaporation_temperature", 0xb407, "int16", 0.1],
+  ["compressor_power", 0xb423, "uint8"],
+  ["ecv_position", 0xb424, "uint8"],
+
+  ["dhw_temperature_storage", 0x01CD, "int16", 0.1], # 3 bytes (sensor temp. w/ status), 2 bytes as 0x010D, but not sent by Vitoconnect
+  ["dhw_temperature_setpoint", 0x6000, "int16", 0.1],
+  ["dhw_temperature_setpoint2", 0x600C, "int16", 0.1],
+  ["dhw_circulation_pump", 0x0490, "byte"],
+
+  #["room_temperature_setpoint_actual", 0x0116, "int16", 0.1],
+  #["room_temperature_setpoint_set", 0x011B, "int16", 0.1],
+  ["room_temperature_setpoint_normal", 0x2000, "int16", 0.1],
+  ["room_temperature_setpoint_reduced", 0x2001, "int16", 0.1],
+  ["room_temperature_setpoint_party", 0x2022, "int16", 0.1],
+
+  ["compressor_phase", 0x0E1A, "byte"], # V1AppState, undocumented 0x130B is used by Vitoconnect
+  ["compressor_starts", 0x0500, "int32"],
+  ["compressor_operating_hours", 0x0580, "uint32", 0.0002777777777777778],
+  ["compressor_heating_power", 0x16A0, "uint"],
+  ["compressor_power_consumption", 0x16A4, "uint"],
+
+  ["one_time_dhw", 0xB020, "byte"],
+
+  ["energy_balance_factor", 0x163F, "int8"],
+  ["energy_balance_heating", 0x1640, "uint32"],
+  ["energy_balance_dhw", 0x1650, "uint32"],
+  ["energy_balance_heating_electric", 0x1660, "uint32"],
+  ["energy_balance_dhw_electric", 0x1670, "uint32"],
+
+  ["annual_performance_factor", 0x1680, "int8", 0.1],
+  ["annual_performance_factor_heating", 0x1681, "int8", 0.1],
+  ["annual_performance_factor_dhw", 0x1682, "int8", 0.1],
+
+  ["auxiliary_heater_enable", 0x6014, "byte"],
+  ["electric_heater_enable", 0x6015, "byte"]
+]
+
+# if set (and not empty), the items in this list are polled at the specified intervals
+# note: setting a poll_items list, results in optolink-bridge being started in "intercept" mode
+# if not set, a PassThrough stream will be used to forward the data from the Optolink bus, if set
+# a Transform stream will be used instead, to inject the poll items into the communication
+poll_items = [
+  # [ival, addr, dlen]
+    # ival: the interval in seconds to poll the item
+      # warning: the Optolink serial port is using quite a low baud rate of 4800 bauds / bytes, which
+      # (with parity bits included, and assuming the average packet size) results in about 20-25 packets
+      # that are transmitted via the bus each second. this includes requests and responses, meaning that only
+      # about 10-12 requests can be sent per second before the bus becomes saturated. optolink-bridge will
+      # only inject one poll request per message sent to the Optolink bus, meaning the maximum polling rate of
+      # items is about 5-6 items per second, reducing the Optolink bus throughput in half. thus the intervals
+      # in the poll_items list should be set accordingly. say you have 10 items that you each want to poll every
+      # second, the polling queue will become over saturated quickly and a warning will be logged to console
+    # addr: the address to poll
+    # dlen: the length of data to poll, note that your heating device will likely respond with a NAK / ERR, in
+      # in case the length of the data is not specified as the address / data type defines it
+  [15, 0xb408, 3], # condensation_temperature
+  [15, 0xb407, 3]  # evaporation_temperature
+]
+
+# the format to publish raw / byte / buffer data, defaults to "hex", one of:
+#   "id" or  "identity" (publish binary data to MQTT)
+#   "hex" or "hex_upper" (lower/upper case hex string)
+#   "0x" or "0x_upper" (lower/upper case hex string with 0x prefix)
+#   "base64" (base64 encoded string)
+buffer_format = "hex"
+# the maximum number of decimals to round to on publish, defaults to 4
+max_decimals = 4
+
+# automatically reload data points and poll items from this configuration file if file changes are detected,
+# without (!) interrupting the active Vitoconnect / Optolink communication, defaults to true
+# note: this setting only affects reloading data points and poll list items, other changes might not be picked up
+# also poll_items will only refresh, in case the list was populated, when you started optolink-bridge
+# in case you add a item to the (previously empty) poll_items list, you will need to restart optolink-bridge
+# (this is because if poll_items is empty, optolink-bridge will start in pass-through mode and is not able to intercept messages)
+auto_reload_addr_items = true
+
+[mqtt]
+
+# broker protocol / host / port
+url = "mqtt://127.0.0.1:1883"
+# broker username
+username = "user"
+# broker password
+password = "password"
+# base topic to publish attributes to, defaults to "Vito"
+# e.g.: Vito/<dpname>
+topic = "Vito"
+# suffix to append to the topic, defaults to <dpname>
+# allowed wildcards are <addr> (or <dpaddr> as alias) and <dpname>
+suffix = "<dpname>"
+# retain a "online" topic, e.g. Vito/online, defaults to true / "online", set to a string to use a different topic
+# note: if set to false, home assistant will not be able to determine if the devices / entities are available
+online = true
+
+# publish unknown data points to MQTT as raw data
+publish_unknown_dps = false
+# the suffix to use to publish unknown data points, defaults to "raw/<addr>"
+unknown_dp_suffix = "raw/<addr>"
+
+[mqtt.options]
+# other broker options (see https://github.com/mqttjs/MQTT.js?tab=readme-ov-file#client options)
+#...
+
+[mqtt.device_discovery]
+
+# set to false to disable publishing a device discovery payload
+enabled = true
+
+# the discovery prefix for devices, defaults to "homeassistant"
+prefix = "homeassistant"
+
+# optolink-bridge publishes a single device discovery payload, see:
+# https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload
+
+# by default all data_points will be published as basic sensors, you may use the next section(s) to override specific
+# settings of the discovery payload, for example to set device classes, icons, units, etc., see the home assistant
+# mqtt integration documentation for details. note that all overrides must be specified in their non-abbreviated form
+
+[mqtt.device_discovery.overrides]
+
+[mqtt.device_discovery.overrides.device]
+
+# if not set, serial_number and identifiers default to the UTF8 string representation of 0xF010 (device serial number).
+# in case no identifiers are set and no serial_number is sent by Vitoconnect, no device discovery payload will be published!
+
+# identifiers = "any_identifier_defaults_to_serial_number"
+# serial_number = "device_serial_number"
+# name = "Vito"
+# model = "Vito"
+# manufacturer = "Viessmann"
+
+# the following override sections will override the default sensor and binary_sensor entity attributes, as listed here:
+# https://www.home-assistant.io/integrations/sensor.mqtt/ and https://www.home-assistant.io/integrations/binary_sensor.mqtt/
+# by default optolink-bridge publishes all data_points as sensors. in case you do not wish to publish a specific data_point,
+# you may set its entry in the overrides section to false, e.g.: some_data_point = false
+[mqtt.device_discovery.overrides.sensor]
+
+outside_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1, icon = "mdi:thermometer" }
+averaged_outside_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1, icon = "mdi:thermometer" }
+averaging_time_outside_temperature = { device_class = "duration", unit_of_measurement = "min" }
+
+operating_mode = { icon = "mdi:cog", value_template = """
+{% set mapping = ({
+  '00': 'Shutdown',
+  '01': 'Hot Water Only',
+  '02': 'Heating and Hot Water',
+  '03': 'Mode 3',
+  '04': 'Continuously Reduced',
+  '05': 'Continuously Normal',
+  '06': 'Normal Shutdown',
+  '07': 'Cooling Only'
+}) %}
+{{ mapping[value] | default('Unknown') }}""" }
+
+hkl_level = { state_class = "measurement", icon = "mdi:chart-line" }
+hkl_slope = { state_class = "measurement", icon = "mdi:chart-line" }
+hysteresis = { device_class = "temperature", unit_of_measurement = "K", icon = "mdi:thermometer-lines" }
+
+buffer_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+primary_circuit_flow_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+secondary_circuit_flow_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+return_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+
+"3way_valve_position" = { unit_of_measurement = "%", suggested_display_precision = 0, icon = "mdi:valve", value_template = "{{ value | float * 100 }}" }
+
+suction_gas_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+suction_gas_pressure = { device_class = "pressure", unit_of_measurement = "bar", suggested_display_precision = 1 }
+hot_gas_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+hot_gas_pressure = { device_class = "pressure", unit_of_measurement = "bar", suggested_display_precision = 1 }
+liquid_gas_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+condensation_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+evaporation_temperature = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+compressor_power = { unit_of_measurement = "%", suggested_display_precision = 0, icon = "mdi:heat-pump", value_template = "{{ value | int }}" }
+ecv_position = { unit_of_measurement = "%", suggested_display_precision = 0, icon = "mdi:valve", value_template = "{{ value | int }}" }
+
+dhw_temperature_storage = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+dhw_temperature_setpoint = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+dhw_temperature_setpoint2 = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+
+room_temperature_setpoint_normal = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+room_temperature_setpoint_reduced = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+room_temperature_setpoint_party = { device_class = "temperature", unit_of_measurement = "°C", suggested_display_precision = 1 }
+
+compressor_phase = { icon = "mdi:information", value_template = """
+{% set mapping = ({
+  '00': 'Off',
+  '01': 'Cooling',
+  '02': 'Heating',
+  '03': 'Error',
+  '04': 'Switching to Cooling',
+  '05': 'Defrosting',
+  '06': 'Waiting',
+  '07': 'Standby',
+  '08': 'Switching to Heating',
+  '09': 'Stopping',
+  '0A': 'Manual Operation',
+  '0B': 'Starting',
+  '0C': 'Utility Lock',
+  '0D': 'Pre-Start',
+  '0E': 'Post-Stop',
+  '0F': 'Blocked',
+  '10': 'Pump-Down',
+  '11': 'PD -> Comp. start',
+  '12': 'PD -> pressure reached',
+  '13': 'PD -> shutdown'
+}) %}
+{{ mapping[value[:2]] | default('Unknown') }}""" }
+
+compressor_starts = { unit_of_measurement = "cycles", state_class = "total_increasing", icon = "mdi:restart" }
+compressor_operating_hours = { device_class = "duration", unit_of_measurement = "h", state_class = "total_increasing", icon = "mdi:fan-clock" }
+compressor_heating_power = { device_class = "power", unit_of_measurement = "W" }
+compressor_power_consumption = { device_class = "power", unit_of_measurement = "W" }
+
+annual_performance_factor = { state_class = "measurement", icon = "mdi:chart-line", value_template = "{{ value | float | round(2) }}" }
+annual_performance_factor_heating = { state_class = "measurement", icon = "mdi:chart-line", value_template = "{{ value | float | round(2) }}" }
+annual_performance_factor_dhw = { state_class = "measurement", icon = "mdi:chart-line", value_template = "{{ value | float | round(2) }}" }
+
+energy_balance_factor = { device_class = "power_factor", state_class = "measurement", value_template = "{{ (value | float / 10) | round(2) }}" }
+energy_balance_heating = { device_class = "energy", unit_of_measurement = "kWh", state_class = "total_increasing", icon = "mdi:fire", value_template = "{{ (value | float * states('sensor.energy_balance_factor') | float) | round(2) }}" }
+energy_balance_dhw = { device_class = "energy", unit_of_measurement = "kWh", state_class = "total_increasing", icon = "mdi:water", value_template = "{{ (value | float * states('sensor.energy_balance_factor') | float) | round(2) }}" }
+energy_balance_heating_electric = { device_class = "energy", unit_of_measurement = "kWh", state_class = "total_increasing", icon = "mdi:flash", value_template = "{{ (value | float * states('sensor.energy_balance_factor') | float) | round(2) }}" }
+energy_balance_dhw_electric = { device_class = "energy", unit_of_measurement = "kWh", state_class = "total_increasing", icon = "mdi:flash", value_template = "{{ (value | float * states('sensor.energy_balance_factor') | float) | round(2) }}" }
+
+# by default optolink-bridge publishes all data_points as sensors, in case you want to publish specific data_points as
+# binary sensors, you may specify them in the next section. in case you do not want to change any attribute of the
+# binary sensor, you may just specify the data point name with a value of true, e.g.: heating_circuit_circulation_pump = true
+[mqtt.device_discovery.overrides.binary_sensor]
+
+heating_circuit_circulation_pump = { payload_on = "01", payload_off = "00", device_class = "running", icon = "mdi:pump" }
+secondary_pump = { payload_on = "01", payload_off = "00", device_class = "running", icon = "mdi:pump" }
+dhw_circulation_pump = { payload_on = "01", payload_off = "00", device_class = "running", icon = "mdi:pump" }
+one_time_dhw = { payload_on = "02", payload_off = "00", device_class = "heat", icon = "mdi:water-thermometer" }
+auxiliary_heater_enable = { payload_on = "01", payload_off = "00", device_class = "running", icon = "mdi:heating-coil" }
+electric_heater_enable = { payload_on = "01", payload_off = "00", device_class = "running", icon = "mdi:heating-coil" }

package/discovery.js

@@ -0,0 +1,74 @@
+import packageJson from './package.json' with { type: 'json' };
+import { capitalCase } from 'change-case';
+
+export async function publishDevice({
+  mqttClient, mqttAvailabilityTopic, mqttDpTopic,
+  deviceSerialNo, prefix = 'homeassistant', dps, overrides = {}
+}) {
+  if (!deviceSerialNo) {
+    throw new TypeError('Device serial number must be provided');
+  }
+
+  function discoveryComponent(dp) {
+    const unique_id = `vito_${deviceSerialNo}_${dp.name}`;
+
+    // check if there are any overrides for this data point
+    let platform = 'sensor', override;
+    for (const overridePlatform of Object.keys(overrides)) {
+      if (overridePlatform === 'device') { continue; }
+      if (override = overrides[overridePlatform]?.[dp.name]) {
+        platform = overridePlatform; // the override determines the platform of the data point
+        break;
+      }
+    }
+
+    if (override === false) {
+      return {}; // do not include this data point in device discovery
+    } else if (override === true) {
+      override = {}; // include this data point with default settings in the specified platform
+    }
+
+    return {
+      [unique_id]: {
+        platform,
+
+        unique_id,
+        name: capitalCase(dp.name), // will automatically get prefixed with the device name
+        state_topic: mqttDpTopic(dp),
+
+        ...(override ?? {})
+      }
+    };
+  }
+
+  // build the discovery record
+  const discoveryPayload = {
+    device: {
+      identifiers: deviceSerialNo,
+      serial_number: deviceSerialNo,
+      name: 'Vito', model: `Vito`,
+      manufacturer: 'Viessmann',
+      ...(overrides?.device ?? {})
+    },
+    origin: { // see https://www.home-assistant.io/integrations/mqtt/#adding-information-about-the-origin-of-a-discovery-message
+      name: 'optolink-bridge',
+      sw_version: packageJson.version,
+      support_url: 'https://github.com/kristian/optolink-bridge/issues'
+    },
+    ...(mqttAvailabilityTopic ? {
+      availability: [ // see https://www.home-assistant.io/integrations/mqtt/#using-availability-topics
+        {
+          topic: mqttAvailabilityTopic,
+          payload_available: 'true',
+          payload_not_available: 'false',
+        }
+      ]
+    } : {}),
+    components: Object.assign({}, ...[...(dps?.values() ?? [])].map(discoveryComponent))
+  };
+
+  // publish to device discovery topic, see: https://www.home-assistant.io/integrations/mqtt/#discovery-messages
+  // config messages are retained, see: https://www.home-assistant.io/integrations/mqtt/#using-retained-config-messages
+  await mqttClient.publishAsync(`${prefix ?? 'homeassistant'}/device/vito_${deviceSerialNo}/config`,
+    JSON.stringify(discoveryPayload), { retain: true });
+}