@jope-io/ecobee

🐝 a library for interacting with ecobee devices

Usage no npm install needed!

<script type="module">
  import jopeIoEcobee from 'https://cdn.skypack.dev/@jope-io/ecobee';
</script>

README

@jope-io/ecobee

A Nodejs wrapper for the ecobee API.

Quickstart

const {ECOBEE, ECOBEE_CONSTANTS} = require('@jope-io/ecobee');

const ecobee = new ECOBEE({
  key: 'example-key'
});

(async () => {
  // Generate application PIN
  const pin = await ecobee.generatePIN(ECOBEE_CONSTANTS.SCOPE.WRITE);

  console.log('Generated PIN:', pin); // => add to your applications on your account

  // Poll and wait for PIN to be added
  // (returned access token is automatically saved in class instance)
  const token = await ecobee.waitForPIN({authCode: pin.code});

  console.log('Generated token:', token); // => generated OAuth token (save the refresh token somewhere)

  const thermostats = await ecobee.getThermostats({
    selection: {
      registered: true,
      selectionType: 'registered',
      includeSettings: true
    }
  });

  console.log(thermostats); // => thermostats associated with user's account
})();

Docs

Table of Contents

ECOBEE

The ecobee class.

Parameters

  • options Object (optional, default {})
    • options.key String API key
    • options.token String OAuth access token
    • options.url String? base URL to use for requests (optional, default 'https://api.ecobee.com/')
    • options.version Number? version of API (optional, default 1)

Examples

const ecobee = new ECOBEE({key: 'example-key', token: 'example-token'});

generatePIN

Generates a PIN for PIN-based authentication.

Parameters
  • scope String? scope that generated PIN should have (optional, default CONSTANTS.SCOPE.WRITE)
Examples
const pin = await ecobee.generatePIN();

Returns Object

checkPINStatus

Checks whether a PIN has been granted access to the associated user's account. Throws error if the PIN has not been added.

Parameters
  • authCode String authentication code from the generated PIN
Examples
const token = await ecobee.checkPINStatus('example-auth-code');

Returns Object OAuth token object

getTokenByCode

Gets token by an authorization code.

Parameters
  • authCode String authorization code
  • redirectURI String the redirect URI of your token grant flow
Examples
const token = await ecobee.getTokenByCode('example-auth-code');

Returns Object OAuth token object

waitForPIN

Recursive helper function that polls checkPINStatus(). Use after generating a PIN and waiting for a user to add it.

Parameters
  • authCode String authentication code from the generated PIN
  • options Object (optional, default {})
    • options.interval Number interval, in seconds, to wait between polls (optional, default 1)
    • options.maxAttempts Number maximum number of polls to make before throwing an error (optional, default 100)
  • attempts Number (for internal use, do not use) (optional, default 0)
Examples
const pin = await ecobee.generatePIN(CONSTANTS.SCOPE.WRITE);

console.log(pin); // => add to your applications

const token = await ecobee.waitForPIN({authCode: pin.code});

console.log(token);

Returns Object OAuth token object

refreshToken

Refreshes an OAuth token.

Parameters
Examples
const newToken = await ecobee.refreshToken('example-refresh-token');

Returns Object OAuth token object

setToken

Sets the OAuth access token that's used when making requests.

Parameters

pollThermostatsRaw

Polls thermostats to get when they were last changed. This directly maps to the ecobee API. For most cases, you'll want to use pollThermostats() instead.

Parameters
Examples
const revisions = await ecobee.pollThermostatsRaw({
  registered: true,
  selectionType: 'registered'
});

console.log(revisions);

Returns Object

pollThermostats

Polls thermostats to get when they where last changed. This is a helper function that wraps pollThermostatsRaw(), and returns an object where the keys are device identifiers.

Parameters
Examples
const revisions = await ecobee.pollThermostatsRaw({
  registered: true,
  selectionType: 'registered'
});

console.log(revisions);

Returns Object

getThermostatsRaw

Gets details of thermostats. This directly maps to the ecobee API. For most cases, you'll want to use getThermostats() instead.

Parameters
  • options Object (optional, default {})
Examples
const thermostats = await ecobee.getThermostatsRaw({
  selection: {
    registered: true,
    selectionType: 'registered',
    includeSettings: true
  }
});

console.log(thermostats);

Returns Object

getThermostats

Gets details of thermostats. This is a helper function that wraps getThermostatsRaw(), and returns an object where the keys are device identifiers.

Parameters
  • options Object (optional, default {})
Examples
const thermostats = await ecobee.getThermostats({
  selection: {
    registered: true,
    selectionType: 'registered',
    includeSettings: true
  }
});

console.log(thermostats);

Returns Object

updateThermostatsRaw

Updates properties of thermostat(s).

Parameters
  • options Object (optional, default {})
    • options.selection Object ecobee Selection object
    • options.settings Object settings to update the thermostat with (named the thermostat property in the ecobee docs) (optional, default {})
    • options.functions Array special functions to apply (optional, default [])
Examples
const update = await ecobee.updateThermostatsRaw({
  selection: {
    selectionType: 'thermostats',
    selectionMatch: '101010101010'
  },
  settings: {
    hvacMode: 'off'
  }
});

console.log(update);

Returns Object

updateThermostats

Update properties of thermostat(s). Helper function that wraps updateThermostatsRaw() to easily update properties by thermostat identifiers.

Parameters
  • options Object (optional, default {})
    • options.identifiers Array thermostat identifiers to select
    • options.settings Object settings to update the thermostat(s) with (named the thermostat property in the ecobee docs) (optional, default {})
    • options.functions Array special functions to apply (optional, default [])
Examples
const update = await ecobee.updateThermostats({
  identifiers: ['101010101010'],
  settings: {
    hvacMode: 'off'
  }
});

console.log(update);

Returns Object