53. 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

53.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.

53.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.

53.1.2 Other variables¶

A datum expression will also provide the following variables:

53.1.3 Functions¶

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

53.1.3.1 Bit functions¶

The following functions help with bitwise integer manipulation operations:

53.1.3.2 Date time functions¶

The following functions help with creating and manipulating dates. The Temporal type can be thought of as some kind of date type: it could be a LocalDate (a date without any time zone), a LocalDateTime (a date and time without any time zone), a ZonedDateTime (a date and time in a specific time zone), or an Instant (a date and time in the UTC time zone).

53.1.3.2.1 Date creation functions¶

53.1.3.2.2 Date manipulation functions¶

53.1.3.2.3 Date range functions¶

53.1.3.3 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.

SolarNode only maintains a limited history for each source, so do not rely on more than a few datum to be available via these method. This history is also cleared when SolarNode restarts.

53.1.3.4 Unfiltered datum stream functions¶

The following functions are similar to the datum stream functions except they deal with unfiltered datum streams, that is the raw datum captured by SolarNode sources before any filters have been applied.

53.1.3.5 Datum stream metadata functions¶

The following functions deal with datum stream metadata.

53.1.3.6 Math functions¶

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

53.1.3.7 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.

53.1.3.8 Operational functions¶

The following functions deal with general SolarNode operations:

53.1.3.9 Property functions¶

The following functions help with expression properties (variables):

53.1.3.10 Tariff schedule functions¶

The following functions help work with tariff schedules, which represent a set of time-based criteria with associated tariffs. A tariff in this scheme is nothing more than a set of one or more number values, each with an associated name.

Here is an example schedule with 4 tariffs each with a single price rate. The * stands for any value:

Assuming the above schedule were available with the identifier my-schedule, here is an example expression that finds the price rate at the time the expression is evaluated:

tariffSchedule('my-schedule')
    .resolveTariff(now(), null)
    .rates['price']
    .amount

If the evuation time was 2024-08-10 13:00 then the expression would return 11.21 because that date matches tariff #4.

You can use the date time functions to find tariffs that match arbitrary dates, such as a date 1 month in the future:

tariffSchedule('my-schedule')
    .resolveTariff(datePlus(now(), 1, 'months'), null)
    .rates['price']
    .amount

Here are the available tariff schedule expression functions:

53.1.3.10.1 TariffSchedule object functions¶

The TariffSchedule object provides the following functions:

53.1.3.10.2 Tariff object properties¶

The Tariff object provides the following properties:

53.1.3.10.3 Rate object properties¶

The Rate object provides the following properties:

53.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:

53.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:

53.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:

53.3 Datum metadata¶

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

53.3.1 Datum metadata properties¶

The properties available on datum metadata objects are:

53.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):

53.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):

53.3.4 Datum metadata global functions¶

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