the VSCP Daemon

Trace: javascript_callbacks


|

Index

Setup

Meta

JavaScript Callbacks

JavaScript callbacks is functions that you can call from JavaScript code in a decision matrix action parameter or in the other places where VSCP JavaScripts can be executed.

Predefined JavaScript variables

The VSCP daemon creates some predefined variables when a JavaScript is executed.

  • vscp_feedEvent - This is the event that triggered the execution of the JavaScript as a JSON object. See the vent handling functions below for the format. The variable is read only.
  • vscp_clientItem - This is an object that represent the client the JavaScript is running as. It is created by the VSCP daemon when the script is started. Some function require that you supply this variable as a parameter. The variable is read only.

vscp_log

Log data to the VSCP daemon logs. Very well suited for reporting errors and log information. As an alternative one can send VSCP events instead. CLASS1.LOG and CLASS1.ERROR is intended for this use.

Parameters

vscp_log("message"[,nDebugLevel, nType] );
  • message is required and is the message that is sent to the logs. Please end this message with a new line.
  • nDebugLevel is optional and should be 0,1 or 2 where 0 is the lowest debug level, 1 is the normal level and 2 is the debug level. Can be omitted and if so defaults to 1.
  • nType is optional and should be 0,1,2,3 and 0 is general log messages, 1 is security log messages, 2 is access log messages and 3 is decision matrix related log messages. Can be omitted and if so defaults to 0.

Return value

This function will always return a boolean true.

Example

This script write out the current date on ISO format (YYMMDD) and “Hello World!” to the general log file. The %isodate is a decision matrix escape and it is replaces with information before the script is executed.

vscp_log("%isodate  Hello World! \n" );

vscp_sleep

Sleep a number of milliseconds.

Parameters

vscp_sleep(sleeptime );
  • sleeptime Time to sleep in milliseconds.

Return value

This function will always return a boolean true.

vscp_readVariable

Fetch a VSCP remote variable by name. Variable information is returned in JSON format and a NULL object is returned if no variable with that name exists. You must be the owner of a variable or have read rights to read it.

Parameters

vscp_readVariable( vscp_ClientItem,"name");
  • vscp_ClientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.
  • name of variable.

Return

Variable information is returned in JSON format or a NULL object is returned if no variable with that name exists.

{  
    "name": "variable-name",
    "type": 1,
    "user": 2,
    "accessrights": 0x777,
    "persistence": true|false,
    "lastchange": "YYYYMMDDTHHMMSS",
    "bnumerical": true|false,
    "bbase64": true|false,
    "value": "This is a test variable of type string",
    "note": "This is a note about this variable"
}

The variable types are listed here.

  • bNumerical is true for a numerical variable.
  • bBase64 is true if the value is coded in BASE64, this is true for all string formats. You can use the built in functions Crypto.base64_decode() and Crypto.base64_encode() to decode/encode.

Example

This example reads the variable test1 which is a numerical VSCP remote variable, it increase the value of it with one and then write it back and finally write the value to the general log file.

var obj = vscp_readVariable(vscp_clientItem,"test1");
obj.value++;
vscp_writeVariable(vscp_clientItem, obj);
vscp_log("Variable value = " + obj.value + "\n" );

vscp_writeVariable

Create or change a VSCP remote variable. The variable is created if it does not exist. You must be the owner of a variable or have write access to read it.

Parameters

vscp_writeVariable( vscp_clientItem,"name of variable", JSON-object );
  • vscp_clientItem A VSCP daemon supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.
  • name of variable of variable.
  • JSON-object The variable data as a JSON object. See the return data for the vscp_readVariable function for format. If the variable is existing only value and note will be read and changed.
{  
    "name": "variable-name",
    "type": 1,
    "accessrights": 0x777,
    "persistence": true|false,
    "value": "This is a test variable of type string",
    "note": "This is a note about this variable"
}
  • name is a required parameter.
  • type defaults to 1 (string).
  • accessrights defaults to 0x700 (all wights to owner).
  • persistence defaults to false (will not survive a restart of VSCP daemon).
  • value should be enclosed in quotes and be BASE64 encoded for all variables that are in string format. No quotes for numerical types. Parameter is required.
  • note Should always be BASE64 encoded if present.

Return

