mqtt-homie-homeassistant 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea47bfb9fc5d373702f2edf0bd746412d12cd884132d87f098fdd29a5b552b51
+  data.tar.gz: a229e5225e2a77daadb9caca7edb547da464211dc0f66aa3840429015970e39a
+SHA512:
+  metadata.gz: b4df1f4dff3da9e5becc45c539720383b7f0f9fed40125412a03b668b5048fff2a9206a01f831f140e986c0a5844d4ae016b5586228ae0d4b1a1710dd49097b9
+  data.tar.gz: 73d1824ec2f29d95414368a1fbbc360c0a250ce54e0a0fecfc93c2c4dd1d2086fcca7f71c2c7b3e33e545c331d69d31da237ff1a8ec15b3f0b0d548218175e5b

data/lib/mqtt/homie/home_assistant/device.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Homie
+    module HomeAssistant
+      module Device
+        def self.included(klass)
+          super
+          klass.attr_accessor :home_assistant_device, :home_assistant_discovery_prefix
+        end
+
+        # @!visibility private
+        def base_hass_config(config)
+          config[:availability] = [{
+            topic: "#{topic}/$state",
+            payload_available: "ready",
+            payload_not_available: "lost"
+          }]
+          config[:device] ||= {}
+          config[:device][:name] ||= name
+          config[:device][:identifiers] ||= id
+          config[:device][:sw_version] ||= MQTT::Homie::Device::VERSION
+          config[:node_id] = id
+          config[:qos] = 1
+        end
+      end
+    end
+    Device.include(HomeAssistant::Device)
+  end
+end

