node-aosmith

This is an API Client for A. O. Smith iCOMM-enabled water heaters. If you can control your water heater using the A. O. Smith mobile app (iOS/Android), then it should be compatible with this library.

Known Compatible Models

• HPTS-50
• HPTS-66
• HPTS-80

If your water heater is not working with this library, but it can be controlled using the A. O. Smith mobile app, please open an issue so that support can be added.

Similarly, if your water heater is working with this library, but is not listed here, please open an issue so it can be added to the list.

Installation

To install the latest release from npm, run npm install node-aosmith.

Quick Start

You will need a compatible water heater which is already connected to Wi-Fi and linked to your A. O. Smith account.

This example initializes the API client and gets a list of water heaters linked to the account. Then, for each water heater, it updates the setpoint to 120 degrees.

import { AOSmithAPIClient } from "./client.js";

// Initialize API client
const client = new AOSmithAPIClient("[email protected]", "mypassword");

// Get list of water heaters linked to the account
const devices = await client.getDevices();

// Loop through the registered water heaters
for (const device of devices) {
    // Update the setpoint to 120 degrees
    await client.updateSetpoint(device.junctionId, 120);
}

API Documentation

Initialize API Client

new AOSmithAPIClient(email, password)

Parameters

| Parameter | Description | | --------- | ----------- | | email | The email address for your A. O. Smith account | | password | The password for your A. O. Smith account |

Return value

Returns an instance of AOSmithAPIClient which can be used to invoke the below methods.

Get List of Devices

await client.getDevices()

Gets a list of water heaters linked with the A. O. Smith account. May only include devices which are known to be compatible with this library.

If your water heater can be controlled in the A. O. Smith mobile app, but is not included in the return value of this method, please open an issue so that support can be added.

Parameters

None

Return value

[
    {
        "brand": "aosmith",
        "model": "HPTS-50 200 202172000",
        "deviceType": "NEXT_GEN_HEAT_PUMP",
        "dsn": "xxxxxxxxxxxxxxx",
        "junctionId": "xxxxxxxxxxxxxxxxxx", // Unique ID needed to call the other API methods
        "name": "Water Heater", // Custom nickname assigned in the mobile app
        "serial": "xxxxxxxxxxxxx",
        "install": {
            "location": "Basement" // Install location set in the mobile app
        },
        "data": {
            "__typename": "NextGenHeatPump",
            "temperatureSetpoint": 130, // Current setpoint (target water temperature)
            "temperatureSetpointPending": false,
            "temperatureSetpointPrevious": 130,
            "temperatureSetpointMaximum": 130, // Max possible setpoint - to increase this, manually adjust the setpoint using the buttons on the water heater
            "modes": [ // Available operation modes
                {
                    "mode": "HYBRID",
                    "controls": null
                },
                {
                    "mode": "HEAT_PUMP",
                    "controls": null
                },
                {
                    "mode": "ELECTRIC",
                    "controls": "SELECT_DAYS"
                },
                {
                    "mode": "VACATION",
                    "controls": "SELECT_DAYS"
                }
            ],
            "isOnline": true,
            "firmwareVersion": "2.14",
            "hotWaterStatus": "LOW", // Current hot water availability ("LOW", "MEDIUM", or "HIGH")
            "mode": "HEAT_PUMP", // Current operation mode
            "modePending": false,
            "vacationModeRemainingDays": 0,
            "electricModeRemainingDays": 0
        }
    }
]

Update setpoint

await client.updateSetpoint(junctionId, setpoint)

Updates the setpoint (target water temperature) of the water heater.

When using this method, the setpoint cannot be adjusted above the temperatureSetpointMaximum from the return value of getDevices(). To increase this maximum, manually adjust the setpoint using the buttons on the water heater.

Parameters

| Parameter | Description | | --------- | ----------- | | junctionId | Unique ID of the water heater, obtained from getDevices() | | setpoint | New target temperature to set |

Return value

None

Update mode

await client.updateMode(junctionId, mode, days?)

Sets the operation mode of the water heater. To determine the list of modes supported by your water heater, check data.modes[] in the return value of getDevices().

Parameters

| Parameter | Description | | --------- | ----------- | | junctionId | Unique ID of the water heater, obtained from getDevices() | | mode | New operation mode to set | | days | Optional. Number of days after which the device will automatically exit this mode. Only works for modes where data.modes[].controls from getDevices() is "SELECT_DAYS".

Return value

None

Get energy use data by DSN

await client.getEnergyUseData(junctionId)

Gets energy use history data from the water heater.

Parameters

| Parameter | Description | | --------- | ----------- | | junctionId | Unique ID of the water heater, obtained from getDevices() |

Return value

{
    "average": 2.7552000000000003,
    "graphData": [
        {
            "date": "2023-10-30T04:00:00.000Z",
            "kwh": 2.01
        },
        {
            "date": "2023-10-31T04:00:00.000Z",
            "kwh": 1.542
        },
        {
            "date": "2023-11-01T04:00:00.000Z",
            "kwh": 1.908
        },
        /* ... */
    ],
    "lifetimeKwh": 132.825,
    "startDate": "Oct 30"
}

Disclaimer

This project is not affiliated with or endorsed by A. O. Smith. This is not an official API, and it may stop working at any time without warning.