Return boolean true on success and false on failure.

var obj = vscp_readVariable(vscp_clientItem,"test1");
obj.value++;
vscp_writeVariable(vscp_clientItem, obj);
vscp_log("Variable value = " + obj.value + "\n" );

vscp_deleteVariable

Delete a VSCP remote variable. You must be the owner of a variable or have write access to be able to delete it.

Parameters

vscp_deleteVariable( vscp_clientItem, "name of variable" );
  • vscp_clientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.
  • name of variable of variable.

Return

Return boolean true on success and false on failure.

Example

if ( vscp_deleteVariable( vscp_clientItem, "testVariable" ) ) {
  vscp_log("Variable deleted.\n" );
}
else {
  vscp_log("Failed to delete variable!\n" );
}

vscp_sendEvent

Send a VSCP event.

Parameters

vscp_sendEvent( vscp_clientItem, vscpEventObject );
  • vscp_clientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.
  • vscpEventObject A JSON object that contain the VSCP event data as of below.

The VSCP Event object has the following format

{
    'time': '20161102T190032',
    'head': 96,
    'timestamp': 0,
    'obid':  0,
    'class': 10,
    'type': 6,
    'guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',
    'data': [1,2,3,4,5,6,7,8...],
    'note': 'A note about this event'
}

time and note has no use in this case and can be left out. head if left out defaults to 96 which is normal priority. timestamp and obid both defaults to zero meaning they will be filled in by the system. guid can be set to “-” or all nulls (same as being omitted) and the GUID of the interface is then used. data can be omitted and is in that case the same as no data.

Return

Return boolean true on success and false on failure.

Example

Send Turn-On-event.

// The JSON text CLASS1.CONTROL, Type= TurnOn,5 zone=11, subzone=3  
var eventTxt = "{ 'class': 30, 'type': 5, 'data': [0,11,3] }";
 
// Make the JSON object
var eventObj = JSON.parse( eventTxt );
 
// Send the TurnOn event
if ( vscp_sendEvent( vscp_clientItem, eventObj ) ) {
  vscp_log("TurnOn event sent successfully!\n");
}
else {
  vscp_log("Faild to send TurnOn event!\n");
}

vscp_receiveEvent

Receive a VSCP event from the local queue.

Parameters

vscp_receiveEvent( vscp_clientItem )
  • vscp_clientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.

Return

Return VSCP Event object on success and NULL on failure. See vscp_sendEvent for the format for the received JSON event object.

Example

Print out received events on the log until the event CLASS1.INFORMATION, Type=Stop, 8 is received. Note that the loop construct here without a delay is not to recommend as it eats a lot of CPU time.

var vscpEventObj;       // JSON object containing VSCP event
var bQuit = false;
 
// Keep on until done
while ( !bQuit ) {
 
    // Fetch event from clinet queue
    vscpEventObj= vscp_receiveEvent( vscp_clientItem );
 
    if ( null != vscpEventObj ) {
 
        vscp_log("VSCP event received: class = " + vscpEventObj.class.toString() + " type = " + vscpEventObj.type.toString() + "\n");
 
        // Event CLASS1.INFORMATION, Type=Stop, 8 terminates the loop
        if ( 30 == vscpEventObj.class ) {
            if ( 8 == vscpEventObj.type ) {
                bQuit = true;
            }
        }
    }
    else {
        vscp_sleep( 500 );
    }
}
 
vscp_log("Done!\n");

You can log in to the tcp/ip interface and issue

 send 96,30,8,0,0,-,0,0,0

to terminate the loop. That is send CLASS1.INFORMATION, Type=Stop, 8

Also note the

if ( 30 == vscpEventObj.class ) {
  if ( 8 == vscpEventObj.type ) {
    bQuit = true;
  }
}

which would have been written as

if ( (30 == vscpEventObj.class) && ( 8 == vscpEventObj.type ) ) {
  bQuit = true;
}

by a sane programmer. But the reason we don't use that here is because of the double ampersands ,“&&”, in the and statement which is not allowed in XML. They could be replaced by two && to make the code valid XML.

if ( (30 == vscpEventObj.class) && ( 8 == vscpEventObj.type ) ) {
  bQuit = true;
}