data/lib/mqtt/homie/home_assistant/node.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Homie
+    module HomeAssistant
+      module Node
+        def hass_climate(action_property: nil,
+                         current_humidity_property: nil,
+                         current_temperature_property: nil,
+                         fan_mode_property: nil,
+                         mode_property: nil,
+                         power_property: nil,
+                         preset_mode_property: nil,
+                         swing_mode_property: nil,
+                         target_humidity_property: nil,
+                         temperature_property: nil,
+                         temperature_high_property: nil,
+                         temperature_low_property: nil,
+                         **kwargs)
+          if power_property && power_property.datatype != :boolean
+            raise ArgumentError, "Power property must be a boolean"
+          end
+
+          temperature_property = resolve_property(temperature_property)
+          temperature_high_property = resolve_property(temperature_high_property)
+          temperature_low_property = resolve_property(temperature_low_property)
+          temp_properties = [
+            temperature_property,
+            temperature_high_property,
+            temperature_low_property
+          ].compact
+          unless (temp_ranges = temp_properties.map(&:range).compact).empty?
+            min = temp_ranges.map(&:begin).min
+            max = temp_ranges.map(&:end).max
+            kwargs[:temp_range] = min..max
+          end
+          kwargs[:temperature_unit] = temp_properties.map(&:unit).compact.first
+          if power_property
+            kwargs[:payload_off] = "false"
+            kwargs[:payload_on] = "true"
+          end
+
+          hass_property(kwargs, action_property, :action, read_only: true)
+          hass_property(kwargs, current_humidity_property, :current_humidity, read_only: true)
+          hass_property(kwargs, current_temperature_property, :current_temperature, read_only: true)
+          hass_enum(kwargs, fan_mode_property, :fan_mode)
+          hass_enum(kwargs, mode_property, :mode, MQTT::HomeAssistant::DEFAULTS[:climate][:modes])
+          hass_property(kwargs, power_property, :power)
+          hass_enum(kwargs, preset_mode_property, :preset_mode)
+          hass_enum(kwargs, swing_mode_property, :swing_mode)
+          hass_property(kwargs, target_humidity_property, :target_humidity)
+          hass_property(kwargs, temperature_property, :temperature)
+          hass_property(kwargs, temperature_high_property, :temperature_high)
+          hass_property(kwargs, temperature_low_property, :temperature_low)
+          publish_hass_component(platform: :climate, **kwargs)
+        end
+
+        def hass_fan(property,
+                     oscillation_property: nil,
+                     preset_mode_property: nil,
+                     **kwargs)
+          hass_property(kwargs, property)
+          hass_property(kwargs, oscillation_property, :oscillation)
+          hass_enum(kwargs, preset_mode_property, :preset_mode)
+          publish_hass_component(platform: :fan, **kwargs)
+        end
+
+        def hass_humidifier(property,
+                            target_humidity_property: nil,
+                            mode_property: nil,
+                            **kwargs)
+          hass_property(kwargs, property)
+          hass_property(kwargs, target_humidity_property, :target_humidity)
+          hass_property(kwargs, mode_property, :mode)
+          publish_hass_component(platform: :humidifier,
+                                 payload_off: "false",
+                                 payload_on: "true",
+                                 **kwargs)
+        end
+
+        def hass_light(property = nil,
+                       brightness_property: nil,
+                       color_mode_property: nil,
+                       color_temp_property: nil,
+                       effect_property: nil,
+                       hs_property: nil,
+                       rgb_property: nil,
+                       white_property: nil,
+                       xy_property: nil,
+                       **kwargs)
+          # automatically infer a brightness-only light and adjust config
+          if brightness_property && property.nil?
+            property = brightness_property
+            kwargs[:on_command_type] = :brightness
+          end
+          case property.datatype
+          when :boolean
+            kwargs[:payload_off] = "false"
+            kwargs[:payload_on] = "true"
+          when :integer
+            kwargs[:payload_off] = "0"
+          when :float
+            kwargs[:payload_off] = "0.0"
+          end
+          kwargs[:brightness_scale] = brightness_property.range.end if brightness_property&.range
+          kwargs[:effect_list] = effect_property.range if effect_property&.datatype == :enum
+          kwargs[:mireds_range] = color_temp_property.range if color_temp_property.unit == "mired"
+          kwargs[:white_scale] = white_property.range.end if white_property&.range
+
+          hass_property(kwargs, property)
+          hass_property(kwargs, brightness_property, :brightness)
+          hass_property(kwargs, color_mode_property, :color_mode)
+          hass_property(kwargs, color_temp_property, :color_temp)
+          hass_property(kwargs, effect_property, :effect)
+          hass_property(kwargs, hs_property, :hs)
+          hass_property(kwargs, rgb_property, :rgb)
+          hass_property(kwargs, white_property, :white)
+          hass_property(kwargs, xy_property, :xy)
+          publish_hass_component(platform: :light, **kwargs)
+        end
+
+        def hass_water_heater(
+          current_temperature_property: nil,
+          mode_property: nil,
+          power_property: nil,
+          temperature_property: nil,
+          **kwargs)
+          temperature_property = resolve_property(temperature_property)
+          current_temperature_property = resolve_property(current_temperature_property)
+          temp_properties = [
+            temperature_property,
+            current_temperature_property
+          ].compact
+          kwargs[:range] = temperature_property&.range
+          kwargs[:temperature_unit] = temp_properties.map(&:unit).compact.first
+          if power_property
+            kwargs[:payload_off] = "false"
+            kwargs[:payload_on] = "true"
+          end
+          hass_property(kwargs, current_temperature_property, :current_temperature, read_only: true)
+          hass_enum(kwargs, mode_property, :mode, MQTT::HomeAssistant::DEFAULTS[:water_heater][:modes])
+          hass_property(kwargs, power_property, :power)
+          hass_property(kwargs, temperature_property, :temperature)
+          publish_hass_component(platform: :water_heater, **kwargs)
+        end
+
+        def publish
+          super.tap do
+            @pending_hass_registrations&.each do |(object_id, kwargs)|
+              device.mqtt.publish_hass_component(object_id, **kwargs)
+            end
+            @pending_hass_registrations = nil
+          end
+        end
+
+        private
+
+        def resolve_property(property)
+          return if property.nil?
+
+          orig_property = property
+          property = self[property] if property.is_a?(String)
+          raise ArgumentError, "Unknown property #{orig_property}" if property.nil?
+
+          property
+        end
+
+        def hass_property(config, property, prefix = nil, read_only: false, templates: {})
+          resolve_property(property)&.hass_property(config, prefix, read_only: read_only, templates: templates)
+        end
+
+        def hass_enum(config, property, prefix = nil, valid_set = nil)
+          return if property.nil?
+
+          property = resolve_property(property)
+          hass_property(config, property, prefix)
+
+          return unless property.datatype == :enum
+
+          values = property.range
+          values &= valid_set if valid_set
+          config[:"#{prefix}s"] = values
+        end
+
+        def publish_hass_component(device: nil, discovery_prefix: nil, object_id: nil, **kwargs)
+          discovery_prefix ||= self.device.home_assistant_discovery_prefix
+          device = self.device.home_assistant_device.merge(device || {}) if self.device.home_assistant_device
+
+          object_id ||= id
+          kwargs[:name] ||= name
+          kwargs[:device] = device
+          kwargs[:discovery_prefix] ||= discovery_prefix
+          kwargs[:unique_id] ||= "#{self.device.id}_#{object_id}"
+          self.device.base_hass_config(kwargs)
+          if published?
+            self.device.mqtt.publish_hass_component(object_id, **kwargs)
+          else
+            pending_hass_registrations << [object_id, kwargs]
+          end
+        end
+
+        def pending_hass_registrations
+          @pending_hass_registrations ||= []
+        end
+      end
+    end
+    Node.prepend(HomeAssistant::Node)
+  end
+end

