Output

The output shall be used to set the desired output values. The names match the output model as specified in the VSCode plugin. For example, if the output model specifies a foo field, it has to be set with output.foo = ....

Just setting the output fields is not sufficient. To give the script implementer strict control over when and if to publish the changed output model, he must call output.publish() to explicitly publish the transformed value.

Input

The input is the representation of the input model. Input model fields are input object fields. On on_update() call, input contains the input model's last known values. They can simply be accessed with var x = input.foo.

Trigger

The trigger identifies the field name of the input model that has been changed. Be aware the simultaneous changes to multiple values of the input model are not possible and each change has to be handled on its own. This can be used to access the last changed value: var x = input[trigger.field_name]

Parameters

The parameters are configurable runtime options for each VSCode pipeline. These settings are to be used to configure the script depending on the pipeline. For example, a script with alerting capabilities has a different threshold per pipeline.

Optional initialization

It is optional to provide a init() function. If present, this function is called exactly once when the pipeline is incorporated. Instantiation occurs when the pipeline is first created or after each restart.

DSRC encode and DSRC decode

The global functions dsrc2016_encode and dsrc2016_decode are used to encode and decode messages to and from ASN.1 format.

Encode JSON strings to Uint8Array

/**
* @fn dsrc2016_encode(json_string) 
* @brief function to encode provided input of json string into Uint8Array format 
* @param json_string -> String (message contains json string format) 
* @return Uint8Array -> Encoded message in byte array format 
*/ dsrc2016_encode(json_string);

Decode Uint8Array to JSON string

/**
* @fn dsrc2016_decode(buffer) 
* @brief function to decode provided input of byte array into json string 
* @param buffer -> Encoded message in Uint8Array byte array format 
* @return json_string -> String (message contains json string format) 
*/ 
dsrc2016_decode(buffer);

BinaryUtils

The BinaryUtils is the representation of binary utility methods to operate on binary data. The following methods are part of the BinaryUtils object:

Valid hex string:

• 0x_00_FF_FF_00 => 32 Bit APIs

• 0x_3F_FC => 16 Bit APIs

• 0x_F_8_ => 8 Bit APIs

Invalid hex string:

• 0x_00_F0_FF_00 => 32 Bit APIs because of non-consecutive 1 bit in mask

• 0x_00_FF_FF => 16 Bit APIs because of invalid length

• 0xFG => 8 Bit APIs because invalid character in mask

/**
* @fn mask8()
* @brief gets the number of bit value from the input byte position as according to mask
* @param mask -> String (Binary or Hex Mask string. Mask should always have 8
bits/1byte)
* @param byte_value -> Uint8 (Input Byte Value)
* @return 8 bit integer -> masked bits from byte_value
*/
/ BinaryUtils.mask8(mask, bytes_value);

/**
* @fn mask16()
* @brief gets the number of bit value from the input buffer index as
according to Mask
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 16
* bits/2bytes)
* @param buffer -> Uint8Array[] (Input buffer)
* @param buffer_index -> Integer (Start buffer index)
* @return Integer -> masked bits from input buffer
*/
BinaryUtils.mask16(mask, buffer, buffer_index);

/**
* @fn mask32()
* @brief gets the number of bit value from the input buffer index as
according to Mask
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 32
* bits/4bytes)
* @param buffer -> Uint8Array[] (Input buffer)
* @param buffer_index -> Integer (Start buffer index)
* @return Integer -> masked bits from input buffer
*/
BinaryUtils.mask32(mask, buffer, buffer_index);

/**
* @fn mask8AndShiftRight()
* @brief gets the number of bit value from the input byte position as
according to Mask and right
* shift the value for all zero bits
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 8 bits/1byte)
* @param byte_value -> Uint8 (Input Byte Value)
* @return 8 bit integer -> masked bits from byte_value after right shift
*/
BinaryUtils.mask8AndShiftRight(mask, bytes_value);

/**
* @fn mask16AndShiftRight()
* @brief gets the number of bit value from the input buffer index as
according to Mask and right
* shift the value for all zero bits
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 16
* bits/2bytes)
* @param buffer -> Uint8Array[] (Input buffer)
* @param buffer_index -> Integer (Start buffer index)
* @return Integer -> masked bits from input buffer after right shift
*/
BinaryUtils.mask16AndShiftRight(mask, buffer, buffer_index);

