Scripting inside the dSS » History » Version 33

« Previous - Version 33/46 (diff) - Next » - Current version
Christoph Hofmann, 09/23/2011 09:47 PM
new Event() example added


Scripting inside the dSS

The dSS has the ability to run scripts inside it using the JavaScript interpreter SpiderMonkey. While it doesn't support running a script using a dedicated api, scripts can be run as a result to a "highlevel event".

The following excerpt is from data/subscriptions.xml. It shows how to run a script (data/initialize.js) on startup.

  <subscription event-name="model_ready" handler-name="javascript">
    <parameter>
      <parameter name="filename1">data/initialize.js</parameter>
    </parameter>
  </subscription>

It is also possible to execute several script files in the same context, the order of script execution is defined by the index number that is appended to the filename parameter, it allows to have 1-255 scripts in the same context, "holes" in the enumeration are not allowed. The following example shows how to run two scripts in the same context for a given event:

  <subscription event-name="model_ready" handler-name="javascript">
    <parameter>
      <parameter name="filename1">data/funclibrary.js</parameter>
    </parameter>
    <parameter>
      <parameter name="filename2">data/initialize.js</parameter>
    </parameter>
  </subscription>

Note: prior to dSS version 0.9.0 alpha 4 running multiple scripts in one context was not supported, the parameter was called filename, without an appended index.

API

Global functions

  • print
    print(arg1, ..., argn)
    Prints arg1 ... argn to the log. The log-entries are prefixed by JS:
  • getDevices
    getDevices()
    Returns a Set that contains all devices of the dss
  • setTimeout
    setTimeout(func, timeoutMS)
    Calls the function func after at least timeoutMS milliseconds have elapsed. Note that the script will need to be run completely for the callback to happen.
  • getName
    getName()
    Returns the name of the Apartment.
  • setName
    setName(name)
    Sets the name of the Apartment.

Constants

  • Scene.User1
  • Scene.User2
  • Scene.User3
  • Scene.User4
  • Scene.Min
  • Scene.Max
  • Scene.DeepOff
  • Scene.Off
  • Scene.StandBy
  • Scene.Bell
  • Scene.Panic
  • Scene.Alarm
  • Scene.Inc
  • Scene.Dec

Devices

  • turnOn
  • turnOff
  • startDim
    startDim(up)
  • endDim
  • setValue
    setValue(value)
  • increaseValue
  • decreaseValue
  • callScene
    callScene(sceneNr)
  • saveScene
    saveScene(sceneNr)
  • undoScene
    undoScene(sceneNr)
  • getSensorValue
    getSensorValue(sensorValue)

The following properties can be read on device objects: className, dsid, name, zoneID, circuitID, functionID, lastCalledScene

Sets

  • perform
    perform(function)
    Calls function for every device contained in the set.
  • length
  • combine
  • remove
  • byName
  • byDSID
  • byFunctionID
  • byZone
  • byDSMeter
  • byGroup
  • byPresence
  • byTag

Logger

This class provides a conveniet way to implement several logs in different files.

  • constructor
    Logger Logger(string logFileName)
    creates a new log file
  • logln
    logln(string message)
    writes the message to the logfile

Event

Class that allows to raise new events. To execute an Event in a later point in time there are two ways that are described in the constructor. However for this case usage of the TimedEvents class is recommended.

Functions

  • constructor
    Event Event(name[, [iCalRRule, iCalStartTime] | [time], parameters])
    The name is absolutely necessary and identifies the event. To execute the Event in a later point in time there are two ways. The first is to use an iCal recurrence rule and an iCal start time according to RFC 2445. The second one is to use the time parameter. For example the string "+10" will raise the event after 10 seconds.
  • raise
    raise()
    raises the event

Example

var evt = new Event("testevent",
   {
     zoneID: raisedEvent.source.zoneID,
     groupID: raisedEvent.source.groupID, 
     sceneID: raisedEvent.parameter.sceneID
   } );
evt.raise();

TimedEvent

Subclass of the normal Event. It is stored in the property tree, where it can be cancelled by deleting the node represting the TimedEvent. The node is stored in /system/EventInterpreter/ScheduledEvents/ID. A TimedEvent returns its ID when the raise() function is executed.

Functions

  • constructor
    TimedEvent TimedEvent(name, time[,parameters])
    name and time are mandatory. The time argument is a relative time duration in seconds and must be given as a string (e.g. "+5"). The event is executed after this duration.
  • raise
    string raise()
    raises the event and returns the ID

TimedICalEvent