Another oprion is to code the code in BASE64 and tell the system so by preceding it with “BASE64:” so it is converted to a string before VSCP decision matrix escapes is written and before it is executed. In this case the parameter line would look like

   BASE64:dmFyIHZzY3BFdmVudE9iajsgICAgICAgLy8gSlNPTiBvYmplY3QgY290YWluaW5nIFZTQ1AgZXZlbnQNCnZhciBiUXVpdCA9IGZhbHNlOw0KDQovLyBLZWVwIG9uIHVudGlsIGRvbmUNCndoaWxlICggIWJRdWl0ICkgew0KDQogICAgLy8gRmV0Y2ggZXZlbnQgZnJvbSBjbGluZXQgcXVldWUNCiAgICB2c2NwRXZlbnRPYmo9IHZzY3BfcmVjZWl2ZUV2ZW50KCB2c2NwX2NsaWVudEl0ZW0gKTsNCg0KICAgIGlmICggbnVsbCAhPSB2c2NwRXZlbnRPYmogKSB7DQoNCiAgICAgICAgdnNjcF9sb2coIlZTQ1AgZXZlbnQgcmVjZWl2ZWQ6IGNsYXNzID0gIiArIHZzY3BFdmVudE9iai5jbGFzcy50b1N0cmluZygpICsgIiB0eXBlID0gIiArIHZzY3BFdmVudE9iai50eXBlLnRvU3RyaW5nKCkgKyAiXG4iKTsNCg0KICAgICAgICAvLyBFdmVudCBDTEFTUzEuSU5GT1JNQVRJT04sIFR5cGU9U3RvcCwgOCB0ZXJtaW5hdGVzIHRoZSBsb29wDQogICAgICAgIGlmICggMzAgPT0gdnNjcEV2ZW50T2JqLmNsYXNzICkgew0KICAgICAgICAgICAgaWYgKCA4ID09IHZzY3BFdmVudE9iai50eXBlICkgew0KICAgICAgICAgICAgICAgIGJRdWl0ID0gdHJ1ZTsNCiAgICAgICAgICAgIH0NCiAgICAgICAgfQ0KICAgIH0NCn0NCg0KdnNjcF9sb2coIkRvbmUhXG4iKTs=

The later gives much nicer XML code.

vscp_countEvent

Return number of VSCP events in the local queue.

Parameters

vscp_countEvent( vscp_ClientItem )
  • vscp_ClientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.

Return

Return the number of events waiting in the client queue for this JavaScript. A client is opened when the script is started and remains open until the script has terminated.

Example

Check the client queue five times with a ten second delay between the checks. Note that the “less than” (<) symbol is not allowed in XML and should be replaced by &lt; if this is used in the dm.xml file.

for ( i=0; i<5; i++ ) {
    var count = vscp_countEvent( vscp_clientItem );
    vscp_log("Number of VSCP events in client queue is " + count.toString() + " i = " + i.toString() + "\n"  );
    vscp_sleep( 10000 );
}

vscp_setFilter

Set a VSCP filter for this clients local queue. This filter limits the events received on this interface.

Parameters

vscp_setFilter( vscp_ClientItem, vscpFilterObject )
  • vscp_ClientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by the VSCP daemon when the script is executed.
  • vscpFilterObject A JSON filter object specifying a complete VSCP filter.
{
    'mask_priority': number,
    'mask_class': number,
    'mask_type': number,
    'mask_guid': 'string',
    'filter_priority'; number,
    'filter_class': number,
    'filter_type': number,
    'filter_guid' 'string'
}

Return

Return boolean true on success and false on failure.

Example

Set filer so that only CLASS1.MEASUREMENT events is received.

// Allow only CLASS1.MEASUREMENT events, from all, 
// with all priorities
var filterTxt = "{\
    'mask_priority': 0,\
    'mask_class': 0xffff,\
    'mask_type': 0,\
    'mask_guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',\
    'filter_priority': 0,\
    'filter_class': 10,\
    'filter_type': 0,\
    'filter_guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00'\
}";
 
// Make the JSON object
var filterObj = JSON.parse( filterTxt );
 
// Set the filter
if ( vscp_setFilter( vscp_clientItem, filterObj ) ) {
  vscp_log("Filter set successfully!\n");
}
else {
  vscp_log("Faild to set filter!\n");
}

