diff --git a/README.md b/README.md index bfe5483..7559fb4 100644 --- a/README.md +++ b/README.md @@ -3,157 +3,278 @@ Node-NUT is a NodeJS module that implements a NUT (Network UPS Tools) client. ## Version compatibility information -v1.0.0 introduce callbacks into all functions including a second "error" parameter. This error parameter is null on success or a text on error. Please see the updated method documentation below. -This change should not break existing code because you can simply ignore the second parameter, but there is one change coming with it: +v2 introduces new method names and Promises for certain functions. Please refer to the API below. -When with v0.0.x an error occured in one of the "Get-List-Of" methods then the callback was pot. never called at all. This has changed now because now the callback is also called in errorcases, but then with an empty object/list in return. So you may want to include error handling code that not strange things happens in error cases. +## API + -## Events +### Nut +**Kind**: global class -### ready +* [Nut](#Nut) + * [new Nut([port], [host])](#new_Nut_new) + * [.connected](#Nut+connected) : boolean + * [.connect()](#Nut+connect) ⇒ Promise + * [.disconnect()](#Nut+disconnect) + * [.getUpsList([callback])](#Nut+getUpsList) ⇒ Promise.<object> + * [.getUpsVars(ups, [callback])](#Nut+getUpsVars) ⇒ Promise.<object> + * [.getUpsCommands(ups, [callback])](#Nut+getUpsCommands) ⇒ Promise.<object> + * [.getRwVars(ups, [callback])](#Nut+getRwVars) ⇒ Promise.<object> + * [.getEnumsForVar(ups, name, [callback])](#Nut+getEnumsForVar) ⇒ Promise.<object> + * [.getRangesForVar(ups, name, [callback])](#Nut+getRangesForVar) ⇒ Promise.<object> + * [.getVarType(ups, name, [callback])](#Nut+getVarType) ⇒ Promise.<object> + * [.getVarDescription(ups, name, [callback])](#Nut+getVarDescription) ⇒ Promise.<object> + * [.getCommandDescription(ups, command, [callback])](#Nut+getCommandDescription) ⇒ Promise.<object> + * [.nutSetRwVar(ups, name, value, [callback])](#Nut+nutSetRwVar) ⇒ Promise.<object> + * [.runUpsCommand(ups, command, [callback])](#Nut+runUpsCommand) ⇒ Promise.<object> + * [.setUsername(username, [callback])](#Nut+setUsername) ⇒ Promise.<object> + * [.setPassword(password, [callback])](#Nut+setPassword) ⇒ Promise.<object> + * [.master(ups, [callback])](#Nut+master) ⇒ Promise.<object> + * [.fsd(ups, [callback])](#Nut+fsd) ⇒ Promise.<object> + * [.help([callback])](#Nut+help) ⇒ Promise.<object> + * [.ver([callback])](#Nut+ver) ⇒ Promise.<object> + * [.netVer([callback])](#Nut+netVer) ⇒ Promise.<object> + * [.listClients(ups, [callback])](#Nut+listClients) ⇒ Promise.<object> -This event is emitted when the connection to the NUT server is established. + -### error +#### new Nut([port], [host]) +Create an instance of Nut to use with the provided upsd instance at host:port -Emitted when there was an error establishing the connection or with the network communication to -the server. -### close +| Param | Type | +| --- | --- | +| [port] | number | +| [host] | string | -Emitted when the connection to the NUT server is closed. + -## Functions (tested) +#### nut.connected : boolean +Gets current connection state -### `start()` +**Kind**: instance property of [Nut](#Nut) + -Starts the connection to the server. +#### nut.connect() ⇒ Promise +Connect to upsd instance. -### `GetUPSList (callback)` +**Kind**: instance method of [Nut](#Nut) +**Returns**: Promise - Connection established. + -Calls the `callback` function with the list of UPS as an object as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -Keys in the object are the UPS names and the values are the provided description for this UPS. +#### nut.disconnect() +Use to disconnect manually inbetween polling cycles when polling with very low frequencies. For e.g. `upslog` disconnects [if the polling cycle is >30s](https://github.com/networkupstools/nut/blob/d56ac7712fa6c3920460a08c649ad03d2c2e82e7/clients/upslog.c#L526). -### `GetUPSVars (upsname, callback)` +**Kind**: instance method of [Nut](#Nut) + -Calls the `callback` function with the list of VARs of `upsname` as an object as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -Keys in the object are the VAR names and the values are the current VAR values. +#### nut.getUpsList([callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) +**Returns**: Promise.<object> - Object containing key-value pairs of upsId -> description. -### `GetUPSCommands (upsname, callback)` +| Param | Type | Description | +| --- | --- | --- | +| [callback] | function | Provide either a callback function or use the returned promise | -Calls the `callback` function with the list of COMMANDs available in `upsname` as an array as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -The values in the array are the available COMMANDs. + -### `GetCommandDescription (upsname, cmdname, callback)` +#### nut.getUpsVars(ups, [callback]) ⇒ Promise.<object> +Get variables for a certain UPS. -Calls the `callback` function with the description for the given `cmdname` as a string as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -The description is returned as string. +**Kind**: instance method of [Nut](#Nut) +**Returns**: Promise.<object> - Object containing key-value list of availabla variables. For e.g. `battery.charge`. -### `RunUPSCommand (upsname, command, callback)` +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| [callback] | function | Provide either a callback function or use the returned promise | -Rund the COMMAND given by `command`. The callback is called with one parameter `err` which is null on success or contains an error string on error and can be used to check the result of the call. + -***Note: Some commands need to set Username and Password before, else it returns an Error! Please consult the documentation of your UPS system.*** +#### nut.getUpsCommands(ups, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -### `SetUsername (username, callback)` +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| [callback] | function | Provide either a callback function or use the returned promise | -Set the password for the connection. The callback is called with one parameter `err` which is null on success or contains an error string on error and can be used to check the result of the call. + -***Note: Incorrect values may not generate an error when setting the username, but when executing the command later on!*** +#### nut.getRwVars(ups, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -### `SetPassword (password, callback)` +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| [callback] | function | Provide either a callback function or use the returned promise | -Set the password for the connection. The callback is called with one parameter `err` which is null on success or contains an error string on error and can be used to check the result of the call. + -***Note: Incorrect values may not generate an error when setting the password, but when executing the command later on!*** +#### nut.getEnumsForVar(ups, name, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -### `GetRWVars (upsname, callback)` +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| name | string | Variable name | +| [callback] | function | Provide either a callback function or use the returned promise | -Calls the `callback` function with the list of RW-VARs of `upsname` as an object as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -Keys in the object are the RW-VAR names and the values are the current RW-VAR values. + -### `SetRWVar (upsname, varname, value, callback)` +#### nut.getRangesForVar(ups, name, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -Set the value of the RW-VAR given by `varname`. The callback is called with one parameter `err` which is null on success or contains an error string on error and can be used to check the result of the call. +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| name | string | Variable name | +| [callback] | function | Provide either a callback function or use the returned promise | -### `GetVarType (upsname, varname, callback)` + -Calls the `callback` function with the type for the given `varname` as a string as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. +#### nut.getVarType(ups, name, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -The following types are defined, and multiple words may be returned: -* RW: this variable may be set to another value with SET -* ENUM: an enumerated type, which supports a few specific values -* STRING:n: this is a string of maximum length n -* RANGE: this is an numeric, either integer or float, comprised in the range (see LIST RANGE) -* NUMBER: this is a simple numeric value, either integer or float : +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| name | string | Variable name | +| [callback] | function | Provide either a callback function or use the returned promise | -For more details see http://networkupstools.org/docs/developer-guide.chunked/ar01s09.html#_type + -### `GetVarDescription (upsname, varname, callback)` +#### nut.getVarDescription(ups, name, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -Calls the `callback` function with the description for the given `varname` as a string as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -The description is returned as string. +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| name | string | Variable name | +| [callback] | function | Provide either a callback function or use the returned promise | -### `GetEnumsForVar (upsname, varname, callback)` + -Calls the `callback` function with the list of allowed ENUM values for the given `varname` as an array as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -The values in the array are the available ENUMs. +#### nut.getCommandDescription(ups, command, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -### `GetRangesForVar (upsname, varname, callback)` +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| command | string | Command name | +| [callback] | function | Provide either a callback function or use the returned promise | -Calls the `callback` function with the list of allowed RANGEs for the values for the given `varname` as an array as the first parameter. If the second parameter is not null then an error happened and the first object is returned as null. -The values in the array are objects with the keys `min` and `max` for the various ranges. + -### `Master (upsname, callback)` +#### nut.nutSetRwVar(ups, name, value, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -Send the MASTER command to the given `upsname`. The callback is called with one parameter `err` which is null on success or contains an error string on error and can be used to check the result of the call. +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| name | string | Variable name | +| value | string | Value to set | +| [callback] | function | Provide either a callback function or use the returned promise | -### `FSD (upsname, callback)` + -Send the FSD command to the given `upsname`. The callback is called with one parameter `err` which is null on success or contains an error string on error and can be used to check the result of the call. +#### nut.runUpsCommand(ups, command, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -### `ListClients (upsname)` +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| command | string | Command name | +| [callback] | function | Provide either a callback function or use the returned promise | -### `help(callback)` + -Call the `callback` function with the result of the command `help` as a string. +#### nut.setUsername(username, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -### `ver (callback)` +| Param | Type | Description | +| --- | --- | --- | +| username | string | Login with provided username | +| [callback] | function | Provide either a callback function or use the returned promise | -Call the `callback` function with the version of the server as a string. + -### `netVer (callback)` +#### nut.setPassword(password, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) -Call the `callback` function with the version of the network protocol as a string. +| Param | Type | Description | +| --- | --- | --- | +| password | string | Login with provided password | +| [callback] | function | Provide either a callback function or use the returned promise | + -## Example +#### nut.master(ups, [callback]) ⇒ Promise.<object> +Gain master privileges for this connection. You have to login with a username/password combination first. -```javascript -var Nut = require('node-nut'); +**Kind**: instance method of [Nut](#Nut) -oNut = new Nut(3493, 'localhost'); +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| [callback] | function | Provide either a callback function or use the returned promise | -oNut.on('error', function(err) { - console.log('There was an error: ' + err); -}); + -oNut.on('close', function() { - console.log('Connection closed.'); -}); +#### nut.fsd(ups, [callback]) ⇒ Promise.<object> +Execute FSD (you must be master to do this) -oNut.on('ready', function() { - self = this; - this.GetUPSList(function(upslist, err) { - if (err) console.log('Error: ' + err) - console.log(upslist); - self.close(); - }); -}); +**Kind**: instance method of [Nut](#Nut) + +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| [callback] | function | Provide either a callback function or use the returned promise | + + + +#### nut.help([callback]) ⇒ Promise.<object> +Send `HELP` command. + +**Kind**: instance method of [Nut](#Nut) + +| Param | Type | Description | +| --- | --- | --- | +| [callback] | function | Provide either a callback function or use the returned promise | + + + +#### nut.ver([callback]) ⇒ Promise.<object> +Send `VER` command. + +**Kind**: instance method of [Nut](#Nut) + +| Param | Type | Description | +| --- | --- | --- | +| [callback] | function | Provide either a callback function or use the returned promise | + + + +#### nut.netVer([callback]) ⇒ Promise.<object> +Send `NETVER` command. + +**Kind**: instance method of [Nut](#Nut) + +| Param | Type | Description | +| --- | --- | --- | +| [callback] | function | Provide either a callback function or use the returned promise | + + + +#### nut.listClients(ups, [callback]) ⇒ Promise.<object> +**Kind**: instance method of [Nut](#Nut) + +| Param | Type | Description | +| --- | --- | --- | +| ups | string | UPS identifier | +| [callback] | function | Provide either a callback function or use the returned promise | -oNut.start(); -``` ## Links diff --git a/docs/README.footer.md b/docs/README.footer.md new file mode 100644 index 0000000..460b968 --- /dev/null +++ b/docs/README.footer.md @@ -0,0 +1,8 @@ + +## Development + +Run `npm run docs` to 'rebuild' README file. + +## Links + +Protocol: http://networkupstools.org/docs/developer-guide.chunked/ar01s09.html diff --git a/docs/README.header.md b/docs/README.header.md new file mode 100644 index 0000000..b109867 --- /dev/null +++ b/docs/README.header.md @@ -0,0 +1,9 @@ +# Node-NUT + +Node-NUT is a NodeJS module that implements a NUT (Network UPS Tools) client. + +## Version compatibility information + +v2 introduces new method names and Promises for certain functions. Please refer to the API below. + +## API diff --git a/examples/basic.js b/examples/basic.js index 1d4cee7..42df343 100644 --- a/examples/basic.js +++ b/examples/basic.js @@ -1,4 +1,4 @@ -var Nut = require('../node-nut'); +var Nut = require('../index'); nut = new Nut(3493, '10.30.21.11'); @@ -6,22 +6,22 @@ nut.on('error', err => { console.log('There was an error: ' + err); }); -nut.on('close', () => { +nut.on('disconnect', () => { console.log('Connection closed.'); }); -nut.on('ready', () => { - nut.GetUPSList((upslist, err) => { +nut.on('connect', () => { + nut.getUpsList((upslist, err) => { if (err) console.log('Error: ' + err) console.log(upslist); let upsname = Object.keys(upslist)[0]; - nut.GetUPSVars(upsname, (vars, err) => { + nut.getUpsVars(upsname, (vars, err) => { if (err) console.err('Error:', err); console.log(vars); }); }); }); -nut.start(); \ No newline at end of file +nut.connect(); \ No newline at end of file diff --git a/examples/polling.js b/examples/polling.js new file mode 100644 index 0000000..eaf0e5c --- /dev/null +++ b/examples/polling.js @@ -0,0 +1,32 @@ +var Nut = require('../index'); + +nut = new Nut(3493, '10.30.21.11'); + +nut.on('error', err => { + console.log('There was an error: ' + err); +}); + +nut.on('disconnect', () => { + console.log('Connection closed.'); +}); + +const interval = 10; + +async function pollOnce() { + if (!nut.connected) { + await nut.connect(); + } + + let upslist = await nut.getUpsList(); + let upsname = Object.keys(upslist)[0]; + + let vars = await nut.getUpsVars(upsname); + console.log('Battery left: ' + vars['battery.charge'] + '%'); + + if (interval > 30) { + nut.disconnect(); + } +} + +setInterval(pollOnce, interval * 1000); +pollOnce(); \ No newline at end of file diff --git a/examples/promises.js b/examples/promises.js index a10dd30..ea69706 100644 --- a/examples/promises.js +++ b/examples/promises.js @@ -1,4 +1,4 @@ -var Nut = require('../node-nut'); +var Nut = require('../index'); nut = new Nut(3493, '10.30.21.11'); @@ -6,14 +6,14 @@ nut.on('error', err => { console.log('There was an error: ' + err); }); -nut.on('close', () => { +nut.on('disconnect', () => { console.log('Connection closed.'); }); -nut.start().then(async () => { - let upslist = await nut.GetUPSList(); +nut.connect().then(async () => { + let upslist = await nut.getUpsList(); let upsname = Object.keys(upslist)[0]; - let vars = await nut.GetUPSVars(upsname); + let vars = await nut.getUpsVars(upsname); console.log(vars); }); \ No newline at end of file diff --git a/node-nut.js b/index.js similarity index 67% rename from node-nut.js rename to index.js index 64a39eb..979f90c 100644 --- a/node-nut.js +++ b/index.js @@ -2,6 +2,11 @@ const net = require('net'); const EventEmitter = require('events'); class Nut extends EventEmitter { + /** + * Create an instance of Nut to use with the provided upsd instance at host:port + * @param {number} [port] + * @param {string} [host] + */ constructor(port, host) { super(); this._port = port; @@ -28,18 +33,36 @@ class Nut extends EventEmitter { } }); + this._connected = false; + this._client.on('connect', () => { + this._connected = true; + this.emit('connect'); + }); this._client.on('error', err => { + this._connected = false; this.emit('error', err); }); - this._client.on('close', () => { - this.emit('close'); + this._client.on('close', hadError => { + this._connected = false; + this.emit('disconnect', hadError); }); } - start() { + /** + * Gets current connection state + * @type {boolean} + */ + get connected() { + return this._connected; + } + + /** + * Connect to upsd instance. + * @return {Promise} Connection established. + */ + connect() { return new Promise(resolve => { this._client.connect(this._port, this._host, () => { - this.emit('ready'); resolve(); }); }); @@ -55,7 +78,10 @@ class Nut extends EventEmitter { } } - close() { + /** + * Use to disconnect manually inbetween polling cycles when polling with very low frequencies. For e.g. `upslog` disconnects [if the polling cycle is >30s](https://github.com/networkupstools/nut/blob/d56ac7712fa6c3920460a08c649ad03d2c2e82e7/clients/upslog.c#L526). + */ + disconnect() { this.send('LOGOUT'); this._client.end(); } @@ -105,18 +131,28 @@ class Nut extends EventEmitter { } } - GetUPSList(callback) { - return this._callbackOrPromise(callback, callback => { + /** + * @param {Function} [callback] Provide either a callback function or use the returned promise + * @return {Promise} Object containing key-value pairs of upsId -> description. + */ + getUpsList(callback) { + return this._callbackOrPromise(callback, proc => { this.send('LIST UPS', data => { this._parseKeyValueList(data, 'UPS', /^UPS\s+(.+)\s+"(.*)"/, (vars, err) => { this.status = 'idle'; - callback(vars, err); + proc(vars, err); }); }); }); } - GetUPSVars(ups, callback) { + /** + * Get variables for a certain UPS. + * @param {string} ups - UPS identifier + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} Object containing key-value list of availabla variables. For e.g. `battery.charge`. + */ + getUpsVars(ups, callback) { return this._callbackOrPromise(callback, callback => { this.send('LIST VAR ' + ups, data => { this._parseKeyValueList(data, 'VAR', /^VAR\s+.+\s+(.+)\s+"(.*)"/, (vars, err) => { @@ -127,7 +163,13 @@ class Nut extends EventEmitter { }); } - GetUPSCommands(ups, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getUpsCommands(ups, callback) { return this._callbackOrPromise(callback, callback => { this.send('LIST CMD ' + ups, data => { if (!data) { @@ -158,7 +200,13 @@ class Nut extends EventEmitter { }); } - GetRWVars(ups, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getRwVars(ups, callback) { return this._callbackOrPromise(callback, callback => { this.send('LIST RW ' + ups, function (data) { this._parseKeyValueList(data, 'RW', /^RW\s+.+\s+(.+)\s+"(.*)"/, (vars, err) => { @@ -169,7 +217,14 @@ class Nut extends EventEmitter { }); } - GetEnumsForVar(ups, name, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} name - Variable name + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getEnumsForVar(ups, name, callback) { return this._callbackOrPromise(callback, callback => { this.send('LIST ENUM ' + ups + ' ' + name, data => { if (!data) { @@ -200,7 +255,14 @@ class Nut extends EventEmitter { }); } - GetRangesForVar(ups, name, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} name - Variable name + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getRangesForVar(ups, name, callback) { return this._callbackOrPromise(callback, callback => { this.send('LIST RANGE ' + ups + ' ' + name, data => { if (!data) { @@ -234,7 +296,14 @@ class Nut extends EventEmitter { }); } - GetVarType(ups, name, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} name - Variable name + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getVarType(ups, name, callback) { return this._callbackOrPromise(callback, callback => { this.send('GET TYPE ' + ups + ' ' + name, data => { if (!data) { @@ -255,7 +324,14 @@ class Nut extends EventEmitter { }); } - GetVarDescription(ups, name, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} name - Variable name + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getVarDescription(ups, name, callback) { return this._callbackOrPromise(callback, callback => { this.send('GET DESC ' + ups + ' ' + name, data => { if (!data) { @@ -276,7 +352,14 @@ class Nut extends EventEmitter { }); } - GetCommandDescription(ups, command, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} command - Command name + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + getCommandDescription(ups, command, callback) { return this._callbackOrPromise(callback, callback => { this.send('GET CMDDESC ' + ups + ' ' + command, data => { if (!data) { @@ -310,7 +393,15 @@ class Nut extends EventEmitter { } } - NutSetRWVar(ups, name, value, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} name - Variable name + * @param {string} value - Value to set + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + nutSetRwVar(ups, name, value, callback) { return this._callbackOrPromise(callback, callback => { this.send('SET VAR ' + ups + ' ' + name + ' ' + value, data => { this.status = 'idle'; @@ -319,7 +410,14 @@ class Nut extends EventEmitter { }); } - RunUPSCommand(ups, command, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {string} command - Command name + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + runUpsCommand(ups, command, callback) { return this._callbackOrPromise(callback, callback => { this.send('INSTCMD ' + ups + ' ' + command, data => { this.status = 'idle'; @@ -328,7 +426,13 @@ class Nut extends EventEmitter { }); } - SetUsername(username, callback) { + /** + * + * @param {string} username - Login with provided username + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + setUsername(username, callback) { return this._callbackOrPromise(callback, callback => { this.send('USERNAME ' + username, data => { this.status = 'idle'; @@ -337,7 +441,13 @@ class Nut extends EventEmitter { }); } - SetPassword(pwd, callback) { + /** + * + * @param {string} password - Login with provided password + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + setPassword(pwd, callback) { return this._callbackOrPromise(callback, callback => { this.send('PASSWORD ' + pwd, data => { this.status = 'idle'; @@ -346,7 +456,13 @@ class Nut extends EventEmitter { }); } - Master(ups, callback) { + /** + * Gain master privileges for this connection. You have to login with a username/password combination first. + * @param {string} ups - UPS identifier + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + master(ups, callback) { return this._callbackOrPromise(callback, callback => { this.send('MASTER ' + ups, data => { this.status = 'idle'; @@ -355,7 +471,13 @@ class Nut extends EventEmitter { }); } - FSD(ups, callback) { + /** + * Execute FSD (you must be master to do this) + * @param {string} ups - UPS identifier + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + fsd(ups, callback) { this.send('FSD ' + ups, data => { if (!data) { data = 'ERR Empty response'; @@ -374,6 +496,11 @@ class Nut extends EventEmitter { }); } + /** + * Send `HELP` command. + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ help(callback) { return this._callbackOrPromise(callback, callback => { this.send('HELP', data => { @@ -383,6 +510,11 @@ class Nut extends EventEmitter { }); } + /** + * Send `VER` command. + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ ver(callback) { return this._callbackOrPromise(callback, callback => { this.send('VER', data => { @@ -392,6 +524,11 @@ class Nut extends EventEmitter { }); } + /** + * Send `NETVER` command. + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ netVer(callback) { return this._callbackOrPromise(callback, callback => { this.send('NETVER', data => { @@ -401,7 +538,13 @@ class Nut extends EventEmitter { }); } - ListClients(ups, callback) { + /** + * + * @param {string} ups - UPS identifier + * @param {Function} [callback] - Provide either a callback function or use the returned promise + * @return {Promise} + */ + listClients(ups, callback) { return this._callbackOrPromise(callback, callback => { this.send('LIST CLIENT ' + ups, data => { if (!data) { diff --git a/package.json b/package.json index 73cf7dc..f19e663 100644 --- a/package.json +++ b/package.json @@ -5,26 +5,24 @@ "contributors": [ "Simon Christmann " ], - "main": "node-nut.js", - "files": [ - "node-nut.js" - ], + "main": "index.js", + "scripts": { + "test": "xo", + "docs": "cat docs/README.header.md > README.md ; jsdoc2md --heading-depth 3 -f index.js >> README.md ; cat docs/README.footer.md >> README.md" + }, "version": "1.0.3", "homepage": "https://github.com/skarcha/node-nut", "repository": { "type": "git", "url": "https://github.com/skarcha/node-nut.git" }, - "engines": { - "node": ">0.8.x", - "npm": ">1.1.x" - }, "keywords": [ "nut", "UPS", "power" ], "devDependencies": { + "jsdoc-to-markdown": "^5.0.2", "xo": "^0.25.3" }, "xo": {