SolarNode Settings

SolarNode plugins support configurable properties, called settings. The SolarNode setup app allows you to manage settings via forms on web pages.

Nearly every form field you can edit in the SolarNode setup app represents a setting for a plugin in SolarNode.

Settings can also be exported and imported via a CSV format, and can be applied when SolarNode starts up via auto settings CSV files. Here's an example of a settings form in the SolarNode setup app:

Settings syntax

Settings files are CSV (comma separated values) files, easily exported from spreadsheet applications like Microsoft Excel or Google Sheets. The CSV must include a header row, which is skipped. All other rows will be processed as settings.

The SolarNode settings CSV format uses a quite general format and contains the following columns:

#	Name	Description
1	key	A unique identifier for the service the setting applies to.
2	type	A unique identifier for the setting with the service specified by key, typically using standard property syntax.
3	value	The setting value.
4	flags	An integer bitmask of flags associated with the setting. See the flags section for more info.
5	modified	The date the setting was last modified, in yyyy-MM-dd HH:mm:ss format.

To understand the key and type values required for a given plugin requires consulting the documentation of that plugin. You can get a pretty good picture of what the values are by exporting the settings after configuring a component in SolarNode. Typically the key value will mirror a plugin's Java package name, and type follows the Spring Framework property accessor syntax for a property exposed by the service providing the settings.

Settings CSV example

Here's an example snippet of settings CSV:

net.solarnetwork.node.io.modbus.1,serialParams.baudRate,19200,0,2014-03-01 21:01:31
net.solarnetwork.node.io.modbus.1,serialParams.parityString,even,0,2014-03-01 21:01:31
net.solarnetwork.node.io.modbus.1,serialParams.portName,/dev/cuaU0,0,2014-03-01 21:01:31
net.solarnetwork.node.io.modbus.FACTORY,1,1,0,2014-03-01 21:00:31

These settings all belong to the net.solarnetwork.node.io.modbus service.

Setting property syntax

The type setting value usually defines a plugin property via a property accessor syntax with these rules:

Expression	Example	Description
Property	name	Indicates a property named name.
Nested property	name.subname	Indicates a nested property subname on a parent property name.
List property	name[0]	Indicates the first element of an indexed list property named name.
Map property	name['key']	Indicates the key element of the map property name.

These rules can be combined in complex expressions, such as the name of the first property include list setting:

propIncludes[0].name

or the UID property filter of the connection factory of the delegate setting:

delegate.connectionFactory.propertyFilters['UID']

Settings flags

Each setting has a set of flags that can be associated with it. The following table outlines the bit offset for each flag along with a description:

#	Name	Description
0	Ignore modification date	If this flag is set then changes to the associated setting will not trigger a new auto backup.
1	Volatile	If this flag is set then changes to the associated setting will not trigger an internal "setting changed" event to be broadcast.

Note these are bit offsets, so the decimal value to ignore modification date is 1, to mark as volatile is 2, and for both is 3.

Component factories

Many plugins provide component factories which allow you to configure any number of a given service provided by the plugin. In the previous example CSV the IO Modbus plugin allows you to configure any number of Modbus connection components, each with their own specific settings. That is an example of a component factory. The settings CSV will include a special row to indicate that such a factory component should be activated, using a unique number, and then all the settings associated with that factory instance will have that unique number appended to their key values.

Going back to that example CSV, this is the row that activates the first IO Modbus component:

net.solarnetwork.node.io.modbus.FACTORY,1,1,0,2014-03-01 21:00:31

The synax for key column is simply the service identifier followed by .FACTORY. Then the type and value columns are both set the same unique number. In this example that number is 1. For all settings specific to a factory component, the key column will be the service identifier followed by .NUMBER where NUMBER is the unique instance number.

Here's an example that shows two factory instances configured, each with a different serialParams.portName setting value:

net.solarnetwork.node.io.modbus.1,serialParams.portName,/dev/cuaU0,0,2014-03-01 21:01:31
net.solarnetwork.node.io.modbus.2,serialParams.portName,/dev/ttyUSB0,0,2014-03-01 21:01:31
net.solarnetwork.node.io.modbus.FACTORY,1,1,0,2014-03-01 21:00:31
net.solarnetwork.node.io.modbus.FACTORY,2,2,0,2014-03-01 21:00:31

Auto settings

SolarNode settings can also be configured via "auto settings" when SolarNode starts up, by placing settings CSV files in the /etc/solarnode/auto-settings.d directory. These settings are applied only if they don't already exist or the modified date in the settings file is newer than the date they were previously applied.