vscp_sendMeasurement

Send a measurement event. A level I or Level II measurement event can be sent with this function with the measurement supplied as a floating point value.

Parameters

vscp_sendMeasurement( vscp_ClientItem, vscpMeasurementObject );
  • vscp_ClientItem A vscpd supplied object that specify a unique VSCP client this JavaScript is acting as. This variable is created by vscpd when the script is executed.
  • vscpMeasurementObject A JSON measurement object that specify the properties of the measurement.
{
    'level': 1|2, 
    'string': true|false,
    'value': 123.5,
    'guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',
    'vscptype': 6,
    'unit': 1,  
    'sensorindex': 0, 
    'zone': 0, 
    'subzone': 0 
}
  • level is either 1 or 2 for Level I or level II events or if not given it defaults to 2.
  • string Only valid for Level II events. If true a CLASS2.MEASUREMENT_STR. If false a CLASS2.MEASUREMENT_FLOAT. If not given defaults to false-
  • value A double representing the measurement value. A required value.
  • guid Optional. Defaults to all nulls that is the GUID of the interface is used.
  • vscptype This is the measurement type. A required value.
  • unit The unit for the measurement. Defaults to 0 (the default unit). Can be 0-3 for a level I measurement and 0-255 for a level II measurement.
  • sensorindex The sensor index for the measurement. Defaults to 0. Can be 0-7 for a level I measurement and 0-255 for a level II measurement.
  • zone The zone for the measurement. Defaults to 0. Can be 0-255 for a level I measurement and 0-255 for a level II measurement.
  • subzone The subzone for the measurement.Defaults to 0. Can be 0-255 for a level I measurement and 0-255 for a level II measurement.

Return

Return boolean true on success and false on failure.

Example

// Send te,perature measurement
var measurementTxt = "{\
    'level': 1,\
    'string': false,\
    'value': 123.5,\
    'guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',\
    'vscptype': 6,\
    'unit': 1,\
    'sensorindex': 0,\
    'zone': 0,\
    'subzone': 0\
}";
 
// Make the JSON object
var measurementObj = JSON.parse( measurementTxt );
 
// Send the measurement event
if ( vscp_sendMeasurement( vscp_clientItem, measurementObj ) ) {
  vscp_log("Measurement event sent successfully!\n");
}
else {
  vscp_log("Faild to send measurement event!\n");
}

This is how the resulting event looks like in VSCP Works.

And this is the decision matrix row. Not that CLASS2.VSCPD,Type=Second,5 event is used to send the measurement event every second. There are many possibilities here such as once on start up, every hour etc.

To send the same Level I measurement in string form use

var measurementTxt = "{\
    'level': 1,\
    'string': true,\
    'value': 123.5,\
    'guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',\
    'vscptype': 6,\
    'unit': 1,\
    'sensorindex': 0,\
    'zone': 0,\
    'subzone': 0\
}";

To send the same measurement in Level II string form use

var measurementTxt = "{\
    'level': 2,\
    'string': true,\
    'value': 123.5,\
    'guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',\
    'vscptype': 6,\
    'unit': 1,\
    'sensorindex': 0,\
    'zone': 0,\
    'subzone': 0\
}";

To send the same measurement in Level II floating point form use

var measurementTxt = "{\
    'level': 2,\
    'string': false,\
    'value': 123.5,\
    'guid': '00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00',\
    'vscptype': 6,\
    'unit': 1,\
    'sensorindex': 0,\
    'zone': 0,\
    'subzone': 0\
}";

vscp_isMeasurement

Check if this VSCP event is a measurement event.

Parameters

vscp_isMeasurement( vscpEventObject )
  • vscpEventObject A JSON object that contain the VSCP event data. See vscp_sendEvent for the format.

Return

Return boolean true if the event is a measurement event and false if not.

vscp_getMeasurementValue

Get a measurement value from a VSCP measurement event.

Parameters

vscp_getMeasurementValue( vscpEventObject )
  • vscpEventObject A JSON object that contain the VSCP event data. See vscp_sendEvent for the format.

Return

Return the value for the measurement as a double or null if error or if event is not a measurement.

Example

