A custom component for Home Assistant to integrate with Lennox iComfort S40, S30, E30 or M30 thermostats; supporting local LAN connections and Lennox Cloud Connections depending on the device model. We believe these configurations work - let us know if your experience is different!

Please Note: This component does not support the other models of Lennox Thermostats.

• Home Assistant >= 2023.3.0
• Thermostat linked to a lennoxicomfort.com account or a Thermostat on local LAN with a static/ DHCP leased IP address

• Note: Where we mention S30 in this documentation that also applies to S40, E30 and M30
• If you are having problems with your S40 - please make sure you have software version 04.25.0070 or greater installed. You also may need to shutdown HA and reboot the thermostats in order to establish a connection.
• It is recommended to disable automatic software updates on the Thermostat. This will prevent outages if new versions are not compatible with this integration.
• If using a local connection and you have more than one S30 in your local network, please use a different app_id for each instance (e.g. homeassistant_1, homeassistant_2). If using a Cloud Connection DO NOT change the default app_id.
• If you are running more than 1 Home Assistant communicating to cloud or locally - you MUST use a different app_id for each instance - Detailed Configuration
• WARNING If using the Power Inverter or Diagnostic Sensors - S30 stability problems may arise if your system is connected to the Lennox Cloud. Please review docs/diagnostics.md before using.
• Equipment Parameters - documentation is here docs/parameters.md
• Passwords with special characters are not properly supported by the Lennox Cloud API and may not work. Known special characters that cause issues are & and ^. If your password contains these characters you may need to change it prior to using the integration.
• Adjusting the fan CFM in a single zone system causes some diagnostics to stop updating. Changing the diag_level to 0 and back to 2 solves the issue. A script is available here
• A power outage to the Lennox Controller causes the diag_level to be reset to 0 on reboot. An automation/package is available here to automatically reset.
• If you add new equipment (BLE Sensors), restart HA in order for the integration to pickup the new equipment.

There are several items to consider before starting the install.

• Set the Name for the system. This name will be appended as the prefix for all the entities that get created, so you want something descriptive using only alphanumeric character; but not too long as it'll be in all the entity names. To set this, go into the panel, select settings and look for the Name field.

This image shows the main entities and controls available for the Lennox S30 integration. Specific entity documentation appears later in this document.

This image shows diagnostic data being collected from the RageHouse Lennox S30 system with an Air Handler and Outdoor Compressor

If you like this integration

HACS is recommended as it provides automated install and will notify you when updates are available.

This assumes you have HACS installed and know how to use it. If you need help with this, go to the HACS project documentation.

As of October 2023, this integration is included in the HACS default configuration.

1. Go to releases in this repo and download the latest zip or clone the repo
2. Extract the zip file and copy the custom_components/lennoxs30 folder and all it's contents including the translations subfolder, into the custom_components folder in your HA installation. If upgrading from a prior release, please remove ALL files from this folder.
3. Restart HA.
4. Follow the Configuration Instructions below

Configuration of the integration is done within the Integrations Panel in Home Assistant.

1. Click on Configuration, then Integrations
2. Click Add Integration
3. Search for Lennox S30/E30

The first step is to select a Cloud or a Local connection.

Most, will use the Local Connection. Local connections are faster and more reliable than Cloud Connections. To have this work requires that the S30 has a static IP address (DHCP lease), consult your router documentation for how to configure this.

Why would you use a Cloud Connection? Perhaps you want to monitor your vacation home in the Alps? Or your parent's house?

Need both or have multiple S30s? You are able to run multiple local and multiple cloud connections at the same time. Each is configured using this process.

1. Select Cloud or Local (default) connection

The next step is providing the connection information.

1. Enter the IP address of the S30. Alternatively, you can use a DNS name. If you have firewalls and do port mapping you may specify the port (hostname:port or ip:port) By default the S30 exposes HTTPS on Port 443.
2. You can use the defaults for the rest of the fields, or adjust as needed. See detailed configuration parameters below. Configuration can be changed later when needed. See Detailed Configuration
3. Submit the form

