Table of Contents

Defining a data source (device) in Signomiks allows you to define code for the data processor. When new data is received from this source, the data processor launches the JavaScript interpreter and executes the code defined for that data source.

When creating code for the processor, the user can utilize the functions of the sgx library built into the data processor. The documentation for this library is provided below.

Variables:

• eui
• dataTimestamp
• applicationConfig
• deviceConfig
• deviceGroups
• latitude
• longitude
• altitude
• tags
• port

Features:

• verify
• accept
• addCommand
• addGroupData
• addHexCommand
• addNotification
• addPlainCommand
• addVirtualData
• clearData
• distance
• getAverage
• getDeviceGroups
• getMinimum
• getMaximum
• getSum
• getLastValue
• getLastData
• getModulo
• getOutput
• getTimestamp
• getTimestampUTC
• getValue
• getStringValue
• homeDistance
• put
• setState
• setStatus
• swap32
• reverseHex

sgx library variables

When the data processor is initialized, the sgx library variables are assigned values read from the incoming data. In the data processor script, you can read the values of these variables in the same way as for the eui variable below.

var eui = sgx.eui

eui

Data source identifier (EUI)

Usage example

var eui = sgx.eui

dataTimestamp

Timestamp of data reception in milliseconds (UTC).

applicationConfig

The configuration object for the application declared for the data source.

deviceConfig

Configuration object defined for the data source.

deviceGroups

Groups associated with the data source.

latitude

The latitude of the data source, as specified in its definition (decimal format, as in Google Maps).

longitude

The longitude of the data source, as specified in its definition (decimal format, as in Google Maps).

altitude

The elevation of the data source above sea level, as specified in its definition.

tags

A map of tags added to the data source definition.

port

The LoRaWAN port number assigned to data transmission.

Functions of the sgx object

verify(received, receivedStatus)

The verify function is used to verify received data and update the object’s status.

Parameters

• received (Array): An array of data objects to be verified.
• receivedStatus (String): The status of the received data.

Returns

• void: The function does not return any value.

Usage example

var receivedData = [
    { name: "temperature", value: 22.5, timestamp: 1628765432 },
    { name: "humidity", value: 60, timestamp: 1628765432 }
];
var status = "ok";

sgx.verify(receivedData, status);

accept(name)

The `accept` function is used to accept data with the specified name and store it in the results. Calling this function may be necessary when using the ` put` function in your code.

See also: put

Parameters

• name (String): The name of the data to be accepted.

Returns

• void: The function does not return any value.

Usage example

sgx.accept("temperature");

addCommand(targetEUI, payload, overwrite)

The addCommand function is used to add a new command.

Parameters

• targetEUI (String): The unique identifier of the target device.
• payload (Object): Data (JavaScript object) to be sent as part of the command.
• overwrite (Boolean): A flag indicating whether to override previous (not yet sent) commands.

Returns

• void: The function does not return any value.

Usage example

var targetEUI = "00124B0004F12345";
var payload = { command: "activate", parameters: { duration: 10 } };
var overwrite = true;

sgx.addCommand(targetEUI, payload, overwrite);

addPlainCommand(targetEUI, payload, overwrite)

The addPlainCommand function is used to add a new command in plain text format.

Parameters

• targetEUI (String): The unique identifier of the target device.
• payload (String): The text to be sent as part of the command.
• overwrite (Boolean): A flag indicating whether to override previous (not yet transmitted) commands.

Returns

• void: The function does not return any value.

Usage example

var targetEUI = "00124B0004F12345";
var payload = 'start'
var overwrite = false;

sgx.addPlainCommand(targetEUI, payload, overwrite);

addHexCommand(targetEUI, payload, overwrite)

The addHexCommand function is used to add a new command with a payload in hexadecimal format.

Parameters

• targetEUI (String): The unique identifier of the target device.
• payload (String): Data in hexadecimal format to be sent as part of the command.
• overwrite (Boolean): A flag indicating whether to override previous (not yet transmitted) commands.

Returns

• void: The function does not return any value.

Usage example

