SolarNode Settings - SolarNetwork/solarnetwork GitHub Wiki
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 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.
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.
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']
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.
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
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.