icomfort-js

A client for the Lennox iComfort services implemented in JavaScript.

Currently this module works natively in Node.js. Using a tool such as browserify, it could be used in modern web browsers.

The minimum supported version of Node.js is 14.

API

All methods of the iComfortClient return promises as they communicate asynchronously with the Lennox iComfort servers via HTTP.

Before calling any of the below methods, the client must be instantiated with valid credentials.

const icomfort = iComfortClient({username: 'valid username', password: 'supersecret'});
// or
const icomfort = new iComfortClient({username: 'valid username', password: 'supersecret'});

• getBuildingsInfo
• getGatewayInfo
• getGatewaysAlerts
• getSystemsInfo
• getThermostatInfoList
• getThermostatLookupInfo
• getThermostatScheduleInfo
• validateUser
• setThermostatInfo

getBuildingsInfo(params)

Retrieves information about the buildings associated with your my iComfort account.

params - Object:

• UserId - A valid iComfort username.

Example Response

{
  "Buildings": [
    {
      "Addr1": "123 Main",
      "Addr2": "Apt Z",
      "Age_of_Building": 99,
      "BuildingAlert": true,
      "BuildingID": 999999,
      "BuildingReminder": true,
      "BuildingSize": 9,
      "BuildingStyle": 9,
      "Building_Name": "My house",
      "City": "Anytown",
      "Country": "US",
      "DealerAlerts_DlrWants": false,
      "DealerAlerts_OwnerAllow": false,
      "DealerID": 999999,
      "DealerReminder_DlrWants": false,
      "DealerReminder_OwnerAllow": false,
      "DealerTStatView": false,
      "DefaultBuilding": true,
      "Latitude": 32.981704,
      "Longitude": -96.760218,
      "NotificationEmail": "",
      "Number_of_Bedrooms": 9,
      "Number_of_Floors": 9,
      "Number_of_Occupants": 9,
      "St_Prov": "ZZ",
      "UserID": null,
      "UtilityCompany": "Nationwide Gas Co",
      "ZIP_PC": "99999"
    }
  ],
  "ReturnStatus": "SUCCESS"
}

getGatewayInfo(params)

Retrieves information about a gateway (thermostat) associated with your account.

params - Object:

• GatewaySN - The serial number of a gateway associated with your account. It can be discovered using the getSystemsInfo method.
• TempUnit - A integer which indicates which temperature units to use to represent values from the gateway. The value 0 Corresponds to F (farenheit) and 1 to C (celsius).

Example Response

{
  "Cool_Set_Point_High_Limit": 99,
  "Cool_Set_Point_Low_Limit": 60,
  "Daylight_Savings_Time": 1,
  "Heat_Cool_Dead_Band": 3,
  "Heat_Set_Point_High_Limit": 90,
  "Heat_Set_Point_Low_Limit": 40,
  "Pref_Language_Nbr": 0,
  "Pref_Temp_Unit": "0",
  "ReturnStatus": "SUCCESS",
  "SystemID": "999998"
}

getGatewaysAlerts(params)

Retrieves a list of alerts associated with a gateway.

params - Object:

• gatewaysn - The serial number of a gateway associated with your account. It can be discovered using the getSystemsInfo method.

Example Response

{
  "Alerts": [],
  "ReturnStatus": "SUCCESS"
}

getSystemsInfo(params)

Retrieves information about systems associated with your account.

params - Object:

• UserId - A valid iComfort username.

Example Response

{
  "ReturnStatus": "SUCCESS",
  "Systems": [
    {
      "BuildingID": 999999,
      "Firmware_Ver": "02.13.0240",
      "Gateway_SN": "WS99C99999",
      "RegistrationCompleteFlag": false,
      "Status": "GOOD",
      "SystemID": 999998,
      "System_Name": "My main thermostat"
    }
  ]
}

getThermostatInfoList(params)

Lists information for thermostats for an account.

params - Object:

• Cancel_Away - 'Cancel away flag'? Unknown use. Set value to -1.
• GatewaySN - The serial number of a gateway associated with your account. It can be discovered using the getSystemsInfo method.
• TempUnit - A integer which indicates which temperature units to use to represent values from the gateway. The value 0 Corresponds to F (farenheit) and 1 to C (celsius).

Example Response