data/lib/mqtt/homie/home_assistant/property.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Homie
+    module HomeAssistant
+      module Property
+        def initialize(*args, hass: nil, **kwargs)
+          super(*args, **kwargs)
+
+          return unless hass
+
+          case hass
+          when Symbol
+            public_send("hass_#{hass}")
+          when Hash
+            raise ArgumentError, "hass must only contain one item" unless hass.length == 1
+
+            public_send("hass_#{hass.first.first}", **hass.first.last)
+          else
+            raise ArgumentError, "hass must be a Symbol or a Hash of HASS device type to additional HASS options"
+          end
+        end
+
+        def hass_binary_sensor(**kwargs)
+          raise ArgumentError, "Property must be a boolean" unless datatype == :boolean
+          raise ArgumentError, "Property must not be settable" if settable?
+
+          hass_property(kwargs)
+          publish_hass_component(platform: :binary_sensor,
+                                 payload_off: "false",
+                                 payload_on: "true",
+                                 **kwargs)
+        end
+
+        def hass_fan(**kwargs)
+          raise ArgumentError, "Property must be a boolean" unless datatype == :boolean
+          raise ArgumentError, "Property must be settable" unless settable?
+
+          hass_property(kwargs)
+          publish_hass_component(platform: :fan,
+                                 payload_off: "false",
+                                 payload_on: "true",
+                                 **kwargs)
+        end
+
+        def hass_light(**kwargs)
+          case datatype
+          when :boolean
+            kwargs[:payload_off] = "false"
+            kwargs[:payload_on] = "true"
+          when :integer
+            kwargs[:payload_off] = "0"
+          when :float
+            kwargs[:payload_off] = "0.0"
+          end
+
+          hass_property(kwargs)
+          publish_hass_component(platform: :light, **kwargs)
+        end
+
+        def hass_number(**kwargs)
+          raise ArgumentError, "Property must be an integer or a float" unless %i[integer float].include?(datatype)
+
+          hass_property(kwargs)
+          kwargs[:range] = range if range
+          kwargs[:unit_of_measurement] = unit if unit
+
+          publish_hass_component(platform: :number, **kwargs)
+        end
+
+        def hass_scene(**kwargs)
+          unless datatype == :enum && range.length == 1
+            raise ArgumentError, "Property must be an enum with a single value"
+          end
+          raise ArgumentError, "Property must be settable" unless settable?
+
+          publish_hass_component(platform: :scene,
+                                 command_topic: "#{topic}/set",
+                                 payload_on: range.first,
+                                 **kwargs)
+        end
+
+        def hass_select(**kwargs)
+          raise ArgumentError, "Property must be an enum" unless datatype == :enum
+          raise ArgumentError, "Property must be settable" unless settable?
+
+          hass_property(kwargs)
+          publish_hass_component(platform: :select, options: range, **kwargs)
+        end
+
+        def hass_sensor(**kwargs)
+          if datatype == :enum
+            kwargs[:device_class] = :enum
+            kwargs[:options] = range
+          end
+
+          publish_hass_component(platform: :sensor,
+                                 state_topic: topic,
+                                 **kwargs)
+        end
+
+        def hass_switch(**kwargs)
+          raise ArgumentError, "Property must be a boolean" unless datatype == :boolean
+
+          hass_property(kwargs)
+          publish_hass_component(platform: :switch,
+                                 payload_off: "false",
+                                 payload_on: "true",
+                                 **kwargs)
+        end
+
+        def publish
+          super.tap do
+            @pending_hass_registrations&.each do |(object_id, kwargs)|
+              device.mqtt.publish_hass_component(object_id, **kwargs)
+            end
+            @pending_hass_registrations = nil
+          end
+        end
+
+        # @!visibility private
+        def hass_property(config, prefix = nil, read_only: false, templates: {})
+          prefix = "#{prefix}_" if prefix
+          state_prefix = "state_" unless read_only
+          config[:"#{prefix}#{state_prefix}topic"] = topic if retained?
+          if !read_only && settable?
+            config[:"#{prefix}command_topic"] = "#{topic}/set"
+            config[:"#{prefix}command_template"] = "{{ value | round(0) }}" if datatype == :integer
+          end
+          config.merge!(templates.slice(:"#{prefix}template", :"#{prefix}command_template"))
+        end
+
+        # @!visibility private
+        def hass_enum(config, prefix = nil, valid_set = nil)
+          prefix = "#{prefix}_" if prefix
+
+          return unless datatype == :enum
+
+          modes = range
+          modes &= valid_set if valid_set
+          config[:"#{prefix}modes"] = modes
+        end
+
+        private
+
+        def publish_hass_component(device: nil, discovery_prefix: nil, object_id: nil, **kwargs)
+          discovery_prefix ||= self.device.home_assistant_discovery_prefix
+          device = self.device.home_assistant_device.merge(device || {}) if self.device.home_assistant_device
+
+          object_id ||= "#{node.id}_#{id}"
+          kwargs[:name] ||= "#{node.name} #{name}"
+          kwargs[:device] = device
+          kwargs[:discovery_prefix] ||= discovery_prefix
+          kwargs[:unique_id] ||= "#{self.device.id}_#{object_id}"
+          self.device.base_hass_config(kwargs)
+          if published?
+            self.device.mqtt.publish_hass_component(object_id, **kwargs)
+          else
+            pending_hass_registrations << [object_id, kwargs]
+          end
+        end
+
+        def pending_hass_registrations
+          @pending_hass_registrations ||= []
+        end
+      end
+    end
+    Property.prepend(HomeAssistant::Property)
+  end
+end

data/lib/mqtt/homie/home_assistant/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module MQTT
+  module Homie
+    module HomeAssistant
+      VERSION = "1.0.0"
+    end
+  end
+end

data/lib/mqtt-homie-homeassistant.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "mqtt/home_assistant"
+require "mqtt/homie"
+require "mqtt/homie/home_assistant/device"
+require "mqtt/homie/home_assistant/node"
+require "mqtt/homie/home_assistant/property"

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: mqtt-homie-homeassistant
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cody Cutrer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: homie-mqtt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: mqtt-homeassistant
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description:
+email: cody@cutrer.com'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mqtt-homie-homeassistant.rb
+- lib/mqtt/homie/home_assistant/device.rb
+- lib/mqtt/homie/home_assistant/node.rb
+- lib/mqtt/homie/home_assistant/property.rb
+- lib/mqtt/homie/home_assistant/version.rb
+homepage: https://github.com/ccutrer/ruby-mqtt-homie-homeassistant
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Library for publishing device auto-discovery configuration for Homie devices
+  to Home Assistant as well.
+test_files: []