/**
* @fn mask32AndShiftRight()
* @brief gets the number of bit value from the input buffer index as
according to Mask and right
* shift the value for all zero bits
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 32
* bits/4bytes)
* @param buffer -> Uint8Array[] (Input buffer)
* @param buffer_index -> Integer (Start buffer index)
* @return Integer -> masked bits from input buffer after right shift
*/
BinaryUtils.mask32AndShiftRight(mask, buffer, buffer_index);

/**
* @fn mask8AndSet()
* @brief returns the byte_value after setting the set_value into the input
byte as according to
* bits mentioned in the mask
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 8 bits/1byte)
* @param byte_value -> Uint8 (Input Byte Value)
* @param set_value -> Integer (value to be set)
* @return 8 bit integer -> The byte_value after setting the set value into
it.
*/
BinaryUtils.mask8AndSet(mask, bytes_value, set_value);

/**
* @fn mask16AndSet()
* @brief sets the number of bits value into the input buffer from buffer
index as according to
* bits mentioned in the mask
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 16
* bits/2bytes)
* @param buffer -> Uint8Array[] (Input buffer)
* @param buffer_index -> Integer (Start buffer index)
* @param set_value -> Integer (value to be set)
* @return updated input buffer
*/
BinaryUtils.mask16AndSet(mask, bytes_value, set_value);

/**
* @fn mask32AndSet()
* @brief sets the number of bits value into the input buffer from buffer
index as according to
* bits mentioned in the mask
* @param mask -> String (Binary or Hex Mask string. Mask
should always have 32
* bits/4bytes)
* @param buffer -> Uint8Array[] (Input buffer)
* @param buffer_index -> Integer (Start buffer index)
* @param set_value -> Integer (value to be set)
* @return updated input buffer
*/
BinaryUtils.mask32AndSet(mask, bytes_value, set_value);

/**
* @fn crc16()
* @brief calculates the crc16 checksum on the input byte array
* @param algorithm -> Builtin Global Object [CRC16Algorithm.ARC,
CRC16Algorithm.XMODEM, CRC16Algorithm.MODBUS, CRC16Algorithm.USB,
CRC16Algorithm.CMS]
* @param buffer -> Uint8Array (Input buffer)
* @param start_index -> Integer [OPTIONAL] (Start index of input
buffer)
* @param length -> Integer [OPTIONAL] (length of input buffer
from start index)
* @return 16 bit integer -> crc16 checksum
*/
BinaryUtils.crc16(algorithm, buffer, start_index, length)

/**
* @fn crc32()
* @brief calculates the crc32 checksum on the input byte array
* @param algorithm -> Builtin Global Object [CRC32Algorithm.AIXM]
* @param buffer -> Uint8Array (Input buffer)
* @param start_index -> Integer [OPTIONAL] (Start index of input
buffer)
* @param length -> Integer [OPTIONAL] (length of input buffer
from start index)
* @return 32 bit integer -> crc32 checksum
*/
BinaryUtils.crc32(algorithm, buffer, start_index, length)

* @fn base64_encode()
* @brief base64 encode the input byte array
* @param buffer -> Uint8Array (Input buffer)
* @return String -> base64 encoded string
*/
BinaryUtils.base64_encode(buffer);
/**
* @fn base64_decode()
* @brief decode the base64 encoded string
* @param encoded_data -> String (Input string)
* @return Uint8Array -> decoded array buffer
*/
BinaryUtils.base64_decode(encoded_data);

Few examples of on_update functions

• Applying Bit Manipulation on Uint8Array using BinaryUtils object

  // Buffer Input (Uint8Array) -> 0x41 0x42 0x43 0x44 0x45 0x46 0x47 0x48
  0x49 0x4A
  function on_update() {
  // encoded_message -> QUJDREVGR0hJSg==
  output.encoded_message = BinaryUtils.base64_encode(buffer);
  
  // decoded_message -> "Cisco - Edge Intelligence"
  var decoded_buf =
  BinaryUtils.base64_decode("Q2lzY28gLSBFZGdlIEludGVsbGlnZW5jZQ==");
  output.decoded_message = String.fromCharCode.apply(null, new
  Uint8Array(decoded_buf));
  
  // crc16_checksum -> 3230
  output.crc16_checksum = BinaryUtils.crc16(CRC16Algorithm.ARC, buffer);
  
  // crc32_checksum -> 840854789
  output.crc32_checksum = BinaryUtils.crc32(CRC32Algorithm.AIXM, buffer);
  
  output.publish();
  }