var targetEUI = "00124B0004F12345";
var payload = "00FFAA01";
var overwrite = true;

sgx.addHexCommand(targetEUI, payload, overwrite);

addNotification(newType, newMessage)

The addNotification function is used to add a new notification.

Parameters

• newType (String): The type of the new notification. Accepted values: info,warning,alert.
• newMessage (String): The text of the new notification.

Returns

• void: The function does not return any value.

Usage example

sgx.addNotification("info", "Device activated successfully.");

addVirtualData(newEUI, newName, newValue)

The addVirtualData function is used to add new virtual data.

Parameters

• newEUI (String): The unique identifier of the new device.
• newName (String): The name of the new data.
• newValue (Mixed): The value of the new data.

Returns

• void: The function does not return any value.

Usage example

sgx.addVirtualData("00124B0004F67890", "virtualTemperature", 25);

clearData()

The clearData function removes all received values from the queue.

Parameters

None

Returns

• void: The function does not return a value.

getAverage(channelName, scope, newValue)

The getAverage function is used to obtain the average value for a given channel.

Parameters

• channelName (String): The channel name.
• scope (Number): The range of values.
• newValue (Number, optional): The new value to include in the calculation.

Returns

• Number: The average value for the given channel.

Usage example

var average = sgx.getAverage("temperature", 10);
var newAverage = sgx.getAverage("temperature", 10, 23.0);

getMinimum(channelName, scope, newValue)

The getMinimum function is used to retrieve the minimum value for a given channel.

Parameters

• channelName (String): The channel name.
• scope (Number): Range of values.
• newValue (Number, optional): The new value to include in the calculation.

Returns

• Number: The minimum value for the given channel.

Usage example

var minimum = sgx.getMinimum("temperature", 10);
var newMinimum = sgx.getMinimum("temperature", 10, 18);

getMaximum(channelName, scope, newValue)

The getMaximum function is used to retrieve the maximum value for a given channel.

Parameters

• channelName (String): The channel name.
• scope (Number): Range of values.
• newValue (Number, optional): The new value to include in the calculation.

Returns

• Number: The maximum value for the given channel.

Usage example

var maximum = sgx.getMaximum("temperature", 10);
var newMaximum = sgx.getMaximum("temperature", 10, 27);

getSum(channelName, scope, newValue)

The getSum function is used to obtain the sum of values for a given channel.

Parameters

• channelName (String): The channel name.
• scope (Number): Range of values.
• newValue (Number, optional): The new value to include in the calculation.

Returns

• Number: The sum of values for the given channel.

Usage example

var sum = sgx.getSum("temperature", 10);
var newSum = sgx.getSum("temperature", 10, 22);

getLastValue(channelName, skipNull)

The getLastValue function is used to retrieve the last value for a given channel.

Parameters

• channelName (String): The channel name.
• skipNull (Boolean): Skip null values. Optional parameter.

Returns

• Mixed: The last value for the given channel, or null if no data is available.

Usage example

var lastValue = sgx.getLastValue("temperature");

getLastData(channelName, skipNull)

The getLastData function is used to retrieve the latest data for a given channel.

Parameters

• channelName (String): The channel name.
• skipNull (Boolean): Skip null values. Optional parameter. If omitted , skipNull == false.

Returns

• Object: The latest data for a given channel.

Usage example

var lastData = sgx.getLastData("temperature");

getModulo(value, divider)

The getModulo function is used to obtain the remainder of a division by a divisor.

Parameters

• value (Number): The value to be divided.
• divider (Number): The divisor.

Returns

• Number: The remainder of the division.

Usage example

var modulo = sgx.getModulo(10, 3); // 1

getOutput()

The getOutput function is used to retrieve processing results.

Returns

• Mixed: The result of the processing.

Usage example

var output = sgx.getOutput();

getTimestamp(channelName)

The getTimestamp function is used to retrieve the timestamp for a given channel.

Parameters

• channelName (String): The channel name.

Returns

• Number: The timestamp for the specified channel.

Usage example

var timestamp = sgx.getTimestamp("temperature");