Subclass of the normal Event. It is stored in the property tree, where it can be cancelled by deleting the node represting the TimedICalEvent. The node is stored in /system/EventInterpreter/ScheduledEvents/ID. A TimedICalEvent returns its ID when the raise() function is executed.

  • constructor
    TimedEvent TimedICalEvent(name, iCalStartTime, iCalRRule[,parameters])
    name, iCalStartTime and iCalRRule are mandatory. Similar to the TimedEvent it is executed, but an absolute point in time can be specified with the iCalRRule and the iCalStartTime.
  • raise
    string raise()
    raises the event and returns the ID

Apartment

Basic functions of the apartment

Static functions

  • getName
    getName()
    Returns the name of the apartment.
  • setName
    setName(name)
    Sets the name of the apartment.
  • getDevices
    getDevices()
    Returns a Set that contains all devices of the dss
  • getDSMeterByDSID
    getDSMeterByDSID(dsid)
  • getDSMeters
    getDSMeters()
    returns an array with all dSMs
  • getEnergyMeterValue
    getEnergyMeterValue()
    returns the actual energy of the the whole apartment.
  • getConsumption()
    getConsumption()
    returns the actual power consumption of the whole apartment.

Metering

This class allows to access the metering data.

Static functions

  • getResultions
    array getResolutions()
    returns the stored resolutions
  • getSeries
    array getSeries()
    returns the stored series
  • getValues
    array getValues(dsid, type, resolution)
    returns an array with the stored metering values. type can be consumption or energy.

Property

Static functions

  • Property.setProperty
    setProperty(propPath, value)
    Sets the property at propPath to value
  • Property.getProperty
    value getProperty(propPath)
    Returns the value at propPath, for example: Property.getProperty("/system/uptime")
  • Property.setListener
    listenerID setListener(propPath, func)
    Sets up a listener and calls func on any change to propPath or its children
  • Property.removeListener
    removeListener(listenerID)
    Removes a previously installed listener
  • Property.hasFlag
    bvalue Property.hasFlag(propPath, flagName)
    Returns true if the given flag is set
  • Property.setFlag
    Property.setFlag(propPath, flagName, value)
    Sets the value (boolean) of the flag
  • Property.getNode
    nodeObj Property.getNode(path)
    Returns a property-object
  • Property.store
    Property.store()
    Persists the properties of the private subtree
  • Property.load
    Property.load()
    Loads previously persisted properties

Functions

  • getValue
    value getValue
    Returns the value of the property
  • setValue
    setValue(value)
    Sets the value of the property to value
  • setListener
    callbackIdent setListener(callbackFunction)
    Registers a callback that gets called if the property changes
  • removeListener
    removeListener(callbackIdent)
    Removes a previously registered callback
  • getChild
    nodeObj getChild(relativePathToNode)
    Returns a child-node or null if it doesn't exist
  • getChildren
    arrayOfChildren getChildren()
    Returns an array of children, an empty one if none present
  • getParent
    nodeObj getParent()
    Returns the parent or null
  • removeChild
    bool removeChild([nodeObj|string])
    Returns true if the child has been removed

TcpSocket

Class that allows communicating to other hosts using TCP. All calls are asynchronous.

Functions

  • connect
    connect(host, port[, function(success)])
    Opens a connection to host:port. When finished the optional function gets called with a boolean argument indicating success.
  • send
    send(data[, function(bytesSent)])
    Sends data over an already open socket. When finished the optional function gets called with the number of bytes actually sent (-1 on error).
  • receive
    receive(numberOfBytes[,function(data)])
    Receives data over an already open socket. When finished the optional function gets called with the data received ("" on error).
  • receiveLine
    receiveLine(numberOfBytes[,function(data),delimiter])
    Receives data over an already open socket, until \r\n, or the optional delimiter character is reached. When finished the optional function gets called with the data received ("" on error).
  • close
    close()
    Closes the socket.
  • bind
    bind(port[, function(success)])
    Opens a server-socket on the given port. When finished the optional function gets called with a boolean argument indicating success.
  • accept
    accept(function(socket))
    Waits for a connection on a previously bound port. The function provided will be called if somebody connects.

Static functions

  • sendTo
    sendTo(host, port, data[, function(success)])
    Opens a connection to host:port and sends data to it. When finished the optional function gets called with a boolean argument indicating success.

Event handlers

If a script gets invoked by a event handler the following variables are made available:

  • raisedEvent.name
  • raisedEvent.parameter.paramname
  • raisedEvent.source.one-of-the-following
    set, dsid, zoneID, groupID, isApartment, isZone, isDevice
  • subscription.name