• Temperature conversion from Celsius to Fahrenheit

  function on_update() {
  var temp_celsius = input.temperature;
  var temp_fahrenheit = temp_celsius * (9 / 5) + 32;
  output.temperature = temp_fahrenheit;
  output.publish();
  }

• This code snippet is responsible for processing incoming sensor data (like temperature or vibration), calculating a sliding average for that data, and then publishing the result.

  function FastSlidingAvg(window_size) {
  this.size = window_size;
  this.values = [];
  this.sum = 0;
  this.update = function (value) {
  if (this.values.length == this.size) {
  this.sum -= this.values[0];
  this.values.shift();
  }
  this.sum += value;
  this.values.push(value);
  };
  this.avg = function () {
  return this.sum / this.values.length;
  };
  }
  var acc = {};
  function init() {
  acc["temp"] = new FastSlidingAvg(parameters.window_size);
  acc["vibration"] = new FastSlidingAvg(parameters.window_size);
  output.temp = 0;
  output.vibration = 0;
  }
  function on_update() {
  var field_name = trigger.field_name;
  var value = input[field_name];
  acc[field_name].update(value);
  output[field_name] = acc[field_name].avg();
  output.publish();
  }

Logging

These scripts represent common logging methods which helps to emit the log messages. Using a global object named logger, you can emit log messages with these six different severity level APIs. They are used to record events, status, and errors within an application, with each method corresponding to a different log level or severity.

logger.trace(...)
logger.debug(...)
logger.info(...)
logger.warn(...)
logger.error(...)
logger.fatal(...)

Example:

logger.info("Calling script with:", my_value);

• This is a log entry which indicates the exact date and time when the log event occurred. Each call accepts a variable number of arguments and will print them to a log message with the following pattern:

  2014-10-17T19:26:42.141Z INF: some text 123
  ^^^^^^^^^^^^^^^^^^^^^^^^ ^^^ ^^^^^^^^^ ^^^
  \Timestamp | \arg1 \arg2
  \LogLevel

• Custom types must implement a toString() method to be displayed in log messages. For example:

  function MyType() {}
  MyType.prototype.toString = function () {
  return "This is MyType";
  };
  var my_type = new MyType();
  logger.info("MyType is:", my_type);

Applying Bit Manipulation get bit functions on Uint8Array using BinaryUtils object

Get bit functions are for reading/inspecting data (checking if a bit is 0 or 1).

1. string_to_byte_array(str)

   • function string_to_byte_array(str) {
     var strLen=str.length;
     var buf = new Uint8Array(strLen);
     for (var i=0; i < strLen; i++) {
     buf[i] = str.charCodeAt(i);
     }
     return buf;
     }
     