At this point, the integration will attempt to connect to the S30 - this should take no more than 5-10 seconds. If it succeeds, the Advanced Configuration Page will appear. If it is unable to connect errors will be reported and detailed information will be in the Home Assistant log file. Go onto the Advanced Configuration section.

If using a cloud connection. The next step is to specify the connection information.

1. Enter the email address associated with your Lennox iComfort account
2. Enter the password associated with your Lennox iComfort account
3. Use the defaults for the rest of the fields, or adjust as needed. See Detailed Configuration
4. Submit the form

At this point, the integration will attempt to connect to the S30 - this should take no more than 5-15 seconds. If it succeeds, the Advanced Configuration Page will appear. If it is unable to connect errors will be reported and detailed information will be in the Home Assistant log file. Go onto the Advanced Configuration section.

The next page brings up advanced configuration properties with the recommended defaults.

1. Use the defaults (recommended) or adjust using the Detailed Configuration
2. Press submit

At this point, the integration will connect to the S30, download and process its configuration (100kb) and create the Entities in Home Assistant. For local connections, this step typically takes 10-30 seconds complete, for cloud connections it an takes 15-45 seconds. If it is successful, you will be presented with a list of discovered devices. If it fails, review the error and look in the log file for more detailed information.

For Local Connections the Integration instance name is the ip_address / host name. For Cloud Connections the instance name is a redacted version of your email.

If you want to change the integration configuration, do into the integrations page, find the integration and click configure. This will bring up the set of options you can change. After saving, select Reload or Restart HA for the changes to take affect.

The integration detects the unit system configured in Home Assistant and reports the data in the correct units. Celsius is in 0.5 degree increments. Fahrenheit is in 1.0 degrees increments. The Lennox API delivers data in both units, so there is no conversion in the Integration and what you see in the Lennox UI should be what you see in HA.

Samples of useful automations and scripts can be found in the samples/ directory. If you have some you'd like included, open a pull request.

The integration will create a full set of devices representing your HVAC system. Note: depending on your HVAC configuration and the configuration options not all devices may have entities. Please don't delete the unused devices, they will be used as we add more entities in future releases

Cloud - Automatically detects all the zones across the homes and systems in your cloud account. Climate Entities created for each zone. The integration creates internal unique_ids using the Cloud GUID of your S30 plus the zone index (0,1,2,3).

Local - Automatically detects all the zones in the S30 it is connected to. Climate Entities created for each zone. The integration creates internal unique_ids using the Serial Number of your S30 plus the zone index (0,1,2,3).

Entities are attached to the corresponding S30 Device and have default names (which you can change in Home Assistant)

climate.<systemname><zone_name>

System name is the name you gave to your S30. By default Lennox names the Zones - "Zone 1", "Zone 2", "Zone 3", "Zone 4" - this is configurable within the S30.

HVAC_MODE supports off, cool, heat or heat_cool mode. The specific modes available depend on you equipment. For example an AC does not support heat, hence the heat and heat_cool modes will not be available.

FAN_MODE may be set to auto, on, circulate.

Heating and cooling setpoints can be set

Presets are supported. The Preset List is the list of schedules that you have configured in the S30.

When you are running a schedule; changes to the temperature or fan create a temporary schedule override (the Mobile APP does the same thing). The override will automatically end at the end of the Next Period (e.g. at the time of your next schedule period.) To cancel the override, there is a preset called Cancel Hold. Invoking this preset will remove the hold and re-enable the underlying schedule.

Away Mode. The Away preset will put the S30 system into Manual Away Mode. You could also use the manual away mode switch to do this. Works the same as if you pressed the away button on the S30 Panel

Cancel Manual Away Mode or Smart Away Mode. The cancel away mode preset will cancel the active away mode (manual or smart) and return the S30 system to whatever state it was in prior to putting it into away mode. This works the same as if you pressed the cancel away icon on the S30 panel.

Emergency Heat - Lennox systems that have a heat pump and an auxiliary furnace, have an additional HVAC_MODE to run just the auxiliary furnace. In the S30 App this is shown as Emergency Heat. Home Assistant does not allow this mode directly - instead Home Assistant provides support for turning aux_heat on and off - independent of the HVAC_MODE. The integration has the following behavior:

