hm-webui-javascript v0.0.1

HM WebUI Javascript Plugin

With the plugin you can run Javascript or Coffescript code triggered by a state change of a device or triggered by a scheduler.

When you write code the following objects / functions support you.

• Global objects
• log
• hmwebui
  • getPlugins
  • callPluginFunction
  • getDeviceList
  • getDevice
  • getState
  • setState
  • on
  • subscribe
  • schedule
  • exec
  • writeConfigJSON
  • readConfigJSON
• Global functions
  • importScript
  • setInterval
  • clearInterval
  • setTimeout
  • clearTimeout
• Changelog

Global objects

The follwoing global objects can be used in the code

log

With the log object functions you can write messages to the log file with the given severity. The log messages will be written to log file only when the severity matches to the log level set on the plugin configuration by the user.

When the user set the log level of the plugin to ERROR only messages with log.error() will be written to the HM WebUI log. If the user set the log level of the plugin to VERBOSE all higher messages with log.error(), log.warn(), log.info() and log.verbose() will be written to the log file.

log.error(message)
log.warn(message)
log.info(message)
log.verbose(message)
log.debug(message)
log.silly(message)

hmwebui

The hmwebui object has functions to read or write data from the HM WebUI system and some supporting function to subscribe to state events or create a scheduler.

All the hmwebui functions return a promise with the following functions:

• .then() - When the request was successful
• .fail() - When an error occurred
• .fin() - Always (if an error occured or the request was successful)

You can combine the functions in the following way:

hmwebui.getPlugins('device').then(function(result){
  ... your code here for successful call
}).fail(function(err){
  ... your code here when an error occurred
}).fin(function(){
  ... your code here that should run always
});

getPlugins(type,status)

The getPlugins function is returning a list of configured plugins.

Parameter

Result

An object with plugin data.

{
  id: <unique id of the plugin instance e.g. hm-webui-httprequest.0>,
  pluginId: <the id of the plugin e.g. hm-webui-httprequest>,
  status: <plugin status>
  ...
}

Example

hmwebui.getPlugins('device').then(function(plugins){
  /*
    the plugins array list contains a list of all device plugins
    with the type 'device'
  */
  ...
});

hmwebui.getPlugins('device','running').then(function(plugins){
  /*
    the plugins array list contains a list of all device plugins
    with the type 'device' that are currently running
  */
  ...
});

callPluginFunction(pluginId,functionName,arg1,arg2,...)

The callPluginFunction is used to call a function of a configured plugin. It depends on the plugin function how many argn parameter you have to provide. See the documentation of the plugin to see which functions you can call.

Parameter

Result

Depends on the plugin function (read plugin documentation for details)

Example

//call the get function of the httprequest plugin
hmwebui.callPluginFunction('hm-webui-httprequest.0','get','http://www.google.com')
.then(function(result){
  /*
    the result contains the body (html) of the get request
    for more information about the content of the request object
    read the plugin documentation for the hm-webui-httprequest plugin
  */
  ...
})
.fail(function(err){
  //the err contains the error messages
  log.error(err);
});

getDeviceList(selector)

This function returns a list of devices matching the given selector

Parameter

Selector parameter

The selector parameter is a string to match the devices. Right now you can match device attributes. All attributes are combined with a AND condition. The selector should be in the following format:

[<attribute>=<value to search for>][<attribute>=<regexp to search for>] ...

As attribute value you could provide a string or a regular expression to match a device attribute.

Result

An array list containing all matched device objects.

Example

//get a list of devices where the type attribute is 'Window'or 'Door'
hmwebui.getDeviceList([type=/Window|Door/]).then(function(list){
  //list is an array list with the device objects matching the selector
  ...
});

/* get a list of devices where the type attribute is 'Window'or 'Door'
    and the pluginId is 'hm-webui-homematic.0' */
hmwebui.getDeviceList([type=/Window|Door/][pluginId='hm-webui-homematic.0']).then(function(list){
  //list is an array list with the device objects matching the selector
  ...
});

getDevice(pluginId,address)

This function returns a device object.

Parameter

Result

An object with the device data

{
    address: <the device address>,
    name: <the name of the device>,
    type: <the type of the device>,
    pluginId: <the plugin id providing the device>,
    channels: {
        ...
    },
    visible: <true or false>,
    editable: <true or false>,
    deletable: <true or false>
    ...
}