2. on_update()

   • Main function that processes input string data and applies various bit manipulation functions from the BinaryUtils object.

   • Steps inside on_update():

     • Convert input string to byte array using string_to_byte_array

     • Apply six different bit mask functions on the byte array:

       // Buffer Input (Uint8Array) -> //# 0x 4E 62 63 64 65 66
       function on_update() {
       var get_buf = string_to_byte_array(input.getbit_array_data);

       Code Fucntions	Descriptions
       mask8: Applies an 8-bit mask to the first byte	//function 1. mask8 output.getbit_mask8 = BinaryUtils.mask8("0b1111_0000", get_buf[0]);
       mask8AndShiftRight: Applies an 8-bit mask and shifts right on the first byte	//function 2. mask8AndShiftRight output.getbit_mask8AndShiftRight = BinaryUtils.mask8AndShiftRight( "0b11110000", get_buf[0] );
       mask16: Applies a 16-bit mask starting at offset 0	//function 3. mask16 output.getbit_mask16 = BinaryUtils.mask16( "0b0000_1111_1111_0000", get_buf, 0 );
       mask16AndShiftRight: Applies a 16-bit mask and shifts right starting at offset 0	//function 4. mask16AndShiftRight output.getbit_mask16AndShiftRight = BinaryUtils.mask16AndShiftRight( "0b0000_1111_1111_0000", get_buf, 0 );
       mask32: Applies a 32-bit mask starting at offset 0	//function 5. mask32 output.getbit_mask32 = BinaryUtils.mask32( "0b0000_1111_1111_1111_1111_1111_1111_0000", get_buf, 0 );
       mask32AndShiftRight: Applies a 32-bit mask and shifts right starting at offset 0	//function 6. mask32AndShiftRight output.getbit_mask32AndShiftRight = BinaryUtils.mask32AndShiftRight( "0b0000_1111_1111_1111_1111_1111_1111_0000", get_buf, 0 );

     • Publish the output after all manipulations

       output.publish();

Applying Bit Manipulation set bit functions on Uint8Array using BinaryUtils object

Set bit functions are for writing/modifying data (changing a bit to 1).

1. string_to_byte_array(str)

   • function string_to_byte_array(str) {
     var strLen=str.length;
     var buf = new Uint8Array(strLen);
     for (var i=0; i < strLen; i++) {
     buf[i] = str.charCodeAt(i);
     }
     return buf;
     }
     

2. on_update()

   • Main function that processes input string data and applies various bit manipulation functions from the BinaryUtils object.

   • Steps inside on_update():

     • Convert input string to byte array using string_to_byte_array

     • Apply six different bit mask functions on the byte array:

       // Buffer Input (Uint8Array) -> //# 0x 41 42 43 44 45 46 - "ABCDEF"
       function on_update() {
       var set_buf = string_to_byte_array(input.setbit_array_data);
       var dup_set_buf = set_buf;

       Code Fucntions	Descriptions
       mask8AndSet	//function 1. mask8AndSet ,output: 0x71 = 113 output.setbit_mask8AndSet = BinaryUtils.mask8AndSet("0xF0", set_buf[0], 7);
       mask16AndSet	//function 2. mask16AndSet ,output: "aBCDEF" set_buf = dup_set_buf; BinaryUtils.mask16AndSet("0xFF00", set_buf, 0, 0x61); output.setbit_mask16AndSet = String.fromCharCode.apply( null, new Uint8Array(set_buf) );
       mask32AndSet	//function 3. mask32AndSet ,output: "bCDDEF" set_buf = dup_set_buf; BinaryUtils.mask32AndSet("0x0F_FF_FF_F0", set_buf, 0, 0x243444); output.setbit_mask32AndSet = String.fromCharCode.apply( null, new Uint8Array(set_buf) );

     • Publish the output after all manipulations

       output.publish();

Currently, all levels are treated equally and either are all emitted or none.

• A pipeline set to productive = true will never emit any log messages.

• A pipelines set to productive = false will emit all messages.

All emitted messages are subject to quota handling.

Function mqtt_add_subscription api from data logic for MQTT destination

/**
* @fn mqtt_add_subscription()
* @brief it is to add the topic subscription for mqtt link the API should
be called from data
* logic init() function and its applicable only for mqtt link, the
API is a blocking * call and will block current thread for maximum
100ms
* @param topic: valid mqtt topic
* @param qos: its optional param allowed values (0,1 or 2) default value
is considered 0 if not * provided
* @return none on success
* @Error message for the invalid use
* 1. Wrong number of argument:
* Error message: Error executing JavaScript: TypeError:
mqtt_add_subscription(): wrong number of argument provide, expecting 1
(topic) or 2 arguments (topic,qos)
* 2. non-utf in topic:
* Error message: Error executing JavaScript: TypeError:
mqtt_add_subscription(): Topic is not UTF-8 string
* 3. invalid QOS
* Error message: Error executing JavaScript: RangeError:
mqtt_add_subscription(): QoS should be 0,1 or 2
* 4. commandPath topic not allowed
* Error message: Error executing JavaScript: SyntaxError:
mqtt_add_subscription(): topic 'commandPath' cannot be * subscribed from
data logic script
* 5. not supported destination
* Error message: Error executing JavaScript: TypeError:
mqtt_add_subscription(): api is only supported for mqtt destination
* 6. api mqtt_add_subscription() is allowed only in init()
* Error message: Error executing JavaScript: TypeError:
mqtt_add_subscription(): api is only allowed to be called from init()
*
*/
mqtt_add_subscription(topic,qos)

HTTP request methods

/**
* @fn http.get(url, [headers], callback)
* @brief Performs an HTTP GET request
*/
function handleGetResponse(err, res) {
if (err) {
logger.error("Request failed: " + err.message);
} else {
output.api_data = JSON.parse(res.body);
output.publish();
}
}

http.get("https://api.example.com/data", {"Accept": "application/json"},
handleGetResponse);

/**
* @fn http.post(url, body, [headers], callback)
* @brief Performs an HTTP POST request
*/
function handlePostResponse(err, res) {
if (err) {
logger.error("POST failed: " + err.message);
} else {
logger.info("Created: " + res.statusCode);
}
}

var data = {"name": "John", "age": 30};
http.post("https://api.example.com/users", data, {"Content-Type":
"application/json"}, handlePostResponse);

/**
* @fn http.put(url, body, [headers], callback)
* @brief Performs an HTTP PUT request (same parameters as POST)
*/

/**
* @fn http.delete(url, [headers], callback)
* @brief Performs an HTTP DELETE request (same parameters as GET)
*/

HTTP configuration

/**
* @fn http.setTimeout(milliseconds)
* @brief Sets the default timeout for HTTP requests
*/
http.setTimeout(30000); // 30 seconds

/**
* @fn http.setConnectionReuse(enabled)
* @brief Controls whether HTTP connections are reused or closed after each
request
*/
http.setConnectionReuse(false); // Disable for problematic servers

/**
* @fn http.getRequestCount()
* @brief Returns the current number of pending HTTP requests
*/
var pendingRequests = http.getRequestCount();

SSL configuration

/**
* @fn http.setSSLOptions(options)
* @brief Configures SSL/TLS options for HTTPS requests
*/
http.setSSLOptions({
verify: true, // Enable peer verification
verifyHostname: true, // Enable hostname verification
allowSelfSigned: false, // Allow self-signed certificates
caFile: "/path/to/ca.pem" // CA certificate file path or content
});

/**
* @fn http.setVerifyMode(verify)
* @brief Sets the SSL peer verification mode
*/
http.setVerifyMode(false); // Disable SSL verification for testing

/**
* @fn http.allowSelfSignedCertificates(allow)
* @brief Controls whether self-signed certificates are accepted
*/
http.allowSelfSignedCertificates(true); // Allow for development

Response object

The response object passed to callbacks contains:

• statusCode (Number): HTTP status code

• body (String): Response body

• headers (Object): Response headers

Error handling

All HTTP methods use error-first callbacks. The error object contains:

• message (String): Error description

• code (String): Error code (if available)

HTTP usage example

function handleApiResponse(err, res) {
if (err) {
logger.error("HTTP error: " + err.message);
return;
}

if (res.statusCode === 200) {
var data = JSON.parse(res.body);
output.external_data = data;
output.publish();
} else {
logger.warn("HTTP status: " + res.statusCode);
}
}

function init() {
http.setTimeout(30000);
http.setConnectionReuse(true);
http.setVerifyMode(true);
}

function on_update() {
var apiUrl = "https://api.example.com/sensor/" + input.sensor_id;
http.get(apiUrl, {"Accept": "application/json"}, handleApiResponse);
}

Protobuf best practices

1. Initialize in init(): Always initialize protobuf types in the init() function to avoid repeated parsing

2. Memory Management: Store protobuf types in global objects to reuse across function calls

3. Base64 Encoding: Proto files must be base64 encoded when embedded in JavaScript

Example: simple message encoding/decoding

var pb = new Object();
function init() {
var protobuf = require("protobuf");
// Base64 encoded proto file content for a simple message
// Original proto:
// syntax = "proto3";
// package simple;
// message SimpleMessage {
// string name = 1;
// int32 value = 2;
// }
var protofile =
"c3ludGF4ID0gInByb3RvMyI7CnBhY2thZ2Ugc2ltcGxlOwptZXNzYWdlIFNpbXBsZU1lc3NhZ2
UgewogIHN0cmluZyBuYW1lID0gMTsKICBpbnQzMiB2YWx1ZSA9IDI7Cn0=";
var root = protobuf.init([protofile]);
pb.SimpleMessage = root.lookupType("simple.SimpleMessage");
}

function on_update() {
// Create and encode a protobuf message
var msg = pb.SimpleMessage.create({
name: input.device_name,
value: input.sensor_reading
});
var encoded_buffer = pb.SimpleMessage.encode(msg).finish();
publish("output", encoded_buffer);

// Decode a protobuf message
var decoded_msg = pb.SimpleMessage.decode(encoded_buffer);
output.decoded_name = decoded_msg.name;
output.decoded_value = decoded_msg.value;
}