• If Emergency Heat Mode is set in the S30, the HA climate will show Heat and the Aux Heat switch will be on.
• If the HA Aux Switch is turned on, the S30 Heat Mode will be set to Emergency Heat
• If the HA Aux Switch is turned off, the S30 Heat Mode will be set to Heat
• If the Lennox Auxiliary Heat is running, the aux attribute in the HA Climate entity will be set to True and the HA Climate Entity will show Heating

Humidification and Dehumidification

Lennox systems may have humidification and dehumidification capability. If so, you will be able to control the humidity setpoint via the Climate Entity and enable / disable humidification/dehumidification via the humidity mode select entity. Lennox has separate setpoints for humidification (husp) and dehumidification (desp); however Home Assistant only support one humidity setpoint. Hence, the Target Humidity shown in Thermostat is based on the active humidity mode. If no humidity mode is active for the zone, the Target Humidity will be unavailable.

The integration provides all of the standard climate attributes, including

1. Temperature
2. Humidity
3. Current HVAC action
4. Active setpoints - dependent on the HVAC_MODE. For example, in Cool Mode the Cool Setpoint is shown, but not the Heat Setpoint.
5. Active Preset

In addition the following extra attributes are provided, to allow for a more detailed information on the current zone operation.

These entities is automatically created for each integration instance and can be used to track the state and health of the Cloud or Local connection to the S30. When using multiple LAN connections, the first host in the list will use lennoxs30.state for backwards compatibility. Additional local connections will use a naming convention of lennoxs30.conn_. Cloud connections wil use lennoxs30._<redacted email_address>

The entity also has a set of attributes to provide diagnostic data:

The S40 supports the use of remote sensors. Bluetooth Low Energy (BLE) is the technology used for the sensor to communicate with the panel. Currently, we have only seen one type of sensor (22V25); if your system has other types of sensors, please open an issue so we can add support.

The 22V25 is a battery powered room sensor.

The 21P02 is a line powered air quality sensor.

When the create_sensors configuration parameter is set, humidity and temperature sensors are created for each zone. This is the default for new configurations. These sensors are attached to the Thermostat Device.

sensor.<system_name>_<zone_name>_temperature

sensor.<system_name>_<zone_name>_humidity

Lennox systems may have an outdoor temperature sensor. If your system has one a sensor will be automatically created and attached to the Outdoor Unit Device. It's name will be

sensor.<system_name>_outdoor_temperature

When the create_inverter_power configuration parameter is set, a power sensor entity will be created. Inverter Power can only be enabled for Local Connections. To get this information the S30 must be placed in Diagnostic Mode 2. To set the diagnostic mode see diagnostic level

WARNING S30 instability may result please review docs/diagnostics.md for configuration recommendations.

When diagnostics is enabled it should begin updating with the current power draw of the system. It's name will be

sensor.<system_name>_inverter_energy

It can be combined with an Integration sensor to count the total energy usage over time, and this Integration sensor can be added to the Home Assistant Energy dashboard. A configuration similar to the following should work:

sensor:
  - platform: integration
    source: sensor.<system_name>_inverter_energy
    name: <system_name>_inverter_kwh
    method: left
    unit_prefix: k
    round: 2

WARNING S30 instability may result please review docs/diagnostics.md for configuration recommendations.

When the option to create diagnostic sensors is enabled, sensors are created for every diagnostic that is available in your system. Hence, the exact list depends on the specific Lennox Equipment you have installed. The names will be

sensor.<system_name>*_<diagnostic_name>

Where eq is IU for your indoor unit (e.g. air handler, furnace); OU for your outdoor unit (Compressor, HeatPump)

This sensor captures the current alert level of the Lennox controller; indicating the severity of the highest active alert. The list of potential values is:

NOTE - the above list is probably incomplete it may also contain other values, if you see these please raise an issue so we can update the documentation.

sensor.<system_name>_alert

This sensor provides a count of the active alerts and the list of active alerts as a attribute.

NOTE High and Low Heatpump Ambient lockouts are reported as alerts!

Example JSON