getTimestampUTC(y, m, d, h, min, s)

The getTimestampUTC function is used to obtain a UTC timestamp based on the specified parameters.

Parameters

• y (Number): Year.
• m (Number): Month.
• d (Number): Day.
• h (Number): Hour.
• min (Number): Minute.
• s (Number): Second.

Returns

• Number: A UTC timestamp.

Usage example

var timestampUTC = sgx.getTimestampUTC(2024, 6, 5, 12, 0, 0);

getValue(channelName)

The getValue function is used to retrieve the value for a given channel.

Parameters

• channelName (String): The channel name.

Returns

• Mixed: The value for the specified channel, or null if no data is available.

Usage example

var value = sgx.getValue("temperature");

getStringValue(channelName)

The getStringValue function is used to retrieve a string value for a given channel.

Parameters

• channelName (String): The channel name.

Returns

• String: The text value for the specified channel, or null if no data is available.

Usage example

var stringValue = sgx.getStringValue("temperature");

put(name, newValue, timestamp)

The put function is used to store new data.

Parameters

• name (String): The name of the data.
• newValue (Mixed): The new value of the data.
• timestamp (Number, optional): The data's timestamp.

Returns

• void: The function does not return any value.

Usage example

sgx.put("temperature", 23.5);
sgx.put("temperature", 23.5, 1628765432);

Notes

Using the put function disables the mechanism for automatically accepting and saving received data to the database. If the put function is used in the data processor code,
will only record the data passed in the ` put ` and ` accept` functions.

Usage example

// Signomix received a request with data named `temperature` and `humidity`, but in the 
// data processor script, we want to add the value of `pressure` as well
sgx.put("pressure", 1000)
// Without the following lines, null values for `temperature` and `humidity` will be written to the database
sgx.accept("temperature")
sgx.accept("humidity")

See also: accept

setState(newState)

The setState function is used to set a new state for the device.

Parameters

• newState (String): The new state of the device.

Returns

• void: The function does not return any value.

Usage example

sgx.setState("active");

setStatus(newStatus)

The setStatus function is used to set a new device status.

Parameters

• newStatus (String): The new device status.

Returns

• void: The function does not return any value.

Usage example

sgx.setStatus("offline");

reverseHex(hexStr)

The reverseHex function is used to reverse the order of characters in a hexadecimal string.

Parameters

• hexStr (String): A hexadecimal string.

Returns

• String: The reversed hexadecimal string.

Usage example

var reversedHex = sgx.reverseHex("00FFAA01"); // "01AAFF00"

swap32(val)

The swap32 function is used to reverse the order of bytes in a 32-bit number.

Parameters

• val (Number): A 32-bit number.

Returns

• Number: A number with the byte order reversed.

Usage example

var swapped = sgx.swap32(0x12345678); // 0x78563412

distance(latitude1, longitude1, latitude2, longitude2)

The distance function is used to calculate the distance between two geographic points.

Parameters

• latitude1 (Number): The latitude of point 1.
• longitude1 (Number): Longitude of point 1.
• latitude2 (Number): Latitude of point 2.
• longitude2 (Number): Longitude of point 2.

Returns

• Number: The distance between the two points in meters.

Usage example

// distance between two points
var dist = sgx.distance(52.2296756, 21.0122287, 41.8919300, 12.5113300);

// distance from the point to the provided location
var dist = sgx.distance(2.2296756, 21.0122287, sgx.getValue("latitude"), sgx.getValue("longitude") );

homeDistance(latitude, longitude)

The homeDistance function is used to calculate the distance between a given geographic point
and the device’s location stored in its configuration.

Parameters

• latitude (Number): The latitude of the point.
• longitude (Number): The longitude of the point.

Returns

• Number: The distance between the two points in meters.

Usage example

// Distance from the specified point to the location specified in the device configuration
var dist = sgx.homeDistance(41.8919300, 12.5113300);

// distance from the uploaded location to the location specified in the device configuration
var dist = sgx.homeDistance( sgx.getValue("latitude"), sgx.getValue("longitude") );