Example

//get the device data for address 'MEQ32546'
hmwebui.getDevice('MEQ32546').then(function(device){
  //device is the device object data
  ...
});

//get the device data for address 'MEQ32546' of the 'hm-webui-homematic.0' plugin
hmwebui.getDevice('hm-webui-homematic.0','MEQ32546').then(function(device){
  //device is the device object data
  ...
});

getState(pluginId,address)

With this function you can retrieve one or multiple state value(s) (depends on the address parameter).

Parameter

Address parameter

If the address is a string it should have the following format:

<device address>.<channel>.<state>

You can retrieve one state value with an address parameter given as string.

If you provide an array of strings as address parameter you retrieve a list of state values in the same order as the address array. The strings should have the same format as for a single state address (see above).

If you provide an object it should have the following format:

{
  <key>:<state address>,
  <key1>:<state address1>,
  ...
}

The result is an object with key / value pairs. The key is the key you gave to the address (see above). For the example above the result will be:

{
  <key>:<state value>,
  <key1>:<state value1>,
  ...
}

Example

//get a single state value for state address 'MEQ32546.1.STATE'
hmwebui.getState('MEQ32546.1.STATE').then(function(state){
  //state contains the value for 'MEQ32546.1.STATE'
  ...
});

//get a single state value for state address 'MEQ32546.1.STATE' of the 'hm-webui-homematic.0' plugin
hmwebui.getState('hm-webui-homematic.0','MEQ32546.1.STATE').then(function(state){
  //state contains the value for 'MEQ32546.1.STATE'
  ...
});

//get a list of state values
hmwebui.getState(['MEQ32546.1.STATE','MEQ88888.1.STATE']).then(function(states){
  /*
    states contains an array list of states in the same order
    as the addresses e.g.
    [1,0]
  */
  ...
});

//get a key / value list of state values
hmwebui.getState({
  state1: 'MEQ32546.1.STATE',
  state2: 'MEQ88888.1.STATE'
}).then(function(states){
  /*
    states contains key / value list of states e.g.
    { state1: 1, state2: 0 }
  */
  ...
});

setState(pluginId,address,value)

With this function you can set one or state value for the provided address.

Parameter

Address parameter

The address is a string and should have the following format:

<device address>.<channel>.<state>

Result

true on success or false on failure

Example

//set the state 'MEQ32546.1.STATE' to true
hmwebui.setState('MEQ32546.1.STATE',true).then(function(result){
  //result is true on success or false on failure
  ...
});

//set the state 'MEQ32546.1.STATE' of the 'hm-webui-homematic.0' plugin to 0
hmwebui.setState('hm-webui-homematic.0','MEQ32546.1.STATE',0).then(function(result){
  //result is true on success or false on failure
  ...
});

on(pattern)

With this function you add a subscription to a state event defined by the given pattern.

Parameter

Object matcher

You have to provide an object (key / value pairs) as pattern with the following possible parameter.

Result

The result is an event object. It depends on the device plugin what kind of information is provided for the event but at least the following fields should be in the object:

{
  address: <device address>,
  channel: <channel id>,
  state: <state id>,
  value: <state new value>,
  timestamp: <value change timestamp as unix timestamp>,
  oldState: <object containing the old state | optional>,
  device: <object with detailed device data | optional>
}

Example

//match all events where the state starts with STA* and the device type matches the given regular expression
hmwebui.on({ state: 'STA*', device: { type: /HM-Sec-SCo/ } }).then(function(event){
  //result is an event object
  ...
});

//match all events where state is STATE and the new value is true
hmwebui.on({ state: 'STATE', val: true }).then(function(event){
  //result is an event object
  ...
});

//match all events where state is STATE and the new value is greater than the old value
hmwebui.on({ state: 'STATE', change: 'gt' }).then(function(event){
  //result is an event object
  ...
});

subscribe(pattern)

Alias for the on(pattern) function

schedule(pattern)

Schedule a function to run on the given pattern.

Parameter

For more details on the expressions visit the nodejs-schedule project page

Cron expression

The pattern can be a cron expression in the following format

*    *    *    *    *    *
┬    ┬    ┬    ┬    ┬    ┬
│    │    │    │    │    |
│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    │    └───── month (1 - 12)
│    │    │    └────────── day of month (1 - 31)
│    │    └─────────────── hour (0 - 23)
│    └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, OPTIONAL)