[
  {
    "alert": {
      "userMessageID": 0,
      "timestampClear": "5273299695",
      "code": 19,
      "notifyDealer": false,
      "userMessage": "",
      "isStillActive": true,
      "update": false,
      "clearableByDealer": false,
      "timestampLast": "1636473073",
      "priority": "info",
      "notifyUser": false,
      "clearedBy": "active",
      "timestampFirst": "1636473073",
      "equipmentType": 0,
      "optionalfieldData": "4.518750e+01",
      "action": "set",
      "optionalfieldType": "temperature",
      "clearableByUser": false,
      "count": 1
    },
    "maxItems": 256,
    "id": 0
  },
  {
    "id": 1,
    "alert": {
      "userMessageID": 0,
      "timestampClear": "1636420745",
      "code": 18,
      "notifyDealer": false,
      "userMessage": "Low Ambient HP Heat Lockout",
      "isStillActive": true,
      "timestampLast": "1636460248",
      "clearableByDealer": false,
      "update": false,
      "priority": "info",
      "action": "clear",
      "clearedBy": "device",
      "timestampFirst": "1636420745",
      "count": 1,
      "optionalfieldType": "null",
      "notifyUser": false,
      "optionalfieldData": "",
      "clearableByUser": false,
      "equipmentType": 0
    }
  }
]

Local Connections Only. Reports the WIFI signal strength, this sensor can be used to diagnose WIFI dropout issues.

If your Lennox System has Humidification or Dehumidification capability, one of these select entities is created per zone to allow you to set the active humidity mode. The available options - depending on your equipment - are Dehumidify, Humidify and Off

select.<system_name><zone_name>_humidity_mode

Some Lennox systems support dehumidification and have several different settings available. The available options are Normal, Max and Climate IQ

select.<system_name>_dehumidification_mode

When the configuration parameter is true a switch will be created.

switch.<system_name>__allergen_defender

The switch will reflect the current state of the allergen defender mode and will allow turning the mode on or off

This switch reports the current state of manual away mode and allows turning manual away mode on or off.

switch.<system_name>_manual_away_mode

This switch enables or disables smart away on the S30. This switch does not put the system into away mode. This switch enables the S30 to perform it's smart away detection of your mobile devices. To properly setup Smart Away you will need to use the Lennox Mobile App. Once smart away is setup, this allow you to turn the detection on or off.

switch.<system_name>_manual_away_mode

If your system has an external outdoor air damper, a 1 or 2 stage ERV, or a 1 or 2 stage HRV ventilation controls will be created.

There are two different aspects of ventilation

1. The Ventilation Mode which is On, Off or Installer. When set to Installer the system will run in a Timed mode or ASHRAE mode depending on how the installer configured the system. When set to On the ventilation will run indefinitely. When set to Off the ventilation will not run.
2. Ventilate Now - this is a one time ventilation for a duration. For example, on the panel, select Ventilate Now and enter 10 minutes - and ventilation will run for 10 minutes.

If the system is receiving weather data; ventilation will not occur if the outside dewpoint is above the configured threshold. The outside dewpoint, for S40, is available in sensor.*_wt_env_dewpoint. The threshold is available in an equipment parameter called Ventilation High Outdoor Dew Point Limit

Allows setting ventilation mode to On, Off or Installer.

Attribute installer_settings contains installer or ASHRAE

Note: in older installs this entity may be called number.<system_name>_timed_ventilation, it was renamed in 2023_10_0 to make it similar to the panel text.

Setting this to a non-zero number will place the system into a ventilate now mode for the specified number of minutes. This is equivalent to selecting a timed ventilation from the S30 panel. As the amount of remaining time decreases, the value of the number will update.

For example, setting this to 10 - will start ventilation for 10 minutes. After 1 minute has elapsed; this value will be 9; after another minute it will be 8. Setting this to Zero cancels any in-progress timed ventilation. Another way to cancel a timed ventilation is to turn the ventilation switch entity off.

The switch will reflect the current state of the ventilation damper and will allow turning the mode on or off.
The switch has the following attributes:

Turning this switch on is equivalent to selecting "Always On" from the S30 Panel. If a ventilate now is active, this switch will be on and turning it off will cancel the timed ventilation.

