A custom component for Home Assistant to integrate with Lennox iComfort S30 or Lennox iComfort E30 thermostats
Please Note: This component does not support the other models of Lennox Thermostats
- Home Assistant >= 2021.04.06 (others may work)
- Thermostat linked to a lennoxicomfort.com account
- Passwords with special characters are not properly supported by the Lennox 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.
- Go to releases in this repo and download the latest zip or clone the repo
- If upgrading from a prior release, pleast remove ALL files from the <HA config directory>/custom_components/lennoxs30 folder.
- Copy the 'lennoxs30' folder and contents to <HA config directory>/custom_components/
- Add the configuration to configuration.yaml. If HA is running and you press the "Validate Configuration" button you may get an error. HA must be restarted before it will see the new custom component.
- Restart HA
There is a HACS.JSON file that was contributed. So this may work also. If it does work please submit some docs we can put in here to describe the process!
Configuration of the integration is done in configuration.yaml
lennoxs30:
email: myemail@myemail.com
password: mypasswordlennoxs30:
email: myemail@myemail.com
password: mypassword
scan_interval: 30
fast_scan_interval: 0.5
allergen_defender_switch: true
init_wait_time: 45
app_id: mapp079372367644467046827001
# Enable logging if reporting issues
logger:
default: info
logs:
custom_components.lennoxs30: debug
custom_components.lennoxs30.climate: debug
lennoxs30api: debug| Name | Type | Requirement | Default | Description |
|---|---|---|---|---|
| string | required | none | Cloud service account username | |
| password | string | required | none | Cloud service account password |
| scan_interval | int | optional | 15 | Scan interval to check for cloud messages in seconds |
| allergen_defender_switch | bool | optional | false | When true creates a switch entity to allow control of allergenDefender mode |
| fast_scan_interval | float | optional | 0.75 | After issuing a command (setpoint change, hvac mode change, etc.) The system goes into a fast scan mode, in order to make the UI more responsive to commands |
| init_wait_time | int | optional | 30 | Amount of time to wait for configuration to arrive from Lennox during integration startup. Increase this value if you see initialization timeouts |
| app_id | string | optional | uniquely generated | Specify the unique application id to use. In most cases, having the integration autogenerate one works fine. If default prevents initialization from being successful then specify the app id here. Please use this string - mapp0793723676444670468270xx - and replace xx with a value from 00 - 99. Note that each instance of your integration (e.g. prod system, test system) must use a different value for xx. |
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 degress 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.
This integration will automatically detect all the homes, systems and zones in your account and add a Climate Entity for each discovered zone. The names of the climate entities will be
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"
The integration creates internal Entity_Ids using the GUID of your S30 plus the zone index (0,1,2,3).
HVAC_MODE supports off, cool, heat or heat_cool mode. The speficic modes available depend on you equipemnt. For example an AC does not support heat, hence the heat and heat_cool modes would not appear in HA.
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 Away Mode and the cancel away mode preset will 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 away / cancel away icon on the S30 panel.
The integration provides all of the standard climate attributes, including
- Temperature
- Humidity
- Current HVAC action
- Active setpoints
- Active Preset
In additon the following extra attributes are provided, to allow for a more detailed information on the current zone operation.
| Attribute Name | Description |
|---|---|
| fan | Indicates if the fan is currently running. Note: this is true only when the fan is running and there is no active HVAC action (cooling, heating, etc.) |
| damper | Position of damper - range 0-100 |
| demand | CFM of air demand for the zone. Thanks @blyons16 for getting this information from his installers |
| tempOperation | Current acvtive temperatue operation heating or cooling |
| humidityOperation | Current active humidty operation - Drying or humidfying |
| allergenDefender | Indicates if this is enabled on the zone |
| ventilation | Indicates if external ventilation is currently active on this zone |
The entity is automatically created in Home Assistant and can be used to track the state and health of the connection to the cloud.
| State | Description |
|---|---|
| Connected | API is connected to cloud system. This is the desired state |
| Connecting | API is trying to connect to the cloud system. |
| Disconnected | API has failed to connect to cloud and will not try again. Please raise an issue if you encounter this state |
| Login Failed | The login failued due to bad email/password combination. Please correct credentials and restart HA |
| Waiting to Retry | The API was unable to connect or lost connection and is waiting to attempt a retry |
| Failed | The API failed. Please raise an issue if you encounter this state |
The entity also has a set of attributes to provide diagnostic data:
| Attribute | Type | Description |
|---|---|---|
| message_count | int | number of messages received from Lennox Cloud |
| send_count | int | number of messages sent to Lennox Cloud |
| receive_count | int | number of queries to recieve new messages. Most queries return no messages |
| bytes_in | int | number of byte received |
| bytes_out | int | number of bytes sent |
| error_count | int | number of errors |
| http_2xx | int | number of HTTP responses received between 200-299. THese are good responses |
| http_4xx | int | number of HTTP responses received between 400-499. These usually indicate a problem with authorization |
| http_5xx | int | number of HTTP responses received between 500-599. These indicate a problem with the Lennox Cloud Servers. Seeing a few of these a day is normal |
| last_receive_time | DateTime | Time of last succesful receive. Should not be more than SCAN_INTERVAL seconds plus few seconds plus the metric update interval (90 seconds). In other words is this time is more than 5 minutes ago using default SCAN_INTERVAL something is wrong. |
| last_error_time | DateTime | Time of the last error response |
| last_reconnect_time | DateTime | Time of the last reconnect or the time of the initial connect |
| last_message_time | DateTime | Time of the last message from Lennox Cloud. How often messages are received is based on how often data is changing in the thermostat. For example, a temperature change, a setpoint change will cause a message to be sent. If nothing is changing nothing will be sent |
Lennox systems may have an outdoor temperature sensor. If your system has one a sensor will be automatically created. It's name will be
sensor.<system_name>_outdoor_temperature
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
If your system has an external outdoor air damper a switch will be created.
switch.<system_name>_ventilation
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:
| Attribute | Type | Description |
|---|---|---|
| ventilationRemainigTime | int | number of minutes remaining in ventilation action |
| ventilatingUntilTime | int | integer timestamp of the end time of the ventilation action |
| receive_count | int | number of queries to recieve new messages. Most queries return no messages |
| diagVentilationRuntime | int | total number of minutes the system has ventilated for over it's lifetime |
Please create issues to track bugs. Please capture the logs with debug turned on.
The Lennox configuration that comes back from the API contains every configuration parameter of your system - including Personally Identifiable Information. It is highly recommend to not publicly post these log files. Information includes - the address of your residence and email address. Issues #14 tracks this and we will work to scrub this information from the log file. If I need a logfile or troubleshooting I will ask you to email it
Enhancement requests are welcomed and encouraged. Please log issues for us to track enhancements.