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.

| Parameters | Required | Type | Details | |------------|----------|--------|-----------------| | email | true | String | User email | | password | true | String | User 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.

| Parameter | Required | Type | Details | |-----------|----------|-------------|---------| | typeIds | false | Type Name | Either an array of Type names or a singular Type name. |

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.

| Parameter | Required | Type | Details | |-----------|----------|---------|---------| | id | true | Integer | Door ID |

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.

| Parameter | Required | Type | Details | |-----------|----------|---------|----------| | id | true | Integer | Light ID |

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.

| Parameter | Required | Type | Details | |--------------|----------|-------------|-----------------------------------| | serialNumber | true | String | Serial number of the device | | toggle | true | Boolean | true or false |

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.

| Parameter | Required | Type | Details | |---------------|----------|--------------|---------------------------------------| | serialNumber | true | String | Light Serial Number | | turnOn | true | Boolean | Whether the light should be on or off |

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 :)

| Constant | Type Name | |-------------------------|----------------------------| | hub | hub | | virtualGarageDoorOpener | virtualgaragedooropener | | wifiGarageDoorOpener | wifigaragedooropener | | wifiGdoGateway | wifigdogateway |

| Type ID | Description | |---------|--------------------------------| | 1 | Gateway | | 2 | GDO | | 3 | Light | | 5 | Gate | | 7 | VGDO Garage Door | | 9 | Commercial Door Operator (CDO) | | 13 | Camera | | 15 | WGDO Gateway AC | | 16 | WGDO Gateway DC | | 17 | WGDO Garage Door |

| Door Toggle | Description | |-------------|-------------| | false | close door | | true | open door |

| doorState | Description | |-----------|-----------------------| | 1 | open | | 2 | closed | | 3 | stopped in the middle | | 4 | going up | | 5 | going down | | 9 | not closed |

| Light Toggle | Description | |--------------|----------------| | 0 | turn off light | | 1 | turn on light |

| lightState | Description | |--------------|-------------| | 0 | off | | 1 | on |

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.

| Return Code | Message | |-------------|---------------------------------------------------------------------------------| | 0 | Successful! | | 11 | Something unexpected happened. Please wait a bit and try again. | | 12 | MyQ service is currently down. Please wait a bit and try again. | | 13 | Not logged in. | | 14 | Email and/or password are incorrect. | | 15 | Invalid parameter(s) provided. | | 16 | User will be locked out due to too many tries. 1 try left. | | 17 | User is locked out due to too many tries. Please reset password and try again. |

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 ([email protected])
• Chad Smith ([email protected])
• Nathan Snyder ([email protected])

License

MIT