The S40 makes its weather data available. The S30 does not appear to. While the data includes an hourly and daily forecast - that information is available in HA through a variety of weather providers. However there are specific environmental data that the S40 uses to control ventilation and allergen defender mode - this information is available in a set of sensors. Note: if your S40 is not connected to the internet these sensors will be unavailable.

If your system has iHarmony Zoning, this switch allows you to turn iHarmony Zoning on and off, just like in the Lennox UI.

When iHarmony zoning is disabled the following occurs:

1. Zone 1 is used to control heating, cooling and humidity
2. Zone 2,3,4 are disabled for control, but still report Temperature and Humidity
3. The Climate Entity Attributes zoningMode and zoneEnabled show the zoning and zone enablement status

Entity is created if your system has a heatpump. Indicates if the heatpump is currently locked out.

binary_sensor.<system_name>_hp_lo_ambient_lockout

Entity is created if your system has a heatpump. Indicates if the heatpump is currently locked out.

binary_sensor.<system_name>_hp_lo_ambient_lockout

Entity is created if your system has auxiliary heat. Indicates if the aux heat is locked out due to high ambient temperature

binary_sensor.<system_name>__auxheat_hi_ambient_lockout

The home state binary sensor reports the current away mode of the S30. A value of 'on' indicates the system is in home mode. A value of 'off' indicates the system is in away mode. This sensor used the "presence" device class, so in Lovelace you will see the value of 'Home' or 'Away'.

binary_sensor.<system_name>_home_state

The S30 has three setpoint states that are possible - Home, Transition and Away. For this binary sensor the Transition and Away states are reported as Away. The detailed information is available within attributes of the binary sensor.

Smart Away State Values

This sensor indicates if the S30 has connectivity to the internet. If you use the Lennox App on your phone, you want this to be in a connected state. If you are using diagnostics you want this is a disconnected state

binary_sensor.<system_name>_internet_status

Note: The S30 can take a while to update this sensor. To accelerate the update, go to the S30 panel, press settings and select WIFI - this seems to cause the S30 to immediately ping the internet.

This sensor indicates if the S30 is connected to the Lennox Cloud Relay Server. If you use the Lennox App on your phone, you want this to be in a connected state. If you are using diagnostics you want this is a disconnected state.

Note: The S30 can take a while to update this sensor. To accelerate the update, go to the S30 panel, press settings and select WIFI - this seems to cause the S30 to immediately check the connection to the relay server.

binary_sensor.<system_name>_relay_server

This sensor indicates if the thermostat is "Online" in the Lennox Cloud. The state should be connected. A disconnected state indicates that the integration is able to communicate to the Lennox Cloud but the thermostat is not able to. Typically this indicates a Wifi config issue with the thermostat.

During testing, turning off the wifi router the S30 was connected caused this sensor to become disconnected after 5 minutes. The sensor is configured to be updated every 10 minutes.

WARNING Setting the Diagnostic Level may cause system instability if your system is connected to the Lennox Cloud Relay Server. Please review this documentation before proceeding. docs/diagnostics.md

When the power inverter or diagnostic sensors option is enabled, a Number entity is created to allow setting and reporting on the active diagnostic level in the S30. A value of zero indicates diagnostics is disabled. Values of 2 will cause the inverter power and diagnostics to be sent. Other values are invalid. The name of the entity is:

number.<system_name>_diagnostic_level

Note: When enabled the S30 sends much more information. If you are using their IOS / Android App - this may impact the performance and cause S30 crashes. It is not recommended to be toggling this mode frequently. If you are using this feature, you may want to monitor the lennoxS30.state sysuptime attribute. This value will reset to zero when the S30 reboots. The integration will log a warning if this is detected.

The circulate time number allows you to set the percentage of time the fan is on when in circulate mode.

Note: In the Lennox UI it shows Minutes+Seconds per hour for circulate time. However, the underlying commands to the S30 use whole number percents (e.g. 20.0). The Home Assistant Sliders are best suited for numbers not mm:ss, so the decision was made to represent this as percents in Home Assistant. That decision can be revisited if needed.

