myq-api-2 v0.0.4

myq-api

Interface with your MyQ devices. Works and tested with both Chamberlain and LiftMaster.

NOTE: This package is currently not working. A new update will be released after this pull request is merged in.

Installation

yarn add myq-api   or   npm install myq-api

Usage Overview

new MyQ(email, password)

Initialize credentials of the user using email and password.

Example code:

var { myQ, constants } = require('myq-api');
var account = new myQ('email', 'password');

account.login()

Logs into the MyQ account and generates a security token. This security token must be generated before you access the rest of this API. Note that this security token is short-term and will not work after some time.

Example code:

account.login()
  .then(function (result) {
    console.log(result);
  }).catch(function (err) {
    console.error(err);
  });

Example returned object if call is successful:

{
  "returnCode": 0,
  "token": "abcd1234-a1b2-ab12-a1b2-abcdef123456"
}

account.getDevices(typeIds)

Returns devices on the account. A (very incomplete) list of possible Type names are provided as constants. See Possible Values for more information.

Example code:

// Optionally, pass in device types to filter them.
// If none are specified, all devices will be returned.
// [WIP]: Fix this.
account.getDevices([
  constants.allDeviceTypes.hub,
  constants.allDeviceTypes.virtualGarageDoorOpener
])
  .then(function (result) {
    console.log(result);
  }).catch(function (err) {
    console.error(err);
  });

Example returned object if call is successful:

{
  returnCode: 0,
  devices: [
    {
      family: 'garagedoor',
      name: 'Garage Door Opener',
      type: 'virtualgaragedooropener',
      serialNumber: '123456ABCDEF',
      online: true,
      doorState: 'closed',
      doorStateUpdated: '12/1/2019, 8:20:18 PM'
    },
    {
      family: 'gateway',
      name: 'Hub',
      type: 'hub',
      serialNumber: 'ABCDEF123456',
      online: true
    }
  ]
}

account.getDoorState(id)

Retrieves the latest state of the requested door.

Example code:

account.getDoorState(door.serialNumber)
  .then(function (result) {
    console.log(result);
  }).catch(function (err) {
    console.error(err);
  });

Example returned object if call is successful:

{
  "returnCode": 0,
  "doorState": "closed" // See Possible Values
}

account.getLightState(id)

Retrieves the latest state of the requested light.

Example code:

account.getLightState(light.id)
  .then(function (result) {
    console.log(result);
  }).catch(function (err) {
    console.error(err);
  });

Example returned object if call is successful:

{
  "returnCode": 0,
  "lightState": "on" // See Possible Values
}

account.setDoorOpen(serialNumber, shouldOpen)

Set the requested door to open or close. Returns a confirmation once complete. Note that the door might not be opened or closed fully by the time this function returns.

Example code:

account.setDoorState(door.serialNumber, true)
  .then(function (result) {
    console.log(result);
  }).catch(function (err) {
    console.error(err);
  });

Example returned object if call is successful:

{
  "returnCode": 0
}

account.setLightState(id, toggle)

Set the requested light to on or off. Returns a confirmation once complete.

Example code:

account.setLightState(light.serialNumber, 1)
  .then(function (result) {
    console.log(result);
  }).catch(function (err) {
    console.error(err);
  });

Example returned object if call is successful:

{
  "returnCode": 0
}

Possible Values

This is a (partial) list of the types of devices that MyQ supports. MyQ no longer returns on Type IDs, but rather, returns (mostly) human-readable strings. Constants for these are provided for your convenience.

Pull requests are welcome to add other device types :)

Return Codes

Each call to the API will include a return code as well as an error message if applicable. The return codes as well their correlated messages have been listed here for convenience.

Example returned object if call is unsuccessful:

{
  returnCode: 14,
  message: "Email and/or password are incorrect."
}

Since the underlying MyQ API is volatile, there might be changes unforeseen by the current version of this software. An extra message detailing the request error that it encountered will be returned whenever possible.

{
  returnCode: 11,
  message: "Something unexpected happened. Please wait a bit and try again."
  unhandledError: // request error
}

Please create a GitHub issue when this happens.

Promises

This API depends on a native ES6 Promise implementation to be supported. If your environment doesn't support ES6 Promises, you can polyfill.

Contributing

If you would like to contribute enhancements or fixes, please do the following: 1. Fork the repository and clone it locally. 2. Make your changes. 3. Create a pull request.

Authors

• Thomas Munduchira (thomas@thomasmunduchira.com)
• Chad Smith (chad@nospam.me)
• Nathan Snyder (nathan@snydern.com)

License

MIT