@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
  • Parameters
  • Examples
  • generatePIN
    • Parameters
    • Examples
  • checkPINStatus
    • Parameters
    • Examples
  • getTokenByCode
    • Parameters
    • Examples
  • waitForPIN
    • Parameters
    • Examples
  • refreshToken
    • Parameters
    • Examples
  • setToken
    • Parameters
  • pollThermostatsRaw
    • Parameters
    • Examples
  • pollThermostats
    • Parameters
    • Examples
  • getThermostatsRaw
    • Parameters
    • Examples
  • getThermostats
    • Parameters
    • Examples
  • updateThermostatsRaw
    • Parameters
    • Examples
  • updateThermostats
    • Parameters
    • Examples

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

• refreshToken String

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

• token String access token

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

• selection Object ecobee Selection object

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

• selection Object ecobee Selection object

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 {})
  • options.selection Object ecobee Selection object
  • options.page Number? page number of results to return

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 {})
  • options.selection Object ecobee Selection object
  • options.page Number? page number of results to return

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