{
  "ReturnStatus": "SUCCESS",
  "tStatInfo": [
    {
      "Away_Mode": 0,
      "Central_Zoned_Away": 2,
      "ConnectionStatus": "GOOD",
      "Cool_Set_Point": 85,
      "DateTime_Mark": "/Date(1487093681823+0000)/",
      "Fan_Mode": 0,
      "GMT_To_Local": -25200,
      "GatewaySN": "WS99C99999",
      "Golden_Table_Updated": true,
      "Heat_Set_Point": 73,
      "Indoor_Humidity": 31,
      "Indoor_Temp": 73,
      "Operation_Mode": 3,
      "Pref_Temp_Units": "0",
      "Program_Schedule_Mode": "1",
      "Program_Schedule_Selection": 1,
      "System_Status": 0,
      "Zone_Enabled": 1,
      "Zone_Name": "Zone 1",
      "Zone_Number": 0,
      "Zones_Installed": 1
    }
  ]
}

getThermostatLookupInfo(params)

Retrieves list of different parameters possible for a gateway (thermostat).

params - Object:

• gatewaysn - The serial number of a gateway associated with your account. It can be discovered using the getSystemsInfo method.
• name - 'Name'? Unknown use. Set value to 'all'.

Example Response

{
  "ReturnStatus": "SUCCESS",
  "tStatlookupInfo": [
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "cool only",
      "name": "Operation_mode",
      "sort_order": 0,
      "value": 2
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "on",
      "name": "Fan_mode",
      "sort_order": 0,
      "value": 1
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Keep Standard Time",
      "name": "Daylight_savings",
      "sort_order": 1,
      "value": 0
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "auto",
      "name": "Fan_mode",
      "sort_order": 1,
      "value": 0
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Contact Me",
      "name": "MessageType",
      "sort_order": 1,
      "value": 0
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "heat only",
      "name": "Operation_mode",
      "sort_order": 1,
      "value": 1
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "idle",
      "name": "System_status",
      "sort_order": 1,
      "value": 0
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "",
      "name": "Fahrenheit",
      "sort_order": 1,
      "value": 0
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "",
      "name": "Celcius",
      "sort_order": 2,
      "value": 1
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "heating",
      "name": "System_status",
      "sort_order": 2,
      "value": 1
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "heat or cool",
      "name": "Operation_mode",
      "sort_order": 2,
      "value": 3
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Need Service",
      "name": "MessageType",
      "sort_order": 2,
      "value": 1
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Observe Daylight Savings Time",
      "name": "Daylight_savings",
      "sort_order": 2,
      "value": 1
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "circulate",
      "name": "Fan_mode",
      "sort_order": 3,
      "value": 2
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Need Information on Products",
      "name": "MessageType",
      "sort_order": 3,
      "value": 2
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "off",
      "name": "Operation_mode",
      "sort_order": 3,
      "value": 0
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "cooling",
      "name": "System_status",
      "sort_order": 3,
      "value": 2
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "waiting",
      "name": "System_status",
      "sort_order": 4,
      "value": 3
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Unit Not Working",
      "name": "MessageType",
      "sort_order": 4,
      "value": 3
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "Other",
      "name": "MessageType",
      "sort_order": 5,
      "value": 4
    },
    {
      "Lang_Nbr": 0,
      "ReturnStatus": "SUCCESS",
      "description": "emergency heat",
      "name": "System_status",
      "sort_order": 5,
      "value": 4
    }
  ]
}

getThermostatScheduleInfo(params)

Retrieves a list of schedules for a given thermostat.

params - Object:

• gatewaysn - The serial number of a gateway associated with your account. It can be discovered using the getSystemsInfo method.

Example Response

{
  "ReturnStatus": "SUCCESS",
  "tStatScheduleInfo": [
    {
      "Schedule_Name": "summer",
      "Schedule_Number": 0
    },
    {
      "Schedule_Name": "winter",
      "Schedule_Number": 1
    },
    {
      "Schedule_Name": "spring fall",
      "Schedule_Number": 2
    },
    {
      "Schedule_Name": "save energy",
      "Schedule_Number": 3
    },
    {
      "Schedule_Name": "custom",
      "Schedule_Number": 4
    }
  ]
}

validateUser(data)

Validates a user account information.

data - Object:

• UserName - A valid iComfort username.

Example Response

{
  "msg_code": "SUCCESS",
  "msg_desc": "Success"
}

setThermostatInfo(data)

Updates operating parameters for a thermostat. Can be used to set temperatures.

This method requires various properties in its data payload. The best way to use this method is to first get the current thermostat info using the getThermostatInfoList method. Then modify properties as needed and use the updated status object as the payload for this method.

data - Object:

• Cool_Set_Point - Maximum temperature before thermostat activates cooling.
• Heat_Set_Point - Minimum temperature before thermostat activates heating.
• Pref_Temp_Units - A integer which indicates which temperature units to use to represent values from the gateway. The value 0 Corresponds to F (farenheit) and 1 to C (celsius).

