xcomfort-shc-api

Xcomfort

This module lets you send commands from node.js to the Xcomfort smart home controller(SHC) made by Eaton. It has no affiliation with Eaton, and is used at your own risk.

If you have xcomfort and a smart home controller at home, this module can be used to create custom software for your system. For example you can create a webpage customized for your home that controls your lighting instead of that generic app that ships with the SHC.

Install

npm install xcomfort-shc-api

Usage

For more details on usage see https://oanylund.github.io/xcomfort-shc-api and the API reference below.

const Xcomfort = require('xcomfort-shc-api');
 
const xapi = new Xcomfort({
  baseUrl: 'http://192.168.0.10', // The url to reach the SHC on your network
  username: 'user', // The username to login to the system
  password: '1234' // The password for that user
  autoSetup: true // Defaults to true.
});
 
xapi.on('ready', () => {
  xapi.setDimState('kitchen light', 20)
    .then((status) => {
      if(status) {
        console.log('Kitchen light set to 20%');
      }
    });
});

API reference

• Xcomfort ⇐ EventEmitter ⏏
  • new Xcomfort(params)
  • instance
    • .login()
    • .query(method, [params], [cb]) ⇒ Promise
    • .setDimState(deviceName, state, [cb]) ⇒ Promise
    • .dimBrighter(deviceName, cb) ⇒ Promise
    • .dimDarker(deviceName, cb) ⇒ Promise
    • .dimStop(deviceName, cb) ⇒ Promise
    • .triggerScene(sceneName, [cb]) ⇒ Promise
    • .getDeviceNames() ⇒ Array.<string>
    • .getSceneNames() ⇒ Array.<string>
    • .getNameObject() ⇒ Object
    • Event: "ready"
    • Event: "error"
  • inner
    • ~initialSetup()
    • ~getZoneDevices(zoneId) ⇒ Promise
    • ~getZoneScenes(zoneId) ⇒ Promise
    • ~importSetup(importPath)
    • ~getQueryParams(method, params) ⇒ Object
    • ~checkIfDeviceExists(deviceName, deviceType) ⇒ Promise
    • ~invokeDCOOperation(id, type, operation, params) ⇒ Promise
    • ~deviceDetail : object
    • ~sceneDetail : object
    • ~callback : function

Xcomfort ⇐ EventEmitter ⏏

Kind: Exported class
Extends: EventEmitter
Emits: error, ready
Properties

Name	Type	Description
baseUrl	string	baseUrl from params
username	string	username from params
password	string	password from params
sessionId	string	The session cookie from a valid login
deviceMap	Map.<string, module:Xcomfort~deviceDetail>	Map with all device details
sceneMap	Map.<string, module:Xcomfort~sceneDetail>	Map with all scene details

---

new Xcomfort(params)

Param	Type	Default	Description
params	object		config for the SHC
params.baseUrl	string		the url to your SHC
params.username	string		username to login to SHC
params.password	string		password to login to SHC
[params.autoSetup]	boolean	true	If true, class will login and setup device and scene map automatically
[params.importSetupPath]	object		Path to json setup file with device and scene maps

---

xcomfort.login()

Sends login request to SHC and stores cookie in sessionId

Kind: instance method of Xcomfort

---

xcomfort.query(method, [params], [cb]) ⇒ Promise

Request method to run on SHC RPC interface

Kind: instance method of Xcomfort
Returns: Promise - Resolves with result
See: http://dz.prosyst.com/pdoc/mBS_SDK_8.0/modules/hdm/api-json/json_rpc_all.html

Param	Type	Default	Description
method	string		Method to run
[params]	Array	['','']	Array with arguments for method
[cb]	callback		Callback (err,result)

---

xcomfort.setDimState(deviceName, state, [cb]) ⇒ Promise

Sets dimactuator to new state

Kind: instance method of Xcomfort
Returns: Promise - Resolves with true or false. True if SHC confirmed action

Param	Type	Description
deviceName	string	Name of device(same as configured on SHC). Not case sensitive
state	number | string	New state of device. Valid values are 0-100(integer) or 'on'/'off'
[cb]	callback	Callback with true or false result. True if SHC confirmed action

---

xcomfort.dimBrighter(deviceName, cb) ⇒ Promise

Tells DimActuator to start continously dimming brighter. How fast is configured on the device by the MRF software

Kind: instance method of Xcomfort
Returns: Promise - - Resolves undefined