// The JSON text CLASS1.MEASUREMENTL, Type= Temperature,6 sensorindex=0, unit=1 (Celsius) 
// 45.464 degrees Celsius 
var eventTxt = "{ 'class': 10, 'type': 6, 'data': [0x48,0x34,0x35,0x2E,0x34,0x36,0x34] }";
 
// Make the JSON object
var eventObj = JSON.parse( eventTxt );
 
if ( null != ( value = vscp_getMeasurementValue( eventObj ) ) ) {
  vscp_log("Measurement event sent successfully! value = " + value.toString() + "\n");
}
else {
  vscp_log("This is not a measurement event!\n");
}

vscp_getMeasurementUnit

Get a measurement unit from a VSCP measurement event.

Parameters

vscp_getMeasurementUnit( vscpEventObject )
  • vscpEventObject A JSON object that contain the VSCP event data. See vscp_sendEvent for the format.

Return

Return the unit for the measurement as an integer or null if error or if event is not a measurement.

Example

Will output Unit = 1.

// The JSON text CLASS1.MEASUREMENTL, Type= Temperature,6 sensorindex=1, unit=1 (Celsius) 
// 45.464 degrees Celsius 
var eventTxt = "{ 'class': 10, 'type': 6, 'data': [0x49,0x34,0x35,0x2E,0x34,0x36,0x34] }";
 
// Make the JSON object
var eventObj = JSON.parse( eventTxt );
 
vscp_log("Unit = " + vscp_getMeasurementUnit( eventObj ).toString() + "\n");

vscp_getMeasurementSensorIndex

Get a measurement sensor index from a VSCP measurement event.

Parameters

vscp_getMeasurementSensorIndex( vscpEventObject )
  • vscpEventObject A JSON object that contain the VSCP event data. See vscp_sendEvent for the format.

Return

Return the sensorindex for the measurement as an integer or null if error or if event is not a measurement.

Example

Will output sensorindex = 1.

// The JSON text CLASS1.MEASUREMENTL, Type= Temperature,6 sensorindex=1, unit=1 (Celsius) 
// 45.464 degrees Celsius 
var eventTxt = "{ 'class': 10, 'type': 6, 'data': [0x49,0x34,0x35,0x2E,0x34,0x36,0x34] }";
 
// Make the JSON object
var eventObj = JSON.parse( eventTxt );
 
vscp_log("Sensor index = " + vscp_getMeasurementSensorIndex( eventObj ).toString() + "\n");

vscp_getMeasurementZone

Get a measurement zone from a VSCP measurement event.

Parameters

vscp_getMeasurementZone( vscpEventObject )
  • vscpEventObject A JSON object that contain the VSCP event data. See vscp_sendEvent for the format.

Example

Will output Zone = 0.

// The JSON text CLASS1.MEASUREMENTL, Type= Temperature,6 sensorindex=1, unit=1 (Celsius) 
// 45.464 degrees Celsius 
var eventTxt = "{ 'class': 10, 'type': 6, 'data': [0x49,0x34,0x35,0x2E,0x34,0x36,0x34] }";
 
// Make the JSON object
var eventObj = JSON.parse( eventTxt );
 
vscp_log("Zone = " + vscp_getMeasurementZone( eventObj ).toString() + "\n");

Return

Return the zone for the measurement as an integer or null if error or if event is not a measurement. Level I events that does not have a zone defined will get a zero returned.

vscp_getMeasurementSubZone

Get a measurement Sib Zone from a VSCP measurement event.

Parameters

vscp_getMeasurementSubZone( vscpEventObject )
  • vscpEventObject A JSON object that contain the VSCP event data. See vscp_sendEvent for the format.

Return

Return the subzone for the measurement as an integer or null if error or if event is not a measurement. Level I events that does not have a zone defined will get a zero returned.

Example

Will output Subzone = 0.

// The JSON text CLASS1.MEASUREMENTL, Type= Temperature,6 sensorindex=1, unit=1 (Celsius) 
// 45.464 degrees Celsius 
var eventTxt = "{ 'class': 10, 'type': 6, 'data': [0x49,0x34,0x35,0x2E,0x34,0x36,0x34] }";
 
// Make the JSON object
var eventObj = JSON.parse( eventTxt );
 
vscp_log("Subzone = " + vscp_getMeasurementSubZone( eventObj ).toString() + "\n");



Grodans Paradis AB