diff --git a/README.md b/README.md index d4d0ed9..f99ce3b 100644 --- a/README.md +++ b/README.md @@ -36,18 +36,18 @@ This should report the current status, set the device to the opposite of what it See the [setup instructions](docs/SETUP.md) for how to find the needed parameters. -## Docs +## 📓 Docs See the [docs](docs/API.md). + **IMPORTANT**: Only one TCP connection can be in use with a device at once. If testing this, do not have the app on your phone open. ## TODO 3. Better documentation. -4. Support arbitrary control schemes for devices as self-reported. -5. Use Promises for all functions? 7. Add automated tests 8. Document details of protocol +9. Add error message for no IP ## Contributors diff --git a/docs/API.md b/docs/API.md index 96a005d..93dc25e 100644 --- a/docs/API.md +++ b/docs/API.md @@ -8,7 +8,6 @@ Docs - [resolveIds](#resolveids) - [get](#get) - [set](#set) - - [\_extractJSON](#_extractjson) ## TuyaDevice @@ -17,13 +16,25 @@ Represents a Tuya device. **Parameters** - `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options for constructing a TuyaDevice - - `options.type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** type of device (optional, default `'outlet'`) - - `options.ip` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** IP of device - - `options.port` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** port of device (optional, default `6668`) - - `options.id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** ID of device - - `options.uid` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** UID of device (optional, default `''`) - - `options.key` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** encryption key of device - - `options.version` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** protocol version (optional, default `3.1`) + - `options.type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** type of device (optional, default `'outlet'`) + - `options.ip` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** IP of device + - `options.port` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** port of device (optional, default `6668`) + - `options.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** ID of device + - `options.uid` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** UID of device (optional, default `''`) + - `options.key` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** encryption key of device + - `options.version` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** protocol version (optional, default `3.1`) + +**Examples** + +```javascript +const tuya = new TuyaDevice({id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}) +``` + +```javascript +const tuya = new TuyaDevice([ +{id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}, +{id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}]) +``` ### resolveIds @@ -33,13 +44,33 @@ Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe ### get -Gets the device's current status. Defaults to returning only the first 'dps', but by setting {schema: true} you can get everything. +Gets the device's current status. Defaults to returning only the value of the first result, +but by setting {schema: true} you can get everything. **Parameters** -- `options` -- `ID` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** optional, ID of device. Defaults to first device. -- `callback` **function ([error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error), result)** +- `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** optional options for getting data + - `options.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** ID of device + - `options.schema` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** true to return entire schema, not just the first result + +**Examples** + +```javascript +// get status for device with one property +tuya.get().then(status => console.log(status)) +``` + +```javascript +// get status for specific device with one property +tuya.get({id: 'xxxxxxxxxxxxxxxxxxxx'}).then(status => console.log(status)) +``` + +```javascript +// get all available data from device +tuya.get({schema: true}).then(data => console.log(data)) +``` + +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** returns boolean if no options are provided, otherwise returns object of results ### set @@ -47,18 +78,21 @@ Sets the device's status. **Parameters** -- `options` -- `on` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` for on, `false` for off - {id, set: true|false, dps:1} -- `callback` **function ([error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error), result)** returns `true` if the command succeeded - -### \_extractJSON +- `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options for setting properties + - `options.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** ID of device + - `options.set` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` for on, `false` for off + - `options.dps` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** dps index to change -Extracts JSON from a raw buffer and returns it as an object. +**Examples** -**Parameters** +```javascript +// set default property on default device +tuya.set({set: true}).then(() => console.log('device was changed')) +``` -- `data` -- `buffer` **[Buffer](https://nodejs.org/api/buffer.html)** of data +```javascript +// set custom property on non-default device +tuya.set({id: 'xxxxxxxxxxxxxxxxxxxx', 'dps': 2, set: true}).then(() => console.log('device was changed')) +``` -Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** extracted object +Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)>** returns `true` if the command succeeded diff --git a/index.js b/index.js index 639ee03..e58555e 100644 --- a/index.js +++ b/index.js @@ -11,15 +11,21 @@ const requests = require('./requests.json'); /** * Represents a Tuya device. -* @constructor +* @class * @param {Object} options - options for constructing a TuyaDevice -* @param {string} [options.type='outlet'] - type of device -* @param {string} options.ip - IP of device -* @param {number} [options.port=6668] - port of device -* @param {string} options.id - ID of device -* @param {string} [options.uid=''] - UID of device -* @param {string} options.key - encryption key of device -* @param {number} [options.version=3.1] - protocol version +* @param {String} [options.type='outlet'] - type of device +* @param {String} [options.ip] - IP of device +* @param {Number} [options.port=6668] - port of device +* @param {String} options.id - ID of device +* @param {String} [options.uid=''] - UID of device +* @param {String} options.key - encryption key of device +* @param {Number} [options.version=3.1] - protocol version +* @example +* const tuya = new TuyaDevice({id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}) +* @example +* const tuya = new TuyaDevice([ +* {id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}, +* {id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}]) */ function TuyaDevice(options) { this.devices = []; @@ -51,7 +57,8 @@ function TuyaDevice(options) { } /** -* Resolves IDs stored in class to IPs. +* Resolves IDs stored in class to IPs. If you didn't pass IPs to the constructor, +* you must call this before doing anything else. * @returns {Promise} - true if IPs were found and devices are ready to be used */ TuyaDevice.prototype.resolveIds = function () { @@ -96,9 +103,21 @@ TuyaDevice.prototype.resolveIds = function () { }; /** -* Gets the device's current status. Defaults to returning only the first 'dps', but by setting {schema: true} you can get everything. -* @param {string} ID - optional, ID of device. Defaults to first device. -* @param {function(error, result)} callback +* Gets the device's current status. Defaults to returning only the value of the first result, +* but by setting {schema: true} you can get everything. +* @param {Object} [options] - optional options for getting data +* @param {String} [options.id] - ID of device +* @param {Boolean} [options.schema] - true to return entire schema, not just the first result +* @example +* // get status for device with one property +* tuya.get().then(status => console.log(status)) +* @example +* // get status for specific device with one property +* tuya.get({id: 'xxxxxxxxxxxxxxxxxxxx'}).then(status => console.log(status)) +* @example +* // get all available data from device +* tuya.get({schema: true}).then(data => console.log(data)) +* @returns {Promise} - returns boolean if no options are provided, otherwise returns object of results */ TuyaDevice.prototype.get = function (options) { let currentDevice; @@ -145,9 +164,17 @@ TuyaDevice.prototype.get = function (options) { /** * Sets the device's status. -* @param {boolean} on - `true` for on, `false` for off -* {id, set: true|false, dps:1} -* @param {function(error, result)} callback - returns `true` if the command succeeded +* @param {Object} options - options for setting properties +* @param {String} [options.id] - ID of device +* @param {Boolean} options.set - `true` for on, `false` for off +* @param {Number} [options.dps] - dps index to change +* @example +* // set default property on default device +* tuya.set({set: true}).then(() => console.log('device was changed')) +* @example +* // set custom property on non-default device +* tuya.set({id: 'xxxxxxxxxxxxxxxxxxxx', 'dps': 2, set: true}).then(() => console.log('device was changed')) +* @returns {Promise} - returns `true` if the command succeeded */ TuyaDevice.prototype.set = function (options) { let currentDevice; @@ -261,6 +288,7 @@ TuyaDevice.prototype._constructBuffer = function (type, data, command) { /** * Extracts JSON from a raw buffer and returns it as an object. +* @private * @param {Buffer} buffer of data * @returns {Object} extracted object */