number.<system_name>_circulate_time

Lennox systems with dehumidifiers may have the ability to provide overcooling to lower the humidity when the dehumidification mode is Max. This number allow you to set this over-cooling. Typically is is 0-4 degrees F or 0-2 degrees Celsius.

When equipment parameters are enabled in configuration, this entity will be created. Pressing this button will reboot the smart hub. The button execution requires that the parameter_safety switch is turned off.

number.<system_name>_reset_smarthub

Please create issues to track bugs. Please include the following information

• HA version and Integration Version
• Configuration Settings (local, cloud)
• Are you using Diagnostic

Please capture the logs with debug turned on.

Debug logging can be enabled by adding the following to your Home Assistant's configuration.yaml:

logger:
  default: warning
  logs:
    custom_components.lennoxs30: debug
    lennoxs30api: debug

Some times I will need a message log. To enable message logging do the following:

• Go into the integrations configuration
• Check the "Debug Logging Logs Message" and "Log S30 Messages to a separate file" and enter a file name.

This section documents the detailed configuration parameters, that are editable through the UI. This configuration is stored in the config/.storage/core_config_entries file. Editing this file is not recommended.

In Release 0.2.0 configuration is moved from configuration.yaml to the internal home assistant configuration repository. On startup of 0.2.0 (or later releases), the YAML configuration will be migrated to the repository. After HA starts please check your entities to verify they are working. Once verified remove the lennoxs30 configuration from configuration.yaml. All of your entities should be preserved and the migration should be seamless.

If you are on older versions of the integration. You may need to adjust your configuration in the YAML fie to meet the new requirements.

1. Start HA
2. Look for errors in the log indicating there is missing configuration
3. Add missing configuration
4. Restart

Use Case: You have the integration configured to use the cloud and you want to go local. Current State: You are on 0.1.3

The simplest approach is to edit the configuration.yaml in 0.1.3 and add the ip_address in and restart HA.

When switching from Cloud to Local - new entities are created in Home Assistant. Perform the following steps after restarting:

• Go into the list of entities and delete the old entities (write down their names if needed)
• Rename the new entities using the old entity's entity ids.

Use Case: You have the integration configured to use the cloud and you want to go local. Current State: You are on 0.2.0 or greater.

• Go into Configuration / Integrations and Delete the cloud integration
• Add a new integration instance for the local connection.

Perform the following steps:

1. Comment out the lennoxs30: section from configuration.yaml (use the #)
2. Moved the old custom_components/lennoxs30 directory to somewhere else so it wouldn't be found. Or delete it. Make sure the lennoxs30 directory no longer exists
3. Restart HA
4. Add custom repository in HACS per the Instructions
5. Add integration in HACS per the instructions
6. Restart HA
7. Uncomment the lennoxs30: section from configuration.yaml
8. Restart HA

In 0.2.0 and greater the config for the integration is not stored in configuration.yaml.

Note: These steps are untested. Please provide feedback if this works :-).

Perform the following steps:

1. Moved the old custom_components/lennoxs30 directory to somewhere else so it wouldn't be found. Or delete it. Make sure the lennoxs30 directory no longer exists
2. Restart HA
3. Add custom repository in HACS per the Instructions
4. Add integration in HACS per the instructions
5. Restart HA

At this point everything should just work.

The local connection uses HTTPS to Port 443 outgoing to the S30.

The cloud connection using HTTPS to Port 443 outgoing to the Lennox Cloud.

There are no incoming connections.

When using local connections you can block all outgoing internet access for the S30 and the local connections still work. Of course, doing this disables the ability to use the Lennox App on your phone.

It is recommended to DISABLE automatic software updates on the S30.

Enhancement requests are welcomed and encouraged. Please log issues for us to track enhancements.

https://tech.lennoxintl.com/C03e7o14l/VIu12Ch2uV/Corp1817-L8f.pdf https://resources.lennox.com/pdfs/owners/s30/Lennox_iComfortS30_Homeowner_Manual.pdf

This work is based in part great work done by these folks:

https://github.com/HyperActiveJ

https://github.com/hufman/lennox_lcc

https://github.com/thevoltagesource