Param	Type	Description
deviceName	String	Device name of DimActuator
cb	callback	Callback

---

xcomfort.dimDarker(deviceName, cb) ⇒ Promise

Tells DimActuator to start continously dimming darker. How fast is configured on the device by the MRF software

Kind: instance method of Xcomfort
Returns: Promise - - Resolves undefined

Param	Type	Description
deviceName	String	Device name of DimActuator
cb	callback	Callback

---

xcomfort.dimStop(deviceName, cb) ⇒ Promise

Tells DimActuator to stop the continous dimming.

Kind: instance method of Xcomfort
Returns: Promise - - Resolves undefined

Param	Type	Description
deviceName	String	Device name of DimActuator
cb	callback	Callback

---

xcomfort.triggerScene(sceneName, [cb]) ⇒ Promise

Triggers scene

Kind: instance method of Xcomfort
Returns: Promise - Resolves with true or false. True if SHC confirmed action

Param	Type	Description
sceneName	string	Name of scene(same as configured on SHC). Not case sensitive
[cb]	callback	Callback with true or false result. True if SHC confirmed action

---

xcomfort.getDeviceNames() ⇒ Array.<string>

Generates list of all device names

Kind: instance method of Xcomfort

---

xcomfort.getSceneNames() ⇒ Array.<string>

Generates list of all scene names

Kind: instance method of Xcomfort

---

xcomfort.getNameObject() ⇒ Object

Generates object with list of devices and scenes

Kind: instance method of Xcomfort

---

Event: "ready"

Ready event gets emitted when autosetup is complete

Kind: event emitted by Xcomfort

---

Event: "error"

General error event emitted when internal errors occur

Kind: event emitted by Xcomfort

---

Xcomfort~initialSetup()

Runs on initialisation. Logs in, then fetches devices and scenes from SHC

Kind: inner method of Xcomfort
Emits: ready

---

Xcomfort~getZoneDevices(zoneId) ⇒ Promise

Gets devices in zone from SHC and adds them to deviceMap with name of device as key and value of type deviceDetail

Kind: inner method of Xcomfort
Returns: Promise - - with no value, only used to tell when its done

Param	Type	Description
zoneId	string	name of zone to get devices in

---

Xcomfort~getZoneScenes(zoneId) ⇒ Promise

Gets scenes in zone from SHC and adds them to sceneMap with name of scene as key and value of type sceneDetail

Kind: inner method of Xcomfort
Returns: Promise - - with no value, only used to tell when its done

Param	Type	Description
zoneId	string	name of zone to get devices in

---

Xcomfort~importSetup(importPath)

Imports existing setup file and creates new device and scene maps

Kind: inner method of Xcomfort
Emits: ready, error

Param	Type	Description
importPath	string	Relative path to file

---

Xcomfort~getQueryParams(method, params) ⇒ Object

Configure request parameters

Kind: inner method of Xcomfort
Returns: Object - Object to pass to request as options

Param	Type	Description
method	String	Remote method to query on SHC
params	Array	Array of arguments to pass to method

---

Xcomfort~checkIfDeviceExists(deviceName, deviceType) ⇒ Promise

Checks if devices with devicetype(optional) exists

Kind: inner method of Xcomfort
Fulfil: Object - Device properties
Reject: String - Error message of one of the following:

• Device name must be of type string: deviceName was not a string
• No device with that name exists: Device not found
• No deviceType with that name exists: No device with correct type found

Param	Type	Description
deviceName	String	SHC id of the device
deviceType	String	SHC devicetype

---

Xcomfort~invokeDCOOperation(id, type, operation, params) ⇒ Promise

Invoke DCO operation on SHC

Kind: inner method of Xcomfort
Returns: Promise - - resolves undefined if no error during query

Param	Type	Description
id	String	SHC id of the device
type	String	SHC devicetype
operation	String	Operation on deviceclass to invoke
params	Object	key-value pairs of arguments for operation

---

Xcomfort~deviceDetail : object

Kind: inner typedef of Xcomfort
Properties

Name	Type	Description
zoneId	string	Zone id
id	string	Device id
type	string	SHC class type
value	string	Device value

---

Xcomfort~sceneDetail : object

Kind: inner typedef of Xcomfort
Properties

Name	Type	Description
zoneId	string	Zone id
id	string	Scene id

---

Xcomfort~callback : function

Callback with result or error

Kind: inner typedef of Xcomfort

Param	Type	Description
error	Error	null if no error
result		null if error

---