43. Expressions¶

Many SolarNode components support a general "expressions" framework that can be used to calculate values using a scripting language. SolarNode comes with the Spel scripting language by default, so this guide describes that language.

A common use case for expressions is to derive datum property values out of the raw property values captured from a device. In the SolarNode Setup App a typical datum data source component might present a configurable list of expression settings like this:

In this example, each time the data source captures a datum from the device it is communicating with it will add a new watts property by multiplying the captured amps and volts property values. In essence the expression is like this code:

watts = amps × volts

43.1 Datum Expressions¶

Many SolarNode expressions are evaluated in the context of a datum, typically one captured from a device SolarNode is collecting data from. In this context, the expression supports accessing datum properties directly as expression variables, and some helpful functions are provided.

43.1.1 Datum property variables¶

All datum properties with simple names can be referred to directly as variables. Here simple just means a name that is also a legal variable name. The property classifications do not matter in this context: the expression will look for properties in all classifications.

For example, given a datum like this:

{
  "i": {
    "watts"     : 123
  },
  "a": {
    "wattHours" : 987654321
  },
  "s": {
    "mode"      : "auto"
  }
}

The expression can use the variables watts, wattHours, and mode.

43.1.2 Other variables¶

A datum expression will also provide the following variables:

43.1.3 Functions¶

Some functions are provided to help with datum-related expressions.

43.1.3.1 Bit functions¶

The following functions help with bitwise integer manipulation operations:

43.1.3.2 Datum stream functions¶

The following functions deal with datum streams. The latest() and offset() functions give you access to recently-captured datum from any SolarNode source, so you can refer to any datum stream being generated in SolarNode. They return another datum expression root object, which means you have access to all the variables and functions documented on this page with them as well.

43.1.3.3 Math functions¶

Expressions support basic math operators like + for addition and * for multiplication. The following functions help with other math operations:

43.1.3.4 Node metadata functions¶

All the Datum Metadata functions like metadataAtPath(path) can be invoked directly, operating on the node's own metadata instead of a datum stream's metadata.

43.1.3.5 Operational functions¶

The following functions deal with general SolarNode operations:

43.1.3.6 Property functions¶

The following functions help with expression properties (variables):

43.2 Expression examples¶

Let's assume a captured datum like this, expressed as JSON:

{
  "i" : {
    "amps"      : 4.2,
    "volts"     : 240.0
  },
  "a" : {
    "reading"   : 38009138
  },
  "s" : {
    "state"     : "Ok"
  }
}

Then here are some example Spel expressions and the results they would produce:

43.2.1 Datum stream history¶

Building on the previous example datum, let's assume an earlier datum for the same source ID had been collected with these properties (the classifications have been omitted for brevity):

{
  "amps"    : 3.1,
  "volts"   : 241.0,
  "reading" : 38009130,
  "state"   : "Ok"
}

Then here are some example expressions and the results they would produce given the original datum example:

43.2.2 Other datum stream history¶

Other datum stream histories collected by SolarNode can also be accessed via the offset(source,offset) function. Let's assume SolarNode is collecting a datum stream for the source ID solar, and had amassed the following history, in newest-to-oldest order:

[
  {"amps" : 6.0, "volts" : 240.0 },
  {"amps" : 5.9, "volts" : 239.9 }
]

Then here are some example expressions and the results they would produce given the original datum example:

If we add another datum stream for the source ID solar1 like this:

[
  {"amps" : 1.0, "volts" : 240.0 }
]

If we also add another datum stream for the source ID solar2 like this:

[
  {"amps" : 3.0, "volts" : 240.0 }
]

Then here are some example expressions and the results they would produce given the previous datum examples:

43.3 Datum metadata¶

Some functions return DatumMetadataOperations objects. These objects provide metadata for things like a specific source ID on SolarNode.

43.3.1 Datum metadata properties¶

The properties available on datum metadata objects are:

43.3.2 Datum metadata general info functions¶

The following functions available on datum metadata objects support access to the general metadata (e.g. the m metadata map):

43.3.3 Datum metadata property info functions¶

The following functions available on datum metadata objects support access to the property metadata (e.g. the pm metadata map):

43.3.4 Datum metadata global functions¶

The following functions available on datum metadata objects support access to both general and property metadata: