htcc 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ab75c3a400f4719a86ea5b1757c17dc2e2d4e6366f1aed56adb2da193bcd79b
+  data.tar.gz: f713bf7a5e3fcbab393b17a5fddce1f2211fe6c823ba3a805e14918748e4e635
+SHA512:
+  metadata.gz: 1bea671742650e7cbb022f96175b7161f065b0dccb31aa9dfb2c9a7eff459980b3d261130bca230d27169b8206a788e97346e8e5f33e4a6994575cb74748a768
+  data.tar.gz: '09cc41bed0804b02a6ed2e0a11383afb28bfcdd2831c7588194a33756607935fb75f3f92c197583c4973c3df4940ab1ce5eddd715c5a4cabaff38f297b620f55'

data/htcc.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |s|
+  s.name        = 'htcc'
+  s.version     = '0.1.1'
+  s.summary     = "A Ruby client for the Honeywell Total Connect Comfort API"
+  s.description = "This gem can be used to control Honeywell thermostats that use the Total Connect Comfort platform."
+  s.author      = 'Lee Folkman'
+  s.email       = 'lee.folkman@gmail.com'
+  s.files       = Dir['README.md', 'LICENSE', 'CHANGELOG.md', 'lib/**/*.rb', 'htcc.gemspec']
+  s.homepage    = 'https://github.com/Folkman/htcc'
+  s.license     = 'MIT'
+  s.platform    = Gem::Platform::RUBY
+end

data/lib/htcc.rb

@@ -0,0 +1,4 @@
+require 'htcc/client'
+require 'htcc/thermostat'
+require 'htcc/scheduler'
+require 'htcc/settings'