hmwebui.schedule('*/5 * * * *').then(function(){
  //the function is called every 5 minutes
});

Object expression

To make things a little easier, an object expression is also supported.

hmwebui.schedule({hour: 14, minute: 30, dayOfWeek: 0}).then(function(){
  //the function is called every Sunday at 2:30pm
});

Returns

As all other functions the schedule function returns a promise with .then() .fail() and .fin() functions. But ist also has a scheduler property holding the instance of the schedule. This is e.g. needed if you want to cancel a schedule.

var sched = hmwebui.schedule({hour: 14, minute: 30, dayOfWeek: 0}).then(function(){
  //the function is called every Sunday at 2:30pm
});

//cancel the scheduler
sched.scheduler.cancel()

exec(cmd)

Execute a command on the system HM WebUi is running on.

Parameter

Result

the ouput of the system command

Example

hmwebui.exec('ls /var/log').then(function(result){
  //result holds the output of the command (stdout)
}).fail(function(err){
  //err contains the error returned by the command if something failed
});

writeConfigJSON(file,data)

Write an data to the config store of the plugin instance.

Parameter

Example

hmwebui.writeConfigJSON('test.json',{id: 1, name: 'Test'}).then(function(){
  //there is no result on success
}).fail(function(err){
  //error message when something went wrong
});

readConfigJSON(file)

Read a JSON object from the config store of the plugin instance.

Parameter

Result

a JSON object from the config file

Example

hmwebui.readConfigJSON('test.json').then(function(result){
  //result is the JSON object from the config file
}).fail(function(err){
  //error message when something went wrong
});

Global functions

The follwoing global functions can be used in the code

importScript(name)

This function can be used in a script to import another script in the same plugin. It is not possible to import scripts of other plugins. The code of the imported script will be copied to the position where the importScript() function is in the code.

To avoid confusion on an error put the importScript() function always at the end of the main code (the line numbers could be different in the error message when you import the script in the middle of the code).

Parameter

Example

//import the script 'Test Script' here
importScript('Test Script');

setInterval(callback,,ms,arg1,arg2,...,argN)

The method calls a function or evaluates an expression at specified intervals (in milliseconds).

For support of the javascript standard setInterval function you can provide as first argument a callback. If you omit the timeout the function is returning a promise that is called after the milliseconds.

Parameter

Returns

If a callback function is provided it returns the id of the interval. If no callback function is provided it returns a promise and the .then() function of the promise is called on every interval. The arguments passed to the .then() function are the arg1 ... argN. The promise also contains a reference to the interval id.

var intervalId = setInterval(10).interval;

Example

//run the function every 5 seconds
var intervalId = setInterval(function(){
    log.info('Five seconds are over');
},5000);

//run the function every 5 seconds
var intervalId = setInterval(5000).then(function(){
    log.info('Five seconds are over');
}).interval;

clearInterval(intervalId)

This method deletes an interval

Parameter

Example

//run the function after 5 seconds
var intervalId = setInterval(5000).then(function(){
    log.info('Five seconds are over');
}).interval;

//clear the interval
clearInterval(intervalId);

setTimeout(callback,,ms,arg1,arg2,...,argN)

The method calls a function or evaluates an expression after a specified number of milliseconds. For support of the javascript standard setTimeout function you can provide as first argument a callback. If you omit the timeout the function is returning a promise that is called after the milliseconds

Parameter

Returns

If a callback function is provided it returns the id of the timeout. If no callback function is provided it returns a promise and the .then() function of the promise is called after the timeout. The arguments passed to the .then() function are the arg1 ... argN. The promise also contains a reference to the timeout id.

var timeoutId = setTimeout(10).timeout;

Example

//run the function after 5 seconds
var timeoutId = setTimeout(function(){
    log.info('Five seconds are over');
},5000);

//run the function after 5 seconds
var timeoutId = setTimeout(5000).then(function(){
    log.info('Five seconds are over');
}).timeout;

clearTimeout(timeoutId)

This method deletes a timeout

Parameter

Example

//run the function after 5 seconds
var timeoutId = setTimeout(5000).then(function(){
    log.info('Five seconds are over');
}).timeout;

//clear the timeout
clearTimeout(timeoutId);

Changelog

0.0.1 (2017-01-08)

• initial version