Example

const icomfort = new iComfortClient({username: 'valid username', password: 'supersecret'});

const myGatewaySN = 'WS99C99999';

icomfort.getThermostatInfoList({Cancel_Away: -1, GatewaySN: myGatewaySN})
    .then(res => {
        const currentSettings = res.tStatInfo.find(tStat => tStat.GatewaySN === myGatewaySN);

        const newOptions = {
            Cool_Set_Point: currentSettings.Cool_Set_Point+2,
            Heat_Set_Point: currentSettings.Heat_Set_Point+2
        };

        const newSettings = Object.assign({}, currentSettings, newOptions);

        return icomfort.setThermostatInfo(newSettings);
    });

Example Response

If the update is successful, the number 0 is returned.

0

setAwayMode(data)

Updates away mode for a thermostat..

This method requires the new away mode (on or off) represented by a 1 or 0. The zone to be updated needs to be specified as well. The underlying endpoint gets passed fan mode, and cooling and heating set points, though they seem to get calculated on the server. The response is the same as that of the getThermostatInfoList method.

data - Object:

• awaymode - Away mode setting. Value 0 activates away mode, and value 1 deactivates it.
• coolsetpoint - Maximum temperature before thermostat activates cooling.
• fanmode - Fan operation mode. See getThermostatLookupInfo for values.
• gatewaysn - The serial number of a gateway associated with your account. It can be discovered using the getSystemsInfo method.
• heatsetpoint - Minimum temperature before thermostat activates heating.
• zonenumber - Zone number of gateway.

Example

const icomfort = new iComfortClient({username: 'valid username', password: 'supersecret'});

const myGatewaySN = 'WS99C99999';
const newAwayMode = 1; // Activates away mode

icomfort.getThermostatInfoList({GatewaySN: myGatewaySN})
    .then(res => {
        const currentSettings = res.tStatInfo.find(tStat => tStat.GatewaySN === myGatewaySN);

        const currentAwayMode = {
            'awaymode': currentSettings.Away_Mode,
            'coolsetpoint': currentSettings.Cool_Set_Point,
            'fanmode': currentSettings.Fan_Mode,
            'gatewaysn': currentSettings.GatewaySN,
            'heatsetpoint': currentSettings.Heat_Set_Point,
            'zonenumber': currentSettings.Zone_Number,
        };

        const newOptions = {
            'awaymode': newAwayMode
        };
        const newSettings = Object.assign({}, currentAwayMode, newOptions);

        return icomfort.setAwayMode(newSettings);
    });

Example Response

{
  "ReturnStatus": "1",
  "tStatInfo": [
    {
      "Away_Mode": 1,
      "Central_Zoned_Away": 2,
      "ConnectionStatus": "GOOD",
      "Cool_Set_Point": 85,
      "DateTime_Mark": "/Date(1487093681823+0000)/",
      "Fan_Mode": 0,
      "GMT_To_Local": -25200,
      "GatewaySN": "WS99C99999",
      "Golden_Table_Updated": true,
      "Heat_Set_Point": 62,
      "Indoor_Humidity": 31,
      "Indoor_Temp": 73,
      "Operation_Mode": 3,
      "Pref_Temp_Units": "0",
      "Program_Schedule_Mode": "1",
      "Program_Schedule_Selection": 1,
      "System_Status": 0,
      "Zone_Enabled": 1,
      "Zone_Name": "Zone 1",
      "Zone_Number": 0,
      "Zones_Installed": 1
    }
  ]
}

Testing

Some very basic tests are implemented using the Mocha testing framework. An npm script has also been defined to fire off the tests. Before running the tests, you will need to define your iComfort username and password in your environment. In Unix/Linux/BSD/mac OS, you can do the following:

export ICOMFORT_USERNAME='your icomfort username'
export ICOMFORT_PASSWORD='your icomfort password'

On Windows, the command is similar:

set ICOMFORT_USERNAME='your icomfort username'
set ICOMFORT_PASSWORD='your icomfort password'

After setting your username and password, to run the test command do the following:

npm test

If your username and password are correct, all of the tests will pass. If not, all of the tests will fail.

Thanks

Thanks to Ian Macdonald for his Ruby iComfort repo which helped get me started in the right direction.

Also thanks to Kate Hall for being the first to make use of this code. Her project encouraged me to make this code more modular. Check out her integration of this project's code with Amazon's Alexa at alexa-icomfort.