data/lib/htcc/client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module HTCC
+  class Client
+    BASE_URL = 'https://mytotalconnectcomfort.com/portal'.freeze
+    HEADERS  = { 'X-Requested-With': 'XMLHttpRequest' }.freeze
+
+    attr_reader :devices
+
+    def initialize(username, password, debug: false, debug_output: nil)
+      @debug = debug
+      @debug_output = nil
+      @devices = []
+      login(username, password)
+      get_devices if logged_in?
+    end
+
+    def debug=(val)
+      @debug = val
+    end
+
+    def logged_in?
+      @logged_in
+    end
+
+    def refresh_devices
+      @devices = []
+      get_devices
+    end
+
+    private
+
+    def get_devices
+      resp = request(
+        '/Location/GetLocationListData',
+        method: 'post',
+        data: { 'page' => '1', 'filter' => '' }
+      )
+      locations = ::JSON.parse(resp.body)
+      @devices = locations.flat_map { |loc| loc['Devices'] }
+      @devices.map! do |device|
+        case device['DeviceType']
+        when 24
+          Thermostat.new(device, self)
+        else # Other devices?
+          Thermostat.new(device, self)
+        end
+      end
+    end
+
+    def login(username, password)
+      resp = request(method: 'post', data: {
+        'UserName': username, 'Password': password, 'timeOffset': '240', 'RememberMe': 'false'
+      })
+      @cookies = get_cookies(resp)
+      @logged_in = resp.get_fields('content-length')[0].to_i < 25 # Successful login
+    end
+
+    def get_cookies(response)
+      response.get_fields('set-cookie')
+              .map { |c| cookie = c.split(/;|,/)[0]; cookie.split('=')[1] ? cookie : nil }
+              .compact
+              .join(';')
+    end
+
+    def request(path = '', method: 'get', data: nil, headers: {})
+      uri = URI("#{BASE_URL}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.set_debug_output(@debug_output || $stdout) if @debug
+      klass = method == 'get' ? Net::HTTP::Get : Net::HTTP::Post
+      request = klass.new(uri.request_uri, HEADERS.merge(headers))
+      request['Cookie'] = @cookies if @cookies
+      request.set_form_data(data) if data
+      http.request(request)
+    end
+  end
+end

data/lib/htcc/scheduler.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module HTCC
+  class Scheduler
+    attr_reader :device_id
+
+    def initialize(device_id, client)
+      @device_id = device_id
+      @client = client
+    end
+
+    def get_schedule
+      resp = @client.send(:request, "/Device/Menu/GetScheduleData/#{device_id}", method: 'post')
+      @schedule = JSON.parse(resp.body)
+    end
+  end
+end
+
+# TODO:
+
+# EDIT_SCHEDULE_PATH = '/Device/Menu/EditSchedule/' + device_id
+# CONFIRM_SCHEDULE_PATH = '/Device/Menu/SendSchedule?deviceId=' + device_id
+# DISCARD_SCHEDULE_PATH = '/Device/Menu/DiscardChangesInSchedule?deviceID=' + device_id
+
+# FormData Encoded:
+
+# DeviceID: 123456
+# Days[0]: True
+# Days[1]: True
+# Days[2]: True
+# Days[3]: True
+# Days[4]: True
+# Days[5]: True
+# Days[6]: True
+# DayChange: True
+# Templates[0].Editable: True
+# Templates[0].OrigIsCancelled: false
+# Templates[0].Editable: True
+# Templates[0].Type: WakeOcc1
+# Templates[0].OrigStartTime: 05:45:00
+# Templates[0].OrigFanMode: Auto
+# Templates[0].OrigHeatSetpoint: 68
+# Templates[0].OrigCoolSetpoint: 79
+# Templates[0].StartTime: 05:45:00
+# Templates[0].IsCancelled: false
+# Templates[1].Editable: True
+# Templates[1].OrigIsCancelled: true
+# Templates[1].Editable: True
+# Templates[1].Type: LeaveUnocc1
+# Templates[1].OrigStartTime: 08:00:00
+# Templates[1].OrigFanMode: Auto
+# Templates[1].OrigHeatSetpoint: 62
+# Templates[1].OrigCoolSetpoint: 85
+# Templates[1].StartTime: 08:00:00
+# Templates[1].IsCancelled: true
+# Templates[2].Editable: True
+# Templates[2].OrigIsCancelled: true
+# Templates[2].Editable: True
+# Templates[2].Type: ReturnOcc2
+# Templates[2].OrigStartTime: 18:00:00
+# Templates[2].OrigFanMode: Auto
+# Templates[2].OrigHeatSetpoint: 70
+# Templates[2].OrigCoolSetpoint: 78
+# Templates[2].StartTime: 18:00:00
+# Templates[2].IsCancelled: true
+# Templates[3].Editable: True
+# Templates[3].OrigIsCancelled: false
+# Templates[3].Editable: True
+# Templates[3].Type: SleepUnocc2
+# Templates[3].OrigStartTime: 21:30:00
+# Templates[3].OrigFanMode: Auto
+# Templates[3].OrigHeatSetpoint: 64
+# Templates[3].OrigCoolSetpoint: 78
+# Templates[3].StartTime: 21:30:00
+# Templates[3].IsCancelled: false
+# Templates[0].Type: WakeOcc1
+# Templates[0].HeatSetpoint: 68
+# Templates[0].CoolSetpoint: 79
+# Templates[1].Type: LeaveUnocc1
+# Templates[1].HeatSetpoint: 62
+# Templates[1].CoolSetpoint: 85
+# Templates[2].Type: ReturnOcc2
+# Templates[2].HeatSetpoint: 70
+# Templates[2].CoolSetpoint: 78
+# Templates[3].Type: SleepUnocc2
+# Templates[3].HeatSetpoint: 64
+# Templates[3].CoolSetpoint: 78
+# DisplayUnits: Fahrenheit
+# IsCommercial: False
+# ScheduleFan: True
+# Templates[0].FanMode: Auto
+# Templates[1].FanMode: Auto
+# Templates[2].FanMode: Auto
+# Templates[3].FanMode: Auto
+# ScheduleOtherDays: False

data/lib/htcc/settings.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module HTCC
+  class Settings
+    attr_reader :device_id
+
+    def initialize(device_id, client)
+      @device_id = device_id
+      @client = client
+    end
+
+    def update(payload)
+      resp = @client.send(:request, '/Device/Menu/Settings', method: 'post', data: payload)
+      JSON.parse(resp.body)
+    end
+  end
+end
+
+# TODO:
+
+# Payload that can be posted to '/Device/Menu/Settings'
+# {
+#   "Name":"THERMOSTAT",
+#   "ApplySettingsToAllZones":false,
+#   "DeviceID":123456,
+#   "DisplayUnits":1,
+#   "TempHigherThanActive":true,
+#   "TempHigherThan":85,
+#   "TempHigherThanMinutes":15,
+#   "TempLowerThanActive":true,
+#   "TempLowerThan":55,
+#   "TempLowerThanMinutes":15,
+#   "HumidityHigherThanActive":null,
+#   "HumidityHigherThan":null,
+#   "HumidityHigherThanMinutes":null,
+#   "HumidityLowerThanActive":null,
+#   "HumidityLowerThan":null,
+#   "HumidityLowerThanMinutes":null,
+#   "FaultConditionExistsActive":false,
+#   "FaultConditionExistsHours":1,
+#   "NormalConditionsActive":true,
+#   "ThermostatAlertActive":null,
+#   "CommunicationFailureActive":true,
+#   "CommunicationFailureMinutes":15,
+#   "CommunicationLostActive":true,
+#   "CommunicationLostHours":1,
+#   "DeviceLostActive":null,
+#   "DeviceLostHours":null,
+#   "TempHigherThanValue":"85°",
+#   "TempLowerThanValue":"55°",
+#   "HumidityHigherThanValue":"--%",
+#   "HumidityLowerThanValue":"--%",
+#   "TempHigherThanMinutesText":"For 15 Minutes",
+#   "TempLowerThanMinutesText":"For 15 Minutes",
+#   "HumidityHigherThanMinutesText":"For 0 Minutes",
+#   "HumidityLowerThanMinutesText":"For 0 Minutes",
+#   "FaultConditionExistsHoursText":"Every 1 Hour",
+#   "CommunicationFailureMinutesText":"For 15 Minutes",
+#   "CommunicationLostHoursText":"After 1 Hour",
+#   "DeviceLostHoursText":"After 1 Hour"
+# }

data/lib/htcc/thermostat.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module HTCC
+  class Thermostat
+    SYSTEM_MODES = %i[emergency_heat heat off cool auto]
+    FAN_MODES = %i[auto on circulate schedule]
+    HOLD_TYPES = %i[none temporary permanent]
+    EQUIPMENT_OUTPUT_STATUS = %i[off heating cooling fan_running]
+
+    attr_reader :info
+
+    def initialize(info, client)
+      @info = info
+      @client = client
+      @refresh = true
+      @status = {}
+    end
+
+    def Scheduler
+      @scheduler ||= Scheduler.new(id, @client)
+    end
+
+    def Settings
+      @settings ||= Settings.new(id, @client)
+    end
+
+    def id
+      @info['DeviceID']
+    end
+
+    def mac_address
+      @info['MacID']
+    end
+
+    def name
+      @info['Name']
+    end
+
+    def connected?
+      get_status
+      @status['deviceLive'] && !@status['communicationLost']
+    end
+
+    def status(refresh = false)
+      get_status if @status.empty? || refresh
+      @status
+    end
+
+    def system_mode
+      get_status
+      SYSTEM_MODES[@status['latestData']['uiData']['SystemSwitchPosition']]
+    end
+
+    def system_mode=(mode)
+      unless system_modes.index(mode)
+        raise SystemError.new("Unknown mode: #{mode.inspect}. Allowed modes: #{system_modes.inspect}")
+      end
+      change_setting(system_mode: mode)
+    end
+
+    def has_fan?
+      return @has_fan unless @has_fan.nil?
+
+      get_status if @status.empty?
+      @has_fan = @status['latestData']['hasFan']
+    end
+
+    def fan_running?
+      get_status
+      @status['latestData']['fanData']['fanIsRunning']
+    end
+
+    def fan_mode
+      get_status
+      FAN_MODES[@status['latestData']['fanData']['fanMode']]
+    end
+
+    def fan_mode=(mode)
+      unless fan_modes.index(mode)
+        raise FanError.new("Unknown mode: #{mode.inspect}. Allowed modes: #{fan_modes.inspect}")
+      end
+      change_setting(fan_mode: mode)
+    end
+
+    # Current ambient temperature
+    def current_temperature
+      get_status
+      @status['latestData']['uiData']['DispTemperature']
+    end
+
+    def temperature_unit
+      get_status
+      @status['latestData']['uiData']['DisplayUnits']
+    end
+
+    # Cooling temperature setting
+    def cool_setpoint
+      get_status
+      @status['latestData']['uiData']['CoolSetpoint']
+    end
+
+    def cool_setpoint=(temp)
+      raise_min_setpoint(min_cool_setpoint, temp) if temp < min_cool_setpoint
+      raise_max_setpoint(max_cool_setpoint, temp) if temp > max_cool_setpoint
+      change_setting(cool_setpoint: temp, hold: :temporary)
+    end
+
+    # Heating temperature setting
+    def heat_setpoint
+      get_status
+      @status['latestData']['uiData']['HeatSetpoint']
+    end
+
+    def heat_setpoint=(temp)
+      raise_min_setpoint(min_heat_setpoint, temp) if temp < min_heat_setpoint
+      raise_max_setpoint(max_heat_setpoint, temp) if temp > max_heat_setpoint
+      change_setting(heat_setpoint: temp, hold: :temporary)
+    end
+
+    def resume_schedule
+      change_setting(hold: :none)
+    end
+
+    def hold
+      get_status
+      HOLD_TYPES[@status['latestData']['uiData']['StatusHeat']] # Both status are the same
+    end
+
+    def hold=(mode)
+      unless HOLD_TYPES.index(mode)
+        raise HoldError.new("Unknown mode: #{mode.inspect}. Allowed modes: #{HOLD_TYPES.inspect}")
+      end
+      change_setting(hold: mode)
+    end
+
+    def output_status
+      get_status
+      status = @status['latestData']['uiData']['EquipmentOutputStatus']
+      status = no_refresh { fan_running? ? 3 : status } if status.zero?
+      EQUIPMENT_OUTPUT_STATUS[@status['latestData']['uiData']['EquipmentOutputStatus']]
+    end
+
+    def system_modes
+      return @system_modes if @system_modes
+
+      get_status if @status.empty?
+      allowed_modes = [
+        @status['latestData']['uiData']['SwitchEmergencyHeatAllowed'],
+        @status['latestData']['uiData']['SwitchHeatAllowed'],
+        @status['latestData']['uiData']['SwitchOffAllowed'],
+        @status['latestData']['uiData']['SwitchCoolAllowed'],
+        @status['latestData']['uiData']['SwitchAutoAllowed'],
+      ]
+      @system_modes = SYSTEM_MODES.select.with_index { |_, i| allowed_modes[i] }
+    end
+
+    def fan_modes
+      return @fan_modes if @fan_modes
+
+      get_status if @status.empty?
+      allowed_modes = [
+        @status['latestData']['fanData']['fanModeAutoAllowed'],
+        @status['latestData']['fanData']['fanModeOnAllowed'],
+        @status['latestData']['fanData']['fanModeCirculateAllowed'],
+        @status['latestData']['fanData']['fanModeFollowScheduleAllowed']
+      ]
+      @fan_modes = FAN_MODES.select.with_index { |_, i| allowed_modes[i] }
+    end
+
+    def no_refresh(&block)
+      @refresh = false
+      result = yield
+      @refresh = true
+      result
+    end
+
+    private
+
+    def get_status
+      return @status unless @refresh || @status.empty?
+
+      resp = @client.send(:request, "/Device/CheckDataSession/#{id}?_=#{Time.now.to_i}")
+      @status = JSON.parse(resp.body)
+    end
+
+    # Required separation between high and low setpoints
+    def deadband
+      return @deadband if @deadband
+
+      get_status if @status.empty?
+      @deadband = @status['latestData']['uiData']['Deadband']
+    end
+
+    def min_cool_setpoint
+      @info['ThermostatData']['MinCoolSetpoint']
+    end
+
+    def max_cool_setpoint
+      @info['ThermostatData']['MaxCoolSetpoint']
+    end
+
+    def min_heat_setpoint
+      @info['ThermostatData']['MinHeatSetpoint']
+    end
+
+    def max_heat_setpoint
+      @info['ThermostatData']['MaxHeatSetpoint']
+    end
+
+    def raise_min_setpoint(min_temp, given_temp)
+      raise TemperatureError.new("Minimum setpoint is #{min_temp}. Given: #{given_temp}")
+    end
+
+    def raise_max_setpoint(max_temp, given_temp)
+      raise TemperatureError.new("Maximum setpoint is #{max_temp}. Given: #{given_temp}")
+    end
+
+    def payload(
+      system_mode: nil,
+      heat_setpoint: nil,
+      cool_setpoint: nil,
+      heat_next_period: nil,
+      cool_next_period: nil,
+      hold: nil,
+      fan_mode: nil
+    )
+      {
+        'DeviceID':       id,
+        'SystemSwitch':   SYSTEM_MODES.index(system_mode),
+        'HeatSetpoint':   heat_setpoint,  
+        'CoolSetpoint':   cool_setpoint,
+        'HeatNextPeriod': heat_next_period, # 0 = hold until 00:00, ..., 92 = hold until 23:45
+        'CoolNextPeriod': cool_next_period, # 0 = hold until 00:00, ..., 92 = hold until 23:45
+        'StatusHeat':     HOLD_TYPES.index(hold),
+        'StatusCool':     HOLD_TYPES.index(hold),
+        'FanMode':        FAN_MODES.index(fan_mode)
+      }
+    end
+
+    def change_setting(**data)
+      resp = @client.send(:request, '/Device/SubmitControlScreenChanges',
+        method: 'post',
+        data: payload(**data)
+      )
+      JSON.parse(resp.body)['success'] == 1
+    end
+
+    class FanError < StandardError; end
+    class HoldError < StandardError; end
+    class SystemError < StandardError; end
+    class TemperatureError < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: htcc
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Lee Folkman
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-03-29 00:00:00.000000000 Z
+dependencies: []
+description: This gem can be used to control Honeywell thermostats that use the Total
+  Connect Comfort platform.
+email: lee.folkman@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- htcc.gemspec
+- lib/htcc.rb
+- lib/htcc/client.rb
+- lib/htcc/scheduler.rb
+- lib/htcc/settings.rb
+- lib/htcc/thermostat.rb
+homepage: https://github.com/Folkman/htcc
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: A Ruby client for the Honeywell Total Connect Comfort API
+test_files: []